feat(realtime): add resolution option (#140)

## Summary

Lets users of realtime models opt into 1080p output via a new
`resolution` option on `realtime.connect`. Defaults to `720p` (no
behavior change for existing callers).

## Usage

```ts
const realtimeClient = await client.realtime.connect(stream, {
  model: models.realtime("lucy-2.1"),
  resolution: "1080p", // default: "720p"
  onRemoteStream,
});
```

## Test plan
- [x] `pnpm typecheck`
- [x] `pnpm test` (4 new unit tests covering URL construction + Zod
validation)
- [x] `pnpm format:check`
- [ ] Manual smoke against staging: verify `lucy-2.1` + `resolution:
"1080p"` delivers a 1884×1080 remote track

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Low risk: adds an optional, Zod-validated `resolution` parameter that
only affects realtime WebRTC URL query construction, with coverage to
prevent invalid values.
> 
> **Overview**
> Adds a new optional `resolution` setting to `realtime.connect`
(validated as `"720p"` or `"1080p"`) and forwards it to the realtime
WebRTC endpoint via a `resolution=` query parameter when provided.
> 
> Updates the SDK README with usage examples and adds unit tests
verifying URL construction (param omitted vs appended) and input
validation for invalid resolutions.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
56c8621. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: AdirAmsalem

packages/sdk/README.md

@@ -79,6 +79,16 @@ Options:
 - `"auto"` — mirror when the input track reports `facingMode: "user"` (mobile front cameras).
 - `true` — always mirror (e.g. desktop webcams).
 
+#### Output resolution
+
+```ts
+const realtimeClient = await client.realtime.connect(stream, {
+  model,
+  resolution: "1080p", // default: "720p"
+  // ...
+});
+```
+
 ### Async Processing (Queue API)
 
 For video generation jobs, use the queue API to submit jobs and poll for results:

packages/sdk/src/realtime/client.ts

@@ -100,6 +100,8 @@ const realTimeClientConnectOptionsSchema = z.object({
    * - true: always mirror.
    */
   mirror: z.union([z.literal("auto"), z.boolean()]).optional(),
+  /** Output resolution. Defaults to "720p". */
+  resolution: z.enum(["720p", "1080p"]).optional(),
 });
 export type RealTimeClientConnectOptions = Omit<z.infer<typeof realTimeClientConnectOptionsSchema>, "model"> & {
   model: ModelDefinition | CustomModelDefinition;
@@ -141,7 +143,7 @@ export const createRealTimeClient = (opts: RealTimeClientOptions) => {
       throw parsedOptions.error;
     }
 
-    const { onRemoteStream, initialState } = parsedOptions.data;
+    const { onRemoteStream, initialState, resolution } = parsedOptions.data;
     const mirror = parsedOptions.data.mirror ?? false;
 
     let inputStream: MediaStream = stream ?? new MediaStream();
@@ -189,9 +191,10 @@ export const createRealTimeClient = (opts: RealTimeClientOptions) => {
         : undefined;
 
       const url = `${baseUrl}${options.model.urlPath}`;
+      const resolutionQs = resolution ? `&resolution=${encodeURIComponent(resolution)}` : "";
 
       webrtcManager = new WebRTCManager({
-        webrtcUrl: `${url}?api_key=${encodeURIComponent(apiKey)}&model=${encodeURIComponent(options.model.name)}`,
+        webrtcUrl: `${url}?api_key=${encodeURIComponent(apiKey)}&model=${encodeURIComponent(options.model.name)}${resolutionQs}`,
         integration,
         logger,
         observability,

packages/sdk/tests/unit.test.ts

@@ -1993,6 +1993,72 @@ describe("Subscribe Client", () => {
       cleanupSpy.mockRestore();
     }
   });
+
+  describe("connect() resolution option", () => {
+    const connectAndCaptureUrl = async (resolution?: "720p" | "1080p"): Promise<string> => {
+      const { createRealTimeClient } = await import("../src/realtime/client.js");
+      const { WebRTCManager } = await import("../src/realtime/webrtc-manager.js");
+
+      let capturedUrl = "";
+      const connectSpy = vi.spyOn(WebRTCManager.prototype, "connect").mockImplementation(async function () {
+        const mgr = this as unknown as {
+          config: {
+            webrtcUrl: string;
+            onConnectionStateChange?: (state: import("../src/realtime/types").ConnectionState) => void;
+          };
+          managerState: import("../src/realtime/types").ConnectionState;
+        };
+        capturedUrl = mgr.config.webrtcUrl;
+        mgr.managerState = "connected";
+        mgr.config.onConnectionStateChange?.("connected");
+        return true;
+      });
+      const stateSpy = vi.spyOn(WebRTCManager.prototype, "getConnectionState").mockReturnValue("connected");
+      const cleanupSpy = vi.spyOn(WebRTCManager.prototype, "cleanup").mockImplementation(() => {});
+
+      try {
+        const realtime = createRealTimeClient({ baseUrl: "wss://api3.decart.ai", apiKey: "test-key" });
+        const client = await realtime.connect({} as MediaStream, {
+          model: models.realtime("lucy-2.1"),
+          onRemoteStream: vi.fn(),
+          ...(resolution ? { resolution } : {}),
+        });
+        client.disconnect();
+        return capturedUrl;
+      } finally {
+        connectSpy.mockRestore();
+        stateSpy.mockRestore();
+        cleanupSpy.mockRestore();
+      }
+    };
+
+    it("omits the resolution query param when unset", async () => {
+      const url = await connectAndCaptureUrl();
+      expect(url).not.toContain("resolution=");
+    });
+
+    it("appends resolution=720p when set", async () => {
+      const url = await connectAndCaptureUrl("720p");
+      expect(url).toContain("&resolution=720p");
+    });
+
+    it("appends resolution=1080p when set", async () => {
+      const url = await connectAndCaptureUrl("1080p");
+      expect(url).toContain("&resolution=1080p");
+    });
+
+    it("rejects invalid resolution values", async () => {
+      const { createRealTimeClient } = await import("../src/realtime/client.js");
+      const realtime = createRealTimeClient({ baseUrl: "wss://api3.decart.ai", apiKey: "test-key" });
+      await expect(
+        realtime.connect({} as MediaStream, {
+          model: models.realtime("lucy-2.1"),
+          onRemoteStream: vi.fn(),
+          resolution: "480p" as unknown as "720p",
+        }),
+      ).rejects.toThrow();
+    });
+  });
 });
 
 describe("Logger", () => {