@primitivedotdev/sdk 0.2.0

package/README.md

@@ -0,0 +1,227 @@
+# `@primitivedotdev/sdk`
+
+Official Primitive Node.js SDK.
+
+This package ships three Node.js modules:
+
+- `@primitivedotdev/sdk` for the webhook module
+- `@primitivedotdev/sdk/contract` for the contract module
+- `@primitivedotdev/sdk/parser` for the parser module
+
+`contract` and `parser` are only available in the Node SDK. The Go and Python SDKs expose the webhook surface only.
+
+## Requirements
+
+- Node.js `>=20`
+
+## Installation
+
+```bash
+npm install @primitivedotdev/sdk
+```
+
+## Modules
+
+### Webhook
+
+The root entrypoint remains webhook-focused.
+
+```ts
+import { handleWebhook, PrimitiveWebhookError } from "@primitivedotdev/sdk";
+
+app.post("/webhooks/email", express.raw({ type: "application/json" }), (req, res) => {
+  try {
+    const event = handleWebhook({
+      body: req.body,
+      headers: req.headers,
+      secret: process.env.PRIMITIVE_WEBHOOK_SECRET!,
+    });
+
+    console.log("Email from:", event.email.headers.from);
+    console.log("Subject:", event.email.headers.subject);
+
+    res.json({ received: true });
+  } catch (error) {
+    if (error instanceof PrimitiveWebhookError) {
+      return res.status(400).json({ error: error.code, message: error.message });
+    }
+
+    throw error;
+  }
+});
+```
+
+The same API is also available from `@primitivedotdev/sdk/webhook`.
+
+Webhook exports include:
+
+- `handleWebhook(options)`
+- `parseWebhookEvent(input)`
+- `validateEmailReceivedEvent(input)`
+- `safeValidateEmailReceivedEvent(input)`
+- `verifyWebhookSignature(options)`
+- `validateEmailAuth(auth)`
+- `emailReceivedEventJsonSchema`
+- `WEBHOOK_VERSION`
+- webhook error classes and webhook types
+
+### Contract
+
+Use the contract module when constructing canonical Primitive webhook payloads on the producer side.
+
+```ts
+import { buildEmailReceivedEvent, signWebhookPayload } from "@primitivedotdev/sdk/contract";
+
+const event = buildEmailReceivedEvent({
+  email_id: "email-123",
+  endpoint_id: "endpoint-456",
+  message_id: "<msg@example.com>",
+  sender: "from@example.com",
+  recipient: "to@example.com",
+  subject: "Hello",
+  received_at: "2025-01-01T00:00:00Z",
+  smtp_helo: "mail.example.com",
+  smtp_mail_from: "from@example.com",
+  smtp_rcpt_to: ["to@example.com"],
+  raw_bytes: Buffer.from("hello"),
+  raw_sha256: "a".repeat(64),
+  raw_size_bytes: 5,
+  attempt_count: 1,
+  date_header: null,
+  download_url: "https://example.com/raw",
+  download_expires_at: "2025-01-02T00:00:00Z",
+  attachments_download_url: null,
+  auth: {
+    spf: "pass",
+    dmarc: "pass",
+    dmarcPolicy: "reject",
+    dmarcFromDomain: "example.com",
+    dmarcSpfAligned: true,
+    dmarcDkimAligned: true,
+    dmarcSpfStrict: false,
+    dmarcDkimStrict: false,
+    dkimSignatures: [],
+  },
+  analysis: {},
+});
+
+const signature = signWebhookPayload(JSON.stringify(event), "whsec_test");
+```
+
+Contract exports include:
+
+- `buildEmailReceivedEvent(input, options?)`
+- `generateEventId(endpointId, emailId)`
+- `RAW_EMAIL_INLINE_THRESHOLD`
+- `signWebhookPayload(rawBody, secret, timestamp?)`
+- `WEBHOOK_VERSION`
+- contract input and payload helper types
+
+### Parser
+
+Use the parser module for raw `.eml` parsing and attachment extraction.
+
+```ts
+import {
+  bundleAttachments,
+  parseEmail,
+  parseEmailWithAttachments,
+  toParsedDataComplete,
+} from "@primitivedotdev/sdk/parser";
+
+const parsed = await parseEmailWithAttachments(emlBuffer);
+const archive = await bundleAttachments(parsed.attachments);
+const webhookParsed = toParsedDataComplete(parsed, null);
+
+await parseEmail(emlBuffer.toString("utf8"));
+```
+
+Parser exports include:
+
+- `parseEmail(emlRaw)`
+- `parseEmailWithAttachments(emlBuffer, options?)`
+- `bundleAttachments(attachments)`
+- `extractAttachmentMetadata(attachments)`
+- `getAttachmentsStorageKey(emailId, sha256)`
+- `toParsedDataComplete(parsed, attachmentsDownloadUrl)`
+- `toWebhookAttachments(attachments)`
+- `attachmentMetadataToWebhookAttachments(metadata)`
+- `toCanonicalHeaders(parsed)`
+- parser attachment and bundle types
+
+## Shared Schema
+
+The webhook payload contract is defined by the canonical JSON schema in the repository and is exported by this package as `emailReceivedEventJsonSchema`.
+
+The SDK uses that schema to generate:
+
+- TypeScript types
+- runtime validators
+- the published schema export
+
+## Error Handling
+
+All SDK-specific runtime errors extend `PrimitiveWebhookError` and include a stable error `code`.
+
+```ts
+import { PrimitiveWebhookError } from "@primitivedotdev/sdk";
+
+try {
+  // ...
+} catch (error) {
+  if (error instanceof PrimitiveWebhookError) {
+    console.error(error.code, error.message);
+  }
+}
+```
+
+## Development
+
+From `sdks/sdk-node`:
+
+```bash
+pnpm install
+pnpm generate
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+Or from repo root `sdks/`:
+
+```bash
+make node-install
+make node-check
+make node-build
+```
+
+## Package Layout
+
+```text
+sdk-node/
+  src/
+    contract/
+      contract.ts
+      index.ts
+    parser/
+      attachment-bundler.ts
+      attachment-parser.ts
+      email-parser.ts
+      index.ts
+      mapping.ts
+    webhook/
+      auth.ts
+      encoding.ts
+      errors.ts
+      index.ts
+      parsing.ts
+      signing.ts
+      version.ts
+    generated/
+      email-received-event.validator.generated.ts
+    index.ts
+    schema.generated.ts
+    types.generated.ts
+    types.ts
+    validation.ts
+```

package/dist/contract/index.d.ts

@@ -0,0 +1,150 @@
+import { EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, ParsedDataComplete, ParsedDataFailed, ParsedError, RawContentDownloadOnly, RawContentInline, WebhookAttachment } from "../types-C6M6oCRS.js";
+import { SignResult, WEBHOOK_VERSION$1 as WEBHOOK_VERSION, signWebhookPayload$1 as signWebhookPayload } from "../index-C9pON-wY.js";
+
+//#region src/contract/contract.d.ts
+/** Maximum raw email size for inline inclusion (256 KB). */
+
+/** Maximum raw email size for inline inclusion (256 KB). */
+declare const RAW_EMAIL_INLINE_THRESHOLD = 262144;
+/** Parsed content input when parsing succeeded. */
+interface ParsedInputComplete {
+  status: "complete";
+  body_text: string | null;
+  body_html: string | null;
+  /** Parsed Reply-To header addresses. Defaults to `null` when omitted. */
+  reply_to?: EmailAddress[] | null;
+  /** Parsed CC header addresses. Defaults to `null` when omitted. */
+  cc?: EmailAddress[] | null;
+  /** Parsed BCC header addresses. Defaults to `null` when omitted. */
+  bcc?: EmailAddress[] | null;
+  /** In-Reply-To header values. Defaults to `null` when omitted. */
+  in_reply_to?: string[] | null;
+  /** References header values. Defaults to `null` when omitted. */
+  references?: string[] | null;
+  attachments: WebhookAttachment[];
+  /** Storage key for the attachments tarball, if attachments were persisted. Ignored by the canonical payload builder. */
+  attachments_storage_key?: string | null;
+}
+/** Parsed content input when parsing failed. */
+interface ParsedInputFailed {
+  status: "failed";
+  error: ParsedError;
+}
+/** Parsed content input (discriminated union on `status`). */
+type ParsedInput = ParsedInputComplete | ParsedInputFailed;
+/**
+ * Input for building an `EmailReceivedEvent`.
+ *
+ * This is the strict producer-side shape required to construct a canonical
+ * Primitive `email.received` webhook payload.
+ */
+interface EmailReceivedEventInput {
+  /** Unique email ID in Primitive. */
+  email_id: string;
+  /** ID of the webhook endpoint receiving this event. */
+  endpoint_id: string;
+  /** Message-ID header value, if present. */
+  message_id: string | null;
+  /** From header value. */
+  sender: string;
+  /** To header value. */
+  recipient: string;
+  /** Subject header value, if present. */
+  subject: string | null;
+  /** ISO 8601 timestamp when Primitive received the email. */
+  received_at: string;
+  /** HELO/EHLO hostname from the sending server. */
+  smtp_helo: string | null;
+  /** SMTP envelope sender (MAIL FROM). */
+  smtp_mail_from: string;
+  /** SMTP envelope recipients (RCPT TO). Must contain at least one recipient. */
+  smtp_rcpt_to: [string, ...string[]];
+  /** Raw email bytes. These are base64 encoded when inlined into the payload. */
+  raw_bytes: Buffer;
+  /** SHA-256 hash of the raw email as a 64-character hex string. */
+  raw_sha256: string;
+  /** Size of the raw email in bytes. */
+  raw_size_bytes: number;
+  /** Delivery attempt number, starting at 1. */
+  attempt_count: number;
+  /** Date header parsed from the raw email, if present. */
+  date_header: string | null;
+  /** HTTPS download URL for the raw email. */
+  download_url: string;
+  /** ISO 8601 timestamp when the raw-email download URL expires. */
+  download_expires_at: string;
+  /** HTTPS download URL for the attachments tarball, if one exists. */
+  attachments_download_url: string | null;
+  /** Parsed email content. Defaults to a failed parse state when omitted. */
+  parsed?: ParsedInput;
+  /** Email authentication results (SPF, DKIM, DMARC). */
+  auth: EmailAuth;
+  /** Email analysis results. */
+  analysis: EmailAnalysis;
+}
+/**
+ * Generate a stable event ID for webhook deduplication.
+ *
+ * Format: `evt_{sha256_hex}` where the hash is deterministic based on the
+ * event type, endpoint ID, and email ID. The same email sent
+ * to the same endpoint will always get the same event ID.
+ *
+ * @param endpoint_id - Webhook endpoint ID.
+ * @param email_id - Primitive email ID.
+ * @returns Stable event ID with `evt_` prefix.
+ */
+declare function generateEventId(endpoint_id: string, email_id: string): string;
+/**
+ * Build an `EmailReceivedEvent` from producer-side input.
+ *
+ * This is the contract package's primary builder. It assembles the canonical
+ * payload shape, applies inline/download raw-content rules, and validates the
+ * 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.
+ * @returns A fully constructed, schema-valid `EmailReceivedEvent`.
+ *
+ * @example
+ * ```typescript
+ * import { buildEmailReceivedEvent } from "@primitivedotdev/sdk/contract";
+ *
+ * const event = buildEmailReceivedEvent({
+ *   email_id: "email-123",
+ *   endpoint_id: "endpoint-456",
+ *   message_id: "<msg@example.com>",
+ *   sender: "from@example.com",
+ *   recipient: "to@example.com",
+ *   subject: "Hello",
+ *   received_at: "2025-01-01T00:00:00Z",
+ *   smtp_helo: "mail.example.com",
+ *   smtp_mail_from: "from@example.com",
+ *   smtp_rcpt_to: ["to@example.com"],
+ *   raw_bytes: Buffer.from("..."),
+ *   raw_sha256: "a".repeat(64),
+ *   raw_size_bytes: 1234,
+ *   attempt_count: 1,
+ *   date_header: "Mon, 1 Jan 2025 00:00:00 +0000",
+ *   download_url: "https://example.com/download/email-123",
+ *   download_expires_at: "2025-01-02T00:00:00Z",
+ *   attachments_download_url: null,
+ *   auth: {
+ *     spf: "pass",
+ *     dmarc: "pass",
+ *     dmarcPolicy: "reject",
+ *     dmarcFromDomain: "example.com",
+ *     dmarcSpfStrict: false,
+ *     dmarcDkimStrict: false,
+ *     dkimSignatures: [],
+ *   },
+ *   analysis: {},
+ * });
+ * ```
+ */
+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; //#endregion
+export { EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EmailReceivedEventInput, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedInput, ParsedInputComplete, ParsedInputFailed, RAW_EMAIL_INLINE_THRESHOLD, RawContentDownloadOnly, RawContentInline, SignResult, WEBHOOK_VERSION, WebhookAttachment, buildEmailReceivedEvent, generateEventId, signWebhookPayload };

package/dist/contract/index.js

@@ -0,0 +1,199 @@
+import { WEBHOOK_VERSION, signWebhookPayload, validateEmailReceivedEvent } from "../webhook-h24dbQEE.js";
+import { createHash } from "node:crypto";
+
+//#region src/contract/contract.ts
+/** Maximum raw email size for inline inclusion (256 KB). */
+const RAW_EMAIL_INLINE_THRESHOLD = 262144;
+/**
+* ISO 8601 timestamp pattern.
+*
+* Matches RFC 3339 date-time strings with either `Z` or an explicit UTC offset,
+* but rejects loose formats like `Tuesday` that `Date.parse()` would otherwise accept.
+*/
+const ISO_8601_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+/**
+* Validate that a timestamp is a valid RFC 3339 date-time string.
+*
+* The original string is preserved so callers retain their chosen precision.
+*
+* @param timestamp - Timestamp string to validate.
+* @param fieldName - Logical field name used in error messages.
+* @returns The validated timestamp, unchanged.
+* @throws Error if the timestamp is not a valid RFC 3339 date-time string.
+*/
+function validateTimestamp(timestamp, fieldName) {
+	if (!ISO_8601_PATTERN.test(timestamp)) throw new Error(`[@primitivedotdev/sdk/contract] Invalid ${fieldName}: "${timestamp}". Expected RFC 3339 date-time format (e.g., "2025-01-15T10:30:00.000Z" or "2025-01-15T10:30:00+00:00")`);
+	const date = new Date(timestamp);
+	if (Number.isNaN(date.getTime())) throw new Error(`[@primitivedotdev/sdk/contract] Invalid ${fieldName}: "${timestamp}" is not a valid date`);
+	return timestamp;
+}
+/**
+* Generate a stable event ID for webhook deduplication.
+*
+* Format: `evt_{sha256_hex}` where the hash is deterministic based on the
+* event type, endpoint ID, and email ID. The same email sent
+* to the same endpoint will always get the same event ID.
+*
+* @param endpoint_id - Webhook endpoint ID.
+* @param email_id - Primitive email ID.
+* @returns Stable event ID with `evt_` prefix.
+*/
+function generateEventId(endpoint_id, email_id) {
+	const hashInput = `email.received:${endpoint_id}:${email_id}`;
+	const hash = createHash("sha256").update(hashInput).digest("hex");
+	return `evt_${hash}`;
+}
+/**
+* Build an `EmailReceivedEvent` from producer-side input.
+*
+* This is the contract package's primary builder. It assembles the canonical
+* payload shape, applies inline/download raw-content rules, and validates the
+* 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.
+* @returns A fully constructed, schema-valid `EmailReceivedEvent`.
+*
+* @example
+* ```typescript
+* import { buildEmailReceivedEvent } from "@primitivedotdev/sdk/contract";
+*
+* const event = buildEmailReceivedEvent({
+*   email_id: "email-123",
+*   endpoint_id: "endpoint-456",
+*   message_id: "<msg@example.com>",
+*   sender: "from@example.com",
+*   recipient: "to@example.com",
+*   subject: "Hello",
+*   received_at: "2025-01-01T00:00:00Z",
+*   smtp_helo: "mail.example.com",
+*   smtp_mail_from: "from@example.com",
+*   smtp_rcpt_to: ["to@example.com"],
+*   raw_bytes: Buffer.from("..."),
+*   raw_sha256: "a".repeat(64),
+*   raw_size_bytes: 1234,
+*   attempt_count: 1,
+*   date_header: "Mon, 1 Jan 2025 00:00:00 +0000",
+*   download_url: "https://example.com/download/email-123",
+*   download_expires_at: "2025-01-02T00:00:00Z",
+*   attachments_download_url: null,
+*   auth: {
+*     spf: "pass",
+*     dmarc: "pass",
+*     dmarcPolicy: "reject",
+*     dmarcFromDomain: "example.com",
+*     dmarcSpfStrict: false,
+*     dmarcDkimStrict: false,
+*     dkimSignatures: [],
+*   },
+*   analysis: {},
+* });
+* ```
+*/
+function buildEmailReceivedEvent(input, options) {
+	const event_id = options?.event_id ?? generateEventId(input.endpoint_id, input.email_id);
+	const attempted_at = options?.attempted_at ? validateTimestamp(options.attempted_at, "attempted_at") : new Date().toISOString();
+	const 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`);
+	const raw_sha256 = createHash("sha256").update(input.raw_bytes).digest("hex");
+	if (input.raw_sha256 !== raw_sha256) throw new Error(`[@primitivedotdev/sdk/contract] Invalid raw_sha256: "${input.raw_sha256}". Expected ${raw_sha256} based on raw_bytes`);
+	const shouldInline = raw_size_bytes <= RAW_EMAIL_INLINE_THRESHOLD;
+	const rawContent = shouldInline ? {
+		included: true,
+		encoding: "base64",
+		max_inline_bytes: RAW_EMAIL_INLINE_THRESHOLD,
+		size_bytes: raw_size_bytes,
+		sha256: raw_sha256,
+		data: input.raw_bytes.toString("base64")
+	} : {
+		included: false,
+		reason_code: "size_exceeded",
+		max_inline_bytes: RAW_EMAIL_INLINE_THRESHOLD,
+		size_bytes: raw_size_bytes,
+		sha256: raw_sha256
+	};
+	let parsedData;
+	if (input.parsed?.status === "complete") parsedData = {
+		status: "complete",
+		error: null,
+		body_text: input.parsed.body_text,
+		body_html: input.parsed.body_html,
+		reply_to: input.parsed.reply_to ?? null,
+		cc: input.parsed.cc ?? null,
+		bcc: input.parsed.bcc ?? null,
+		in_reply_to: input.parsed.in_reply_to ?? null,
+		references: input.parsed.references ?? null,
+		attachments: input.parsed.attachments,
+		attachments_download_url: input.parsed.attachments.length === 0 ? null : input.attachments_download_url
+	};
+	else if (input.parsed?.status === "failed") parsedData = {
+		status: "failed",
+		error: input.parsed.error,
+		body_text: null,
+		body_html: null,
+		reply_to: null,
+		cc: null,
+		bcc: null,
+		in_reply_to: null,
+		references: null,
+		attachments: [],
+		attachments_download_url: null
+	};
+	else parsedData = {
+		status: "failed",
+		error: {
+			code: "PARSE_FAILED",
+			message: "Parsing not attempted",
+			retryable: false
+		},
+		body_text: null,
+		body_html: null,
+		reply_to: null,
+		cc: null,
+		bcc: null,
+		in_reply_to: null,
+		references: null,
+		attachments: [],
+		attachments_download_url: null
+	};
+	const event = {
+		id: event_id,
+		event: "email.received",
+		version: WEBHOOK_VERSION,
+		delivery: {
+			endpoint_id: input.endpoint_id,
+			attempt: input.attempt_count,
+			attempted_at
+		},
+		email: {
+			id: input.email_id,
+			received_at: validateTimestamp(input.received_at, "received_at"),
+			smtp: {
+				helo: input.smtp_helo,
+				mail_from: input.smtp_mail_from,
+				rcpt_to: input.smtp_rcpt_to
+			},
+			headers: {
+				message_id: input.message_id,
+				subject: input.subject,
+				from: input.sender,
+				to: input.recipient,
+				date: input.date_header
+			},
+			content: {
+				raw: rawContent,
+				download: {
+					url: input.download_url,
+					expires_at: validateTimestamp(input.download_expires_at, "download_expires_at")
+				}
+			},
+			parsed: parsedData,
+			analysis: input.analysis,
+			auth: input.auth
+		}
+	};
+	return validateEmailReceivedEvent(event);
+}
+
+//#endregion
+export { RAW_EMAIL_INLINE_THRESHOLD, WEBHOOK_VERSION, buildEmailReceivedEvent, generateEventId, signWebhookPayload };