@benclmnt/postmock 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bennett Clement
+
+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

@@ -0,0 +1,251 @@
+# postmock
+
+A mock Postmark server in TypeScript, for testing code that sends email through Postmark.
+Real, unmodified clients talk to it: every official Postmark SDK, and plain SMTP clients.
+Tests then read what was sent, seed suppressions and bounces, inject faults, and trigger webhooks.
+
+> Not affiliated with or endorsed by Postmark or ActiveCampaign. "Postmark" is their trademark.
+
+## Status
+
+W0 to W3 are built: REST and account APIs, SMTP, webhooks, the control API, a conformance runner for every official SDK, the npm package, the Docker image and CI.
+[`docs/11`](docs/11-build-plan.md) is the build plan; [`ARCHITECTURE.md`](ARCHITECTURE.md) marks what is built.
+The docs record Postmark's behavior from its public docs, its Swagger specs, and the official SDKs.
+One behavior is CAPTURED from real Postmark so far: the sender check ([`docs/03`](docs/03-sending.md) §3.4). [`docs/10`](docs/10-live-capture-plan.md) plans the rest.
+
+## Run
+
+| Way | Command |
+| --- | --- |
+| npm package (`npm pack` builds it) | `npx @benclmnt/postmock --seed conformance` |
+| From a checkout | `pnpm install`, then `pnpm start --seed conformance` |
+| Docker image | `docker build -t postmock .`, then `docker run --rm -p 127.0.0.1:8080:8080 -p 127.0.0.1:8025:8025 -p 127.0.0.1:2525:2525 postmock --seed conformance` |
+| Compose, with the Postmark host names | Option B below |
+
+The control API and SMTP have no real authentication: publish their ports on `127.0.0.1` only.
+
+Startup prints one `name=url` per listener:
+
+```text
+postmock api=http://127.0.0.1:8080 smtp=smtp://127.0.0.1:53648 control=http://127.0.0.1:8025 seed=conformance
+```
+
+Every setting is an env key and a flag (`postmock --help`). A flag wins over the env:
+
+| Flag | Env | Default | Effect |
+| --- | --- | --- | --- |
+| `--host` | `POSTMOCK_HOST` | `127.0.0.1` (image: `0.0.0.0`) | Bind address of every listener |
+| `--api-port` | `POSTMOCK_API_PORT` | `8080` | REST over plain http |
+| `--control-port` | `POSTMOCK_CONTROL_PORT` | `8025` | Control API |
+| `--seed` | `POSTMOCK_SEED` | `empty` | Seed applied at start: `empty`, `conformance` ([`CONTROL-API.md`](CONTROL-API.md#seeds)) |
+| `--https-port`, `--https-tls-key`, `--https-tls-cert` | `POSTMOCK_HTTPS_PORT`, `POSTMOCK_HTTPS_TLS_KEY`, `POSTMOCK_HTTPS_TLS_CERT` | off | REST over TLS; PEM files; all three or none |
+| `--smtp-ports` | `POSTMOCK_SMTP_PORTS` | `0`, a free port (image: `2525`) | Comma list; every port serves the same SMTP endpoint |
+| `--smtp-tls-key`, `--smtp-tls-cert` | `POSTMOCK_SMTP_TLS_KEY`, `POSTMOCK_SMTP_TLS_CERT` | off | PEM files; with both, SMTP offers STARTTLS |
+| `--webhooks-allow-hosts` | `POSTMOCK_WEBHOOKS_ALLOW_HOSTS` | none | Webhook targets other than loopback; `*` for all |
+
+Port `0` picks a free port.
+A bad value stops startup: an unknown flag, an empty value, a port that is not a decimal number, or a PEM file that does not exist.
+
+## Reach postmock from a client
+
+A client reaches postmock with no code change ([`docs/01`](docs/01-client-reachability.md) §3.3).
+Use a token that only postmock knows, such as the `conformance` seed token `postmock-server-token`.
+A misrouted request then gets 401 from real Postmark and sends nothing.
+
+### Option A: base-URL option
+
+Set the client's own host option to postmock's REST listener, here `127.0.0.1:8080` over plain http.
+
+| SDK | Option |
+| --- | --- |
+| postmark.js | `new ServerClient(token, { requestHost: "127.0.0.1:8080", useHttps: false })` |
+| postmark-cli | `--request-host 127.0.0.1:8443` on `templates pull`, `templates push`, `email template`, `email raw` and `servers list`. The CLI keeps https: start postmock with `--https-port 8443` and a certificate from `tools/test-ca.sh`, and set `NODE_EXTRA_CA_CERTS` to its `ca.pem`. |
+| postmark-python | `ServerClient(token, base_url="http://127.0.0.1:8080")` |
+| postmark-dotnet | `new PostmarkClient(token, "http://127.0.0.1:8080")` |
+| postmark-php | `PostmarkClientBase::$BASE_URL = "http://127.0.0.1:8080"` |
+| postmark-gem, postmark-rails | `host: "127.0.0.1", port: 8080, secure: false` (rails: `config.action_mailer.postmark_settings`) |
+| postmark-java | `Postmark.getApiClient(token, false, "127.0.0.1:8080")`: host and port, then the scheme from the `false` |
+| postmark-mcp | none: use option B |
+
+Cites and per-SDK transport details: [`docs/01`](docs/01-client-reachability.md) §2.1, [`docs/08`](docs/08-sdk-client-matrix.md).
+
+### Sender addresses
+
+As on Postmark, a send `From` must be on a DKIM-verified domain or be a confirmed sender signature.
+A `From` that no account domain or signature matches gets HTTP 422 with ErrorCode 400 ([`docs/03`](docs/03-sending.md) §3.4, CAPTURED).
+Other states that no capture covers answer 501 on REST and a 502 reply on SMTP: an unverified domain, a subdomain, an unconfirmed signature.
+SMTP accepts every message and records problems as bounces (`refs/user-guide_send-email-with-smtp.md:56`); the `SMTPApiError` bounce with ErrorCode 400 is INFERRED.
+The `POSTMARK_API_TEST` token skips this check.
+
+| Need | How |
+| --- | --- |
+| Send from `example.com` | The `conformance` seed verifies `example.com` and `your-verified-domain.com` |
+| Send from another domain | `POST /domains` with the account token, then `POST /control/domains/<ID>/verify` with `{"dkim": true}` ([`CONTROL-API.md`](CONTROL-API.md)) |
+| Send from one address | `POST /senders` with the account token, then `POST /control/senders/<ID>/confirm` |
+
+### Option B: DNS and a test CA, with Compose
+
+[`compose.yaml`](compose.yaml) runs postmock on the internal network `sandbox` under the names `api.postmarkapp.com`, `smtp.postmarkapp.com` and `smtp-broadcasts.postmarkapp.com`.
+postmock serves REST over TLS on 443 and SMTP with STARTTLS on 25, 587 and 2525.
+
+| Volume | Content | Mounted by |
+| --- | --- | --- |
+| `ca` | `ca.pem` only | clients |
+| `tls` | `cert.pem`, `key.pem` | postmock only |
+
+The `ca` service ([`tools/compose-ca.sh`](tools/compose-ca.sh)) writes both with [`tools/test-ca.sh`](tools/test-ca.sh).
+It deletes the CA key after signing: that is the protection, as nobody can sign another certificate with this CA.
+Name constraints on the CA (`postmarkapp.com`, `localhost`, `127.0.0.1`) add a limit only for clients that enforce them on a trust anchor; Java does not.
+The volumes keep the CA across runs. A missing file, a key that does not match the certificate, or a certificate that fails to verify or expires within a day makes a new one; restart postmock after that (`docker compose restart postmock`).
+
+Run the example application:
+
+```bash
+docker compose run --rm --build example-node
+docker compose --profile example down -v
+```
+
+[`examples/node/default-hosts.ts`](examples/node/default-hosts.ts) sends with postmark.js and nodemailer, and neither names postmock.
+
+To test your own application, include this `compose.yaml` from your Compose file (Compose 2.20 or later).
+[`examples/compose/compose.yaml`](examples/compose/compose.yaml) is a complete file:
+
+```yaml
+include:
+  - path:
+      - path/to/postmock/compose.yaml
+      - postmock.override.yaml   # your settings for the postmock service
+services:
+  app:
+    build: .
+    depends_on:
+      postmock: { condition: service_healthy }
+    environment:
+      NODE_EXTRA_CA_CERTS: /ca/ca.pem
+      POSTMARK_SERVER_TOKEN: postmock-server-token
+    volumes: [ca:/ca:ro]
+    networks: [sandbox]
+```
+
+| Need | Setting |
+| --- | --- |
+| Trust the CA | Node: `NODE_EXTRA_CA_CERTS=/ca/ca.pem`; Java: import `ca.pem` into a trust store; others: the runtime's trust store |
+| Read what was sent | `http://postmock:8025/control/messages` |
+| Receive webhooks | `POSTMOCK_WEBHOOKS_ALLOW_HOSTS: app` in the override file ([`examples/compose/postmock.override.yaml`](examples/compose/postmock.override.yaml)) |
+
+A service of your file cannot redefine an included service, so postmock settings go in the override file.
+
+No route out holds only while the application joins `sandbox` and no other network.
+With a second network, `api.postmarkapp.com` resolves to real Postmark whenever postmock is down.
+Use a token that only postmock knows in every case: a misrouted request then gets 401 and sends nothing.
+
+Why DNS and not a hosts file: nodemailer queries DNS before it reads the hosts file ([`docs/01`](docs/01-client-reachability.md) §2.2).
+
+### SMTP
+
+| Setting | Value |
+| --- | --- |
+| Host | postmock's host, or `smtp.postmarkapp.com` with option B |
+| Port | The `smtp` URL in the startup line; `25`, `587` or `2525` with option B |
+| User and password | A server API token for both, or an SMTP token from `POST /control/smtp/tokens` |
+| TLS | STARTTLS when `POSTMOCK_SMTP_TLS_KEY` and `POSTMOCK_SMTP_TLS_CERT` are set |
+| Stream | Header `X-PM-Message-Stream` |
+
+[`examples/node/smtp-send.ts`](examples/node/smtp-send.ts) sends with nodemailer through option A.
+Details: [`docs/07`](docs/07-smtp-sandbox-limits.md).
+
+## Control API
+
+Tests drive postmock through the control API on its own port: reset, seeds, the clock, faults, sent messages, bounces, opens, clicks, inbound mail and webhook attempts.
+Every call maps to something that can happen on real Postmark.
+Reference: [`CONTROL-API.md`](CONTROL-API.md).
+
+## SDK compatibility
+
+Each official SDK's own live integration suite runs unmodified against postmock ([`TESTING.md`](TESTING.md)).
+`pnpm compat-table` writes this table from `conformance/results/*.json`.
+`not run` means the suite has no results yet. postmark-cli, postmark-java and postmark-php run in Docker containers.
+CI runs every suite, writes the full table to its job summary, and fails when a row this table lists as run differs from its results ([`.github/workflows/ci.yml`](.github/workflows/ci.yml)).
+A `not run` row enters this table only after a real run.
+
+<!-- compat-table:start -->
+| SDK | SDK commit | Pass | Fail | Skip | Baseline |
+| --- | --- | --- | --- | --- | --- |
+| postmark-cli | c88a59d | 31/31 | 0 | 0 | 31 |
+| postmark-dotnet | b4249c5 | 103/111 | 0 | 8 | 103 |
+| postmark-gem | a50ff39 | 41/41 | 0 | 0 | 41 |
+| postmark-java | c6c5eb6 | 100/100 | 0 | 0 | 100 |
+| postmark-mcp | 63ef055 | 50/50 | 0 | 0 | 50 |
+| postmark-php | ad4b80e | 87/87 | 0 | 0 | 87 |
+| postmark-python | 620d659 | 72/174 | 0 | 102 | 72 |
+| postmark-rails | f9e4acc | 7/7 | 0 | 0 | 7 |
+| postmark.js | f955212 | 79/80 | 0 | 1 | 79 |
+<!-- compat-table:end -->
+
+## Why
+
+Postmark has no local test server.
+Its sandbox mode is hosted: it cannot inject faults or fire events on demand, and sends count toward the plan.
+Existing open-source mocks answer `POST /email` only, with no errors, suppressions, webhooks or SMTP (`docs/09`).
+
+## Scope
+
+| Surface | Doc |
+| --- | --- |
+| Transport, tokens, error envelope, ErrorCodes | `docs/02` |
+| Sending: single, batch, templates, bulk | `docs/03` |
+| Bounces, suppressions, message streams, data removals | `docs/04` |
+| Webhooks: config API, every RecordType, retries, inbound | `docs/05` |
+| Messages, stats, templates, server, servers, domains, sender signatures | `docs/06` |
+| SMTP, sandbox mode, limits | `docs/07` |
+
+## Top traps
+
+| Trap | Doc |
+| --- | --- |
+| The 406 `Message` must match an SDK regex, or clients get an empty inactive-recipient list | `docs/03` |
+| postmark.js has no proxy support and a default host; apps that never set a host need DNS + a test CA | `docs/01` |
+| SMTP accepts every message; problems become `SMTPApiError` bounces, not SMTP rejects | `docs/07` |
+| Every success is HTTP 200 with JSON; several SDKs treat 201/204 as errors | `docs/08` |
+| SDKs disagree on path case, query key case and boolean encoding; the server must accept all of them | `docs/08` |
+
+## Layout
+
+| Path | Content |
+| --- | --- |
+| `AGENTS.md` | Rules for working in this repo (`CLAUDE.md` links to it) |
+| `ARCHITECTURE.md` | Listeners, modules, request flow, shared contracts, traps |
+| `CONTROL-API.md` | Test-facing control API: principle, shape, endpoints, seeds |
+| `TESTING.md` | Gates, conformance runners, results and baseline, test traps |
+| `flake.nix` | Dev shell with every toolchain the SDK suites need |
+| `Dockerfile`, `compose.yaml` | The image, and the option B sandbox |
+| `.github/workflows/` | CI |
+| `examples/node/` | Applications that send through Postmark with no postmock code |
+| `examples/compose/` | An application's Compose file that includes postmock's |
+| `src/` | The server (`ARCHITECTURE.md` "Modules") |
+| `seeds/` | Named seeds: `empty`, `conformance` |
+| `conformance/` | One runner per SDK suite, baselines, skip lists |
+| `docs/01-client-reachability.md` | How clients pick the host; routing an unmodified app to the mock; client parsing of server text; surface tiers |
+| `docs/02-transport-auth-errors.md` | Hosts, headers, tokens, `POSTMARK_API_TEST`, error envelope, ErrorCode table, SDK error mapping, JSON and paging rules |
+| `docs/03-sending.md` | `/email`, batch, templates, bulk; validation and ErrorCodes; sandbox; tracking after accept |
+| `docs/04-bounces-suppressions-streams.md` | Bounce API, suppressions, message streams, data removals, and the state machine between them |
+| `docs/05-webhooks.md` | Webhook config API, every RecordType payload, retries, inbound |
+| `docs/06-messages-stats-templates-server.md` | Messages, opens/clicks, stats, templates, server/servers/domains/signatures |
+| `docs/07-smtp-sandbox-limits.md` | SMTP and `X-PM-*` headers, sandbox mode, bounce-testing addresses, limits |
+| `docs/08-sdk-client-matrix.md` | How each official SDK sends and parses; endpoint coverage; spec bugs; conformance plan |
+| `docs/09-implementation-options.md` | TypeScript design, routing options, control API, phases, decisions |
+| `docs/10-live-capture-plan.md` | Open questions and a safe capture harness design (deferred) |
+| `docs/11-build-plan.md` | Waves, parallel tracks, conformance runners, definition of done |
+| `tools/fetch-sources.sh` | Clones the official SDKs into `sdk/` at the commits the docs cite |
+| `tools/fetch-refs.sh` | Downloads Postmark's docs and Swagger specs into `refs/` |
+| `tools/test-ca.sh` | Writes a test CA and a certificate for the Postmark host names |
+| `tools/compose-ca.sh` | Keeps a valid test CA in the Compose volumes |
+| `tools/pack-smoke.sh` | Installs the packed npm package outside the repo and checks REST and SMTP |
+| `tools/compat-table.ts` | Writes the SDK compatibility table into this README |
+
+`sdk/` and `refs/` are git-ignored: they hold third-party code and Postmark's copyrighted docs.
+Run both scripts before you follow a citation.
+
+## License
+
+MIT.

package/dist/seeds/conformance/00-core.d.ts

@@ -0,0 +1,4 @@
+import type { Seed } from "../../src/control/seed.ts";
+/** Account token and server 1 with the default streams. */
+declare const core: Seed;
+export default core;

package/dist/seeds/conformance/00-core.js

@@ -0,0 +1,12 @@
+import { addAccountToken, createServer } from "../../src/state/servers.js";
+import { CONFORMANCE } from "../lib/conformance.js";
+/** Account token and server 1 with the default streams. */
+const core = ({ store, clock }) => {
+    addAccountToken(store, CONFORMANCE.accountToken);
+    createServer(store, clock.now(), {
+        ID: CONFORMANCE.serverId,
+        Name: CONFORMANCE.serverName,
+        ApiTokens: [CONFORMANCE.serverToken],
+    });
+};
+export default core;

package/dist/seeds/conformance/20-bounces.d.ts

@@ -0,0 +1,3 @@
+import type { Seed } from "../../src/control/seed.ts";
+declare const bounces: Seed;
+export default bounces;

package/dist/seeds/conformance/20-bounces.js

@@ -0,0 +1,108 @@
+import { BOUNCE_DESCRIPTIONS } from "../../src/recipients/transitions.js";
+import { suppressionKey } from "../../src/state/store.js";
+import { CONFORMANCE } from "../lib/conformance.js";
+// The conformance server received two bounces: SDK suites read the first bounce, its dump, and activate an
+// inactive one (docs/08 §5.3). The messages carry the bounced addresses, never the recipient that
+// sending tests use. Bounce IDs come from the T2 range (docs/11 §5).
+const MINUTE = 60_000;
+const bounced = (now, id, messageId, email, type, details, minutesAgo) => {
+    const sentAt = new Date(now.getTime() - (minutesAgo + 1) * MINUTE);
+    const bouncedAt = new Date(now.getTime() - minutesAgo * MINUTE);
+    const subject = "postmock seeded bounce";
+    const message = {
+        MessageID: messageId,
+        ServerID: CONFORMANCE.serverId,
+        MessageStream: "outbound",
+        From: CONFORMANCE.senderEmail,
+        To: [{ Email: email, Name: null }],
+        Cc: [],
+        Bcc: [],
+        ReplyTo: null,
+        Subject: subject,
+        HtmlBody: null,
+        TextBody: "Hello",
+        Tag: "postmock-bounce",
+        Headers: [],
+        Attachments: [],
+        Metadata: {},
+        TrackOpens: false,
+        TrackLinks: "None",
+        Status: "Sent",
+        Sandboxed: false,
+        ReceivedAt: sentAt,
+        // docs/06 §1.6; a hard bounce also suppresses the address.
+        MessageEvents: [
+            {
+                Recipient: email,
+                Type: "Bounced",
+                ReceivedAt: bouncedAt,
+                Details: { Summary: details, BounceID: String(id) },
+            },
+            ...(type === "HardBounce"
+                ? [
+                    {
+                        Recipient: email,
+                        Type: "SubscriptionChanged",
+                        ReceivedAt: bouncedAt,
+                        Details: { Origin: "Recipient", SuppressSending: "True" },
+                    },
+                ]
+                : []),
+        ],
+        channel: "rest",
+        request: {
+            From: CONFORMANCE.senderEmail,
+            To: email,
+            Subject: subject,
+            TextBody: "Hello",
+            Tag: "postmock-bounce",
+            MessageStream: "outbound",
+        },
+        rawSource: "",
+        bulkRequestId: null,
+        templateId: null,
+        suppressedRecipients: [],
+    };
+    const bounce = {
+        ID: id,
+        ServerID: CONFORMANCE.serverId,
+        MessageStream: "outbound",
+        MessageID: messageId,
+        Type: type,
+        Tag: message.Tag,
+        Description: BOUNCE_DESCRIPTIONS[type],
+        Details: details,
+        Email: email,
+        From: CONFORMANCE.senderEmail,
+        Subject: subject,
+        BouncedAt: bouncedAt,
+        Inactive: type === "HardBounce",
+        CanActivate: true,
+        Content: `Return-Path: <>\r\nSubject: Undelivered Mail Returned to Sender\r\n\r\n${details}\r\n`,
+        Metadata: {},
+    };
+    return [message, bounce];
+};
+const bounces = ({ store, clock }) => {
+    const now = clock.now();
+    const seeded = [
+        bounced(now, 2001, "6f1c2a0e-2b7d-4c55-9a51-0c3f2d7e2001", "hardbounce@example.com", "HardBounce", "smtp;550 5.1.1 The email account does not exist.", 120),
+        bounced(now, 2002, "6f1c2a0e-2b7d-4c55-9a51-0c3f2d7e2002", "softbounce@example.com", "SoftBounce", "smtp;452 4.2.2 The mailbox is full.", 60),
+    ];
+    for (const [message, bounce] of seeded) {
+        store.useId("bounce", bounce.ID);
+        store.state.outbound.set(message.MessageID, message);
+        store.state.bounces.set(bounce.ID, bounce);
+        if (bounce.Inactive) {
+            store.state.suppressions.set(suppressionKey(bounce.ServerID, bounce.MessageStream, bounce.Email), {
+                ServerID: bounce.ServerID,
+                MessageStream: bounce.MessageStream,
+                EmailAddress: bounce.Email,
+                SuppressionReason: "HardBounce",
+                Origin: "Recipient",
+                CreatedAt: bounce.BouncedAt,
+            });
+        }
+    }
+};
+export default bounces;

package/dist/seeds/conformance/40-messages.d.ts

@@ -0,0 +1,3 @@
+import type { Seed } from "../../src/control/seed.ts";
+declare const messages: Seed;
+export default messages;

package/dist/seeds/conformance/40-messages.js

@@ -0,0 +1,144 @@
+import { createServer } from "../../src/state/servers.js";
+import { recordClick, recordDelivery, recordOpen } from "../../src/tracking.js";
+import { CONFORMANCE } from "../lib/conformance.js";
+import { pastBounce, pastInbound, pastSend, pastSmtpApiError } from "../lib/history.js";
+import { READ_SERVER } from "../lib/read-server.js";
+// Message history on the read server for the read suites (docs/08 §5.3; T4 ID range 4000–4999):
+// ≥ 51 outbound messages in the retention window, some tagged `test_tag`, with deliveries,
+// bounces, opens and clicks; ≥ 10 processed inbound messages among several statuses; and older
+// sends that make the stats windows of the dotnet live test decrease strictly
+// (sdk/postmark-dotnet/src/Postmark.Tests/ClientStatisticsTests.cs:40-62).
+// php reads outbound message 51 and ten processed inbound messages
+// (sdk/postmark-php/tests/PostmarkClientOutboundMessageTest.php:31;
+// sdk/postmark-php/tests/PostmarkClientInboundMessageTest.php:21-24).
+// Bounces 4000–4003: hard (suppresses reader-4), soft, transient, SMTP API error.
+// The core conformance server gets one processed inbound message only: postmark.js reads inbound
+// details there (sdk/postmark.js/test/integration/Messages.test.ts:119-133).
+const HOUR = 60 * 60 * 1000;
+const DAY = 24 * HOUR;
+const LINK = "https://example.com/welcome";
+const CLIENTS = [
+    { Name: "Apple Mail 16.0", Company: "Apple Inc.", Family: "Apple Mail" },
+    { Name: "Outlook 2019", Company: "Microsoft Corporation", Family: "Outlook" },
+    { Name: "Chrome 120.0", Company: "Google Inc.", Family: "Chrome" },
+    { Name: "Safari 17.1", Company: "Apple Inc.", Family: "Safari" },
+];
+/** A mail client for opens (`browser` false) or a browser for clicks. */
+const agent = (n, browser) => ({
+    UserAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15",
+    Client: CLIENTS[(browser ? 2 : 0) + (n % 3 === 0 ? 1 : 0)] ?? null,
+    OS: { Name: "OS X 10.15 Catalina", Company: "Apple Computer, Inc.", Family: "OS X" },
+    Platform: n % 3 === 0 ? "Mobile" : "Desktop",
+    Geo: { CountryISOCode: "DK", Country: "Denmark", City: "Copenhagen" },
+});
+const send = (runtime, at, fields) => pastSend(runtime, {
+    ServerID: READ_SERVER.id,
+    ReceivedAt: at,
+    From: CONFORMANCE.senderEmail,
+    To: fields.to.map((Email) => ({ Email, Name: null })),
+    Cc: (fields.cc ?? []).map((Email) => ({ Email, Name: null })),
+    Subject: fields.subject,
+    HtmlBody: `<p>${fields.subject}</p><p><a href="${LINK}">Start</a></p>`,
+    TextBody: `${fields.subject}\n\nStart: ${LINK}`,
+    Tag: fields.tag,
+    Metadata: { seed: "t4" },
+    TrackOpens: fields.tracked,
+    TrackLinks: fields.tracked ? "HtmlAndText" : "None",
+});
+const messages = async (runtime) => {
+    createServer(runtime.store, runtime.clock.now(), {
+        ID: READ_SERVER.id,
+        Name: READ_SERVER.name,
+        ApiTokens: [READ_SERVER.token],
+    });
+    const now = runtime.clock.now().getTime();
+    const ago = (ms) => new Date(now - ms);
+    const recent = [];
+    for (let i = 0; i < 40; i++) {
+        recent.push(await send(runtime, ago(i * 15 * HOUR + HOUR), {
+            to: [`reader-${i % 5}@example.com`],
+            ...(i % 7 === 0 && { cc: ["reader-cc@example.com"] }),
+            subject: `Order update ${i}`,
+            tag: i % 3 === 0 ? "test_tag" : null,
+            tracked: i % 4 !== 3,
+        }));
+    }
+    // 26–29 days ago: after the dotnet `todate` of 30 days ago (ClientStatisticsTests.cs:16), so only
+    // the all-time window grows.
+    for (let i = 0; i < 8; i++) {
+        await send(runtime, ago(26 * DAY + i * 9 * HOUR), {
+            to: [`reader-${i % 5}@example.com`],
+            subject: `Monthly digest ${i}`,
+            tag: null,
+            tracked: false,
+        });
+    }
+    // Older sends: the stats windows [35 days ago, 30 days ago] and before (see header).
+    for (const [days, tag] of [
+        [32, "test_tag"],
+        [32, null],
+        [33, null],
+        [40, null],
+        [41, null],
+        [60, null],
+    ]) {
+        await send(runtime, ago(days * DAY), {
+            to: ["reader-archive@example.com"],
+            subject: "Archived notice",
+            tag,
+            tracked: false,
+        });
+    }
+    const minutes = (m, n) => new Date(m.ReceivedAt.getTime() + n * 60000);
+    const hard = recent[4];
+    await pastBounce(runtime, hard, { id: 4000, type: "HardBounce", at: minutes(hard, 60) });
+    const soft = recent[8];
+    await pastBounce(runtime, soft, { id: 4001, type: "SoftBounce", at: minutes(soft, 60) });
+    // A delay notice comes before the delivery below.
+    const delayed = recent[12];
+    await pastBounce(runtime, delayed, { id: 4002, type: "Transient", at: minutes(delayed, 5) });
+    // A later SMTP send to the address the hard bounce suppressed.
+    await pastSmtpApiError(runtime, {
+        id: 4003,
+        serverId: READ_SERVER.id,
+        stream: "outbound",
+        email: hard.To[0]?.Email,
+        tag: null,
+        at: minutes(hard, 120),
+    });
+    for (const [i, message] of recent.entries()) {
+        if (message === hard || message === soft)
+            continue;
+        const later = (n) => minutes(message, n);
+        const target = { messageId: message.MessageID, recipient: message.To[0]?.Email };
+        await recordDelivery(runtime, { ...target, details: "smtp;250 2.0.0 OK" }, later(15));
+        if (!message.TrackOpens || i % 2 === 1)
+            continue;
+        await recordOpen(runtime, { ...target, agent: agent(i, false), readSeconds: 5 + i }, later(30));
+        if (i % 4 !== 0)
+            continue;
+        await recordOpen(runtime, { ...target, agent: agent(i, false), readSeconds: 3 }, later(45));
+        const location = i % 8 === 0 ? "HTML" : "Text";
+        await recordClick(runtime, { ...target, link: LINK, location, agent: agent(i, true) }, later(45));
+    }
+    const statuses = [
+        ...Array(3).fill("Processed"),
+        "Blocked",
+        "Failed",
+        ...Array(7).fill("Processed"),
+    ];
+    for (const [n, Status] of statuses.entries()) {
+        pastInbound(runtime, {
+            ServerID: READ_SERVER.id,
+            ReceivedAt: ago((n + 1) * 6 * HOUR),
+            Status,
+            Subject: `Inbound ${n}`,
+        });
+    }
+    pastInbound(runtime, {
+        ServerID: CONFORMANCE.serverId,
+        ReceivedAt: ago(2 * HOUR),
+        Status: "Processed",
+    });
+};
+export default messages;

package/dist/seeds/conformance/50-server-color.d.ts

@@ -0,0 +1,8 @@
+import type { Seed } from "../../src/control/seed.ts";
+/**
+ * The conformance server is yellow, the color the dotnet server test leaves after its reset. That
+ * test sets purple and asserts the color changed
+ * (sdk/postmark-dotnet/src/Postmark.Tests/ClientServerInformationTests.cs:76-98).
+ */
+declare const serverColor: Seed;
+export default serverColor;

package/dist/seeds/conformance/50-server-color.js

@@ -0,0 +1,13 @@
+import { CONFORMANCE } from "../lib/conformance.js";
+/**
+ * The conformance server is yellow, the color the dotnet server test leaves after its reset. That
+ * test sets purple and asserts the color changed
+ * (sdk/postmark-dotnet/src/Postmark.Tests/ClientServerInformationTests.cs:76-98).
+ */
+const serverColor = ({ store }) => {
+    const server = store.state.servers.get(CONFORMANCE.serverId);
+    if (server === undefined)
+        throw new Error("the core seed part creates the conformance server");
+    server.Color = "yellow";
+};
+export default serverColor;

package/dist/seeds/conformance/70-account.d.ts

@@ -0,0 +1,9 @@
+import type { Seed } from "../../src/control/seed.ts";
+/**
+ * The account the SDK suites ran against: server deletion enabled, verified domains, and a
+ * confirmed sender signature. The dotnet, java and php suites read the first domain and signature
+ * (sdk/postmark-java/src/test/java/integration/DomainTest.java:36-41). A send needs a `From` on a
+ * verified domain or a confirmed signature (docs/03 §3.4).
+ */
+declare const account: Seed;
+export default account;

package/dist/seeds/conformance/70-account.js

@@ -0,0 +1,29 @@
+import { confirmDkim } from "../../src/api/account/authentication.js";
+import { addVerifiedDomain } from "../../src/api/account/domains.js";
+import { newSender } from "../../src/api/account/senders.js";
+import { CONFORMANCE } from "../lib/conformance.js";
+/**
+ * The account the SDK suites ran against: server deletion enabled, verified domains, and a
+ * confirmed sender signature. The dotnet, java and php suites read the first domain and signature
+ * (sdk/postmark-java/src/test/java/integration/DomainTest.java:36-41). A send needs a `From` on a
+ * verified domain or a confirmed signature (docs/03 §3.4).
+ */
+const account = ({ store, clock }) => {
+    const now = clock.now();
+    store.state.account.serverDeletionEnabled = true;
+    addVerifiedDomain(store.state, store.useId("domain", 7000), CONFORMANCE.domain, now);
+    // The postmark-python start example sends from its placeholder domain
+    // (sdk/postmark-python/examples/start_here.py:53); its owner verifies that domain first.
+    addVerifiedDomain(store.state, store.useId("domain", 7001), CONFORMANCE.exampleDomain, now);
+    const sender = newSender(store.useId("sender", 7000), {
+        FromEmail: CONFORMANCE.senderEmail,
+        Name: "postmock sender",
+        ReplyToEmail: "",
+        ReturnPathDomain: "",
+        ConfirmationPersonalNote: "",
+    }, now);
+    sender.Confirmed = true;
+    confirmDkim(sender);
+    store.state.senders.set(sender.ID, sender);
+};
+export default account;

package/dist/seeds/conformance/80-templates.d.ts

@@ -0,0 +1,4 @@
+import type { Seed } from "../../src/control/seed.ts";
+/** A server with one standard template that renders without a model. */
+declare const templates: Seed;
+export default templates;

package/dist/seeds/conformance/80-templates.js

@@ -0,0 +1,23 @@
+import { createServer } from "../../src/state/servers.js";
+import { TEMPLATE_SERVER } from "../lib/template-server.js";
+/** A server with one standard template that renders without a model. */
+const templates = ({ store, clock }) => {
+    createServer(store, clock.now(), {
+        ID: TEMPLATE_SERVER.id,
+        Name: TEMPLATE_SERVER.name,
+        ApiTokens: [TEMPLATE_SERVER.token],
+    });
+    store.state.templates.set(store.useId("template", TEMPLATE_SERVER.templateId), {
+        TemplateId: TEMPLATE_SERVER.templateId,
+        ServerID: TEMPLATE_SERVER.id,
+        Name: "postmock welcome",
+        Alias: "postmock-welcome",
+        Subject: "Welcome",
+        HtmlBody: "<p>Welcome</p>",
+        TextBody: "Welcome",
+        TemplateType: "Standard",
+        LayoutTemplate: null,
+        Active: true,
+    });
+};
+export default templates;

package/dist/seeds/conformance.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("../src/control/seed.ts").Seed;
+export default _default;

package/dist/seeds/conformance.js

@@ -0,0 +1,3 @@
+import { seedFromDirectory } from "../src/control/seed.js";
+// The harness seed for SDK conformance suites (docs/08 §5.3): every part in `seeds/conformance/`.
+export default seedFromDirectory(new URL("./conformance/", import.meta.url));