SDK API Redesign - Clearer and More Intuitive API #73

decart-reindeer-coder · 2026-01-28T09:36:14Z

ref API-667

Summary

Redesigned the SDK API to provide clearer method names, flatter structure, and better organization while maintaining full backward compatibility.

What Changed

New API Methods

✨ client.generate() - synchronous generation (replaces process())
✨ client.submit() - async job submission (replaces queue.submit())
✨ client.submitAndWait() - async with auto-polling (replaces queue.submitAndPoll())
✨ client.getJobStatus() - check job status (replaces queue.status())
✨ client.getJobResult() - get job result (replaces queue.result())
✨ onProgress callback - more intuitive than onStatusChange

Old API (Deprecated but Working)

⚠️ client.process() - deprecated, use client.generate()
⚠️ client.queue.* methods - deprecated, use new flat methods
⚠️ onStatusChange - deprecated, use onProgress

Why This Change?

The previous API had several issues:

Confusing naming: "process" didn't clearly indicate synchronous operation
Unnecessary nesting: queue.* methods created extra API surface
Type constraints: API was organized by model type (image/video) rather than capability (sync/async)
Unclear callbacks: onStatusChange wasn't as intuitive as onProgress

Example: Before and After

Before (Old API)

const blob = await client.process({
  model: models.image("lucy-pro-t2i"),
  prompt: "A sunset"
});

const result = await client.queue.submitAndPoll({
  model: models.video("lucy-pro-t2v"),
  prompt: "A cat",
  onStatusChange: (job) => console.log(job.status)
});

After (New API)

const blob = await client.generate({
  model: models.image("lucy-pro-t2i"),
  prompt: "A sunset"
});

const result = await client.submitAndWait({
  model: models.video("lucy-pro-t2v"),
  prompt: "A cat",
  onProgress: (job) => console.log(job.status)
});

Files Changed

packages/sdk/src/index.ts - Add new unified API methods
packages/sdk/src/shared/unified-types.ts - New type definitions
packages/sdk/README.md - Document new API with examples
packages/sdk/tests/unit.test.ts - Add comprehensive test coverage
examples/ - New example files demonstrating new API
SDK_REDESIGN_PROPOSAL.md - Design proposal and rationale
MIGRATION_GUIDE.md - Complete migration guide

Backward Compatibility

✅ All old methods still work!
✅ No breaking changes
✅ Gradual migration supported

The old API is marked as deprecated and will be removed in v1.0.0.

Testing

✅ All existing tests pass
✅ New tests for all new API methods
✅ Builds successfully with no TypeScript errors
✅ Example files demonstrate usage

Documentation

📖 Complete migration guide in MIGRATION_GUIDE.md
📖 Updated README with new API examples
📖 Design proposal in SDK_REDESIGN_PROPOSAL.md

Next Steps

Review this PR
Test with existing integrations
Update docs site (if needed)
Plan deprecation timeline

🤖 Generated with Claude Code

Note

Introduces a flatter, clearer SDK API while preserving backward compatibility.

Adds unified methods: client.generate() (sync), client.submit(), client.submitAndWait(), client.getJobStatus(), client.getJobResult(); submitAndWait maps onProgress (and supports deprecated onStatusChange)
Implements new shared types (shared/unified-types.ts, shared/type-helpers.ts) and updates process/queue option types to merge schema-inferred types with documented fields
Exposes new API via packages/sdk/src/index.ts; keeps deprecated client.process() and client.queue.* aliases
Updates docs: expanded README “New API”, adds MIGRATION_GUIDE.md and SDK_REDESIGN_PROPOSAL.md
Adds examples using new API (image/video generation, manual polling), and small realtime hook fix to re-run on prompt
Extends unit tests to cover new methods and callback behavior

^{Written by Cursor Bugbot for commit f626b32. This will update automatically on new commits. Configure here.}

This commit implements a redesigned SDK API that addresses several issues with the current design: **Issues Fixed:** - Confusing naming: "process" didn't clearly indicate sync operation - Unnecessary nesting: queue.* methods created extra API surface - Type constraints mismatched with actual capabilities - Unclear callback naming: onStatusChange vs onProgress **New API:** - client.generate() - synchronous generation (replaces process()) - client.submit() - async job submission (replaces queue.submit()) - client.submitAndWait() - async with auto-polling (replaces queue.submitAndPoll()) - client.getJobStatus() - check job status (replaces queue.status()) - client.getJobResult() - get job result (replaces queue.result()) - onProgress callback - more intuitive than onStatusChange **Key Features:** - Full backward compatibility: old API still works but deprecated - Clearer method names that communicate intent - Flatter API structure without unnecessary nesting - Future-proof: organized by capability (sync/async) not model type - Comprehensive tests for new API - Migration guide and examples **Files Changed:** - packages/sdk/src/index.ts: Add new unified API methods - packages/sdk/src/shared/unified-types.ts: New type definitions - packages/sdk/README.md: Document new API with examples - packages/sdk/tests/unit.test.ts: Add comprehensive test coverage - examples/: New example files demonstrating new API - SDK_REDESIGN_PROPOSAL.md: Design proposal and rationale - MIGRATION_GUIDE.md: Complete migration guide **Testing:** All existing tests pass + new tests for new API methods. Builds successfully with no TypeScript errors. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

packages/sdk/src/shared/unified-types.ts

packages/sdk/src/index.ts

packages/sdk/src/shared/unified-types.ts

- Remove unused import of 'z' from zod in unified-types.ts - Fix type safety in submitAndWait by using proper generic types - Remove unnecessary 'as any' type assertions - All linting checks now pass with no warnings Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

This commit addresses all feedback from PR review: **1. Remove Redundant Type Definitions** - Replaced `SyncCapableModelDefinition` and `AsyncCapableModelDefinition` with single `GenerationCapableModelDefinition` type - Both were identical, causing confusion about their purpose - New unified type clearly indicates models support both sync and async **2. Remove Unnecessary Async Wrapper** - Changed `generate` from async wrapper to direct assignment: `const generate = process` - Consistent with other method aliases like `submit = queue.submit` - Eliminates unnecessary overhead **3. Extract Duplicated Type Helpers** - Created shared `type-helpers.ts` with generic type manipulation utilities - Replaced duplicate `PickDocumentedInputs` and `MergeDocumentedInputs` in 3 files (process/types.ts, queue/types.ts, unified-types.ts) - New generic `PickDocumentedFields<TDocumented, TInferred>` and `MergeDocumentedFields<TDocumented, TInferred>` helpers - Reduces maintenance burden and ensures consistency **Files Changed:** - packages/sdk/src/shared/type-helpers.ts (new) - shared type utilities - packages/sdk/src/process/types.ts - use shared helpers - packages/sdk/src/queue/types.ts - use shared helpers - packages/sdk/src/shared/unified-types.ts - use shared helpers, consolidate types - packages/sdk/src/index.ts - update exports, fix generate method **Testing:** - All 64 tests still passing - TypeScript compilation successful - Linting and formatting clean Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

cursor · 2026-01-28T11:57:05Z

packages/sdk/src/shared/unified-types.ts

+   * Optional `AbortSignal` for canceling the request.
+   */
+  signal?: AbortSignal;
+} & MergeDocumentedFields<ProcessInputs & ModelSpecificInputs<T>, InferModelInputs<T>>;


Duplicate type definitions for GenerateOptions and SubmitOptions

Low Severity

GenerateOptions and SubmitOptions are structurally identical types with the exact same definition: { model: T; signal?: AbortSignal; } & MergeDocumentedFields<ProcessInputs & ModelSpecificInputs<T>, InferModelInputs<T>>. The only differences are the JSDoc comments. SubmitOptions could be defined as a simple type alias (e.g., type SubmitOptions<T extends GenerationCapableModelDefinition = GenerationCapableModelDefinition> = GenerateOptions<T>) to reduce code duplication and maintenance burden.

Additional Locations (1)

packages/sdk/src/shared/unified-types.ts#L17-L27

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

cursor · 2026-01-28T12:08:01Z

examples/nextjs-realtime/components/video-stream.tsx

      realtimeClientRef.current?.disconnect();
    };
-  }, []);
+  }, [prompt]);


Adding prompt dependency causes unnecessary reconnection on change

Medium Severity

Adding prompt to the first useEffect's dependency array causes the entire connection setup, including camera access, to re-run on every prompt change. This results in unnecessary reconnections, visual flickering, repeated camera permission requests, and a camera resource leak because the previous stream isn't properly stopped.

Additional Locations (1)

examples/nextjs-realtime/components/video-stream.tsx#L31-L32

cursor bot reviewed Jan 28, 2026

View reviewed changes

packages/sdk/src/shared/unified-types.ts Outdated Show resolved Hide resolved

packages/sdk/src/index.ts Outdated Show resolved Hide resolved

packages/sdk/src/shared/unified-types.ts Outdated Show resolved Hide resolved

Claude Code on behalf of Local Developer and others added 2 commits January 28, 2026 11:33

cursor bot reviewed Jan 28, 2026

View reviewed changes

fix: apply biome formatting and linting fixes

f626b32

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

cursor bot reviewed Jan 28, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

SDK API Redesign - Clearer and More Intuitive API #73

SDK API Redesign - Clearer and More Intuitive API #73

Uh oh!

decart-reindeer-coder bot commented Jan 28, 2026 •

edited by cursor bot

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot Jan 28, 2026

Uh oh!

cursor bot left a comment

Uh oh!

cursor bot Jan 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

0 participants

SDK API Redesign - Clearer and More Intuitive API #73

Are you sure you want to change the base?

SDK API Redesign - Clearer and More Intuitive API #73

Uh oh!

Conversation

decart-reindeer-coder bot commented Jan 28, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What Changed

New API Methods

Old API (Deprecated but Working)

Why This Change?

Example: Before and After

Before (Old API)

After (New API)

Files Changed

Backward Compatibility

Testing

Documentation

Next Steps

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot Jan 28, 2026

Choose a reason for hiding this comment

Duplicate type definitions for GenerateOptions and SubmitOptions

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Jan 28, 2026

Choose a reason for hiding this comment

Adding prompt dependency causes unnecessary reconnection on change

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

0 participants

decart-reindeer-coder bot commented Jan 28, 2026 •

edited by cursor bot

Loading