@giveitsmaller/contracts 0.78.0 → 0.79.0

package/dist/openapi/models/WorkflowWarningSeverity.js

@@ -4,7 +4,7 @@
  * GISL Compression API
  * REST API for the GISL (Give It Smaller) file compression and processing service.  **Architecture:** - Upload files to get a `file_id` - Create workflows referencing uploaded files with operations (compress, thumbnail, image_watermark, text_watermark, merge, archive, convert, custom_luma, audio_overlay, audio_watermark) - Poll status, stream SSE events, or receive webhook callbacks - Download results per operation output  **Response envelope:** All mutation and query endpoints return `{ success: true, data: {...} }` on success and `{ success: false, error: \"...\", details: [...] }` on failure. Exceptions: `GET /api/operations/schema` returns raw JSON (per-tier private caching with ETag revalidation per ADR-0002 + I3), health probes return flat objects, and `POST /api/contact` returns 204 with no body.  **Availability metadata.** This spec uses the `x-availability` vendor extension as **decorative documentation only**. Per [ADR-0001](../docs/decisions/0001-contract-first-availability.md) §1.5, the runtime endpoint `GET /api/operations/schema` (ticket I3) is the authoritative source; the sidecar `availability.json` (ticket I3b) is the authoritative companion (generated, never hand-edited; CI cross-checks runtime ⇄ sidecar). SDKs MUST NOT depend on `x-availability` reaching generated code — code-generators that surface vendor extensions may emit it as documentation, but consumers read availability from the runtime endpoint, not from the generated bindings.  The 5-value vocabulary (`stable | beta | experimental | planned | deprecated`) is defined in the `AvailabilityValue` schema. See `schemas/FORMAT.md` §Availability Taxonomy for the operational rules (parser obligation: absent = stable; per-enum-value granularity is the `per_value_availability` primitive landed via ticket I17).  **Free-text string fields: `x-string-vocabulary` (ticket [`Q79yjcFF`](https://trello.com/c/Q79yjcFF)).** A `type: string` field with no `enum` that names example values says, as data, what a client may do with them (the same marker is used in the AsyncAPI document): - `open` — a vocabulary that grows. Each published value keeps its   meaning, the SET is not closed: switch on the values you know and   handle an unknown one as the generic case (e.g. `ErrorEnvelope.error`). - `advisory` — explanatory text. Display or log it; **never switch on   it** (e.g. `SseWorkflowTerminalData.reason`). - `none` — not a vocabulary at all (an expression or an identifier,   e.g. `OptionSchema.pattern`). A field whose description hedges with \"common values\" or \"free-form\" must carry the marker; a test enforces it.  **Localisation (per ticket [I26](https://trello.com/c/rcnqwgI4)).**  Error responses + paused/blocked workflow statuses carry a localised human-readable `message` alongside a stable, never-localised `message_key`. Machine-readable fields (`error`, enum values, status codes) stay canonical English.  - **Currently committed locales:** `en-GB` only (per ticket   [`4GKyuYo6`](https://trello.com/c/4GKyuYo6)). The I26 carrier   shape (`Accept-Language` + `Content-Language` + `Vary` headers +   `locale` envelope field + `message_key` + `message_params`) is   stable and exercised; the **catalog** of translated `message`   strings is en-GB-only at runtime today. Additional locales (e.g.   `pt-PT`) will be advertised by name when their catalogs ship —   the request/response carrier shape does NOT change when a new   locale lands. Treat unrequested locales as \"machine-code +   `message_key` path is committed; localised `message` prose is   not\" until this prose enumerates them by name. - **Request:** `Accept-Language` header per RFC 9110 §12.5.4 (q-value   negotiation supported). The server selects the best-match locale   from its supported list; falls back to `en-GB` when no match —   which, until additional catalogs land, is every non-`en-GB`   `Accept-Language`. - **Response:** `Content-Language: <locale>` echo on every localised   response; `Vary: Accept-Language` on every response (CDN/cache   correctness — different `Accept-Language` requests produce   different responses). `Vary` is emitted unconditionally so the   header contract does not flip when a second locale ships. - **Fallback locale:** `en-GB` (also the canonical locale for   `message_key` translations and English `message` prose). - **SDK guidance:** switch on `error` (machine code) for typed   error branches; surface `message_key` to client-side i18n   catalogs (SDK companion work tracked at X19, cross-repo);   display `message` for end-user UI; **never parse `message` for   control flow** — it changes per locale.  Carrier shape lives on `ErrorEnvelope` (envelope-level optional `message_key` + `message` + `locale` + `message_params`) and `ValidationErrorEnvelope` (also per-`details[]` entry). Existing 402 / 403 / 422 envelopes (`BalanceExhaustedResponse`, `FeatureNotAvailableResponse`, `FeatureTierRestrictedResponse`, `WorkflowPausedDetail`) inherit the convention.  **Upload thresholds (per tickets [u0ar7Yye](https://trello.com/c/u0ar7Yye) + [58nBQLWQ](https://trello.com/c/58nBQLWQ)).** Canonical upload constants (single-shot cap, multipart chunk size, multipart concurrency default, multipart first-chunk size) live on the `UploadThresholds` schema with `const:`-pinned values. SDK generators emit these as typed binding constants so frontend / API / SDKs reference one source of truth instead of hardcoding magic numbers. A runtime `GET /api/uploads/limits` endpoint for dynamic discovery (per-tier / per-environment overrides) is a deferred follow-up.
  *
- * The version of the OpenAPI document: 2.213.0
+ * The version of the OpenAPI document: 2.214.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

package/dist/openapi/runtime.d.ts

@@ -2,7 +2,7 @@
  * GISL Compression API
  * REST API for the GISL (Give It Smaller) file compression and processing service.  **Architecture:** - Upload files to get a `file_id` - Create workflows referencing uploaded files with operations (compress, thumbnail, image_watermark, text_watermark, merge, archive, convert, custom_luma, audio_overlay, audio_watermark) - Poll status, stream SSE events, or receive webhook callbacks - Download results per operation output  **Response envelope:** All mutation and query endpoints return `{ success: true, data: {...} }` on success and `{ success: false, error: \"...\", details: [...] }` on failure. Exceptions: `GET /api/operations/schema` returns raw JSON (per-tier private caching with ETag revalidation per ADR-0002 + I3), health probes return flat objects, and `POST /api/contact` returns 204 with no body.  **Availability metadata.** This spec uses the `x-availability` vendor extension as **decorative documentation only**. Per [ADR-0001](../docs/decisions/0001-contract-first-availability.md) §1.5, the runtime endpoint `GET /api/operations/schema` (ticket I3) is the authoritative source; the sidecar `availability.json` (ticket I3b) is the authoritative companion (generated, never hand-edited; CI cross-checks runtime ⇄ sidecar). SDKs MUST NOT depend on `x-availability` reaching generated code — code-generators that surface vendor extensions may emit it as documentation, but consumers read availability from the runtime endpoint, not from the generated bindings.  The 5-value vocabulary (`stable | beta | experimental | planned | deprecated`) is defined in the `AvailabilityValue` schema. See `schemas/FORMAT.md` §Availability Taxonomy for the operational rules (parser obligation: absent = stable; per-enum-value granularity is the `per_value_availability` primitive landed via ticket I17).  **Free-text string fields: `x-string-vocabulary` (ticket [`Q79yjcFF`](https://trello.com/c/Q79yjcFF)).** A `type: string` field with no `enum` that names example values says, as data, what a client may do with them (the same marker is used in the AsyncAPI document): - `open` — a vocabulary that grows. Each published value keeps its   meaning, the SET is not closed: switch on the values you know and   handle an unknown one as the generic case (e.g. `ErrorEnvelope.error`). - `advisory` — explanatory text. Display or log it; **never switch on   it** (e.g. `SseWorkflowTerminalData.reason`). - `none` — not a vocabulary at all (an expression or an identifier,   e.g. `OptionSchema.pattern`). A field whose description hedges with \"common values\" or \"free-form\" must carry the marker; a test enforces it.  **Localisation (per ticket [I26](https://trello.com/c/rcnqwgI4)).**  Error responses + paused/blocked workflow statuses carry a localised human-readable `message` alongside a stable, never-localised `message_key`. Machine-readable fields (`error`, enum values, status codes) stay canonical English.  - **Currently committed locales:** `en-GB` only (per ticket   [`4GKyuYo6`](https://trello.com/c/4GKyuYo6)). The I26 carrier   shape (`Accept-Language` + `Content-Language` + `Vary` headers +   `locale` envelope field + `message_key` + `message_params`) is   stable and exercised; the **catalog** of translated `message`   strings is en-GB-only at runtime today. Additional locales (e.g.   `pt-PT`) will be advertised by name when their catalogs ship —   the request/response carrier shape does NOT change when a new   locale lands. Treat unrequested locales as \"machine-code +   `message_key` path is committed; localised `message` prose is   not\" until this prose enumerates them by name. - **Request:** `Accept-Language` header per RFC 9110 §12.5.4 (q-value   negotiation supported). The server selects the best-match locale   from its supported list; falls back to `en-GB` when no match —   which, until additional catalogs land, is every non-`en-GB`   `Accept-Language`. - **Response:** `Content-Language: <locale>` echo on every localised   response; `Vary: Accept-Language` on every response (CDN/cache   correctness — different `Accept-Language` requests produce   different responses). `Vary` is emitted unconditionally so the   header contract does not flip when a second locale ships. - **Fallback locale:** `en-GB` (also the canonical locale for   `message_key` translations and English `message` prose). - **SDK guidance:** switch on `error` (machine code) for typed   error branches; surface `message_key` to client-side i18n   catalogs (SDK companion work tracked at X19, cross-repo);   display `message` for end-user UI; **never parse `message` for   control flow** — it changes per locale.  Carrier shape lives on `ErrorEnvelope` (envelope-level optional `message_key` + `message` + `locale` + `message_params`) and `ValidationErrorEnvelope` (also per-`details[]` entry). Existing 402 / 403 / 422 envelopes (`BalanceExhaustedResponse`, `FeatureNotAvailableResponse`, `FeatureTierRestrictedResponse`, `WorkflowPausedDetail`) inherit the convention.  **Upload thresholds (per tickets [u0ar7Yye](https://trello.com/c/u0ar7Yye) + [58nBQLWQ](https://trello.com/c/58nBQLWQ)).** Canonical upload constants (single-shot cap, multipart chunk size, multipart concurrency default, multipart first-chunk size) live on the `UploadThresholds` schema with `const:`-pinned values. SDK generators emit these as typed binding constants so frontend / API / SDKs reference one source of truth instead of hardcoding magic numbers. A runtime `GET /api/uploads/limits` endpoint for dynamic discovery (per-tier / per-environment overrides) is a deferred follow-up.
  *
- * The version of the OpenAPI document: 2.213.0
+ * The version of the OpenAPI document: 2.214.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

package/dist/openapi/runtime.js

@@ -4,7 +4,7 @@
  * GISL Compression API
  * REST API for the GISL (Give It Smaller) file compression and processing service.  **Architecture:** - Upload files to get a `file_id` - Create workflows referencing uploaded files with operations (compress, thumbnail, image_watermark, text_watermark, merge, archive, convert, custom_luma, audio_overlay, audio_watermark) - Poll status, stream SSE events, or receive webhook callbacks - Download results per operation output  **Response envelope:** All mutation and query endpoints return `{ success: true, data: {...} }` on success and `{ success: false, error: \"...\", details: [...] }` on failure. Exceptions: `GET /api/operations/schema` returns raw JSON (per-tier private caching with ETag revalidation per ADR-0002 + I3), health probes return flat objects, and `POST /api/contact` returns 204 with no body.  **Availability metadata.** This spec uses the `x-availability` vendor extension as **decorative documentation only**. Per [ADR-0001](../docs/decisions/0001-contract-first-availability.md) §1.5, the runtime endpoint `GET /api/operations/schema` (ticket I3) is the authoritative source; the sidecar `availability.json` (ticket I3b) is the authoritative companion (generated, never hand-edited; CI cross-checks runtime ⇄ sidecar). SDKs MUST NOT depend on `x-availability` reaching generated code — code-generators that surface vendor extensions may emit it as documentation, but consumers read availability from the runtime endpoint, not from the generated bindings.  The 5-value vocabulary (`stable | beta | experimental | planned | deprecated`) is defined in the `AvailabilityValue` schema. See `schemas/FORMAT.md` §Availability Taxonomy for the operational rules (parser obligation: absent = stable; per-enum-value granularity is the `per_value_availability` primitive landed via ticket I17).  **Free-text string fields: `x-string-vocabulary` (ticket [`Q79yjcFF`](https://trello.com/c/Q79yjcFF)).** A `type: string` field with no `enum` that names example values says, as data, what a client may do with them (the same marker is used in the AsyncAPI document): - `open` — a vocabulary that grows. Each published value keeps its   meaning, the SET is not closed: switch on the values you know and   handle an unknown one as the generic case (e.g. `ErrorEnvelope.error`). - `advisory` — explanatory text. Display or log it; **never switch on   it** (e.g. `SseWorkflowTerminalData.reason`). - `none` — not a vocabulary at all (an expression or an identifier,   e.g. `OptionSchema.pattern`). A field whose description hedges with \"common values\" or \"free-form\" must carry the marker; a test enforces it.  **Localisation (per ticket [I26](https://trello.com/c/rcnqwgI4)).**  Error responses + paused/blocked workflow statuses carry a localised human-readable `message` alongside a stable, never-localised `message_key`. Machine-readable fields (`error`, enum values, status codes) stay canonical English.  - **Currently committed locales:** `en-GB` only (per ticket   [`4GKyuYo6`](https://trello.com/c/4GKyuYo6)). The I26 carrier   shape (`Accept-Language` + `Content-Language` + `Vary` headers +   `locale` envelope field + `message_key` + `message_params`) is   stable and exercised; the **catalog** of translated `message`   strings is en-GB-only at runtime today. Additional locales (e.g.   `pt-PT`) will be advertised by name when their catalogs ship —   the request/response carrier shape does NOT change when a new   locale lands. Treat unrequested locales as \"machine-code +   `message_key` path is committed; localised `message` prose is   not\" until this prose enumerates them by name. - **Request:** `Accept-Language` header per RFC 9110 §12.5.4 (q-value   negotiation supported). The server selects the best-match locale   from its supported list; falls back to `en-GB` when no match —   which, until additional catalogs land, is every non-`en-GB`   `Accept-Language`. - **Response:** `Content-Language: <locale>` echo on every localised   response; `Vary: Accept-Language` on every response (CDN/cache   correctness — different `Accept-Language` requests produce   different responses). `Vary` is emitted unconditionally so the   header contract does not flip when a second locale ships. - **Fallback locale:** `en-GB` (also the canonical locale for   `message_key` translations and English `message` prose). - **SDK guidance:** switch on `error` (machine code) for typed   error branches; surface `message_key` to client-side i18n   catalogs (SDK companion work tracked at X19, cross-repo);   display `message` for end-user UI; **never parse `message` for   control flow** — it changes per locale.  Carrier shape lives on `ErrorEnvelope` (envelope-level optional `message_key` + `message` + `locale` + `message_params`) and `ValidationErrorEnvelope` (also per-`details[]` entry). Existing 402 / 403 / 422 envelopes (`BalanceExhaustedResponse`, `FeatureNotAvailableResponse`, `FeatureTierRestrictedResponse`, `WorkflowPausedDetail`) inherit the convention.  **Upload thresholds (per tickets [u0ar7Yye](https://trello.com/c/u0ar7Yye) + [58nBQLWQ](https://trello.com/c/58nBQLWQ)).** Canonical upload constants (single-shot cap, multipart chunk size, multipart concurrency default, multipart first-chunk size) live on the `UploadThresholds` schema with `const:`-pinned values. SDK generators emit these as typed binding constants so frontend / API / SDKs reference one source of truth instead of hardcoding magic numbers. A runtime `GET /api/uploads/limits` endpoint for dynamic discovery (per-tier / per-environment overrides) is a deferred follow-up.
  *
- * The version of the OpenAPI document: 2.213.0
+ * The version of the OpenAPI document: 2.214.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).

package/openapi/api.yaml

@@ -103,7 +103,7 @@ info:
     of truth instead of hardcoding magic numbers. A runtime
     `GET /api/uploads/limits` endpoint for dynamic discovery
     (per-tier / per-environment overrides) is a deferred follow-up.
-  version: 2.213.0
+  version: 2.214.0
   contact:
     name: API Support
 
@@ -9922,9 +9922,11 @@ components:
     ProcessingClassRejectReason:
       type: string
       description: |
-        Why a job cannot be classified — input size/duration exceeds
-        the `long_form` (or `long_form_re_encode`) ceiling under the
-        caller's effective per-tier caps (per
+        Why a job cannot be classified: an input exceeds the ceiling of
+        the last class it could reach — the `long_form` (or
+        `long_form_re_encode`) ceiling, or the `short_form` ceiling when
+        `long_form` is not available — or its resolution band is not
+        served. Ceilings are the caller's effective per-tier caps (per
         [ADR-0011](../docs/decisions/0011-per-tier-processing-class-constraints.md)
         `per_tier_constraints`). Distinct from `ProcessingClassReason`
         (which describes WHY a job got its assigned class — success-
@@ -9948,11 +9950,35 @@ components:
           (`max_total_input_size_bytes` / `max_total_duration`).
           Applies to operations whose `processing_class.<class>.
           constraints` carries `max_total_*` — merge today.
+        - `input_size_exceeds_short_form_no_long_form` /
+          `input_duration_exceeds_short_form_no_long_form`: a single input exceeds the
+          `short_form` ceiling (the band's, when the class declares
+          `resolution_bands`) AND the job cannot escalate to `long_form`
+          because that class is not available. `processing_class` on the
+          violation is `short_form`. Added 2026-09-25 for api `nslA1V1S`;
+          before, such a refusal had to borrow a `*_long_form` reason.
+          The `_no_long_form` suffix keeps these distinct from
+          `ProcessingClassReason`'s `*_exceeds_short_form`, which means
+          the job ESCALATED (the two enums are kept disjoint on purpose).
+        - `resolution_band_not_served`: the input's resolution band is
+          `basis: not_served` on the class (FORMAT.md §`resolution_bands`),
+          so no duration or size fits. `actual` is the input's FRAME
+          PIXELS (width x height) and `ceiling` is the `max_frame_pixels`
+          of the highest band the class DOES serve; `resolution_band`
+          names the band. The `unknown` band is never `not_served` (CI),
+          so this reason always has a measured `actual`.
+      # OPEN: a new reason is a new refusal cause. A consumer that does not know
+      # one shows the envelope's localised message; `actual` / `ceiling` stay
+      # integers in the unit the reason names.
+      x-enum-openness: open
       enum:
         - input_size_exceeds_long_form
         - input_duration_exceeds_long_form
         - combined_size_exceeds_long_form
         - combined_duration_exceeds_long_form
+        - input_size_exceeds_short_form_no_long_form
+        - input_duration_exceeds_short_form_no_long_form
+        - resolution_band_not_served
 
     ProcessingClassBandViolation:
       type: object
@@ -9968,6 +9994,14 @@ components:
         fail-all violations back to the offending job in multi-job
         workflows and (b) render "X exceeded by Y" without re-deriving
         caps from the per-tier overlay.
+      # A not_served refusal names the band it refused (codex #606).
+      if:
+        properties:
+          reason:
+            const: resolution_band_not_served
+        required: [reason]
+      then:
+        required: [resolution_band]
       required:
         - reason
         - job_ref
@@ -9996,10 +10030,11 @@ components:
           description: |
             0-based ordinal into `JobDefinition.inputs[]` identifying
             the specific input that violated the per-input ceiling.
-            Set ONLY on `input_*_exceeds_long_form` reasons for
-            multi-input operations; omitted on single-input
-            operations (no positional ambiguity) and on
-            `combined_*_exceeds_long_form` reasons (whole-job
+            Set on every PER-INPUT reason (`input_*_exceeds_long_form`,
+            `input_*_exceeds_short_form_no_long_form`,
+            `resolution_band_not_served`) for multi-input operations;
+            omitted on single-input operations (no positional ambiguity)
+            and on `combined_*_exceeds_long_form` reasons (whole-job
             violation across all inputs).
         operation:
           $ref: '#/components/schemas/OperationType'
@@ -10007,22 +10042,27 @@ components:
         processing_class:
           $ref: '#/components/schemas/ProcessingClass'
           description: |
-            The class whose ceiling was exceeded — typically `long_form`
-            or `long_form_re_encode`.
+            The class whose ceiling was exceeded: `long_form` /
+            `long_form_re_encode`, or `short_form` for the
+            `*_exceeds_short_form_no_long_form` reasons and for a
+            `not_served` band on short_form.
         resolution_band:
           $ref: '#/components/schemas/ResolutionBand'
           description: |
             The band whose ceiling `ceiling` is, when the class declares
-            `resolution_bands`; omitted otherwise. `unknown` means the
+            `resolution_bands`; omitted otherwise. EXCEPTION: for
+            `resolution_band_not_served` it names the INPUT's (unserved)
+            band, and `ceiling` is the highest served band's
+            `max_frame_pixels`, not this band's. `unknown` means the
             resolution could not be determined — a different customer
             action from a known-resolution overflow.
         actual:
           type: integer
           minimum: 0
           description: |
-            Observed value. Bytes for `*_size_exceeds_long_form`
-            reasons; whole seconds for `*_duration_exceeds_long_form`
-            reasons.
+            Observed value. Bytes for `*_size_exceeds_*` reasons; whole
+            seconds for `*_duration_exceeds_*` reasons; frame pixels
+            (width x height) for `resolution_band_not_served`.
         ceiling:
           type: integer
           minimum: 0
@@ -10030,7 +10070,9 @@ components:
             Effective per-tier ceiling for this caller (same units as
             `actual`). The binding cap after `per_tier_constraints`
             overlay; lets consumers render "X exceeded by Y" without
-            re-deriving caps from the per-tier overlay.
+            re-deriving caps from the per-tier overlay. EXCEPTION: for
+            `resolution_band_not_served` it is the highest served band's
+            `max_frame_pixels` (a resolution bound, not a per-tier cap).
         required_tier:
           description: |
             Optional. When a HIGHER tier exists whose
@@ -14709,6 +14751,17 @@ components:
           const: 100
         result:
           $ref: '#/components/schemas/SseOperationCompletionResult'
+        result_metadata:
+          $ref: '#/components/schemas/OperationResultMetadata'
+          description: |
+            OPTIONAL. The same whitelisted per-operation metadata the REST
+            operation object serves as `result_metadata` (a sibling of
+            `result` there too): `already_optimal`, `estimated_saving_pct`,
+            `watermark_id`. It lets the completion frame say "already
+            optimal" without a follow-up read. Absent means the frame does
+            not carry it, NOT that the operation has no metadata; a consumer
+            that needs it falls back to the REST read. Card `Fu372Ze7`
+            (api), contracts `DIDOPiZQ`.
 
     SseOperationCompletionResult:
       description: |

package/operation-capabilities/operation-capabilities.json

@@ -860,5 +860,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.213.0"
+  "schema_version": "2.214.0"
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.78.0",
-  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.213.0.",
-  "gislContractsSpec": "v2.213.0",
+  "version": "0.79.0",
+  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.214.0.",
+  "gislContractsSpec": "v2.214.0",
   "license": "Apache-2.0",
   "homepage": "https://docs.giveitsmaller.com",
   "bugs": {