@serviceai/api-spec 1.1.23 → 1.2.1

package/types.d.ts

@@ -1064,7 +1064,6 @@ export interface paths {
                                 position: {
                                     x: number;
                                     y: number;
-                                    z: number;
                                 };
                                 width: number;
                                 height: number;
@@ -1080,7 +1079,6 @@ export interface paths {
                                 position: {
                                     x: number;
                                     y: number;
-                                    z: number;
                                 };
                                 width: number;
                                 height: number;
@@ -1096,7 +1094,6 @@ export interface paths {
                                 position: {
                                     x: number;
                                     y: number;
-                                    z: number;
                                 };
                                 width: number;
                                 height: number;
@@ -1198,7 +1195,6 @@ export interface paths {
                                     position: {
                                         x: number;
                                         y: number;
-                                        z: number;
                                     };
                                     width: number;
                                     height: number;
@@ -1214,7 +1210,6 @@ export interface paths {
                                     position: {
                                         x: number;
                                         y: number;
-                                        z: number;
                                     };
                                     width: number;
                                     height: number;
@@ -1230,7 +1225,6 @@ export interface paths {
                                     position: {
                                         x: number;
                                         y: number;
-                                        z: number;
                                     };
                                     width: number;
                                     height: number;
@@ -1278,6 +1272,552 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/chatty-voice/tools": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List the OpenAI-Realtime-compatible function tools the executor can run.
+         * @description Returns the canonical Chatty Voice tool catalogue as a BARE ARRAY of `ChattyToolDefinition` envelopes (no wrapping object). Each entry is executable via POST /api/chatty-voice/tools/execute.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: {
+                    /** @description Semver of the calling app build. Drives the 426 / soft-upgrade handshake. */
+                    "X-Client-Version"?: string;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Bare array of tool definitions. */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @enum {string} */
+                            type: "function";
+                            function: {
+                                name: string;
+                                description: string;
+                                parameters: {
+                                    /** @enum {string} */
+                                    type: "object";
+                                    properties: {
+                                        [key: string]: {
+                                            [key: string]: unknown;
+                                        } & {
+                                            type: string | string[];
+                                            description?: string;
+                                            enum?: string[];
+                                            required?: string[];
+                                            additionalProperties?: boolean;
+                                        };
+                                    };
+                                    required?: string[];
+                                    additionalProperties?: boolean;
+                                };
+                            };
+                        }[];
+                    };
+                };
+                /** @description Unauthenticated. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Caller lacks the chatty-voice entitlement. */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Client major below minClientVersion. */
+                426: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["UpgradeRequiredEnvelope"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/chatty-voice/tools/execute": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Execute a Chatty Voice tool by canonical `function` (or legacy `name`).
+         * @description Body accepts either the canonical `function` field or the legacy `name` alias — at least one is required. The executor treats them as equivalent and dispatches to the same switch case in `tools.ts`. Tool arguments are passed through verbatim as an opaque JSON object.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: {
+                    /** @description Semver of the calling app build. Drives the 426 / soft-upgrade handshake. */
+                    "X-Client-Version"?: string;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": {
+                        function?: string;
+                        name?: string;
+                        arguments?: {
+                            [key: string]: unknown;
+                        };
+                    };
+                };
+            };
+            responses: {
+                /** @description Always returned when execution reaches the executor. `success: false` envelopes carry an `error` and (for permission denials) a `code` — including the missing/unknown function case. */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            success: boolean;
+                            message?: string;
+                            error?: string;
+                            code?: string;
+                            data?: unknown;
+                            action?: unknown;
+                        };
+                    };
+                };
+                /** @description Unauthenticated. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Caller lacks the chatty-voice entitlement or a per-tool permission. */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Unhandled executor error. Body is `{ success: false, error }` (same envelope as 200). */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            success: boolean;
+                            message?: string;
+                            error?: string;
+                            code?: string;
+                            data?: unknown;
+                            action?: unknown;
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/chatty-voice/ai-context": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Fetch the Chatty Voice system prompt + load-status flags. */
+        get: {
+            parameters: {
+                query?: never;
+                header?: {
+                    /** @description Semver of the calling app build. Drives the 426 / soft-upgrade handshake. */
+                    "X-Client-Version"?: string;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description System instructions + knowledge-base / workflow-stage load flags. */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            instructions: string;
+                            knowledgeBaseLoaded: boolean;
+                            workflowStagesLoaded: boolean;
+                            timestamp: string;
+                        };
+                    };
+                };
+                /** @description Unauthenticated. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Caller lacks the chatty-voice entitlement. */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/realtime-token": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Mint an OpenAI Realtime ephemeral session token (single union object).
+         * @description Body: `{ directWebRTC?: boolean }`. Response is a SINGLE union object — the directWebRTC, desktop server-proxied, and HTTP-fallback branches all share the same envelope. Only `fallback` is always present; every other field is optional and presence depends on the branch.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: {
+                    /** @description Semver of the calling app build. Drives the 426 / soft-upgrade handshake. */
+                    "X-Client-Version"?: string;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": {
+                        directWebRTC?: boolean;
+                    };
+                };
+            };
+            responses: {
+                /** @description Session minted (or fallback signalled). See union shape. */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            sessionId?: string;
+                            model?: string;
+                            voice?: string;
+                            clientSecret?: string;
+                            fallback: boolean;
+                            directWebRTC?: boolean;
+                            useWebRTC?: boolean;
+                            expiresInSeconds?: number;
+                            metadata?: {
+                                organizationId: string | number;
+                            };
+                            message?: string;
+                        };
+                    };
+                };
+                /** @description Unauthenticated. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Caller lacks the chatty-voice entitlement. */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Method Not Allowed (POST only). */
+                405: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Per-user rate limit on token mint. */
+                429: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Mint failure — body still carries `fallback: true`. */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            sessionId?: string;
+                            model?: string;
+                            voice?: string;
+                            clientSecret?: string;
+                            fallback: boolean;
+                            directWebRTC?: boolean;
+                            useWebRTC?: boolean;
+                            expiresInSeconds?: number;
+                            metadata?: {
+                                organizationId: string | number;
+                            };
+                            message?: string;
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/csrf-token": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Mint a short-lived CSRF token for the WebRTC SDP exchange.
+         * @description Returned token is required as `X-CSRF-Token` on POST /api/realtime/webrtc and is bound to the calling user for 5 minutes.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: {
+                    /** @description Semver of the calling app build. Drives the 426 / soft-upgrade handshake. */
+                    "X-Client-Version"?: string;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Fresh CSRF token. */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            token: string;
+                        };
+                    };
+                };
+                /** @description Unauthenticated. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Caller lacks the chatty-voice entitlement. */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/realtime/webrtc": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Server-proxied OpenAI Realtime SDP exchange (desktop branch).
+         * @description Request body is JSON `{ sdp }`; the server mints a fresh OpenAI ephemeral client_secret, forwards the raw SDP to OpenAI's WebRTC endpoint, and returns the raw SDP answer as `application/sdp` text. CSRF-protected via `X-CSRF-Token` (see GET /api/csrf-token) and rate-limited to 3 req/min/IP.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header: {
+                    /** @description Semver of the calling app build. Drives the 426 / soft-upgrade handshake. */
+                    "X-Client-Version"?: string;
+                    /** @description CSRF token previously minted by GET /api/csrf-token. */
+                    "X-CSRF-Token": string;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": {
+                        sdp: string;
+                    };
+                };
+            };
+            responses: {
+                /** @description Raw OpenAI SDP answer (text body, not JSON). */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/sdp": string;
+                    };
+                };
+                /** @description Invalid SDP format. */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Unauthenticated. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Caller lacks the chatty-voice entitlement, or CSRF token invalid. */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Rate limit (3 req/min/IP). */
+                429: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description SDP exchange failed locally. */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Local failure minting the OpenAI ephemeral client_secret required to authenticate the SDP exchange. Returned as a JSON envelope generated by this server: `{ error, status? }`. */
+                502: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            error: string;
+                            status?: number;
+                        };
+                    };
+                };
+                /** @description Upstream OpenAI SDP exchange error. Pass-through: this endpoint forwards OpenAI's HTTP status verbatim (typically 4xx/5xx) and the body is OpenAI's raw error payload — NOT a JSON envelope generated by this server. Content-Type and exact shape are determined by OpenAI; clients MUST treat any non-200 response on this endpoint as opaque error text unless they explicitly detect the 502 JSON envelope above. */
+                default: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": unknown;
+                        "text/plain": string;
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -1302,7 +1842,7 @@ export interface components {
         };
         /** @description Cross-platform version handshake manifest. See docs/api-versioning.md. */
         VersionManifest: {
-            /** @example 1.1.23 */
+            /** @example 1.2.1 */
             apiVersion: string;
             /** @example 1.0.0 */
             minClientVersion: string;
@@ -1594,19 +2134,37 @@ export interface components {
             orgId: number;
             role: string;
         };
-        /** @description POST /api/jobs/:jobId/scans/mobile-upload body. Required: `roomPlanJSON` (object with nested `rooms` array) + `name`. All other fields are additive / optional per the v2 contract. */
+        /** @description POST /api/jobs/:jobId/scans/mobile-upload body. v5 of the LiDAR contract (Task #879) — additive over v3/v4. Required: `roomPlanJSON` (object with nested `rooms` array) + `name`. All v3 and v4 payloads remain accepted byte-for-byte. New first-class fields: per-room `roomLocalId`, `pins[]`, `objects[]`, `boundaryPolygon[]`, per-wall `captureMetadata`; append-room `parentScanId`, `entryDoorwayId`, `entryDoorwayWallIndex`, `entryDoorwayPosition`; opening `position` is 2D `{x, y}` (an additional `z` is tolerated for backwards compatibility but ignored by the server). `wallConfidences` advertises the canonical nested `(number[] | null)[]` shape; the two legacy shapes (flat `number[]` and `Record<roomLocalIdOrIndex, number[]>`) are still parsed by `normalizeWallConfidences` in `server/routes/lidar.ts`. */
         MobileUploadRequest: {
+            /** @description RoomPlan JSON envelope. `rooms[]` carries the per-room geometry (walls/doors/windows/openings/pins/objects/boundaryPolygon). iOS continues to upload positions in the RoomPlan-native frame; the server applies the view-alignment intake transform once at `/scans/mobile-upload` (see docs/lidar-contract-v4.md). */
             roomPlanJSON: {
                 rooms: {
                     label?: string;
                     name?: string;
                     category?: string;
-                    walls?: unknown[];
+                    roomLocalId?: string;
+                    walls?: {
+                        start?: {
+                            x: number;
+                            y: number;
+                        };
+                        end?: {
+                            x: number;
+                            y: number;
+                        };
+                        length?: number;
+                        height?: number;
+                        captureMetadata?: {
+                            identifier?: string;
+                            isDoor?: boolean;
+                            isOpening?: boolean;
+                        };
+                        captureMethod?: string;
+                    }[];
                     doors?: {
                         position: {
                             x: number;
                             y: number;
-                            z: number;
                         };
                         width: number;
                         height: number;
@@ -1621,7 +2179,6 @@ export interface components {
                         position: {
                             x: number;
                             y: number;
-                            z: number;
                         };
                         width: number;
                         height: number;
@@ -1636,7 +2193,6 @@ export interface components {
                         position: {
                             x: number;
                             y: number;
-                            z: number;
                         };
                         width: number;
                         height: number;
@@ -1647,6 +2203,35 @@ export interface components {
                         /** @enum {string} */
                         placementSource?: "auto" | "manual";
                     }[];
+                    pins?: {
+                        id: string;
+                        position: {
+                            x: number;
+                            y: number;
+                        };
+                        label?: string;
+                        roomLocalId?: string;
+                        kind?: string;
+                        note?: string;
+                    }[];
+                    objects?: {
+                        category?: string;
+                        position?: {
+                            x: number;
+                            y: number;
+                        };
+                        dimensions?: {
+                            width?: number;
+                            height?: number;
+                            depth?: number;
+                        };
+                    }[];
+                    boundaryPolygon?: {
+                        x: number;
+                        y: number;
+                    }[];
+                    roomNote?: string;
+                    entryDoorwayId?: string;
                 }[];
             };
             name: string;
@@ -1655,7 +2240,10 @@ export interface components {
             autoMeasure?: boolean;
             cleanupPipelineVersion?: string;
             userOrientationHint?: string;
-            wallConfidences?: unknown[];
+            /** @description Per-room per-wall capture confidences. Canonical shape: nested `(number[] | null)[]` parallel to `roomPlanJSON.rooms[]`. Two legacy shapes are still accepted for backwards compatibility but should not be emitted by new clients: a flat `number[]` (treated as room[0] confidences) and an object keyed by `roomLocalId` (or numeric index as string). See `normalizeWallConfidences` in `server/routes/lidar.ts`. */
+            wallConfidences?: (number[] | null)[] | number[] | {
+                [key: string]: number[];
+            };
             deviceTrack?: unknown;
             referencePhotos?: unknown[];
             propertyId?: number;
@@ -1683,6 +2271,14 @@ export interface components {
             sessionId?: string;
             sessionCapturedAt?: string;
             clientMirrorApplied?: boolean;
+            parentScanId?: number;
+            /** @description Append-room doorway link to a target room on the parent composite. Format: `scan-<scanId>-room-<roomLocalId>-(door|opening)-<idx>`. The trailing segment selects kind-specifically — `door` indexes the target room's `doors[]`, `opening` indexes `openings[]`; the two are never folded. `<scanId>` and `<roomLocalId>` must reference a scan + room on the parent composite the iOS client is appending to. */
+            entryDoorwayId?: string;
+            entryDoorwayWallIndex?: number;
+            entryDoorwayPosition?: {
+                x: number;
+                y: number;
+            };
         };
         MobileUploadResponse: {
             scanId: number;
@@ -1762,6 +2358,75 @@ export interface components {
             squareUpAngleRad: number;
             mirrorX: boolean;
         };
+        ChattyToolDefinition: {
+            /** @enum {string} */
+            type: "function";
+            function: {
+                name: string;
+                description: string;
+                parameters: {
+                    /** @enum {string} */
+                    type: "object";
+                    properties: {
+                        [key: string]: {
+                            [key: string]: unknown;
+                        } & {
+                            type: string | string[];
+                            description?: string;
+                            enum?: string[];
+                            required?: string[];
+                            additionalProperties?: boolean;
+                        };
+                    };
+                    required?: string[];
+                    additionalProperties?: boolean;
+                };
+            };
+        };
+        ChattyExecuteRequest: {
+            function?: string;
+            name?: string;
+            arguments?: {
+                [key: string]: unknown;
+            };
+        };
+        ChattyExecuteResponse: {
+            success: boolean;
+            message?: string;
+            error?: string;
+            code?: string;
+            data?: unknown;
+            action?: unknown;
+        };
+        ChattyAiContextResponse: {
+            instructions: string;
+            knowledgeBaseLoaded: boolean;
+            workflowStagesLoaded: boolean;
+            timestamp: string;
+        };
+        RealtimeTokenRequest: {
+            directWebRTC?: boolean;
+        };
+        RealtimeTokenResponse: {
+            sessionId?: string;
+            model?: string;
+            voice?: string;
+            clientSecret?: string;
+            fallback: boolean;
+            directWebRTC?: boolean;
+            useWebRTC?: boolean;
+            expiresInSeconds?: number;
+            metadata?: {
+                organizationId: string | number;
+            };
+            message?: string;
+        };
+        CsrfTokenResponse: {
+            token: string;
+        };
+        RealtimeWebrtcRequest: {
+            sdp: string;
+        };
     };
     responses: never;
     parameters: never;