@shipeasy/openapi 3.3.0 → 3.4.0

package/openapi.yaml

@@ -234,6 +234,17 @@ tags:
       run record with the answers in the prompt. `delivery: poll` (the default
       for a live, connector-less session such as Claude Code in a terminal)
       fires nothing — call `list` until the status reads `completed`.
+  - name: QA notes
+    parent: Ops
+    description: |-
+      Typed QA notes on a queue item — the QA follow-up that is not discussion.
+      Each note is one of four kinds: `narrowing` (only part of the bug still
+      fails), `clarification` (changes what "fixed" means), `verification` (a
+      `pass` / `fail` verdict on a fix) or `correction` (withdraws an earlier
+      framing). Notes are append-only, carry their author and time, and render in
+      their own section of the item's detail panel, separate from the comment
+      thread. A failing verification offers a "Reopen item" action in the
+      dashboard; it is always an explicit click, never a side effect of `create`.
   - name: Projects
     description: |-
       Projects: the account-level container every other resource is scoped to.
@@ -6642,6 +6653,132 @@ paths:
         positional:
           - handle
           - questionId
+  /api/admin/ops/{handle}/qa-notes:
+    get:
+      operationId: listOpsQaNotes
+      summary: List an item's QA notes
+      description: |-
+        The typed QA notes on a queue item, newest first (max 200) — narrowing,
+        clarification, verification and correction notes, each with its author and
+        time. They are separate from the comment thread: read these to learn the
+        CURRENT QA state of a ticket (what remains failing, what "fixed" now means,
+        the last verification verdict) without parsing prose comments.
+
+        **Use case:** A coding agent picks an item up and checks the latest
+        `verification` verdict and any `narrowing` note before touching the code.
+      tags:
+        - QA notes
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+        - name: handle
+          in: path
+          required: true
+          description: Per-project item number (e.g. `7`) or the full ops item id.
+          schema:
+            $ref: '#/components/schemas/ResourceId'
+        - name: kind
+          in: query
+          required: false
+          description: Only notes of this kind.
+          schema:
+            $ref: '#/components/schemas/OpsQaNoteKind'
+      responses:
+        '200':
+          description: List an item's QA notes
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListOpsQaNotesResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
+      x-error-codes:
+        - BAD_REQUEST
+        - UNAUTHORIZED
+        - FORBIDDEN
+        - NOT_FOUND
+      x-cli:
+        name: list
+        positional:
+          - handle
+    post:
+      operationId: createOpsQaNote
+      summary: Add a QA note to an item
+      description: |-
+        Append one typed QA note to a queue item. `kind` is `narrowing` (what now
+        passes vs what still fails), `clarification` (what "fixed" now means),
+        `verification` (requires a `verdict` of `pass` or `fail`, and `body` says
+        what was checked) or `correction` (withdraws an earlier framing). Notes
+        are append-only and appear in the item's QA notes section, not in the
+        comment thread. The author is the caller's identity; pass `agent` to
+        record the note as written by that agent type's QA automation. A `fail` verdict never changes the item's
+        status by itself: the dashboard offers an explicit "Reopen item" action,
+        and `ops update --status open` does the same from the CLI.
+
+        **Use case:** QA automation records "verified on production: FAIL, the
+        second facet still errors" as data an agent can read back.
+      tags:
+        - QA notes
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+        - name: handle
+          in: path
+          required: true
+          description: Per-project item number (e.g. `7`) or the full ops item id.
+          schema:
+            $ref: '#/components/schemas/ResourceId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateOpsQaNoteRequest'
+            examples:
+              verification:
+                summary: A failing verification
+                value:
+                  kind: verification
+                  verdict: fail
+                  body: Retested on production after the deploy — the export still drops the second sheet
+              narrowing:
+                summary: Narrow a bug to the facet that still fails
+                value:
+                  kind: narrowing
+                  body: The list view is fixed; only the detail panel still shows the stale count
+      responses:
+        '200':
+          description: The created note
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OpsQaNote'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
+      x-error-codes:
+        - BAD_REQUEST
+        - UNAUTHORIZED
+        - FORBIDDEN
+        - NOT_FOUND
+        - VALIDATION
+      x-cli:
+        name: create
+        positional:
+          - handle
   /api/admin/agent-profiles:
     get:
       operationId: listOpsAgents
@@ -17411,6 +17548,100 @@ components:
       additionalProperties: false
       minProperties: 1
       description: Body for `POST /api/admin/ops/{handle}/questions/{questionId}/answer` — pick option labels, write a free-text answer, or both (multi-select only).
+    OpsQaNoteKind:
+      type: string
+      enum:
+        - narrowing
+        - clarification
+        - verification
+        - correction
+      description: What a QA note is — `narrowing` (only part of the bug still fails), `clarification` (changes what "fixed" means), `verification` (a pass/fail verdict on a fix) or `correction` (withdraws an earlier framing).
+    OpsQaNoteVerdict:
+      type: string
+      enum:
+        - pass
+        - fail
+      description: The outcome a `verification` note records.
+    OpsQaNote:
+      type: object
+      properties:
+        id:
+          type: string
+          description: Note id.
+        feedbackId:
+          type: string
+          description: The queue item the note hangs off.
+        kind:
+          $ref: '#/components/schemas/OpsQaNoteKind'
+        verdict:
+          anyOf:
+            - $ref: '#/components/schemas/OpsQaNoteVerdict'
+            - type: 'null'
+          description: The pass/fail verdict of a `verification` note; `null` for every other kind.
+        body:
+          type: string
+          description: The note (markdown) — for a `verification`, what was checked.
+        authorEmail:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: Email of the person (or the key's actor) who wrote the note, or `null` when an agent wrote it.
+        authorAgent:
+          anyOf:
+            - type: string
+              enum:
+                - jarvis
+                - claude
+                - cursor
+                - copilot
+                - jules
+            - type: 'null'
+          description: The agent type that wrote the note (QA automation), or `null` for a person.
+        createdAt:
+          type: string
+          description: ISO-8601 creation timestamp.
+      required:
+        - id
+        - feedbackId
+        - kind
+        - verdict
+        - body
+        - authorEmail
+        - authorAgent
+        - createdAt
+      additionalProperties: false
+      description: One typed, append-only QA note on a queue item.
+    ListOpsQaNotesResponse:
+      type: array
+      items:
+        $ref: '#/components/schemas/OpsQaNote'
+      description: Response for `GET /api/admin/ops/{handle}/qa-notes` — the item's QA notes, newest first (max 200).
+    CreateOpsQaNoteRequest:
+      type: object
+      properties:
+        kind:
+          $ref: '#/components/schemas/OpsQaNoteKind'
+        body:
+          type: string
+          minLength: 1
+          maxLength: 10000
+          description: The note (markdown).
+        verdict:
+          $ref: '#/components/schemas/OpsQaNoteVerdict'
+        agent:
+          type: string
+          enum:
+            - jarvis
+            - claude
+            - cursor
+            - copilot
+            - jules
+          description: The agent type writing the note — pass your own type when you are QA automation. Omitted, the note is attributed to the caller's identity.
+      required:
+        - kind
+        - body
+      additionalProperties: false
+      description: Body for `POST /api/admin/ops/{handle}/qa-notes`. A `verification` note requires `verdict`; every other kind rejects it.
     OpsAgentProfile:
       type: object
       properties:
@@ -17625,6 +17856,38 @@ components:
         - op
         - rules
       additionalProperties: false
+    AlertRuleNotify:
+      anyOf:
+        - type: object
+          properties:
+            slackChannel:
+              anyOf:
+                - type: object
+                  properties:
+                    id:
+                      type: string
+                      minLength: 1
+                    name:
+                      type: string
+                      minLength: 1
+                  required:
+                    - id
+                    - name
+                  additionalProperties: false
+                - type: 'null'
+            email:
+              anyOf:
+                - type: string
+                  format: email
+                - type: 'null'
+            inApp:
+              anyOf:
+                - type: boolean
+                - type: 'null'
+              description: Whether the in-app notification (the dashboard bell and Home) is recorded when the rule fires. Absent or `null` means on; `false` skips it for this rule.
+          additionalProperties: false
+        - type: 'null'
+      description: Delivery target for a rule's alert; `null` = use the project default. The `NotificationTarget` shape plus the in-app switch.
     ListAlertRulesResponse:
       type: array
       items:
@@ -17755,7 +18018,7 @@ components:
             type: boolean
             description: Whether the rule is evaluated by the cron.
           notify:
-            $ref: '#/components/schemas/NotificationTarget'
+            $ref: '#/components/schemas/AlertRuleNotify'
           createdAt:
             type: string
             description: ISO-8601 timestamp of creation.
@@ -17931,7 +18194,7 @@ components:
           description: Whether the rule is evaluated by the cron.
           type: boolean
         notify:
-          $ref: '#/components/schemas/NotificationTarget'
+          $ref: '#/components/schemas/AlertRuleNotify'
       required:
         - name
         - metricId
@@ -18074,7 +18337,7 @@ components:
         enabled:
           type: boolean
         notify:
-          $ref: '#/components/schemas/NotificationTarget'
+          $ref: '#/components/schemas/AlertRuleNotify'
       additionalProperties: false
     UpdateAlertRuleResponse:
       type: object
@@ -20319,6 +20582,14 @@ components:
             - type: string
             - type: 'null'
           description: Last 4 characters of the raw token, so the dashboard mask is matchable against the held key. `null` for keys minted before this column.
+        origin:
+          type: string
+          enum:
+            - cli
+            - mobile
+            - dashboard
+            - api
+          description: Where the key was minted. `cli` (a signed-in CLI session from device auth), `mobile` (a mobile app login), `dashboard` (the "New API key" dialog) or `api` (minted with another key — CLI, MCP, agents). Set at mint time; keys that predate the column were backfilled from their label, defaulting to `dashboard`.
       required:
         - id
         - type
@@ -20331,6 +20602,7 @@ components:
         - description
         - scopes
         - last4
+        - origin
       additionalProperties: false
     ListKeysResponse:
       type: object
@@ -20487,6 +20759,7 @@ components:
             - config
             - killswitch
             - metric
+            - ops
           description: Resource family — drives the result group + icon in the palette. (`member` hits are surfaced first.)
         id:
           type: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/openapi",
-  "version": "3.3.0",
+  "version": "3.4.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/schemas/alert-rules.yaml

@@ -1,3 +1,29 @@
+AlertRuleNotify:
+  anyOf:
+    - type: object
+      properties:
+        slackChannel:
+          anyOf:
+            - type: object
+              properties:
+                id: { type: string, minLength: 1 }
+                name: { type: string, minLength: 1 }
+              required: [id, name]
+              additionalProperties: false
+            - type: "null"
+        email:
+          anyOf:
+            - type: string
+              format: email
+            - type: "null"
+        inApp:
+          anyOf:
+            - type: boolean
+            - type: "null"
+          description: Whether the in-app notification (the dashboard bell and Home) is recorded when the rule fires. Absent or `null` means on; `false` skips it for this rule.
+      additionalProperties: false
+    - type: "null"
+  description: Delivery target for a rule's alert; `null` = use the project default. The `NotificationTarget` shape plus the in-app switch.
 AlertCompositeSpec:
   type: object
   description: >-
@@ -172,7 +198,7 @@ ListAlertRulesResponse:
         type: boolean
         description: Whether the rule is evaluated by the cron.
       notify:
-        $ref: ./common.yaml#/NotificationTarget
+        $ref: "#/AlertRuleNotify"
       createdAt:
         type: string
         description: ISO-8601 timestamp of creation.
@@ -415,7 +441,7 @@ CreateAlertRuleRequest:
       description: Whether the rule is evaluated by the cron.
       type: boolean
     notify:
-      $ref: ./common.yaml#/NotificationTarget
+      $ref: "#/AlertRuleNotify"
   required:
     - name
     - metricId
@@ -551,7 +577,7 @@ UpdateAlertRuleRequest:
     enabled:
       type: boolean
     notify:
-      $ref: ./common.yaml#/NotificationTarget
+      $ref: "#/AlertRuleNotify"
   additionalProperties: false
 UpdateAlertRuleResponse:
   type: object

package/spec/components/schemas/keys.yaml

@@ -77,6 +77,14 @@ KeyRecord:
         - type: string
         - type: "null"
       description: Last 4 characters of the raw token, so the dashboard mask is matchable against the held key. `null` for keys minted before this column.
+    origin:
+      type: string
+      enum:
+        - cli
+        - mobile
+        - dashboard
+        - api
+      description: Where the key was minted. `cli` (a signed-in CLI session from device auth), `mobile` (a mobile app login), `dashboard` (the "New API key" dialog) or `api` (minted with another key — CLI, MCP, agents). Set at mint time; keys that predate the column were backfilled from their label, defaulting to `dashboard`.
   required:
     - id
     - type
@@ -89,6 +97,7 @@ KeyRecord:
     - description
     - scopes
     - last4
+    - origin
   additionalProperties: false
 UpdateKeyRequest:
   type: object

package/spec/components/schemas/ops.yaml

@@ -2516,6 +2516,100 @@ ListOpsQuestionsResponse:
   items:
     $ref: "#/OpsQuestion"
   description: Response for `GET /api/admin/ops/{handle}/questions` — the item's questions, newest first (max 100).
+OpsQaNoteKind:
+  type: string
+  enum:
+    - narrowing
+    - clarification
+    - verification
+    - correction
+  description: "What a QA note is — `narrowing` (only part of the bug still fails), `clarification` (changes what \"fixed\" means), `verification` (a pass/fail verdict on a fix) or `correction` (withdraws an earlier framing)."
+OpsQaNoteVerdict:
+  type: string
+  enum:
+    - pass
+    - fail
+  description: The outcome a `verification` note records.
+OpsQaNote:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Note id.
+    feedbackId:
+      type: string
+      description: The queue item the note hangs off.
+    kind:
+      $ref: "#/OpsQaNoteKind"
+    verdict:
+      anyOf:
+        - $ref: "#/OpsQaNoteVerdict"
+        - type: "null"
+      description: The pass/fail verdict of a `verification` note; `null` for every other kind.
+    body:
+      type: string
+      description: The note (markdown) — for a `verification`, what was checked.
+    authorEmail:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Email of the person (or the key's actor) who wrote the note, or `null` when an agent wrote it.
+    authorAgent:
+      anyOf:
+        - type: string
+          enum:
+            - jarvis
+            - claude
+            - cursor
+            - copilot
+            - jules
+        - type: "null"
+      description: The agent type that wrote the note (QA automation), or `null` for a person.
+    createdAt:
+      type: string
+      description: ISO-8601 creation timestamp.
+  required:
+    - id
+    - feedbackId
+    - kind
+    - verdict
+    - body
+    - authorEmail
+    - authorAgent
+    - createdAt
+  additionalProperties: false
+  description: One typed, append-only QA note on a queue item.
+CreateOpsQaNoteRequest:
+  type: object
+  properties:
+    kind:
+      $ref: "#/OpsQaNoteKind"
+    body:
+      type: string
+      minLength: 1
+      maxLength: 10000
+      description: The note (markdown).
+    verdict:
+      $ref: "#/OpsQaNoteVerdict"
+    agent:
+      type: string
+      enum:
+        - jarvis
+        - claude
+        - cursor
+        - copilot
+        - jules
+      description: The agent type writing the note — pass your own type when you are QA automation. Omitted, the note is attributed to the caller's identity.
+  required:
+    - kind
+    - body
+  additionalProperties: false
+  description: "Body for `POST /api/admin/ops/{handle}/qa-notes`. A `verification` note requires `verdict`; every other kind rejects it."
+ListOpsQaNotesResponse:
+  type: array
+  items:
+    $ref: "#/OpsQaNote"
+  description: Response for `GET /api/admin/ops/{handle}/qa-notes` — the item's QA notes, newest first (max 200).
 NotificationFeedItem:
   type: object
   properties:

package/spec/components/schemas/search.yaml

@@ -22,6 +22,7 @@ SearchHit:
         - config
         - killswitch
         - metric
+        - ops
       description: Resource family — drives the result group + icon in the palette. (`member` hits are surfaced first.)
     id:
       type: string

package/spec/openapi.yaml

@@ -236,6 +236,17 @@ tags:
       run record with the answers in the prompt. `delivery: poll` (the default
       for a live, connector-less session such as Claude Code in a terminal)
       fires nothing — call `list` until the status reads `completed`.
+  - name: QA notes
+    parent: Ops
+    description: |-
+      Typed QA notes on a queue item — the QA follow-up that is not discussion.
+      Each note is one of four kinds: `narrowing` (only part of the bug still
+      fails), `clarification` (changes what "fixed" means), `verification` (a
+      `pass` / `fail` verdict on a fix) or `correction` (withdraws an earlier
+      framing). Notes are append-only, carry their author and time, and render in
+      their own section of the item's detail panel, separate from the comment
+      thread. A failing verification offers a "Reopen item" action in the
+      dashboard; it is always an explicit click, never a side effect of `create`.
   - name: Projects
     description: |-
       Projects: the account-level container every other resource is scoped to.
@@ -407,6 +418,8 @@ paths:
     $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}~1questions~1{questionId}~1answer
   /api/admin/ops/{handle}/questions/{questionId}/cancel:
     $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}~1questions~1{questionId}~1cancel
+  /api/admin/ops/{handle}/qa-notes:
+    $ref: ./paths/ops.yaml#/~1api~1admin~1ops~1{handle}~1qa-notes
   /api/admin/agent-profiles:
     $ref: ./paths/ops.yaml#/~1api~1admin~1agent-profiles
   /api/admin/ops/{handle}/comments: