@shipeasy/openapi 2.4.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/openapi",
-  "version": "2.4.0",
+  "version": "3.0.0",
   "description": "Shipeasy admin OpenAPI 3.2 spec (hand-authored, single source of truth) + the generated TypeScript client, Zod schemas, and types. Consumed by @shipeasy/cli and @shipeasy/mcp.",
   "type": "module",
   "main": "./dist/index.js",

package/spec/components/schemas/configs.yaml

@@ -223,12 +223,26 @@ CreateConfigRequest:
       additionalProperties: {}
       description: JSON Schema (draft 2020-12) describing the shape of the config value. Top-level `type` must be `'object'`; every published value is validated against this schema.
     value:
+      type: object
+      additionalProperties: {}
       description: "Initial config value. Either a single JSON object applied to every env, or a `{ env: value }` map seeding per-env values. Must match `schema`. Defaults to `{}` on every env when omitted."
+    dev:
+      type: object
+      additionalProperties: {}
+      description: "Seed the **dev** env's initial value (version 1), overriding `value` for dev. Published immediately. Must match `schema`."
+    staging:
+      type: object
+      additionalProperties: {}
+      description: "Seed the **staging** env's initial value (version 1), overriding `value` for staging. Published immediately. Must match `schema`."
+    prod:
+      type: object
+      additionalProperties: {}
+      description: "Seed the **prod** env's initial value (version 1), overriding `value` for prod. Published immediately. Must match `schema`."
   required:
     - name
     - schema
   additionalProperties: false
-  description: Body for `POST /api/admin/configs`. `name` + `schema` required.
+  description: "Body for `POST /api/admin/configs`. `name` + `schema` required. Per-env `dev`/`staging`/`prod` values are published to that env at version 1 (overriding `value`)."
 CreateConfigResponse:
   type: object
   properties:
@@ -251,11 +265,25 @@ UpdateConfigRequest:
       type: object
       additionalProperties: {}
     value:
-      description: Flat value applied to **every** env. Publishes a new version per env. To target one env, use `PUT /{id}/drafts` then `POST /{id}/publish`.
+      type: object
+      additionalProperties: {}
+      description: Flat value applied to **every** env. Publishes a new version per env. To publish one env only, pass that env's key (`dev`/`staging`/`prod`) instead.
+    dev:
+      type: object
+      additionalProperties: {}
+      description: "Publish a new version to the **dev** env only, immediately (no draft). Overrides `value` for dev. Must match the effective schema."
+    staging:
+      type: object
+      additionalProperties: {}
+      description: "Publish a new version to the **staging** env only, immediately (no draft). Overrides `value` for staging. Must match the effective schema."
+    prod:
+      type: object
+      additionalProperties: {}
+      description: "Publish a new version to the **prod** env only, immediately (no draft). Overrides `value` for prod. Must match the effective schema."
     folder:
       $ref: ./common.yaml#/Folder
   additionalProperties: false
-  description: Body for `PATCH /api/admin/configs/{id}`. Partial — only supplied fields change. `value` republishes on every env.
+  description: "Body for `PATCH /api/admin/configs/{id}`. Partial — only supplied fields change. `value` republishes on every env; per-env `dev`/`staging`/`prod` publish a new version to just that env."
 UpdateConfigResponse:
   type: object
   properties:
@@ -300,6 +328,8 @@ SaveConfigDraftRequest:
     env:
       $ref: ./common.yaml#/Env
     value:
+      type: object
+      additionalProperties: {}
       description: Draft value to stage on `env`. Validated against the config's current schema.
   required:
     - env

package/spec/components/schemas/gates.yaml

@@ -205,6 +205,9 @@ GateApiRow:
                   locked:
                     description: If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).
                     type: boolean
+                  whitelist:
+                    description: Cosmetic marker. When `true`, the dashboard renders this condition as the pinned, always-first "whitelist" allowlist block (a direct `email`/`user_id` `in […]` list) rather than a numbered targeting step. Purely presentational — ignored by evaluation, which treats the entry as an ordinary condition.
+                    type: boolean
                 required:
                   - id
                   - type
@@ -517,6 +520,9 @@ CreateGateRequest:
                   locked:
                     description: If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).
                     type: boolean
+                  whitelist:
+                    description: Cosmetic marker. When `true`, the dashboard renders this condition as the pinned, always-first "whitelist" allowlist block (a direct `email`/`user_id` `in […]` list) rather than a numbered targeting step. Purely presentational — ignored by evaluation, which treats the entry as an ordinary condition.
+                    type: boolean
                 required:
                   - id
                   - type
@@ -802,6 +808,9 @@ UpdateGateRequest:
                   locked:
                     description: If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).
                     type: boolean
+                  whitelist:
+                    description: Cosmetic marker. When `true`, the dashboard renders this condition as the pinned, always-first "whitelist" allowlist block (a direct `email`/`user_id` `in […]` list) rather than a numbered targeting step. Purely presentational — ignored by evaluation, which treats the entry as an ordinary condition.
+                    type: boolean
                 required:
                   - id
                   - type

package/spec/components/schemas/i18n.yaml

@@ -94,14 +94,6 @@ ListI18nKeysResponse:
             anyOf:
               - type: string
               - type: "null"
-          chunkId:
-            description: Owning chunk (authoring grouping) id.
-            type: string
-          chunkName:
-            description: Name of the owning chunk (authoring grouping), or `null` when it cannot be resolved.
-            anyOf:
-              - type: string
-              - type: "null"
           updatedAt:
             description: ISO-8601 timestamp of the last edit.
             type: string
@@ -116,8 +108,6 @@ ListI18nKeysResponse:
           - variables
           - profileId
           - profileName
-          - chunkId
-          - chunkName
           - updatedAt
           - updatedBy
         additionalProperties: false
@@ -138,12 +128,6 @@ PushI18nKeysRequest:
       type: string
       format: uuid
       description: Target profile id to add keys to.
-    chunk:
-      description: Logical grouping the new keys are filed under. Defaults to `default`.
-      type: string
-      minLength: 1
-      maxLength: 64
-      default: default
     keys:
       type: array
       minItems: 1
@@ -174,12 +158,16 @@ PushI18nKeysRequest:
           - key
           - value
         additionalProperties: false
-      description: Keys to add. Insert-only — existing keys are reported back as `skipped`.
+      description: Keys to add. Insert-only by default — existing keys are reported back as `skipped` (set `force` to overwrite them instead).
+    force:
+      type: boolean
+      default: false
+      description: Overwrite keys that already exist with the submitted value instead of skipping them. Overwritten keys come back as `updated`. Off by default so a routine push can never clobber live translations.
   required:
     - profile_id
     - keys
   additionalProperties: false
-  description: "Body for `POST /api/admin/i18n/keys`. Insert-only: keys that already exist are never overwritten — use `PUT /keys/{id}` to change a value."
+  description: "Body for `POST /api/admin/i18n/keys`. Insert-only by default: keys that already exist are never overwritten — pass `force: true` to overwrite them in bulk, or use `PUT /keys/{id}` to change one value."
 PushI18nKeysResponse:
   type: object
   properties:
@@ -192,23 +180,30 @@ PushI18nKeysResponse:
       type: array
       items:
         type: string
-      description: Key names that already existed and were left untouched.
+      description: Key names that already existed and were left untouched. Always empty when `force` was set — those key names come back under `updated` instead.
+    updated:
+      type: array
+      items:
+        type: string
+      description: Key names that already existed and were overwritten with the submitted value. Only ever non-empty when the push set `force`.
     pushed_count:
       type: number
       description: Number of keys inserted (== `added.length`).
     skipped_count:
       type: number
       description: Number of keys skipped (== `skipped.length`).
-    chunk:
-      description: The chunk the keys were filed under.
-      type: string
+    updated_count:
+      type: number
+      description: Number of existing keys overwritten (== `updated.length`).
   required:
     - added
     - skipped
+    - updated
     - pushed_count
     - skipped_count
+    - updated_count
   additionalProperties: false
-  description: Result of an insert-only key push.
+  description: Result of a key push — what was inserted, what was left alone, and (with `force`) what was overwritten.
 UpdateI18nKeyRequest:
   type: object
   properties:
@@ -249,12 +244,6 @@ UpsertI18nKeysRequest:
       type: string
       format: uuid
       description: Target profile id to upsert keys into.
-    chunk:
-      description: Logical grouping the keys are filed under. Defaults to `default`.
-      type: string
-      minLength: 1
-      maxLength: 64
-      default: default
     keys:
       type: array
       minItems: 1
@@ -297,12 +286,8 @@ UpsertI18nKeysResponse:
     upserted:
       type: number
       description: Number of keys written (inserted or overwritten).
-    chunk:
-      type: string
-      description: The chunk the keys were filed under.
   required:
     - upserted
-    - chunk
   additionalProperties: false
   description: Result of a bulk key upsert. The affected profile's KV snapshot is rebuilt (and the CDN purged) before this returns.
 ListI18nDraftsResponse:
@@ -465,12 +450,9 @@ UpsertI18nDraftKeyResponse:
   $ref: "./common.yaml#/OkResponse"
 PublishI18nProfileRequest:
   type: object
-  properties:
-    chunk:
-      description: Optional chunk label to stamp on the audit log. Publishing is profile-wide regardless — the whole profile is snapshotted into one KV blob.
-      type: string
+  properties: {}
   additionalProperties: false
-  description: Body for `POST /api/admin/i18n/profiles/{profileId}/publish`. The `chunk` is an audit label only.
+  description: Body for `POST /api/admin/i18n/profiles/{profileId}/publish`. Publishing is profile-wide — the whole profile is snapshotted into one KV blob — so the body takes no options.
 PublishI18nProfileResponse:
   type: object
   properties:
@@ -481,11 +463,6 @@ PublishI18nProfileResponse:
     profile_id:
       type: string
       description: Profile that was published.
-    chunk:
-      anyOf:
-        - type: string
-        - type: "null"
-      description: Audit chunk label, or `null` when none was given.
     published_at:
       type: string
       description: ISO-8601 timestamp of the publish.
@@ -514,7 +491,6 @@ PublishI18nProfileResponse:
   required:
     - ok
     - profile_id
-    - chunk
     - published_at
     - version
     - key_count

package/spec/components/schemas/metrics.yaml

@@ -487,6 +487,11 @@ MetricDirection:
     - lower_better
     - neutral
   description: Desired direction of movement. `higher_better` (default), `lower_better`, or `neutral` (guardrail).
+MetricDisplayUnit:
+  description: Display unit (e.g. `ms`, `%`, `$`), or `null` when unitless.
+  anyOf:
+    - type: string
+    - type: "null"
 CreateMetricRequest:
   oneOf:
     - $ref: "#/CreateMetricWithQuery"
@@ -509,6 +514,8 @@ CreateMetricWithQuery:
       $ref: "#/MetricDefaultMinEffectOfInterest"
     direction:
       $ref: "#/MetricDirection"
+    unit:
+      $ref: "#/MetricDisplayUnit"
   required:
     - name
     - event_name
@@ -532,6 +539,8 @@ CreateMetricWithQueryIr:
       $ref: "#/MetricDefaultMinEffectOfInterest"
     direction:
       $ref: "#/MetricDirection"
+    unit:
+      $ref: "#/MetricDisplayUnit"
   required:
     - name
     - event_name
@@ -559,6 +568,8 @@ UpdateMetricWithQuery:
       $ref: "#/MetricDefaultMinEffectOfInterest"
     direction:
       $ref: "#/MetricDirection"
+    unit:
+      $ref: "#/MetricDisplayUnit"
   required:
     - query
   additionalProperties: false
@@ -578,6 +589,8 @@ UpdateMetricWithQueryIr:
       $ref: "#/MetricDefaultMinEffectOfInterest"
     direction:
       $ref: "#/MetricDirection"
+    unit:
+      $ref: "#/MetricDisplayUnit"
   required:
     - query_ir
   additionalProperties: false
@@ -595,8 +608,10 @@ UpdateMetricFields:
       $ref: "#/MetricDefaultMinEffectOfInterest"
     direction:
       $ref: "#/MetricDirection"
+    unit:
+      $ref: "#/MetricDisplayUnit"
   additionalProperties: false
-  description: Update-metric variant that leaves the query untouched (metadata-only edit — folder, event, winsorisation, default minimum effect of interest, direction).
+  description: Update-metric variant that leaves the query untouched (metadata-only edit — folder, event, winsorisation, default minimum effect of interest, direction, display unit).
 CreateMetricResponse:
   type: object
   properties:

package/spec/components/schemas/ops.yaml

@@ -356,6 +356,11 @@ OpsRun:
         - type: string
         - type: "null"
       description: The agent-run session id recorded on the ack (dashboard deep-links to the run page), or `null`.
+    sessionUrl:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: "The run's session-page deep link, or `null`. DERIVED (never stored): rebuilt from `sessionId` + the run's trigger connector — Claude's routine id (`?trigger=`), Copilot's repo (`/tasks/`), Cursor/Jules from the id alone."
     startedAt:
       type: string
       description: ISO-8601 timestamp the run started (the ack time).
@@ -365,15 +370,7 @@ OpsRun:
         - type: "null"
       description: ISO-8601 timestamp the run closed, or `null` while still open.
     completedAction:
-      anyOf:
-        - type: string
-          enum:
-            - link_pr
-            - notify
-            - status
-            - superseded
-        - type: "null"
-      description: "Which final action closed the run — `link_pr`/`notify` are the agent's terminal ops actions, `status` a completion status flip (ready_for_qa/resolved), `superseded` a newer ack replacing it. `null` while the run is open."
+      $ref: "#/OpsRunActionOrNull"
     prNumber:
       anyOf:
         - type: number
@@ -390,6 +387,7 @@ OpsRun:
     - connectorId
     - ackedBy
     - sessionId
+    - sessionUrl
     - startedAt
     - completedAt
     - completedAction
@@ -918,6 +916,28 @@ CreateBugRequest:
         - $ref: "#/OpsItemPriority"
         - type: "null"
       description: Initial triage priority, or `null`.
+    status:
+      anyOf:
+        - $ref: "#/OpsItemStatus"
+      description: Initial lifecycle status; defaults to `open` when omitted.
+    assigneeId:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: The `users.id` of the person to assign as owner at creation, or `null`.
+    subscribers:
+      type: array
+      items:
+        type: string
+        format: email
+      default: []
+      description: Emails of teammates to subscribe to this item's Slack pings at creation.
+    tags:
+      type: array
+      items:
+        type: string
+      default: []
+      description: Tag names to attach at creation (get-or-created by name, deduped case-insensitively).
     reporterEmail:
       anyOf:
         - type: string
@@ -987,6 +1007,28 @@ CreateFeatureRequestRequest:
         - $ref: "#/OpsItemPriority"
         - type: "null"
       description: Initial triage priority, or `null`.
+    status:
+      anyOf:
+        - $ref: "#/OpsItemStatus"
+      description: Initial lifecycle status; defaults to `open` when omitted.
+    assigneeId:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: The `users.id` of the person to assign as owner at creation, or `null`.
+    subscribers:
+      type: array
+      items:
+        type: string
+        format: email
+      default: []
+      description: Emails of teammates to subscribe to this item's Slack pings at creation.
+    tags:
+      type: array
+      items:
+        type: string
+      default: []
+      description: Tag names to attach at creation (get-or-created by name, deduped case-insensitively).
     reporterEmail:
       anyOf:
         - type: string
@@ -1127,6 +1169,22 @@ OpsItemNotifyOrNull:
     - $ref: ./common.yaml#/NotificationTarget
     - type: "null"
   description: Where this item's completion notification lands, or `null`.
+OpsRunAction:
+  type: string
+  enum:
+    - link_pr
+    - notify
+    - status
+    - superseded
+  description: >-
+    The final action that closed a run record — `link_pr`/`notify` are the
+    agent's terminal ops actions, `status` a completion status flip
+    (ready_for_qa/resolved), `superseded` a newer ack replacing an open run.
+OpsRunActionOrNull:
+  anyOf:
+    - $ref: "#/OpsRunAction"
+    - type: "null"
+  description: Which final action closed the run, or `null` while it is open (or a non-run record).
 UpdateOpsItemStatusRequest:
   type: object
   properties:
@@ -1681,22 +1739,19 @@ OpsInvestigation:
       anyOf:
         - type: string
         - type: "null"
-      description: The agent-run session id, or `null`.
-    ackedBy:
+      description: "The agent-run session id, or `null`."
+    sessionUrl:
       anyOf:
         - type: string
         - type: "null"
-      description: Email of the human who acked (run records for a human ack), or `null`.
-    completedAction:
+      description: "The run's session-page deep link, or `null`. DERIVED (never stored): rebuilt from `sessionId` + the run's trigger connector — Claude's routine id (`?trigger=`), Copilot's repo (`/tasks/`), Cursor/Jules from the id alone. Only `working` run records carry one."
+    ackedBy:
       anyOf:
         - type: string
-          enum:
-            - link_pr
-            - notify
-            - status
-            - superseded
         - type: "null"
-      description: "Which final action closed a `working` run record, or `null` (open run / non-run record)."
+      description: Email of the human who acked (run records for a human ack), or `null`.
+    completedAction:
+      $ref: "#/OpsRunActionOrNull"
     createdAt:
       type: string
       description: ISO-8601 creation timestamp.
@@ -1724,6 +1779,7 @@ OpsInvestigation:
     - startedAt
     - completedAt
     - sessionId
+    - sessionUrl
     - ackedBy
     - completedAction
     - createdAt
@@ -1840,6 +1896,94 @@ CreateOpsInvestigationRequest:
     - kind
   additionalProperties: false
   description: "Body for `POST /api/admin/ops/{handle}/investigation`. `kind` is required; include at least one content field (`summary`/`findings`/`question`/`qaNotes`) — the panel renders whatever it gets."
+UpdateOpsInvestigationRequest:
+  type: object
+  properties:
+    kind:
+      type: string
+      enum:
+        - investigated
+        - detected
+        - question
+        - ready_for_qa
+        - working
+        - note
+      description: Reclassify the record's lifecycle stage (e.g. flip a `working` run into `investigated` once findings land).
+    summary:
+      type: string
+      maxLength: 2000
+      description: One-line summary of the record.
+    findings:
+      type: string
+      maxLength: 50000
+      description: The full findings write-up (markdown).
+    question:
+      type: string
+      maxLength: 10000
+      description: A blocking question for the team (markdown).
+    qaNotes:
+      type: string
+      maxLength: 50000
+      description: How to verify the fix — QA notes (markdown).
+    model:
+      type: string
+      maxLength: 200
+      description: The model the agent ran on.
+    prNumber:
+      type: integer
+      description: A PR the record references.
+    prUrl:
+      type: string
+      format: uri
+      maxLength: 2000
+      description: HTML URL of that PR.
+    sources:
+      type: array
+      maxItems: 200
+      items:
+        type: object
+        properties:
+          path:
+            type: string
+            description: Repo-relative file path inspected.
+          url:
+            type: string
+            description: External link consulted.
+          label:
+            type: string
+            description: Human-readable label for the source.
+        additionalProperties: false
+        description: One file/link inspected while producing the record.
+      description: The files/links inspected.
+    confidence:
+      type: string
+      enum:
+        - low
+        - medium
+        - high
+      description: Self-reported confidence in the record.
+    tokensUsed:
+      type: integer
+      description: Tokens the run consumed.
+    durationMs:
+      type: integer
+      description: Run duration in milliseconds.
+    visibility:
+      type: string
+      enum:
+        - draft
+        - published
+      description: Record visibility. `draft` keeps it out of the panel; `published` surfaces it.
+    completedAt:
+      type: string
+      description: ISO-8601 timestamp the work finished. Set it (or flip `kind` off `working`) to mark a run record done.
+    sessionId:
+      type: string
+      maxLength: 300
+      description: The agent-run session id, so the dashboard can deep-link to the run.
+  additionalProperties: false
+  minProperties: 1
+  description: "Body for `PATCH /api/admin/ops/{handle}/investigation/{investigationId}` — a partial update of one existing investigation record (typically the `working` run record you were handed). Send only the fields you want to change; at least one is required."
 NotificationFeedItem:
   type: object
   properties:

package/spec/openapi.yaml

@@ -209,6 +209,15 @@ tags:
       **Mentions.** `@teammate` in a body raises an in-app notification for that
       person; `@shipeasy` asks Jarvis (the AI agent) to read the item and reply.
       Comments authored by Jarvis carry `authorType: system`.
+  - name: Investigations
+    parent: Ops
+    description: |-
+      Investigation records on a queue item — the structured, read-only write-ups
+      an AI agent produces while working it (findings / a blocking question / QA
+      notes), plus the `working` run rows an ack or an AI hand-off opens. This is
+      the AI-write seam the cockpit's detail panel renders: `list` reads what a
+      previous run found, `create` appends a new record, and `update` fills in the
+      `working` run record you were handed (findings, PR, confidence) as you work.
   - name: Projects
     description: |-
       Projects: the account-level container every other resource is scoped to.
@@ -219,14 +228,14 @@ tags:
   - name: i18n
     description: |-
       String Manager (i18n): the worker-safe REST surface — locale profiles, the
-      insert-only key push, single-key overwrite, chunk publish, and the read-only
+      insert-only key push, single-key overwrite, profile publish, and the read-only
       key/draft listings.
 
       The fs/AST parts (scan, validate, install-loader, codemod) are NOT part of
       this API — they stay in the fs-having CLI/MCP.
   - name: Profiles
     parent: i18n
-    description: Locale profiles (e.g. `en:prod`) — create, list, and publish a profile's chunks to the CDN.
+    description: Locale profiles (e.g. `en:prod`) — create, list, and publish a profile to the CDN.
   - name: Keys
     parent: i18n
     description: Translation keys — the insert-only push, single-key overwrite, and key listing.
@@ -351,6 +360,8 @@ paths:
     $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}~1ack
   /api/admin/ops/{handle}/investigation:
     $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}~1investigation
+  /api/admin/ops/{handle}/investigation/{investigationId}:
+    $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}~1investigation~1{investigationId}
   /api/admin/agent-profiles:
     $ref: ./paths/ops.yaml#/~1api~1admin~1agent-profiles
   /api/admin/ops/{handle}/comments: