@bitbitpress/client 1.1.3 → 1.2.2

package/dist/generated/openapi.d.ts

@@ -4,6 +4,86 @@
  */
 
 export interface paths {
+    "/v1/auth/magic-link": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Auth - Send Magic Link
+         * @description **POST** `/v1/auth/magic-link`
+         *
+         *     Send a one-time sign-in link by email. The callback must be registered for the supplied client. The token in the link is exchanged through `POST /v1/auth/token`.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        email: string;
+                        /** @description Public identifier of the app requesting the sign-in link */
+                        clientId: string;
+                        /** @description Registered callback URL. Optional when the client has a default callback. */
+                        redirectUri?: string;
+                    };
+                };
+            };
+            responses: {
+                /** @description Default Response */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example true */
+                            success: boolean;
+                        };
+                    };
+                };
+                /** @description Bad request - missing or invalid parameters */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example Bad request */
+                            error?: string;
+                        };
+                    };
+                };
+                /** @description Internal server error */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example false */
+                            success?: boolean;
+                            /** @example Internal server error: An unknown error occurred */
+                            error?: string;
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/auth/token": {
         parameters: {
             query?: never;
@@ -93,6 +173,21 @@ export interface paths {
                         };
                     };
                 };
+                /** @description Forbidden errors */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @example Forbidden: Subscription required
+                             * @enum {string}
+                             */
+                            error: "Forbidden: Subscription required";
+                        };
+                    };
+                };
                 /** @description Internal server error */
                 500: {
                     headers: {
@@ -195,6 +290,21 @@ export interface paths {
                         };
                     };
                 };
+                /** @description Forbidden errors */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @example Forbidden: Subscription required
+                             * @enum {string}
+                             */
+                            error: "Forbidden: Subscription required";
+                        };
+                    };
+                };
                 /** @description Internal server error */
                 500: {
                     headers: {
@@ -288,6 +398,21 @@ export interface paths {
                         };
                     };
                 };
+                /** @description Forbidden errors */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @example Forbidden: Subscription required
+                             * @enum {string}
+                             */
+                            error: "Forbidden: Subscription required";
+                        };
+                    };
+                };
                 /** @description Internal server error */
                 500: {
                     headers: {
@@ -414,6 +539,21 @@ export interface paths {
                         };
                     };
                 };
+                /** @description Forbidden errors */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @example Forbidden: Subscription required
+                             * @enum {string}
+                             */
+                            error: "Forbidden: Subscription required";
+                        };
+                    };
+                };
                 /** @description Internal server error */
                 500: {
                     headers: {
@@ -510,6 +650,21 @@ export interface paths {
                         };
                     };
                 };
+                /** @description Forbidden errors */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @example Forbidden: Subscription required
+                             * @enum {string}
+                             */
+                            error: "Forbidden: Subscription required";
+                        };
+                    };
+                };
                 /** @description Internal server error */
                 500: {
                     headers: {
@@ -629,6 +784,21 @@ export interface paths {
                         };
                     };
                 };
+                /** @description Forbidden errors */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @example Forbidden: Subscription required
+                             * @enum {string}
+                             */
+                            error: "Forbidden: Subscription required";
+                        };
+                    };
+                };
                 /** @description Internal server error */
                 500: {
                     headers: {
@@ -745,6 +915,21 @@ export interface paths {
                         };
                     };
                 };
+                /** @description Forbidden errors */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @example Forbidden: Subscription required
+                             * @enum {string}
+                             */
+                            error: "Forbidden: Subscription required";
+                        };
+                    };
+                };
                 /** @description Internal server error */
                 500: {
                     headers: {
@@ -767,7 +952,7 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/v1/user/synthesize": {
+    "/v1/user/piece-events": {
         parameters: {
             query?: never;
             header?: never;
@@ -777,10 +962,8 @@ export interface paths {
         get?: never;
         put?: never;
         /**
-         * Synthesis - Synthesize Content
-         * @description **POST** `/v1/user/synthesize`
-         *
-         *     Synthesize content items personalized to the user.
+         * Synthesis - Record Piece Events
+         * @description **POST** `/v1/user/piece-events` Records behavioral events (views, clicks) for a SynthesisPiece embed, addressed by the piece's `keyName`. Batched by the SDK; powers per-piece engagement. Distinct from `/v1/user/events` (SynthesisUIs) so a keyName shared across the two entity namespaces is never misattributed.
          */
         post: {
             parameters: {
@@ -795,73 +978,45 @@ export interface paths {
             requestBody: {
                 content: {
                     "application/json": {
-                        /** @description Array of items to synthesize. Each item has inputs and output; optional configurationKeyName to use a named config (omit for default). */
-                        items: {
-                            /** @description Optional configuration key name. Loads an existing synthesis config by this name; omit for default configuration. */
-                            configurationKeyName?: string;
-                            /** @description How many recent stored synthesis outputs to expose in the streamed `synthesisHistory` / `synthesisHistoryEntries` fields. Defaults to 0 (no history emitted). When > 0, the final data event includes a `synthesisHistoryEntries` array of up to N `{ synthesisOutputId, data }` (most-recent first; each row's payload paired with its output id, so submissions can attach to a specific historical output), and — DEPRECATED, for older app builds — an index-aligned `synthesisHistory` array of the same bare `data` payloads. The first entry is the current synthesis itself — the same payload `data` is derived from — and the remaining entries are older stored rows. */
-                            synthesisHistoryLimit?: number;
-                            /** @description Per-request overrides for search options. */
-                            searchOptionsOverrides?: {
-                                /** @description Override for search lookback window in minutes (e.g. 1440 for last 24 hours). */
-                                lookbackMinutes?: number;
-                            };
-                            /** @description Inputs used as context for the synthesis: externalId (article ID), or text (freeform text). */
-                            inputs?: {
-                                /**
-                                 * @description Type of input: externalId (article) or text (freeform).
-                                 * @enum {string}
-                                 */
-                                type: "externalId" | "text" | "excludeExternalIds";
-                                /** @description External ID (e.g. article) for externalId, freeform text for text, or comma-separated list of external IDs to exclude */
-                                value: string;
-                            }[];
-                            /** @description Optional output definition. Omit to use the output schema declared on the config named by `configurationKeyName` (`output.outputSchema`). */
-                            output?: {
-                                /** @description Output schema as a JSON string. Top-level type must be "object". Supports object, string, number, boolean, array, and enum. Example: {"type":"object","properties":{"title":{"type":"string","description":"title"},"status":{"type":"string","enum":["draft","published"]}}} */
-                                schema: string;
+                        /** @description Events to record. */
+                        events: {
+                            /** @description The piece's load id (`<BitBitPiece keyName>`) the event belongs to. */
+                            keyName: string;
+                            /**
+                             * @description VIEW (the piece was shown) or CLICK (a tracked interaction).
+                             * @enum {string}
+                             */
+                            type: "VIEW" | "CLICK";
+                            /** @description For CLICK: the human-readable action name. Omit for VIEW. */
+                            name?: string;
+                            /** @description Arbitrary event properties (retained for analytics drill-down). */
+                            payload?: {
+                                [key: string]: unknown;
                             };
+                            /** @description ISO timestamp the event occurred; defaults to server time. */
+                            occurredAt?: string;
                         }[];
                     };
                 };
             };
             responses: {
-                /**
-                 * @description Streaming response (Server-Sent Events). Each event is a JSON object sent as `data: {JSON}\n\n`.
-                 *
-                 *     **Connection Events:**
-                 *     ```json
-                 *     {"type":"connected" | "complete"}
-                 *     ```
-                 *
-                 *     **Data Events (success):**
-                 *     ```json
-                 *     {
-                 *       "index": number,
-                 *       "data": {...},
-                 *       "synthesisHistory"?: [{...}, ...],
-                 *       "complete": false | true
-                 *     }
-                 *     ```
-                 *     `data` is always a single synthesized object (keys match your output schema). `complete` is `false` for partial streaming updates and `true` for the final validated payload.
-                 *
-                 *     When `synthesisHistoryLimit > 0`, the final event additionally includes `synthesisHistoryEntries`: an array of up to N entries (most-recent first), each `{ synthesisOutputId, data }`, so a client can attach submissions (e.g. poll votes) to a specific historical output. The first entry is the current synthesis itself — the raw payload `data` is derived from (identical to `data` when reranking isn't configured; the unreranked source when it is) — and the remaining entries are older stored rows. A DEPRECATED `synthesisHistory` field (index-aligned bare `data` payloads) is also included for older app builds. The primary `data` field stays a single object — when user reranking is configured, it is built by pooling items at the reranking field across the fetched rows and scoring against the user profile.
-                 *
-                 *     **Data Events (error):**
-                 *     ```json
-                 *     {
-                 *       "index": number,
-                 *       "error": "error message"
-                 *     }
-                 *     ```
-                 *     Sent when synthesis fails for that item (e.g. resolve failure, exception).
-                 */
+                /** @description Events recorded */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": string;
+                        "application/json": {
+                            /** @example true */
+                            success: boolean;
+                            data: {
+                                /**
+                                 * @description Whether any event resolved to a known piece and was recorded.
+                                 * @example true
+                                 */
+                                recorded: boolean;
+                            };
+                        };
                     };
                 };
                 /** @description Bad request - missing or invalid parameters */
@@ -913,7 +1068,7 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/v1/user/synthesize-ui": {
+    "/v1/user/synthesize": {
         parameters: {
             query?: never;
             header?: never;
@@ -923,12 +1078,10 @@ export interface paths {
         get?: never;
         put?: never;
         /**
-         * Synthesis - Synthesize UI
-         * @description **POST** `/v1/user/synthesize-ui`
-         *
-         *     Resolve one or more generated UIs in a single request, each identified by its `keyName`. Works exactly like `/v1/user/synthesize` — same per-item synthesis inputs (`inputs`, `output.schema`, `searchOptionsOverrides`, `synthesisHistoryLimit`) and the same personalized, streamed `data` — except it additionally returns the UI code bundle to render that data. The synthesis runs against the config attached to each UI.
+         * Synthesis - Synthesize Content
+         * @description **POST** `/v1/user/synthesize`
          *
-         *     Streams as Server-Sent Events so the client can load the (cacheable) code bundle immediately and render synthesis `data` as it arrives. The code bundle is immutable per published version and identical for every app user, so it is served from a CDN by versioned `bundleUrl` and cached once across renders and users. `data` is the per-request, per-user piece and may stream in partials before a final `complete: true` event. `theme` is deployment-level and emitted once in the `manifest`. (`bundleSource` is an inlined fallback used only while bundles are served inline, before CDN delivery.)
+         *     Synthesize content items personalized to the user.
          */
         post: {
             parameters: {
@@ -943,16 +1096,179 @@ export interface paths {
             requestBody: {
                 content: {
                     "application/json": {
-                        /**
-                         * @description Target platform for the bundles, for the whole request. Defaults to `web`.
-                         * @enum {string}
-                         */
-                        platform?: "web" | "mobile";
-                        /** @description UIs to resolve in this request. */
+                        /** @description Array of items to synthesize. Each item has inputs and output; optional configurationKeyName to use a named config (omit for default). */
                         items: {
-                            /** @description Stable identifier of the UI to load. Configured in the CMS. */
-                            keyName: string;
-                            /** @description How many recent stored synthesis outputs to expose in the streamed `synthesisHistory` / `synthesisHistoryEntries` fields. Defaults to 0. See `/v1/user/synthesize` for the full semantics. */
+                            /** @description Optional configuration key name. Loads an existing synthesis config by this name; omit for default configuration. */
+                            configurationKeyName?: string;
+                            /** @description How many recent stored synthesis outputs to expose in the streamed `synthesisHistory` / `synthesisHistoryEntries` fields. Defaults to 0 (no history emitted). When > 0, the final data event includes a `synthesisHistoryEntries` array of up to N `{ synthesisOutputId, data }` (most-recent first; each row's payload paired with its output id, so submissions can attach to a specific historical output), and — DEPRECATED, for older app builds — an index-aligned `synthesisHistory` array of the same bare `data` payloads. The first entry is the current synthesis itself — the same payload `data` is derived from — and the remaining entries are older stored rows. */
+                            synthesisHistoryLimit?: number;
+                            /** @description Per-request overrides for search options. */
+                            searchOptionsOverrides?: {
+                                /** @description Override for search lookback window in minutes (e.g. 1440 for last 24 hours). */
+                                lookbackMinutes?: number;
+                            };
+                            /** @description Inputs used as context for the synthesis: externalId (article ID), or text (freeform text). */
+                            inputs?: {
+                                /**
+                                 * @description Type of input: externalId (article) or text (freeform).
+                                 * @enum {string}
+                                 */
+                                type: "externalId" | "text" | "excludeExternalIds";
+                                /** @description External ID (e.g. article) for externalId, freeform text for text, or comma-separated list of external IDs to exclude */
+                                value: string;
+                            }[];
+                            /** @description Optional output definition. Omit to use the output schema declared on the config named by `configurationKeyName` (`output.outputSchema`). */
+                            output?: {
+                                /** @description Output schema as a JSON string. Top-level type must be "object". Supports object, string, number, boolean, array, and enum. Example: {"type":"object","properties":{"title":{"type":"string","description":"title"},"status":{"type":"string","enum":["draft","published"]}}} */
+                                schema: string;
+                            };
+                        }[];
+                    };
+                };
+            };
+            responses: {
+                /**
+                 * @description Streaming response (Server-Sent Events). Each event is a JSON object sent as `data: {JSON}\n\n`.
+                 *
+                 *     **Connection Events:**
+                 *     ```json
+                 *     {"type":"connected" | "complete"}
+                 *     ```
+                 *
+                 *     **Data Events (success):**
+                 *     ```json
+                 *     {
+                 *       "index": number,
+                 *       "data": {...},
+                 *       "synthesisHistory"?: [{...}, ...],
+                 *       "complete": false | true
+                 *     }
+                 *     ```
+                 *     `data` is always a single synthesized object (keys match your output schema). `complete` is `false` for partial streaming updates and `true` for the final validated payload.
+                 *
+                 *     When `synthesisHistoryLimit > 0`, the final event additionally includes `synthesisHistoryEntries`: an array of up to N entries (most-recent first), each `{ synthesisOutputId, data }`, so a client can attach submissions (e.g. poll votes) to a specific historical output. The first entry is the current synthesis itself — the raw payload `data` is derived from (identical to `data` when reranking isn't configured; the unreranked source when it is) — and the remaining entries are older stored rows. A DEPRECATED `synthesisHistory` field (index-aligned bare `data` payloads) is also included for older app builds. The primary `data` field stays a single object — when user reranking is configured, it is built by pooling items at the reranking field across the fetched rows and scoring against the user profile.
+                 *
+                 *     **Data Events (error):**
+                 *     ```json
+                 *     {
+                 *       "index": number,
+                 *       "error": "error message"
+                 *     }
+                 *     ```
+                 *     Sent when synthesis fails for that item (e.g. resolve failure, exception).
+                 */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": string;
+                    };
+                };
+                /** @description Bad request - missing or invalid parameters */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example Bad request */
+                            error?: string;
+                        };
+                    };
+                };
+                /** @description Unauthorized errors */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @example Unauthorized: No authentication token provided
+                             * @enum {string}
+                             */
+                            error?: "Unauthorized: No authentication token provided" | "Unauthorized: Token has expired" | "Unauthorized: Invalid token" | "Unauthorized: Authentication failed";
+                        };
+                    };
+                };
+                /** @description Forbidden errors */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @example Forbidden: Subscription required
+                             * @enum {string}
+                             */
+                            error: "Forbidden: Subscription required";
+                        };
+                    };
+                };
+                /** @description Internal server error */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example false */
+                            success?: boolean;
+                            /** @example Internal server error: An unknown error occurred */
+                            error?: string;
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/user/synthesize-ui": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Synthesis - Synthesize UI
+         * @description **POST** `/v1/user/synthesize-ui`
+         *
+         *     Resolve one or more generated UIs in a single request, each identified by its `keyName`. Works exactly like `/v1/user/synthesize` — same per-item synthesis inputs (`inputs`, `output.schema`, `searchOptionsOverrides`, `synthesisHistoryLimit`) and the same personalized, streamed `data` — except it additionally returns the UI code bundle to render that data. The synthesis runs against the config attached to each UI.
+         *
+         *     Streams as Server-Sent Events so the client can load the (cacheable) code bundle immediately and render synthesis `data` as it arrives. The code bundle is immutable per published version and identical for every app user, so it is served from a CDN by versioned `bundleUrl` and cached once across renders and users. `data` is the per-request, per-user piece and may stream in partials before a final `complete: true` event. `theme` is deployment-level and emitted once in the `manifest`. (`bundleSource` is an inlined fallback used only while bundles are served inline, before CDN delivery.)
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header: {
+                    /** @description Bearer token for authentication */
+                    authorization: string;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        /**
+                         * @description Target platform for the bundles, for the whole request. Defaults to `web`.
+                         * @enum {string}
+                         */
+                        platform?: "web" | "mobile";
+                        /** @description UIs to resolve in this request. */
+                        items: {
+                            /** @description Stable identifier of the UI to load. Configured in the CMS. */
+                            keyName: string;
+                            /** @description How many recent stored synthesis outputs to expose in the streamed `synthesisHistory` / `synthesisHistoryEntries` fields. Defaults to 0. See `/v1/user/synthesize` for the full semantics. */
                             synthesisHistoryLimit?: number;
                             /** @description Per-request overrides for search options. */
                             searchOptionsOverrides?: {
@@ -1043,6 +1359,350 @@ export interface paths {
                         };
                     };
                 };
+                /** @description Forbidden errors */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @example Forbidden: Subscription required
+                             * @enum {string}
+                             */
+                            error: "Forbidden: Subscription required";
+                        };
+                    };
+                };
+                /** @description Internal server error */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example false */
+                            success?: boolean;
+                            /** @example Internal server error: An unknown error occurred */
+                            error?: string;
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/user/synthesis-piece": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * User - Get Synthesis Pieces
+         * @description **POST** `/v1/user/synthesis-piece`
+         *
+         *     Fetch one or more published pieces to display, each by its `keyName`. For every requested piece you receive its ready-to-render view (`uiWebCode`), its current content (`fields`), and your workspace's display theme (`theme`, the same for every piece). Render the view and give it the content as its data. Results come back in the same order as the pieces you requested; if a piece can't be found or isn't published, its result contains an `error` message in place of the content.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header: {
+                    /** @description Bearer token for authentication */
+                    authorization: string;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        /** @description The pieces to fetch, each by its key. */
+                        items: {
+                            /** @description The piece's unique key. */
+                            keyName: string;
+                        }[];
+                    };
+                };
+            };
+            responses: {
+                /** @description Successful response */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example true */
+                            success: boolean;
+                            data: {
+                                /** @description Your workspace's brand theme as CSS custom properties (the same for every piece). */
+                                theme: {
+                                    [key: string]: string;
+                                };
+                                /** @description One result per requested piece, in the same order. */
+                                items: ({
+                                    /** @description Position of this result in the requested list. */
+                                    index: number;
+                                    /** @description The piece's ready-to-render view. */
+                                    uiWebCode?: string;
+                                    /** @description The piece's current content, given to the view as its data (includes ready-to-play audio for audio pieces). */
+                                    fields?: {
+                                        [key: string]: unknown;
+                                    };
+                                    /** @description A message explaining why this piece couldn't be returned. */
+                                    error?: string;
+                                } & {
+                                    [key: string]: unknown;
+                                })[];
+                            };
+                        };
+                    };
+                };
+                /** @description Bad request - missing or invalid parameters */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example Bad request */
+                            error?: string;
+                        };
+                    };
+                };
+                /** @description Unauthorized errors */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @example Unauthorized: No authentication token provided
+                             * @enum {string}
+                             */
+                            error?: "Unauthorized: No authentication token provided" | "Unauthorized: Token has expired" | "Unauthorized: Invalid token" | "Unauthorized: Authentication failed";
+                        };
+                    };
+                };
+                /** @description Internal server error */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example false */
+                            success?: boolean;
+                            /** @example Internal server error: An unknown error occurred */
+                            error?: string;
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/user/synthesis-piece/tts": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * User - Synthesize Piece Audio
+         * @description **POST** `/v1/user/synthesis-piece/tts`
+         *
+         *     Mint a short-lived, self-authenticating HLS URL for a published piece's spoken content. A media player calls this when the listener presses play, then plays the returned `url` (via the SDK's `ctx.playMedia`) to stream the synthesized speech on demand. The request REFERENCES the piece's content — omit `field` for the whole piece's spoken content, pass a top-level `field` to scope to it, and/or `index` for a single turn — and the server resolves the turns from the piece itself (so the URL never carries the text). The URL is gated at issue time (it expires ~30 minutes after minting, and only PUBLISHED pieces), so a fresh URL can't be minted after a piece is unpublished. Note: the URL is an HLS playlist whose audio segments are content-addressed and cached long-lived — a player that already loaded a URL may keep playing that audio from cache after the URL expires or the piece is unpublished.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header: {
+                    /** @description Bearer token for authentication */
+                    authorization: string;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        /** @description The piece's unique key. */
+                        keyName: string;
+                        /** @description Top-level field to voice. Omit for the whole piece's spoken content. */
+                        field?: string;
+                        /** @description A single turn index within the resolved content. Omit for all turns. */
+                        index?: number;
+                    };
+                };
+            };
+            responses: {
+                /** @description Successful response */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example true */
+                            success: boolean;
+                            data: {
+                                /** @description A short-lived streaming URL to point an `<audio>` element at. */
+                                url?: string;
+                                /** @description Set instead of `url` when audio can't be produced (piece not found/published, or the text isn't part of the piece). */
+                                error?: string;
+                            };
+                        };
+                    };
+                };
+                /** @description Bad request - missing or invalid parameters */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example Bad request */
+                            error?: string;
+                        };
+                    };
+                };
+                /** @description Unauthorized errors */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @example Unauthorized: No authentication token provided
+                             * @enum {string}
+                             */
+                            error?: "Unauthorized: No authentication token provided" | "Unauthorized: Token has expired" | "Unauthorized: Invalid token" | "Unauthorized: Authentication failed";
+                        };
+                    };
+                };
+                /** @description Internal server error */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example false */
+                            success?: boolean;
+                            /** @example Internal server error: An unknown error occurred */
+                            error?: string;
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/user/synthesis/tts": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * User - Synthesize Synthesis Output Audio
+         * @description **POST** `/v1/user/synthesis/tts`
+         *
+         *     Mint a short-lived, self-authenticating HLS URL for the authenticated app user's own stored synthesis output — the on-request audio entry point a rendered SynthesisUI's `ctx.tts` calls when the listener presses play. The request REFERENCES the output's spoken content by `synthesisOutputId` (the id returned with the synthesis result) — omit `field` for the whole output's spoken content, pass a top-level `field` to scope to it, and/or `index` for a single turn — and the server reloads the turns from the stored output row (so the URL never carries the text). The URL is gated at mint by OWNERSHIP (only the app user who owns the output can mint it) and expires ~30 minutes after minting. Note: the URL is an HLS playlist whose audio segments are content-addressed and cached long-lived — a player that already loaded a URL may keep playing that audio from cache after the URL expires.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header: {
+                    /** @description Bearer token for authentication */
+                    authorization: string;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        /** @description The id of the synthesis output to voice (returned with the synthesis result). */
+                        synthesisOutputId: string;
+                        /** @description Top-level field to voice. Omit for the whole output's spoken content. */
+                        field?: string;
+                        /** @description A single turn index within the resolved content. Omit for all turns. */
+                        index?: number;
+                    };
+                };
+            };
+            responses: {
+                /** @description Successful response */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example true */
+                            success: boolean;
+                            data: {
+                                /** @description A short-lived streaming URL to point an `<audio>` element at. */
+                                url?: string;
+                                /** @description Set instead of `url` when audio can't be produced (output not found/not owned, or the text isn't part of the output). */
+                                error?: string;
+                            };
+                        };
+                    };
+                };
+                /** @description Bad request - missing or invalid parameters */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @example Bad request */
+                            error?: string;
+                        };
+                    };
+                };
+                /** @description Unauthorized errors */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @example Unauthorized: No authentication token provided
+                             * @enum {string}
+                             */
+                            error?: "Unauthorized: No authentication token provided" | "Unauthorized: Token has expired" | "Unauthorized: Invalid token" | "Unauthorized: Authentication failed";
+                        };
+                    };
+                };
                 /** @description Internal server error */
                 500: {
                     headers: {
@@ -1150,10 +1810,25 @@ export interface paths {
                     content: {
                         "application/json": {
                             /**
-                             * @example Unauthorized: No authentication token provided
+                             * @example Unauthorized: No authentication token provided
+                             * @enum {string}
+                             */
+                            error?: "Unauthorized: No authentication token provided" | "Unauthorized: Token has expired" | "Unauthorized: Invalid token" | "Unauthorized: Authentication failed";
+                        };
+                    };
+                };
+                /** @description Forbidden errors */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @example Forbidden: Subscription required
                              * @enum {string}
                              */
-                            error?: "Unauthorized: No authentication token provided" | "Unauthorized: Token has expired" | "Unauthorized: Invalid token" | "Unauthorized: Authentication failed";
+                            error: "Forbidden: Subscription required";
                         };
                     };
                 };
@@ -1270,6 +1945,21 @@ export interface paths {
                         };
                     };
                 };
+                /** @description Forbidden errors */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @example Forbidden: Subscription required
+                             * @enum {string}
+                             */
+                            error: "Forbidden: Subscription required";
+                        };
+                    };
+                };
                 /** @description Default Response */
                 404: {
                     headers: {
@@ -1376,6 +2066,21 @@ export interface paths {
                         };
                     };
                 };
+                /** @description Forbidden errors */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @example Forbidden: Subscription required
+                             * @enum {string}
+                             */
+                            error: "Forbidden: Subscription required";
+                        };
+                    };
+                };
                 /** @description Internal server error */
                 500: {
                     headers: {
@@ -1482,6 +2187,21 @@ export interface paths {
                         };
                     };
                 };
+                /** @description Forbidden errors */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /**
+                             * @example Forbidden: Subscription required
+                             * @enum {string}
+                             */
+                            error: "Forbidden: Subscription required";
+                        };
+                    };
+                };
                 /** @description Not found */
                 404: {
                     headers: {
@@ -1606,248 +2326,18 @@ export interface paths {
                         };
                     };
                 };
-                /** @description Internal server error */
-                500: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            /** @example false */
-                            success?: boolean;
-                            /** @example Internal server error: An unknown error occurred */
-                            error?: string;
-                        };
-                    };
-                };
-            };
-        };
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/v1/user-submissions": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /**
-         * User Submissions - Create Submission
-         * @description **POST** `/v1/user-submissions` Creates a structured user submission and optional presigned file upload URLs.
-         */
-        post: {
-            parameters: {
-                query?: never;
-                header: {
-                    authorization: string;
-                };
-                path?: never;
-                cookie?: never;
-            };
-            requestBody: {
-                content: {
-                    "application/json": {
-                        synthesisOutputId: string;
-                        synthesisOutputContentKey?: string;
-                        data: {
-                            [key: string]: unknown;
-                        };
-                        files?: {
-                            field: string;
-                            contentType: string;
-                            fileName?: string;
-                        }[];
-                    };
-                };
-            };
-            responses: {
-                /** @description Default Response */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            success: boolean;
-                            data: {
-                                submission: {
-                                    id: string;
-                                    synthesisConfigId: string;
-                                    synthesisOutputId: string;
-                                    synthesisOutputContentKey: string;
-                                    appUserId: string;
-                                    state: string;
-                                    createdAt: string;
-                                    updatedAt?: string;
-                                } & {
-                                    [key: string]: unknown;
-                                };
-                                uploads: {
-                                    field: string;
-                                    s3Key: string;
-                                    uploadUrl: string;
-                                }[];
-                            };
-                        };
-                    };
-                };
-                /** @description Bad request - missing or invalid parameters */
-                400: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            /** @example Bad request */
-                            error?: string;
-                        };
-                    };
-                };
-                /** @description Unauthorized errors */
-                401: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            /**
-                             * @example Unauthorized: No authentication token provided
-                             * @enum {string}
-                             */
-                            error?: "Unauthorized: No authentication token provided" | "Unauthorized: Token has expired" | "Unauthorized: Invalid token" | "Unauthorized: Authentication failed";
-                        };
-                    };
-                };
-                /** @description Not found */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            /** @example Not found */
-                            error?: string;
-                        };
-                    };
-                };
-                /** @description Internal server error */
-                500: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            /** @example false */
-                            success?: boolean;
-                            /** @example Internal server error: An unknown error occurred */
-                            error?: string;
-                        };
-                    };
-                };
-            };
-        };
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/v1/user-submission-schemas/{keyName}/submissions": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        /**
-         * User Submissions - List Live Submissions
-         * @description **GET** `/v1/user-submission-schemas/:keyName/submissions` Lists live submissions for a schema. Customer apps cannot read non-live submissions.
-         */
-        get: {
-            parameters: {
-                query?: {
-                    first?: number;
-                    after?: string;
-                };
-                header: {
-                    authorization: string;
-                };
-                path: {
-                    keyName: string;
-                };
-                cookie?: never;
-            };
-            requestBody?: never;
-            responses: {
-                /** @description Default Response */
-                200: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            success: boolean;
-                            data: {
-                                cursor: null | string;
-                                items: {
-                                    id: string;
-                                    data: {
-                                        [key: string]: unknown;
-                                    };
-                                    files: {
-                                        field: string;
-                                        contentType: string;
-                                        fileName?: string;
-                                        downloadUrl: string;
-                                    }[];
-                                    createdAt: string;
-                                }[];
-                            };
-                        };
-                    };
-                };
-                /** @description Bad request - missing or invalid parameters */
-                400: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            /** @example Bad request */
-                            error?: string;
-                        };
-                    };
-                };
-                /** @description Unauthorized errors */
-                401: {
+                /** @description Forbidden errors */
+                403: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
                         "application/json": {
                             /**
-                             * @example Unauthorized: No authentication token provided
+                             * @example Forbidden: Subscription required
                              * @enum {string}
                              */
-                            error?: "Unauthorized: No authentication token provided" | "Unauthorized: Token has expired" | "Unauthorized: Invalid token" | "Unauthorized: Authentication failed";
-                        };
-                    };
-                };
-                /** @description Not found */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": {
-                            /** @example Not found */
-                            error?: string;
+                            error: "Forbidden: Subscription required";
                         };
                     };
                 };
@@ -1867,8 +2357,6 @@ export interface paths {
                 };
             };
         };
-        put?: never;
-        post?: never;
         delete?: never;
         options?: never;
         head?: never;