@primitivedotdev/sdk 0.6.0 → 0.8.0

package/dist/parser/address-parser.js

@@ -0,0 +1,129 @@
+import addressparser from "nodemailer/lib/addressparser/index.js";
+import isEmail from "validator/lib/isEmail.js";
+// Per RFC 5322 §2.1.1, header lines are bounded at 998 octets. We measure
+// in UTF-8 bytes, not JS code units, so SMTPUTF8 (RFC 6531) headers with
+// multi-byte characters cannot bypass the cap by being short on chars but
+// long on bytes. Reject anything beyond as malformed without parsing: a
+// longer From field is either a header-injection probe or a corrupt feed.
+const MAX_HEADER_LENGTH = 998;
+// Options for validator's isEmail. The per-part length limits (64-octet
+// local-part, 255-octet domain), dot-atom rules, hostname-label rules,
+// and TLD requirement are all enforced inside isEmail. We choose:
+//   allow_ip_domain: true     -- accept user@[192.168.1.1] address-literals
+//   require_tld: true         -- reject user@localhost
+//   allow_display_name: false -- we already extracted the address with
+//                                addressparser, so isEmail only sees the
+//                                bare addr-spec
+//   allow_utf8_local_part: true -- accept SMTPUTF8 / EAI local-parts
+const IS_EMAIL_OPTIONS = {
+    allow_ip_domain: true,
+    require_tld: true,
+    allow_display_name: false,
+    allow_utf8_local_part: true,
+};
+/**
+ * Strict parser for RFC 5322 From-style headers in security-bearing
+ * contexts (allowlist gates, permission grants).
+ *
+ * Rejects, without falling back to a "best guess":
+ *   - empty / whitespace-only input
+ *   - inputs longer than RFC 5322's 998-octet line limit
+ *   - multi-address From (RFC 5322 allows it but it is vanishingly
+ *     rare and ambiguous as an identity)
+ *   - group syntax ("Friends: a@b.com, c@d.com;")
+ *   - any address that fails validator's isEmail check with our chosen
+ *     options. That covers per-part length limits, dot-atom rules,
+ *     hostname-label rules, TLD requirement, and other RFC 5321/5322
+ *     conformance checks.
+ *
+ * Returns ONLY the validated address, with no display name. Strict
+ * exists for gating decisions, where the address is the security-
+ * bearing field. Display names from addressparser are not trustworthy
+ * here: weird inputs like `Name <user@x.com> <attacker@y.com>` get
+ * parsed as a single entry whose `name` silently includes the second
+ * address. Surfacing that as a "parsed name" would invite downstream
+ * misuse, so we drop it. If you need the name, call
+ * {@link parseFromHeaderLoose} alongside (it returns null on failure
+ * anyway, so you can still gate on strict's Result).
+ *
+ * Returns a typed Result so callers can map the failure reason to
+ * stable error codes without inspecting message text.
+ */
+export function parseFromHeader(header) {
+    if (header === null || header === undefined) {
+        return { ok: false, reason: "empty" };
+    }
+    const trimmed = header.trim();
+    if (trimmed.length === 0) {
+        return { ok: false, reason: "empty" };
+    }
+    if (Buffer.byteLength(trimmed, "utf8") > MAX_HEADER_LENGTH) {
+        return { ok: false, reason: "too_long" };
+    }
+    // Default (no flatten) so group entries surface as { name, group: [] }
+    // rather than being silently merged into the address list.
+    const parsed = addressparser(trimmed);
+    if (parsed.length > 1) {
+        return { ok: false, reason: "multiple_addresses" };
+    }
+    const entry = parsed[0];
+    // addressparser returns a single entry with empty `address` for raw
+    // garbage rather than an empty array, so an empty result is only
+    // possible for inputs that already failed our trim/empty check above.
+    // The defensive fall-through maps any future regression to
+    // invalid_address rather than crashing on parsed[0].
+    if (entry === undefined) {
+        return { ok: false, reason: "invalid_address" };
+    }
+    if ("group" in entry) {
+        return { ok: false, reason: "group_syntax" };
+    }
+    const address = entry.address;
+    if (address === undefined || !isEmail(address, IS_EMAIL_OPTIONS)) {
+        return { ok: false, reason: "invalid_address" };
+    }
+    return {
+        ok: true,
+        value: { address: address.toLowerCase() },
+    };
+}
+/**
+ * Lenient parser for display-only call sites (inbox card "from",
+ * log lines, debugging). Returns the first parseable address with its
+ * display name, or null.
+ *
+ * Differences from {@link parseFromHeader}:
+ *   - Multi-address From returns the first address instead of rejecting
+ *   - Group syntax is flattened into its member addresses
+ *   - Returns null instead of a typed reason on failure
+ *   - Includes the parsed display name in the result
+ *
+ * Do not use for permission gates or any decision that grants access.
+ * That is what {@link parseFromHeader} is for. Names returned here can
+ * include addressparser's recovery output (trailing tokens, garbage
+ * before the address); treat as opaque text for display.
+ */
+export function parseFromHeaderLoose(header) {
+    if (header === null || header === undefined) {
+        return null;
+    }
+    const trimmed = header.trim();
+    if (trimmed.length === 0 ||
+        Buffer.byteLength(trimmed, "utf8") > MAX_HEADER_LENGTH) {
+        return null;
+    }
+    const parsed = addressparser(trimmed);
+    for (const entry of parsed) {
+        const candidates = "group" in entry && Array.isArray(entry.group) ? entry.group : [entry];
+        for (const candidate of candidates) {
+            const address = candidate.address;
+            if (address !== undefined && isEmail(address, IS_EMAIL_OPTIONS)) {
+                return {
+                    address: address.toLowerCase(),
+                    name: candidate.name && candidate.name.length > 0 ? candidate.name : null,
+                };
+            }
+        }
+    }
+    return null;
+}

package/dist/parser/index.d.ts

@@ -1,5 +1,105 @@
-import { EmailAddress, ParsedDataComplete, WebhookAttachment } from "../types-CKFmgitP.js";
+import { EmailAddress, ParsedDataComplete, WebhookAttachment } from "../types-CIOzt1FY.js";
 
+//#region src/parser/address-parser.d.ts
+/**
+* A validated RFC 5322 address. Returned by the strict parser, which
+* deliberately does not expose a display name.
+*
+* `address` is normalized to lowercase. Both the local-part and the
+* domain are lowercased: RFC 5321 §2.4 permits case-sensitive local-
+* parts, but every consumer mailbox in practice treats them as
+* case-insensitive, and a case-sensitive grant key would split
+* `Bob@x.com` from `bob@x.com` into separate rows and defeat the
+* primary-key index on lookup.
+*/
+/**
+ * A validated RFC 5322 address. Returned by the strict parser, which
+ * deliberately does not expose a display name.
+ *
+ * `address` is normalized to lowercase. Both the local-part and the
+ * domain are lowercased: RFC 5321 §2.4 permits case-sensitive local-
+ * parts, but every consumer mailbox in practice treats them as
+ * case-insensitive, and a case-sensitive grant key would split
+ * `Bob@x.com` from `bob@x.com` into separate rows and defeat the
+ * primary-key index on lookup.
+ */
+interface ValidatedAddress {
+  address: string;
+}
+/**
+ * A parsed RFC 5322 address with its display name. Returned by the
+ * loose parser for display-only call sites.
+ *
+ * `address` is lowercased on the same rationale as
+ * {@link ValidatedAddress}. The display name is preserved as provided
+ * (after addressparser's quote / encoded-word handling), or null if the
+ * header had no display name. Names from the loose parser are NOT
+ * trustworthy for downstream mail building: addressparser's recovery
+ * mode can fold trailing tokens or a second bracketed address into the
+ * name field. Treat as opaque text, sanitize before re-emitting.
+ */
+interface ParsedAddress {
+  address: string;
+  name: string | null;
+}
+/**
+ * Reason a strict From-header parse rejected the input. Stable enum so
+ * callers can branch on the reason without parsing message text.
+ */
+type ParseFromHeaderFailureReason = "empty" | "too_long" | "multiple_addresses" | "group_syntax" | "invalid_address";
+type ParseFromHeaderResult = {
+  ok: true;
+  value: ValidatedAddress;
+} | {
+  ok: false;
+  reason: ParseFromHeaderFailureReason;
+};
+/**
+ * Strict parser for RFC 5322 From-style headers in security-bearing
+ * contexts (allowlist gates, permission grants).
+ *
+ * Rejects, without falling back to a "best guess":
+ *   - empty / whitespace-only input
+ *   - inputs longer than RFC 5322's 998-octet line limit
+ *   - multi-address From (RFC 5322 allows it but it is vanishingly
+ *     rare and ambiguous as an identity)
+ *   - group syntax ("Friends: a@b.com, c@d.com;")
+ *   - any address that fails validator's isEmail check with our chosen
+ *     options. That covers per-part length limits, dot-atom rules,
+ *     hostname-label rules, TLD requirement, and other RFC 5321/5322
+ *     conformance checks.
+ *
+ * Returns ONLY the validated address, with no display name. Strict
+ * exists for gating decisions, where the address is the security-
+ * bearing field. Display names from addressparser are not trustworthy
+ * here: weird inputs like `Name <user@x.com> <attacker@y.com>` get
+ * parsed as a single entry whose `name` silently includes the second
+ * address. Surfacing that as a "parsed name" would invite downstream
+ * misuse, so we drop it. If you need the name, call
+ * {@link parseFromHeaderLoose} alongside (it returns null on failure
+ * anyway, so you can still gate on strict's Result).
+ *
+ * Returns a typed Result so callers can map the failure reason to
+ * stable error codes without inspecting message text.
+ */
+declare function parseFromHeader(header: string | null | undefined): ParseFromHeaderResult;
+/**
+ * Lenient parser for display-only call sites (inbox card "from",
+ * log lines, debugging). Returns the first parseable address with its
+ * display name, or null.
+ *
+ * Differences from {@link parseFromHeader}:
+ *   - Multi-address From returns the first address instead of rejecting
+ *   - Group syntax is flattened into its member addresses
+ *   - Returns null instead of a typed reason on failure
+ *   - Includes the parsed display name in the result
+ *
+ * Do not use for permission gates or any decision that grants access.
+ * That is what {@link parseFromHeader} is for. Names returned here can
+ * include addressparser's recovery output (trailing tokens, garbage
+ * before the address); treat as opaque text for display.
+ */
+declare function parseFromHeaderLoose(header: string | null | undefined): ParsedAddress | null; //#endregion
 //#region src/parser/attachment-parser.d.ts
 interface ParsedAttachment {
   id: string;
@@ -61,7 +161,9 @@ declare function sha256Hex(buffer: Buffer): string;
  * Sanitize a filename for safe use in Content-Disposition headers.
  * Prevents path traversal, removes control characters, enforces length limits.
  */
-declare function sanitizeFilename(filename: string | null, partIndex: number): string; //#endregion
+declare function sanitizeFilename(filename: string | null, partIndex: number): string;
+
+//#endregion
 //#region src/parser/attachment-bundler.d.ts
 /**
  * Result of bundling attachments into a tar.gz archive
@@ -187,4 +289,4 @@ declare function toCanonicalHeaders(parsed: ParsedEmailWithAttachments): {
 declare function sanitizeHtml(html: string): string;
 
 //#endregion
-export { AttachmentMetadata, BundleResult, ParsedAttachment, ParsedEmail, ParsedEmailWithAttachments, attachmentMetadataToWebhookAttachments, bundleAttachments, extractAttachmentMetadata, getAttachmentsStorageKey, normalizeContentType, parseEmail, parseEmailWithAttachments, sanitizeFilename, sanitizeHtml, sha256Hex, toCanonicalHeaders, toParsedDataComplete, toWebhookAttachments };
+export { AttachmentMetadata, BundleResult, ParseFromHeaderFailureReason, ParseFromHeaderResult, ParsedAddress, ParsedAttachment, ParsedEmail, ParsedEmailWithAttachments, ValidatedAddress, attachmentMetadataToWebhookAttachments, bundleAttachments, extractAttachmentMetadata, getAttachmentsStorageKey, normalizeContentType, parseEmail, parseEmailWithAttachments, parseFromHeader, parseFromHeaderLoose, sanitizeFilename, sanitizeHtml, sha256Hex, toCanonicalHeaders, toParsedDataComplete, toWebhookAttachments };

package/dist/parser/index.js

@@ -1,3 +1,4 @@
+import { parseFromHeader, parseFromHeaderLoose } from "../address-parser-CfPHs3mE.js";
 import { createHash } from "node:crypto";
 import { createGzip } from "node:zlib";
 import { pack } from "tar-stream";
@@ -557,4 +558,4 @@ function requireNonEmptyHeader(value, headerName) {
 }
 
 //#endregion
-export { attachmentMetadataToWebhookAttachments, bundleAttachments, extractAttachmentMetadata, getAttachmentsStorageKey, normalizeContentType, parseEmail, parseEmailWithAttachments, sanitizeFilename, sanitizeHtml, sha256Hex, toCanonicalHeaders, toParsedDataComplete, toWebhookAttachments };
+export { attachmentMetadataToWebhookAttachments, bundleAttachments, extractAttachmentMetadata, getAttachmentsStorageKey, normalizeContentType, parseEmail, parseEmailWithAttachments, parseFromHeader, parseFromHeaderLoose, sanitizeFilename, sanitizeHtml, sha256Hex, toCanonicalHeaders, toParsedDataComplete, toWebhookAttachments };

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

@@ -0,0 +1,36 @@
+import { EmailAnalysis, EmailAuth, EmailReceivedEvent, WebhookAttachment } from "./types-CIOzt1FY.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 { ReceivedEmail, ReceivedEmailAddress, ReceivedEmailThread, buildForwardSubject as buildForwardSubject$1, buildReplySubject as buildReplySubject$1, formatAddress as formatAddress$1, normalizeReceivedEmail as normalizeReceivedEmail$1, parseHeaderAddress as parseHeaderAddress$1 };

package/dist/received-email-Q6Cha3wc.js

@@ -0,0 +1,71 @@
+import { parseFromHeaderLoose } from "./address-parser-CfPHs3mE.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 { buildForwardSubject, buildReplySubject, formatAddress, normalizeReceivedEmail, parseHeaderAddress };

package/dist/types.generated.js

@@ -0,0 +1,7 @@
+/**
+ * Types for Primitive webhook payloads.
+ *
+ * AUTO-GENERATED - DO NOT EDIT
+ * Run `pnpm generate:types` to regenerate.
+ */
+export {};

package/dist/types.js

@@ -0,0 +1,53 @@
+/**
+ * Primitive webhook event types derived from the canonical JSON schema.
+ *
+ * @packageDocumentation
+ */
+export const EventType = {
+    EmailReceived: "email.received",
+};
+export const ParsedStatus = {
+    Complete: "complete",
+    Failed: "failed",
+};
+export const ForwardVerdict = {
+    Legit: "legit",
+    Unknown: "unknown",
+};
+export const SpfResult = {
+    Pass: "pass",
+    Fail: "fail",
+    Softfail: "softfail",
+    Neutral: "neutral",
+    None: "none",
+    Temperror: "temperror",
+    Permerror: "permerror",
+};
+export const DmarcResult = {
+    Pass: "pass",
+    Fail: "fail",
+    None: "none",
+    Temperror: "temperror",
+    Permerror: "permerror",
+};
+export const DmarcPolicy = {
+    Reject: "reject",
+    Quarantine: "quarantine",
+    None: "none",
+};
+export const DkimResult = {
+    Pass: "pass",
+    Fail: "fail",
+    Temperror: "temperror",
+    Permerror: "permerror",
+};
+export const AuthConfidence = {
+    High: "high",
+    Medium: "medium",
+    Low: "low",
+};
+export const AuthVerdict = {
+    Legit: "legit",
+    Suspicious: "suspicious",
+    Unknown: "unknown",
+};

package/dist/webhook/index.d.ts

@@ -1,3 +1,4 @@
-import { AuthConfidence$1 as AuthConfidence, AuthVerdict$1 as AuthVerdict, DkimResult$1 as DkimResult, DkimSignature, DmarcPolicy$1 as DmarcPolicy, DmarcResult$1 as DmarcResult, EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EventType$1 as EventType, ForwardAnalysis, ForwardOriginalSender, ForwardResult, ForwardResultAttachmentAnalyzed, ForwardResultAttachmentSkipped, ForwardResultInline, ForwardVerdict$1 as ForwardVerdict, ForwardVerification, KnownWebhookEvent, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus$1 as ParsedStatus, RawContent, RawContentDownloadOnly, RawContentInline, SpfResult$1 as SpfResult, UnknownEvent, ValidateEmailAuthResult, WebhookAttachment, WebhookEvent } from "../types-CKFmgitP.js";
-import { DecodeRawEmailOptions, GenerateDownloadTokenOptions, HandleWebhookOptions, LEGACY_CONFIRMED_HEADER$1 as LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER$1 as LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS$1 as PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER$1 as PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER$1 as PRIMITIVE_SIGNATURE_HEADER, PrimitiveWebhookError$1 as PrimitiveWebhookError, RAW_EMAIL_ERRORS$1 as RAW_EMAIL_ERRORS, RawEmailDecodeError$1 as RawEmailDecodeError, RawEmailDecodeErrorCode, STANDARD_WEBHOOK_ID_HEADER$1 as STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER$1 as STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER$1 as STANDARD_WEBHOOK_TIMESTAMP_HEADER, SignResult, StandardWebhooksSignResult, StandardWebhooksVerifyOptions, VERIFICATION_ERRORS$1 as VERIFICATION_ERRORS, VerifyDownloadTokenOptions, VerifyDownloadTokenResult, VerifyOptions, WEBHOOK_VERSION$1 as WEBHOOK_VERSION, WebhookErrorCode, WebhookHeaders, WebhookPayloadError$1 as WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError$1 as WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError$1 as WebhookVerificationError, WebhookVerificationErrorCode, confirmedHeaders$1 as confirmedHeaders, decodeRawEmail$1 as decodeRawEmail, emailReceivedEventJsonSchema$1 as emailReceivedEventJsonSchema, generateDownloadToken$1 as generateDownloadToken, getDownloadTimeRemaining$1 as getDownloadTimeRemaining, handleWebhook$1 as handleWebhook, isDownloadExpired$1 as isDownloadExpired, isEmailReceivedEvent$1 as isEmailReceivedEvent, isRawIncluded$1 as isRawIncluded, parseWebhookEvent$1 as parseWebhookEvent, safeValidateEmailReceivedEvent$1 as safeValidateEmailReceivedEvent, signStandardWebhooksPayload$1 as signStandardWebhooksPayload, signWebhookPayload$1 as signWebhookPayload, validateEmailAuth$1 as validateEmailAuth, validateEmailReceivedEvent$1 as validateEmailReceivedEvent, verifyDownloadToken$1 as verifyDownloadToken, verifyRawEmailDownload$1 as verifyRawEmailDownload, verifyStandardWebhooksSignature$1 as verifyStandardWebhooksSignature, verifyWebhookSignature$1 as verifyWebhookSignature } from "../index-DLmAI4UQ.js";
-export { AuthConfidence, AuthVerdict, DecodeRawEmailOptions, DkimResult, DkimSignature, DmarcPolicy, DmarcResult, EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EventType, ForwardAnalysis, ForwardOriginalSender, ForwardResult, ForwardResultAttachmentAnalyzed, ForwardResultAttachmentSkipped, ForwardResultInline, ForwardVerdict, ForwardVerification, GenerateDownloadTokenOptions, HandleWebhookOptions, KnownWebhookEvent, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawContent, RawContentDownloadOnly, RawContentInline, RawEmailDecodeError, RawEmailDecodeErrorCode, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SignResult, SpfResult, StandardWebhooksSignResult, StandardWebhooksVerifyOptions, UnknownEvent, VERIFICATION_ERRORS, ValidateEmailAuthResult, VerifyDownloadTokenOptions, VerifyDownloadTokenResult, VerifyOptions, WEBHOOK_VERSION, WebhookAttachment, WebhookErrorCode, WebhookEvent, WebhookHeaders, WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError, WebhookVerificationErrorCode, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };
+import { AuthConfidence$1 as AuthConfidence, AuthVerdict$1 as AuthVerdict, DkimResult$1 as DkimResult, DkimSignature, DmarcPolicy$1 as DmarcPolicy, DmarcResult$1 as DmarcResult, EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EventType$1 as EventType, ForwardAnalysis, ForwardOriginalSender, ForwardResult, ForwardResultAttachmentAnalyzed, ForwardResultAttachmentSkipped, ForwardResultInline, ForwardVerdict$1 as ForwardVerdict, ForwardVerification, KnownWebhookEvent, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus$1 as ParsedStatus, RawContent, RawContentDownloadOnly, RawContentInline, SpfResult$1 as SpfResult, UnknownEvent, ValidateEmailAuthResult, WebhookAttachment, WebhookEvent } from "../types-CIOzt1FY.js";
+import { ReceivedEmail, ReceivedEmailAddress, ReceivedEmailThread, buildForwardSubject$1 as buildForwardSubject, buildReplySubject$1 as buildReplySubject, formatAddress$1 as formatAddress, normalizeReceivedEmail$1 as normalizeReceivedEmail, parseHeaderAddress$1 as parseHeaderAddress } from "../received-email-C67Z7Dha.js";
+import { DecodeRawEmailOptions, GenerateDownloadTokenOptions, HandleWebhookOptions, LEGACY_CONFIRMED_HEADER$1 as LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER$1 as LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS$1 as PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER$1 as PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER$1 as PRIMITIVE_SIGNATURE_HEADER, PrimitiveWebhookError$1 as PrimitiveWebhookError, RAW_EMAIL_ERRORS$1 as RAW_EMAIL_ERRORS, RawEmailDecodeError$1 as RawEmailDecodeError, RawEmailDecodeErrorCode, ReceiveRequestOptions, STANDARD_WEBHOOK_ID_HEADER$1 as STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER$1 as STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER$1 as STANDARD_WEBHOOK_TIMESTAMP_HEADER, SignResult, StandardWebhooksSignResult, StandardWebhooksVerifyOptions, VERIFICATION_ERRORS$1 as VERIFICATION_ERRORS, VerifyDownloadTokenOptions, VerifyDownloadTokenResult, VerifyOptions, WEBHOOK_VERSION$1 as WEBHOOK_VERSION, WebhookErrorCode, WebhookHeaders, WebhookPayloadError$1 as WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError$1 as WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError$1 as WebhookVerificationError, WebhookVerificationErrorCode, confirmedHeaders$1 as confirmedHeaders, decodeRawEmail$1 as decodeRawEmail, emailReceivedEventJsonSchema$1 as emailReceivedEventJsonSchema, generateDownloadToken$1 as generateDownloadToken, getDownloadTimeRemaining$1 as getDownloadTimeRemaining, handleWebhook$1 as handleWebhook, isDownloadExpired$1 as isDownloadExpired, isEmailReceivedEvent$1 as isEmailReceivedEvent, isRawIncluded$1 as isRawIncluded, parseWebhookEvent$1 as parseWebhookEvent, receive$1 as receive, safeValidateEmailReceivedEvent$1 as safeValidateEmailReceivedEvent, signStandardWebhooksPayload$1 as signStandardWebhooksPayload, signWebhookPayload$1 as signWebhookPayload, validateEmailAuth$1 as validateEmailAuth, validateEmailReceivedEvent$1 as validateEmailReceivedEvent, verifyDownloadToken$1 as verifyDownloadToken, verifyRawEmailDownload$1 as verifyRawEmailDownload, verifyStandardWebhooksSignature$1 as verifyStandardWebhooksSignature, verifyWebhookSignature$1 as verifyWebhookSignature } from "../index-CuuP1JkG.js";
+export { AuthConfidence, AuthVerdict, DecodeRawEmailOptions, DkimResult, DkimSignature, DmarcPolicy, DmarcResult, EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EventType, ForwardAnalysis, ForwardOriginalSender, ForwardResult, ForwardResultAttachmentAnalyzed, ForwardResultAttachmentSkipped, ForwardResultInline, ForwardVerdict, ForwardVerification, GenerateDownloadTokenOptions, HandleWebhookOptions, KnownWebhookEvent, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawContent, RawContentDownloadOnly, RawContentInline, RawEmailDecodeError, RawEmailDecodeErrorCode, ReceiveRequestOptions, ReceivedEmail, ReceivedEmailAddress, ReceivedEmailThread, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SignResult, SpfResult, StandardWebhooksSignResult, StandardWebhooksVerifyOptions, UnknownEvent, VERIFICATION_ERRORS, ValidateEmailAuthResult, VerifyDownloadTokenOptions, VerifyDownloadTokenResult, VerifyOptions, WEBHOOK_VERSION, WebhookAttachment, WebhookErrorCode, WebhookEvent, WebhookHeaders, WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError, WebhookVerificationErrorCode, 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/index.js

@@ -1,3 +1,5 @@
-import { 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, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature } from "../webhook-COe5N_Uj.js";
+import "../address-parser-CfPHs3mE.js";
+import { buildForwardSubject, buildReplySubject, formatAddress, normalizeReceivedEmail, parseHeaderAddress } from "../received-email-Q6Cha3wc.js";
+import { 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, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, receive, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature } from "../webhook-2TALcBQz.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, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };
+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/received-email.js

@@ -0,0 +1,82 @@
+import { parseFromHeaderLoose } from "../parser/address-parser.js";
+const REPLY_PREFIX_RE = /^re\s*:/i;
+const FORWARD_PREFIX_RE = /^(fwd?|fw)\s*:/i;
+export 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,
+    };
+}
+export function buildReplySubject(subject) {
+    const trimmed = subject?.trim() ?? "";
+    if (trimmed.length === 0) {
+        return "Re:";
+    }
+    return REPLY_PREFIX_RE.test(trimmed) ? trimmed : `Re: ${trimmed}`;
+}
+export function buildForwardSubject(subject) {
+    const trimmed = subject?.trim() ?? "";
+    if (trimmed.length === 0) {
+        return "Fwd:";
+    }
+    return FORWARD_PREFIX_RE.test(trimmed) ? trimmed : `Fwd: ${trimmed}`;
+}
+export 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,
+    };
+}
+// Lenient about quirky headers (unquoted commas in display names, missing
+// closing angle brackets) but strict about the resulting address: it must
+// validate as an email, otherwise the normalizer falls back to the SMTP
+// envelope sender. Exported so cross-SDK fixtures can exercise it directly.
+export function parseHeaderAddress(value) {
+    const parsed = parseFromHeaderLoose(value);
+    if (!parsed) {
+        return null;
+    }
+    return {
+        address: parsed.address,
+        name: parsed.name?.trim() || null,
+    };
+}

package/dist/{webhook-COe5N_Uj.js → webhook-2TALcBQz.js}

@@ -1,3 +1,4 @@
+import { normalizeReceivedEmail } from "./received-email-Q6Cha3wc.js";
 import { createHash, createHmac, timingSafeEqual } from "node:crypto";
 
 //#region src/generated/email-received-event.validator.generated.ts
@@ -7829,6 +7830,20 @@ function handleWebhook(options) {
 	const parsed = parseJsonBody(body);
 	return validateEmailReceivedEvent(parsed);
 }
+function receive(input, options) {
+	if (input instanceof Request) return receiveFromRequest(input, options);
+	return normalizeReceivedEmail(handleWebhook(input));
+}
+async function receiveFromRequest(request, options) {
+	if (!options?.secret) throw new WebhookVerificationError("MISSING_SECRET", "Webhook secret is required but was empty or not provided");
+	const body = Buffer.from(await request.arrayBuffer());
+	return normalizeReceivedEmail(handleWebhook({
+		body,
+		headers: request.headers,
+		secret: options.secret,
+		toleranceSeconds: options.toleranceSeconds
+	}));
+}
 /**
 * Returns headers for the optional "content discard" feature.
 *
@@ -8003,4 +8018,4 @@ function verifyRawEmailDownload(downloaded, event) {
 }
 
 //#endregion
-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, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };
+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, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, generateDownloadToken, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, receive, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyDownloadToken, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };

package/oclif.manifest.json

@@ -1136,6 +1136,52 @@
       "summary": "Update a filter rule",
       "enableJsonFlag": false
     },
+    "sending:send-email": {
+      "aliases": [],
+      "args": {},
+      "description": "Sends an outbound email through Primitive's outbound relay. By default\nthe request returns once the relay accepts the message for delivery.\nSet `wait: true` to wait for the first downstream SMTP delivery outcome.\n",
+      "flags": {
+        "api-key": {
+          "description": "Primitive API key (defaults to PRIMITIVE_API_KEY)",
+          "env": "PRIMITIVE_API_KEY",
+          "name": "api-key",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "base-url": {
+          "description": "API base URL (defaults to PRIMITIVE_API_URL or production)",
+          "env": "PRIMITIVE_API_URL",
+          "name": "base-url",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "body": {
+          "description": "JSON request body",
+          "name": "body",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "body-file": {
+          "description": "Path to a JSON file used as the request body",
+          "name": "body-file",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "sending:send-email",
+      "pluginAlias": "@primitivedotdev/sdk",
+      "pluginName": "@primitivedotdev/sdk",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Send outbound email",
+      "enableJsonFlag": false
+    },
     "webhook-deliveries:list-deliveries": {
       "aliases": [],
       "args": {},
@@ -1263,5 +1309,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.6.0"
+  "version": "0.8.0"
 }