@giveitsmaller/contracts 0.65.0 → 0.68.0

package/README.md

@@ -5,8 +5,8 @@
 
 | | |
 |---|---|
-| Package version | `0.65.0` |
-| Generated from spec | **`v2.194.0`** |
+| Package version | `0.68.0` |
+| Generated from spec | **`v2.198.0`** |
 
 ## Two version lines, and they are not comparable
 

package/accepted-options/accepted-options.json

@@ -1074,7 +1074,20 @@
       }
     },
     "thumbnail": {
-      "document": {
+      "document_epub": {
+        "accepted_options": {
+          "*": [
+            "fit",
+            "format",
+            "height",
+            "quality",
+            "source",
+            "width"
+          ]
+        },
+        "output_format_option": null
+      },
+      "document_office": {
         "accepted_options": {
           "*": [
             "fit",
@@ -1088,12 +1101,13 @@
         },
         "output_format_option": null
       },
-      "document_epub": {
+      "document_pdf": {
         "accepted_options": {
           "*": [
             "fit",
             "format",
             "height",
+            "page",
             "quality",
             "source",
             "width"
@@ -1200,5 +1214,5 @@
       }
     }
   },
-  "schema_version": "2.194.0"
+  "schema_version": "2.198.0"
 }

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

@@ -246,5 +246,5 @@
       "source_op": "compress"
     }
   },
-  "schema_version": "2.194.0"
+  "schema_version": "2.198.0"
 }

package/availability/availability.json

@@ -1,5 +1,6 @@
 {
-  "capabilities_version": 181,
+  "capabilities_profile": "baseline",
+  "capabilities_version": 184,
   "endpoints": {
     "DELETE /api/auth/account": {
       "auth": "required",
@@ -22,6 +23,13 @@
       "operation_id": "exportAccountData",
       "required_tier": null
     },
+    "GET /api/auth/profile": {
+      "auth": "required",
+      "availability": "stable",
+      "identity_scoped": true,
+      "operation_id": "getProfile",
+      "required_tier": null
+    },
     "GET /api/operations/schema": {
       "auth": "optional",
       "availability": "stable",
@@ -91,7 +99,12 @@
           "url": "http://localhost:8080"
         },
         {
-          "description": "Staging stream host. A SEPARATE PUBLIC ENTRY POINT from\n`api.staging.giveitsmaller.com`, which is why it is declared here\nrather than inherited: the API host fronts an integration with no\nresponse-streaming mode, and this is the only endpoint that needs\nstreaming.\n\n\u26a0\ufe0f **THIS HOST ALLOWS EXACTLY ONE CORS ORIGIN, AND IT IS A\nDIFFERENT POLICY FROM THE API HOST.** The stream stack sets\n`cors_allow_origin` (**singular**) to the frontend host alone, in\n**both** environments. The API host sets `cors_allow_origins`\n(**plural**) \u2014 and **the list differs BY ENVIRONMENT**:\n\n    staging api host   localhost:5173, localhost:3000, www.staging\u2026\n    prod    api host   www.giveitsmaller.com   \u2190 NO localhost, never had\n    both    stream     the frontend host only  (singular)\n\n\u21d2 **A BROWSER ON localhost CAN CALL THE STAGING API HOST AND\nCANNOT CALL EITHER STREAM HOST.** The break is **conditional on a\nlocal build choosing this host**: the frontend's local build leaves\n`VITE_SSE_BASE_URL` unset and falls back to the API host, so nothing\nbreaks today (measured by `compression_frontend`, 2026-08-14). **A\nclient that DOES point a localhost browser here is blocked, and the\nfailure arrives as a CORS error that reads as a configuration\nmistake in their own app.**\n\n**This is a local-development concern only; prod never permitted\nlocalhost on any host** (measured by `compression_terraform`,\n2026-08-14 \u2014 an earlier version of this note gave the staging list\nwithout saying it was staging's, which would have read as universal\nand turned a dev-experience issue into an apparent launch one).\n\n\u26a0\ufe0f **\"Just add another origin\" is not a CONFIG CHANGE here, and\nthe reason is our implementation rather than an AWS limit.** An API\nGateway **HTTP** API has a native, declarative CORS configuration\nthat takes a LIST and echoes whichever origin matches. A **REST**\nAPI has no equivalent declarative feature \u2014 the value is whatever\nthe preflight MOCK integration and the backend return \u2014 so\nmulti-origin support is possible but must be **built**\n(validate-the-Origin-then-echo), which is a change with its own\ncorrectness risk rather than an extra list entry.\n\n*(An earlier version of this note said a REST API simply cannot do\nit. That is wrong: AWS documents that for proxy integrations the\nBACKEND returns `Access-Control-Allow-Origin`, so per-origin\nresponses are available to anyone willing to implement them.\nStating a platform prohibition where an implementation choice\nexists closes a door that is open.)*\n\nThe credentialed case does foreclose the other escape: with\n`Allow-Credentials: true` the origin header cannot be `*`.\n\nThe same applies to embedded and third-party consumers, and to any\n**browser build of a published SDK**: `@giveitsmaller/sdk` ships a\nbrowser entry point whose client carries `streamEvents`, so this is\na published-surface limit rather than an internal one.\n\nA server-side caller is unaffected. **The origin list is a property\nof the deployed stack, not of this contract** \u2014 it is stated here\nbecause a client author reading only the URL cannot discover it, and\nit changes only in `compression_terraform`.\n\n\u26a0\ufe0f **AUTH ON THIS HOST IS CROSS-ORIGIN, AND `sessionAuth` IS THE\nONE THAT MAY NOT SURVIVE IT.** This operation advertises\n`bearerAuth`, `sessionAuth` and anonymous access \u2014 but the security\nlist describes what the ENDPOINT accepts, not what a browser can\ndeliver to a different origin.\n\n**Cookie domain scope is necessary and NOT sufficient.** A\ncredentialed cross-origin request additionally requires the client\nto opt in (`EventSource { withCredentials: true }`, or `fetch`\nwith `credentials: 'include'`) **and** the server to answer with\n`Access-Control-Allow-Credentials` and a non-wildcard origin. Bearer\nand capability headers likewise need the header to be permitted by\nthe preflight response.\n\n**None of that is verified by this contract, and contracts has not\nmeasured it.** \u21d2 **A browser client SHOULD prefer `bearerAuth` or\nthe anonymous capability header on this host**, and should treat\ncookie-based session auth over it as unproven until somebody\nmeasures a credentialed cross-origin stream.\n",
+          "description": "Production stream host. Declared 2026-08-18 after **routing** was\nmeasured; see the two headings below for exactly what that does and\ndoes not cover.\n\n\ud83d\udd34 **THIS ENTRY WAS DELIBERATELY WITHHELD FROM 2026-08-14 TO\n2026-08-18, AND THE REASON IT LANDED IS NOT THAT THE ORIGINAL GATE\nWAS MET.** The gate was *\"prod has never had a proven stream; a\ndeclared host would be a contract fact pointing at nothing \u2014 worse\nthan the gap, because it looks resolved.\"* What changed is that **the\ngap was found to be already occupied**:\n`compression_frontend/.github/workflows/deploy-env.yml` hardcodes\n`VITE_SSE_BASE_URL: https://stream.giveitsmaller.com` for prod, so\n**the production frontend has been routing SSE to this host all\nalong, undeclared.** Contract silence was not preventing anyone from\ndepending on the host; it was preventing them from *knowing* about\nit \u2014 which is the undeclared per-client convention this whole\ndeclaration exists to end.\n\n### WHAT IS MEASURED (2026-08-18, prod, by `compression_e2e`)\n\n- An **authenticated stream against a real prod workflow** returned\n  `200` with `content-type: text/event-stream`, replayed\n  `operation.progress` at 10 / 50 / 90, then `operation.completed`\n  carrying a real presigned S3 `download_url`, `size_bytes` 246217,\n  `compression_ratio` 0.3288 \u2014 then `job.completed` and\n  `workflow.completed`.\n- An **unauthenticated** request returns the full localised error\n  envelope (`WORKFLOW_NOT_FOUND` with `message_key`,\n  `Content-Language: en-GB`, `Vary`, HSTS), byte-identical to\n  `api.giveitsmaller.com` \u2014 so this host reaches the **real\n  application**, not an edge stub or a parked custom domain.\n- **CORS is correct on both hosts**: preflight `200`,\n  `Access-Control-Allow-Origin` exactly\n  `https://www.giveitsmaller.com`, `Allow-Credentials: true`,\n  `Authorization` among the allowed headers.\n\n### \u26a0\ufe0f WHAT IS **NOT** MEASURED: DURATION \u2014 THE PROPERTY THIS HOST EXISTS FOR\n\n**The split host exists because `api.*` is an API Gateway HTTP API\nwith a 30-second hard ceiling** (staging measured it `503`-ing at\n**29.35s**, to the millisecond) and `responseTransferMode: STREAM` is\nREST-only. **Nothing has yet shown that a stream on THIS host\nsurvives past that ceiling.**\n\nThe attempt was made and could not answer: prod holds exactly one\nworkflow and it was already **terminal**, so the server correctly\nreplayed history and closed on the terminal frame \u2014 total elapsed\n**0.355s**. \u21d2 **A stream that closes at 0.4s because the job finished\nsays nothing about whether a stream that WANTED to stay open would\nsurvive to 35s.** It is a non-answer, not a negative result.\n\n**The discriminator, named so nobody re-derives it:** a\n**NON-TERMINAL** prod job, streamed and held, reporting either the\nlast-byte timestamp or that the connection was still open at **35s+**.\nOne request; no browser needed. Until then, treat long-lived prod\nstreams as unproven on this host \u2014 and note that a client falling\nback to `api.giveitsmaller.com` is *provably* subject to the 30s\nceiling, so this entry cannot be worse than the fallback.\n\n\u26a0\ufe0f **The BROWSER path is also unmeasured.** The evidence above is\nHTTP-layer. The CORS preflight is correct, which is the part a\nbrowser needs, but no browser client has been observed consuming this\nstream in production.\n\n**This entry declares ROUTING. It does not assert that prod SSE\nworks** \u2014 do not let it be quoted as though it did.\n\nThe CORS scope, auth and cross-origin caveats stated on the staging\nentry above apply here too, with one difference already noted there:\n**prod's API host has never permitted `localhost`.**\n",
+          "replaces": "https://api.giveitsmaller.com",
+          "url": "https://stream.giveitsmaller.com"
+        },
+        {
+          "description": "Staging stream host. A SEPARATE PUBLIC ENTRY POINT from\n`api.staging.giveitsmaller.com`, which is why it is declared here\nrather than inherited: the API host fronts an integration with no\nresponse-streaming mode, and this is the only endpoint that needs\nstreaming.\n\n\u26a0\ufe0f **THIS HOST ALLOWS EXACTLY ONE CORS ORIGIN, AND IT IS A\nDIFFERENT POLICY FROM THE API HOST.** The stream stack sets\n`cors_allow_origin` (**singular**) to the frontend host alone, in\n**both** environments. The API host sets `cors_allow_origins`\n(**plural**) \u2014 and **the list differs BY ENVIRONMENT**:\n\n    staging api host   localhost:5173, localhost:3000, www.staging\u2026\n    prod    api host   www.giveitsmaller.com   \u2190 NO localhost, never had\n    both    stream     the frontend host only  (singular)\n\n\u21d2 **A BROWSER ON localhost CAN CALL THE STAGING API HOST AND\nCANNOT CALL EITHER STREAM HOST.** The break is **conditional on a\nlocal build choosing this host**: the frontend's local build leaves\n`VITE_SSE_BASE_URL` unset and falls back to the API host, so nothing\nbreaks today (measured by `compression_frontend`, 2026-08-14). **A\nclient that DOES point a localhost browser here is blocked, and the\nfailure arrives as a CORS error that reads as a configuration\nmistake in their own app.**\n\n**This is a local-development concern only; prod never permitted\nlocalhost on any host** (measured by `compression_terraform`,\n2026-08-14 \u2014 an earlier version of this note gave the staging list\nwithout saying it was staging's, which would have read as universal\nand turned a dev-experience issue into an apparent launch one).\n\n\u26a0\ufe0f **\"Just add another origin\" is not a CONFIG CHANGE here, and\nthe reason is our implementation rather than an AWS limit.** An API\nGateway **HTTP** API has a native, declarative CORS configuration\nthat takes a LIST and echoes whichever origin matches. A **REST**\nAPI has no equivalent declarative feature \u2014 the value is whatever\nthe preflight MOCK integration and the backend return \u2014 so\nmulti-origin support is possible but must be **built**\n(validate-the-Origin-then-echo), which is a change with its own\ncorrectness risk rather than an extra list entry.\n\n*(An earlier version of this note said a REST API simply cannot do\nit. That is wrong: AWS documents that for proxy integrations the\nBACKEND returns `Access-Control-Allow-Origin`, so per-origin\nresponses are available to anyone willing to implement them.\nStating a platform prohibition where an implementation choice\nexists closes a door that is open.)*\n\nThe credentialed case does foreclose the other escape: with\n`Allow-Credentials: true` the origin header cannot be `*`.\n\nThe same applies to embedded and third-party consumers, and to any\n**browser build of a published SDK**: `@giveitsmaller/sdk` ships a\nbrowser entry point whose client carries `streamEvents`, so this is\na published-surface limit rather than an internal one.\n\nA server-side caller is unaffected. **The origin list is a property\nof the deployed stack, not of this contract** \u2014 it is stated here\nbecause a client author reading only the URL cannot discover it, and\nit changes only in `compression_terraform`.\n\n\u26a0\ufe0f **AUTH ON THIS HOST IS CROSS-ORIGIN, AND `sessionAuth` IS THE\nONE THAT MAY NOT SURVIVE IT.** This operation advertises\n`bearerAuth`, `sessionAuth` and anonymous access \u2014 but the security\nlist describes what the ENDPOINT accepts, not what a browser can\ndeliver to a different origin.\n\n**Cookie domain scope is necessary and NOT sufficient.** A\ncredentialed cross-origin request additionally requires the client\nto opt in (`EventSource { withCredentials: true }`, or `fetch`\nwith `credentials: 'include'`) **and** the server to answer with\n`Access-Control-Allow-Credentials` and a non-wildcard origin. Bearer\nand capability headers likewise need the header to be permitted by\nthe preflight response.\n\n**None of that is verified by this contract, and contracts has not\nmeasured it.**\n\n\ud83d\udd34 **This passage used to conclude \"a browser client SHOULD prefer\n`bearerAuth` or the anonymous capability header on this host, and\nshould treat cookie-based session auth as unproven\". DO NOT\nREINSTATE IT.** For an **owned** stream the shipped browser client\nhas no bearer token on its runtime path at all, so that advice named\na credential the caller does not possess \u2014 leaving a logged-in user\nwith nothing to send. See **AUTH ON THE STREAM HOST** on the\noperation below, which is the single place this question is\nanswered; the cross-origin caveats above remain true and are what\nthat section is qualified by.\n",
           "replaces": "https://api.staging.giveitsmaller.com",
           "url": "https://stream.staging.giveitsmaller.com"
         }
@@ -1985,7 +1998,7 @@
             },
             "encoding_mode": {
               "default": "crf",
-              "description": "crf = constant quality (variable file size). target_size = constrained output file size (two-pass). target_size is LIVE for mp4/MOV output; for webm/ogg output and long-form the server returns `feature_not_available` (use crf there) until two-pass for this container ships.",
+              "description": "`crf` = constant quality. `target_size` = constrained output file size\n(two-pass). `target_size` is LIVE for mp4/MOV output; for webm/ogg output\nand long-form the server returns `feature_not_available` (use `crf` there)\nuntil two-pass for this container ships.\n\n\ud83d\udd34 **`crf` DOES NOT MEAN UNCONSTRAINED FILE SIZE. THIS DESCRIPTION USED TO\nSAY \"variable file size\" AND THAT WAS FALSE BY OMISSION.** For **mp4/MOV\noutput**, the worker additionally derives a **source-relative peak-bitrate\nceiling of roughly 60% of the source video bitrate** (`-maxrate`/`-bufsize`),\nand **it binds regardless of an explicit `crf`** \u2014 constrained-CRF. The `crf`\nvalue is still honoured as the **quality ceiling**; the cap adds a peak\nceiling on top of it.\n\n\u26a0\ufe0f **Scope, because \"we cap every video\" would be a second false sentence:**\nthe cap is **mp4/MOV only** \u2014 WebM/VP9 discards it and skips the probe\nentirely \u2014 and it is **best-effort**, so an unprobeable source gets no cap.\n\n\u2b50 **Why it exists, which is also why the old wording surprised in the wrong\ndirection:** plain CRF alone **INFLATES already-efficient sources** \u2014 an\nefficient HEVC re-encoded to H.264 at CRF 23/25/30 grows. The compress\ncontract is *reduce file size*, so the cap is what makes shrinking reliable.\nA caller who deliberately pins a low `crf` on an efficient source therefore\ngets a constrained-CRF transcode rather than a byte-for-byte original: a\ndeliberate, accepted shift.\n\n\ud83d\udd34 **THIS DESCRIPTION IS BOUND TO THE WORKER, NOT DATED AGAINST IT.**\n`tests/test_bitrate_cap_disclosure_matches_the_worker.py` reads\n`compression_lambdas` at `origin/main` and fails if the cap stops\nbeing source-relative, stops being mp4/MOV-only, or stops deriving\nfrom a source probe. **An as-of date would make a superseded\nsentence look deliberate**; a gate makes it go red instead.\n",
               "type": "enum",
               "values": [
                 "crf",
@@ -2049,7 +2062,7 @@
             },
             "preset": {
               "default": "medium",
-              "description": "Encoding speed vs compression ratio trade-off",
+              "description": "x264/x265 encoder effort. **A SIZE LEVER, CONDITIONALLY** \u2014 it moves\noutput size **only while the mp4/MOV peak-bitrate cap is NOT binding.**\n\n**Measured by `compression_lambdas`, medium vs slow, all else held:**\n\n    crf 30, cap inert    1,220,156 vs 1,144,043 bytes   6.2% apart\n    crf 18, cap binding  2,514,788 vs 2,516,986 bytes   0.09% apart\n\n\ud83d\udd34 **THE MECHANISM IS MECHANICAL, NOT EMPIRICAL, AND EXPLAINS BOTH ROWS.**\nIn pure CRF the encoder targets constant QUALITY, so a slower preset spends\nits extra effort producing a **smaller file at the same quality**. Once\n`-maxrate` binds the encode is rate-limited, so the extra effort can only go\ninto **picture at a fixed size** \u2014 an axis a size measurement cannot see.\n\n\u26a0\ufe0f **This description previously said `preset` was effort-only and that `crf`\nwas the size lever. That was wrong**, and it was wrong because a 0.09% figure\nmeasured on a **cap-binding** clip was generalised into a property of `preset`.\n**A measurement is not a property until you know what held it.**\n\n\u21d2 **Callers optimising for size:** `crf` is the primary lever; `preset` adds\nreal reduction **only when the cap is not already constraining the encode** \u2014\nwhich is exactly the high-`crf`, small-output end. See `encoding_mode` for what\nthe cap is and when it applies.\n\n\u26a0\ufe0f **What the extra effort buys once the cap DOES bind is mechanically\nimplied and empirically UNCONFIRMED.** The mechanism says it must go\ninto picture; `compression_lambdas` could not see a difference on 2x\ncrops, but that was **one frame of one 5-second clip**, and preset\ndifferences concentrate in high-motion frames that were not\ndeliberately sampled. **Recorded as unestablished, not asserted.**\n",
               "type": "enum",
               "values": [
                 "ultrafast",
@@ -4446,10 +4459,72 @@
       "description": "Resize an image to specific dimensions, or extract a preview frame/page from a video or document. For images this is a full resizer (1-16384px), not just small previews.",
       "input_model": "single",
       "mime_groups": {
-        "document": {
+        "document_epub": {
+          "max_input_size_bytes": 104857600,
+          "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"
+            },
+            "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` (the only supported value) = extract the EPUB's declared cover image \u2014 the cheap path, no rendering. Cover lookup supports 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 would miss a large slice of real-world files. Both are staging-proven (pL16ZfOw Wave 3). A cover image is OPTIONAL per W3C EPUB 3.3, so a cover-less EPUB is a REAL and expected case: it fails with `error_code: processing_failed` and `is_retryable: false`. That is the live behaviour, not an aspiration \u2014 the worker classifies it as `CoverError::NoCoverDeclared` and maps it there (`epub/error.rs`), and non-retryability is DERIVED from the code rather than set per-call, so it cannot drift. A cover-less EPUB will not grow a cover, so retrying is always futile. A more specific code would be better, and is NOT promised here: `ErrorCode` (asyncapi) is a CLOSED enum with no \"no cover\" member, so adding one is a real cross-repo co-land (enum edit -> SDK regen -> lockstep). Until then this description states what actually happens \u2014 an undecided-reject note on a STABLE route would leave consumers unable to handle a case they will certainly meet.",
+              "type": "enum",
+              "values": [
+                "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_office": {
+          "max_input_size_bytes": 157286400,
           "max_output_pixels": 16000000,
           "mimes": [
-            "application/pdf",
             "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
             "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
             "application/vnd.openxmlformats-officedocument.presentationml.presentation",
@@ -4523,10 +4598,11 @@
             }
           }
         },
-        "document_epub": {
+        "document_pdf": {
+          "input_size_bound": "processing_time",
           "max_output_pixels": 16000000,
           "mimes": [
-            "application/epub+zip"
+            "application/pdf"
           ],
           "options": {
             "fit": {
@@ -4555,6 +4631,15 @@
               "min": 1,
               "type": "integer"
             },
+            "page": {
+              "default": 1,
+              "depends_on": {
+                "source": "page"
+              },
+              "description": "1-based index of the printed page to render, after print-layout pagination is applied. For office formats this is the page in the document's print layout \u2014 NOT a 1:1 sheet/slide index: a spreadsheet sheet may span multiple printed pages and multi-sheet workbooks paginate their sheets in order. For PDF inputs it is the PDF page number directly.",
+              "min": 1,
+              "type": "integer"
+            },
             "quality": {
               "default": 85,
               "depends_on": {
@@ -4569,10 +4654,11 @@
               "type": "integer"
             },
             "source": {
-              "default": "cover",
-              "description": "`cover` (the only supported value) = extract the EPUB's declared cover image \u2014 the cheap path, no rendering. Cover lookup supports 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 would miss a large slice of real-world files. Both are staging-proven (pL16ZfOw Wave 3). A cover image is OPTIONAL per W3C EPUB 3.3, so a cover-less EPUB is a REAL and expected case: it fails with `error_code: processing_failed` and `is_retryable: false`. That is the live behaviour, not an aspiration \u2014 the worker classifies it as `CoverError::NoCoverDeclared` and maps it there (`epub/error.rs`), and non-retryability is DERIVED from the code rather than set per-call, so it cannot drift. A cover-less EPUB will not grow a cover, so retrying is always futile. A more specific code would be better, and is NOT promised here: `ErrorCode` (asyncapi) is a CLOSED enum with no \"no cover\" member, so adding one is a real cross-repo co-land (enum edit -> SDK regen -> lockstep). Until then this description states what actually happens \u2014 an undecided-reject note on a STABLE route would leave consumers unable to handle a case they will certainly meet.",
+              "default": "page",
+              "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"
               ]
             },
@@ -5130,7 +5216,7 @@
       "sole_op": true
     }
   },
-  "schema_version": "2.194.0",
+  "schema_version": "2.198.0",
   "source_commit": null,
   "user_tier": null,
   "workflow_features": {

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

@@ -2803,7 +2803,7 @@
             },
             "encoding_mode": {
               "default": "crf",
-              "description": "crf = constant quality (variable file size). target_size = constrained output file size (two-pass). target_size is LIVE for mp4/MOV output; for webm/ogg output and long-form the server returns `feature_not_available` (use crf there) until two-pass for this container ships.",
+              "description": "`crf` = constant quality. `target_size` = constrained output file size\n(two-pass). `target_size` is LIVE for mp4/MOV output; for webm/ogg output\nand long-form the server returns `feature_not_available` (use `crf` there)\nuntil two-pass for this container ships.\n\n\ud83d\udd34 **`crf` DOES NOT MEAN UNCONSTRAINED FILE SIZE. THIS DESCRIPTION USED TO\nSAY \"variable file size\" AND THAT WAS FALSE BY OMISSION.** For **mp4/MOV\noutput**, the worker additionally derives a **source-relative peak-bitrate\nceiling of roughly 60% of the source video bitrate** (`-maxrate`/`-bufsize`),\nand **it binds regardless of an explicit `crf`** \u2014 constrained-CRF. The `crf`\nvalue is still honoured as the **quality ceiling**; the cap adds a peak\nceiling on top of it.\n\n\u26a0\ufe0f **Scope, because \"we cap every video\" would be a second false sentence:**\nthe cap is **mp4/MOV only** \u2014 WebM/VP9 discards it and skips the probe\nentirely \u2014 and it is **best-effort**, so an unprobeable source gets no cap.\n\n\u2b50 **Why it exists, which is also why the old wording surprised in the wrong\ndirection:** plain CRF alone **INFLATES already-efficient sources** \u2014 an\nefficient HEVC re-encoded to H.264 at CRF 23/25/30 grows. The compress\ncontract is *reduce file size*, so the cap is what makes shrinking reliable.\nA caller who deliberately pins a low `crf` on an efficient source therefore\ngets a constrained-CRF transcode rather than a byte-for-byte original: a\ndeliberate, accepted shift.\n\n\ud83d\udd34 **THIS DESCRIPTION IS BOUND TO THE WORKER, NOT DATED AGAINST IT.**\n`tests/test_bitrate_cap_disclosure_matches_the_worker.py` reads\n`compression_lambdas` at `origin/main` and fails if the cap stops\nbeing source-relative, stops being mp4/MOV-only, or stops deriving\nfrom a source probe. **An as-of date would make a superseded\nsentence look deliberate**; a gate makes it go red instead.\n",
               "origin": "contract",
               "sdk_exposure": "expose",
               "surface_key": "encodingMode",
@@ -2908,7 +2908,7 @@
             },
             "preset": {
               "default": "medium",
-              "description": "Encoding speed vs compression ratio trade-off",
+              "description": "x264/x265 encoder effort. **A SIZE LEVER, CONDITIONALLY** \u2014 it moves\noutput size **only while the mp4/MOV peak-bitrate cap is NOT binding.**\n\n**Measured by `compression_lambdas`, medium vs slow, all else held:**\n\n    crf 30, cap inert    1,220,156 vs 1,144,043 bytes   6.2% apart\n    crf 18, cap binding  2,514,788 vs 2,516,986 bytes   0.09% apart\n\n\ud83d\udd34 **THE MECHANISM IS MECHANICAL, NOT EMPIRICAL, AND EXPLAINS BOTH ROWS.**\nIn pure CRF the encoder targets constant QUALITY, so a slower preset spends\nits extra effort producing a **smaller file at the same quality**. Once\n`-maxrate` binds the encode is rate-limited, so the extra effort can only go\ninto **picture at a fixed size** \u2014 an axis a size measurement cannot see.\n\n\u26a0\ufe0f **This description previously said `preset` was effort-only and that `crf`\nwas the size lever. That was wrong**, and it was wrong because a 0.09% figure\nmeasured on a **cap-binding** clip was generalised into a property of `preset`.\n**A measurement is not a property until you know what held it.**\n\n\u21d2 **Callers optimising for size:** `crf` is the primary lever; `preset` adds\nreal reduction **only when the cap is not already constraining the encode** \u2014\nwhich is exactly the high-`crf`, small-output end. See `encoding_mode` for what\nthe cap is and when it applies.\n\n\u26a0\ufe0f **What the extra effort buys once the cap DOES bind is mechanically\nimplied and empirically UNCONFIRMED.** The mechanism says it must go\ninto picture; `compression_lambdas` could not see a difference on 2x\ncrops, but that was **one frame of one 5-second clip**, and preset\ndifferences concentrate in high-motion frames that were not\ndeliberately sampled. **Recorded as unestablished, not asserted.**\n",
               "enum_ref": "VideoPreset",
               "enum_translations": {
                 "fast": "Fast",
@@ -6209,11 +6209,105 @@
       },
       "input_model": "single",
       "media_groups": {
-        "document": {
+        "document_epub": {
+          "max_input_size_bytes": 104857600,
+          "max_output_pixels": 16000000,
+          "media_group": "document",
+          "mimes": [
+            "application/epub+zip"
+          ],
+          "options": {
+            "fit": {
+              "default": "crop",
+              "description": "Resize mode",
+              "origin": "contract",
+              "sdk_exposure": "expose",
+              "surface_key": "fit",
+              "type": "enum",
+              "value_exposure": {
+                "crop": "expose",
+                "max": "expose",
+                "scale": "expose"
+              },
+              "values": [
+                "max",
+                "crop",
+                "scale"
+              ]
+            },
+            "format": {
+              "default": "jpg",
+              "description": "Output format for the thumbnail",
+              "origin": "contract",
+              "sdk_exposure": "expose",
+              "surface_key": "format",
+              "type": "enum",
+              "value_exposure": {
+                "jpg": "expose",
+                "png": "expose",
+                "webp": "expose"
+              },
+              "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": "expose",
+              "surface_key": "height",
+              "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": "expose",
+              "surface_key": "quality",
+              "type": "integer"
+            },
+            "source": {
+              "default": "cover",
+              "description": "`cover` (the only supported value) = extract the EPUB's declared cover image \u2014 the cheap path, no rendering. Cover lookup supports 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 would miss a large slice of real-world files. Both are staging-proven (pL16ZfOw Wave 3). A cover image is OPTIONAL per W3C EPUB 3.3, so a cover-less EPUB is a REAL and expected case: it fails with `error_code: processing_failed` and `is_retryable: false`. That is the live behaviour, not an aspiration \u2014 the worker classifies it as `CoverError::NoCoverDeclared` and maps it there (`epub/error.rs`), and non-retryability is DERIVED from the code rather than set per-call, so it cannot drift. A cover-less EPUB will not grow a cover, so retrying is always futile. A more specific code would be better, and is NOT promised here: `ErrorCode` (asyncapi) is a CLOSED enum with no \"no cover\" member, so adding one is a real cross-repo co-land (enum edit -> SDK regen -> lockstep). Until then this description states what actually happens \u2014 an undecided-reject note on a STABLE route would leave consumers unable to handle a case they will certainly meet.",
+              "origin": "contract",
+              "sdk_exposure": "expose",
+              "surface_key": "source",
+              "type": "enum",
+              "value_exposure": {
+                "cover": "expose"
+              },
+              "values": [
+                "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": "expose",
+              "surface_key": "width",
+              "type": "integer"
+            }
+          }
+        },
+        "document_office": {
+          "max_input_size_bytes": 157286400,
           "max_output_pixels": 16000000,
           "media_group": "document",
           "mimes": [
-            "application/pdf",
             "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
             "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
             "application/vnd.openxmlformats-officedocument.presentationml.presentation",
@@ -6322,11 +6416,12 @@
             }
           }
         },
-        "document_epub": {
+        "document_pdf": {
+          "input_size_bound": "processing_time",
           "max_output_pixels": 16000000,
           "media_group": "document",
           "mimes": [
-            "application/epub+zip"
+            "application/pdf"
           ],
           "options": {
             "fit": {
@@ -6374,6 +6469,18 @@
               "surface_key": "height",
               "type": "integer"
             },
+            "page": {
+              "default": 1,
+              "depends_on": {
+                "source": "page"
+              },
+              "description": "1-based index of the printed page to render, after print-layout pagination is applied. For office formats this is the page in the document's print layout \u2014 NOT a 1:1 sheet/slide index: a spreadsheet sheet may span multiple printed pages and multi-sheet workbooks paginate their sheets in order. For PDF inputs it is the PDF page number directly.",
+              "min": 1,
+              "origin": "contract",
+              "sdk_exposure": "expose",
+              "surface_key": "page",
+              "type": "integer"
+            },
             "quality": {
               "default": 85,
               "depends_on": {
@@ -6391,16 +6498,18 @@
               "type": "integer"
             },
             "source": {
-              "default": "cover",
-              "description": "`cover` (the only supported value) = extract the EPUB's declared cover image \u2014 the cheap path, no rendering. Cover lookup supports 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 would miss a large slice of real-world files. Both are staging-proven (pL16ZfOw Wave 3). A cover image is OPTIONAL per W3C EPUB 3.3, so a cover-less EPUB is a REAL and expected case: it fails with `error_code: processing_failed` and `is_retryable: false`. That is the live behaviour, not an aspiration \u2014 the worker classifies it as `CoverError::NoCoverDeclared` and maps it there (`epub/error.rs`), and non-retryability is DERIVED from the code rather than set per-call, so it cannot drift. A cover-less EPUB will not grow a cover, so retrying is always futile. A more specific code would be better, and is NOT promised here: `ErrorCode` (asyncapi) is a CLOSED enum with no \"no cover\" member, so adding one is a real cross-repo co-land (enum edit -> SDK regen -> lockstep). Until then this description states what actually happens \u2014 an undecided-reject note on a STABLE route would leave consumers unable to handle a case they will certainly meet.",
+              "default": "page",
+              "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",
               "type": "enum",
               "value_exposure": {
-                "cover": "expose"
+                "cover": "expose",
+                "page": "expose"
               },
               "values": [
+                "page",
                 "cover"
               ]
             },
@@ -7188,7 +7297,7 @@
     }
   },
   "preset_config_hash": "sha256:354814f7906f85be6a6ca5ede6c0722c83cdc058fd658a9bb2b0996520466c6d",
-  "schema_version": "2.194.0",
+  "schema_version": "2.198.0",
   "sdk_spec_version": "2.3.0",
-  "source_hash": "sha256:d7ff190cf08026ff0029b37b31ca48f6dcaa67827dfc46e1328a9cbb43aada31"
+  "source_hash": "sha256:6eae18a646e1338f5fc7e62cc0ae70e4670a4de671ed00f9539e957ea1cf755c"
 }

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

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

package/dist/openapi/models/AccountLimits.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.194.0
+ * The version of the OpenAPI document: 2.198.0
  *
  *
  * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
@@ -23,15 +23,23 @@ import type { AccountLimitsLimits } from './AccountLimitsLimits.js';
  *   (`UserTier.maxFileSizeBytes` — the request-level tier quota the
  *   upload endpoints enforce). **Distinct** from the per-operation
  *   processing ceiling `max_input_size_bytes` in operation schemas
- *   (different axis AND number). Tier defaults: free 10 MiB, pro 5 GiB,
- *   enterprise 100 GiB.
+ *   (different axis AND number).
+ *   ⚠️ **The per-tier byte defaults are deliberately NOT restated here.**
+ *   This line used to list them for `free` / `pro` / `enterprise` and
+ *   **silently omitted `max`** — a tier the `UserTier` enum declares. The
+ *   response itself carries the answer per caller (`tier_default` beside
+ *   `effective`), which is override-aware in a way a static table can
+ *   never be.
  * - `max_total_input_size_bytes`: the effective merge combined-input
  *   size cap (the summed-inputs ceiling). Same key as the
  *   operation-schema merge band; the band is processing-class +
- *   tier dependent (`short_form_concat` baseline 1 GiB; the
- *   `long_form_re_encode` band where the tier permits it — Pro 5 GB,
- *   Enterprise 120 GB). The server resolves the effective value for
- *   the caller.
+ *   tier dependent. **The server resolves the effective value for the
+ *   caller** and returns it here — that is the point of this endpoint.
+ *   ⚠️ **A THIRD restated per-tier table lived on this line** (it named
+ *   two tiers' band ceilings and, like the other two, omitted `max`). The
+ *   machine-readable source is `per_tier_constraints` on the operation
+ *   schema's `processing_class`; it is generated, so it cannot drift from
+ *   the schemas the way a sentence here does.
  *
  * @export
  * @interface AccountLimits

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