@shipeasy/openapi 3.1.0 → 3.2.0

package/spec/paths/gates.yaml

@@ -601,3 +601,285 @@
       name: activity
       positional:
         - id
+/api/admin/gates/{id}/whitelist:
+  get:
+    operationId: getGateWhitelist
+    summary: Read a gate's whitelist
+    description: |-
+      Returns the gate's whitelist — the always-first allowlist that admits the listed identities before any targeting rule or percentage rollout is evaluated.
+
+      A gate with no whitelist returns `entries: []` (and the default `attr`), never a 404 — so a caller can read-then-write without special-casing the empty gate.
+
+      **Use case:** Check whether an account is already let through before adding it.
+    tags:
+      - Flags
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque gate id (`gate_…`) or the gate's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: Read a gate's whitelist
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/gates.yaml#/GetGateWhitelistResponse
+            example:
+              id: gate_01j7w8a1b2c3d4e5f6g7h8i9j0
+              name: new_checkout
+              attr: email
+              entries:
+                - alice@acme.dev
+                - bob@acme.dev
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+    x-cli:
+      name: whitelist
+      positional:
+        - id
+  put:
+    operationId: setGateWhitelist
+    summary: Replace a gate's whitelist
+    description: |-
+      Replaces the gate's whole whitelist with `entries`, creating the block if the gate didn't have one. Idempotent — the same call twice leaves the same list.
+
+      This is the only whitelist call that can switch `attr` (`email` ⇄ `user_id`) or clear the block: `entries: []` removes the whitelist from the gate entirely.
+
+      **Use cases**
+
+      - **Pin an exact list** — `{ "entries": ["alice@acme.dev", "bob@acme.dev"] }`.
+      - **Switch to user ids** — `{ "attr": "user_id", "entries": ["usr_123"] }`.
+      - **Drop the whitelist** — `{ "entries": [] }`.
+    tags:
+      - Flags
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque gate id (`gate_…`) or the gate's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/gates.yaml#/SetGateWhitelistRequest
+          examples:
+            pinList:
+              summary: Pin an exact list of emails
+              value:
+                entries:
+                  - alice@acme.dev
+                  - bob@acme.dev
+            switchToUserIds:
+              summary: Re-key the whitelist onto user ids
+              description: Switching `attr` replaces the entries wholesale — the old emails are not translated.
+              value:
+                attr: user_id
+                entries:
+                  - usr_01j7w8a1b2c3d4e5f6g7h8i9j0
+            clear:
+              summary: Remove the whitelist
+              description: An empty list drops the pinned block from the gate's stack.
+              value:
+                entries: []
+    responses:
+      "200":
+        description: Replace a gate's whitelist
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/gates.yaml#/SetGateWhitelistResponse
+            example:
+              id: gate_01j7w8a1b2c3d4e5f6g7h8i9j0
+              name: new_checkout
+              attr: email
+              entries:
+                - alice@acme.dev
+                - bob@acme.dev
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: whitelist-set
+      positional:
+        - id
+  post:
+    operationId: addToGateWhitelist
+    summary: Add entries to a gate's whitelist
+    description: |-
+      Adds identities to the gate's whitelist, creating the block if the gate doesn't have one yet. Entries already on the list are skipped, so the call is idempotent and safe to retry.
+
+      Adding to a gate that already has a whitelist keyed on the other attribute is rejected (409) rather than silently re-keying the entries already there — use `PUT` to switch `attr` deliberately.
+
+      **Use case:** Let one more customer into a private beta without reading the current list first.
+    tags:
+      - Flags
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque gate id (`gate_…`) or the gate's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/gates.yaml#/AddToGateWhitelistRequest
+          examples:
+            addOne:
+              summary: Admit one more email
+              value:
+                entries:
+                  - carol@acme.dev
+            createOnUserIds:
+              summary: Start a whitelist keyed on user ids
+              description: "`attr` is honoured only because this gate has no whitelist yet."
+              value:
+                attr: user_id
+                entries:
+                  - usr_01j7w8a1b2c3d4e5f6g7h8i9j0
+    responses:
+      "200":
+        description: Add entries to a gate's whitelist
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/gates.yaml#/AddToGateWhitelistResponse
+            example:
+              id: gate_01j7w8a1b2c3d4e5f6g7h8i9j0
+              name: new_checkout
+              attr: email
+              entries:
+                - alice@acme.dev
+                - bob@acme.dev
+                - carol@acme.dev
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - IMMUTABLE_FIELD
+      - VALIDATION
+    x-cli:
+      name: whitelist-add
+      positional:
+        - id
+  delete:
+    operationId: removeFromGateWhitelist
+    summary: Remove entries from a gate's whitelist
+    description: |-
+      Removes identities from the gate's whitelist. Entries that aren't on the list are skipped, so the call is idempotent.
+
+      Removing the last entry leaves an empty whitelist block in place; to drop the block itself use `PUT` with `entries: []`.
+
+      **Use case:** Revoke one beta tester's access without touching anyone else's.
+    tags:
+      - Flags
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque gate id (`gate_…`) or the gate's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/gates.yaml#/RemoveFromGateWhitelistRequest
+          examples:
+            removeOne:
+              summary: Revoke one email
+              value:
+                entries:
+                  - carol@acme.dev
+    responses:
+      "200":
+        description: Remove entries from a gate's whitelist
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/gates.yaml#/RemoveFromGateWhitelistResponse
+            example:
+              id: gate_01j7w8a1b2c3d4e5f6g7h8i9j0
+              name: new_checkout
+              attr: email
+              entries:
+                - alice@acme.dev
+                - bob@acme.dev
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: whitelist-remove
+      positional:
+        - id

package/spec/paths/killswitches.yaml

@@ -579,3 +579,99 @@
       name: set-value
       positional:
         - id
+/api/admin/killswitches/{id}/toggle:
+  post:
+    operationId: toggleKillswitch
+    summary: Toggle a killswitch or one of its switches
+    description: |-
+      Flips a killswitch on one environment and publishes a new version there. This is the one-call incident verb: it reads the current value, flips it, and publishes, so you don't have to fetch the killswitch first.
+
+      Every body field is optional, which is what makes the call widen cleanly:
+
+      - **Flip the killswitch** — `{}`. Flips the flat `value` on `prod`.
+      - **Flip one sub-switch** — `{ "switchKey": "eu_region" }`. Flips that entry on `prod`, creating it (from `false`) if it isn't in the map yet.
+      - **Set it idempotently** — `{ "switchKey": "eu_region", "value": true }`. Publishes exactly that value, so a retried call can't undo the first one. A `null` `value` means "flip", not "set to null".
+      - **Choose the environment** — add `"env": "staging"`. Omitted, `env` is `prod`.
+
+      The response reports both `previous` and `value`, so a caller that asked for a flip can see what it actually changed.
+
+      Prefer this over `PUT /{id}/value` and `PUT /{id}/switch` unless you specifically need those endpoints' unconditional set semantics.
+    tags:
+      - Killswitch
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: false
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/killswitches.yaml#/ToggleKillswitchRequest
+          examples:
+            flipOnProd:
+              summary: Flip the killswitch on prod
+              description: No body fields — reads the flat `value` on prod and publishes its opposite.
+              value: {}
+            flipOneSwitch:
+              summary: Flip one sub-switch on prod
+              description: Flips `switches.eu_region` on prod, leaving the flat `value` and every other key alone.
+              value:
+                switchKey: eu_region
+            setOneSwitch:
+              summary: Trip one sub-switch idempotently
+              description: Publishes `switches.eu_region = true` on prod whatever it was before — safe to retry.
+              value:
+                switchKey: eu_region
+                value: true
+            setOneSwitchOnStaging:
+              summary: Trip one sub-switch on a chosen env
+              description: The same idempotent set, published on staging instead of prod.
+              value:
+                switchKey: eu_region
+                value: true
+                env: staging
+    responses:
+      "200":
+        description: Toggle a killswitch or one of its switches
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/killswitches.yaml#/ToggleKillswitchResponse
+            example:
+              id: ksw_01j7w9d8h2k4m6n8p0q2r4s6t8
+              env: prod
+              switchKey: eu_region
+              previous: false
+              value: true
+              version: 7
+              published:
+                value: false
+                switches:
+                  eu_region: true
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: toggle
+      positional:
+        - id

package/spec/paths/ops.yaml

@@ -180,6 +180,185 @@
           summary: File a feature request.
           preset:
             type: feature_request
+/ops/bug:
+  post:
+    operationId: createPublicBug
+    summary: File a bug
+    description: |-
+      Files one bug onto a project's queue, awaiting human approval. This is the **public** intake: it authenticates with a *client* SDK key rather than an admin key, so it can be called from a CLI, an installer script, a devtools overlay, or any shipped code — the same places a client key already lives.
+
+      Three gates decide whether a ticket is filed, and nothing else the caller sends can widen them:
+
+      1. the key is a `client` key carrying the `tickets:public_create` scope,
+      2. the key's project has public ticket creation enabled, and
+      3. the item is filed as `pending_approval` — parked out of the work queue until a human promotes it in the dashboard.
+
+      The project is the key's own project; there is no `X-Project-Id` to pass and no way to file into someone else's queue. Repeat submissions of the same title dedupe against the open ticket already tracking it, which returns `200` with `deduped: true` instead of filing again.
+
+      This endpoint is served by the Shipeasy **edge worker** (`api.shipeasy.ai`), not the admin API — see `servers` below.
+
+      **Use case:** `shipeasy setup` fails on a customer's machine and self-reports the failure with the user's consent — `{ "title": "Setup failed at Feature installs", "stepsToReproduce": "…", "actualResult": "…" }`.
+    tags:
+      - Ops
+    servers:
+      - url: https://api.shipeasy.ai
+        description: Shipeasy edge worker (production)
+      - url: http://localhost:8787
+        description: Local `wrangler dev`
+    security:
+      - clientSdkKey: []
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/ops.yaml#/CreatePublicBugRequest
+          examples:
+            minimal:
+              summary: Just a title
+              description: Every other field is optional — the queue triages from `open` at default priority.
+              value:
+                title: Checkout button misaligned on mobile
+            full:
+              summary: A full report
+              value:
+                title: Checkout button misaligned on mobile
+                stepsToReproduce: Open the cart on iOS Safari and tap the price row.
+                actualResult: The primary CTA overlaps the price.
+                expectedResult: The CTA sits below the price with clear spacing.
+                priority: high
+                reporterEmail: alice@acme.dev
+                pageUrl: https://acme.dev/cart
+    responses:
+      "200":
+        description: An open ticket already tracks this report; nothing was filed
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/CreatePublicTicketResponse
+            example:
+              number: 7
+              deduped: true
+      "201":
+        description: File a bug
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/CreatePublicTicketResponse
+            example:
+              id: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
+              number: 7
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "413":
+        $ref: ../components/responses.yaml#/PayloadTooLarge
+      "429":
+        $ref: ../components/responses.yaml#/TooManyRequests
+      "503":
+        $ref: ../components/responses.yaml#/ServiceUnavailable
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - VALIDATION
+    x-cli:
+      hidden: true
+      # Spec- and SDK-only. The generated CLI/MCP client resolves ONE base URL
+      # and ONE credential for the whole contract, so it cannot honour this
+      # operation's own `servers` (the edge worker) or its `clientSdkKey`
+      # security — it would POST to the admin host with an admin bearer and 404.
+      # Both surfaces are authenticated admin tools anyway: `shipeasy ops bug`
+      # and the `ops_bug` MCP tool file through `createOpsItem`, which lands an
+      # `open` item with the full field set rather than a `pending_approval` one.
+/ops/feature-request:
+  post:
+    operationId: createPublicFeatureRequest
+    summary: File a feature request
+    description: |-
+      Files one feature request onto a project's queue, awaiting human approval. The feature-request counterpart to `POST /ops/bug`, with the same three gates: a `client` key carrying `tickets:public_create`, a project that has opted in, and a `pending_approval` state forced server-side.
+
+      The project is the key's own project; there is no `X-Project-Id` to pass. Repeat submissions of the same title dedupe against the open ticket already tracking it, which returns `200` with `deduped: true` instead of filing again.
+
+      This endpoint is served by the Shipeasy **edge worker** (`api.shipeasy.ai`), not the admin API — see `servers` below.
+
+      **Use case:** An in-product "request a feature" form posts what the user asked for — `{ "title": "Dark mode", "useCase": "Reduce eye strain at night" }`.
+    tags:
+      - Ops
+    servers:
+      - url: https://api.shipeasy.ai
+        description: Shipeasy edge worker (production)
+      - url: http://localhost:8787
+        description: Local `wrangler dev`
+    security:
+      - clientSdkKey: []
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/ops.yaml#/CreatePublicFeatureRequestRequest
+          examples:
+            minimal:
+              summary: Just a title
+              value:
+                title: Dark mode for the dashboard
+            full:
+              summary: A full request
+              value:
+                title: Dark mode for the dashboard
+                description: Add a theme toggle that persists per user.
+                useCase: Reduce eye strain for users working at night.
+                priority: nice_to_have
+                reporterEmail: alice@acme.dev
+    responses:
+      "200":
+        description: An open ticket already tracks this report; nothing was filed
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/CreatePublicTicketResponse
+            example:
+              number: 7
+              deduped: true
+      "201":
+        description: File a feature request
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/CreatePublicTicketResponse
+            example:
+              id: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
+              number: 8
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "413":
+        $ref: ../components/responses.yaml#/PayloadTooLarge
+      "429":
+        $ref: ../components/responses.yaml#/TooManyRequests
+      "503":
+        $ref: ../components/responses.yaml#/ServiceUnavailable
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - VALIDATION
+    x-cli:
+      hidden: true
+      # Spec- and SDK-only. The generated CLI/MCP client resolves ONE base URL
+      # and ONE credential for the whole contract, so it cannot honour this
+      # operation's own `servers` (the edge worker) or its `clientSdkKey`
+      # security — it would POST to the admin host with an admin bearer and 404.
+      # Both surfaces are authenticated admin tools anyway: `shipeasy ops bug`
+      # and the `ops_bug` MCP tool file through `createOpsItem`, which lands an
+      # `open` item with the full field set rather than a `pending_approval` one.
 /api/admin/ops/{handle}:
   get:
     operationId: getOpsItem