@shipeasy/openapi 2.4.0 → 3.0.0

package/spec/paths/configs.yaml

@@ -87,7 +87,7 @@
 
       - **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.
+      - **Per-env seed** — supply a `{ env: value }` map under `value`, or pass the env keys `dev`/`staging`/`prod` directly (each overrides `value` for that env and is published at version 1).
     tags:
       - Configs
     parameters:
@@ -129,8 +129,8 @@
                     - name: free
                     - name: pro
             perEnvSeed:
-              summary: Per-env seed
-              description: "Pass a `{ env: value }` map to seed different initial values per env."
+              summary: Per-env seed (env keys)
+              description: "Pass the env keys directly to seed different initial values per env. Each overrides `value` for that env and is published at version 1."
               value:
                 name: pricing.tiers
                 schema:
@@ -140,20 +140,15 @@
                       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
+                dev:
+                  tiers:
+                    - name: free
+                    - name: pro
+                    - name: enterprise
+                prod:
+                  tiers:
+                    - name: free
+                    - name: pro
     responses:
       "201":
         description: Create a dynamic config
@@ -302,15 +297,13 @@
     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.
+      Partial update. When `value` is supplied it is **republished on every env** (new version per env). A per-env key (`dev`/`staging`/`prod`) publishes a new version to **only that env**, immediately, overriding `value` for it. When `schema` is supplied it replaces the current schema; every existing value is re-validated.
 
       **Use cases**
 
       - **Republish flat value** — `{ "value": {…} }` sets the same value on every env.
+      - **Publish one env** — `{ "prod": {…} }` publishes a new version to prod only, instantly.
       - **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:
@@ -336,6 +329,15 @@
                   tiers:
                     - name: free
                     - name: pro
+            prodOnly:
+              summary: Per-env — publish prod only
+              description: Publishes a new version to prod only, immediately. dev/staging untouched.
+              value:
+                prod:
+                  tiers:
+                    - name: free
+                    - name: pro
+                    - name: enterprise
             schemaOnly:
               summary: Schema-only update
               description: Replaces the schema. Existing values must still validate or the update fails.
@@ -496,6 +498,7 @@
       - VALIDATION
     x-cli:
       name: draft
+      hidden: true
       positional:
         - id
   delete:
@@ -555,6 +558,7 @@
       - NOT_FOUND
     x-cli:
       name: discard-draft
+      hidden: true
       positional:
         - id
 /api/admin/configs/{id}/publish:
@@ -626,6 +630,7 @@
       - VALIDATION
     x-cli:
       name: publish
+      hidden: true
       positional:
         - id
 /api/admin/configs/{id}/activity:
@@ -690,6 +695,7 @@
       - NOT_FOUND
     x-cli:
       name: activity
+      hidden: true
       positional:
         - id
 /api/admin/configs/{id}/versions:
@@ -756,6 +762,7 @@
       - NOT_FOUND
     x-cli:
       name: versions
+      hidden: true
       positional:
         - id
 /api/admin/configs/{id}/schema:

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

@@ -505,7 +505,7 @@
       **Use case:** Read what a previous agent run already found before starting
       your own investigation of the item.
     tags:
-      - Ops
+      - Investigations
     parameters:
       - $ref: ../components/parameters.yaml#/ProjectId
       - name: handle
@@ -536,6 +536,10 @@
       - UNAUTHORIZED
       - FORBIDDEN
       - NOT_FOUND
+    x-cli:
+      name: list
+      positional:
+        - handle
   post:
     operationId: createOpsInvestigation
     summary: Record an investigation
@@ -551,7 +555,7 @@
       markdown findings, sources inspected, confidence) so the team — and the
       next agent run — sees what you learned.
     tags:
-      - Ops
+      - Investigations
     parameters:
       - $ref: ../components/parameters.yaml#/ProjectId
       - name: handle
@@ -609,6 +613,85 @@
       - FORBIDDEN
       - NOT_FOUND
       - VALIDATION
+    x-cli:
+      name: create
+      positional:
+        - handle
+/api/admin/ops/{handle}/investigation/{investigationId}:
+  patch:
+    operationId: updateOpsInvestigation
+    summary: Update an investigation record
+    description: |-
+      Update one existing investigation record in place — the write-back seam for
+      the `working` run record you were handed when a run was launched. Fill in
+      the `summary`/`findings`, attach the fixing PR, record your `confidence`
+      and the `sources` you inspected, or flip its `kind` off `working` once the
+      investigation is done. A partial patch: send only the fields you want to
+      change. Safe for restricted ops keys (it never reads or deletes).
+
+      **Use case:** A run started with an empty `working` record; as you work,
+      PATCH it with your findings so the cockpit's detail panel fills in live —
+      no need to append a second record.
+    tags:
+      - Investigations
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: handle
+        in: path
+        required: true
+        description: Per-project item number (e.g. `7`) or the full ops item id.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+      - name: investigationId
+        in: path
+        required: true
+        description: The investigation record id (from `POST`/`GET .../investigation` or the `runId` an ack/launch returned).
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/ops.yaml#/UpdateOpsInvestigationRequest
+          examples:
+            findings:
+              summary: Fill in the run record's findings
+              value:
+                kind: investigated
+                summary: Root cause is a stale KV read on the checkout flag.
+                findings: "The `checkout.cta` gate is rebuilt without a CDN purge, so…"
+                confidence: high
+                prNumber: 4821
+                prUrl: https://github.com/acme/web/pull/4821
+    responses:
+      "200":
+        description: The updated investigation record
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/ops.yaml#/OpsInvestigation
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: update
+      positional:
+        - handle
+        - investigationId
 /api/admin/agent-profiles:
   get:
     operationId: listOpsAgents