void 0.10.12 → 0.20.0

package/dist/inbound-BJ70in1n.d.mts

@@ -0,0 +1,354 @@
+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;
+}
+/**
+ * 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 };