@primitivedotdev/sdk 0.24.0 → 0.25.1

package/dist/{api-BjzvA2Fy.js → api-CoP5vKPK.js}

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./chunk-pbuEa-1d.js";
-import { r as formatAddress } from "./received-email-D6tKtWwW.js";
+import { c as WebhookVerificationError, d as formatAddress } from "./errors-x91I_yEt.js";
 //#region src/api/generated/core/bodySerializer.gen.ts
 const jsonBodySerializer = { bodySerializer: (body) => JSON.stringify(body, (_key, value) => typeof value === "bigint" ? value.toString() : value) };
 //#endregion
@@ -689,7 +689,7 @@ const pollCliLogin = (options) => (options.client ?? client$1).post({
 	url: "/cli/login/poll",
 	...options,
 	headers: {
-		"Content-Type": "application/json",
+		...options.body !== void 0 && { "Content-Type": "application/json" },
 		...options.headers
 	}
 });
@@ -734,7 +734,7 @@ const updateAccount = (options) => (options.client ?? client$1).patch({
 	url: "/account",
 	...options,
 	headers: {
-		"Content-Type": "application/json",
+		...options.body !== void 0 && { "Content-Type": "application/json" },
 		...options.headers
 	}
 });
@@ -828,7 +828,7 @@ const addDomain = (options) => (options.client ?? client$1).post({
 	url: "/domains",
 	...options,
 	headers: {
-		"Content-Type": "application/json",
+		...options.body !== void 0 && { "Content-Type": "application/json" },
 		...options.headers
 	}
 });
@@ -860,7 +860,7 @@ const updateDomain = (options) => (options.client ?? client$1).patch({
 	url: "/domains/{id}",
 	...options,
 	headers: {
-		"Content-Type": "application/json",
+		...options.body !== void 0 && { "Content-Type": "application/json" },
 		...options.headers
 	}
 });
@@ -1042,7 +1042,7 @@ const replyToEmail = (options) => (options.client ?? client$1).post({
 	url: "/emails/{id}/reply",
 	...options,
 	headers: {
-		"Content-Type": "application/json",
+		...options.body !== void 0 && { "Content-Type": "application/json" },
 		...options.headers
 	}
 });
@@ -1132,7 +1132,7 @@ const createEndpoint = (options) => (options.client ?? client$1).post({
 	url: "/endpoints",
 	...options,
 	headers: {
-		"Content-Type": "application/json",
+		...options.body !== void 0 && { "Content-Type": "application/json" },
 		...options.headers
 	}
 });
@@ -1167,7 +1167,7 @@ const updateEndpoint = (options) => (options.client ?? client$1).patch({
 	url: "/endpoints/{id}",
 	...options,
 	headers: {
-		"Content-Type": "application/json",
+		...options.body !== void 0 && { "Content-Type": "application/json" },
 		...options.headers
 	}
 });
@@ -1217,7 +1217,7 @@ const createFilter = (options) => (options.client ?? client$1).post({
 	url: "/filters",
 	...options,
 	headers: {
-		"Content-Type": "application/json",
+		...options.body !== void 0 && { "Content-Type": "application/json" },
 		...options.headers
 	}
 });
@@ -1245,7 +1245,7 @@ const updateFilter = (options) => (options.client ?? client$1).patch({
 	url: "/filters/{id}",
 	...options,
 	headers: {
-		"Content-Type": "application/json",
+		...options.body !== void 0 && { "Content-Type": "application/json" },
 		...options.headers
 	}
 });
@@ -1350,7 +1350,7 @@ const sendEmail = (options) => (options.client ?? client$1).post({
 	url: "/send-mail",
 	...options,
 	headers: {
-		"Content-Type": "application/json",
+		...options.body !== void 0 && { "Content-Type": "application/json" },
 		...options.headers
 	}
 });
@@ -1455,7 +1455,7 @@ const createFunction = (options) => (options.client ?? client$1).post({
 	url: "/functions",
 	...options,
 	headers: {
-		"Content-Type": "application/json",
+		...options.body !== void 0 && { "Content-Type": "application/json" },
 		...options.headers
 	}
 });
@@ -1520,7 +1520,7 @@ const updateFunction = (options) => (options.client ?? client$1).put({
 	url: "/functions/{id}",
 	...options,
 	headers: {
-		"Content-Type": "application/json",
+		...options.body !== void 0 && { "Content-Type": "application/json" },
 		...options.headers
 	}
 });
@@ -1528,8 +1528,14 @@ const updateFunction = (options) => (options.client ?? client$1).put({
 * Send a test invocation
 *
 * Sends a real test email from a Primitive-controlled sender to a
-* synthetic local-part on one of the org's verified inbound
-* domains. The function fires through the normal MX delivery
+* local-part on one of the org's verified inbound domains. By
+* default the recipient is a synthetic
+* `__primitive_function_test+<random>@<domain>` address that
+* every handler's catch-all routing receives identically; pass
+* `local_part` to override and exercise routing logic that
+* branches on a specific recipient (the common pattern when one
+* function handles multiple inboxes like `summarize@` and
+* `action@`). The function fires through the normal MX delivery
 * path, so reply / send-mail calls from inside the handler
 * against the inbound's `email.id` work the same as in
 * production. Returns immediately after the send is queued; the
@@ -1539,6 +1545,8 @@ const updateFunction = (options) => (options.client ?? client$1).put({
 * Requires that the function is currently `deployed`. Returns 422
 * if the function is in `pending` or `failed` state, or if the
 * org has no verified inbound domain to receive the test mail.
+* Returns 400 if `local_part` is set to a value that does not
+* match the local-part character set.
 *
 */
 const testFunction = (options) => (options.client ?? client$1).post({
@@ -1547,7 +1555,11 @@ const testFunction = (options) => (options.client ?? client$1).post({
 		type: "http"
 	}],
 	url: "/functions/{id}/test",
-	...options
+	...options,
+	headers: {
+		...options.body !== void 0 && { "Content-Type": "application/json" },
+		...options.headers
+	}
 });
 /**
 * List a function's secrets
@@ -1594,7 +1606,7 @@ const createFunctionSecret = (options) => (options.client ?? client$1).post({
 	url: "/functions/{id}/secrets",
 	...options,
 	headers: {
-		"Content-Type": "application/json",
+		...options.body !== void 0 && { "Content-Type": "application/json" },
 		...options.headers
 	}
 });
@@ -1634,11 +1646,150 @@ const setFunctionSecret = (options) => (options.client ?? client$1).put({
 	url: "/functions/{id}/secrets/{key}",
 	...options,
 	headers: {
-		"Content-Type": "application/json",
+		...options.body !== void 0 && { "Content-Type": "application/json" },
 		...options.headers
 	}
 });
 //#endregion
+//#region src/api/verify-signature.ts
+/**
+* Workers-safe webhook signature verification.
+*
+* Mirrors `verifyWebhookSignature` from `@primitivedotdev/sdk` but
+* implements the HMAC-SHA256 step with the Web Crypto API
+* (`crypto.subtle`) instead of `node:crypto`. The Node version is
+* still the right choice for server-side handlers running on Node
+* (it's measurably faster and supports Buffer bodies); this one
+* exists so a Primitive Function handler can bundle the verifier
+* without dragging in a `node:crypto` polyfill that inflates the
+* deploy artifact past the size cap.
+*
+* Available natively in Workers, Node 22+, browsers, Deno, and Bun.
+* Zero polyfill weight, zero new runtime dependencies.
+*
+* Surface contract matches the Node verifier exactly: same input
+* shape, same `WebhookVerificationError` class, same set of error
+* codes. Existing callers can swap the import path with no other
+* code changes:
+*
+*   // Node (existing):
+*   import { verifyWebhookSignature } from '@primitivedotdev/sdk';
+*
+*   // Workers / in-handler (this file):
+*   import { verifyWebhookSignature } from '@primitivedotdev/sdk/api';
+*/
+const PRIMITIVE_SIGNATURE_HEADER = "Primitive-Signature";
+const DEFAULT_TOLERANCE_SECONDS = 300;
+const FUTURE_TOLERANCE_SECONDS = 60;
+const HEX_PATTERN = /^[0-9a-f]+$/i;
+const HEX_LENGTH = 64;
+const UNIX_SECONDS_PATTERN = /^\d{1,10}$/;
+function parseSignatureHeader(signatureHeader) {
+	if (!signatureHeader || typeof signatureHeader !== "string") return null;
+	const parts = signatureHeader.split(",");
+	let timestamp = null;
+	const signatures = [];
+	for (const part of parts) {
+		const idx = part.indexOf("=");
+		if (idx === -1) continue;
+		const key = part.slice(0, idx).trim();
+		const value = part.slice(idx + 1).trim();
+		if (!key || !value) continue;
+		if (key === "t") {
+			if (!UNIX_SECONDS_PATTERN.test(value)) continue;
+			const parsed = Number(value);
+			if (Number.isSafeInteger(parsed)) timestamp = parsed;
+		} else if (key === "v1") signatures.push(value);
+	}
+	if (timestamp === null || signatures.length === 0) return null;
+	return {
+		timestamp,
+		signatures
+	};
+}
+function isValidHex(str) {
+	return str.length === HEX_LENGTH && HEX_PATTERN.test(str);
+}
+function arrayBufferToHex(buffer) {
+	const bytes = new Uint8Array(buffer);
+	let hex = "";
+	for (let i = 0; i < bytes.length; i++) hex += bytes[i].toString(16).padStart(2, "0");
+	return hex;
+}
+/**
+* Constant-time comparison of two equal-length hex strings. Returns
+* false if lengths differ (intentionally not a security issue: lengths
+* are public). Iterates the full length regardless of mismatch so the
+* timing signal does not reveal the position of the first divergence.
+*/
+function timingSafeEqualHex(a, b) {
+	if (a.length !== b.length) return false;
+	let diff = 0;
+	for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+	return diff === 0;
+}
+async function computeHmacHex(secret, payload) {
+	const encoder = new TextEncoder();
+	const keyData = encoder.encode(secret);
+	const key = await crypto.subtle.importKey("raw", keyData, {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	return arrayBufferToHex(await crypto.subtle.sign("HMAC", key, encoder.encode(payload)));
+}
+/**
+* Verify a webhook signature using the Web Crypto API.
+*
+* Throws `WebhookVerificationError` on failure with a specific error
+* code matching the Node verifier's set. Returns `true` on success.
+*
+* @example
+* ```typescript
+* import {
+*   verifyWebhookSignature,
+*   WebhookVerificationError,
+*   PRIMITIVE_SIGNATURE_HEADER,
+* } from '@primitivedotdev/sdk/api';
+*
+* export default {
+*   async fetch(request: Request, env: { PRIMITIVE_WEBHOOK_SECRET: string }) {
+*     const rawBody = await request.text();
+*     try {
+*       await verifyWebhookSignature({
+*         rawBody,
+*         signatureHeader: request.headers.get(PRIMITIVE_SIGNATURE_HEADER) ?? '',
+*         secret: env.PRIMITIVE_WEBHOOK_SECRET,
+*       });
+*     } catch (err) {
+*       if (err instanceof WebhookVerificationError) {
+*         return new Response('invalid signature', { status: 401 });
+*       }
+*       throw err;
+*     }
+*     // ... process the webhook
+*   },
+* };
+* ```
+*/
+async function verifyWebhookSignature(opts) {
+	const { rawBody, signatureHeader, secret, toleranceSeconds = DEFAULT_TOLERANCE_SECONDS, nowSeconds } = opts;
+	if (!secret) throw new WebhookVerificationError("MISSING_SECRET", "Webhook secret is required but was empty or not provided");
+	const parsed = parseSignatureHeader(signatureHeader);
+	if (!parsed) throw new WebhookVerificationError("INVALID_SIGNATURE_HEADER", "Invalid Primitive-Signature header format. Expected: t={timestamp},v1={signature}");
+	const { timestamp, signatures } = parsed;
+	const age = (nowSeconds ?? Math.floor(Date.now() / 1e3)) - timestamp;
+	if (age > toleranceSeconds) throw new WebhookVerificationError("TIMESTAMP_OUT_OF_RANGE", `Webhook timestamp too old (${age}s). Max age is ${toleranceSeconds}s.`);
+	if (age < -FUTURE_TOLERANCE_SECONDS) throw new WebhookVerificationError("TIMESTAMP_OUT_OF_RANGE", "Webhook timestamp is too far in the future. Check server clock sync.");
+	const expectedHex = await computeHmacHex(secret, `${timestamp}.${rawBody}`);
+	let anyMatch = false;
+	for (const candidate of signatures) {
+		if (!isValidHex(candidate)) continue;
+		if (timingSafeEqualHex(candidate.toLowerCase(), expectedHex)) anyMatch = true;
+	}
+	if (!anyMatch) throw new WebhookVerificationError("SIGNATURE_MISMATCH", "Webhook signature did not match. The body may have been modified in transit, or the secret may be out of date.");
+	return true;
+}
+//#endregion
 //#region src/api/index.ts
 const DEFAULT_API_BASE_URL_1 = "https://www.primitive.dev/api/v1";
 const DEFAULT_API_BASE_URL_2 = "https://api.primitive.dev/v1";
@@ -1927,4 +2078,4 @@ function client(options = {}) {
 }
 const operations = sdk_gen_exports;
 //#endregion
-export { updateEndpoint as $, getStorageStats as A, pollCliLogin as B, downloadAttachments as C, getFunction as D, getEmail as E, listEndpoints as F, searchEmails as G, replayEmailWebhooks as H, listFilters as I, startCliLogin as J, sendEmail as K, listFunctionSecrets as L, listDeliveries as M, listDomains as N, getSendPermissions as O, listEmails as P, updateDomain as Q, listFunctions as R, discardEmailContent as S, getAccount as T, replyToEmail as U, replayDelivery as V, rotateWebhookSecret as W, testFunction as X, testEndpoint as Y, updateAccount as Z, deleteEmail as _, PrimitiveClient as a, deleteFunction as b, createPrimitiveClient as c, cliLogout as d, updateFilter as et, createEndpoint as f, deleteDomain as g, createFunctionSecret as h, PrimitiveApiError as i, getWebhookSecret as j, getSentEmail as k, operations as l, createFunction as m, DEFAULT_API_BASE_URL_2 as n, verifyDomain as nt, client as o, createFilter as p, setFunctionSecret as q, PrimitiveApiClient as r, createPrimitiveApiClient as s, DEFAULT_API_BASE_URL_1 as t, updateFunction as tt, addDomain as u, deleteEndpoint as v, downloadRawEmail as w, deleteFunctionSecret as x, deleteFilter as y, listSentEmails as z };
+export { updateAccount as $, getSendPermissions as A, listFunctions as B, deleteFunctionSecret as C, getAccount as D, downloadRawEmail as E, listDomains as F, replyToEmail as G, pollCliLogin as H, listEmails as I, sendEmail as J, rotateWebhookSecret as K, listEndpoints as L, getStorageStats as M, getWebhookSecret as N, getEmail as O, listDeliveries as P, testFunction as Q, listFilters as R, deleteFunction as S, downloadAttachments as T, replayDelivery as U, listSentEmails as V, replayEmailWebhooks as W, startCliLogin as X, setFunctionSecret as Y, testEndpoint as Z, createFunctionSecret as _, PrimitiveClient as a, deleteEndpoint as b, createPrimitiveClient as c, verifyWebhookSignature as d, updateDomain as et, addDomain as f, createFunction as g, createFilter as h, PrimitiveApiError as i, verifyDomain as it, getSentEmail as j, getFunction as k, operations as l, createEndpoint as m, DEFAULT_API_BASE_URL_2 as n, updateFilter as nt, client as o, cliLogout as p, searchEmails as q, PrimitiveApiClient as r, updateFunction as rt, createPrimitiveApiClient as s, DEFAULT_API_BASE_URL_1 as t, updateEndpoint as tt, PRIMITIVE_SIGNATURE_HEADER as u, deleteDomain as v, discardEmailContent as w, deleteFilter as x, deleteEmail as y, listFunctionSecrets as z };

package/dist/contract/index.d.ts

@@ -1,5 +1,5 @@
 import { C as ParsedDataFailed, D as RawContentDownloadOnly, M as WebhookAttachment, O as RawContentInline, S as ParsedDataComplete, c as EmailAnalysis, l as EmailAuth, s as EmailAddress, u as EmailReceivedEvent, w as ParsedError } from "../types-9vXGZjPd.js";
-import { C as signStandardWebhooksPayload, h as WEBHOOK_VERSION, j as signWebhookPayload, k as SignResult, x as StandardWebhooksSignResult } from "../index-CDlwyxdp.js";
+import { C as signStandardWebhooksPayload, h as WEBHOOK_VERSION, j as signWebhookPayload, k as SignResult, x as StandardWebhooksSignResult } from "../index-Dbx9udpX.js";
 
 //#region src/contract/contract.d.ts
 /** Maximum raw email size for inline inclusion (256 KB). */

package/dist/contract/index.js

@@ -1,4 +1,4 @@
-import { E as signStandardWebhooksPayload, L as validateEmailReceivedEvent, M as signWebhookPayload, d as WEBHOOK_VERSION } from "../webhook-rUjGV6Zu.js";
+import { E as signStandardWebhooksPayload, L as validateEmailReceivedEvent, M as signWebhookPayload, d as WEBHOOK_VERSION } from "../webhook-DJkfUnFZ.js";
 import { createHash } from "node:crypto";
 //#region src/contract/contract.ts
 /**

package/dist/errors-C53fe686.d.ts

@@ -0,0 +1,245 @@
+import { M as WebhookAttachment, c as EmailAnalysis, l as EmailAuth, u as EmailReceivedEvent } from "./types-9vXGZjPd.js";
+import { ErrorObject } from "ajv";
+
+//#region src/webhook/received-email.d.ts
+interface ReceivedEmailAddress {
+  address: string;
+  name: string | null;
+}
+interface ReceivedEmailThread {
+  messageId: string | null;
+  inReplyTo: string[];
+  references: string[];
+}
+interface ReceivedEmail {
+  id: string;
+  eventId: string;
+  receivedAt: string;
+  sender: ReceivedEmailAddress;
+  replyTarget: ReceivedEmailAddress;
+  receivedBy: string;
+  receivedByAll: string[];
+  subject: string | null;
+  replySubject: string;
+  forwardSubject: string;
+  text: string | null;
+  thread: ReceivedEmailThread;
+  attachments: WebhookAttachment[];
+  auth: EmailAuth;
+  analysis: EmailAnalysis;
+  raw: EmailReceivedEvent;
+}
+declare function normalizeReceivedEmail(event: EmailReceivedEvent): ReceivedEmail;
+declare function buildReplySubject(subject: string | null | undefined): string;
+declare function buildForwardSubject(subject: string | null | undefined): string;
+declare function formatAddress(address: ReceivedEmailAddress): string;
+declare function parseHeaderAddress(value: string | null | undefined): ReceivedEmailAddress | null;
+//#endregion
+//#region src/webhook/errors.d.ts
+/**
+ * Verification error definitions.
+ * Use these for documentation, dashboards, and i18n.
+ */
+declare const VERIFICATION_ERRORS: {
+  readonly INVALID_SIGNATURE_HEADER: {
+    readonly message: "Missing or malformed Primitive-Signature header";
+    readonly suggestion: "Check that you're reading the correct header (Primitive-Signature) and it's being passed correctly from your web framework.";
+  };
+  readonly TIMESTAMP_OUT_OF_RANGE: {
+    readonly message: "Timestamp is too old (possible replay attack)";
+    readonly suggestion: "This could indicate a replay attack, network delay, or server clock drift. Check your server's time is synced.";
+  };
+  readonly SIGNATURE_MISMATCH: {
+    readonly message: "Signature doesn't match expected value";
+    readonly suggestion: "Verify the webhook secret matches and you're using the raw request body (not re-serialized JSON).";
+  };
+  readonly MISSING_SECRET: {
+    readonly message: "No webhook secret was provided";
+    readonly suggestion: "Pass your webhook secret from the Primitive dashboard. Check that the environment variable is set.";
+  };
+};
+/**
+ * Payload parsing error definitions.
+ * Use these for documentation, dashboards, and i18n.
+ */
+declare const PAYLOAD_ERRORS: {
+  readonly PAYLOAD_NULL: {
+    readonly message: "Webhook payload is null";
+    readonly suggestion: "Ensure you're passing the parsed JSON body, not null. Check your framework's body parsing middleware.";
+  };
+  readonly PAYLOAD_UNDEFINED: {
+    readonly message: "Webhook payload is undefined";
+    readonly suggestion: "The payload was not provided. Make sure you're passing the request body to the handler.";
+  };
+  readonly PAYLOAD_WRONG_TYPE: {
+    readonly message: "Webhook payload must be an object";
+    readonly suggestion: "The payload should be a parsed JSON object. Check that you're not passing a string or other primitive.";
+  };
+  readonly PAYLOAD_IS_ARRAY: {
+    readonly message: "Webhook payload is an array, expected object";
+    readonly suggestion: "Primitive webhooks are single event objects, not arrays. Check the payload structure.";
+  };
+  readonly PAYLOAD_MISSING_EVENT: {
+    readonly message: "Webhook payload missing 'event' field";
+    readonly suggestion: "All webhook payloads must have an 'event' field. This may not be a valid Primitive webhook.";
+  };
+  readonly PAYLOAD_UNKNOWN_EVENT: {
+    readonly message: "Unknown webhook event type";
+    readonly suggestion: "This event type is not recognized. You may need to update your SDK or handle unknown events gracefully.";
+  };
+  readonly PAYLOAD_EMPTY_BODY: {
+    readonly message: "Request body is empty";
+    readonly suggestion: "The request body was empty. Ensure the webhook is sending data and your framework is parsing it correctly.";
+  };
+  readonly JSON_PARSE_FAILED: {
+    readonly message: "Failed to parse JSON body";
+    readonly suggestion: "The request body is not valid JSON. Check the raw body content and Content-Type header.";
+  };
+  readonly INVALID_ENCODING: {
+    readonly message: "Invalid body encoding";
+    readonly suggestion: "The request body encoding is not supported. Primitive webhooks use UTF-8 encoded JSON.";
+  };
+};
+/**
+ * Raw email decode error definitions.
+ * Use these for documentation, dashboards, and i18n.
+ */
+declare const RAW_EMAIL_ERRORS: {
+  readonly NOT_INCLUDED: {
+    readonly message: "Raw email content not included inline";
+    readonly suggestion: "Use the download URL at event.email.content.download.url to fetch the raw email.";
+  };
+  readonly INVALID_BASE64: {
+    readonly message: "Raw email content is not valid base64";
+    readonly suggestion: "The raw email data is malformed. Fetch the raw email from the download URL or regenerate the webhook payload.";
+  };
+  readonly HASH_MISMATCH: {
+    readonly message: "SHA-256 hash verification failed";
+    readonly suggestion: "The raw email data may be corrupted. Try downloading from the URL instead.";
+  };
+};
+/**
+ * All error codes that can be thrown by the SDK.
+ */
+type WebhookErrorCode = WebhookVerificationErrorCode | WebhookPayloadErrorCode | WebhookValidationErrorCode | RawEmailDecodeErrorCode;
+type RawEmailDecodeErrorCode = keyof typeof RAW_EMAIL_ERRORS;
+/**
+ * Base class for all Primitive webhook errors.
+ *
+ * Catch this to handle any error from the SDK in a single catch block.
+ *
+ * @example
+ * ```typescript
+ * import { handleWebhook, PrimitiveWebhookError } from '@primitivedotdev/sdk';
+ *
+ * try {
+ *   const event = handleWebhook({ body, headers, secret });
+ * } catch (err) {
+ *   if (err instanceof PrimitiveWebhookError) {
+ *     console.error(`[${err.code}] ${err.message}`);
+ *     return res.status(400).json({ error: err.code });
+ *   }
+ *   throw err;
+ * }
+ * ```
+ */
+declare abstract class PrimitiveWebhookError extends Error {
+  /** Programmatic error code for monitoring and handling */
+  abstract readonly code: WebhookErrorCode;
+  /** Actionable guidance for fixing the issue */
+  abstract readonly suggestion: string;
+  /**
+   * Formats the error for logging/display.
+   */
+  toString(): string;
+  /**
+   * Serializes cleanly for structured logging (Datadog, CloudWatch, etc.)
+   */
+  toJSON(): {
+    name: string;
+    code: WebhookErrorCode;
+    message: string;
+    suggestion: string;
+  };
+}
+/**
+ * Error codes for webhook verification failures.
+ * Derived from VERIFICATION_ERRORS keys.
+ */
+type WebhookVerificationErrorCode = keyof typeof VERIFICATION_ERRORS;
+/**
+ * Error thrown when webhook signature verification fails.
+ *
+ * Use the `code` property to programmatically handle specific error cases.
+ */
+declare class WebhookVerificationError extends PrimitiveWebhookError {
+  readonly code: WebhookVerificationErrorCode;
+  readonly suggestion: string;
+  constructor(code: WebhookVerificationErrorCode, message?: string, suggestion?: string);
+}
+/**
+ * Error codes for webhook payload parsing failures.
+ * Derived from PAYLOAD_ERRORS keys.
+ */
+type WebhookPayloadErrorCode = keyof typeof PAYLOAD_ERRORS;
+/**
+ * Error thrown when webhook payload parsing fails (lightweight parser).
+ *
+ * Use the `code` property for programmatic handling and monitoring.
+ * The `suggestion` property contains actionable guidance for fixing the issue.
+ */
+declare class WebhookPayloadError extends PrimitiveWebhookError {
+  readonly code: WebhookPayloadErrorCode;
+  readonly suggestion: string;
+  /** Original error if this wraps another error (e.g., JSON.parse failure) */
+  readonly cause?: Error;
+  constructor(code: WebhookPayloadErrorCode, message?: string, suggestion?: string, cause?: Error);
+}
+/**
+ * Error code for schema validation failures.
+ */
+type WebhookValidationErrorCode = "SCHEMA_VALIDATION_FAILED";
+/**
+ * Error thrown when schema validation fails.
+ */
+declare class WebhookValidationError extends PrimitiveWebhookError {
+  readonly code: WebhookValidationErrorCode;
+  readonly suggestion: string;
+  /** The specific field path that failed (e.g., "email.headers.from") */
+  readonly field: string;
+  /** Original schema validation errors for advanced debugging */
+  readonly validationErrors: readonly ErrorObject[];
+  /** Number of additional validation errors beyond the first */
+  readonly additionalErrorCount: number;
+  constructor(field: string, message: string, suggestion: string, validationErrors: readonly ErrorObject[]);
+  /**
+   * Formats the error for logging/display.
+   * Includes error count and suggestion.
+   */
+  toString(): string;
+  /**
+   * Serializes cleanly for structured logging (Datadog, CloudWatch, etc.)
+   */
+  toJSON(): {
+    name: string;
+    code: "SCHEMA_VALIDATION_FAILED";
+    field: string;
+    message: string;
+    suggestion: string;
+    additionalErrorCount: number;
+  };
+}
+/**
+ * Error thrown when raw email decoding or verification fails.
+ *
+ * Use the `code` property to determine the failure reason:
+ * - `NOT_INCLUDED`: Raw email not inline, must download from URL
+ * - `HASH_MISMATCH`: SHA-256 verification failed, content may be corrupted
+ */
+declare class RawEmailDecodeError extends PrimitiveWebhookError {
+  readonly code: RawEmailDecodeErrorCode;
+  readonly suggestion: string;
+  constructor(code: RawEmailDecodeErrorCode, message?: string);
+}
+//#endregion
+export { buildForwardSubject as _, RawEmailDecodeErrorCode as a, normalizeReceivedEmail as b, WebhookPayloadError as c, WebhookValidationErrorCode as d, WebhookVerificationError as f, ReceivedEmailThread as g, ReceivedEmailAddress as h, RawEmailDecodeError as i, WebhookPayloadErrorCode as l, ReceivedEmail as m, PrimitiveWebhookError as n, VERIFICATION_ERRORS as o, WebhookVerificationErrorCode as p, RAW_EMAIL_ERRORS as r, WebhookErrorCode as s, PAYLOAD_ERRORS as t, WebhookValidationError as u, buildReplySubject as v, parseHeaderAddress as x, formatAddress as y };