@belonguniverseai/react-sdk 0.2.0 → 0.3.1

package/README.md

@@ -59,7 +59,8 @@ by voice.
 Voice calls require the backend to be configured with an `OPENAI_API_KEY`
 (model/voice are tuned via `OPENAI_REALTIME_MODEL` / `OPENAI_REALTIME_VOICE`);
 on an unconfigured deployment the call button shows "Call mode is not enabled
-on this deployment." when tapped. Embedding hosts must allow
-the browser↔OpenAI WebRTC leg in their CSP: `connect-src
-https://api.openai.com` plus standard WebRTC permissions — audio never relays
-through the Belong backend.
+on this deployment." when tapped. Embedding hosts need **no CSP changes**:
+the WebRTC handshake (SDP offer/answer) relays through the Belong backend —
+already in your `connect-src` if the dock works at all — and the call audio
+itself is a direct browser↔OpenAI WebRTC media stream, which `connect-src`
+does not govern (audio never relays through the Belong backend).

package/dist/api/client.d.ts

@@ -1383,6 +1383,55 @@ export declare const createApiClient: (baseUrl: string) => {
             }>;
         };
     };
+} & {
+    v1: {
+        voice: {
+            "call-sdp": import('hono/client').ClientRequest<string, "/v1/voice/call-sdp", {
+                $post: {
+                    input: {};
+                    output: string;
+                    outputFormat: "body";
+                    status: 200;
+                } | {
+                    input: {};
+                    output: {
+                        error: {
+                            type: string;
+                        };
+                    };
+                    outputFormat: "json";
+                    status: 400;
+                } | {
+                    input: {};
+                    output: {
+                        error: {
+                            type: string;
+                        };
+                    };
+                    outputFormat: "json";
+                    status: 403;
+                } | {
+                    input: {};
+                    output: {
+                        error: {
+                            type: string;
+                        };
+                    };
+                    outputFormat: "json";
+                    status: 503;
+                } | {
+                    input: {};
+                    output: {
+                        error: {
+                            type: string;
+                        };
+                    };
+                    outputFormat: "json";
+                    status: 502;
+                };
+            }>;
+        };
+    };
 } & {
     v1: {
         voice: {
@@ -2949,10 +2998,27 @@ export declare const createApiClient: (baseUrl: string) => {
                         timezone: string;
                         message: string;
                         clientScheduleId: string;
+                        notification?: {
+                            kind: "completion_email";
+                        } | {
+                            kind: "custom_email";
+                            templatePath: string;
+                        } | undefined;
                         title?: string | undefined;
                         mode?: "plan" | "approve" | "balanced" | "bypass" | undefined;
                         recurrence?: {
-                            kind: "none" | "daily" | "weekdays" | "weekly";
+                            kind: "none";
+                        } | {
+                            kind: "daily";
+                        } | {
+                            kind: "weekdays";
+                        } | {
+                            kind: "weekly";
+                        } | {
+                            kind: "manual";
+                        } | {
+                            kind: "interval";
+                            intervalMinutes: number;
                         } | undefined;
                         originatingSessionId?: string | undefined;
                         workspaceExternalId?: string | undefined;
@@ -2977,10 +3043,27 @@ export declare const createApiClient: (baseUrl: string) => {
                         timezone: string;
                         message: string;
                         clientScheduleId: string;
+                        notification?: {
+                            kind: "completion_email";
+                        } | {
+                            kind: "custom_email";
+                            templatePath: string;
+                        } | undefined;
                         title?: string | undefined;
                         mode?: "plan" | "approve" | "balanced" | "bypass" | undefined;
                         recurrence?: {
-                            kind: "none" | "daily" | "weekdays" | "weekly";
+                            kind: "none";
+                        } | {
+                            kind: "daily";
+                        } | {
+                            kind: "weekdays";
+                        } | {
+                            kind: "weekly";
+                        } | {
+                            kind: "manual";
+                        } | {
+                            kind: "interval";
+                            intervalMinutes: number;
                         } | undefined;
                         originatingSessionId?: string | undefined;
                         workspaceExternalId?: string | undefined;
@@ -2995,7 +3078,7 @@ export declare const createApiClient: (baseUrl: string) => {
                     scheduledFor: string;
                     seriesStatus: "active" | "completed" | "paused" | "deleted";
                     recurrence: {
-                        kind: "none" | "daily" | "weekdays" | "weekly";
+                        kind: "none" | "manual" | "daily" | "weekdays" | "weekly" | "interval";
                     };
                     nextRunAt: string | null;
                     title: string;
@@ -3010,10 +3093,27 @@ export declare const createApiClient: (baseUrl: string) => {
                         timezone: string;
                         message: string;
                         clientScheduleId: string;
+                        notification?: {
+                            kind: "completion_email";
+                        } | {
+                            kind: "custom_email";
+                            templatePath: string;
+                        } | undefined;
                         title?: string | undefined;
                         mode?: "plan" | "approve" | "balanced" | "bypass" | undefined;
                         recurrence?: {
-                            kind: "none" | "daily" | "weekdays" | "weekly";
+                            kind: "none";
+                        } | {
+                            kind: "daily";
+                        } | {
+                            kind: "weekdays";
+                        } | {
+                            kind: "weekly";
+                        } | {
+                            kind: "manual";
+                        } | {
+                            kind: "interval";
+                            intervalMinutes: number;
                         } | undefined;
                         originatingSessionId?: string | undefined;
                         workspaceExternalId?: string | undefined;
@@ -3037,10 +3137,27 @@ export declare const createApiClient: (baseUrl: string) => {
                         timezone: string;
                         message: string;
                         clientScheduleId: string;
+                        notification?: {
+                            kind: "completion_email";
+                        } | {
+                            kind: "custom_email";
+                            templatePath: string;
+                        } | undefined;
                         title?: string | undefined;
                         mode?: "plan" | "approve" | "balanced" | "bypass" | undefined;
                         recurrence?: {
-                            kind: "none" | "daily" | "weekdays" | "weekly";
+                            kind: "none";
+                        } | {
+                            kind: "daily";
+                        } | {
+                            kind: "weekdays";
+                        } | {
+                            kind: "weekly";
+                        } | {
+                            kind: "manual";
+                        } | {
+                            kind: "interval";
+                            intervalMinutes: number;
                         } | undefined;
                         originatingSessionId?: string | undefined;
                         workspaceExternalId?: string | undefined;
@@ -3074,7 +3191,8 @@ export declare const createApiClient: (baseUrl: string) => {
                         title: string;
                         status: "active" | "completed" | "paused" | "deleted";
                         recurrence: {
-                            kind: "none" | "daily" | "weekdays" | "weekly";
+                            intervalMinutes?: number | undefined;
+                            kind: "none" | "manual" | "daily" | "weekdays" | "weekly" | "interval";
                         };
                         timezone: string;
                         nextRunAt: string | null;
@@ -3109,6 +3227,12 @@ export declare const createApiClient: (baseUrl: string) => {
                     output: {
                         explicitTitle: string | null;
                         message: string;
+                        notification: {
+                            kind: "completion_email";
+                        } | {
+                            kind: "custom_email";
+                            templatePath: string;
+                        };
                         mode: "plan" | "approve" | "balanced" | "bypass";
                         timeExpression: string;
                         anchorAt: string;
@@ -3118,7 +3242,8 @@ export declare const createApiClient: (baseUrl: string) => {
                         title: string;
                         status: "active" | "completed" | "paused" | "deleted";
                         recurrence: {
-                            kind: "none" | "daily" | "weekdays" | "weekly";
+                            intervalMinutes?: number | undefined;
+                            kind: "none" | "manual" | "daily" | "weekdays" | "weekly" | "interval";
                         };
                         timezone: string;
                         nextRunAt: string | null;
@@ -3167,7 +3292,18 @@ export declare const createApiClient: (baseUrl: string) => {
                             timeExpression?: string | undefined;
                             timezone?: string | undefined;
                             recurrence?: {
-                                kind: "none" | "daily" | "weekdays" | "weekly";
+                                kind: "none";
+                            } | {
+                                kind: "daily";
+                            } | {
+                                kind: "weekdays";
+                            } | {
+                                kind: "weekly";
+                            } | {
+                                kind: "manual";
+                            } | {
+                                kind: "interval";
+                                intervalMinutes: number;
                             } | undefined;
                         };
                     };
@@ -3197,7 +3333,18 @@ export declare const createApiClient: (baseUrl: string) => {
                             timeExpression?: string | undefined;
                             timezone?: string | undefined;
                             recurrence?: {
-                                kind: "none" | "daily" | "weekdays" | "weekly";
+                                kind: "none";
+                            } | {
+                                kind: "daily";
+                            } | {
+                                kind: "weekdays";
+                            } | {
+                                kind: "weekly";
+                            } | {
+                                kind: "manual";
+                            } | {
+                                kind: "interval";
+                                intervalMinutes: number;
                             } | undefined;
                         };
                     };
@@ -3226,7 +3373,18 @@ export declare const createApiClient: (baseUrl: string) => {
                             timeExpression?: string | undefined;
                             timezone?: string | undefined;
                             recurrence?: {
-                                kind: "none" | "daily" | "weekdays" | "weekly";
+                                kind: "none";
+                            } | {
+                                kind: "daily";
+                            } | {
+                                kind: "weekdays";
+                            } | {
+                                kind: "weekly";
+                            } | {
+                                kind: "manual";
+                            } | {
+                                kind: "interval";
+                                intervalMinutes: number;
                             } | undefined;
                         };
                     };
@@ -3255,7 +3413,18 @@ export declare const createApiClient: (baseUrl: string) => {
                             timeExpression?: string | undefined;
                             timezone?: string | undefined;
                             recurrence?: {
-                                kind: "none" | "daily" | "weekdays" | "weekly";
+                                kind: "none";
+                            } | {
+                                kind: "daily";
+                            } | {
+                                kind: "weekdays";
+                            } | {
+                                kind: "weekly";
+                            } | {
+                                kind: "manual";
+                            } | {
+                                kind: "interval";
+                                intervalMinutes: number;
                             } | undefined;
                         };
                     };
@@ -3284,7 +3453,18 @@ export declare const createApiClient: (baseUrl: string) => {
                             timeExpression?: string | undefined;
                             timezone?: string | undefined;
                             recurrence?: {
-                                kind: "none" | "daily" | "weekdays" | "weekly";
+                                kind: "none";
+                            } | {
+                                kind: "daily";
+                            } | {
+                                kind: "weekdays";
+                            } | {
+                                kind: "weekly";
+                            } | {
+                                kind: "manual";
+                            } | {
+                                kind: "interval";
+                                intervalMinutes: number;
                             } | undefined;
                         };
                     };

package/dist/api/retry-fetch.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Transparent retry for transient backend failures.
+ *
+ * Why: under a burst (many docks reloading at once) Cloud Run can reject
+ * requests at the ingress with 429 "no available instance" for the ~15s it
+ * takes to scale out — the request NEVER reaches the app, and the browser
+ * often reports it as a CORS/`Failed to fetch` TypeError because Google
+ * Frontend's reject carries no CORS headers (BEL-145's "CORS mask").
+ * Surfacing that to the user as an error is wrong: it self-heals in seconds.
+ *
+ * Policy:
+ *  - Retry on the transient status set below and on network-level rejections
+ *    (`TypeError`), with capped exponential backoff + full jitter.
+ *  - Everything else (200s, 400/401/403/404/409…) returns/throws untouched —
+ *    auth handling (401 forced-mint) stays with the callers.
+ *  - Retrying POSTs here is deliberate: an ingress 429/503 was never
+ *    processed, and the belong-cloud API is defensively idempotent where it
+ *    matters (`clientMessageId` dedupe on message posts, §18/§28 state guards
+ *    on approvals/cancels), so a replay is safe.
+ *  - `Retry-After` (seconds form) is honored when present, capped like any
+ *    other delay.
+ *  - Abort-aware: an aborted `init.signal` short-circuits both the request
+ *    and any backoff wait — a user cancel must never be held by a retry.
+ *
+ * Time and randomness are injectable (CLAUDE.md §25/§26); production callers
+ * use the exported `retryingFetch` singleton.
+ */
+export declare const TRANSIENT_STATUSES: ReadonlySet<number>;
+/** Total attempts including the first. 5 attempts ≈ 8–12s of cumulative
+ *  backoff — most of a Cloud Run scale-out window; long-lived surfaces
+ *  (chat/browser SSE) layer their own reconnect loops on top. */
+export declare const RETRY_MAX_ATTEMPTS = 5;
+export declare const RETRY_BASE_DELAY_MS = 500;
+export declare const RETRY_MAX_DELAY_MS = 6000;
+export type RetryFetchOptions = {
+    readonly fetchImpl?: typeof fetch;
+    readonly maxAttempts?: number;
+    readonly baseDelayMs?: number;
+    readonly maxDelayMs?: number;
+    /** Injectable delay (§25). Tests pass an instant recorder. */
+    readonly sleepMs?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Injectable jitter source (§26). */
+    readonly random?: () => number;
+    /** Observability hook — fired before each backoff wait. */
+    readonly onRetry?: (info: {
+        readonly attempt: number;
+        readonly status: number | null;
+        readonly delayMs: number;
+    }) => void;
+};
+/**
+ * Build a drop-in `fetch` that absorbs transient failures. The returned
+ * function matches `typeof fetch`, so it wires straight into `hc(baseUrl,
+ * { fetch })` and any raw call site.
+ */
+export declare const createRetryFetch: (options?: RetryFetchOptions) => typeof fetch;
+/** The production instance every backend call should go through. */
+export declare const retryingFetch: typeof fetch;