@the-smithy/bellow 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# @the-smithy/bellow
+
+## 0.1.0
+
+First release.
+
+- `Bellow` client, with `createBellow()` and `createBellowFromEnv()` (`BELLOW_API_KEY`, `EMAIL_FROM`,
+  `EMAIL_REPLY_TO`, `BELLOW_URL`).
+- `send()` returns a result and never throws for send problems. It validates locally (addresses, header
+  injection, size, tags, required `category`), uses an automatic or caller-supplied idempotency key (unsafe
+  keys are hashed), and retries network errors, timeouts, 429 and 5xx with backoff. `sendOrThrow()` is the
+  throwing variant.
+- `getMessage()` returns a message's status and delivery events.
+- Typed `BellowError` with `code`, `status`, `details`, `retryAfter` and `retryable`.
+- Security: refuses to run in a browser, requires HTTPS, never follows redirects, keeps the key out of
+  logs and serialized output.
+- `@the-smithy/bellow/testing`: `createMockBellow()` for app tests.

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) The Smithy. All rights reserved.
+
+You may use this package to build software that sends email through The Smithy's Bellow service, with an API key
+issued for it. It's provided as is, without warranty of any kind.
+
+Questions: hello@thesmithy.io

package/README.md

@@ -1,3 +1,175 @@
-# Temporary Holding Version
+# @the-smithy/bellow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The standard way for The Smithy's apps to send transactional email through
+[Bellow](https://bellow.thesmithy.io). Every Smithy site uses this package rather than calling an email
+provider directly, so every email is validated, labelled, safe to retry, and sent from a verified domain.
+
+- **Server-side only.** It refuses to run in a browser: the API key can send email as your domains.
+- **Validated before it leaves your server.** Bad addresses, header injection, missing bodies, oversize
+  emails and malformed tags fail locally with a clear message.
+- **Safe to retry.** Every send carries an idempotency key (yours, or one the SDK makes), and network
+  errors, timeouts, 429s and 5xx responses are retried with backoff.
+- **Never throws for a send problem.** `send` returns `{ ok: false, error }`, so a mail hiccup can't break
+  a checkout or a sign-up.
+
+Agents: read [llms.md](./llms.md) for the condensed reference.
+
+## Install
+
+Public on npm: no registry config or token needed.
+
+```sh
+pnpm add @the-smithy/bellow
+```
+
+It only sends with a Bellow API key, which Smithy staff issue per client and environment.
+
+Requires Node 20.3+ (or any runtime with `fetch`, `AbortSignal.any` and Web Crypto).
+
+## Configure
+
+Smithy staff create the client, verify its domain and issue an API key in the Bellow dashboard. Set these
+server-side environment variables (in `.env.local` and on the host):
+
+| Variable | Required | Example |
+| --- | --- | --- |
+| `BELLOW_API_KEY` | yes (secret) | `bk_…` |
+| `EMAIL_FROM` | yes | `Acme <hello@acme.com>`: a domain verified for this client in Bellow |
+| `EMAIL_REPLY_TO` | no | `support@acme.com` |
+| `BELLOW_URL` | no | Only to point at a non-production Bellow |
+
+Never put the key in a `NEXT_PUBLIC_*` variable, client code, the repo or logs. Use one key per app and
+environment, so any one can be revoked alone.
+
+## Use
+
+Create one client for the app, in a server-only module:
+
+```ts
+// lib/email.ts
+import "server-only"; // Next.js
+import { createBellowFromEnv } from "@the-smithy/bellow";
+
+/** null when BELLOW_API_KEY or EMAIL_FROM isn't set: treat email as off and fall back. */
+export const bellow = createBellowFromEnv();
+```
+
+Send:
+
+```ts
+import { bellow } from "@/lib/email";
+
+const result = await bellow?.send(
+  {
+    to: user.email,
+    subject: "Reset your password",
+    html,
+    text,
+    category: "password-reset",
+  },
+  { idempotencyKey: `password-reset-${user.id}-${Math.floor(Date.now() / 600_000)}` },
+);
+
+if (!result) {
+  // Email isn't configured here: show the link on screen instead.
+} else if (!result.ok) {
+  console.error("[email]", result.error.code, result.error.message);
+}
+```
+
+### The email
+
+| Field | Notes |
+| --- | --- |
+| `to` | Address or array. `ada@x.com` or `Ada Lovelace <ada@x.com>`. |
+| `cc`, `bcc` | Optional. 50 recipients at most across to, cc and bcc, with no address twice. |
+| `from` | Optional; defaults to `EMAIL_FROM`. Must be on a domain verified for your client. |
+| `replyTo` | Optional, up to 5; defaults to `EMAIL_REPLY_TO`. |
+| `subject` | Required, one line. |
+| `html`, `text` | At least one; send both. 512 KB in total with the subject. |
+| `category` | **Required.** What kind of email this is: `password-reset`, `receipt`, `form-alert`. Letters, numbers, `_`, `-`. |
+| `tags` | Optional extra labels, up to 9. Same character rules; names can't start with `bellow`. |
+
+### Options
+
+- `idempotencyKey`: same key and same email → sent at most once, however often you call. Build it from
+  stable ids (`order-1042-receipt`), not from the time of the retry. Any string works: keys with characters
+  Bellow doesn't accept (an email address, say) are hashed into a stable safe key. Reusing a key for a
+  *different* email is a `conflict` error.
+- `retries`: override the client's retry count for one call.
+- `signal`: an `AbortSignal` to cancel.
+
+### The result
+
+```ts
+type SendResult =
+  | { ok: true; id: string; status: string; suppressed: string[]; duplicate: boolean }
+  | { ok: false; error: BellowError };
+```
+
+- `suppressed`: recipients Bellow skipped because they bounced or complained before. The rest were sent.
+- `duplicate`: this idempotency key was already used for this email, so nothing new was sent.
+- `sendOrThrow()` is the same, but throws the `BellowError`.
+
+### Errors
+
+`BellowError` has `code`, `message` (safe to log; never contains the key), `status`, `details`,
+`retryAfter` and `retryable`. `isBellowError(value)` narrows.
+
+| `code` | Meaning | Retried by the SDK |
+| --- | --- | --- |
+| `invalid_email` | Failed validation locally; `details` lists each problem. No request was made. | no |
+| `bad_request` | The API rejected the body; `details` names the field. | no |
+| `unauthorized` | Missing, wrong or revoked key. | no |
+| `forbidden` | The from domain isn't verified for your client, or the client is paused. | no |
+| `conflict` | Idempotency key reused for a different email. | no |
+| `unprocessable` | Every To address is suppressed; nothing was sent. | no |
+| `rate_limited` | Over your client's per-minute or daily limit, or SES is busy. | yes, if `Retry-After` ≤ `maxRetryAfter` |
+| `unavailable`, `server_error` | SES or Bellow had a problem. | yes |
+| `network_error`, `timeout` | Couldn't reach Bellow in time. | yes |
+| `aborted` | Your `signal` fired. | no |
+
+### Delivery status
+
+```ts
+const status = await bellow.getMessage(result.id);
+if (status.ok) console.log(status.message.status, status.message.events);
+```
+
+`status` moves from `sent` to `delivered`, or to `bounced`, `complained`, `rejected` or `failed`. A key can
+only read its own client's messages.
+
+### Client options
+
+`new Bellow({ apiKey, from?, replyTo?, baseUrl?, timeout? = 15000, retries? = 2, maxRetryAfter? = 30, fetch? })`.
+`createBellowFromEnv(env?, overrides?)` reads the variables above and accepts the same options as overrides.
+`validateEmail(email)` returns the list of problems without sending, which is handy in forms and tests.
+
+## Testing your app
+
+Depend on the `BellowSender` interface, and use the mock from `@the-smithy/bellow/testing` in tests:
+
+```ts
+import { createMockBellow } from "@the-smithy/bellow/testing";
+
+const mock = createMockBellow({ from: "Acme <hello@acme.com>" });
+await sendWelcome(mock.client, user);
+expect(mock.sent).toHaveLength(1);
+expect(mock.sent[0].email.category).toBe("welcome");
+```
+
+The mock validates exactly like the real client, dedupes idempotency keys, and can fail on demand
+(`fail: (email) => "rate_limited"`) or report addresses as suppressed (`suppressed: ["gone@x.com"]`).
+
+## Security rules for apps
+
+- Server-side only; one key per app and environment; the key only in secret environment variables.
+- **Never let a visitor choose both the recipient and the content.** Public forms must send to a fixed
+  address (the site owner), or a fixed template to the visitor's own address, and must be rate-limited or
+  CAPTCHA-protected. If a form is abused, Bellow pauses the whole client.
+- Don't put email bodies or the key in logs. Log `error.code` and `error.message`.
+
+## While Bellow is in the SES sandbox
+
+Until Amazon approves production access, SES only delivers to addresses verified in SES. Sends to anyone
+else fail with `unavailable` (MessageRejected). Ask Smithy staff which address to test with.

package/dist/chunk-IO7QZUKG.js

@@ -0,0 +1,101 @@
+// src/errors.ts
+var RETRYABLE = /* @__PURE__ */ new Set(["rate_limited", "unavailable", "server_error", "network_error", "timeout"]);
+var BellowError = class extends Error {
+  name = "BellowError";
+  code;
+  /** HTTP status, when the API answered. */
+  status;
+  /** Field-level problems for `invalid_email` and `bad_request`; suppressed addresses for `unprocessable`. */
+  details;
+  /** Seconds the API asked us to wait (429). */
+  retryAfter;
+  constructor(code, message, extra = {}) {
+    super(message, extra.cause === void 0 ? void 0 : { cause: extra.cause });
+    this.code = code;
+    this.status = extra.status;
+    this.details = extra.details;
+    this.retryAfter = extra.retryAfter;
+  }
+  /** True when sending again later (with the same idempotency key) may succeed. */
+  get retryable() {
+    return RETRYABLE.has(this.code);
+  }
+  toJSON() {
+    return { name: this.name, code: this.code, message: this.message, status: this.status, details: this.details, retryAfter: this.retryAfter };
+  }
+};
+var isBellowError = (value) => value instanceof BellowError;
+
+// src/validate.ts
+var LIMITS = {
+  maxRecipients: 50,
+  maxReplyTo: 5,
+  maxTags: 10,
+  /** subject + html + text, in UTF-8 bytes. */
+  maxContentBytes: 512 * 1024,
+  maxSubjectLength: 998
+};
+var LOCAL = /^[A-Za-z0-9.!#$%&'*+/=?^_`{|}~-]{1,64}$/;
+var DOMAIN = /^(?=.{1,253}$)([A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)+[A-Za-z]{2,63}$/;
+var TAG = /^[A-Za-z0-9_-]{1,128}$/;
+function parseAddress(input) {
+  if (typeof input !== "string" || /[\r\n\0]/.test(input)) return null;
+  const trimmed = input.trim();
+  const named = trimmed.match(/^(?:"([^"\\]*)"|([^"<>@,;]*?))\s*<([^<>\s]+)>$/);
+  if (named && (named[1] ?? named[2] ?? "").trim().length > 120) return null;
+  const value = named ? named[3] : trimmed;
+  const at = value.lastIndexOf("@");
+  if (at < 1 || value.length > 254) return null;
+  const local = value.slice(0, at);
+  const domain = value.slice(at + 1);
+  if (!LOCAL.test(local) || local.startsWith(".") || local.endsWith(".") || local.includes("..")) return null;
+  if (!DOMAIN.test(domain)) return null;
+  return `${local}@${domain}`.toLowerCase();
+}
+var isValidTag = (value) => typeof value === "string" && TAG.test(value);
+var list = (v) => v === void 0 ? [] : Array.isArray(v) ? v : [v];
+function validateEmail(email) {
+  const issues = [];
+  const add = (field, message) => issues.push({ field, message });
+  if (!email.from) add("from", "Set `from`, or a default `from` on the client (EMAIL_FROM).");
+  else if (!parseAddress(email.from)) add("from", "`from` must look like `hello@yourdomain.com` or `Name <hello@yourdomain.com>`.");
+  const seen = /* @__PURE__ */ new Set();
+  let recipients = 0;
+  for (const field of ["to", "cc", "bcc"]) {
+    for (const value of list(email[field])) {
+      recipients++;
+      const parsed = parseAddress(value);
+      if (!parsed) add(field, `Not a usable address: ${JSON.stringify(String(value).slice(0, 120))}. Use one address per entry.`);
+      else if (seen.has(parsed)) add(field, `${parsed} appears more than once across to, cc and bcc.`);
+      else seen.add(parsed);
+    }
+  }
+  if (list(email.to).length === 0) add("to", "Add at least one `to` address.");
+  if (recipients > LIMITS.maxRecipients) add("to", `Up to ${LIMITS.maxRecipients} recipients in total (to, cc and bcc).`);
+  const replyTo = list(email.replyTo);
+  if (replyTo.length > LIMITS.maxReplyTo) add("replyTo", `Up to ${LIMITS.maxReplyTo} replyTo addresses.`);
+  for (const value of replyTo) if (!parseAddress(value)) add("replyTo", `Not a usable address: ${JSON.stringify(String(value).slice(0, 120))}.`);
+  if (typeof email.subject !== "string" || !email.subject.trim()) add("subject", "Add a subject.");
+  else if (/[\r\n]/.test(email.subject)) add("subject", "The subject can't contain line breaks.");
+  else if (email.subject.length > LIMITS.maxSubjectLength) add("subject", `The subject is over ${LIMITS.maxSubjectLength} characters.`);
+  if (!email.html && !email.text) add("html", "Send `html`, `text`, or both (both is best for deliverability).");
+  const bytes = new TextEncoder().encode(`${email.subject ?? ""}${email.html ?? ""}${email.text ?? ""}`).length;
+  if (bytes > LIMITS.maxContentBytes) add("html", `The email is too large (limit ${LIMITS.maxContentBytes / 1024} KB for subject, html and text together).`);
+  if (!isValidTag(email.category)) add("category", "`category` is required: letters, numbers, _ and - only, e.g. `password-reset`.");
+  const tags = Object.entries(email.tags ?? {});
+  if (tags.length + 1 > LIMITS.maxTags) add("tags", `Up to ${LIMITS.maxTags - 1} tags besides category.`);
+  for (const [name, value] of tags) {
+    if (!isValidTag(name) || !isValidTag(value)) add("tags", `Tag ${JSON.stringify(name)}: names and values use letters, numbers, _ and - only (up to 128).`);
+    if (name === "category") add("tags", "Use the `category` field rather than a `category` tag.");
+    if (name.startsWith("bellow")) add("tags", `Tag names starting with "bellow" are reserved (${name}).`);
+  }
+  return issues;
+}
+
+export {
+  BellowError,
+  isBellowError,
+  LIMITS,
+  parseAddress,
+  validateEmail
+};

package/dist/client-BgpTyZ0a.d.ts

@@ -0,0 +1,167 @@
+/** Codes from the Bellow API, plus the ones the SDK raises itself before or around a request. */
+type BellowErrorCode = "bad_request" | "unauthorized" | "forbidden" | "not_found" | "conflict" | "unprocessable" | "rate_limited" | "unavailable" | "server_error" | "invalid_email" | "invalid_request" | "network_error" | "timeout" | "aborted";
+/**
+ * Every failure the SDK reports. Its message is safe to log: it never contains the API key.
+ * Show `message` to staff and developers, not to site visitors.
+ */
+declare class BellowError extends Error {
+    readonly name = "BellowError";
+    readonly code: BellowErrorCode;
+    /** HTTP status, when the API answered. */
+    readonly status?: number;
+    /** Field-level problems for `invalid_email` and `bad_request`; suppressed addresses for `unprocessable`. */
+    readonly details?: unknown;
+    /** Seconds the API asked us to wait (429). */
+    readonly retryAfter?: number;
+    constructor(code: BellowErrorCode, message: string, extra?: {
+        status?: number;
+        details?: unknown;
+        retryAfter?: number;
+        cause?: unknown;
+    });
+    /** True when sending again later (with the same idempotency key) may succeed. */
+    get retryable(): boolean;
+    toJSON(): {
+        name: string;
+        code: BellowErrorCode;
+        message: string;
+        status: number | undefined;
+        details: unknown;
+        retryAfter: number | undefined;
+    };
+}
+declare const isBellowError: (value: unknown) => value is BellowError;
+
+declare const DEFAULT_BASE_URL = "https://bellow.thesmithy.io";
+/** Stamped from package.json at build time ("dev" when running from source). */
+declare const SDK_VERSION: string;
+/** One transactional email. */
+type Email = {
+    /** `hello@yourdomain.com` or `Name <hello@yourdomain.com>`, on a domain verified for your client in Bellow. Defaults to the client's `from`. */
+    from?: string;
+    to: string | string[];
+    cc?: string | string[];
+    bcc?: string | string[];
+    /** Defaults to the client's `replyTo`. Up to 5. */
+    replyTo?: string | string[];
+    /** One line. */
+    subject: string;
+    /** Send both html and text when you can. */
+    html?: string;
+    text?: string;
+    /**
+     * Required: what kind of email this is, e.g. `password-reset`, `receipt`, `form-alert`.
+     * Letters, numbers, _ and -. It's how messages are grouped and found in the Bellow dashboard.
+     */
+    category: string;
+    /** Extra labels, up to 9: letters, numbers, _ and - for names and values. */
+    tags?: Record<string, string>;
+};
+type SendOptions = {
+    /**
+     * Same key + same email → Bellow sends at most once, however often you call. Build it from stable
+     * ids (`order-1042-receipt`). Any string works; unsafe characters are hashed. Without one, the SDK
+     * makes a key per call, so its own retries are still safe.
+     */
+    idempotencyKey?: string;
+    /** Override the client's retry count for this call. */
+    retries?: number;
+    signal?: AbortSignal;
+};
+type SendResult = {
+    ok: true;
+    id: string;
+    status: string;
+    suppressed: string[];
+    duplicate: boolean;
+} | {
+    ok: false;
+    error: BellowError;
+};
+type MessageEvent = {
+    type: string;
+    recipient: string | null;
+    subtype: string | null;
+    at: string;
+};
+type Message = {
+    id: string;
+    status: "queued" | "sent" | "delivered" | "delivery_delayed" | "bounced" | "complained" | "rejected" | "failed";
+    from: string;
+    to: string[];
+    cc: string[];
+    bcc: string[];
+    subject: string;
+    tags: Record<string, string>;
+    createdAt: string;
+    events: MessageEvent[];
+};
+type MessageResult = {
+    ok: true;
+    message: Message;
+} | {
+    ok: false;
+    error: BellowError;
+};
+type BellowOptions = {
+    /** `bk_…`, from the Bellow dashboard. Server-side only. */
+    apiKey: string;
+    /** Default sender for every email (usually EMAIL_FROM). */
+    from?: string;
+    /** Default reply-to for every email (usually EMAIL_REPLY_TO). */
+    replyTo?: string;
+    /** Defaults to https://bellow.thesmithy.io. Must be HTTPS (http://localhost is allowed for development). */
+    baseUrl?: string;
+    /** Per attempt, in milliseconds. Default 15000. */
+    timeout?: number;
+    /** Retries for network errors, timeouts, 429 and 5xx. Default 2. */
+    retries?: number;
+    /** Longest Retry-After (seconds) the SDK will wait for before giving up. Default 30. */
+    maxRetryAfter?: number;
+    fetch?: typeof fetch;
+    /**
+     * The SDK refuses to run in a browser, because the key can send email as your domains.
+     * Only set this for a trusted, non-public environment (e.g. an Electron main process).
+     */
+    dangerouslyAllowBrowser?: boolean;
+};
+/** What both the real client and the testing mock implement. Depend on this in your own code. */
+interface BellowSender {
+    send(email: Email, options?: SendOptions): Promise<SendResult>;
+    getMessage(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<MessageResult>;
+}
+declare class Bellow implements BellowSender {
+    #private;
+    constructor(options: BellowOptions);
+    /** Where this client sends. Useful in logs; never includes the key. */
+    get baseUrl(): string;
+    /**
+     * Sends one email. Never throws for an API or network problem: check `result.ok`. Invalid input is
+     * reported as `invalid_email` without calling the API.
+     */
+    send(email: Email, options?: SendOptions): Promise<SendResult>;
+    /** Like `send`, but throws a BellowError instead of returning `{ ok: false }`. */
+    sendOrThrow(email: Email, options?: SendOptions): Promise<{
+        ok: true;
+        id: string;
+        status: string;
+        suppressed: string[];
+        duplicate: boolean;
+    }>;
+    /** A message sent with this client's key, with its delivery events. Messages of other clients are `not_found`. */
+    getMessage(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<MessageResult>;
+}
+declare function createBellow(options: BellowOptions): Bellow;
+type Env = Record<string, string | undefined>;
+/**
+ * The standard setup: BELLOW_API_KEY, EMAIL_FROM, and optionally EMAIL_REPLY_TO and BELLOW_URL.
+ * Returns null when BELLOW_API_KEY or EMAIL_FROM is missing, so the app can treat email as off
+ * (skip and fall back) instead of crashing in environments without email.
+ */
+declare function createBellowFromEnv(env?: Env, overrides?: Partial<BellowOptions>): Bellow | null;
+
+export { Bellow as B, DEFAULT_BASE_URL as D, type Email as E, type Message as M, SDK_VERSION as S, BellowError as a, type BellowErrorCode as b, type BellowOptions as c, type BellowSender as d, type MessageEvent as e, type MessageResult as f, type SendOptions as g, type SendResult as h, createBellow as i, createBellowFromEnv as j, isBellowError as k };

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+export { B as Bellow, a as BellowError, b as BellowErrorCode, c as BellowOptions, d as BellowSender, D as DEFAULT_BASE_URL, E as Email, M as Message, e as MessageEvent, f as MessageResult, S as SDK_VERSION, g as SendOptions, h as SendResult, i as createBellow, j as createBellowFromEnv, k as isBellowError } from './client-BgpTyZ0a.js';
+
+/**
+ * A key Bellow will accept, from any string. Safe keys pass through unchanged so they're easy to
+ * find in the dashboard; anything else (an email address, spaces, a long key) is hashed, so the
+ * same input always maps to the same key.
+ */
+declare function toIdempotencyKey(key: string): Promise<string>;
+
+/**
+ * Client-side checks that mirror Bellow's server rules (src/lib/send in the Bellow app), so a bad
+ * email fails fast with a clear message instead of a round trip and a 400. The server re-checks
+ * everything; these exist for developer experience and to stop header injection at the source.
+ */
+declare const LIMITS: {
+    readonly maxRecipients: 50;
+    readonly maxReplyTo: 5;
+    readonly maxTags: 10;
+    /** subject + html + text, in UTF-8 bytes. */
+    readonly maxContentBytes: number;
+    readonly maxSubjectLength: 998;
+};
+/** The bare, lowercased address in `email` or `Name <email>`, or null if it isn't one. */
+declare function parseAddress(input: string): string | null;
+type Issue = {
+    field: string;
+    message: string;
+};
+/**
+ * Every problem with an email, or an empty list. `email.from` must already be resolved (the
+ * client fills it from its default).
+ */
+declare function validateEmail(email: {
+    from?: string;
+    to: string | string[];
+    cc?: string | string[];
+    bcc?: string | string[];
+    replyTo?: string | string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    category: string;
+    tags?: Record<string, string>;
+}): Issue[];
+
+export { type Issue, LIMITS, parseAddress, toIdempotencyKey, validateEmail };

package/dist/index.js

@@ -0,0 +1,201 @@
+import {
+  BellowError,
+  LIMITS,
+  isBellowError,
+  parseAddress,
+  validateEmail
+} from "./chunk-IO7QZUKG.js";
+
+// src/idempotency.ts
+var SAFE = /^[A-Za-z0-9_.:-]{1,200}$/;
+async function sha256Hex(value) {
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+  return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function toIdempotencyKey(key) {
+  return SAFE.test(key) ? key : `h-${await sha256Hex(key)}`;
+}
+var randomIdempotencyKey = () => `auto-${globalThis.crypto.randomUUID()}`;
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://bellow.thesmithy.io";
+var SDK_VERSION = true ? "0.1.0" : "dev";
+var KEY = /^bk_[A-Za-z0-9_-]{43}$/;
+var sleep = (ms, signal) => new Promise((resolve, reject) => {
+  if (signal?.aborted) return reject(signal.reason);
+  const timer = setTimeout(resolve, ms);
+  signal?.addEventListener("abort", () => (clearTimeout(timer), reject(signal.reason)), { once: true });
+});
+var list = (v) => v === void 0 ? void 0 : Array.isArray(v) ? v : [v];
+function checkBaseUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`Bellow: baseUrl ${JSON.stringify(value)} isn't a URL.`);
+  }
+  const local = url.hostname === "localhost" || url.hostname === "127.0.0.1";
+  if (url.protocol !== "https:" && !(local && url.protocol === "http:")) {
+    throw new Error("Bellow: baseUrl must use HTTPS, so the API key is never sent in the clear.");
+  }
+  return url.origin;
+}
+var Bellow = class {
+  // Private fields don't show up in console.log, JSON.stringify or error reports.
+  #apiKey;
+  #fetch;
+  #from;
+  #replyTo;
+  #baseUrl;
+  #timeout;
+  #retries;
+  #maxRetryAfter;
+  constructor(options) {
+    const isBrowser = typeof window !== "undefined" && typeof document !== "undefined";
+    if (isBrowser && !options.dangerouslyAllowBrowser) {
+      throw new Error("Bellow: refusing to run in a browser. The API key can send email as your domains; call Bellow from server code only.");
+    }
+    if (typeof options.apiKey !== "string" || !KEY.test(options.apiKey.trim())) {
+      throw new Error("Bellow: apiKey must be a Bellow key (bk_ followed by 43 characters). Check BELLOW_API_KEY.");
+    }
+    this.#apiKey = options.apiKey.trim();
+    this.#baseUrl = checkBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
+    this.#from = options.from || void 0;
+    this.#replyTo = options.replyTo || void 0;
+    this.#timeout = options.timeout ?? 15e3;
+    this.#retries = Math.max(0, Math.min(options.retries ?? 2, 5));
+    this.#maxRetryAfter = options.maxRetryAfter ?? 30;
+    const f = options.fetch ?? globalThis.fetch;
+    if (typeof f !== "function") throw new Error("Bellow: no fetch available. Use Node 20+ or pass `fetch`.");
+    this.#fetch = f.bind(globalThis);
+  }
+  /** Where this client sends. Useful in logs; never includes the key. */
+  get baseUrl() {
+    return this.#baseUrl;
+  }
+  /**
+   * Sends one email. Never throws for an API or network problem: check `result.ok`. Invalid input is
+   * reported as `invalid_email` without calling the API.
+   */
+  async send(email, options = {}) {
+    const resolved = { ...email, from: email.from || this.#from, replyTo: email.replyTo ?? this.#replyTo };
+    const issues = validateEmail(resolved);
+    if (issues.length) {
+      return { ok: false, error: new BellowError("invalid_email", `This email can't be sent: ${issues.map((i) => i.message).join(" ")}`, { details: issues }) };
+    }
+    const body = JSON.stringify({
+      from: resolved.from,
+      to: resolved.to,
+      cc: list(resolved.cc),
+      bcc: list(resolved.bcc),
+      reply_to: list(resolved.replyTo),
+      subject: resolved.subject,
+      html: resolved.html || void 0,
+      text: resolved.text || void 0,
+      tags: { ...resolved.tags, category: resolved.category }
+    });
+    const idempotencyKey = options.idempotencyKey ? await toIdempotencyKey(options.idempotencyKey) : randomIdempotencyKey();
+    const response = await this.#request("POST", "/api/v1/send", { body, idempotencyKey, signal: options.signal, retries: options.retries });
+    if (!response.ok) return response;
+    const data = response.data;
+    if (typeof data?.id !== "string") return { ok: false, error: new BellowError("server_error", "Bellow answered without a message id.") };
+    return {
+      ok: true,
+      id: data.id,
+      status: typeof data.status === "string" ? data.status : "sent",
+      suppressed: Array.isArray(data.suppressed) ? data.suppressed : [],
+      duplicate: data.duplicate === true
+    };
+  }
+  /** Like `send`, but throws a BellowError instead of returning `{ ok: false }`. */
+  async sendOrThrow(email, options) {
+    const result = await this.send(email, options);
+    if (!result.ok) throw result.error;
+    return result;
+  }
+  /** A message sent with this client's key, with its delivery events. Messages of other clients are `not_found`. */
+  async getMessage(id, options = {}) {
+    if (!/^[0-9a-f-]{36}$/i.test(id)) return { ok: false, error: new BellowError("invalid_request", "That isn't a Bellow message id.") };
+    const response = await this.#request("GET", `/api/v1/messages/${id}`, { signal: options.signal });
+    if (!response.ok) return response;
+    return { ok: true, message: response.data };
+  }
+  async #request(method, path, { body, idempotencyKey, signal, retries = this.#retries }) {
+    let last;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      if (attempt > 0 && last) {
+        const wait = last.retryAfter !== void 0 ? last.retryAfter * 1e3 : Math.min(8e3, 500 * 2 ** (attempt - 1)) + Math.random() * 250;
+        try {
+          await sleep(wait, signal);
+        } catch {
+          return { ok: false, error: new BellowError("aborted", "The request was aborted.") };
+        }
+      }
+      const outcome = await this.#attempt(method, path, body, idempotencyKey, signal);
+      if (outcome.ok) return outcome;
+      last = outcome.error;
+      const tooLong = last.retryAfter !== void 0 && last.retryAfter > this.#maxRetryAfter;
+      if (!last.retryable || tooLong || last.code === "aborted") break;
+    }
+    return { ok: false, error: last };
+  }
+  async #attempt(method, path, body, idempotencyKey, signal) {
+    const timeout = AbortSignal.timeout(this.#timeout);
+    const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+    let res;
+    try {
+      res = await this.#fetch(`${this.#baseUrl}${path}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.#apiKey}`,
+          Accept: "application/json",
+          "User-Agent": `bellow-sdk/${SDK_VERSION}`,
+          ...body ? { "Content-Type": "application/json" } : {},
+          ...idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}
+        },
+        body,
+        // Never follow a redirect: it could carry the Authorization header somewhere else.
+        redirect: "error",
+        signal: combined
+      });
+    } catch (err) {
+      if (signal?.aborted) return { ok: false, error: new BellowError("aborted", "The request was aborted.", { cause: err }) };
+      if (timeout.aborted) return { ok: false, error: new BellowError("timeout", `Bellow didn't answer within ${this.#timeout} ms.`, { cause: err }) };
+      return { ok: false, error: new BellowError("network_error", `Couldn't reach Bellow: ${err?.message ?? "network error"}`, { cause: err }) };
+    }
+    const data = await res.json().catch(() => null);
+    if (res.ok) return { ok: true, data };
+    const retryAfter = Number(res.headers.get("retry-after"));
+    const code = data?.error?.code ?? (res.status === 404 ? "not_found" : res.status >= 500 ? "server_error" : "bad_request");
+    return {
+      ok: false,
+      error: new BellowError(code, data?.error?.message ?? `Bellow responded ${res.status}.`, {
+        status: res.status,
+        details: data?.error?.details,
+        retryAfter: Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter : void 0
+      })
+    };
+  }
+};
+function createBellow(options) {
+  return new Bellow(options);
+}
+function createBellowFromEnv(env = globalThis.process?.env ?? {}, overrides = {}) {
+  const apiKey = env.BELLOW_API_KEY?.trim();
+  const from = env.EMAIL_FROM?.trim();
+  if (!apiKey || !from) return null;
+  return new Bellow({ apiKey, from, replyTo: env.EMAIL_REPLY_TO?.trim() || void 0, baseUrl: env.BELLOW_URL?.trim() || void 0, ...overrides });
+}
+export {
+  Bellow,
+  BellowError,
+  DEFAULT_BASE_URL,
+  LIMITS,
+  SDK_VERSION,
+  createBellow,
+  createBellowFromEnv,
+  isBellowError,
+  parseAddress,
+  toIdempotencyKey,
+  validateEmail
+};

package/dist/testing.d.ts

@@ -0,0 +1,37 @@
+import { E as Email, b as BellowErrorCode, a as BellowError, g as SendOptions, d as BellowSender } from './client-BgpTyZ0a.js';
+
+/**
+ * @the-smithy/bellow/testing: a stand-in for the Bellow client in your app's tests.
+ *
+ *   const mock = createMockBellow({ from: "Acme <hello@acme.com>" });
+ *   await signUp(mock.client, user);              // your code takes a BellowSender
+ *   expect(mock.sent[0].email.category).toBe("welcome");
+ *
+ * It applies the same validation as the real client, so a malformed email fails in tests too.
+ */
+
+type SentEmail = {
+    id: string;
+    email: Email & {
+        from: string;
+    };
+    options: SendOptions;
+};
+type MockBellowOptions = {
+    /** Default sender, like the real client's `from`. */
+    from?: string;
+    replyTo?: string;
+    /** Return an error code (or BellowError) to make a send fail, e.g. `() => "rate_limited"`. */
+    fail?: (email: Email) => BellowErrorCode | BellowError | undefined;
+    /** Addresses to report as suppressed (skipped) when sent to. */
+    suppressed?: string[];
+};
+declare function createMockBellow(options?: MockBellowOptions): {
+    client: BellowSender;
+    /** Every email accepted so far, oldest first. */
+    sent: SentEmail[];
+    /** Forget everything sent. */
+    reset(): void;
+};
+
+export { type MockBellowOptions, type SentEmail, createMockBellow };

package/dist/testing.js

@@ -0,0 +1,62 @@
+import {
+  BellowError,
+  parseAddress,
+  validateEmail
+} from "./chunk-IO7QZUKG.js";
+
+// src/testing.ts
+function createMockBellow(options = {}) {
+  const sent = [];
+  const byKey = /* @__PURE__ */ new Map();
+  let counter = 0;
+  const client = {
+    async send(email, sendOptions = {}) {
+      const resolved = { ...email, from: email.from || options.from, replyTo: email.replyTo ?? options.replyTo };
+      const issues = validateEmail(resolved);
+      if (issues.length) {
+        return { ok: false, error: new BellowError("invalid_email", `This email can't be sent: ${issues.map((i) => i.message).join(" ")}`, { details: issues }) };
+      }
+      const failure = options.fail?.(email);
+      if (failure) return { ok: false, error: typeof failure === "string" ? new BellowError(failure, `Mock failure: ${failure}`) : failure };
+      const key = sendOptions.idempotencyKey;
+      if (key && byKey.has(key)) return { ok: true, id: byKey.get(key), status: "sent", suppressed: [], duplicate: true };
+      const id = `00000000-0000-4000-8000-${String(++counter).padStart(12, "0")}`;
+      if (key) byKey.set(key, id);
+      sent.push({ id, email: { ...resolved, from: resolved.from }, options: sendOptions });
+      const recipients = new Set([resolved.to, resolved.cc ?? [], resolved.bcc ?? []].flat().map((a) => parseAddress(a)));
+      const suppressed = (options.suppressed ?? []).map((a) => parseAddress(a) ?? a.toLowerCase()).filter((a) => recipients.has(a));
+      return { ok: true, id, status: "sent", suppressed, duplicate: false };
+    },
+    async getMessage(id) {
+      const found = sent.find((s) => s.id === id);
+      if (!found) return { ok: false, error: new BellowError("not_found", "No such message.", { status: 404 }) };
+      const asList = (v) => v === void 0 ? [] : Array.isArray(v) ? v : [v];
+      const message = {
+        id,
+        status: "sent",
+        from: found.email.from,
+        to: asList(found.email.to),
+        cc: asList(found.email.cc),
+        bcc: asList(found.email.bcc),
+        subject: found.email.subject,
+        tags: { ...found.email.tags, category: found.email.category },
+        createdAt: (/* @__PURE__ */ new Date(0)).toISOString(),
+        events: []
+      };
+      return { ok: true, message };
+    }
+  };
+  return {
+    client,
+    /** Every email accepted so far, oldest first. */
+    sent,
+    /** Forget everything sent. */
+    reset() {
+      sent.length = 0;
+      byKey.clear();
+    }
+  };
+}
+export {
+  createMockBellow
+};

package/llms.md

@@ -0,0 +1,74 @@
+# @the-smithy/bellow: reference for AI assistants
+
+Bellow is The Smithy's transactional email service (Amazon SES behind `https://bellow.thesmithy.io`). This
+package is the **only** sanctioned way for a Smithy app to send email. It's server-only: never import it in
+client components or browser code, since the key can send email as the client's domains.
+
+## Before writing code, confirm with the human
+- The client exists in the Bellow dashboard, with its sending domain **verified**.
+- An API key exists for this app and environment and is set as the secret env var `BELLOW_API_KEY`. Never ask
+  for the key in chat, and never write it to a file.
+- Which address to test with: while SES is in the sandbox, only verified addresses receive mail.
+
+## Install
+- `pnpm add @the-smithy/bellow`: public on npm, no `.npmrc` entry or token needed.
+- Use pnpm, not npm or npx, in Smithy repos.
+
+## Env
+`BELLOW_API_KEY` (required, secret), `EMAIL_FROM` (required, `Name <addr@verified-domain>`),
+`EMAIL_REPLY_TO` (optional), `BELLOW_URL` (optional, non-production only).
+
+## Setup (one module)
+```ts
+// lib/email.ts
+import "server-only";
+import { createBellowFromEnv } from "@the-smithy/bellow";
+export const bellow = createBellowFromEnv(); // null when not configured: treat email as off and fall back
+```
+
+## Send
+```ts
+const result = await bellow?.send(
+  { to, subject, html, text, category: "password-reset", tags?: { plan: "pro" }, cc?, bcc?, replyTo?, from? },
+  { idempotencyKey?: "password-reset-<userId>-<window>", retries?, signal? },
+);
+// result: undefined (not configured) | { ok: true, id, status, suppressed, duplicate } | { ok: false, error: BellowError }
+```
+- `category` is required: letters, numbers, `_`, `-`. Pick a stable kebab-case name per kind of email.
+- Addresses: `a@b.com` or `Name <a@b.com>`; one per entry; arrays for several; no duplicates across to/cc/bcc;
+  50 recipients max.
+- Subject is one line. Send both `html` and `text`. Subject, html and text total 512 KB or less.
+- Tags: up to 9 besides category; names can't start with `bellow`; no `category` tag (use the field).
+- `send` never throws for send problems. `sendOrThrow` throws `BellowError`. Invalid input → `invalid_email`
+  with `error.details: { field, message }[]`, and no request is made.
+- Idempotency: always pass a key built from stable ids for anything retryable (webhooks, jobs, buttons). Any
+  string is fine (unsafe ones are hashed). Without one the SDK generates a key per call.
+- The SDK retries `network_error`, `timeout`, `rate_limited` (when Retry-After ≤ 30s), `unavailable` and
+  `server_error`, 2 retries with backoff, reusing the same idempotency key.
+
+## Errors (`BellowError`: code, message, status, details, retryAfter, retryable)
+`invalid_email`, `invalid_request` (local) · `bad_request` 400 · `unauthorized` 401 (key missing/revoked) ·
+`forbidden` 403 (from domain not verified, or client paused) · `not_found` 404 · `conflict` 409 (key reused for
+a different email) · `unprocessable` 422 (all To suppressed) · `rate_limited` 429 · `unavailable` 503 ·
+`server_error` 500 · `network_error` · `timeout` · `aborted`.
+Log `code` and `message`; never log the key or email bodies; don't show raw messages to site visitors.
+
+## Status
+`await bellow.getMessage(id)` → `{ ok: true, message: { id, status, from, to, cc, bcc, subject, tags, createdAt, events[] } }`.
+Status: `queued`, `sent`, `delivered`, `delivery_delayed`, `bounced`, `complained`, `rejected`, `failed`.
+
+## Testing
+```ts
+import { createMockBellow } from "@the-smithy/bellow/testing";
+const mock = createMockBellow({ from: "Acme <hello@acme.com>", fail?: (email) => "rate_limited" | undefined, suppressed?: [...] });
+// pass mock.client wherever your code takes a BellowSender; inspect mock.sent; mock.reset()
+```
+Type your own email helpers against `BellowSender` (from the main entry) so tests can inject the mock.
+
+## Rules
+- One `bellow` instance per app, in a server-only module. Everything that sends goes through it.
+- Public forms: never let a visitor pick both the recipient and the content. Send to a fixed owner address,
+  or a fixed template to the visitor's own address, behind rate limiting or a CAPTCHA.
+- When replacing another provider (Resend, SendGrid, nodemailer): keep the app's existing `sendEmail()` shape
+  if callers depend on it, implement it with `bellow.send`, map its "category"/tag concept to `category`,
+  remove the old dependency and env vars, and keep the "not configured → skip and fall back" behavior.

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@the-smithy/bellow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The standard way for The Smithy's apps to send transactional email through Bellow: validated, retried, idempotent, server-only.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/The-Smithy/bellow.git",
+    "directory": "packages/bellow"
+  },
+  "engines": {
+    "node": ">=20.3"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "llms.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "keywords": [
+    "email",
+    "transactional",
+    "ses",
+    "bellow",
+    "the-smithy"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "node --test --experimental-strip-types --disable-warning=ExperimentalWarning \"test/**/*.test.ts\"",
+    "typecheck": "tsc --noEmit"
+  }
 }