@shipeasy/openapi 2.5.0 → 3.0.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/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: