mymx 0.3.5 → 0.3.7

package/dist/contract.cjs

@@ -1,188 +0,0 @@
-"use strict";
-const require_errors = require('./errors-DOkb_I6u.cjs');
-const require_signing = require('./signing-Bqe14lp0.cjs');
-const node_crypto = require_errors.__toESM(require("node:crypto"));
-
-//#region src/contract.ts
-/** Maximum raw email size for inline inclusion (256 KB) */
-const RAW_EMAIL_INLINE_THRESHOLD = 262144;
-/**
-* Generate a stable event ID for webhook deduplication.
-*
-* Format: `evt_{sha256_hex}` where the hash is deterministic based on:
-* - event_type ("email.received")
-* - version (WEBHOOK_VERSION)
-* - endpoint_id
-* - email_id
-*
-* This ensures the same email delivered to the same endpoint always has
-* the same event ID, enabling idempotent processing.
-*
-* The full 64-character SHA-256 hash is used for maximum collision resistance.
-*/
-function generateEventId(endpoint_id, email_id) {
-	const hashInput = `email.received:${require_errors.WEBHOOK_VERSION}:${endpoint_id}:${email_id}`;
-	const hash = (0, node_crypto.createHash)("sha256").update(hashInput).digest("hex");
-	return `evt_${hash}`;
-}
-/**
-* ISO 8601 timestamp pattern.
-* Matches: YYYY-MM-DDTHH:mm:ss.sssZ or YYYY-MM-DDTHH:mm:ssZ
-* Does NOT match loose formats like "Tuesday" that Date.parse accepts.
-*/
-const ISO_8601_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
-/**
-* Validate that a timestamp is a valid ISO 8601 string in UTC format.
-* Does NOT transform the input - preserves original format and precision.
-*
-* @param timestamp - The timestamp string to validate
-* @returns The validated timestamp (unchanged)
-* @throws Error if timestamp is not valid ISO 8601 UTC format
-*/
-function validateTimestamp(timestamp, fieldName) {
-	if (!ISO_8601_PATTERN.test(timestamp)) throw new Error(`[mymx/contract] Invalid ${fieldName}: "${timestamp}". Expected ISO 8601 UTC format (e.g., "2025-01-15T10:30:00.000Z")`);
-	const date = new Date(timestamp);
-	if (Number.isNaN(date.getTime())) throw new Error(`[mymx/contract] Invalid ${fieldName}: "${timestamp}" is not a valid date`);
-	return timestamp;
-}
-/**
-* Build an EmailReceivedEvent from server input.
-*
-* This is the exact function used by MyMX servers to construct webhook payloads.
-* By importing this from the SDK, the server gets build-time guarantees that
-* the payload will match what consumers expect.
-*
-* @param input - The server-side input data
-* @param options - Optional overrides for testing
-* @returns A fully constructed EmailReceivedEvent
-*
-* @example
-* ```typescript
-* import { buildEmailReceivedEvent } from 'mymx/contract';
-*
-* const event = buildEmailReceivedEvent({
-*   email_id: 'email-123',
-*   endpoint_id: 'endpoint-456',
-*   message_id: '<msg@example.com>',
-*   sender: 'from@example.com',
-*   recipient: 'to@example.com',
-*   subject: 'Hello',
-*   received_at: '2025-01-01T00:00:00Z',
-*   smtp_helo: 'mail.example.com',
-*   smtp_mail_from: 'from@example.com',
-*   smtp_rcpt_to: ['to@example.com'],
-*   raw_bytes: Buffer.from('...'),
-*   raw_sha256: 'abc123...',
-*   raw_size_bytes: 1234,
-*   attempt_count: 1,
-*   date_header: 'Mon, 1 Jan 2025 00:00:00 +0000',
-*   download_url: 'https://...',
-*   download_expires_at: '2025-01-02T00:00:00Z',
-*   attachments_download_url: null,
-* });
-* ```
-*/
-function buildEmailReceivedEvent(input, options) {
-	const event_id = options?.event_id ?? generateEventId(input.endpoint_id, input.email_id);
-	const attempted_at = options?.attempted_at ? validateTimestamp(options.attempted_at, "attempted_at") : new Date().toISOString();
-	const shouldInline = input.raw_size_bytes <= RAW_EMAIL_INLINE_THRESHOLD;
-	const rawContent = shouldInline ? {
-		included: true,
-		encoding: "base64",
-		max_inline_bytes: RAW_EMAIL_INLINE_THRESHOLD,
-		size_bytes: input.raw_size_bytes,
-		sha256: input.raw_sha256,
-		data: input.raw_bytes.toString("base64")
-	} : {
-		included: false,
-		reason_code: "size_exceeded",
-		max_inline_bytes: RAW_EMAIL_INLINE_THRESHOLD,
-		size_bytes: input.raw_size_bytes,
-		sha256: input.raw_sha256
-	};
-	let parsedData;
-	if (input.parsed?.status === "complete") parsedData = {
-		status: "complete",
-		error: null,
-		body_text: shouldInline ? input.parsed.body_text : null,
-		body_html: shouldInline ? input.parsed.body_html : null,
-		reply_to: input.parsed.reply_to ?? null,
-		cc: input.parsed.cc ?? null,
-		bcc: input.parsed.bcc ?? null,
-		in_reply_to: input.parsed.in_reply_to ?? null,
-		references: input.parsed.references ?? null,
-		attachments: input.parsed.attachments,
-		attachments_download_url: input.attachments_download_url
-	};
-	else if (input.parsed?.status === "failed") parsedData = {
-		status: "failed",
-		error: input.parsed.error,
-		body_text: null,
-		body_html: null,
-		reply_to: null,
-		cc: null,
-		bcc: null,
-		in_reply_to: null,
-		references: null,
-		attachments: [],
-		attachments_download_url: null
-	};
-	else parsedData = {
-		status: "failed",
-		error: {
-			code: "PARSE_FAILED",
-			message: "Parsing not attempted",
-			retryable: false
-		},
-		body_text: null,
-		body_html: null,
-		reply_to: null,
-		cc: null,
-		bcc: null,
-		in_reply_to: null,
-		references: null,
-		attachments: [],
-		attachments_download_url: null
-	};
-	return {
-		id: event_id,
-		event: "email.received",
-		version: require_errors.WEBHOOK_VERSION,
-		delivery: {
-			endpoint_id: input.endpoint_id,
-			attempt: input.attempt_count,
-			attempted_at
-		},
-		email: {
-			id: input.email_id,
-			received_at: validateTimestamp(input.received_at, "received_at"),
-			smtp: {
-				helo: input.smtp_helo,
-				mail_from: input.smtp_mail_from,
-				rcpt_to: input.smtp_rcpt_to
-			},
-			headers: {
-				message_id: input.message_id,
-				subject: input.subject,
-				from: input.sender,
-				to: input.recipient,
-				date: input.date_header
-			},
-			content: {
-				raw: rawContent,
-				download: {
-					url: input.download_url,
-					expires_at: validateTimestamp(input.download_expires_at, "download_expires_at")
-				}
-			},
-			parsed: parsedData
-		}
-	};
-}
-
-//#endregion
-exports.RAW_EMAIL_INLINE_THRESHOLD = RAW_EMAIL_INLINE_THRESHOLD
-exports.WEBHOOK_VERSION = require_errors.WEBHOOK_VERSION
-exports.buildEmailReceivedEvent = buildEmailReceivedEvent
-exports.generateEventId = generateEventId
-exports.signWebhookPayload = require_signing.signWebhookPayload

package/dist/contract.d.cts

@@ -1,146 +0,0 @@
-import { EmailAddress, EmailReceivedEvent, ParsedDataComplete, ParsedDataFailed, ParsedError, RawContentDownloadOnly, RawContentInline, WEBHOOK_VERSION, WebhookAttachment } from "./types-BRl0ogvI.cjs";
-import { SignResult, signWebhookPayload } from "./signing-ChbxCBRQ.cjs";
-
-//#region src/contract.d.ts
-/** Maximum raw email size for inline inclusion (256 KB) */
-
-/** Maximum raw email size for inline inclusion (256 KB) */
-declare const RAW_EMAIL_INLINE_THRESHOLD = 262144;
-/**
- * Parsed content input when parsing succeeded.
- */
-interface ParsedInputComplete {
-  status: "complete";
-  body_text: string | null;
-  body_html: string | null;
-  /** Parsed Reply-To header addresses (optional, defaults to null) */
-  reply_to?: EmailAddress[] | null;
-  /** Parsed CC header addresses (optional, defaults to null) */
-  cc?: EmailAddress[] | null;
-  /** Parsed BCC header addresses (optional, defaults to null) */
-  bcc?: EmailAddress[] | null;
-  /** In-Reply-To header values (optional, defaults to null) */
-  in_reply_to?: string[] | null;
-  /** References header values (optional, defaults to null) */
-  references?: string[] | null;
-  attachments: WebhookAttachment[];
-  /** Storage key for attachments tarball (used to generate download URL) */
-  attachments_storage_key: string | null;
-}
-/**
- * Parsed content input when parsing failed.
- */
-interface ParsedInputFailed {
-  status: "failed";
-  error: ParsedError;
-}
-/**
- * Parsed content input (discriminated union on status).
- */
-type ParsedInput = ParsedInputComplete | ParsedInputFailed;
-/**
- * Input for building an EmailReceivedEvent.
- *
- * This is the strict input shape that the MyMX server must provide.
- * TypeScript will enforce this at build time, ensuring the server
- * cannot construct a payload that doesn't match the SDK's expectations.
- */
-interface EmailReceivedEventInput {
-  /** Unique email ID in MyMX */
-  email_id: string;
-  /** ID of the webhook endpoint receiving this event */
-  endpoint_id: string;
-  /** Message-ID header (may be null) */
-  message_id: string | null;
-  /** From header value */
-  sender: string;
-  /** To header value */
-  recipient: string;
-  /** Subject header (may be null) */
-  subject: string | null;
-  /** ISO 8601 timestamp when MyMX received the email */
-  received_at: string;
-  /** HELO/EHLO hostname from the sending server */
-  smtp_helo: string | null;
-  /** SMTP envelope sender (MAIL FROM) */
-  smtp_mail_from: string;
-  /** SMTP envelope recipients (RCPT TO) */
-  smtp_rcpt_to: string[];
-  /** Raw email bytes (will be base64 encoded if small enough) */
-  raw_bytes: Buffer;
-  /** SHA-256 hash of raw email (hex) */
-  raw_sha256: string;
-  /** Size of raw email in bytes */
-  raw_size_bytes: number;
-  /** Delivery attempt number (starts at 1) */
-  attempt_count: number;
-  /** Date header value parsed from raw email (may be null) */
-  date_header: string | null;
-  /** Download URL for raw email */
-  download_url: string;
-  /** ISO 8601 timestamp when download URL expires */
-  download_expires_at: string;
-  /** URL to download attachments tarball (null if no attachments) */
-  attachments_download_url: string | null;
-  /** Parsed email content (optional, defaults to failed state) */
-  parsed?: ParsedInput;
-}
-/**
- * Generate a stable event ID for webhook deduplication.
- *
- * Format: `evt_{sha256_hex}` where the hash is deterministic based on:
- * - event_type ("email.received")
- * - version (WEBHOOK_VERSION)
- * - endpoint_id
- * - email_id
- *
- * This ensures the same email delivered to the same endpoint always has
- * the same event ID, enabling idempotent processing.
- *
- * The full 64-character SHA-256 hash is used for maximum collision resistance.
- */
-declare function generateEventId(endpoint_id: string, email_id: string): string;
-/**
- * Build an EmailReceivedEvent from server input.
- *
- * This is the exact function used by MyMX servers to construct webhook payloads.
- * By importing this from the SDK, the server gets build-time guarantees that
- * the payload will match what consumers expect.
- *
- * @param input - The server-side input data
- * @param options - Optional overrides for testing
- * @returns A fully constructed EmailReceivedEvent
- *
- * @example
- * ```typescript
- * import { buildEmailReceivedEvent } from 'mymx/contract';
- *
- * const event = buildEmailReceivedEvent({
- *   email_id: 'email-123',
- *   endpoint_id: 'endpoint-456',
- *   message_id: '<msg@example.com>',
- *   sender: 'from@example.com',
- *   recipient: 'to@example.com',
- *   subject: 'Hello',
- *   received_at: '2025-01-01T00:00:00Z',
- *   smtp_helo: 'mail.example.com',
- *   smtp_mail_from: 'from@example.com',
- *   smtp_rcpt_to: ['to@example.com'],
- *   raw_bytes: Buffer.from('...'),
- *   raw_sha256: 'abc123...',
- *   raw_size_bytes: 1234,
- *   attempt_count: 1,
- *   date_header: 'Mon, 1 Jan 2025 00:00:00 +0000',
- *   download_url: 'https://...',
- *   download_expires_at: '2025-01-02T00:00:00Z',
- *   attachments_download_url: null,
- * });
- * ```
- */
-declare function buildEmailReceivedEvent(input: EmailReceivedEventInput, options?: {
-  /** Override event ID (for testing or custom ID generation) */
-  event_id?: string;
-  /** Override attempted_at timestamp (for testing) */
-  attempted_at?: string;
-}): EmailReceivedEvent; //#endregion
-export { EmailAddress, EmailReceivedEvent, EmailReceivedEventInput, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedInput, ParsedInputComplete, ParsedInputFailed, RAW_EMAIL_INLINE_THRESHOLD, RawContentDownloadOnly, RawContentInline, SignResult, WEBHOOK_VERSION, WebhookAttachment, buildEmailReceivedEvent, generateEventId, signWebhookPayload };

package/dist/errors-CwKIO2XZ.d.cts

@@ -1,211 +0,0 @@
-import { ZodError } from "zod";
-
-//#region src/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 MyMX-Signature header";
-    readonly suggestion: "Check that you're reading the correct header (MyMX-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 MyMX 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: "MyMX 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 MyMX 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. MyMX 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 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 MyMX webhook errors.
- *
- * Catch this to handle any error from the SDK in a single catch block.
- *
- * @example
- * ```typescript
- * import { handleWebhook, MyMXWebhookError } from 'mymx';
- *
- * try {
- *   const event = handleWebhook({ body, signature, secret });
- * } catch (err) {
- *   if (err instanceof MyMXWebhookError) {
- *     console.error(`[${err.code}] ${err.message}`);
- *     return res.status(400).json({ error: err.code });
- *   }
- *   throw err;
- * }
- * ```
- */
-declare abstract class MyMXWebhookError 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 MyMXWebhookError {
-  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 MyMXWebhookError {
-  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 Zod schema validation failures.
- */
-type WebhookValidationErrorCode = "SCHEMA_VALIDATION_FAILED";
-/**
- * Error thrown when Zod schema validation fails.
- *
- * Wraps ZodError with human-friendly messages and actionable suggestions.
- */
-declare class WebhookValidationError extends MyMXWebhookError {
-  readonly code: WebhookValidationErrorCode;
-  readonly suggestion: string;
-  /** The specific field path that failed (e.g., "email.headers.from") */
-  readonly field: string;
-  /** Original Zod error for advanced debugging */
-  readonly zodError: ZodError;
-  /** Number of additional validation errors beyond the first */
-  readonly additionalErrorCount: number;
-  constructor(field: string, message: string, suggestion: string, zodError: ZodError);
-  /**
-   * 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 MyMXWebhookError {
-  readonly code: RawEmailDecodeErrorCode;
-  readonly suggestion: string;
-  constructor(code: RawEmailDecodeErrorCode, message?: string);
-} //#endregion
-export { MyMXWebhookError, PAYLOAD_ERRORS, RAW_EMAIL_ERRORS, RawEmailDecodeError, RawEmailDecodeErrorCode, VERIFICATION_ERRORS, WebhookErrorCode, WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError, WebhookVerificationErrorCode };