@lunora/bindings 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/images/index.d.mts

@@ -1,41 +1,41 @@
 /**
-* 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.
-*/
+ * 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;
@@ -59,11 +59,11 @@ interface DrawOverlay {
   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 +74,24 @@ 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.
-  */
+   * 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 +114,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 +137,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 +156,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. 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`.
+ */
 interface ImageDrawOptions {
   /** Offset, in pixels, from the bottom edge. */
   bottom?: number;
@@ -178,10 +178,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 +195,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,73 +220,73 @@ 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;
 interface SignedImageUrlOptions {
   /** Delivery / Worker origin the signed URL points at (e.g. `https://cdn.acme.test`). */
@@ -298,40 +298,40 @@ 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;
   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>;