@primitivedotdev/sdk 0.2.0

package/dist/index-C9pON-wY.d.ts

@@ -0,0 +1,1474 @@
+import { EmailAuth, EmailReceivedEvent, ValidateEmailAuthResult, WebhookEvent } from "./types-C6M6oCRS.js";
+import { ErrorObject } from "ajv";
+
+//#region src/webhook/errors.d.ts
+/**
+* Verification error definitions.
+* Use these for documentation, dashboards, and i18n.
+*/
+/**
+ * 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
+//#region src/validation.d.ts
+interface ValidationSuccess<T> {
+  success: true;
+  data: T;
+}
+interface ValidationFailure {
+  success: false;
+  error: WebhookValidationError;
+}
+type ValidationResult<T> = ValidationSuccess<T> | ValidationFailure;
+declare function validateEmailReceivedEvent(input: unknown): EmailReceivedEvent;
+declare function safeValidateEmailReceivedEvent(input: unknown): ValidationResult<EmailReceivedEvent>;
+
+//#endregion
+//#region src/webhook/signing.d.ts
+/**
+ * Webhook HMAC Signing (Stripe-style format)
+ *
+ * Implements HMAC-SHA256 signature for webhook security with timestamp validation.
+ * Prevents replay attacks by including timestamp in signature.
+ *
+ * Header format:
+ *   Primitive-Signature: t=<unix_seconds>,v1=<hex_hmac_sha256>
+ *
+ * Signed payload format: "{timestamp}.{raw_body}"
+ *
+ * This format matches Stripe's webhook signature scheme, which is widely understood
+ * and easy to implement in any language with ~15 lines of code.
+ */
+/** Header name for incoming webhook signature */
+declare const PRIMITIVE_SIGNATURE_HEADER = "Primitive-Signature";
+/** Header name to confirm webhook was processed (prevents retries) */
+declare const PRIMITIVE_CONFIRMED_HEADER = "X-Primitive-Confirmed";
+/**
+ * Result from signing a webhook payload
+ */
+interface SignResult {
+  /** Full header value ready to set on Primitive-Signature */
+  header: string;
+  /** Unix timestamp used for signing */
+  timestamp: number;
+  /** Raw hex signature (useful for debugging/tests) */
+  v1: string;
+}
+/**
+ * Options for verifying a webhook signature
+ */
+interface VerifyOptions {
+  /** The raw HTTP request body (must be the exact bytes, not re-serialized JSON) */
+  rawBody: string | Buffer;
+  /** The full Primitive-Signature header value */
+  signatureHeader: string;
+  /** Your webhook secret */
+  secret: string | Buffer;
+  /** Max age in seconds (default: 300) */
+  toleranceSeconds?: number;
+  /** Override current time for testing (unix seconds) */
+  nowSeconds?: number;
+}
+/**
+ * Sign a webhook payload using HMAC-SHA256.
+ *
+ * Useful for:
+ * - Internal testing and dogfooding
+ * - Generating test vectors
+ * - Integration tests
+ *
+ * @param rawBody - The raw JSON body string to sign
+ * @param secret - The webhook secret key
+ * @param timestamp - Unix timestamp in seconds (defaults to current time)
+ */
+declare function signWebhookPayload(rawBody: string | Buffer, secret: string | Buffer, timestamp?: number): SignResult;
+/**
+ * Verify a webhook signature.
+ *
+ * Throws `WebhookVerificationError` on failure with a specific error code.
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature, WebhookVerificationError } from '@primitivedotdev/sdk';
+ *
+ * try {
+ *   const signatureHeader = req.headers['primitive-signature'];
+ *   if (typeof signatureHeader !== 'string') {
+ *     throw new Error('Missing Primitive-Signature header');
+ *   }
+ *   verifyWebhookSignature({
+ *     rawBody: req.body, // raw string, NOT parsed JSON
+ *     signatureHeader,
+ *     secret: process.env.PRIMITIVE_WEBHOOK_SECRET!,
+ *   });
+ *   // Signature is valid, process the webhook
+ * } catch (err) {
+ *   if (err instanceof WebhookVerificationError) {
+ *     console.error('Invalid webhook:', err.code, err.message);
+ *   }
+ *   return res.status(400).send('Invalid signature');
+ * }
+ * ```
+ */
+declare function verifyWebhookSignature(opts: VerifyOptions): true;
+
+//#endregion
+//#region src/schema.generated.d.ts
+/**
+ * JSON Schema for EmailReceivedEvent.
+ *
+ * AUTO-GENERATED - DO NOT EDIT
+ * Run `pnpm generate:schema` to regenerate.
+ */
+declare const emailReceivedEventJsonSchema: {
+  readonly $schema: "http://json-schema.org/draft-07/schema#";
+  readonly $ref: "#/definitions/EmailReceivedEvent";
+  readonly definitions: {
+    readonly EmailReceivedEvent: {
+      readonly type: "object";
+      readonly properties: {
+        readonly id: {
+          readonly type: "string";
+          readonly pattern: "^evt_[a-f0-9]{64}$";
+          readonly description: "Unique delivery event ID.\n\nThis ID is stable across retries to the same endpoint - use it as your idempotency/dedupe key. Note that the same email delivered to different endpoints will have different event IDs.\n\nFormat: `evt_` prefix followed by a SHA-256 hash (64 hex characters). Example: `evt_a1b2c3d4e5f6...` (68 characters total)";
+        };
+        readonly event: {
+          readonly type: "string";
+          readonly const: "email.received";
+          readonly description: "Event type identifier. Always `\"email.received\"` for this event type.";
+        };
+        readonly version: {
+          readonly $ref: "#/definitions/WebhookVersion";
+          readonly description: "API version in date format (YYYY-MM-DD). Use this to detect version mismatches between webhook and SDK.";
+        };
+        readonly delivery: {
+          readonly type: "object";
+          readonly properties: {
+            readonly endpoint_id: {
+              readonly type: "string";
+              readonly description: "ID of the webhook endpoint receiving this event. Matches the endpoint ID from your Primitive dashboard.";
+            };
+            readonly attempt: {
+              readonly type: "integer";
+              readonly minimum: 1;
+              readonly description: "Delivery attempt number, starting at 1. Increments with each retry if previous attempts failed.";
+            };
+            readonly attempted_at: {
+              readonly type: "string";
+              readonly format: "date-time";
+              readonly description: "ISO 8601 timestamp (UTC) when this delivery was attempted.";
+              readonly examples: ["2025-01-15T10:30:00.000Z"];
+            };
+          };
+          readonly required: ["endpoint_id", "attempt", "attempted_at"];
+          readonly description: "Metadata about this webhook delivery.";
+        };
+        readonly email: {
+          readonly type: "object";
+          readonly properties: {
+            readonly id: {
+              readonly type: "string";
+              readonly description: "Unique email ID in Primitive. Use this ID when calling Primitive APIs to reference this email.";
+            };
+            readonly received_at: {
+              readonly type: "string";
+              readonly format: "date-time";
+              readonly description: "ISO 8601 timestamp (UTC) when Primitive received the email.";
+              readonly examples: ["2025-01-15T10:29:55.123Z"];
+            };
+            readonly smtp: {
+              readonly type: "object";
+              readonly properties: {
+                readonly helo: {
+                  readonly type: ["string", "null"];
+                  readonly description: "HELO/EHLO hostname from the sending server. Null if not provided during SMTP transaction.";
+                };
+                readonly mail_from: {
+                  readonly type: "string";
+                  readonly description: "SMTP envelope sender (MAIL FROM command). This is the bounce address, which may differ from the From header.";
+                };
+                readonly rcpt_to: {
+                  readonly type: "array";
+                  readonly items: {
+                    readonly type: "string";
+                  };
+                  readonly minItems: 1;
+                  readonly description: "SMTP envelope recipients (RCPT TO commands). All addresses that received this email in a single delivery.";
+                };
+              };
+              readonly required: ["helo", "mail_from", "rcpt_to"];
+              readonly description: "SMTP envelope information. This is the \"real\" sender/recipient info from the SMTP transaction, which may differ from the headers (e.g., BCC recipients).";
+            };
+            readonly headers: {
+              readonly type: "object";
+              readonly properties: {
+                readonly message_id: {
+                  readonly type: ["string", "null"];
+                  readonly description: "Message-ID header value. Null if the email had no Message-ID header.";
+                };
+                readonly subject: {
+                  readonly type: ["string", "null"];
+                  readonly description: "Subject header value. Null if the email had no Subject header.";
+                };
+                readonly from: {
+                  readonly type: "string";
+                  readonly minLength: 1;
+                  readonly description: "From header value. May include display name: `\"John Doe\" <john@example.com>`";
+                };
+                readonly to: {
+                  readonly type: "string";
+                  readonly minLength: 1;
+                  readonly description: "To header value. May include multiple addresses or display names.";
+                };
+                readonly date: {
+                  readonly type: ["string", "null"];
+                  readonly description: "Date header value as it appeared in the email. Null if the email had no Date header.";
+                };
+              };
+              readonly required: ["message_id", "subject", "from", "to", "date"];
+              readonly description: "Parsed email headers. These are extracted from the email content, not the SMTP envelope.";
+            };
+            readonly content: {
+              readonly type: "object";
+              readonly properties: {
+                readonly raw: {
+                  readonly $ref: "#/definitions/RawContent";
+                  readonly description: "Raw email in RFC 5322 format. May be inline (base64) or download-only depending on size.";
+                };
+                readonly download: {
+                  readonly type: "object";
+                  readonly properties: {
+                    readonly url: {
+                      readonly type: "string";
+                      readonly format: "uri";
+                      readonly pattern: "^https://";
+                      readonly description: "HTTPS URL to download the raw email. Returns the email as-is in RFC 5322 format.";
+                    };
+                    readonly expires_at: {
+                      readonly type: "string";
+                      readonly format: "date-time";
+                      readonly description: "ISO 8601 timestamp (UTC) when this URL expires. Download before this time or the URL will return 403.";
+                    };
+                  };
+                  readonly required: ["url", "expires_at"];
+                  readonly description: "Download information for the raw email. Always present, even if raw content is inline.";
+                };
+              };
+              readonly required: ["raw", "download"];
+              readonly description: "Raw email content and download information.";
+            };
+            readonly parsed: {
+              readonly $ref: "#/definitions/ParsedData";
+              readonly description: "Parsed email content (body text, HTML, attachments). Check `status` to determine if parsing succeeded.";
+            };
+            readonly analysis: {
+              readonly $ref: "#/definitions/EmailAnalysis";
+              readonly description: "Email analysis and classification results.";
+            };
+            readonly auth: {
+              readonly $ref: "#/definitions/EmailAuth";
+              readonly description: "Email authentication results (SPF, DKIM, DMARC).";
+            };
+          };
+          readonly required: ["id", "received_at", "smtp", "headers", "content", "parsed", "analysis", "auth"];
+          readonly description: "The email that triggered this event.";
+        };
+      };
+      readonly required: ["id", "event", "version", "delivery", "email"];
+      readonly description: "Webhook payload for the `email.received` event.\n\nThis is delivered to your webhook endpoint when Primitive receives an email matching your domain configuration.";
+    };
+    readonly WebhookVersion: {
+      readonly type: "string";
+      readonly pattern: "^(?:(?:\\d{4}-(?:(?:01|03|05|07|08|10|12)-(?:0[1-9]|[12]\\d|3[01])|(?:04|06|09|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:[02468][048]00|[13579][26]00|\\d{2}(?:0[48]|[2468][048]|[13579][26]))-02-29))$";
+      readonly description: "Valid webhook version format (YYYY-MM-DD date string). The SDK accepts any valid date-formatted version, not just the current one, for forward and backward compatibility.";
+    };
+    readonly RawContent: {
+      readonly anyOf: [{
+        readonly $ref: "#/definitions/RawContentInline";
+      }, {
+        readonly $ref: "#/definitions/RawContentDownloadOnly";
+      }];
+      readonly description: "Raw email content - a discriminated union on `included`.";
+    };
+    readonly RawContentInline: {
+      readonly type: "object";
+      readonly properties: {
+        readonly included: {
+          readonly type: "boolean";
+          readonly const: true;
+          readonly description: "Discriminant indicating raw content is included inline.";
+        };
+        readonly encoding: {
+          readonly type: "string";
+          readonly const: "base64";
+          readonly description: "Encoding used for the data field. Always \"base64\".";
+        };
+        readonly max_inline_bytes: {
+          readonly type: "integer";
+          readonly minimum: 1;
+          readonly description: "Maximum size in bytes for inline inclusion. Emails larger than this threshold require download.";
+        };
+        readonly size_bytes: {
+          readonly type: "integer";
+          readonly minimum: 0;
+          readonly description: "Actual size of the raw email in bytes.";
+        };
+        readonly sha256: {
+          readonly type: "string";
+          readonly pattern: "^[a-fA-F0-9]{64}$";
+          readonly description: "SHA-256 hash of the raw email content (hex-encoded). Use this to verify integrity after base64 decoding.";
+        };
+        readonly data: {
+          readonly type: "string";
+          readonly description: "Base64-encoded raw email (RFC 5322 format). Decode with `Buffer.from(data, 'base64')` in Node.js.";
+        };
+      };
+      readonly required: ["included", "encoding", "max_inline_bytes", "size_bytes", "sha256", "data"];
+      readonly description: "Raw email content included inline (base64 encoded).\n\nWhen the raw email is small enough (under  {@link  max_inline_bytes } ), it's included directly in the webhook payload for convenience.";
+    };
+    readonly RawContentDownloadOnly: {
+      readonly type: "object";
+      readonly properties: {
+        readonly included: {
+          readonly type: "boolean";
+          readonly const: false;
+          readonly description: "Discriminant indicating raw content must be downloaded.";
+        };
+        readonly reason_code: {
+          readonly type: "string";
+          readonly const: "size_exceeded";
+          readonly description: "Reason the content wasn't included inline.";
+        };
+        readonly max_inline_bytes: {
+          readonly type: "integer";
+          readonly minimum: 1;
+          readonly description: "Maximum size in bytes for inline inclusion. The email exceeded this threshold.";
+        };
+        readonly size_bytes: {
+          readonly type: "integer";
+          readonly minimum: 0;
+          readonly description: "Actual size of the raw email in bytes.";
+        };
+        readonly sha256: {
+          readonly type: "string";
+          readonly pattern: "^[a-fA-F0-9]{64}$";
+          readonly description: "SHA-256 hash of the raw email content (hex-encoded). Use this to verify integrity after download.";
+        };
+      };
+      readonly required: ["included", "reason_code", "max_inline_bytes", "size_bytes", "sha256"];
+      readonly description: "Raw email content not included (must be downloaded).\n\nWhen the raw email exceeds  {@link  max_inline_bytes } , it's not included in the webhook payload. Use the download URL from  {@link  EmailReceivedEvent.email.content.download  }  to fetch it.";
+    };
+    readonly ParsedData: {
+      readonly anyOf: [{
+        readonly $ref: "#/definitions/ParsedDataComplete";
+      }, {
+        readonly $ref: "#/definitions/ParsedDataFailed";
+      }];
+      readonly description: "Parsed email content - a discriminated union on `status`.";
+    };
+    readonly ParsedDataComplete: {
+      readonly type: "object";
+      readonly properties: {
+        readonly status: {
+          readonly type: "string";
+          readonly const: "complete";
+          readonly description: "Discriminant indicating successful parsing.";
+        };
+        readonly error: {
+          readonly type: "null";
+          readonly description: "Always null when parsing succeeds.";
+        };
+        readonly body_text: {
+          readonly type: ["string", "null"];
+          readonly description: "Plain text body of the email. Null if the email had no text/plain part.";
+        };
+        readonly body_html: {
+          readonly type: ["string", "null"];
+          readonly description: "HTML body of the email. Null if the email had no text/html part.";
+        };
+        readonly reply_to: {
+          readonly anyOf: [{
+            readonly type: "array";
+            readonly items: {
+              readonly $ref: "#/definitions/EmailAddress";
+            };
+          }, {
+            readonly type: "null";
+          }];
+          readonly description: "Parsed Reply-To header addresses. Null if the email had no Reply-To header.";
+        };
+        readonly cc: {
+          readonly anyOf: [{
+            readonly type: "array";
+            readonly items: {
+              readonly $ref: "#/definitions/EmailAddress";
+            };
+          }, {
+            readonly type: "null";
+          }];
+          readonly description: "Parsed CC header addresses. Null if the email had no CC header.";
+        };
+        readonly bcc: {
+          readonly anyOf: [{
+            readonly type: "array";
+            readonly items: {
+              readonly $ref: "#/definitions/EmailAddress";
+            };
+          }, {
+            readonly type: "null";
+          }];
+          readonly description: "Parsed BCC header addresses. Null if the email had no BCC header. Note: BCC is only available for outgoing emails or when explicitly provided.";
+        };
+        readonly in_reply_to: {
+          readonly anyOf: [{
+            readonly type: "array";
+            readonly items: {
+              readonly type: "string";
+            };
+          }, {
+            readonly type: "null";
+          }];
+          readonly description: "In-Reply-To header values (Message-IDs of the email(s) being replied to). Null if the email had no In-Reply-To header. Per RFC 5322, this can contain multiple Message-IDs, though typically just one.";
+          readonly examples: [["<original-message-id@example.com>"]];
+        };
+        readonly references: {
+          readonly anyOf: [{
+            readonly type: "array";
+            readonly items: {
+              readonly type: "string";
+            };
+          }, {
+            readonly type: "null";
+          }];
+          readonly description: "References header values (Message-IDs of the email thread). Null if the email had no References header.";
+          readonly examples: [["<msg1@example.com>", "<msg2@example.com>"]];
+        };
+        readonly attachments: {
+          readonly type: "array";
+          readonly items: {
+            readonly $ref: "#/definitions/WebhookAttachment";
+          };
+          readonly description: "List of attachments with metadata. Use  {@link  attachments_download_url }  to download the actual files.";
+        };
+        readonly attachments_download_url: {
+          readonly type: ["string", "null"];
+          readonly format: "uri";
+          readonly pattern: "^https://";
+          readonly description: "HTTPS URL to download all attachments as a tar.gz archive. Null if the email had no attachments. URL expires - check the expiration before downloading.";
+        };
+      };
+      readonly required: ["status", "error", "body_text", "body_html", "reply_to", "cc", "bcc", "in_reply_to", "references", "attachments", "attachments_download_url"];
+      readonly description: "Parsed email content when parsing succeeded.\n\nUse the discriminant `status: \"complete\"` to narrow from  {@link  ParsedData } .";
+    };
+    readonly EmailAddress: {
+      readonly type: "object";
+      readonly properties: {
+        readonly address: {
+          readonly type: "string";
+          readonly description: "The email address portion (e.g., \"john@example.com\").\n\nThis is the raw value from the email header with no validation applied. May contain unusual but valid formats like quoted local parts.";
+        };
+        readonly name: {
+          readonly type: ["string", "null"];
+          readonly description: "The display name portion, if present. Null if the address had no display name.\n\nMay contain any characters including unicode, emoji, or special characters as they appeared in the original email header.";
+        };
+      };
+      readonly required: ["address", "name"];
+      readonly description: "A parsed email address with optional display name.\n\nThis structure is used in the `parsed` section of the webhook payload (e.g., `reply_to`, `cc`, `bcc`). For unparsed header strings, see the `headers` section (e.g., `event.email.headers.from`).";
+    };
+    readonly WebhookAttachment: {
+      readonly type: "object";
+      readonly properties: {
+        readonly filename: {
+          readonly type: ["string", "null"];
+          readonly description: "Original filename from the email. May be null if the attachment had no filename specified.";
+        };
+        readonly content_type: {
+          readonly type: "string";
+          readonly description: "MIME content type (e.g., \"application/pdf\", \"image/png\").";
+        };
+        readonly size_bytes: {
+          readonly type: "integer";
+          readonly minimum: 0;
+          readonly description: "Size of the attachment in bytes.";
+        };
+        readonly sha256: {
+          readonly type: "string";
+          readonly pattern: "^[a-fA-F0-9]{64}$";
+          readonly description: "SHA-256 hash of the attachment content (hex-encoded). Use this to verify attachment integrity after download.";
+        };
+        readonly part_index: {
+          readonly type: "integer";
+          readonly minimum: 0;
+          readonly description: "Zero-based index of this part in the MIME structure.";
+        };
+        readonly tar_path: {
+          readonly type: "string";
+          readonly description: "Path to this attachment within the downloaded tar.gz archive.";
+        };
+      };
+      readonly required: ["filename", "content_type", "size_bytes", "sha256", "part_index", "tar_path"];
+      readonly description: "Metadata for an email attachment.\n\nAttachment content is not included directly in the webhook payload. Use the `attachments_download_url` from  {@link  ParsedDataComplete }  to download all attachments as a tar.gz archive.";
+    };
+    readonly ParsedDataFailed: {
+      readonly type: "object";
+      readonly properties: {
+        readonly status: {
+          readonly type: "string";
+          readonly const: "failed";
+          readonly description: "Discriminant indicating parsing failed.";
+        };
+        readonly error: {
+          readonly $ref: "#/definitions/ParsedError";
+          readonly description: "Details about why parsing failed.";
+        };
+        readonly body_text: {
+          readonly type: "null";
+          readonly description: "Always null when parsing fails.";
+        };
+        readonly body_html: {
+          readonly type: "null";
+          readonly description: "Always null when parsing fails.";
+        };
+        readonly reply_to: {
+          readonly type: "null";
+          readonly description: "Always null when parsing fails.";
+        };
+        readonly cc: {
+          readonly type: "null";
+          readonly description: "Always null when parsing fails.";
+        };
+        readonly bcc: {
+          readonly type: "null";
+          readonly description: "Always null when parsing fails.";
+        };
+        readonly in_reply_to: {
+          readonly type: "null";
+          readonly description: "Always null when parsing fails.";
+        };
+        readonly references: {
+          readonly type: "null";
+          readonly description: "Always null when parsing fails.";
+        };
+        readonly attachments: {
+          readonly type: "array";
+          readonly items: {
+            readonly $ref: "#/definitions/WebhookAttachment";
+          };
+          readonly description: "May contain partial attachment metadata even when parsing failed. Useful for debugging or recovering partial data.";
+        };
+        readonly attachments_download_url: {
+          readonly type: "null";
+          readonly description: "Always null when parsing fails.";
+        };
+      };
+      readonly required: ["status", "error", "body_text", "body_html", "reply_to", "cc", "bcc", "in_reply_to", "references", "attachments", "attachments_download_url"];
+      readonly description: "Parsed email content when parsing failed.\n\nUse the discriminant `status: \"failed\"` to narrow from  {@link  ParsedData } .";
+    };
+    readonly ParsedError: {
+      readonly type: "object";
+      readonly properties: {
+        readonly code: {
+          readonly type: "string";
+          readonly enum: ["PARSE_FAILED", "ATTACHMENT_EXTRACTION_FAILED"];
+          readonly description: "Error code indicating the type of failure.\n- `PARSE_FAILED`: The email could not be parsed (e.g., malformed MIME)\n- `ATTACHMENT_EXTRACTION_FAILED`: Email parsed but attachments couldn't be extracted";
+        };
+        readonly message: {
+          readonly type: "string";
+          readonly description: "Human-readable error message describing what went wrong.";
+        };
+        readonly retryable: {
+          readonly type: "boolean";
+          readonly description: "Whether retrying might succeed. If true, the error was transient (e.g., timeout). If false, the email itself is problematic.";
+        };
+      };
+      readonly required: ["code", "message", "retryable"];
+      readonly description: "Error details when email parsing fails.";
+    };
+    readonly EmailAnalysis: {
+      readonly type: "object";
+      readonly properties: {
+        readonly spamassassin: {
+          readonly type: "object";
+          readonly properties: {
+            readonly score: {
+              readonly type: "number";
+              readonly description: "Overall spam score (sum of all rule scores). Higher scores indicate higher likelihood of spam. Unbounded - can be negative (ham) or very high (spam).";
+            };
+          };
+          readonly required: ["score"];
+          readonly description: "SpamAssassin analysis results.";
+        };
+        readonly forward: {
+          readonly $ref: "#/definitions/ForwardAnalysis";
+          readonly description: "Forward detection and analysis results.";
+        };
+      };
+      readonly description: "Email analysis and classification results.";
+    };
+    readonly ForwardAnalysis: {
+      readonly type: "object";
+      readonly properties: {
+        readonly detected: {
+          readonly type: "boolean";
+          readonly description: "Whether any forwards were detected in the email.";
+        };
+        readonly results: {
+          readonly type: "array";
+          readonly items: {
+            readonly $ref: "#/definitions/ForwardResult";
+          };
+          readonly description: "Analysis results for each detected forward.";
+        };
+        readonly attachments_found: {
+          readonly type: "integer";
+          readonly minimum: 0;
+          readonly description: "Total number of .eml attachments found.";
+        };
+        readonly attachments_analyzed: {
+          readonly type: "integer";
+          readonly minimum: 0;
+          readonly description: "Number of .eml attachments that were analyzed.";
+        };
+        readonly attachments_limit: {
+          readonly type: ["integer", "null"];
+          readonly minimum: 1;
+          readonly description: "Maximum number of attachments that will be analyzed, or null if unlimited.";
+        };
+      };
+      readonly required: ["detected", "results", "attachments_found", "attachments_analyzed", "attachments_limit"];
+      readonly description: "Forward detection and analysis results.";
+    };
+    readonly ForwardResult: {
+      readonly anyOf: [{
+        readonly $ref: "#/definitions/ForwardResultInline";
+      }, {
+        readonly $ref: "#/definitions/ForwardResultAttachmentAnalyzed";
+      }, {
+        readonly $ref: "#/definitions/ForwardResultAttachmentSkipped";
+      }];
+      readonly description: "Result for a single forwarded email detected in the message.\n\nUse the `type` and `analyzed` fields to narrow the type:\n- `type: 'inline'` - Inline forward, always analyzed\n- `type: 'attachment'` + `analyzed: true` - Analyzed attachment\n- `type: 'attachment'` + `analyzed: false` - Skipped attachment";
+    };
+    readonly ForwardResultInline: {
+      readonly type: "object";
+      readonly properties: {
+        readonly type: {
+          readonly type: "string";
+          readonly const: "inline";
+        };
+        readonly original_sender: {
+          readonly anyOf: [{
+            readonly $ref: "#/definitions/ForwardOriginalSender";
+          }, {
+            readonly type: "null";
+          }];
+          readonly description: "Original sender of the forwarded email, if extractable.";
+        };
+        readonly verification: {
+          readonly $ref: "#/definitions/ForwardVerification";
+          readonly description: "Verification result for the forwarded email.";
+        };
+        readonly summary: {
+          readonly type: "string";
+          readonly description: "Human-readable summary of the forward analysis.";
+        };
+      };
+      readonly required: ["type", "original_sender", "verification", "summary"];
+      readonly description: "Result for an inline forward that was detected and analyzed. Inline forwards are always analyzed when forward detection is enabled.";
+    };
+    readonly ForwardOriginalSender: {
+      readonly type: "object";
+      readonly properties: {
+        readonly email: {
+          readonly type: "string";
+          readonly description: "Email address of the original sender.";
+        };
+        readonly domain: {
+          readonly type: "string";
+          readonly description: "Domain of the original sender.";
+        };
+      };
+      readonly required: ["email", "domain"];
+      readonly description: "Original sender information extracted from the forwarded email.";
+    };
+    readonly ForwardVerification: {
+      readonly type: "object";
+      readonly properties: {
+        readonly verdict: {
+          readonly $ref: "#/definitions/ForwardVerdict";
+          readonly description: "Overall verdict on whether the forward is authentic.";
+        };
+        readonly confidence: {
+          readonly $ref: "#/definitions/AuthConfidence";
+          readonly description: "Confidence level for this verdict.";
+        };
+        readonly dkim_verified: {
+          readonly type: "boolean";
+          readonly description: "Whether a valid DKIM signature was found that verifies the original sender.";
+        };
+        readonly dkim_domain: {
+          readonly type: ["string", "null"];
+          readonly description: "Domain of the DKIM signature that verified the forward, if any.";
+        };
+        readonly dmarc_policy: {
+          readonly $ref: "#/definitions/DmarcPolicy";
+          readonly description: "DMARC policy of the original sender's domain.";
+        };
+      };
+      readonly required: ["verdict", "confidence", "dkim_verified", "dkim_domain", "dmarc_policy"];
+      readonly description: "Verification result for a forwarded email.";
+    };
+    readonly ForwardVerdict: {
+      readonly type: "string";
+      readonly enum: ["legit", "unknown"];
+      readonly description: "Verdict for forwarded email verification.\n\n- `legit`: DKIM signature verified the original sender\n- `unknown`: Could not verify the forwarded email's authenticity";
+    };
+    readonly AuthConfidence: {
+      readonly type: "string";
+      readonly enum: ["high", "medium", "low"];
+      readonly description: "Confidence level for the authentication verdict.\n\n- `high`: Strong cryptographic evidence (DKIM aligned + DMARC pass)\n- `medium`: Good evidence but with caveats (SPF-only alignment)\n- `low`: Weak evidence (missing authentication or unclear results)";
+    };
+    readonly DmarcPolicy: {
+      readonly type: ["string", "null"];
+      readonly enum: ["reject", "quarantine", "none", null];
+      readonly description: "DMARC policy action specified in the domain's DMARC record.\n\n- `reject`: The domain owner requests that receivers reject failing emails\n- `quarantine`: The domain owner requests that failing emails be treated as suspicious\n- `none`: The domain owner is only monitoring (no action requested)\n- `null`: No DMARC policy was found for the domain";
+    };
+    readonly ForwardResultAttachmentAnalyzed: {
+      readonly type: "object";
+      readonly properties: {
+        readonly type: {
+          readonly type: "string";
+          readonly const: "attachment";
+        };
+        readonly attachment_tar_path: {
+          readonly type: "string";
+          readonly description: "Path to the attachment in the attachments tar archive.";
+        };
+        readonly attachment_filename: {
+          readonly type: ["string", "null"];
+          readonly description: "Original filename of the attachment, if available.";
+        };
+        readonly analyzed: {
+          readonly type: "boolean";
+          readonly const: true;
+          readonly description: "Whether this attachment was analyzed.";
+        };
+        readonly original_sender: {
+          readonly anyOf: [{
+            readonly $ref: "#/definitions/ForwardOriginalSender";
+          }, {
+            readonly type: "null";
+          }];
+          readonly description: "Original sender of the forwarded email, if extractable.";
+        };
+        readonly verification: {
+          readonly $ref: "#/definitions/ForwardVerification";
+          readonly description: "Verification result for the forwarded email.";
+        };
+        readonly summary: {
+          readonly type: "string";
+          readonly description: "Human-readable summary of the forward analysis.";
+        };
+      };
+      readonly required: ["type", "attachment_tar_path", "attachment_filename", "analyzed", "original_sender", "verification", "summary"];
+      readonly description: "Result for an attachment forward that was analyzed.";
+    };
+    readonly ForwardResultAttachmentSkipped: {
+      readonly type: "object";
+      readonly properties: {
+        readonly type: {
+          readonly type: "string";
+          readonly const: "attachment";
+        };
+        readonly attachment_tar_path: {
+          readonly type: "string";
+          readonly description: "Path to the attachment in the attachments tar archive.";
+        };
+        readonly attachment_filename: {
+          readonly type: ["string", "null"];
+          readonly description: "Original filename of the attachment, if available.";
+        };
+        readonly analyzed: {
+          readonly type: "boolean";
+          readonly const: false;
+          readonly description: "Whether this attachment was analyzed.";
+        };
+        readonly original_sender: {
+          readonly type: "null";
+          readonly description: "Always null when not analyzed.";
+        };
+        readonly verification: {
+          readonly type: "null";
+          readonly description: "Always null when not analyzed.";
+        };
+        readonly summary: {
+          readonly type: "string";
+          readonly description: "Human-readable summary explaining why analysis was skipped.";
+        };
+      };
+      readonly required: ["type", "attachment_tar_path", "attachment_filename", "analyzed", "original_sender", "verification", "summary"];
+      readonly description: "Result for an attachment forward that was detected but not analyzed. This occurs when attachment analysis is disabled or the limit was reached.";
+    };
+    readonly EmailAuth: {
+      readonly type: "object";
+      readonly properties: {
+        readonly spf: {
+          readonly $ref: "#/definitions/SpfResult";
+          readonly description: "SPF verification result.\n\nSPF checks if the sending IP is authorized by the envelope sender's domain. \"pass\" means the IP is authorized; \"fail\" means it's explicitly not allowed.";
+        };
+        readonly dmarc: {
+          readonly $ref: "#/definitions/DmarcResult";
+          readonly description: "DMARC verification result.\n\nDMARC passes if either SPF or DKIM passes AND aligns with the From: domain. \"pass\" means the email is authenticated according to the sender's policy.";
+        };
+        readonly dmarcPolicy: {
+          readonly $ref: "#/definitions/DmarcPolicy";
+          readonly description: "DMARC policy from the sender's DNS record.\n\n- `reject`: Domain wants receivers to reject failing emails\n- `quarantine`: Domain wants failing emails marked as suspicious\n- `none`: Domain is monitoring only (no action requested)\n- `null`: No DMARC record found for this domain";
+        };
+        readonly dmarcFromDomain: {
+          readonly type: ["string", "null"];
+          readonly description: "The organizational domain used for DMARC lookups.\n\nFor example, if the From: address is `user@mail.example.com`, the DMARC lookup checks `_dmarc.mail.example.com`, then falls back to `_dmarc.example.com`. This field shows which domain's policy was used.";
+        };
+        readonly dmarcSpfAligned: {
+          readonly type: "boolean";
+          readonly description: "Whether SPF aligned with the From: domain for DMARC purposes.\n\nTrue if the envelope sender domain matches the From: domain (per alignment mode). Optional in self-hosted environments.";
+        };
+        readonly dmarcDkimAligned: {
+          readonly type: "boolean";
+          readonly description: "Whether DKIM aligned with the From: domain for DMARC purposes.\n\nTrue if at least one DKIM signature's domain matches the From: domain. Optional in self-hosted environments.";
+        };
+        readonly dmarcSpfStrict: {
+          readonly type: ["boolean", "null"];
+          readonly description: "Whether DMARC SPF alignment mode is strict.\n\n- `true`: Strict alignment required (exact domain match)\n- `false`: Relaxed alignment allowed (organizational domain match)\n- `null`: No DMARC record found";
+        };
+        readonly dmarcDkimStrict: {
+          readonly type: ["boolean", "null"];
+          readonly description: "Whether DMARC DKIM alignment mode is strict.\n\n- `true`: Strict alignment required (exact domain match)\n- `false`: Relaxed alignment allowed (organizational domain match)\n- `null`: No DMARC record found";
+        };
+        readonly dkimSignatures: {
+          readonly type: "array";
+          readonly items: {
+            readonly $ref: "#/definitions/DkimSignature";
+          };
+          readonly description: "All DKIM signatures found in the email with their verification results.\n\nMay be empty if no DKIM signatures were present.";
+        };
+      };
+      readonly required: ["spf", "dmarc", "dmarcPolicy", "dmarcFromDomain", "dmarcSpfStrict", "dmarcDkimStrict", "dkimSignatures"];
+      readonly description: "Email authentication results for SPF, DKIM, and DMARC.\n\nUse `validateEmailAuth()` to compute a verdict based on these results.";
+    };
+    readonly SpfResult: {
+      readonly type: "string";
+      readonly enum: ["pass", "fail", "softfail", "neutral", "none", "temperror", "permerror"];
+      readonly description: "SPF verification result.";
+    };
+    readonly DmarcResult: {
+      readonly type: "string";
+      readonly enum: ["pass", "fail", "none", "temperror", "permerror"];
+      readonly description: "DMARC verification result.";
+    };
+    readonly DkimSignature: {
+      readonly type: "object";
+      readonly properties: {
+        readonly domain: {
+          readonly type: "string";
+          readonly description: "The domain that signed this DKIM signature (d= tag). This may differ from the From: domain (that's what alignment checks).";
+        };
+        readonly selector: {
+          readonly type: ["string", "null"];
+          readonly description: "The DKIM selector used to locate the public key (s= tag). Combined with the domain to form the DNS lookup: `selector._domainkey.domain`\n\nOptional in self-hosted environments where the milter may not provide selector info.";
+        };
+        readonly result: {
+          readonly $ref: "#/definitions/DkimResult";
+          readonly description: "Verification result for this specific signature.";
+        };
+        readonly aligned: {
+          readonly type: "boolean";
+          readonly description: "Whether this signature's domain aligns with the From: domain (for DMARC).\n\nAlignment can be \"strict\" (exact match) or \"relaxed\" (organizational domain match). For example, if From: is `user@sub.example.com` and DKIM is signed by `example.com`:\n- Relaxed alignment: true (same organizational domain)\n- Strict alignment: false (not exact match)";
+        };
+        readonly keyBits: {
+          readonly type: ["integer", "null"];
+          readonly minimum: 1;
+          readonly maximum: 16384;
+          readonly description: "Key size in bits (e.g., 1024, 2048). Null if the key size couldn't be determined.\n\nOptional in self-hosted environments.";
+        };
+        readonly algo: {
+          readonly type: ["string", "null"];
+          readonly description: "Signing algorithm (e.g., \"rsa-sha256\", \"ed25519-sha256\").\n\nOptional in self-hosted environments.";
+        };
+      };
+      readonly required: ["domain", "result", "aligned"];
+      readonly description: "Details about a single DKIM signature found in the email.\n\nAn email may have multiple DKIM signatures (e.g., one from the sending domain and one from the ESP). Each signature is verified independently.\n\nFields marked optional (`selector`, `keyBits`, `algo`) may be unavailable in self-hosted environments where the milter provides limited DKIM detail.";
+    };
+    readonly DkimResult: {
+      readonly type: "string";
+      readonly enum: ["pass", "fail", "temperror", "permerror"];
+      readonly description: "DKIM signature verification result for a single signature.";
+    };
+  };
+}; //#endregion
+//#region src/webhook/auth.d.ts
+/**
+ * Validate email authentication and compute a verdict.
+ *
+ * This function analyzes SPF, DKIM, and DMARC results to determine
+ * whether an email is likely authentic ("legit"), potentially spoofed
+ * ("suspicious"), or indeterminate ("unknown").
+ *
+ * ## Verdict Logic
+ *
+ * **Legit (high confidence):**
+ * - DMARC pass with DKIM alignment (cryptographic proof of authenticity)
+ *
+ * **Legit (medium confidence):**
+ * - DMARC pass with SPF alignment only (no DKIM)
+ *   - Note: SPF can break through forwarding, but DMARC pass is still meaningful
+ *
+ * **Suspicious (high confidence):**
+ * - DMARC fail when domain has `reject` or `quarantine` policy
+ *   - The domain owner explicitly says to distrust failing emails
+ * - SPF explicitly fails (IP not authorized by sender)
+ *
+ * **Suspicious (low confidence):**
+ * - DMARC fail when domain has `none` policy (monitoring mode)
+ * - No DMARC record but SPF/DKIM fail
+ *
+ * **Unknown:**
+ * - No DMARC record and no clear pass/fail
+ * - Temporary errors during authentication
+ * - No authentication data available
+ *
+ * @param auth - Email authentication results from the webhook
+ * @returns Verdict, confidence level, and explanatory reasons
+ *
+ * @example
+ * ```typescript
+ * const result = validateEmailAuth({
+ *   spf: 'pass',
+ *   dmarc: 'pass',
+ *   dmarcPolicy: 'reject',
+ *   dmarcFromDomain: 'example.com',
+ *   dmarcSpfAligned: true,
+ *   dmarcDkimAligned: true,
+ *   dmarcSpfStrict: false,
+ *   dmarcDkimStrict: false,
+ *   dkimSignatures: [{
+ *     domain: 'example.com',
+ *     selector: 'default',
+ *     result: 'pass',
+ *     aligned: true,
+ *     keyBits: 2048,
+ *     algo: 'rsa-sha256',
+ *   }],
+ * });
+ *
+ * // result.verdict === 'legit'
+ * // result.confidence === 'high'
+ * // result.reasons === ['DMARC passed with DKIM alignment']
+ * ```
+ */
+declare function validateEmailAuth(auth: EmailAuth): ValidateEmailAuthResult;
+
+//#endregion
+//#region src/webhook/version.d.ts
+/**
+ * Webhook API Version
+ *
+ * Single source of truth for the webhook version.
+ * Update this file when bumping the API version.
+ */
+/**
+ * The current webhook API version this SDK is built for.
+ * Webhooks may be sent with different versions - the SDK accepts any valid
+ * YYYY-MM-DD formatted version string. Compare against this constant if you
+ * need to handle version-specific behavior.
+ */
+declare const WEBHOOK_VERSION = "2025-12-14";
+
+//#endregion
+//#region src/webhook/index.d.ts
+/**
+ * Valid webhook version format (YYYY-MM-DD date string).
+ * The SDK accepts any valid date-formatted version, not just the current one,
+ * for forward and backward compatibility.
+ */
+
+/**
+ * Parse a webhook payload, returning typed events for known types
+ * and UnknownEvent for future event types.
+ *
+ * This provides forward-compatibility: when Primitive adds new event types,
+ * your code won't break - you'll receive an UnknownEvent that you can
+ * handle or ignore.
+ *
+ * Known event types are validated against the canonical schema. Unknown
+ * event types are returned as-is for forward compatibility.
+ *
+ * For most use cases, prefer `handleWebhook()` which also verifies the
+ * signature before parsing the payload.
+ *
+ * @param input - The parsed JSON payload
+ * @returns Typed event for known types, UnknownEvent for unknown types
+ * @throws WebhookPayloadError if the input is not a valid webhook structure
+ * @throws WebhookValidationError if a known event fails schema validation
+ *
+ * @example
+ * ```typescript
+ * import { parseWebhookEvent } from '@primitivedotdev/sdk';
+ *
+ * const event = parseWebhookEvent(JSON.parse(rawBody));
+ *
+ * if (event.event === "email.received") {
+ *   // TypeScript knows this is EmailReceivedEvent
+ *   console.log(event.email.headers.subject);
+ * } else {
+ *   // Handle or log unknown event types
+ *   console.log("Unknown event:", event.event);
+ * }
+ * ```
+ */
+declare function parseWebhookEvent(input: unknown): WebhookEvent;
+/**
+ * Type guard to check if a webhook event is an EmailReceivedEvent.
+ *
+ * @example
+ * ```typescript
+ * const event = parseWebhookEvent(payload);
+ * if (isEmailReceivedEvent(event)) {
+ *   // TypeScript knows event is EmailReceivedEvent
+ *   console.log(event.email.headers.subject);
+ * }
+ * ```
+ */
+declare function isEmailReceivedEvent(event: WebhookEvent | unknown): event is EmailReceivedEvent;
+/**
+ * Request headers in any common format.
+ *
+ * Accepts:
+ * - **Plain object** from Express/Node.js (`req.headers`)
+ * - **Fetch API `Headers`** from Next.js App Router, Cloudflare Workers (`request.headers`)
+ *
+ * Header lookup is case-insensitive per RFC 7230.
+ */
+type WebhookHeaders = Record<string, string | string[] | undefined> | Headers;
+/**
+ * Options for the handleWebhook function.
+ */
+interface HandleWebhookOptions {
+  /**
+   * The raw request body (before JSON parsing).
+   * Must be the exact bytes received - do not re-serialize.
+   */
+  body: string | Buffer;
+  /**
+   * The request headers object.
+   * Works with Express (req.headers), Fetch API (Request.headers), or any
+   * object with string keys. The SDK will find the Primitive-Signature header.
+   */
+  headers: WebhookHeaders;
+  /**
+   * Your webhook secret from the Primitive dashboard.
+   */
+  secret: string;
+  /**
+   * Maximum age of the webhook in seconds.
+   * Webhooks older than this will be rejected as potential replay attacks.
+   * @default 300 (5 minutes)
+   */
+  toleranceSeconds?: number;
+}
+/**
+ * Verify, parse, and validate a webhook in one call.
+ *
+ * This is the recommended way to handle Primitive webhooks. It:
+ * 1. Verifies the signature to ensure the webhook is authentic
+ * 2. Parses the JSON body
+ * 3. Validates the payload against the canonical JSON schema
+ * 4. Returns a fully typed EmailReceivedEvent
+ *
+ * @param options - The webhook data and secret
+ * @returns A validated EmailReceivedEvent
+ * @throws {WebhookVerificationError} If signature verification fails
+ * @throws {WebhookPayloadError} If JSON parsing fails
+ * @throws {WebhookValidationError} If schema validation fails
+ *
+ * @example
+ * ```typescript
+ * import { handleWebhook, PrimitiveWebhookError } from '@primitivedotdev/sdk';
+ *
+ * app.post('/webhooks/email', express.raw({ type: 'application/json' }), (req, res) => {
+ *   try {
+ *     const event = handleWebhook({
+ *       body: req.body,
+ *       headers: req.headers,
+ *       secret: process.env.PRIMITIVE_WEBHOOK_SECRET,
+ *     });
+ *
+ *     console.log('Email from:', event.email.headers.from);
+ *     res.json({ received: true });
+ *   } catch (err) {
+ *     if (err instanceof PrimitiveWebhookError) {
+ *       console.error(`[${err.code}] ${err.message}`);
+ *       return res.status(400).json({ error: err.code });
+ *     }
+ *     throw err;
+ *   }
+ * });
+ * ```
+ */
+declare function handleWebhook(options: HandleWebhookOptions): EmailReceivedEvent;
+/**
+ * Returns headers for the optional "content discard" feature.
+ *
+ * If you have the "content discard" setting enabled in your Primitive dashboard,
+ * returning this header tells Primitive to permanently delete the email content
+ * after successful delivery. Requires BOTH the dashboard setting AND this header.
+ *
+ * **Warning:** Only use this if you can durably guarantee you've processed the email.
+ * Once discarded, the email content is gone forever.
+ *
+ * @returns Headers object to spread into your response
+ *
+ * @example Express (only if using content discard)
+ * ```typescript
+ * app.post('/webhook', async (req, res) => {
+ *   const event = handleWebhook({ ... });
+ *   // Durably save the email first!
+ *   await db.saveEmail(event);
+ *   res.set(confirmedHeaders()).json({ received: true });
+ * });
+ * ```
+ *
+ * @example Fetch API / Next.js (only if using content discard)
+ * ```typescript
+ * return new Response(JSON.stringify({ received: true }), {
+ *   status: 200,
+ *   headers: {
+ *     'Content-Type': 'application/json',
+ *     ...confirmedHeaders(),
+ *   },
+ * });
+ * ```
+ */
+declare function confirmedHeaders(): {
+  "X-Primitive-Confirmed": "true";
+};
+/**
+ * Check if the download URL for a webhook event has expired.
+ *
+ * @param event - The webhook event
+ * @param now - Optional current time for testing (defaults to Date.now())
+ * @returns true if the download URL has expired
+ *
+ * @example
+ * ```typescript
+ * if (isDownloadExpired(event)) {
+ *   console.log("Download URL has expired, cannot fetch raw email");
+ * } else {
+ *   const response = await fetch(event.email.content.download.url);
+ * }
+ * ```
+ */
+declare function isDownloadExpired(event: EmailReceivedEvent, now?: number): boolean;
+/**
+ * Get the time remaining (in milliseconds) before the download URL expires.
+ * Returns 0 if already expired.
+ *
+ * @param event - The webhook event
+ * @param now - Optional current time for testing (defaults to Date.now())
+ * @returns Milliseconds until expiration, or 0 if expired
+ *
+ * @example
+ * ```typescript
+ * const remaining = getDownloadTimeRemaining(event);
+ * if (remaining > 60000) {
+ *   // More than 1 minute left, safe to download
+ * }
+ * ```
+ */
+declare function getDownloadTimeRemaining(event: EmailReceivedEvent, now?: number): number;
+/**
+ * Check if the raw email content is included inline in the event.
+ *
+ * Use this to check before calling `decodeRawEmail()` to avoid try/catch.
+ *
+ * @param event - The webhook event
+ * @returns true if raw content is included inline, false if download required
+ *
+ * @example
+ * ```typescript
+ * if (isRawIncluded(event)) {
+ *   const rawEmail = decodeRawEmail(event);
+ * } else {
+ *   const response = await fetch(event.email.content.download.url);
+ * }
+ * ```
+ */
+declare function isRawIncluded(event: EmailReceivedEvent): boolean;
+/**
+ * Options for decoding raw email content.
+ */
+interface DecodeRawEmailOptions {
+  /**
+   * Whether to verify the SHA-256 hash after decoding.
+   * @default true
+   */
+  verify?: boolean;
+}
+/**
+ * Decode the raw email content from an EmailReceivedEvent.
+ *
+ * Throws if the raw content is not included inline (i.e., must be downloaded).
+ * By default, verifies the SHA-256 hash matches after decoding.
+ *
+ * NOTE: This function assumes a well-formed event from `handleWebhook()`.
+ * Passing a manually constructed event with missing fields (e.g., `raw.data`
+ * undefined when `raw.included` is true) will result in undefined behavior.
+ *
+ * @param event - The webhook event containing the raw email
+ * @param options - Decoding options
+ * @returns The decoded raw email as a Buffer
+ * @throws {RawEmailDecodeError} If content not included or hash mismatch
+ *
+ * @example
+ * ```typescript
+ * import { handleWebhook, decodeRawEmail, isRawIncluded } from '@primitivedotdev/sdk';
+ *
+ * const event = handleWebhook({ body, headers, secret });
+ *
+ * if (isRawIncluded(event)) {
+ *   const rawEmail = decodeRawEmail(event);
+ *   // rawEmail is a Buffer containing the RFC 5322 email
+ * } else {
+ *   // Must download from event.email.content.download.url
+ * }
+ * ```
+ */
+declare function decodeRawEmail(event: EmailReceivedEvent, options?: DecodeRawEmailOptions): Buffer;
+/**
+ * Verify downloaded raw email content against the SHA-256 hash in the event.
+ *
+ * Use this after fetching from `event.email.content.download.url` to ensure
+ * the downloaded content matches what Primitive received.
+ *
+ * @param downloaded - The downloaded raw email content (Buffer, ArrayBuffer, or Uint8Array)
+ * @param event - The webhook event containing the expected hash
+ * @returns The verified content as a Buffer
+ * @throws {RawEmailDecodeError} If hash doesn't match
+ *
+ * @example
+ * ```typescript
+ * import { handleWebhook, verifyRawEmailDownload, isRawIncluded } from '@primitivedotdev/sdk';
+ *
+ * const event = handleWebhook({ body, headers, secret });
+ *
+ * if (!isRawIncluded(event)) {
+ *   const response = await fetch(event.email.content.download.url);
+ *   const arrayBuffer = await response.arrayBuffer();
+ *   const verified = verifyRawEmailDownload(arrayBuffer, event);
+ *   // verified is a Buffer containing the RFC 5322 email
+ * }
+ * ```
+ */
+declare function verifyRawEmailDownload(downloaded: Buffer | ArrayBuffer | Uint8Array, event: EmailReceivedEvent): Buffer;
+
+//#endregion
+export { DecodeRawEmailOptions, HandleWebhookOptions, PAYLOAD_ERRORS as PAYLOAD_ERRORS$1, PRIMITIVE_CONFIRMED_HEADER as PRIMITIVE_CONFIRMED_HEADER$1, PRIMITIVE_SIGNATURE_HEADER as PRIMITIVE_SIGNATURE_HEADER$1, PrimitiveWebhookError as PrimitiveWebhookError$1, RAW_EMAIL_ERRORS as RAW_EMAIL_ERRORS$1, RawEmailDecodeError as RawEmailDecodeError$1, RawEmailDecodeErrorCode, SignResult, VERIFICATION_ERRORS as VERIFICATION_ERRORS$1, VerifyOptions, WEBHOOK_VERSION as WEBHOOK_VERSION$1, WebhookErrorCode, WebhookHeaders, WebhookPayloadError as WebhookPayloadError$1, WebhookPayloadErrorCode, WebhookValidationError as WebhookValidationError$1, WebhookValidationErrorCode, WebhookVerificationError as WebhookVerificationError$1, WebhookVerificationErrorCode, confirmedHeaders as confirmedHeaders$1, decodeRawEmail as decodeRawEmail$1, emailReceivedEventJsonSchema as emailReceivedEventJsonSchema$1, getDownloadTimeRemaining as getDownloadTimeRemaining$1, handleWebhook as handleWebhook$1, isDownloadExpired as isDownloadExpired$1, isEmailReceivedEvent as isEmailReceivedEvent$1, isRawIncluded as isRawIncluded$1, parseWebhookEvent as parseWebhookEvent$1, safeValidateEmailReceivedEvent as safeValidateEmailReceivedEvent$1, signWebhookPayload as signWebhookPayload$1, validateEmailAuth as validateEmailAuth$1, validateEmailReceivedEvent as validateEmailReceivedEvent$1, verifyRawEmailDownload as verifyRawEmailDownload$1, verifyWebhookSignature as verifyWebhookSignature$1 };