@shipeasy/openapi 2.5.0 → 3.1.0

package/spec/components/schemas/i18n.yaml

@@ -94,14 +94,6 @@ ListI18nKeysResponse:
             anyOf:
               - type: string
               - type: "null"
-          chunkId:
-            description: Owning chunk (authoring grouping) id.
-            type: string
-          chunkName:
-            description: Name of the owning chunk (authoring grouping), or `null` when it cannot be resolved.
-            anyOf:
-              - type: string
-              - type: "null"
           updatedAt:
             description: ISO-8601 timestamp of the last edit.
             type: string
@@ -116,8 +108,6 @@ ListI18nKeysResponse:
           - variables
           - profileId
           - profileName
-          - chunkId
-          - chunkName
           - updatedAt
           - updatedBy
         additionalProperties: false
@@ -138,12 +128,6 @@ PushI18nKeysRequest:
       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
@@ -174,12 +158,16 @@ PushI18nKeysRequest:
           - key
           - value
         additionalProperties: false
-      description: Keys to add. Insert-only — existing keys are reported back as `skipped`.
+      description: Keys to add. Insert-only by default — existing keys are reported back as `skipped` (set `force` to overwrite them instead).
+    force:
+      type: boolean
+      default: false
+      description: Overwrite keys that already exist with the submitted value instead of skipping them. Overwritten keys come back as `updated`. Off by default so a routine push can never clobber live translations.
   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."
+  description: "Body for `POST /api/admin/i18n/keys`. Insert-only by default: keys that already exist are never overwritten — pass `force: true` to overwrite them in bulk, or use `PUT /keys/{id}` to change one value."
 PushI18nKeysResponse:
   type: object
   properties:
@@ -192,23 +180,30 @@ PushI18nKeysResponse:
       type: array
       items:
         type: string
-      description: Key names that already existed and were left untouched.
+      description: Key names that already existed and were left untouched. Always empty when `force` was set — those key names come back under `updated` instead.
+    updated:
+      type: array
+      items:
+        type: string
+      description: Key names that already existed and were overwritten with the submitted value. Only ever non-empty when the push set `force`.
     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
+    updated_count:
+      type: number
+      description: Number of existing keys overwritten (== `updated.length`).
   required:
     - added
     - skipped
+    - updated
     - pushed_count
     - skipped_count
+    - updated_count
   additionalProperties: false
-  description: Result of an insert-only key push.
+  description: Result of a key push — what was inserted, what was left alone, and (with `force`) what was overwritten.
 UpdateI18nKeyRequest:
   type: object
   properties:
@@ -249,12 +244,6 @@ UpsertI18nKeysRequest:
       type: string
       format: uuid
       description: Target profile id to upsert keys into.
-    chunk:
-      description: Logical grouping the keys are filed under. Defaults to `default`.
-      type: string
-      minLength: 1
-      maxLength: 64
-      default: default
     keys:
       type: array
       minItems: 1
@@ -297,12 +286,8 @@ UpsertI18nKeysResponse:
     upserted:
       type: number
       description: Number of keys written (inserted or overwritten).
-    chunk:
-      type: string
-      description: The chunk the keys were filed under.
   required:
     - upserted
-    - chunk
   additionalProperties: false
   description: Result of a bulk key upsert. The affected profile's KV snapshot is rebuilt (and the CDN purged) before this returns.
 ListI18nDraftsResponse:
@@ -465,12 +450,9 @@ UpsertI18nDraftKeyResponse:
   $ref: "./common.yaml#/OkResponse"
 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
+  properties: {}
   additionalProperties: false
-  description: Body for `POST /api/admin/i18n/profiles/{profileId}/publish`. The `chunk` is an audit label only.
+  description: Body for `POST /api/admin/i18n/profiles/{profileId}/publish`. Publishing is profile-wide — the whole profile is snapshotted into one KV blob — so the body takes no options.
 PublishI18nProfileResponse:
   type: object
   properties:
@@ -481,11 +463,6 @@ PublishI18nProfileResponse:
     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.
@@ -514,7 +491,6 @@ PublishI18nProfileResponse:
   required:
     - ok
     - profile_id
-    - chunk
     - published_at
     - version
     - key_count

package/spec/components/schemas/ops.yaml

@@ -1093,8 +1093,6 @@ OpsItemStatus:
   enum:
     - open
     - pending_approval
-    - triage
-    - triaged
     - investigating_by_ai
     - in_progress
     - blocked
@@ -1102,7 +1100,7 @@ OpsItemStatus:
     - resolved
     - wont_fix
   description: >-
-    Lifecycle status of a queue item. The working flow is `open` → `triaged` →
+    Lifecycle status of a queue item. The working flow is `open` →
     `in_progress` → `ready_for_qa` → `resolved` (or `wont_fix`, terminal from
     any earlier stage). `blocked` marks an item that can't progress until an
     external dependency clears — a working state a human sets and clears.
@@ -1111,18 +1109,17 @@ OpsItemStatus:
     after verification — set it directly from code only when the fix has been
     verified end-to-end. `investigating_by_ai` is a system-owned display state —
     set when the AI agent (Jarvis) picks an item up to investigate, never chosen
-    by a human — so it is shown but not offered as a manual choice. Two
-    human-gated holding states park an item OUT of the work queue until a human
-    promotes it to `open` in the dashboard, so `GET /api/admin/ops` excludes
-    them under `status=all`/default and returns them only when requested as an
-    exact `status`: `pending_approval` is the pre-open approval gate for
-    untriaged inbound (e.g. connector requests filed from a customer's
-    connectors panel) so it never gets auto-implemented — approving = flipping
-    the status to `open`; `triage` is the onboarding-help bucket —
-    questions/errors submitted to the "Stuck in onboarding?" assistant are
-    funnelled into the platform project as `triage` rows so the team can see
-    where people get stuck and follow up, keeping onboarding chatter out of the
-    work queue until a human moves real items to `open`.
+    by a human — so it is shown but not offered as a manual choice.
+    `pending_approval` is the one human-gated holding state: it parks an item
+    OUT of the work queue until a human promotes it to `open` in the dashboard,
+    so `GET /api/admin/ops` excludes it under `status=all`/default and returns
+    it only when requested as an exact `status`. It covers untriaged inbound
+    that must never be auto-implemented — connector requests filed from a
+    customer's connectors panel, and questions funnelled in from the "Stuck in
+    onboarding?" assistant — where approving means flipping the status to
+    `open`. Two earlier values were removed in favour of this single gate:
+    `triage` (the onboarding-help bucket, now `pending_approval`) and `triaged`
+    (a redundant "looked at but not started" step, now plain `open`).
 OpsItemPriority:
   type: string
   enum:
@@ -1138,14 +1135,13 @@ OpsInvestigationState:
   type: string
   enum:
     - pr_ready
+    - pr_merged
     - investigated
     - detected
     - question
     - ready_for_qa
     - pending_approval
-    - needs_triage
     - working
-    - triaged_low
     - backlog
   description: >-
     Where automation has taken an item in the investigation lifecycle — the
@@ -1154,11 +1150,14 @@ OpsInvestigationState:
     happen**, never authored on its own: linking a PR sets `pr_ready`, moving to
     `in_progress` sets `working`, `ready_for_qa` sets `ready_for_qa`, a
     system/assistant reply sets `question`, resolving clears it, and creation
-    seeds `needs_triage`/`backlog` (by priority) or `investigated`/`detected`
-    for auto-filed error/alert tickets. `triaged_low` marks a low-signal item AI
-    has looked at but that nothing is moving. Absent on rows filed before the
-    field existed — consumers should treat a missing value as "derive from the
-    other fields".
+    seeds `backlog` or `investigated`/`detected` for auto-filed error/alert
+    tickets. `backlog` is the single "nothing has happened yet" state — how
+    urgent that is reads off `priority`, not off a separate state, and its one
+    action is to hand the item to an agent. `pr_merged` is derived client-side
+    by scanning the linked pull request on GitHub, so it is accepted on write
+    but not currently emitted by the API. Absent on rows filed before the field
+    existed — consumers should treat a missing value as "derive from the other
+    fields".
 OpsItemPriorityOrNull:
   anyOf:
     - $ref: "#/OpsItemPriority"

package/spec/openapi.yaml

@@ -228,14 +228,14 @@ tags:
   - name: i18n
     description: |-
       String Manager (i18n): the worker-safe REST surface — locale profiles, the
-      insert-only key push, single-key overwrite, chunk publish, and the read-only
+      insert-only key push, single-key overwrite, profile publish, and the read-only
       key/draft listings.
 
       The fs/AST parts (scan, validate, install-loader, codemod) are NOT part of
       this API — they stay in the fs-having CLI/MCP.
   - name: Profiles
     parent: i18n
-    description: Locale profiles (e.g. `en:prod`) — create, list, and publish a profile's chunks to the CDN.
+    description: Locale profiles (e.g. `en:prod`) — create, list, and publish a profile to the CDN.
   - name: Keys
     parent: i18n
     description: Translation keys — the insert-only push, single-key overwrite, and key listing.

package/spec/paths/i18n.yaml

@@ -5,7 +5,7 @@
     description: |-
       Returns every locale profile in the project (e.g. `en:prod`, `fr:prod`).
 
-      **Use case:** Discover which locale profiles exist before pushing keys or publishing a chunk.
+      **Use case:** Discover which locale profiles exist before pushing keys or publishing.
     tags:
       - Profiles
     parameters:
@@ -173,11 +173,13 @@
       name: list
   post:
     operationId: pushI18nKeys
-    summary: Push new i18n keys (insert-only)
+    summary: Push i18n keys (insert-only, or `force` to overwrite)
     description: |-
-      Add NEW keys to a profile. Insert-only — existing keys are left untouched (overwrite one with `updateI18nKey`).
+      Add NEW keys to a profile. Insert-only by default — existing keys are left untouched and reported back as `skipped`.
 
-      **Use case:** Seed newly-extracted keys without clobbering translations already in the profile.
+      Pass `force: true` to overwrite the existing ones in bulk with the submitted values: they come back as `updated` instead of `skipped`. Without `force` the only overwrite paths are `updateI18nKey` (one key) and the devtools-only `upsertI18nKeys`.
+
+      **Use case:** Seed newly-extracted keys without clobbering translations already in the profile — or re-push a whole source-language file with `force` after the copy changed.
     tags:
       - Keys
     parameters:
@@ -195,7 +197,7 @@
                 value: Buy now
     responses:
       "201":
-        description: Push new i18n keys (insert-only)
+        description: Push i18n keys (insert-only, or `force` to overwrite)
         content:
           application/json:
             schema:
@@ -204,8 +206,10 @@
               added:
                 - checkout.cta
               skipped: []
+              updated: []
               pushed_count: 1
               skipped_count: 0
+              updated_count: 0
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":
@@ -259,7 +263,6 @@
               $ref: ../components/schemas/i18n.yaml#/UpsertI18nKeysResponse
             example:
               upserted: 1
-              chunk: default
       "400":
         $ref: ../components/responses.yaml#/BadRequest
       "401":
@@ -726,7 +729,7 @@
     operationId: publishI18nProfile
     summary: Publish a profile live
     description: |-
-      Publish a profile to the CDN — rebuild its KV snapshot + purge the edge. Publishing is PROFILE-WIDE: the whole profile is snapshotted into one KV blob, so the optional `chunk` in the body is an audit label only (it does not scope what ships).
+      Publish a profile to the CDN — rebuild its KV snapshot + purge the edge. Publishing is PROFILE-WIDE: the whole profile is snapshotted into one KV blob, so the body takes no options.
 
       **Use case:** Ship the latest translations live after pushing/updating keys.
     tags:
@@ -740,16 +743,15 @@
         schema:
           $ref: ../components/schemas/common.yaml#/ResourceId
     requestBody:
-      required: true
+      required: false
       content:
         application/json:
           schema:
             $ref: ../components/schemas/i18n.yaml#/PublishI18nProfileRequest
-          example:
-            chunk: default
+          example: {}
     responses:
       "200":
-        description: Publish a profile chunk
+        description: Publish a profile
         content:
           application/json:
             schema:

package/spec/paths/ops.yaml

@@ -29,9 +29,9 @@
         in: query
         required: false
         description: >-
-          Filter by lifecycle status, or `all`. The human-gated holding states
-          (`pending_approval`, `triage`) are excluded from `all`/default and
-          returned only when requested as the exact status.
+          Filter by lifecycle status, or `all`. The human-gated holding state
+          (`pending_approval`) is excluded from `all`/default and returned only
+          when requested as the exact status.
         schema:
           anyOf:
             - $ref: ../components/schemas/ops.yaml#/OpsItemStatus