@lunora/bindings 1.0.0-alpha.5 → 1.0.0-alpha.50

package/dist/images/index.d.mts

@@ -1,69 +1,38 @@
 /**
-* Structural projections of the Cloudflare **Images** binding (`env.IMAGES`).
-*
-* Declared structurally — the same pattern `@lunora/storage` uses for
-* `R2BucketLike` — so a unit test can pass a plain object double and the real
-* `ImagesBinding` from `@cloudflare/workers-types` satisfies the same shape. We
-* project only the slice of the chain we actually call
-* (`input(stream).transform(opts).output(opts)` + `info(stream)`), not the full
-* hosted-images CRUD surface.
-*
-* TODO(workers-types): the 2026-06-16 optimization features — the `aspect-crop`
-* / `scale-up` fit modes and the `upscale` param — are modeled here by hand
-* because `@cloudflare/workers-types` (through 4.20260616.1) does not type them
-* yet. Re-check on the next `@cloudflare/workers-types` bump: once `ImageTransform`
-* carries `fit: "aspect-crop" | "scale-up"` and `upscale`, drop our hand-rolled
-* additions and lean on the upstream type.
-*/
+ * Structural projections of the Cloudflare **Images** binding (`env.IMAGES`).
+ *
+ * Declared structurally — the same pattern `@lunora/storage` uses for
+ * `R2BucketLike` — so a unit test can pass a plain object double and the real
+ * `ImagesBinding` from `@cloudflare/workers-types` satisfies the same shape. We
+ * project only the slice of the chain we actually call
+ * (`input(stream).transform(opts).output(opts)` + `info(stream)`), not the full
+ * hosted-images CRUD surface.
+ *
+ * TODO(workers-types): the 2026-06-16 optimization features — the `aspect-crop`
+ * / `scale-up` fit modes and the `upscale` param — are modeled here by hand
+ * because `@cloudflare/workers-types` (through 4.20260616.1) does not type them
+ * yet. Re-check on the next `@cloudflare/workers-types` bump: once `ImageTransform`
+ * carries `fit: "aspect-crop" | "scale-up"` and `upscale`, drop our hand-rolled
+ * additions and lean on the upstream type.
+ */
 /**
-* Porter-Duff compositing operation controlling how an overlay is blended onto
-* the image beneath it. Mirrors the binding's `ImageCompositeMode`.
-*
-* - `over` — foreground drawn on top of the backdrop (default).
-* - `in` — foreground shown only where the backdrop is opaque.
-* - `atop` — foreground drawn on top, clipped to the backdrop's shape.
-* - `out` — foreground shown only where the backdrop is transparent.
-* - `xor` — foreground and backdrop visible only where the other is not.
-* - `lighter` — foreground and backdrop channels added (brightening).
-*/
+ * Porter-Duff compositing operation controlling how an overlay is blended onto
+ * the image beneath it. Mirrors the binding's `ImageCompositeMode`.
+ *
+ * - `over` — foreground drawn on top of the backdrop (default).
+ * - `in` — foreground shown only where the backdrop is opaque.
+ * - `atop` — foreground drawn on top, clipped to the backdrop's shape.
+ * - `out` — foreground shown only where the backdrop is transparent.
+ * - `xor` — foreground and backdrop visible only where the other is not.
+ * - `lighter` — foreground and backdrop channels added (brightening).
+ */
 type ImageCompositeMode = "atop" | "in" | "lighter" | "out" | "over" | "xor";
 /**
-* One overlay in a {@link TransformOptions.draw} list — the **URL-form** overlay
-* (the `cf.image.draw` / `/cdn-cgi/image` shape), where the overlay image is
-* referenced by absolute `url`. For the **binding** path use {@link ImageOverlay}
-* instead, which carries the overlay bytes as a stream.
-*
-* `width`/`height` accept either an integer (pixels) or a decimal in `(0, 1]`
-* interpreted as a fraction of the base image's corresponding dimension.
-*/
-interface DrawOverlay {
-  /** Offset, in pixels, from the bottom edge. */
-  bottom?: number;
-  /** Blend mode for compositing this overlay onto the image. Default `over`. */
-  composite?: ImageCompositeMode;
-  /** Overlay height — pixels (integer) or a `0–1` fraction of the base height. */
-  height?: number;
-  /** Offset, in pixels, from the left edge. */
-  left?: number;
-  /** Overlay opacity, `0.0` (transparent) – `1.0` (opaque). */
-  opacity?: number;
-  /** Tile the overlay across the base image: `true`, or a single axis `"x"`/`"y"`. */
-  repeat?: "x" | "y" | boolean;
-  /** Offset, in pixels, from the right edge. */
-  right?: number;
-  /** Offset, in pixels, from the top edge. */
-  top?: number;
-  /** Absolute URL of the overlay image. */
-  url: string;
-  /** Overlay width — pixels (integer) or a `0–1` fraction of the base width. */
-  width?: number;
-}
-/**
-* Transform parameters threaded into `binding.input(stream).transform(...)`.
-* A structural subset of the real `ImageTransform`; the keys here are the
-* resize/format/optimize knobs apps reach for. Unknown extra keys on the real
-* binding are still accepted because the binding owns the authoritative type.
-*/
+ * Transform parameters threaded into `binding.input(stream).transform(...)`.
+ * A structural subset of the real `ImageTransform`; the keys here are the
+ * resize/format/optimize knobs apps reach for. Unknown extra keys on the real
+ * binding are still accepted because the binding owns the authoritative type.
+ */
 interface TransformOptions {
   /** Background color (CSS color) painted under transparent images. */
   background?: string;
@@ -74,24 +43,17 @@ interface TransformOptions {
   /** Contrast multiplier (1 = unchanged). */
   contrast?: number;
   /**
-  * URL-form overlays composited over the result, in paint order (last entry on
-  * top). Consumed by the URL builders ({@link DrawOverlay} references each
-  * overlay by `url`); the binding path applies overlays via the `overlays`
-  * argument to `Images.transform` instead, so this key is ignored there.
-  */
-  draw?: DrawOverlay[];
-  /**
-  * Resize mode. Affects how `width`/`height` are interpreted.
-  *
-  * - `scale-down` — contain, but never enlarges.
-  * - `contain` — fit within the box, preserving aspect ratio.
-  * - `cover` — fill the box, cropping overflow.
-  * - `crop` — shrink-and-crop to fit, but never enlarges.
-  * - `aspect-crop` — crop to the target aspect ratio, but never enlarges.
-  * - `pad` — fit within the box, padding the remainder with `background`.
-  * - `squeeze` — stretch to the exact box, distorting aspect ratio.
-  * - `scale-up` — enlarge to show the whole image, but never downscales.
-  */
+   * Resize mode. Affects how `width`/`height` are interpreted.
+   *
+   * - `scale-down` — contain, but never enlarges.
+   * - `contain` — fit within the box, preserving aspect ratio.
+   * - `cover` — fill the box, cropping overflow.
+   * - `crop` — shrink-and-crop to fit, but never enlarges.
+   * - `aspect-crop` — crop to the target aspect ratio, but never enlarges.
+   * - `pad` — fit within the box, padding the remainder with `background`.
+   * - `squeeze` — stretch to the exact box, distorting aspect ratio.
+   * - `scale-up` — enlarge to show the whole image, but never downscales.
+   */
   fit?: "aspect-crop" | "contain" | "cover" | "crop" | "pad" | "scale-down" | "scale-up" | "squeeze";
   /** Mirror the image horizontally, vertically, or both. */
   flip?: "h" | "hv" | "v";
@@ -114,11 +76,11 @@ interface TransformOptions {
   /** Sharpen strength (0–10). */
   sharpen?: number;
   /**
-  * Algorithm used when a transform enlarges the image (e.g. `fit: "scale-up"`).
-  *
-  * - `interpolate` — bicubic interpolation (default), may soften detail.
-  * - `generate` — AI upscaling for sharper, more detailed enlargements.
-  */
+   * Algorithm used when a transform enlarges the image (e.g. `fit: "scale-up"`).
+   *
+   * - `interpolate` — bicubic interpolation (default), may soften detail.
+   * - `generate` — AI upscaling for sharper, more detailed enlargements.
+   */
   upscale?: "generate" | "interpolate";
   /** Target width in pixels (integer). Clamped to the configured ceiling. */
   width?: number;
@@ -137,10 +99,10 @@ interface OutputOptions {
   quality?: number;
 }
 /**
-* The result of `binding.input(...).transform(...).output(...)`. Mirrors the
-* real `ImageTransformationResult` — a `Response`, the content type, and the
-* raw byte stream.
-*/
+ * The result of `binding.input(...).transform(...).output(...)`. Mirrors the
+ * real `ImageTransformationResult` — a `Response`, the content type, and the
+ * raw byte stream.
+ */
 interface ImageTransformationResultLike {
   contentType: () => string;
   image: () => ReadableStream<Uint8Array>;
@@ -156,11 +118,11 @@ type ImageInfoLike = {
   format: string;
 };
 /**
-* Binding-side overlay options for `transformer.draw(image, options)` — the
-* blend/position/opacity knobs. Unlike {@link DrawOverlay} there is no `url`
-* (the overlay bytes are passed as the stream) and no `width`/`height` (the
-* overlay is pre-sized via its own transform); mirrors `ImageDrawOptions`.
-*/
+ * Binding-side overlay options for `transformer.draw(image, options)` — the
+ * blend/position/opacity knobs. There is no `url` (the overlay bytes are passed
+ * as the stream) and no `width`/`height` (the overlay is pre-sized via its own
+ * transform); mirrors `ImageDrawOptions`.
+ */
 interface ImageDrawOptions {
   /** Offset, in pixels, from the bottom edge. */
   bottom?: number;
@@ -178,10 +140,10 @@ interface ImageDrawOptions {
   top?: number;
 }
 /**
-* One overlay applied through the **binding** path (`Images.transform`'s
-* `overlays` argument). The overlay bytes come from `image` (any {@link ImageInput});
-* an optional `transform` pre-sizes/reformats the overlay before it is drawn.
-*/
+ * One overlay applied through the **binding** path (`Images.transform`'s
+ * `overlays` argument). The overlay bytes come from `image` (any {@link ImageInput});
+ * an optional `transform` pre-sizes/reformats the overlay before it is drawn.
+ */
 interface ImageOverlay extends ImageDrawOptions {
   /** The overlay image bytes — a stream, buffer, `Blob`, or R2 object body. */
   image: ImageInput;
@@ -195,19 +157,19 @@ interface ImageTransformerLike {
   transform: (transform: TransformOptions) => ImageTransformerLike;
 }
 /**
-* Minimal projection of `ImagesBinding`. Declared structurally so unit tests can
-* pass a plain object double; the real `env.IMAGES` binding satisfies the same
-* shape. Only the input/transform/output chain and `info` are projected — the
-* hosted-images CRUD surface is out of scope.
-*/
+ * Minimal projection of `ImagesBinding`. Declared structurally so unit tests can
+ * pass a plain object double; the real `env.IMAGES` binding satisfies the same
+ * shape. Only the input/transform/output chain and `info` are projected — the
+ * hosted-images CRUD surface is out of scope.
+ */
 interface ImagesBindingLike {
   info: (stream: ReadableStream<Uint8Array>) => Promise<ImageInfoLike>;
   input: (stream: ReadableStream<Uint8Array>) => ImageTransformerLike;
 }
 /**
-* An R2 object body (as returned by `ctx.storage.download(key)`) — first-class
-* transform input. Only `.body` is read, so a structural projection is enough.
-*/
+ * An R2 object body (as returned by `ctx.storage.download(key)`) — first-class
+ * transform input. Only `.body` is read, so a structural projection is enough.
+ */
 interface R2ObjectBodyLike {
   body: ReadableStream | null;
 }
@@ -220,74 +182,89 @@ interface LunoraImagesOptions {
   maxDimension?: number;
 }
 /**
-* The action-only Images client wired onto `ctx.images`.
-*
-* The binding-backed `transform`/`info` calls are non-deterministic network /
-* compute I/O, so this lives on **ActionCtx only** — the same seam as `ctx.ai`.
-* The pure URL/signed-URL builders are exported as free functions (see
-* `index.ts`) and are safe to call from any handler.
-*/
+ * The action-only Images client wired onto `ctx.images`.
+ *
+ * The binding-backed `transform`/`info` calls are non-deterministic network /
+ * compute I/O, so this lives on **ActionCtx only** — the same seam as `ctx.ai`.
+ * The pure URL/signed-URL builders are exported as free functions (see
+ * `index.ts`) and are safe to call from any handler.
+ */
 interface Images {
   /**
-  * Probe an image for its format and (for raster formats) dimensions + byte
-  * size, without running a transform. Wraps `binding.info(...)`.
-  */
+   * Probe an image for its format and (for raster formats) dimensions + byte
+   * size, without running a transform. Wraps `binding.info(...)`.
+   */
   info: (input: ImageInput) => Promise<ImageInfoLike>;
   /**
-  * Resize / reformat / optimize `input`, returning the transformed result
-  * (a `Response`, content type, and byte stream). Accepts a raw stream/buffer,
-  * a `Blob`, or an R2 object body straight from `ctx.storage.download(key)`.
-  *
-  * `transform` dimensions are clamped to the configured ceiling and the output
-  * `format` is validated against the allowlist, so a hostile request can't
-  * mint a multi-gigapixel canvas or an unexpected content type.
-  *
-  * `overlays` are composited over the result in order (last on top) via the
-  * binding's `draw` step — each overlay's bytes come from its own `image`, with
-  * optional per-overlay `transform` (resize/reformat) and blend/position options.
-  */
+   * Resize / reformat / optimize `input`, returning the transformed result
+   * (a `Response`, content type, and byte stream). Accepts a raw stream/buffer,
+   * a `Blob`, or an R2 object body straight from `ctx.storage.download(key)`.
+   *
+   * `transform` dimensions are clamped to the configured ceiling and the output
+   * `format` is validated against the allowlist, so a hostile request can't
+   * mint a multi-gigapixel canvas or an unexpected content type.
+   *
+   * `overlays` are composited over the result in order (last on top) via the
+   * binding's `draw` step — each overlay's bytes come from its own `image`, with
+   * optional per-overlay `transform` (resize/reformat) and blend/position options.
+   */
   transform: (input: ImageInput, transform?: TransformOptions, output?: OutputOptions, overlays?: ImageOverlay[]) => Promise<ImageTransformationResultLike>;
 }
 /**
-* Build the action-only {@link Images} client over a Cloudflare Images binding.
-*
-* ```ts
-* const images = createImages({ binding: env.IMAGES });
-* const result = await images.transform(
-*     await ctx.storage.download("uploads/avatar.png"),
-*     { width: 256, height: 256, fit: "cover" },
-*     { format: "image/webp", quality: 82 },
-* );
-* ```
-*/
+ * Build the action-only {@link Images} client over a Cloudflare Images binding.
+ *
+ * ```ts
+ * const images = createImages({ binding: env.IMAGES });
+ * const result = await images.transform(
+ *     await ctx.storage.download("uploads/avatar.png"),
+ *     { width: 256, height: 256, fit: "cover" },
+ *     { format: "image/webp", quality: 82 },
+ * );
+ * ```
+ */
 declare const createImages: (options: LunoraImagesOptions) => Images;
 interface ImageDeliveryUrlOptions {
   /** Delivery / transform origin, e.g. `https://cdn.acme.test`. */
   baseUrl: string;
   /**
-  * Hosted-Images image id. When set, the **delivery-variant** form is built
-  * (`&lt;baseUrl>/&lt;imageId>/&lt;variant>`) and `transform`/`key` are ignored.
-  */
+   * Hosted-Images image id. When set, the **delivery-variant** form is built
+   * (`<baseUrl>/<imageId>/<variant>`) and `transform`/`key` are ignored.
+   */
   imageId?: string;
   /**
-  * Source image — an absolute URL or an origin-relative key. Used by the
-  * `/cdn-cgi/image/...` transform form. Ignored when `imageId` is set.
-  */
+   * Source image — an absolute URL or an origin-relative key. Used by the
+   * `/cdn-cgi/image/...` transform form. Ignored when `imageId` is set.
+   */
   key?: string;
-  /** Transform options for the `/cdn-cgi/image/&lt;options>/&lt;source>` form. */
+  /** Transform options for the `/cdn-cgi/image/<options>/<source>` form. */
   transform?: TransformOptions;
   /** Named delivery variant (e.g. `public`, `thumbnail`). Used with `imageId`; default `public`. */
   variant?: string;
 }
 /**
-* Build a Cloudflare Images delivery / transform URL.
-*
-* - With `imageId`: `&lt;baseUrl>/&lt;imageId>/&lt;variant>` (hosted delivery variant).
-* - With `key`: `&lt;baseUrl>/cdn-cgi/image/&lt;options>/&lt;source>` (URL-based transform).
-*
-* Pure and deterministic — usable from any handler.
-*/
+ * Build a Cloudflare Images delivery / transform URL.
+ *
+ * - With `imageId`: `<baseUrl>/<imageId>/<variant>` (hosted delivery variant).
+ * - With `key`: `<baseUrl>/cdn-cgi/image/<options>/<source>` (URL-based transform).
+ *
+ * Pure and deterministic — usable from any handler.
+ */
 declare const buildImageDeliveryUrl: (options: ImageDeliveryUrlOptions) => string;
+/**
+ * Parse a verified transform string (the `t` query value handed back by
+ * {@link verifySignedImageUrl}) back into the {@link TransformOptions} it was
+ * serialized from, so the Worker can apply exactly the signed transform via
+ * `ctx.images.transform(...)` without hand-writing the inverse encoding.
+ *
+ * The exact inverse of `serializeTransform` above — the two MUST evolve
+ * together (the round-trip test in
+ * `__tests__/images/signed-delivery-url.test.ts` pins the pairing). Throws a
+ * `TypeError` on an unknown key or an uncoercible value: the input is meant to
+ * be a string whose HMAC already verified, so a parse failure means
+ * encoder/decoder drift in the library, never user input — fail loud rather
+ * than silently un-binding the transform the signature protects.
+ */
+declare const parseSignedTransform: (t: string) => TransformOptions;
 interface SignedImageUrlOptions {
   /** Delivery / Worker origin the signed URL points at (e.g. `https://cdn.acme.test`). */
   baseUrl: string;
@@ -298,41 +275,50 @@ interface SignedImageUrlOptions {
   /** HMAC secret. MUST NOT be shared across tenants. */
   secret: string;
   /**
-  * Transform requested by this URL. Bound into the signature, so a client
-  * can't alter the render without invalidating it. The Worker should apply
-  * exactly this (verified) transform via `ctx.images.transform(...)`.
-  */
+   * Transform requested by this URL. Bound into the signature, so a client
+   * can't alter the render without invalidating it. The Worker should apply
+   * exactly this (verified) transform via `ctx.images.transform(...)`.
+   */
   transform?: TransformOptions;
 }
 /**
-* Mint a Worker-signed image URL: `baseUrl` joined to `key`, plus `exp` (unix
-* seconds), the serialized `t` (transform), and `sig` (base64url HMAC). The
-* canonical binds host + key + expiry + transform.
-*
-* The Worker handling the route should call {@link verifySignedImageUrl} to
-* validate before serving / transforming.
-*/
+ * Mint a Worker-signed image URL: `baseUrl` joined to `key`, plus `exp` (unix
+ * seconds), the serialized `t` (transform), and `sig` (base64url HMAC). The
+ * canonical binds host + key + expiry + transform.
+ *
+ * The Worker handling the route should call {@link verifySignedImageUrl} to
+ * validate before serving / transforming.
+ */
 declare const buildSignedImageUrl: (options: SignedImageUrlOptions) => Promise<string>;
 interface VerifyImageResult {
   /** The verified image key (route pathname). */
   key?: string;
   /**
-  * Internal-only failure reason for server logs/diagnostics. **Do not echo to
-  * clients** — a precise reason ("expired" vs "bad_signature") is a signing
-  * oracle. Public responses should expose only `valid`.
-  */
+   * Internal-only failure reason for server logs/diagnostics. **Do not echo to
+   * clients** — a precise reason ("expired" vs "bad_signature") is a signing
+   * oracle. Public responses should expose only `valid`.
+   */
   reason?: "bad_signature" | "expired" | "malformed";
   /** The raw, verified transform string (the `t` query value), when present. */
   transform?: string;
+  /**
+   * The verified transform decoded back into the options object to pass to
+   * `ctx.images.transform(...)` — {@link parseSignedTransform} applied to
+   * `transform`. Left `undefined` when `transform` is absent, and also when a
+   * genuinely signed transform carries a key this build does not know (an
+   * old URL minted before a key was renamed): the request stays `valid`, the
+   * raw `transform` is still returned, and the caller decides.
+   */
+  transformOptions?: TransformOptions;
   valid: boolean;
 }
 /**
-* Verify a {@link buildSignedImageUrl} output. By default the signature is
-* canonicalized against the inbound `url.host`; pass `expectedHost` for a
-* CDN/host-rewrite topology where the Worker sees a different host than the one
-* the URL was minted for.
-*/
+ * Verify a {@link buildSignedImageUrl} output. By default the signature is
+ * canonicalized against the inbound `url.host`; pass `expectedHost` for a
+ * CDN/host-rewrite topology where the Worker sees a different host than the one
+ * the URL was minted for.
+ */
 declare const verifySignedImageUrl: (input: string | URL, secret: string, options?: {
   expectedHost?: string;
 }) => Promise<VerifyImageResult>;
-export { type DrawOverlay, type ImageCompositeMode, type ImageDeliveryUrlOptions, type ImageDrawOptions, type ImageInfoLike, type ImageInput, type ImageOutputFormat, type ImageOverlay, type ImageTransformationResultLike, type ImageTransformerLike, type Images, type ImagesBindingLike, type LunoraImagesOptions, type OutputOptions, type R2ObjectBodyLike, type SignedImageUrlOptions, type TransformOptions, type VerifyImageResult, buildImageDeliveryUrl, buildSignedImageUrl, createImages, verifySignedImageUrl };
+export { type ImageCompositeMode, type ImageDeliveryUrlOptions, type ImageDrawOptions, type ImageInfoLike, type ImageInput, type ImageOutputFormat, type ImageOverlay, type ImageTransformationResultLike, type ImageTransformerLike, type Images, type ImagesBindingLike, type LunoraImagesOptions, type OutputOptions, type R2ObjectBodyLike, type SignedImageUrlOptions, type TransformOptions, type VerifyImageResult, buildImageDeliveryUrl, buildSignedImageUrl, createImages, parseSignedTransform, verifySignedImageUrl };