@shipeasy/openapi 1.6.0 → 2.2.0

package/spec/paths/configs.yaml

@@ -0,0 +1,758 @@
+/api/admin/configs:
+  get:
+    operationId: listConfigs
+    summary: List dynamic configs
+    description: |-
+      Returns a single page of configs ordered by `updated_at desc, id desc`. Each row includes the latest published `version` per env and any active drafts.
+
+      **Use case:** Snapshot every config in the project — e.g. CI check that asserts no env is stuck on a stale default or that every config has a published value on prod.
+    tags:
+      - Configs
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - $ref: ../components/parameters.yaml#/PaginationLimit
+      - $ref: ../components/parameters.yaml#/PaginationCursor
+      - $ref: ../components/parameters.yaml#/Q
+    responses:
+      "200":
+        description: List dynamic configs
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/configs.yaml#/ListConfigsResponse
+            example:
+              data:
+                - id: cfg_01j7wae5h6j7k8l9m0n1p2q3r4
+                  name: pricing.tiers
+                  description: Pricing tier definitions consumed by the checkout flow.
+                  schema:
+                    type: object
+                    properties:
+                      tiers:
+                        type: array
+                        items:
+                          type: object
+                    required:
+                      - tiers
+                  updatedAt: 2026-05-09T18:22:11.000Z
+                  envs:
+                    dev:
+                      version: 5
+                      publishedAt: 2026-05-09T18:22:11.000Z
+                      publishedBy: ana@example.com
+                    stage:
+                      version: 4
+                      publishedAt: 2026-05-08T11:05:22.000Z
+                      publishedBy: ana@example.com
+                    prod:
+                      version: 4
+                      publishedAt: 2026-05-08T11:05:22.000Z
+                      publishedBy: ana@example.com
+                  drafts:
+                    dev:
+                      updatedAt: 2026-05-10T09:31:00.000Z
+                      authorEmail: bo@example.com
+                      baseVersion: 5
+              next_cursor: null
+      "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: createConfig
+    summary: Create a dynamic config
+    description: |-
+      Creates a new config with the given `schema`. The initial `value` (or an empty object) is published as version 1 on **every** env.
+
+      Returns `409` if `name` already exists in the project, `400` if `value` doesn't validate against `schema`.
+
+      **Use cases**
+
+      - **Minimal create** — `name` + `schema`. Initial value defaults to `{}`.
+      - **Seeded create** — supply a flat `value` to publish the same object on every env.
+      - **Per-env seed** — supply a `{ env: value }` map for different per-env starting values.
+    tags:
+      - Configs
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/configs.yaml#/CreateConfigRequest
+          examples:
+            minimal:
+              summary: Minimal — name + schema
+              description: Smallest valid body. Initial value defaults to `{}` on every env.
+              value:
+                name: pricing.tiers
+                schema:
+                  type: object
+                  properties:
+                    tiers:
+                      type: array
+                  required:
+                    - tiers
+            seededValue:
+              summary: Seeded — schema + initial value
+              description: Seed the same JSON object on every env at version 1.
+              value:
+                name: pricing.tiers
+                description: Pricing tier definitions consumed by checkout.
+                schema:
+                  type: object
+                  properties:
+                    tiers:
+                      type: array
+                  required:
+                    - tiers
+                value:
+                  tiers:
+                    - name: free
+                    - name: pro
+            perEnvSeed:
+              summary: Per-env seed
+              description: "Pass a `{ env: value }` map to seed different initial values per env."
+              value:
+                name: pricing.tiers
+                schema:
+                  type: object
+                  properties:
+                    tiers:
+                      type: array
+                  required:
+                    - tiers
+                value:
+                  dev:
+                    tiers:
+                      - name: free
+                      - name: pro
+                      - name: enterprise
+                  stage:
+                    tiers:
+                      - name: free
+                      - name: pro
+                  prod:
+                    tiers:
+                      - name: free
+                      - name: pro
+    responses:
+      "201":
+        description: Create a dynamic config
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/configs.yaml#/CreateConfigResponse
+            example:
+              id: cfg_01j7wae5h6j7k8l9m0n1p2q3r4
+              name: pricing.tiers
+        links:
+          GetConfig:
+            operationId: getConfig
+            parameters: { id: $response.body#/id }
+          UpdateConfig:
+            operationId: updateConfig
+            parameters: { id: $response.body#/id }
+          PublishConfigDraft:
+            operationId: publishConfigDraft
+            parameters: { id: $response.body#/id }
+          DeleteConfig:
+            operationId: deleteConfig
+            parameters: { id: $response.body#/id }
+      "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/configs/{id}:
+  get:
+    operationId: getConfig
+    summary: Get one config
+    description: |-
+      Returns config metadata plus the latest published values per env and any active draft values. Use this to fetch the JSON the editor renders.
+
+      **Use case:** Fetch one config's current published values and any in-flight drafts.
+    tags:
+      - Configs
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque config id (`cfg_…`) or the config's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: Get one config
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/configs.yaml#/GetConfigResponse
+            example:
+              id: cfg_01j7wae5h6j7k8l9m0n1p2q3r4
+              name: pricing.tiers
+              description: Pricing tier definitions consumed by the checkout flow.
+              schema:
+                type: object
+                properties:
+                  tiers:
+                    type: array
+                    items:
+                      type: object
+                required:
+                  - tiers
+              updatedAt: 2026-05-09T18:22:11.000Z
+              envs:
+                dev:
+                  version: 5
+                  publishedAt: 2026-05-09T18:22:11.000Z
+                  publishedBy: ana@example.com
+                stage:
+                  version: 4
+                  publishedAt: 2026-05-08T11:05:22.000Z
+                  publishedBy: ana@example.com
+                prod:
+                  version: 4
+                  publishedAt: 2026-05-08T11:05:22.000Z
+                  publishedBy: ana@example.com
+              drafts:
+                dev:
+                  updatedAt: 2026-05-10T09:31:00.000Z
+                  authorEmail: bo@example.com
+                  baseVersion: 5
+              values:
+                dev:
+                  tiers:
+                    - name: free
+                    - name: pro
+                stage:
+                  tiers:
+                    - name: free
+                    - name: pro
+                prod:
+                  tiers:
+                    - name: free
+                    - name: pro
+              draftValues:
+                dev:
+                  tiers:
+                    - name: free
+                    - name: pro
+                    - name: enterprise
+      "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: updateConfig
+    summary: Update a dynamic config
+    description: |-
+      Partial update. When `value` is supplied it is **republished on every env** (new version per env). When `schema` is supplied it replaces the current schema; every existing value is re-validated.
+
+      For env-scoped edits, use the draft/publish flow (`PUT /{id}/drafts` then `POST /{id}/publish`) instead.
+
+      **Use cases**
+
+      - **Republish flat value** — `{ "value": {…} }` sets the same value on every env.
+      - **Schema migration** — `{ "schema": {…} }` replaces the schema; existing values are re-validated.
+      - **Env-scoped edits** — use `PUT /{id}/drafts` + `POST /{id}/publish` instead of PATCH.
+    tags:
+      - Configs
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque config id (`cfg_…`) or the config's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/configs.yaml#/UpdateConfigRequest
+          examples:
+            flatValue:
+              summary: Flat value — republish on every env
+              description: Sets the same JSON object as a new version on dev/stage/prod.
+              value:
+                value:
+                  tiers:
+                    - name: free
+                    - name: pro
+            schemaOnly:
+              summary: Schema-only update
+              description: Replaces the schema. Existing values must still validate or the update fails.
+              value:
+                schema:
+                  type: object
+                  properties:
+                    tiers:
+                      type: array
+                    trial_days:
+                      type: integer
+                  required:
+                    - tiers
+    responses:
+      "200":
+        description: Update a dynamic config
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/configs.yaml#/UpdateConfigResponse
+            example:
+              id: cfg_01j7wae5h6j7k8l9m0n1p2q3r4
+      "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: deleteConfig
+    summary: Delete a dynamic config
+    description: |-
+      Soft-deletes the config and rebuilds the project's flags KV blob.
+
+      **Use case:** Tear down a config after its consumers have stopped reading it.
+    tags:
+      - Configs
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque config id (`cfg_…`) or the config's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: Delete a dynamic config
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/configs.yaml#/DeleteConfigResponse
+            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
+    x-cli:
+      name: archive
+      positional:
+        - id
+/api/admin/configs/{id}/drafts:
+  put:
+    operationId: saveConfigDraft
+    summary: Save a draft value
+    description: |-
+      Stages a value for one env without publishing. The draft is validated against the config's current schema and stored alongside the `baseVersion` it was forked from.
+
+      Saving over an existing draft overwrites it. Use `POST /{id}/publish` to promote it to a new published version.
+
+      **Use case:** Iterate on a config value on dev without affecting prod — preview in staging, then publish.
+    tags:
+      - Configs
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque config id (`cfg_…`) or the config's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/configs.yaml#/SaveConfigDraftRequest
+          examples:
+            stageDev:
+              summary: Stage a dev draft
+              description: Stages a new value on dev without touching stage/prod.
+              value:
+                env: dev
+                value:
+                  tiers:
+                    - name: free
+                    - name: pro
+                    - name: enterprise
+    responses:
+      "200":
+        description: Save a draft value
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/configs.yaml#/SaveConfigDraftResponse
+            example:
+              id: cfg_01j7wae5h6j7k8l9m0n1p2q3r4
+              env: dev
+              baseVersion: 5
+              updatedAt: 2026-05-10T09:31:00.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
+      - VALIDATION
+    x-cli:
+      name: draft
+      positional:
+        - id
+  delete:
+    operationId: discardConfigDraft
+    summary: Discard a draft
+    description: |-
+      Drops the in-flight draft on one env. Published values are unaffected.
+
+      **Use case:** Abandon an in-progress draft after deciding not to ship it.
+    tags:
+      - Configs
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque config id (`cfg_…`) or the config's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/configs.yaml#/DiscardConfigDraftRequest
+          examples:
+            discardDev:
+              summary: Discard the dev draft
+              description: Drops the staged dev draft without publishing.
+              value:
+                env: dev
+    responses:
+      "200":
+        description: Discard a draft
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/configs.yaml#/DiscardConfigDraftResponse
+            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
+    x-cli:
+      name: discard-draft
+      positional:
+        - id
+/api/admin/configs/{id}/publish:
+  post:
+    operationId: publishConfigDraft
+    summary: Publish a draft
+    description: |-
+      Promotes the staged draft on one env to a new published version. The draft must still validate against the current schema.
+
+      Returns `404` if there is no draft for the given env.
+
+      **Use case:** Ship a staged change once you've validated it on a lower env.
+    tags:
+      - Configs
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque config id (`cfg_…`) or the config's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/configs.yaml#/PublishConfigDraftRequest
+          examples:
+            publishDev:
+              summary: Publish the dev draft
+              description: Promotes the dev draft to a new published version on dev.
+              value:
+                env: dev
+            publishProd:
+              summary: Publish to prod
+              description: Promotes the prod draft after staging signed off.
+              value:
+                env: prod
+    responses:
+      "200":
+        description: Publish a draft
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/configs.yaml#/PublishConfigDraftResponse
+            example:
+              id: cfg_01j7wae5h6j7k8l9m0n1p2q3r4
+              env: dev
+              version: 6
+      "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
+      - INVALID_TRANSITION
+      - VALIDATION
+    x-cli:
+      name: publish
+      positional:
+        - id
+/api/admin/configs/{id}/activity:
+  get:
+    operationId: listConfigActivity
+    summary: List config activity
+    description: |-
+      Returns recent audit rows for one config (create, update, draft.save, publish, delete) ordered newest first. Use the `limit` query parameter to cap the result (1–100, default 20).
+
+      **Use case:** Render the activity panel in the config editor or drive a slack notification on publish events.
+    tags:
+      - Configs
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque config id (`cfg_…`) or the config's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+      - name: limit
+        in: query
+        required: false
+        description: Max rows to return (1–100). Defaults to 20.
+        schema:
+          default: 20
+          type: integer
+          minimum: 1
+          maximum: 100
+    responses:
+      "200":
+        description: List config activity
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/configs.yaml#/ListConfigActivityResponse
+            example:
+              - id: act_01j7waf01a2b3c4d5e6f7g8h9i
+                action: config.publish
+                actorEmail: ana@example.com
+                actorType: user
+                payload:
+                  env: dev
+                  version: 6
+                createdAt: 2026-05-10T09:31:42.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: activity
+      positional:
+        - id
+/api/admin/configs/{id}/schema:
+  patch:
+    operationId: updateConfigSchema
+    summary: Update a config schema
+    description: |-
+      Replaces a config's JSON Schema in place. Every existing published value is re-validated against the new schema before it lands; the update fails if any value no longer validates.
+
+      **Use case:** Evolve a config's shape (add/remove a field) without republishing values.
+    tags:
+      - Configs
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque config id (`cfg_…`) or the config's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/configs.yaml#/UpdateConfigSchemaRequest
+          examples:
+            addField:
+              summary: Add a field to the schema
+              description: Replaces the schema; existing values must still validate or the update fails.
+              value:
+                schema:
+                  type: object
+                  properties:
+                    tiers:
+                      type: array
+                    trial_days:
+                      type: integer
+                  required:
+                    - tiers
+    responses:
+      "200":
+        description: Update a config schema
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/configs.yaml#/UpdateConfigSchemaResponse
+            example:
+              id: cfg_01j7wae5h6j7k8l9m0n1p2q3r4
+      "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-schema
+      positional:
+        - id