mymx 0.3.5 → 0.3.6

package/dist/types-BRl0ogvI.d.cts

@@ -1,520 +0,0 @@
-//#region src/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";
-/**
- * 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.
- */
-type WebhookVersion = string;
-
-//#endregion
-//#region src/types.d.ts
-
-/**
- * A parsed email address with optional display name.
- *
- * This 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`).
- *
- * @remarks
- * The `address` field contains the raw value extracted from the email header.
- * No validation is performed - any string value from the email header is
- * accepted as-is, including malformed or unusual addresses.
- *
- * @example
- * ```typescript
- * // "John Doe" <john@example.com>
- * { address: "john@example.com", name: "John Doe" }
- *
- * // john@example.com (no display name)
- * { address: "john@example.com", name: null }
- * ```
- */
-interface EmailAddress {
-  /**
-   * The email address portion (e.g., "john@example.com").
-   *
-   * This is the raw value from the email header with no validation applied.
-   * May contain unusual but valid formats like quoted local parts.
-   */
-  address: string;
-  /**
-   * The display name portion, if present.
-   * Null if the address had no display name.
-   *
-   * May contain any characters including unicode, emoji, or special characters
-   * as they appeared in the original email header.
-   */
-  name: string | null;
-}
-/**
- * Metadata for an email attachment.
- *
- * Attachment 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.
- */
-interface WebhookAttachment {
-  /**
-   * Original filename from the email.
-   * May be null if the attachment had no filename specified.
-   */
-  filename: string | null;
-  /**
-   * MIME content type (e.g., "application/pdf", "image/png").
-   */
-  content_type: string;
-  /**
-   * Size of the attachment in bytes.
-   */
-  size_bytes: number;
-  /**
-   * SHA-256 hash of the attachment content (hex-encoded).
-   * Use this to verify attachment integrity after download.
-   */
-  sha256: string;
-  /**
-   * Zero-based index of this part in the MIME structure.
-   */
-  part_index: number;
-  /**
-   * Path to this attachment within the downloaded tar.gz archive.
-   */
-  tar_path: string;
-}
-/**
- * Error details when email parsing fails.
- */
-interface ParsedError {
-  /**
-   * Error code indicating the type of failure.
-   * - `PARSE_FAILED`: The email could not be parsed (e.g., malformed MIME)
-   * - `ATTACHMENT_EXTRACTION_FAILED`: Email parsed but attachments couldn't be extracted
-   */
-  code: "PARSE_FAILED" | "ATTACHMENT_EXTRACTION_FAILED";
-  /**
-   * Human-readable error message describing what went wrong.
-   */
-  message: string;
-  /**
-   * Whether retrying might succeed.
-   * If true, the error was transient (e.g., timeout). If false, the email itself is problematic.
-   */
-  retryable: boolean;
-}
-/**
- * Parsed email content when parsing succeeded.
- *
- * Use the discriminant `status: "complete"` to narrow from {@link ParsedData}.
- */
-interface ParsedDataComplete {
-  /** Discriminant indicating successful parsing. */
-  status: "complete";
-  /** Always null when parsing succeeds. */
-  error: null;
-  /**
-   * Plain text body of the email.
-   * Null if the email had no text/plain part.
-   */
-  body_text: string | null;
-  /**
-   * HTML body of the email.
-   * Null if the email had no text/html part.
-   */
-  body_html: string | null;
-  /**
-   * Parsed Reply-To header addresses.
-   * Null if the email had no Reply-To header.
-   */
-  reply_to: EmailAddress[] | null;
-  /**
-   * Parsed CC header addresses.
-   * Null if the email had no CC header.
-   */
-  cc: EmailAddress[] | null;
-  /**
-   * Parsed BCC header addresses.
-   * Null if the email had no BCC header.
-   * Note: BCC is only available for outgoing emails or when explicitly provided.
-   */
-  bcc: EmailAddress[] | null;
-  /**
-   * 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.
-   * @example ["<original-message-id@example.com>"]
-   */
-  in_reply_to: string[] | null;
-  /**
-   * References header values (Message-IDs of the email thread).
-   * Null if the email had no References header.
-   * @example ["<msg1@example.com>", "<msg2@example.com>"]
-   */
-  references: string[] | null;
-  /**
-   * List of attachments with metadata.
-   * Use {@link attachments_download_url} to download the actual files.
-   */
-  attachments: WebhookAttachment[];
-  /**
-   * 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.
-   */
-  attachments_download_url: string | null;
-}
-/**
- * Parsed email content when parsing failed.
- *
- * Use the discriminant `status: "failed"` to narrow from {@link ParsedData}.
- */
-interface ParsedDataFailed {
-  /** Discriminant indicating parsing failed. */
-  status: "failed";
-  /** Details about why parsing failed. */
-  error: ParsedError;
-  /** Always null when parsing fails. */
-  body_text: null;
-  /** Always null when parsing fails. */
-  body_html: null;
-  /** Always null when parsing fails. */
-  reply_to: null;
-  /** Always null when parsing fails. */
-  cc: null;
-  /** Always null when parsing fails. */
-  bcc: null;
-  /** Always null when parsing fails. */
-  in_reply_to: null;
-  /** Always null when parsing fails. */
-  references: null;
-  /**
-   * May contain partial attachment metadata even when parsing failed.
-   * Useful for debugging or recovering partial data.
-   */
-  attachments: WebhookAttachment[];
-  /** Always null when parsing fails. */
-  attachments_download_url: null;
-}
-/**
- * Parsed email content - a discriminated union on `status`.
- *
- * @example
- * ```typescript
- * if (event.email.parsed.status === "complete") {
- *   console.log(event.email.parsed.body_text);
- * } else {
- *   console.error("Parse failed:", event.email.parsed.error.message);
- * }
- * ```
- */
-type ParsedData = ParsedDataComplete | ParsedDataFailed;
-/**
- * Raw email content included inline (base64 encoded).
- *
- * When the raw email is small enough (under {@link max_inline_bytes}),
- * it's included directly in the webhook payload for convenience.
- */
-interface RawContentInline {
-  /** Discriminant indicating raw content is included inline. */
-  included: true;
-  /** Encoding used for the data field. Always "base64". */
-  encoding: "base64";
-  /**
-   * Maximum size in bytes for inline inclusion.
-   * Emails larger than this threshold require download.
-   */
-  max_inline_bytes: number;
-  /** Actual size of the raw email in bytes. */
-  size_bytes: number;
-  /**
-   * SHA-256 hash of the raw email content (hex-encoded).
-   * Use this to verify integrity after base64 decoding.
-   */
-  sha256: string;
-  /**
-   * Base64-encoded raw email (RFC 5322 format).
-   * Decode with `Buffer.from(data, 'base64')` in Node.js.
-   */
-  data: string;
-}
-/**
- * Raw email content not included (must be downloaded).
- *
- * When 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.
- */
-interface RawContentDownloadOnly {
-  /** Discriminant indicating raw content must be downloaded. */
-  included: false;
-  /** Reason the content wasn't included inline. */
-  reason_code: "size_exceeded";
-  /**
-   * Maximum size in bytes for inline inclusion.
-   * The email exceeded this threshold.
-   */
-  max_inline_bytes: number;
-  /** Actual size of the raw email in bytes. */
-  size_bytes: number;
-  /**
-   * SHA-256 hash of the raw email content (hex-encoded).
-   * Use this to verify integrity after download.
-   */
-  sha256: string;
-}
-/**
- * Raw email content - a discriminated union on `included`.
- *
- * @example
- * ```typescript
- * if (event.email.content.raw.included) {
- *   const rawEmail = Buffer.from(event.email.content.raw.data, 'base64');
- * } else {
- *   // Download from event.email.content.download.url
- *   console.log("Email too large, size:", event.email.content.raw.size_bytes);
- * }
- * ```
- */
-type RawContent = RawContentInline | RawContentDownloadOnly;
-/**
- * Webhook payload for the `email.received` event.
- *
- * This is delivered to your webhook endpoint when MyMX receives an email
- * matching your domain configuration.
- *
- * @example
- * ```typescript
- * import { handleWebhook } from 'mymx';
- *
- * const event = handleWebhook({ body, headers, secret });
- *
- * console.log('From:', event.email.headers.from);
- * console.log('Subject:', event.email.headers.subject);
- *
- * if (event.email.parsed.status === 'complete') {
- *   console.log('Body:', event.email.parsed.body_text);
- * }
- * ```
- */
-interface EmailReceivedEvent {
-  /**
-   * Unique delivery event ID.
-   *
-   * This 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.
-   *
-   * Format: `evt_` prefix followed by a SHA-256 hash (64 hex characters).
-   * Example: `evt_a1b2c3d4e5f6...` (68 characters total)
-   */
-  id: string;
-  /**
-   * Event type identifier.
-   * Always `"email.received"` for this event type.
-   */
-  event: "email.received";
-  /**
-   * API version in date format (YYYY-MM-DD).
-   * Use this to detect version mismatches between webhook and SDK.
-   */
-  version: WebhookVersion;
-  /**
-   * Metadata about this webhook delivery.
-   */
-  delivery: {
-    /**
-     * ID of the webhook endpoint receiving this event.
-     * Matches the endpoint ID from your MyMX dashboard.
-     */
-    endpoint_id: string;
-    /**
-     * Delivery attempt number, starting at 1.
-     * Increments with each retry if previous attempts failed.
-     */
-    attempt: number;
-    /**
-     * ISO 8601 timestamp (UTC) when this delivery was attempted.
-     * @example "2025-01-15T10:30:00.000Z"
-     */
-    attempted_at: string;
-  };
-  /**
-   * The email that triggered this event.
-   */
-  email: {
-    /**
-     * Unique email ID in MyMX.
-     * Use this ID when calling MyMX APIs to reference this email.
-     */
-    id: string;
-    /**
-     * ISO 8601 timestamp (UTC) when MyMX received the email.
-     * @example "2025-01-15T10:29:55.123Z"
-     */
-    received_at: string;
-    /**
-     * SMTP envelope information.
-     * This is the "real" sender/recipient info from the SMTP transaction,
-     * which may differ from the headers (e.g., BCC recipients).
-     */
-    smtp: {
-      /**
-       * HELO/EHLO hostname from the sending server.
-       * Null if not provided during SMTP transaction.
-       */
-      helo: string | null;
-      /**
-       * SMTP envelope sender (MAIL FROM command).
-       * This is the bounce address, which may differ from the From header.
-       */
-      mail_from: string;
-      /**
-       * SMTP envelope recipients (RCPT TO commands).
-       * All addresses that received this email in a single delivery.
-       */
-      rcpt_to: string[];
-    };
-    /**
-     * Parsed email headers.
-     * These are extracted from the email content, not the SMTP envelope.
-     */
-    headers: {
-      /**
-       * Message-ID header value.
-       * Null if the email had no Message-ID header.
-       */
-      message_id: string | null;
-      /**
-       * Subject header value.
-       * Null if the email had no Subject header.
-       */
-      subject: string | null;
-      /**
-       * From header value.
-       * May include display name: `"John Doe" <john@example.com>`
-       */
-      from: string;
-      /**
-       * To header value.
-       * May include multiple addresses or display names.
-       */
-      to: string;
-      /**
-       * Date header value as it appeared in the email.
-       * Null if the email had no Date header.
-       */
-      date: string | null;
-    };
-    /**
-     * Raw email content and download information.
-     */
-    content: {
-      /**
-       * Raw email in RFC 5322 format.
-       * May be inline (base64) or download-only depending on size.
-       */
-      raw: RawContent;
-      /**
-       * Download information for the raw email.
-       * Always present, even if raw content is inline.
-       */
-      download: {
-        /**
-         * HTTPS URL to download the raw email.
-         * Returns the email as-is in RFC 5322 format.
-         */
-        url: string;
-        /**
-         * ISO 8601 timestamp (UTC) when this URL expires.
-         * Download before this time or the URL will return 403.
-         */
-        expires_at: string;
-      };
-    };
-    /**
-     * Parsed email content (body text, HTML, attachments).
-     * Check `status` to determine if parsing succeeded.
-     */
-    parsed: ParsedData;
-    /**
-     * Email analysis and classification results.
-     * May be absent if analysis was not performed.
-     */
-    analysis?: {
-      /**
-       * SpamAssassin analysis results.
-       */
-      spamassassin: {
-        /**
-         * Overall spam score (sum of all rule scores).
-         * Higher scores indicate higher likelihood of spam.
-         * Unbounded - can be negative (ham) or very high (spam).
-         */
-        score: number;
-      };
-    };
-  };
-}
-/**
- * Represents a webhook event type not yet supported by this SDK version.
- *
- * When MyMX adds new event types, your code won't break - you'll receive
- * an UnknownEvent that you can handle or ignore.
- *
- * @example
- * ```typescript
- * import { parseWebhookEvent } from 'mymx';
- *
- * const event = parseWebhookEvent(payload);
- *
- * if (event.event === 'email.received') {
- *   // TypeScript knows this is EmailReceivedEvent
- *   handleEmail(event);
- * } else {
- *   // Unknown event type - log and acknowledge
- *   console.log('Unknown event:', event.event);
- * }
- * ```
- */
-interface UnknownEvent {
-  /** The event type string (not a known type). */
-  event: string;
-  /** Event ID, if present in the payload. */
-  id?: string;
-  /** API version, if present in the payload. */
-  version?: string;
-  /** All other fields from the payload. */
-  [key: string]: unknown;
-}
-/**
- * All known webhook event types.
- *
- * Currently only includes `email.received`. More event types may be added
- * in future SDK versions.
- */
-type KnownWebhookEvent = EmailReceivedEvent;
-/**
- * All webhook event types, including unknown future events.
- *
- * Use `parseWebhookEvent()` to get this type with automatic narrowing
- * for known events and forward-compatibility for unknown events.
- */
-type WebhookEvent = KnownWebhookEvent | UnknownEvent;
-/**
- * Possible values for the `status` field in {@link ParsedData}.
- */
-type ParsedStatus = "complete" | "failed"; //#endregion
-export { EmailAddress, EmailReceivedEvent, KnownWebhookEvent, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus, RawContent, RawContentDownloadOnly, RawContentInline, UnknownEvent, WEBHOOK_VERSION, WebhookAttachment, WebhookEvent };