@giveitsmaller/contracts 0.19.0 → 0.21.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.73.0
+  version: 2.78.0
   contact:
     name: API Support
 
@@ -1932,6 +1932,18 @@ paths:
           description: Workflow ID (UUID v7)
           schema:
             $ref: '#/components/schemas/UuidV7'
+        - name: X-Workflow-Capability
+          in: header
+          required: false
+          schema:
+            type: string
+          description: |
+            Capability token (the `cap` from the anonymous workflow-create
+            response) authorizing this read for a **null-owner** workflow.
+            Optional — an authenticated owner does not need it. A wrong or
+            missing cap on a null-owner workflow returns 404 `WorkflowNotFound`
+            (no existence oracle — not 401/403). Per ticket
+            [`YQt88cq2`](https://trello.com/c/YQt88cq2).
       responses:
         '200':
           description: Workflow status retrieved
@@ -2015,6 +2027,18 @@ paths:
           description: Workflow ID (UUID v7)
           schema:
             $ref: '#/components/schemas/UuidV7'
+        - name: X-Workflow-Capability
+          in: header
+          required: false
+          schema:
+            type: string
+          description: |
+            Capability token (the `cap` from the anonymous workflow-create
+            response) authorizing this read for a **null-owner** workflow.
+            Optional — an authenticated owner does not need it. A wrong or
+            missing cap on a null-owner workflow returns 404 `WorkflowNotFound`
+            (no existence oracle — not 401/403). Per ticket
+            [`YQt88cq2`](https://trello.com/c/YQt88cq2).
       responses:
         '200':
           description: Download URLs retrieved
@@ -2119,6 +2143,26 @@ paths:
           description: Workflow ID (UUID v7)
           schema:
             $ref: '#/components/schemas/UuidV7'
+        - name: X-Workflow-Capability
+          in: header
+          required: false
+          schema:
+            type: string
+          description: |
+            Capability token (the `cap` from the anonymous workflow-create
+            response) authorizing this read for a **null-owner** workflow.
+            Optional — an authenticated owner does not need it. A wrong or
+            missing cap on a null-owner workflow returns 404 `WorkflowNotFound`
+            (no existence oracle — not 401/403). Per ticket
+            [`YQt88cq2`](https://trello.com/c/YQt88cq2).
+
+            **SSE transport note:** native browser `EventSource` cannot set
+            request headers (its constructor accepts only `url` + `withCredentials`
+            per the WHATWG SSE spec), so an anonymous caller must reach this
+            endpoint with a header-capable SSE client (a `fetch`-based
+            `EventSource` implementation). The cap is deliberately NOT accepted as
+            a query parameter — that would leak the bearer into URLs / logs /
+            referrers.
       responses:
         '200':
           description: SSE event stream
@@ -5963,6 +6007,49 @@ components:
         created_at:
           type: string
           format: date-time
+        # Activity-display fields (ticket B9ppslt2 / odct4sPB) — additive, all
+        # nullable + optional. Populate ONLY on `type: reservation` rows going
+        # forward; legacy reservation rows (pre-migration) and all non-reservation
+        # ledger types emit `null`. The frontend composes the human "Recent
+        # activity" label from these STRUCTURED fields (operation_summary +
+        # operation_count + primary_filename + type/state) instead of the opaque
+        # `description` legacy fallback. No separate `label` field — FE composes
+        # it (en/pt). Part A (state/state_changed_at) is live on API main (#426);
+        # Part B (operation_summary/operation_count/primary_filename) lands
+        # additively from the API ahead of this contract.
+        state:
+          type: [string, "null"]
+          description: |
+            Reservation lifecycle state — free-form string (kept opaque like
+            `type`/`reference_type` for churn-resistance; SDKs duck-type).
+            Current values: `active` (held), `settled` (charged), `released` /
+            `cancelled_released` (refunded / cancelled), `expired`. `null` for
+            non-reservation ledger types. Lets the consumer distinguish an
+            internal HOLD from a final charge rather than showing raw
+            reservations as spends.
+        state_changed_at:
+          type: [string, "null"]
+          format: date-time
+          description: |
+            RFC3339 / ISO-8601 timestamp of the last `state` transition.
+            `null` for non-reservation types.
+        operation_summary:
+          type: [string, "null"]
+          description: |
+            Distinct canonical operation type(s) for the referenced workflow,
+            comma-joined (e.g. `"compress"` or `"convert, compress"`). `null`
+            for legacy rows + non-reservation types. Human-label input.
+        operation_count:
+          type: [integer, "null"]
+          minimum: 0
+          description: |
+            Count of operations in the referenced workflow. `null` for legacy /
+            non-reservation rows. Human-label input (e.g. "Compressed 3 images").
+        primary_filename:
+          type: [string, "null"]
+          description: |
+            Original filename of the primary (first) input of the referenced
+            workflow. `null` for legacy / non-reservation rows. Human-label input.
 
     CreditsUsageResponse:
       type: object
@@ -9536,6 +9623,25 @@ components:
             Use this key to verify the `X-GIS-Signature` header on incoming webhook
             requests: `sha256=<hex(hmac-sha256(webhook_secret, raw_body))>`.
           example: "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
+        cap:
+          type:
+            - string
+            - "null"
+          readOnly: true
+          description: |
+            Per-workflow capability token (plaintext). Present ONLY for an
+            **anonymous (null-owner)** workflow create — it is the bearer that
+            authorizes reads of this workflow without a session. ABSENT for
+            authenticated creates (the session authorizes those). Like
+            `webhook_secret`, this is the only time it is exposed; it does not
+            appear in status queries.
+
+            Pass it as the `X-Workflow-Capability` request header on
+            `GET /api/workflows/{id}/status` / `/downloads` / `/events`. A wrong
+            or missing cap on a null-owner workflow returns **404**
+            (`WorkflowNotFound`) — deliberately no existence oracle (not 401/403).
+            Per ticket [`YQt88cq2`](https://trello.com/c/YQt88cq2).
+          example: "wcap_3f8a1c9e2b7d4f60a5c1e8b2d9f6a0c3"
 
     WorkflowCreateSuccessEnvelope:
       type: object

package/operations/schemas/compress.yaml

@@ -76,21 +76,22 @@ operation:
             # hlKCslIu-class over-claim. Tagged `planned` until each value's
             # facade piece lands (API canonicalization + lambdas encode), then
             # flipped `stable` per value with capability proof (ADR-0001/0006).
-            # ALL non-`original` values are tagged `planned`: the compress+format
-            # FACADE path (API canonicalization → convert) is not live for ANY
-            # value until [API] IsjNT2PJ ships, so even jpeg/avif are dormant-safe
-            # `planned` in this lead PR (without the marker the canonicalizer would
-            # dispatch them to a not-live path). They flip `stable` per value as
-            # each facade piece lands + capability proof (ADR-0001/0006): jpeg/avif
-            # first (closest — shipped foldImageEncodeOperations), then png (API
-            # fold), webp (lambdas lossy-webp PfGs5PBT), auto/smallest (runtime
-            # selection, unbuilt). `original` (same-format, today's behaviour) stays stable.
+            # Values flip `stable` per value as each facade piece lands: `webp` is
+            # DONE (see the stable-flip note below); the rest stay `planned` — auto/
+            # smallest (runtime selection, unbuilt), jpeg/png/avif (no canonicalization
+            # live yet). `original` (same-format, today's behaviour) stays stable.
+            # WEBP STABLE-FLIP (VcPeRWdD): webp is now FUNCTIONAL end-to-end — API B
+            # (#422) canonicalizes compress(image,webp)→convert(webp,quality) + lambdas
+            # lossy-webp (PfGs5PBT) is live+proven on staging — so webp is removed from
+            # this map (untagged = stable, ADR-0001 §1.4). jpeg/png/avif/auto/smallest
+            # stay `planned` (their canonicalization is NOT in API B — flipping them now
+            # would stop the 422 while they still dispatch to the same-format worker =
+            # silent no-op, re-opening the over-claim).
             auto:     { availability: planned }   # runtime Accept-best selection — unbuilt
             smallest: { availability: planned }   # runtime try-all-smallest selection — unbuilt
-            jpeg:     { availability: planned }   # facade path not live until IsjNT2PJ
-            png:      { availability: planned }   # facade path not live until IsjNT2PJ
-            webp:     { availability: planned }   # + needs lambdas lossy-webp (PfGs5PBT)
-            avif:     { availability: planned }   # facade path not live until IsjNT2PJ
+            jpeg:     { availability: planned }   # facade path not live until its own canonicalization
+            png:      { availability: planned }   # facade path not live until its own canonicalization
+            avif:     { availability: planned }   # facade path not live until its own canonicalization
           description: >-
             Output format. original = keep input format (default); auto = best for browser
             support (AVIF > WebP > JPEG via Accept hint); smallest = try all supported formats,
@@ -110,19 +111,14 @@ operation:
           type: enum
           values: [original, mp3, aac, ogg, flac, wav]
           default: original
-          per_value_availability:
-            # FACADE (VcPeRWdD): "compress audio + change format" resolves to a
-            # SINGLE API-canonicalized convert pass (the API computes a discrete
-            # target bitrate; convert honours it via -b:a — no compress-worker
-            # change, no source-relative cap needed for audio). Non-`original`
-            # values are facade-pending until the API canonicalization lands,
-            # then flipped `stable` per value. `original` (same-format, today's
-            # behaviour) stays stable. Values mirror convert.audio.output_format.
-            mp3:  { availability: planned }
-            aac:  { availability: planned }
-            ogg:  { availability: planned }
-            flac: { availability: planned }
-            wav:  { availability: planned }
+          # FACADE (VcPeRWdD -> RTokti20 stable-flip): "compress audio + change
+          # format" resolves to a SINGLE API-canonicalized convert pass (the API
+          # computes a discrete target bitrate; convert honours it via -b:a — no
+          # compress-worker change, no source-relative cap needed for audio).
+          # All non-`original` values are now LIVE (API canonicalization landed,
+          # convert.audio worker live) so the per_value_availability block is
+          # removed => untagged = stable (ADR-0001 §1.4). Values mirror
+          # convert.audio.output_format.
           description: >-
             Output audio format. original = keep input format (default, same-format
             compression). Non-`original` values re-target the container/codec via the
@@ -136,7 +132,7 @@ operation:
             Output bitrate in kbps (CBR/ABR). Applies to lossy OUTPUTS. Only a
             caller-EXPLICIT bitrate against a lossless output is rejected as
             invalid_options (flac/wav have no bitrate target); the `default: 128` is
-            never the basis for a rejection (ADR-0020 D1 — a default a caller did not set
+            never the basis for a rejection (ADR-0020 D1, carried into ADR-0023 — a default a caller did not set
             is the server's to resolve, and is dropped for a lossless target). The output
             is the input format unless `output_format` re-targets it: with
             `output_format: original` the lossy/lossless distinction follows the input MIME
@@ -206,6 +202,37 @@ operation:
               max_input_size_bytes: 120000000000   # 120 GB (Enterprise enforced ceiling)
               max_output_size_bytes: 120000000000
       options:
+        output_format:
+          type: enum
+          values: [original, mp4, webm, ogg]
+          default: original
+          per_value_availability:
+            # FACADE Phase-2 (8t2iEd4f, ADR-0023 — supersedes ADR-0020).
+            # "compress video + change container" resolves to a SINGLE API-
+            # canonicalized convert(output_format=X + source-relative size-cap)
+            # pass — the compress worker stays same-format and NEVER reads
+            # output_format. Non-`original` values lead `planned` until the API
+            # canonicalization + the convert-video size-cap (lambdas 6M5Bz0zf)
+            # land and each value flips `stable` with capability proof (ADR-0006).
+            # `original` (same-format, today's behaviour) stays stable. gif is
+            # EXCLUDED (animation target, not a compress output — use convert/
+            # merge). ogg inherits convert.video's PRE-EXISTING Theora codec-enum
+            # gap (ADR-0023 D6); ogg-video codec/audio resolution is an explicit
+            # ogg stable-flip prerequisite. The API enforces planned->422
+            # feature_not_available generically (per-op effective-input-MIME);
+            # activated on the API re-vendor of this cut.
+            mp4:  { availability: planned }
+            webm: { availability: planned }
+            ogg:  { availability: planned }
+          description: >-
+            Output container. original = keep the input container (default,
+            same-format compression). Non-`original` values re-target the
+            container via the API "compress+format" facade (one canonicalized
+            convert-with-size-cap pass); see per_value_availability + ADR-0023 +
+            FORMAT.md. When set, the RESOLVED target container determines the
+            valid codec/audio_codec/faststart sets — an absent/default codec
+            resolves to a container-valid one (e.g. webm -> vp9) and is never
+            rejected; only a caller-EXPLICIT incompatible value is invalid_options.
         codec:
           type: enum
           values: [h264, h265, vp9, av1]
@@ -213,18 +240,33 @@ operation:
           description: >
             Video codec. h264 = widest compatibility, h265/av1 = better
             compression but slower. The default (h264) is the MP4/MOV standard
-            and is CONTAINER-CONDITIONAL: for an output container that cannot
-            carry it (e.g. WebM, which carries VP8/VP9/AV1) the server resolves
-            a container-valid codec (WebM -> vp9). A DEFAULT value is never
-            rejected; only a caller-EXPLICIT incompatible codec returns
-            invalid_options. See FORMAT.md "Container-conditional defaults" +
-            ADR-0020.
+            and is CONTAINER-CONDITIONAL against the RESOLVED output container
+            (the explicit `output_format` if set, else the input container): for
+            a container that cannot carry it (e.g. WebM, which carries VP8/VP9/
+            AV1) the server resolves a container-valid codec (WebM -> vp9). A
+            DEFAULT value is never rejected — including an explicit
+            `output_format: webm` left at the default `h264` (resolves to vp9,
+            NOT invalid_options); only a caller-EXPLICIT incompatible codec
+            returns invalid_options. See FORMAT.md "Container-conditional
+            defaults" + ADR-0023 (supersedes ADR-0020).
         encoding_mode:
           type: enum
           values: [crf, target_size]
           default: crf
-          # target_size is implemented as a two-pass encode in the worker.
-          description: "crf = constant quality (variable file size), target_size = constrained file size"
+          per_value_availability:
+            # honesty gate (hlKCslIu): the compress-video worker does NOT
+            # implement target_size two-pass — it REJECTS it
+            # (crates/shared/src/domain/video_encode_options.rs:248-259;
+            # lambdas-confirmed). `planned` until two-pass ships; `crf` (the
+            # default) stays stable. NOTE the current worker reject surfaces as
+            # `invalid_options`, NOT `feature_not_available` — `planned` is the
+            # honest availability signal (lets FE/SDK hide it) ahead of an edge-
+            # gate / the implementation. See ADR-0023 D8.
+            target_size: { availability: planned }
+          description: >-
+            crf = constant quality (variable file size). target_size =
+            constrained file size — `planned`: the worker does not yet implement
+            the two-pass encode (it rejects target_size); crf only today.
         crf:
           type: integer
           min: 0
@@ -235,9 +277,13 @@ operation:
         target_size_bytes:
           type: integer
           min: 1048576
+          availability: planned
           depends_on: { encoding_mode: target_size }
-          # Met via a two-pass encode in the worker.
-          description: "Target output file size in bytes (min 1MB)."
+          # honesty gate (hlKCslIu): two-pass NOT implemented — the worker
+          # REJECTS target_size_bytes (video_encode_options.rs:255-259), so this
+          # option is `planned`. The current reject is `invalid_options`, not
+          # feature_not_available; flips stable when two-pass ships. See ADR-0023 D8.
+          description: "Target output file size in bytes (min 1MB). `planned` — the worker does not yet implement the two-pass target-size encode."
         preset:
           type: enum
           values: [ultrafast, superfast, veryfast, faster, fast, medium, slow, slower, veryslow]
@@ -269,25 +315,32 @@ operation:
           default: true
           description: >
             Move the MP4/MOV moov atom to start for progressive web playback.
-            MP4/MOV only. CONTAINER-CONDITIONAL: the default (true) is silently
-            inapplicable for a container with no moov atom (e.g. WebM) — that
-            is NOT a rejection. Only a caller-EXPLICIT faststart:true on such a
-            container returns invalid_options. See FORMAT.md
-            "Container-conditional defaults" + ADR-0020.
+            MP4/MOV only. CONTAINER-CONDITIONAL against the RESOLVED output
+            container (the explicit `output_format` if set, else the input): the
+            default (true) is silently inapplicable for a container with no moov
+            atom (e.g. WebM) — that is NOT a rejection. Only a caller-EXPLICIT
+            faststart:true on such a container returns invalid_options. See
+            FORMAT.md "Container-conditional defaults" + ADR-0023 (supersedes
+            ADR-0020).
         audio_codec:
           type: enum
           values: [aac, opus, vorbis, copy]
           default: copy
           description: >
-            Audio codec. copy = passthrough (keep the source audio stream as-is;
-            re-encode only on explicit request) — aac = widest compatibility,
-            opus = best quality/size. Default is `copy` (ADR-0020 D7): it MATCHES
-            the worker's actual absent-audio behaviour and is container-safe for
-            compress (output container = input container, so the source stream is
-            already compatible). Set an explicit codec to re-encode; an explicit
-            codec the output container cannot carry (e.g. aac on a WebM output)
-            returns invalid_options. A DEFAULT value is never rejected. See
-            FORMAT.md "Container-conditional defaults" + ADR-0020.
+            Audio codec. copy = passthrough (keep the source stream as-is;
+            re-encode only on explicit request) — aac/opus/vorbis re-encode.
+            Default is `copy` (ADR-0020 D7, carried into ADR-0023): on the
+            same-container path (`output_format` original/absent) the source
+            stream is already container-compatible, so copy is safe. When
+            `output_format` RE-TARGETS the container, an absent/default
+            audio_codec resolves to a container-valid codec via the facade
+            (e.g. webm -> opus), NOT a blind copy of an incompatible stream — a
+            DEFAULT is never rejected (the exact per-container resolution, incl.
+            ogg vorbis-vs-opus, is an output_format stable-flip prerequisite,
+            ADR-0023 D5). A caller-EXPLICIT codec the resolved container cannot
+            carry (e.g. aac on a webm target) returns invalid_options. See
+            FORMAT.md "Container-conditional defaults" + ADR-0023 (supersedes
+            ADR-0020).
         audio_bitrate:
           type: enum
           value_type: integer

package/operations/schemas/convert.yaml

@@ -86,7 +86,7 @@ operation:
             codec (no literal default — the required output_format determines
             it). This is the container-conditional-default principle applied via
             an explicit container choice. See FORMAT.md
-            "Container-conditional defaults" + ADR-0020.
+            "Container-conditional defaults" + ADR-0023 (supersedes ADR-0020).
             Not applicable to a `gif` output (no video codec): an explicit
             `codec` on a `gif` output is rejected as `invalid_options` at
             workflow-create (the API enforces this `depends_on`); FE/SDK prune

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "Generated contract types for GISL (Give It Smaller)",
   "license": "MIT",
   "type": "module",