feat!: Lettermint Node SDK 3.0

[bjarn]

Summary

Lettermint Node SDK 3.0, a new major version. The main reason is safety: in 2.x, Lettermint.email(token) returned one mutable builder per client. Two emails built at the same time on one client could mix recipients, content and Idempotency-Key, and an email abandoned halfway leaked into the next send. 3.0 stores nothing about a message on the client.

const lettermint = new Lettermint('lm_…');             // or { sendingToken }, { teamToken }, or both
await lettermint.emails.send({ from, to, subject, html }, { idempotencyKey: 'order-123' });
const base = lettermint.emails.compose().from('Acme <hi@acme.com>');   // immutable builder
for await (const domain of lettermint.domains.iterate()) { … }
const event = await new Webhook(secret).verify(rawBody, req.headers);

What changes

• One client. new Lettermint({ sendingToken, teamToken }) replaces Lettermint.email() and Lettermint.api(). One token is enough.
  • Each part uses its own token and never falls back to the other: emails.* uses the sending token, the Team API uses the team token. ping(), messages.reschedule() and messages.cancel() accept either.
  • A single string is classified by format: lm_team_ plus letters and digits is a team token, lm_ plus letters and digits is a sending token. Anything else (such as lm_sso_…) throws.
• Stateless sending. emails.send(), emails.sendBatch(), and an immutable emails.compose() builder where every setter returns a new builder. The idempotency key is a per-call option. Attachments are objects.
• Typed errors. ApiError (with status and API code) and its subclasses for 401, 403, 404, 409, 422, 429 and 5xx. Also TimeoutError, ConnectionError, UnexpectedResponseError (empty or HTML bodies) and RedirectError. Class names survive the build.
• Transport.
  • Redirects are never followed, so tokens never go to another host.
  • The timeout covers the response body.
  • Tokens never appear in console.log, util.inspect or JSON.stringify.
• Runtimes. Node 20+, Bun, Deno and edge runtimes. No dependencies, no Buffer, no node: imports.
• Team API. Typed query objects, CursorPage<T>, and iterate() helpers. A few methods moved, e.g. projects.routes(id) → routes.list(projectId).
• Webhooks. verify() is async (Web Crypto). It requires both X-Lettermint-Signature and X-Lettermint-Delivery, accepts any matching v1, and accepts strings or bytes.
• Types. Generated from the current API spec (lettermint/lettermint#2582) with its names, e.g. ListDomainsResponse, ProjectMutationResponse, ApiError. Enums are open, so new API values don't break typing.
• Package. ESM and CommonJS with default and named exports. Unminified, without source maps (582 kB unpacked).
• Upgrade with a coding agent: UPGRADE.md has a ready-to-copy instruction for Claude Code, Codex and similar tools. It ships in the package, so agents can read the guide from node_modules.
• 2.x no longer receives updates. UPGRADE.md covers every changed call and the full type rename table. All 81 removed or renamed 2.x exports are listed (checked by script).
• Includes the unreleased feat(webhooks)!: add Basic Auth and required read flags #35 (webhook Basic Auth types).

Release notes for the maintainer

• Release as 3.0.0 by publishing a GitHub release v3.0.0. release.yaml sets the version from the tag. package.json says 3.0.0-dev on the branch.
• The docs update is a separate PR: lettermint/lettermint#2590. Merge it after 3.0.0 is on npm.

Verification

• 300 Jest tests pass on Node 20, 22, 24 and 26; a Bun run of the built package also passes.
• Lint, type-check and build pass.
• npm run test:smoke packs the tarball and checks:
  • the file list;
  • ESM import and CJS require;
  • types under nodenext;
  • that tokens stay out of debug output.
• Shared conformance suite (private lettermint/sdk-generator): 42 of 42 scenarios pass with --strict. They cover concurrent and half-built emails, unknown enum values, empty and HTML bodies, redirects, timeouts, token redaction, token detection and 25 webhook vectors. For comparison, 2.8.0 fails 7.
• README and UPGRADE snippets type-check against the build.