@shipeasy/openapi 1.6.0 → 2.1.0

package/spec/components/schemas/errors-api.yaml

@@ -0,0 +1,209 @@
+ErrorRecord:
+  type: object
+  description: |-
+    A tracked production error — one row per distinct issue, keyed by `fingerprint`. Rows are never created by hand: an ingestion path (worker log drain / the `see()` SDK reporter) folds each occurrence into the matching row, bumping `count` and `lastSeenAt`. The admin surface only lists them, reads one, and flips `status`.
+
+    Field names are camelCase (the D1 row projected through Drizzle). Many columns are nullable because the reporting source may not supply them.
+  properties:
+    id:
+      type: string
+      description: Stable opaque error id.
+    projectId:
+      type: string
+      description: Project this issue belongs to.
+    fingerprint:
+      type: string
+      description: Stable dedupe key (hash of `errorType` + normalized `message` + consequence). Unique per project — every occurrence with the same fingerprint folds into this one row.
+    causedByFingerprint:
+      description: Fingerprint of the issue this one descends from — set when `see()` reported the same error (re-throw) or its `{ cause }` (wrap) at an inner boundary first. Points at another error's `fingerprint` in the same project (soft reference, no FK). `null` for a root issue.
+      anyOf:
+        - type: string
+        - type: "null"
+    message:
+      type: string
+      description: Error message text.
+    errorType:
+      description: Error class/name, e.g. `TypeError`. `null` when the source didn't supply one.
+      anyOf:
+        - type: string
+        - type: "null"
+    stack:
+      description: Stack trace of the latest occurrence, or `null` if none was captured.
+      anyOf:
+        - type: string
+        - type: "null"
+    source:
+      description: Where it surfaced — Worker name (`shipeasy`, `shipeasy-worker`) or `sdk-client` / `sdk-server`. `null` if unknown.
+      anyOf:
+        - type: string
+        - type: "null"
+    url:
+      description: Latest occurrence's raw URL (with ids intact), or `null`.
+      anyOf:
+        - type: string
+        - type: "null"
+    seenUrls:
+      description: 'Distinct, id-normalized route templates this issue has surfaced on, as a JSON-encoded string array (e.g. `["https://app/dashboard/#/gates"]`). UUIDs / numeric ids / opaque tokens are collapsed to `#` so the same route under different ids counts once. `null` if none recorded.'
+      anyOf:
+        - type: string
+        - type: "null"
+    subject:
+      description: Consequence subject — `<errorType> causes the <subject> to <outcome>`. `null` if no consequence was reported.
+      anyOf:
+        - type: string
+        - type: "null"
+    outcome:
+      description: Consequence outcome — see `subject`. `null` if no consequence was reported.
+      anyOf:
+        - type: string
+        - type: "null"
+    side:
+      description: Which SDK side reported it — `client` or `server`. `null` if unknown.
+      anyOf:
+        - type: string
+        - type: "null"
+    env:
+      description: Published env the reporting SDK ran against (e.g. `dev`, `staging`, `prod`). `null` if unknown.
+      anyOf:
+        - type: string
+        - type: "null"
+    kind:
+      description: "`see()` error kind. `null` when the source didn't classify the occurrence."
+      anyOf:
+        - type: string
+          enum:
+            - caught
+            - uncaught
+            - unhandled_rejection
+            - network
+            - violation
+        - type: "null"
+    lastExtrasJson:
+      description: Latest occurrence's sanitized extras, JSON-encoded. `null` if none.
+      anyOf:
+        - type: string
+        - type: "null"
+    sdkVersion:
+      description: "`@shipeasy/sdk` version of the latest occurrence, or `null`."
+      anyOf:
+        - type: string
+        - type: "null"
+    count:
+      type: integer
+      minimum: 1
+      description: Number of folded occurrences for this fingerprint.
+    status:
+      type: string
+      enum:
+        - open
+        - resolved
+        - ignored
+      description: "Triage state. `open` is the default; a `resolved` error reopens automatically (ingestion-side) if it recurs; `ignored` is sticky until flipped back here."
+    firstSeenAt:
+      type: string
+      description: ISO-8601 timestamp of the first folded occurrence.
+    lastSeenAt:
+      type: string
+      description: ISO-8601 timestamp of the most recent folded occurrence. Rows are ordered by this, descending.
+    createdAt:
+      type: string
+      description: ISO-8601 timestamp the row was created.
+    updatedAt:
+      type: string
+      description: ISO-8601 timestamp of the last mutation (e.g. a status flip).
+  required:
+    - id
+    - projectId
+    - fingerprint
+    - message
+    - count
+    - status
+    - firstSeenAt
+    - lastSeenAt
+    - createdAt
+    - updatedAt
+  additionalProperties: false
+ListErrorsResponse:
+  type: array
+  description: A bare JSON array of tracked errors, ordered by `lastSeenAt` descending. There is no pagination envelope — `limit` caps the page size.
+  items:
+    $ref: "#/ErrorRecord"
+UpdateErrorStatusRequest:
+  type: object
+  description: Body for `PATCH /api/admin/errors/{id}`. The only mutable field is `status` (open ⇄ resolved ⇄ ignored).
+  properties:
+    status:
+      type: string
+      enum:
+        - open
+        - resolved
+        - ignored
+      description: New triage state. `resolved` reopens automatically on recurrence; `ignored` is sticky.
+  required:
+    - status
+  additionalProperties: false
+FileErrorTicketResponse:
+  type: object
+  description: |-
+    The feedback ticket that tracks this error. Idempotent — if an open `error` ticket already tracks this fingerprint (hand- or auto-filed), the existing one is returned instead of creating a duplicate.
+  properties:
+    id:
+      type: string
+      description: Feedback ticket id.
+    number:
+      type: integer
+      description: Human-facing per-project ticket number.
+  required:
+    - id
+    - number
+  additionalProperties: false
+ErrorSeriesRequest:
+  type: object
+  description: |-
+    Time window for the occurrence series. Bounds are epoch **seconds** (Analytics Engine stores the occurrence timestamp in seconds). `to` must be strictly greater than `from`.
+  properties:
+    from:
+      type: integer
+      minimum: 0
+      description: Window start, epoch seconds (inclusive).
+    to:
+      type: integer
+      minimum: 0
+      description: Window end, epoch seconds (exclusive). Must be greater than `from`.
+    bucket:
+      type: integer
+      minimum: 60
+      maximum: 86400
+      default: 3600
+      description: Bucket width in seconds (60s–86400s/1d). Defaults to `3600` (hourly). Each returned point is floor-aligned to this width.
+  required:
+    - from
+    - to
+  additionalProperties: false
+ErrorSeriesResponse:
+  type: object
+  description: Bucketed occurrence counts for one tracked error (by its fingerprint), plus the Analytics Engine SQL that produced them.
+  properties:
+    sql:
+      type: string
+      description: The Analytics Engine SQL executed to produce `rows` (echoed for transparency / debugging).
+    rows:
+      type: array
+      description: Bucketed occurrence series, ordered by `t` ascending.
+      items:
+        type: object
+        properties:
+          t:
+            type: integer
+            description: Bucket start, epoch seconds, floor-aligned to `bucket`.
+          v:
+            type: number
+            description: Occurrence count in the bucket (sample-interval weighted).
+        required:
+          - t
+          - v
+        additionalProperties: true
+  required:
+    - sql
+    - rows
+  additionalProperties: false

package/spec/components/schemas/events.yaml

@@ -0,0 +1,321 @@
+ListEventsResponse:
+  type: array
+  items:
+    type: object
+    properties:
+      id:
+        type: string
+        description: Stable opaque event id.
+      name:
+        type: string
+        description: Event name — the handle metric queries reference.
+      folder:
+        anyOf:
+          - description: "Optional folder name used to group items in the dashboard. Part of the SDK lookup key: an item in folder `checkout` named `new-cart` is referenced as `checkout/new-cart` from the SDK."
+            anyOf:
+              - type: string
+                maxLength: 256
+                pattern: ^[a-zA-Z0-9_-]+$
+              - type: "null"
+          - type: "null"
+        description: Folder the event is filed under, or `null` if at the root.
+      description:
+        anyOf:
+          - type: string
+          - type: "null"
+        description: Human-readable description, or `null` if none set.
+      properties:
+        type: array
+        items:
+          type: object
+          properties:
+            name:
+              type: string
+              minLength: 1
+              maxLength: 64
+              description: Property key, e.g. `amount` or `plan`.
+            type:
+              type: string
+              enum:
+                - string
+                - number
+                - boolean
+              description: Value type of the property as recorded on the event.
+            required:
+              default: false
+              description: Whether the property must be present on every emitted event.
+              type: boolean
+            description:
+              default: ""
+              description: Human-readable description of the property.
+              type: string
+          required:
+            - name
+            - type
+          additionalProperties: false
+          description: One typed property declared on a catalogued event.
+        description: Typed properties declared on the event.
+      pending:
+        type: integer
+        minimum: -9007199254740991
+        maximum: 9007199254740991
+        description: "`1` if this is an auto-discovered name awaiting approval (metrics on it fail until approved), `0` if approved/usable."
+      createdAt:
+        type: string
+        description: ISO-8601 timestamp of creation.
+    required:
+      - id
+      - name
+      - description
+      - properties
+      - pending
+      - createdAt
+    additionalProperties: false
+    description: A catalogued event.
+  description: Every catalogued event in the project (including pending auto-discovered names).
+GetEventResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Stable opaque event id.
+    name:
+      type: string
+      description: Event name — the handle metric queries reference.
+    folder:
+      anyOf:
+        - description: "Optional folder name used to group items in the dashboard. Part of the SDK lookup key: an item in folder `checkout` named `new-cart` is referenced as `checkout/new-cart` from the SDK."
+          anyOf:
+            - type: string
+              maxLength: 256
+              pattern: ^[a-zA-Z0-9_-]+$
+            - type: "null"
+        - type: "null"
+      description: Folder the event is filed under, or `null` if at the root.
+    description:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Human-readable description, or `null` if none set.
+    properties:
+      type: array
+      items:
+        type: object
+        properties:
+          name:
+            type: string
+            minLength: 1
+            maxLength: 64
+            description: Property key, e.g. `amount` or `plan`.
+          type:
+            type: string
+            enum:
+              - string
+              - number
+              - boolean
+            description: Value type of the property as recorded on the event.
+          required:
+            default: false
+            description: Whether the property must be present on every emitted event.
+            type: boolean
+          description:
+            default: ""
+            description: Human-readable description of the property.
+            type: string
+        required:
+          - name
+          - type
+        additionalProperties: false
+        description: One typed property declared on a catalogued event.
+      description: Typed properties declared on the event.
+    pending:
+      type: integer
+      minimum: -9007199254740991
+      maximum: 9007199254740991
+      description: "`1` if this is an auto-discovered name awaiting approval (metrics on it fail until approved), `0` if approved/usable."
+    createdAt:
+      type: string
+      description: ISO-8601 timestamp of creation.
+  required:
+    - id
+    - name
+    - description
+    - properties
+    - pending
+    - createdAt
+  additionalProperties: false
+  description: A catalogued event.
+CreateEventRequest:
+  type: object
+  properties:
+    name:
+      type: string
+      pattern: ^[a-zA-Z0-9_][a-zA-Z0-9_\-.]{0,127}$
+      description: Event name. Starts with a letter, digit, or `_`; letters, digits, `_`, `-`, `.`; max 128 chars. Immutable after create — this is the handle metric queries reference.
+    folder:
+      $ref: ./common.yaml#/Folder
+    description:
+      description: Optional human-readable description of the event.
+      type: string
+    properties:
+      default: []
+      description: Typed properties declared on the event. Defaults to an empty list.
+      type: array
+      items:
+        type: object
+        properties:
+          name:
+            type: string
+            minLength: 1
+            maxLength: 64
+            description: Property key, e.g. `amount` or `plan`.
+          type:
+            type: string
+            enum:
+              - string
+              - number
+              - boolean
+            description: Value type of the property as recorded on the event.
+          required:
+            default: false
+            description: Whether the property must be present on every emitted event.
+            type: boolean
+          description:
+            default: ""
+            description: Human-readable description of the property.
+            type: string
+        required:
+          - name
+          - type
+        additionalProperties: false
+        description: One typed property declared on a catalogued event.
+  required:
+    - name
+  additionalProperties: false
+  description: Body for `POST /api/admin/events`. Only `name` is required.
+CreateEventResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Newly assigned event id.
+    name:
+      type: string
+      description: The event name that was registered.
+  required:
+    - id
+    - name
+  additionalProperties: false
+  description: Result of creating (or approving an existing pending) event.
+UpdateEventRequest:
+  type: object
+  properties:
+    folder:
+      $ref: ./common.yaml#/Folder
+    description:
+      description: New description for the event.
+      type: string
+    properties:
+      description: Replaces the full property set (no merge). Omit to leave properties unchanged.
+      type: array
+      items:
+        type: object
+        properties:
+          name:
+            type: string
+            minLength: 1
+            maxLength: 64
+            description: Property key, e.g. `amount` or `plan`.
+          type:
+            type: string
+            enum:
+              - string
+              - number
+              - boolean
+            description: Value type of the property as recorded on the event.
+          required:
+            default: false
+            description: Whether the property must be present on every emitted event.
+            type: boolean
+          description:
+            default: ""
+            description: Human-readable description of the property.
+            type: string
+        required:
+          - name
+          - type
+        additionalProperties: false
+        description: One typed property declared on a catalogued event.
+  additionalProperties: false
+  description: Body for `PATCH /api/admin/events/{id}` and `POST /api/admin/events/{id}/approve`. All fields optional; `name` is immutable after create.
+UpdateEventResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Event id that was updated.
+  required:
+    - id
+  additionalProperties: false
+  description: Result of updating or approving an event.
+ApproveEventRequest:
+  type: object
+  properties:
+    folder:
+      $ref: ./common.yaml#/Folder
+    description:
+      description: New description for the event.
+      type: string
+    properties:
+      description: Replaces the full property set (no merge). Omit to leave properties unchanged.
+      type: array
+      items:
+        type: object
+        properties:
+          name:
+            type: string
+            minLength: 1
+            maxLength: 64
+            description: Property key, e.g. `amount` or `plan`.
+          type:
+            type: string
+            enum:
+              - string
+              - number
+              - boolean
+            description: Value type of the property as recorded on the event.
+          required:
+            default: false
+            description: Whether the property must be present on every emitted event.
+            type: boolean
+          description:
+            default: ""
+            description: Human-readable description of the property.
+            type: string
+        required:
+          - name
+          - type
+        additionalProperties: false
+        description: One typed property declared on a catalogued event.
+  additionalProperties: false
+  description: Body for `PATCH /api/admin/events/{id}` and `POST /api/admin/events/{id}/approve`. All fields optional; `name` is immutable after create.
+ApproveEventResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Event id that was updated.
+  required:
+    - id
+  additionalProperties: false
+  description: Result of updating or approving an event.
+DeleteEventResponse:
+  type: object
+  properties:
+    ok:
+      type: boolean
+      const: true
+  required:
+    - ok
+  additionalProperties: false
+  description: Confirmation that the event was archived.