@shipeasy/openapi 2.3.0 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/openapi",
-  "version": "2.3.0",
+  "version": "2.5.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/errors.yaml

@@ -28,6 +28,8 @@ ErrorCode:
     # Metrics
     - METRIC_NOT_FOUND
     - METRIC_UNKNOWN_ID
+    # Ops
+    - AGENT_NOT_CONNECTED
   x-enum-descriptions:
     BAD_REQUEST: Malformed request (bad JSON, missing project scope).
     UNAUTHORIZED: Missing or invalid admin SDK key.
@@ -53,6 +55,7 @@ ErrorCode:
     EXPERIMENT_IMMUTABLE_FIELD: A field that is immutable while the experiment is running was modified.
     METRIC_NOT_FOUND: The referenced metric does not exist or is not visible to the caller.
     METRIC_UNKNOWN_ID: The supplied metric id is malformed or not recognised.
+    AGENT_NOT_CONNECTED: The named AI agent type has no connected trigger connector in this project — list the available agents (`ops agents list` / `GET /api/admin/agent-profiles`) and use one of those, or connect the agent under Settings → Triggers.
 Error:
   type: object
   description: Uniform error envelope returned by every admin endpoint on a non-2xx status. `error` is the human-readable message; `code` is the stable machine code (present whenever the failure maps to a catalogued `ErrorCode`); `detail` carries extra context (validation paths, conflicting field); `fields` maps each failing input field to its own message; `instructions` is optional actionable guidance for resolving the error; `schema` echoes back the expected JSON Schema when a value failed schema validation.

package/spec/components/schemas/alerts.yaml

@@ -0,0 +1,138 @@
+AlertApiRow:
+  type: object
+  description: |-
+    One FIRED alert — a condition the platform observed and raised, not the rule that defines it (alert *rules* are the `/api/admin/alert-rules` resource). Alerts are never filed by hand: the UI (killswitch flips) and the worker (analysis consumer + alerts cron) raise them, keyed by `(source, dedupeKey)` so re-raising refreshes the active row and a clearing condition auto-resolves it.
+
+    Every field is always present on the wire; nullable fields are `null`, never absent.
+  properties:
+    id:
+      type: string
+      description: Stable opaque alert id.
+    source:
+      type: string
+      enum:
+        - metric_rule
+        - killswitch_armed
+        - experiment_srm
+        - experiment_peek
+        - guardrail
+      description: Which platform subsystem raised the alert — a metric-threshold rule crossing (`metric_rule`), an armed kill switch (`killswitch_armed`), a sample-ratio mismatch or peeking guard on an experiment (`experiment_srm` / `experiment_peek`), or a guardrail-metric breach (`guardrail`).
+    ruleId:
+      description: >-
+        Id of the alert rule that raised it (`ar_…`), for `source: metric_rule`.
+        `null` for alerts raised outside the rules engine.
+      anyOf:
+        - type: string
+        - type: "null"
+    severity:
+      type: string
+      enum:
+        - danger
+        - warn
+        - info
+      description: How loud the alert is — `danger` pages, `warn` is the default, `info` is FYI-only.
+    dedupeKey:
+      type: string
+      description: Idempotency + reconcile key within `(project, source)` — re-raising the same condition refreshes the existing active row instead of stacking duplicates, and the condition clearing flips that row to `resolved`.
+    title:
+      type: string
+      description: Short human-readable headline (what fired).
+    detail:
+      type: string
+      description: Longer human-readable explanation — the observed condition, thresholds, and context.
+    href:
+      description: Dashboard-relative link to the surface that explains the alert (e.g. the experiment or kill switch page), or `null` if there is no single destination.
+      anyOf:
+        - type: string
+        - type: "null"
+    observedValue:
+      description: The numeric value that tripped the condition (e.g. the metric aggregate a rule compared against its threshold), or `null` when the source has no scalar observation.
+      anyOf:
+        - type: number
+        - type: "null"
+    status:
+      type: string
+      enum:
+        - active
+        - resolved
+        - dismissed
+      description: Lifecycle state. `active` means the condition currently holds (shown as "Firing" in the UI); `resolved` means it cleared (auto, when the raiser reconciles, or by hand); `dismissed` means a human waved it off.
+    createdAt:
+      type: string
+      description: ISO-8601 timestamp the alert was first raised.
+    resolvedAt:
+      description: ISO-8601 timestamp the alert flipped to `resolved`, or `null` while it hasn't.
+      anyOf:
+        - type: string
+        - type: "null"
+    dismissedAt:
+      description: ISO-8601 timestamp the alert was dismissed, or `null` while it hasn't been.
+      anyOf:
+        - type: string
+        - type: "null"
+    assigneeId:
+      description: PERSON owner of the triage — a `users.id` (soft reference, same value space as a feedback item's `assigneeId`), or `null` if unassigned. Set from the ops cockpit's Owner column; independent of the agent half.
+      anyOf:
+        - type: string
+        - type: "null"
+    assigneeConnectorId:
+      description: AGENT owner — the id of a connected trigger connector (`connectors.id`), or `null`. Mutually exclusive with `assigneeAgent`.
+      anyOf:
+        - type: string
+        - type: "null"
+    assigneeAgent:
+      description: AGENT owner — a built-in hosted Shipeasy agent (`"jarvis"`, Enterprise-gated), or `null`. Mutually exclusive with `assigneeConnectorId`.
+      anyOf:
+        - type: string
+        - type: "null"
+  required:
+    - id
+    - source
+    - ruleId
+    - severity
+    - dedupeKey
+    - title
+    - detail
+    - href
+    - observedValue
+    - status
+    - createdAt
+    - resolvedAt
+    - dismissedAt
+    - assigneeId
+    - assigneeConnectorId
+    - assigneeAgent
+  additionalProperties: false
+ListAlertsResponse:
+  type: array
+  description: A bare JSON array of fired alerts, ordered by `createdAt` descending. There is no pagination envelope.
+  items:
+    $ref: "#/AlertApiRow"
+UpdateAlertRequest:
+  type: object
+  description: |-
+    Body for `PATCH /api/admin/alerts/{id}` — the triage writes the ops cockpit needs on a fired alert. All fields optional, at least one required; only the fields present are changed.
+
+    Flipping `status` stamps the matching timestamp (`resolvedAt` on `resolved`, `dismissedAt` on `dismissed`; both cleared on `active`). The person owner (`assigneeId`) and the agent owner (`agent`) are independent halves — setting one never touches the other.
+  properties:
+    status:
+      type: string
+      enum:
+        - active
+        - resolved
+        - dismissed
+      description: New lifecycle state. `resolved` / `dismissed` stamp their timestamp; `active` re-opens and clears both.
+    assigneeId:
+      description: PERSON owner — a `users.id`, or `null` to clear the assignment.
+      anyOf:
+        - type: string
+        - type: "null"
+    agent:
+      description: AGENT owner — a connected trigger connector's id (`connectors.id`), the built-in `"jarvis"` (Enterprise plan only — rejected with `403` otherwise), or `null` to clear. Stored in `assigneeConnectorId` or `assigneeAgent` depending on the value; the two are mutually exclusive.
+      anyOf:
+        - type: string
+        - type: "null"
+  minProperties: 1
+  additionalProperties: false
+UpdateAlertResponse:
+  $ref: "#/AlertApiRow"

package/spec/components/schemas/attributes.yaml

@@ -3,17 +3,67 @@ ListAttributesResponse:
   items:
     type: object
     properties:
+      id:
+        type: string
+        description: Stable opaque attribute id.
       name:
         type: string
         description: Attribute key as seen in evaluation context (e.g. `plan`, `country`).
       type:
-        description: Inferred value type (`string`, `number`, `boolean`, …) when known.
+        $ref: "#/AttributeType"
+      enumValues:
+        description: Allowed values for `enum` attributes, else `null`.
+        anyOf:
+          - type: array
+            items:
+              type: string
+          - type: "null"
+      required:
+        type: integer
+        enum:
+          - 0
+          - 1
+        description: Whether the attribute must be present on the evaluation context (D1 stores the flag as `0`/`1`).
+      description:
+        description: Human note shown in the dashboard, or `null`.
+        anyOf:
+          - type: string
+          - type: "null"
+      sdkPath:
+        description: Dotted path the SDK reads the value from, or `null`.
+        anyOf:
+          - type: string
+          - type: "null"
+      createdAt:
+        type: string
+        description: ISO-8601 creation timestamp.
+      source:
         type: string
+        enum:
+          - auto
+          - manual
+        description: How the attribute came to exist — `auto` (inferred by the `/sdk/evaluate` sampler) or `manual` (declared via the UI/API).
+      lastSeenAt:
+        description: ISO-8601 timestamp of the most recent SDK sample that carried this attribute, or `null` when never sampled.
+        anyOf:
+          - type: string
+          - type: "null"
+      deprecated:
+        type: integer
+        enum:
+          - 0
+          - 1
+        description: "`1` when an auto-discovered attribute has stopped appearing in samples. Deprecated attributes stay listed; pickers may hide or de-rank them."
     required:
+      - id
       - name
+      - type
+    # Deliberately left open — the endpoint returns the raw attribute row, which
+    # still carries undocumented internal columns; tighten to `false` only once
+    # the handler projects an explicit allow-list.
     additionalProperties: {}
-    description: One auto-inferred targeting attribute.
-  description: Every auto-inferred targeting attribute in the project.
+    description: One declared or auto-inferred targeting attribute row.
+  description: Every targeting attribute in the project (declared and auto-inferred).
 AttributeType:
   type: string
   enum:

package/spec/components/schemas/common.yaml

@@ -49,6 +49,16 @@ NotificationTarget:
       additionalProperties: false
     - type: "null"
   description: Delivery target for a notification; `null` = use the project default.
+OkResponse:
+  type: object
+  properties:
+    ok:
+      type: boolean
+      const: true
+      description: Always `true` — the operation succeeded (errors use the error envelope instead).
+  required: [ok]
+  additionalProperties: false
+  description: Generic success acknowledgement for operations with no meaningful payload.
 PageQuery:
   type: object
   properties:

package/spec/components/schemas/configs.yaml

@@ -17,10 +17,25 @@ ListConfigsResponse:
             anyOf:
               - type: string
               - type: "null"
+          folder:
+            description: Folder segment used for dashboard organisation, or `null` when the config lives at the root.
+            anyOf:
+              - type: string
+              - type: "null"
           schema:
             type: object
             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.
+          creatorEmail:
+            description: Resolved email of the creator (`created_by` → `users.email`), or `null` when unknown. List-only enrichment — present on `GET /api/admin/configs` rows, absent from the by-id detail — so it is optional, never required.
+            anyOf:
+              - type: string
+              - type: "null"
+          createdAt:
+            description: ISO-8601 creation timestamp, or `null` on legacy rows. List-only enrichment — present on `GET /api/admin/configs` rows, absent from the by-id detail — so it is optional, never required.
+            anyOf:
+              - type: string
+              - type: "null"
           updatedAt:
             type: string
             description: ISO-8601 timestamp of last mutation.
@@ -80,6 +95,7 @@ ListConfigsResponse:
           - id
           - name
           - description
+          - folder
           - schema
           - updatedAt
           - envs
@@ -107,10 +123,25 @@ GetConfigResponse:
       anyOf:
         - type: string
         - type: "null"
+    folder:
+      description: Folder segment used for dashboard organisation, or `null` when the config lives at the root.
+      anyOf:
+        - type: string
+        - type: "null"
     schema:
       type: object
       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.
+    creatorEmail:
+      description: Resolved email of the creator (`created_by` → `users.email`), or `null` when unknown. List-only enrichment — present on `GET /api/admin/configs` rows, absent from this by-id detail — so it is optional, never required.
+      anyOf:
+        - type: string
+        - type: "null"
+    createdAt:
+      description: ISO-8601 creation timestamp, or `null` on legacy rows. List-only enrichment — present on `GET /api/admin/configs` rows, absent from this by-id detail — so it is optional, never required.
+      anyOf:
+        - type: string
+        - type: "null"
     updatedAt:
       type: string
       description: ISO-8601 timestamp of last mutation.
@@ -170,6 +201,7 @@ GetConfigResponse:
     - id
     - name
     - description
+    - folder
     - schema
     - updatedAt
     - envs
@@ -191,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:
@@ -219,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:
@@ -268,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
@@ -369,3 +431,29 @@ ListConfigActivityResponse:
       - createdAt
     additionalProperties: false
   description: Recent audit rows for one config, newest first.
+ListConfigVersionsResponse:
+  type: array
+  items:
+    type: object
+    properties:
+      version:
+        type: integer
+        minimum: 1
+        maximum: 9007199254740991
+        description: Published version number on the requested env (monotonically increasing per env).
+      value:
+        description: The full JSON value that was published at this version.
+      publishedAt:
+        type: string
+        description: ISO-8601 publish timestamp.
+      publishedBy:
+        type: string
+        description: Email/id of the actor who published this version.
+    required:
+      - version
+      - value
+      - publishedAt
+      - publishedBy
+    additionalProperties: false
+    description: One published version of the config's value on the requested env.
+  description: Full published-value history for one (config, env), newest first. The config's schema is config-level and not versioned — this is value history only.

package/spec/components/schemas/connectors.yaml

@@ -47,6 +47,9 @@ ConnectorRecord:
         - type: string
         - type: "null"
       description: "Display label for the connected account / target (e.g. the OAuth account email, or a trigger's idempotency key such as its repo url or routine id). `null` until the connector is authenticated/configured."
+    hasCredentials:
+      type: boolean
+      description: "Whether an encrypted credentials cipher is stored for this connector (`true` once OAuth/token setup completed). The cipher itself is never serialised — this boolean is the only signal. `false` for a fresh OAuth stub or a tokenless trigger."
     lastError:
       anyOf:
         - type: string
@@ -77,13 +80,14 @@ ConnectorRecord:
     - events
     - config
     - accountLabel
+    - hasCredentials
     - lastError
     - lastAttemptAt
     - lastSuccessAt
     - createdAt
     - updatedAt
   additionalProperties: false
-  description: "A connector row. The encrypted credentials cipher backing the connector is intentionally never serialised."
+  description: "A connector row. The encrypted credentials cipher backing the connector is intentionally never serialised — `hasCredentials` reports only whether one is stored."
 ListConnectorsResponse:
   type: array
   items:

package/spec/components/schemas/errors-api.yaml

@@ -3,7 +3,7 @@ ErrorRecord:
   description: |-
     A tracked production error — one row per distinct issue, keyed by `fingerprint`. Rows are never created by hand: an ingestion path (worker log drain / the `see()` SDK reporter) folds each occurrence into the matching row, bumping `count` and `lastSeenAt`. The admin surface only lists them, reads one, and flips `status`.
 
-    Field names are camelCase (the D1 row projected through Drizzle). Many columns are nullable because the reporting source may not supply them.
+    Field names are camelCase (the D1 row projected through Drizzle). Every row column is always present on the wire; many are *nullable* because the reporting source may not supply them — `null`, never absent. Only `occurrences` is conditional (detail reads only).
   properties:
     id:
       type: string
@@ -121,25 +121,62 @@ ErrorRecord:
     updatedAt:
       type: string
       description: ISO-8601 timestamp of the last mutation (e.g. a status flip).
+    assigneeId:
+      description: PERSON owner of the triage — a `users.id` (soft reference, same value space as a feedback item's `assigneeId`), or `null` if unassigned. Set from the ops cockpit's Owner column; independent of the agent half.
+      anyOf:
+        - type: string
+        - type: "null"
+    assigneeConnectorId:
+      description: AGENT owner — the id of a connected trigger connector (`connectors.id`), or `null`. Mutually exclusive with `assigneeAgent`.
+      anyOf:
+        - type: string
+        - type: "null"
+    assigneeAgent:
+      description: AGENT owner — a built-in hosted Shipeasy agent (`"jarvis"`, Enterprise-gated), or `null`. Mutually exclusive with `assigneeConnectorId`.
+      anyOf:
+        - type: string
+        - type: "null"
   required:
     - id
     - projectId
     - fingerprint
+    - causedByFingerprint
     - message
+    - errorType
+    - stack
+    - source
+    - url
+    - seenUrls
+    - subject
+    - outcome
+    - side
+    - env
+    - kind
+    - lastExtrasJson
+    - sdkVersion
     - count
     - status
     - firstSeenAt
     - lastSeenAt
     - createdAt
     - updatedAt
+    - assigneeId
+    - assigneeConnectorId
+    - assigneeAgent
   additionalProperties: false
 ErrorOccurrence:
   type: object
-  description: One sampled instance behind a tracked error — the minimal per-occurrence payload (what varies between instances; everything else lives on the parent `ErrorRecord`).
+  description: One sampled instance behind a tracked error — the minimal per-occurrence payload (what varies between instances; everything else lives on the parent `ErrorRecord`). Every column is always present on the wire; nullable columns are `null`, never absent.
   properties:
     id:
       type: string
       description: Stable opaque occurrence id.
+    projectId:
+      type: string
+      description: Project this occurrence belongs to. Always echoes the parent error's `projectId` — redundant on this nested read (a projection candidate), kept because the raw row is returned as-is today.
+    errorId:
+      type: string
+      description: Id of the parent tracked error (`err_…`). Always echoes the enclosing `ErrorRecord.id` — redundant on this nested read (a projection candidate), kept because the raw row is returned as-is today.
     message:
       type: string
       description: This instance's raw message (unlike the fingerprint, never normalized).
@@ -182,7 +219,15 @@ ErrorOccurrence:
       description: ISO-8601 timestamp this instance was ingested.
   required:
     - id
+    - projectId
+    - errorId
     - message
+    - stack
+    - url
+    - env
+    - side
+    - sdkVersion
+    - extrasJson
     - sampleRate
     - seenAt
   additionalProperties: false
@@ -214,8 +259,10 @@ FileErrorTicketResponse:
       type: string
       description: Feedback ticket id.
     number:
-      type: integer
-      description: Human-facing per-project ticket number.
+      description: Human-facing per-project ticket number. `null` only on the idempotent dedupe path when the pre-existing ticket is a legacy row created before per-project numbering.
+      anyOf:
+        - type: integer
+        - type: "null"
   required:
     - id
     - number