@lunora/bindings 0.0.0 → 1.0.0-alpha.2

package/dist/analytics/index.d.mts

@@ -0,0 +1,148 @@
+/**
+* Structural types for the Analytics Engine write path.
+*
+* The real binding is workers-types' `AnalyticsEngineDataset`. We mirror it
+* **structurally** (`AnalyticsEngineDatasetLike`) so plain-object test doubles
+* satisfy the contract without pulling workerd into a unit test — the same
+* approach `@lunora/d1` takes with `D1DatabaseLike`
+* (`packages/d1/src/d1-client.ts`).
+*/
+/**
+* One Analytics Engine data point, mirroring the positional shape
+* `writeDataPoint` accepts. AE stores up to 20 string `blobs`, up to 20 numeric
+* `doubles`, and exactly **one** `index` (the high-cardinality sampling key) per
+* data point — the SQL API later exposes them as `blob1..blob20`,
+* `double1..double20`, and `index1`.
+*/
+interface AnalyticsEngineDataPoint {
+  /** String columns, mapped positionally to `blob1..blob20`. */
+  blobs?: (ArrayBuffer | null | string)[];
+  /** Numeric columns, mapped positionally to `double1..double20`. */
+  doubles?: number[];
+  /** Sampling key, exposed as `index1`. AE accepts at most one. */
+  indexes?: (ArrayBuffer | string)[];
+}
+/**
+* Minimal structural projection of workers-types' `AnalyticsEngineDataset`,
+* kept loose enough for a plain-object fake in unit tests. `writeDataPoint` is
+* fire-and-forget: it returns `void` and never throws on the hot path.
+*/
+interface AnalyticsEngineDatasetLike {
+  writeDataPoint: (event: AnalyticsEngineDataPoint) => void;
+}
+/**
+* Named-field event handed to {@link AnalyticsClient.track}. Each field is
+* mapped to a positional AE column and the mapping recorded in a returned
+* {@link TrackSchema}, so the read side can reconstruct named columns from the
+* SQL API's positional `blobN`/`doubleN`/`index1` output.
+*/
+interface TrackEvent {
+  /** String dimensions → `blobs` (`blob1..blob20`), in object key order. */
+  dimensions?: Record<string, string>;
+  /** Single high-cardinality sampling key → `index1`. */
+  index?: string;
+  /** Numeric metrics → `doubles` (`double1..double20`), in object key order. */
+  metrics?: Record<string, number>;
+}
+/** One named field's position in the AE positional layout. */
+interface TrackColumn {
+  /** Positional AE column it maps to (`blob3`, `double1`, `index1`). */
+  column: string;
+  /** Field name from the {@link TrackEvent}. */
+  field: string;
+}
+/**
+* The field→column mapping {@link AnalyticsClient.track} records for one event
+* shape, so the read side can project the SQL API's positional columns back to
+* named fields. `name` is the logical event name; the column arrays are in the
+* same order the dimensions/metrics were written.
+*/
+interface TrackSchema {
+  dimensions: TrackColumn[];
+  index: TrackColumn | null;
+  metrics: TrackColumn[];
+  name: string;
+}
+/**
+* The write-side client bound to `ctx.analytics` (the generated context imports
+* this exact type as `import("@lunora/bindings/analytics").AnalyticsClient`). Telemetry
+* is fire-and-forget and sampled — never read a data point back in-handler.
+*/
+interface AnalyticsClient {
+  /**
+  * Ergonomic named-field write: maps `{ dimensions, metrics, index }` to the
+  * positional layout, writes it, and returns the {@link TrackSchema} mapping
+  * (the logical `name` is recorded as the first blob, `blob1`).
+  */
+  track: (name: string, event?: TrackEvent) => TrackSchema;
+  /**
+  * Write a raw positional data point. Enforces AE's per-data-point count
+  * caps (≤20 blobs, ≤20 doubles, ≤1 index) and byte budget (combined blobs
+  * ≤16 KiB, index ≤96 bytes, measured as UTF-8); overflow throws so a misuse
+  * surfaces in dev rather than being silently rejected by the platform.
+  */
+  writeDataPoint: (event: AnalyticsEngineDataPoint) => void;
+}
+/**
+* Wrap an Analytics Engine dataset binding in the write-side
+* {@link AnalyticsClient} bound to `ctx.analytics`.
+*
+* The binding is `env.ANALYTICS` (the self-describing
+* `analytics_engine_datasets` binding the config layer reconciles). Writes are
+* fire-and-forget and sampled — there is no return value to read in-handler.
+*
+* `writeDataPoint` enforces AE's per-data-point caps eagerly — both the count
+* caps (≤20 blobs, ≤20 doubles, ≤1 index) and the byte budget (combined blobs
+* ≤16 KiB, index ≤96 bytes, measured as UTF-8) — so a misuse throws in dev
+* instead of being silently rejected by the platform at the edge. `track` is
+* the ergonomic named-field path: it maps a
+* `{ dimensions, metrics, index }` object to the positional layout and returns
+* the field→column mapping the read side uses to reconstruct named columns.
+*/
+declare const createAnalytics: (binding: AnalyticsEngineDatasetLike) => AnalyticsClient;
+/** Configuration for an {@link AnalyticsSqlClient}. */
+interface AnalyticsSqlConfig {
+  /** Cloudflare account id that owns the dataset. */
+  accountId: string;
+  /** API token with Analytics Engine read scope. A secret — never a binding. */
+  apiToken: string;
+  /**
+  * `fetch` implementation. Defaults to the global `fetch`; injected in tests
+  * so the SQL path never touches the network.
+  */
+  fetch?: typeof globalThis.fetch;
+}
+/**
+* One column descriptor in a SQL-API response's `meta` array: the column `name`
+* and the AE storage `type` (`String`, `Float64`, `DateTime`, …).
+*/
+interface AnalyticsSqlColumnMeta {
+  name: string;
+  type: string;
+}
+/**
+* Parsed SQL-API result. AE returns `{ meta, data, rows, rows_before_limit_at_least }`;
+* we surface `columns` (from `meta`), the `rows` array of column→value records,
+* and the total `rowCount`.
+*/
+interface AnalyticsSqlResult {
+  columns: AnalyticsSqlColumnMeta[];
+  rowCount: number;
+  rows: Record<string, unknown>[];
+}
+/** Thrown when the SQL API responds with a non-2xx status; carries the status + body for the caller to surface. */
+declare class AnalyticsSqlError extends Error {
+  readonly status: number;
+  constructor(status: number, body: string);
+}
+/** The read client: a single `query(sql)` over the AE SQL API. */
+interface AnalyticsSqlClient {
+  query: (sql: string) => Promise<AnalyticsSqlResult>;
+}
+/**
+* Build an {@link AnalyticsSqlClient}. Each `query` POSTs the raw SQL text to
+* the account's `analytics_engine/sql` endpoint with the bearer token, then
+* normalises AE's `{ meta, data, rows }` body into {@link AnalyticsSqlResult}.
+*/
+declare const createAnalyticsSqlClient: (config: AnalyticsSqlConfig) => AnalyticsSqlClient;
+export { type AnalyticsClient, type AnalyticsEngineDataPoint, type AnalyticsEngineDatasetLike, type AnalyticsSqlClient, type AnalyticsSqlColumnMeta, type AnalyticsSqlConfig, AnalyticsSqlError, type AnalyticsSqlResult, type TrackColumn, type TrackEvent, type TrackSchema, createAnalytics, createAnalyticsSqlClient };

package/dist/analytics/index.d.ts

@@ -0,0 +1,148 @@
+/**
+* Structural types for the Analytics Engine write path.
+*
+* The real binding is workers-types' `AnalyticsEngineDataset`. We mirror it
+* **structurally** (`AnalyticsEngineDatasetLike`) so plain-object test doubles
+* satisfy the contract without pulling workerd into a unit test — the same
+* approach `@lunora/d1` takes with `D1DatabaseLike`
+* (`packages/d1/src/d1-client.ts`).
+*/
+/**
+* One Analytics Engine data point, mirroring the positional shape
+* `writeDataPoint` accepts. AE stores up to 20 string `blobs`, up to 20 numeric
+* `doubles`, and exactly **one** `index` (the high-cardinality sampling key) per
+* data point — the SQL API later exposes them as `blob1..blob20`,
+* `double1..double20`, and `index1`.
+*/
+interface AnalyticsEngineDataPoint {
+  /** String columns, mapped positionally to `blob1..blob20`. */
+  blobs?: (ArrayBuffer | null | string)[];
+  /** Numeric columns, mapped positionally to `double1..double20`. */
+  doubles?: number[];
+  /** Sampling key, exposed as `index1`. AE accepts at most one. */
+  indexes?: (ArrayBuffer | string)[];
+}
+/**
+* Minimal structural projection of workers-types' `AnalyticsEngineDataset`,
+* kept loose enough for a plain-object fake in unit tests. `writeDataPoint` is
+* fire-and-forget: it returns `void` and never throws on the hot path.
+*/
+interface AnalyticsEngineDatasetLike {
+  writeDataPoint: (event: AnalyticsEngineDataPoint) => void;
+}
+/**
+* Named-field event handed to {@link AnalyticsClient.track}. Each field is
+* mapped to a positional AE column and the mapping recorded in a returned
+* {@link TrackSchema}, so the read side can reconstruct named columns from the
+* SQL API's positional `blobN`/`doubleN`/`index1` output.
+*/
+interface TrackEvent {
+  /** String dimensions → `blobs` (`blob1..blob20`), in object key order. */
+  dimensions?: Record<string, string>;
+  /** Single high-cardinality sampling key → `index1`. */
+  index?: string;
+  /** Numeric metrics → `doubles` (`double1..double20`), in object key order. */
+  metrics?: Record<string, number>;
+}
+/** One named field's position in the AE positional layout. */
+interface TrackColumn {
+  /** Positional AE column it maps to (`blob3`, `double1`, `index1`). */
+  column: string;
+  /** Field name from the {@link TrackEvent}. */
+  field: string;
+}
+/**
+* The field→column mapping {@link AnalyticsClient.track} records for one event
+* shape, so the read side can project the SQL API's positional columns back to
+* named fields. `name` is the logical event name; the column arrays are in the
+* same order the dimensions/metrics were written.
+*/
+interface TrackSchema {
+  dimensions: TrackColumn[];
+  index: TrackColumn | null;
+  metrics: TrackColumn[];
+  name: string;
+}
+/**
+* The write-side client bound to `ctx.analytics` (the generated context imports
+* this exact type as `import("@lunora/bindings/analytics").AnalyticsClient`). Telemetry
+* is fire-and-forget and sampled — never read a data point back in-handler.
+*/
+interface AnalyticsClient {
+  /**
+  * Ergonomic named-field write: maps `{ dimensions, metrics, index }` to the
+  * positional layout, writes it, and returns the {@link TrackSchema} mapping
+  * (the logical `name` is recorded as the first blob, `blob1`).
+  */
+  track: (name: string, event?: TrackEvent) => TrackSchema;
+  /**
+  * Write a raw positional data point. Enforces AE's per-data-point count
+  * caps (≤20 blobs, ≤20 doubles, ≤1 index) and byte budget (combined blobs
+  * ≤16 KiB, index ≤96 bytes, measured as UTF-8); overflow throws so a misuse
+  * surfaces in dev rather than being silently rejected by the platform.
+  */
+  writeDataPoint: (event: AnalyticsEngineDataPoint) => void;
+}
+/**
+* Wrap an Analytics Engine dataset binding in the write-side
+* {@link AnalyticsClient} bound to `ctx.analytics`.
+*
+* The binding is `env.ANALYTICS` (the self-describing
+* `analytics_engine_datasets` binding the config layer reconciles). Writes are
+* fire-and-forget and sampled — there is no return value to read in-handler.
+*
+* `writeDataPoint` enforces AE's per-data-point caps eagerly — both the count
+* caps (≤20 blobs, ≤20 doubles, ≤1 index) and the byte budget (combined blobs
+* ≤16 KiB, index ≤96 bytes, measured as UTF-8) — so a misuse throws in dev
+* instead of being silently rejected by the platform at the edge. `track` is
+* the ergonomic named-field path: it maps a
+* `{ dimensions, metrics, index }` object to the positional layout and returns
+* the field→column mapping the read side uses to reconstruct named columns.
+*/
+declare const createAnalytics: (binding: AnalyticsEngineDatasetLike) => AnalyticsClient;
+/** Configuration for an {@link AnalyticsSqlClient}. */
+interface AnalyticsSqlConfig {
+  /** Cloudflare account id that owns the dataset. */
+  accountId: string;
+  /** API token with Analytics Engine read scope. A secret — never a binding. */
+  apiToken: string;
+  /**
+  * `fetch` implementation. Defaults to the global `fetch`; injected in tests
+  * so the SQL path never touches the network.
+  */
+  fetch?: typeof globalThis.fetch;
+}
+/**
+* One column descriptor in a SQL-API response's `meta` array: the column `name`
+* and the AE storage `type` (`String`, `Float64`, `DateTime`, …).
+*/
+interface AnalyticsSqlColumnMeta {
+  name: string;
+  type: string;
+}
+/**
+* Parsed SQL-API result. AE returns `{ meta, data, rows, rows_before_limit_at_least }`;
+* we surface `columns` (from `meta`), the `rows` array of column→value records,
+* and the total `rowCount`.
+*/
+interface AnalyticsSqlResult {
+  columns: AnalyticsSqlColumnMeta[];
+  rowCount: number;
+  rows: Record<string, unknown>[];
+}
+/** Thrown when the SQL API responds with a non-2xx status; carries the status + body for the caller to surface. */
+declare class AnalyticsSqlError extends Error {
+  readonly status: number;
+  constructor(status: number, body: string);
+}
+/** The read client: a single `query(sql)` over the AE SQL API. */
+interface AnalyticsSqlClient {
+  query: (sql: string) => Promise<AnalyticsSqlResult>;
+}
+/**
+* Build an {@link AnalyticsSqlClient}. Each `query` POSTs the raw SQL text to
+* the account's `analytics_engine/sql` endpoint with the bearer token, then
+* normalises AE's `{ meta, data, rows }` body into {@link AnalyticsSqlResult}.
+*/
+declare const createAnalyticsSqlClient: (config: AnalyticsSqlConfig) => AnalyticsSqlClient;
+export { type AnalyticsClient, type AnalyticsEngineDataPoint, type AnalyticsEngineDatasetLike, type AnalyticsSqlClient, type AnalyticsSqlColumnMeta, type AnalyticsSqlConfig, AnalyticsSqlError, type AnalyticsSqlResult, type TrackColumn, type TrackEvent, type TrackSchema, createAnalytics, createAnalyticsSqlClient };

package/dist/analytics/index.mjs

@@ -0,0 +1,2 @@
+export { createAnalytics } from '../packem_shared/createAnalytics-CEEI69o9.mjs';
+export { AnalyticsSqlError, createAnalyticsSqlClient } from '../packem_shared/AnalyticsSqlError-CGTdsi4H.mjs';

package/dist/images/index.d.mts

@@ -0,0 +1,338 @@
+/**
+* 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).
+*/
+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.
+*/
+interface TransformOptions {
+  /** Background color (CSS color) painted under transparent images. */
+  background?: string;
+  /** Gaussian blur radius (1–250). */
+  blur?: number;
+  /** Brightness multiplier (1 = unchanged). */
+  brightness?: number;
+  /** 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.
+  */
+  fit?: "aspect-crop" | "contain" | "cover" | "crop" | "pad" | "scale-down" | "scale-up" | "squeeze";
+  /** Mirror the image horizontally, vertically, or both. */
+  flip?: "h" | "hv" | "v";
+  /** Gamma multiplier (1 = unchanged). */
+  gamma?: number;
+  /** Crop anchor when `fit: "cover"`/`"crop"`. */
+  gravity?: "auto" | "bottom" | "center" | "entropy" | "face" | "left" | "right" | "top" | {
+    mode: "box-center" | "remainder";
+    x?: number;
+    y?: number;
+  };
+  /** Target height in pixels (integer). Clamped to the configured ceiling. */
+  height?: number;
+  /** Rotate by a fixed multiple of 90 degrees. `width`/`height` refer to axes after rotation. */
+  rotate?: 0 | 90 | 180 | 270;
+  /** Saturation multiplier (0 = greyscale, 1 = unchanged). */
+  saturation?: number;
+  /** AI segmentation — set non-`foreground` pixels transparent. */
+  segment?: "foreground";
+  /** 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.
+  */
+  upscale?: "generate" | "interpolate";
+  /** Target width in pixels (integer). Clamped to the configured ceiling. */
+  width?: number;
+}
+/** The output image formats Lunora permits (the binding allowlist plus `json` info). */
+type ImageOutputFormat = "image/avif" | "image/gif" | "image/jpeg" | "image/png" | "image/webp";
+/** Options for the terminal `output(...)` call. */
+interface OutputOptions {
+  /** Encode animated source frames into the output (WebP/GIF/AVIF). */
+  anim?: boolean;
+  /** Background color (CSS color) for formats without an alpha channel. */
+  background?: string;
+  /** Output MIME type. Validated against {@link ImageOutputFormat}. Default `image/webp`. */
+  format?: ImageOutputFormat;
+  /** Encoder quality 1–100 (lossy formats). */
+  quality?: number;
+}
+/**
+* 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>;
+  response: () => Response;
+}
+/** Metadata returned by `binding.info(...)` — format, and (for raster images) dimensions + size. */
+type ImageInfoLike = {
+  fileSize: number;
+  format: string;
+  height: number;
+  width: number;
+} | {
+  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`.
+*/
+interface ImageDrawOptions {
+  /** Offset, in pixels, from the bottom edge. */
+  bottom?: number;
+  /** Blend mode for compositing this overlay onto the image. Default `over`. */
+  composite?: ImageCompositeMode;
+  /** 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;
+}
+/**
+* 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;
+  /** Optional transform applied to the overlay before compositing (e.g. resize). */
+  transform?: TransformOptions;
+}
+/** One link in the transform chain: apply more transforms, draw an overlay, or finalize with `output`. */
+interface ImageTransformerLike {
+  draw: (image: ImageTransformerLike | ReadableStream<Uint8Array>, options?: ImageDrawOptions) => ImageTransformerLike;
+  output: (options: OutputOptions) => Promise<ImageTransformationResultLike>;
+  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.
+*/
+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.
+*/
+interface R2ObjectBodyLike {
+  body: ReadableStream | null;
+}
+/** Anything `transform`/`info` accept as input bytes. R2 bodies are unwrapped to their stream. */
+type ImageInput = ArrayBuffer | Blob | R2ObjectBodyLike | ReadableStream | Uint8Array;
+interface LunoraImagesOptions {
+  /** The Cloudflare Images binding (`env.IMAGES`). */
+  binding: ImagesBindingLike;
+  /** Maximum pixel value any single `width`/`height` may request. Default 10000. */
+  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.
+*/
+interface Images {
+  /**
+  * 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.
+  */
+  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 },
+* );
+* ```
+*/
+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.
+  */
+  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.
+  */
+  key?: string;
+  /** Transform options for the `/cdn-cgi/image/&lt;options>/&lt;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.
+*/
+declare const buildImageDeliveryUrl: (options: ImageDeliveryUrlOptions) => string;
+interface SignedImageUrlOptions {
+  /** Delivery / Worker origin the signed URL points at (e.g. `https://cdn.acme.test`). */
+  baseUrl: string;
+  /** Seconds the URL stays valid. Default 3600; capped at 7 days. */
+  expiresInSeconds?: number;
+  /** Image key/id resolved by the Worker route (the pathname). */
+  key: string;
+  /** 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?: 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.
+*/
+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`.
+  */
+  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.
+*/
+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 };