@shipeasy/openapi 2.3.0 → 2.5.0

package/spec/paths/i18n.yaml

@@ -20,9 +20,9 @@
             example:
               - id: i18n_01j7w8a1b2c3
                 name: en:prod
-                locales:
-                  - en
-                default_locale: en
+                isDefault: 1
+                createdAt: 2026-04-12T10:14:08.000Z
+                deletedAt: null
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":
@@ -60,9 +60,6 @@
             $ref: ../components/schemas/i18n.yaml#/CreateI18nProfileRequest
           example:
             name: fr:prod
-            locales:
-              - fr
-            default_locale: fr
     responses:
       "201":
         description: Create an i18n profile
@@ -229,6 +226,58 @@
       - VALIDATION
     x-cli:
       name: push
+  put:
+    operationId: upsertI18nKeys
+    summary: Bulk upsert i18n keys (overwrite)
+    description: |-
+      Bulk upsert keys into a profile — existing keys ARE overwritten, new ones inserted. The profile's KV snapshot is rebuilt and the CDN purged before the call returns, so the edits go live on their own.
+
+      This is the overwrite counterpart of the insert-only `pushI18nKeys`. It backs the devtools overlay's in-product "Apply changes" label editing and is deliberately not surfaced by the CLI or MCP — those surfaces only expose the insert-only push so a whole `en.json` can't wholesale-overwrite prod.
+
+      **Use case:** Apply a batch of in-product label edits (devtools overlay) in one call.
+    tags:
+      - Keys
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/i18n.yaml#/UpsertI18nKeysRequest
+          example:
+            profile_id: 3f1a6c2e-1b2c-4d5e-8f90-0a1b2c3d4e5f
+            keys:
+              - key: checkout.cta
+                value: Buy it now
+    responses:
+      "200":
+        description: Bulk upsert i18n keys (overwrite)
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/i18n.yaml#/UpsertI18nKeysResponse
+            example:
+              upserted: 1
+              chunk: default
+      "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
 /api/admin/i18n/keys/{id}:
   put:
     operationId: updateI18nKey
@@ -288,6 +337,94 @@
       name: update
       positional:
         - id
+  delete:
+    operationId: deleteI18nKey
+    summary: Delete one i18n key
+    description: |-
+      Permanently delete a single key from its profile. The profile's KV snapshot is rebuilt and the CDN purged as part of this call, so the removal goes live on its own.
+
+      **Use case:** Remove a stale or mistakenly-pushed key without touching the rest of the profile.
+    tags:
+      - Keys
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: The key's id.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: Delete one i18n key
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/i18n.yaml#/DeleteI18nKeyResponse
+            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
+/api/admin/i18n/profiles/{profileId}:
+  delete:
+    operationId: deleteI18nProfile
+    summary: Delete an i18n profile
+    description: |-
+      Soft-delete a locale profile. The project's default profile cannot be deleted (409). The profile's keys are retained in the database but the profile no longer resolves for listing or publishing.
+
+      **Use case:** Retire a locale that is no longer shipped.
+    tags:
+      - Profiles
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: profileId
+        in: path
+        required: true
+        description: The profile id to delete.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: Delete an i18n profile
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/i18n.yaml#/DeleteI18nProfileResponse
+            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
+      - READ_ONLY
 /api/admin/i18n/drafts:
   get:
     operationId: listI18nDrafts
@@ -437,6 +574,153 @@
       name: update
       positional:
         - draftId
+  delete:
+    operationId: deleteI18nDraft
+    summary: Delete a translation draft
+    description: |-
+      Permanently delete a staged translation draft. Its staged keys are removed with it; the target profile's live keys are untouched.
+
+      **Use case:** Discard a draft that will never ship instead of leaving it abandoned.
+    tags:
+      - Drafts
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: draftId
+        in: path
+        required: true
+        description: The draft id to delete.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: Delete a translation draft
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/i18n.yaml#/DeleteI18nDraftResponse
+            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
+/api/admin/i18n/drafts/{draftId}/keys:
+  get:
+    operationId: listI18nDraftKeys
+    summary: List a draft's staged keys
+    description: |-
+      Returns every staged key in a translation draft — the values queued to ship when the draft is merged.
+
+      **Use case:** Review a machine-translation draft's staged strings before marking it merged.
+    tags:
+      - Drafts
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: draftId
+        in: path
+        required: true
+        description: The draft id to list staged keys for.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: List a draft's staged keys
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/i18n.yaml#/ListI18nDraftKeysResponse
+            example:
+              - id: dk_01j7
+                draftId: draft_01j7
+                key: checkout.cta
+                value: Achetez maintenant
+                description: null
+                variables: null
+                updatedBy: owner@acme.com
+                updatedAt: 2026-07-01T10: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
+  post:
+    operationId: upsertI18nDraftKey
+    summary: Upsert one staged draft key
+    description: |-
+      Upsert a single staged key into an **open** draft — inserted when new, overwritten when it already exists. A draft that is `merged` or `abandoned` rejects the write (400). `{{var}}` placeholder names are auto-derived from the value.
+
+      **Use case:** Stage or correct one translation in a draft under review without touching the live profile.
+    tags:
+      - Drafts
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: draftId
+        in: path
+        required: true
+        description: The draft id to stage the key into.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/i18n.yaml#/UpsertI18nDraftKeyRequest
+          example:
+            key: checkout.cta
+            value: Achetez maintenant
+    responses:
+      "201":
+        description: Upsert one staged draft key
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/i18n.yaml#/UpsertI18nDraftKeyResponse
+            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
+      - VALIDATION
 /api/admin/i18n/profiles/{profileId}/publish:
   post:
     operationId: publishI18nProfile

package/spec/paths/killswitches.yaml

@@ -25,6 +25,9 @@
                 - id: ksw_01j7w9d8h2k4m6n8p0q2r4s6t8
                   name: payments.checkout
                   description: Master kill for the checkout flow. Trip to fall back to the legacy provider.
+                  folder: payments
+                  creatorEmail: ana@example.com
+                  createdAt: 2026-05-01T10:12:00.000Z
                   updatedAt: 2026-05-09T18:22:11.000Z
                   envs:
                     dev:
@@ -183,6 +186,9 @@
               id: ksw_01j7w9d8h2k4m6n8p0q2r4s6t8
               name: payments.checkout
               description: Master kill for the checkout flow. Trip to fall back to the legacy provider.
+              folder: payments
+              creatorEmail: ana@example.com
+              createdAt: 2026-05-01T10:12:00.000Z
               updatedAt: 2026-05-09T18:22:11.000Z
               envs:
                 dev:

package/spec/paths/metrics.yaml

@@ -29,6 +29,7 @@
                   metric: checkout_completed
                   filters: []
                 direction: higher_better
+                version: 1
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":
@@ -184,6 +185,7 @@
                 filters: []
               direction: higher_better
               winsorizePct: 99
+              version: 1
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":
@@ -312,3 +314,187 @@
       name: archive
       positional:
         - id
+/api/admin/metrics/{id}/experiments:
+  get:
+    operationId: listMetricExperiments
+    summary: List experiments using a metric
+    description: |-
+      Returns every experiment that attaches this metric — as `goal`, `guardrail`, or `secondary` — ordered with running experiments first, then by role weight (goal > guardrail > secondary).
+
+      **Use case:** See who depends on a metric before editing or archiving it — e.g. the metric detail panel's "used by" list.
+    tags:
+      - Metrics
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque metric id (`met_…`) or the metric's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: List experiments using a metric
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/metrics.yaml#/ListMetricExperimentsResponse
+            example:
+              experiments:
+                - id: exp_01j7wb12c3d4e5f6g7h8j9k0l1
+                  name: checkout_button_color
+                  status: running
+                  role: goal
+                - id: exp_01j7wb98x7y6z5w4v3u2t1s0r9
+                  name: pricing_page_copy
+                  status: stopped
+                  role: guardrail
+      "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: experiments
+      positional:
+        - id
+/api/admin/metrics/{id}/unarchive:
+  post:
+    operationId: unarchiveMetric
+    summary: Unarchive a metric
+    description: |-
+      Reverses a soft-delete (archive), making the metric live again. Idempotent — unarchiving a metric that is already live succeeds with no effect.
+
+      **Use case:** Undo an accidental archive (the metrics list "Undo" toast calls this).
+    tags:
+      - Metrics
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque metric id (`met_…`) or the metric's `name`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: Unarchive a metric
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/metrics.yaml#/UnarchiveMetricResponse
+            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: unarchive
+      positional:
+        - id
+/api/admin/metrics/{id}/series:
+  post:
+    operationId: getMetricSeries
+    summary: Get a metric's time series
+    description: |-
+      Compiles the metric's typed IR into Analytics Engine SQL and returns the bucketed series over the requested window (near-real-time; ingest lag is seconds). The window bounds are epoch **seconds**; `to` must be strictly greater than `from`. The response echoes the SQL that produced the rows.
+
+      Returns `422` when the stored definition can't compile (e.g. a label or event has gone away — re-save the metric), and `502`/`503` when the analytics upstream fails or isn't configured.
+
+      **Use case:** Render the metric trend chart / sparkline, or pull raw bucketed values to feed an external dashboard.
+    tags:
+      - Metrics
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque metric id (`met_…`).
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/metrics.yaml#/GetMetricSeriesRequest
+          examples:
+            lastDayHourly:
+              summary: Last 24h, hourly buckets
+              description: Hourly metric values over a one-day window (bounds in epoch seconds).
+              value:
+                from: 1751000400
+                to: 1751086800
+                bucket: 3600
+    responses:
+      "200":
+        description: Get a metric's time series
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/metrics.yaml#/GetMetricSeriesResponse
+            example:
+              sql: |-
+                SELECT intDiv(toUInt32(double2), 3600) * 3600 AS t,
+                  sum(_sample_interval) AS v
+                FROM shipeasy_metric_events
+                WHERE index1 = 'e976b15e-2f0d-4c6e-9b1a-3a7c1f2d8e90'
+                  AND blob1 = 'checkout_completed'
+                  AND double2 >= 1751000400 AND double2 < 1751086800
+                GROUP BY t
+                ORDER BY t
+              rows:
+                - t: 1751000400
+                  v: 412
+                - t: 1751004000
+                  v: 531
+                - t: 1751007600
+                  v: 468
+      "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: series
+      positional:
+        - id