@shipeasy/openapi 1.6.0 → 2.1.0

package/spec/components/schemas/common.yaml

@@ -0,0 +1,87 @@
+# Cross-cutting shared schemas referenced from multiple resources.
+Env:
+  type: string
+  enum:
+    - dev
+    - staging
+    - prod
+  description: Target environment. One of the project's configured envs (`dev`, `staging`, `prod`).
+Folder:
+  anyOf:
+    - type: string
+      maxLength: 256
+      pattern: ^[a-zA-Z0-9_-]+$
+    - type: "null"
+  description: Optional folder name grouping items in the dashboard. Alphanumeric, `_` or `-` (no `/`). Part of the SDK lookup key (`<folder>/<name>`).
+MetricName:
+  type: string
+  maxLength: 128
+  pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
+  description: Stable metric key. Single segment or `folder.name`; lowercase letters, digits, `_`/`-`; max 128 chars.
+ConfigName:
+  type: string
+  maxLength: 128
+  pattern: ^(?:_default|[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?$
+  description: Stable config/killswitch key in `folder.name` form (two lowercase segments separated by a dot, e.g. `pricing.tiers`). Immutable after create.
+NotificationTarget:
+  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"
+      additionalProperties: false
+    - type: "null"
+  description: Delivery target for a notification; `null` = use the project default.
+PageQuery:
+  type: object
+  properties:
+    limit:
+      type: integer
+      minimum: 1
+      maximum: 500
+      default: 100
+      description: Max rows to return (1–500, default 100).
+    cursor:
+      type: string
+      minLength: 1
+      description: Opaque keyset cursor from a previous page's `next_cursor`.
+  additionalProperties: false
+  description: Query params for any paginated list endpoint.
+KillswitchValue:
+  type: object
+  properties:
+    value:
+      type: boolean
+      description: Default boolean delivered when no `switches` entry matches.
+    switches:
+      type: object
+      additionalProperties: { type: boolean }
+      description: Per-switch overrides; a matching key takes precedence over `value`.
+  required: [value]
+  additionalProperties: false
+  description: Runtime killswitch payload returned to SDKs.
+ExperimentInlineMetric:
+  type: object
+  properties:
+    name: { $ref: "#/MetricName" }
+    query: { type: string, minLength: 1, maxLength: 4096, description: Metric DSL string. Provide this OR `event`. }
+    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`.
+    value: { type: string, minLength: 1, maxLength: 256, description: Numeric event property for `sum`/`avg` (with `event`). }
+  additionalProperties: false
+  description: Inline metric — a DSL `query`, or an `event` (+ `aggregation`/`value`) the server compiles into one.

package/spec/components/schemas/configs.yaml

@@ -0,0 +1,371 @@
+ListConfigsResponse:
+  type: object
+  properties:
+    data:
+      type: array
+      items:
+        type: object
+        properties:
+          id:
+            type: string
+            description: Stable opaque config id (`cfg_…`).
+          name:
+            type: string
+            maxLength: 128
+            description: Stable config key in `folder.name` form (two lowercase segments separated by a dot, e.g. `pricing.tiers`). Used by SDKs as `Shipeasy.getConfig('<name>')`. Immutable after create.
+          description:
+            anyOf:
+              - type: string
+              - type: "null"
+          schema:
+            type: object
+            additionalProperties: {}
+            description: JSON Schema (draft 2020-12) describing the shape of the config value. Top-level `type` must be `'object'`; every published value is validated against this schema.
+          updatedAt:
+            type: string
+            description: ISO-8601 timestamp of last mutation.
+          envs:
+            type: object
+            additionalProperties:
+              type: object
+              properties:
+                version:
+                  type: integer
+                  minimum: -9007199254740991
+                  maximum: 9007199254740991
+                  description: Monotonically increasing version per env.
+                publishedAt:
+                  type: string
+                  description: ISO-8601 publish timestamp.
+                publishedBy:
+                  type: string
+                  description: Email/id of the actor who published this version.
+              required:
+                - version
+                - publishedAt
+                - publishedBy
+              additionalProperties: false
+            description: Per-env latest published version metadata.
+          drafts:
+            type: object
+            additionalProperties:
+              type: object
+              properties:
+                updatedAt:
+                  type: string
+                  description: ISO-8601 last-edit timestamp on the draft.
+                authorEmail:
+                  type: string
+                  description: Email/id of the actor who last edited the draft.
+                baseVersion:
+                  type: integer
+                  minimum: -9007199254740991
+                  maximum: 9007199254740991
+                  description: Published version the draft was forked from.
+              required:
+                - updatedAt
+                - authorEmail
+                - baseVersion
+              additionalProperties: false
+            description: Per-env active drafts (if any).
+          values:
+            description: Per-env latest published values (only returned by `GET /{id}`, not list).
+            type: object
+            additionalProperties: {}
+          draftValues:
+            description: Per-env draft values (only returned by `GET /{id}`).
+            type: object
+            additionalProperties: {}
+        required:
+          - id
+          - name
+          - description
+          - schema
+          - updatedAt
+          - envs
+          - drafts
+        additionalProperties: false
+    next_cursor:
+      anyOf:
+        - type: string
+        - type: "null"
+  required:
+    - data
+    - next_cursor
+  additionalProperties: false
+GetConfigResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Stable opaque config id (`cfg_…`).
+    name:
+      type: string
+      maxLength: 128
+      description: Stable config key in `folder.name` form (two lowercase segments separated by a dot, e.g. `pricing.tiers`). Used by SDKs as `Shipeasy.getConfig('<name>')`. Immutable after create.
+    description:
+      anyOf:
+        - type: string
+        - type: "null"
+    schema:
+      type: object
+      additionalProperties: {}
+      description: JSON Schema (draft 2020-12) describing the shape of the config value. Top-level `type` must be `'object'`; every published value is validated against this schema.
+    updatedAt:
+      type: string
+      description: ISO-8601 timestamp of last mutation.
+    envs:
+      type: object
+      additionalProperties:
+        type: object
+        properties:
+          version:
+            type: integer
+            minimum: -9007199254740991
+            maximum: 9007199254740991
+            description: Monotonically increasing version per env.
+          publishedAt:
+            type: string
+            description: ISO-8601 publish timestamp.
+          publishedBy:
+            type: string
+            description: Email/id of the actor who published this version.
+        required:
+          - version
+          - publishedAt
+          - publishedBy
+        additionalProperties: false
+      description: Per-env latest published version metadata.
+    drafts:
+      type: object
+      additionalProperties:
+        type: object
+        properties:
+          updatedAt:
+            type: string
+            description: ISO-8601 last-edit timestamp on the draft.
+          authorEmail:
+            type: string
+            description: Email/id of the actor who last edited the draft.
+          baseVersion:
+            type: integer
+            minimum: -9007199254740991
+            maximum: 9007199254740991
+            description: Published version the draft was forked from.
+        required:
+          - updatedAt
+          - authorEmail
+          - baseVersion
+        additionalProperties: false
+      description: Per-env active drafts (if any).
+    values:
+      description: Per-env latest published values (only returned by `GET /{id}`, not list).
+      type: object
+      additionalProperties: {}
+    draftValues:
+      description: Per-env draft values (only returned by `GET /{id}`).
+      type: object
+      additionalProperties: {}
+  required:
+    - id
+    - name
+    - description
+    - schema
+    - updatedAt
+    - envs
+    - drafts
+  additionalProperties: false
+CreateConfigRequest:
+  type: object
+  properties:
+    name:
+      $ref: ./common.yaml#/ConfigName
+    description:
+      description: Optional free-form description shown in the dashboard. Max 512 chars.
+      type: string
+      maxLength: 512
+    folder:
+      $ref: ./common.yaml#/Folder
+    schema:
+      type: object
+      additionalProperties: {}
+      description: JSON Schema (draft 2020-12) describing the shape of the config value. Top-level `type` must be `'object'`; every published value is validated against this schema.
+    value:
+      description: "Initial config value. Either a single JSON object applied to every env, or a `{ env: value }` map seeding per-env values. Must match `schema`. Defaults to `{}` on every env when omitted."
+  required:
+    - name
+    - schema
+  additionalProperties: false
+  description: Body for `POST /api/admin/configs`. `name` + `schema` required.
+CreateConfigResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Newly assigned config id.
+    name:
+      type: string
+      maxLength: 128
+      description: Stable config key in `folder.name` form (two lowercase segments separated by a dot, e.g. `pricing.tiers`). Used by SDKs as `Shipeasy.getConfig('<name>')`. Immutable after create.
+  required:
+    - id
+    - name
+  additionalProperties: false
+UpdateConfigRequest:
+  type: object
+  properties:
+    schema:
+      description: Replacement schema. When supplied, the new schema is validated against every published value before it lands.
+      type: object
+      additionalProperties: {}
+    value:
+      description: Flat value applied to **every** env. Publishes a new version per env. To target one env, use `PUT /{id}/drafts` then `POST /{id}/publish`.
+    folder:
+      $ref: ./common.yaml#/Folder
+  additionalProperties: false
+  description: Body for `PATCH /api/admin/configs/{id}`. Partial — only supplied fields change. `value` republishes on every env.
+UpdateConfigResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Config id that was updated.
+  required:
+    - id
+  additionalProperties: false
+UpdateConfigSchemaRequest:
+  type: object
+  properties:
+    schema:
+      description: Replacement JSON Schema (draft 2020-12). Validated against every published value before it lands.
+      type: object
+      additionalProperties: {}
+  required:
+    - schema
+  additionalProperties: false
+  description: Body for `PATCH /api/admin/configs/{id}/schema`. Schema-only update — replaces the config's schema and re-validates existing values.
+UpdateConfigSchemaResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Config id whose schema was updated.
+  required:
+    - id
+  additionalProperties: false
+DeleteConfigResponse:
+  type: object
+  properties:
+    ok:
+      type: boolean
+      const: true
+  required:
+    - ok
+  additionalProperties: false
+SaveConfigDraftRequest:
+  type: object
+  properties:
+    env:
+      $ref: ./common.yaml#/Env
+    value:
+      description: Draft value to stage on `env`. Validated against the config's current schema.
+  required:
+    - env
+    - value
+  additionalProperties: false
+  description: Body for `PUT /api/admin/configs/{id}/drafts`. Stages a value for a single env without publishing.
+SaveConfigDraftResponse:
+  type: object
+  properties:
+    id:
+      type: string
+    env:
+      $ref: ./common.yaml#/Env
+    baseVersion:
+      type: integer
+      minimum: -9007199254740991
+      maximum: 9007199254740991
+      description: Published version the draft is based on.
+    updatedAt:
+      type: string
+  required:
+    - id
+    - env
+    - baseVersion
+    - updatedAt
+  additionalProperties: false
+DiscardConfigDraftRequest:
+  type: object
+  properties:
+    env:
+      $ref: ./common.yaml#/Env
+  required:
+    - env
+  additionalProperties: false
+  description: Body for `POST /api/admin/configs/{id}/publish` and `DELETE /api/admin/configs/{id}/drafts`. Names the target env.
+DiscardConfigDraftResponse:
+  type: object
+  properties:
+    ok:
+      type: boolean
+      const: true
+  required:
+    - ok
+  additionalProperties: false
+PublishConfigDraftRequest:
+  type: object
+  properties:
+    env:
+      $ref: ./common.yaml#/Env
+  required:
+    - env
+  additionalProperties: false
+  description: Body for `POST /api/admin/configs/{id}/publish` and `DELETE /api/admin/configs/{id}/drafts`. Names the target env.
+PublishConfigDraftResponse:
+  type: object
+  properties:
+    id:
+      type: string
+    env:
+      $ref: ./common.yaml#/Env
+    version:
+      type: integer
+      minimum: -9007199254740991
+      maximum: 9007199254740991
+      description: Newly published version on `env`.
+  required:
+    - id
+    - env
+    - version
+  additionalProperties: false
+ListConfigActivityResponse:
+  type: array
+  items:
+    type: object
+    properties:
+      id:
+        type: string
+      action:
+        type: string
+        description: Audit action (e.g. `config.create`, `config.publish`).
+      actorEmail:
+        type: string
+      actorType:
+        type: string
+        enum:
+          - user
+          - cli
+          - system
+      payload: {}
+      createdAt:
+        type: string
+        description: ISO-8601 timestamp.
+    required:
+      - id
+      - action
+      - actorEmail
+      - actorType
+      - payload
+      - createdAt
+    additionalProperties: false
+  description: Recent audit rows for one config, newest first.