@shipeasy/openapi 1.5.0 → 2.1.0

package/spec/paths/events.yaml

@@ -0,0 +1,366 @@
+/api/admin/events:
+  get:
+    operationId: listEvents
+    summary: List events
+    description: |-
+      Returns every catalogued event in the project, including pending auto-discovered names. Each row carries its own `pending` flag, so the unapproved queue can be filtered client-side.
+
+      **Use case:** Snapshot the event catalog — for example to review the pending auto-discovery queue before approving names, or to confirm which events your metrics can reference.
+    tags:
+      - Events
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    responses:
+      "200":
+        description: List events
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/events.yaml#/ListEventsResponse
+            example:
+              - id: evt_01j7w8a1b2c3d4e5f6g7h8i9j0
+                name: checkout_completed
+                folder: checkout
+                description: Fired when a customer finishes checkout.
+                properties:
+                  - name: amount
+                    type: number
+                    required: true
+                    description: ""
+                pending: 0
+                createdAt: 2026-04-12T10:14:08.000Z
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+    x-cli:
+      name: list
+  post:
+    operationId: createEvent
+    summary: Register an event
+    description: |-
+      Registers a new event name and (optionally) its typed properties. Only `name` is required.
+
+      If the name matches an existing **pending** (auto-discovered) row, this approves that row instead of returning a conflict. Otherwise an already-registered name returns `409`.
+
+      **Use cases**
+
+      - **Register a known event** — `{ "name": "checkout_completed" }` so metrics can reference it.
+      - **Declare typed properties** — supply `properties` to document the event's payload shape.
+    tags:
+      - Events
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/events.yaml#/CreateEventRequest
+          examples:
+            minimal:
+              summary: Minimal — name only
+              description: Smallest valid body. Registers the event with no properties.
+              value:
+                name: checkout_completed
+            withProperty:
+              summary: With a typed, required property
+              description: Declare a required numeric `amount` property and file it under `checkout`.
+              value:
+                name: purchase
+                folder: checkout
+                properties:
+                  - name: amount
+                    type: number
+                    required: true
+    responses:
+      "201":
+        description: Register an event
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/events.yaml#/CreateEventResponse
+            example:
+              id: evt_01j7w8a1b2c3d4e5f6g7h8i9j0
+              name: checkout_completed
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - ALREADY_EXISTS
+      - VALIDATION
+    x-cli:
+      name: create
+      positional:
+        - name
+/api/admin/events/{id}:
+  get:
+    operationId: getEvent
+    summary: Get an event
+    description: |-
+      Returns one event's full detail. Resolves by exact id, unique id-prefix, or exact (unique) name.
+
+      **Use case:** Inspect one event's declared properties and pending state by id or name.
+    tags:
+      - Events
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque event id (`evt_…`) or the event's `name`.
+        schema:
+          type: string
+    responses:
+      "200":
+        description: Get an event
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/events.yaml#/GetEventResponse
+            example:
+              id: evt_01j7w8a1b2c3d4e5f6g7h8i9j0
+              name: checkout_completed
+              folder: checkout
+              description: Fired when a customer finishes checkout.
+              properties:
+                - name: amount
+                  type: number
+                  required: true
+                  description: ""
+              pending: 0
+              createdAt: 2026-04-12T10:14:08.000Z
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+    x-cli:
+      name: get
+      positional:
+        - id
+  patch:
+    operationId: updateEvent
+    summary: Update an event
+    description: |-
+      Partial update of an event's folder, description, or properties. `name` is immutable.
+
+      `properties` replaces the full set (no merge) — omit it to leave properties unchanged.
+
+      **Use case:** Refile an event, update its description, or redeclare its typed properties.
+    tags:
+      - Events
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque event id (`evt_…`) or the event's `name`.
+        schema:
+          type: string
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/events.yaml#/UpdateEventRequest
+          examples:
+            refile:
+              summary: Move to a folder
+              description: File the event under `checkout`.
+              value:
+                folder: checkout
+            setProperties:
+              summary: Replace the property set
+              description: Overwrite the full property list (no merge).
+              value:
+                properties:
+                  - name: amount
+                    type: number
+                    required: true
+    responses:
+      "200":
+        description: Update an event
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/events.yaml#/UpdateEventResponse
+            example:
+              id: evt_01j7w8a1b2c3d4e5f6g7h8i9j0
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: update
+      positional:
+        - id
+  delete:
+    operationId: deleteEvent
+    summary: Archive an event
+    description: |-
+      Soft-deletes (archives) the event. Returns `409` if any metric still references it — delete those metrics first.
+
+      **Use case:** Retire an event from the catalog once no metric depends on it.
+    tags:
+      - Events
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque event id (`evt_…`) or the event's `name`.
+        schema:
+          type: string
+    responses:
+      "200":
+        description: Archive an event
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/events.yaml#/DeleteEventResponse
+            example:
+              ok: true
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - REFERENCED_IN_USE
+    x-cli:
+      name: archive
+      positional:
+        - id
+/api/admin/events/{id}/approve:
+  post:
+    operationId: approveEvent
+    summary: Approve a pending event
+    description: |-
+      Promotes a pending (auto-discovered) event to usable so metrics can query it (`pending` → `0`).
+
+      You may optionally declare the event's folder, description, or properties in the same call — the body is the same shape as update, and may be empty.
+
+      **Use case:** Clear an auto-discovered event out of the pending queue so metrics defined on it start resolving.
+    tags:
+      - Events
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque event id (`evt_…`) or the event's `name`.
+        schema:
+          type: string
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/events.yaml#/ApproveEventRequest
+          examples:
+            bare:
+              summary: Approve as-is
+              description: Promote the pending event with no further changes.
+              value: {}
+            withProperties:
+              summary: Approve and declare properties
+              description: Promote the event and document its payload shape at the same time.
+              value:
+                folder: checkout
+                properties:
+                  - name: amount
+                    type: number
+                    required: true
+    responses:
+      "200":
+        description: Approve a pending event
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/events.yaml#/ApproveEventResponse
+            example:
+              id: evt_01j7w8a1b2c3d4e5f6g7h8i9j0
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: approve
+      positional:
+        - id