@shipeasy/openapi 3.1.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
@@ -1063,6 +1110,212 @@ CreateFeatureRequestRequest:
     - title
   additionalProperties: false
   description: "Feature-request-kind fields for `POST /api/admin/ops` (sent with `type: feature_request`)."
+CreatePublicBugRequest:
+  type: object
+  properties:
+    title:
+      type: string
+      minLength: 1
+      maxLength: 200
+      pattern: '^\S(.*\S)?$'
+      description: One-line bug title (no leading/trailing whitespace).
+    stepsToReproduce:
+      type: string
+      maxLength: 8000
+      default: ""
+      description: How to reproduce the bug.
+    actualResult:
+      type: string
+      maxLength: 8000
+      default: ""
+      description: What actually happened.
+    expectedResult:
+      type: string
+      maxLength: 8000
+      default: ""
+      description: What was expected instead.
+    priority:
+      anyOf:
+        - $ref: "#/OpsItemPriority"
+        - type: "null"
+      description: Initial triage priority, or `null`.
+    status:
+      anyOf:
+        - $ref: "#/OpsItemStatus"
+      description: Initial lifecycle status; defaults to `open` when omitted.
+    assigneeId:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: The `users.id` of the person to assign as owner at creation, or `null`.
+    subscribers:
+      type: array
+      items:
+        type: string
+        format: email
+      default: []
+      description: Emails of teammates to subscribe to this item's Slack pings at creation.
+    tags:
+      type: array
+      maxItems: 50
+      items:
+        $ref: ./tags.yaml#/TagName
+      default: []
+      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
+          format: email
+        - type: "null"
+      description: Email of the reporter, or `null`.
+    pageUrl:
+      anyOf:
+        - type: string
+          format: uri
+        - type: "null"
+      description: URL of the page the bug relates to, or `null`.
+    userAgent:
+      anyOf:
+        - type: string
+          maxLength: 500
+        - type: "null"
+      description: Reporter's user-agent string, or `null`.
+    viewport:
+      anyOf:
+        - type: string
+          maxLength: 40
+        - type: "null"
+      description: Reporter's viewport (e.g. `1280x720`), or `null`.
+    context:
+      anyOf:
+        - type: object
+          additionalProperties: {}
+        - type: "null"
+      description: Arbitrary capture context, or `null`.
+    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
+        - type: "null"
+      description: Where this bug's completion notification lands.
+  required:
+    - title
+  additionalProperties: false
+  description: "Body for `POST /ops/bug`. The same bug fields as `CreateBugRequest`, minus the `type` discriminator — the path already says what is being filed, plus the public intake's own `dedupKey`."
+CreatePublicFeatureRequestRequest:
+  type: object
+  properties:
+    title:
+      type: string
+      minLength: 1
+      maxLength: 200
+      pattern: '^\S(.*\S)?$'
+      description: One-line feature-request title (no leading/trailing whitespace).
+    description:
+      type: string
+      maxLength: 8000
+      default: ""
+      description: What the feature is.
+    useCase:
+      type: string
+      maxLength: 8000
+      default: ""
+      description: Why it's needed / the use case.
+    priority:
+      anyOf:
+        - $ref: "#/OpsItemPriority"
+        - type: "null"
+      description: Initial triage priority, or `null`.
+    status:
+      anyOf:
+        - $ref: "#/OpsItemStatus"
+      description: Initial lifecycle status; defaults to `open` when omitted.
+    assigneeId:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: The `users.id` of the person to assign as owner at creation, or `null`.
+    subscribers:
+      type: array
+      items:
+        type: string
+        format: email
+      default: []
+      description: Emails of teammates to subscribe to this item's Slack pings at creation.
+    tags:
+      type: array
+      maxItems: 50
+      items:
+        $ref: ./tags.yaml#/TagName
+      default: []
+      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
+          format: email
+        - type: "null"
+      description: Email of the reporter, or `null`.
+    pageUrl:
+      anyOf:
+        - type: string
+          format: uri
+        - type: "null"
+      description: URL of the page the request relates to, or `null`.
+    userAgent:
+      anyOf:
+        - type: string
+          maxLength: 500
+        - type: "null"
+      description: Reporter's user-agent string, or `null`.
+    context:
+      anyOf:
+        - type: object
+          additionalProperties: {}
+        - type: "null"
+      description: Arbitrary capture context, or `null`.
+    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
+        - type: "null"
+      description: Where this request's completion notification lands.
+  required:
+    - title
+  additionalProperties: false
+  description: "Body for `POST /ops/feature-request`. The same feature-request fields as `CreateFeatureRequestRequest`, minus the `type` discriminator — the path already says what is being filed, plus the public intake's own `dedupKey`."
 CreateOpsItemRequest:
   oneOf:
     - $ref: "#/CreateBugRequest"
@@ -1073,6 +1326,25 @@ CreateOpsItemRequest:
       bug: "#/CreateBugRequest"
       feature_request: "#/CreateFeatureRequestRequest"
   description: "Body for `POST /api/admin/ops`. A discriminated union on `type`: `bug` carries the bug fields, `feature_request` the feature fields. Only these two user-fileable types are accepted — `error`, `alert`, and `measure_plan` tickets are auto-filed by the platform and cannot be created over the API."
+CreatePublicTicketResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: The new item's id. Absent on a deduped response — nothing was created, so there is no new id to report.
+    number:
+      type: integer
+      description: Per-project item number. On a deduped response this is the number of the OPEN ticket already tracking the report, which is what a caller should show the user either way.
+    deduped:
+      type: boolean
+      description: "`true` when an open ticket already tracked this report and nothing was filed (HTTP 200). Absent on a fresh file (HTTP 201)."
+    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` — plus `updated: true` when a `dedupKey` re-triggered it and its fields were refreshed."
 CreateOpsItemResponse:
   type: object
   properties:
@@ -1136,6 +1408,7 @@ OpsInvestigationState:
   enum:
     - pr_ready
     - pr_merged
+    - pr_closed
     - investigated
     - detected
     - question
@@ -1150,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"
@@ -1335,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
@@ -1983,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: