@giveitsmaller/contracts 0.58.0 → 0.59.0

package/accepted-options/accepted-options.json

@@ -1088,6 +1088,20 @@
         },
         "output_format_option": null
       },
+      "document_epub": {
+        "accepted_options": {
+          "*": [
+            "fit",
+            "format",
+            "height",
+            "page",
+            "quality",
+            "source",
+            "width"
+          ]
+        },
+        "output_format_option": null
+      },
       "image": {
         "accepted_options": {
           "*": [
@@ -1187,5 +1201,5 @@
       }
     }
   },
-  "schema_version": "2.171.0"
+  "schema_version": "2.180.0"
 }

package/accepted-options/image-output-routes.json

@@ -246,5 +246,5 @@
       "source_op": "compress"
     }
   },
-  "schema_version": "2.171.0"
+  "schema_version": "2.180.0"
 }

package/asyncapi/events.yaml

@@ -4186,9 +4186,13 @@ components:
 
             **Purpose (future-proofing per ADR-0022).** The API consumes this MIME +
             its deterministic MIME→extension map (`DownloadFilenameComputer`) to derive
-            the canonical download extension and the download `Content-Type` header
-            SERVER-SIDE. It is NOT the download filename (the API already has that from
-            the key). For today's traffic the API can infer the output MIME (compress is
+            the canonical download extension SERVER-SIDE (it does NOT set
+            `Content-Type` from this field). It is NOT the download filename — the API synthesises that
+            from the upload's `original_name`, and `output_file_type` feeds only the
+            download EXTENSION (see `OperationDownload.filename` in
+            `openapi/api.yaml` for the full synthesis; the presigner sets
+            `Content-Disposition`, and `Content-Type` is not derived from this
+            field). For today's traffic the API can infer the output MIME (compress is
             same-format; the compress+format facade canonicalizes to `convert` whose
             target is known), so this is **advisory/future-proofing** for a
             runtime-format-selection path (e.g. `compress output_format=auto|smallest`,
@@ -4199,7 +4203,7 @@ components:
             completion-result surface as `OperationResult.mime_type` (advisory/optional —
             the OpenAPI surface names the concept `mime_type`), so the client can name the
             server-chosen format for the savings readout. The download `OperationDownload`
-            schema still carries no echo: the API derives its ext/Content-Type server-side.
+            schema still carries no echo: the API derives its download extension server-side.
           example: "image/webp"
 
         # Multi-output success fields (per ADR-0009 MultiOutputCompletion)
@@ -4355,16 +4359,20 @@ components:
             multi-output (heterogeneous fan-out e.g. convert PDF→image — each entry MAY
             differ); the top-level `output_file_type` covers the single-output shape.
             Present on completion only. See ADR-0022 — the API derives the per-output
-            download extension + Content-Type server-side from this MIME via its
-            MIME→extension map. Future-proofing (additive now, cf. `target_id`).
+            download extension server-side from this MIME via its
+            MIME→extension map (it does NOT set `Content-Type` from this field;
+            the presigner sets `Content-Disposition` only). Future-proofing (additive now, cf. `target_id`).
           example: "image/png"
         page_index:
           type: integer
           minimum: 1
           description: |
-            1-based page number for PDF-page outputs. Gapless within an
-            operation (an N-page conversion emits `page_index` 1..N). Mutually
-            exclusive with `position`. Per ADR-0009 §D2.
+            1-based **literal source page number** for PDF-page outputs —
+            the actual page from the input PDF. A full conversion emits `1..N`;
+            a sparse `pages` selection (e.g. `'1-5,8'`) emits exactly the
+            selected pages (`1,2,3,4,5,8`) — gapless ONLY for a full conversion.
+            Mutually exclusive with `position`. Normative semantics:
+            ADR-0009 §D2.
           example: 1
         position:
           type: integer

package/availability/availability.json

@@ -1,5 +1,5 @@
 {
-  "capabilities_version": 168,
+  "capabilities_version": 172,
   "endpoints": {
     "DELETE /api/auth/api-keys/{apiKeyId}": {
       "auth": "required",
@@ -253,6 +253,13 @@
       "operation_id": "createWorkflow",
       "required_tier": null
     },
+    "POST /api/workflows/{id}/archive": {
+      "auth": "required",
+      "availability": "stable",
+      "identity_scoped": true,
+      "operation_id": "archiveWorkflow",
+      "required_tier": null
+    },
     "POST /api/workflows/{id}/cancel": {
       "auth": "required",
       "availability": "stable",
@@ -260,6 +267,13 @@
       "operation_id": "cancelWorkflow",
       "required_tier": null
     },
+    "POST /api/workflows/{id}/restore": {
+      "auth": "required",
+      "availability": "stable",
+      "identity_scoped": true,
+      "operation_id": "restoreWorkflow",
+      "required_tier": null
+    },
     "POST /api/workflows/{id}/resume": {
       "auth": "required",
       "availability": "stable",
@@ -669,6 +683,7 @@
       "max_inputs": 2,
       "mime_groups": {
         "audio": {
+          "max_input_duration": "PT2H",
           "mimes": [
             "audio/mpeg",
             "audio/aac",
@@ -964,6 +979,7 @@
           }
         },
         "document_epub": {
+          "max_input_size_bytes": 104857600,
           "mimes": [
             "application/epub+zip"
           ],
@@ -990,6 +1006,7 @@
           }
         },
         "document_odf": {
+          "max_input_size_bytes": 104857600,
           "mimes": [
             "application/vnd.oasis.opendocument.text",
             "application/vnd.oasis.opendocument.spreadsheet",
@@ -1018,6 +1035,7 @@
           }
         },
         "document_office": {
+          "max_input_size_bytes": 104857600,
           "mimes": [
             "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
             "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
@@ -1052,6 +1070,7 @@
           }
         },
         "image": {
+          "max_input_size_bytes": 524288000,
           "max_output_pixels": 16000000,
           "mimes": [
             "image/gif",
@@ -1175,6 +1194,7 @@
           }
         },
         "image_avif": {
+          "max_input_size_bytes": 20971520,
           "max_output_pixels": 16000000,
           "mimes": [
             "image/avif"
@@ -1345,6 +1365,7 @@
           }
         },
         "image_jpeg": {
+          "max_input_size_bytes": 524288000,
           "max_output_pixels": 16000000,
           "mimes": [
             "image/jpeg"
@@ -1537,6 +1558,7 @@
           }
         },
         "image_png": {
+          "max_input_size_bytes": 524288000,
           "max_output_pixels": 16000000,
           "mimes": [
             "image/png"
@@ -1664,6 +1686,7 @@
           }
         },
         "image_svg": {
+          "max_input_size_bytes": 524288000,
           "mimes": [
             "image/svg+xml"
           ],
@@ -1687,11 +1710,14 @@
             },
             "output_format": {
               "default": "original",
-              "description": "Output format. original = keep input format (default); webp = recompress to WebP. Concrete format changes are handled by the convert operation. `auto` / `smallest` are PLANNED auto-format directives (the server picks the best/smallest candidate format, reported via the result `mime_type`) \u2014 selection strategies, not concrete targets, planned until supported. See FORMAT.md.",
+              "description": "Output format. `original` = keep input format \u2014 SVG -> SVG optimisation via SVGO. **`original` is PLANNED** (G9O6yrQD): the worker does not implement SVG->SVG optimisation yet (\"SVG is a follow-up\"), so it returns `feature_not_available` (422) rather than 422ing under a `stable` claim. It is also the schema `default`. **KNOWN ENFORCEMENT GAP (api co-land owed):** the API's per-value gate only inspects an EXPLICITLY submitted `output_format` (`CreateWorkflowCommandHandler`: `$requestedFormat = $opDef->options['output_format'] ?? null; if (is_scalar(...))`), so an OMITTED value is not materialized to its default before the check and bypasses this tag \u2014 a bare `compress` on an SVG still dispatches and fails at the worker instead of returning a clean 422. `original` is the first PLANNED DEFAULT in the contract, so nothing exercised that path before. The tag is correct and truthful regardless; closing the gap is api's (gate against the effective default). Ask for `webp` meanwhile \u2014 that route works. `webp` = recompress to WebP: **STABLE and working today** \u2014 this facade route canonicalizes to the `convert` operation (`convert.image_svg` carries its own quality), which is why this group is NOT gated at group level. Concrete format changes are handled by the convert operation. `auto` / `smallest` are PLANNED auto-format directives (the server picks the best/smallest candidate format, reported via the result `mime_type`) \u2014 selection strategies, not concrete targets, planned until supported. See FORMAT.md.",
               "per_value_availability": {
                 "auto": {
                   "availability": "planned"
                 },
+                "original": {
+                  "availability": "planned"
+                },
                 "smallest": {
                   "availability": "planned"
                 }
@@ -1707,6 +1733,7 @@
           }
         },
         "image_webp": {
+          "max_input_size_bytes": 524288000,
           "max_output_pixels": 16000000,
           "mimes": [
             "image/webp"
@@ -2157,7 +2184,7 @@
             },
             "pages": {
               "default": "1",
-              "description": "Page selection (e.g. '1-5,8'). Each resolved page produces a\nseparate output file. **Maximum 200 resolved entries per\nrequest** \u2014 aligns with the `OperationResult.outputs[]`\n`maxItems: 200` cap. Expressions resolving to more than 200\nentries (e.g. `'1-201'`, `'1-100,102-205'`) are out of\ncontract. Duplicate or overlapping entries (e.g. `'1,1'`,\n`'1-100,50-150'`) are counted toward the cap as parsed;\ndeduplication, if any, is a runtime concern and is NOT part\nof this contract.\n",
+              "description": "Page selection (e.g. '1-5,8'). Each resolved page produces a\nseparate output file whose `page_index` is the **literal source\npage number** \u2014 a sparse selection stays sparse: `pages: '1-5,8'`\nyields outputs with `page_index` `1,2,3,4,5,8` (NOT renumbered\n`1..6`), and `pages: '5-7'` yields `5,6,7`. The download `filename`\nsuffix is a separate 0-based array position and does NOT track the\npage number. **Maximum 200 resolved entries per\nrequest** \u2014 aligns with the `OperationResult.outputs[]`\n`maxItems: 200` cap. Expressions resolving to more than 200\nentries (e.g. `'1-201'`, `'1-100,102-205'`) are out of\ncontract. Duplicate or overlapping entries (e.g. `'1,1'`,\n`'1-100,50-150'`) are counted toward the cap as parsed;\ndeduplication, if any, is a runtime concern and is NOT part\nof this contract.\n",
               "type": "string"
             }
           }
@@ -3824,7 +3851,7 @@
     "split": {
       "availability": "beta",
       "default": false,
-      "description": "Fan one input file into N outputs across GIF, PDF, audio, and\nvideo MIME families. Single-input \u2014 one input file per job, fanned\ninto N outputs per the per-mime-group catalog. Mirrors the\n`merge` / `convert` catalog-split-by-mime-group pattern.\n\n**Three shared modes** (audio + video; the mode discriminator\ngates which option applies per the `depends_on` rules in this\nschema):\n- `interval`: split every N numeric-seconds.\n- `count`: split into N equal-duration pieces (integer 2..=200).\n- `cut_points`: explicit cut points in numeric-seconds (strictly\n  increasing, no duplicates, each > 0 and < probed duration).\n\n**Plus an audio-only `silence` mode** (`beta`, gated by the\n`silence_mode_audio` feature): cut at detected silence gaps via\nserver-side silence detection. Video stays three-mode.\n\n**GIF + PDF use range-based selection** instead of three modes:\n- GIF (`image_gif`): `frame_range` REQUIRED + `output_format`\n  enum {png,webp,jpg}.\n- PDF (`document_pdf`): `page_range` OR `page_groups` (mutually\n  exclusive per `depends_on`).\n\n**Wire format**: numeric seconds (floats allowed for sub-second\nprecision). NOT ISO 8601 duration strings. Matches common\nvideo-tooling conventions.\n\n**200-output hard cap** (`OperationResult.outputs[].maxItems:\n200`). Preflight rejects\nrequests exceeding this BEFORE work as `invalid_options` (422).\nCap math by mode:\n- `interval`: `ceil(probed_duration / interval) <= 200`\n- `count`: enforced by the option's `min: 2 max: 200` range\n- `cut_points`: `cut_points.len() + 1 <= 200`\n- `silence` (audio): resolved segment count (detected gaps + 1)\n  `<= 200`; preflight rejects as `invalid_options` (422)\n- PDF: resolved page count after expansion `<= 200`\n  (cross-ref [`WgCqnMRa`](https://trello.com/c/WgCqnMRa))\n- GIF: resolved frame count after expansion `<= 200`\n\n**Output naming**: 3-digit zero-padded \u2014 `output-001` ..\n`output-200`. Matches the convert PDF\u2192N precedent.\n\n**Output envelope binding**:\n- `image_gif`: `PositionIndexed` (frame stream-position 0-based\n  ordinal)\n- `document_pdf`: `PageIndexed` (1-based gapless page index)\n- `audio`: `PositionIndexed` (cut stream-position ordinal)\n- `video`: `PositionIndexed` (cut stream-position ordinal)\n\n**`precision` flag** (audio + video only): `fast` (default) =\npacket-boundary approximate cuts; `exact` = re-encode-aligned\nprecise cuts. Mime_group scoping is the gate \u2014 precision does\nNOT apply to GIF or PDF (frame extraction is exact and PDF page\nselection is exact by definition).\n\n**Long-form video** routes to a separate long-form processing\npath (same `split` OperationType; routing via `processing_class`).\nNo schema-side discriminator beyond MIME detection +\n`processing_class`.\n\n`availability: beta` for the `audio` and `video` mime_groups\n(shape-stable + opt-in, MUST NOT 422). Video activates **both\nclasses**: `video.processing_class.short_form` AND `long_form` are\n`beta`. The `image_gif` and `document_pdf` mime_groups stay\n`availability: planned` until their cross-repo backend support ships;\ndispatch returns `feature_not_available` (422) for the still-planned\ngroups/classes until then.\n",
+      "description": "Fan one input file into N outputs across GIF, PDF, audio, and\nvideo MIME families. Single-input \u2014 one input file per job, fanned\ninto N outputs per the per-mime-group catalog. Mirrors the\n`merge` / `convert` catalog-split-by-mime-group pattern.\n\n**Three shared modes** (audio + video; the mode discriminator\ngates which option applies per the `depends_on` rules in this\nschema):\n- `interval`: split every N numeric-seconds.\n- `count`: split into N equal-duration pieces (integer 2..=200).\n- `cut_points`: explicit cut points in numeric-seconds (strictly\n  increasing, no duplicates, each > 0 and < probed duration).\n\n**Plus an audio-only `silence` mode** (`beta`, gated by the\n`silence_mode_audio` feature): cut at detected silence gaps via\nserver-side silence detection. Video stays three-mode.\n\n**GIF + PDF use range-based selection** instead of three modes:\n- GIF (`image_gif`): `frame_range` REQUIRED + `output_format`\n  enum {png,webp,jpg}.\n- PDF (`document_pdf`): `page_range` OR `page_groups` (mutually\n  exclusive per `depends_on`).\n\n**Wire format**: numeric seconds (floats allowed for sub-second\nprecision). NOT ISO 8601 duration strings. Matches common\nvideo-tooling conventions.\n\n**200-output hard cap** (`OperationResult.outputs[].maxItems:\n200`). Preflight rejects\nrequests exceeding this BEFORE work as `invalid_options` (422).\nCap math by mode:\n- `interval`: `ceil(probed_duration / interval) <= 200`\n- `count`: enforced by the option's `min: 2 max: 200` range\n- `cut_points`: `cut_points.len() + 1 <= 200`\n- `silence` (audio): resolved segment count (detected gaps + 1)\n  `<= 200`; preflight rejects as `invalid_options` (422)\n- PDF: resolved page count after expansion `<= 200`\n  (cross-ref [`WgCqnMRa`](https://trello.com/c/WgCqnMRa))\n- GIF: resolved frame count after expansion `<= 200`\n\n**Output naming (S3 object key)**: the object-key leaf is 3-digit\nzero-padded \u2014 `output-001` .. `output-200` (ADR-0014 \u00a7D9). This binds the\n**S3 object key**, NOT the user-facing download filename \u2014 the API\nsynthesises that separately (see `OperationDownload.filename` in\n`openapi/api.yaml`). Only the **3-digit zero-padding** follows the convert\nPDF\u2192N precedent \u2014 convert keys are `page-NNN.ext`, split keys are\n`output-NNN.ext`.\n\n**Output envelope binding**:\n- `image_gif`: `PositionIndexed` (frame stream-position 0-based\n  ordinal)\n- `document_pdf`: `PageIndexed` (1-based literal source page number).\n  **`mode: page_range` only** \u2014 each output is one page, so `page_index` is\n  that page. For **`mode: page_groups`** an output spans multiple source\n  pages, so a single `page_index` cannot name them all; that grouped-output\n  semantics is NOT specified by this correction and is deferred (do not\n  assume it is the group's first page \u2014 that is unverified).\n- `audio`: `PositionIndexed` (cut stream-position ordinal)\n- `video`: `PositionIndexed` (cut stream-position ordinal)\n\n**`precision` flag** (audio + video only): `fast` (default) =\npacket-boundary approximate cuts; `exact` = re-encode-aligned\nprecise cuts. Mime_group scoping is the gate \u2014 precision does\nNOT apply to GIF or PDF (frame extraction is exact and PDF page\nselection is exact by definition).\n\n**Long-form video** routes to a separate long-form processing\npath (same `split` OperationType; routing via `processing_class`).\nNo schema-side discriminator beyond MIME detection +\n`processing_class`.\n\n`availability: beta` for the `audio` and `video` mime_groups\n(shape-stable + opt-in, MUST NOT 422). Video activates **both\nclasses**: `video.processing_class.short_form` AND `long_form` are\n`beta`. The `image_gif` and `document_pdf` mime_groups stay\n`availability: planned` until their cross-repo backend support ships;\ndispatch returns `feature_not_available` (422) for the still-planned\ngroups/classes until then.\n",
       "features": {
         "silence_mode_audio": {
           "availability": "beta",
@@ -4386,7 +4413,6 @@
           "max_output_pixels": 16000000,
           "mimes": [
             "application/pdf",
-            "application/epub+zip",
             "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
             "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
             "application/vnd.openxmlformats-officedocument.presentationml.presentation",
@@ -4445,7 +4471,79 @@
             },
             "source": {
               "default": "page",
-              "description": "page = render a specific page/slide, cover = extract cover image (EPUB only, ignored for other formats)",
+              "description": "`page` = render a specific page/slide. `cover` = extract a cover image \u2014 only meaningful for EPUB inputs, which are served by the `document_epub` group; on PDF/office/ODF it is accepted and IGNORED (retained for backward compatibility).",
+              "type": "enum",
+              "values": [
+                "page",
+                "cover"
+              ]
+            },
+            "width": {
+              "description": "Target width in pixels (1-16384; width*height <= 16MP). Optional \u2014 when omitted the server applies an aspect-preserving default (both omitted \u2192 longest edge 320px; only one of width/height provided \u2192 the other is derived from the source aspect ratio).",
+              "max": 16384,
+              "min": 1,
+              "type": "integer"
+            }
+          }
+        },
+        "document_epub": {
+          "availability": "planned",
+          "max_output_pixels": 16000000,
+          "mimes": [
+            "application/epub+zip"
+          ],
+          "options": {
+            "fit": {
+              "default": "crop",
+              "description": "Resize mode",
+              "type": "enum",
+              "values": [
+                "max",
+                "crop",
+                "scale"
+              ]
+            },
+            "format": {
+              "default": "jpg",
+              "description": "Output format for the thumbnail",
+              "type": "enum",
+              "values": [
+                "jpg",
+                "png",
+                "webp"
+              ]
+            },
+            "height": {
+              "description": "Target height in pixels (1-16384; width*height <= 16MP). Optional \u2014 see `width` for the omitted-default behaviour.",
+              "max": 16384,
+              "min": 1,
+              "type": "integer"
+            },
+            "page": {
+              "default": 1,
+              "depends_on": {
+                "source": "page"
+              },
+              "description": "1-based index of the printed page to render, after the book's print-layout pagination is applied.",
+              "min": 1,
+              "type": "integer"
+            },
+            "quality": {
+              "default": 85,
+              "depends_on": {
+                "format": [
+                  "jpg",
+                  "webp"
+                ]
+              },
+              "description": "Output quality for lossy thumbnail formats (jpg/webp): higher = better quality, larger file. Ignored for png (lossless).",
+              "max": 100,
+              "min": 1,
+              "type": "integer"
+            },
+            "source": {
+              "default": "cover",
+              "description": "`cover` (default) = extract the EPUB's declared cover image \u2014 the cheap path, no rendering. `page` = render a paginated page of the book's XHTML. Cover lookup MUST support both mechanisms: the EPUB 3 `cover-image` property on an OPF manifest item, AND the legacy EPUB 2 `<meta name=\"cover\" content=\"...\"/>` pointing at a manifest item \u2014 supporting only the former misses a large slice of real-world files. A cover image is OPTIONAL per W3C EPUB 3.3, so a cover-less EPUB is a real case. The reject shape for it is NOT yet decided and is deliberately unpromised here: `ErrorCode` (asyncapi) is a CLOSED enum with no \"no cover\" member, so a distinct code is a real cross-repo co-land (enum edit -> SDK regen -> lockstep), not a free string. It is settled when this group graduates \u2014 do not infer one from this description.",
               "type": "enum",
               "values": [
                 "page",
@@ -5006,7 +5104,7 @@
       "sole_op": true
     }
   },
-  "schema_version": "2.171.0",
+  "schema_version": "2.180.0",
   "source_commit": null,
   "user_tier": null,
   "workflow_features": {
@@ -5039,6 +5137,24 @@
           }
         }
       }
+    },
+    "processing": {
+      "class_hint": {
+        "per_value_availability": {
+          "auto": {
+            "availability": "stable"
+          },
+          "long_form_allowed": {
+            "availability": "planned"
+          },
+          "long_form_preferred": {
+            "availability": "planned"
+          },
+          "short_form_only": {
+            "availability": "planned"
+          }
+        }
+      }
     }
   }
 }

package/code-builder/code-builder-metadata.json

@@ -739,6 +739,7 @@
       "input_model": "multi",
       "media_groups": {
         "audio": {
+          "max_input_duration": "PT2H",
           "media_group": "audio",
           "mimes": [
             "audio/mpeg",
@@ -1203,6 +1204,7 @@
           }
         },
         "document_epub": {
+          "max_input_size_bytes": 104857600,
           "media_group": "document",
           "mimes": [
             "application/epub+zip"
@@ -1253,6 +1255,7 @@
           }
         },
         "document_odf": {
+          "max_input_size_bytes": 104857600,
           "media_group": "document",
           "mimes": [
             "application/vnd.oasis.opendocument.text",
@@ -1305,6 +1308,7 @@
           }
         },
         "document_office": {
+          "max_input_size_bytes": 104857600,
           "media_group": "document",
           "mimes": [
             "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
@@ -1369,6 +1373,7 @@
           }
         },
         "image": {
+          "max_input_size_bytes": 524288000,
           "max_output_pixels": 16000000,
           "media_group": "image",
           "mimes": [
@@ -1566,6 +1571,7 @@
           }
         },
         "image_avif": {
+          "max_input_size_bytes": 20971520,
           "max_output_pixels": 16000000,
           "media_group": "image",
           "mimes": [
@@ -1831,6 +1837,7 @@
           }
         },
         "image_jpeg": {
+          "max_input_size_bytes": 524288000,
           "max_output_pixels": 16000000,
           "media_group": "image",
           "mimes": [
@@ -2131,6 +2138,7 @@
           }
         },
         "image_png": {
+          "max_input_size_bytes": 524288000,
           "max_output_pixels": 16000000,
           "media_group": "image",
           "mimes": [
@@ -2335,6 +2343,7 @@
           }
         },
         "image_svg": {
+          "max_input_size_bytes": 524288000,
           "media_group": "image",
           "mimes": [
             "image/svg+xml"
@@ -2371,7 +2380,7 @@
             },
             "output_format": {
               "default": "original",
-              "description": "Output format. original = keep input format (default); webp = recompress to WebP. Concrete format changes are handled by the convert operation. `auto` / `smallest` are PLANNED auto-format directives (the server picks the best/smallest candidate format, reported via the result `mime_type`) \u2014 selection strategies, not concrete targets, planned until supported. See FORMAT.md.",
+              "description": "Output format. `original` = keep input format \u2014 SVG -> SVG optimisation via SVGO. **`original` is PLANNED** (G9O6yrQD): the worker does not implement SVG->SVG optimisation yet (\"SVG is a follow-up\"), so it returns `feature_not_available` (422) rather than 422ing under a `stable` claim. It is also the schema `default`. **KNOWN ENFORCEMENT GAP (api co-land owed):** the API's per-value gate only inspects an EXPLICITLY submitted `output_format` (`CreateWorkflowCommandHandler`: `$requestedFormat = $opDef->options['output_format'] ?? null; if (is_scalar(...))`), so an OMITTED value is not materialized to its default before the check and bypasses this tag \u2014 a bare `compress` on an SVG still dispatches and fails at the worker instead of returning a clean 422. `original` is the first PLANNED DEFAULT in the contract, so nothing exercised that path before. The tag is correct and truthful regardless; closing the gap is api's (gate against the effective default). Ask for `webp` meanwhile \u2014 that route works. `webp` = recompress to WebP: **STABLE and working today** \u2014 this facade route canonicalizes to the `convert` operation (`convert.image_svg` carries its own quality), which is why this group is NOT gated at group level. Concrete format changes are handled by the convert operation. `auto` / `smallest` are PLANNED auto-format directives (the server picks the best/smallest candidate format, reported via the result `mime_type`) \u2014 selection strategies, not concrete targets, planned until supported. See FORMAT.md.",
               "enum_ref": "ImageFormat",
               "enum_translations": {
                 "original": "Original",
@@ -2382,6 +2391,9 @@
                 "auto": {
                   "availability": "planned"
                 },
+                "original": {
+                  "availability": "planned"
+                },
                 "smallest": {
                   "availability": "planned"
                 }
@@ -2391,7 +2403,7 @@
               "type": "enum",
               "value_exposure": {
                 "auto": "coming_soon",
-                "original": "expose",
+                "original": "coming_soon",
                 "smallest": "coming_soon",
                 "webp": "expose"
               },
@@ -2419,6 +2431,7 @@
           }
         },
         "image_webp": {
+          "max_input_size_bytes": 524288000,
           "max_output_pixels": 16000000,
           "media_group": "image",
           "mimes": [
@@ -3166,7 +3179,7 @@
             },
             "pages": {
               "default": "1",
-              "description": "Page selection (e.g. '1-5,8'). Each resolved page produces a\nseparate output file. **Maximum 200 resolved entries per\nrequest** \u2014 aligns with the `OperationResult.outputs[]`\n`maxItems: 200` cap. Expressions resolving to more than 200\nentries (e.g. `'1-201'`, `'1-100,102-205'`) are out of\ncontract. Duplicate or overlapping entries (e.g. `'1,1'`,\n`'1-100,50-150'`) are counted toward the cap as parsed;\ndeduplication, if any, is a runtime concern and is NOT part\nof this contract.\n",
+              "description": "Page selection (e.g. '1-5,8'). Each resolved page produces a\nseparate output file whose `page_index` is the **literal source\npage number** \u2014 a sparse selection stays sparse: `pages: '1-5,8'`\nyields outputs with `page_index` `1,2,3,4,5,8` (NOT renumbered\n`1..6`), and `pages: '5-7'` yields `5,6,7`. The download `filename`\nsuffix is a separate 0-based array position and does NOT track the\npage number. **Maximum 200 resolved entries per\nrequest** \u2014 aligns with the `OperationResult.outputs[]`\n`maxItems: 200` cap. Expressions resolving to more than 200\nentries (e.g. `'1-201'`, `'1-100,102-205'`) are out of\ncontract. Duplicate or overlapping entries (e.g. `'1,1'`,\n`'1-100,50-150'`) are counted toward the cap as parsed;\ndeduplication, if any, is a runtime concern and is NOT part\nof this contract.\n",
               "origin": "contract",
               "sdk_exposure": "expose",
               "surface_key": "pages",
@@ -6197,7 +6210,6 @@
           "media_group": "document",
           "mimes": [
             "application/pdf",
-            "application/epub+zip",
             "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
             "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
             "application/vnd.openxmlformats-officedocument.presentationml.presentation",
@@ -6281,7 +6293,7 @@
             },
             "source": {
               "default": "page",
-              "description": "page = render a specific page/slide, cover = extract cover image (EPUB only, ignored for other formats)",
+              "description": "`page` = render a specific page/slide. `cover` = extract a cover image \u2014 only meaningful for EPUB inputs, which are served by the `document_epub` group; on PDF/office/ODF it is accepted and IGNORED (retained for backward compatibility).",
               "origin": "contract",
               "sdk_exposure": "expose",
               "surface_key": "source",
@@ -6306,6 +6318,114 @@
             }
           }
         },
+        "document_epub": {
+          "availability": "planned",
+          "max_output_pixels": 16000000,
+          "media_group": "document",
+          "mimes": [
+            "application/epub+zip"
+          ],
+          "options": {
+            "fit": {
+              "default": "crop",
+              "description": "Resize mode",
+              "origin": "contract",
+              "sdk_exposure": "coming_soon",
+              "surface_key": "fit",
+              "type": "enum",
+              "value_exposure": {
+                "crop": "coming_soon",
+                "max": "coming_soon",
+                "scale": "coming_soon"
+              },
+              "values": [
+                "max",
+                "crop",
+                "scale"
+              ]
+            },
+            "format": {
+              "default": "jpg",
+              "description": "Output format for the thumbnail",
+              "origin": "contract",
+              "sdk_exposure": "coming_soon",
+              "surface_key": "format",
+              "type": "enum",
+              "value_exposure": {
+                "jpg": "coming_soon",
+                "png": "coming_soon",
+                "webp": "coming_soon"
+              },
+              "values": [
+                "jpg",
+                "png",
+                "webp"
+              ]
+            },
+            "height": {
+              "description": "Target height in pixels (1-16384; width*height <= 16MP). Optional \u2014 see `width` for the omitted-default behaviour.",
+              "max": 16384,
+              "min": 1,
+              "origin": "contract",
+              "sdk_exposure": "coming_soon",
+              "surface_key": "height",
+              "type": "integer"
+            },
+            "page": {
+              "default": 1,
+              "depends_on": {
+                "source": "page"
+              },
+              "description": "1-based index of the printed page to render, after the book's print-layout pagination is applied.",
+              "min": 1,
+              "origin": "contract",
+              "sdk_exposure": "coming_soon",
+              "surface_key": "page",
+              "type": "integer"
+            },
+            "quality": {
+              "default": 85,
+              "depends_on": {
+                "format": [
+                  "jpg",
+                  "webp"
+                ]
+              },
+              "description": "Output quality for lossy thumbnail formats (jpg/webp): higher = better quality, larger file. Ignored for png (lossless).",
+              "max": 100,
+              "min": 1,
+              "origin": "contract",
+              "sdk_exposure": "coming_soon",
+              "surface_key": "quality",
+              "type": "integer"
+            },
+            "source": {
+              "default": "cover",
+              "description": "`cover` (default) = extract the EPUB's declared cover image \u2014 the cheap path, no rendering. `page` = render a paginated page of the book's XHTML. Cover lookup MUST support both mechanisms: the EPUB 3 `cover-image` property on an OPF manifest item, AND the legacy EPUB 2 `<meta name=\"cover\" content=\"...\"/>` pointing at a manifest item \u2014 supporting only the former misses a large slice of real-world files. A cover image is OPTIONAL per W3C EPUB 3.3, so a cover-less EPUB is a real case. The reject shape for it is NOT yet decided and is deliberately unpromised here: `ErrorCode` (asyncapi) is a CLOSED enum with no \"no cover\" member, so a distinct code is a real cross-repo co-land (enum edit -> SDK regen -> lockstep), not a free string. It is settled when this group graduates \u2014 do not infer one from this description.",
+              "origin": "contract",
+              "sdk_exposure": "coming_soon",
+              "surface_key": "source",
+              "type": "enum",
+              "value_exposure": {
+                "cover": "coming_soon",
+                "page": "coming_soon"
+              },
+              "values": [
+                "page",
+                "cover"
+              ]
+            },
+            "width": {
+              "description": "Target width in pixels (1-16384; width*height <= 16MP). Optional \u2014 when omitted the server applies an aspect-preserving default (both omitted \u2192 longest edge 320px; only one of width/height provided \u2192 the other is derived from the source aspect ratio).",
+              "max": 16384,
+              "min": 1,
+              "origin": "contract",
+              "sdk_exposure": "coming_soon",
+              "surface_key": "width",
+              "type": "integer"
+            }
+          }
+        },
         "image": {
           "max_output_pixels": 16000000,
           "media_group": "image",
@@ -7079,7 +7199,7 @@
     }
   },
   "preset_config_hash": "sha256:354814f7906f85be6a6ca5ede6c0722c83cdc058fd658a9bb2b0996520466c6d",
-  "schema_version": "2.171.0",
+  "schema_version": "2.180.0",
   "sdk_spec_version": "2.3.0",
-  "source_hash": "sha256:efe755920ce6da1324ab6d4891c74fd7edc8039631f783fa4cf048300adadc17"
+  "source_hash": "sha256:b6c13412c2b801042e9c5aaf86469e74efc2ea015b04fd1ee771b8030e9cdce0"
 }

package/dist/openapi/models/AccountLimitEntry.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).  **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.171.0
+ * The version of the OpenAPI document: 2.180.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).