@shipeasy/openapi 2.1.0 → 2.2.0

package/package.json

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

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/gate-templates.yaml

@@ -25,13 +25,52 @@ GateTemplateRule:
         - exp_in
       description: "Comparison operator. Equality: `eq`/`neq`. Set membership: `in`/`not_in` (value is an array). Numeric order: `gt`/`gte`/`lt`/`lte`. Semver order: `semver_gt`/`semver_gte`/`semver_lt`/`semver_lte`. String: `contains` (substring), `regex` (JS-flavour pattern). Cross-resource: `gate_pass` (value is another gate's name), `exp_in` (attr is an experiment name, value is a variant / `\"$holdout\"` / `\"$any\"`)."
     value:
-      description: 'Operand. Shape depends on `op`: scalar for `eq/neq/gt/gte/lt/lte/contains/semver_*`; array of scalars for `in/not_in`; string pattern for `regex`; referenced gate name for `gate_pass`; variant selector for `exp_in`.'
+      description: 'Operand. Shape depends on `op`: scalar for `eq/neq/gt/gte/lt/lte/contains/semver_*`; array of scalars for `in/not_in`; string pattern for `regex`; referenced gate name for `gate_pass`; variant selector for `exp_in`. Required on every request rule (value-ops need it; the valueless built-in presets are read-only and never created via the API).'
+      anyOf:
+        - type: string
+        - type: number
+        - type: boolean
+        - type: array
+          items: {}
   required:
     - attr
     - op
     - value
   additionalProperties: false
   description: Single targeting predicate. Copy a template's rules, substitute the concrete `value`(s), and pass them as the `rules` arg of `release_flags_create`.
+GateTemplateRuleResponse:
+  type: object
+  properties:
+    attr:
+      type: string
+      description: Attribute key on the evaluation context (e.g. `country`, `plan`, `email`). Matched case-sensitively against `Shipeasy.checkGate(user, name)` input. May be empty on a built-in template whose attribute is supplied at substitution time (e.g. the `exp_in` "in any experiment" preset — you fill in the experiment name).
+    op:
+      type: string
+      enum:
+        - eq
+        - neq
+        - in
+        - not_in
+        - gt
+        - gte
+        - lt
+        - lte
+        - contains
+        - regex
+        - semver_gt
+        - semver_gte
+        - semver_lt
+        - semver_lte
+        - gate_pass
+        - exp_in
+      description: "Comparison operator. Equality: `eq`/`neq`. Set membership: `in`/`not_in` (value is an array). Numeric order: `gt`/`gte`/`lt`/`lte`. Semver order: `semver_gt`/`semver_gte`/`semver_lt`/`semver_lte`. String: `contains` (substring), `regex` (JS-flavour pattern). Cross-resource: `gate_pass` (value is another gate's name), `exp_in` (attr is an experiment name, value is a variant / `\"$holdout\"` / `\"$any\"`)."
+    value:
+      description: 'Operand. Shape depends on `op`: scalar for `eq/neq/gt/gte/lt/lte/contains/semver_*`; array of scalars for `in/not_in`; string pattern for `regex`; referenced gate name for `gate_pass`; variant selector for `exp_in`.'
+  required:
+    - attr
+    - op
+  additionalProperties: false
+  description: Single targeting predicate as returned by the API. `value` is optional here — read-only built-in templates (e.g. `@owner`, or presets whose operand is supplied at substitution time) legitimately omit it. Request bodies still require `value`.
 GateTemplate:
   type: object
   description: "A reusable targeting-rule template. Built-ins are read-only (`builtin: true`, stable slug `id`); per-project customer templates are `builtin: false` with a `gtpl_…` id."
@@ -65,7 +104,7 @@ GateTemplate:
     rules:
       type: array
       items:
-        $ref: "#/GateTemplateRule"
+        $ref: "#/GateTemplateRuleResponse"
       description: The rule definition — copy, substitute the value(s), pass as `rules`.
     createdAt:
       anyOf:

package/spec/components/schemas/ops.yaml

@@ -946,8 +946,10 @@ NotifyOpsRequest:
       items:
         type: string
     href:
-      description: Dashboard-relative deep link to the related item.
-      type: string
+      description: Dashboard-relative deep link to the related item. `null` is accepted and treated as "no link".
+      anyOf:
+        - type: string
+        - type: "null"
     dedupeKey:
       description: Stable per-escalation key (e.g. `feedback:7`) so re-runs dedupe to one row.
       type: string

package/spec/openapi.yaml

@@ -21,9 +21,28 @@ security:
   - bearerSdkKey: []
 tags:
   - name: Release
-    summary: Feature delivery
+    summary: >-
+      Feature delivery — flags, kill switches, dynamic configs, A/B experiments,
+      and the universes they bucket in.
     kind: nav
-    description: Flags, kill switches, dynamic configs, experiments, and the universes they bucket in — the feature-delivery surface.
+    description: |-
+      Release: the feature-delivery surface. One roof over the five resources
+      that decide which code path a user gets — feature gates (flags), kill
+      switches, dynamic configs, A/B/n experiments, and the universes that bucket
+      them — each exposed as its own subcommand group.
+
+      **Groups.**
+      - `flags` — boolean feature gates: AND-combined targeting rules + a percentage rollout (basis points), evaluated on the SDK hot path.
+      - `killswitch` (`ks`) — per-env boolean overrides for incident response; no rules, no rollout, versioned per environment.
+      - `configs` — JSON-Schema-validated structured values with a draft → publish workflow, delivered per environment.
+      - `experiments` — randomised A/B/n assignment plus the analysis pipeline (t-test, sequential testing, SRM detection); `universes` hold the shared bucketing space and holdouts the experiments draw from.
+
+      **Delivery model.** Every write rebuilds the project's KV blob and purges
+      the CDN — SDKs poll at the plan interval and never touch the database on
+      the hot path. The destructive verb is `archive` (soft-delete), never
+      `delete`.
+
+      Run `shipeasy release <group> --help` for the full contract of each group.
   - name: Flags
     parent: Release
     description: |-

package/spec/paths/alert-rules.yaml

@@ -10,6 +10,7 @@
       - Alerts
     parameters:
       - $ref: ../components/parameters.yaml#/ProjectId
+      - $ref: ../components/parameters.yaml#/Q
     responses:
       "200":
         description: List alert rules
@@ -103,6 +104,13 @@
               $ref: ../components/schemas/alert-rules.yaml#/CreateAlertRuleResponse
             example:
               id: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
+        links:
+          UpdateAlertRule:
+            operationId: updateAlertRule
+            parameters: { id: $response.body#/id }
+          DeleteAlertRule:
+            operationId: deleteAlertRule
+            parameters: { id: $response.body#/id }
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":
@@ -146,7 +154,7 @@
         required: true
         description: Stable opaque alert-rule id (`ar_…`) or the rule's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -217,7 +225,7 @@
         required: true
         description: Stable opaque alert-rule id (`ar_…`) or the rule's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Delete an alert rule

package/spec/paths/attributes.yaml

@@ -10,6 +10,7 @@
       - Attributes
     parameters:
       - $ref: ../components/parameters.yaml#/ProjectId
+      - $ref: ../components/parameters.yaml#/Q
     responses:
       "200":
         description: List targeting attributes
@@ -76,6 +77,16 @@
             example:
               id: attr_01j7w8a1b2c3
               name: plan
+        links:
+          GetAttribute:
+            operationId: getAttribute
+            parameters: { id: $response.body#/id }
+          UpdateAttribute:
+            operationId: updateAttribute
+            parameters: { id: $response.body#/id }
+          DeleteAttribute:
+            operationId: deleteAttribute
+            parameters: { id: $response.body#/id }
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":
@@ -115,7 +126,7 @@
         required: true
         description: The attribute id.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Get a targeting attribute
@@ -169,7 +180,7 @@
         required: true
         description: The attribute id.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -228,7 +239,7 @@
         required: true
         description: The attribute id.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Archive a targeting attribute

package/spec/paths/configs.yaml

@@ -12,6 +12,7 @@
       - $ref: ../components/parameters.yaml#/ProjectId
       - $ref: ../components/parameters.yaml#/PaginationLimit
       - $ref: ../components/parameters.yaml#/PaginationCursor
+      - $ref: ../components/parameters.yaml#/Q
     responses:
       "200":
         description: List dynamic configs
@@ -160,6 +161,19 @@
             example:
               id: cfg_01j7wae5h6j7k8l9m0n1p2q3r4
               name: pricing.tiers
+        links:
+          GetConfig:
+            operationId: getConfig
+            parameters: { id: $response.body#/id }
+          UpdateConfig:
+            operationId: updateConfig
+            parameters: { id: $response.body#/id }
+          PublishConfigDraft:
+            operationId: publishConfigDraft
+            parameters: { id: $response.body#/id }
+          DeleteConfig:
+            operationId: deleteConfig
+            parameters: { id: $response.body#/id }
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":
@@ -199,7 +213,7 @@
         required: true
         description: Stable opaque config id (`cfg_…`) or the config's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Get one config
@@ -301,7 +315,7 @@
         required: true
         description: Stable opaque config id (`cfg_…`) or the config's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -377,7 +391,7 @@
         required: true
         description: Stable opaque config id (`cfg_…`) or the config's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Delete a dynamic config
@@ -427,7 +441,7 @@
         required: true
         description: Stable opaque config id (`cfg_…`) or the config's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -495,7 +509,7 @@
         required: true
         description: Stable opaque config id (`cfg_…`) or the config's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -557,7 +571,7 @@
         required: true
         description: Stable opaque config id (`cfg_…`) or the config's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -576,7 +590,7 @@
               value:
                 env: prod
     responses:
-      "201":
+      "200":
         description: Publish a draft
         content:
           application/json:
@@ -626,7 +640,7 @@
         required: true
         description: Stable opaque config id (`cfg_…`) or the config's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
       - name: limit
         in: query
         required: false
@@ -690,7 +704,7 @@
         required: true
         description: Stable opaque config id (`cfg_…`) or the config's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:

package/spec/paths/connectors.yaml

@@ -12,6 +12,7 @@
       - Connectors
     parameters:
       - $ref: ../components/parameters.yaml#/ProjectId
+      - $ref: ../components/parameters.yaml#/Q
     responses:
       "200":
         description: List connectors
@@ -130,6 +131,19 @@
               $ref: ../components/schemas/connectors.yaml#/CreateConnectorResponse
             example:
               id: 9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10
+        links:
+          GetConnector:
+            operationId: getConnector
+            parameters: { id: $response.body#/id }
+          UpdateConnector:
+            operationId: updateConnector
+            parameters: { id: $response.body#/id }
+          TestConnector:
+            operationId: testConnector
+            parameters: { id: $response.body#/id }
+          DeleteConnector:
+            operationId: deleteConnector
+            parameters: { id: $response.body#/id }
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":
@@ -165,7 +179,7 @@
         required: true
         description: Stable opaque connector id.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Get a connector
@@ -233,7 +247,7 @@
         required: true
         description: Stable opaque connector id.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -306,7 +320,7 @@
         required: true
         description: Stable opaque connector id.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Delete a connector
@@ -355,7 +369,7 @@
         required: true
         description: Stable opaque connector id.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: false
       content:
@@ -373,7 +387,7 @@
                 text: Triage only the P0 bugs reported in the last 24h.
     responses:
       "200":
-        description: Fire a trigger connector
+        description: The trigger run was successfully kicked off.
         content:
           application/json:
             schema:
@@ -392,6 +406,8 @@
         $ref: ../components/responses.yaml#/Conflict
       "422":
         $ref: ../components/responses.yaml#/UnprocessableEntity
+      "502":
+        $ref: ../components/responses.yaml#/BadGateway
     x-error-codes:
       - UNAUTHORIZED
       - FORBIDDEN
@@ -419,10 +435,10 @@
         required: true
         description: Stable opaque connector id.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
-        description: Test a connector
+        description: The test dispatch reached the destination.
         content:
           application/json:
             schema:
@@ -442,6 +458,8 @@
         $ref: ../components/responses.yaml#/Conflict
       "422":
         $ref: ../components/responses.yaml#/UnprocessableEntity
+      "502":
+        $ref: ../components/responses.yaml#/BadGateway
     x-error-codes:
       - UNAUTHORIZED
       - FORBIDDEN
@@ -471,7 +489,7 @@
         required: true
         description: Stable opaque connector id. Its stored `provider` must match the body's `provider`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -577,6 +595,22 @@
               $ref: ../components/schemas/connectors.yaml#/CreateConnectorResponse
             example:
               id: 9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10
+        links:
+          FireConnector:
+            operationId: fireConnector
+            parameters: { id: $response.body#/id }
+          TestConnector:
+            operationId: testConnector
+            parameters: { id: $response.body#/id }
+          GetConnector:
+            operationId: getConnector
+            parameters: { id: $response.body#/id }
+          UpdateTriggerConnector:
+            operationId: updateTriggerConnector
+            parameters: { id: $response.body#/id }
+          DeleteConnector:
+            operationId: deleteConnector
+            parameters: { id: $response.body#/id }
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":

package/spec/paths/errors.yaml

@@ -108,7 +108,7 @@
         required: true
         description: Stable opaque error id (`err_…`).
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Get a tracked error
@@ -183,7 +183,7 @@
         required: true
         description: Stable opaque error id (`err_…`).
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -272,7 +272,7 @@
         required: true
         description: Stable opaque error id (`err_…`).
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "201":
         description: File a feedback ticket for an error
@@ -320,7 +320,7 @@
         required: true
         description: Stable opaque error id (`err_…`).
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:

package/spec/paths/events.yaml

@@ -10,6 +10,7 @@
       - Events
     parameters:
       - $ref: ../components/parameters.yaml#/ProjectId
+      - $ref: ../components/parameters.yaml#/Q
     responses:
       "200":
         description: List events
@@ -95,6 +96,19 @@
             example:
               id: evt_01j7w8a1b2c3d4e5f6g7h8i9j0
               name: checkout_completed
+        links:
+          GetEvent:
+            operationId: getEvent
+            parameters: { id: $response.body#/id }
+          UpdateEvent:
+            operationId: updateEvent
+            parameters: { id: $response.body#/id }
+          ApproveEvent:
+            operationId: approveEvent
+            parameters: { id: $response.body#/id }
+          DeleteEvent:
+            operationId: deleteEvent
+            parameters: { id: $response.body#/id }
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":
@@ -134,7 +148,7 @@
         required: true
         description: Stable opaque event id (`evt_…`) or the event's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Get an event
@@ -193,7 +207,7 @@
         required: true
         description: Stable opaque event id (`evt_…`) or the event's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content:
@@ -261,7 +275,7 @@
         required: true
         description: Stable opaque event id (`evt_…`) or the event's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     responses:
       "200":
         description: Archive an event
@@ -312,7 +326,7 @@
         required: true
         description: Stable opaque event id (`evt_…`) or the event's `name`.
         schema:
-          type: string
+          $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
       required: true
       content: