feat(realtime): add realtimeBaseUrl option to createDecartClient

examples/sdk-core/README.md

@@ -58,6 +58,7 @@ See `examples/nextjs-realtime` or `examples/react-vite` for runnable demos.
 - `realtime/connection-events.ts` - Handling connection state and errors
 - `realtime/prompt-update.ts` - Updating prompt dynamically
 - `realtime/custom-model.ts` - Using a custom model definition (e.g., preview/experimental models)
+- `realtime/custom-base-url.ts` - Using a custom WebSocket base URL for realtime connections
 
 ## API Reference
 

examples/sdk-core/realtime/custom-base-url.ts

@@ -0,0 +1,47 @@
+/**
+ * Browser-only example - requires WebRTC APIs
+ * Demonstrates using a custom realtimeBaseUrl for WebSocket connections
+ * See examples/nextjs-realtime or examples/react-vite for runnable demos
+ */
+
+import { createDecartClient, models } from "@decartai/sdk";
+
+async function main() {
+  const model = models.realtime("mirage_v2");
+
+  // Get webcam stream with model-specific settings
+  const stream = await navigator.mediaDevices.getUserMedia({
+    audio: true,
+    video: {
+      frameRate: model.fps,
+      width: model.width,
+      height: model.height,
+    },
+  });
+
+  // Create a client with a custom realtime WebSocket base URL
+  // This overrides the default wss://api3.decart.ai endpoint
+  const client = createDecartClient({
+    apiKey: process.env.DECART_API_KEY!,
+    realtimeBaseUrl: "wss://custom-ws.example.com",
+  });
+
+  const realtimeClient = await client.realtime.connect(stream, {
+    model,
+    onRemoteStream: (transformedStream) => {
+      const video = document.getElementById("output") as HTMLVideoElement;
+      video.srcObject = transformedStream;
+    },
+    initialState: {
+      prompt: {
+        text: "Studio Ghibli animation style",
+        enhance: true,
+      },
+    },
+  });
+
+  console.log("Session ID:", realtimeClient.sessionId);
+  console.log("Connected:", realtimeClient.isConnected());
+}
+
+main();

packages/sdk/index.html

@@ -228,6 +228,10 @@ <h3>Configuration</h3>
             <label for="api-key">API Key:</label>
             <input type="password" autocomplete="off" id="api-key" placeholder="Enter your Decart API key">
         </div>
+        <div class="control-group">
+            <label for="realtime-base-url">Realtime Base URL (optional):</label>
+            <input type="text" id="realtime-base-url" placeholder="wss://api3.decart.ai">
+        </div>
         <div class="control-group">
             <label for="model-select">Model:</label>
             <select id="model-select">
@@ -369,6 +373,7 @@ <h3>Console Logs</h3>
         const elements = {
             apiKey: document.getElementById('api-key'),
             modelSelect: document.getElementById('model-select'),
+            realtimeBaseUrl: document.getElementById('realtime-base-url'),
             startCamera: document.getElementById('start-camera'),
             connectBtn: document.getElementById('connect-btn'),
             disconnectBtn: document.getElementById('disconnect-btn'),
@@ -492,8 +497,10 @@ <h3>Console Logs</h3>
 
                 addLog('Initializing Decart client...', 'info');
 
+                const realtimeBaseUrl = elements.realtimeBaseUrl.value.trim();
                 decartClient = createDecartClient({
                     apiKey,
+                    ...(realtimeBaseUrl && { realtimeBaseUrl }),
                 });
 
                 addLog('Connecting to Decart server...', 'info');
@@ -780,8 +787,10 @@ <h3>Console Logs</h3>
 
                 // Initialize client if not already done
                 if (!decartClient) {
+                    const realtimeBaseUrl = elements.realtimeBaseUrl.value.trim();
                     decartClient = createDecartClient({
                         apiKey,
+                        ...(realtimeBaseUrl && { realtimeBaseUrl }),
                     });
                     addLog('Initialized Decart client for processing', 'info');
                 }

packages/sdk/src/index.ts

@@ -75,6 +75,7 @@ const decartClientOptionsSchema = z
     baseUrl: z.url().optional(),
     proxy: proxySchema.optional(),
     integration: z.string().optional(),
+    realtimeBaseUrl: z.url().optional(),
   })
   .refine(
     (data) => {
@@ -96,6 +97,7 @@ export type DecartClientOptions =
       proxy: string;
       apiKey?: never;
       baseUrl?: string;
+      realtimeBaseUrl?: string;
       integration?: string;
       logger?: Logger;
       telemetry?: boolean;
@@ -104,6 +106,7 @@ export type DecartClientOptions =
       proxy?: never;
       apiKey?: string;
       baseUrl?: string;
+      realtimeBaseUrl?: string;
       integration?: string;
       logger?: Logger;
       telemetry?: boolean;
@@ -116,6 +119,7 @@ export type DecartClientOptions =
  * @param options.proxy - URL of the proxy server. When set, the client will use the proxy instead of direct API access and apiKey is not required.
  * @param options.apiKey - API key for authentication.
  * @param options.baseUrl - Override the default API base URL.
+ * @param options.realtimeBaseUrl - Override the default WebSocket base URL for realtime connections.
  * @param options.integration - Optional integration identifier.
  *
  * @example
@@ -141,10 +145,9 @@ export const createDecartClient = (options: DecartClientOptions = {}) => {
       throw createInvalidApiKeyError();
     }
 
-    if (issue.path.includes("baseUrl")) {
-      throw createInvalidBaseUrlError(
-        issue.path.includes("baseUrl") ? (options as { baseUrl?: string }).baseUrl : undefined,
-      );
+    if (issue.path.includes("baseUrl") || issue.path.includes("realtimeBaseUrl")) {
+      const urlField = issue.path.includes("realtimeBaseUrl") ? "realtimeBaseUrl" : "baseUrl";
+      throw createInvalidBaseUrlError((options as Record<string, string | undefined>)[urlField]);
     }
 
     if (issue.path.includes("proxy")) {
@@ -181,7 +184,7 @@ export const createDecartClient = (options: DecartClientOptions = {}) => {
   // Realtime (WebRTC) always requires direct API access with API key
   // Proxy mode is only for HTTP endpoints (process, queue, tokens)
   // Note: Realtime will fail at connection time if no API key is provided
-  const wsBaseUrl = "wss://api3.decart.ai";
+  const wsBaseUrl = parsedOptions.data.realtimeBaseUrl || "wss://api3.decart.ai";
   const realtime = createRealTimeClient({
     baseUrl: wsBaseUrl,
     apiKey: apiKey || "",

packages/sdk/tests/unit.test.ts

@@ -52,6 +52,18 @@ describe("Decart SDK", () => {
     it("throws an error if invalid base url is provided", () => {
       expect(() => createDecartClient({ apiKey: "test", baseUrl: "not-a-url" })).toThrow("Invalid base URL");
     });
+
+    it("throws an error if invalid realtimeBaseUrl is provided", () => {
+      expect(() => createDecartClient({ apiKey: "test", realtimeBaseUrl: "not-a-url" })).toThrow("Invalid base URL");
+    });
+
+    it("creates a client with custom realtimeBaseUrl", () => {
+      const decart = createDecartClient({
+        apiKey: "test",
+        realtimeBaseUrl: "wss://custom-ws.example.com",
+      });
+      expect(decart).toBeDefined();
+    });
   });
 
   describe("Process API", () => {