@primitivedotdev/sdk 0.24.0 → 0.25.1

package/dist/errors-x91I_yEt.js

@@ -0,0 +1,287 @@
+import { n as parseFromHeaderLoose } from "./address-parser-BYn8oW5r.js";
+//#region src/webhook/received-email.ts
+const REPLY_PREFIX_RE = /^re\s*:/i;
+const FORWARD_PREFIX_RE = /^(fwd?|fw)\s*:/i;
+function normalizeReceivedEmail(event) {
+	const receivedBy = event.email.smtp.rcpt_to[0];
+	if (!receivedBy) throw new Error("email.smtp.rcpt_to must contain at least one recipient");
+	const sender = parseHeaderAddress(event.email.headers.from) ?? {
+		address: event.email.smtp.mail_from.trim().toLowerCase(),
+		name: null
+	};
+	const replyTarget = firstStructuredAddress(event.email.parsed.reply_to) ?? sender;
+	const subject = event.email.headers.subject ?? null;
+	const references = event.email.parsed.references ?? [];
+	const messageId = event.email.headers.message_id ?? null;
+	return {
+		id: event.email.id,
+		eventId: event.id,
+		receivedAt: event.email.received_at,
+		sender,
+		replyTarget,
+		receivedBy,
+		receivedByAll: [...event.email.smtp.rcpt_to],
+		subject,
+		replySubject: buildReplySubject(subject),
+		forwardSubject: buildForwardSubject(subject),
+		text: event.email.parsed.body_text ?? null,
+		thread: {
+			messageId,
+			inReplyTo: event.email.parsed.in_reply_to ?? [],
+			references
+		},
+		attachments: event.email.parsed.attachments ?? [],
+		auth: event.email.auth,
+		analysis: event.email.analysis,
+		raw: event
+	};
+}
+function buildReplySubject(subject) {
+	const trimmed = subject?.trim() ?? "";
+	if (trimmed.length === 0) return "Re:";
+	return REPLY_PREFIX_RE.test(trimmed) ? trimmed : `Re: ${trimmed}`;
+}
+function buildForwardSubject(subject) {
+	const trimmed = subject?.trim() ?? "";
+	if (trimmed.length === 0) return "Fwd:";
+	return FORWARD_PREFIX_RE.test(trimmed) ? trimmed : `Fwd: ${trimmed}`;
+}
+function formatAddress(address) {
+	return address.name ? `${address.name} <${address.address}>` : address.address;
+}
+function firstStructuredAddress(addresses) {
+	const address = addresses?.[0];
+	if (!address) return null;
+	return {
+		address: address.address.trim().toLowerCase(),
+		name: address.name ?? null
+	};
+}
+function parseHeaderAddress(value) {
+	const parsed = parseFromHeaderLoose(value);
+	if (!parsed) return null;
+	return {
+		address: parsed.address,
+		name: parsed.name?.trim() || null
+	};
+}
+//#endregion
+//#region src/webhook/errors.ts
+/**
+* Verification error definitions.
+* Use these for documentation, dashboards, and i18n.
+*/
+const VERIFICATION_ERRORS = {
+	INVALID_SIGNATURE_HEADER: {
+		message: "Missing or malformed Primitive-Signature header",
+		suggestion: "Check that you're reading the correct header (Primitive-Signature) and it's being passed correctly from your web framework."
+	},
+	TIMESTAMP_OUT_OF_RANGE: {
+		message: "Timestamp is too old (possible replay attack)",
+		suggestion: "This could indicate a replay attack, network delay, or server clock drift. Check your server's time is synced."
+	},
+	SIGNATURE_MISMATCH: {
+		message: "Signature doesn't match expected value",
+		suggestion: "Verify the webhook secret matches and you're using the raw request body (not re-serialized JSON)."
+	},
+	MISSING_SECRET: {
+		message: "No webhook secret was provided",
+		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.
+*/
+const PAYLOAD_ERRORS = {
+	PAYLOAD_NULL: {
+		message: "Webhook payload is null",
+		suggestion: "Ensure you're passing the parsed JSON body, not null. Check your framework's body parsing middleware."
+	},
+	PAYLOAD_UNDEFINED: {
+		message: "Webhook payload is undefined",
+		suggestion: "The payload was not provided. Make sure you're passing the request body to the handler."
+	},
+	PAYLOAD_WRONG_TYPE: {
+		message: "Webhook payload must be an object",
+		suggestion: "The payload should be a parsed JSON object. Check that you're not passing a string or other primitive."
+	},
+	PAYLOAD_IS_ARRAY: {
+		message: "Webhook payload is an array, expected object",
+		suggestion: "Primitive webhooks are single event objects, not arrays. Check the payload structure."
+	},
+	PAYLOAD_MISSING_EVENT: {
+		message: "Webhook payload missing 'event' field",
+		suggestion: "All webhook payloads must have an 'event' field. This may not be a valid Primitive webhook."
+	},
+	PAYLOAD_UNKNOWN_EVENT: {
+		message: "Unknown webhook event type",
+		suggestion: "This event type is not recognized. You may need to update your SDK or handle unknown events gracefully."
+	},
+	PAYLOAD_EMPTY_BODY: {
+		message: "Request body is empty",
+		suggestion: "The request body was empty. Ensure the webhook is sending data and your framework is parsing it correctly."
+	},
+	JSON_PARSE_FAILED: {
+		message: "Failed to parse JSON body",
+		suggestion: "The request body is not valid JSON. Check the raw body content and Content-Type header."
+	},
+	INVALID_ENCODING: {
+		message: "Invalid body encoding",
+		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.
+*/
+const RAW_EMAIL_ERRORS = {
+	NOT_INCLUDED: {
+		message: "Raw email content not included inline",
+		suggestion: "Use the download URL at event.email.content.download.url to fetch the raw email."
+	},
+	INVALID_BASE64: {
+		message: "Raw email content is not valid base64",
+		suggestion: "The raw email data is malformed. Fetch the raw email from the download URL or regenerate the webhook payload."
+	},
+	HASH_MISMATCH: {
+		message: "SHA-256 hash verification failed",
+		suggestion: "The raw email data may be corrupted. Try downloading from the URL instead."
+	}
+};
+/**
+* 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;
+* }
+* ```
+*/
+var PrimitiveWebhookError = class extends Error {
+	/**
+	* Formats the error for logging/display.
+	*/
+	toString() {
+		return `${this.name} [${this.code}]: ${this.message}\n\nSuggestion: ${this.suggestion}`;
+	}
+	/**
+	* Serializes cleanly for structured logging (Datadog, CloudWatch, etc.)
+	*/
+	toJSON() {
+		return {
+			name: this.name,
+			code: this.code,
+			message: this.message,
+			suggestion: this.suggestion
+		};
+	}
+};
+/**
+* Error thrown when webhook signature verification fails.
+*
+* Use the `code` property to programmatically handle specific error cases.
+*/
+var WebhookVerificationError = class extends PrimitiveWebhookError {
+	code;
+	suggestion;
+	constructor(code, message, suggestion) {
+		super(message ?? VERIFICATION_ERRORS[code].message);
+		this.name = "WebhookVerificationError";
+		this.code = code;
+		this.suggestion = suggestion ?? VERIFICATION_ERRORS[code].suggestion;
+	}
+};
+/**
+* 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.
+*/
+var WebhookPayloadError = class extends PrimitiveWebhookError {
+	code;
+	suggestion;
+	/** Original error if this wraps another error (e.g., JSON.parse failure) */
+	cause;
+	constructor(code, message, suggestion, cause) {
+		super(message ?? PAYLOAD_ERRORS[code].message);
+		this.name = "WebhookPayloadError";
+		this.code = code;
+		this.suggestion = suggestion ?? PAYLOAD_ERRORS[code].suggestion;
+		this.cause = cause;
+	}
+};
+/**
+* Error thrown when schema validation fails.
+*/
+var WebhookValidationError = class extends PrimitiveWebhookError {
+	code = "SCHEMA_VALIDATION_FAILED";
+	suggestion;
+	/** The specific field path that failed (e.g., "email.headers.from") */
+	field;
+	/** Original schema validation errors for advanced debugging */
+	validationErrors;
+	/** Number of additional validation errors beyond the first */
+	additionalErrorCount;
+	constructor(field, message, suggestion, validationErrors) {
+		super(message);
+		this.name = "WebhookValidationError";
+		this.field = field;
+		this.suggestion = suggestion;
+		this.validationErrors = validationErrors;
+		this.additionalErrorCount = Math.max(0, validationErrors.length - 1);
+	}
+	/**
+	* Formats the error for logging/display.
+	* Includes error count and suggestion.
+	*/
+	toString() {
+		let output = `${this.name} [${this.code}]: ${this.message}`;
+		if (this.additionalErrorCount > 0) output += ` (and ${this.additionalErrorCount} more validation error${this.additionalErrorCount > 1 ? "s" : ""})`;
+		output += `\n\nSuggestion: ${this.suggestion}`;
+		return output;
+	}
+	/**
+	* Serializes cleanly for structured logging (Datadog, CloudWatch, etc.)
+	*/
+	toJSON() {
+		return {
+			name: this.name,
+			code: this.code,
+			field: this.field,
+			message: this.message,
+			suggestion: this.suggestion,
+			additionalErrorCount: this.additionalErrorCount
+		};
+	}
+};
+/**
+* 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
+*/
+var RawEmailDecodeError = class extends PrimitiveWebhookError {
+	code;
+	suggestion;
+	constructor(code, message) {
+		super(message ?? RAW_EMAIL_ERRORS[code].message);
+		this.name = "RawEmailDecodeError";
+		this.code = code;
+		this.suggestion = RAW_EMAIL_ERRORS[code].suggestion;
+	}
+};
+//#endregion
+export { VERIFICATION_ERRORS as a, WebhookVerificationError as c, formatAddress as d, normalizeReceivedEmail as f, RawEmailDecodeError as i, buildForwardSubject as l, PrimitiveWebhookError as n, WebhookPayloadError as o, parseHeaderAddress as p, RAW_EMAIL_ERRORS as r, WebhookValidationError as s, PAYLOAD_ERRORS as t, buildReplySubject as u };

package/dist/{index-CDlwyxdp.d.ts → index-Dbx9udpX.d.ts}

@@ -1,214 +1,6 @@
 import { N as WebhookEvent, j as ValidateEmailAuthResult, l as EmailAuth, u as EmailReceivedEvent } from "./types-9vXGZjPd.js";
-import { t as ReceivedEmail } from "./received-email-DNjpq_Wt.js";
-import { ErrorObject } from "ajv";
+import { m as ReceivedEmail, u as WebhookValidationError } from "./errors-C53fe686.js";
 
-//#region src/webhook/errors.d.ts
-/**
- * Verification error definitions.
- * Use these for documentation, dashboards, and i18n.
- */
-declare const VERIFICATION_ERRORS: {
-  readonly INVALID_SIGNATURE_HEADER: {
-    readonly message: "Missing or malformed Primitive-Signature header";
-    readonly suggestion: "Check that you're reading the correct header (Primitive-Signature) and it's being passed correctly from your web framework.";
-  };
-  readonly TIMESTAMP_OUT_OF_RANGE: {
-    readonly message: "Timestamp is too old (possible replay attack)";
-    readonly suggestion: "This could indicate a replay attack, network delay, or server clock drift. Check your server's time is synced.";
-  };
-  readonly SIGNATURE_MISMATCH: {
-    readonly message: "Signature doesn't match expected value";
-    readonly suggestion: "Verify the webhook secret matches and you're using the raw request body (not re-serialized JSON).";
-  };
-  readonly MISSING_SECRET: {
-    readonly message: "No webhook secret was provided";
-    readonly suggestion: "Pass your webhook secret from the Primitive dashboard. Check that the environment variable is set.";
-  };
-};
-/**
- * Payload parsing error definitions.
- * Use these for documentation, dashboards, and i18n.
- */
-declare const PAYLOAD_ERRORS: {
-  readonly PAYLOAD_NULL: {
-    readonly message: "Webhook payload is null";
-    readonly suggestion: "Ensure you're passing the parsed JSON body, not null. Check your framework's body parsing middleware.";
-  };
-  readonly PAYLOAD_UNDEFINED: {
-    readonly message: "Webhook payload is undefined";
-    readonly suggestion: "The payload was not provided. Make sure you're passing the request body to the handler.";
-  };
-  readonly PAYLOAD_WRONG_TYPE: {
-    readonly message: "Webhook payload must be an object";
-    readonly suggestion: "The payload should be a parsed JSON object. Check that you're not passing a string or other primitive.";
-  };
-  readonly PAYLOAD_IS_ARRAY: {
-    readonly message: "Webhook payload is an array, expected object";
-    readonly suggestion: "Primitive webhooks are single event objects, not arrays. Check the payload structure.";
-  };
-  readonly PAYLOAD_MISSING_EVENT: {
-    readonly message: "Webhook payload missing 'event' field";
-    readonly suggestion: "All webhook payloads must have an 'event' field. This may not be a valid Primitive webhook.";
-  };
-  readonly PAYLOAD_UNKNOWN_EVENT: {
-    readonly message: "Unknown webhook event type";
-    readonly suggestion: "This event type is not recognized. You may need to update your SDK or handle unknown events gracefully.";
-  };
-  readonly PAYLOAD_EMPTY_BODY: {
-    readonly message: "Request body is empty";
-    readonly suggestion: "The request body was empty. Ensure the webhook is sending data and your framework is parsing it correctly.";
-  };
-  readonly JSON_PARSE_FAILED: {
-    readonly message: "Failed to parse JSON body";
-    readonly suggestion: "The request body is not valid JSON. Check the raw body content and Content-Type header.";
-  };
-  readonly INVALID_ENCODING: {
-    readonly message: "Invalid body encoding";
-    readonly suggestion: "The request body encoding is not supported. Primitive webhooks use UTF-8 encoded JSON.";
-  };
-};
-/**
- * Raw email decode error definitions.
- * Use these for documentation, dashboards, and i18n.
- */
-declare const RAW_EMAIL_ERRORS: {
-  readonly NOT_INCLUDED: {
-    readonly message: "Raw email content not included inline";
-    readonly suggestion: "Use the download URL at event.email.content.download.url to fetch the raw email.";
-  };
-  readonly INVALID_BASE64: {
-    readonly message: "Raw email content is not valid base64";
-    readonly suggestion: "The raw email data is malformed. Fetch the raw email from the download URL or regenerate the webhook payload.";
-  };
-  readonly HASH_MISMATCH: {
-    readonly message: "SHA-256 hash verification failed";
-    readonly suggestion: "The raw email data may be corrupted. Try downloading from the URL instead.";
-  };
-};
-/**
- * All error codes that can be thrown by the SDK.
- */
-type WebhookErrorCode = WebhookVerificationErrorCode | WebhookPayloadErrorCode | WebhookValidationErrorCode | RawEmailDecodeErrorCode;
-type RawEmailDecodeErrorCode = keyof typeof RAW_EMAIL_ERRORS;
-/**
- * Base class for all Primitive webhook errors.
- *
- * Catch this to handle any error from the SDK in a single catch block.
- *
- * @example
- * ```typescript
- * import { handleWebhook, PrimitiveWebhookError } from '@primitivedotdev/sdk';
- *
- * try {
- *   const event = handleWebhook({ body, headers, secret });
- * } catch (err) {
- *   if (err instanceof PrimitiveWebhookError) {
- *     console.error(`[${err.code}] ${err.message}`);
- *     return res.status(400).json({ error: err.code });
- *   }
- *   throw err;
- * }
- * ```
- */
-declare abstract class PrimitiveWebhookError extends Error {
-  /** Programmatic error code for monitoring and handling */
-  abstract readonly code: WebhookErrorCode;
-  /** Actionable guidance for fixing the issue */
-  abstract readonly suggestion: string;
-  /**
-   * Formats the error for logging/display.
-   */
-  toString(): string;
-  /**
-   * Serializes cleanly for structured logging (Datadog, CloudWatch, etc.)
-   */
-  toJSON(): {
-    name: string;
-    code: WebhookErrorCode;
-    message: string;
-    suggestion: string;
-  };
-}
-/**
- * Error codes for webhook verification failures.
- * Derived from VERIFICATION_ERRORS keys.
- */
-type WebhookVerificationErrorCode = keyof typeof VERIFICATION_ERRORS;
-/**
- * Error thrown when webhook signature verification fails.
- *
- * Use the `code` property to programmatically handle specific error cases.
- */
-declare class WebhookVerificationError extends PrimitiveWebhookError {
-  readonly code: WebhookVerificationErrorCode;
-  readonly suggestion: string;
-  constructor(code: WebhookVerificationErrorCode, message?: string, suggestion?: string);
-}
-/**
- * Error codes for webhook payload parsing failures.
- * Derived from PAYLOAD_ERRORS keys.
- */
-type WebhookPayloadErrorCode = keyof typeof PAYLOAD_ERRORS;
-/**
- * Error thrown when webhook payload parsing fails (lightweight parser).
- *
- * Use the `code` property for programmatic handling and monitoring.
- * The `suggestion` property contains actionable guidance for fixing the issue.
- */
-declare class WebhookPayloadError extends PrimitiveWebhookError {
-  readonly code: WebhookPayloadErrorCode;
-  readonly suggestion: string;
-  /** Original error if this wraps another error (e.g., JSON.parse failure) */
-  readonly cause?: Error;
-  constructor(code: WebhookPayloadErrorCode, message?: string, suggestion?: string, cause?: Error);
-}
-/**
- * Error code for schema validation failures.
- */
-type WebhookValidationErrorCode = "SCHEMA_VALIDATION_FAILED";
-/**
- * Error thrown when schema validation fails.
- */
-declare class WebhookValidationError extends PrimitiveWebhookError {
-  readonly code: WebhookValidationErrorCode;
-  readonly suggestion: string;
-  /** The specific field path that failed (e.g., "email.headers.from") */
-  readonly field: string;
-  /** Original schema validation errors for advanced debugging */
-  readonly validationErrors: readonly ErrorObject[];
-  /** Number of additional validation errors beyond the first */
-  readonly additionalErrorCount: number;
-  constructor(field: string, message: string, suggestion: string, validationErrors: readonly ErrorObject[]);
-  /**
-   * Formats the error for logging/display.
-   * Includes error count and suggestion.
-   */
-  toString(): string;
-  /**
-   * Serializes cleanly for structured logging (Datadog, CloudWatch, etc.)
-   */
-  toJSON(): {
-    name: string;
-    code: "SCHEMA_VALIDATION_FAILED";
-    field: string;
-    message: string;
-    suggestion: string;
-    additionalErrorCount: number;
-  };
-}
-/**
- * Error thrown when raw email decoding or verification fails.
- *
- * Use the `code` property to determine the failure reason:
- * - `NOT_INCLUDED`: Raw email not inline, must download from URL
- * - `HASH_MISMATCH`: SHA-256 verification failed, content may be corrupted
- */
-declare class RawEmailDecodeError extends PrimitiveWebhookError {
-  readonly code: RawEmailDecodeErrorCode;
-  readonly suggestion: string;
-  constructor(code: RawEmailDecodeErrorCode, message?: string);
-}
-//#endregion
 //#region src/validation.d.ts
 interface ValidationSuccess<T> {
   success: true;
@@ -1624,4 +1416,4 @@ declare function decodeRawEmail(event: EmailReceivedEvent, options?: DecodeRawEm
  */
 declare function verifyRawEmailDownload(downloaded: Buffer | ArrayBuffer | Uint8Array, event: EmailReceivedEvent): Buffer;
 //#endregion
-export { VerifyOptions as A, PAYLOAD_ERRORS as B, signStandardWebhooksPayload as C, PRIMITIVE_CONFIRMED_HEADER as D, LEGACY_SIGNATURE_HEADER as E, VerifyDownloadTokenResult as F, VERIFICATION_ERRORS as G, RAW_EMAIL_ERRORS as H, generateDownloadToken as I, WebhookPayloadErrorCode as J, WebhookErrorCode as K, verifyDownloadToken as L, verifyWebhookSignature as M, GenerateDownloadTokenOptions as N, PRIMITIVE_SIGNATURE_HEADER as O, VerifyDownloadTokenOptions as P, WebhookVerificationErrorCode as Q, safeValidateEmailReceivedEvent as R, StandardWebhooksVerifyOptions as S, LEGACY_CONFIRMED_HEADER as T, RawEmailDecodeError as U, PrimitiveWebhookError as V, RawEmailDecodeErrorCode as W, WebhookValidationErrorCode as X, WebhookValidationError as Y, WebhookVerificationError as Z, emailReceivedEventJsonSchema as _, confirmedHeaders as a, STANDARD_WEBHOOK_TIMESTAMP_HEADER as b, handleWebhook as c, isRawIncluded as d, parseWebhookEvent as f, validateEmailAuth as g, WEBHOOK_VERSION as h, WebhookHeaders as i, signWebhookPayload as j, SignResult as k, isDownloadExpired as l, verifyRawEmailDownload as m, HandleWebhookOptions as n, decodeRawEmail as o, receive as p, WebhookPayloadError as q, ReceiveRequestOptions as r, getDownloadTimeRemaining as s, DecodeRawEmailOptions as t, isEmailReceivedEvent as u, STANDARD_WEBHOOK_ID_HEADER as v, verifyStandardWebhooksSignature as w, StandardWebhooksSignResult as x, STANDARD_WEBHOOK_SIGNATURE_HEADER as y, validateEmailReceivedEvent as z };
+export { VerifyOptions as A, signStandardWebhooksPayload as C, PRIMITIVE_CONFIRMED_HEADER as D, LEGACY_SIGNATURE_HEADER as E, VerifyDownloadTokenResult as F, generateDownloadToken as I, verifyDownloadToken as L, verifyWebhookSignature as M, GenerateDownloadTokenOptions as N, PRIMITIVE_SIGNATURE_HEADER as O, VerifyDownloadTokenOptions as P, safeValidateEmailReceivedEvent as R, StandardWebhooksVerifyOptions as S, LEGACY_CONFIRMED_HEADER as T, emailReceivedEventJsonSchema as _, confirmedHeaders as a, STANDARD_WEBHOOK_TIMESTAMP_HEADER as b, handleWebhook as c, isRawIncluded as d, parseWebhookEvent as f, validateEmailAuth as g, WEBHOOK_VERSION as h, WebhookHeaders as i, signWebhookPayload as j, SignResult as k, isDownloadExpired as l, verifyRawEmailDownload as m, HandleWebhookOptions as n, decodeRawEmail as o, receive as p, ReceiveRequestOptions as r, getDownloadTimeRemaining as s, DecodeRawEmailOptions as t, isEmailReceivedEvent as u, STANDARD_WEBHOOK_ID_HEADER as v, verifyStandardWebhooksSignature as w, StandardWebhooksSignResult as x, STANDARD_WEBHOOK_SIGNATURE_HEADER as y, validateEmailReceivedEvent as z };