{"schema_version":"1.0","publisher":"Primitive SDKs","canonical_url":"https://test.abhinandan.one/node-sdk-overview","markdown_url":"https://test.abhinandan.one/node-sdk-overview.md","article":{"id":"ea40429c-9d21-4d19-9f27-ea4ccc4a20ff","article_slug":"node-sdk-overview","parent_article_slug":null,"parent_article_title":null,"kind":"concept","published_at":"2026-08-11T18:54:55.194931+00:00","keywords":["@primitivedotdev/sdk","primitive.receive","primitive.client","subpath exports","PrimitiveApiClient","createX402Client"],"meta_description":"@primitivedotdev/sdk is a typed Node.js client with a root import for send/receive/reply and six subpaths for webhooks, payments, and the generated API.","og_image_url":null,"source_file_paths":["sdk-node/README.md"],"recording_id":null,"replayable":false,"task_name":"What is the Primitive Node.js SDK?","category":"Node.js SDK","summary":null,"description":"@primitivedotdev/sdk is the official Node.js client for Primitive's inbound/outbound email platform, exposing a small default surface for send/receive/reply plus dedicated subpaths for webhooks, x402 payments, the generated API client, and raw MIME parsing.","content_kind":"repo_page","content_markdown":"`@primitivedotdev/sdk` is the official Node.js library for [Primitive](https://primitive.dev), an email API for sending and receiving programmatic mail. It gives you a typed client for receiving and verifying inbound webhooks, sending mail, parsing raw MIME, calling the full HTTP API, and moving USDC with x402 payments.\n\nRequires Node.js 22 or newer. Install it with:\n\n```bash\nnpm install @primitivedotdev/sdk\n```\n\n<Note>\n\nLooking for the terminal instead of application code? The CLI ships as a separate package. Run `npm install -g primitive` (or `npx primitive@latest <command>`); `@primitivedotdev/sdk` no longer ships a `primitive` bin. See [What is the Primitive CLI?](cli-overview)\n\n</Note>\n\n## The default import is deliberately small\n\nThe root import (`import primitive from \"@primitivedotdev/sdk\"`) covers the two things almost every integration needs on day one: receiving inbound webhook deliveries and sending mail.\n\n```typescript\nimport primitive from \"@primitivedotdev/sdk\";\n\nexport const runtime = \"nodejs\";\nexport const maxDuration = 300;\n\nconst client = primitive.client({\n  apiKey: process.env.PRIMITIVE_API_KEY!,\n});\n\nexport async function POST(req: Request) {\n  const email = await primitive.receive(req, {\n    secret: process.env.PRIMITIVE_WEBHOOK_SECRET!,\n  });\n\n  await client.reply(email, \"Thank you for your email.\");\n\n  return Response.json({ ok: true });\n}\n```\n\nThis is the shared receive-then-`send`/`reply`/`forward` model every SDK implements; see [Inbound and Outbound Email Model](email-model) for the field-by-field reference.\n\nEverything past that default is reachable through a small set of subpath imports, each scoped to one job.\n\n## Subpath export map\n\n| Subpath | What it's for | Owning page |\n| --- | --- | --- |\n| `@primitivedotdev/sdk` (root) | `primitive.receive`, `primitive.client`, `client.send`/`reply`/`forward` | [Sending, Replying, and Forwarding Email](node-sdk-sending-email), [Receiving Inbound Email](node-sdk-receiving-email) |\n| `@primitivedotdev/sdk/webhook` | `verifyWebhookSignature`, `handleWebhookEvent`, event type guards, download-token helpers | [Webhook Signature Verification](node-sdk-webhook-signing), [Handling Payment and Interaction Webhook Events](node-sdk-webhook-events) |\n| `@primitivedotdev/sdk/api` | `PrimitiveApiClient`, `createPrimitiveClient`, `client.memories`, `isTrustedSender`, `validateEmailAuth`, `normalizeReceivedEmail`, the Workers-safe surface | [Generated API Client and Primitive Memories](node-sdk-api-client), [Verifying Inbound Email Authenticity](node-sdk-email-authenticity) |\n| `@primitivedotdev/sdk/x402` | `createX402Client`, `parseEmailChallengeFromPart`, the low-level signing primitives | [x402 Payments Overview](x402-payments-overview), [Paying a Challenge](node-sdk-x402-paying) |\n| `@primitivedotdev/sdk/openapi` | The generated OpenAPI document export, for JavaScript consumers that need the raw spec | [OpenAPI Spec Normalization and Codegen Artifacts](openapi-spec-normalization) |\n| `@primitivedotdev/sdk/contract` | `buildEmailReceivedEvent`, producer-side types for constructing schema-valid webhook fixtures | [Building Webhook Payloads (Contract Module)](node-sdk-contract-module) |\n| `@primitivedotdev/sdk/parser` | `parseFromHeader`, `parseFromHeaderLoose`, raw MIME address parsing | [Raw MIME Address Parsing (parser/address)](node-sdk-address-parsing) |\n\nTwo subpaths matter architecturally, not just organizationally:\n\n- **`/api` is Workers-safe.** It re-exports `isTrustedSender`, `validateEmailAuth`, and `normalizeReceivedEmail` specifically so Primitive Functions handlers, which run on an edge runtime, can make trust decisions and normalize inbound events without pulling in `node:crypto`. The root import and `/webhook` both pull `node:crypto` through the Node-crypto signing helpers and break a Workers-style bundle.\n- **`/api` also carries the generated HTTP surface.** `PrimitiveApiClient` and the raw generated operations (`setMemory`, `getMemory`, `searchMemories`, `deleteMemory`, `getAccount`, and every other OpenAPI operation) live here, re-exported from the workspace-internal `@primitivedotdev/api-core` package. See [What is API Core?](api-core-overview) for how that package is built and bundled.\n\n## Why the surface is split this way\n\nThe split mirrors how integrations actually grow. Most handlers start and stay on the root import: receive an email, reply to it, done. Some need signature verification without a standard `Request` object, where the framework hands you raw bytes and headers instead; that's `/webhook`. Some need Primitive Memories or an uncommon operation the high-level client doesn't wrap; that's `/api`. Only integrations doing agent-to-agent payments touch `/x402`, and only tooling that builds or tests webhook fixtures touches `/contract`.\n\nEach subpath is a separate entry point, so a Next.js route that only replies to email never bundles the x402 signing code.\n\n## A concrete example: three subpaths in one handler\n\nA Primitive Function that replies to trusted senders, stores state in Primitive Memories, and settles an x402 payment touches three subpaths at once:\n\n```typescript\nimport { createPrimitiveClient, isTrustedSender } from \"@primitivedotdev/sdk/api\";\nimport { createX402Client } from \"@primitivedotdev/sdk/x402\";\n\nconst client = createPrimitiveClient({ apiKey: process.env.PRIMITIVE_API_KEY! });\nconst x402 = createX402Client({ apiKey: process.env.PRIMITIVE_API_KEY! });\n\nexport default {\n  async fetch(request: Request): Promise<Response> {\n    const event = await request.json();\n\n    const trust = isTrustedSender(event, { domain: \"example.com\" });\n    if (!trust.trusted) {\n      return new Response(\"untrusted sender\", { status: 403 });\n    }\n\n    await client.memories.set({ key: \"last_seen\", value: { at: Date.now() } });\n\n    const challenge = await x402.charge({ amountUsdc: \"0.01\", network: \"base-sepolia\" });\n    return Response.json({ challenge });\n  },\n};\n```\n\nEvery import here comes from `/api` or `/x402` rather than the root. That is exactly the Workers-safe path a Primitive Function needs.\n\n## What lives outside these subpaths\n\nTwo capabilities ship as part of the SDK but aren't separate subpaths:\n\n- **Primitive Payloads** (streaming large, end-to-end-encrypted attachments with `pushFile`/`pushBytes`/`pullFile`) backs `client.sendAttachment`, which picks inline delivery versus a payload reference by size for you. Inline attachments are the default under the inline size cap (~25-30 MiB). See [Primitive Payloads: Streaming Large Attachments](node-sdk-payloads).\n- **Agent accounts** (`client.agent.createAccount`, the email-claim flow) hang off the same `client` object you get from `primitive.client(...)`. See [Agent Accounts](node-sdk-agent-accounts).\n\n## Next steps\n\n<CardGroup cols={2}>\n\n<Card title=\"Node.js SDK Quickstart\" href=\"node-sdk-quickstart\">\n\nInstall the SDK, set your API key, and receive and reply to your first inbound email in a Next.js route.\n\n</Card>\n\n<Card title=\"Sending, Replying, and Forwarding Email\" href=\"node-sdk-sending-email\">\n\nUse client.send, client.reply, and client.forward with wait mode and attachments.\n\n</Card>\n\n<Card title=\"Generated API Client and Primitive Memories\" href=\"node-sdk-api-client\">\n\nCall any Primitive HTTP endpoint directly and store durable JSON records.\n\n</Card>\n\n<Card title=\"x402 Payments Overview\" href=\"x402-payments-overview\">\n\nUnderstand the non-custodial USDC payment model shared by every SDK.\n\n</Card>\n\n</CardGroup>","canonical_base_url":"https://test.abhinandan.one","seo_indexing_enabled":true,"last_modified":"2026-08-21T18:22:43.359885+00:00","video_url":null,"voiceover_url":null,"tools_used":[],"demonstrated_by":[],"steps":[],"related_links":[],"intro":null,"prerequisites":[],"verification":[],"troubleshooting":[],"suggest_edit_url":"https://github.com/abhi-browzer/primitive-sdks/edit/main/sdk-node/README.md","raise_issue_url":"https://github.com/abhi-browzer/primitive-sdks/issues/new?title=Docs+feedback%3A+What+is+the+Primitive+Node.js+SDK%3F&body=Page%3A+https%3A%2F%2Ftest.abhinandan.one%2Fnode-sdk-overview","page_feedback_enabled":true,"verified_ref":null,"verified_at":"2026-08-11T18:38:45.205849+00:00"}}