@shipeasy/openapi 1.6.0 → 2.1.0

package/spec/paths/ops.yaml

@@ -0,0 +1,446 @@
+/api/admin/ops:
+  get:
+    operationId: listOpsItems
+    summary: List the operational queue
+    description: |-
+      Returns the unified ops queue (bugs, feature requests, errors, alerts) in work order — highest priority first, oldest first within a priority — so consumers work it top-down. Filter by `type` and/or `status`, and cap with `limit`. Human-gated holding states (items awaiting human sign-off in the dashboard) are never returned by `all`/default status.
+
+      **Use case:** Pull the open queue to triage — e.g. every `bug` still `open` — before working items down one by one.
+    tags:
+      - Ops
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: type
+        in: query
+        required: false
+        description: Filter by item type (`bug`/`feature_request`/`error`/`alert`), or `all`.
+        schema:
+          anyOf:
+            - type: string
+              enum:
+                - bug
+                - feature_request
+                - error
+                - alert
+              description: Queue item type. `bug` and `feature_request` are user-fileable; `error` and `alert` tickets are auto-filed by the platform.
+            - type: string
+              const: all
+      - name: status
+        in: query
+        required: false
+        description: >-
+          Filter by lifecycle status, or `all`. The human-gated holding states
+          (`pending_approval`, `triage`) are excluded from `all`/default and
+          returned only when requested as the exact status.
+        schema:
+          anyOf:
+            - $ref: ../components/schemas/ops.yaml#/OpsItemStatus
+            - type: string
+              const: all
+      - name: limit
+        in: query
+        required: false
+        description: Max items to return (1–500).
+        schema:
+          type: integer
+          minimum: 1
+          maximum: 500
+    responses:
+      "200":
+        description: List the operational queue
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/ListOpsItemsResponse
+            example:
+              - id: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
+                number: 7
+                type: bug
+                title: Checkout button misaligned on mobile
+                status: open
+                priority: high
+                createdAt: 2026-06-20T09:14:08.000Z
+      "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
+    x-cli:
+      name: list
+  post:
+    operationId: createOpsItem
+    summary: File a queue item
+    description: |-
+      Files one queue item — a bug report or a feature request — and fires the project's connectors (GitHub issue / Slack). `type` selects which; only the two user-fileable types are accepted (`error`/`alert` tickets are auto-filed by the platform). Returns the new id and per-project number.
+
+      **Use cases**
+
+      - **File a bug** — `{ "type": "bug", "title": "Checkout 500s on Safari", "stepsToReproduce": "…" }`.
+      - **File a feature request** — `{ "type": "feature_request", "title": "Dark mode", "priority": "nice_to_have" }`.
+    tags:
+      - Ops
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/ops.yaml#/CreateOpsItemRequest
+          examples:
+            bug:
+              summary: File a bug report
+              value:
+                type: bug
+                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
+            featureRequest:
+              summary: File a feature request
+              value:
+                type: feature_request
+                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
+    responses:
+      "201":
+        description: File a queue item
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/CreateOpsItemResponse
+            example:
+              id: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
+              number: 7
+      "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
+      - ALREADY_EXISTS
+      - VALIDATION
+    x-cli:
+      name: create
+      positional:
+        - title
+      commands:
+        - name: create
+          summary: File a queue item (bug or feature request) — pass --type.
+        - name: bug
+          summary: File a bug report.
+          preset:
+            type: bug
+        - name: feature
+          summary: File a feature request.
+          preset:
+            type: feature_request
+/api/admin/ops/{handle}:
+  get:
+    operationId: getOpsItem
+    summary: Get one queue item
+    description: |-
+      Fetch a single queue item by its per-project `number` or full id.
+
+      **Use case:** Inspect one item's full detail before updating its status or linking a PR.
+    tags:
+      - Ops
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: handle
+        in: path
+        required: true
+        description: Per-project item number (e.g. `7`) or the full ops item id.
+        schema:
+          type: string
+    responses:
+      "200":
+        description: Get one queue item
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/GetOpsItemResponse
+            example:
+              id: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
+              number: 7
+              type: bug
+              title: Checkout button misaligned on mobile
+              status: open
+              priority: high
+              createdAt: 2026-06-20T09:14:08.000Z
+      "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: get
+      positional:
+        - handle
+  patch:
+    operationId: updateOpsItem
+    summary: Update a queue item
+    description: |-
+      Update a queue item. The body is validated against the item's stored type: a `bug` accepts its content fields (title, steps-to-reproduce, actual/expected result) plus `status`/`priority`/`notify` and a GitHub PR link; a `feature_request` its content (title, description, use-case) plus the same triage fields; `error`/`alert`/`measure_plan` accept `status`/`priority`/`notify` only (their content is platform-owned). Pass at least one field.
+
+      Completing an `error` ticket (status `resolved` or `ready_for_qa`) also resolves the tracked error it links to; the error reopens automatically if it recurs — so completing is safe pre-deploy.
+
+      **Use cases**
+
+      - **Start working an item** — `{ "status": "in_progress" }`.
+      - **Hand off for review** — `{ "status": "ready_for_qa" }` once the fix landed (the mode PR-based loops use).
+      - **Triage** — `{ "priority": "high" }`, content edits on bug/feature items.
+    tags:
+      - Ops
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: handle
+        in: path
+        required: true
+        description: Per-project item number (e.g. `7`) or the full ops item id.
+        schema:
+          type: string
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/ops.yaml#/UpdateOpsItemRequest
+          examples:
+            startWork:
+              summary: Flip an item to in_progress when starting it
+              value:
+                status: in_progress
+            handOff:
+              summary: Hand a fixed item off for human review
+              value:
+                status: ready_for_qa
+            triage:
+              summary: Set priority while triaging
+              value:
+                priority: high
+    responses:
+      "200":
+        description: Update a queue item
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/UpdateOpsItemResponse
+            example:
+              id: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
+      "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: update
+      positional:
+        - handle
+/api/admin/ops/{handle}/link-pr:
+  post:
+    operationId: linkPrToOpsItem
+    summary: Link a fixing PR
+    description: |-
+      Record the pull request that fixes a queue item (and clears the link with `prNumber: null`).
+
+      **Use case:** Tie the fixing PR to the item so closing the PR can flip it to ready_for_qa.
+    tags:
+      - Ops
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: handle
+        in: path
+        required: true
+        description: Per-project item number (e.g. `7`) or the full ops item id.
+        schema:
+          type: string
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/ops.yaml#/LinkPrToOpsItemRequest
+          example:
+            prNumber: 412
+            prUrl: https://github.com/acme/app/pull/412
+    responses:
+      "200":
+        description: Link a fixing PR
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/LinkPrToOpsItemResponse
+            example:
+              id: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
+      "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: link-pr
+      positional:
+        - handle
+/api/admin/notifications:
+  post:
+    operationId: notifyOps
+    summary: Raise an attention notification
+    description: |-
+      Raise a 'needs your attention' bell notification. Create-only and idempotent on `dedupeKey` — re-raising with the same key updates the one card instead of stacking duplicates. It never reads, marks read, or deletes the feed, so it is safe for restricted ops keys.
+
+      **Use case:** Escalate work that can't land in code (a product decision, a credential only a human has, a resource only a human may edit), deduped so repeats don't spam the bell.
+    tags:
+      - Ops
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/ops.yaml#/NotifyOpsRequest
+          example:
+            title: "Alert rule @alert:checkout-error-rate needs a human edit for #42"
+            summary: "#42 is a false positive — the rule fires on the expected nightly batch spike, and rule definitions can only be edited by a human."
+            steps:
+              - "Open @alert:checkout-error-rate in the dashboard alerts page."
+              - "Raise the threshold from `2%` to `5%` and widen the window to `1h`."
+              - "Re-run the shipeasy-ops-work loop — #42 will be acknowledged."
+            dedupeKey: feedback:42
+            href: /dashboard/prj_0abc/bugs/42
+    responses:
+      "201":
+        description: Raise an attention notification
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/NotifyOpsResponse
+            example:
+              dedupeKey: error:checkout:5xx
+              dispatched: 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
+      - VALIDATION
+    x-cli:
+      name: notify
+/api/admin/slack/channels:
+  get:
+    operationId: listSlackChannels
+    summary: List Slack channels
+    description: |-
+      List the project's connected Slack channels — used to resolve an alert rule's notification target.
+
+      **Use case:** Populate a channel picker, or validate an alert rule's `--slack-channel` before saving.
+    tags:
+      - Alerts
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    responses:
+      "200":
+        description: List Slack channels
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/ListSlackChannelsResponse
+            example:
+              connected: true
+              channels:
+                - id: C0123
+                  name: alerts
+                - id: C0456
+                  name: general
+      "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
+    x-cli:
+      name: channels

package/spec/paths/projects.yaml

@@ -0,0 +1,210 @@
+/api/admin/projects/current:
+  get:
+    operationId: getCurrentProject
+    summary: Show the current project
+    description: |-
+      Returns the project the caller's auth header resolves to — plan, status, billing, and which modules are enabled. The server reads the project from the credential, so there is no id parameter. Powers `whoami`.
+
+      **Use case:** Resolve who you are — the project, plan, and enabled modules tied to the current credential — without passing an id. Backs a registry-driven `whoami`.
+    tags:
+      - Projects
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    responses:
+      "200":
+        description: Show the current project
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/projects.yaml#/GetCurrentProjectResponse
+            example:
+              id: f81d4fae-7dec-11d0-a765-00a0c91e6bf6
+              name: Acme
+              domain: acme.com
+              ownerEmail: owner@acme.com
+              plan: paid
+              status: active
+              subscriptionStatus: active
+              billingInterval: monthly
+              currentPeriodEnd: 2026-07-12T00:00:00.000Z
+              trialEndsAt: null
+              cancelAtPeriodEnd: 0
+              moduleTranslations: true
+              moduleConfigs: true
+              moduleGates: true
+              moduleExperiments: true
+              moduleFeedback: true
+              createdAt: 2026-04-12T10:14:08.000Z
+              updatedAt: 2026-06-12T08:01:55.000Z
+      "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
+    x-cli:
+      name: current
+      # Also surface this op as a top-level `whoami` command (CLI) / `whoami`
+      # tool (MCP) — the canonical identity lookup. The CLI/MCP generators emit
+      # an extra top-level entry that dispatches to the same operation.
+      topLevelAlias: whoami
+/api/admin/projects/upsert:
+  post:
+    operationId: upsertProject
+    summary: Find-or-create a project by domain
+    description: |-
+      Find-or-creates a project keyed by `(owner_email, domain)` under the session's owner, and returns it. Idempotent: a second call with the same domain returns the existing project with `created: false`.
+
+      Only `domain` is required — `name` defaults to the domain on first create. Recording the result in a local `.shipeasy` binding is a consumer side-effect; this endpoint never performs it.
+
+      **Use cases**
+
+      - **Install flow** — provision a per-app project without a trip to the dashboard. Run it on every install; the idempotent key means a re-run returns the existing project rather than duplicating it.
+      - **Name explicitly** — pass `name` to label the project distinctly from its `domain`.
+    tags:
+      - Projects
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/projects.yaml#/UpsertProjectRequest
+          examples:
+            minimal:
+              summary: Minimal — domain only
+              description: Smallest valid body. Names the project after the domain on first create.
+              value:
+                domain: acme.com
+            named:
+              summary: Named project
+              description: Supply a human-readable `name` distinct from the domain.
+              value:
+                domain: shouks.app
+                name: Shouks
+    responses:
+      "200":
+        description: Find-or-create a project by domain
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/projects.yaml#/UpsertProjectResponse
+            example:
+              id: f81d4fae-7dec-11d0-a765-00a0c91e6bf6
+              name: Acme
+              domain: acme.com
+              owner_email: owner@acme.com
+              created: 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
+      - VALIDATION
+    x-cli:
+      name: upsert
+/api/admin/projects/{id}:
+  patch:
+    operationId: updateProject
+    summary: Update the current project
+    description: |-
+      Update the current project's settings — name, domain, slug, default environment, timezone, experiment-analysis knobs (statistical method, significance threshold, auto-rollback, minimum sample days), and the per-module enable flags. Partial: only the fields you send change.
+
+      The project id in the path must match the project the caller's credential resolves to (a credential can only edit its own project). Changing `domain` re-stamps the allowed origin into every live SDK key.
+
+      **Use case:** Rename a project, move its domain, toggle a module on/off, or tune the experiment-analysis defaults without leaving the CLI.
+    tags:
+      - Projects
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque project id. Must match the caller's own project.
+        schema:
+          type: string
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/projects.yaml#/UpdateProjectRequest
+          examples:
+            rename:
+              summary: Rename the project
+              value:
+                name: Acme Rockets
+            toggleModule:
+              summary: Turn a module off
+              value:
+                moduleExperiments: false
+    responses:
+      "200":
+        description: The updated project.
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/projects.yaml#/GetCurrentProjectResponse
+            example:
+              id: f81d4fae-7dec-11d0-a765-00a0c91e6bf6
+              name: Acme Rockets
+              domain: acme.com
+              ownerEmail: owner@acme.com
+              plan: paid
+              status: active
+              subscriptionStatus: active
+              billingInterval: monthly
+              currentPeriodEnd: 2026-07-12T00:00:00.000Z
+              trialEndsAt: null
+              cancelAtPeriodEnd: 0
+              moduleTranslations: true
+              moduleConfigs: true
+              moduleGates: true
+              moduleExperiments: false
+              moduleFeedback: true
+              createdAt: 2026-04-12T10:14:08.000Z
+              updatedAt: 2026-06-12T08:01:55.000Z
+      "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: update
+      positional:
+        - id