@serviceai/api-spec 1.2.434 → 1.6.1

package/types.d.ts

@@ -129,6 +129,238 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/impersonate/native-read-ticket": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Authorize an exact browser-native download URL for the current support session.
+         * @description Requires the current typed support session and X-Support-Impersonation: 1. A narrow fixed GET allowlist only; record permissions still run on every GET. Admission lasts at most 15 minutes and never outlives the original one-hour support grant. The same browser session is required; URL alone is insufficient. GET/Range retries recheck current authority. Response is no-store with no-referrer. No user bearer is issued.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header: {
+                    "X-Support-Impersonation": "1";
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": {
+                        url: string;
+                    };
+                };
+            };
+            responses: {
+                /** @description Exact relative URL and terminal admission deadline. */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            url: string;
+                            expiresAt: number;
+                        };
+                    };
+                };
+                /** @description Unsupported destination or malformed request. */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description No authenticated session. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description Support authority unavailable; explicit exit required. */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["StreamAuthenticationError"];
+                    };
+                };
+                /** @description Authentication lookup temporarily unavailable. */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["StreamAuthenticationError"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/events/ticket": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Create a short-lived stream-only admission ticket from the current authenticated actor.
+         * @description Connect within at most 60 seconds using GET /api/events?ticket=.... The ticket preserves the real principal, effective target and original login/impersonation deadlines; it cannot authenticate ordinary API requests. It is never a target-user bearer token. Response Cache-Control is no-store. An invalid temporary context returns 403 and must be explicitly exited, without dropping the real login.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": Record<string, never>;
+                };
+            };
+            responses: {
+                /** @description Opaque ticket, usable only for short-lived stream admission. */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["EventStreamTicketResponse"];
+                    };
+                };
+                /** @description Unexpected request fields. */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            message: string;
+                            errors: unknown[];
+                        };
+                    };
+                };
+                /** @description Real principal is missing, deleted, revoked or expired. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["StreamAuthenticationError"];
+                    };
+                };
+                /** @description Impersonation is unavailable; explicitly exit before continuing as the real principal. */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["StreamAuthenticationError"];
+                    };
+                };
+                /** @description Authentication lookup unavailable; retry without discarding credentials. */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["StreamAuthenticationError"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/events": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Open the authenticated server-sent event stream.
+         * @description New clients use a stream-only ticket in the ticket query parameter. Legacy authenticated connections remain supported. A supplied invalid ticket never falls back to another credential. Current user, session and revocation state is rechecked before admission and each delivery batch/heartbeat. Original authority deadlines also close idle or blocked sockets. A stream:resync hint means refresh authorized snapshots; this stream is not a replay log.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    ticket?: string;
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Bounded SSE hints and heartbeat comments until disconnect or authority expiry. */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "text/event-stream": string;
+                    };
+                };
+                /** @description Ticket/source authentication expired, revoked or invalid. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["StreamAuthenticationError"];
+                    };
+                };
+                /** @description Legacy temporary context is unavailable. */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["StreamAuthenticationError"];
+                    };
+                };
+                /** @description Authorization temporarily unavailable; retry with backoff. */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["StreamAuthenticationError"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/jobs/{jobId}/scans/mobile-upload": {
         parameters: {
             query?: never;
@@ -3832,6 +4064,179 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/projects/{projectId}/documents/draft-from-walkthrough": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Turn a voice walk-through (timed transcript + photos) into a checklist draft.
+         * @description Returns a DRAFT only; nothing is saved to the job. The phone's review screen creates the checklist with POST /api/projects/{projectId}/documents (custom `items`, carrying `referenceMedia`). Sections come from, in order: the camera pose of a scan, the room the tech named (the item's words, the photo's room chip, a section opened), the AI Image Sort's room for the item's photo (add-on), then the last room mentioned; items with no signal go to Not sure. GPS is never used. Item types come from spoken hints only (checkbox unless "photo required", "yes or no" or a reading; "required" sets the flag). Reference photos are the shots taken from 10 s before a sentence to 20 s after it. 200 when the draft is ready at once; 202 with `runId` while the photos go through an AI vision sort (poll the runs route). Requires the job (404 otherwise) and the Create Checklists permission (403). Photos that are not the organization's assets are left out.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    projectId: number;
+                };
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": components["schemas"]["WalkthroughDraftRequest"];
+                };
+            };
+            responses: {
+                /** @description The draft (status completed). */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["WalkthroughDraftResponse"];
+                    };
+                };
+                /** @description A vision sort runs first (status running); poll GET …/draft-from-walkthrough/runs/{runId}. */
+                202: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["WalkthroughDraftResponse"];
+                    };
+                };
+                /** @description No transcript, or a wrong shape. */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Authentication required. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description The role cannot create checklists. */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Job not found. */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description The AI's answer could not be used. */
+                502: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description AI is not configured. */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/projects/{projectId}/documents/draft-from-walkthrough/runs/{runId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Poll a walk-through draft that waits for an AI vision sort.
+         * @description Status `running` (with the sort's progress in `sortRun`) until the draft is ready, then `completed` with `draft`, or `failed` with `message`. A run that stops making progress is marked failed on the next poll and never re-run.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    projectId: number;
+                    runId: number;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description The run's envelope. */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["WalkthroughDraftResponse"];
+                    };
+                };
+                /** @description Authentication required. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description The role cannot create checklists. */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Job or run not found. */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -3856,7 +4261,7 @@ export interface components {
         };
         /** @description Cross-platform version handshake manifest. See docs/api-versioning.md. */
         VersionManifest: {
-            /** @example 1.2.434 */
+            /** @example 1.6.1 */
             apiVersion: string;
             /** @example 1.0.0 */
             minClientVersion: string;
@@ -4376,6 +4781,14 @@ export interface components {
             scanRoomSnapshots: boolean;
             roomConnections: boolean;
         };
+        EventStreamTicketResponse: {
+            ticket: string;
+        };
+        StreamAuthenticationError: {
+            message: string;
+            /** @enum {string} */
+            code?: "IMPERSONATION_UNAVAILABLE" | "SUPPORT_IMPERSONATION_UNAVAILABLE" | "auth_unavailable";
+        };
         JobSummary: {
             id: number;
             name: string;
@@ -5029,6 +5442,288 @@ export interface components {
             token: string;
             roomIds: number[];
         };
+        WalkthroughDraftRequest: {
+            transcript: {
+                text: string;
+                /** Format: date-time */
+                startedAt: string;
+                /** Format: date-time */
+                endedAt: string;
+            }[];
+            photos?: {
+                assetId: string;
+                /** Format: date-time */
+                capturedAt: string;
+                roomHint?: string | null;
+                sketchRoomId?: number | null;
+                capturePose?: {
+                    x?: number;
+                    y?: number;
+                    z?: number;
+                    floorId?: number | null;
+                    sketchId?: number | null;
+                    scanSessionId?: string;
+                    scanRoomLocalId?: string;
+                    scanRoomName?: string;
+                } | null;
+            }[];
+            sections?: {
+                name: string;
+                /** Format: date-time */
+                startedAt: string;
+                sketchRoomId?: number | null;
+            }[];
+            /** @enum {string} */
+            roomsFrom?: "speech" | "scan";
+        };
+        ChecklistDraft: {
+            name: string;
+            sections: {
+                key: string;
+                title: string;
+                sketchRoomId: number | null;
+                /** @enum {string} */
+                kind: "room" | "custom" | "not_sure";
+                items: {
+                    key: string;
+                    itemText: string;
+                    description: string | null;
+                    /** @enum {string} */
+                    itemType: "checkbox" | "yes/no" | "text" | "number" | "date" | "dropdown" | "multi-select" | "photo" | "signature";
+                    required: boolean;
+                    options: {
+                        [key: string]: unknown;
+                    } | null;
+                    referenceMedia: {
+                        assetId: string;
+                        caption?: string | null;
+                        order?: number;
+                    }[];
+                    hints: ("photo_required" | "yes_no" | "required" | "reading")[];
+                    /** @enum {string} */
+                    roomSource: "pose" | "named" | "vision" | "time" | "none";
+                    spokenAt: string;
+                    quote: string | null;
+                }[];
+            }[];
+            photos: {
+                assetId: string;
+                capturedAt: string;
+                sectionKey: string | null;
+                /** @enum {string} */
+                roomSource: "pose" | "named" | "vision" | "time" | "none";
+                itemKeys: string[];
+            }[];
+            visionUsed: boolean;
+            model: string | null;
+            promptVersion: string;
+        };
+        WalkthroughDraftResponse: {
+            /** @enum {string} */
+            status: "completed" | "running" | "failed";
+            runId: number | null;
+            draft: {
+                name: string;
+                sections: {
+                    key: string;
+                    title: string;
+                    sketchRoomId: number | null;
+                    /** @enum {string} */
+                    kind: "room" | "custom" | "not_sure";
+                    items: {
+                        key: string;
+                        itemText: string;
+                        description: string | null;
+                        /** @enum {string} */
+                        itemType: "checkbox" | "yes/no" | "text" | "number" | "date" | "dropdown" | "multi-select" | "photo" | "signature";
+                        required: boolean;
+                        options: {
+                            [key: string]: unknown;
+                        } | null;
+                        referenceMedia: {
+                            assetId: string;
+                            caption?: string | null;
+                            order?: number;
+                        }[];
+                        hints: ("photo_required" | "yes_no" | "required" | "reading")[];
+                        /** @enum {string} */
+                        roomSource: "pose" | "named" | "vision" | "time" | "none";
+                        spokenAt: string;
+                        quote: string | null;
+                    }[];
+                }[];
+                photos: {
+                    assetId: string;
+                    capturedAt: string;
+                    sectionKey: string | null;
+                    /** @enum {string} */
+                    roomSource: "pose" | "named" | "vision" | "time" | "none";
+                    itemKeys: string[];
+                }[];
+                visionUsed: boolean;
+                model: string | null;
+                promptVersion: string;
+            } | null;
+            sortRun: {
+                /** @enum {string} */
+                status: "running" | "completed" | "failed";
+                total: number;
+                done: number;
+            } | null;
+            message: string | null;
+        };
+        /** @description `arguments` of the Chatty tool `list_job_checklists` (POST /api/chatty-voice/tools/execute). */
+        ChattyListJobChecklistsArguments: {
+            jobId?: number | string;
+        };
+        /** @description `data` of a successful `list_job_checklists` call (`success: true`). */
+        ChattyListJobChecklistsData: {
+            id: number;
+            name: string;
+            status: string | null;
+            completionPercentage: number;
+            templateId: number | null;
+        }[];
+        /** @description `arguments` of the Chatty tool `get_checklist` (POST /api/chatty-voice/tools/execute). */
+        ChattyGetChecklistArguments: {
+            checklistId?: number | string;
+            checklistName?: string;
+            jobId?: number | string;
+        };
+        /** @description `data` of a successful `get_checklist` call (`success: true`). */
+        ChattyGetChecklistData: {
+            id: number;
+            name: string;
+            status: string | null;
+            completionPercentage: number;
+            jobId: number | null;
+            items: {
+                id: number;
+                itemText: string;
+                itemType: string;
+                required: boolean;
+                done: boolean;
+                value: string | null;
+                section: string | null;
+                referencePhotos: number;
+            }[];
+        };
+        /** @description `arguments` of the Chatty tool `create_checklist` (POST /api/chatty-voice/tools/execute). */
+        ChattyCreateChecklistArguments: {
+            jobId?: number | string;
+            name?: string;
+            templateId?: number | string;
+            templateName?: string;
+            notes?: string;
+            items?: string[];
+        };
+        /** @description `data` of a successful `create_checklist` call (`success: true`). */
+        ChattyCreateChecklistData: {
+            id: number;
+            name: string;
+            jobId: number;
+            itemCount: number;
+            templateId?: number;
+            sections?: {
+                title: string;
+                items: {
+                    itemText: string;
+                    /** @enum {string} */
+                    itemType: "checkbox" | "yes/no" | "text" | "number" | "date" | "dropdown" | "multi-select" | "photo" | "signature";
+                    required: boolean;
+                }[];
+            }[];
+        };
+        /** @description `arguments` of the Chatty tool `add_checklist_item` (POST /api/chatty-voice/tools/execute). */
+        ChattyAddChecklistItemArguments: {
+            checklistId?: number | string;
+            checklistName?: string;
+            jobId?: number | string;
+            itemText: string;
+            /** @enum {string} */
+            itemType?: "checkbox" | "yes/no" | "text" | "number" | "date" | "dropdown" | "multi-select" | "photo" | "signature";
+            required?: boolean;
+            description?: string;
+            sectionName?: string;
+        };
+        /** @description `data` of a successful `add_checklist_item` call (`success: true`). */
+        ChattyAddChecklistItemData: {
+            id: number;
+            checklistId: number;
+            itemText: string;
+            /** @enum {string} */
+            itemType: "checkbox" | "yes/no" | "text" | "number" | "date" | "dropdown" | "multi-select" | "photo" | "signature";
+            required: boolean;
+            section: string | null;
+        };
+        /** @description `arguments` of the Chatty tool `complete_checklist_item` (POST /api/chatty-voice/tools/execute). */
+        ChattyCompleteChecklistItemArguments: {
+            checklistId?: number | string;
+            checklistName?: string;
+            jobId?: number | string;
+            itemId?: number | string;
+            itemText?: string;
+            completed?: boolean;
+        };
+        /** @description `data` of a successful `complete_checklist_item` call (`success: true`). */
+        ChattyCompleteChecklistItemData: {
+            checklistId: number;
+            itemId: number;
+            completed: boolean;
+        };
+        /** @description `arguments` of the Chatty tool `set_checklist_item_answer` (POST /api/chatty-voice/tools/execute). */
+        ChattySetChecklistItemAnswerArguments: {
+            checklistId?: number | string;
+            checklistName?: string;
+            jobId?: number | string;
+            itemId?: number | string;
+            itemText?: string;
+            value: string;
+        };
+        /** @description `data` of a successful `set_checklist_item_answer` call (`success: true`). */
+        ChattySetChecklistItemAnswerData: {
+            checklistId: number;
+            itemId: number;
+            value: string;
+        };
+        /** @description `arguments` of the Chatty tool `attach_reference_photo_to_item` (POST /api/chatty-voice/tools/execute). */
+        ChattyAttachReferencePhotoToItemArguments: {
+            checklistId?: number | string;
+            checklistName?: string;
+            jobId?: number | string;
+            itemId?: number | string;
+            itemText?: string;
+            photoId: number | string;
+            caption?: string;
+        };
+        /** @description `data` of a successful `attach_reference_photo_to_item` call (`success: true`). */
+        ChattyAttachReferencePhotoToItemData: {
+            checklistId: number;
+            itemId: number;
+            referenceMedia: {
+                assetId: string;
+                caption?: string | null;
+                order?: number;
+            }[];
+        };
+        /** @description `arguments` of the Chatty tool `draft_checklist_from_job_photos` (POST /api/chatty-voice/tools/execute). */
+        ChattyDraftChecklistFromJobPhotosArguments: {
+            jobId?: number | string;
+            name?: string;
+            create?: boolean;
+        };
+        /** @description `data` of a successful `draft_checklist_from_job_photos` call (`success: true`). */
+        ChattyDraftChecklistFromJobPhotosData: {
+            id?: number;
+            jobId?: number;
+            name: string;
+            items: {
+                itemText: string;
+                photos: number;
+            }[];
+            unsortedPhotos: number;
+            created: boolean;
+        };
     };
     responses: never;
     parameters: never;