@giveitsmaller/contracts 0.51.0 → 0.53.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.152.0
+  version: 2.154.0
   contact:
     name: API Support
 
@@ -7187,7 +7187,7 @@ components:
           exceeds the per-input ceiling (`max_input_size_bytes` /
           `max_input_duration`). Applies to single-input operations
           (compress, convert, thumbnail, text_watermark,
-          audio_watermark) AND per-input checks on multi-input
+          audio_watermark, transform) AND per-input checks on multi-input
           operations with per-input caps (image_watermark,
           custom_luma, audio_overlay).
         - `combined_size_exceeds_long_form` /
@@ -7594,6 +7594,8 @@ components:
         - split: Fan one input file into N outputs across GIF / PDF / audio / video MIME families. Single-input per-mime-group catalog (mirrors merge/convert): GIF uses `frame_range` (REQUIRED) + `output_format`; PDF uses `page_range` OR `page_groups` (mutually exclusive); audio + video use a `mode` discriminator (interval/count/cut_points) + numeric-seconds wire format + `precision` flag (fast/exact). 200-output hard cap per ADR-0009 §D5 with per-mode preflight math; output naming `output-001..output-200`. Long-form video routes to a separate `split-video-fargate` worker via `processing_class`. `availability: beta` for the `audio` and `video` mime_groups (workers live on staging — shape-stable + opt-in, MUST NOT 422); video activates BOTH classes (`video.processing_class.short_form: beta` AND `long_form: beta` — `split-video-fargate` deployed + wired on staging but NOT yet proven end-to-end per [`rcwvUKhI`](https://trello.com/c/rcwvUKhI); the first customer-path soak has not completed, the 4GB+ speed-up is unmeasured, and the long-form fan-out is flag-gated dark). The `image_gif` and `document_pdf` mime_groups stay `availability: planned` and dispatch returns `feature_not_available` (422) until their workers ship. Per ticket [`vKI0CFDu`](https://trello.com/c/vKI0CFDu) + ADR-0014.
         - passthrough: Inert lossless source operation. A single-input source job whose SOLE operation is `passthrough` emits its source bytes UNCHANGED — no compression, no Lambda. The API self-completes the job at publish (terminal output = the upload `{bucket, key}` unchanged). Its purpose is to feed an uploaded file into a multi-input operation LOSSLESSLY: because `JobInputV2.source` is narrowed to exclude upload-direct, an upload that must enter a `merge` / `archive` / `image_watermark` op enters via a `passthrough` source job referenced downstream by `{type: job_output, from: <id>}` — preserving billing / DAG / lineage. Distinct from `operations: []` (which keeps its implicit-compress meaning on a single-input upload job); `passthrough` is the EXPLICIT lossless path via the "non-empty `operations[]` without `compress` = compression opt-out" rule. Media-agnostic; no options. `availability: beta` — activated (the inputs[]-narrowing + passthrough self-complete mechanism is deployed API-side); workflow-create accepts `passthrough` source jobs and MUST NOT return `feature_not_available`. **Never published to SNS** — deliberately absent from the AsyncAPI routing enums (API self-completes; no `ops-passthrough` queue). Per ticket [`4som89Uh`](https://trello.com/c/4som89Uh) + ADR-0004 (planned→beta flip).
 
+        - transform: Geometric/orientation transform — v1 = rotate (0/90/180/270) + flip (none/horizontal/vertical/both), ADR-0026. Single-input; `produces: same_as_input` (geometry preserves format/container). Chainable (NOT sole_op); canonical single-job chain order is `transform → convert → compress → thumbnail` (geometry before encode/derive so downstream width/height/fit refer to the final frame). Media groups: image (still jpeg/png/webp + animated `image_gif`), video (mp4/webm), document (PDF page-rotate only — no flip); audio not supported. ALL groups `availability: planned` (epic `fhiWebI0`) — workflow-create returns `feature_not_available` (422) until per-media Lambdas ship. A no-op transform (`rotate: 0` + `flip: none`) is rejected as `invalid_options`. The public operation type is `transform`; the API resolves an internal per-media SNS routing sub-type (`transform_image` / `transform_video` / `transform_document`) — those sub-types are routing-only and are NOT part of this public enum. Per ADR-0026.
+
         Both the legacy `thumbnail` value and the four sub-type values
         are valid routing targets today during the thumbnail migration
         window. See `asyncapi/events.yaml` for the full routing
@@ -7622,6 +7624,7 @@ components:
         - video_watermark
         - video_text_watermark
         - split
+        - transform
         - passthrough
 
     OperationInputModel:
@@ -7631,7 +7634,7 @@ components:
         - single: One input file (compress, thumbnail, thumbnail_image,
           thumbnail_video, thumbnail_document, thumbnail_office,
           text_watermark, convert, audio_watermark,
-          video_text_watermark, split, passthrough)
+          video_text_watermark, split, transform, passthrough)
         - multi: Multiple input files (merge, archive, image_watermark, custom_luma, audio_overlay, audio_to_video, video_watermark). audio_to_video is the first role-based op with an OPTIONAL role (min_inputs=1, max_inputs=2 — see `per_role_cardinality`); video_watermark is a fixed base+overlay pair (exactly one each, min_inputs=max_inputs=2) on video bases; image_watermark widened to base + 1–8 overlays (min 2 / max 9) with the multi_overlay_stack flip (2026-07-01).
       enum:
         - single
@@ -9408,12 +9411,18 @@ components:
           description: |
             The canonical pipeline spine (single mutated stream), as an
             ordered list of `chain_group` stage names. The known image/AV
-            spine is `merge` (fan-in) → `image_watermark` → `text_watermark`
-            → `audio` → `encode` (terminal: convert+compress folded) →
-            `derived` (fan-out: thumbnail/split). Informational — read per-op
-            `chain_group` / `chain_position` for placement. The geometry
-            stage is intentionally not exposed as a node for v1 (image
-            resize/fit live inside the thumbnail node).
+            spine is `transform` (geometry: rotate/flip) → `merge` (fan-in)
+            → `image_watermark` → `text_watermark` → `audio` → `encode`
+            (terminal: convert+compress folded) → `derived` (fan-out:
+            thumbnail/split). Informational — read per-op `chain_group` /
+            `chain_position` for placement. The `transform` geometry stage
+            (ADR-0026) runs FIRST — orientation before resize/encode so
+            downstream width/height/fit refer to the final frame; its
+            canonical single-job order is `transform → convert → compress →
+            thumbnail`. It is `availability: planned` (epic `fhiWebI0`) — no
+            transform nodes are produced until it activates. (Image
+            resize/fit still live inside the `thumbnail` node — that is a
+            separate stage from the `transform` op.)
 
             **Open string, NOT a fixed enum** (mirrors
             `ProcessingPlanJob.execution_pool`): the canonical model still
@@ -9493,6 +9502,9 @@ components:
             `additionalProperties: false`; consumers MUST treat unknown
             stage names as forward-compatible. The watermark stages are
             **media-agnostic overlay stages**, not image-only. Known stages:
+            - `transform`: geometry stage (rotate/flip) — covers the
+              `transform` operation type. Runs first in the spine (ADR-0026);
+              `availability: planned` until activation.
             - `merge`: fan-in.
             - `image_watermark`: raster/image-overlay watermark stage —
               covers the `image_watermark` AND `video_watermark` operation

package/operation-capabilities/operation-capabilities.json

@@ -454,6 +454,21 @@
       },
       "sole_op": false
     },
+    "transform": {
+      "accepts": [
+        "document",
+        "image",
+        "video"
+      ],
+      "availability": "planned",
+      "input": {
+        "model": "single"
+      },
+      "produces": {
+        "same_as_input": true
+      },
+      "sole_op": false
+    },
     "video_text_watermark": {
       "accepts": [
         "video"
@@ -565,5 +580,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.152.0"
+  "schema_version": "2.154.0"
 }

package/operations/schemas/transform.yaml

@@ -0,0 +1,196 @@
+schema_version: "2.0.0"
+
+operation:
+  type: transform
+  availability: planned
+  description: |
+    Apply a geometric / orientation transform to a media asset. **v1 supports
+    rotate + flip only** (orientation transforms) — it does NOT do crop, scale,
+    skew, or colour transforms. The name is deliberately `transform` (not
+    `orient`) to leave room for a future `crop` on the same op; do not read the
+    name as advertising arbitrary affine transforms. Full design + normative
+    order-of-operations, routing topology, chain order, media gating, and
+    billing model: ADR-0026.
+
+    **Params (per media group):**
+    - `rotate` — `0 | 90 | 180 | 270` degrees clockwise (default `0`).
+    - `flip` — `none | horizontal | vertical | both` mirror (default `none`).
+      `horizontal` = left↔right (the selfie/webcam mirror-correction),
+      `vertical` = top↔bottom, `both` = both axes.
+
+    **Normative order-of-operations (v1 has NO arbitrary sequence).** For a
+    single `transform` op the worker applies, in this fixed order:
+    1. (images) normalize display orientation from EXIF,
+    2. apply `rotate`,
+    3. apply `flip` in the FINAL (post-rotate) display axes,
+    4. (images) write pixels with the orientation tag reset/removed.
+    So `flip: horizontal` always means left↔right in the *visible result*, even
+    after a 90/270 rotate. See ADR-0026 §Order-of-operations.
+
+    **auto_orient coexistence.** `transform` reads the image honouring EXIF
+    orientation, applies rotate/flip, and emits normalized-orientation pixels —
+    so a downstream `compress`/`convert` `auto_orient` is a no-op. Raw
+    stored-pixel rotation that ignores EXIF is out of scope for v1.
+
+    **No-op is rejected at create.** A `transform` with `rotate: 0` AND
+    `flip: none` (for documents: `rotate: 0`) does nothing, so the API rejects
+    it as `invalid_options` at create — there is no billed, worker-dispatched
+    no-op (mirrors the API facade gate that rejects inert option combos). At
+    least one of `rotate`/`flip` must be non-default.
+
+    **Media scope (v1).** IMAGE **still-raster** (jpeg/png/webp) and animated
+    GIF; VIDEO (mp4/webm); DOCUMENT is PDF-rotate ONLY (no flip — the
+    `document_pdf` group offers `rotate` alone). AUDIO is intentionally absent
+    (no spatial geometry). SVG, HEIC/AVIF, and non-PDF documents
+    (Office/ODF/EPUB) are out of scope for v1 and are not advertised.
+    **Animated PNG (APNG) and animated WebP** are NOT covered by the
+    still-raster `image` group's activation proof — like animated GIF, a
+    pixel-baking geometry op would drop frames / animation metadata. Before the
+    `image` group flips stable the worker MUST either reject animated PNG/WebP
+    variants at probe or transform ALL frames + preserve animation metadata
+    (same bar as the `image_gif` group). Everything ships `availability:
+    planned` first and flips per media on worker capability-source proof
+    (ADR-0006) — each activation co-updates schema availability + AsyncAPI
+    routing + API OperationType/chain/pricing + the billing weight row together
+    (ADR-0026 §Rollout).
+
+    **Routing (thumbnail precedent).** The payload `operation_type` stays the
+    base value `transform`; the API publisher resolves the effective input MIME
+    to an SNS `operation_type` routing-attribute sub-type
+    (`transform_image` / `transform_video` / `transform_document`). Those
+    sub-types are ROUTING ATTRIBUTES ONLY — never persisted or public operation
+    types (they are absent from the OperationType payload enum). The
+    `document_pdf` group routes under `transform_document` (media-family level,
+    even though v1 is PDF-only). See ADR-0026 §Routing + asyncapi/events.yaml.
+  default: false
+  input_model: single
+  # Chains normally (ADR-0025: absent ≡ false; set explicitly to document intent).
+  # Canonical single-job order is transform -> convert -> compress -> thumbnail
+  # (ADR-0026): orientation runs before resize/encode so downstream width/height/fit
+  # refer to the final visual frame, and rotate never triggers a second video encode.
+  sole_op: false
+
+  mime_groups:
+    image:
+      # Still-raster first. availability:planned until the image worker
+      # (Rust `image` crate: fliph/flipv/rotate90/180/270 — already vendored for
+      # resize/thumbnail) is capability-proven, then flips stable per ADR-0006.
+      # STILL jpeg/png/webp only: animated PNG (APNG) + animated WebP are NOT
+      # covered by this group's still-raster proof (a pixel-bake drops frames /
+      # animation metadata) — they must be rejected at probe OR handled with
+      # all-frames + animation-metadata preservation (GIF bar) before the flip.
+      availability: planned
+      mimes:
+        - image/jpeg
+        - image/png
+        - image/webp
+      options:
+        rotate:
+          type: enum
+          value_type: integer
+          values: [0, 90, 180, 270]
+          default: 0
+          description: >-
+            Clockwise rotation in degrees. Applied BEFORE `flip` (see the
+            operation-level normative order-of-operations).
+        flip:
+          type: enum
+          values: [none, horizontal, vertical, both]
+          default: none
+          description: >-
+            Mirror the image. `horizontal` = left↔right, `vertical` = top↔bottom,
+            `both` = both axes. Applied AFTER `rotate`, in the final (post-rotate)
+            display axes, so `horizontal` always means left↔right in the visible
+            result.
+
+    image_gif:
+      # Animated GIF as a parallel planned group (mirrors image_watermark's
+      # image_gif). Only honest once the worker transforms ALL frames AND
+      # preserves animation metadata (frame delays, loop count, disposal);
+      # dispatch returns feature_not_available (422) until that ships. Do NOT
+      # flip stable on the still-raster proof alone.
+      availability: planned
+      mimes:
+        - image/gif
+      options:
+        rotate:
+          type: enum
+          value_type: integer
+          values: [0, 90, 180, 270]
+          default: 0
+          description: "Clockwise rotation in degrees (all frames). Applied before `flip`."
+        flip:
+          type: enum
+          values: [none, horizontal, vertical, both]
+          default: none
+          description: "Mirror all frames. Applied after `rotate`, in final display axes."
+
+    video:
+      # mp4/webm first (the FFmpeg containers we already decode AND encode).
+      # hflip/vflip + transpose bake into pixels → a real re-encode (no
+      # stream-copy shortcut), so it costs compute like any transcode (billing
+      # weight 10, ADR-0026). quicktime/mov and other containers follow the same
+      # decode-AND-encode proof discipline and are not advertised in v1.
+      mimes:
+        - video/mp4
+        - video/webm
+      processing_class:
+        # F8 long-form video tier (ADR-0011). Both classes ship planned; short_form
+        # is first-in-line to flip on the FFmpeg worker proof, long_form stays
+        # planned until the Fargate re-encode route is real and costed (ADR-0026).
+        short_form:
+          availability: planned
+          constraints:
+            max_input_duration: "PT5M"
+            max_input_size_bytes: 524288000
+            max_output_size_bytes: 524288000
+        long_form:
+          availability: planned
+          required_tier: pro
+          constraints:                            # baseline = Pro
+            max_input_duration: "PT12H"
+            max_input_size_bytes: 5000000000       # 5 GB (Pro)
+            max_output_size_bytes: 5000000000
+          per_tier_constraints:
+            max:
+              max_input_size_bytes: 50000000000    # 50 GB (Max self-serve band)
+              max_output_size_bytes: 50000000000
+            enterprise:
+              max_input_size_bytes: 120000000000   # 120 GB (Enterprise enforced ceiling)
+              max_output_size_bytes: 120000000000
+      options:
+        rotate:
+          type: enum
+          value_type: integer
+          values: [0, 90, 180, 270]
+          default: 0
+          description: >-
+            Clockwise rotation in degrees (FFmpeg `transpose`). Applied BEFORE
+            `flip`. Re-encodes the video.
+        flip:
+          type: enum
+          values: [none, horizontal, vertical, both]
+          default: none
+          description: >-
+            Mirror the video (FFmpeg `hflip` / `vflip`). `horizontal` = left↔right,
+            `vertical` = top↔bottom, `both` = both. Applied AFTER `rotate`, in the
+            final display axes. Re-encodes the video.
+
+    document_pdf:
+      # PDF-rotate ONLY (page rotation for scanned/phone PDFs). NO flip — mirror
+      # is not a clean promise for documents. Office/ODF/EPUB are NOT covered
+      # (page rotation there is not same_as_input). availability:planned,
+      # flips beta/stable separately on worker proof; routes under the
+      # media-family attribute transform_document (ADR-0026 §Routing).
+      availability: planned
+      mimes:
+        - application/pdf
+      options:
+        rotate:
+          type: enum
+          value_type: integer
+          values: [0, 90, 180, 270]
+          default: 0
+          description: >-
+            Clockwise page rotation in degrees, applied to the rendered page
+            orientation. `flip` is NOT offered for documents in v1.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.51.0",
+  "version": "0.53.0",
   "description": "Generated contract types for GISL (Give It Smaller)",
   "license": "MIT",
   "type": "module",
@@ -29,6 +29,7 @@
     "./accepted-options/accepted-options.json": "./accepted-options/accepted-options.json",
     "./accepted-options/image-output-routes.json": "./accepted-options/image-output-routes.json",
     "./operation-capabilities/operation-capabilities.json": "./operation-capabilities/operation-capabilities.json",
+    "./code-builder/code-builder-metadata.json": "./code-builder/code-builder-metadata.json",
     "./operations/schemas/archive.yaml": "./operations/schemas/archive.yaml",
     "./operations/schemas/audio_overlay.yaml": "./operations/schemas/audio_overlay.yaml",
     "./operations/schemas/audio_to_video.yaml": "./operations/schemas/audio_to_video.yaml",
@@ -43,6 +44,7 @@
     "./operations/schemas/split.yaml": "./operations/schemas/split.yaml",
     "./operations/schemas/text_watermark.yaml": "./operations/schemas/text_watermark.yaml",
     "./operations/schemas/thumbnail.yaml": "./operations/schemas/thumbnail.yaml",
+    "./operations/schemas/transform.yaml": "./operations/schemas/transform.yaml",
     "./operations/schemas/video_text_watermark.yaml": "./operations/schemas/video_text_watermark.yaml",
     "./operations/schemas/video_watermark.yaml": "./operations/schemas/video_watermark.yaml"
   },
@@ -54,7 +56,8 @@
     "availability/availability.json",
     "accepted-options/accepted-options.json",
     "accepted-options/image-output-routes.json",
-    "operation-capabilities/operation-capabilities.json"
+    "operation-capabilities/operation-capabilities.json",
+    "code-builder/code-builder-metadata.json"
   ],
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\"",