mymx 0.3.5 → 0.3.6

package/dist/index.d.cts

@@ -1,764 +0,0 @@
-import { EmailAddress, EmailReceivedEvent, KnownWebhookEvent, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus, RawContent, RawContentDownloadOnly, RawContentInline, UnknownEvent, WEBHOOK_VERSION, WebhookAttachment, WebhookEvent } from "./types-BRl0ogvI.cjs";
-import { MYMX_CONFIRMED_HEADER, MYMX_SIGNATURE_HEADER, VerifyOptions, verifyWebhookSignature } from "./signing-ChbxCBRQ.cjs";
-import { MyMXWebhookError, PAYLOAD_ERRORS, RAW_EMAIL_ERRORS, RawEmailDecodeError, RawEmailDecodeErrorCode, VERIFICATION_ERRORS, WebhookErrorCode, WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError, WebhookVerificationErrorCode } from "./errors-CwKIO2XZ.cjs";
-
-//#region src/schema.generated.d.ts
-/**
-* JSON Schema for EmailReceivedEvent.
-*
-* AUTO-GENERATED - DO NOT EDIT
-* Run `pnpm generate:schema` to regenerate.
-*/
-/**
- * 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 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 MyMX dashboard.";
-            };
-            readonly attempt: {
-              readonly type: "number";
-              readonly description: "Delivery attempt number, starting at 1. Increments with each retry if previous attempts failed.";
-            };
-            readonly attempted_at: {
-              readonly type: "string";
-              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 additionalProperties: false;
-          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 MyMX. Use this ID when calling MyMX APIs to reference this email.";
-            };
-            readonly received_at: {
-              readonly type: "string";
-              readonly description: "ISO 8601 timestamp (UTC) when MyMX 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 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 additionalProperties: false;
-              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 description: "From header value. May include display name: `\"John Doe\" <john@example.com>`";
-                };
-                readonly to: {
-                  readonly type: "string";
-                  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 additionalProperties: false;
-              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 description: "HTTPS URL to download the raw email. Returns the email as-is in RFC 5322 format.";
-                    };
-                    readonly expires_at: {
-                      readonly type: "string";
-                      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 additionalProperties: false;
-                  readonly description: "Download information for the raw email. Always present, even if raw content is inline.";
-                };
-              };
-              readonly required: ["raw", "download"];
-              readonly additionalProperties: false;
-              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 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 additionalProperties: false;
-                  readonly description: "SpamAssassin analysis results.";
-                };
-              };
-              readonly required: ["spamassassin"];
-              readonly additionalProperties: false;
-              readonly description: "Email analysis and classification results. May be absent if analysis was not performed.";
-            };
-          };
-          readonly required: ["id", "received_at", "smtp", "headers", "content", "parsed"];
-          readonly additionalProperties: false;
-          readonly description: "The email that triggered this event.";
-        };
-      };
-      readonly required: ["id", "event", "version", "delivery", "email"];
-      readonly additionalProperties: false;
-      readonly description: "Webhook payload for the `email.received` event.\n\nThis is delivered to your webhook endpoint when MyMX receives an email matching your domain configuration.";
-    };
-    readonly WebhookVersion: {
-      readonly type: "string";
-      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: "number";
-          readonly description: "Maximum size in bytes for inline inclusion. Emails larger than this threshold require download.";
-        };
-        readonly size_bytes: {
-          readonly type: "number";
-          readonly description: "Actual size of the raw email in bytes.";
-        };
-        readonly sha256: {
-          readonly type: "string";
-          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 additionalProperties: false;
-      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: "number";
-          readonly description: "Maximum size in bytes for inline inclusion. The email exceeded this threshold.";
-        };
-        readonly size_bytes: {
-          readonly type: "number";
-          readonly description: "Actual size of the raw email in bytes.";
-        };
-        readonly sha256: {
-          readonly type: "string";
-          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 additionalProperties: false;
-      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 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 additionalProperties: false;
-      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 additionalProperties: false;
-      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: "number";
-          readonly description: "Size of the attachment in bytes.";
-        };
-        readonly sha256: {
-          readonly type: "string";
-          readonly description: "SHA-256 hash of the attachment content (hex-encoded). Use this to verify attachment integrity after download.";
-        };
-        readonly part_index: {
-          readonly type: "number";
-          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 additionalProperties: false;
-      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 additionalProperties: false;
-      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 additionalProperties: false;
-      readonly description: "Error details when email parsing fails.";
-    };
-  };
-}; //#endregion
-//#region src/index.d.ts
-
-/**
- * Parse a webhook payload, returning typed events for known types
- * and UnknownEvent for future event types.
- *
- * This provides forward-compatibility: when MyMX adds new event types,
- * your code won't break - you'll receive an UnknownEvent that you can
- * handle or ignore.
- *
- * For most use cases, prefer `handleWebhook()` which also verifies
- * the signature and validates the payload schema.
- *
- * @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
- *
- * @example
- * ```typescript
- * import { parseWebhookEvent } from 'mymx';
- *
- * 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 MyMX-Signature header.
-   */
-  headers: WebhookHeaders;
-  /**
-   * Your webhook secret from the MyMX 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 MyMX webhooks. It:
- * 1. Verifies the signature to ensure the webhook is authentic
- * 2. Parses the JSON body
- * 3. Validates the payload against the schema with Zod
- * 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, MyMXWebhookError } from 'mymx';
- *
- * app.post('/webhooks/email', express.raw({ type: 'application/json' }), (req, res) => {
- *   try {
- *     const event = handleWebhook({
- *       body: req.body,
- *       headers: req.headers,
- *       secret: process.env.MYMX_WEBHOOK_SECRET,
- *     });
- *
- *     console.log('Email from:', event.email.headers.from);
- *     res.json({ received: true });
- *   } catch (err) {
- *     if (err instanceof MyMXWebhookError) {
- *       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 MyMX dashboard,
- * returning this header tells MyMX 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', (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-MyMX-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 'mymx';
- *
- * 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 MyMX 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 'mymx';
- *
- * 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, EmailAddress, EmailReceivedEvent, HandleWebhookOptions, KnownWebhookEvent, MYMX_CONFIRMED_HEADER, MYMX_SIGNATURE_HEADER, MyMXWebhookError, PAYLOAD_ERRORS, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus, RAW_EMAIL_ERRORS, RawContent, RawContentDownloadOnly, RawContentInline, RawEmailDecodeError, RawEmailDecodeErrorCode, UnknownEvent, VERIFICATION_ERRORS, VerifyOptions, WEBHOOK_VERSION, WebhookAttachment, WebhookErrorCode, WebhookEvent, WebhookHeaders, WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError, WebhookVerificationErrorCode, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, verifyRawEmailDownload, verifyWebhookSignature };