shipmail 0.1.20 → 0.1.22

package/README.md

@@ -1,219 +1,471 @@
-# ShipMail TypeScript SDK
-
-Official TypeScript SDK for the [ShipMail](https://shipmail.to) API. Zero runtime dependencies. Works with Node.js 18+, Bun, and Deno.
-
-## Installation
+# Shipmail TypeScript SDK
+
+[![npm version](https://img.shields.io/npm/v/shipmail.svg)](https://www.npmjs.com/package/shipmail)
+[![npm downloads](https://img.shields.io/npm/dm/shipmail.svg)](https://www.npmjs.com/package/shipmail)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/shipmail.svg)](https://bundlephobia.com/package/shipmail)
+[![types](https://img.shields.io/npm/types/shipmail.svg)](https://www.npmjs.com/package/shipmail)
+[![license](https://img.shields.io/npm/l/shipmail.svg)](./LICENSE)
+
+Official TypeScript SDK for the [Shipmail](https://shipmail.to) API. Zero runtime dependencies. Native `fetch`. Full TypeScript types. ESM and CommonJS.
+
+**Runtimes**: Node.js 18+, Bun, Deno. Webhook verification uses `node:crypto` (enable `nodejs_compat` on Cloudflare Workers if you verify webhooks there).
+
+## Contents
+
+- [Install](#install)
+- [Quick start](#quick-start)
+- [Configuration](#configuration)
+- [Domains](#domains)
+- [Mailboxes](#mailboxes)
+- [Messages](#messages)
+- [Threads](#threads)
+- [Webhooks](#webhooks)
+- [Suppressions](#suppressions)
+- [Status](#status)
+- [Pagination](#pagination)
+- [Webhook verification](#webhook-verification)
+- [Per-request options](#per-request-options)
+- [Idempotency](#idempotency)
+- [Cancellation](#cancellation)
+- [Custom fetch and proxies](#custom-fetch-and-proxies)
+- [Errors](#errors)
+- [Retries](#retries)
+- [Bundling](#bundling)
+- [Testing](#testing)
+- [License](#license)
+- [Links](#links)
+
+## Install
 
 ```bash
+bun add shipmail
+# or
 npm install shipmail
 # or
-bun add shipmail
+pnpm add shipmail
 ```
 
-Requires Node.js 18+ (uses native `fetch` and `crypto`).
-
-## Quick Start
+## Quick start
 
-```typescript
-import ShipMail from "shipmail";
-
-const client = new ShipMail("sm_live_...");
+```ts
+import { ShipMailClient } from "shipmail";
 
-// Create a domain
-const domain = await client.domains.create({ name: "example.com" });
+const shipmail = new ShipMailClient({ apiKey: process.env.SHIPMAIL_API_KEY! });
 
-// Send an email
-const message = await client.messages.send({
+const message = await shipmail.messages.send({
   mailbox_id: "mbx_...",
-  to: [{ address: "user@example.com" }],
+  to: [{ address: "user@example.com", name: "User" }],
   subject: "Hello",
-  body_text: "Hi there",
+  text: "Hi there",
+  html: "<p>Hi there</p>",
 });
 ```
 
-## Configuration
+The SDK does not auto-read environment variables. Pass the key explicitly.
 
-```typescript
-import { ShipMailClient } from "shipmail";
+You can also pass a key string directly:
 
-const client = new ShipMailClient({
-  apiKey: "sm_live_...",
-  baseUrl: "https://shipmail.to/api/v1", // default
-  maxRetries: 2, // default, retries on 5xx and 429
-  timeout: 30_000, // default, in milliseconds
-});
+```ts
+const shipmail = new ShipMailClient("sm_live_...");
 ```
 
-## Resources
+## Configuration
 
-### Domains
+```ts
+const shipmail = new ShipMailClient({
+  apiKey: process.env.SHIPMAIL_API_KEY!,
+  baseUrl: "https://shipmail.to/api/v1",
+  maxRetries: 2,
+  timeout: 30_000,
+  fetch: customFetch,
+  defaultHeaders: { "x-app-name": "my-app" },
+});
+```
 
-```typescript
-const domain = await client.domains.create({ name: "example.com" });
-const domains = await client.domains.list({ limit: 10 });
-const domain = await client.domains.get("dom_...");
-const updated = await client.domains.update("dom_...", { catch_all_mailbox_id: "mbx_..." });
-await client.domains.delete("dom_...");
-const result = await client.domains.verify("dom_...");
+| Option           | Type                     | Default                      | Description                                                     |
+| ---------------- | ------------------------ | ---------------------------- | --------------------------------------------------------------- |
+| `apiKey`         | `string`                 | required                     | Shipmail API key (`sm_live_...`).                               |
+| `baseUrl`        | `string`                 | `https://shipmail.to/api/v1` | API base URL.                                                   |
+| `maxRetries`     | `number`                 | `2`                          | Retry count on 5xx and 429. Total attempts is `maxRetries + 1`. |
+| `timeout`        | `number`                 | `30_000`                     | Per-request timeout in ms.                                      |
+| `fetch`          | `typeof fetch`           | `globalThis.fetch`           | Custom fetch implementation.                                    |
+| `defaultHeaders` | `Record<string, string>` | `{}`                         | Headers added to every request.                                 |
+
+## Domains
+
+```ts
+await shipmail.domains.create({ name: "example.com" });
+await shipmail.domains.list({ limit: 10 });
+await shipmail.domains.get("dom_...");
+await shipmail.domains.update("dom_...", { catch_all_mailbox_id: "mbx_..." });
+await shipmail.domains.delete("dom_...");
+await shipmail.domains.verify("dom_...");
+await shipmail.domains.search({ keyword: "example" });
+await shipmail.domains.register({
+  name: "example.com",
+  years: 1,
+  contact: {
+    first_name: "Jane",
+    last_name: "Doe",
+    address1: "1 Main St",
+    /* ... */
+  },
+});
 ```
 
-### Mailboxes
+## Mailboxes
 
-```typescript
-const mailbox = await client.mailboxes.create({
+```ts
+await shipmail.mailboxes.create({
   domain_id: "dom_...",
   address: "hello",
   display_name: "Hello",
 });
-const mailboxes = await client.mailboxes.list({ domain_id: "dom_..." });
-const mailbox = await client.mailboxes.get("mbx_...");
-const updated = await client.mailboxes.update("mbx_...", { display_name: "New Name" });
-await client.mailboxes.delete("mbx_...");
+await shipmail.mailboxes.list({ domain_id: "dom_..." });
+await shipmail.mailboxes.get("mbx_...");
+await shipmail.mailboxes.update("mbx_...", { display_name: "New Name" });
+await shipmail.mailboxes.resetPassword("mbx_...", { password: "NewPassword1" });
+const folders = await shipmail.mailboxes.listFolders("mbx_...");
+const folder = await shipmail.mailboxes.createFolder("mbx_...", {
+  name: "VIP",
+  parent_id: null,
+});
+await shipmail.mailboxes.updateFolder("mbx_...", folder.id, { name: "VIP Clients" });
+await shipmail.mailboxes.deleteFolder("mbx_...", folder.id);
+const identities = await shipmail.mailboxes.listIdentities("mbx_...");
+const rules = await shipmail.mailboxes.getRules("mbx_...");
+await shipmail.mailboxes.updateRules("mbx_...", { rules: rules.rules });
+await shipmail.mailboxes.updateSpamFilter("mbx_...", { threshold: 8 });
+await shipmail.mailboxes.delete("mbx_...");
+
+await shipmail.mailboxes.updateAutoReply("mbx_...", {
+  enabled: true,
+  subject: "Out of office",
+  body: "Back on Monday.",
+  from_date: "2026-06-01",
+  to_date: "2026-06-07",
+});
 ```
 
-### Messages
+## Messages
 
-```typescript
-const message = await client.messages.send({
+```ts
+await shipmail.messages.send({
   mailbox_id: "mbx_...",
-  to: [{ address: "user@example.com", name: "User" }],
+  to: [{ address: "user@example.com" }],
   cc: [{ address: "cc@example.com" }],
   subject: "Hello",
-  body_html: "<p>Hi there</p>",
-  body_text: "Hi there",
+  text: "Hi there",
+  html: "<p>Hi there</p>",
 });
 
-const message = await client.messages.get("msg_...");
+await shipmail.messages.list({ mailbox_id: "mbx_...", limit: 25 });
+await shipmail.messages.get("msg_...");
+
+await shipmail.messages.reply("msg_...", {
+  to: [{ address: "user@example.com" }],
+  text: "Thanks for your email.",
+});
 ```
 
-### Threads
+## Threads
 
-```typescript
-const threads = await client.threads.list({ mailbox_id: "mbx_..." });
-const thread = await client.threads.get("thd_...");
-const reply = await client.threads.reply("thd_...", {
-  body_text: "Thanks for your email",
-  to: [{ address: "user@example.com" }],
+```ts
+const threads = await shipmail.threads.list({ mailbox_id: "mbx_..." });
+const threadId = threads.data[0].id;
+const thread = await shipmail.threads.get(threadId);
+
+await shipmail.threads.reply(threadId, {
+  text: "Thanks for your email.",
 });
 ```
 
-### Webhooks
+## Webhooks
 
-```typescript
-const webhook = await client.webhooks.create({
+```ts
+const webhook = await shipmail.webhooks.create({
   url: "https://example.com/webhook",
   events: ["message.received", "message.sent"],
-  description: "My webhook",
+  description: "Incoming email handler",
 });
-// webhook.secret is only available at creation time
+// webhook.secret is returned only on creation. Store it now.
+
+await shipmail.webhooks.list();
+await shipmail.webhooks.get("whk_...");
+await shipmail.webhooks.update("whk_...", { active: false });
+await shipmail.webhooks.delete("whk_...");
+
+await shipmail.webhooks.rotateSecret("whk_...");
+await shipmail.webhooks.test("whk_...");
+await shipmail.webhooks.listDeliveries("whk_...");
+```
+
+Supported event types:
+
+```
+message.received
+message.sent
+message.delivered
+message.bounced
+message.complained
+domain.verified
+domain.verification_failed
+domain.degraded
+org.reputation_warning
+org.sending_throttled
+org.sending_suspended
+org.reputation_recovered
+```
+
+## Suppressions
+
+```ts
+await shipmail.suppressions.list({ limit: 25 });
+await shipmail.suppressions.remove("user@example.com");
+```
 
-const webhooks = await client.webhooks.list();
-const webhook = await client.webhooks.get("whk_...");
-const updated = await client.webhooks.update("whk_...", { active: false });
-await client.webhooks.delete("whk_...");
+Auto-paginate:
 
-const rotated = await client.webhooks.rotateSecret("whk_...");
-const test = await client.webhooks.test("whk_...");
-const deliveries = await client.webhooks.listDeliveries("whk_...");
+```ts
+for await (const item of shipmail.suppressions.listAutoPaginating({ limit: 100 })) {
+  console.log(item.email_address, item.reason);
+}
 ```
 
-### Status
+## Status
 
-```typescript
-const status = await client.status.get();
+```ts
+const status = await shipmail.status.get();
 ```
 
 ## Pagination
 
-List methods return a paginated response with cursor-based pagination:
+List methods return `{ data, pagination }` with cursor-based pagination:
 
-```typescript
-const page = await client.domains.list({ limit: 10 });
-console.log(page.data); // Domain[]
-console.log(page.pagination); // { next_cursor, has_more }
+```ts
+const page = await shipmail.domains.list({ limit: 10 });
+page.data; // Domain[]
+page.pagination; // { next_cursor, has_more }
 
-// Fetch next page
 if (page.pagination.has_more) {
-  const next = await client.domains.list({
+  const next = await shipmail.domains.list({
     cursor: page.pagination.next_cursor,
     limit: 10,
   });
 }
 ```
 
-Auto-pagination iterates through all pages automatically:
+Auto-paginate over all pages:
 
-```typescript
-for await (const domain of client.domains.listAutoPaginating({ limit: 25 })) {
+```ts
+for await (const domain of shipmail.domains.listAutoPaginating({ limit: 25 })) {
   console.log(domain.name);
 }
 ```
 
-## Webhook Verification
+`listAutoPaginating` is available on `domains`, `mailboxes`, `messages`, `threads`, `webhooks`, `webhooks.listDeliveriesAutoPaginating`, and `suppressions`.
+
+## Webhook verification
 
 Verify incoming webhook signatures without instantiating a client:
 
-```typescript
+```ts
 import { verifyWebhook, WebhookVerificationError } from "shipmail";
 
 try {
   const event = await verifyWebhook(rawBody, request.headers, webhookSecret);
-  console.log(event.event_type); // e.g., "message.received"
-  console.log(event.data);
+  event.event_type; // typed WebhookEventType union
+  event.data;
 } catch (err) {
   if (err instanceof WebhookVerificationError) {
-    return new Response("Invalid signature", { status: 401 });
+    // signature mismatch, missing header, expired timestamp, etc.
+  }
+}
+```
+
+### Next.js Route Handler example
+
+App Router consumes `request.text()` to get the raw body. Do not parse to JSON before verifying.
+
+```ts
+// app/api/webhooks/shipmail/route.ts
+import { verifyWebhook, WebhookVerificationError } from "shipmail";
+
+export async function POST(request: Request) {
+  const rawBody = await request.text();
+  const secret = process.env.SHIPMAIL_WEBHOOK_SECRET!;
+
+  try {
+    const event = await verifyWebhook(rawBody, request.headers, secret);
+    // handle event...
+    return new Response("ok");
+  } catch (err) {
+    if (err instanceof WebhookVerificationError) {
+      return new Response("invalid signature", { status: 401 });
+    }
+    throw err;
   }
 }
 ```
 
-## Error Handling
+## Per-request options
+
+Every method accepts a final `options` argument:
+
+```ts
+type MethodOptions = {
+  timeout?: number;
+  signal?: AbortSignal;
+  headers?: Record<string, string>;
+  idempotencyKey?: string;
+};
+```
+
+```ts
+await shipmail.messages.send(params, {
+  timeout: 5_000,
+  headers: { "x-trace-id": traceId },
+});
+```
+
+## Idempotency
+
+Pass `idempotencyKey` on mutating calls to make them safe to retry:
+
+```ts
+await shipmail.messages.send(
+  {
+    mailbox_id: "mbx_...",
+    to: [{ address: "user@example.com" }],
+    subject: "Receipt",
+    text: "Thanks for your purchase.",
+  },
+  { idempotencyKey: `receipt-${orderId}` },
+);
+```
+
+The SDK adds the key as the `Idempotency-Key` header. Reuse the same key to retry without sending a duplicate email. Keys are scoped per API key.
+
+## Cancellation
+
+Pass an `AbortSignal` to cancel an in-flight request. The signal also cancels SDK-internal retries:
+
+```ts
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 2_000);
+
+await shipmail.messages.send(params, { signal: controller.signal });
+```
 
-The SDK throws typed errors that map to API error responses:
+## Custom fetch and proxies
 
-```typescript
+Inject a custom fetch implementation for proxies, observability, or testing:
+
+```ts
+const shipmail = new ShipMailClient({
+  apiKey: process.env.SHIPMAIL_API_KEY!,
+  fetch: async (url, init) => {
+    const start = Date.now();
+    const res = await fetch(url, init);
+    metrics.histogram("shipmail.fetch.duration_ms", Date.now() - start);
+    return res;
+  },
+});
+```
+
+The custom fetch receives the same arguments as the global `fetch` and must return a `Response`.
+
+## Errors
+
+The SDK throws typed errors that map to HTTP responses. All inherit from `ShipMailError`:
+
+```ts
 import {
   ShipMailError,
   AuthenticationError,
   AuthorizationError,
   ValidationError,
   NotFoundError,
-  RateLimitError,
   ConflictError,
+  RateLimitError,
+  QuotaExceededError,
   InternalServerError,
   ConnectionError,
 } from "shipmail";
 
 try {
-  await client.domains.create({ name: "" });
+  await shipmail.messages.send(params);
 } catch (err) {
   if (err instanceof ValidationError) {
-    console.log(err.message); // Error message
-    console.log(err.details); // Field-level validation errors
+    err.message;
+    err.details; // field-level validation errors
   }
   if (err instanceof RateLimitError) {
-    console.log(err.retryAfter); // Seconds to wait
+    err.retryAfter; // seconds
   }
   if (err instanceof ShipMailError) {
-    console.log(err.status); // HTTP status code
-    console.log(err.type); // Error type string
-    console.log(err.requestId); // Request ID for support
-    console.log(err.retryable); // Whether the request can be retried
+    err.status; // HTTP status
+    err.type; // error type string
+    err.requestId; // include this when contacting support
+    err.retryable;
   }
+  throw err;
 }
 ```
 
+| Error                 | When                                                           |
+| --------------------- | -------------------------------------------------------------- |
+| `AuthenticationError` | 401. Bad or missing API key.                                   |
+| `AuthorizationError`  | 403. Key lacks permission for the resource.                    |
+| `ValidationError`     | 400 or 422. See `details` for per-field errors.                |
+| `NotFoundError`       | 404.                                                           |
+| `ConflictError`       | 409. Resource already exists or state conflict.                |
+| `RateLimitError`      | 429. Read `retryAfter` (seconds).                              |
+| `QuotaExceededError`  | 402. Plan or sending quota exceeded.                           |
+| `InternalServerError` | 5xx. Retried automatically up to `maxRetries`.                 |
+| `ConnectionError`     | Network error, timeout, or DNS failure. Retried automatically. |
+
 ## Retries
 
-The SDK automatically retries on 5xx errors and 429 (rate limit) responses with exponential backoff and jitter. Configure with `maxRetries` (default: 2, meaning up to 3 total attempts).
+The SDK retries on `5xx`, `429`, and connection errors with exponential backoff and jitter. `Retry-After` is honored when present. Default is 2 retries (3 total attempts).
 
-```typescript
-const client = new ShipMailClient({
-  apiKey: "sm_live_...",
-  maxRetries: 0, // Disable retries
+```ts
+new ShipMailClient({ apiKey, maxRetries: 0 }); // disable retries
+```
+
+Retries respect any `AbortSignal` you pass via `MethodOptions.signal`.
+
+## Bundling
+
+The package ships ESM and CommonJS via `exports`, with `"sideEffects": false` for tree-shaking. Importing a single resource pulls in only what it needs. The published bundle has no runtime dependencies.
+
+## Testing
+
+Mock by injecting a custom `fetch` at construction time:
+
+```ts
+const shipmail = new ShipMailClient({
+  apiKey: "sm_live_test",
+  fetch: async () =>
+    new Response(JSON.stringify({ id: "msg_123", status: "queued" }), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    }),
 });
 ```
 
+This is the recommended pattern for unit tests. No HTTP interception or mocking library required.
+
 ## License
 
-MIT
+[MIT](./LICENSE).
+
+## Links
+
+- [Shipmail docs](https://shipmail.to/docs)
+- [Quick start](https://shipmail.to/docs/quick-start)
+- [API reference](https://shipmail.to/docs/api)
+- [TypeScript SDK guide](https://shipmail.to/docs/sdks/typescript)
+- [`shipmail-mcp` (MCP server)](https://www.npmjs.com/package/shipmail-mcp)
+- [Changelog](./CHANGELOG.md)
+- [Issues](https://github.com/jcoulaud/ShipMail/issues)