@marlinjai/mail-sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 marlinjai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,293 @@
+# @marlinjai/mail-sdk
+
+The typed client for the Lumitra Mail v1 Application Programming Interface (API).
+Every request and response shape comes from `@marlinjai/mail-contract`
+(workspace dependency): this package only adds the Hypertext Transfer Protocol
+(HTTP) mechanics on top (authentication, retries, idempotency, cursor
+pagination). Nothing here redefines a shape the contract already owns.
+
+Runs in Node 20+ (Node 18/19 need `--experimental-global-webcrypto` for
+`crypto.randomUUID`, which the SDK uses to mint idempotency keys) and on every
+major edge runtime: only `fetch`, `FormData`, `AbortController` and
+`globalThis.crypto` are used, no `node:` built-ins.
+
+## Install
+
+```bash
+pnpm add @marlinjai/mail-sdk
+```
+
+## Quick start: a server-side client in a Next.js app (ŌPUNTIA's Studio)
+
+ŌPUNTIA's admin keeps its own people and pushes recipients per mailing; the mail
+service is its mail infrastructure. A workspace application programming
+interface (API) key is created once in the mail service's dashboard and stored
+as a server-only secret (never shipped to the browser).
+
+```ts
+// lib/mail-client.ts (server-only module)
+import { createMailClient } from '@marlinjai/mail-sdk';
+
+export const mail = createMailClient({
+  baseUrl: process.env.MAIL_SERVICE_URL!, // e.g. https://mail.lumitra.co
+  apiKey: process.env.MAIL_API_KEY!, // a workspace key, scope "send" is enough to mail people
+});
+```
+
+```ts
+// app/actions/send-programme-update.ts ("use server")
+import { mail } from '@/lib/mail-client';
+
+export async function sendProgrammeUpdate(document: unknown, recipients: { email: string; external_id: string }[]) {
+  const mailing = await mail.mailings.create({
+    subject: 'This week at ŌPUNTIA',
+    topic: 'programme-updates',
+    provider_id: process.env.MAIL_PROVIDER_ID!,
+    document: document as never, // the editor's TemplateDocument
+  });
+
+  await mail.mailings.addRecipients(mailing.id, { recipients });
+  await mail.mailings.send(mailing.id);
+  return mailing;
+}
+```
+
+Every mutating call carries its own `Idempotency-Key` automatically, reused
+across retries, so calling `sendProgrammeUpdate` again after a network blip
+never double-sends: a retried `mailings.send` with the same key returns the
+first response instead of starting a second send.
+
+### Paginating a list
+
+```ts
+for await (const contact of mail.paginate('contacts.list', { query: { topic: 'programme-updates' } })) {
+  console.log(contact.email);
+}
+```
+
+`paginate` only accepts operations whose response is a cursor page (`{ data,
+next_cursor }`); passing `billing.plans` or `contactProperties.list`, which
+return a bare `{ data }` array, is a compile error, not a runtime surprise.
+
+### Anything the friendly methods do not cover
+
+Every namespaced method (`mail.mailings.*`, `mail.contacts.*`, and so on) is a
+thin wrapper over `mail.request(operationId, { params, query, body })`, which
+accepts any operation id from `@marlinjai/mail-contract`'s route table and is
+typed from the same source. Reach for it directly for an operation this
+package has not wrapped yet, or to pass a raw `AbortSignal`.
+
+```ts
+const workspace = await mail.request('workspace.get');
+```
+
+## The dashboard variant: server-only, per signed-in person
+
+The mail service's own dashboard (`apps/dashboard`) signs people in through
+auth-brain and calls the service with its own service token plus the signed-in
+person's auth-brain subject and workspace. **`createDashboardMailClient` must
+never run in a browser**: its service token authenticates as the whole
+dashboard, not one person, and shipping it to a browser bundle would leak it to
+every visitor. The constructor throws immediately if it detects a `window`
+global, but the real guarantee has to come from where you call it: only from
+server-side code (a Next.js server action, route handler or server component).
+
+```ts
+// lib/dashboard-mail-client.ts (server-only module)
+import { createDashboardMailClient } from '@marlinjai/mail-sdk';
+
+const dashboardMail = createDashboardMailClient({
+  baseUrl: process.env.MAIL_SERVICE_URL!,
+  serviceToken: process.env.MAIL_DASHBOARD_SERVICE_TOKEN!,
+});
+
+export function mailClientFor(subject: string, workspaceId: string) {
+  return dashboardMail.forUser({ subject, workspaceId });
+}
+```
+
+```ts
+// app/dashboard/mailings/actions.ts ("use server")
+import { auth } from '@/lib/auth-brain'; // however the app resolves the signed-in person
+import { mailClientFor } from '@/lib/dashboard-mail-client';
+
+export async function pauseMailing(mailingId: string) {
+  const session = await auth();
+  const client = mailClientFor(session.subject, session.workspaceId);
+  return client.mailings.pause(mailingId);
+}
+```
+
+The service checks that `subject`'s membership and role in `workspaceId` on
+every call; the SDK never assumes the caller is authorized, it only carries the
+headers.
+
+### Creating a workspace: the one call with no workspace yet
+
+`workspaces.create` and `workspaces.list` are `dashboard`-access routes: they
+run before the signed-in person has a workspace to be scoped to, so
+`workspaceId` is optional on `forUser` for exactly these two calls (every other
+route needs it, and the service checks membership against it on every call).
+
+```ts
+const client = dashboardMail.forUser({ subject: session.subject }); // no workspaceId yet
+const workspace = await client.workspaces.create({
+  slug: 'opuntia',
+  name: 'ŌPUNTIA',
+  owner: { email: session.email, name: session.name },
+});
+// From here on, calls for this workspace pass its id: forUser({ subject, workspaceId: workspace.id }).
+```
+
+Adding a person to an existing workspace binds them by their auth-brain
+subject, not an email invite (the service never sees a login, so the caller
+resolves the person first):
+
+```ts
+await client.members.add({ subject: person.subject, email: person.email, name: person.name, role: 'editor' });
+```
+
+## A webhook receiver
+
+The webhook signature helpers and the `WebhookEvent` union are re-exported from
+`@marlinjai/mail-contract`, so a receiver needs only this one package.
+
+```ts
+// app/api/mail-webhooks/route.ts
+import { WEBHOOK_SIGNATURE_HEADER, WEBHOOK_TIMESTAMP_HEADER, WebhookEvent, verifyWebhook } from '@marlinjai/mail-sdk';
+
+export async function POST(req: Request) {
+  const rawBody = await req.text();
+  const check = await verifyWebhook({
+    secret: process.env.MAIL_WEBHOOK_SECRET!,
+    rawBody,
+    signatureHeader: req.headers.get(WEBHOOK_SIGNATURE_HEADER),
+    timestampHeader: req.headers.get(WEBHOOK_TIMESTAMP_HEADER),
+  });
+  if (!check.ok) return new Response(check.reason, { status: 401 });
+
+  const event = WebhookEvent.parse(JSON.parse(rawBody));
+  // Deliveries may repeat: deduplicate on event.id before acting on it.
+  switch (event.type) {
+    case 'message.sent':
+      // archive event.data.html next to your own record of the send
+      break;
+    case 'contact.unsubscribed':
+      // mirror the unsubscribe into your own system of record
+      break;
+    case 'contact.resubscribed':
+      // the person opted back in on the hosted page: lift your mirror of the unsubscribe
+      break;
+    // ...
+  }
+  return new Response(null, { status: 204 });
+}
+```
+
+## Errors
+
+Every failure is one of four typed classes; a switch on `instanceof` (or on
+`MailApiError.code`) is always enough, never on `.message`, which is for
+humans:
+
+| Class | When |
+| --- | --- |
+| `MailApiError` | The service answered a non-2xx response. Carries `code` (`ErrorCode` from the contract), `status`, `message`, `details` and `requestId`. |
+| `MailNetworkError` | The request never reached the service (Domain Name System (DNS), Transport Layer Security (TLS), connection reset). |
+| `MailTimeoutError` | A single attempt exceeded `timeoutMs`. |
+| `MailResponseValidationError` | The service answered 2xx but the body did not match the contract's schema (a service bug or a contract version mismatch). Never retried: retrying an already-succeeded mutating call risks a duplicate. |
+
+```ts
+import { MailApiError } from '@marlinjai/mail-sdk';
+
+try {
+  await mail.mailings.send(mailingId);
+} catch (err) {
+  if (err instanceof MailApiError && err.code === 'missing_unsubscribe_url') {
+    // the document has no {{unsubscribe_url}}; show the editor error, don't retry
+  }
+  throw err;
+}
+```
+
+## Retries
+
+Retries apply only to network failures, request timeouts, and responses whose
+error `code` is in the contract's `RETRYABLE_ERRORS` (`rate_limited`,
+`provider_error`, `internal_error`, `service_unavailable`). Every other error,
+including `daily_budget_exhausted` and `plan_limit_reached` even though both
+are HTTP 429, is never retried: retrying them would not help, since the
+condition they report does not clear on its own within the request's lifetime.
+For the same reason a `service_unavailable` whose `details.reason` is
+`billing_not_configured` (checkout or the portal while Stripe is not set up) is
+answered at once; the contract's `isRetryableError` holds the rule.
+
+- Exponential backoff with full jitter, capped at 8 seconds between attempts.
+- `Retry-After` (seconds or a Hypertext Transfer Protocol (HTTP) date) is
+  honoured when the service sends it, capped at 60 seconds so a large value can
+  never hang a caller.
+- A fresh `Idempotency-Key` is minted once per call (via `crypto.randomUUID()`)
+  and reused across every attempt of that call: this is what makes a retry safe.
+  A caller may also pass its own key through the last `opts` argument any
+  mutating method takes (`{ idempotencyKey }`).
+- `maxRetries` (default 3) and `timeoutMs` (default 10000, per attempt) are
+  configurable on `createMailClient`.
+- A caller-provided `AbortSignal` (also in the last `opts` argument) is never
+  itself retried: an abort you asked for propagates immediately.
+
+## Response headers: usage warnings
+
+A successful call's headers are available through `onResponse` in the last
+`opts` argument. It receives the status, the request id, the raw `Headers`,
+and `usageWarnings`: the `x-mail-usage-warning` header (sent on
+`mailings.send` and `mailings.test` once the workspace is at 80 percent of a
+plan limit) already parsed into `{ metric, used, limit }` entries.
+
+```ts
+let warnings: UsageWarningHeaderEntry[] = [];
+await mail.mailings.send(mailingId, { onResponse: (meta) => (warnings = meta.usageWarnings) });
+if (warnings.length > 0) {
+  // e.g. "messages: 8200 of 10000 this period"; show it before the next send
+}
+```
+
+`onResponse` runs once the body has parsed and validated, just before the call
+returns; it is not called for a failed call (a `MailApiError` carries its own
+status and request id). A limit that is already exceeded fails the call
+with `plan_limit_reached` (HTTP 429), whose `details` name the `metric`, the
+`used` count, the `limit` and the `plan`.
+
+## Health check
+
+`client.health()` hits the service's liveness probe (`HEALTH_PATH`, outside
+`/v1`, no credentials) and never throws: a network failure or a non-2xx status
+both resolve `false`. Meant for a caller polling "is it up" (a deploy script, a
+monitor), not for anything that needs a typed error.
+
+```ts
+if (!(await mail.health())) {
+  // back off and retry, or alert
+}
+```
+
+## Configuration
+
+```ts
+createMailClient({
+  baseUrl: string; // the mail service's origin, e.g. "https://mail.lumitra.co"
+  apiKey: string; // a workspace API key: `Authorization: Bearer <key>`
+  fetch?: typeof fetch; // defaults to the runtime's global fetch
+  timeoutMs?: number; // default 10000, per attempt
+  maxRetries?: number; // default 3
+  userAgent?: string;
+  validateResponses?: boolean; // default true; disable only once you trust the deployment
+});
+```
+
+## Development
+
+```bash
+pnpm -F @marlinjai/mail-sdk run build   # tsup, dual CJS/ESM + .d.ts
+pnpm -F @marlinjai/mail-sdk run lint    # tsc --noEmit (the linter for this repo)
+pnpm -F @marlinjai/mail-sdk run test    # vitest, a mocked fetch, no network
+```