@shipeasy/openapi 1.5.0 → 2.1.0

package/spec/components/schemas/i18n.yaml

@@ -0,0 +1,478 @@
+ListI18nProfilesResponse:
+  type: array
+  items:
+    type: object
+    properties:
+      id:
+        type: string
+        description: Stable opaque profile id.
+      name:
+        type: string
+        description: Profile handle, e.g. `en:prod` or `fr:prod`.
+      isDefault:
+        description: "`1` for the project's single default profile (always seeded as `en:prod`), else `0`."
+        type: number
+      createdAt:
+        description: ISO-8601 timestamp of creation.
+        type: string
+      deletedAt:
+        description: ISO-8601 soft-delete timestamp, or `null` if live.
+        anyOf:
+          - type: string
+          - type: "null"
+    required:
+      - id
+      - name
+    additionalProperties: false
+    description: One i18n locale profile.
+CreateI18nProfileRequest:
+  type: object
+  properties:
+    name:
+      type: string
+      minLength: 1
+      maxLength: 64
+      pattern: ^[a-z0-9][a-z0-9_:.-]*$
+      description: Profile handle to create, e.g. `en:prod` or `fr:prod`. Lowercase alphanumeric start, then letters/digits/`_`/`:`/`.`/`-`; max 64 chars. The locale is encoded in the handle, so no separate locale fields are accepted.
+  required:
+    - name
+  additionalProperties: false
+  description: Body for `POST /api/admin/i18n/profiles`. Only `name` is accepted.
+CreateI18nProfileResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Newly assigned profile id.
+    name:
+      type: string
+      description: Profile handle that was created.
+  required:
+    - id
+    - name
+  additionalProperties: false
+  description: Created profile id + name.
+ListI18nKeysResponse:
+  type: object
+  properties:
+    keys:
+      type: array
+      items:
+        type: object
+        properties:
+          id:
+            type: string
+            description: Stable opaque key id.
+          key:
+            type: string
+            description: Dotted key path, e.g. `home.cta`.
+          value:
+            type: string
+            description: Current translated value for the key.
+          description:
+            description: Optional human note stored with the key.
+            anyOf:
+              - type: string
+              - type: "null"
+          variables:
+            description: "`{{var}}` placeholder names in the value, or `null` when there are none."
+            anyOf:
+              - type: array
+                items:
+                  type: string
+              - type: "null"
+          profileId:
+            description: Owning profile id.
+            type: string
+          chunkId:
+            description: Owning chunk (authoring grouping) id.
+            type: string
+          updatedAt:
+            description: ISO-8601 timestamp of the last edit.
+            type: string
+          updatedBy:
+            description: Actor email that last edited the key.
+            type: string
+        required:
+          - id
+          - key
+          - value
+        additionalProperties: {}
+        description: One i18n key row.
+      description: The page of matching keys.
+    total:
+      type: number
+      description: Total matching keys across all pages (ignores `limit`/`offset`).
+  required:
+    - keys
+    - total
+  additionalProperties: false
+  description: A page of i18n keys plus the total count. (The client also tolerates a bare array.)
+PushI18nKeysRequest:
+  type: object
+  properties:
+    profile_id:
+      type: string
+      format: uuid
+      description: Target profile id to add keys to.
+    chunk:
+      description: Logical grouping the new keys are filed under. Defaults to `default`.
+      type: string
+      minLength: 1
+      maxLength: 64
+      default: default
+    keys:
+      type: array
+      minItems: 1
+      maxItems: 5000
+      items:
+        type: object
+        properties:
+          key:
+            type: string
+            minLength: 1
+            maxLength: 256
+            description: Dotted key path, e.g. `home.cta`.
+          value:
+            type: string
+            description: Translated value for the key.
+          description:
+            type: string
+            description: Optional human note stored with the key.
+          variables:
+            type: array
+            maxItems: 32
+            items:
+              type: string
+              minLength: 1
+              maxLength: 64
+            description: Optional explicit list of `{{var}}` placeholder names in the value. Auto-derived from the value when omitted.
+        required:
+          - key
+          - value
+        additionalProperties: false
+      description: Keys to add. Insert-only — existing keys are reported back as `skipped`.
+  required:
+    - profile_id
+    - keys
+  additionalProperties: false
+  description: "Body for `POST /api/admin/i18n/keys`. Insert-only: keys that already exist are never overwritten — use `PUT /keys/{id}` to change a value."
+PushI18nKeysResponse:
+  type: object
+  properties:
+    added:
+      type: array
+      items:
+        type: string
+      description: Key names that were newly inserted.
+    skipped:
+      type: array
+      items:
+        type: string
+      description: Key names that already existed and were left untouched.
+    pushed_count:
+      type: number
+      description: Number of keys inserted (== `added.length`).
+    skipped_count:
+      type: number
+      description: Number of keys skipped (== `skipped.length`).
+    chunk:
+      description: The chunk the keys were filed under.
+      type: string
+  required:
+    - added
+    - skipped
+    - pushed_count
+    - skipped_count
+  additionalProperties: false
+  description: Result of an insert-only key push.
+UpdateI18nKeyRequest:
+  type: object
+  properties:
+    value:
+      type: string
+      description: New value for the key (the only overwrite path).
+    description:
+      description: Optional human note to store with the key.
+      type: string
+    variables:
+      description: Explicit `{{var}}` placeholder names in the value. Omit to auto-derive them from the value.
+      type: array
+      maxItems: 32
+      items:
+        type: string
+        minLength: 1
+        maxLength: 64
+  required:
+    - value
+  additionalProperties: false
+  description: Body for `PUT /api/admin/i18n/keys/{id}`. Updates one existing key's value.
+UpdateI18nKeyResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Id of the key that was updated.
+  required:
+    - id
+  additionalProperties: false
+  description: Updated key id.
+ListI18nDraftsResponse:
+  type: array
+  items:
+    type: object
+    properties:
+      id:
+        type: string
+        description: Stable opaque draft id.
+      name:
+        description: Draft name, e.g. the target locale being staged.
+        type: string
+      profileId:
+        description: Profile the draft targets.
+        type: string
+      sourceProfileId:
+        description: Profile the draft was seeded from, or `null`.
+        anyOf:
+          - type: string
+          - type: "null"
+      status:
+        description: Lifecycle state of the draft.
+        type: string
+        enum:
+          - open
+          - merged
+          - abandoned
+      createdBy:
+        description: Actor email that created the draft.
+        type: string
+      createdAt:
+        description: ISO-8601 timestamp of creation.
+        type: string
+      publishedAt:
+        description: ISO-8601 merge/publish timestamp, or `null`.
+        anyOf:
+          - type: string
+          - type: "null"
+    required:
+      - id
+    additionalProperties: {}
+    description: One staged translation draft.
+I18nDraft:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Stable opaque draft id.
+    name:
+      type: string
+      description: Draft name, e.g. the target locale being staged.
+    profileId:
+      type: string
+      description: Profile the draft targets.
+    sourceProfileId:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Profile the draft was seeded from, or `null`.
+    status:
+      type: string
+      enum:
+        - open
+        - merged
+        - abandoned
+      description: Lifecycle state of the draft.
+    createdBy:
+      type: string
+      description: Actor email that created the draft.
+    createdAt:
+      type: string
+      description: ISO-8601 timestamp of creation.
+    publishedAt:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: ISO-8601 merge/publish timestamp, or `null`.
+  required:
+    - id
+  additionalProperties: {}
+  description: One staged translation draft.
+CreateI18nDraftRequest:
+  type: object
+  properties:
+    name:
+      type: string
+      minLength: 1
+      maxLength: 64
+      description: Draft name, e.g. the target locale being staged.
+    profile_id:
+      type: string
+      format: uuid
+      description: Profile the draft targets.
+    source_profile_id:
+      type: string
+      format: uuid
+      description: Optional profile to seed the draft's keys from.
+  required:
+    - name
+    - profile_id
+  additionalProperties: false
+  description: Body for `POST /api/admin/i18n/drafts`. Stages a new translation draft against a target profile, optionally seeding from a source profile.
+CreateI18nDraftResponse:
+  $ref: "#/I18nDraft"
+UpdateI18nDraftRequest:
+  type: object
+  properties:
+    status:
+      type: string
+      enum:
+        - open
+        - merged
+        - abandoned
+      description: New lifecycle state for the draft.
+  additionalProperties: false
+  description: Body for `PATCH /api/admin/i18n/drafts/{draftId}`. Transitions the draft's lifecycle state.
+UpdateI18nDraftResponse:
+  $ref: "#/I18nDraft"
+PublishI18nProfileRequest:
+  type: object
+  properties:
+    chunk:
+      description: Optional chunk label to stamp on the audit log. Publishing is profile-wide regardless — the whole profile is snapshotted into one KV blob.
+      type: string
+  additionalProperties: false
+  description: Body for `POST /api/admin/i18n/profiles/{profileId}/publish`. The `chunk` is an audit label only.
+PublishI18nProfileResponse:
+  type: object
+  properties:
+    ok:
+      type: boolean
+      const: true
+      description: Always `true` on success.
+    profile_id:
+      type: string
+      description: Profile that was published.
+    chunk:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Audit chunk label, or `null` when none was given.
+    published_at:
+      type: string
+      description: ISO-8601 timestamp of the publish.
+    version:
+      type: string
+      description: New KV snapshot version that was shipped.
+    key_count:
+      type: number
+      description: Number of keys in the published snapshot.
+    changed:
+      type: boolean
+      description: Whether the snapshot's contents actually changed since the last publish.
+    purged:
+      type: string
+      enum:
+        - purged
+        - skipped
+        - failed
+      description: "CDN purge outcome: `purged` ok, `skipped` (no creds), or `failed` (edge still stale)."
+    kv_verified:
+      type: boolean
+      description: Whether a KV read-back confirmed the new version persisted.
+    warning:
+      description: Human-readable caveat when the publish landed but is not fully live.
+      type: string
+  required:
+    - ok
+    - profile_id
+    - chunk
+    - published_at
+    - version
+    - key_count
+    - changed
+    - purged
+    - kv_verified
+  additionalProperties: false
+  description: Result of a profile-wide publish.
+SetI18nLabelRequest:
+  type: object
+  properties:
+    key:
+      type: string
+      minLength: 1
+      maxLength: 256
+      description: Dotted key path to set, e.g. `home.cta`.
+    value:
+      type: string
+      description: New value for the key. Inserted when the key is new, overwritten when it exists.
+    profile:
+      description: Profile name to target, e.g. `en:prod`. Omit to target the project's default-marked profile.
+      type: string
+      minLength: 1
+      maxLength: 64
+    description:
+      description: Optional human note to store with the key.
+      type: string
+  required:
+    - key
+    - value
+  additionalProperties: false
+  description: "Body for `POST /api/admin/i18n/set`. Upserts one key's value and publishes the profile live."
+SetI18nLabelResponse:
+  type: object
+  properties:
+    ok:
+      type: boolean
+      const: true
+      description: Always `true` on success.
+    profile:
+      type: string
+      description: Name of the profile that was published.
+    profile_id:
+      type: string
+      description: Id of the profile that was published.
+    key:
+      type: string
+      description: The key that was set.
+    value:
+      type: string
+      description: The value that was stored.
+    published_at:
+      type: string
+      description: ISO-8601 timestamp of the publish.
+    version:
+      type: string
+      description: New KV snapshot version that was shipped.
+    key_count:
+      type: number
+      description: Number of keys in the published snapshot.
+    changed:
+      type: boolean
+      description: Whether the snapshot's contents actually changed since the last publish.
+    purged:
+      type: string
+      enum:
+        - purged
+        - skipped
+        - failed
+      description: "CDN purge outcome: `purged` ok, `skipped` (no creds), or `failed` (edge still stale)."
+    kv_verified:
+      type: boolean
+      description: Whether a KV read-back confirmed the new version persisted.
+    warning:
+      description: Human-readable caveat when the publish landed but is not fully live.
+      type: string
+  required:
+    - ok
+    - profile
+    - profile_id
+    - key
+    - value
+    - published_at
+    - version
+    - key_count
+    - changed
+    - purged
+    - kv_verified
+  additionalProperties: false
+  description: Result of a one-shot set-and-publish.

package/spec/components/schemas/keys.yaml

@@ -0,0 +1,186 @@
+ListKeysResponse:
+  type: object
+  properties:
+    data:
+      type: array
+      items:
+        $ref: "#/KeyRecord"
+    next_cursor:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Opaque cursor for the next page, or `null` on the last page. Pass it back as the `cursor` query parameter.
+  required:
+    - data
+    - next_cursor
+  additionalProperties: false
+  description: One page of API keys plus a keyset `next_cursor` (ordered `created_at desc, id desc`).
+KeyRecord:
+  type: object
+  description: A single API key as returned by the list endpoint. Response fields are snake_case. The raw token is never returned here — only its `last4` tail. `last4` and the typed `scopes` may be `null` for keys minted before those columns existed.
+  properties:
+    id:
+      type: string
+      description: Stable opaque key id (UUID). Use it to revoke the key.
+    type:
+      type: string
+      enum:
+        - server
+        - client
+        - admin
+        - ops
+      description: "Key kind. `server` (back-end, full SDK auth), `client` (public, browser-embeddable), `admin` (CLI/devtools auth token), `ops` (restricted unattended-trigger credential)."
+    env:
+      type: string
+      enum:
+        - dev
+        - staging
+        - prod
+      description: Environment the key is bound to. The worker derives the read env from the key, so this is the isolation boundary. `admin`/`ops` keys are env-agnostic and pinned to `prod`.
+    created_at:
+      type: string
+      description: ISO-8601 timestamp the key was minted.
+    revoked_at:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: ISO-8601 timestamp the key was revoked, or `null` while the key is active.
+    expires_at:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: ISO-8601 expiry, or `null` for a key that never expires. `admin` keys are fixed at 90 days; `ops` keys use a short sliding window.
+    created_by_email:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Email of the human or actor that minted the key, or `null` when not attributable (e.g. CLI device-flow).
+    name:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Human label for the key. `null` for unnamed dashboard mints; programmatic mints auto-name themselves.
+    scopes:
+      anyOf:
+        - type: array
+          items:
+            type: string
+        - type: "null"
+      description: Permission strings recorded on the key for audit/display, or `null` when none were set.
+    last4:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Last 4 characters of the raw token, so the dashboard mask is matchable against the held key. `null` for keys minted before this column.
+  required:
+    - id
+    - type
+    - env
+    - created_at
+    - revoked_at
+    - expires_at
+    - created_by_email
+    - name
+    - scopes
+    - last4
+  additionalProperties: false
+CreateKeyRequest:
+  type: object
+  description: |-
+    Body for `POST /api/admin/keys`. Only `type` is required.
+
+    `env` is **required** for `server` and `client` keys (the key is bound to one environment — that binding is the read-env isolation boundary). For `admin` and `ops` keys `env` is ignored and the key is pinned to `prod`.
+  properties:
+    type:
+      type: string
+      enum:
+        - server
+        - client
+        - admin
+        - ops
+      description: "Key kind to mint. `server` (back-end), `client` (public, browser), `admin` (CLI/devtools token), `ops` (restricted unattended-trigger credential). `admin`/`ops` keys don't count toward the plan key limit."
+    name:
+      type: string
+      minLength: 1
+      maxLength: 80
+      description: Optional human label. Programmatic (API) mints that omit it get an auto-generated descriptive name; dashboard mints may leave it blank.
+    scopes:
+      type: array
+      items:
+        type: string
+        enum:
+          - experiments:read
+          - gates:evaluate
+          - events:write
+          - configs:write
+          - experiments:write
+      description: Optional permission strings recorded on the key for audit/display.
+    expiresInDays:
+      anyOf:
+        - type: integer
+          minimum: 1
+          maximum: 3650
+        - type: "null"
+      description: "Days until the key expires (1–3650), or `null`/omitted for a key that never expires. Ignored for `admin` keys (fixed 90-day expiry) and `ops` keys (short sliding window)."
+    env:
+      type: string
+      enum:
+        - dev
+        - staging
+        - prod
+      description: Environment to bind the key to. Always required. For `server`/`client` keys it is the isolation boundary the worker reads from; `admin`/`ops` keys are env-agnostic and pinned to `prod` by the handler regardless of the value sent.
+  required:
+    - type
+    - env
+  additionalProperties: false
+CreateKeyResponse:
+  type: object
+  description: The minted key. The plaintext `key` is returned **once**, here — it is stored hashed and can never be retrieved again.
+  properties:
+    id:
+      type: string
+      description: Stable opaque key id (UUID). Use it to revoke the key.
+    type:
+      type: string
+      enum:
+        - server
+        - client
+        - admin
+        - ops
+      description: The kind of key that was minted.
+    env:
+      type: string
+      enum:
+        - dev
+        - staging
+        - prod
+      description: Environment the key is bound to (`prod` for `admin`/`ops`).
+    key:
+      type: string
+      description: The plaintext API token (e.g. `sdk_server_…`). Returned once — store it now; it cannot be recovered.
+    expires_at:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: ISO-8601 expiry, or `null` if the key never expires.
+  required:
+    - id
+    - type
+    - env
+    - key
+    - expires_at
+  additionalProperties: false
+RevokeKeyResponse:
+  type: object
+  description: Confirms the key is revoked. Idempotent — revoking an already-revoked key returns the same shape.
+  properties:
+    id:
+      type: string
+      description: Id of the key that was revoked.
+    revoked:
+      type: boolean
+      const: true
+  required:
+    - id
+    - revoked
+  additionalProperties: false