@shipeasy/openapi 3.2.0 → 3.3.0

package/spec/components/schemas/ops.yaml

@@ -416,7 +416,7 @@ OpsItemContext:
             properties:
               t:
                 type: number
-                description: Bucket start — unix epoch **milliseconds** (hourly buckets).
+                description: Bucket start — unix epoch **milliseconds**. Bucket width scales with the window (hourly up to ~5 days, coarser beyond).
               v:
                 type: number
                 description: Occurrence count in the bucket (sample-rate weighted).
@@ -424,11 +424,11 @@ OpsItemContext:
               - t
               - v
             additionalProperties: {}
-            description: One hourly occurrence bucket.
-          description: Hourly occurrence buckets, oldest first. Hours with no occurrences are omitted.
+            description: One occurrence bucket.
+          description: Occurrence buckets, oldest first. Buckets with no occurrences are omitted.
         domainFrom:
           type: number
-          description: Chart domain start — unix epoch milliseconds (24h before the read).
+          description: Chart domain start — unix epoch milliseconds (the window's start).
         domainTo:
           type: number
           description: Chart domain end — unix epoch milliseconds (the read time).
@@ -437,7 +437,7 @@ OpsItemContext:
         - domainFrom
         - domainTo
       additionalProperties: {}
-      description: "Occurrence timeline for an `error` ticket — hourly buckets over the last 24h from the sampled occurrences, hydrated at read time by the single-item read only. ABSENT (not `null`) on non-error tickets, on list rows (raw context), and when no occurrence landed in the window."
+      description: "Occurrence timeline for an `error` ticket — buckets over the project's error auto-close window (Settings → Errors: `errorAutocloseDays`, 7 days when auto-close is off, capped at 30) from the sampled occurrences, hydrated at read time by the single-item read only. Plotting exactly the quiet window that auto-resolves the error is what makes an empty right-hand edge meaningful. ABSENT (not `null`) on non-error tickets, on list rows (raw context), and when no occurrence landed in the window."
   additionalProperties: {}
   description: "Per-type capture context on a queue item. Exactly one of `browser` (bug/feature), `error`, `alert`, or `measurePlan` is populated depending on `type`; other keys (e.g. the AI dedupe block on bugs) may also be present."
 OpsBrowserContext:
@@ -548,20 +548,31 @@ OpsAlertContext:
       type: string
       enum:
         - metric_rule
+        - killswitch_armed
         - experiment_srm
         - experiment_peek
         - guardrail
-      description: What kind of alert transitioned to active.
+      description: What kind of condition opened this alert instance.
     dedupeKey:
       type: string
       description: Stable per-condition key; with `source` forms the ticket's `sourceRef`.
+    detail:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: The instance's one-line reading — the observed condition in words.
+    ruleId:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Id of the alert rule that opened this instance, or `null` for a built-in condition.
     severity:
       type: string
       enum:
         - danger
         - warn
         - info
-      description: Alert severity.
+      description: "How loud the alert is. Severity belongs to the RULE and is carried by this ticket as `priority`; it is DERIVED from that on the hydrated single-item read, and absent from the raw stored context list rows return."
     observedValue:
       anyOf:
         - type: number
@@ -580,7 +591,7 @@ OpsAlertContext:
             - resolved
             - dismissed
         - type: "null"
-      description: "Current status of the underlying alert (`active` while the condition holds), or `null` if the alert row is gone."
+      description: "Firing state of this instance, projected from the ticket's own status (`active` while it is open, i.e. while the condition holds). Absent from the raw stored context list rows return."
     activeSince:
       anyOf:
         - type: string
@@ -604,9 +615,8 @@ OpsAlertContext:
   required:
     - source
     - dedupeKey
-    - severity
   additionalProperties: {}
-  description: "Hydrated detail for an auto-filed `alert` ticket, resolving the rule → metric → event chain at request time."
+  description: "Detail for an `alert` ticket — the fired-alert INSTANCE this ticket is. List rows carry the stored capture subset (`source`, `dedupeKey`, `ruleId`, `detail`, `href`, `observedValue`); the single-item read hydrates the rest, resolving `severity`/`status` off the ticket itself and the rule → metric → event chain at request time."
 OpsAlertRuleSummary:
   type: object
   properties:
@@ -855,6 +865,33 @@ GithubPrLink:
         - closes
         - comment
       description: How the PR was connected to the issue.
+    owner:
+      type: string
+      description: >-
+        Repository owner (org or user) the pull request lives in. Absent on
+        links recorded before the field existed — `url` still carries it.
+    repo:
+      type: string
+      description: >-
+        Repository name the pull request lives in. Absent on links recorded
+        before the field existed — `url` still carries it.
+    state:
+      type: string
+      enum:
+        - open
+        - merged
+        - closed
+      description: >-
+        Outcome of the pull request on GitHub, kept current by the
+        `pull_request` webhook. `merged` and `closed` (closed WITHOUT merging,
+        i.e. rejected) are terminal. Absent means the outcome has never been
+        observed — treat it as `open`.
+    mergedAt:
+      type: string
+      description: ISO-8601 timestamp the pull request merged, when `state` is `merged`.
+    closedAt:
+      type: string
+      description: ISO-8601 timestamp the pull request closed unmerged, when `state` is `closed`.
   required:
     - number
     - url
@@ -934,10 +971,15 @@ CreateBugRequest:
       description: Emails of teammates to subscribe to this item's Slack pings at creation.
     tags:
       type: array
+      maxItems: 50
       items:
-        type: string
+        $ref: ./tags.yaml#/TagName
       default: []
-      description: Tag names to attach at creation (get-or-created by name, deduped case-insensitively).
+      description: >-
+        Tag names to label the item with, e.g. `["ios", "checkout"]`. Each name
+        is matched case-insensitively against the project's existing tags and
+        reuses that tag (keeping its stored casing) when one matches; a name with
+        no match creates a new project tag.
     reporterEmail:
       anyOf:
         - type: string
@@ -1025,10 +1067,15 @@ CreateFeatureRequestRequest:
       description: Emails of teammates to subscribe to this item's Slack pings at creation.
     tags:
       type: array
+      maxItems: 50
       items:
-        type: string
+        $ref: ./tags.yaml#/TagName
       default: []
-      description: Tag names to attach at creation (get-or-created by name, deduped case-insensitively).
+      description: >-
+        Tag names to label the item with, e.g. `["ios", "checkout"]`. Each name
+        is matched case-insensitively against the project's existing tags and
+        reuses that tag (keeping its stored casing) when one matches; a name with
+        no match creates a new project tag.
     reporterEmail:
       anyOf:
         - type: string
@@ -1110,10 +1157,17 @@ CreatePublicBugRequest:
       description: Emails of teammates to subscribe to this item's Slack pings at creation.
     tags:
       type: array
+      maxItems: 50
       items:
-        type: string
+        $ref: ./tags.yaml#/TagName
       default: []
-      description: Tag names to attach at creation (get-or-created by name, deduped case-insensitively).
+      description: >-
+        Tag names to label the item with, e.g. `["ios", "checkout"]`. Each name
+        is matched case-insensitively against the project's existing tags and
+        reuses that tag (keeping its stored casing) when one matches; a name with
+        no match creates a new project tag. Here the tags only label the
+        ticket: the project's tag rules (owner/status/agent routing) are not
+        applied to a public report while it awaits approval.
     reporterEmail:
       anyOf:
         - type: string
@@ -1144,6 +1198,20 @@ CreatePublicBugRequest:
           additionalProperties: {}
         - type: "null"
       description: Arbitrary capture context, or `null`.
+    dedupKey:
+      type: string
+      maxLength: 200
+      description: >-
+        Caller-chosen dedupe identity for this report, stored on the ticket. A
+        repeat submission carrying the same key does NOT file a second ticket:
+        the open ticket already holding that key is refreshed from this payload
+        (title and the report fields overwritten, a "re-triggered" comment
+        appended) and returned with `deduped: true` and `updated: true`. Triage
+        state a human owns — status, priority, assignee, tags — is left
+        untouched, and a `resolved`/`wont_fix` ticket no longer holds the key, so
+        a failure that comes back after being closed files a fresh ticket. Omit
+        it to fall back to the derived (title + `context.step`) dedupe, whose
+        repeats return the existing ticket unchanged.
     notify:
       anyOf:
         - $ref: ./common.yaml#/NotificationTarget
@@ -1152,7 +1220,7 @@ CreatePublicBugRequest:
   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."
+  description: "Body for `POST /ops/bug`. The same bug fields as `CreateBugRequest`, minus the `type` discriminator — the path already says what is being filed, plus the public intake's own `dedupKey`."
 CreatePublicFeatureRequestRequest:
   type: object
   properties:
@@ -1195,10 +1263,17 @@ CreatePublicFeatureRequestRequest:
       description: Emails of teammates to subscribe to this item's Slack pings at creation.
     tags:
       type: array
+      maxItems: 50
       items:
-        type: string
+        $ref: ./tags.yaml#/TagName
       default: []
-      description: Tag names to attach at creation (get-or-created by name, deduped case-insensitively).
+      description: >-
+        Tag names to label the item with, e.g. `["ios", "checkout"]`. Each name
+        is matched case-insensitively against the project's existing tags and
+        reuses that tag (keeping its stored casing) when one matches; a name with
+        no match creates a new project tag. Here the tags only label the
+        ticket: the project's tag rules (owner/status/agent routing) are not
+        applied to a public report while it awaits approval.
     reporterEmail:
       anyOf:
         - type: string
@@ -1223,6 +1298,15 @@ CreatePublicFeatureRequestRequest:
           additionalProperties: {}
         - type: "null"
       description: Arbitrary capture context, or `null`.
+    dedupKey:
+      type: string
+      maxLength: 200
+      description: >-
+        Caller-chosen dedupe identity for this request, stored on the ticket.
+        Behaves exactly as on `POST /ops/bug`: a repeat carrying the same key
+        refreshes the open ticket already holding it (fields overwritten, a
+        "re-triggered" comment appended) and returns `deduped: true` with
+        `updated: true`, instead of filing a second one.
     notify:
       anyOf:
         - $ref: ./common.yaml#/NotificationTarget
@@ -1231,7 +1315,7 @@ CreatePublicFeatureRequestRequest:
   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."
+  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, plus the public intake's own `dedupKey`."
 CreateOpsItemRequest:
   oneOf:
     - $ref: "#/CreateBugRequest"
@@ -1254,10 +1338,13 @@ CreatePublicTicketResponse:
     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)."
+    updated:
+      type: boolean
+      description: "`true` when the deduped ticket was REFRESHED from this payload and got a \"re-triggered\" comment — only ever set alongside `deduped` on a submission that carried a `dedupKey`. Absent when the existing ticket was returned untouched."
   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`."
+  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` — plus `updated: true` when a `dedupKey` re-triggered it and its fields were refreshed."
 CreateOpsItemResponse:
   type: object
   properties:
@@ -1321,6 +1408,7 @@ OpsInvestigationState:
   enum:
     - pr_ready
     - pr_merged
+    - pr_closed
     - investigated
     - detected
     - question
@@ -1335,14 +1423,17 @@ OpsInvestigationState:
     happen**, never authored on its own: linking a PR sets `pr_ready`, moving to
     `in_progress` sets `working`, `ready_for_qa` sets `ready_for_qa`, a
     system/assistant reply sets `question`, resolving clears it, and creation
-    seeds `backlog` or `investigated`/`detected` for auto-filed error/alert
-    tickets. `backlog` is the single "nothing has happened yet" state — how
-    urgent that is reads off `priority`, not off a separate state, and its one
-    action is to hand the item to an agent. `pr_merged` is derived client-side
-    by scanning the linked pull request on GitHub, so it is accepted on write
-    but not currently emitted by the API. Absent on rows filed before the field
-    existed — consumers should treat a missing value as "derive from the other
-    fields".
+    seeds `backlog` for every untouched item (bugs, features, and auto-filed
+    error/alert tickets alike — type is not a signal). `backlog` is the single
+    "nothing has happened yet" state — how urgent that is reads off `priority`,
+    not off a separate state, and its one action is to hand the item to an
+    agent. `investigated`/`detected` are set when a completed agent run leaves
+    findings to review, not at filing time. `pr_merged` and `pr_closed` are
+    written by the GitHub `pull_request` webhook when the linked PR reaches a
+    terminal outcome — merged (the fix shipped, resolve the item) or closed
+    without merging (the fix was rejected, decide what happens next). Absent on
+    rows filed before the field existed — consumers should treat a missing
+    value as "derive from the other fields".
 OpsItemPriorityOrNull:
   anyOf:
     - $ref: "#/OpsItemPriority"
@@ -1520,6 +1611,16 @@ AckOpsItemRequest:
         The agent-run session id (e.g. Claude's `session_01…`), so the dashboard
         can deep-link to the exact run page. Omit when the harness has no
         session id.
+    launch:
+      type: boolean
+      default: true
+      description: >-
+        Whether an AI ack may FIRE the agent's connected trigger. Default
+        `true`: an ack naming a connected agent, with no `sessionId`, starts a
+        new provider run of that agent. Pass `false` to only record the ack —
+        claim the item and open the run record — without starting anything,
+        e.g. when you ARE that agent working the item yourself and have no
+        session id to pass. Ignored on a human ack.
   additionalProperties: false
   description: >-
     Body for `POST /api/admin/ops/{handle}/ack`. With `agent` set this is an AI
@@ -2168,6 +2269,253 @@ UpdateOpsInvestigationRequest:
   additionalProperties: false
   minProperties: 1
   description: "Body for `PATCH /api/admin/ops/{handle}/investigation/{investigationId}` — a partial update of one existing investigation record (typically the `working` run record you were handed). Send only the fields you want to change; at least one is required."
+OpsQuestionStatus:
+  type: string
+  enum:
+    - open
+    - completed
+    - cancelled
+  description: "Where a question stands — `open` (waiting on a person), `completed` (answered), or `cancelled` (withdrawn by the asker)."
+OpsQuestionDelivery:
+  type: string
+  enum:
+    - resume
+    - poll
+  description: "How the answer gets back to the asker — `resume` re-fires the asking run's trigger connector on the item once every question that run asked is answered; `poll` fires nothing and the asker reads `GET .../questions`."
+OpsQuestionOption:
+  type: object
+  properties:
+    label:
+      type: string
+      minLength: 1
+      maxLength: 120
+      description: The option's display text — short (1–5 words). Answers name options by this label.
+    description:
+      type: string
+      maxLength: 500
+      description: What picking this option means — its trade-off or consequence.
+  required:
+    - label
+  additionalProperties: false
+  description: One choice offered by a question — rendered as a radio, or a checkbox when the question is `multiSelect`.
+OpsQuestionAnswer:
+  type: object
+  properties:
+    selected:
+      type: array
+      items:
+        type: string
+      description: The option labels the person picked (empty when they only answered "Other").
+    other:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: The free-text "Other" answer, or `null`.
+  required:
+    - selected
+    - other
+  additionalProperties: false
+  description: A person's answer to a question.
+AskOpsQuestionInput:
+  type: object
+  properties:
+    header:
+      type: string
+      minLength: 1
+      maxLength: 24
+      description: Very short chip label for the question (max 24 chars), e.g. `Auth method`.
+    question:
+      type: string
+      minLength: 1
+      maxLength: 2000
+      description: The complete question, ending with a question mark (markdown).
+    options:
+      type: array
+      minItems: 2
+      maxItems: 4
+      items:
+        $ref: "#/OpsQuestionOption"
+      description: 2–4 distinct choices. Do not add an "Other" option — a free-text answer is always offered.
+    multiSelect:
+      type: boolean
+      default: false
+      description: "`true` lets the person pick several options (checkboxes); `false` (the default) exactly one (radios)."
+  required:
+    - header
+    - question
+    - options
+  additionalProperties: false
+  description: One question to ask — the `AskUserQuestion` shape.
+AskOpsQuestionsRequest:
+  type: object
+  properties:
+    questions:
+      type: array
+      minItems: 1
+      maxItems: 4
+      items:
+        $ref: "#/AskOpsQuestionInput"
+      description: 1–4 questions to ask at once.
+    runId:
+      type: string
+      maxLength: 200
+      description: The run (investigation record id) you are working the item under — the `runId` an ack or a launch handed you. Ties the questions to that run so a `resume` delivery continues it.
+    agent:
+      type: string
+      enum:
+        - jarvis
+        - claude
+        - cursor
+        - copilot
+        - jules
+      description: The agent type asking — pass your own type when you are a coding agent. Defaults to the run's agent.
+    delivery:
+      $ref: "#/OpsQuestionDelivery"
+  required:
+    - questions
+  additionalProperties: false
+  description: "Body for `POST /api/admin/ops/{handle}/questions`."
+AskOpsQuestionsResponse:
+  type: array
+  items:
+    $ref: "#/OpsQuestion"
+  description: Response for `POST /api/admin/ops/{handle}/questions` — the created questions, in the order asked.
+AnswerOpsQuestionRequest:
+  type: object
+  properties:
+    selected:
+      type: array
+      maxItems: 4
+      items:
+        type: string
+        maxLength: 120
+      description: The option labels picked — exactly one for a single-select question (unless answering only with `other`), one or more for `multiSelect`.
+    other:
+      type: string
+      maxLength: 10000
+      description: A free-text "Other" answer.
+  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)."
+OpsQuestion:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Question id.
+    feedbackId:
+      type: string
+      description: The queue item the question hangs off.
+    header:
+      type: string
+      description: Short chip label for the question.
+    question:
+      type: string
+      description: The full question (markdown).
+    options:
+      type: array
+      items:
+        type: object
+        properties:
+          label:
+            type: string
+            description: The option's display text.
+          description:
+            anyOf:
+              - type: string
+              - type: "null"
+            description: What picking the option means, or `null`.
+        required:
+          - label
+          - description
+        additionalProperties: false
+        description: One offered choice.
+      description: The offered choices, in order.
+    multiSelect:
+      type: boolean
+      description: Whether several options may be picked.
+    status:
+      $ref: "#/OpsQuestionStatus"
+    answer:
+      anyOf:
+        - $ref: "#/OpsQuestionAnswer"
+        - type: "null"
+      description: The person's answer, or `null` while the question is open (or was withdrawn).
+    answeredBy:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Email of the person who answered, or `null`.
+    answeredAt:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: ISO-8601 timestamp of the answer, or `null`.
+    agent:
+      anyOf:
+        - type: string
+          enum:
+            - jarvis
+            - claude
+            - cursor
+            - copilot
+            - jules
+        - type: "null"
+      description: The agent that asked, or `null` (asked by a person or an unattributed key).
+    askedBy:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Email of the person who asked, when a human asked, or `null`.
+    runId:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: The run (investigation record id) the question was asked under, or `null`.
+    delivery:
+      $ref: "#/OpsQuestionDelivery"
+    deliveredAt:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: ISO-8601 timestamp the answer was re-delivered to the asking run (`resume` only), or `null`.
+    deliveryError:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Why a `resume` re-delivery failed, or `null`.
+    createdAt:
+      type: string
+      description: ISO-8601 creation timestamp.
+    updatedAt:
+      type: string
+      description: ISO-8601 last-update timestamp.
+  required:
+    - id
+    - feedbackId
+    - header
+    - question
+    - options
+    - multiSelect
+    - status
+    - answer
+    - answeredBy
+    - answeredAt
+    - agent
+    - askedBy
+    - runId
+    - delivery
+    - deliveredAt
+    - deliveryError
+    - createdAt
+    - updatedAt
+  additionalProperties: false
+  description: One structured question on a queue item and, once answered, its answer.
+ListOpsQuestionsResponse:
+  type: array
+  items:
+    $ref: "#/OpsQuestion"
+  description: Response for `GET /api/admin/ops/{handle}/questions` — the item's questions, newest first (max 100).
 NotificationFeedItem:
   type: object
   properties:

package/spec/components/schemas/projects.yaml

@@ -171,6 +171,12 @@ GetCurrentProjectResponse:
         - type: boolean
         - type: number
       description: Whether key-authenticated public ticket creation (`POST /cli/report`) is allowed into this project. Off by default.
+    errorAutocloseDays:
+      type: integer
+      description: Days an `open` tracked error may go unseen before the nightly sweep auto-resolves it. `0` disables auto-close for this project. Ingest reopens a resolved error the moment it recurs, so this never hides a live issue.
+    errorTicketMinOccurrences:
+      type: integer
+      description: Occurrence count a tracked error must cross before an `error` ticket is auto-filed into the ops queue. Customising it requires a paid plan; unentitled projects always run at the platform default of 10.
     stripeSubscriptionId:
       anyOf:
         - type: string
@@ -250,6 +256,8 @@ GetCurrentProjectResponse:
     - moduleUser
     - moduleEvents
     - allowPublicTickets
+    - errorAutocloseDays
+    - errorTicketMinOccurrences
     - slug
     - logo
     - defaultEnv
@@ -462,5 +470,15 @@ UpdateProjectRequest:
       minimum: 0.0001
       maximum: 0.05
       description: SRM chi-square p-value below which the run is called invalid.
+    errorAutocloseDays:
+      type: integer
+      minimum: 0
+      maximum: 365
+      description: Days an `open` tracked error may go unseen before the nightly sweep auto-resolves it. `0` disables auto-close for this project.
+    errorTicketMinOccurrences:
+      type: integer
+      minimum: 1
+      maximum: 10000
+      description: Occurrence count a tracked error must cross before an `error` ticket is auto-filed into the ops queue. Requires a paid plan — the request is rejected with 403 on a plan without the `ops_auto_error_issues` entitlement.
   additionalProperties: false
   description: "Body for `PATCH /api/admin/projects/{id}`. Partial — every field is optional; only supplied fields change. The project id in the path must match the caller's own project."