void 0.10.13 → 0.20.1

package/dist/inbound-afAcWeQ9.d.mts

@@ -0,0 +1,363 @@
+import { Email } from "postal-mime";
+//#region src/runtime/email/types.d.ts
+/**
+ * Public types for the void/email module.
+ *
+ * The runtime entrypoint (../email.ts) re-exports these so that consumers
+ * can import them via `import type { SendEmailOptions } from "void/email"`.
+ */
+type Address = string | {
+  email: string;
+  name?: string;
+};
+interface Attachment {
+  filename: string;
+  content: string | Uint8Array | ArrayBuffer | Blob;
+  contentType?: string;
+  contentId?: string;
+  disposition?: "attachment" | "inline";
+}
+interface SendEmailOptions {
+  /**
+   * Sender envelope address. Optional — when omitted, the framework
+   * substitutes `<__VOID_PROJECT_SLUG>+noreply@<__VOID_EMAIL_DOMAIN>`
+   * from the two platform-injected bindings (the project slug and the
+   * mail domain configured for this environment). Outside a deployed
+   * worker, or whenever either binding is missing, `sendEmail` returns
+   * `INVALID_FROM` — it never falls back to a baked-in domain.
+   */
+  from?: Address;
+  to: Address | Array<Address>;
+  subject: string;
+  text?: string;
+  html?: string;
+  replyTo?: Address;
+  cc?: Address | Array<Address>;
+  bcc?: Address | Array<Address>;
+  headers?: Record<string, string>;
+  attachments?: Array<Attachment>;
+  /**
+   * Per-call escape hatch for local development. When true, bypasses the
+   * `void dev` in-memory inbox for this one send.
+   *
+   * It does not deliver. `void dev` binds no send transport at all: the
+   * platform's `__VOID_PROXY` service binding is added only on a deployed
+   * worker, and the own-account `SEND_EMAIL` binding is stripped under
+   * `serve`. With the inbox skipped there is nothing to fall through to,
+   * so the call returns `BINDING_MISSING`. To verify real delivery, deploy
+   * and send from the deployed worker.
+   *
+   * Has no effect outside `void dev` (production always sends; the dev
+   * inbox is registered only when `void dev` is running).
+   */
+  sendInDev?: boolean;
+}
+type SendEmailErrorCode = "BINDING_MISSING" | "INVALID_FROM" | "INVALID_TO" | "UNVERIFIED_DESTINATION" | "MIME_ERROR" | "QUOTA_EXCEEDED" | "UPSTREAM_ERROR";
+interface SendEmailError {
+  code: SendEmailErrorCode;
+  message: string;
+  cause?: unknown;
+}
+/**
+ * One successful CF envelope send. The `to`/`cc`/`bcc` fan-out produces one
+ * of these per recipient, since the CF `EmailMessage` envelope is
+ * single-recipient.
+ */
+interface SendEmailDelivery {
+  recipient: string;
+  messageId: string;
+}
+/**
+ * Per-recipient outcome for a multi-recipient send. `ok: true` carries the
+ * CF-issued messageId; `ok: false` carries the error for that specific
+ * recipient (e.g. one address is unverified while others succeed).
+ */
+type SendEmailRecipientResult = {
+  recipient: string;
+  ok: true;
+  messageId: string;
+} | {
+  recipient: string;
+  ok: false;
+  error: SendEmailError;
+};
+/**
+ * Result of `sendEmail`.
+ *
+ * Three discriminated cases — narrow with `result.ok`, then check whether
+ * `'error' in result` (pre-flight failure, no sends attempted) or
+ * `'deliveries' in result` (per-recipient failure, some may have succeeded):
+ *
+ * - `{ ok: true, ids }`            — every envelope succeeded.
+ * - `{ ok: false, error }`         — pre-flight failure (validation, MIME,
+ *                                     missing binding); no envelopes attempted.
+ * - `{ ok: false, deliveries }`    — sends were attempted; at least one failed.
+ *                                     `deliveries` carries the per-recipient
+ *                                     outcome so callers can safely retry only
+ *                                     the failed ones. There is no aggregate
+ *                                     top-level error — distinct recipients can
+ *                                     fail with distinct errors, and picking one
+ *                                     would be arbitrary.
+ */
+type SendEmailResult = {
+  ok: true;
+  ids: Array<SendEmailDelivery>;
+} | {
+  ok: false;
+  error: SendEmailError;
+} | {
+  ok: false;
+  deliveries: Array<SendEmailRecipientResult>;
+};
+/**
+ * Normalized representation produced by validation, consumed by both the
+ * MIME builder and the dev inbox.
+ */
+interface NormalizedEmail {
+  from: {
+    email: string;
+    name?: string;
+  };
+  to: Array<{
+    email: string;
+    name?: string;
+  }>;
+  cc: Array<{
+    email: string;
+    name?: string;
+  }>;
+  bcc: Array<{
+    email: string;
+    name?: string;
+  }>;
+  replyTo?: {
+    email: string;
+    name?: string;
+  };
+  subject: string;
+  text?: string;
+  html?: string;
+  headers: Record<string, string>;
+  attachments: Array<NormalizedAttachment>;
+  /**
+   * Internal-only threading headers, set by `replyEmail`/`buildReplyMessage`.
+   * The MIME builder emits these as proper `In-Reply-To` / `References`
+   * top-level headers. User-supplied `headers` with these names are
+   * always dropped (they're in `RESERVED_HEADERS`); this field is the
+   * supported channel for the trusted reply path.
+   */
+  threading?: {
+    inReplyTo?: string;
+    references?: string;
+  };
+}
+interface NormalizedAttachment {
+  filename: string;
+  contentType: string;
+  bytes: Uint8Array;
+  contentId?: string;
+  disposition: "attachment" | "inline";
+}
+//#endregion
+//#region src/runtime/email/inbound.d.ts
+interface EmailHandlerInfo {
+  /**
+   * Captured params from dynamic / tagged route segments. For example, a
+   * handler at `email/support+[ticket].ts` invoked for `support+abc-123@…`
+   * receives `{ ticket: "abc-123" }`. Empty `{}` for static handlers and
+   * `_default`.
+   */
+  params: Record<string, string>;
+}
+type EmailHandler = (message: ForwardableEmailMessage, env: unknown, ctx: ExecutionContext, info?: EmailHandlerInfo) => void | Promise<void>;
+/**
+ * Identity helper that types the inbound email handler. Use as the default
+ * export of `email/<address>.ts` or `email/_default.ts`.
+ */
+declare function defineEmail(handler: EmailHandler): EmailHandler;
+type ParsedEmail = Email;
+type ParseEmailErrorCode = "INBOUND_TOO_LARGE" | "PARSE_FAILED";
+/**
+ * Typed error thrown by `parseEmail`. Lets handler authors distinguish
+ * "too big" from "malformed body" without string-matching error messages.
+ */
+declare class ParseEmailError extends Error {
+  readonly code: ParseEmailErrorCode;
+  constructor(code: ParseEmailErrorCode, message: string, options?: {
+    cause?: unknown;
+  });
+}
+/**
+ * Parse a `ForwardableEmailMessage` into structured fields. postal-mime is
+ * loaded lazily so workers that never call this don't bundle it.
+ *
+ * For proxy messages (built via `createMessageProxy`) the raw bytes are
+ * cached on first read so subsequent `parseEmail`/`message.raw` accesses
+ * still work. For real CF `ForwardableEmailMessage`s the raw stream is
+ * one-shot.
+ */
+declare function parseEmail(message: ForwardableEmailMessage): Promise<ParsedEmail>;
+/**
+ * Serialized inbound email message — sent from the platform router to the
+ * user worker over RPC. Every field is in workerd's RPC `BaseType`
+ * allowlist (string, plain object, ReadableStream<Uint8Array>, number).
+ */
+interface EmailEnvelope {
+  from: string;
+  to: string;
+  /** Headers serialized as a plain object so they cross RPC. */
+  headers: Record<string, string>;
+  /**
+   * Raw RFC 5322 bytes. Pre-buffered by the router so it's replayable on the
+   * receiving side (`parseEmail` consumes the stream once; if the handler
+   * also calls `parseEmail` directly, the platform tee'd a fresh stream per
+   * delivery).
+   */
+  raw: ReadableStream<Uint8Array> | Uint8Array;
+  rawSize: number;
+  /**
+   * The registered custom domain this message arrived on, set only by the
+   * platform's relay lane (`POST /email/relay` — design doc 0078, "Custom
+   * domains on Cloudflare"). Undefined on the platform mail zone. A relayed
+   * recipient carries no `<slug>+` prefix, so the generated dispatcher runs
+   * in no-prefix mode for it (Mode B item 4) and `replyEmail` defaults
+   * `from` to the address that received it, on this domain.
+   */
+  viaDomain?: string;
+}
+/**
+ * What the user handler decided to do with a message. Returned from the
+ * worker's `email(envelope)` RPC method as an array (handlers may chain
+ * multiple actions, e.g. forward then reply); the router enacts each on the
+ * real `ForwardableEmailMessage` in order.
+ */
+type EmailAction = {
+  type: "reject";
+  reason: string;
+} | {
+  type: "forward";
+  to: string;
+  headers?: Record<string, string>;
+} | {
+  type: "reply";
+  from: string;
+  to: string;
+  raw: Uint8Array;
+};
+interface MessageProxy {
+  message: ForwardableEmailMessage;
+  getActions(): Array<EmailAction>;
+}
+interface CreateMessageProxyOptions {
+  /**
+   * Project slug stripped from the `<slug>+<tag>` recipient by the
+   * dispatcher. When set, `message.to` is rewritten to the bare
+   * `<tag>@<domain>` form so user handlers see clean addresses (the slug
+   * is platform-internal). The original `<slug>+<tag>@<domain>` is
+   * preserved on a non-enumerable `__voidPlatformTo` property for
+   * diagnostics.
+   */
+  slug?: string;
+}
+/**
+ * Build a proxy `ForwardableEmailMessage` from an envelope. The proxy's
+ * `setReject` / `forward` / `reply` methods don't dispatch directly — they
+ * record `EmailAction` entries that the router (which holds the real
+ * message) enacts after the handler returns.
+ *
+ * `reply()` accepts a duck-typed `{ from, to, raw }` with `raw` a
+ * `Uint8Array` or `ReadableStream` — what `replyEmail()` passes. It does NOT
+ * accept a native `EmailMessage` from `cloudflare:email`: that class exposes
+ * only `from` and `to` (workers-types declares nothing else, and the body
+ * has no public accessor), so its bytes cannot be recorded here, and nothing
+ * could carry them over RPC to the platform router. The reply MIME bytes are
+ * buffered before being recorded so the action is fully self-contained.
+ *
+ * When `opts.slug` is provided, `message.to` is rewritten to remove the
+ * platform-injected `<slug>+` prefix so handlers see `<tag>@<domain>`
+ * instead of `<slug>+<tag>@<domain>`. The original wire-form recipient is
+ * preserved on a non-enumerable `__voidPlatformTo` property.
+ */
+declare function createMessageProxy(envelope: EmailEnvelope, opts?: CreateMessageProxyOptions): MessageProxy;
+interface ReplyEmailOptions {
+  /**
+   * On the managed platform (a `__VOID_PROJECT_SLUG` is injected) defaults
+   * to `<__VOID_PROJECT_SLUG>+noreply@<__VOID_EMAIL_DOMAIN>`, and THROWS
+   * when the domain binding is absent — a reply sender is never guessed.
+   *
+   * There, an override must stay on your own slug. The platform accepts a
+   * reply sender whose local-part before the first `+` equals the slug the
+   * message was delivered to; anything else is dropped silently. In
+   * particular `message.to` is the STRIPPED address (`<tag>@<domain>`), so
+   * passing it here is exactly the shape the platform rejects.
+   *
+   * Without a slug (your own Cloudflare account, local harnesses) the
+   * default is the address the message was delivered to, `message.to` —
+   * a real address on your own zone.
+   */
+  from?: Address;
+  /**
+   * Defaults to the original `message.from` envelope address. A reply is a
+   * single-recipient message — for fan-out, build a fresh `sendEmail()` call.
+   */
+  to?: Address;
+  /**
+   * Defaults to `Re: <original-subject>` (no double-prefix). The original is
+   * remote-sender controlled, so the default is best-effort: control
+   * characters become a space, and a subject over 4096 characters, or an
+   * ASCII one too long to fold, falls back to a bare `Re:`. Pass `subject`
+   * to control it exactly.
+   */
+  subject?: string;
+  text?: string;
+  html?: string;
+  /**
+   * Custom headers; threading headers (`In-Reply-To`, `References`) are
+   * added automatically, best-effort: an inbound id too long for a header
+   * line is dropped, and a `References` chain over 8 KiB keeps only its
+   * newest ids.
+   */
+  headers?: Record<string, string>;
+  attachments?: Array<Attachment>;
+}
+/**
+ * Send a threading-aware reply to an inbound message. Builds the reply MIME
+ * (correct `In-Reply-To` / `References` / `Subject: Re: …`) and records a
+ * reply intent on the message proxy. The platform router enacts the reply
+ * via the real `ForwardableEmailMessage.reply()` once the handler returns.
+ *
+ * The threading headers are best-effort, since the inbound values they are
+ * built from are remote-sender controlled: an id no header line can carry
+ * is dropped, and a `References` chain over 8 KiB keeps only its newest
+ * ids. The reply is sent either way.
+ */
+declare function replyEmail(message: ForwardableEmailMessage, opts: ReplyEmailOptions): Promise<void>;
+/**
+ * Whether `value` is a real `ForwardableEmailMessage` — one Cloudflare
+ * delivered to this worker's `email()` directly — rather than an
+ * `EmailEnvelope` from the platform router. Functions do not survive RPC,
+ * so their presence is the discriminator.
+ */
+declare function isForwardableEmailMessage(value: unknown): value is ForwardableEmailMessage;
+/**
+ * Replay recorded `EmailAction`s on a real `ForwardableEmailMessage`, in
+ * order. The proxy already made `setReject` terminal (earlier forward/reply
+ * entries are purged, later ones dropped), so a reject is never followed by
+ * anything. `reply` needs a genuine `EmailMessage` — Cloudflare rejects a
+ * duck-typed object — so `cloudflare:email` is loaded here, and only when
+ * a reply was recorded.
+ *
+ * The `new Headers()` below is the one step this loop constructs from
+ * handler input, and it cannot fail on a recorded action: the proxy's
+ * `forward()` already ran the record through that constructor, so a bad
+ * record failed inside the handler, before any replay. (`EmailMessage`
+ * construction neither validates nor reads its stream — measured under
+ * workerd.) A reject's reason reaches the native `setReject()` as the proxy
+ * recorded it — already sliced and stripped the way the platform router
+ * would (`normalizeRejectReason`), so the SMTP reply is the same in both
+ * deployments. What Cloudflare itself refuses at `forward()` / `reply()`
+ * still throws out of the loop, as any native call would.
+ */
+declare function enactEmailActions(message: ForwardableEmailMessage, actions: ReadonlyArray<EmailAction>): Promise<void>;
+//#endregion
+export { SendEmailRecipientResult as C, SendEmailOptions as S, Attachment as _, MessageProxy as a, SendEmailError as b, ParsedEmail as c, defineEmail as d, enactEmailActions as f, Address as g, replyEmail as h, EmailHandlerInfo as i, ReplyEmailOptions as l, parseEmail as m, EmailEnvelope as n, ParseEmailError as o, isForwardableEmailMessage as p, EmailHandler as r, ParseEmailErrorCode as s, EmailAction as t, createMessageProxy as u, NormalizedEmail as v, SendEmailResult as w, SendEmailErrorCode as x, SendEmailDelivery as y };

package/dist/index.d.mts

@@ -1,44 +1,71 @@
-import { n as HeadDescriptor } from "./head-nmvOgFjd.mjs";
-import { r as AuthUser } from "./auth-qgMlYp7Z.mjs";
-import { C as defer, E as ValidatorSlots, S as InferProps, T as HandlerInput, _ as defineQueue, a as CloudEnv, b as Deferred, c as QueueRetryOptions, d as TypedQueueHandler, f as VoidAssetRewriteError, g as defineMiddleware, h as defineHead, i as CloudContextVariables, l as RenderAssetTags, m as defineHandler, o as QueueBatch, p as basicAuth, r as CloudContext, s as QueueMessage, t as BasicAuthOptions, u as TypedHandler, v as defineRender, x as DeferredState, y as defineScheduled } from "./handler-Cjh8uM3Y.mjs";
+import { n as HeadDescriptor } from "./head-Do8P4puT.mjs";
+import { r as AuthUser } from "./auth-DkcFflXV.mjs";
+import { C as defer, E as ValidatorSlots, S as InferProps, T as HandlerInput, _ as defineQueue, a as CloudEnv, b as Deferred, c as QueueRetryOptions, d as TypedQueueHandler, f as VoidAssetRewriteError, g as defineMiddleware, h as defineHead, i as CloudContextVariables, l as RenderAssetTags, m as defineHandler, o as QueueBatch, p as basicAuth, r as CloudContext, s as QueueMessage, t as BasicAuthOptions, u as TypedHandler, v as defineRender, x as DeferredState, y as defineScheduled } from "./handler-D1hLsObx.mjs";
 import { QueueMap } from "./runtime/queues.mjs";
 import { PluginConfig } from "@cloudflare/vite-plugin";
 import { Plugin } from "vite";
-
+//#region src/router/parse-filename.d.ts
+type RouteEnvironment = "dev" | "prod";
+//#endregion
 //#region src/index.d.ts
 /**
-* Decide whether to inject a Workers AI binding into the built wrangler config.
-*
-* Build-only: dev/miniflare has no local Workers AI, so serve must never bind
-* `env.AI` (dev uses the P2 `__VOID_TOKEN` proxy path instead).
-*
-* `!resolvedAi` is load-bearing: mergeBindings' return is defu-merged over the
-* resolved root-wrangler config and wins, so skipping when the user already
-* declared an `ai` binding avoids clobbering theirs. `!resultAi` is harmless
-* defense-in-depth (nothing else in mergeBindings sets `result.ai`).
-*/
-declare function shouldBindWorkersAi(command: string, needsAI: boolean, resolvedAi: unknown, resultAi: unknown): boolean;
+ * Decide whether to inject a Workers AI binding into the built wrangler config.
+ *
+ * Builds use the production binding. During dev, a project explicitly saved
+ * with the direct Cloudflare destination uses Cloudflare's remote binding;
+ * managed and unsaved projects keep using the Void HTTPS proxy.
+ *
+ * `!resolvedAi` is load-bearing: mergeBindings' return is defu-merged over the
+ * resolved root-wrangler config and wins, so skipping when the user already
+ * declared an `ai` binding avoids clobbering theirs. `!resultAi` is harmless
+ * defense-in-depth (nothing else in mergeBindings sets `result.ai`).
+ */
+export declare function shouldBindWorkersAi(command: string, needsAI: boolean, resolvedAi: unknown, resultAi: unknown, directCloudflareDev?: boolean): boolean;
+/**
+ * Decide whether to inject the `void dev` email-inbox loopback var.
+ *
+ * The dev inbox buffer lives in the Vite dev server's Node process;
+ * `sendEmail` runs in workerd and reaches it by fetching the inbox capture
+ * endpoint through the worker's assets binding, which
+ * `@cloudflare/vite-plugin` wires straight into the dev server's middleware
+ * stack. The var carries that binding's NAME (`ASSETS` for a Void app, or
+ * whatever a Class A framework's own wrangler config declares) and its
+ * presence is what arms the dev path at runtime — so it must never reach a
+ * production build's `wrangler.json`, exactly like the `__VOID_TOKEN`
+ * credential gate.
+ *
+ * Gated on `routeEnvironment`, not on `command`: `vite preview` also reports
+ * `command: 'serve'`, but it runs the BUILT worker whose assets binding is a
+ * real asset directory rather than a dev-server loopback. `routeEnvironment`
+ * is the existing `command === 'serve' && !isPreview` distinction.
+ *
+ * Without an assets binding there is no loopback, so injecting the var would
+ * only arm a path that must then fail; gate on it instead.
+ */
+export declare function shouldInjectEmailDevInboxVar(routeEnvironment: RouteEnvironment, needsEmail: boolean | undefined, assetsBinding: string | undefined): boolean;
+/** Resolve the runtime Workers AI binding, preserving a root Wrangler declaration. */
+export declare function resolveWorkersAiBindingName(resolvedAi: unknown, configuredName?: string): string;
 /**
-* Void plugin — the main entry point.
-*
-* Composes:
-* 1. Routing plugin (file-based routing from routes/ and middleware/)
-* 2. Migration plugin (auto-apply .sql migrations on dev startup)
-* 3. @cloudflare/vite-plugin (workerd runtime, HMR, builds)
-*
-* Binding inference runs synchronously here so results are available
-* before the Cloudflare plugin initializes.
-*
-* If the user has a `wrangler.jsonc` / `wrangler.json` in their project root,
-* the Cloudflare plugin reads it and provides the resolved config to our
-* config function. Bindings already defined there (with real IDs for
-* production deployment) are preserved — we only add inferred bindings
-* that are missing. This allows `vite build && wrangler deploy` to work
-* for deploying directly to Cloudflare without the Void platform.
-*/
-declare function voidPlugin(options?: {
+ * Void plugin — the main entry point.
+ *
+ * Composes:
+ * 1. Routing plugin (file-based routing from routes/ and middleware/)
+ * 2. Migration plugin (auto-apply .sql migrations on dev startup)
+ * 3. @cloudflare/vite-plugin (workerd runtime, HMR, builds)
+ *
+ * Binding inference runs synchronously here so results are available
+ * before the Cloudflare plugin initializes.
+ *
+ * If the user has a `wrangler.jsonc` / `wrangler.json` in their project root,
+ * the Cloudflare plugin reads it and provides the resolved config to our
+ * config function. Bindings already defined there (with real IDs for
+ * production deployment) are preserved — we only add inferred bindings
+ * that are missing. This allows `vite build && wrangler deploy` to work
+ * for deploying directly to Cloudflare without the Void platform.
+ */
+export declare function voidPlugin(options?: {
   persistTo?: string;
   auxiliaryWorkers?: PluginConfig["auxiliaryWorkers"];
 }): Array<Plugin>;
 //#endregion
-export { type AuthUser, type BasicAuthOptions, type CloudContext, type CloudContextVariables, type CloudEnv, type Deferred, type DeferredState, type HandlerInput, type HeadDescriptor, type InferProps, type QueueBatch, type QueueMap, type QueueMessage, type QueueRetryOptions, type RenderAssetTags, type TypedHandler, type TypedQueueHandler, type ValidatorSlots, VoidAssetRewriteError, basicAuth, defer, defineHandler, defineHead, defineMiddleware, defineQueue, defineRender, defineScheduled, shouldBindWorkersAi, voidPlugin };
+export { type AuthUser, type BasicAuthOptions, type CloudContext, type CloudContextVariables, type CloudEnv, type Deferred, type DeferredState, type HandlerInput, type HeadDescriptor, type InferProps, type QueueBatch, type QueueMap, type QueueMessage, type QueueRetryOptions, type RenderAssetTags, type TypedHandler, type TypedQueueHandler, type ValidatorSlots, VoidAssetRewriteError, basicAuth, defer, defineHandler, defineHead, defineMiddleware, defineQueue, defineRender, defineScheduled };