@volter/twin-postmark 0.1.0

package/dist/src/postmark-mirror-ui.js

@@ -0,0 +1,207 @@
+// Postmark MIRROR UI — a Postmark-dashboard-like Activity view served as a React/TSX app
+// (Bun-bundled, the repo convention).
+//
+// TRANSPORT: archetype A, API PASSTHROUGH (ADDING_A_TWIN "Does this vendor get a mirror?").
+// Every non-asset request falls straight through to the pack's OWN FETCH ADAPTER, and the
+// browser client fetches POSTMARK'S OWN REAL API PATHS — `/messages/outbound`,
+// `/messages/outbound/:id/details`, `/bounces`, `/templates`, `/message-streams`,
+// `/webhooks`, `/message-streams/outbound/suppressions/dump`. There is exactly ONE code path
+// serving the screen and the API, so API↔UI parity cannot drift: it is not "kept in sync",
+// it is the same handler. (Resend needed a `/_twin/emails` side-read only because Resend has
+// no list-emails endpoint; Postmark's Messages API does, so no side projection exists here.)
+//
+// The pure render/format helpers below are framework-agnostic so they can be unit-tested AND
+// imported by the browser client — Bun tree-shakes the server-only exports out of the bundle.
+//
+// PURE FRONTEND (R3): the mirror imports no handler and no twin internals — it MOUNTS the pack's
+// own fetch adapter as its API backend and reads every byte of state back over the wire.
+import { readFile } from 'node:fs/promises';
+import { bundleClient, fileResponse } from '@volter/world-core';
+import { serveHttp } from '@volter/world-core';
+import { createPostmarkTwinFetch } from "./postmark-server.js";
+const CLIENT_ENTRY = () => new URL('../client/postmark-mirror.tsx', import.meta.url).pathname; // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+const CLIENT_CSS = () => new URL('../client/postmark-mirror.css', import.meta.url).pathname; // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+/** The recipients of an outbound message, as a readable list. */
+export function recipientsOf(m) {
+    if (Array.isArray(m?.Recipients))
+        return m.Recipients.map(String).join(', ');
+    if (Array.isArray(m?.To))
+        return m.To.map((r) => String(r?.Email ?? '')).filter(Boolean).join(', ');
+    if (typeof m?.To === 'string')
+        return m.To;
+    return '';
+}
+/** A subject line for a message row, or a placeholder. */
+export function messageSubject(m) {
+    return m?.Subject ? String(m.Subject) : '(no subject)';
+}
+/** The ordered `MessageEvents` types the twin recorded for a message. */
+export function deliveryTimeline(m) {
+    const events = Array.isArray(m?.MessageEvents) ? m.MessageEvents : [];
+    return ['Sent', ...events.map((e) => String(e?.Type ?? ''))].filter(Boolean);
+}
+/**
+ * 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 function messageStatus(m) {
+    const timeline = deliveryTimeline(m);
+    const last = timeline[timeline.length - 1];
+    return last && last !== 'Sent' ? last : String(m?.Status ?? 'Sent');
+}
+/** The rendered preview of a message body — prefers HtmlBody, falls back to TextBody. */
+export function messagePreview(m) {
+    if (m?.HtmlBody)
+        return { kind: 'html', value: String(m.HtmlBody) };
+    if (m?.TextBody)
+        return { kind: 'text', value: String(m.TextBody) };
+    return { kind: 'none', value: '' };
+}
+/** Format an ISO timestamp as a short date, or an em dash. */
+export function formatPostmarkDate(iso) {
+    if (typeof iso !== 'string' || !iso)
+        return '—';
+    const t = Date.parse(iso);
+    if (!Number.isFinite(t))
+        return '—';
+    try {
+        return new Date(t).toISOString().slice(0, 16).replace('T', ' ');
+    }
+    catch {
+        return '—';
+    }
+}
+/**
+ * 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 function statusTone(value) {
+    const v = String(value ?? '').toLowerCase();
+    if (['delivered', 'opened', 'linkclicked', 'sent', 'processed', 'verified', 'active', 'true'].includes(v))
+        return 'ok';
+    if (['queued', 'pending', 'scheduled', 'unconfirmed', 'false'].includes(v))
+        return 'warn';
+    if (['bounced', 'hardbounce', 'spamcomplaint', 'blocked', 'failed', 'suppressed', 'transient'].includes(v))
+        return 'bad';
+    return 'neutral';
+}
+export function flattenPostmarkValue(value, prefix = '', depth = 0, out = []) {
+    if (value === null || value === undefined) {
+        out.push({ key: prefix || '(value)', value: '—', depth });
+    }
+    else if (Array.isArray(value)) {
+        if (value.length === 0)
+            out.push({ key: prefix, value: '[]', depth });
+        else
+            value.forEach((v, i) => flattenPostmarkValue(v, `${prefix}[${i}]`, depth, out));
+    }
+    else if (typeof value === 'object') {
+        for (const [k, v] of Object.entries(value)) {
+            flattenPostmarkValue(v, prefix ? `${prefix}.${k}` : k, depth, out);
+        }
+    }
+    else {
+        out.push({ key: prefix || '(value)', value: String(value), depth });
+    }
+    return out;
+}
+export const POSTMARK_MIRROR_SECTIONS = [
+    { key: 'messages', label: 'Activity', path: '/messages/outbound', collection: 'Messages', idKey: 'MessageID' },
+    { key: 'bounces', label: 'Bounces', path: '/bounces', collection: 'Bounces', idKey: 'ID' },
+    { key: 'templates', label: 'Templates', path: '/templates', collection: 'Templates', idKey: 'TemplateId' },
+    { key: 'streams', label: 'Streams', path: '/message-streams', collection: 'MessageStreams', idKey: 'ID' },
+    { key: 'webhooks', label: 'Webhooks', path: '/webhooks', collection: 'Webhooks', idKey: 'ID' },
+    { key: 'suppressions', label: 'Suppressions', path: '/message-streams/outbound/suppressions/dump', collection: 'Suppressions', idKey: 'EmailAddress' },
+];
+// ---------------------------------------------------------------------------
+// Server-only (Bun) below — NOT imported by the browser client.
+// ---------------------------------------------------------------------------
+const APP_SHELL = `<!doctype html><html lang="en"><head><meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<base href="/"><title>Postmark twin — activity mirror</title>
+<link rel="stylesheet" href="assets/styles.css" /></head>
+<body><div id="root"></div><script type="module" src="assets/app.js"></script></body></html>`;
+let clientBundle = null;
+/** 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 function buildPostmarkMirrorClient() {
+    if (!clientBundle) {
+        clientBundle = bundleClient(CLIENT_ENTRY())
+            .catch((error) => { clientBundle = null; throw error; });
+    }
+    return clientBundle;
+}
+/**
+ * The mirror's first-party credential, added to a request the adapter is about to serve.
+ *
+ * A pure REQUEST REWRITE — the mirror never calls the handler and never reaches around the wire;
+ * it only fills in the token header a browser cannot carry (Postmark authenticates every route
+ * with `X-Postmark-Server-Token`, or `X-Postmark-Account-Token` on its account-scoped families).
+ * The console is signed in to ITS root, so any non-empty token does — deliberately NOT the
+ * vendor's public test token, which is /email-only and changes the send reply text. Headers
+ * already present are left alone, so a caller that brings its own token keeps it.
+ */
+const MIRROR_TOKEN = 'postmark-twin-mirror-token';
+async function withMirrorCredentials(request) {
+    const headers = new Headers(request.headers);
+    if (!headers.has('x-postmark-server-token'))
+        headers.set('x-postmark-server-token', MIRROR_TOKEN);
+    if (!headers.has('x-postmark-account-token'))
+        headers.set('x-postmark-account-token', MIRROR_TOKEN);
+    const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
+    return new Request(request.url, {
+        method: request.method,
+        headers,
+        ...(hasBody ? { body: await request.text() } : {}),
+    });
+}
+/** Serve the Postmark activity mirror (React app) over the twin's OWN REST API. */
+export async function createPostmarkMirrorServer(options) {
+    const twin = createPostmarkTwinFetch(options);
+    const server = await serveHttp({
+        // LOOPBACK-SPECIFIC bind (2026-08-20, the roving ui-verify flake): with the default
+        // wildcard hostname, `port: 0` can be handed a port some long-running app already LISTENS
+        // on at 127.0.0.1 (SO_REUSEADDR allows the overlapping non-identical bind), and the more
+        // specific loopback listener then shadows this server for every 127.0.0.1 fetch — the
+        // verify talks to a STRANGER (captured: a desktop app's asset server answering 404s on the
+        // mirror's port). Binding 127.0.0.1 makes the kernel allocate a port that is actually free
+        // on loopback, so the verify's fetches deterministically reach THIS server.
+        hostname: '127.0.0.1',
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        async fetch(request) {
+            const url = new URL(request.url);
+            if (request.method === 'GET' && url.pathname === '/assets/app.js') {
+                try {
+                    return new Response(await buildPostmarkMirrorClient(), { headers: { 'content-type': 'text/javascript; charset=utf-8' } });
+                }
+                catch (error) {
+                    return new Response(String(error), { status: 500 });
+                }
+            }
+            if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
+                return fileResponse(CLIENT_CSS(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+            }
+            if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '')) {
+                return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+            }
+            // Everything else → the twin's OWN FETCH ADAPTER (composition, R2): the same closure
+            // `createPostmarkTwinServer` serves, so the mirror port and the API port cannot drift — the
+            // uniform `GET /twin` door, the world clock, `readOnly`, Postmark's token auth and the
+            // `connection: close` Bun-socket workaround all come from it rather than from a hand-rolled
+            // copy that has to be kept in step. The client fetches the vendor's real paths, so the
+            // mirror and an SDK consumer are served by literally the same code (archetype A).
+            return twin(await withMirrorCredentials(request));
+        },
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}
+/** The app-shell HTML (pure, for tests). The mirror itself is the React client. */
+export function postmarkMirrorHtml() {
+    return APP_SHELL;
+}
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export function postmarkMirrorStyles() {
+    return readFile(CLIENT_CSS(), 'utf8');
+}

package/dist/src/postmark-perform-harness.d.ts

@@ -0,0 +1,9 @@
+import { type PostmarkClient } from './postmark-connector.js';
+export declare function performPending(client: PostmarkClient, opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<{
+    pushed: number;
+    confirmed: string[];
+    externalIds: Record<string, string>;
+}>;

package/dist/src/postmark-perform-harness.js

@@ -0,0 +1,24 @@
+// A MINIATURE OF THE HEAD, for this pack's own claims and suites (protocol 2). Not on the serve path.
+import { confirmAction, deployableEntries, worldNow } from '@volter/world-core';
+import { pushPostmarkAction } from "./postmark-connector.js";
+export async function performPending(client, opts = {}) {
+    const confirmed = [];
+    const externalIds = {};
+    for (const entry of deployableEntries('postmark', opts.root)) {
+        let externalId;
+        try {
+            ({ externalId } = await pushPostmarkAction(client, { operation: entry.operation ?? `${entry.subject.type}.update`, subject: entry.subject, fields: entry.fields ?? {} }));
+        }
+        catch {
+            continue;
+        } // the twin's own record: nothing to write
+        confirmAction({
+            service: 'postmark', actionId: entry.id, subject: entry.subject, fields: entry.fields ?? {},
+            occurredAt: opts.occurredAt ?? worldNow(), vendorSubjectId: externalId, receipt: { status: 'deployed' },
+            ...(opts.root !== undefined ? { root: opts.root } : {}),
+        });
+        confirmed.push(entry.id);
+        externalIds[entry.id] = externalId;
+    }
+    return { pushed: confirmed.length, confirmed, externalIds };
+}

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

@@ -0,0 +1,14 @@
+/** Options every Postmark-twin HTTP surface needs, independent of who owns the socket. */
+export interface PostmarkTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+}
+export declare function createPostmarkTwinFetch(options: PostmarkTwinFetchOptions): (request: Request) => Promise<Response>;
+export declare function createPostmarkTwinServer(options: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/postmark-server.js

@@ -0,0 +1,29 @@
+// Postmark twin HTTP server — serve the full Postmark API twin handler over HTTP so the real
+// `postmark` SDK (pointed at this base URL) works unmodified. JSON bodies pass through to the
+// handler. Writable by default; pass readOnly to reject writes (D3).
+//
+// FETCH-FIRST (runtime contract R12b): the serve path is the plain fetch below, built from the
+// kernel's ONE adaptation (`createTwinFetchFromHandler`); this file contributes only VALUES —
+// the manifest and the `connection: close` response header. The server is one line of Bun.serve
+// around that same closure.
+import { serveHttp } from '@volter/world-core';
+import { handlePostmarkTwinRequest } from "./postmark-twin.js";
+import { createTwinFetchFromHandler, statefulTwinManifest } from '@volter/world-core';
+export function createPostmarkTwinFetch(options) {
+    return createTwinFetchFromHandler(handlePostmarkTwinRequest, {
+        ...options,
+        manifest: statefulTwinManifest({ vendor: 'postmark', twinOf: 'the Postmark transactional-email API', stores: 'servers, sent messages and their opens/deliveries (the mirror shows the inbox)' }),
+        // The official SDK's Node transport reuses sockets. Bun 1.2 can reject a later request on
+        // that socket with its own HTTP 400 before fetch() runs; closing makes each modeled request
+        // reach the handler. (Inert under workerd, which owns its own connection handling.)
+        responseHeaders: { connection: 'close' },
+    });
+}
+export async function createPostmarkTwinServer(options) {
+    const server = await serveHttp({
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        fetch: createPostmarkTwinFetch(options),
+    });
+    return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

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

@@ -0,0 +1,82 @@
+import { type PostmarkWebhookDelivery } from './postmark-events.js';
+export type PostmarkRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    occurredAt?: string;
+    root?: string;
+    readOnly?: boolean;
+    /** Injected webhook deliverer (fake in tests, HTTP live). Keeps verify() offline. */
+    deliver?: PostmarkWebhookDelivery;
+    /**
+     * Request headers (case-insensitive). When PRESENT (the HTTP server always supplies them),
+     * the twin enforces Postmark's token auth: a missing/empty `X-Postmark-Server-Token` (or
+     * `X-Postmark-Account-Token` on account routes) → 401 `{ErrorCode:10}`. When the whole
+     * object is ABSENT, auth is not exercised — the in-process verify()/mirror path is a
+     * trusted local call, mirroring the resend pack's convention.
+     */
+    headers?: Record<string, string>;
+};
+export type PostmarkResponse = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+/**
+ * The Postmark `ErrorCode` values this twin emits, each with the HTTP status the vendor
+ * pairs it with. Every number + status here is transcribed from developer.postmarkapp.com's
+ * published API-error-codes table (see the GROUNDING note above). Note how few of these are
+ * 404: Postmark answers "not found" for a KNOWN route with 422 + a per-domain code, and
+ * reserves 404 for a route that does not exist at all.
+ */
+export declare const POSTMARK_ERRORS: {
+    readonly ok: 0;
+    readonly badToken: 10;
+    readonly bulkNotApproved: 14;
+    readonly invalidEmailRequest: 300;
+    readonly invalidJson: 402;
+    readonly invalidRequestField: 403;
+    readonly inactiveRecipient: 406;
+    readonly tooManyBatchMessages: 410;
+    readonly signatureNotFound: 501;
+    readonly signatureNoData: 502;
+    readonly publicDomainSignature: 503;
+    readonly signatureExists: 504;
+    readonly domainNotFound: 510;
+    readonly domainExists: 512;
+    readonly domainNameRequired: 514;
+    readonly fromEmailRequired: 520;
+    readonly invalidEmailValue: 522;
+    readonly serverInboundDomainInUse: 602;
+    readonly serverNameExists: 603;
+    readonly serverNameInvalid: 608;
+    readonly serverNoData: 609;
+    readonly serverNotFound: 1453;
+    readonly messageNotFound: 701;
+    readonly inboundRuleNoData: 809;
+    readonly inboundRuleExists: 810;
+    readonly inboundRuleNotFound: 812;
+    readonly bounceNotFound: 1001;
+    readonly bounceCannotActivate: 1003;
+    readonly templateNotFound: 1101;
+    readonly templateNoData: 1109;
+    readonly streamTypeInvalid: 1221;
+    readonly streamNameRequired: 1223;
+    readonly streamNotFound: 1226;
+    readonly streamIdInvalid: 1227;
+    readonly streamCannotArchiveDefault: 1229;
+    readonly streamIdExists: 1230;
+    readonly streamCannotArchive: 1241;
+    readonly streamCannotUnarchive: 1232;
+    readonly streamIdReservedPrefix: 1233;
+    readonly sendStreamNotFound: 1235;
+    readonly dataRemovalIdInvalid: 1301;
+    readonly webhookArchivedStream: 1350;
+    readonly webhookNotFound: 1352;
+    readonly webhookUrlRequired: 1354;
+    readonly suppressionAuthority: 1406;
+    readonly suppressionInvalidEmail: 1408;
+    readonly suppressionNoBody: 1409;
+};
+export declare function handlePostmarkTwinRequest(req: PostmarkRequest): Promise<PostmarkResponse>;
+export declare const POSTMARK_RESOURCE_TYPES: readonly ["message", "bounce", "template", "message_stream", "webhook", "suppression", "server", "domain", "sender_signature", "inbound_rule", "inbound_message", "data_removal"];