@primitivedotdev/sdk 0.5.1 → 0.7.0

package/dist/contract/index.d.ts

@@ -102,7 +102,7 @@ declare function generateEventId(endpoint_id: string, email_id: string): string;
  * result against the generated JSON Schema before returning.
  *
  * @param input - Producer-side data for the webhook payload.
- * @param options - Optional overrides for event ID and attempted-at timestamp.
+ * @param options - Optional overrides for the attempted-at timestamp.
  * @returns A fully constructed, schema-valid `EmailReceivedEvent`.
  *
  * @example
@@ -142,8 +142,6 @@ declare function generateEventId(endpoint_id: string, email_id: string): string;
  * ```
  */
 declare function buildEmailReceivedEvent(input: EmailReceivedEventInput, options?: {
-  /** Override the generated event ID, typically for tests. */
-  event_id?: string;
   /** Override the attempted-at timestamp, typically for tests. */
   attempted_at?: string;
 }): EmailReceivedEvent;
@@ -194,7 +192,6 @@ interface BuildEventFromParsedDataOptions {
   dateHeader?: string | null;
   /** Optional overrides forwarded to `buildEmailReceivedEvent`. */
   buildOptions?: {
-    event_id?: string;
     attempted_at?: string;
   };
 }

package/dist/contract/index.js

@@ -51,7 +51,7 @@ function generateEventId(endpoint_id, email_id) {
 * result against the generated JSON Schema before returning.
 *
 * @param input - Producer-side data for the webhook payload.
-* @param options - Optional overrides for event ID and attempted-at timestamp.
+* @param options - Optional overrides for the attempted-at timestamp.
 * @returns A fully constructed, schema-valid `EmailReceivedEvent`.
 *
 * @example
@@ -91,7 +91,7 @@ function generateEventId(endpoint_id, email_id) {
 * ```
 */
 function buildEmailReceivedEvent(input, options) {
-	const event_id = options?.event_id ?? generateEventId(input.endpoint_id, input.email_id);
+	const 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 raw_size_bytes = input.raw_bytes.length;
 	if (input.raw_size_bytes !== raw_size_bytes) throw new Error(`[@primitivedotdev/sdk/contract] Invalid raw_size_bytes: ${input.raw_size_bytes}. Expected ${raw_size_bytes} based on raw_bytes length`);

package/dist/parser/index.d.ts

@@ -1,5 +1,105 @@
 import { EmailAddress, ParsedDataComplete, WebhookAttachment } from "../types-CKFmgitP.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,9 +1,114 @@
 import { createHash } from "node:crypto";
+import addressparser from "nodemailer/lib/addressparser/index.js";
+import isEmail from "validator/lib/isEmail.js";
 import { createGzip } from "node:zlib";
 import { pack } from "tar-stream";
 import { simpleParser } from "mailparser";
 import DOMPurify from "isomorphic-dompurify";
 
+//#region src/parser/address-parser.ts
+const MAX_HEADER_LENGTH = 998;
+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.
+*/
+function parseFromHeader(header) {
+	if (header === null || header === void 0) 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"
+	};
+	const parsed = addressparser(trimmed);
+	if (parsed.length > 1) return {
+		ok: false,
+		reason: "multiple_addresses"
+	};
+	const entry = parsed[0];
+	if (entry === void 0) return {
+		ok: false,
+		reason: "invalid_address"
+	};
+	if ("group" in entry) return {
+		ok: false,
+		reason: "group_syntax"
+	};
+	if (!isEmail(entry.address, IS_EMAIL_OPTIONS)) return {
+		ok: false,
+		reason: "invalid_address"
+	};
+	return {
+		ok: true,
+		value: { address: entry.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.
+*/
+function parseFromHeaderLoose(header) {
+	if (header === null || header === void 0) return null;
+	const trimmed = header.trim();
+	if (trimmed.length === 0 || Buffer.byteLength(trimmed, "utf8") > MAX_HEADER_LENGTH) return null;
+	const parsed = addressparser(trimmed, { flatten: true });
+	const entry = parsed[0];
+	if (entry === void 0 || !isEmail(entry.address, IS_EMAIL_OPTIONS)) return null;
+	return {
+		address: entry.address.toLowerCase(),
+		name: entry.name && entry.name.length > 0 ? entry.name : null
+	};
+}
+
+//#endregion
 //#region src/parser/attachment-bundler.ts
 function appendTarEntry(archive, name, content) {
 	return new Promise((resolve, reject) => {
@@ -557,4 +662,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/oclif.manifest.json

@@ -1263,5 +1263,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "0.5.1"
+  "version": "0.7.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/sdk",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Official Primitive Node.js SDK — webhook, api, openapi, contract, and parser modules",
   "type": "module",
   "module": "./dist/index.js",
@@ -132,15 +132,19 @@
     "ajv": "^8.17.1",
     "isomorphic-dompurify": "^3.8.0",
     "mailparser": "^3.9.0",
-    "tar-stream": "^3.1.8"
+    "nodemailer": "^8.0.7",
+    "tar-stream": "^3.1.8",
+    "validator": "^13.15.35"
   },
   "devDependencies": {
-    "@hey-api/openapi-ts": "0.96.0",
     "@biomejs/biome": "^2.4.10",
+    "@hey-api/openapi-ts": "0.96.0",
     "@types/json-schema": "^7.0.15",
     "@types/mailparser": "^3.4.6",
     "@types/node": "^22.10.2",
+    "@types/nodemailer": "^8.0.0",
     "@types/tar-stream": "^3.1.4",
+    "@types/validator": "^13.15.10",
     "@vitest/coverage-v8": "^4.1.4",
     "json-schema-to-typescript": "^15.0.4",
     "oclif": "^4.23.0",