@shipeasy/openapi 2.1.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/openapi",
-  "version": "2.1.0",
+  "version": "2.3.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

@@ -17,6 +17,17 @@ ErrorCode:
     - GROUPS_WEIGHT_SUM
     - EVENT_PENDING
     - INTERNAL
+    - PLAN_LIMIT
+    # Experiments
+    - EXPERIMENT_NO_GOAL_METRIC
+    - EXPERIMENT_ARCHIVED_RESTART
+    - EXPERIMENT_RESTORE_INVALID
+    - EXPERIMENT_NOT_RUNNING
+    - EXPERIMENT_RUNNING_ARCHIVE
+    - EXPERIMENT_IMMUTABLE_FIELD
+    # Metrics
+    - METRIC_NOT_FOUND
+    - METRIC_UNKNOWN_ID
   x-enum-descriptions:
     BAD_REQUEST: Malformed request (bad JSON, missing project scope).
     UNAUTHORIZED: Missing or invalid admin SDK key.
@@ -33,9 +44,18 @@ ErrorCode:
     GROUPS_WEIGHT_SUM: Experiment group weights must sum to 10000 (basis points).
     EVENT_PENDING: The referenced event is still pending review and cannot back a metric yet.
     INTERNAL: Unexpected server error.
+    PLAN_LIMIT: The action would exceed a plan quota (e.g. the tier's maximum experiments, metrics, or configs). Upgrade the plan or archive an existing resource.
+    EXPERIMENT_NO_GOAL_METRIC: The experiment has no goal metric set, which the requested action requires.
+    EXPERIMENT_ARCHIVED_RESTART: An archived experiment cannot be restarted.
+    EXPERIMENT_RESTORE_INVALID: The experiment cannot be restored from its current state.
+    EXPERIMENT_NOT_RUNNING: The action requires the experiment to be running.
+    EXPERIMENT_RUNNING_ARCHIVE: A running experiment cannot be archived — stop it first.
+    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.
 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); `instructions` is optional actionable guidance for resolving the error.
+  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.
   required:
     - error
   additionalProperties: false
@@ -48,6 +68,15 @@ Error:
     detail:
       type: string
       description: Extra context (validation details, conflicting field, referenced row).
+    fields:
+      type: object
+      additionalProperties:
+        type: string
+      description: Per-field validation messages, keyed by the submitted field's path (dot-notation for nested fields, e.g. `groups.0.weight`). Present when structural validation failed on one or more specific input fields, so a client form can attach each message to its own input instead of collapsing everything into one banner.
     instructions:
       type: string
       description: Actionable guidance for resolving this error — what to check or change next.
+    schema:
+      type: object
+      additionalProperties: true
+      description: The expected JSON Schema (draft 2020-12) the submitted value must satisfy. Returned only when a value failed schema validation (e.g. a config `value` that does not match its config's saved schema), so the caller can correct the value and retry without re-fetching.

package/spec/components/parameters.yaml

@@ -22,3 +22,11 @@ PaginationCursor:
   description: Opaque cursor returned in the previous page's `next_cursor`. Omit for the first page.
   schema:
     type: string
+Q:
+  name: q
+  in: query
+  required: false
+  description: Case-insensitive substring filter across the resource's human-readable text columns (e.g. `name`, `title`, `description`). OR-matched across those columns; omit to return everything.
+  schema:
+    type: string
+    maxLength: 100

package/spec/components/responses.yaml

@@ -105,3 +105,18 @@ UnprocessableEntity:
           value:
             error: The referenced event is still pending review and cannot back a metric yet.
             code: EVENT_PENDING
+BadGateway:
+  description: |-
+    The request was well-formed and the resource exists, but a downstream provider
+    the endpoint delegates to (e.g. a connector's Slack/GitHub/cloud-agent dispatch)
+    failed. The failure is upstream of this API, not a client error. No stable
+    `ErrorCode` is assigned to upstream failures, so `code` is omitted.
+  content:
+    application/json:
+      schema:
+        $ref: ./errors.yaml#/Error
+      examples:
+        UPSTREAM_FAILURE:
+          summary: Downstream provider dispatch failed
+          value:
+            error: "GitHub API responded 403: resource not accessible by integration."

package/spec/components/schemas/common.yaml

@@ -1,4 +1,9 @@
 # Cross-cutting shared schemas referenced from multiple resources.
+ResourceId:
+  type: string
+  minLength: 1
+  maxLength: 128
+  description: A resource path identifier — an opaque `xxx_<ULID>` id (~30 chars) or the resource's `name`/`key`. 1–128 characters; the upper bound matches the longest name/key any resource accepts, so an over-long value can never name a real row.
 Env:
   type: string
   enum:
@@ -83,5 +88,11 @@ ExperimentInlineMetric:
       enum: [count_users, count_events, retention_7d, retention_30d, sum, avg]
       description: Reducer for the `event` form. Defaults to `count_users`.
     value: { type: string, minLength: 1, maxLength: 256, description: Numeric event property for `sum`/`avg` (with `event`). }
+    min_effect_of_interest:
+      description: Per-experiment override of the metric's default minimum effect of interest (relative, 0–1) — the smallest change worth acting on for this experiment's decision. `null`/omitted inherits the metric default. For a guardrail, the non-inferiority margin.
+      default: null
+      anyOf:
+        - type: number
+        - type: "null"
   additionalProperties: false
   description: Inline metric — a DSL `query`, or an `event` (+ `aggregation`/`value`) the server compiles into one.

package/spec/components/schemas/connectors.yaml

@@ -564,30 +564,24 @@ FireConnectorResponse:
   properties:
     ok:
       type: boolean
-      description: "`true` when the trigger run was successfully kicked off; `false` when the dispatch itself failed (still HTTP 200, with `error` set)."
-    error:
-      type: string
-      description: "Failure reason. Present only when `ok` is `false` — the fire reached the handler but the underlying dispatch to the provider failed."
+      description: "Always `true` — a successful fire returns HTTP 200. A dispatch failure returns HTTP 502 with the `Error` envelope, not this body."
   required:
     - ok
   additionalProperties: false
-  description: "Result of firing a trigger connector. `{ ok: true }` on success; `{ ok: false, error }` when the dispatch fails (the request still returns HTTP 200)."
+  description: "Result of a successful trigger fire: `{ ok: true }`. When the downstream dispatch fails the endpoint returns HTTP 502 (see the `Error` response), never `ok: false`."
 TestConnectorResponse:
   type: object
   properties:
     ok:
       type: boolean
-      description: "`true` when the test dispatch reached the destination; `false` when the dispatch itself failed (still HTTP 200, with `error` set)."
+      description: "Always `true` — a successful test returns HTTP 200. A dispatch failure returns HTTP 502 with the `Error` envelope, not this body."
     issueUrl:
       anyOf:
         - type: string
         - type: "null"
-      description: "URL of the artifact the test produced (e.g. the GitHub Issue created by a `github` connector), or `null` when the provider produces no linkable artifact (or the dispatch failed)."
-    error:
-      type: string
-      description: "Failure reason. Present only when `ok` is `false` — the test reached the handler but the underlying dispatch to the provider failed."
+      description: "URL of the artifact the test produced (e.g. the GitHub Issue created by a `github` connector), or `null` when the provider produces no linkable artifact."
   required:
     - ok
     - issueUrl
   additionalProperties: false
-  description: "Result of testing a connector. `{ ok: true, issueUrl }` on success; `{ ok: false, issueUrl: null, error }` when the dispatch fails (the request still returns HTTP 200)."
+  description: "Result of a successful connector test: `{ ok: true, issueUrl }`. When the downstream dispatch fails the endpoint returns HTTP 502 (see the `Error` response), never `ok: false`."

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

@@ -13,7 +13,11 @@ ErrorRecord:
       description: Project this issue belongs to.
     fingerprint:
       type: string
-      description: Stable dedupe key (hash of `errorType` + normalized `message` + consequence). Unique per project — every occurrence with the same fingerprint folds into this one row.
+      description: >-
+        Stable dedupe key — the issue TITLE (hash of `errorType` + `subject` +
+        `outcome`, plus the violation name for violations). Unique per project —
+        every occurrence with the same title folds into this one row;
+        per-instance variety (message/stack/extras) lives in `occurrences`.
     causedByFingerprint:
       description: Fingerprint of the issue this one descends from — set when `see()` reported the same error (re-throw) or its `{ cause }` (wrap) at an inner boundary first. Points at another error's `fingerprint` in the same project (soft reference, no FK). `null` for a root issue.
       anyOf:
@@ -91,7 +95,13 @@ ErrorRecord:
     count:
       type: integer
       minimum: 1
-      description: Number of folded occurrences for this fingerprint.
+      description: EXACT number of folded occurrences for this fingerprint — every occurrence increments it, regardless of detail-row sampling.
+    occurrences:
+      type: array
+      description: |-
+        Sampled per-instance detail rows behind this issue, newest first. Returned only by `GET /api/admin/errors/{id}` (never in list responses). The parent row's `count` / `firstSeenAt` / `lastSeenAt` are exact; these rows are a *sampled sketch* of the instances — exhaustive while the issue is small, thinning to roughly 1-in-10 past 10 occurrences, 1-in-100 past 100, and 1-in-1000 past 1000 (each row's `sampleRate` records the rate in force when it was kept), capped at the newest 100 rows.
+      items:
+        $ref: "#/ErrorOccurrence"
     status:
       type: string
       enum:
@@ -123,9 +133,62 @@ ErrorRecord:
     - createdAt
     - updatedAt
   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`).
+  properties:
+    id:
+      type: string
+      description: Stable opaque occurrence id.
+    message:
+      type: string
+      description: This instance's raw message (unlike the fingerprint, never normalized).
+    stack:
+      description: This instance's stack trace, or `null` if none was captured.
+      anyOf:
+        - type: string
+        - type: "null"
+    url:
+      description: This instance's raw URL (ids intact), or `null`.
+      anyOf:
+        - type: string
+        - type: "null"
+    env:
+      description: Published env this instance ran against, or `null`.
+      anyOf:
+        - type: string
+        - type: "null"
+    side:
+      description: Which SDK side reported it — `client` or `server`. `null` if unknown.
+      anyOf:
+        - type: string
+        - type: "null"
+    sdkVersion:
+      description: "`@shipeasy/sdk` version of this instance, or `null`."
+      anyOf:
+        - type: string
+        - type: "null"
+    extrasJson:
+      description: This instance's sanitized extras, JSON-encoded. `null` if none.
+      anyOf:
+        - type: string
+        - type: "null"
+    sampleRate:
+      type: integer
+      minimum: 1
+      description: 1-in-N sampling rate in force when this instance was kept (`1` = the issue was still being recorded exhaustively).
+    seenAt:
+      type: string
+      description: ISO-8601 timestamp this instance was ingested.
+  required:
+    - id
+    - message
+    - sampleRate
+    - seenAt
+  additionalProperties: false
 ListErrorsResponse:
   type: array
-  description: A bare JSON array of tracked errors, ordered by `lastSeenAt` descending. There is no pagination envelope — `limit` caps the page size.
+  description: A bare JSON array of tracked errors, ordered by `lastSeenAt` descending. There is no pagination envelope — `limit` caps the page size. List rows never include `occurrences` — read one error to get them.
   items:
     $ref: "#/ErrorRecord"
 UpdateErrorStatusRequest:

package/spec/components/schemas/experiment-api-row.yaml

@@ -0,0 +1,293 @@
+# The single wire shape for an experiment row, shared by `ListExperimentsResponse`
+# (`data[]` items) and `GET /api/admin/experiments/{id}`. The app projects every
+# experiment through one `toExperimentApiRow` allow-list at the HTTP boundary, so
+# both endpoints return the SAME object — this schema is that allow-list.
+#
+# Two tiers of fields:
+#   • base (always present) — persisted columns + the pool-slice / headroom /
+#     version fields the serializer defaults (`?? null` / `?? 0` / `?? 1`), so
+#     they appear on every row. These are `required`.
+#   • enriched (list only) — verdict + goal/guardrail summary + exposure spark +
+#     resolved creator/editor emails. The list handler derives them for every
+#     row; the by-id handler returns the raw row, so they are `undefined` and
+#     drop out of the JSON. They are therefore OPTIONAL (present on list rows,
+#     absent on the by-id detail) — never `required`.
+ExperimentApiRow:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Stable opaque experiment id (`exp_…`).
+    name:
+      type: string
+      maxLength: 128
+      pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
+      description: Stable experiment key. Single segment or `folder.name` (a-z, 0-9, `_`/`-`; max 128 chars). Used by SDKs as `Shipeasy.getExperiment(user, '<name>')`. Immutable after create.
+    description:
+      anyOf:
+        - type: string
+        - type: "null"
+    hypothesis:
+      anyOf:
+        - type: string
+        - type: "null"
+    tag:
+      anyOf:
+        - type: string
+        - type: "null"
+    ownerEmail:
+      anyOf:
+        - type: string
+        - type: "null"
+    audience:
+      anyOf:
+        - type: string
+        - type: "null"
+    bucketBy:
+      anyOf:
+        - type: string
+          minLength: 1
+          maxLength: 128
+          pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
+          description: User-attribute name used as the bucketing key — e.g. `user_id` (default), `session_id`, `device_id`, or a custom attribute like `company_id` to keep a whole org on one variant. Defaults to `user_id` when omitted.
+        - type: "null"
+    folder:
+      anyOf:
+        - type: string
+        - type: "null"
+    status:
+      type: string
+      enum:
+        - draft
+        - running
+        - stopped
+        - archived
+    universe:
+      type: string
+      description: Universe name this experiment draws from.
+    targetingGate:
+      anyOf:
+        - type: string
+        - type: "null"
+    holdoutGate:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Per-experiment holdout gate name (a `holdout`-type flag), or `null`.
+    allocationPct:
+      type: integer
+      minimum: -9007199254740991
+      maximum: 9007199254740991
+      description: Allocation in basis points (0–10000).
+    reservedHeadroom:
+      type: integer
+      minimum: 0
+      maximum: 10000
+      description: Basis points of the split reserved for appended variants (group weights sum to 10000 − this).
+    hashVersion:
+      type: integer
+      minimum: 1
+      description: Bucketing hash algorithm version for the experiment's pool slice (§B4). Defaults to 1.
+    poolOffsetBp:
+      anyOf:
+        - type: integer
+          minimum: 0
+          maximum: 10000
+        - type: "null"
+      description: Basis-point offset of the experiment's contiguous slice in the universe pool, or `null` before a slice is allocated.
+    poolSizeBp:
+      anyOf:
+        - type: integer
+          minimum: 0
+          maximum: 10000
+        - type: "null"
+      description: Basis-point width of the experiment's pool slice (equal to its allocation), or `null` before a slice is allocated.
+    salt:
+      type: string
+    params:
+      type: object
+      additionalProperties:
+        type: string
+        enum:
+          - string
+          - bool
+          - number
+    groups:
+      type: array
+      items:
+        type: object
+        properties:
+          name:
+            type: string
+            minLength: 1
+            maxLength: 64
+            description: Group label (e.g. `control`, `treatment_a`). Max 64 chars.
+          weight:
+            type: integer
+            minimum: 0
+            maximum: 10000
+            description: Allocation weight in basis points (0–10000). The sum across all groups must equal exactly **10000** (100%).
+          params:
+            default: {}
+            description: Per-group parameter values delivered to the SDK when a caller is hashed into this group. Keys must match the experiment's `params` schema.
+            type: object
+            additionalProperties: {}
+        required:
+          - name
+          - weight
+        additionalProperties: false
+        description: One variant in the experiment. Weights across all groups must sum to 10000.
+    significanceThreshold:
+      type: number
+    minRuntimeDays:
+      type: integer
+      minimum: -9007199254740991
+      maximum: 9007199254740991
+    minSampleSize:
+      type: integer
+      minimum: -9007199254740991
+      maximum: 9007199254740991
+    sequentialTesting:
+      type: boolean
+    startedAt:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: ISO-8601 timestamp the experiment last transitioned to `running`, or `null`.
+    stoppedAt:
+      anyOf:
+        - type: string
+        - type: "null"
+    updatedAt:
+      type: string
+    version:
+      anyOf:
+        - type: integer
+        - type: "null"
+      description: Save counter (number of published edits), or `null` on pre-versioning rows.
+    creatorEmail:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: "Resolved creator email (`created_by` → users). Enriched field: present on list rows, omitted from the by-id detail."
+    updaterEmail:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: "Resolved last-editor email (`updated_by` → users). Enriched field: present on list rows, omitted from the by-id detail."
+    verdict:
+      type: string
+      enum:
+        - ship
+        - hold
+        - wait
+        - invalid
+        - draft
+      description: "Answer-first decision from the goal metric + guardrails + SRM vs. the significance threshold and min runtime: `ship`, `hold`, `wait`, `invalid`, `draft`. Enriched field: list rows only."
+    verdictTitle:
+      type: string
+      description: "Expanded verdict headline the results hero renders. Enriched field: list rows only."
+    verdictWhy:
+      type: string
+      description: "Verdict rationale the results hero renders. Enriched field: list rows only."
+    goalMetric:
+      anyOf:
+        - type: object
+          properties:
+            id:
+              type: string
+            name:
+              type: string
+          required:
+            - id
+            - name
+          additionalProperties: false
+        - type: "null"
+      description: "The experiment's goal metric `{ id, name }`, or `null` when none is set. Enriched field: list rows only."
+    guardrails:
+      type: array
+      items:
+        type: object
+        properties:
+          id:
+            type: string
+          name:
+            type: string
+          eventName:
+            anyOf:
+              - type: string
+              - type: "null"
+        required:
+          - id
+          - name
+        additionalProperties: false
+      description: "Guardrail metrics `{ id, name, eventName? }`. Enriched field: list rows only."
+    guardrailCount:
+      type: integer
+      minimum: 0
+      description: "Number of guardrail metrics. Enriched field: list rows only."
+    primaryLiftPct:
+      anyOf:
+        - type: number
+        - type: "null"
+      description: "Goal-metric lift of the leading variant vs. control, in percent, or `null` when not yet computed. Enriched field: list rows only."
+    significancePct:
+      anyOf:
+        - type: number
+        - type: "null"
+      description: "Statistical significance (1 − p) as a percent, or `null` when not yet computed. Enriched field: list rows only."
+    sampleSize:
+      anyOf:
+        - type: integer
+        - type: "null"
+      description: "Total distinct units analysed, or `null` when not yet computed. Enriched field: list rows only."
+    exposure:
+      type: array
+      items:
+        type: object
+        properties:
+          ds:
+            type: string
+          value:
+            type: number
+        required:
+          - ds
+          - value
+        additionalProperties: false
+      description: "Cumulative unique-users-enrolled series for the exposure sparkline. Enriched field: list rows only."
+    exposureTotal:
+      anyOf:
+        - type: integer
+        - type: "null"
+      description: "Total distinct units ever exposed (sparkline headline), or `null`. Enriched field: list rows only."
+  required:
+    - id
+    - name
+    - description
+    - hypothesis
+    - tag
+    - ownerEmail
+    - audience
+    - bucketBy
+    - folder
+    - status
+    - universe
+    - targetingGate
+    - holdoutGate
+    - allocationPct
+    - reservedHeadroom
+    - hashVersion
+    - poolOffsetBp
+    - poolSizeBp
+    - salt
+    - params
+    - groups
+    - significanceThreshold
+    - minRuntimeDays
+    - minSampleSize
+    - sequentialTesting
+    - startedAt
+    - stoppedAt
+    - updatedAt
+    - version
+  additionalProperties: false