@volter/twin-postmark 0.1.0

package/dist/src/postmark-connector.js

@@ -0,0 +1,251 @@
+// Postmark CONNECTOR — the live-vendor pull/push path that gives the Postmark twin the full
+// "git for SaaS" lifecycle over an INJECTED client (the auth boundary).
+//
+// PULL  (real → twin):  fetch real Postmark objects via the injected client (outbound
+//                       messages, bounces, templates, message streams, webhooks, and the
+//                       server itself), map them to SyncResource[], and fold them into the
+//                       tree through the kernel's observe (its own diff, so a re-pull of identical
+//                       state is a no-op).
+// PUSH  (twin → real):  for every PENDING local action, call the injected client and
+//                       confirmAction on success. The headline push is sending local
+//                       messages to real Postmark; templates/webhooks/streams follow.
+//
+// The vendor I/O is an INJECTED client interface (`PostmarkClient`): a fake in tests, a real
+// `new postmark.ServerClient(token)` in prod. The pack imports NO SDK and holds NO key. The
+// shape below is a structural SUBSET of the real `ServerClient` (method names taken from the
+// SDK's own ServerClient.d.ts), so a real client satisfies it without adaptation.
+import { observeResources } from '@volter/world-core';
+const SERVICE = 'postmark';
+function listOf(value) {
+    return Array.isArray(value) ? value : [];
+}
+// ── PULL: pure shape mappers (no client, no I/O — trivially unit-testable) ──────────
+export function mapMessage(m) {
+    return {
+        type: 'message',
+        id: String(m.MessageID),
+        fields: {
+            MessageID: String(m.MessageID), Tag: m.Tag ?? '', To: listOf(m.To), Cc: listOf(m.Cc), Bcc: listOf(m.Bcc),
+            Recipients: listOf(m.Recipients), ReceivedAt: m.ReceivedAt ?? null, From: m.From ?? null,
+            Subject: m.Subject ?? '', Attachments: listOf(m.Attachments), Status: m.Status ?? 'Sent',
+            TrackOpens: m.TrackOpens === true, TrackLinks: m.TrackLinks ?? 'None', Metadata: m.Metadata ?? {},
+            MessageStream: m.MessageStream ?? 'outbound', Sandboxed: m.Sandboxed === true,
+            HtmlBody: null, TextBody: null, MessageEvents: [],
+        },
+    };
+}
+export function mapBounce(b) {
+    return {
+        type: 'bounce',
+        id: String(b.ID),
+        fields: {
+            RecordType: 'Bounce', ID: b.ID, Type: b.Type ?? 'HardBounce', TypeCode: b.TypeCode ?? 1,
+            Name: b.Name ?? 'Hard bounce', Tag: b.Tag ?? '', MessageID: b.MessageID ?? null,
+            ServerID: b.ServerID ?? 1, Description: b.Description ?? '', Details: b.Details ?? '',
+            Email: b.Email ?? null, From: b.From ?? null, BouncedAt: b.BouncedAt ?? null,
+            DumpAvailable: b.DumpAvailable === true, Inactive: b.Inactive === true,
+            CanActivate: b.CanActivate === true, Subject: b.Subject ?? '', MessageStream: b.MessageStream ?? 'outbound',
+        },
+    };
+}
+export function mapTemplate(t) {
+    return {
+        type: 'template',
+        id: String(t.TemplateId),
+        fields: {
+            TemplateId: t.TemplateId, Name: t.Name ?? null, Alias: t.Alias ?? null,
+            TemplateType: t.TemplateType ?? 'Standard', Active: t.Active !== false,
+            LayoutTemplate: t.LayoutTemplate ?? null, Subject: t.Subject ?? '',
+            HtmlBody: t.HtmlBody ?? null, TextBody: t.TextBody ?? null, AssociatedServerId: 1,
+        },
+    };
+}
+export function mapMessageStream(s) {
+    return {
+        type: 'message_stream',
+        id: String(s.ID),
+        fields: {
+            ID: String(s.ID), ServerID: s.ServerID ?? 1, Name: s.Name ?? String(s.ID),
+            Description: s.Description ?? '', MessageStreamType: s.MessageStreamType ?? 'Transactional',
+            CreatedAt: s.CreatedAt ?? null, UpdatedAt: s.UpdatedAt ?? null, ArchivedAt: s.ArchivedAt ?? null,
+            SubscriptionManagementConfiguration: s.SubscriptionManagementConfiguration ?? { UnsubscribeHandlingType: 'None' },
+        },
+    };
+}
+export function mapWebhook(w) {
+    return {
+        type: 'webhook',
+        id: String(w.ID),
+        fields: {
+            ID: w.ID, Url: w.Url ?? null, MessageStream: w.MessageStream ?? 'outbound',
+            HttpAuth: w.HttpAuth ?? null, HttpHeaders: listOf(w.HttpHeaders), Triggers: w.Triggers ?? {},
+        },
+    };
+}
+export function mapServer(s) {
+    return {
+        type: 'server',
+        id: String(s.ID),
+        fields: {
+            ID: s.ID, Name: s.Name ?? null, Color: s.Color ?? 'blue', DeliveryType: s.DeliveryType ?? 'Live',
+            TrackOpens: s.TrackOpens === true, TrackLinks: s.TrackLinks ?? 'None',
+            InboundAddress: s.InboundAddress ?? '', ServerLink: s.ServerLink ?? '',
+            SmtpApiActivated: s.SmtpApiActivated !== false,
+        },
+    };
+}
+// ── PULL: the network-touching entry points ────────────────────────────────────────
+export async function pullPostmarkMessages(client) {
+    return listOf((await client.getOutboundMessages({ count: 500, offset: 0 })).Messages).map(mapMessage);
+}
+export async function pullPostmarkBounces(client) {
+    return listOf((await client.getBounces({ count: 500, offset: 0 })).Bounces).map(mapBounce);
+}
+export async function pullPostmarkTemplates(client) {
+    return listOf((await client.getTemplates({ count: 500, offset: 0 })).Templates).map(mapTemplate);
+}
+export async function pullPostmarkMessageStreams(client) {
+    return listOf((await client.getMessageStreams()).MessageStreams).map(mapMessageStream);
+}
+export async function pullPostmarkWebhooks(client) {
+    return listOf((await client.getWebhooks()).Webhooks).map(mapWebhook);
+}
+export async function pullPostmarkServer(client) {
+    return [mapServer(await client.getServer())];
+}
+/**
+ * D7 entry point: pull from real Postmark and fold everything into the twin (mirror seeding).
+ * Callers never have to know the per-domain `pull*` mechanics.
+ */
+export async function syncPostmarkFromReal(client, opts) {
+    const resources = [
+        ...(await pullPostmarkMessageStreams(client)),
+        ...(await pullPostmarkServer(client)),
+        ...(await pullPostmarkTemplates(client)),
+        ...(await pullPostmarkMessages(client)),
+        ...(await pullPostmarkBounces(client)),
+        ...(await pullPostmarkWebhooks(client)),
+    ];
+    // protocol 2: the observation lands on the head through the kernel's fold — one batch, one instant
+    const result = observeResources(SERVICE, resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), { ...(opts.root !== undefined ? { root: opts.root } : {}), at: opts.occurredAt, batch: `obs:${SERVICE}:${opts.occurredAt}` });
+    return { observed: result.observed, deltasAppended: result.appended };
+}
+// ── PUSH ────────────────────────────────────────────────────────────────────────────
+// The twin operations this connector knows how to push to real Postmark. Anything not here
+// FAILS LOUDLY rather than being silently dropped.
+const PUSHABLE = new Set(['message.send', 'template.create', 'webhook.create', 'message_stream.create']);
+function assertPushable(op) {
+    if (!PUSHABLE.has(op)) {
+        throw new Error(`postmark push: unsupported operation '${op}' — refusing to silently drop a local write`);
+    }
+}
+/** Recipients are stored structurally in the twin; Postmark's API takes a comma-joined string. */
+function joinRecipients(v) {
+    if (Array.isArray(v))
+        return v.map((r) => String(r?.Email ?? r)).filter(Boolean).join(', ');
+    return typeof v === 'string' ? v : '';
+}
+/**
+ * Push ONE pending action to REAL Postmark via the injected client. Returns the real external
+ * id (the Postmark object id from the response). WRITES TO THE REAL ACCOUNT (sends real email).
+ */
+export async function pushPostmarkAction(client, action) {
+    const op = action.operation ?? `${action.subject.type}.update`;
+    assertPushable(op);
+    const f = action.fields ?? {};
+    let externalId = action.subject.id;
+    if (op === 'message.send') {
+        const res = await client.sendEmail({
+            From: String(f.From ?? ''),
+            To: joinRecipients(f.To) || joinRecipients(f.Recipients),
+            ...(joinRecipients(f.Cc) ? { Cc: joinRecipients(f.Cc) } : {}),
+            ...(joinRecipients(f.Bcc) ? { Bcc: joinRecipients(f.Bcc) } : {}),
+            Subject: String(f.Subject ?? ''),
+            ...(f.HtmlBody != null ? { HtmlBody: String(f.HtmlBody) } : {}),
+            ...(f.TextBody != null ? { TextBody: String(f.TextBody) } : {}),
+            ...(f.Tag ? { Tag: String(f.Tag) } : {}),
+            ...(f.MessageStream ? { MessageStream: String(f.MessageStream) } : {}),
+            ...(f.TrackOpens === true ? { TrackOpens: true } : {}),
+            ...(f.TrackLinks && f.TrackLinks !== 'None' ? { TrackLinks: String(f.TrackLinks) } : {}),
+        });
+        externalId = String(res.MessageID);
+    }
+    else if (op === 'template.create') {
+        externalId = String((await client.createTemplate({
+            Name: String(f.Name ?? ''),
+            ...(f.Alias != null ? { Alias: String(f.Alias) } : {}),
+            Subject: String(f.Subject ?? ''),
+            ...(f.HtmlBody != null ? { HtmlBody: String(f.HtmlBody) } : {}),
+            ...(f.TextBody != null ? { TextBody: String(f.TextBody) } : {}),
+            TemplateType: String(f.TemplateType ?? 'Standard'),
+        })).TemplateId);
+    }
+    else if (op === 'webhook.create') {
+        externalId = String((await client.createWebhook({
+            Url: String(f.Url ?? ''),
+            MessageStream: String(f.MessageStream ?? 'outbound'),
+            ...(f.HttpAuth ? { HttpAuth: f.HttpAuth } : {}),
+            ...(Array.isArray(f.HttpHeaders) && f.HttpHeaders.length ? { HttpHeaders: f.HttpHeaders } : {}),
+            Triggers: f.Triggers ?? {},
+        })).ID);
+    }
+    else if (op === 'message_stream.create') {
+        externalId = String((await client.createMessageStream({
+            ID: String(f.ID ?? action.subject.id),
+            Name: String(f.Name ?? ''),
+            MessageStreamType: String(f.MessageStreamType ?? 'Transactional'),
+            ...(f.Description ? { Description: String(f.Description) } : {}),
+        })).ID);
+    }
+    return { externalId: externalId || action.subject.id };
+}
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/** A PostmarkClient over the kernel's executor. At a REAL boundary the kernel's executor sets the sealed
+ *  credential over these headers (executor.ts); at the twin's own wire any credential is one. */
+export function postmarkClientOver(execute) {
+    const get = async (path) => {
+        const res = await execute({ method: 'GET', path, headers: { accept: 'application/json', authorization: 'Bearer twin', 'x-postmark-server-token': 'twin' } });
+        if (res.status < 200 || res.status >= 300)
+            throw new Error(`postmark GET ${path} refused: HTTP ${res.status} ${res.body.slice(0, 200)}`);
+        return JSON.parse(res.body || '{}');
+    };
+    const post = async (path, body) => {
+        const res = await execute({ method: 'POST', path, headers: { accept: 'application/json', 'content-type': 'application/json', 'x-postmark-server-token': 'twin' }, body: JSON.stringify(body) });
+        if (res.status < 200 || res.status >= 300)
+            throw new Error(`postmark POST ${path} refused: HTTP ${res.status} ${res.body.slice(0, 200)}`);
+        return JSON.parse(res.body || '{}');
+    };
+    return {
+        getServer: () => get('/server'),
+        getMessageStreams: () => get('/message-streams'),
+        getOutboundMessages: () => get('/messages/outbound'),
+        getBounces: () => get('/bounces'),
+        getTemplates: () => get('/templates'),
+        getWebhooks: () => get('/webhooks'),
+        sendEmail: (message) => post('/email', message),
+        createTemplate: (options) => post('/templates', options),
+        createWebhook: (options) => post('/webhooks', options),
+        createMessageStream: (options) => post('/message-streams', options),
+    };
+}
+/** The refresh adapter: pull the account's state through the executor and fold it into the root. */
+export async function syncPostmarkFromRemote(execute, opts = {}) {
+    return syncPostmarkFromReal(postmarkClientOver(execute), {
+        ...(opts.root !== undefined ? { root: opts.root } : {}),
+        occurredAt: opts.occurredAt ?? new Date().toISOString(),
+    });
+}
+/** The perform adapter: a message send crosses; everything else is the twin's own record. */
+export async function performPostmarkAction(execute, action, _ctx) {
+    const op = action.operation ?? `${action.subject.type}.update`;
+    try {
+        return await pushPostmarkAction(postmarkClientOver(execute), { operation: op, subject: action.subject, fields: action.fields ?? {} });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (/unsupported operation|not pushable|no push/i.test(message)) {
+            return { externalId: action.subject.id, data: { performed: false, reason: `${op} is the twin's own record — nothing at Postmark to write` } };
+        }
+        throw error;
+    }
+}

package/dist/src/postmark-events.d.ts

@@ -0,0 +1,85 @@
+/** Postmark's webhook `RecordType` discriminators (the outbound delivery-lifecycle family). */
+export declare const POSTMARK_RECORD_TYPES: readonly ["Delivery", "Open", "Click", "Bounce", "SpamComplaint", "SubscriptionChange"];
+export type PostmarkRecordType = (typeof POSTMARK_RECORD_TYPES)[number];
+/** An injected webhook deliverer — a fake in tests, a real HTTP POST live. */
+export type PostmarkWebhookDelivery = (url: string, body: string, headers: Record<string, string>) => Promise<void> | void;
+/** What the twin needs to route a webhook: the root to read from + the injected deliverer. */
+export type WebhookContext = {
+    root?: string;
+    deliver?: PostmarkWebhookDelivery;
+};
+/**
+ * The webhooks registered on a stream whose trigger for `recordType` is enabled — read from
+ * the SAME projection the Webhooks API serves, so a webhook created through `POST /webhooks`
+ * is the one that fires (no parallel registry to drift).
+ */
+export declare function webhooksFor(stream: string, recordType: PostmarkRecordType, root?: string): Array<Record<string, unknown>>;
+/**
+ * The headers Postmark sends with a webhook delivery: JSON content type, the webhook's own
+ * custom `HttpHeaders`, and an HTTP Basic `Authorization` header when `HttpAuth` is set.
+ * Pure — exported so a verify() can assert the auth/header wiring without any I/O.
+ */
+export declare function webhookHeaders(webhook: Record<string, unknown>): Record<string, string>;
+/**
+ * POST one Postmark webhook payload to every webhook on `stream` whose trigger for this
+ * `RecordType` is enabled. Returns what was delivered (for assertions); a no-op when no
+ * webhook subscribes. Offline whenever `ctx.deliver` is injected.
+ */
+export declare function emitPostmarkWebhook(stream: string, recordType: PostmarkRecordType, payload: Record<string, unknown>, ctx?: WebhookContext): Promise<Array<{
+    url: string;
+    body: string;
+    headers: Record<string, string>;
+}>>;
+/**
+ * Deliver ONE arriving inbound message to the server's `InboundHookUrl`.
+ *
+ * This is a different door from `emitPostmarkWebhook` on purpose, because the vendor's is:
+ * Postmark's Webhooks API (`POST /webhooks`, `Triggers`) covers the OUTBOUND delivery
+ * lifecycle, while an inbound message is posted to the URL configured on the SERVER
+ * (`InboundHookUrl`, settable via `PUT /server`). The payload is the inbound message
+ * document itself — the same object `GET /messages/inbound/:id/details` serves, with NO
+ * `RecordType` discriminator, which is exactly what the vendor sends.
+ *
+ * AUTH. Postmark's inbound hook has no header configuration at all: the only credential it
+ * can carry is HTTP Basic userinfo embedded in the configured URL. That userinfo is split
+ * out into an `Authorization: Basic` header here rather than left on the URL, because that
+ * is both what the vendor puts on the wire and what `fetch` refuses to send otherwise.
+ */
+export declare function emitPostmarkInboundHook(message: Record<string, unknown>, ctx?: WebhookContext): Promise<Array<{
+    url: string;
+    body: string;
+    headers: Record<string, string>;
+}>>;
+export type PostmarkEventType = 'Delivered' | 'Opened' | 'LinkClicked' | 'Bounced' | 'SpamComplaint';
+/**
+ * The ordered `MessageEvents` the twin drives a sent message through, OFFLINE.
+ *
+ * The recipient prefixes below are a TWIN-LOCAL convention (Postmark's own bounce testing
+ * needs real mail flow, which a local twin has none of), deliberately documented rather than
+ * dressed up as vendor behavior — they are the seam that lets a test drive the bounce and
+ * spam-complaint paths deterministically:
+ *   · a recipient whose local part starts with `bounce`  → a HARD BOUNCE (no delivery);
+ *   · one starting with `spam` or `complaint`            → delivered, then a SPAM COMPLAINT;
+ *   · anything else                                      → delivered.
+ * Opens and clicks are emitted ONLY when the message asked for that tracking — `TrackOpens`
+ * and `TrackLinks` respectively — exactly as the vendor does, so a message sent with tracking
+ * off records neither.
+ *
+ * `status` is the outbound message's `Status`. It stays `Sent` for every submitted message:
+ * on real Postmark a bounce does NOT rewrite the message's Status, it surfaces through
+ * `MessageEvents` and the Bounce API. Modeled that way here on purpose.
+ */
+export declare function deliveryPlan(input: {
+    recipient: string;
+    trackOpens: boolean;
+    trackLinks: string;
+}): {
+    events: PostmarkEventType[];
+    status: string;
+};
+/** The terminal event a message lands on, given its plan (the outbound activity headline). */
+export declare function terminalEvent(input: {
+    recipient: string;
+    trackOpens: boolean;
+    trackLinks: string;
+}): PostmarkEventType;

package/dist/src/postmark-events.js

@@ -0,0 +1,169 @@
+// Postmark WEBHOOK DELIVERY + the deterministic offline delivery plan.
+//
+// ⚠ FIDELITY NOTE — READ THIS BEFORE "ADDING SIGNATURES". Postmark webhooks are NOT signed.
+// There is no `svix-signature`, no HMAC, no shared secret anywhere in Postmark's webhook
+// design (this is a real difference from Resend/Clerk/Svix-backed vendors, and a twin that
+// invented a signature scheme would be teaching consumers to verify something the vendor
+// never sends). Postmark authenticates a webhook delivery the two ways its Webhooks API
+// actually models — both of which this module reproduces:
+//   · `HttpAuth: { Username, Password }` → an HTTP Basic `Authorization` header, and
+//   · `HttpHeaders: [{ Name, Value }]`   → arbitrary caller-chosen headers (the usual place
+//                                          a shared secret goes).
+// Both are stored on the webhook resource by the Webhooks API (POST /webhooks), so the
+// registry here is the twin's OWN projected state — not a parallel in-memory store.
+//
+// PAYLOAD. Each delivery is a plain JSON POST whose body carries a `RecordType` discriminator
+// — `Delivery` | `Open` | `Click` | `Bounce` | `SpamComplaint` | `SubscriptionChange` |
+// `Inbound` — matching the vendor's documented webhook payloads. A webhook only receives a
+// record type whose `Triggers.<Type>.Enabled` is true, and only for its own MessageStream.
+//
+// DELIVERY PLAN. A sent email progresses through a DETERMINISTIC, OFFLINE outcome the twin
+// drives — no SMTP, no network. `deliveryPlan()` is pure so the twin + its tests are
+// repeatable.
+import { projectResources } from '@volter/world-core';
+import { worldEgressRefusal } from '@volter/world-core/network-policy';
+const SERVICE = 'postmark';
+/** Postmark's webhook `RecordType` discriminators (the outbound delivery-lifecycle family). */
+export const POSTMARK_RECORD_TYPES = ['Delivery', 'Open', 'Click', 'Bounce', 'SpamComplaint', 'SubscriptionChange'];
+/** RecordType → the `Triggers` key on the webhook resource that gates it. */
+const TRIGGER_FOR = {
+    Delivery: 'Delivery', Open: 'Open', Click: 'Click',
+    Bounce: 'Bounce', SpamComplaint: 'SpamComplaint', SubscriptionChange: 'SubscriptionChange',
+};
+function asObject(v) {
+    return v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+}
+/**
+ * The webhooks registered on a stream whose trigger for `recordType` is enabled — read from
+ * the SAME projection the Webhooks API serves, so a webhook created through `POST /webhooks`
+ * is the one that fires (no parallel registry to drift).
+ */
+export function webhooksFor(stream, recordType, root) {
+    return projectResources(SERVICE, root)
+        .filter((r) => r.type === 'webhook' && r.deleted !== true)
+        .filter((w) => w.MessageStream === stream)
+        .filter((w) => asObject(asObject(w.Triggers)[TRIGGER_FOR[recordType]]).Enabled === true);
+}
+/**
+ * The headers Postmark sends with a webhook delivery: JSON content type, the webhook's own
+ * custom `HttpHeaders`, and an HTTP Basic `Authorization` header when `HttpAuth` is set.
+ * Pure — exported so a verify() can assert the auth/header wiring without any I/O.
+ */
+export function webhookHeaders(webhook) {
+    const headers = { 'content-type': 'application/json' };
+    for (const raw of Array.isArray(webhook.HttpHeaders) ? webhook.HttpHeaders : []) {
+        const h = asObject(raw);
+        if (typeof h.Name === 'string' && h.Name !== '')
+            headers[h.Name] = String(h.Value ?? '');
+    }
+    const auth = asObject(webhook.HttpAuth);
+    if (typeof auth.Username === 'string' && auth.Username !== '') {
+        headers.Authorization = `Basic ${Buffer.from(`${auth.Username}:${String(auth.Password ?? '')}`).toString('base64')}`;
+    }
+    return headers;
+}
+/** Fire-and-forget HTTP delivery — the live path, like the real vendor's. */
+const httpDelivery = async (url, body, headers) => {
+    if (worldEgressRefusal(url) !== null)
+        return; // the World's egress rule: refused like an unreachable endpoint
+    try {
+        await fetch(url, { method: 'POST', headers, body });
+    }
+    catch {
+        /* fire-and-forget, like the real vendor */
+    }
+};
+/**
+ * POST one Postmark webhook payload to every webhook on `stream` whose trigger for this
+ * `RecordType` is enabled. Returns what was delivered (for assertions); a no-op when no
+ * webhook subscribes. Offline whenever `ctx.deliver` is injected.
+ */
+export async function emitPostmarkWebhook(stream, recordType, payload, ctx = {}) {
+    const targets = webhooksFor(stream, recordType, ctx.root);
+    if (targets.length === 0)
+        return [];
+    const deliver = ctx.deliver ?? httpDelivery;
+    const body = JSON.stringify({ RecordType: recordType, ...payload });
+    const out = [];
+    for (const w of targets) {
+        const headers = webhookHeaders(w);
+        await deliver(String(w.Url), body, headers);
+        out.push({ url: String(w.Url), body, headers });
+    }
+    return out;
+}
+/**
+ * Deliver ONE arriving inbound message to the server's `InboundHookUrl`.
+ *
+ * This is a different door from `emitPostmarkWebhook` on purpose, because the vendor's is:
+ * Postmark's Webhooks API (`POST /webhooks`, `Triggers`) covers the OUTBOUND delivery
+ * lifecycle, while an inbound message is posted to the URL configured on the SERVER
+ * (`InboundHookUrl`, settable via `PUT /server`). The payload is the inbound message
+ * document itself — the same object `GET /messages/inbound/:id/details` serves, with NO
+ * `RecordType` discriminator, which is exactly what the vendor sends.
+ *
+ * AUTH. Postmark's inbound hook has no header configuration at all: the only credential it
+ * can carry is HTTP Basic userinfo embedded in the configured URL. That userinfo is split
+ * out into an `Authorization: Basic` header here rather than left on the URL, because that
+ * is both what the vendor puts on the wire and what `fetch` refuses to send otherwise.
+ */
+export async function emitPostmarkInboundHook(message, ctx = {}) {
+    const server = projectResources(SERVICE, ctx.root).find((r) => r.type === 'server' && r.deleted !== true);
+    const configured = typeof server?.InboundHookUrl === 'string' ? server.InboundHookUrl : '';
+    if (configured === '')
+        return [];
+    let parsed;
+    try {
+        parsed = new URL(configured);
+    }
+    catch {
+        return [];
+    }
+    const headers = { 'content-type': 'application/json' };
+    if (parsed.username !== '') {
+        headers.Authorization = `Basic ${Buffer.from(`${decodeURIComponent(parsed.username)}:${decodeURIComponent(parsed.password)}`).toString('base64')}`;
+        parsed.username = '';
+        parsed.password = '';
+    }
+    const url = parsed.toString();
+    const body = JSON.stringify(message);
+    await (ctx.deliver ?? httpDelivery)(url, body, headers);
+    return [{ url, body, headers }];
+}
+/**
+ * The ordered `MessageEvents` the twin drives a sent message through, OFFLINE.
+ *
+ * The recipient prefixes below are a TWIN-LOCAL convention (Postmark's own bounce testing
+ * needs real mail flow, which a local twin has none of), deliberately documented rather than
+ * dressed up as vendor behavior — they are the seam that lets a test drive the bounce and
+ * spam-complaint paths deterministically:
+ *   · a recipient whose local part starts with `bounce`  → a HARD BOUNCE (no delivery);
+ *   · one starting with `spam` or `complaint`            → delivered, then a SPAM COMPLAINT;
+ *   · anything else                                      → delivered.
+ * Opens and clicks are emitted ONLY when the message asked for that tracking — `TrackOpens`
+ * and `TrackLinks` respectively — exactly as the vendor does, so a message sent with tracking
+ * off records neither.
+ *
+ * `status` is the outbound message's `Status`. It stays `Sent` for every submitted message:
+ * on real Postmark a bounce does NOT rewrite the message's Status, it surfaces through
+ * `MessageEvents` and the Bounce API. Modeled that way here on purpose.
+ */
+export function deliveryPlan(input) {
+    const local = String(input.recipient ?? '').split('@')[0]?.toLowerCase() ?? '';
+    if (local.startsWith('bounce'))
+        return { events: ['Bounced'], status: 'Sent' };
+    if (local.startsWith('spam') || local.startsWith('complaint')) {
+        return { events: ['Delivered', 'SpamComplaint'], status: 'Sent' };
+    }
+    const events = ['Delivered'];
+    if (input.trackOpens)
+        events.push('Opened');
+    if (input.trackLinks && input.trackLinks !== 'None')
+        events.push('LinkClicked');
+    return { events, status: 'Sent' };
+}
+/** The terminal event a message lands on, given its plan (the outbound activity headline). */
+export function terminalEvent(input) {
+    const { events } = deliveryPlan(input);
+    return events[events.length - 1];
+}

package/dist/src/postmark-mirror-ui.d.ts

@@ -0,0 +1,58 @@
+export type PostmarkRow = Record<string, any>;
+/** The recipients of an outbound message, as a readable list. */
+export declare function recipientsOf(m: PostmarkRow): string;
+/** A subject line for a message row, or a placeholder. */
+export declare function messageSubject(m: PostmarkRow): string;
+/** The ordered `MessageEvents` types the twin recorded for a message. */
+export declare function deliveryTimeline(m: PostmarkRow): string[];
+/**
+ * The headline delivery status of a message: its LAST recorded MessageEvent, falling back to
+ * the vendor's `Status` field. This is what the Activity list and the status pill show.
+ */
+export declare function messageStatus(m: PostmarkRow): string;
+/** The rendered preview of a message body — prefers HtmlBody, falls back to TextBody. */
+export declare function messagePreview(m: PostmarkRow): {
+    kind: 'html' | 'text' | 'none';
+    value: string;
+};
+/** Format an ISO timestamp as a short date, or an em dash. */
+export declare function formatPostmarkDate(iso: unknown): string;
+/**
+ * A status → CSS tone class for the status pill. The returned values are STATIC STRING
+ * LITERALS (never template-built) so they survive the bundler's minification and a UI
+ * verify can assert on the class the component actually emits.
+ */
+export declare function statusTone(value: string): string;
+/** Flatten a (possibly nested) value into label/value lines for the detail panel. */
+export type FlatLine = {
+    key: string;
+    value: string;
+    depth: number;
+};
+export declare function flattenPostmarkValue(value: unknown, prefix?: string, depth?: number, out?: FlatLine[]): FlatLine[];
+/** The nav sections the mirror renders, each bound to one REAL Postmark API path + its
+ *  collection key. Shared by the client (to fetch) and by tests (to assert the binding). */
+export type MirrorSection = {
+    key: string;
+    label: string;
+    path: string;
+    collection: string;
+    idKey: string;
+};
+export declare const POSTMARK_MIRROR_SECTIONS: MirrorSection[];
+/** Build the React/TSX mirror client to browser JS (Bun bundles TSX); memoized at module
+ *  scope so a pack on its own does exactly ONE `Bun.build`. */
+export declare function buildPostmarkMirrorClient(): Promise<string>;
+/** Serve the Postmark activity mirror (React app) over the twin's OWN REST API. */
+export declare function createPostmarkMirrorServer(options: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;
+/** The app-shell HTML (pure, for tests). The mirror itself is the React client. */
+export declare function postmarkMirrorHtml(): string;
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export declare function postmarkMirrorStyles(): Promise<string>;