@thinkai/tai-api-contract 2.120.0 → 2.123.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.120.0
+  version: 2.123.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -3121,6 +3121,107 @@ paths:
         "404":
           description: Workspace does not exist or malformed workspaceId
 
+  /workspaces/{workspaceId}/ingest/sdlc/rollups/rebuild:
+    post:
+      tags: [SdlcInsights]
+      summary: Rebuild SDLC DORA/CI daily rollups for a day range
+      operationId: rebuildSdlcRollups
+      description: >
+        Queues a rebuild of DORA/CI daily rollups for this workspace from stored dashboard
+        productivity history for the inclusive `from`/`to` UTC day range (max 90 days).
+        Does not re-pull GitHub. Returns immediately with `{ ok: true }` while the rebuild
+        runs under an advisory lock; ingest-coverage reports `sdlc_github` as `in_progress`
+        until the lock is released. Returns 409 when another rebuild holds the advisory lock.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: from
+          in: query
+          required: true
+          description: Inclusive UTC start day (`YYYY-MM-DD`).
+          schema:
+            type: string
+            format: date
+        - name: to
+          in: query
+          required: true
+          description: Inclusive UTC end day (`YYYY-MM-DD`).
+          schema:
+            type: string
+            format: date
+      responses:
+        "200":
+          description: Rebuild accepted and running asynchronously
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok]
+                properties:
+                  ok:
+                    type: boolean
+                    enum: [true]
+                  rollupRows:
+                    type: integer
+                    minimum: 0
+                    description: >
+                      Optional. Omitted when the rebuild is queued asynchronously
+                      (current behavior).
+              example:
+                ok: true
+        "400":
+          description: >
+            Invalid range. Stable `error` codes: `invalid_day_range` (missing pair,
+            bad calendar date, or from > to) and `range_too_large` (more than 90 days).
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok, error]
+                properties:
+                  ok:
+                    type: boolean
+                    enum: [false]
+                  error:
+                    type: string
+                    enum: [invalid_day_range, range_too_large]
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: >
+            Feature off or no dashboard metrics source. Stable `error` codes:
+            `feature_off`, `no_source`.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok, error]
+                properties:
+                  ok:
+                    type: boolean
+                    enum: [false]
+                  error:
+                    type: string
+                    enum: [feature_off, no_source]
+        "409":
+          description: Rebuild already in progress
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok, error]
+                properties:
+                  ok:
+                    type: boolean
+                    enum: [false]
+                  error:
+                    type: string
+                    enum: [already_in_progress]
+              example:
+                ok: false
+                error: already_in_progress
+
   /workspaces/{workspaceId}/insights/sdlc/overview:
     get:
       tags: [SdlcInsights]
@@ -4446,8 +4547,11 @@ paths:
       summary: Refresh AI tool integration snapshots
       operationId: refreshWorkspaceAiTool
       description: >
-        Provider-agnostic refresh. Returns 409 when an advisory-lock refresh is already in progress.
-        On upstream auth/rate/network failures, returns `200` with `{ ok:false, error }` so the SPA can render inline error.
+        Provider-agnostic refresh. Queues work for `ai-tool-refresher` and returns immediately
+        with `{ ok: true }` when accepted. Progress is visible via ingest-coverage
+        (`ai.refreshInProgress`) and the provider status endpoint while the on-demand flag
+        (or advisory lock) is held. Returns 409 when an advisory-lock refresh is already in
+        progress. Returns 404 when the provider source is missing.
         Pass `full=true` to force a full re-sync that re-pulls the full history instead of the
         incremental window, used to backfill historical months. Provider-specific behavior:
         Claude Enterprise re-pulls six calendar months of daily usage; Claude Team widens its
@@ -4455,6 +4559,14 @@ paths:
         Cursor resets its spend/model/daily backfill cursors so the full `spendHistoryDays` window
         re-ingests from the retention floor even when the backfill was already complete.
         Omitted/false performs a normal incremental refresh.
+        Pass `from` and `to` (UTC `YYYY-MM-DD`) together to re-ingest only that
+        inclusive day range without resetting incremental watermarks; mutually
+        exclusive with `full`. Day-range behavior is provider-specific: all providers
+        re-pull generic daily usage for the window (Cursor does this via the spend-daily
+        path instead of a duplicate top-level poll); Cursor additionally re-ingests
+        spend/model daily for the window without resetting backfill cursors. Claude
+        Enterprise model/product/engagement ingest paths are not day-range scoped and
+        continue to use their normal refresh windows.
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
         - name: provider
@@ -4473,9 +4585,32 @@ paths:
           schema:
             type: string
             enum: ["true", "1"]
+        - name: from
+          in: query
+          required: false
+          description: >
+            Inclusive UTC start day (`YYYY-MM-DD`) for a targeted re-ingest window.
+            Must be paired with `to`. Mutually exclusive with `full`. Clamped to the
+            configured retention floor (`spendHistoryDays`). Cursor also re-ingests
+            spend/model daily for the window; Claude Enterprise model/product/engagement
+            paths are not day-range scoped.
+          schema:
+            type: string
+            format: date
+        - name: to
+          in: query
+          required: false
+          description: >
+            Inclusive UTC end day (`YYYY-MM-DD`) for a targeted re-ingest window.
+            Must be paired with `from`. Mutually exclusive with `full`.
+          schema:
+            type: string
+            format: date
       responses:
         "200":
-          description: Refresh result
+          description: >
+            Refresh accepted and queued for `ai-tool-refresher`. Upstream auth/rate/network
+            failures are reported later via refresh status / ingest-coverage, not on this response.
           content:
             application/json:
               schema:
@@ -4483,8 +4618,23 @@ paths:
               examples:
                 ok:
                   value: { ok: true }
-                invalid_token:
-                  value: { ok: false, error: "invalid_token" }
+        "400":
+          description: >
+            Invalid request. Stable `error` codes: `invalid_day_range` (missing pair,
+            bad calendar date, or from > to), `full_and_day_range_conflict` (`full`
+            combined with `from`/`to`), and `invalid_provider` (path provider is not
+            a supported AI-tool integration id).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiToolRefreshResponseDto"
+              examples:
+                invalid_day_range:
+                  value: { ok: false, error: "invalid_day_range" }
+                full_and_day_range_conflict:
+                  value: { ok: false, error: "full_and_day_range_conflict" }
+                invalid_provider:
+                  value: { ok: false, error: "invalid_provider" }
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -4499,7 +4649,9 @@ paths:
                 ok: false
                 error: "no_source"
         "409":
-          description: Refresh already in progress
+          description: >
+            Refresh already in progress — advisory lock held, or an on-demand refresh
+            is already queued for this workspace/provider.
           content:
             application/json:
               schema:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkai/tai-api-contract",
-  "version": "2.120.0",
+  "version": "2.123.0",
   "private": false,
   "type": "module",
   "main": "dist/index.js",

package/src/generated/openapi.ts

@@ -1110,6 +1110,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/workspaces/{workspaceId}/ingest/sdlc/rollups/rebuild": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Rebuild SDLC DORA/CI daily rollups for a day range
+         * @description Queues a rebuild of DORA/CI daily rollups for this workspace from stored dashboard productivity history for the inclusive `from`/`to` UTC day range (max 90 days). Does not re-pull GitHub. Returns immediately with `{ ok: true }` while the rebuild runs under an advisory lock; ingest-coverage reports `sdlc_github` as `in_progress` until the lock is released. Returns 409 when another rebuild holds the advisory lock.
+         */
+        post: operations["rebuildSdlcRollups"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/workspaces/{workspaceId}/insights/sdlc/overview": {
         parameters: {
             query?: never;
@@ -1630,7 +1650,7 @@ export interface paths {
         put?: never;
         /**
          * Refresh AI tool integration snapshots
-         * @description Provider-agnostic refresh. Returns 409 when an advisory-lock refresh is already in progress. On upstream auth/rate/network failures, returns `200` with `{ ok:false, error }` so the SPA can render inline error. Pass `full=true` to force a full re-sync that re-pulls the full history instead of the incremental window, used to backfill historical months. Provider-specific behavior: Claude Enterprise re-pulls six calendar months of daily usage; Claude Team widens its daily-usage window to the configured history depth (`spendHistoryDays`, default 180 days); Cursor resets its spend/model/daily backfill cursors so the full `spendHistoryDays` window re-ingests from the retention floor even when the backfill was already complete. Omitted/false performs a normal incremental refresh.
+         * @description Provider-agnostic refresh. Queues work for `ai-tool-refresher` and returns immediately with `{ ok: true }` when accepted. Progress is visible via ingest-coverage (`ai.refreshInProgress`) and the provider status endpoint while the on-demand flag (or advisory lock) is held. Returns 409 when an advisory-lock refresh is already in progress. Returns 404 when the provider source is missing. Pass `full=true` to force a full re-sync that re-pulls the full history instead of the incremental window, used to backfill historical months. Provider-specific behavior: Claude Enterprise re-pulls six calendar months of daily usage; Claude Team widens its daily-usage window to the configured history depth (`spendHistoryDays`, default 180 days); Cursor resets its spend/model/daily backfill cursors so the full `spendHistoryDays` window re-ingests from the retention floor even when the backfill was already complete. Omitted/false performs a normal incremental refresh. Pass `from` and `to` (UTC `YYYY-MM-DD`) together to re-ingest only that inclusive day range without resetting incremental watermarks; mutually exclusive with `full`. Day-range behavior is provider-specific: all providers re-pull generic daily usage for the window (Cursor does this via the spend-daily path instead of a duplicate top-level poll); Cursor additionally re-ingests spend/model daily for the window without resetting backfill cursors. Claude Enterprise model/product/engagement ingest paths are not day-range scoped and continue to use their normal refresh windows.
          */
         post: operations["refreshWorkspaceAiTool"];
         delete?: never;
@@ -13002,6 +13022,93 @@ export interface operations {
             };
         };
     };
+    rebuildSdlcRollups: {
+        parameters: {
+            query: {
+                /** @description Inclusive UTC start day (`YYYY-MM-DD`). */
+                from: string;
+                /** @description Inclusive UTC end day (`YYYY-MM-DD`). */
+                to: string;
+            };
+            header?: never;
+            path: {
+                workspaceId: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Rebuild accepted and running asynchronously */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "ok": true
+                     *     }
+                     */
+                    "application/json": {
+                        /** @enum {boolean} */
+                        ok: true;
+                        /** @description Optional. Omitted when the rebuild is queued asynchronously (current behavior). */
+                        rollupRows?: number;
+                    };
+                };
+            };
+            /** @description Invalid range. Stable `error` codes: `invalid_day_range` (missing pair, bad calendar date, or from > to) and `range_too_large` (more than 90 days). */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @enum {boolean} */
+                        ok: false;
+                        /** @enum {string} */
+                        error: "invalid_day_range" | "range_too_large";
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            /** @description Feature off or no dashboard metrics source. Stable `error` codes: `feature_off`, `no_source`. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @enum {boolean} */
+                        ok: false;
+                        /** @enum {string} */
+                        error: "feature_off" | "no_source";
+                    };
+                };
+            };
+            /** @description Rebuild already in progress */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "ok": false,
+                     *       "error": "already_in_progress"
+                     *     }
+                     */
+                    "application/json": {
+                        /** @enum {boolean} */
+                        ok: false;
+                        /** @enum {string} */
+                        error: "already_in_progress";
+                    };
+                };
+            };
+        };
+    };
     getSdlcInsightsOverview: {
         parameters: {
             query?: {
@@ -14420,6 +14527,10 @@ export interface operations {
             query?: {
                 /** @description Force a full history re-sync instead of the incremental window (Enterprise: 6 months; Team: `spendHistoryDays`-day daily-usage window; Cursor: spend/model/daily backfill reset over `spendHistoryDays`). Truthy only for `true` or `1`. */
                 full?: "true" | "1";
+                /** @description Inclusive UTC start day (`YYYY-MM-DD`) for a targeted re-ingest window. Must be paired with `to`. Mutually exclusive with `full`. Clamped to the configured retention floor (`spendHistoryDays`). Cursor also re-ingests spend/model daily for the window; Claude Enterprise model/product/engagement paths are not day-range scoped. */
+                from?: string;
+                /** @description Inclusive UTC end day (`YYYY-MM-DD`) for a targeted re-ingest window. Must be paired with `from`. Mutually exclusive with `full`. */
+                to?: string;
             };
             header?: never;
             path: {
@@ -14430,7 +14541,7 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @description Refresh result */
+            /** @description Refresh accepted and queued for `ai-tool-refresher`. Upstream auth/rate/network failures are reported later via refresh status / ingest-coverage, not on this response. */
             200: {
                 headers: {
                     [name: string]: unknown;
@@ -14439,6 +14550,15 @@ export interface operations {
                     "application/json": components["schemas"]["AiToolRefreshResponseDto"];
                 };
             };
+            /** @description Invalid request. Stable `error` codes: `invalid_day_range` (missing pair, bad calendar date, or from > to), `full_and_day_range_conflict` (`full` combined with `from`/`to`), and `invalid_provider` (path provider is not a supported AI-tool integration id). */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["AiToolRefreshResponseDto"];
+                };
+            };
             401: components["responses"]["Unauthorized"];
             403: components["responses"]["Forbidden"];
             /** @description Provider source missing for this workspace */
@@ -14456,7 +14576,7 @@ export interface operations {
                     "application/json": components["schemas"]["AiToolRefreshResponseDto"];
                 };
             };
-            /** @description Refresh already in progress */
+            /** @description Refresh already in progress — advisory lock held, or an on-demand refresh is already queued for this workspace/provider. */
             409: {
                 headers: {
                     [name: string]: unknown;