@shipeasy/openapi 3.1.0 → 3.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/openapi",
-  "version": "3.1.0",
+  "version": "3.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",
@@ -40,17 +40,19 @@
       "default": "./src/codegen.ts"
     },
     "./openapi.yaml": "./openapi.yaml",
-    "./openapi.json": "./openapi.json"
+    "./openapi.json": "./openapi.json",
+    "./openapi-sdk.json": "./openapi-sdk.json"
   },
   "files": [
     "dist/",
     "openapi.yaml",
     "openapi.json",
+    "openapi-sdk.json",
     "spec/"
   ],
   "scripts": {
-    "lint:spec": "redocly lint spec/openapi.yaml",
-    "bundle": "redocly bundle spec/openapi.yaml -o openapi.yaml && redocly bundle spec/openapi.yaml -o openapi.json",
+    "lint:spec": "redocly lint spec/openapi.yaml && redocly lint spec/openapi-sdk.yaml",
+    "bundle": "redocly bundle spec/openapi.yaml -o openapi.yaml && redocly bundle spec/openapi.yaml -o openapi.json && redocly bundle spec/openapi-sdk.yaml -o openapi-sdk.json",
     "gen:sdk": "openapi-ts",
     "gen": "pnpm bundle && pnpm gen:sdk",
     "prebuild": "pnpm gen",

package/spec/components/responses.yaml

@@ -120,3 +120,42 @@ BadGateway:
           summary: Downstream provider dispatch failed
           value:
             error: "GitHub API responded 403: resource not accessible by integration."
+PayloadTooLarge:
+  description: The request body exceeded the intake's fixed size cap (16 KB).
+  content:
+    application/json:
+      schema:
+        $ref: ./errors.yaml#/Error
+      examples:
+        BAD_REQUEST:
+          summary: Body too large
+          value:
+            error: Body too large
+            code: BAD_REQUEST
+TooManyRequests:
+  description: |-
+    The public intake is rate-limited per (project, client IP). Back off and retry;
+    the limit is a burst guard, not a quota, so a modest delay clears it.
+  content:
+    application/json:
+      schema:
+        $ref: ./errors.yaml#/Error
+      examples:
+        BAD_REQUEST:
+          summary: Rate limited
+          value:
+            error: Too many requests
+            code: BAD_REQUEST
+ServiceUnavailable:
+  description: |-
+    A backing store the endpoint needs is not bound in this environment. Transient
+    and infrastructural — no stable `ErrorCode` is assigned, so `code` is omitted.
+  content:
+    application/json:
+      schema:
+        $ref: ./errors.yaml#/Error
+      examples:
+        UNAVAILABLE:
+          summary: Storage unbound
+          value:
+            error: Unavailable

package/spec/components/schemas/gates.yaml

@@ -980,3 +980,90 @@ ListGateActivityResponse:
       - createdAt
     additionalProperties: false
   description: Recent audit rows for one gate, newest first.
+GateWhitelistAttr:
+  type: string
+  enum:
+    - email
+    - user_id
+  description: Which identity attribute the whitelist matches on. `email` compares the caller's `email`; `user_id` compares the caller's `userID`. A whitelist matches on exactly one of the two at a time.
+GateWhitelist:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Resolved gate id.
+    name:
+      type: string
+      description: The gate's stable `name`.
+    attr:
+      $ref: "#/GateWhitelistAttr"
+    entries:
+      type: array
+      items:
+        type: string
+        minLength: 1
+      description: The whitelisted identities, in the order they are stored. Deduplicated case-sensitively; an empty array means the gate has no whitelist.
+  required:
+    - id
+    - name
+    - attr
+    - entries
+  additionalProperties: false
+  description: A gate's whitelist — the always-first allowlist that admits the listed identities before any targeting rule or rollout runs. Backed by the pinned `whitelist` entry at the head of the gate's `stack`, so it is the same list the dashboard's Whitelist block edits.
+SetGateWhitelistRequest:
+  type: object
+  properties:
+    attr:
+      anyOf:
+        - $ref: "#/GateWhitelistAttr"
+      description: Identity attribute to match on. Defaults to the whitelist's current attribute, or `email` when the gate has no whitelist yet.
+    entries:
+      type: array
+      items:
+        type: string
+        minLength: 1
+      description: The complete whitelist after the call. Pass `[]` to remove the whitelist from the gate entirely.
+  required:
+    - entries
+  additionalProperties: false
+  description: Body for `PUT /api/admin/gates/{id}/whitelist`. Replaces the whole list — idempotent, and the only call that can switch `attr` or clear the whitelist.
+AddToGateWhitelistRequest:
+  type: object
+  properties:
+    attr:
+      anyOf:
+        - $ref: "#/GateWhitelistAttr"
+      description: Identity attribute to match on. Only honoured when the gate has no whitelist yet (this call creates it); passing an attribute that disagrees with an existing whitelist is a 409 rather than a silent re-key of the entries already there.
+    entries:
+      type: array
+      minItems: 1
+      items:
+        type: string
+        minLength: 1
+      description: Identities to admit. Already-listed entries are skipped, so the call is idempotent.
+  required:
+    - entries
+  additionalProperties: false
+  description: Body for `POST /api/admin/gates/{id}/whitelist`. Adds entries to the whitelist, creating it if the gate doesn't have one.
+RemoveFromGateWhitelistRequest:
+  type: object
+  properties:
+    entries:
+      type: array
+      minItems: 1
+      items:
+        type: string
+        minLength: 1
+      description: Identities to stop admitting. Entries that aren't listed are skipped, so the call is idempotent.
+  required:
+    - entries
+  additionalProperties: false
+  description: "Body for `DELETE /api/admin/gates/{id}/whitelist`. Removes entries from the whitelist. Removing the last entry leaves an empty whitelist in place — use `PUT` with `entries: []` to drop the block itself."
+GetGateWhitelistResponse:
+  $ref: "#/GateWhitelist"
+SetGateWhitelistResponse:
+  $ref: "#/GateWhitelist"
+AddToGateWhitelistResponse:
+  $ref: "#/GateWhitelist"
+RemoveFromGateWhitelistResponse:
+  $ref: "#/GateWhitelist"

package/spec/components/schemas/keys.yaml

@@ -102,8 +102,8 @@ CreateKeyRequest:
     name:
       type: string
       minLength: 1
-      maxLength: 80
-      description: Optional human label. Programmatic (API) mints that omit it get an auto-generated descriptive name; dashboard mints may leave it blank.
+      maxLength: 160
+      description: "Optional human label. Programmatic (API) mints that omit it get an auto-generated descriptive name; dashboard mints may leave it blank. The cap is generous because provenance labels are composed, not typed — `shipeasy setup` mints keys named with the stack, package, date, and operator that produced them, which does not fit in a one-line-input budget."
     scopes:
       type: array
       items:

package/spec/components/schemas/killswitches.yaml

@@ -343,3 +343,67 @@ SetKillswitchValueResponse:
     - version
     - published
   additionalProperties: false
+ToggleKillswitchRequest:
+  type: object
+  properties:
+    switchKey:
+      anyOf:
+        - type: string
+          maxLength: 64
+          pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$
+        - type: "null"
+      description: Which target to flip. Omit (or `null`) to flip the killswitch's own flat `value`; name a switch key to flip that nested sub-switch instead, creating the entry if it doesn't exist yet.
+    value:
+      anyOf:
+        - type: boolean
+        - type: "null"
+      description: The value to publish. Omit (or `null`) to flip whatever is stored now — read-modify-write in one call. Pass an explicit `true`/`false` to make the call idempotent, so a retry can't undo the first attempt.
+    env:
+      anyOf:
+        - $ref: ./common.yaml#/Env
+      description: Environment to publish on. Defaults to `prod` — the environment an incident response means when it says "kill it".
+  additionalProperties: false
+  description: |-
+    Body for `POST /api/admin/killswitches/{id}/toggle`. Every field is optional, so the four useful calls read as one method with a widening argument list:
+
+    - `{}` — flip the flat value on prod.
+    - `{ "switchKey": "eu_region" }` — flip that sub-switch on prod.
+    - `{ "switchKey": "eu_region", "value": true }` — set that sub-switch on prod, idempotently.
+    - `{ "switchKey": "eu_region", "value": true, "env": "staging" }` — the same, on a chosen env.
+ToggleKillswitchResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Resolved killswitch id.
+    env:
+      $ref: ./common.yaml#/Env
+    switchKey:
+      anyOf:
+        - type: string
+          maxLength: 64
+          pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$
+        - type: "null"
+      description: The sub-switch that was flipped, or `null` when the flat `value` was.
+    previous:
+      type: boolean
+      description: The value that was in effect before this call. Equal to `value` when an idempotent `value` matched what was already stored.
+    value:
+      type: boolean
+      description: The value now in effect on `env`.
+    version:
+      type: integer
+      minimum: -9007199254740991
+      maximum: 9007199254740991
+      description: Newly published version on `env`.
+    published:
+      $ref: ./common.yaml#/KillswitchValue
+  required:
+    - id
+    - env
+    - switchKey
+    - previous
+    - value
+    - version
+    - published
+  additionalProperties: false

package/spec/components/schemas/ops.yaml

@@ -1063,6 +1063,175 @@ CreateFeatureRequestRequest:
     - title
   additionalProperties: false
   description: "Feature-request-kind fields for `POST /api/admin/ops` (sent with `type: feature_request`)."
+CreatePublicBugRequest:
+  type: object
+  properties:
+    title:
+      type: string
+      minLength: 1
+      maxLength: 200
+      pattern: '^\S(.*\S)?$'
+      description: One-line bug title (no leading/trailing whitespace).
+    stepsToReproduce:
+      type: string
+      maxLength: 8000
+      default: ""
+      description: How to reproduce the bug.
+    actualResult:
+      type: string
+      maxLength: 8000
+      default: ""
+      description: What actually happened.
+    expectedResult:
+      type: string
+      maxLength: 8000
+      default: ""
+      description: What was expected instead.
+    priority:
+      anyOf:
+        - $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
+          format: email
+        - type: "null"
+      description: Email of the reporter, or `null`.
+    pageUrl:
+      anyOf:
+        - type: string
+          format: uri
+        - type: "null"
+      description: URL of the page the bug relates to, or `null`.
+    userAgent:
+      anyOf:
+        - type: string
+          maxLength: 500
+        - type: "null"
+      description: Reporter's user-agent string, or `null`.
+    viewport:
+      anyOf:
+        - type: string
+          maxLength: 40
+        - type: "null"
+      description: Reporter's viewport (e.g. `1280x720`), or `null`.
+    context:
+      anyOf:
+        - type: object
+          additionalProperties: {}
+        - type: "null"
+      description: Arbitrary capture context, or `null`.
+    notify:
+      anyOf:
+        - $ref: ./common.yaml#/NotificationTarget
+        - type: "null"
+      description: Where this bug's completion notification lands.
+  required:
+    - title
+  additionalProperties: false
+  description: "Body for `POST /ops/bug`. The same bug fields as `CreateBugRequest`, minus the `type` discriminator — the path already says what is being filed."
+CreatePublicFeatureRequestRequest:
+  type: object
+  properties:
+    title:
+      type: string
+      minLength: 1
+      maxLength: 200
+      pattern: '^\S(.*\S)?$'
+      description: One-line feature-request title (no leading/trailing whitespace).
+    description:
+      type: string
+      maxLength: 8000
+      default: ""
+      description: What the feature is.
+    useCase:
+      type: string
+      maxLength: 8000
+      default: ""
+      description: Why it's needed / the use case.
+    priority:
+      anyOf:
+        - $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
+          format: email
+        - type: "null"
+      description: Email of the reporter, or `null`.
+    pageUrl:
+      anyOf:
+        - type: string
+          format: uri
+        - type: "null"
+      description: URL of the page the request relates to, or `null`.
+    userAgent:
+      anyOf:
+        - type: string
+          maxLength: 500
+        - type: "null"
+      description: Reporter's user-agent string, or `null`.
+    context:
+      anyOf:
+        - type: object
+          additionalProperties: {}
+        - type: "null"
+      description: Arbitrary capture context, or `null`.
+    notify:
+      anyOf:
+        - $ref: ./common.yaml#/NotificationTarget
+        - type: "null"
+      description: Where this request's completion notification lands.
+  required:
+    - title
+  additionalProperties: false
+  description: "Body for `POST /ops/feature-request`. The same feature-request fields as `CreateFeatureRequestRequest`, minus the `type` discriminator — the path already says what is being filed."
 CreateOpsItemRequest:
   oneOf:
     - $ref: "#/CreateBugRequest"
@@ -1073,6 +1242,22 @@ CreateOpsItemRequest:
       bug: "#/CreateBugRequest"
       feature_request: "#/CreateFeatureRequestRequest"
   description: "Body for `POST /api/admin/ops`. A discriminated union on `type`: `bug` carries the bug fields, `feature_request` the feature fields. Only these two user-fileable types are accepted — `error`, `alert`, and `measure_plan` tickets are auto-filed by the platform and cannot be created over the API."
+CreatePublicTicketResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: The new item's id. Absent on a deduped response — nothing was created, so there is no new id to report.
+    number:
+      type: integer
+      description: Per-project item number. On a deduped response this is the number of the OPEN ticket already tracking the report, which is what a caller should show the user either way.
+    deduped:
+      type: boolean
+      description: "`true` when an open ticket already tracked this report and nothing was filed (HTTP 200). Absent on a fresh file (HTTP 201)."
+  required:
+    - number
+  additionalProperties: false
+  description: "Response for the public ticket intake. A fresh file returns `201` with `id` + `number`; a repeat of a report already tracked by an open ticket returns `200` with that ticket's `number` and `deduped: true`."
 CreateOpsItemResponse:
   type: object
   properties:

package/spec/openapi-sdk.yaml

@@ -0,0 +1,86 @@
+# The SERVER-SDK surface of the admin API — a second root over the same
+# `paths/` and `components/schemas/` tree that `openapi.yaml` bundles.
+#
+# WHY A SECOND ROOT. The CLI and MCP consume the FULL spec (127 operations);
+# the published server SDKs ship a deliberately tiny opt-in `AdminClient`, and
+# vendoring the whole contract into eight repos bloated each generated client
+# into the megabytes for operations nobody called. This file IS that smaller
+# contract, declared rather than derived: `paths` below lists exactly the
+# operations the SDKs expose, and `redocly bundle` pulls in only the schemas
+# those operations transitively reference.
+#
+# WHY IT'S EXACT. Every path listed here is a dedicated, single-purpose route,
+# so a path item never drags in a method the SDK shouldn't have. That is the
+# reason the SDK-facing endpoints were built as their own paths instead of
+# extra query/discriminator modes on the generic CRUD routes.
+#
+# ADDING AN OPERATION is one `$ref` here — then `pnpm gen` in this package and
+# `pnpm sdk:spec:regen` in the monorepo, and commit the regenerated client
+# inside each SDK submodule. A monorepo pre-commit hook blocks any commit that
+# changes this contract while a vendored copy is stale.
+#
+# DELIBERATELY ABSENT, so nobody re-adds them by accident: everything else.
+# Listing, generic CRUD, key minting, projects, connectors, i18n, errors,
+# alerts, metrics, events, experiments, universes, templates, attributes, and
+# the AI-agent working seam (ack / link-pr / investigations) all stay reachable
+# through the CLI and MCP, which read `openapi.yaml`.
+openapi: 3.2.0
+info:
+  title: Shipeasy Admin API (server-SDK surface)
+  version: 2.0.0
+  description: |-
+    The slice of the Shipeasy admin API that the published server SDKs expose as their optional `AdminClient`. Authenticate with an admin SDK key (`Authorization: Bearer sdk_admin_…`) and scope every request to a project via the `X-Project-Id` header.
+
+    Three capabilities, nothing else:
+
+    - **File a public ticket** — a bug or a feature request onto the project's ops queue.
+    - **Toggle a kill switch** — flip the switch itself, or one of its named sub-switches, on one environment.
+    - **Manage a flag's whitelist** — read, replace, add to, or remove from the allowlist that admits specific identities ahead of every targeting rule.
+
+    Everything else in the admin API is reachable through the Shipeasy CLI and MCP server, which speak the complete contract (`openapi.yaml`).
+  contact:
+    name: Shipeasy
+    url: https://shipeasy.ai
+  license:
+    name: Proprietary
+    identifier: LicenseRef-Proprietary
+servers:
+  - url: https://shipeasy.ai
+    description: Production
+  - url: http://localhost:3000
+    description: Local Next.js dev server
+security:
+  - bearerSdkKey: []
+tags:
+  - name: Flags
+    description: A feature gate's whitelist — the always-first allowlist that admits named identities before any targeting rule or percentage rollout runs.
+  - name: Killswitch
+    description: Per-env boolean overrides for incident response. `toggle` reads the current value and publishes its opposite in one call, on the flat value or on one named sub-switch.
+  - name: Ops
+    description: The public ticket queue — filing a bug or a feature request, which also fires the project's GitHub/Slack connectors.
+paths:
+  /ops/bug:
+    $ref: ./paths/ops.yaml#/~1ops~1bug
+  /ops/feature-request:
+    $ref: ./paths/ops.yaml#/~1ops~1feature-request
+  /api/admin/killswitches/{id}/toggle:
+    $ref: ./paths/killswitches.yaml#/~1api~1admin~1killswitches~1{id}~1toggle
+  /api/admin/gates/{id}/whitelist:
+    $ref: ./paths/gates.yaml#/~1api~1admin~1gates~1{id}~1whitelist
+components:
+  securitySchemes:
+    bearerSdkKey:
+      type: http
+      scheme: bearer
+      bearerFormat: sdk_admin_*
+      description: 'Pass an admin SDK key as `Authorization: Bearer sdk_admin_…`. Mint via `POST /api/admin/keys` with `type: "admin"`.'
+    clientSdkKey:
+      type: apiKey
+      in: header
+      name: X-SDK-Key
+      description: |-
+        Pass a **client** SDK key as `X-SDK-Key: sdk_client_…`. Used only by the public ticket intake (`POST /ops/bug`, `POST /ops/feature-request`), which is served by the edge worker rather than the admin API.
+
+        Client keys are designed to be embedded in shipped code — a CLI, an installer, a browser bundle — so presenting one here is safe by construction: it can do nothing but file a rate-limited ticket into its own project, in a state a human must approve. It carries no read access and cannot reach any other operation in this contract.
+
+        The key must additionally carry the `tickets:public_create` scope, and its project must have public ticket creation enabled.

package/spec/openapi.yaml

@@ -282,6 +282,8 @@ paths:
     $ref: ./paths/gates.yaml#/~1api~1admin~1gates~1{id}~1disable
   /api/admin/gates/{id}/activity:
     $ref: ./paths/gates.yaml#/~1api~1admin~1gates~1{id}~1activity
+  /api/admin/gates/{id}/whitelist:
+    $ref: ./paths/gates.yaml#/~1api~1admin~1gates~1{id}~1whitelist
   /api/admin/experiments:
     $ref: ./paths/experiments.yaml#/~1api~1admin~1experiments
   /api/admin/experiments/{id}:
@@ -322,6 +324,8 @@ paths:
     $ref: ./paths/killswitches.yaml#/~1api~1admin~1killswitches~1{id}~1switch
   /api/admin/killswitches/{id}/value:
     $ref: ./paths/killswitches.yaml#/~1api~1admin~1killswitches~1{id}~1value
+  /api/admin/killswitches/{id}/toggle:
+    $ref: ./paths/killswitches.yaml#/~1api~1admin~1killswitches~1{id}~1toggle
   /api/admin/universes:
     $ref: ./paths/universes.yaml#/~1api~1admin~1universes
   /api/admin/universes/{id}:
@@ -352,6 +356,10 @@ paths:
     $ref: ./paths/events.yaml#/~1api~1admin~1events~1{id}~1approve
   /api/admin/ops:
     $ref: ./paths/ops.yaml#/~1api~1admin~1ops
+  /ops/bug:
+    $ref: ./paths/ops.yaml#/~1ops~1bug
+  /ops/feature-request:
+    $ref: ./paths/ops.yaml#/~1ops~1feature-request
   /api/admin/ops/{handle}:
     $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}
   /api/admin/ops/{handle}/link-pr:
@@ -437,3 +445,13 @@ components:
       scheme: bearer
       bearerFormat: sdk_admin_*
       description: 'Pass an admin SDK key as `Authorization: Bearer sdk_admin_…`. Mint via `POST /api/admin/keys` with `type: "admin"`.'
+    clientSdkKey:
+      type: apiKey
+      in: header
+      name: X-SDK-Key
+      description: |-
+        Pass a **client** SDK key as `X-SDK-Key: sdk_client_…`. Used only by the public ticket intake (`POST /ops/bug`, `POST /ops/feature-request`), which is served by the edge worker rather than the admin API.
+
+        Client keys are designed to be embedded in shipped code — a CLI, an installer, a browser bundle — so presenting one here is safe by construction: it can do nothing but file a rate-limited ticket into its own project, in a state a human must approve. It carries no read access and cannot reach any other operation in this contract.
+
+        The key must additionally carry the `tickets:public_create` scope, and its project must have public ticket creation enabled.