@primitivedotdev/sdk 0.6.0 → 0.8.0

package/README.md

@@ -2,17 +2,18 @@
 
 Official Primitive Node.js SDK.
 
-This package ships five Node.js modules and one CLI:
+The default root import is intentionally small and centered on email
+automation:
 
-- `@primitivedotdev/sdk` for the webhook module
-- `@primitivedotdev/sdk/api` for the generated HTTP API client
-- `@primitivedotdev/sdk/openapi` for the canonical OpenAPI document export
-- `@primitivedotdev/sdk/contract` for the contract module
-- `@primitivedotdev/sdk/parser` for the parser module
+- `primitive.receive(...)`
+- `primitive.client(...)`
+- `client.send(...)`
+- `client.reply(...)`
+- `client.forward(...)`
 
-It also publishes the `primitive` CLI bin from the same package.
-
-`contract`, `parser`, and `openapi` are Node-only extras. The Go and Python SDKs expose `webhook` and `api` modules.
+Advanced webhook helpers, generated API operations, OpenAPI exports, contract
+tooling, raw MIME parsing, and the CLI still exist as named exports or subpath
+imports.
 
 ## Requirements
 
@@ -24,207 +25,154 @@ It also publishes the `primitive` CLI bin from the same package.
 npm install @primitivedotdev/sdk
 ```
 
-## Modules
-
-### Webhook
+## Basic usage
 
-The root entrypoint remains webhook-focused.
+### Receive and reply in a Next.js route
 
 ```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;
-  }
-});
-```
+import primitive from "@primitivedotdev/sdk";
 
-The same API is also available from `@primitivedotdev/sdk/webhook`.
+export const runtime = "nodejs";
+export const maxDuration = 300;
 
-Webhook exports include:
+const client = primitive.client({
+  apiKey: process.env.PRIMITIVE_API_KEY!,
+});
 
-- `handleWebhook(options)`
-- `parseWebhookEvent(input)`
-- `validateEmailReceivedEvent(input)`
-- `safeValidateEmailReceivedEvent(input)`
-- `verifyWebhookSignature(options)`
-- `validateEmailAuth(auth)`
-- `emailReceivedEventJsonSchema`
-- `WEBHOOK_VERSION`
-- webhook error classes and webhook types
+export async function POST(req: Request) {
+  const email = await primitive.receive(req, {
+    secret: process.env.PRIMITIVE_WEBHOOK_SECRET!,
+  });
 
-### API
+  await client.reply(email, "Thank you for your email.");
 
-Use the API module for outbound calls to the Primitive HTTP API.
+  return Response.json({ ok: true });
+}
+```
+
+### Send a new email
 
 ```ts
-import { PrimitiveApiClient, getAccount } from "@primitivedotdev/sdk/api";
+import primitive from "@primitivedotdev/sdk";
 
-const api = new PrimitiveApiClient({ apiKey: process.env.PRIMITIVE_API_KEY });
-const result = await getAccount({ client: api.client });
+const client = primitive.client({
+  apiKey: process.env.PRIMITIVE_API_KEY!,
+});
 
-if (result.error) {
-  throw result.error;
-}
+const result = await client.send({
+  from: "Support <support@example.com>",
+  to: "alice@example.com",
+  subject: "Hello",
+  bodyText: "Hi there",
+  // Use a unique key per logical send. Reusing a key returns the original
+  // response from the first send, which is how retries are deduplicated.
+  idempotencyKey: "customer-key-abc123",
+  wait: true,
+  waitTimeoutMs: 5000,
+});
 
-console.log(result.data.id);
+console.log(result.id, result.status, result.queueId, result.deliveryStatus);
 ```
 
-The package also ships a generated CLI bin named `primitive`.
-
-### OpenAPI
+`send`, `reply`, and `forward` keep the HTTP request open until Primitive's
+downstream SMTP transaction completes. In production, configure your runtime or
+transport with a request timeout long enough for SMTP delivery, typically 30-60
+seconds.
 
-Use the OpenAPI module when another JavaScript application needs the canonical Primitive API spec.
+### About `wait` mode
 
-```ts
-import { openapiDocument } from "@primitivedotdev/sdk/openapi";
+When `wait: true`, the call returns the first downstream SMTP outcome (or
+`waitTimeoutMs`, default 30000). Possible terminal `deliveryStatus` values:
 
-console.log(openapiDocument.openapi);
-```
+- `delivered` accepted by the receiving MTA
+- `bounced` rejected by the receiving MTA (the response is still 200 OK)
+- `deferred` temporary failure, the receiving MTA may retry
+- `wait_timeout` no outcome was observed in time. Treat as "outcome unknown."
+  The send may still complete after the response returns.
 
-### CLI
+### Reply from a different address
 
-Use the published `primitive` CLI for outbound API access from the terminal.
+`reply()` defaults the From address to the inbound recipient (the address that
+received the email). When your verified outbound domain differs from your
+inbound domain, pass `from` explicitly:
 
-```bash
-primitive --help
-primitive account get-account --api-key prim_test
-primitive emails download-raw-email --id <uuid> --api-key prim_test --output email.eml
+```ts
+await client.reply(email, {
+  text: "Thanks for your email.",
+  from: "notifications@outbound.example.com",
+});
 ```
 
-Autocomplete support is available through:
+### Forward an inbound email
 
-- `primitive completion fish`
-- `primitive completion bash`
-- `primitive completion zsh`
-- `primitive completion powershell`
+```ts
+await client.forward(email, {
+  to: "ops@example.com",
+  bodyText: "Can you take this one?",
+});
+```
 
-### Contract
+## The normalized email object
 
-Use the contract module when constructing canonical Primitive webhook payloads on the producer side.
+`primitive.receive(...)` returns a normalized inbound email object that keeps the
+common case clean:
 
 ```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: {},
-});
+email.sender.address
+email.sender.name
 
-const signature = signWebhookPayload(JSON.stringify(event), "whsec_test");
-```
+email.receivedBy
+email.receivedByAll
 
-Contract exports include:
+email.replyTarget.address
+email.replySubject
+email.forwardSubject
 
-- `buildEmailReceivedEvent(input, options?)`
-- `generateEventId(endpointId, emailId)`
-- `RAW_EMAIL_INLINE_THRESHOLD`
-- `signWebhookPayload(rawBody, secret, timestamp?)`
-- `WEBHOOK_VERSION`
-- contract input and payload helper types
+email.subject
+email.text
 
-### Parser
+email.thread.messageId
+email.thread.references
 
-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"));
+email.raw
 ```
 
-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
+Use `email.raw` when you need the original validated webhook event shape.
 
-## Shared Schema
+## Advanced usage
 
-The webhook payload contract is defined by the canonical JSON schema in the repository and is exported by this package as `emailReceivedEventJsonSchema`.
+### Explicit receive form
 
-The SDK uses that schema to generate:
+If your framework does not expose a standard `Request`, use the lower-level
+form:
 
-- TypeScript types
-- runtime validators
-- the published schema export
+```ts
+const email = primitive.receive({
+  body: req.body,
+  headers: req.headers,
+  secret: process.env.PRIMITIVE_WEBHOOK_SECRET!,
+});
+```
 
-## Error Handling
+### Generated API module
 
-All SDK-specific runtime errors extend `PrimitiveWebhookError` and include a stable error `code`.
+Use the API subpath when you want the full generated HTTP API surface:
 
 ```ts
-import { PrimitiveWebhookError } from "@primitivedotdev/sdk";
-
-try {
-  // ...
-} catch (error) {
-  if (error instanceof PrimitiveWebhookError) {
-    console.error(error.code, error.message);
-  }
-}
+import { PrimitiveApiClient, getAccount } from "@primitivedotdev/sdk/api";
+
+const api = new PrimitiveApiClient({ apiKey: process.env.PRIMITIVE_API_KEY });
+const result = await getAccount({ client: api.client });
 ```
 
+### Other advanced surfaces
+
+- `@primitivedotdev/sdk/webhook`
+- `@primitivedotdev/sdk/openapi`
+- `@primitivedotdev/sdk/contract`
+- `@primitivedotdev/sdk/parser`
+- `primitive` CLI
+
 ## Development
 
 From `sdks/sdk-node`:
@@ -240,51 +188,7 @@ pnpm build
 Or from repo root `sdks/`:
 
 ```bash
-make node-install
+make node-generate
 make node-check
 make node-build
 ```
-
-## Package Layout
-
-```text
-sdk-node/
-  bin/
-    run.js
-  src/
-    api/
-      generated/
-      index.ts
-    contract/
-      contract.ts
-      index.ts
-    oclif/
-      api-command.ts
-      fish-completion.ts
-      index.ts
-    openapi/
-      index.ts
-      openapi.generated.ts
-      operations.generated.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/address-parser-CfPHs3mE.js

@@ -0,0 +1,113 @@
+import addressparser from "nodemailer/lib/addressparser/index.js";
+import isEmail from "validator/lib/isEmail.js";
+
+//#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"
+	};
+	const address = entry.address;
+	if (address === void 0 || !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.
+*/
+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);
+	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 !== void 0 && isEmail(address, IS_EMAIL_OPTIONS)) return {
+				address: address.toLowerCase(),
+				name: candidate.name && candidate.name.length > 0 ? candidate.name : null
+			};
+		}
+	}
+	return null;
+}
+
+//#endregion
+export { parseFromHeader, parseFromHeaderLoose };

package/dist/api/generated/index.js

@@ -1,2 +1,2 @@
 // This file is auto-generated by @hey-api/openapi-ts
-export { addDomain, createEndpoint, createFilter, deleteDomain, deleteEmail, deleteEndpoint, deleteFilter, downloadAttachments, downloadRawEmail, getAccount, getEmail, getStorageStats, getWebhookSecret, listDeliveries, listDomains, listEmails, listEndpoints, listFilters, replayDelivery, replayEmailWebhooks, rotateWebhookSecret, testEndpoint, updateAccount, updateDomain, updateEndpoint, updateFilter, verifyDomain } from './sdk.gen.js';
+export { addDomain, createEndpoint, createFilter, deleteDomain, deleteEmail, deleteEndpoint, deleteFilter, downloadAttachments, downloadRawEmail, getAccount, getEmail, getStorageStats, getWebhookSecret, listDeliveries, listDomains, listEmails, listEndpoints, listFilters, replayDelivery, replayEmailWebhooks, rotateWebhookSecret, sendEmail, testEndpoint, updateAccount, updateDomain, updateEndpoint, updateFilter, verifyDomain } from './sdk.gen.js';

package/dist/api/generated/sdk.gen.js

@@ -345,3 +345,20 @@ export const replayDelivery = (options) => (options.client ?? client).post({
     url: '/webhooks/deliveries/{id}/replay',
     ...options
 });
+/**
+ * Send outbound email
+ *
+ * Sends an outbound email through Primitive's outbound relay. By default
+ * the request returns once the relay accepts the message for delivery.
+ * Set `wait: true` to wait for the first downstream SMTP delivery outcome.
+ *
+ */
+export const sendEmail = (options) => (options.client ?? client).post({
+    security: [{ scheme: 'bearer', type: 'http' }],
+    url: '/send-mail',
+    ...options,
+    headers: {
+        'Content-Type': 'application/json',
+        ...options.headers
+    }
+});