@groundmail/groundhog 0.0.0-stage → 0.1.1

package/dist/http.js

@@ -0,0 +1,152 @@
+import busboy from 'busboy';
+export const MAX_BODY_BYTES = 60 * 1024 * 1024;
+export class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+export class RequestContext {
+    req;
+    res;
+    url;
+    params = {};
+    bodyPromise = null;
+    constructor(req, res) {
+        this.req = req;
+        this.res = res;
+        this.url = new URL(req.url ?? '/', 'http://localhost');
+    }
+    get method() {
+        return (this.req.method ?? 'GET').toUpperCase();
+    }
+    header(name) {
+        const value = this.req.headers[name.toLowerCase()];
+        return Array.isArray(value) ? value.join(', ') : (value ?? '');
+    }
+    query(name) {
+        return this.url.searchParams.get(name) ?? undefined;
+    }
+    body() {
+        if (!this.bodyPromise) {
+            this.bodyPromise = new Promise((resolve, reject) => {
+                const chunks = [];
+                let size = 0;
+                this.req.on('data', (chunk) => {
+                    size += chunk.length;
+                    if (size > MAX_BODY_BYTES) {
+                        reject(new HttpError(413, 'Request body is too large'));
+                        this.req.destroy();
+                        return;
+                    }
+                    chunks.push(chunk);
+                });
+                this.req.on('end', () => resolve(Buffer.concat(chunks)));
+                this.req.on('error', reject);
+            });
+        }
+        return this.bodyPromise;
+    }
+    async json() {
+        const raw = await this.body();
+        if (!raw.length)
+            return {};
+        try {
+            return JSON.parse(raw.toString('utf8'));
+        }
+        catch {
+            throw new HttpError(400, 'The request body is not valid JSON');
+        }
+    }
+    /** application/x-www-form-urlencoded, as ordered pairs (keys repeat). */
+    async formPairs() {
+        const raw = await this.body();
+        return [...new URLSearchParams(raw.toString('utf8')).entries()];
+    }
+    async multipart() {
+        const contentType = this.header('content-type');
+        if (!contentType.toLowerCase().startsWith('multipart/')) {
+            return { fields: await this.formPairs(), files: [] };
+        }
+        const raw = await this.body();
+        return new Promise((resolve, reject) => {
+            const form = { fields: [], files: [] };
+            const parser = busboy({ headers: { 'content-type': contentType }, limits: { fileSize: MAX_BODY_BYTES, fieldSize: MAX_BODY_BYTES } });
+            parser.on('field', (name, value) => form.fields.push([name, value]));
+            parser.on('file', (name, stream, info) => {
+                const chunks = [];
+                stream.on('data', (chunk) => chunks.push(chunk));
+                stream.on('end', () => form.files.push({ field: name, filename: info.filename || 'attachment', contentType: info.mimeType || 'application/octet-stream', content: Buffer.concat(chunks) }));
+            });
+            parser.on('close', () => resolve(form));
+            parser.on('error', reject);
+            parser.end(raw);
+        });
+    }
+    send(result) {
+        if (this.res.headersSent)
+            return;
+        const headers = { ...(result.headers ?? {}) };
+        let payload = '';
+        if (Buffer.isBuffer(result.body))
+            payload = result.body;
+        else if (typeof result.body === 'string')
+            payload = result.body;
+        else if (result.body !== undefined) {
+            payload = JSON.stringify(result.body);
+            if (!Object.keys(headers).some((key) => key.toLowerCase() === 'content-type'))
+                headers['Content-Type'] = 'application/json; charset=utf-8';
+        }
+        this.res.writeHead(result.status, headers);
+        this.res.end(payload);
+    }
+}
+export function compileRoute(path) {
+    const pattern = path
+        .split('/')
+        .map((segment) => {
+        if (segment === '*')
+            return '(?<rest>.*)';
+        if (segment.startsWith(':'))
+            return `(?<${segment.slice(1)}>[^/]+)`;
+        return segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    })
+        .join('/');
+    return new RegExp(`^${pattern}/?$`);
+}
+export class Router {
+    routes = [];
+    add(method, path, handler) {
+        this.routes.push({ method: method.toUpperCase(), path, handler, regex: compileRoute(path) });
+        return this;
+    }
+    get(path, handler) {
+        return this.add('GET', path, handler);
+    }
+    post(path, handler) {
+        return this.add('POST', path, handler);
+    }
+    put(path, handler) {
+        return this.add('PUT', path, handler);
+    }
+    delete(path, handler) {
+        return this.add('DELETE', path, handler);
+    }
+    match(method, pathname) {
+        let pathMatched = false;
+        for (const route of this.routes) {
+            const match = route.regex.exec(pathname);
+            if (!match)
+                continue;
+            pathMatched = true;
+            if (route.method !== method && !(route.method === 'GET' && method === 'HEAD'))
+                continue;
+            const params = {};
+            for (const [key, value] of Object.entries(match.groups ?? {}))
+                params[key] = decodeURIComponent(value ?? '');
+            return { route, params };
+        }
+        return pathMatched ? 'method' : null;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { clearEmails, clearFaults, extractCode, extractLink, extractLinks, fireWebhook, getEmail, listEmails, simulateFault, waitForEmail, type ClientOptions, type EmailQuery, type WaitOptions, } from './client.js';
+export { startGroundhog, VERSION, type Groundhog, type GroundhogOptions } from './server.js';
+export type { Address, AttachmentInfo, Email, FaultKind, Provider, WebhookEvent } from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { clearEmails, clearFaults, extractCode, extractLink, extractLinks, fireWebhook, getEmail, listEmails, simulateFault, waitForEmail, } from './client.js';
+export { startGroundhog, VERSION } from './server.js';

package/dist/mcp.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `groundhog mcp`: an MCP server (stdio) so coding agents can read the emails their
+ * app sends: finish a sign-up with the code, follow a reset link, test failures.
+ * Uses the Groundhog at GROUNDHOG_URL (default http://localhost:3025), and starts
+ * one in this process when none is running.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createMcpServer(baseUrl: string): McpServer;
+export declare function runMcp(options?: {
+    baseUrl?: string;
+}): Promise<void>;

package/dist/mcp.js

@@ -0,0 +1,156 @@
+/**
+ * `groundhog mcp`: an MCP server (stdio) so coding agents can read the emails their
+ * app sends: finish a sign-up with the code, follow a reset link, test failures.
+ * Uses the Groundhog at GROUNDHOG_URL (default http://localhost:3025), and starts
+ * one in this process when none is running.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { getEmail, listEmails, simulateFault, waitForEmail } from './client.js';
+import { pickLink } from './extract.js';
+import { startGroundhog, VERSION } from './server.js';
+function brief(email) {
+    return {
+        id: email.id,
+        subject: email.subject,
+        from: email.from?.address ?? null,
+        to: email.to.map((a) => a.address),
+        via: email.via,
+        received_at: email.createdAt,
+        code: email.code,
+        links: email.links.slice(0, 10),
+    };
+}
+function text(value) {
+    return { content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }] };
+}
+function failure(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+async function reachable(baseUrl) {
+    try {
+        const response = await fetch(`${baseUrl}/api/health`, { signal: AbortSignal.timeout(1500) });
+        const body = (await response.json());
+        return body.name === 'groundhog';
+    }
+    catch {
+        return false;
+    }
+}
+async function emailFor(baseUrl, input) {
+    if (input.id)
+        return getEmail(input.id, { baseUrl });
+    return waitForEmail({ baseUrl, to: input.to, subject: input.subject, timeout: Math.round((input.wait_seconds ?? 10) * 1000) });
+}
+export function createMcpServer(baseUrl) {
+    const server = new McpServer({ name: 'groundhog', version: VERSION });
+    const filters = {
+        to: z.string().optional().describe('Recipient address (or @domain) to match'),
+        subject: z.string().optional().describe('Text the subject contains'),
+    };
+    server.registerTool('list_emails', {
+        title: 'List caught emails',
+        description: 'Newest first. Emails the app sent to Groundhog, the local dev inbox; nothing was delivered.',
+        inputSchema: { ...filters, limit: z.number().int().min(1).max(100).optional().describe('Default 20') },
+        annotations: { readOnlyHint: true },
+    }, async ({ to, subject, limit }) => {
+        const emails = await listEmails({ baseUrl, to, subject, limit: limit ?? 20 });
+        return text(emails.length ? emails.map(brief) : 'The inbox is empty. Trigger the email in the app first (sign up, reset a password…).');
+    });
+    server.registerTool('wait_for_email', {
+        title: 'Wait for an email',
+        description: 'Waits until an email matching `to`/`subject` arrives (an already-caught one counts) and returns it with its code and links.',
+        inputSchema: { ...filters, timeout_seconds: z.number().min(1).max(300).optional().describe('Default 30') },
+        annotations: { readOnlyHint: true },
+    }, async ({ to, subject, timeout_seconds }) => {
+        try {
+            const email = await waitForEmail({ baseUrl, to, subject, timeout: Math.round((timeout_seconds ?? 30) * 1000) });
+            return text({ ...brief(email), text: (email.text ?? '').slice(0, 2000) });
+        }
+        catch (error) {
+            return failure(error.message);
+        }
+    });
+    server.registerTool('get_email', {
+        title: 'Read an email',
+        description: 'The full text, headers summary, code and links of one email, by id.',
+        inputSchema: { id: z.string().describe('Email id from list_emails') },
+        annotations: { readOnlyHint: true },
+    }, async ({ id }) => {
+        try {
+            const email = await getEmail(id, { baseUrl });
+            return text({ ...brief(email), cc: email.cc.map((a) => a.address), text: email.text, attachments: email.attachments.map((a) => a.filename) });
+        }
+        catch (error) {
+            return failure(error.message);
+        }
+    });
+    server.registerTool('get_code', {
+        title: 'Get the one-time code',
+        description: 'The verification / sign-in code from the latest matching email (waits briefly if it has not arrived).',
+        inputSchema: { ...filters, id: z.string().optional(), wait_seconds: z.number().min(0).max(300).optional().describe('Default 10') },
+        annotations: { readOnlyHint: true },
+    }, async (input) => {
+        try {
+            const email = await emailFor(baseUrl, input);
+            if (!email.code)
+                return failure(`"${email.subject}" (${email.id}) has no code in it. Its links: ${email.links.slice(0, 5).join(' ') || 'none'}`);
+            return text(email.code);
+        }
+        catch (error) {
+            return failure(error.message);
+        }
+    });
+    server.registerTool('get_link', {
+        title: 'Get a link',
+        description: 'A link from the latest matching email: the magic link / verify / reset link by default, or the first one containing `contains`.',
+        inputSchema: { ...filters, id: z.string().optional(), contains: z.string().optional().describe('Part of the URL to look for, e.g. "/verify"'), wait_seconds: z.number().min(0).max(300).optional().describe('Default 10') },
+        annotations: { readOnlyHint: true },
+    }, async (input) => {
+        try {
+            const email = await emailFor(baseUrl, input);
+            const link = pickLink(email.links, input.contains);
+            if (!link)
+                return failure(`No ${input.contains ? `link containing "${input.contains}"` : 'link'} in "${email.subject}" (${email.id}).`);
+            return text(link);
+        }
+        catch (error) {
+            return failure(error.message);
+        }
+    });
+    server.registerTool('simulate_fault', {
+        title: 'Make sends fail',
+        description: "Makes the app's next sends fail the way a real provider would (every provider API and SMTP), to test error handling. status: 429 rate limit, 422 invalid recipient, 401 bad key, 5xx outage, timeout. next: 0 turns failure mode off.",
+        inputSchema: {
+            status: z.enum(['429', '422', '401', '5xx', 'timeout']),
+            next: z.number().int().min(0).max(1000).optional().describe('How many sends fail. Default 1'),
+        },
+    }, async ({ status, next }) => {
+        try {
+            await simulateFault({ baseUrl, status: status === '5xx' || status === 'timeout' ? status : Number(status), next: next ?? 1 });
+            return text(next === 0 ? 'Failure mode is off.' : `The next ${next ?? 1} send(s) will fail with ${status}.`);
+        }
+        catch (error) {
+            return failure(error.message);
+        }
+    });
+    return server;
+}
+export async function runMcp(options = {}) {
+    let baseUrl = (options.baseUrl ?? process.env.GROUNDHOG_URL ?? 'http://localhost:3025').replace(/\/+$/, '');
+    if (!(await reachable(baseUrl))) {
+        // No Groundhog running: start one here so the agent still has an inbox.
+        try {
+            const port = Number(new URL(baseUrl).port) || 3025;
+            const local = await startGroundhog({ httpPort: port, smtpPort: Number(process.env.GROUNDHOG_SMTP_PORT) || 1025, log: (line) => process.stderr.write(`[groundhog] ${line}\n`) });
+            baseUrl = local.url;
+            process.stderr.write(`[groundhog] started an inbox at ${local.url} (SMTP :${local.smtpPort})\n`);
+        }
+        catch (error) {
+            process.stderr.write(`[groundhog] could not reach or start Groundhog at ${baseUrl}: ${error.message}\n`);
+        }
+    }
+    const server = createMcpServer(baseUrl);
+    await server.connect(new StdioServerTransport());
+}

package/dist/mime.d.ts

@@ -0,0 +1,52 @@
+import type { Address, Provider, StoredEmail } from './types.js';
+export declare function newId(prefix?: string): string;
+export type AddressInput = string | {
+    email?: string;
+    address?: string;
+    name?: string | null;
+} | null | undefined;
+/** "Ada <ada@example.com>", "ada@example.com", { email, name } or { address, name } → Address. */
+export declare function toAddress(input: AddressInput): Address | null;
+/** Accepts one address, an array, or a comma-separated string. */
+export declare function toAddressList(input: unknown): Address[];
+export declare function formatAddress(address: Address): string;
+export type AttachmentInput = {
+    filename?: string;
+    content: Buffer | string;
+    contentType?: string;
+    cid?: string;
+    encoding?: 'base64' | 'utf8';
+};
+/** The parts an HTTP send API hands us. Every provider route maps its own body onto this. */
+export type ComposeInput = {
+    from: Address | null;
+    to: Address[];
+    cc?: Address[];
+    bcc?: Address[];
+    replyTo?: Address[];
+    subject?: string;
+    html?: string | null;
+    text?: string | null;
+    headers?: Record<string, string>;
+    attachments?: AttachmentInput[];
+    tags?: string[];
+    metadata?: Record<string, string>;
+};
+/** Build the RFC 5322 source for an API send, so every email has a real Source tab. */
+export declare function compose(input: ComposeInput, messageId: string): Promise<Buffer>;
+export type IngestMeta = {
+    via: Provider;
+    providerMessageId?: string;
+    /** Envelope recipients (SMTP RCPT TO, or API bcc) that aren't in the headers. */
+    envelopeTo?: Address[];
+    bcc?: Address[];
+    tags?: string[];
+    metadata?: Record<string, string>;
+    id?: string;
+    createdAt?: string;
+};
+/** Parse raw source into the stored shape. */
+export declare function parseEmail(raw: Buffer, meta: IngestMeta): Promise<StoredEmail>;
+/** Compose and parse an API send in one step. */
+export declare function ingestApiSend(input: ComposeInput, meta: IngestMeta): Promise<StoredEmail>;
+export declare function uuid(): string;

package/dist/mime.js

@@ -0,0 +1,182 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { simpleParser } from 'mailparser';
+import MailComposer from 'nodemailer/lib/mail-composer/index.js';
+import { extractCode, extractLinks } from './extract.js';
+export function newId(prefix = 'gh') {
+    return `${prefix}_${randomBytes(9).toString('base64url')}`;
+}
+/** "Ada <ada@example.com>", "ada@example.com", { email, name } or { address, name } → Address. */
+export function toAddress(input) {
+    if (!input)
+        return null;
+    if (typeof input === 'string') {
+        const trimmed = input.trim();
+        if (!trimmed)
+            return null;
+        const match = trimmed.match(/^\s*"?([^"<]*?)"?\s*<([^>]+)>\s*$/);
+        if (match)
+            return { name: match[1].trim(), address: match[2].trim() };
+        return { name: '', address: trimmed };
+    }
+    const address = (input.email ?? input.address ?? '').trim();
+    if (!address)
+        return null;
+    return { name: (input.name ?? '').trim(), address };
+}
+/** Accepts one address, an array, or a comma-separated string. */
+export function toAddressList(input) {
+    if (input == null || input === '')
+        return [];
+    if (Array.isArray(input))
+        return input.flatMap((item) => toAddressList(item));
+    if (typeof input === 'string') {
+        return splitAddresses(input)
+            .map((part) => toAddress(part))
+            .filter((a) => Boolean(a));
+    }
+    const one = toAddress(input);
+    return one ? [one] : [];
+}
+function splitAddresses(value) {
+    const out = [];
+    let current = '';
+    let inQuotes = false;
+    let inAngle = false;
+    for (const ch of value) {
+        if (ch === '"')
+            inQuotes = !inQuotes;
+        if (ch === '<')
+            inAngle = true;
+        if (ch === '>')
+            inAngle = false;
+        if ((ch === ',' || ch === ';') && !inQuotes && !inAngle) {
+            if (current.trim())
+                out.push(current.trim());
+            current = '';
+        }
+        else
+            current += ch;
+    }
+    if (current.trim())
+        out.push(current.trim());
+    return out;
+}
+export function formatAddress(address) {
+    return address.name ? `"${address.name.replace(/"/g, '')}" <${address.address}>` : address.address;
+}
+/** Build the RFC 5322 source for an API send, so every email has a real Source tab. */
+export async function compose(input, messageId) {
+    const mail = {
+        from: input.from ? formatAddress(input.from) : undefined,
+        to: input.to.map(formatAddress),
+        cc: input.cc?.map(formatAddress),
+        bcc: input.bcc?.map(formatAddress),
+        replyTo: input.replyTo?.map(formatAddress),
+        subject: input.subject ?? '',
+        html: input.html ?? undefined,
+        text: input.text ?? undefined,
+        headers: input.headers,
+        messageId: `<${messageId}@groundhog.local>`,
+        attachments: input.attachments?.map((attachment) => ({
+            filename: attachment.filename,
+            content: attachment.content,
+            contentType: attachment.contentType,
+            cid: attachment.cid,
+            encoding: typeof attachment.content === 'string' ? (attachment.encoding ?? 'base64') : undefined,
+        })),
+    };
+    const node = new MailComposer(mail).compile();
+    node.keepBcc = true;
+    return node.build();
+}
+function addressList(value) {
+    if (!value)
+        return [];
+    const objects = Array.isArray(value) ? value : [value];
+    const out = [];
+    for (const object of objects) {
+        for (const entry of object.value) {
+            if (entry.address)
+                out.push({ name: entry.name ?? '', address: entry.address });
+            for (const member of entry.group ?? []) {
+                if (member.address)
+                    out.push({ name: member.name ?? '', address: member.address });
+            }
+        }
+    }
+    return out;
+}
+function headerPairs(parsed) {
+    return parsed.headerLines.map((line) => {
+        const colon = line.line.indexOf(':');
+        const name = colon >= 0 ? line.line.slice(0, colon) : line.key;
+        const value = colon >= 0 ? line.line.slice(colon + 1).replace(/\r?\n[ \t]+/g, ' ').trim() : '';
+        return [name, value];
+    });
+}
+/** Parse raw source into the stored shape. */
+export async function parseEmail(raw, meta) {
+    const parsed = await simpleParser(raw, { skipImageLinks: true, skipTextToHtml: true });
+    const id = meta.id ?? newId();
+    const to = addressList(parsed.to);
+    const cc = addressList(parsed.cc);
+    let bcc = meta.bcc ?? addressList(parsed.bcc);
+    if (meta.envelopeTo?.length) {
+        const visible = new Set([...to, ...cc, ...bcc].map((a) => a.address.toLowerCase()));
+        bcc = [...bcc, ...meta.envelopeTo.filter((a) => !visible.has(a.address.toLowerCase()))];
+    }
+    const attachmentContent = new Map();
+    const attachments = parsed.attachments.map((attachment, index) => {
+        const attachmentId = `${index}`;
+        attachmentContent.set(attachmentId, attachment.content);
+        return {
+            id: attachmentId,
+            filename: attachment.filename ?? `attachment-${index + 1}`,
+            contentType: attachment.contentType,
+            size: attachment.size ?? attachment.content.length,
+            contentId: attachment.contentId?.replace(/^<|>$/g, ''),
+            inline: attachment.contentDisposition === 'inline' || Boolean(attachment.related),
+        };
+    });
+    const html = typeof parsed.html === 'string' ? parsed.html : null;
+    const text = parsed.text ?? null;
+    const subject = parsed.subject ?? '';
+    return {
+        id,
+        providerMessageId: meta.providerMessageId ?? parsed.messageId?.replace(/^<|>$/g, '') ?? id,
+        via: meta.via,
+        from: addressList(parsed.from)[0] ?? null,
+        to,
+        cc,
+        bcc,
+        replyTo: addressList(parsed.replyTo),
+        subject,
+        html,
+        text,
+        headers: headerPairs(parsed),
+        attachments,
+        tags: meta.tags ?? [],
+        metadata: meta.metadata ?? {},
+        createdAt: meta.createdAt ?? new Date().toISOString(),
+        size: raw.length,
+        code: extractCode({ html, text, subject }),
+        links: extractLinks({ html, text }),
+        raw,
+        attachmentContent,
+    };
+}
+/** Compose and parse an API send in one step. */
+export async function ingestApiSend(input, meta) {
+    const id = meta.id ?? newId();
+    const raw = await compose(input, id);
+    return parseEmail(raw, {
+        ...meta,
+        id,
+        bcc: input.bcc ?? [],
+        tags: meta.tags ?? input.tags,
+        metadata: meta.metadata ?? input.metadata,
+    });
+}
+export function uuid() {
+    return randomUUID();
+}

package/dist/providers/common.d.ts

@@ -0,0 +1,14 @@
+import type { AttachmentInput } from '../mime.js';
+import type { Email } from '../types.js';
+/** Base64 string, a JSON-serialized Buffer (`{ type: 'Buffer', data }`), or a byte array → Buffer. */
+export declare function decodeContent(content: unknown): Buffer;
+export declare function attachment(filename: unknown, content: unknown, contentType?: unknown, cid?: unknown): AttachmentInput;
+export declare function str(value: unknown): string | undefined;
+/** `{ "X-Foo": "bar" }` or `[{ name, value }]` / `[{ Name, Value }]` → record. */
+export declare function headerRecord(input: unknown): Record<string, string> | undefined;
+export declare function hex(bytes: number): string;
+export declare function unixSeconds(date?: Date): number;
+export declare function recipient(email: Email): string;
+export declare function allRecipients(email: Email): string[];
+export declare function fromString(email: Email): string;
+export declare function senderDomain(email: Email): string;

package/dist/providers/common.js

@@ -0,0 +1,68 @@
+import { randomBytes } from 'node:crypto';
+/** Base64 string, a JSON-serialized Buffer (`{ type: 'Buffer', data }`), or a byte array → Buffer. */
+export function decodeContent(content) {
+    if (Buffer.isBuffer(content))
+        return content;
+    if (typeof content === 'string')
+        return Buffer.from(content, 'base64');
+    if (Array.isArray(content))
+        return Buffer.from(content);
+    if (content && typeof content === 'object' && Array.isArray(content.data)) {
+        return Buffer.from(content.data);
+    }
+    return Buffer.alloc(0);
+}
+export function attachment(filename, content, contentType, cid) {
+    return {
+        filename: typeof filename === 'string' && filename ? filename : 'attachment',
+        content: decodeContent(content),
+        contentType: typeof contentType === 'string' && contentType ? contentType : undefined,
+        cid: typeof cid === 'string' && cid ? cid : undefined,
+    };
+}
+export function str(value) {
+    if (value == null)
+        return undefined;
+    return typeof value === 'string' ? value : String(value);
+}
+/** `{ "X-Foo": "bar" }` or `[{ name, value }]` / `[{ Name, Value }]` → record. */
+export function headerRecord(input) {
+    if (!input)
+        return undefined;
+    const out = {};
+    if (Array.isArray(input)) {
+        for (const item of input) {
+            const name = str(item.name ?? item.Name);
+            const value = str(item.value ?? item.Value);
+            if (name && value !== undefined)
+                out[name] = value;
+        }
+    }
+    else if (typeof input === 'object') {
+        for (const [name, value] of Object.entries(input)) {
+            if (value !== undefined && value !== null)
+                out[name] = String(value);
+        }
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+export function hex(bytes) {
+    return randomBytes(bytes).toString('hex');
+}
+export function unixSeconds(date = new Date()) {
+    return Math.floor(date.getTime() / 1000);
+}
+export function recipient(email) {
+    return email.to[0]?.address ?? email.cc[0]?.address ?? email.bcc[0]?.address ?? 'unknown@localhost';
+}
+export function allRecipients(email) {
+    return [...email.to, ...email.cc, ...email.bcc].map((a) => a.address);
+}
+export function fromString(email) {
+    if (!email.from)
+        return '';
+    return email.from.name ? `${email.from.name} <${email.from.address}>` : email.from.address;
+}
+export function senderDomain(email) {
+    return email.from?.address.split('@')[1] ?? 'localhost';
+}

package/dist/providers/groundmail.d.ts

@@ -0,0 +1,31 @@
+import type { HttpResult } from '../http.js';
+import type { Email, StoredEmail } from '../types.js';
+import type { ProviderModule } from './types.js';
+export declare function groundmailSendFromBody(body: Record<string, unknown>, via: 'groundmail' | 'resend'): Promise<StoredEmail | HttpResult>;
+export declare function isResult(value: StoredEmail | HttpResult): value is HttpResult;
+export declare function emailView(email: Email): {
+    id: string;
+    from: string;
+    to: string[];
+    cc: string[];
+    bcc: string[];
+    reply_to: string[];
+    subject: string;
+    status: string;
+    last_event: string;
+    bounce_reason: null;
+    bounce_type: null;
+    held_back: never[];
+    test: boolean;
+    tags: string[];
+    scheduled_at: null;
+    cancelled_at: null;
+    created_at: string;
+    sent_at: string;
+    delivered_at: string;
+    bounced_at: null;
+    opened_at: null;
+    clicked_at: null;
+};
+/** Groundmail's own API. Mounted at `/` and `/groundmail`. */
+export declare const groundmail: ProviderModule;