@shipeasy/openapi 1.6.0 → 2.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipeasy/openapi",
-  "version": "1.6.0",
-  "description": "Shipeasy admin OpenAPI spec + typed client. Single source of truth for endpoint paths, request/response shapes, and the resource registry consumed by @shipeasy/cli and @shipeasy/mcp.",
+  "version": "2.1.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",
   "types": "./dist/index.d.ts",
@@ -10,7 +10,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/shipeasy-ai/openapi.git"
+    "url": "git+https://github.com/shipeasy-ai/shipeasy.git",
+    "directory": "openapi"
   },
   "license": "MIT",
   "exports": {
@@ -18,51 +19,57 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./resources/*": {
-      "types": "./dist/resources/*.d.ts",
-      "default": "./dist/resources/*.js"
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
     },
-    "./schemas/*": {
-      "types": "./dist/schemas/*.d.ts",
-      "default": "./dist/schemas/*.js"
+    "./schemas": {
+      "types": "./dist/schemas.d.ts",
+      "default": "./dist/schemas.js"
     },
-    "./operations": {
-      "types": "./dist/operations/index.d.ts",
-      "default": "./dist/operations/index.js"
-    },
-    "./transport": {
-      "types": "./dist/transport.d.ts",
-      "default": "./dist/transport.js"
-    },
-    "./pagination": {
-      "types": "./dist/pagination.d.ts",
-      "default": "./dist/pagination.js"
+    "./custom": {
+      "types": "./dist/custom.d.ts",
+      "default": "./dist/custom.js"
     },
     "./node-context": {
       "types": "./dist/node-context.d.ts",
       "default": "./dist/node-context.js"
-    }
+    },
+    "./codegen": {
+      "types": "./src/codegen.ts",
+      "default": "./src/codegen.ts"
+    },
+    "./openapi.yaml": "./openapi.yaml",
+    "./openapi.json": "./openapi.json"
   },
   "files": [
     "dist/",
-    "openapi.json"
+    "openapi.yaml",
+    "openapi.json",
+    "spec/"
   ],
   "scripts": {
+    "lint:spec": "redocly lint spec/openapi.yaml",
+    "bundle": "redocly bundle spec/openapi.yaml -o openapi.yaml && redocly bundle spec/openapi.yaml -o openapi.json",
+    "gen:sdk": "openapi-ts",
+    "gen": "pnpm bundle && pnpm gen:sdk",
+    "prebuild": "pnpm gen",
     "build": "tsup",
     "type-check": "tsc --noEmit",
     "test": "vitest run",
-    "emit-openapi": "tsx scripts/emit-spec.ts"
+    "check:drift": "node scripts/check-drift.mjs"
   },
   "dependencies": {
     "zod": "^4.0.0"
   },
   "devDependencies": {
+    "@hey-api/openapi-ts": "^0.99.0",
+    "@redocly/cli": "^2.0.0",
     "@types/node": "^20.19.39",
-    "openapi-types": "^12.1.3",
     "tsup": "^8.3.0",
-    "tsx": "^4.21.0",
     "typescript": "^5.7.4",
-    "vitest": "^2.1.0"
+    "vitest": "^2.1.0",
+    "yaml": "^2.5.0"
   },
   "engines": {
     "node": ">=20"

package/spec/components/errors.yaml

@@ -0,0 +1,53 @@
+ErrorCode:
+  type: string
+  description: Stable, machine-readable error code. Mirrors the `ErrorCode` catalogue in `@shipeasy/core`. Each operation lists the subset it can return under `x-error-codes`.
+  enum:
+    - BAD_REQUEST
+    - UNAUTHORIZED
+    - FORBIDDEN
+    - PLAN_REQUIRED
+    - NOT_FOUND
+    - ALREADY_EXISTS
+    - INVALID_TRANSITION
+    - IMMUTABLE_FIELD
+    - READ_ONLY
+    - REFERENCED_IN_USE
+    - VALIDATION
+    - REFERENCED_NOT_FOUND
+    - GROUPS_WEIGHT_SUM
+    - EVENT_PENDING
+    - INTERNAL
+  x-enum-descriptions:
+    BAD_REQUEST: Malformed request (bad JSON, missing project scope).
+    UNAUTHORIZED: Missing or invalid admin SDK key.
+    FORBIDDEN: Key is valid but not allowed to act on this project.
+    PLAN_REQUIRED: The requested feature requires a higher plan tier (e.g. sequential testing, custom alpha, holdout, group count).
+    NOT_FOUND: The resource does not exist or is not visible to the caller.
+    ALREADY_EXISTS: A resource with this name already exists in the project.
+    INVALID_TRANSITION: The requested lifecycle transition is not allowed from the current state.
+    IMMUTABLE_FIELD: A field that is immutable in the current state was modified (e.g. editing allocation while running).
+    READ_ONLY: The resource is a read-only built-in (e.g. a built-in gate-rule template) and cannot be modified or deleted.
+    REFERENCED_IN_USE: The resource cannot be archived/deleted while another resource still references it.
+    VALIDATION: The request body failed structural (schema) validation.
+    REFERENCED_NOT_FOUND: A referenced entity (universe, metric, gate, event) does not exist.
+    GROUPS_WEIGHT_SUM: Experiment group weights must sum to 10000 (basis points).
+    EVENT_PENDING: The referenced event is still pending review and cannot back a metric yet.
+    INTERNAL: Unexpected server error.
+Error:
+  type: object
+  description: Uniform error envelope returned by every admin endpoint on a non-2xx status. `error` is the human-readable message; `code` is the stable machine code (present whenever the failure maps to a catalogued `ErrorCode`); `detail` carries extra context (validation paths, conflicting field); `instructions` is optional actionable guidance for resolving the error.
+  required:
+    - error
+  additionalProperties: false
+  properties:
+    error:
+      type: string
+      description: Human-readable error message.
+    code:
+      $ref: ./errors.yaml#/ErrorCode
+    detail:
+      type: string
+      description: Extra context (validation details, conflicting field, referenced row).
+    instructions:
+      type: string
+      description: Actionable guidance for resolving this error — what to check or change next.

package/spec/components/parameters.yaml

@@ -0,0 +1,24 @@
+ProjectId:
+  name: X-Project-Id
+  in: header
+  required: false
+  description: Project the request operates on. Optional — defaults to the project the SDK key belongs to; pass it only to scope a multi-project key (the generated client sets it once from its configuration, so per-call callers never thread it).
+  schema:
+    type: string
+PaginationLimit:
+  name: limit
+  in: query
+  required: false
+  description: Page size (1–500). Defaults to 100.
+  schema:
+    type: integer
+    minimum: 1
+    maximum: 500
+    default: 100
+PaginationCursor:
+  name: cursor
+  in: query
+  required: false
+  description: Opaque cursor returned in the previous page's `next_cursor`. Omit for the first page.
+  schema:
+    type: string

package/spec/components/responses.yaml

@@ -0,0 +1,107 @@
+BadRequest:
+  description: The request was malformed (bad JSON or missing project scope).
+  content:
+    application/json:
+      schema:
+        $ref: ./errors.yaml#/Error
+      examples:
+        BAD_REQUEST:
+          summary: Malformed request
+          value:
+            error: Malformed request (bad JSON, missing project scope).
+            code: BAD_REQUEST
+Unauthorized:
+  description: Missing or invalid admin SDK key.
+  content:
+    application/json:
+      schema:
+        $ref: ./errors.yaml#/Error
+      examples:
+        UNAUTHORIZED:
+          summary: No / invalid key
+          value:
+            error: Missing or invalid admin SDK key.
+            code: UNAUTHORIZED
+Forbidden:
+  description: The key is valid but not allowed to perform this action.
+  content:
+    application/json:
+      schema:
+        $ref: ./errors.yaml#/Error
+      examples:
+        FORBIDDEN:
+          summary: Not an admin of this project
+          value:
+            error: Key is valid but not allowed to act on this project.
+            code: FORBIDDEN
+        PLAN_REQUIRED:
+          summary: Feature gated behind a higher plan
+          value:
+            error: The requested feature requires a higher plan tier (e.g. sequential testing, custom alpha, holdout, group count).
+            code: PLAN_REQUIRED
+NotFound:
+  description: The resource does not exist or is not visible to the caller.
+  content:
+    application/json:
+      schema:
+        $ref: ./errors.yaml#/Error
+      examples:
+        NOT_FOUND:
+          summary: Unknown id or name
+          value:
+            error: The resource does not exist or is not visible to the caller.
+            code: NOT_FOUND
+Conflict:
+  description: The mutation conflicts with current state.
+  content:
+    application/json:
+      schema:
+        $ref: ./errors.yaml#/Error
+      examples:
+        ALREADY_EXISTS:
+          summary: Duplicate name
+          value:
+            error: A resource with this name already exists in the project.
+            code: ALREADY_EXISTS
+        REFERENCED_IN_USE:
+          summary: Still referenced by another resource
+          value:
+            error: The resource cannot be archived/deleted while another resource still references it.
+            code: REFERENCED_IN_USE
+        INVALID_TRANSITION:
+          summary: Illegal lifecycle transition
+          value:
+            error: The requested lifecycle transition is not allowed from the current state.
+            code: INVALID_TRANSITION
+        IMMUTABLE_FIELD:
+          summary: Edited an immutable field while running
+          value:
+            error: A field that is immutable in the current state was modified (e.g. editing allocation while running).
+            code: IMMUTABLE_FIELD
+UnprocessableEntity:
+  description: The request body failed validation.
+  content:
+    application/json:
+      schema:
+        $ref: ./errors.yaml#/Error
+      examples:
+        VALIDATION:
+          summary: Schema validation failed
+          value:
+            error: The request body failed structural (schema) validation.
+            code: VALIDATION
+        REFERENCED_NOT_FOUND:
+          summary: Referenced entity missing
+          value:
+            error: A referenced entity (universe, metric, gate, event) does not exist.
+            code: REFERENCED_NOT_FOUND
+        GROUPS_WEIGHT_SUM:
+          summary: Group weights must sum to 10000
+          value:
+            error: Experiment group weights must sum to 10000 (basis points).
+            code: GROUPS_WEIGHT_SUM
+        EVENT_PENDING:
+          summary: Event still pending review
+          value:
+            error: The referenced event is still pending review and cannot back a metric yet.
+            code: EVENT_PENDING

package/spec/components/schemas/alert-rules.yaml

@@ -0,0 +1,175 @@
+ListAlertRulesResponse:
+  type: array
+  items:
+    type: object
+    properties:
+      id:
+        type: string
+        description: Stable opaque alert-rule id.
+      name:
+        type: string
+        description: Human label for the rule.
+      metricId:
+        type: string
+        description: Id of the metric the rule evaluates. Immutable after create.
+      metricName:
+        anyOf:
+          - type: string
+          - type: "null"
+        description: Display name of the bound metric, or `null` if the metric no longer exists.
+      comparator:
+        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.
+      windowHours:
+        type: integer
+        minimum: -9007199254740991
+        maximum: 9007199254740991
+        description: Lookback window (hours) the metric is aggregated over.
+      severity:
+        type: string
+        enum:
+          - danger
+          - warn
+          - info
+        description: Severity of the raised alert.
+      enabled:
+        type: boolean
+        description: Whether the rule is evaluated by the cron.
+      notify:
+        $ref: ./common.yaml#/NotificationTarget
+      createdAt:
+        type: string
+        description: ISO-8601 timestamp of creation.
+      updatedAt:
+        type: string
+        description: ISO-8601 timestamp of the last update.
+    required:
+      - id
+      - name
+      - metricId
+      - metricName
+      - comparator
+      - threshold
+      - windowHours
+      - severity
+      - enabled
+      - notify
+      - createdAt
+      - updatedAt
+    additionalProperties: false
+    description: One metric-threshold alert rule.
+CreateAlertRuleRequest:
+  type: object
+  properties:
+    name:
+      type: string
+      minLength: 1
+      maxLength: 120
+      description: Human label for the rule, shown on the alert and the rules list.
+    metricId:
+      type: string
+      minLength: 1
+      description: Id of the metric to evaluate.
+    comparator:
+      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.
+    windowHours:
+      default: 24
+      description: Lookback window (hours) the metric is aggregated over. 1–720.
+      type: integer
+      minimum: 1
+      maximum: 720
+    severity:
+      default: warn
+      description: Severity of the raised alert.
+      type: string
+      enum:
+        - danger
+        - warn
+        - info
+    enabled:
+      default: true
+      description: Whether the rule is evaluated by the cron.
+      type: boolean
+    notify:
+      $ref: ./common.yaml#/NotificationTarget
+  required:
+    - name
+    - metricId
+    - comparator
+    - threshold
+  additionalProperties: false
+CreateAlertRuleResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Newly assigned alert-rule id.
+  required:
+    - id
+  additionalProperties: false
+UpdateAlertRuleRequest:
+  type: object
+  properties:
+    name:
+      type: string
+      minLength: 1
+      maxLength: 120
+    comparator:
+      type: string
+      enum:
+        - gt
+        - gte
+        - lt
+        - lte
+    threshold:
+      type: number
+    windowHours:
+      type: integer
+      minimum: 1
+      maximum: 720
+    severity:
+      type: string
+      enum:
+        - danger
+        - warn
+        - info
+    enabled:
+      type: boolean
+    notify:
+      $ref: ./common.yaml#/NotificationTarget
+  additionalProperties: false
+UpdateAlertRuleResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Newly assigned alert-rule id.
+  required:
+    - id
+  additionalProperties: false
+DeleteAlertRuleResponse:
+  type: object
+  properties:
+    ok:
+      type: boolean
+      const: true
+  required:
+    - ok
+  additionalProperties: false

package/spec/components/schemas/attributes.yaml

@@ -0,0 +1,157 @@
+ListAttributesResponse:
+  type: array
+  items:
+    type: object
+    properties:
+      name:
+        type: string
+        description: Attribute key as seen in evaluation context (e.g. `plan`, `country`).
+      type:
+        description: Inferred value type (`string`, `number`, `boolean`, …) when known.
+        type: string
+    required:
+      - name
+    additionalProperties: {}
+    description: One auto-inferred targeting attribute.
+  description: Every auto-inferred targeting attribute in the project.
+AttributeType:
+  type: string
+  enum:
+    - string
+    - number
+    - boolean
+    - enum
+    - date
+  description: Declared value type of a targeting attribute.
+CreateAttributeRequest:
+  type: object
+  properties:
+    name:
+      type: string
+      pattern: ^[a-z0-9][a-z0-9_-]{0,63}$
+      description: Attribute key (lowercase alphanumeric start, then letters/digits/`_`/`-`; max 64 chars). Immutable after create.
+    type:
+      $ref: "#/AttributeType"
+    enum_values:
+      anyOf:
+        - type: array
+          items:
+            type: string
+        - type: "null"
+      default: null
+      description: Allowed values when `type` is `enum` (required in that case — 422 otherwise); `null` for non-enum types.
+    required:
+      type: boolean
+      default: false
+      description: Whether the attribute must be present on the evaluation context.
+    description:
+      type: string
+      description: Optional human note shown in the dashboard.
+    sdk_path:
+      type: string
+      description: Optional dotted path the SDK reads the value from.
+  required:
+    - name
+    - type
+  additionalProperties: false
+  description: Body for `POST /api/admin/attributes`. Declares a targeting attribute.
+CreateAttributeResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Newly assigned attribute id.
+    name:
+      type: string
+      description: The attribute key that was created.
+  required:
+    - id
+    - name
+  additionalProperties: false
+  description: Response for `POST /api/admin/attributes`.
+UpdateAttributeRequest:
+  type: object
+  properties:
+    type:
+      $ref: "#/AttributeType"
+    enum_values:
+      anyOf:
+        - type: array
+          items:
+            type: string
+        - type: "null"
+      description: Replacement allowed values (for `enum`), or `null` to clear.
+    required:
+      type: boolean
+      description: Whether the attribute must be present on the evaluation context.
+    description:
+      type: string
+      description: Optional human note shown in the dashboard.
+    sdk_path:
+      type: string
+      description: Optional dotted path the SDK reads the value from.
+  additionalProperties: false
+  description: "Body for `PATCH /api/admin/attributes/{id}`. Every field is optional; `name` is immutable."
+UpdateAttributeResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Id of the attribute that was updated.
+  required:
+    - id
+  additionalProperties: false
+  description: Response for `PATCH /api/admin/attributes/{id}`.
+GetAttributeResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Stable opaque attribute id.
+    name:
+      type: string
+      description: Attribute key.
+    type:
+      $ref: "#/AttributeType"
+    enumValues:
+      anyOf:
+        - type: array
+          items:
+            type: string
+        - type: "null"
+      description: Allowed values for `enum` attributes, else `null`.
+    required:
+      type: integer
+      enum:
+        - 0
+        - 1
+      description: Whether the attribute is required (D1 stores the flag as `0`/`1`).
+    description:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Human note, or `null`.
+    sdkPath:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Dotted SDK path, or `null`.
+    createdAt:
+      type: string
+      description: ISO-8601 creation timestamp.
+  required:
+    - id
+    - name
+    - type
+  additionalProperties: {}
+  description: One targeting attribute row.
+DeleteAttributeResponse:
+  type: object
+  properties:
+    ok:
+      type: boolean
+      description: True when the attribute was archived.
+  required:
+    - ok
+  additionalProperties: false
+  description: Response for `DELETE /api/admin/attributes/{id}`.