@serviceai/api-spec 1.6.1 → 1.6.3

package/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: ServiceAi API
-  version: 1.6.1
+  version: 1.6.3
   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
@@ -103,7 +103,7 @@ components:
       properties:
         apiVersion:
           type: string
-          example: 1.6.1
+          example: 1.6.3
         minClientVersion:
           type: string
           example: 1.0.0
@@ -3496,6 +3496,60 @@ components:
             - action
             - token
           additionalProperties: false
+        - type: object
+          properties:
+            action:
+              type: string
+              enum:
+                - separate
+            rooms:
+              type: array
+              items:
+                type: object
+                properties:
+                  id:
+                    type: integer
+                    exclusiveMinimum: 0
+                  revision:
+                    type: string
+                    pattern: ^[a-f0-9]{64}$
+                required:
+                  - id
+                  - revision
+                additionalProperties: false
+          required:
+            - action
+            - rooms
+          additionalProperties: false
+        - type: object
+          properties:
+            action:
+              type: string
+              enum:
+                - disconnect
+            connectionId:
+              type: integer
+              exclusiveMinimum: 0
+            rooms:
+              type: array
+              items:
+                type: object
+                properties:
+                  id:
+                    type: integer
+                    exclusiveMinimum: 0
+                  revision:
+                    type: string
+                    pattern: ^[a-f0-9]{64}$
+                required:
+                  - id
+                  - revision
+                additionalProperties: false
+          required:
+            - action
+            - connectionId
+            - rooms
+          additionalProperties: false
         - type: object
           properties:
             action:
@@ -4514,6 +4568,226 @@ components:
         - unsortedPhotos
         - created
       description: '`data` of a successful `draft_checklist_from_job_photos` call (`success: true`).'
+    AssetInitUploadRequest:
+      type: object
+      properties:
+        filename:
+          anyOf:
+            - type: string
+              maxLength: 10000
+            - type: number
+            - type: 'null'
+        byteSize:
+          anyOf:
+            - type: number
+            - type: string
+              maxLength: 10000
+            - type: 'null'
+        clientQueueId:
+          anyOf:
+            - type: string
+              maxLength: 10000
+            - type: number
+            - type: 'null'
+        pendingMetadata:
+          type:
+            - object
+            - 'null'
+          additionalProperties: {}
+        mimeType:
+          anyOf:
+            - type: string
+              maxLength: 10000
+            - type: number
+            - type: 'null'
+        contentType:
+          anyOf:
+            - type: string
+              maxLength: 10000
+            - type: number
+            - type: 'null'
+        poster:
+          type:
+            - object
+            - 'null'
+          properties:
+            contentType:
+              type: string
+              enum:
+                - image/jpeg
+            byteSize:
+              type: integer
+              exclusiveMinimum: 0
+              maximum: 2097152
+          required:
+            - contentType
+            - byteSize
+      description: >-
+        POST /api/assets/init-upload body. `filename` and `mimeType` (alias `contentType`) are required by the handler.
+        `poster` is accepted only when the upload's content type is `video/*`: a JPEG frame of at most 2 MiB the client
+        renders locally and PUTs to `posterUploadUrl`; on any other content type the response is 400
+        `poster_requires_video`.
+    AssetInitUploadResponse:
+      type: object
+      properties:
+        assetId:
+          type: string
+        key:
+          type: string
+          description: Storage key of the original (`org/<orgId>/assets/<assetId>/original`).
+        putUrl:
+          type: string
+          description: Presigned PUT for the original. Absent when `alreadyCompleted` is true.
+        headersToSend:
+          type: object
+          additionalProperties:
+            type: string
+        putUrlExpiresAt:
+          type: string
+          description: ISO instant; also the expiry of `posterUploadUrl`.
+        reused:
+          type: boolean
+        alreadyCompleted:
+          type: boolean
+        posterUploadUrl:
+          type: string
+          description: 'Presigned PUT (Content-Type: image/jpeg) for the poster frame. Present only when `poster` was sent.'
+        posterKey:
+          type: string
+          description: 'The poster''s storage key: the asset prefix with `/original` replaced by `/thumb_320`.'
+      required:
+        - assetId
+        - key
+    AssetCompleteUploadRequest:
+      type: object
+      properties:
+        assetId:
+          anyOf:
+            - type: string
+              maxLength: 10000
+            - type: number
+            - type: 'null'
+        clientQueueId:
+          anyOf:
+            - type: string
+              maxLength: 10000
+            - type: number
+            - type: 'null'
+        gpsLatitude:
+          anyOf:
+            - type: number
+            - type: string
+              maxLength: 10000
+            - type: 'null'
+        gpsLongitude:
+          anyOf:
+            - type: number
+            - type: string
+              maxLength: 10000
+            - type: 'null'
+        gpsAddress:
+          anyOf:
+            - type: string
+              maxLength: 10000
+            - type: number
+            - type: 'null'
+        captureTimestamp:
+          anyOf:
+            - type: string
+            - type: number
+            - type: string
+              format: date-time
+            - type: 'null'
+        deviceInfo:
+          anyOf:
+            - type: string
+              maxLength: 10000
+            - type: number
+            - type: 'null'
+        overlayApplied:
+          anyOf:
+            - type: boolean
+            - type: string
+            - type: number
+            - type: 'null'
+        hasMarkup:
+          anyOf:
+            - type: boolean
+            - type: string
+            - type: number
+            - type: 'null'
+        tags:
+          type:
+            - array
+            - 'null'
+          items: {}
+        projectId:
+          anyOf:
+            - type: number
+            - type: string
+              maxLength: 10000
+            - type: 'null'
+        contactId:
+          anyOf:
+            - type: number
+            - type: string
+              maxLength: 10000
+            - type: 'null'
+        folderId:
+          anyOf:
+            - type: string
+              maxLength: 10000
+            - type: number
+            - type: 'null'
+        description:
+          anyOf:
+            - type: string
+              maxLength: 200000
+            - type: number
+            - type: 'null'
+        serverOverlay:
+          type:
+            - object
+            - 'null'
+          additionalProperties: {}
+        capturePose:
+          type:
+            - object
+            - 'null'
+          additionalProperties: {}
+        posterUploaded:
+          anyOf:
+            - type: boolean
+            - type: string
+            - type: number
+            - type: 'null'
+      description: >-
+        POST /api/assets/complete-upload body. `assetId` or `clientQueueId` is required. `posterUploaded: true` (video
+        uploads only) asks the server to verify the poster frame PUT to `posterUploadUrl` and use it as the thumbnail at
+        once; a missing, oversized or non-JPEG poster never fails the upload — it completes without it.
+    AssetCompleteUploadResponse:
+      type: object
+      properties:
+        ok:
+          type: boolean
+          enum:
+            - true
+        assetId:
+          type: string
+        alreadyCompleted:
+          type: boolean
+        actions:
+          type: array
+          items:
+            type: string
+          description: >-
+            Human-readable log of what finalize did (status change, links, pipeline dispatch, `thumbnail: client poster
+            accepted (thumb_320)`).
+      required:
+        - ok
+        - assetId
+        - alreadyCompleted
+        - actions
   parameters: {}
 paths:
   /api/version:
@@ -8700,4 +8974,66 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorEnvelope'
+  /api/assets/init-upload:
+    post:
+      summary: 'Open a direct-to-S3 upload: presigned PUT for the original, and for a video''s optional poster frame.'
+      tags:
+        - photos
+      parameters:
+        - *ref_0
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssetInitUploadRequest'
+      responses:
+        '200':
+          description: Presigned URL(s) and the asset id to pass to complete-upload.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AssetInitUploadResponse'
+        '400':
+          description: Missing filename/mimeType, or a `poster` on a non-video upload (`poster_requires_video`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '401':
+          description: Authentication required.
+        '413':
+          description: File larger than the single-PUT limit.
+  /api/assets/complete-upload:
+    post:
+      summary: Mark a direct upload complete (idempotent); link it to a job/contact; dispatch processing.
+      tags:
+        - photos
+      parameters:
+        - *ref_0
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssetCompleteUploadRequest'
+      responses:
+        '200':
+          description: Finalized (or already was).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AssetCompleteUploadResponse'
+        '400':
+          description: Neither assetId nor clientQueueId.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorEnvelope'
+        '401':
+          description: Authentication required.
+        '403':
+          description: Attaching to a job/contact without the Upload Files permission.
+        '404':
+          description: Asset, job or contact not found in the organization.
 webhooks: {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serviceai/api-spec",
-  "version": "1.6.1",
+  "version": "1.6.3",
   "description": "ServiceAi OpenAPI 3.1 contract + generated TS types. Auto-published from the desktop repo.",
   "main": "index.js",
   "types": "index.d.ts",

package/types.d.ts

@@ -4237,6 +4237,145 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/assets/init-upload": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Open a direct-to-S3 upload: presigned PUT for the original, and for a video's optional poster frame. */
+        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": components["schemas"]["AssetInitUploadRequest"];
+                };
+            };
+            responses: {
+                /** @description Presigned URL(s) and the asset id to pass to complete-upload. */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["AssetInitUploadResponse"];
+                    };
+                };
+                /** @description Missing filename/mimeType, or a `poster` on a non-video upload (`poster_requires_video`). */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Authentication required. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description File larger than the single-PUT limit. */
+                413: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/assets/complete-upload": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Mark a direct upload complete (idempotent); link it to a job/contact; dispatch processing. */
+        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": components["schemas"]["AssetCompleteUploadRequest"];
+                };
+            };
+            responses: {
+                /** @description Finalized (or already was). */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["AssetCompleteUploadResponse"];
+                    };
+                };
+                /** @description Neither assetId nor clientQueueId. */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorEnvelope"];
+                    };
+                };
+                /** @description Authentication required. */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description Attaching to a job/contact without the Upload Files permission. */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+                /** @description Asset, job or contact not found in the organization. */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content?: never;
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
 }
 export type webhooks = Record<string, never>;
 export interface components {
@@ -4261,7 +4400,7 @@ export interface components {
         };
         /** @description Cross-platform version handshake manifest. See docs/api-versioning.md. */
         VersionManifest: {
-            /** @example 1.6.1 */
+            /** @example 1.6.3 */
             apiVersion: string;
             /** @example 1.0.0 */
             minClientVersion: string;
@@ -5419,6 +5558,21 @@ export interface components {
             /** @enum {string} */
             action: "undo";
             token: string;
+        } | {
+            /** @enum {string} */
+            action: "separate";
+            rooms: {
+                id: number;
+                revision: string;
+            }[];
+        } | {
+            /** @enum {string} */
+            action: "disconnect";
+            connectionId: number;
+            rooms: {
+                id: number;
+                revision: string;
+            }[];
         } | {
             /** @enum {string} */
             action: "connect";
@@ -5724,6 +5878,72 @@ export interface components {
             unsortedPhotos: number;
             created: boolean;
         };
+        /** @description POST /api/assets/init-upload body. `filename` and `mimeType` (alias `contentType`) are required by the handler. `poster` is accepted only when the upload's content type is `video/*`: a JPEG frame of at most 2 MiB the client renders locally and PUTs to `posterUploadUrl`; on any other content type the response is 400 `poster_requires_video`. */
+        AssetInitUploadRequest: {
+            filename?: string | number | null;
+            byteSize?: number | string | null;
+            clientQueueId?: string | number | null;
+            pendingMetadata?: {
+                [key: string]: unknown;
+            } | null;
+            mimeType?: string | number | null;
+            contentType?: string | number | null;
+            poster?: {
+                /** @enum {string} */
+                contentType: "image/jpeg";
+                byteSize: number;
+            } | null;
+        };
+        AssetInitUploadResponse: {
+            assetId: string;
+            /** @description Storage key of the original (`org/<orgId>/assets/<assetId>/original`). */
+            key: string;
+            /** @description Presigned PUT for the original. Absent when `alreadyCompleted` is true. */
+            putUrl?: string;
+            headersToSend?: {
+                [key: string]: string;
+            };
+            /** @description ISO instant; also the expiry of `posterUploadUrl`. */
+            putUrlExpiresAt?: string;
+            reused?: boolean;
+            alreadyCompleted?: boolean;
+            /** @description Presigned PUT (Content-Type: image/jpeg) for the poster frame. Present only when `poster` was sent. */
+            posterUploadUrl?: string;
+            /** @description The poster's storage key: the asset prefix with `/original` replaced by `/thumb_320`. */
+            posterKey?: string;
+        };
+        /** @description POST /api/assets/complete-upload body. `assetId` or `clientQueueId` is required. `posterUploaded: true` (video uploads only) asks the server to verify the poster frame PUT to `posterUploadUrl` and use it as the thumbnail at once; a missing, oversized or non-JPEG poster never fails the upload — it completes without it. */
+        AssetCompleteUploadRequest: {
+            assetId?: string | number | null;
+            clientQueueId?: string | number | null;
+            gpsLatitude?: number | string | null;
+            gpsLongitude?: number | string | null;
+            gpsAddress?: string | number | null;
+            captureTimestamp?: string | number | null;
+            deviceInfo?: string | number | null;
+            overlayApplied?: boolean | string | number | null;
+            hasMarkup?: boolean | string | number | null;
+            tags?: unknown[] | null;
+            projectId?: number | string | null;
+            contactId?: number | string | null;
+            folderId?: string | number | null;
+            description?: string | number | null;
+            serverOverlay?: {
+                [key: string]: unknown;
+            } | null;
+            capturePose?: {
+                [key: string]: unknown;
+            } | null;
+            posterUploaded?: boolean | string | number | null;
+        };
+        AssetCompleteUploadResponse: {
+            /** @enum {boolean} */
+            ok: true;
+            assetId: string;
+            alreadyCompleted: boolean;
+            /** @description Human-readable log of what finalize did (status change, links, pipeline dispatch, `thumbnail: client poster accepted (thumb_320)`). */
+            actions: string[];
+        };
     };
     responses: never;
     parameters: never;