@serviceai/api-spec 1.1.23 → 1.2.1

package/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: ServiceAi API
-  version: 1.1.23
+  version: 1.2.1
   description: >-
     Source-of-truth API contract for ServiceAi. Generated from `shared/schema.ts` Zod schemas by
     `scripts/build-api-spec.ts`. Versioning policy: see `docs/api-versioning.md`. The hand-written docs/ios-contract.md
@@ -78,7 +78,7 @@ components:
       properties:
         apiVersion:
           type: string
-          example: 1.1.23
+          example: 1.2.1
         minClientVersion:
           type: string
           example: 1.0.0
@@ -1234,9 +1234,49 @@ components:
                     type: string
                   category:
                     type: string
+                  roomLocalId:
+                    type: string
+                    maxLength: 128
                   walls:
                     type: array
-                    items: {}
+                    items:
+                      type: object
+                      properties:
+                        start:
+                          type: object
+                          properties:
+                            x:
+                              type: number
+                            'y':
+                              type: number
+                          required:
+                            - x
+                            - 'y'
+                        end:
+                          type: object
+                          properties:
+                            x:
+                              type: number
+                            'y':
+                              type: number
+                          required:
+                            - x
+                            - 'y'
+                        length:
+                          type: number
+                        height:
+                          type: number
+                        captureMetadata:
+                          type: object
+                          properties:
+                            identifier:
+                              type: string
+                            isDoor:
+                              type: boolean
+                            isOpening:
+                              type: boolean
+                        captureMethod:
+                          type: string
                   doors:
                     type: array
                     items:
@@ -1249,12 +1289,9 @@ components:
                               type: number
                             'y':
                               type: number
-                            z:
-                              type: number
                           required:
                             - x
                             - 'y'
-                            - z
                         width:
                           type: number
                           exclusiveMinimum: 0
@@ -1296,12 +1333,9 @@ components:
                               type: number
                             'y':
                               type: number
-                            z:
-                              type: number
                           required:
                             - x
                             - 'y'
-                            - z
                         width:
                           type: number
                           exclusiveMinimum: 0
@@ -1338,12 +1372,9 @@ components:
                               type: number
                             'y':
                               type: number
-                            z:
-                              type: number
                           required:
                             - x
                             - 'y'
-                            - z
                         width:
                           type: number
                           exclusiveMinimum: 0
@@ -1368,6 +1399,83 @@ components:
                         - position
                         - width
                         - height
+                  pins:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        id:
+                          type: string
+                          minLength: 1
+                          maxLength: 128
+                        position:
+                          type: object
+                          properties:
+                            x:
+                              type: number
+                            'y':
+                              type: number
+                          required:
+                            - x
+                            - 'y'
+                        label:
+                          type: string
+                          maxLength: 256
+                        roomLocalId:
+                          type: string
+                          maxLength: 128
+                        kind:
+                          type: string
+                          maxLength: 64
+                        note:
+                          type: string
+                          maxLength: 1024
+                      required:
+                        - id
+                        - position
+                  objects:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        category:
+                          type: string
+                        position:
+                          type: object
+                          properties:
+                            x:
+                              type: number
+                            'y':
+                              type: number
+                          required:
+                            - x
+                            - 'y'
+                        dimensions:
+                          type: object
+                          properties:
+                            width:
+                              type: number
+                            height:
+                              type: number
+                            depth:
+                              type: number
+                  boundaryPolygon:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        x:
+                          type: number
+                        'y':
+                          type: number
+                      required:
+                        - x
+                        - 'y'
+                  roomNote:
+                    type: string
+                    maxLength: 4096
+                  entryDoorwayId:
+                    type: string
                 description: >-
                   Mobile-upload scan room. `doors`, `windows`, and `openings` are three distinct non-overlapping arrays
                   — array membership IS the discriminator (there is no `kind` / `type` field on the item itself).
@@ -1377,6 +1485,11 @@ components:
                   an `entryDoorwayId` target.
           required:
             - rooms
+          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).
         name:
           type: string
           minLength: 1
@@ -1391,8 +1504,27 @@ components:
         userOrientationHint:
           type: string
         wallConfidences:
-          type: array
-          items: {}
+          anyOf:
+            - type: array
+              items:
+                type:
+                  - array
+                  - 'null'
+                items:
+                  type: number
+            - type: array
+              items:
+                type: number
+            - type: object
+              additionalProperties:
+                type: array
+                items:
+                  type: number
+          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`.
         deviceTrack: {}
         referencePhotos:
           type: array
@@ -1473,12 +1605,42 @@ components:
           type: string
         clientMirrorApplied:
           type: boolean
+        parentScanId:
+          type: integer
+          exclusiveMinimum: 0
+        entryDoorwayId:
+          type: string
+          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.
+        entryDoorwayWallIndex:
+          type: integer
+          minimum: 0
+        entryDoorwayPosition:
+          type: object
+          properties:
+            x:
+              type: number
+            'y':
+              type: number
+          required:
+            - x
+            - 'y'
       required:
         - roomPlanJSON
         - name
       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.
+        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`.
     MobileUploadResponse:
       type: object
       properties:
@@ -1693,6 +1855,169 @@ components:
       description: >-
         Persisted floor-plan PNG render-frame. `mirrorX` is derived from `scans.client_mirror_applied` (negate when
         false). Null sentinel: ANY required column NULL → `null` is emitted instead of a partial frame.
+    ChattyToolDefinition:
+      type: object
+      properties:
+        type:
+          type: string
+          enum:
+            - function
+        function:
+          type: object
+          properties:
+            name:
+              type: string
+              minLength: 1
+            description:
+              type: string
+            parameters:
+              type: object
+              properties:
+                type:
+                  type: string
+                  enum:
+                    - object
+                properties:
+                  type: object
+                  additionalProperties:
+                    allOf:
+                      - type: object
+                        additionalProperties: {}
+                      - type: object
+                        properties:
+                          type:
+                            anyOf:
+                              - type: string
+                              - type: array
+                                items:
+                                  type: string
+                          description:
+                            type: string
+                          enum:
+                            type: array
+                            items:
+                              type: string
+                          required:
+                            type: array
+                            items:
+                              type: string
+                          additionalProperties:
+                            type: boolean
+                        required:
+                          - type
+                required:
+                  type: array
+                  items:
+                    type: string
+                additionalProperties:
+                  type: boolean
+              required:
+                - type
+                - properties
+          required:
+            - name
+            - description
+            - parameters
+      required:
+        - type
+        - function
+    ChattyExecuteRequest:
+      type: object
+      properties:
+        function:
+          type: string
+          minLength: 1
+        name:
+          type: string
+          minLength: 1
+        arguments:
+          type: object
+          additionalProperties: {}
+    ChattyExecuteResponse:
+      type: object
+      properties:
+        success:
+          type: boolean
+        message:
+          type: string
+        error:
+          type: string
+        code:
+          type: string
+        data: {}
+        action: {}
+      required:
+        - success
+    ChattyAiContextResponse:
+      type: object
+      properties:
+        instructions:
+          type: string
+        knowledgeBaseLoaded:
+          type: boolean
+        workflowStagesLoaded:
+          type: boolean
+        timestamp:
+          type: string
+      required:
+        - instructions
+        - knowledgeBaseLoaded
+        - workflowStagesLoaded
+        - timestamp
+    RealtimeTokenRequest:
+      type: object
+      properties:
+        directWebRTC:
+          type: boolean
+    RealtimeTokenResponse:
+      type: object
+      properties:
+        sessionId:
+          type: string
+        model:
+          type: string
+        voice:
+          type: string
+        clientSecret:
+          type: string
+        fallback:
+          type: boolean
+        directWebRTC:
+          type: boolean
+        useWebRTC:
+          type: boolean
+        expiresInSeconds:
+          type: integer
+          minimum: 0
+        metadata:
+          type: object
+          properties:
+            organizationId:
+              anyOf:
+                - type: string
+                - type: number
+          required:
+            - organizationId
+        message:
+          type: string
+      required:
+        - fallback
+    CsrfTokenResponse:
+      type: object
+      properties:
+        token:
+          type: string
+          minLength: 1
+      required:
+        - token
+    RealtimeWebrtcRequest:
+      type: object
+      properties:
+        sdp:
+          type: string
+          minLength: 1
+      required:
+        - sdp
   parameters: {}
 paths:
   /api/version:
@@ -2831,12 +3156,9 @@ paths:
                                     type: number
                                   'y':
                                     type: number
-                                  z:
-                                    type: number
                                 required:
                                   - x
                                   - 'y'
-                                  - z
                               width:
                                 type: number
                                 exclusiveMinimum: 0
@@ -2876,12 +3198,9 @@ paths:
                                     type: number
                                   'y':
                                     type: number
-                                  z:
-                                    type: number
                                 required:
                                   - x
                                   - 'y'
-                                  - z
                               width:
                                 type: number
                                 exclusiveMinimum: 0
@@ -2921,12 +3240,9 @@ paths:
                                     type: number
                                   'y':
                                     type: number
-                                  z:
-                                    type: number
                                 required:
                                   - x
                                   - 'y'
-                                  - z
                               width:
                                 type: number
                                 exclusiveMinimum: 0
@@ -3081,12 +3397,9 @@ paths:
                                         type: number
                                       'y':
                                         type: number
-                                      z:
-                                        type: number
                                     required:
                                       - x
                                       - 'y'
-                                      - z
                                   width:
                                     type: number
                                     exclusiveMinimum: 0
@@ -3126,12 +3439,9 @@ paths:
                                         type: number
                                       'y':
                                         type: number
-                                      z:
-                                        type: number
                                     required:
                                       - x
                                       - 'y'
-                                      - z
                                   width:
                                     type: number
                                     exclusiveMinimum: 0
@@ -3171,12 +3481,9 @@ paths:
                                         type: number
                                       'y':
                                         type: number
-                                      z:
-                                        type: number
                                     required:
                                       - x
                                       - 'y'
-                                      - z
                                   width:
                                     type: number
                                     exclusiveMinimum: 0
@@ -3243,4 +3550,469 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
+  /api/chatty-voice/tools:
+    get:
+      summary: 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.
+      tags:
+        - chatty
+      parameters:
+        - *ref_2
+      responses:
+        '200':
+          description: Bare array of tool definitions.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    type:
+                      type: string
+                      enum:
+                        - function
+                    function:
+                      type: object
+                      properties:
+                        name:
+                          type: string
+                          minLength: 1
+                        description:
+                          type: string
+                        parameters:
+                          type: object
+                          properties:
+                            type:
+                              type: string
+                              enum:
+                                - object
+                            properties:
+                              type: object
+                              additionalProperties:
+                                allOf:
+                                  - type: object
+                                    additionalProperties: {}
+                                  - type: object
+                                    properties:
+                                      type:
+                                        anyOf:
+                                          - type: string
+                                          - type: array
+                                            items:
+                                              type: string
+                                      description:
+                                        type: string
+                                      enum:
+                                        type: array
+                                        items:
+                                          type: string
+                                      required:
+                                        type: array
+                                        items:
+                                          type: string
+                                      additionalProperties:
+                                        type: boolean
+                                    required:
+                                      - type
+                            required:
+                              type: array
+                              items:
+                                type: string
+                            additionalProperties:
+                              type: boolean
+                          required:
+                            - type
+                            - properties
+                      required:
+                        - name
+                        - description
+                        - parameters
+                  required:
+                    - type
+                    - function
+        '401':
+          description: Unauthenticated.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '403':
+          description: Caller lacks the chatty-voice entitlement.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '426':
+          description: Client major below minClientVersion.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UpgradeRequiredEnvelope'
+  /api/chatty-voice/tools/execute:
+    post:
+      summary: 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.
+      tags:
+        - chatty
+      parameters:
+        - *ref_2
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                function:
+                  type: string
+                  minLength: 1
+                name:
+                  type: string
+                  minLength: 1
+                arguments:
+                  type: object
+                  additionalProperties: {}
+      responses:
+        '200':
+          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.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                  message:
+                    type: string
+                  error:
+                    type: string
+                  code:
+                    type: string
+                  data: {}
+                  action: {}
+                required:
+                  - success
+        '401':
+          description: Unauthenticated.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '403':
+          description: Caller lacks the chatty-voice entitlement or a per-tool permission.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '500':
+          description: 'Unhandled executor error. Body is `{ success: false, error }` (same envelope as 200).'
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  success:
+                    type: boolean
+                  message:
+                    type: string
+                  error:
+                    type: string
+                  code:
+                    type: string
+                  data: {}
+                  action: {}
+                required:
+                  - success
+  /api/chatty-voice/ai-context:
+    get:
+      summary: Fetch the Chatty Voice system prompt + load-status flags.
+      tags:
+        - chatty
+      parameters:
+        - *ref_2
+      responses:
+        '200':
+          description: System instructions + knowledge-base / workflow-stage load flags.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  instructions:
+                    type: string
+                  knowledgeBaseLoaded:
+                    type: boolean
+                  workflowStagesLoaded:
+                    type: boolean
+                  timestamp:
+                    type: string
+                required:
+                  - instructions
+                  - knowledgeBaseLoaded
+                  - workflowStagesLoaded
+                  - timestamp
+        '401':
+          description: Unauthenticated.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '403':
+          description: Caller lacks the chatty-voice entitlement.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+  /api/realtime-token:
+    post:
+      summary: 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.
+      tags:
+        - chatty
+      parameters:
+        - *ref_2
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                directWebRTC:
+                  type: boolean
+      responses:
+        '200':
+          description: Session minted (or fallback signalled). See union shape.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  sessionId:
+                    type: string
+                  model:
+                    type: string
+                  voice:
+                    type: string
+                  clientSecret:
+                    type: string
+                  fallback:
+                    type: boolean
+                  directWebRTC:
+                    type: boolean
+                  useWebRTC:
+                    type: boolean
+                  expiresInSeconds:
+                    type: integer
+                    minimum: 0
+                  metadata:
+                    type: object
+                    properties:
+                      organizationId:
+                        anyOf:
+                          - type: string
+                          - type: number
+                    required:
+                      - organizationId
+                  message:
+                    type: string
+                required:
+                  - fallback
+        '401':
+          description: Unauthenticated.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '403':
+          description: Caller lacks the chatty-voice entitlement.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '405':
+          description: Method Not Allowed (POST only).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '429':
+          description: Per-user rate limit on token mint.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '500':
+          description: 'Mint failure — body still carries `fallback: true`.'
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  sessionId:
+                    type: string
+                  model:
+                    type: string
+                  voice:
+                    type: string
+                  clientSecret:
+                    type: string
+                  fallback:
+                    type: boolean
+                  directWebRTC:
+                    type: boolean
+                  useWebRTC:
+                    type: boolean
+                  expiresInSeconds:
+                    type: integer
+                    minimum: 0
+                  metadata:
+                    type: object
+                    properties:
+                      organizationId:
+                        anyOf:
+                          - type: string
+                          - type: number
+                    required:
+                      - organizationId
+                  message:
+                    type: string
+                required:
+                  - fallback
+  /api/csrf-token:
+    get:
+      summary: 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.
+      tags:
+        - chatty
+      parameters:
+        - *ref_2
+      responses:
+        '200':
+          description: Fresh CSRF token.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  token:
+                    type: string
+                    minLength: 1
+                required:
+                  - token
+        '401':
+          description: Unauthenticated.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '403':
+          description: Caller lacks the chatty-voice entitlement.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+  /api/realtime/webrtc:
+    post:
+      summary: 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.
+      tags:
+        - chatty
+      parameters:
+        - *ref_2
+        - name: X-CSRF-Token
+          in: header
+          required: true
+          schema:
+            type: string
+          description: CSRF token previously minted by GET /api/csrf-token.
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                sdp:
+                  type: string
+                  minLength: 1
+              required:
+                - sdp
+      responses:
+        '200':
+          description: Raw OpenAI SDP answer (text body, not JSON).
+          content:
+            application/sdp:
+              schema:
+                type: string
+        '400':
+          description: Invalid SDP format.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '401':
+          description: Unauthenticated.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '403':
+          description: Caller lacks the chatty-voice entitlement, or CSRF token invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '429':
+          description: Rate limit (3 req/min/IP).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '500':
+          description: SDP exchange failed locally.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '502':
+          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? }`.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+                  status:
+                    type: integer
+                required:
+                  - error
+        default:
+          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.
+          content:
+            application/json:
+              schema: {}
+            text/plain:
+              schema:
+                type: string
 webhooks: {}