@groundmail/groundhog 0.0.0-stage → 0.1.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,321 @@
-# Temporary Holding Version
+<p align="center"><img src="docs/groundhog.svg" width="360" alt="The Groundhog mascot peeking out of its burrow holding an envelope"></p>
 
-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.
+<h1 align="center">Groundhog</h1>
+
+<p align="center">Catch every email your app sends while you build. Nothing leaves your laptop.<br>
+An open-source local inbox from <a href="https://groundmail.dev/?utm_source=groundhog&utm_medium=readme&utm_campaign=header">Groundmail</a>.</p>
+
+---
+
+Groundhog is a local email inbox for development and tests. Point your app at it and every
+email it sends shows up at `http://localhost:3025`: sign-up codes, password resets, receipts.
+
+- **SMTP** on port 1025, and the **HTTP send APIs** of Groundmail, SendGrid, Postmark, Mailgun,
+  Resend and Amazon SES. Each provider's official SDK works unmodified: you change its base URL,
+  not your code.
+- **A web inbox** with live updates, HTML/text/source/headers, attachments, desktop and mobile
+  widths, light and dark preview, and the one-time code and links pulled out for you.
+- **Failure mode**: make the next sends fail with a 429, 422, 401, outage or timeout, in each
+  provider's own error format (SMTP answers with the matching reply code).
+- **Webhook simulation**: fire delivered, bounce, complaint, open and click events at your app in
+  the payload and signature format of the provider the email came through.
+- **Send to my real inbox**: see a caught email in real Gmail or Outlook, through a free Groundmail account.
+- **For tests and agents**: `waitForEmail()` for Playwright/Vitest, and an MCP server so coding
+  agents can read the verification email themselves.
+
+Coming from MailHog? Groundhog keeps SMTP on 1025; the inbox moves from 8025 to 3025.
+
+## Start it
+
+```bash
+npx @groundmail/groundhog
+```
+
+Node 20 or newer. It opens the inbox in your browser. Or with Docker:
+
+```bash
+docker run --rm -p 1025:1025 -p 3025:3025 ghcr.io/groundmail/groundhog
+```
+
+```yaml
+# docker-compose.yml, next to your app
+services:
+  groundhog:
+    image: ghcr.io/groundmail/groundhog
+    ports: ["1025:1025", "3025:3025"]
+```
+
+In Compose, other services reach it at `groundhog:1025` (SMTP) and `http://groundhog:3025` (APIs).
+Images are multi-arch (amd64, arm64).
+
+## Point your app at it
+
+Pick the way your app already sends. Any API key, username or password is accepted.
+
+### SMTP (Nodemailer, Laravel, Rails, Django, Phoenix…)
+
+```bash
+SMTP_HOST=localhost
+SMTP_PORT=1025
+```
+
+```js
+// Nodemailer
+nodemailer.createTransport({ host: 'localhost', port: 1025 })
+```
+
+```ini
+# Laravel .env
+MAIL_MAILER=smtp
+MAIL_HOST=127.0.0.1
+MAIL_PORT=1025
+MAIL_ENCRYPTION=null
+```
+
+```ruby
+# Rails: config/environments/development.rb
+config.action_mailer.delivery_method = :smtp
+config.action_mailer.smtp_settings = { address: "localhost", port: 1025 }
+```
+
+```python
+# Django settings.py
+EMAIL_HOST = "localhost"
+EMAIL_PORT = 1025
+```
+
+### Groundmail
+
+```js
+import { Groundmail } from 'groundmail'
+
+const gm = new Groundmail(process.env.GROUNDMAIL_API_KEY ?? 'gm_test_anything', {
+  baseUrl: process.env.GROUNDMAIL_BASE_URL ?? 'http://localhost:3025',
+})
+```
+
+### SendGrid
+
+```js
+import sgMail from '@sendgrid/mail'
+
+sgMail.setApiKey('SG.anything')
+sgMail.client.setDefaultRequest('baseUrl', 'http://localhost:3025/sendgrid')
+```
+
+### Postmark
+
+```js
+import { ServerClient } from 'postmark'
+
+const client = new ServerClient('anything', { requestHost: 'localhost:3025/postmark', useHttps: false })
+```
+
+### Mailgun
+
+```js
+import Mailgun from 'mailgun.js'
+import FormData from 'form-data'
+
+const mg = new Mailgun(FormData).client({ username: 'api', key: 'anything', url: 'http://localhost:3025/mailgun' })
+```
+
+### Resend
+
+```bash
+RESEND_BASE_URL=http://localhost:3025/resend
+```
+
+### Amazon SES
+
+```js
+import { SESv2Client } from '@aws-sdk/client-sesv2' // the v1 SESClient works too
+
+const ses = new SESv2Client({
+  endpoint: 'http://localhost:3025/ses',
+  region: 'us-east-1',
+  credentials: { accessKeyId: 'x', secretAccessKey: 'x' },
+})
+```
+
+| API | Base URL | Emulated endpoints |
+|---|---|---|
+| Groundmail | `http://localhost:3025` (or `/groundmail`) | `POST /emails`, `POST /emails/batch`, `GET /emails/:id` |
+| SendGrid | `http://localhost:3025/sendgrid` | `POST /v3/mail/send` |
+| Postmark | `localhost:3025/postmark` | `POST /email`, `/email/batch`, `/email/withTemplate`, `/email/batchWithTemplates` |
+| Mailgun | `http://localhost:3025/mailgun` | `POST /v3/:domain/messages`, `/v3/:domain/messages.mime` |
+| Resend | `http://localhost:3025/resend` | `POST /emails`, `POST /emails/batch`, `GET /emails/:id` |
+| Amazon SES | `http://localhost:3025/ses` | v2 `SendEmail` (simple, raw, template), v1 `SendEmail`, `SendRawEmail` |
+
+Stored provider templates (a SendGrid `template_id`, a Postmark `TemplateAlias`…) can't be
+rendered locally; Groundhog shows the template name and the data it was sent with.
+
+## Testing
+
+`waitForEmail()` waits for an email (one that's already arrived counts) and gives you its code and links.
+
+```bash
+npm install -D @groundmail/groundhog
+```
+
+```ts
+// Playwright
+import { expect, test } from '@playwright/test'
+import { waitForEmail } from '@groundmail/groundhog'
+
+test('magic-link sign-in', async ({ page }) => {
+  const to = `ada+${Date.now()}@example.com`
+  await page.goto('http://localhost:3000/signin')
+  await page.getByLabel('Email').fill(to)
+  await page.getByRole('button', { name: 'Email me a link' }).click()
+
+  const email = await waitForEmail({ to })
+  email.code     // "482913"
+  email.links[0] // "http://localhost:3000/magic?token=…"
+
+  await page.goto(email.links[0])
+  await expect(page.getByRole('heading', { name: `Signed in as ${to}` })).toBeVisible()
+})
+```
+
+The full runnable version is in [examples/playwright](examples/playwright). Helpers:
+
+| Helper | What it does |
+|---|---|
+| `waitForEmail({ to, subject, since, timeout })` | Resolves with the first matching email; throws after `timeout` (default 30 s) |
+| `listEmails({ to, subject, q, limit })` | Newest first |
+| `getEmail(id)`, `clearEmails()` | |
+| `extractCode(email)`, `extractLinks(email)`, `extractLink(email, contains?)` | Work on any HTML or text too |
+| `simulateFault({ status, next })`, `clearFaults()` | Failure mode from a test |
+| `fireWebhook({ id, event })` | Fire a simulated webhook |
+| `startGroundhog({ httpPort, smtpPort })` | Run Groundhog inside your test process (`httpPort: 0` picks a free port) |
+
+The helpers use `GROUNDHOG_URL` (default `http://localhost:3025`) or a `baseUrl` option.
+
+Prefer plain HTTP? The same things are on the JSON API:
+
+| Request | |
+|---|---|
+| `GET /api/emails?to=&subject=&q=&limit=` | List (newest first) |
+| `GET /api/emails/latest?to=` | Latest match, or 404 |
+| `GET /api/wait?to=&subject=&timeout=30000` | Long-poll until a match arrives (408 on timeout) |
+| `GET /api/emails/:id` | One email, with `code` and `links` |
+| `GET /api/emails/:id/source` | Raw RFC 5322 source (`?download` for an `.eml`) |
+| `GET /api/emails/:id/attachments/:n` | An attachment |
+| `DELETE /api/emails/:id`, `DELETE /api/emails` | Delete one, or clear the inbox |
+| `POST /api/faults` `{ "status": 429, "next": 3 }` | Failure mode; `DELETE /api/faults` turns it off |
+| `PUT /api/webhooks` `{ "url": "…" }` | Where simulated webhooks go |
+| `POST /api/emails/:id/webhooks` `{ "event": "bounced" }` | Fire one |
+| `GET /api/events` | Server-sent events for everything above |
+
+## Failure mode
+
+Most apps have never seen their own error handling run. Turn on failure mode in the inbox
+(**Failure mode** in the header) or from a test, and the next sends fail the way the real
+provider fails:
+
+```bash
+curl -X POST localhost:3025/api/faults -d '{"status":429,"next":3}'
+```
+
+| `status` | HTTP APIs answer | SMTP answers |
+|---|---|---|
+| `429` | the provider's rate-limit error (SES v1: `Throttling`) | `450 4.7.1` |
+| `422` | the provider's invalid-recipient error (400 where the provider uses 400) | `550 5.1.1` at `RCPT TO` |
+| `401` | the provider's bad-key error (403 where the provider uses 403) | `535 5.7.8` |
+| `5xx` | 500/503 in the provider's format | `451 4.3.0` |
+| `timeout` | holds the request 30 s, then drops the connection | holds, then `421` |
+
+A banner stays in the inbox while failure mode is on. `next: 0` or `DELETE /api/faults` turns it off.
+
+## Webhook simulation
+
+Set your app's webhook URL in an email's **Webhooks** tab (or `PUT /api/webhooks`), then fire
+`delivered`, `bounced`, `complained`, `opened` or `clicked`. The payload is in the format of the
+API the email came through (Groundmail's for SMTP), or pick one. The delivery log shows what
+your app answered.
+
+Signatures use fixed local keys, so your verification code runs unchanged in development:
+
+| Format | Signature | Local key |
+|---|---|---|
+| Groundmail | `Groundmail-Signature: t=…,v1=…` | `whsec_groundhog_local_dev_secret` |
+| Resend (Svix) | `svix-id`, `svix-timestamp`, `svix-signature` | `whsec_Z3JvdW5kaG9nLWxvY2FsLWRldi13ZWJob29rLWtleSE=` |
+| SendGrid | `X-Twilio-Email-Event-Webhook-Signature` (ECDSA) | public key shown in the Webhooks tab and `GET /api/webhooks` |
+| Mailgun | `signature.signature` in the body | `groundhog-local-mailgun-signing-key` |
+| Postmark | not signed (Postmark uses basic auth) | |
+| Amazon SES | SNS `Notification` envelope | AWS signs SNS with its own certificate, which can't be reproduced locally; skip SNS signature checks in development |
+
+Override the keys with `PUT /api/webhooks { "secrets": { "groundmail": "…" } }`. These keys are
+public; never use them outside local development.
+
+## Send to my real inbox
+
+Some things only show up in a real mail client. Open an email, click **Send to my real inbox**,
+and connect a free [Groundmail account](https://app.groundmail.dev/signup?utm_source=groundhog&utm_medium=readme&utm_campaign=real_inbox)
+once. The sign-in opens in your browser; there's no key to paste. Copies come from Groundmail's
+sandbox sender, which only delivers to your own account address until you verify a domain, so
+Groundhog can't email real users by mistake. The sign-in is saved in `~/.config/groundhog` and
+only used when you click send.
+
+## AI coding agents (MCP)
+
+Agents can finish sign-up and password-reset flows on their own by reading the email:
+
+```bash
+claude mcp add groundhog -- npx -y @groundmail/groundhog mcp
+```
+
+```json
+// Cursor: .cursor/mcp.json
+{ "mcpServers": { "groundhog": { "command": "npx", "args": ["-y", "@groundmail/groundhog", "mcp"] } } }
+```
+
+Tools: `list_emails`, `wait_for_email(to, timeout)`, `get_email(id)`, `get_code(to)`,
+`get_link(to, contains)` and `simulate_fault(status, next)`. The MCP server uses the Groundhog
+running at `GROUNDHOG_URL` (default `http://localhost:3025`), and starts one itself if none is running.
+
+## Options
+
+| Flag | Env | Default |
+|---|---|---|
+| `--smtp-port` | `GROUNDHOG_SMTP_PORT` | `1025` |
+| `--http-port` | `GROUNDHOG_HTTP_PORT` | `3025` |
+| `--host` | `GROUNDHOG_HOST` | `localhost` (`0.0.0.0` in Docker) |
+| `--store <file>` | `GROUNDHOG_STORE` | in memory; a JSON file keeps emails across restarts |
+| `--max <n>` | | `1000` emails |
+| `--webhook-url <url>` | `GROUNDHOG_WEBHOOK_URL` | |
+| `--no-open` | `GROUNDHOG_NO_OPEN=1` | opens the browser at a terminal |
+| `--quiet` | | logs each caught email |
+
+Groundhog never relays mail. Nothing it catches is sent anywhere unless you click
+**Send to my real inbox**.
+
+## Ready for real inboxes?
+
+When it's time to ship, [Groundmail](https://groundmail.dev/?utm_source=groundhog&utm_medium=readme&utm_campaign=go_live)
+sends your app's email for real: an HTTP API and SMTP, with transactional mail on its own servers
+and IPs. The free plan includes 3,000 emails a month. If you use the Groundmail SDK, going live is
+two environment variables:
+
+```bash
+GROUNDMAIL_API_KEY=gm_live_…   # and drop GROUNDMAIL_BASE_URL
+```
+
+[Start free on Groundmail →](https://app.groundmail.dev/signup?utm_source=groundhog&utm_medium=readme&utm_campaign=go_live)
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test                         # Vitest: every provider SDK, SMTP, faults, webhooks, MCP
+npx playwright install chromium
+npm run test:e2e                 # the inbox UI and the Playwright example
+```
+
+Issues and pull requests are welcome.
+
+## License
+
+[MIT](LICENSE)

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { parseArgs } from 'node:util';
+import { withUtm } from './groundmail-account.js';
+import { startGroundhog, VERSION } from './server.js';
+const HELP = `Groundhog ${VERSION}: a local inbox for development. Catches every email your app sends; nothing is delivered.
+
+Usage
+  npx @groundmail/groundhog [options]     start the inbox
+  npx @groundmail/groundhog mcp           MCP server (stdio) for coding agents
+
+Options
+  --smtp-port <port>    SMTP port (default 1025, env GROUNDHOG_SMTP_PORT)
+  --http-port <port>    web UI + APIs (default 3025, env GROUNDHOG_HTTP_PORT)
+  --host <host>         listen address (default localhost; 0.0.0.0 in Docker, env GROUNDHOG_HOST)
+  --store <file>        keep emails in this JSON file across restarts (env GROUNDHOG_STORE)
+  --max <n>             emails kept in memory (default 1000)
+  --webhook-url <url>   where simulated webhooks go (env GROUNDHOG_WEBHOOK_URL)
+  --no-open             don't open the browser
+  --quiet               don't log each caught email
+  -v, --version         print the version
+  -h, --help            this help
+
+Point your app at it
+  SMTP              localhost:1025, any username and password
+  Groundmail SDK    new Groundmail(key, { baseUrl: 'http://localhost:3025' })
+  SendGrid          sgMail.client.setDefaultRequest('baseUrl', 'http://localhost:3025/sendgrid')
+  Postmark          new ServerClient(key, { requestHost: 'localhost:3025/postmark', useHttps: false })
+  Mailgun           mailgun.client({ username: 'api', key, url: 'http://localhost:3025/mailgun' })
+  Resend            RESEND_BASE_URL=http://localhost:3025/resend
+  Amazon SES        new SESv2Client({ endpoint: 'http://localhost:3025/ses' })
+
+Docs: https://github.com/Groundmail/groundhog`;
+function openInBrowser(url) {
+    const [cmd, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] : ['xdg-open', [url]];
+    try {
+        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch {
+        // The URL is printed either way.
+    }
+}
+function port(value, fallback) {
+    if (value === undefined || value === '')
+        return fallback;
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 0 || n > 65535) {
+        console.error(`Not a port: ${value}`);
+        process.exit(2);
+    }
+    return n;
+}
+async function main(argv) {
+    if (argv[0] === 'mcp') {
+        const { runMcp } = await import('./mcp.js');
+        await runMcp();
+        return;
+    }
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            'smtp-port': { type: 'string' },
+            'http-port': { type: 'string' },
+            host: { type: 'string' },
+            store: { type: 'string' },
+            max: { type: 'string' },
+            'webhook-url': { type: 'string' },
+            open: { type: 'boolean', default: true },
+            'no-open': { type: 'boolean' },
+            quiet: { type: 'boolean' },
+            version: { type: 'boolean', short: 'v' },
+            help: { type: 'boolean', short: 'h' },
+        },
+    });
+    if (values.help || positionals[0] === 'help') {
+        console.log(HELP);
+        return;
+    }
+    if (values.version) {
+        console.log(VERSION);
+        return;
+    }
+    if (positionals.length && positionals[0] !== 'start') {
+        console.error(`Unknown command: ${positionals[0]}\n\n${HELP}`);
+        process.exit(2);
+    }
+    const env = process.env;
+    const gh = await startGroundhog({
+        smtpPort: port(values['smtp-port'] ?? env.GROUNDHOG_SMTP_PORT, 1025),
+        httpPort: port(values['http-port'] ?? env.GROUNDHOG_HTTP_PORT, 3025),
+        host: values.host ?? env.GROUNDHOG_HOST ?? 'localhost',
+        storeFile: values.store ?? env.GROUNDHOG_STORE,
+        maxEmails: values.max ? Number(values.max) : undefined,
+        webhooks: { url: values['webhook-url'] ?? env.GROUNDHOG_WEBHOOK_URL ?? null },
+        openBrowser: openInBrowser,
+        log: values.quiet ? undefined : (line) => console.log(`  ${new Date().toLocaleTimeString()}  ${line}`),
+    }).catch((error) => {
+        console.error(`\n  ${error.message}\n`);
+        process.exit(1);
+    });
+    console.log(`
+  Groundhog ${VERSION} is catching email. Nothing leaves this machine.
+
+    Inbox   ${gh.url}
+    SMTP    localhost:${gh.smtpPort}  (any username and password)
+    APIs    ${gh.url}/<groundmail|sendgrid|postmark|mailgun|resend|ses>
+
+  From Groundmail: ${withUtm('https://groundmail.dev/', 'cli')}
+`);
+    const wantsOpen = values.open !== false && !values['no-open'] && process.stdout.isTTY && !env.CI && !env.GROUNDHOG_NO_OPEN;
+    if (wantsOpen)
+        openInBrowser(gh.url);
+    let closing = false;
+    const shutdown = async () => {
+        if (closing)
+            process.exit(0);
+        closing = true;
+        await gh.close();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+main(process.argv.slice(2)).catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/dist/client.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Helpers for tests (Playwright, Vitest, Jest…) that talk to a running Groundhog.
+ *
+ *   const email = await waitForEmail({ to: 'ada@example.com' })
+ *   email.code      // "482913"
+ *   email.links[0]  // "http://localhost:3000/verify?token=…"
+ */
+import { extractCode, extractLinks } from './extract.js';
+import type { Email, FaultKind, WebhookEvent } from './types.js';
+export type ClientOptions = {
+    /** Groundhog's HTTP URL. Default: GROUNDHOG_URL, then http://localhost:3025. */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+};
+export type EmailQuery = {
+    to?: string;
+    from?: string;
+    subject?: string;
+    /** Free-text search over subject, addresses, text and code. */
+    q?: string;
+    via?: Email['via'];
+    /** Only emails caught at or after this time. */
+    since?: Date | string;
+};
+export type WaitOptions = EmailQuery & ClientOptions & {
+    /** Milliseconds. Default 30 000. */
+    timeout?: number;
+};
+/** Wait for an email that matches (one already caught counts). Throws after `timeout`. */
+export declare function waitForEmail(options?: WaitOptions): Promise<Email>;
+export declare function listEmails(query?: EmailQuery & ClientOptions & {
+    limit?: number;
+}): Promise<Email[]>;
+export declare function getEmail(id: string, options?: ClientOptions): Promise<Email>;
+export declare function clearEmails(options?: ClientOptions): Promise<void>;
+/** Make the next `next` sends fail. `status`: 429, 422, 401, '5xx' or 'timeout'. */
+export declare function simulateFault(options: ClientOptions & {
+    status: 429 | 422 | 401 | 500 | 503 | '5xx' | 'timeout' | FaultKind;
+    next?: number;
+    timeoutMs?: number;
+}): Promise<void>;
+export declare function clearFaults(options?: ClientOptions): Promise<void>;
+/** Fire a simulated webhook for a caught email at the configured (or given) URL. */
+export declare function fireWebhook(options: ClientOptions & {
+    id: string;
+    event: WebhookEvent;
+    url?: string;
+}): Promise<{
+    status: number | null;
+    ok: boolean;
+    error: string | null;
+}>;
+/** The first link in the email (skipping unsubscribe/asset links), or the first containing `contains`. */
+export declare function extractLink(email: Pick<Email, 'html' | 'text'> | string, contains?: string): string | null;
+export { extractCode, extractLinks };

package/dist/client.js

@@ -0,0 +1,90 @@
+/**
+ * Helpers for tests (Playwright, Vitest, Jest…) that talk to a running Groundhog.
+ *
+ *   const email = await waitForEmail({ to: 'ada@example.com' })
+ *   email.code      // "482913"
+ *   email.links[0]  // "http://localhost:3000/verify?token=…"
+ */
+import { extractCode, extractLinks, pickLink } from './extract.js';
+function base(options = {}) {
+    const fromEnv = typeof process !== 'undefined' ? process.env?.GROUNDHOG_URL : undefined;
+    return (options.baseUrl ?? fromEnv ?? 'http://localhost:3025').replace(/\/+$/, '');
+}
+function queryString(query) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        if (!['to', 'from', 'subject', 'q', 'via', 'since', 'timeout', 'limit'].includes(key))
+            continue;
+        params.set(key, value instanceof Date ? value.toISOString() : String(value));
+    }
+    const text = params.toString();
+    return text ? `?${text}` : '';
+}
+async function request(path, init = {}) {
+    const doFetch = init.fetch ?? fetch;
+    let response;
+    try {
+        response = await doFetch(`${base(init)}${path}`, {
+            ...init,
+            headers: { 'Content-Type': 'application/json', ...(init.headers ?? {}) },
+        });
+    }
+    catch (error) {
+        throw new Error(`Could not reach Groundhog at ${base(init)}. Start it with \`npx @groundmail/groundhog\`. (${error.message})`);
+    }
+    const body = (await response.json().catch(() => ({})));
+    return { status: response.status, body };
+}
+/** Wait for an email that matches (one already caught counts). Throws after `timeout`. */
+export async function waitForEmail(options = {}) {
+    const timeout = options.timeout ?? 30_000;
+    const { status, body } = await request(`/api/wait${queryString({ ...options, timeout })}`, options);
+    if (status === 200)
+        return body;
+    const what = [options.to && `to ${options.to}`, options.subject && `subject "${options.subject}"`].filter(Boolean).join(', ');
+    throw new Error(`No email${what ? ` ${what}` : ''} arrived within ${timeout} ms${body.error && status !== 408 ? `: ${body.error}` : ''}`);
+}
+export async function listEmails(query = {}) {
+    const { body } = await request(`/api/emails${queryString(query)}`, query);
+    return body.data ?? [];
+}
+export async function getEmail(id, options = {}) {
+    const { status, body } = await request(`/api/emails/${encodeURIComponent(id)}`, options);
+    if (status !== 200)
+        throw new Error(body.error ?? `Email ${id} not found`);
+    return body;
+}
+export async function clearEmails(options = {}) {
+    await request(`/api/emails`, { ...options, method: 'DELETE' });
+}
+/** Make the next `next` sends fail. `status`: 429, 422, 401, '5xx' or 'timeout'. */
+export async function simulateFault(options) {
+    const { status, body } = await request(`/api/faults`, {
+        ...options,
+        method: 'POST',
+        body: JSON.stringify({ status: options.status, next: options.next ?? 1, timeoutMs: options.timeoutMs }),
+    });
+    if (status !== 200)
+        throw new Error(body.error ?? 'Could not set the fault');
+}
+export async function clearFaults(options = {}) {
+    await request(`/api/faults`, { ...options, method: 'DELETE' });
+}
+/** Fire a simulated webhook for a caught email at the configured (or given) URL. */
+export async function fireWebhook(options) {
+    const { status, body } = await request(`/api/emails/${encodeURIComponent(options.id)}/webhooks`, {
+        ...options,
+        method: 'POST',
+        body: JSON.stringify({ event: options.event, url: options.url }),
+    });
+    if (status !== 200)
+        throw new Error(body.error ?? 'Could not fire the webhook');
+    return body;
+}
+/** The first link in the email (skipping unsubscribe/asset links), or the first containing `contains`. */
+export function extractLink(email, contains) {
+    return pickLink(extractLinks(email), contains);
+}
+export { extractCode, extractLinks };

package/dist/extract.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Pull the one-time code and the links out of an email, so a test (or an agent)
+ * can finish a sign-in without reading the email itself.
+ */
+type EmailLike = {
+    html?: string | null;
+    text?: string | null;
+    subject?: string | null;
+};
+export declare function decodeEntities(value: string): string;
+/** A rough plain-text rendering of HTML, good enough for finding codes. */
+export declare function htmlToText(html: string): string;
+/** Every http(s) link in the email, in the order it appears, without duplicates. */
+export declare function extractLinks(input: EmailLike | string): string[];
+/**
+ * The one-time code in the email: digits (4–8, also "123 456" / "123-456"), or a short
+ * letters-and-digits code next to a word like "code". `null` when nothing looks like one.
+ */
+export declare function extractCode(input: EmailLike | string): string | null;
+/** The first link whose URL contains `contains` (or the first link that isn't an unsubscribe/asset link). */
+export declare function pickLink(links: string[], contains?: string): string | null;
+export {};