@primitivedotdev/sdk 0.25.0 → 0.25.1

package/dist/webhook/index.js

@@ -1,3 +1,3 @@
-import { a as parseHeaderAddress, i as normalizeReceivedEmail, n as buildReplySubject, r as formatAddress, t as buildForwardSubject } from "../received-email-D6tKtWwW.js";
-import { A as PRIMITIVE_CONFIRMED_HEADER, B as RAW_EMAIL_ERRORS, C as STANDARD_WEBHOOK_ID_HEADER, D as verifyStandardWebhooksSignature, E as signStandardWebhooksPayload, F as verifyDownloadToken, G as WebhookVerificationError, H as VERIFICATION_ERRORS, I as safeValidateEmailReceivedEvent, L as validateEmailReceivedEvent, M as signWebhookPayload, N as verifyWebhookSignature, O as LEGACY_CONFIRMED_HEADER, P as generateDownloadToken, R as PAYLOAD_ERRORS, S as emailReceivedEventJsonSchema, T as STANDARD_WEBHOOK_TIMESTAMP_HEADER, U as WebhookPayloadError, V as RawEmailDecodeError, W as WebhookValidationError, _ as DmarcResult, a as isDownloadExpired, b as ParsedStatus, c as parseWebhookEvent, d as WEBHOOK_VERSION, f as validateEmailAuth, g as DmarcPolicy, h as DkimResult, i as handleWebhook, j as PRIMITIVE_SIGNATURE_HEADER, k as LEGACY_SIGNATURE_HEADER, l as receive, m as AuthVerdict, n as decodeRawEmail, o as isEmailReceivedEvent, p as AuthConfidence, r as getDownloadTimeRemaining, s as isRawIncluded, t as confirmedHeaders, u as verifyRawEmailDownload, v as EventType, w as STANDARD_WEBHOOK_SIGNATURE_HEADER, x as SpfResult, y as ForwardVerdict, z as PrimitiveWebhookError } from "../webhook-rUjGV6Zu.js";
+import { a as VERIFICATION_ERRORS, c as WebhookVerificationError, d as formatAddress, f as normalizeReceivedEmail, i as RawEmailDecodeError, l as buildForwardSubject, n as PrimitiveWebhookError, o as WebhookPayloadError, p as parseHeaderAddress, r as RAW_EMAIL_ERRORS, s as WebhookValidationError, t as PAYLOAD_ERRORS, u as buildReplySubject } from "../errors-x91I_yEt.js";
+import { A as PRIMITIVE_CONFIRMED_HEADER, C as STANDARD_WEBHOOK_ID_HEADER, D as verifyStandardWebhooksSignature, E as signStandardWebhooksPayload, F as verifyDownloadToken, I as safeValidateEmailReceivedEvent, L as validateEmailReceivedEvent, M as signWebhookPayload, N as verifyWebhookSignature, O as LEGACY_CONFIRMED_HEADER, P as generateDownloadToken, S as emailReceivedEventJsonSchema, T as STANDARD_WEBHOOK_TIMESTAMP_HEADER, _ as DmarcResult, a as isDownloadExpired, b as ParsedStatus, c as parseWebhookEvent, d as WEBHOOK_VERSION, f as validateEmailAuth, g as DmarcPolicy, h as DkimResult, i as handleWebhook, j as PRIMITIVE_SIGNATURE_HEADER, k as LEGACY_SIGNATURE_HEADER, l as receive, m as AuthVerdict, n as decodeRawEmail, o as isEmailReceivedEvent, p as AuthConfidence, r as getDownloadTimeRemaining, s as isRawIncluded, t as confirmedHeaders, u as verifyRawEmailDownload, v as EventType, w as STANDARD_WEBHOOK_SIGNATURE_HEADER, x as SpfResult, y as ForwardVerdict } from "../webhook-DJkfUnFZ.js";
 export { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, buildForwardSubject, buildReplySubject, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, formatAddress, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, normalizeReceivedEmail, parseHeaderAddress, parseWebhookEvent, receive, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };

package/dist/{webhook-rUjGV6Zu.js → webhook-DJkfUnFZ.js}

@@ -1,4 +1,4 @@
-import { i as normalizeReceivedEmail } from "./received-email-D6tKtWwW.js";
+import { c as WebhookVerificationError, f as normalizeReceivedEmail, i as RawEmailDecodeError, o as WebhookPayloadError, s as WebhookValidationError } from "./errors-x91I_yEt.js";
 import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 //#region src/generated/email-received-event.validator.generated.ts
 /**
@@ -5632,224 +5632,6 @@ function validate10(data, { instancePath = "", parentData, parentDataProperty, r
 	return errors === 0;
 }
 //#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
 //#region src/validation.ts
 const validateSchema = email_received_event_validator_generated_default;
 function toFieldPath(instancePath) {
@@ -8041,4 +7823,4 @@ function verifyRawEmailDownload(downloaded, event) {
 	return buffer;
 }
 //#endregion
-export { PRIMITIVE_CONFIRMED_HEADER as A, RAW_EMAIL_ERRORS as B, STANDARD_WEBHOOK_ID_HEADER as C, verifyStandardWebhooksSignature as D, signStandardWebhooksPayload as E, verifyDownloadToken as F, WebhookVerificationError as G, VERIFICATION_ERRORS as H, safeValidateEmailReceivedEvent as I, validateEmailReceivedEvent as L, signWebhookPayload as M, verifyWebhookSignature as N, LEGACY_CONFIRMED_HEADER as O, generateDownloadToken as P, PAYLOAD_ERRORS as R, emailReceivedEventJsonSchema as S, STANDARD_WEBHOOK_TIMESTAMP_HEADER as T, WebhookPayloadError as U, RawEmailDecodeError as V, WebhookValidationError as W, DmarcResult as _, isDownloadExpired as a, ParsedStatus as b, parseWebhookEvent as c, WEBHOOK_VERSION as d, validateEmailAuth as f, DmarcPolicy as g, DkimResult as h, handleWebhook as i, PRIMITIVE_SIGNATURE_HEADER as j, LEGACY_SIGNATURE_HEADER as k, receive as l, AuthVerdict as m, decodeRawEmail as n, isEmailReceivedEvent as o, AuthConfidence as p, getDownloadTimeRemaining as r, isRawIncluded as s, confirmedHeaders as t, verifyRawEmailDownload as u, EventType as v, STANDARD_WEBHOOK_SIGNATURE_HEADER as w, SpfResult as x, ForwardVerdict as y, PrimitiveWebhookError as z };
+export { PRIMITIVE_CONFIRMED_HEADER as A, STANDARD_WEBHOOK_ID_HEADER as C, verifyStandardWebhooksSignature as D, signStandardWebhooksPayload as E, verifyDownloadToken as F, safeValidateEmailReceivedEvent as I, validateEmailReceivedEvent as L, signWebhookPayload as M, verifyWebhookSignature as N, LEGACY_CONFIRMED_HEADER as O, generateDownloadToken as P, emailReceivedEventJsonSchema as S, STANDARD_WEBHOOK_TIMESTAMP_HEADER as T, DmarcResult as _, isDownloadExpired as a, ParsedStatus as b, parseWebhookEvent as c, WEBHOOK_VERSION as d, validateEmailAuth as f, DmarcPolicy as g, DkimResult as h, handleWebhook as i, PRIMITIVE_SIGNATURE_HEADER as j, LEGACY_SIGNATURE_HEADER as k, receive as l, AuthVerdict as m, decodeRawEmail as n, isEmailReceivedEvent as o, AuthConfidence as p, getDownloadTimeRemaining as r, isRawIncluded as s, confirmedHeaders as t, verifyRawEmailDownload as u, EventType as v, STANDARD_WEBHOOK_SIGNATURE_HEADER as w, SpfResult as x, ForwardVerdict as y };

package/oclif.manifest.json

@@ -4304,5 +4304,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.25.0"
+  "version": "0.25.1"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/sdk",
-  "version": "0.25.0",
+  "version": "0.25.1",
   "description": "Official Primitive Node.js SDK: webhook, api, openapi, contract, and parser runtime modules. The CLI moved to @primitivedotdev/cli; this package retains the CLI as a deprecated alias for a few minor releases.",
   "type": "module",
   "module": "./dist/index.js",

package/dist/received-email-D6tKtWwW.js

@@ -1,69 +0,0 @@
-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
-export { parseHeaderAddress as a, normalizeReceivedEmail as i, buildReplySubject as n, formatAddress as r, buildForwardSubject as t };

package/dist/received-email-DNjpq_Wt.d.ts

@@ -1,37 +0,0 @@
-import { M as WebhookAttachment, c as EmailAnalysis, l as EmailAuth, u as EmailReceivedEvent } from "./types-9vXGZjPd.js";
-
-//#region src/webhook/received-email.d.ts
-interface ReceivedEmailAddress {
-  address: string;
-  name: string | null;
-}
-interface ReceivedEmailThread {
-  messageId: string | null;
-  inReplyTo: string[];
-  references: string[];
-}
-interface ReceivedEmail {
-  id: string;
-  eventId: string;
-  receivedAt: string;
-  sender: ReceivedEmailAddress;
-  replyTarget: ReceivedEmailAddress;
-  receivedBy: string;
-  receivedByAll: string[];
-  subject: string | null;
-  replySubject: string;
-  forwardSubject: string;
-  text: string | null;
-  thread: ReceivedEmailThread;
-  attachments: WebhookAttachment[];
-  auth: EmailAuth;
-  analysis: EmailAnalysis;
-  raw: EmailReceivedEvent;
-}
-declare function normalizeReceivedEmail(event: EmailReceivedEvent): ReceivedEmail;
-declare function buildReplySubject(subject: string | null | undefined): string;
-declare function buildForwardSubject(subject: string | null | undefined): string;
-declare function formatAddress(address: ReceivedEmailAddress): string;
-declare function parseHeaderAddress(value: string | null | undefined): ReceivedEmailAddress | null;
-//#endregion
-export { buildReplySubject as a, parseHeaderAddress as c, buildForwardSubject as i, ReceivedEmailAddress as n, formatAddress as o, ReceivedEmailThread as r, normalizeReceivedEmail as s, ReceivedEmail as t };