@giveitsmaller/contracts 0.63.0 → 0.65.0

package/openapi/api.yaml

@@ -89,7 +89,7 @@ info:
     of truth instead of hardcoding magic numbers. A runtime
     `GET /api/uploads/limits` endpoint for dynamic discovery
     (per-tier / per-environment overrides) is a deferred follow-up.
-  version: 2.192.0
+  version: 2.194.0
   contact:
     name: API Support
 
@@ -2369,6 +2369,160 @@ paths:
   /api/workflows/{id}/events:
     get:
       summary: Stream workflow events (SSE)
+      # THE STREAM DOES NOT LIVE ON THE API HOST. THAT IS A CONTRACT FACT,
+      # DECLARED PER-OPERATION, AND DELIBERATELY NOT A CONVENTION.
+      #
+      # ⚠️ RULING (hub, 2026-08-14, on sdks' recommendation with api agreeing):
+      # SPLIT HOSTS, DECLARED PER-OPERATION. Not string surgery on `api.*`, not
+      # a per-client rule. The reason is not aesthetic — IT IS THAT A CONVENTION
+      # CAN ONLY FAIL SILENTLY. The frontend carried `VITE_SSE_BASE_URL`
+      # (created 2026-06-17) and preferred it when set; PROD NEVER SET IT, so
+      # prod silently fell back to the gateway path and inherited an entry point
+      # that cannot stream — for weeks, while everyone believed SSE worked. A
+      # declared per-operation server cannot fail that way.
+      #
+      # 🔴 WHAT THIS DECLARATION DOES **NOT** DO, STATED BECAUSE IT IS THE
+      # DIFFERENCE BETWEEN DECLARED AND IN EFFECT: it does not repoint any
+      # existing client. Both shipped SDKs resolve EVERY url from a single
+      # configured base — PHP `GislClient::streamEvents()` builds from the same
+      # base URL as everything else, and TypeScript does likewise — and the
+      # generators emit models and supporting files rather than per-operation
+      # server handling. **A CLIENT CONFIGURED FOR `api.*` KEEPS SENDING SSE TO
+      # `api.*` AFTER THIS LANDS.**
+      #
+      # ⇒ This block makes the routing a CONTRACT FACT that a client can
+      # consume. Consuming it is a change to endpoint RESOLUTION in two
+      # languages (sdks' `VUozk5Bc`), and it is theirs. Writing "a generated
+      # client picks the host up from the contract" would be the same
+      # declared-equals-working error this comment exists to warn about.
+      #
+      # THE RULE, STATED SO NOBODY DERIVES A DIFFERENT ONE: this is the ONLY
+      # operation with its own `servers`. Every other endpoint uses the
+      # root-level `servers:`. The stream API happens to proxy `ANY /{proxy+}`
+      # — the whole API — so "route SSE at the stream host" could have meant
+      # "move everything"; IT DOES NOT. Split per-endpoint, and the split is
+      # expressed here rather than in three consumers' READMEs.
+      #
+      # WHY THE API HOST CANNOT DO THIS — mechanism, not a workaround (api,
+      # 2026-08-13, relayed via the hub; contracts has not measured it):
+      # `api.*` is an API Gateway **HTTP API** with `integration_timeout_ms`
+      # 29000 against a **30s hard AWS ceiling with no quota path**, and
+      # `responseTransferMode: STREAM` is **REST-only**. `stream.*` is a REST
+      # API with a 900000ms timeout and STREAM set. Raising a number fixes
+      # nothing.
+      #
+      # THE REVERT CONDITION IS MET. This block was reverted on 2026-08-12
+      # (27d606c) with a named gate: "re-lands when the path is PROVEN".
+      # e2e then measured `stream.staging` streaming — `:ok` at 0.0s, frames
+      # over 165s, ~16s heartbeats — while `api.staging` 503s at 29.35s, which
+      # is the integration timeout firing to the millisecond. Measured AND
+      # mechanistically explained, which is what the gate asked for.
+      #
+      # ⚠️ THERE IS STILL DELIBERATELY NO PRODUCTION ENTRY, and the reason is
+      # UNCHANGED by the staging proof: PROD HAS NEVER HAD A PROVEN STREAM.
+      # Declaring a prod host would be a contract fact pointing at something
+      # unproven, which is worse than the gap because it LOOKS resolved — the
+      # same error this block exists to prevent, committed in the opposite
+      # direction. The gate is the same one, applied to prod: a first-byte
+      # timestamp on a heartbeat from the prod stream host.
+      servers:
+        - url: http://localhost:8080
+          # WHICH ROOT SERVER THIS ENTRY REPLACES. Without it a client has to
+          # infer the mapping from ordering or hostname shape — which is a
+          # per-client rule, i.e. the exact thing declaring the split was meant
+          # to remove. A client matches its CONFIGURED base against
+          # `x-replaces` exactly and takes `url`; no convention, no ordering
+          # dependency, and an unmatched base is an honest "no override for the
+          # host you are pointed at" rather than a guess.
+          x-replaces: http://localhost:8080
+          description: |
+            Local development. Same origin as the rest of the API — local runs
+            do NOT reproduce the split-host topology, so a client that works
+            locally has **not** exercised the cross-origin path. Treat a local
+            pass as evidence about your code and not about the routing.
+        - url: https://stream.staging.giveitsmaller.com
+          x-replaces: https://api.staging.giveitsmaller.com
+          description: |
+            Staging stream host. A SEPARATE PUBLIC ENTRY POINT from
+            `api.staging.giveitsmaller.com`, which is why it is declared here
+            rather than inherited: the API host fronts an integration with no
+            response-streaming mode, and this is the only endpoint that needs
+            streaming.
+
+            ⚠️ **THIS HOST ALLOWS EXACTLY ONE CORS ORIGIN, AND IT IS A
+            DIFFERENT POLICY FROM THE API HOST.** The stream stack sets
+            `cors_allow_origin` (**singular**) to the frontend host alone, in
+            **both** environments. The API host sets `cors_allow_origins`
+            (**plural**) — and **the list differs BY ENVIRONMENT**:
+
+                staging api host   localhost:5173, localhost:3000, www.staging…
+                prod    api host   www.giveitsmaller.com   ← NO localhost, never had
+                both    stream     the frontend host only  (singular)
+
+            ⇒ **A BROWSER ON localhost CAN CALL THE STAGING API HOST AND
+            CANNOT CALL EITHER STREAM HOST.** The break is **conditional on a
+            local build choosing this host**: the frontend's local build leaves
+            `VITE_SSE_BASE_URL` unset and falls back to the API host, so nothing
+            breaks today (measured by `compression_frontend`, 2026-08-14). **A
+            client that DOES point a localhost browser here is blocked, and the
+            failure arrives as a CORS error that reads as a configuration
+            mistake in their own app.**
+
+            **This is a local-development concern only; prod never permitted
+            localhost on any host** (measured by `compression_terraform`,
+            2026-08-14 — an earlier version of this note gave the staging list
+            without saying it was staging's, which would have read as universal
+            and turned a dev-experience issue into an apparent launch one).
+
+            ⚠️ **"Just add another origin" is not a CONFIG CHANGE here, and
+            the reason is our implementation rather than an AWS limit.** An API
+            Gateway **HTTP** API has a native, declarative CORS configuration
+            that takes a LIST and echoes whichever origin matches. A **REST**
+            API has no equivalent declarative feature — the value is whatever
+            the preflight MOCK integration and the backend return — so
+            multi-origin support is possible but must be **built**
+            (validate-the-Origin-then-echo), which is a change with its own
+            correctness risk rather than an extra list entry.
+
+            *(An earlier version of this note said a REST API simply cannot do
+            it. That is wrong: AWS documents that for proxy integrations the
+            BACKEND returns `Access-Control-Allow-Origin`, so per-origin
+            responses are available to anyone willing to implement them.
+            Stating a platform prohibition where an implementation choice
+            exists closes a door that is open.)*
+
+            The credentialed case does foreclose the other escape: with
+            `Allow-Credentials: true` the origin header cannot be `*`.
+
+            The same applies to embedded and third-party consumers, and to any
+            **browser build of a published SDK**: `@giveitsmaller/sdk` ships a
+            browser entry point whose client carries `streamEvents`, so this is
+            a published-surface limit rather than an internal one.
+
+            A server-side caller is unaffected. **The origin list is a property
+            of the deployed stack, not of this contract** — it is stated here
+            because a client author reading only the URL cannot discover it, and
+            it changes only in `compression_terraform`.
+
+            ⚠️ **AUTH ON THIS HOST IS CROSS-ORIGIN, AND `sessionAuth` IS THE
+            ONE THAT MAY NOT SURVIVE IT.** This operation advertises
+            `bearerAuth`, `sessionAuth` and anonymous access — but the security
+            list describes what the ENDPOINT accepts, not what a browser can
+            deliver to a different origin.
+
+            **Cookie domain scope is necessary and NOT sufficient.** A
+            credentialed cross-origin request additionally requires the client
+            to opt in (`EventSource { withCredentials: true }`, or `fetch`
+            with `credentials: 'include'`) **and** the server to answer with
+            `Access-Control-Allow-Credentials` and a non-wildcard origin. Bearer
+            and capability headers likewise need the header to be permitted by
+            the preflight response.
+
+            **None of that is verified by this contract, and contracts has not
+            measured it.** ⇒ **A browser client SHOULD prefer `bearerAuth` or
+            the anonymous capability header on this host**, and should treat
+            cookie-based session auth over it as unproven until somebody
+            measures a credentialed cross-origin stream.
       description: |
         Server-Sent Events endpoint for real-time workflow progress. The server pushes
         events as workflow, job, and operation statuses change.
@@ -5699,7 +5853,7 @@ paths:
                   type: subscription
                   key: pro
               credit_pack:
-                summary: Buy a 25-credit pack
+                summary: Buy the £25 credit pack
                 value:
                   type: pack
                   key: pack_25
@@ -7118,6 +7272,17 @@ components:
         - `type: subscription` → `key` ∈ { `pro`, `max` }
         - `type: pack` → `key` ∈ { `pack_10`, `pack_25`, `pack_50` }
 
+        ⚠️ **The number in a pack SKU is the PRICE IN POUNDS, not a credit
+        count** — `pack_25` is the £25 pack, and the credits it grants are a
+        different number entirely, roughly two orders of magnitude larger.
+        **How many** is server-side (api's versioned Stripe catalog) and is
+        deliberately not restated here, because a credit grant that lives in
+        two places drifts — and the copy a customer reads before paying is the
+        one that must not be stale. Clients that need to show it read it from
+        the server; they never infer it from the SKU. *An example on this very
+        endpoint read the SKU as a quantity until 2026-08-12, so the axis is
+        named here rather than assumed obvious.*
+
         The `type` ↔ `key` pairing is validated **server-side**, not by this
         schema (the `key` enum lists all values across both types). A
         mismatched or unprovisioned pair returns `422` `UNPROCESSABLE_ENTITY`;
@@ -13970,11 +14135,16 @@ components:
     EndpointProjection:
       type: object
       description: |
-        Per-endpoint projection entry per ADR-0016 §D4. Five fields;
-        `required_tier` and `availability` at endpoint level are
-        reserved/null today (operation-level `required_tier` continues
-        to flow via `operations.*.required_tier`; every shipped
-        endpoint is currently `availability: stable`).
+        Per-endpoint projection entry per ADR-0016 §D4. Five required
+        fields plus an OPTIONAL `servers`; `required_tier` at endpoint
+        level is reserved/null today (operation-level `required_tier`
+        continues to flow via `operations.*.required_tier`).
+
+        ⚠️ **`availability` is DERIVED from the operation's
+        `x-availability` and is no longer always `stable`** — an
+        earlier version of this description said every shipped endpoint
+        was `stable`, which was true only because the generator
+        hardcoded it.
       required:
         - auth
         - identity_scoped
@@ -13982,6 +14152,54 @@ components:
         - availability
         - operation_id
       properties:
+        servers:
+          type: array
+          minItems: 1
+          description: |
+            OPTIONAL. Present **only** when the operation overrides the
+            root host — today, the SSE stream endpoint alone.
+
+            **Absence means "inherits the root `servers`" and is not a
+            gap.** Emitting a copy of the root on every entry would put
+            one value on 43 rows, which conveys nothing and would invite
+            a consumer to read this projection as the routing source of
+            record for endpoints that have no override.
+
+            ⚠️ **This field exists because the declaration was
+            unreachable without it.** The routing split is declared on
+            the operation in `openapi/api.yaml`, but SDK consumers read
+            this sidecar rather than parsing the spec at runtime — so a
+            host declared only in the spec was in the same position as
+            the convention it replaced.
+          items:
+            type: object
+            additionalProperties: false
+            required: [url, replaces]
+            properties:
+              url:
+                type: string
+                format: uri
+                description: The host serving this operation.
+              replaces:
+                type: string
+                minLength: 1
+                description: |
+                  **The ROOT server URL this entry overrides.** A client
+                  matches its own configured base against this exactly
+                  and takes `url`.
+
+                  ⚠️ **Without it the mapping has to be inferred** from
+                  list ordering or hostname shape — which is a
+                  per-client rule, and therefore the precise thing that
+                  declaring the split was meant to remove. An
+                  unmatched base is an honest *"no override for the host
+                  you are pointed at"* rather than a guess.
+              description:
+                type: string
+                description: |
+                  Verbatim from the operation's server entry. Carries
+                  the caveats a URL cannot — CORS scope, whether the
+                  entry exercises the split-host topology at all.
         auth:
           type: string
           enum: [anonymous, optional, required]
@@ -14019,9 +14237,17 @@ components:
           type: string
           enum: [stable, beta, experimental, planned, deprecated]
           description: |
-            Endpoint-level availability tag. Currently always
-            `"stable"` for shipped endpoints. Reserved for future
-            `planned` / `deprecated` endpoint-level annotation.
+            Endpoint-level availability, **DERIVED from the operation's
+            `x-availability`** and defaulting to `stable` when the
+            operation declares none.
+
+            ⚠️ **It is NOT always `stable`.** This description used to
+            say it was, and the sidecar agreed with it — because the
+            generator HARDCODED the value. Four endpoints read `planned`
+            today, three of which (`probeUpload`,
+            `createExternalImport`, `decodeAudioWatermark`) had declared
+            `planned` in the spec all along and were silently
+            contradicted.
         operation_id:
           type: string
           description: |

package/operation-capabilities/operation-capabilities.json

@@ -732,5 +732,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.192.0"
+  "schema_version": "2.194.0"
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.63.0",
-  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.192.0.",
-  "gislContractsSpec": "v2.192.0",
+  "version": "0.65.0",
+  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.194.0.",
+  "gislContractsSpec": "v2.194.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",