@pidgeon-ai/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+Versioned independently of the application. The API is `/v1`; this package
+is `0.x`. They are different contracts with different audiences, and tying
+the two would publish a release for every unrelated product deploy.
+
+Semver applies to **this package's own surface** — the exported types, the
+method signatures, the error shape — not to the API behind it.
+
+## Unreleased
+
+## 0.1.0
+
+First release.
+
+- `Pidgeon` — a typed client over `/v1`: `identities`, `messages`,
+  `attachments`, `threads`, `webhooks`, `events`, `domains`.
+- `verifyWebhook` — the receiving half of the signature scheme, tested
+  against payloads signed by the server's own implementation.
+- `PidgeonError` — one error class, carrying the API's `code`, HTTP
+  `status`, the offending `field` on a validation failure, and the request
+  id.
+- ESM and CommonJS builds with per-condition type declarations. Zero
+  runtime dependencies; needs only `fetch` and `crypto.subtle`.

package/README.md

@@ -0,0 +1,130 @@
+# @pidgeon-ai/sdk
+
+A thin TypeScript client for the [Pidgeon](https://pidgeon.ai) email API.
+Typed `fetch` wrappers, one error class, and a webhook verifier.
+
+**Zero dependencies.** Needs `fetch` and `crypto.subtle`, so it runs on
+Node 18+, Bun, Deno, Cloudflare Workers and Vercel functions. ESM and
+CommonJS.
+
+```bash
+pnpm add @pidgeon-ai/sdk
+```
+
+## Receiving mail
+
+Mail arriving at an address your code owns becomes an event, and your
+endpoint is called with a signed payload.
+
+```ts
+import { Pidgeon, verifyWebhook } from '@pidgeon-ai/sdk';
+
+const pidgeon = new Pidgeon({ apiKey: process.env.PIDGEON_API_KEY! });
+
+export async function POST(request: Request) {
+  // Verify first. An unverified payload is an unauthenticated POST that
+  // claims a message arrived.
+  const event = await verifyWebhook({
+    rawBody: await request.text(),
+    headers: request.headers,
+    secret: process.env.PIDGEON_WEBHOOK_SECRET!,
+  });
+
+  if (event.type !== 'message.received') return new Response(null, { status: 204 });
+
+  // The event carries ids, never a body. Exchange one for the content.
+  const mail = await pidgeon.messages.get(event.data.message_id as string);
+
+  await pidgeon.messages.send({
+    from: mail.to[0].email,
+    to: mail.from.email,
+    subject: `Re: ${mail.subject}`,
+    text: 'Got it — someone will be in touch.',
+    // Keeps the conversation together in the recipient's client too.
+    in_reply_to: mail.id,
+  });
+
+  return new Response(null, { status: 204 });
+}
+```
+
+`rawBody` must be the exact bytes we sent. Parse the JSON _after_
+verifying — re-serialising changes key order and the signature will not
+match.
+
+`verifyWebhook` throws rather than returning a boolean, because the failure
+mode of a boolean is a caller who forgets to check it. It rejects a
+timestamp outside tolerance (five minutes by default) before it looks at
+the signature, and compares in constant time.
+
+## Handing a conversation to a person
+
+```ts
+await pidgeon.threads.handOff(threadId);
+```
+
+It appears in the web inbox, and `thread.updated` tells whatever was
+driving the conversation that it no longer is.
+
+## Errors
+
+Every failure is a `PidgeonError` carrying the API's own `code`, the HTTP
+`status`, the offending `field` on a validation failure, and the request id
+to quote in a support conversation.
+
+```ts
+import { PidgeonError } from '@pidgeon-ai/sdk';
+
+try {
+  await pidgeon.messages.send({ from, to, text });
+} catch (error) {
+  if (error instanceof PidgeonError && error.code === 'rate_limited') {
+    // Back off. Deliberately not done for you — see below.
+  }
+  throw error;
+}
+```
+
+`code` is one of `validation`, `unauthenticated`, `entitlement`,
+`forbidden`, `not_found`, `conflict`, `rate_limited`, `internal`.
+
+## Pagination
+
+List endpoints return a page, not an iterator.
+
+```ts
+let cursor: string | null = null;
+
+do {
+  const page = await pidgeon.events.list({ limit: 50, cursor: cursor ?? undefined });
+  for (const event of page.data) handle(event);
+  cursor = page.next_cursor;
+} while (cursor);
+```
+
+## What this deliberately does not do
+
+No retry policy, no queue, no caching, no auto-paginating iterator. Those
+are decisions that belong to your application — an SDK that makes them for
+you is one you eventually work around, and an iterator that hides
+pagination also hides the rate limit pagination is subject to.
+
+## Options
+
+```ts
+new Pidgeon({
+  apiKey: process.env.PIDGEON_API_KEY!,
+  // Point at a local dev server, or a preview deployment.
+  baseUrl: 'http://localhost:3000/api/v1',
+  // Inject a transport. Useful in tests.
+  fetch: myFetch,
+});
+```
+
+## Versioning
+
+Versioned independently of the API. The API is `/v1`; this package is
+`0.x`, and semver applies to its own surface — the exported types, the
+method signatures, the error shape. See `CHANGELOG.md`.
+
+MIT.

package/dist/index.cjs

@@ -0,0 +1,210 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Pidgeon: () => Pidgeon,
+  PidgeonError: () => PidgeonError,
+  SIGNATURE_HEADER: () => SIGNATURE_HEADER,
+  TIMESTAMP_HEADER: () => TIMESTAMP_HEADER,
+  verifyWebhook: () => verifyWebhook
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var PidgeonError = class extends Error {
+  code;
+  status;
+  field;
+  requestId;
+  constructor(input) {
+    super(input.message);
+    this.name = "PidgeonError";
+    this.code = input.code;
+    this.status = input.status;
+    this.field = input.field;
+    this.requestId = input.requestId;
+  }
+};
+var DEFAULT_BASE_URL = "https://pidgeon.ai/api/v1";
+var Pidgeon = class {
+  #apiKey;
+  #baseUrl;
+  #fetch;
+  constructor(options) {
+    if (!options.apiKey) throw new Error("An API key is required.");
+    this.#apiKey = options.apiKey;
+    this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+  async #request(method, path, options = {}) {
+    const url = new URL(`${this.#baseUrl}${path}`);
+    for (const [key, value] of Object.entries(options.query ?? {})) {
+      if (value !== void 0) url.searchParams.set(key, String(value));
+    }
+    const response = await this.#fetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.#apiKey}`,
+        ...options.body ? { "Content-Type": "application/json" } : {}
+      },
+      body: options.body ? JSON.stringify(options.body) : void 0
+    });
+    const requestId = response.headers.get("x-request-id") ?? void 0;
+    const payload = await response.json().catch(() => null);
+    if (!response.ok || payload?.error) {
+      throw new PidgeonError({
+        code: payload?.error?.code ?? "internal",
+        message: payload?.error?.message ?? `Request failed with ${response.status}.`,
+        status: response.status,
+        field: payload?.error?.field,
+        requestId
+      });
+    }
+    return payload?.data;
+  }
+  // --- identities ---------------------------------------------------------
+  identities = {
+    list: () => this.#request("GET", "/identities"),
+    get: (id) => this.#request("GET", `/identities/${id}`),
+    create: (input) => this.#request("POST", "/identities", { body: input }),
+    update: (id, input) => this.#request("PATCH", `/identities/${id}`, { body: input }),
+    delete: (id) => this.#request("DELETE", `/identities/${id}`)
+  };
+  // --- messages -----------------------------------------------------------
+  messages = {
+    get: (id) => this.#request("GET", `/messages/${id}`),
+    listInThread: (threadId, options = {}) => this.#requestPage("GET", "/messages", {
+      thread_id: threadId,
+      limit: options.limit
+    }),
+    send: (input) => this.#request(
+      "POST",
+      "/messages",
+      { body: input }
+    )
+  };
+  attachments = {
+    /** A short-lived signed URL. Fetch it when you need it, don't store it. */
+    downloadUrl: (id) => this.#request("GET", `/attachments/${id}`)
+  };
+  // --- threads ------------------------------------------------------------
+  threads = {
+    list: (options = {}) => this.#requestPage("GET", "/threads", options),
+    get: (id) => this.#request("GET", `/threads/${id}`),
+    update: (id, input) => this.#request("PATCH", `/threads/${id}`, { body: input }),
+    /** Hand the conversation to a person. The takeover primitive, named. */
+    handOff: (id) => this.#request("PATCH", `/threads/${id}`, {
+      body: { owner_type: "human", status: "human_review" }
+    })
+  };
+  // --- webhooks -----------------------------------------------------------
+  webhooks = {
+    list: () => this.#request("GET", "/webhooks"),
+    /** The response carries `secret`, once. Store it before you discard it. */
+    create: (input) => this.#request("POST", "/webhooks", { body: input }),
+    delete: (id) => this.#request("DELETE", `/webhooks/${id}`)
+  };
+  // --- events -------------------------------------------------------------
+  events = {
+    list: (options = {}) => this.#requestPage("GET", "/events", options),
+    get: (id) => this.#request("GET", `/events/${id}`)
+  };
+  domains = {
+    /** Read-only. Adding and verifying a domain is a DNS-and-a-human task. */
+    list: () => this.#request("GET", "/domains")
+  };
+  async #requestPage(method, path, query) {
+    const url = new URL(`${this.#baseUrl}${path}`);
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== void 0) url.searchParams.set(key, String(value));
+    }
+    const response = await this.#fetch(url, {
+      method,
+      headers: { Authorization: `Bearer ${this.#apiKey}` }
+    });
+    const payload = await response.json().catch(() => null);
+    if (!response.ok || payload?.error) {
+      throw new PidgeonError({
+        code: payload?.error?.code ?? "internal",
+        message: payload?.error?.message ?? `Request failed with ${response.status}.`,
+        status: response.status,
+        field: payload?.error?.field,
+        requestId: response.headers.get("x-request-id") ?? void 0
+      });
+    }
+    return {
+      data: payload?.data ?? [],
+      has_more: payload?.has_more ?? false,
+      next_cursor: payload?.next_cursor ?? null
+    };
+  }
+};
+
+// src/webhooks.ts
+var SIGNATURE_HEADER = "x-pidgeon-signature";
+var TIMESTAMP_HEADER = "x-pidgeon-timestamp";
+async function verifyWebhook(input) {
+  const get = (name) => input.headers instanceof Headers ? input.headers.get(name) ?? void 0 : input.headers[name] ?? input.headers[name.toLowerCase()];
+  const timestamp = get(TIMESTAMP_HEADER);
+  const signature = get(SIGNATURE_HEADER);
+  if (!timestamp || !signature) throw new Error("This request is not signed.");
+  const seconds = Number(timestamp);
+  if (!Number.isFinite(seconds)) throw new Error("The signature timestamp is not a number.");
+  const now = Math.floor((input.now ?? /* @__PURE__ */ new Date()).getTime() / 1e3);
+  const tolerance = input.toleranceSeconds ?? 300;
+  if (Math.abs(now - seconds) > tolerance) {
+    throw new Error("This request is too old to trust. It may be a replay.");
+  }
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(input.secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const mac = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    new TextEncoder().encode(`${seconds}.${input.rawBody}`)
+  );
+  const expected = `v1=${[...new Uint8Array(mac)].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+  if (!constantTimeEqual(expected, signature)) {
+    throw new Error("The signature does not match.");
+  }
+  return JSON.parse(input.rawBody);
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let difference = 0;
+  for (let index = 0; index < a.length; index += 1) {
+    difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
+  }
+  return difference === 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Pidgeon,
+  PidgeonError,
+  SIGNATURE_HEADER,
+  TIMESTAMP_HEADER,
+  verifyWebhook
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/client.ts","../src/webhooks.ts"],"sourcesContent":["/**\n * `@pidgeon-ai/sdk` — a thin typed client for the Pidgeon email API.\n *\n * Three things and no more: typed `fetch` wrappers, one error class, and a\n * webhook verifier.\n *\n *   import { Pidgeon, verifyWebhook } from '@pidgeon-ai/sdk';\n *\n * The module split follows what can be wrong on its own. `wire.ts` is the\n * shape of every response and is the single definition the application\n * checks its own DTOs against. `client.ts` is transport. `webhooks.ts` is\n * the only part with a security contract.\n */\n\nexport { Pidgeon, PidgeonError, type PidgeonOptions } from './client';\n\nexport {\n  verifyWebhook,\n  SIGNATURE_HEADER,\n  TIMESTAMP_HEADER,\n  type WebhookEnvelope,\n} from './webhooks';\n\nexport type {\n  Address,\n  Attachment,\n  Domain,\n  Event,\n  Identity,\n  Message,\n  Page,\n  RoutingRule,\n  Thread,\n  Webhook,\n} from './wire';\n","import type { Domain, Event, Identity, Message, Page, Thread, Webhook } from './wire';\n\n/**\n * The Pidgeon client.\n *\n * Deliberately thin: typed wrappers over `fetch`, one error class, and\n * nothing else. No retry policy, no queue, no caching, no ambient state —\n * those are decisions that belong to the application, and an SDK that makes\n * them for you is an SDK you eventually have to work around.\n *\n * Zero dependencies. The only runtime requirements are `fetch` and\n * `crypto.subtle`, both standard in Node 18+, Bun, Deno and every edge\n * runtime.\n */\n\nexport interface PidgeonOptions {\n  apiKey: string;\n  /** Defaults to the hosted API. Point this at a local dev server to test. */\n  baseUrl?: string;\n  /** Injected in tests. Defaults to the global. */\n  fetch?: typeof globalThis.fetch;\n}\n\nexport class PidgeonError extends Error {\n  readonly code: string;\n  readonly status: number;\n  readonly field?: string;\n  readonly requestId?: string;\n\n  constructor(input: {\n    code: string;\n    message: string;\n    status: number;\n    field?: string;\n    requestId?: string;\n  }) {\n    super(input.message);\n    this.name = 'PidgeonError';\n    this.code = input.code;\n    this.status = input.status;\n    this.field = input.field;\n    this.requestId = input.requestId;\n  }\n}\n\nconst DEFAULT_BASE_URL = 'https://pidgeon.ai/api/v1';\n\nexport class Pidgeon {\n  #apiKey: string;\n  #baseUrl: string;\n  #fetch: typeof globalThis.fetch;\n\n  constructor(options: PidgeonOptions) {\n    if (!options.apiKey) throw new Error('An API key is required.');\n\n    this.#apiKey = options.apiKey;\n    this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/$/, '');\n    this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);\n  }\n\n  async #request<T>(\n    method: string,\n    path: string,\n    options: { query?: Record<string, string | number | undefined>; body?: unknown } = {},\n  ): Promise<T> {\n    const url = new URL(`${this.#baseUrl}${path}`);\n\n    for (const [key, value] of Object.entries(options.query ?? {})) {\n      if (value !== undefined) url.searchParams.set(key, String(value));\n    }\n\n    const response = await this.#fetch(url, {\n      method,\n      headers: {\n        Authorization: `Bearer ${this.#apiKey}`,\n        ...(options.body ? { 'Content-Type': 'application/json' } : {}),\n      },\n      body: options.body ? JSON.stringify(options.body) : undefined,\n    });\n\n    const requestId = response.headers.get('x-request-id') ?? undefined;\n    const payload = (await response.json().catch(() => null)) as {\n      data?: unknown;\n      error?: { code: string; message: string; field?: string };\n    } | null;\n\n    if (!response.ok || payload?.error) {\n      throw new PidgeonError({\n        code: payload?.error?.code ?? 'internal',\n        message: payload?.error?.message ?? `Request failed with ${response.status}.`,\n        status: response.status,\n        field: payload?.error?.field,\n        requestId,\n      });\n    }\n\n    return payload?.data as T;\n  }\n\n  // --- identities ---------------------------------------------------------\n\n  identities = {\n    list: () => this.#request<Identity[]>('GET', '/identities'),\n    get: (id: string) => this.#request<Identity>('GET', `/identities/${id}`),\n    create: (input: {\n      domain_id: string;\n      local_part: string;\n      display_name?: string | null;\n      type?: 'human' | 'team' | 'application' | 'workflow' | 'agent';\n      mode?: 'human' | 'automated' | 'hybrid';\n    }) => this.#request<Identity>('POST', '/identities', { body: input }),\n    update: (\n      id: string,\n      input: {\n        display_name?: string | null;\n        mode?: 'human' | 'automated' | 'hybrid';\n        capabilities?: Record<string, boolean>;\n        status?: 'active' | 'suspended' | 'archived';\n      },\n    ) => this.#request<Identity>('PATCH', `/identities/${id}`, { body: input }),\n    delete: (id: string) => this.#request<{ id: string }>('DELETE', `/identities/${id}`),\n  };\n\n  // --- messages -----------------------------------------------------------\n\n  messages = {\n    get: (id: string) => this.#request<Message>('GET', `/messages/${id}`),\n    listInThread: (threadId: string, options: { limit?: number } = {}) =>\n      this.#requestPage<Message>('GET', '/messages', {\n        thread_id: threadId,\n        limit: options.limit,\n      }),\n    send: (input: {\n      from: string;\n      to: string | string[];\n      cc?: string | string[];\n      bcc?: string | string[];\n      subject?: string;\n      text?: string;\n      in_reply_to?: string | null;\n    }) =>\n      this.#request<{ id: string; thread_id: string; rejected: { address: string }[] }>(\n        'POST',\n        '/messages',\n        { body: input },\n      ),\n  };\n\n  attachments = {\n    /** A short-lived signed URL. Fetch it when you need it, don't store it. */\n    downloadUrl: (id: string) =>\n      this.#request<{ id: string; url: string }>('GET', `/attachments/${id}`),\n  };\n\n  // --- threads ------------------------------------------------------------\n\n  threads = {\n    list: (\n      options: { identity_id?: string; status?: string; limit?: number; cursor?: string } = {},\n    ) => this.#requestPage<Thread>('GET', '/threads', options),\n    get: (id: string) => this.#request<Thread>('GET', `/threads/${id}`),\n    update: (\n      id: string,\n      input: {\n        status?: 'open' | 'waiting' | 'resolved' | 'human_review';\n        owner_type?: 'human' | 'automation' | 'agent';\n      },\n    ) => this.#request<Thread>('PATCH', `/threads/${id}`, { body: input }),\n    /** Hand the conversation to a person. The takeover primitive, named. */\n    handOff: (id: string) =>\n      this.#request<Thread>('PATCH', `/threads/${id}`, {\n        body: { owner_type: 'human', status: 'human_review' },\n      }),\n  };\n\n  // --- webhooks -----------------------------------------------------------\n\n  webhooks = {\n    list: () => this.#request<Webhook[]>('GET', '/webhooks'),\n    /** The response carries `secret`, once. Store it before you discard it. */\n    create: (input: { url: string; identity_id?: string | null; event_types?: string[] }) =>\n      this.#request<Webhook & { secret: string }>('POST', '/webhooks', { body: input }),\n    delete: (id: string) => this.#request<{ id: string }>('DELETE', `/webhooks/${id}`),\n  };\n\n  // --- events -------------------------------------------------------------\n\n  events = {\n    list: (\n      options: { type?: string; identity_id?: string; limit?: number; cursor?: string } = {},\n    ) => this.#requestPage<Event>('GET', '/events', options),\n    get: (id: string) => this.#request<Event>('GET', `/events/${id}`),\n  };\n\n  domains = {\n    /** Read-only. Adding and verifying a domain is a DNS-and-a-human task. */\n    list: () => this.#request<Domain[]>('GET', '/domains'),\n  };\n\n  async #requestPage<T>(\n    method: string,\n    path: string,\n    query: Record<string, string | number | undefined>,\n  ): Promise<Page<T>> {\n    const url = new URL(`${this.#baseUrl}${path}`);\n    for (const [key, value] of Object.entries(query)) {\n      if (value !== undefined) url.searchParams.set(key, String(value));\n    }\n\n    const response = await this.#fetch(url, {\n      method,\n      headers: { Authorization: `Bearer ${this.#apiKey}` },\n    });\n\n    const payload = (await response.json().catch(() => null)) as\n      (Page<T> & { error?: { code: string; message: string; field?: string } }) | null;\n\n    if (!response.ok || payload?.error) {\n      throw new PidgeonError({\n        code: payload?.error?.code ?? 'internal',\n        message: payload?.error?.message ?? `Request failed with ${response.status}.`,\n        status: response.status,\n        field: payload?.error?.field,\n        requestId: response.headers.get('x-request-id') ?? undefined,\n      });\n    }\n\n    return {\n      data: payload?.data ?? [],\n      has_more: payload?.has_more ?? false,\n      next_cursor: payload?.next_cursor ?? null,\n    };\n  }\n}\n","/**\n * Verifying a delivery.\n *\n * The only part of this package with a security contract: it is what a\n * customer runs to decide whether a request claiming a message arrived\n * actually came from us. Everything else here is a typed `fetch`.\n *\n * Two properties carry that contract, and both are tested against payloads\n * signed by the server's own implementation — see\n * `tests/unit/sdk-webhook-verifier.test.ts`. Testing this file against\n * itself would prove only that it agrees with itself, which is exactly the\n * bug two implementations of one scheme produce.\n */\n\nexport const SIGNATURE_HEADER = 'x-pidgeon-signature';\nexport const TIMESTAMP_HEADER = 'x-pidgeon-timestamp';\n\nexport interface WebhookEnvelope {\n  id: string;\n  type: string;\n  created_at: string;\n  data: Record<string, unknown>;\n}\n\n/**\n * Verifies a delivery and returns its payload.\n *\n * Throws rather than returning false, because the one thing this must not\n * allow is a caller who forgets to check the boolean. Uses `crypto.subtle`,\n * so it works unchanged in Node, Bun, Deno, Workers and Vercel functions.\n *\n * `rawBody` must be the exact bytes we sent. Re-serialising parsed JSON\n * changes key order and whitespace, and the signature will not match — read\n * the body as text before you parse it.\n */\nexport async function verifyWebhook(input: {\n  rawBody: string;\n  headers: Headers | Record<string, string | undefined>;\n  secret: string;\n  toleranceSeconds?: number;\n  now?: Date;\n}): Promise<WebhookEnvelope> {\n  const get = (name: string): string | undefined =>\n    input.headers instanceof Headers\n      ? (input.headers.get(name) ?? undefined)\n      : (input.headers[name] ?? input.headers[name.toLowerCase()]);\n\n  const timestamp = get(TIMESTAMP_HEADER);\n  const signature = get(SIGNATURE_HEADER);\n\n  if (!timestamp || !signature) throw new Error('This request is not signed.');\n\n  const seconds = Number(timestamp);\n  if (!Number.isFinite(seconds)) throw new Error('The signature timestamp is not a number.');\n\n  const now = Math.floor((input.now ?? new Date()).getTime() / 1000);\n  const tolerance = input.toleranceSeconds ?? 300;\n\n  if (Math.abs(now - seconds) > tolerance) {\n    throw new Error('This request is too old to trust. It may be a replay.');\n  }\n\n  const key = await crypto.subtle.importKey(\n    'raw',\n    new TextEncoder().encode(input.secret),\n    { name: 'HMAC', hash: 'SHA-256' },\n    false,\n    ['sign'],\n  );\n\n  const mac = await crypto.subtle.sign(\n    'HMAC',\n    key,\n    new TextEncoder().encode(`${seconds}.${input.rawBody}`),\n  );\n\n  const expected = `v1=${[...new Uint8Array(mac)].map((byte) => byte.toString(16).padStart(2, '0')).join('')}`;\n\n  if (!constantTimeEqual(expected, signature)) {\n    throw new Error('The signature does not match.');\n  }\n\n  return JSON.parse(input.rawBody) as WebhookEnvelope;\n}\n\n/** Length-independent compare. Not `===`, which returns on the first byte. */\nfunction constantTimeEqual(a: string, b: string): boolean {\n  if (a.length !== b.length) return false;\n\n  let difference = 0;\n  for (let index = 0; index < a.length; index += 1) {\n    difference |= a.charCodeAt(index) ^ b.charCodeAt(index);\n  }\n\n  return difference === 0;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,302 @@
+/**
+ * The wire format.
+ *
+ * **This is the single definition of what the API returns**, and it lives
+ * here rather than in the application on purpose: the wire format *is* the
+ * public contract, and this package is the artifact that contract is
+ * published as.
+ *
+ * `src/lib/api/dto.ts` imports these types — with `import type`, so nothing
+ * of this package reaches the application at runtime — and every mapper
+ * there is checked against them. A field renamed in the application is a
+ * compile error in the application, immediately, rather than a silent lie
+ * in a customer's editor a release later. That was the alternative worth
+ * avoiding: two hand-maintained copies of the same shapes, which is what
+ * this replaced.
+ *
+ * Conventions, and they are not negotiable per-field: `snake_case`,
+ * ISO-8601 timestamps, ids as opaque strings. Nothing here ever carries a
+ * secret, a hash, a spam score or an internal provider id.
+ */
+interface Address {
+    email: string;
+    name?: string | null;
+}
+interface Attachment {
+    id: string;
+    filename: string;
+    content_type: string;
+    size: number;
+    /** False when there is no object store behind the metadata. */
+    downloadable: boolean;
+}
+interface Identity {
+    id: string;
+    email: string;
+    local_part: string;
+    domain: string;
+    display_name: string | null;
+    /** `human`, `team`, `application`, `workflow` or `agent`. */
+    type: string;
+    /** Who answers: `human`, `automated` or `hybrid`. */
+    mode: string;
+    status: string;
+    capabilities: Record<string, boolean>;
+    /** False for an address that turns mail into events and stores nothing. */
+    has_inbox: boolean;
+    routed_address_count: number;
+    created_at: string;
+}
+interface Message {
+    id: string;
+    thread_id: string;
+    identity: string | null;
+    direction: string;
+    from: Address;
+    to: Address[];
+    cc: Address[];
+    subject: string | null;
+    /** The envelope recipient, which is not always in `to`. */
+    delivered_to: string | null;
+    text: string | null;
+    /** Sanitised server-side. Our policy travels with the content. */
+    html: string;
+    is_read: boolean;
+    is_spam: boolean;
+    attachments: Attachment[];
+    created_at: string;
+}
+interface Thread {
+    id: string;
+    identity: string;
+    subject: string | null;
+    status: 'open' | 'waiting' | 'resolved' | 'human_review';
+    owner_type: 'human' | 'automation' | 'agent';
+    message_count: number;
+    last_message_at: string | null;
+    created_at: string;
+}
+interface Webhook {
+    id: string;
+    url: string;
+    identity: string | null;
+    event_types: string[];
+    status: string;
+    consecutive_failures: number;
+    last_delivered_at: string | null;
+    last_failed_at: string | null;
+    created_at: string;
+}
+interface Event {
+    id: string;
+    type: string;
+    identity: string | null;
+    message_id: string | null;
+    thread_id: string | null;
+    /** Ids and metadata. An event never carries a message body. */
+    data: Record<string, unknown>;
+    created_at: string;
+}
+interface RoutingRule {
+    id: string;
+    /** The address or pattern this rule matches. */
+    match: string;
+    /** `exact` for an address, `catch_all` for the domain's fallback. */
+    match_type: string;
+    /** `identity` for an inbox, `webhook` for a URL. */
+    destination_type: string;
+    destination: string;
+    status: string;
+    domain: string;
+    created_at: string;
+}
+interface Domain {
+    id: string;
+    domain: string;
+    status: string;
+    catch_all_enabled: boolean;
+    identity_count: number;
+    verified_at: string | null;
+    created_at: string;
+}
+/**
+ * A page of results.
+ *
+ * Deliberately not an async iterator. Hiding pagination hides the rate
+ * limit that pagination is subject to, and the application calling us is
+ * better placed to decide what to do when it is hit.
+ */
+interface Page<T> {
+    data: T[];
+    has_more: boolean;
+    next_cursor: string | null;
+}
+
+/**
+ * The Pidgeon client.
+ *
+ * Deliberately thin: typed wrappers over `fetch`, one error class, and
+ * nothing else. No retry policy, no queue, no caching, no ambient state —
+ * those are decisions that belong to the application, and an SDK that makes
+ * them for you is an SDK you eventually have to work around.
+ *
+ * Zero dependencies. The only runtime requirements are `fetch` and
+ * `crypto.subtle`, both standard in Node 18+, Bun, Deno and every edge
+ * runtime.
+ */
+interface PidgeonOptions {
+    apiKey: string;
+    /** Defaults to the hosted API. Point this at a local dev server to test. */
+    baseUrl?: string;
+    /** Injected in tests. Defaults to the global. */
+    fetch?: typeof globalThis.fetch;
+}
+declare class PidgeonError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly field?: string;
+    readonly requestId?: string;
+    constructor(input: {
+        code: string;
+        message: string;
+        status: number;
+        field?: string;
+        requestId?: string;
+    });
+}
+declare class Pidgeon {
+    #private;
+    constructor(options: PidgeonOptions);
+    identities: {
+        list: () => Promise<Identity[]>;
+        get: (id: string) => Promise<Identity>;
+        create: (input: {
+            domain_id: string;
+            local_part: string;
+            display_name?: string | null;
+            type?: "human" | "team" | "application" | "workflow" | "agent";
+            mode?: "human" | "automated" | "hybrid";
+        }) => Promise<Identity>;
+        update: (id: string, input: {
+            display_name?: string | null;
+            mode?: "human" | "automated" | "hybrid";
+            capabilities?: Record<string, boolean>;
+            status?: "active" | "suspended" | "archived";
+        }) => Promise<Identity>;
+        delete: (id: string) => Promise<{
+            id: string;
+        }>;
+    };
+    messages: {
+        get: (id: string) => Promise<Message>;
+        listInThread: (threadId: string, options?: {
+            limit?: number;
+        }) => Promise<Page<Message>>;
+        send: (input: {
+            from: string;
+            to: string | string[];
+            cc?: string | string[];
+            bcc?: string | string[];
+            subject?: string;
+            text?: string;
+            in_reply_to?: string | null;
+        }) => Promise<{
+            id: string;
+            thread_id: string;
+            rejected: {
+                address: string;
+            }[];
+        }>;
+    };
+    attachments: {
+        /** A short-lived signed URL. Fetch it when you need it, don't store it. */
+        downloadUrl: (id: string) => Promise<{
+            id: string;
+            url: string;
+        }>;
+    };
+    threads: {
+        list: (options?: {
+            identity_id?: string;
+            status?: string;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Thread>>;
+        get: (id: string) => Promise<Thread>;
+        update: (id: string, input: {
+            status?: "open" | "waiting" | "resolved" | "human_review";
+            owner_type?: "human" | "automation" | "agent";
+        }) => Promise<Thread>;
+        /** Hand the conversation to a person. The takeover primitive, named. */
+        handOff: (id: string) => Promise<Thread>;
+    };
+    webhooks: {
+        list: () => Promise<Webhook[]>;
+        /** The response carries `secret`, once. Store it before you discard it. */
+        create: (input: {
+            url: string;
+            identity_id?: string | null;
+            event_types?: string[];
+        }) => Promise<Webhook & {
+            secret: string;
+        }>;
+        delete: (id: string) => Promise<{
+            id: string;
+        }>;
+    };
+    events: {
+        list: (options?: {
+            type?: string;
+            identity_id?: string;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Event>>;
+        get: (id: string) => Promise<Event>;
+    };
+    domains: {
+        /** Read-only. Adding and verifying a domain is a DNS-and-a-human task. */
+        list: () => Promise<Domain[]>;
+    };
+}
+
+/**
+ * Verifying a delivery.
+ *
+ * The only part of this package with a security contract: it is what a
+ * customer runs to decide whether a request claiming a message arrived
+ * actually came from us. Everything else here is a typed `fetch`.
+ *
+ * Two properties carry that contract, and both are tested against payloads
+ * signed by the server's own implementation — see
+ * `tests/unit/sdk-webhook-verifier.test.ts`. Testing this file against
+ * itself would prove only that it agrees with itself, which is exactly the
+ * bug two implementations of one scheme produce.
+ */
+declare const SIGNATURE_HEADER = "x-pidgeon-signature";
+declare const TIMESTAMP_HEADER = "x-pidgeon-timestamp";
+interface WebhookEnvelope {
+    id: string;
+    type: string;
+    created_at: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Verifies a delivery and returns its payload.
+ *
+ * Throws rather than returning false, because the one thing this must not
+ * allow is a caller who forgets to check the boolean. Uses `crypto.subtle`,
+ * so it works unchanged in Node, Bun, Deno, Workers and Vercel functions.
+ *
+ * `rawBody` must be the exact bytes we sent. Re-serialising parsed JSON
+ * changes key order and whitespace, and the signature will not match — read
+ * the body as text before you parse it.
+ */
+declare function verifyWebhook(input: {
+    rawBody: string;
+    headers: Headers | Record<string, string | undefined>;
+    secret: string;
+    toleranceSeconds?: number;
+    now?: Date;
+}): Promise<WebhookEnvelope>;
+
+export { type Address, type Attachment, type Domain, type Event, type Identity, type Message, type Page, Pidgeon, PidgeonError, type PidgeonOptions, type RoutingRule, SIGNATURE_HEADER, TIMESTAMP_HEADER, type Thread, type Webhook, type WebhookEnvelope, verifyWebhook };

package/dist/index.d.ts

@@ -0,0 +1,302 @@
+/**
+ * The wire format.
+ *
+ * **This is the single definition of what the API returns**, and it lives
+ * here rather than in the application on purpose: the wire format *is* the
+ * public contract, and this package is the artifact that contract is
+ * published as.
+ *
+ * `src/lib/api/dto.ts` imports these types — with `import type`, so nothing
+ * of this package reaches the application at runtime — and every mapper
+ * there is checked against them. A field renamed in the application is a
+ * compile error in the application, immediately, rather than a silent lie
+ * in a customer's editor a release later. That was the alternative worth
+ * avoiding: two hand-maintained copies of the same shapes, which is what
+ * this replaced.
+ *
+ * Conventions, and they are not negotiable per-field: `snake_case`,
+ * ISO-8601 timestamps, ids as opaque strings. Nothing here ever carries a
+ * secret, a hash, a spam score or an internal provider id.
+ */
+interface Address {
+    email: string;
+    name?: string | null;
+}
+interface Attachment {
+    id: string;
+    filename: string;
+    content_type: string;
+    size: number;
+    /** False when there is no object store behind the metadata. */
+    downloadable: boolean;
+}
+interface Identity {
+    id: string;
+    email: string;
+    local_part: string;
+    domain: string;
+    display_name: string | null;
+    /** `human`, `team`, `application`, `workflow` or `agent`. */
+    type: string;
+    /** Who answers: `human`, `automated` or `hybrid`. */
+    mode: string;
+    status: string;
+    capabilities: Record<string, boolean>;
+    /** False for an address that turns mail into events and stores nothing. */
+    has_inbox: boolean;
+    routed_address_count: number;
+    created_at: string;
+}
+interface Message {
+    id: string;
+    thread_id: string;
+    identity: string | null;
+    direction: string;
+    from: Address;
+    to: Address[];
+    cc: Address[];
+    subject: string | null;
+    /** The envelope recipient, which is not always in `to`. */
+    delivered_to: string | null;
+    text: string | null;
+    /** Sanitised server-side. Our policy travels with the content. */
+    html: string;
+    is_read: boolean;
+    is_spam: boolean;
+    attachments: Attachment[];
+    created_at: string;
+}
+interface Thread {
+    id: string;
+    identity: string;
+    subject: string | null;
+    status: 'open' | 'waiting' | 'resolved' | 'human_review';
+    owner_type: 'human' | 'automation' | 'agent';
+    message_count: number;
+    last_message_at: string | null;
+    created_at: string;
+}
+interface Webhook {
+    id: string;
+    url: string;
+    identity: string | null;
+    event_types: string[];
+    status: string;
+    consecutive_failures: number;
+    last_delivered_at: string | null;
+    last_failed_at: string | null;
+    created_at: string;
+}
+interface Event {
+    id: string;
+    type: string;
+    identity: string | null;
+    message_id: string | null;
+    thread_id: string | null;
+    /** Ids and metadata. An event never carries a message body. */
+    data: Record<string, unknown>;
+    created_at: string;
+}
+interface RoutingRule {
+    id: string;
+    /** The address or pattern this rule matches. */
+    match: string;
+    /** `exact` for an address, `catch_all` for the domain's fallback. */
+    match_type: string;
+    /** `identity` for an inbox, `webhook` for a URL. */
+    destination_type: string;
+    destination: string;
+    status: string;
+    domain: string;
+    created_at: string;
+}
+interface Domain {
+    id: string;
+    domain: string;
+    status: string;
+    catch_all_enabled: boolean;
+    identity_count: number;
+    verified_at: string | null;
+    created_at: string;
+}
+/**
+ * A page of results.
+ *
+ * Deliberately not an async iterator. Hiding pagination hides the rate
+ * limit that pagination is subject to, and the application calling us is
+ * better placed to decide what to do when it is hit.
+ */
+interface Page<T> {
+    data: T[];
+    has_more: boolean;
+    next_cursor: string | null;
+}
+
+/**
+ * The Pidgeon client.
+ *
+ * Deliberately thin: typed wrappers over `fetch`, one error class, and
+ * nothing else. No retry policy, no queue, no caching, no ambient state —
+ * those are decisions that belong to the application, and an SDK that makes
+ * them for you is an SDK you eventually have to work around.
+ *
+ * Zero dependencies. The only runtime requirements are `fetch` and
+ * `crypto.subtle`, both standard in Node 18+, Bun, Deno and every edge
+ * runtime.
+ */
+interface PidgeonOptions {
+    apiKey: string;
+    /** Defaults to the hosted API. Point this at a local dev server to test. */
+    baseUrl?: string;
+    /** Injected in tests. Defaults to the global. */
+    fetch?: typeof globalThis.fetch;
+}
+declare class PidgeonError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly field?: string;
+    readonly requestId?: string;
+    constructor(input: {
+        code: string;
+        message: string;
+        status: number;
+        field?: string;
+        requestId?: string;
+    });
+}
+declare class Pidgeon {
+    #private;
+    constructor(options: PidgeonOptions);
+    identities: {
+        list: () => Promise<Identity[]>;
+        get: (id: string) => Promise<Identity>;
+        create: (input: {
+            domain_id: string;
+            local_part: string;
+            display_name?: string | null;
+            type?: "human" | "team" | "application" | "workflow" | "agent";
+            mode?: "human" | "automated" | "hybrid";
+        }) => Promise<Identity>;
+        update: (id: string, input: {
+            display_name?: string | null;
+            mode?: "human" | "automated" | "hybrid";
+            capabilities?: Record<string, boolean>;
+            status?: "active" | "suspended" | "archived";
+        }) => Promise<Identity>;
+        delete: (id: string) => Promise<{
+            id: string;
+        }>;
+    };
+    messages: {
+        get: (id: string) => Promise<Message>;
+        listInThread: (threadId: string, options?: {
+            limit?: number;
+        }) => Promise<Page<Message>>;
+        send: (input: {
+            from: string;
+            to: string | string[];
+            cc?: string | string[];
+            bcc?: string | string[];
+            subject?: string;
+            text?: string;
+            in_reply_to?: string | null;
+        }) => Promise<{
+            id: string;
+            thread_id: string;
+            rejected: {
+                address: string;
+            }[];
+        }>;
+    };
+    attachments: {
+        /** A short-lived signed URL. Fetch it when you need it, don't store it. */
+        downloadUrl: (id: string) => Promise<{
+            id: string;
+            url: string;
+        }>;
+    };
+    threads: {
+        list: (options?: {
+            identity_id?: string;
+            status?: string;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Thread>>;
+        get: (id: string) => Promise<Thread>;
+        update: (id: string, input: {
+            status?: "open" | "waiting" | "resolved" | "human_review";
+            owner_type?: "human" | "automation" | "agent";
+        }) => Promise<Thread>;
+        /** Hand the conversation to a person. The takeover primitive, named. */
+        handOff: (id: string) => Promise<Thread>;
+    };
+    webhooks: {
+        list: () => Promise<Webhook[]>;
+        /** The response carries `secret`, once. Store it before you discard it. */
+        create: (input: {
+            url: string;
+            identity_id?: string | null;
+            event_types?: string[];
+        }) => Promise<Webhook & {
+            secret: string;
+        }>;
+        delete: (id: string) => Promise<{
+            id: string;
+        }>;
+    };
+    events: {
+        list: (options?: {
+            type?: string;
+            identity_id?: string;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Event>>;
+        get: (id: string) => Promise<Event>;
+    };
+    domains: {
+        /** Read-only. Adding and verifying a domain is a DNS-and-a-human task. */
+        list: () => Promise<Domain[]>;
+    };
+}
+
+/**
+ * Verifying a delivery.
+ *
+ * The only part of this package with a security contract: it is what a
+ * customer runs to decide whether a request claiming a message arrived
+ * actually came from us. Everything else here is a typed `fetch`.
+ *
+ * Two properties carry that contract, and both are tested against payloads
+ * signed by the server's own implementation — see
+ * `tests/unit/sdk-webhook-verifier.test.ts`. Testing this file against
+ * itself would prove only that it agrees with itself, which is exactly the
+ * bug two implementations of one scheme produce.
+ */
+declare const SIGNATURE_HEADER = "x-pidgeon-signature";
+declare const TIMESTAMP_HEADER = "x-pidgeon-timestamp";
+interface WebhookEnvelope {
+    id: string;
+    type: string;
+    created_at: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Verifies a delivery and returns its payload.
+ *
+ * Throws rather than returning false, because the one thing this must not
+ * allow is a caller who forgets to check the boolean. Uses `crypto.subtle`,
+ * so it works unchanged in Node, Bun, Deno, Workers and Vercel functions.
+ *
+ * `rawBody` must be the exact bytes we sent. Re-serialising parsed JSON
+ * changes key order and whitespace, and the signature will not match — read
+ * the body as text before you parse it.
+ */
+declare function verifyWebhook(input: {
+    rawBody: string;
+    headers: Headers | Record<string, string | undefined>;
+    secret: string;
+    toleranceSeconds?: number;
+    now?: Date;
+}): Promise<WebhookEnvelope>;
+
+export { type Address, type Attachment, type Domain, type Event, type Identity, type Message, type Page, Pidgeon, PidgeonError, type PidgeonOptions, type RoutingRule, SIGNATURE_HEADER, TIMESTAMP_HEADER, type Thread, type Webhook, type WebhookEnvelope, verifyWebhook };

package/dist/index.js

@@ -0,0 +1,179 @@
+// src/client.ts
+var PidgeonError = class extends Error {
+  code;
+  status;
+  field;
+  requestId;
+  constructor(input) {
+    super(input.message);
+    this.name = "PidgeonError";
+    this.code = input.code;
+    this.status = input.status;
+    this.field = input.field;
+    this.requestId = input.requestId;
+  }
+};
+var DEFAULT_BASE_URL = "https://pidgeon.ai/api/v1";
+var Pidgeon = class {
+  #apiKey;
+  #baseUrl;
+  #fetch;
+  constructor(options) {
+    if (!options.apiKey) throw new Error("An API key is required.");
+    this.#apiKey = options.apiKey;
+    this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+  async #request(method, path, options = {}) {
+    const url = new URL(`${this.#baseUrl}${path}`);
+    for (const [key, value] of Object.entries(options.query ?? {})) {
+      if (value !== void 0) url.searchParams.set(key, String(value));
+    }
+    const response = await this.#fetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.#apiKey}`,
+        ...options.body ? { "Content-Type": "application/json" } : {}
+      },
+      body: options.body ? JSON.stringify(options.body) : void 0
+    });
+    const requestId = response.headers.get("x-request-id") ?? void 0;
+    const payload = await response.json().catch(() => null);
+    if (!response.ok || payload?.error) {
+      throw new PidgeonError({
+        code: payload?.error?.code ?? "internal",
+        message: payload?.error?.message ?? `Request failed with ${response.status}.`,
+        status: response.status,
+        field: payload?.error?.field,
+        requestId
+      });
+    }
+    return payload?.data;
+  }
+  // --- identities ---------------------------------------------------------
+  identities = {
+    list: () => this.#request("GET", "/identities"),
+    get: (id) => this.#request("GET", `/identities/${id}`),
+    create: (input) => this.#request("POST", "/identities", { body: input }),
+    update: (id, input) => this.#request("PATCH", `/identities/${id}`, { body: input }),
+    delete: (id) => this.#request("DELETE", `/identities/${id}`)
+  };
+  // --- messages -----------------------------------------------------------
+  messages = {
+    get: (id) => this.#request("GET", `/messages/${id}`),
+    listInThread: (threadId, options = {}) => this.#requestPage("GET", "/messages", {
+      thread_id: threadId,
+      limit: options.limit
+    }),
+    send: (input) => this.#request(
+      "POST",
+      "/messages",
+      { body: input }
+    )
+  };
+  attachments = {
+    /** A short-lived signed URL. Fetch it when you need it, don't store it. */
+    downloadUrl: (id) => this.#request("GET", `/attachments/${id}`)
+  };
+  // --- threads ------------------------------------------------------------
+  threads = {
+    list: (options = {}) => this.#requestPage("GET", "/threads", options),
+    get: (id) => this.#request("GET", `/threads/${id}`),
+    update: (id, input) => this.#request("PATCH", `/threads/${id}`, { body: input }),
+    /** Hand the conversation to a person. The takeover primitive, named. */
+    handOff: (id) => this.#request("PATCH", `/threads/${id}`, {
+      body: { owner_type: "human", status: "human_review" }
+    })
+  };
+  // --- webhooks -----------------------------------------------------------
+  webhooks = {
+    list: () => this.#request("GET", "/webhooks"),
+    /** The response carries `secret`, once. Store it before you discard it. */
+    create: (input) => this.#request("POST", "/webhooks", { body: input }),
+    delete: (id) => this.#request("DELETE", `/webhooks/${id}`)
+  };
+  // --- events -------------------------------------------------------------
+  events = {
+    list: (options = {}) => this.#requestPage("GET", "/events", options),
+    get: (id) => this.#request("GET", `/events/${id}`)
+  };
+  domains = {
+    /** Read-only. Adding and verifying a domain is a DNS-and-a-human task. */
+    list: () => this.#request("GET", "/domains")
+  };
+  async #requestPage(method, path, query) {
+    const url = new URL(`${this.#baseUrl}${path}`);
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== void 0) url.searchParams.set(key, String(value));
+    }
+    const response = await this.#fetch(url, {
+      method,
+      headers: { Authorization: `Bearer ${this.#apiKey}` }
+    });
+    const payload = await response.json().catch(() => null);
+    if (!response.ok || payload?.error) {
+      throw new PidgeonError({
+        code: payload?.error?.code ?? "internal",
+        message: payload?.error?.message ?? `Request failed with ${response.status}.`,
+        status: response.status,
+        field: payload?.error?.field,
+        requestId: response.headers.get("x-request-id") ?? void 0
+      });
+    }
+    return {
+      data: payload?.data ?? [],
+      has_more: payload?.has_more ?? false,
+      next_cursor: payload?.next_cursor ?? null
+    };
+  }
+};
+
+// src/webhooks.ts
+var SIGNATURE_HEADER = "x-pidgeon-signature";
+var TIMESTAMP_HEADER = "x-pidgeon-timestamp";
+async function verifyWebhook(input) {
+  const get = (name) => input.headers instanceof Headers ? input.headers.get(name) ?? void 0 : input.headers[name] ?? input.headers[name.toLowerCase()];
+  const timestamp = get(TIMESTAMP_HEADER);
+  const signature = get(SIGNATURE_HEADER);
+  if (!timestamp || !signature) throw new Error("This request is not signed.");
+  const seconds = Number(timestamp);
+  if (!Number.isFinite(seconds)) throw new Error("The signature timestamp is not a number.");
+  const now = Math.floor((input.now ?? /* @__PURE__ */ new Date()).getTime() / 1e3);
+  const tolerance = input.toleranceSeconds ?? 300;
+  if (Math.abs(now - seconds) > tolerance) {
+    throw new Error("This request is too old to trust. It may be a replay.");
+  }
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(input.secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const mac = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    new TextEncoder().encode(`${seconds}.${input.rawBody}`)
+  );
+  const expected = `v1=${[...new Uint8Array(mac)].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+  if (!constantTimeEqual(expected, signature)) {
+    throw new Error("The signature does not match.");
+  }
+  return JSON.parse(input.rawBody);
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let difference = 0;
+  for (let index = 0; index < a.length; index += 1) {
+    difference |= a.charCodeAt(index) ^ b.charCodeAt(index);
+  }
+  return difference === 0;
+}
+export {
+  Pidgeon,
+  PidgeonError,
+  SIGNATURE_HEADER,
+  TIMESTAMP_HEADER,
+  verifyWebhook
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts","../src/webhooks.ts"],"sourcesContent":["import type { Domain, Event, Identity, Message, Page, Thread, Webhook } from './wire';\n\n/**\n * The Pidgeon client.\n *\n * Deliberately thin: typed wrappers over `fetch`, one error class, and\n * nothing else. No retry policy, no queue, no caching, no ambient state —\n * those are decisions that belong to the application, and an SDK that makes\n * them for you is an SDK you eventually have to work around.\n *\n * Zero dependencies. The only runtime requirements are `fetch` and\n * `crypto.subtle`, both standard in Node 18+, Bun, Deno and every edge\n * runtime.\n */\n\nexport interface PidgeonOptions {\n  apiKey: string;\n  /** Defaults to the hosted API. Point this at a local dev server to test. */\n  baseUrl?: string;\n  /** Injected in tests. Defaults to the global. */\n  fetch?: typeof globalThis.fetch;\n}\n\nexport class PidgeonError extends Error {\n  readonly code: string;\n  readonly status: number;\n  readonly field?: string;\n  readonly requestId?: string;\n\n  constructor(input: {\n    code: string;\n    message: string;\n    status: number;\n    field?: string;\n    requestId?: string;\n  }) {\n    super(input.message);\n    this.name = 'PidgeonError';\n    this.code = input.code;\n    this.status = input.status;\n    this.field = input.field;\n    this.requestId = input.requestId;\n  }\n}\n\nconst DEFAULT_BASE_URL = 'https://pidgeon.ai/api/v1';\n\nexport class Pidgeon {\n  #apiKey: string;\n  #baseUrl: string;\n  #fetch: typeof globalThis.fetch;\n\n  constructor(options: PidgeonOptions) {\n    if (!options.apiKey) throw new Error('An API key is required.');\n\n    this.#apiKey = options.apiKey;\n    this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/$/, '');\n    this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);\n  }\n\n  async #request<T>(\n    method: string,\n    path: string,\n    options: { query?: Record<string, string | number | undefined>; body?: unknown } = {},\n  ): Promise<T> {\n    const url = new URL(`${this.#baseUrl}${path}`);\n\n    for (const [key, value] of Object.entries(options.query ?? {})) {\n      if (value !== undefined) url.searchParams.set(key, String(value));\n    }\n\n    const response = await this.#fetch(url, {\n      method,\n      headers: {\n        Authorization: `Bearer ${this.#apiKey}`,\n        ...(options.body ? { 'Content-Type': 'application/json' } : {}),\n      },\n      body: options.body ? JSON.stringify(options.body) : undefined,\n    });\n\n    const requestId = response.headers.get('x-request-id') ?? undefined;\n    const payload = (await response.json().catch(() => null)) as {\n      data?: unknown;\n      error?: { code: string; message: string; field?: string };\n    } | null;\n\n    if (!response.ok || payload?.error) {\n      throw new PidgeonError({\n        code: payload?.error?.code ?? 'internal',\n        message: payload?.error?.message ?? `Request failed with ${response.status}.`,\n        status: response.status,\n        field: payload?.error?.field,\n        requestId,\n      });\n    }\n\n    return payload?.data as T;\n  }\n\n  // --- identities ---------------------------------------------------------\n\n  identities = {\n    list: () => this.#request<Identity[]>('GET', '/identities'),\n    get: (id: string) => this.#request<Identity>('GET', `/identities/${id}`),\n    create: (input: {\n      domain_id: string;\n      local_part: string;\n      display_name?: string | null;\n      type?: 'human' | 'team' | 'application' | 'workflow' | 'agent';\n      mode?: 'human' | 'automated' | 'hybrid';\n    }) => this.#request<Identity>('POST', '/identities', { body: input }),\n    update: (\n      id: string,\n      input: {\n        display_name?: string | null;\n        mode?: 'human' | 'automated' | 'hybrid';\n        capabilities?: Record<string, boolean>;\n        status?: 'active' | 'suspended' | 'archived';\n      },\n    ) => this.#request<Identity>('PATCH', `/identities/${id}`, { body: input }),\n    delete: (id: string) => this.#request<{ id: string }>('DELETE', `/identities/${id}`),\n  };\n\n  // --- messages -----------------------------------------------------------\n\n  messages = {\n    get: (id: string) => this.#request<Message>('GET', `/messages/${id}`),\n    listInThread: (threadId: string, options: { limit?: number } = {}) =>\n      this.#requestPage<Message>('GET', '/messages', {\n        thread_id: threadId,\n        limit: options.limit,\n      }),\n    send: (input: {\n      from: string;\n      to: string | string[];\n      cc?: string | string[];\n      bcc?: string | string[];\n      subject?: string;\n      text?: string;\n      in_reply_to?: string | null;\n    }) =>\n      this.#request<{ id: string; thread_id: string; rejected: { address: string }[] }>(\n        'POST',\n        '/messages',\n        { body: input },\n      ),\n  };\n\n  attachments = {\n    /** A short-lived signed URL. Fetch it when you need it, don't store it. */\n    downloadUrl: (id: string) =>\n      this.#request<{ id: string; url: string }>('GET', `/attachments/${id}`),\n  };\n\n  // --- threads ------------------------------------------------------------\n\n  threads = {\n    list: (\n      options: { identity_id?: string; status?: string; limit?: number; cursor?: string } = {},\n    ) => this.#requestPage<Thread>('GET', '/threads', options),\n    get: (id: string) => this.#request<Thread>('GET', `/threads/${id}`),\n    update: (\n      id: string,\n      input: {\n        status?: 'open' | 'waiting' | 'resolved' | 'human_review';\n        owner_type?: 'human' | 'automation' | 'agent';\n      },\n    ) => this.#request<Thread>('PATCH', `/threads/${id}`, { body: input }),\n    /** Hand the conversation to a person. The takeover primitive, named. */\n    handOff: (id: string) =>\n      this.#request<Thread>('PATCH', `/threads/${id}`, {\n        body: { owner_type: 'human', status: 'human_review' },\n      }),\n  };\n\n  // --- webhooks -----------------------------------------------------------\n\n  webhooks = {\n    list: () => this.#request<Webhook[]>('GET', '/webhooks'),\n    /** The response carries `secret`, once. Store it before you discard it. */\n    create: (input: { url: string; identity_id?: string | null; event_types?: string[] }) =>\n      this.#request<Webhook & { secret: string }>('POST', '/webhooks', { body: input }),\n    delete: (id: string) => this.#request<{ id: string }>('DELETE', `/webhooks/${id}`),\n  };\n\n  // --- events -------------------------------------------------------------\n\n  events = {\n    list: (\n      options: { type?: string; identity_id?: string; limit?: number; cursor?: string } = {},\n    ) => this.#requestPage<Event>('GET', '/events', options),\n    get: (id: string) => this.#request<Event>('GET', `/events/${id}`),\n  };\n\n  domains = {\n    /** Read-only. Adding and verifying a domain is a DNS-and-a-human task. */\n    list: () => this.#request<Domain[]>('GET', '/domains'),\n  };\n\n  async #requestPage<T>(\n    method: string,\n    path: string,\n    query: Record<string, string | number | undefined>,\n  ): Promise<Page<T>> {\n    const url = new URL(`${this.#baseUrl}${path}`);\n    for (const [key, value] of Object.entries(query)) {\n      if (value !== undefined) url.searchParams.set(key, String(value));\n    }\n\n    const response = await this.#fetch(url, {\n      method,\n      headers: { Authorization: `Bearer ${this.#apiKey}` },\n    });\n\n    const payload = (await response.json().catch(() => null)) as\n      (Page<T> & { error?: { code: string; message: string; field?: string } }) | null;\n\n    if (!response.ok || payload?.error) {\n      throw new PidgeonError({\n        code: payload?.error?.code ?? 'internal',\n        message: payload?.error?.message ?? `Request failed with ${response.status}.`,\n        status: response.status,\n        field: payload?.error?.field,\n        requestId: response.headers.get('x-request-id') ?? undefined,\n      });\n    }\n\n    return {\n      data: payload?.data ?? [],\n      has_more: payload?.has_more ?? false,\n      next_cursor: payload?.next_cursor ?? null,\n    };\n  }\n}\n","/**\n * Verifying a delivery.\n *\n * The only part of this package with a security contract: it is what a\n * customer runs to decide whether a request claiming a message arrived\n * actually came from us. Everything else here is a typed `fetch`.\n *\n * Two properties carry that contract, and both are tested against payloads\n * signed by the server's own implementation — see\n * `tests/unit/sdk-webhook-verifier.test.ts`. Testing this file against\n * itself would prove only that it agrees with itself, which is exactly the\n * bug two implementations of one scheme produce.\n */\n\nexport const SIGNATURE_HEADER = 'x-pidgeon-signature';\nexport const TIMESTAMP_HEADER = 'x-pidgeon-timestamp';\n\nexport interface WebhookEnvelope {\n  id: string;\n  type: string;\n  created_at: string;\n  data: Record<string, unknown>;\n}\n\n/**\n * Verifies a delivery and returns its payload.\n *\n * Throws rather than returning false, because the one thing this must not\n * allow is a caller who forgets to check the boolean. Uses `crypto.subtle`,\n * so it works unchanged in Node, Bun, Deno, Workers and Vercel functions.\n *\n * `rawBody` must be the exact bytes we sent. Re-serialising parsed JSON\n * changes key order and whitespace, and the signature will not match — read\n * the body as text before you parse it.\n */\nexport async function verifyWebhook(input: {\n  rawBody: string;\n  headers: Headers | Record<string, string | undefined>;\n  secret: string;\n  toleranceSeconds?: number;\n  now?: Date;\n}): Promise<WebhookEnvelope> {\n  const get = (name: string): string | undefined =>\n    input.headers instanceof Headers\n      ? (input.headers.get(name) ?? undefined)\n      : (input.headers[name] ?? input.headers[name.toLowerCase()]);\n\n  const timestamp = get(TIMESTAMP_HEADER);\n  const signature = get(SIGNATURE_HEADER);\n\n  if (!timestamp || !signature) throw new Error('This request is not signed.');\n\n  const seconds = Number(timestamp);\n  if (!Number.isFinite(seconds)) throw new Error('The signature timestamp is not a number.');\n\n  const now = Math.floor((input.now ?? new Date()).getTime() / 1000);\n  const tolerance = input.toleranceSeconds ?? 300;\n\n  if (Math.abs(now - seconds) > tolerance) {\n    throw new Error('This request is too old to trust. It may be a replay.');\n  }\n\n  const key = await crypto.subtle.importKey(\n    'raw',\n    new TextEncoder().encode(input.secret),\n    { name: 'HMAC', hash: 'SHA-256' },\n    false,\n    ['sign'],\n  );\n\n  const mac = await crypto.subtle.sign(\n    'HMAC',\n    key,\n    new TextEncoder().encode(`${seconds}.${input.rawBody}`),\n  );\n\n  const expected = `v1=${[...new Uint8Array(mac)].map((byte) => byte.toString(16).padStart(2, '0')).join('')}`;\n\n  if (!constantTimeEqual(expected, signature)) {\n    throw new Error('The signature does not match.');\n  }\n\n  return JSON.parse(input.rawBody) as WebhookEnvelope;\n}\n\n/** Length-independent compare. Not `===`, which returns on the first byte. */\nfunction constantTimeEqual(a: string, b: string): boolean {\n  if (a.length !== b.length) return false;\n\n  let difference = 0;\n  for (let index = 0; index < a.length; index += 1) {\n    difference |= a.charCodeAt(index) ^ b.charCodeAt(index);\n  }\n\n  return difference === 0;\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@pidgeon-ai/sdk",
+  "version": "0.1.0",
+  "description": "Thin TypeScript client for the Pidgeon email API.",
+  "keywords": [
+    "pidgeon",
+    "email",
+    "webhooks",
+    "api-client"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/patrickcneuhaus/pidgeon.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://pidgeon.ai",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm build"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5"
+  }
+}