@everydaydevopsio/hail 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,9 @@
+ISC License
+
+Copyright (c) 2026 Mark Allen and Hail contributors
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+Original source snapshots under upstream/ retain their own notices and package license declarations. See docs/UPSTREAM.md for provenance.

package/README.md

@@ -1,3 +1,199 @@
-# Temporary Holding Version
+# Hail
 
-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.
+[![CI](https://github.com/everydaydevopsio/hail/actions/workflows/ci.yml/badge.svg)](https://github.com/everydaydevopsio/hail/actions/workflows/ci.yml) [![Release](https://github.com/everydaydevopsio/hail/actions/workflows/release.yml/badge.svg)](https://github.com/everydaydevopsio/hail/actions/workflows/release.yml) [![GitHub Release](https://img.shields.io/github/v/release/everydaydevopsio/hail)](https://github.com/everydaydevopsio/hail/releases) [![License](https://img.shields.io/github/license/everydaydevopsio/hail)](LICENSE)
+
+**Send. Receive. Verify.**
+
+Playwright-native tests for magic-link logins, invitations, one-time codes, and application email delivery. Hail receives real email in your own AWS account, gives each test a unique address, and helps your browser test complete the workflow.
+
+**Status: release workflow available; live AWS delivery must be verified separately.** Check the [npm package](https://www.npmjs.com/package/@everydaydevopsio/hail) for published versions. The automated suite separates local browser proof from the opt-in live delivery gate.
+
+Maintainers can use the [manual npm release workflow](docs/RELEASING.md) after its registry trust and GitHub environment are configured. Adding the workflow alone does not publish a package.
+
+Start with the [AWS quickstart](docs/QUICKSTART.md) to deploy with Cloudflare and a GitHub-sourced Terraform module, then run your first email workflow test.
+
+## What is included
+
+- TypeScript email client with unique inboxes, checkpoints, sender/subject filters, bounded waits, message consumption, pagination, and legacy SES-client storage support.
+- Playwright `hail` and `inbox` fixtures. Link extraction parses HTML, requires allowed origins, and never fetches the link.
+- `hail init`, `hail configure`, and read-only `hail doctor` commands.
+- Terraform receiver and Cloudflare, Route53, and manual-DNS templates. No long-lived server, database, or Kubernetes cluster.
+- One retryable SES → S3/SNS → SQS → Lambda ingestion path. The worker retains raw MIME and publishes idempotent recipient metadata. Failed records reach the ingestion DLQ.
+- Unit, Python worker, Terraform mock, package, and Chromium/Firefox/WebKit workflow tests.
+
+The application keeps its existing email sender. No mailbox or Terraform apply is needed per test. Unique addresses prevent accidental collisions; they are not an IAM isolation boundary.
+
+## Validate this checkout without AWS
+
+Requirements: Node.js 22+, Python 3.12+, and Terraform 1.7+ for infrastructure checks.
+
+```bash
+npm ci
+npm run build
+npm run typecheck
+npm test
+npm run test:python
+npx playwright install --with-deps chromium firefox webkit
+npm run test:e2e
+
+terraform -chdir=terraform/modules/receiver init -backend=false
+terraform -chdir=terraform/modules/receiver validate
+terraform -chdir=terraform/modules/receiver test
+```
+
+The browser tests use a loopback-only demo application and an in-memory MIME store. They test authenticated identity, one-time token reuse, server-side expiry, invitation roles, revocation, and isolated inboxes. They **do not prove internet email delivery** or test your application's selectors and authorization model.
+
+## Install from this checkout
+
+The package is named `@everydaydevopsio/hail`. A checkout can be packed locally whether or not that version has been published.
+Its JavaScript entry points are ESM; use an ESM consumer project (`"type": "module"`) for Playwright TypeScript specs.
+
+```bash
+npm ci
+npm pack
+# In your application repository, use the actual tarball path:
+npm install --save-dev /path/to/hail/everydaydevopsio-hail-0.1.0.tgz @playwright/test
+npx hail --help
+```
+
+Terraform templates and the worker are included in the tarball. Original source snapshots, test output, state files, and email contents are not.
+
+## Set up a dedicated email test domain
+
+Start with a fresh subdomain such as `email-test.example.com`. Never point the company email domain at Hail. Use an existing authoritative DNS zone; changing registrar or nameservers is not required.
+
+For Cloudflare, configure a zone-scoped `CLOUDFLARE_API_TOKEN` in your shell. The token needs DNS editing and permission to read the selected zone. AWS credentials use the normal SDK/provider chain.
+
+```bash
+npx hail init \
+  --dns cloudflare \
+  --domain email-test.example.com \
+  --zone-name example.com \
+  --zone-id YOUR_EXISTING_CLOUDFLARE_ZONE_ID \
+  --region us-east-1 \
+  --name myapp-hail \
+  --existing-rule-set shared-inbound \
+  --out infra/hail
+```
+
+Choose `--dns route53 --zone-id YOUR_PUBLIC_HOSTED_ZONE_ID` for Route53. Choose `--dns manual` and omit `--zone-id` for another provider.
+
+For an AWS account/region with **no active receipt rule set**, replace `--existing-rule-set shared-inbound` with `--activate-new-rule-set`. The CLI checks the active set and refuses to replace it. The Terraform module defaults to no activation; direct Terraform use still requires you to review current AWS/DNS state and the plan.
+
+`init` performs read-only AWS/DNS checks, then generates ordinary Terraform files. By default, the receiver module source uses the Git tag matching the installed package version (for example `v0.1.0` for Hail `0.1.0`); that tag must exist in the repository before Terraform can download it. Use `--local-modules` to copy the bundled module instead, such as when installing from an unreleased checkout. `--out` selects the output directory and `--file` selects the Terraform filename inside it (default `main.tf`). Existing directories are allowed, but existing generated files are never overwritten. An existing `.gitignore` is preserved; ensure it excludes Terraform variables, state, and plans. `init` never runs `terraform apply` or creates sender identities. It refuses domains with existing MX records. Existing receiver users should attach their configuration rather than rerun initialization.
+
+Edit `infra/hail/terraform.tfvars.json` to configure `reader_principal_arns`, or attach the exported `reader_policy_arn` to your existing developer/CI role. Review your infrastructure naming, region, retention, and state backend before applying.
+
+```bash
+terraform -chdir=infra/hail init
+terraform -chdir=infra/hail plan
+terraform -chdir=infra/hail apply
+npx hail configure --terraform-dir infra/hail
+npx hail doctor
+```
+
+Manual DNS mode prints the required MX and TXT records with `terraform output dns_records`. Publish them before running `doctor`. Managed modes wait for SES identity verification, which can take time after DNS changes. DNS tokens and AWS credentials never belong in tfvars or Git.
+
+`doctor` checks resolved MX, SES identity, the active domain/bucket receipt rule, and S3 listing access. It does **not** verify all preceding SES rules, queue health, raw-object read permissions, or actual delivery. Use the live test gate and check the DLQ before calling a deployment validated.
+
+## Write a Playwright test
+
+Set Playwright's `use.baseURL` to your application. Replace selectors and expected states with your app's actual contract.
+
+```typescript
+import { test, expect, visitAuthLink } from "@everydaydevopsio/hail/playwright";
+
+test("sign in using the delivered magic link", async ({ page, inbox }) => {
+  test.setTimeout(90_000);
+  await page.goto("/login");
+  const after = await inbox.checkpoint();
+  await page.getByLabel("Email").fill(inbox.address);
+  await page.getByRole("button", { name: /send magic link/i }).click();
+
+  const email = await inbox.waitForEmail({
+    after,
+    subject: /sign in/i,
+    timeoutMs: 60_000,
+  });
+  const origin = new URL(page.url()).origin;
+  await visitAuthLink(
+    page,
+    email.getLink({ text: /sign in/i, allowedOrigins: [origin] }),
+  );
+  await expect(page.getByTestId("current-user-email")).toHaveText(
+    inbox.address,
+  );
+});
+```
+
+Continue magic-link flows in the requesting browser when your app binds a request nonce to a cookie. Invitation recipes must use separate administrator and invitee contexts. Seed authorized test users through your test setup when the application disallows arbitrary signup; do not relax production authentication.
+
+### Core API
+
+```typescript
+import { Hail, loadConfig } from "@everydaydevopsio/hail";
+const hail = new Hail(await loadConfig());
+const inbox = hail.createInbox("login");
+const after = await inbox.checkpoint();
+// Trigger your application's send here.
+const email = await inbox.waitForEmail({ after, subject: /sign in/i });
+const code = email.getCode(); // Only for a message containing a single distinct code.
+```
+
+`waitForEmail` and `waitForEmails(count, options)` support `after`, `subject`, `from`, `timeoutMs`, `pollIntervalMs`, `signal`, and `consume`. String filters match exactly; regex filters match patterns. Messages are consumed within an Inbox instance by default. Use a separate inbox for concurrent actors; concurrent waits on the same Inbox are not a transactional queue.
+
+`inbox.expectNoEmail({ forMs: 2000, subject: /unexpected/i })` asserts that no matching message was observed during that window, not that none will ever arrive.
+
+`email.getLink({ allowedOrigins, text?, pathname? })` requires one distinct matching HTTP(S) URL and preserves signed URL encoding after normal HTML decoding. It does not follow redirects, rewrite tracking links, or change production URLs to localhost. Only allow origins you trust; redirect destinations remain the application's responsibility.
+
+`email.text`, `email.html`, `email.attachments`, `email.receivedAt`, and `email.delivery` are available for explicit assertions. Received timestamps come from SES metadata, not the sender-controlled Date header. New storage supports up to 16 MiB per message; oversize messages fail ingestion into the DLQ.
+
+## Attach to an existing receiver
+
+For a Hail receiver, obtain the `hail_config` Terraform output and reader-role access. A developer does not need infrastructure or DNS write permission to run tests.
+
+For the original recipient-folder layout, use this configuration:
+
+```json
+{
+  "schemaVersion": 1,
+  "domain": "email-test.example.com",
+  "bucketName": "your-existing-ses-bucket",
+  "region": "us-east-1",
+  "layout": "legacy"
+}
+```
+
+An optional `roleArn` uses refreshable assumed-role credentials. Legacy layout uses `<recipient>/<message-id>.eml` and S3 LastModified timestamps; it lacks the trusted SES receipt metadata of `indexed-v1`. Prefer fresh per-test addresses rather than reused legacy mailboxes. Importing source code does not migrate any deployed Terraform state or activate a new receiver.
+
+## Live delivery gate
+
+For a disposable Cloudflare receiver and the complete local/live/cleanup sequence, use the [one-command live runner](docs/LIVE-RUNNER.md):
+
+```bash
+npm run test:live:full -- --profile hail-bootstrap --domain example.com --region us-east-1 --execute
+```
+
+This explicitly provisions resources and sends synthetic email. Select the approved profile/domain and install prerequisites first; it is never invoked by ordinary PR CI.
+
+See [live verification](docs/LIVE-VERIFICATION.md). The live suite uses the same browser scenarios, but sends email through an explicitly configured SES sender and reads the actual receiver. It requires a deployed receiver, verified sender, appropriately restricted AWS credentials, and explicit invocation. The existing `npm run test:live` browser suite requires that receiver to be provisioned already; `test:live:full` above manages its own disposable receiver.
+
+SES receipt proves delivery to this SES inbox, not Gmail/Outlook inbox placement or native email-client rendering. A live run against the demo application is not a substitute for running the generated recipe against your own application.
+
+## Security and scope
+
+Read [security and operations](docs/SECURITY.md) before granting access or enabling live CI. Raw MIME and authentication links are secrets. Hail does not auto-attach them; Playwright navigation failures and third-party logging may still include URLs. Disable auth traces/screenshots by default and keep live CI output restricted.
+
+A hosted inbox viewer, local SMTP server, provider-specific delivery event adapters, full diagnostic queue inspection, and an MCP server are future work, not features of this PR.
+
+## Provenance
+
+Hail evolves [ses-email-client](https://github.com/markcallen/ses-email-client) and [ses-receiving-terraform](https://github.com/markcallen/ses-receiving-terraform). Complete unchanged snapshots are retained under `upstream/`; their historical docs are not the supported Hail setup guide. See [the exact imported commits](docs/UPSTREAM.md).
+
+## Contributor checks
+
+Run `make deps`, then `make setup`. Source `.dev-tools/activate` or run `make shell`; run `make check` for local validation. Setup reports missing tools and directs you to `make deps`. See the [documentation index](docs/README.md) and [development checks](docs/DEVELOPMENT.md).
+
+## License
+
+ISC — see [LICENSE](LICENSE).

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+import { parseArgs, promisify } from "node:util";
+import { execFile } from "node:child_process";
+import { writeFile } from "node:fs/promises";
+import { resolveMx } from "node:dns/promises";
+import { SESClient, DescribeActiveReceiptRuleSetCommand, GetIdentityVerificationAttributesCommand, } from "@aws-sdk/client-ses";
+import { loadConfig, parseConfig } from "./config.js";
+import { S3MailStore, awsCredentials } from "./store.js";
+import { scaffold, validateInit } from "./setup.js";
+const execute = promisify(execFile);
+const help = `Hail: Send. Receive. Verify.\n\nCommands:\n  hail init --dns cloudflare|route53|manual --domain email-test.example.com\n    --zone-name example.com [--zone-id ID] --region us-east-1\n    (--existing-rule-set NAME | --activate-new-rule-set) [--out infra/hail] [--file main.tf] [--local-modules]\n  hail configure --terraform-dir infra/hail [--out hail.config.json]\n  hail doctor [--config hail.config.json]\n\ninit generates Terraform pinned to the installed Hail version unless --local-modules is set. It never runs terraform apply.\nconfigure reads Terraform outputs; doctor never sends email.\n`;
+async function activeRules(region, config) {
+    const client = new SESClient({
+        region,
+        credentials: config ? awsCredentials(config) : undefined,
+    });
+    try {
+        return await client.send(new DescribeActiveReceiptRuleSetCommand({}), {
+            abortSignal: AbortSignal.timeout(20_000),
+        });
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            ["RuleSetDoesNotExist", "RuleSetDoesNotExistException"].includes(error.name))
+            return { $metadata: {} };
+        throw error;
+    }
+}
+async function checkNewDomain(domain) {
+    try {
+        if ((await resolveMx(domain)).length)
+            throw new Error("This domain already has MX records. Use a fresh test subdomain or explicitly migrate/import the existing records outside init.");
+    }
+    catch (error) {
+        if (["ENODATA", "ENOTFOUND"].includes(error.code ?? ""))
+            return;
+        throw error;
+    }
+}
+async function doctor(config) {
+    const results = [];
+    const check = async (name, operation) => {
+        try {
+            await operation();
+            results.push({ check: name, ok: true, detail: "Passed" });
+        }
+        catch (error) {
+            results.push({
+                check: name,
+                ok: false,
+                detail: error instanceof Error && error.name === "Error"
+                    ? error.message
+                    : `Check failed (${error instanceof Error ? error.name : "unknown error"}).`,
+            });
+        }
+    };
+    await check("dns-mx", async () => {
+        const expected = `inbound-smtp.${config.region}.amazonaws.com`;
+        const records = await resolveMx(config.domain);
+        if (!records.length ||
+            records.some((record) => record.exchange.toLowerCase().replace(/\.$/, "") !== expected))
+            throw new Error("MX does not exclusively target this SES receiving region.");
+    });
+    await check("ses-identity", async () => {
+        const ses = new SESClient({
+            region: config.region,
+            credentials: awsCredentials(config),
+        });
+        const result = await ses.send(new GetIdentityVerificationAttributesCommand({
+            Identities: [config.domain],
+        }), { abortSignal: AbortSignal.timeout(20_000) });
+        if (result.VerificationAttributes?.[config.domain]?.VerificationStatus !==
+            "Success")
+            throw new Error("SES receiving identity is not verified yet.");
+    });
+    await check("active-receipt-rule", async () => {
+        const active = await activeRules(config.region, config);
+        if (config.ruleSetName && active.Metadata?.Name !== config.ruleSetName)
+            throw new Error("Expected SES receipt rule set is not active.");
+        const found = active.Rules?.some((rule) => rule.Enabled &&
+            (!config.ruleName || rule.Name === config.ruleName) &&
+            rule.Recipients?.includes(config.domain) &&
+            rule.Actions?.some((action) => action.S3Action?.BucketName === config.bucketName));
+        if (!found)
+            throw new Error("No enabled receipt rule routes this domain into the configured bucket.");
+    });
+    await check("s3-reader", async () => {
+        const store = new S3MailStore(config);
+        await store.list(`hail-doctor@${config.domain}`, AbortSignal.timeout(20_000));
+    });
+    console.log(JSON.stringify({
+        results,
+        deliveryTested: false,
+        note: "Read-only checks only. Queue health, object reads, and actual email delivery require separate validation; run the opt-in live suite.",
+    }, null, 2));
+    if (results.some((result) => !result.ok))
+        process.exitCode = 1;
+}
+async function main() {
+    const [command, ...args] = process.argv.slice(2);
+    if (!command || command === "--help" || command === "help") {
+        console.log(help);
+        return;
+    }
+    const { values } = parseArgs({
+        args,
+        options: {
+            dns: { type: "string" },
+            domain: { type: "string" },
+            "zone-name": { type: "string" },
+            "zone-id": { type: "string" },
+            region: { type: "string" },
+            name: { type: "string" },
+            out: { type: "string" },
+            file: { type: "string" },
+            "local-modules": { type: "boolean" },
+            "existing-rule-set": { type: "string" },
+            "activate-new-rule-set": { type: "boolean" },
+            "terraform-dir": { type: "string" },
+            config: { type: "string" },
+        },
+    });
+    if (command === "init") {
+        const options = validateInit({
+            dns: (values.dns ?? "manual"),
+            domain: values.domain ?? "",
+            zoneName: values["zone-name"] ?? "",
+            zoneId: values["zone-id"],
+            region: values.region ?? "us-east-1",
+            name: values.name ?? "hail",
+            out: values.out ?? "infra/hail",
+            file: values.file,
+            localModules: values["local-modules"],
+            existingRuleSet: values["existing-rule-set"],
+            activateNewRuleSet: values["activate-new-rule-set"],
+        });
+        await checkNewDomain(options.domain);
+        const active = await activeRules(options.region);
+        if (options.activateNewRuleSet && active.Metadata?.Name)
+            throw new Error("An SES rule set is already active. Use --existing-rule-set instead; Hail will not replace it.");
+        if (options.existingRuleSet &&
+            active.Metadata?.Name !== options.existingRuleSet)
+            throw new Error("The requested existing SES rule set is not active in this region.");
+        const destination = await scaffold(options);
+        console.log(`Created ${destination}. Review the files, configure reader access, then run terraform init, plan, and apply there. Copy example.spec.ts into your tests and adapt its selectors. No cloud resources were changed.`);
+    }
+    else if (command === "configure") {
+        if (!values["terraform-dir"])
+            throw new Error("configure requires --terraform-dir.");
+        const { stdout } = await execute("terraform", [`-chdir=${values["terraform-dir"]}`, "output", "-json", "hail_config"], { timeout: 30_000, maxBuffer: 1024 * 1024 });
+        const config = parseConfig(JSON.parse(stdout));
+        const destination = values.out ?? "hail.config.json";
+        await writeFile(destination, JSON.stringify(config, null, 2) + "\n", {
+            mode: 0o600,
+            flag: "wx",
+        });
+        console.log(`Wrote ${destination}. Existing files are never overwritten.`);
+    }
+    else if (command === "doctor") {
+        await doctor(await loadConfig(values.config));
+    }
+    else
+        throw new Error("Unknown command. Run hail --help.");
+}
+main().catch((error) => {
+    const known = error instanceof Error && error.name === "Error";
+    console.error(known
+        ? error.message
+        : `Hail failed (${error instanceof Error ? error.name : "unknown error"}). Check configuration and credentials.`);
+    process.exitCode = 1;
+});

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+export interface HailConfig {
+    schemaVersion: 1;
+    domain: string;
+    bucketName: string;
+    region: string;
+    layout: "indexed-v1" | "legacy";
+    roleArn?: string;
+    ruleSetName?: string;
+    ruleName?: string;
+}
+export declare function normalizeDomain(value: string): string;
+export declare function normalizeAddress(value: string): string;
+export declare function parseConfig(value: unknown): HailConfig;
+export declare function loadConfig(path?: string): Promise<HailConfig>;

package/dist/config.js

@@ -0,0 +1,56 @@
+import { readFile } from "node:fs/promises";
+export function normalizeDomain(value) {
+    const domain = value.toLowerCase().replace(/\.$/, "");
+    if (domain.length > 253 ||
+        !/^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/.test(domain)) {
+        throw new Error("Use a valid ASCII DNS domain.");
+    }
+    return domain;
+}
+export function normalizeAddress(value) {
+    const address = value.toLowerCase();
+    const parts = address.split("@");
+    if (parts.length !== 2 || !/^[a-z0-9][a-z0-9._+-]{0,63}$/.test(parts[0])) {
+        throw new Error("Use a simple test mailbox address with a local part of at most 64 characters.");
+    }
+    return `${parts[0]}@${normalizeDomain(parts[1])}`;
+}
+export function parseConfig(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("Hail configuration must be an object.");
+    const data = value;
+    if (data.schemaVersion !== 1)
+        throw new Error("Unsupported Hail configuration schemaVersion.");
+    if (typeof data.domain !== "string" ||
+        typeof data.bucketName !== "string" ||
+        typeof data.region !== "string") {
+        throw new Error("Hail configuration requires domain, bucketName, and region.");
+    }
+    if (!/^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/.test(data.bucketName))
+        throw new Error("Invalid S3 bucket name.");
+    if (!/^[a-z]{2}(?:-gov)?-[a-z]+-\d+$/.test(data.region))
+        throw new Error("Invalid AWS region.");
+    if (data.layout !== "indexed-v1" && data.layout !== "legacy")
+        throw new Error("Unsupported mailbox storage layout.");
+    const result = {
+        schemaVersion: 1,
+        domain: normalizeDomain(data.domain),
+        bucketName: data.bucketName,
+        region: data.region,
+        layout: data.layout,
+    };
+    for (const name of ["roleArn", "ruleSetName", "ruleName"]) {
+        if (data[name] != null) {
+            if (typeof data[name] !== "string" || !data[name])
+                throw new Error(`Invalid ${name}.`);
+            result[name] = data[name];
+        }
+    }
+    if (result.roleArn &&
+        !/^arn:aws(?:-us-gov|-cn)?:iam::\d{12}:role\/.+$/.test(result.roleArn))
+        throw new Error("Invalid reader role ARN.");
+    return result;
+}
+export async function loadConfig(path = process.env.HAIL_CONFIG ?? "hail.config.json") {
+    return parseConfig(JSON.parse(await readFile(path, "utf8")));
+}

package/dist/email.d.ts

@@ -0,0 +1,36 @@
+import { inspect } from "node:util";
+import type { StoredMail } from "./store.js";
+export type Pattern = string | RegExp;
+export declare function matches(value: string, pattern?: Pattern): boolean;
+export interface LinkQuery {
+    allowedOrigins: string[];
+    text?: Pattern;
+    pathname?: Pattern;
+}
+export declare class EmailMessage {
+    private readonly parsed;
+    private readonly stored;
+    private constructor();
+    static parse(stored: StoredMail): Promise<EmailMessage>;
+    get id(): string;
+    get recipient(): string;
+    get receivedAt(): Date;
+    get subject(): string;
+    get from(): string;
+    get text(): string;
+    get html(): string;
+    get attachments(): import("mailparser").Attachment[];
+    get delivery(): Record<string, string>;
+    getLink(query: LinkQuery): string;
+    getCode(pattern?: RegExp): string;
+    toJSON(): {
+        id: string;
+        receivedAt: Date;
+        attachmentCount: number;
+    };
+    [inspect.custom](): {
+        id: string;
+        receivedAt: Date;
+        attachmentCount: number;
+    };
+}

package/dist/email.js

@@ -0,0 +1,119 @@
+import { inspect } from "node:util";
+import { simpleParser } from "mailparser";
+import { load } from "cheerio";
+export function matches(value, pattern) {
+    if (pattern === undefined)
+        return true;
+    return typeof pattern === "string"
+        ? value === pattern
+        : new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, "")).test(value);
+}
+export class EmailMessage {
+    parsed;
+    stored;
+    constructor(parsed, stored) {
+        this.parsed = parsed;
+        this.stored = stored;
+    }
+    static async parse(stored) {
+        const raw = typeof stored.raw === "string"
+            ? Buffer.from(stored.raw)
+            : Buffer.from(stored.raw);
+        return new EmailMessage(await simpleParser(raw, { skipHtmlToText: true, skipTextToHtml: true }), stored);
+    }
+    get id() {
+        return this.stored.id;
+    }
+    get recipient() {
+        return this.stored.recipient;
+    }
+    get receivedAt() {
+        return this.stored.receivedAt;
+    }
+    get subject() {
+        return this.parsed.subject ?? "";
+    }
+    get from() {
+        return (this.parsed.from?.value.map((value) => value.address ?? "").join(", ") ??
+            "");
+    }
+    get text() {
+        return this.parsed.text ?? "";
+    }
+    get html() {
+        return this.parsed.html || "";
+    }
+    get attachments() {
+        return this.parsed.attachments;
+    }
+    get delivery() {
+        return this.stored.delivery ?? {};
+    }
+    getLink(query) {
+        if (!query.allowedOrigins.length)
+            throw new Error("At least one allowed link origin is required.");
+        const allowed = new Set(query.allowedOrigins.map((value) => {
+            const url = new URL(value);
+            if (!["http:", "https:"].includes(url.protocol) ||
+                url.username ||
+                url.password)
+                throw new Error("Invalid allowed origin.");
+            return url.origin;
+        }));
+        const candidates = [];
+        if (this.html) {
+            const document = load(this.html);
+            document("a[href]").each((_index, element) => {
+                const href = document(element).attr("href");
+                if (href)
+                    candidates.push({
+                        href,
+                        text: document(element).text().replace(/\s+/g, " ").trim(),
+                    });
+            });
+        }
+        if (query.text === undefined) {
+            for (const href of this.text.match(/https?:\/\/[^\s<>"']+/g) ?? [])
+                candidates.push({ href, text: "" });
+        }
+        const links = new Set();
+        for (const candidate of candidates) {
+            let url;
+            try {
+                url = new URL(candidate.href);
+            }
+            catch {
+                continue;
+            }
+            if (!["http:", "https:"].includes(url.protocol) ||
+                url.username ||
+                url.password ||
+                !allowed.has(url.origin))
+                continue;
+            if (matches(candidate.text, query.text) &&
+                matches(url.pathname, query.pathname))
+                links.add(candidate.href);
+        }
+        if (links.size !== 1)
+            throw new Error(`Expected one matching safe link; found ${links.size}. Link values are redacted.`);
+        return [...links][0];
+    }
+    getCode(pattern = /\b(\d{6})\b/g) {
+        const expression = new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, "") + "g");
+        const content = this.text || load(this.html).text();
+        const codes = new Set([...content.matchAll(expression)].map((match) => match[1] ?? match[0]));
+        if (codes.size !== 1)
+            throw new Error(`Expected one distinct code; found ${codes.size}. Codes are redacted.`);
+        return [...codes][0];
+    }
+    toJSON() {
+        return {
+            id: this.id,
+            receivedAt: this.receivedAt,
+            attachmentCount: this.attachments.length,
+        };
+    }
+    [inspect.custom]() {
+        return this.toJSON();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import { type HailConfig } from "./config.js";
+import { EmailMessage, type Pattern } from "./email.js";
+import { type MailStore } from "./store.js";
+export * from "./config.js";
+export * from "./email.js";
+export * from "./store.js";
+export interface Checkpoint {
+    readonly startedAt: Date;
+    readonly seen: ReadonlySet<string>;
+}
+export interface WaitOptions {
+    after?: Checkpoint | Date;
+    subject?: Pattern;
+    from?: Pattern;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    signal?: AbortSignal;
+    consume?: boolean;
+}
+export declare class EmailTimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+export declare class Inbox {
+    private readonly store;
+    private readonly consumed;
+    private readonly cache;
+    readonly address: string;
+    constructor(address: string, store: MailStore);
+    checkpoint(): Promise<Checkpoint>;
+    waitForEmail(options?: WaitOptions): Promise<EmailMessage>;
+    waitForEmails(count: number, options?: WaitOptions): Promise<EmailMessage[]>;
+    expectNoEmail(options: Omit<WaitOptions, "timeoutMs" | "consume"> & {
+        forMs: number;
+    }): Promise<void>;
+}
+export declare class Hail {
+    readonly config: HailConfig;
+    readonly store: MailStore;
+    constructor(config: HailConfig, store?: MailStore);
+    createInbox(label?: string): Inbox;
+    inbox(address: string): Inbox;
+}