@shipeasy/openapi 2.5.0 → 3.1.0

package/openapi.json

@@ -124,12 +124,12 @@
     },
     {
       "name": "i18n",
-      "description": "String Manager (i18n): the worker-safe REST surface — locale profiles, the\ninsert-only key push, single-key overwrite, chunk publish, and the read-only\nkey/draft listings.\n\nThe fs/AST parts (scan, validate, install-loader, codemod) are NOT part of\nthis API — they stay in the fs-having CLI/MCP."
+      "description": "String Manager (i18n): the worker-safe REST surface — locale profiles, the\ninsert-only key push, single-key overwrite, profile publish, and the read-only\nkey/draft listings.\n\nThe fs/AST parts (scan, validate, install-loader, codemod) are NOT part of\nthis 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",
@@ -6939,7 +6939,7 @@
             "name": "status",
             "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.",
+            "description": "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": [
                 {
@@ -9099,7 +9099,7 @@
       "get": {
         "operationId": "listI18nProfiles",
         "summary": "List i18n profiles",
-        "description": "Returns every locale profile in the project (e.g. `en:prod`, `fr:prod`).\n\n**Use case:** Discover which locale profiles exist before pushing keys or publishing a chunk.",
+        "description": "Returns every locale profile in the project (e.g. `en:prod`, `fr:prod`).\n\n**Use case:** Discover which locale profiles exist before pushing keys or publishing.",
         "tags": [
           "Profiles"
         ],
@@ -9348,8 +9348,8 @@
       },
       "post": {
         "operationId": "pushI18nKeys",
-        "summary": "Push new i18n keys (insert-only)",
-        "description": "Add NEW keys to a profile. Insert-only — existing keys are left untouched (overwrite one with `updateI18nKey`).\n\n**Use case:** Seed newly-extracted keys without clobbering translations already in the profile.",
+        "summary": "Push i18n keys (insert-only, or `force` to overwrite)",
+        "description": "Add NEW keys to a profile. Insert-only by default — existing keys are left untouched and reported back as `skipped`.\n\nPass `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`.\n\n**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"
         ],
@@ -9379,7 +9379,7 @@
         },
         "responses": {
           "201": {
-            "description": "Push new i18n keys (insert-only)",
+            "description": "Push i18n keys (insert-only, or `force` to overwrite)",
             "content": {
               "application/json": {
                 "schema": {
@@ -9390,8 +9390,10 @@
                     "checkout.cta"
                   ],
                   "skipped": [],
+                  "updated": [],
                   "pushed_count": 1,
-                  "skipped_count": 0
+                  "skipped_count": 0,
+                  "updated_count": 0
                 }
               }
             }
@@ -9466,8 +9468,7 @@
                   "$ref": "#/components/schemas/UpsertI18nKeysResponse"
                 },
                 "example": {
-                  "upserted": 1,
-                  "chunk": "default"
+                  "upserted": 1
                 }
               }
             }
@@ -10136,7 +10137,7 @@
       "post": {
         "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).\n\n**Use case:** Ship the latest translations live after pushing/updating keys.",
+        "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 body takes no options.\n\n**Use case:** Ship the latest translations live after pushing/updating keys.",
         "tags": [
           "Profiles"
         ],
@@ -10155,21 +10156,19 @@
           }
         ],
         "requestBody": {
-          "required": true,
+          "required": false,
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/PublishI18nProfileRequest"
               },
-              "example": {
-                "chunk": "default"
-              }
+              "example": {}
             }
           }
         },
         "responses": {
           "200": {
-            "description": "Publish a profile chunk",
+            "description": "Publish a profile",
             "content": {
               "application/json": {
                 "schema": {
@@ -19273,8 +19272,6 @@
         "enum": [
           "open",
           "pending_approval",
-          "triage",
-          "triaged",
           "investigating_by_ai",
           "in_progress",
           "blocked",
@@ -19282,7 +19279,7 @@
           "resolved",
           "wont_fix"
         ],
-        "description": "Lifecycle status of a queue item. The working flow is `open` → `triaged` → `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. `ready_for_qa` is what a developer sets once a fix lands; `resolved` is the QA sign-off, normally flipped in the dashboard 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`."
+        "description": "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. `ready_for_qa` is what a developer sets once a fix lands; `resolved` is the QA sign-off, normally flipped in the dashboard 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. `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",
@@ -19298,17 +19295,16 @@
         "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 signal the ops cockpit renders as \"what AI did\" plus the one action expected of the user. It is **written as a side-effect of the actions that already 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\"."
+        "description": "Where automation has taken an item in the investigation lifecycle — the signal the ops cockpit renders as \"what AI did\" plus the one action expected of the user. It is **written as a side-effect of the actions that already 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 `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\"."
       },
       "OpsBrowserContext": {
         "type": "object",
@@ -23611,21 +23607,6 @@
                     }
                   ]
                 },
-                "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"
@@ -23643,8 +23624,6 @@
                 "variables",
                 "profileId",
                 "profileName",
-                "chunkId",
-                "chunkName",
                 "updatedAt",
                 "updatedBy"
               ],
@@ -23673,13 +23652,6 @@
             "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,
@@ -23734,15 +23706,10 @@
           "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"
+          "upserted"
         ],
         "additionalProperties": false,
         "description": "Result of a bulk key upsert. The affected profile's KV snapshot is rebuilt (and the CDN purged) before this returns."
@@ -23755,13 +23722,6 @@
             "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,
@@ -23800,7 +23760,12 @@
               ],
               "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": [
@@ -23808,7 +23773,7 @@
           "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",
@@ -23825,7 +23790,14 @@
             "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",
@@ -23835,19 +23807,21 @@
             "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"
+          "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",
@@ -24121,14 +24095,9 @@
       },
       "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",
@@ -24142,17 +24111,6 @@
             "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."
@@ -24190,7 +24148,6 @@
         "required": [
           "ok",
           "profile_id",
-          "chunk",
           "published_at",
           "version",
           "key_count",

package/openapi.yaml

@@ -226,14 +226,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.
@@ -5078,7 +5078,7 @@ paths:
         - name: status
           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.
+          description: 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/OpsItemStatus'
@@ -6698,7 +6698,7 @@ paths:
       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:
@@ -6867,11 +6867,13 @@ paths:
         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:
@@ -6889,7 +6891,7 @@ paths:
                   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:
@@ -6898,8 +6900,10 @@ paths:
                 added:
                   - checkout.cta
                 skipped: []
+                updated: []
                 pushed_count: 1
                 skipped_count: 0
+                updated_count: 0
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -6953,7 +6957,6 @@ paths:
                 $ref: '#/components/schemas/UpsertI18nKeysResponse'
               example:
                 upserted: 1
-                chunk: default
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -7420,7 +7423,7 @@ paths:
       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:
@@ -7434,16 +7437,15 @@ paths:
           schema:
             $ref: '#/components/schemas/ResourceId'
       requestBody:
-        required: true
+        required: false
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/PublishI18nProfileRequest'
-            example:
-              chunk: default
+            example: {}
       responses:
         '200':
-          description: Publish a profile chunk
+          description: Publish a profile
           content:
             application/json:
               schema:
@@ -13923,15 +13925,13 @@ components:
       enum:
         - open
         - pending_approval
-        - triage
-        - triaged
         - investigating_by_ai
         - in_progress
         - blocked
         - ready_for_qa
         - resolved
         - wont_fix
-      description: 'Lifecycle status of a queue item. The working flow is `open` → `triaged` → `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. `ready_for_qa` is what a developer sets once a fix lands; `resolved` is the QA sign-off, normally flipped in the dashboard 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`.'
+      description: '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. `ready_for_qa` is what a developer sets once a fix lands; `resolved` is the QA sign-off, normally flipped in the dashboard 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. `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:
@@ -13944,16 +13944,15 @@ components:
       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 signal the ops cockpit renders as "what AI did" plus the one action expected of the user. It is **written as a side-effect of the actions that already 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".'
+      description: 'Where automation has taken an item in the investigation lifecycle — the signal the ops cockpit renders as "what AI did" plus the one action expected of the user. It is **written as a side-effect of the actions that already 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 `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".'
     OpsBrowserContext:
       type: object
       properties:
@@ -16730,14 +16729,6 @@ components:
                 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
@@ -16752,8 +16743,6 @@ components:
               - variables
               - profileId
               - profileName
-              - chunkId
-              - chunkName
               - updatedAt
               - updatedBy
             additionalProperties: false
@@ -16774,12 +16763,6 @@ components:
           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
@@ -16822,12 +16805,8 @@ components:
         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.
     PushI18nKeysRequest:
@@ -16837,12 +16816,6 @@ components:
           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
@@ -16873,12 +16846,16 @@ components:
               - 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:
@@ -16891,23 +16868,30 @@ components:
           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:
@@ -17102,12 +17086,9 @@ components:
       description: Body for `POST /api/admin/i18n/drafts/{draftId}/keys`. Upserts one staged key into an open draft — inserted when new, overwritten when it already exists. `{{var}}` placeholder names are auto-derived from the value.
     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:
@@ -17118,11 +17099,6 @@ components:
         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.
@@ -17151,7 +17127,6 @@ components:
       required:
         - ok
         - profile_id
-        - chunk
         - published_at
         - version
         - key_count

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipeasy/openapi",
-  "version": "2.5.0",
+  "version": "3.1.0",
   "description": "Shipeasy admin OpenAPI 3.2 spec (hand-authored, single source of truth) + the generated TypeScript client, Zod schemas, and types. Consumed by @shipeasy/cli and @shipeasy/mcp.",
   "type": "module",
   "main": "./dist/index.js",