@lunora/bindings 1.0.0-alpha.9 → 1.0.0-alpha.91

package/dist/artifacts/index.d.ts

@@ -0,0 +1,426 @@
+/**
+ * Structural projections of the Cloudflare **Artifacts** binding (`env.ARTIFACTS`)
+ * — a versioned file system that speaks Git. Namespaces hold repos; the binding
+ * creates, imports, forks, lists and deletes them, mints repo-scoped Git tokens,
+ * and READS commits, trees, blobs and files. It has no write method: every write
+ * is a `git push` over HTTPS with one of those tokens.
+ *
+ * Declared structurally (the `ImagesBindingLike` pattern) rather than leaning on
+ * the global `Artifacts` type, because the pinned `@cloudflare/workers-types`
+ * lags the runtime: it lacks `info()`, `log()`, `readCommit()`, `readTree()`,
+ * `readBlob()` and `readFile()`, and it models `ArtifactsRepo` as carrying its
+ * metadata as properties, which the deployed binding does not do (call
+ * `info()`). The shapes here follow the Workers-binding docs and
+ * `@cloudflare/workers-types@5.20261002.1`, the first release that matches them.
+ *
+ * TODO(workers-types): once the catalog pin includes the read methods, add a
+ * type test asserting the global `Artifacts` is assignable to
+ * {@link ArtifactsBindingLike}.
+ */
+/** A repo-scoped Git token's scope: `read` covers clone/fetch/pull, `write` adds push. */
+type ArtifactsTokenScope = "read" | "write";
+/** Current metadata for one repository, from `repo.info()`. */
+interface ArtifactsRepoInfo {
+  /** ISO 8601 creation timestamp. */
+  createdAt: string;
+  /** Default branch name, e.g. `main`. */
+  defaultBranch: string;
+  /** Repository description, or `null` when unset. */
+  description: string | null;
+  /** Unique repository id. */
+  id: string;
+  /** ISO 8601 timestamp of the last push, or `null` when never pushed. */
+  lastPushAt: string | null;
+  /** Repository name. */
+  name: string;
+  /** Whether the repository is read-only. */
+  readOnly: boolean;
+  /** The HTTPS Git remote URL. */
+  remote: string;
+  /** Fork source (`github:owner/repo`, `artifacts:namespace/repo`), or `null` when not a fork. */
+  source: string | null;
+  /** ISO 8601 last-updated timestamp. */
+  updatedAt: string;
+}
+/**
+ * The result of `create()`, `import()` and `fork()`: the new repo plus an
+ * initial Git token. `token` is a secret — never log it or return it to a client
+ * that should not push.
+ */
+interface ArtifactsCreateRepoResult {
+  /** Default branch name. */
+  defaultBranch: string;
+  /** Repository description, or `null` when unset. */
+  description: string | null;
+  /** Unique repository id. */
+  id: string;
+  /** Repository name. */
+  name: string;
+  /** The HTTPS Git remote URL. */
+  remote: string;
+  /** Plaintext initial access token, returned only at creation time. */
+  token: string;
+}
+/** One page of `list()`. */
+interface ArtifactsRepoListResult {
+  /** Cursor for the next page; absent on the last page. */
+  cursor?: string;
+  /** The repos on this page (without `remote`). */
+  repos: Omit<ArtifactsRepoInfo, "remote">[];
+  /** Total number of repos in the namespace. */
+  total: number;
+}
+/** A freshly minted Git token. `plaintext` is a secret. */
+interface ArtifactsCreateTokenResult {
+  /** ISO 8601 expiry timestamp. */
+  expiresAt: string;
+  /** Unique token id — pass it to `revokeToken` instead of the plaintext where you can. */
+  id: string;
+  /** The Git token string, returned only at creation time. */
+  plaintext: string;
+  /** The token's scope. */
+  scope: ArtifactsTokenScope;
+}
+/** Token metadata (never the plaintext). */
+interface ArtifactsTokenInfo {
+  /** ISO 8601 creation timestamp. */
+  createdAt: string;
+  /** ISO 8601 expiry timestamp. */
+  expiresAt: string;
+  /** Unique token id. */
+  id: string;
+  /** The token's scope. */
+  scope: ArtifactsTokenScope;
+  /** Whether the token can still be used. */
+  state: "active" | "expired" | "revoked";
+}
+/** The tokens minted for one repo. */
+interface ArtifactsTokenListResult {
+  /** The tokens. */
+  tokens: ArtifactsTokenInfo[];
+  /** Total number of tokens for the repo. */
+  total: number;
+}
+/** A Git tree entry's kind, derived from its mode. */
+type ArtifactsTreeEntryType = "blob" | "exec" | "gitlink" | "symlink" | "tree";
+/** An immediate child of a Git tree, from `readTree()`. */
+interface ArtifactsTreeEntry {
+  /** Lowercase, 40-character SHA-1 object id. */
+  hash: string;
+  /** Canonical Git mode, such as `100644` for a file or `40000` for a tree. */
+  mode: string;
+  /** Name relative to the tree being read. */
+  name: string;
+  /** Kind derived from `mode`. */
+  type: ArtifactsTreeEntryType;
+}
+/** A Git identity on a commit. */
+interface ArtifactsCommitIdentity {
+  email: string;
+  name: string;
+}
+/** Decoded commit metadata, from `readCommit()` and `log()`. */
+interface ArtifactsCommitMetadata {
+  /** The commit's author. */
+  author: ArtifactsCommitIdentity;
+  /** Author timestamp in Unix seconds. */
+  authoredAt: number;
+  /** Committer timestamp in Unix seconds. */
+  committedAt: number;
+  /** The commit's committer. */
+  committer: ArtifactsCommitIdentity;
+  /** Lowercase, 40-character SHA-1 commit id. */
+  hash: string;
+  /** Commit message with one trailing newline removed. */
+  message: string;
+  /** Parent commit ids in Git order; empty for a root commit. */
+  parents: string[];
+  /** SHA-1 id of the commit's root tree. */
+  treeHash: string;
+}
+/** Options for `create()`. */
+interface ArtifactsCreateOptions {
+  description?: string;
+  readOnly?: boolean;
+  /** The default branch name (the binding's `setDefaultBranch`). */
+  setDefaultBranch?: string;
+}
+/** Options for `repo.fork()`. */
+interface ArtifactsForkOptions {
+  /** Copy only the default branch. The binding defaults this to `true`. */
+  defaultBranchOnly?: boolean;
+  description?: string;
+  readOnly?: boolean;
+}
+/** Parameters for `import()`: an external HTTPS Git remote and the repo it lands in. */
+interface ArtifactsImportParams {
+  source: {
+    /** Branch to import; defaults to the remote's default branch. */
+    branch?: string;
+    /** Shallow-clone depth. */
+    depth?: number;
+    /** HTTPS URL of the source repository. */
+    url: string;
+  };
+  target: {
+    name: string;
+    opts?: {
+      description?: string;
+      readOnly?: boolean;
+    };
+  };
+}
+/** Options for `list()`. */
+interface ArtifactsListOptions {
+  cursor?: string;
+  /** Page size, 1–200 (the binding defaults to 50). */
+  limit?: number;
+}
+/** Options for `repo.log()`. */
+interface ArtifactsLogOptions {
+  /** Page size; the binding defaults to 50 and caps at 1000. */
+  limit?: number;
+  offset?: number;
+  /** Branch, tag or commit id; defaults to `HEAD`. */
+  ref?: string;
+}
+/** Arguments for `repo.readFile()`. */
+interface ArtifactsReadFileArgs {
+  /** Non-empty repository-relative path. */
+  path: string;
+  /** Branch, tag or commit id. */
+  ref: string;
+}
+/**
+ * The repo operations — the methods of the handle `binding.get(name)` returns,
+ * which `createArtifacts` wraps with the Lunora error mapping and hands to
+ * {@link ArtifactsClient.withRepo}'s callback.
+ *
+ * Declared on its own rather than derived from {@link ArtifactsRepoLike} by
+ * omitting `Symbol.dispose`: without `lib.esnext.disposable` or `@types/node`
+ * (an app on `lib: ["ES2024"]` + workers-types) `typeof Symbol.dispose` is
+ * `any`, and `Omit<…, any>` drops every member.
+ */
+interface ArtifactsRepoClient {
+  /**
+   * Mint a repo-scoped Git token. `ttl` is in seconds (60 to one year; the
+   * binding defaults to 86,400). Keep write tokens short-lived and revoke them
+   * when the session that needed them ends.
+   */
+  createToken: (scope?: ArtifactsTokenScope, ttl?: number) => Promise<ArtifactsCreateTokenResult>;
+  /** Fork this repo into a new repo in the same namespace. */
+  fork: (name: string, options?: ArtifactsForkOptions) => Promise<ArtifactsCreateRepoResult>;
+  /** Fresh repository metadata. */
+  info: () => Promise<ArtifactsRepoInfo>;
+  /** Token metadata for this repo (never plaintext). */
+  listTokens: () => Promise<ArtifactsTokenListResult>;
+  /** First-parent history, newest first. An unresolvable ref yields `[]`. */
+  log: (options?: ArtifactsLogOptions) => Promise<ArtifactsCommitMetadata[]>;
+  /** A blob's raw bytes as an untyped `Blob` (returned unbuffered), or `null` when missing. */
+  readBlob: (hash: string) => Promise<Blob | null>;
+  /** One decoded commit, or `null` when missing. */
+  readCommit: (hash: string) => Promise<ArtifactsCommitMetadata | null>;
+  /** A file at a ref as a MIME-typed `Blob` (returned unbuffered), or `null` when the path is missing or a directory. */
+  readFile: (args: ArtifactsReadFileArgs) => Promise<Blob | null>;
+  /** A tree's immediate children, or `null` when missing. */
+  readTree: (hash: string) => Promise<ArtifactsTreeEntry[] | null>;
+  /** Revoke a token by id (preferred) or plaintext. `false` when it was not found. */
+  revokeToken: (tokenOrId: string) => Promise<boolean>;
+}
+/**
+ * The repo capability `binding.get(name)` returns: an RPC stub that has to be
+ * disposed before the request ends. `Disposable` is `Partial` only so a
+ * plain-object test double satisfies the shape; the real handle always has it.
+ */
+interface ArtifactsRepoLike extends ArtifactsRepoClient, Partial<Disposable> {}
+/** The namespace-level `env.ARTIFACTS` binding. */
+interface ArtifactsBindingLike {
+  /** Create a repo. The first `create` against a missing namespace creates that namespace, unrestricted. */
+  create: (name: string, options?: ArtifactsCreateOptions) => Promise<ArtifactsCreateRepoResult>;
+  /** Delete a repo and its tokens. `false` when it did not exist. */
+  delete: (name: string) => Promise<boolean>;
+  /** Open a repo handle. It must be disposed of before the request ends — prefer `ArtifactsClient.withRepo`. */
+  get: (name: string) => Promise<ArtifactsRepoLike>;
+  /** Import a repo from an external HTTPS Git remote. */
+  import: (params: ArtifactsImportParams) => Promise<ArtifactsCreateRepoResult>;
+  /** One page of the namespace's repos. */
+  list: (options?: ArtifactsListOptions) => Promise<ArtifactsRepoListResult>;
+}
+/** The `code` an `ArtifactsError` carries. */
+type ArtifactsErrorCode = "ALREADY_EXISTS" | "CREATE_IN_PROGRESS" | "FORK_IN_PROGRESS" | "IMPORT_IN_PROGRESS" | "INTERNAL_ERROR" | "INVALID_INPUT" | "INVALID_REPO_NAME" | "INVALID_TTL" | "INVALID_URL" | "MEMORY_LIMIT" | "NOT_FOUND" | "REMOTE_AUTH_REQUIRED" | "UPSTREAM_UNAVAILABLE";
+/** The `data` a mapped `LunoraError` carries: the binding's own codes, never its message. */
+interface ArtifactsErrorData {
+  /** The binding's string code. */
+  code: string;
+  /** The binding's numeric code (matches the REST API's `errors[].code`), when it sent one. */
+  numericCode?: number;
+}
+/**
+ * The action-only `ctx.artifacts` client: the binding's namespace operations,
+ * with the raw `get` replaced by the disposing `withRepo`, plus two helpers.
+ * Every call is a billed, remote operation, and every `ArtifactsError` is
+ * rethrown as a `LunoraError` (see `createArtifacts`). It cannot write files —
+ * push with a Git client using a token from `ArtifactsRepoClient.createToken`
+ * and `authenticatedRemote`.
+ */
+type ArtifactsClient = {
+  /**
+   * Build the `https://x:<token>@host/…` remote a Git client pushes to. Pure: no
+   * I/O. With a write token the result is a push credential — never return it
+   * from a public function, log it, or put it in a command argument.
+   */
+  authenticatedRemote: (remote: string, token: string) => string;
+  /** Fresh metadata for one repo — shorthand for `withRepo(name, (repo) => repo.info())`. */
+  info: (name: string) => Promise<ArtifactsRepoInfo>;
+  /**
+   * Open a repo handle, run `callback` with it, and dispose of the handle whether
+   * `callback` returns or throws, so it cannot outlive the request. Use the
+   * handle only inside `callback`.
+   */
+  withRepo: <T>(name: string, callback: (repo: ArtifactsRepoClient) => Promise<T> | T) => Promise<T>;
+} & Omit<ArtifactsBindingLike, "get">;
+/** Options for `createArtifacts`. */
+interface LunoraArtifactsOptions {
+  /** The `env.ARTIFACTS` binding (wrangler `artifacts[]`). */
+  binding: ArtifactsBindingLike;
+}
+/**
+ * Envelope fields shared by every Artifacts Queues event (`eventSchemaVersion: 1`).
+ * @experimental
+ */
+interface ArtifactsEventMetadata {
+  accountId: string;
+  eventSchemaVersion: 1;
+  eventSubscriptionId: string;
+  eventTimestamp: string;
+}
+/** The repo-state payload the account-level lifecycle events carry. */
+interface ArtifactsRepoEventState {
+  createdAt: string;
+  defaultBranch: string;
+  description: string | null;
+  lastPushAt: string | null;
+  readOnly: boolean;
+  repoId: string;
+  updatedAt: string;
+}
+/**
+ * Envelope of an account-level event (source `artifacts`). For a fork, `source`
+ * names the repo forked FROM; the payload names the new one.
+ * @experimental
+ */
+interface ArtifactsLifecycleEnvelope {
+  metadata: ArtifactsEventMetadata;
+  source: {
+    namespace: string;
+    repoName: string;
+    type: "artifacts";
+  };
+}
+/**
+ * Envelope of a repo-level event (source `artifacts.repo`, subscribed per
+ * namespace + repo).
+ * @experimental
+ */
+interface ArtifactsActivityEnvelope {
+  metadata: ArtifactsEventMetadata;
+  source: {
+    namespace: string;
+    repoName: string;
+    type: "artifacts.repo";
+  };
+}
+/** One commit in a `cf.artifacts.repo.pushed` payload. */
+interface ArtifactsPushedCommit {
+  author: ArtifactsCommitIdentity;
+  committer: ArtifactsCommitIdentity;
+  id: string;
+  message: string;
+  messageTruncated: boolean;
+  parents: string[];
+  timestamp: string;
+}
+/**
+ * An account-level repo lifecycle event: `created`, `deleted`, `forked` or
+ * `imported`. Narrow on `type`.
+ * @experimental
+ */
+type ArtifactsRepoLifecycleEvent = (ArtifactsLifecycleEnvelope & {
+  payload: ArtifactsRepoEventState & {
+    branch: string;
+    sourceUrl: string;
+  };
+  type: "cf.artifacts.repo.imported";
+}) | (ArtifactsLifecycleEnvelope & {
+  payload: ArtifactsRepoEventState & {
+    namespace: string;
+    repoName: string;
+  };
+  type: "cf.artifacts.repo.forked";
+}) | (ArtifactsLifecycleEnvelope & {
+  payload: ArtifactsRepoEventState;
+  type: "cf.artifacts.repo.created";
+}) | (ArtifactsLifecycleEnvelope & {
+  payload: ArtifactsRepoEventState;
+  type: "cf.artifacts.repo.deleted";
+});
+/**
+ * A repo-level activity event: `pushed`, `cloned`, `fetched`,
+ * `token.created` or `token.revoked`. Narrow on `type`. Token events carry the
+ * token id, never the plaintext.
+ * @experimental
+ */
+type ArtifactsRepoActivityEvent = (ArtifactsActivityEnvelope & {
+  payload: {
+    after: string;
+    before: string;
+    commits: ArtifactsPushedCommit[];
+    commitsTruncated: boolean;
+    ref: string;
+    totalCommitsCount: number;
+  };
+  type: "cf.artifacts.repo.pushed";
+}) | (ArtifactsActivityEnvelope & {
+  payload: {
+    expiresAt: string;
+    scope: ArtifactsTokenScope;
+    tokenId: string;
+  };
+  type: "cf.artifacts.repo.token.created";
+}) | (ArtifactsActivityEnvelope & {
+  payload: {
+    tokenId: string;
+  };
+  type: "cf.artifacts.repo.token.revoked";
+}) | (ArtifactsActivityEnvelope & {
+  payload: Record<string, never>;
+  type: "cf.artifacts.repo.cloned";
+}) | (ArtifactsActivityEnvelope & {
+  payload: Record<string, never>;
+  type: "cf.artifacts.repo.fetched";
+});
+/**
+ * Any Artifacts event a Queue subscription delivers — type a `defineQueue`
+ * consumer's messages with it and narrow on `type`.
+ * @experimental
+ */
+type ArtifactsEvent = ArtifactsRepoActivityEvent | ArtifactsRepoLifecycleEvent;
+/**
+ * Build the action-only {@link ArtifactsClient} over an Artifacts binding.
+ *
+ * ```ts
+ * const artifacts = createArtifacts({ binding: env.ARTIFACTS });
+ * const readme = await artifacts.withRepo("docs", (repo) => repo.readFile({ ref: "main", path: "README.md" }));
+ * ```
+ */
+declare const createArtifacts: (options: LunoraArtifactsOptions) => ArtifactsClient;
+/**
+ * Build `https://x:<secret>@host/…` from a repo `remote` and a Git token.
+ *
+ * A token can carry an `?expires=…` suffix; that is not part of the secret Git
+ * sends, so it is stripped first. The result embeds the secret — hand it to a
+ * Git client through an environment variable and keep it out of logs, command
+ * arguments and error messages. Errors raised here never quote the token.
+ */
+declare const authenticatedRemote: (remote: string, token: string) => string;
+export { type ArtifactsActivityEnvelope, type ArtifactsBindingLike, type ArtifactsClient, type ArtifactsCommitIdentity, type ArtifactsCommitMetadata, type ArtifactsCreateOptions, type ArtifactsCreateRepoResult, type ArtifactsCreateTokenResult, type ArtifactsErrorCode, type ArtifactsErrorData, type ArtifactsEvent, type ArtifactsEventMetadata, type ArtifactsForkOptions, type ArtifactsImportParams, type ArtifactsLifecycleEnvelope, type ArtifactsListOptions, type ArtifactsLogOptions, type ArtifactsPushedCommit, type ArtifactsReadFileArgs, type ArtifactsRepoActivityEvent, type ArtifactsRepoClient, type ArtifactsRepoEventState, type ArtifactsRepoInfo, type ArtifactsRepoLifecycleEvent, type ArtifactsRepoLike, type ArtifactsRepoListResult, type ArtifactsTokenInfo, type ArtifactsTokenListResult, type ArtifactsTokenScope, type ArtifactsTreeEntry, type ArtifactsTreeEntryType, type LunoraArtifactsOptions, authenticatedRemote, createArtifacts };

package/dist/artifacts/index.mjs

@@ -0,0 +1 @@
+import{createArtifacts as r}from"../packem_shared/createArtifacts-cXCusYbi.mjs";import{authenticatedRemote as a}from"../packem_shared/authenticatedRemote-CPm87dLq.mjs";export{a as authenticatedRemote,r as createArtifacts};

package/dist/images/index.d.mts

@@ -8,12 +8,11 @@
  * (`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.
+ * TODO(workers-types): the `aspect-crop` fit mode is modeled here by hand because
+ * `@cloudflare/workers-types` still does not type it — checked at the pinned
+ * 5.20260811.1, whose `ImageTransform` now carries `fit: "scale-up"` and `upscale`.
+ * Re-check on the next bump: once `ImageTransform` also carries
+ * `fit: "aspect-crop"`, drop our hand-rolled addition and lean on the upstream type.
  */
 /**
  * Porter-Duff compositing operation controlling how an overlay is blended onto
@@ -27,37 +26,6 @@
  * - `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
@@ -73,13 +41,6 @@ interface TransformOptions {
   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.
    *
@@ -157,9 +118,9 @@ type ImageInfoLike = {
 };
 /**
  * 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`.
+ * 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. */
@@ -266,7 +227,7 @@ interface ImageDeliveryUrlOptions {
   baseUrl: string;
   /**
    * Hosted-Images image id. When set, the **delivery-variant** form is built
-   * (`<baseUrl>/<imageId>/<variant>`) and `transform`/`key` are ignored.
+   * (`<baseUrl>/<imageId>/<variant>`) and `transform`/`key` are ignored.
    */
   imageId?: string;
   /**
@@ -274,7 +235,7 @@ interface ImageDeliveryUrlOptions {
    * `/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;
@@ -282,12 +243,27 @@ interface ImageDeliveryUrlOptions {
 /**
  * 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).
+ * - 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;
@@ -324,6 +300,15 @@ interface VerifyImageResult {
   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;
 }
 /**
@@ -335,4 +320,4 @@ interface VerifyImageResult {
 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 };