@shipeasy/openapi 3.2.0 → 3.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/openapi",
-  "version": "3.2.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,56 @@
+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: >-
+    What a `composite` rule is a boolean over. `rules` are sibling alert-rule ids
+    in the same project and `op` is how their states combine. A child's state is
+    what the current pass concluded about it, falling back to whether it has an
+    open instance — so a composite still means something on a tick where a child
+    could not be evaluated, which is exactly the tick a "two of these are broken
+    at once" rule is for. One level deep: a child may not itself be composite.
+  properties:
+    op:
+      type: string
+      enum:
+        - and
+        - or
+      description: How the children's states combine.
+    rules:
+      type: array
+      minItems: 2
+      items:
+        type: string
+        minLength: 1
+      description: Ids of the alert rules to combine. Stored sorted and de-duplicated.
+  required:
+    - op
+    - rules
+  additionalProperties: false
 ListAlertRulesResponse:
   type: array
   items:
@@ -17,6 +70,26 @@ ListAlertRulesResponse:
           - type: string
           - type: "null"
         description: Display name of the bound metric, or `null` if the metric no longer exists.
+      kind:
+        type: string
+        enum:
+          - normal
+          - anomaly
+          - outliers
+          - no_data
+          - composite
+        description: >-
+          What the rule watches for. `normal` compares the metric's own value —
+          against `threshold` via `comparator`, or against the
+          [`rangeMin`, `rangeMax`] corridor it must stay inside. `anomaly`
+          compares it against ITS OWN seasonal baseline in sigmas, which is the
+          same fit a chart draws as the band. `outliers` compares each `by()`
+          group against its peers in the same bucket, so it needs a grouped
+          metric. `no_data` fires when the metric records nothing at all for
+          `noDataMinutes` — a count of zero is not silence, and the two are
+          distinguished by the reader's presence columns. `composite` is a
+          boolean over OTHER rules' current state and watches no metric of its
+          own.
       comparator:
         type: string
         enum:
@@ -24,15 +97,96 @@ ListAlertRulesResponse:
           - gte
           - lt
           - lte
-        description: How the metric value is compared to the threshold (gt/gte/lt/lte).
+        description: How the metric value is compared to the threshold (gt/gte/lt/lte). Read only by a `normal` rule with no range set.
       threshold:
         type: number
-        description: Threshold the metric value is compared against.
+        description: Threshold the metric value is compared against. Read only by a `normal` rule with no range set.
+      rangeMin:
+        anyOf:
+          - type: number
+          - type: "null"
+        description: Lower edge of the corridor a `normal` rule must stay inside; `null` if the rule is judged by comparator and threshold.
+      rangeMax:
+        anyOf:
+          - type: number
+          - type: "null"
+        description: Upper edge of the corridor a `normal` rule must stay inside; `null` if the rule is judged by comparator and threshold.
+      sigma:
+        anyOf:
+          - type: number
+          - type: "null"
+        description: How far from normal is too far, for `anomaly` and `outliers`, in sigma-equivalents. `null` takes the default of 3, which is also the width of the band a chart draws.
+      direction:
+        anyOf:
+          - type: string
+            enum:
+              - above
+              - below
+              - either
+          - type: "null"
+        description: Which side of the baseline an `anomaly` or `outliers` rule watches. `null` means either.
+      sustained:
+        type: boolean
+        description: >-
+          Whether the rule is judged by ACCUMULATED departure rather than bucket
+          by bucket. `anomaly` and `outliers` only.
+      warnThreshold:
+        anyOf:
+          - type: number
+          - type: "null"
+        description: The milder bound, in the same unit the kind judges in. `null` means the rule has one level.
+      recoveryThreshold:
+        anyOf:
+          - type: number
+          - type: "null"
+        description: What the metric must get back to before a live alert closes. `null` means no hysteresis — the firing bound clears it.
+      groupAlerts:
+        type: boolean
+        description: Whether the rule fires one alert per `by()` group rather than one for the whole metric.
+      maxGroups:
+        anyOf:
+          - type: integer
+          - type: "null"
+        description: How many groups this rule may alert on at once. `null` takes the shipped cap of 10.
+      noDataMinutes:
+        anyOf:
+          - type: integer
+          - type: "null"
+        description: How long the silence must last for a `no_data` rule. `null` on every other kind.
+      delayMinutes:
+        anyOf:
+          - type: integer
+          - type: "null"
+        description: How far behind live the evaluated window is held, on top of the reader's settle grace. `null` means no extra delay.
+      autoResolveMinutes:
+        anyOf:
+          - type: integer
+          - type: "null"
+        description: Close a live instance that has gone this long without a fresh verdict. `null` never auto-resolves.
+      composite:
+        anyOf:
+          - $ref: "#/AlertCompositeSpec"
+          - type: "null"
+        description: For a `composite` rule, the child rules and how their states combine. `null` on every other kind.
       windowHours:
         type: integer
         minimum: -9007199254740991
         maximum: 9007199254740991
         description: Lookback window (hours) the metric is aggregated over.
+      bucketMinutes:
+        anyOf:
+          - type: integer
+          - type: "null"
+        description: >-
+          Width of the buckets the window is split into, in minutes. `null`
+          divides the window into 12 equal buckets.
+      requiredBuckets:
+        anyOf:
+          - type: integer
+          - type: "null"
+        description: >-
+          How many buckets must breach before the rule fires. `null` means
+          every bucket that had data.
       severity:
         type: string
         enum:
@@ -44,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.
@@ -56,9 +210,25 @@ ListAlertRulesResponse:
       - name
       - metricId
       - metricName
+      - kind
       - comparator
       - threshold
+      - rangeMin
+      - rangeMax
+      - sigma
+      - direction
+      - sustained
+      - warnThreshold
+      - recoveryThreshold
+      - groupAlerts
+      - maxGroups
+      - noDataMinutes
+      - delayMinutes
+      - autoResolveMinutes
+      - composite
       - windowHours
+      - bucketMinutes
+      - requiredBuckets
       - severity
       - enabled
       - notify
@@ -78,26 +248,189 @@ CreateAlertRuleRequest:
       type: string
       minLength: 1
       description: Id of the metric to evaluate.
+    kind:
+      default: normal
+      description: >-
+        What the rule watches for. `normal` compares the metric's own value —
+        against `threshold` via `comparator`, or against the
+        [`rangeMin`, `rangeMax`] corridor it must stay inside. `anomaly` compares
+        it against its own seasonal baseline in sigmas: the same fit a chart
+        draws as the band, so a point outside the drawn band is exactly a
+        breaching bucket, and one metric can back rules at several sigmas.
+        `outliers` compares each `by()` group against its peers in the same
+        bucket and is refused on a metric with no grouping.
+      type: string
+      enum:
+        - normal
+        - anomaly
+        - outliers
+        - no_data
+        - composite
     comparator:
+      default: gt
+      description: How the metric value is compared to the threshold. Read only by a `normal` rule with no range set.
       type: string
       enum:
         - gt
         - gte
         - lt
         - lte
-      description: How the metric value is compared to the threshold (gt/gte/lt/lte).
     threshold:
       type: number
-      description: Threshold the metric value is compared against.
+      description: >-
+        Threshold the metric value is compared against. Required for a `normal`
+        rule unless a range is given; ignored by every other kind.
+    rangeMin:
+      anyOf:
+        - type: number
+        - type: "null"
+      description: >-
+        Lower edge of the corridor the metric must stay inside. Setting either
+        bound switches a `normal` rule off `comparator`/`threshold` and onto the
+        range, which breaches on LEAVING it in either direction. One bound alone
+        is a one-sided range.
+    rangeMax:
+      anyOf:
+        - type: number
+        - type: "null"
+      description: Upper edge of the corridor the metric must stay inside.
+    sigma:
+      anyOf:
+        - type: number
+          exclusiveMinimum: 0
+        - type: "null"
+      description: >-
+        How far from normal is too far, for `anomaly` and `outliers`, in
+        sigma-equivalents. Omit (or `null`) for 3, which is also the half-width
+        of the band a chart draws — so an unconfigured rule fires exactly where
+        the picture says it would.
+    direction:
+      anyOf:
+        - type: string
+          enum:
+            - above
+            - below
+            - either
+        - type: "null"
+      description: >-
+        Which side of the baseline an `anomaly` or `outliers` rule watches. Omit
+        (or `null`) for either, which is what "is this unusual" means; name a
+        side for a metric that is only bad in one direction.
+    sustained:
+      default: false
+      type: boolean
+      description: >-
+        Judge the window by ACCUMULATED departure instead of bucket by bucket.
+        The ordinary check asks every bucket to be past `sigma`, which a slow
+        regression never manages: a metric running 1.5σ worse than normal since
+        Tuesday puts no single bucket past 3σ and pages nobody. A sustained rule
+        adds up each bucket's excess over half a sigma and fires once the total
+        passes twice `sigma` — four buckets at 2σ do it, a lone 3σ spike does
+        not. `anomaly` and `outliers` only, and refused alongside
+        `requiredBuckets`: the accumulated bar IS the evidence bar, and a second
+        one counted in buckets would silently override it.
     windowHours:
       default: 24
       description: Lookback window (hours) the metric is aggregated over. 1–720.
       type: integer
       minimum: 1
       maximum: 720
+    bucketMinutes:
+      anyOf:
+        - type: integer
+          minimum: 1
+          maximum: 43200
+        - type: "null"
+      description: >-
+        Width of the buckets the window is split into, in minutes. Omit (or
+        `null`) to divide the window into 12 equal buckets. The rule is judged
+        per bucket, so this is the resolution at which "sustained" is measured —
+        a short bucket asks the condition to hold through finer detail.
+    requiredBuckets:
+      anyOf:
+        - type: integer
+          minimum: 1
+        - type: "null"
+      description: >-
+        How many buckets must breach before the rule fires. Omit (or `null`) to
+        require every bucket that had data. Buckets with nothing in them are
+        excluded before this is counted, so on a sparse metric `null` can mean a
+        single bucket — set this to 2 or more where one lone sample must never
+        page.
+    warnThreshold:
+      anyOf:
+        - type: number
+        - type: "null"
+      description: >-
+        The milder bound — a second level, in the same unit the kind judges in,
+        that raises a quieter alert before the firing level is reached. Must be
+        strictly milder than the level the rule fires at, or it could never fire
+        on its own. Refused on a range rule and on a `sustained` one: neither
+        condition is a single number, so there is nothing to substitute.
+    recoveryThreshold:
+      anyOf:
+        - type: number
+        - type: "null"
+      description: >-
+        What the metric must get back to before a live alert closes. Without it a
+        metric sitting on its threshold pages and clears once per tick. Must be
+        on the safe side of the firing level, or equal to it. Omit (or `null`)
+        for no hysteresis.
+    groupAlerts:
+      default: false
+      type: boolean
+      description: >-
+        Fire one alert per `by()` group instead of one for the whole metric. The
+        firing key becomes (rule, group), so each group raises, dedupes and
+        recovers on its own. Refused on a metric with no `by()`, and on `no_data`
+        — a group that went silent has no rows left to be missing from.
+    maxGroups:
+      anyOf:
+        - type: integer
+          minimum: 1
+          maximum: 50
+        - type: "null"
+      description: >-
+        How many groups this rule may alert on at once. Omit (or `null`) for 10.
+        Past the cap the worst groups fire and the count of the rest is stated on
+        each ticket — a group set is customer data, and an uncapped rule on
+        `by(user_id)` would file a ticket per user.
+    noDataMinutes:
+      anyOf:
+        - type: integer
+          minimum: 5
+          maximum: 43200
+        - type: "null"
+      description: >-
+        For a `no_data` rule: how long the silence must last. Omit (or `null`)
+        for 15 minutes. Five is the floor — below it, ordinary ingest lag empties
+        the trailing bucket and reads as an outage.
+    delayMinutes:
+      anyOf:
+        - type: integer
+          minimum: 1
+          maximum: 1440
+        - type: "null"
+      description: >-
+        Hold the evaluated window back this far behind live, on top of the
+        reader's own settle grace. For a metric assembled from a source that
+        lands in batches, whose trailing buckets are legitimately incomplete for
+        longer than the grace covers.
+    autoResolveMinutes:
+      anyOf:
+        - type: integer
+          minimum: 1
+        - type: "null"
+      description: >-
+        Close a live instance that has gone this long without a fresh verdict. A
+        rule that cannot reach a verdict deliberately leaves its alert alone,
+        which is right for a tick and wrong for a week. Never closes an instance
+        that is currently breaching. Omit (or `null`) to never auto-resolve.
+    composite:
+      $ref: "#/AlertCompositeSpec"
     severity:
       default: warn
-      description: Severity of the raised alert.
+      description: Severity of the raised alert. A `warnThreshold` breach opens one step quieter than this.
       type: string
       enum:
         - danger
@@ -108,12 +441,10 @@ CreateAlertRuleRequest:
       description: Whether the rule is evaluated by the cron.
       type: boolean
     notify:
-      $ref: ./common.yaml#/NotificationTarget
+      $ref: "#/AlertRuleNotify"
   required:
     - name
     - metricId
-    - comparator
-    - threshold
   additionalProperties: false
 CreateAlertRuleResponse:
   type: object
@@ -131,6 +462,14 @@ UpdateAlertRuleRequest:
       type: string
       minLength: 1
       maxLength: 120
+    kind:
+      type: string
+      enum:
+        - normal
+        - anomaly
+        - outliers
+        - no_data
+        - composite
     comparator:
       type: string
       enum:
@@ -140,10 +479,95 @@ UpdateAlertRuleRequest:
         - lte
     threshold:
       type: number
+    rangeMin:
+      anyOf:
+        - type: number
+        - type: "null"
+      description: Lower edge of the corridor; `null` drops it, returning the rule to comparator and threshold when both bounds are gone.
+    rangeMax:
+      anyOf:
+        - type: number
+        - type: "null"
+      description: Upper edge of the corridor; `null` drops it.
+    sigma:
+      anyOf:
+        - type: number
+          exclusiveMinimum: 0
+        - type: "null"
+      description: Sigmas an `anomaly` or `outliers` rule fires at; `null` restores the default of 3.
+    direction:
+      anyOf:
+        - type: string
+          enum:
+            - above
+            - below
+            - either
+        - type: "null"
+      description: Which side an `anomaly` or `outliers` rule watches; `null` restores either.
+    sustained:
+      type: boolean
+      description: >-
+        Judge the window by accumulated departure rather than bucket by bucket.
+        `anomaly` and `outliers` only; refused alongside `requiredBuckets`.
+    warnThreshold:
+      anyOf:
+        - type: number
+        - type: "null"
+      description: The milder bound; `null` drops the warning level, leaving the rule with one.
+    recoveryThreshold:
+      anyOf:
+        - type: number
+        - type: "null"
+      description: What the metric must get back to before a live alert closes; `null` drops the hysteresis.
+    groupAlerts:
+      type: boolean
+      description: Fire one alert per `by()` group. Refused on a metric with no grouping.
+    maxGroups:
+      anyOf:
+        - type: integer
+          minimum: 1
+          maximum: 50
+        - type: "null"
+      description: How many groups may alert at once; `null` restores the default of 10.
+    noDataMinutes:
+      anyOf:
+        - type: integer
+          minimum: 5
+          maximum: 43200
+        - type: "null"
+      description: How long a `no_data` rule's silence must last; `null` restores 15 minutes.
+    delayMinutes:
+      anyOf:
+        - type: integer
+          minimum: 1
+          maximum: 1440
+        - type: "null"
+      description: How far behind live the window is held; `null` drops the delay.
+    autoResolveMinutes:
+      anyOf:
+        - type: integer
+          minimum: 1
+        - type: "null"
+      description: Close a stale live instance after this long; `null` never auto-resolves.
+    composite:
+      $ref: "#/AlertCompositeSpec"
     windowHours:
       type: integer
       minimum: 1
       maximum: 720
+    bucketMinutes:
+      anyOf:
+        - type: integer
+          minimum: 1
+          maximum: 43200
+        - type: "null"
+      description: Bucket width in minutes; `null` restores the default 12 buckets per window.
+    requiredBuckets:
+      anyOf:
+        - type: integer
+          minimum: 1
+        - type: "null"
+      description: Buckets that must breach to fire; `null` restores "every bucket that had data".
     severity:
       type: string
       enum:
@@ -153,7 +577,7 @@ UpdateAlertRuleRequest:
     enabled:
       type: boolean
     notify:
-      $ref: ./common.yaml#/NotificationTarget
+      $ref: "#/AlertRuleNotify"
   additionalProperties: false
 UpdateAlertRuleResponse:
   type: object

package/spec/components/schemas/alerts.yaml

@@ -1,13 +1,15 @@
 AlertApiRow:
   type: object
   description: |-
-    One FIRED alert — a condition the platform observed and raised, not the rule that defines it (alert *rules* are the `/api/admin/alert-rules` resource). Alerts are never filed by hand: the UI (killswitch flips) and the worker (analysis consumer + alerts cron) raise them, keyed by `(source, dedupeKey)` so re-raising refreshes the active row and a clearing condition auto-resolves it.
+    One FIRED alert — an INSTANCE of a condition the platform observed, not the rule that defines it (alert *rules* are the `/api/admin/alert-rules` resource). Instances are never filed by hand: the UI (killswitch flips) and the worker (analysis consumer + alerts cron) open them, keyed by `(source, dedupeKey)`, and at most one instance per condition is open at a time — re-raising refreshes the open one, and the condition clearing closes it.
+
+    An instance IS an ops queue item (`/api/admin/ops` with `type: "alert"`) seen through the alert lens: same `id`, `severity` is that item's `priority`, and `status` is its work status projected onto three states. Resolving the queue item and clearing the alert are therefore the same act.
 
     Every field is always present on the wire; nullable fields are `null`, never absent.
   properties:
     id:
       type: string
-      description: Stable opaque alert id.
+      description: Stable opaque instance id — also the id of the ops queue item this instance is.
     source:
       type: string
       enum:
@@ -30,10 +32,10 @@ AlertApiRow:
         - danger
         - warn
         - info
-      description: How loud the alert is — `danger` pages, `warn` is the default, `info` is FYI-only.
+      description: How loud the alert is — `danger` pages, `warn` is the default, `info` is FYI-only. Severity belongs to the RULE and seeds the instance's queue `priority` (`danger`→`critical`, `warn`→`high`, `info`→`medium`); it is read back from there, so re-prioritising the queue item changes what this reports.
     dedupeKey:
       type: string
-      description: Idempotency + reconcile key within `(project, source)` — re-raising the same condition refreshes the existing active row instead of stacking duplicates, and the condition clearing flips that row to `resolved`.
+      description: Idempotency + reconcile key within `(project, source)` — re-raising the same condition refreshes the open instance instead of stacking duplicates, and the condition clearing closes it. A later firing of the same condition opens a NEW instance with its own `id`.
     title:
       type: string
       description: Short human-readable headline (what fired).
@@ -56,10 +58,10 @@ AlertApiRow:
         - active
         - resolved
         - dismissed
-      description: Lifecycle state. `active` means the condition currently holds (shown as "Firing" in the UI); `resolved` means it cleared (auto, when the raiser reconciles, or by hand); `dismissed` means a human waved it off.
+      description: 'Lifecycle state, projected from the queue item''s work status. `active` means the item is still open, i.e. the condition holds (shown as "Firing" in the UI); `resolved` means it cleared (auto, when the raiser reconciles, or by hand); `dismissed` means a human waved it off (the item is closed `wont_fix`).'
     createdAt:
       type: string
-      description: ISO-8601 timestamp the alert was first raised.
+      description: ISO-8601 timestamp this instance opened — when the condition started firing.
     resolvedAt:
       description: ISO-8601 timestamp the alert flipped to `resolved`, or `null` while it hasn't.
       anyOf:
@@ -121,7 +123,7 @@ UpdateAlertRequest:
         - active
         - resolved
         - dismissed
-      description: New lifecycle state. `resolved` / `dismissed` stamp their timestamp; `active` re-opens and clears both.
+      description: New lifecycle state, written through to the queue item (`resolved` / `wont_fix` / `open`). `resolved` / `dismissed` stamp their timestamp; `active` re-opens and clears both.
     assigneeId:
       description: PERSON owner — a `users.id`, or `null` to clear the assignment.
       anyOf:

package/spec/components/schemas/common.yaml

@@ -95,8 +95,8 @@ ExperimentInlineMetric:
     event: { type: string, minLength: 1, maxLength: 256, description: Event name to build the metric from server-side. Auto-created if missing. }
     aggregation:
       type: string
-      enum: [count_users, count_events, retention_7d, retention_30d, sum, avg]
-      description: Reducer for the `event` form. Defaults to `count_users`.
+      enum: [count_events, sum, avg]
+      description: "Reducer for the `event` form. Defaults to `count_events`. `count_users` was removed: Analytics Engine samples rows and weights the survivors, and a distinct count cannot be reweighted, so it under-reports by the sample interval. `retention_7d` / `retention_30d` were removed on 2026-08-10: the day count reached no query and no reducer, so both produced the same number as a distinct user count and reported it as a returning-user rate."
     value: { type: string, minLength: 1, maxLength: 256, description: Numeric event property for `sum`/`avg` (with `event`). }
     min_effect_of_interest:
       description: Per-experiment override of the metric's default minimum effect of interest (relative, 0–1) — the smallest change worth acting on for this experiment's decision. `null`/omitted inherits the metric default. For a guardrail, the non-inferiority margin.