@volter/twin-postmark 0.1.0

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@volter/twin-postmark",
+  "version": "0.1.0",
+  "description": "Local Postmark twin — a faithful, stateful local Postmark transactional-email API your real `postmark` SDK talks to unmodified. Plain/templated/batch sends, outbound + inbound message activity, bounces and delivery stats, templates, message streams, suppressions, webhooks, servers, domains and sender signatures. Deterministic offline delivery lifecycle and Postmark's real (unsigned, Basic-auth/custom-header) webhooks. Activity mirror UI. Built on @volter/world-core.",
+  "keywords": [
+    "twin",
+    "local",
+    "mock",
+    "mirror",
+    "simulator",
+    "fixtures",
+    "testing",
+    "sdk",
+    "api",
+    "localstack",
+    "postmark",
+    "email",
+    "transactional-email",
+    "webhooks"
+  ],
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "client",
+    "test-fixtures",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/postmark"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/postmark#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-postmark": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "dependencies": {
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "postmark": "^4.0.5",
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-postmark CLI: serve the Postmark API twin, the activity mirror UI, or run conformance.
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createPostmarkTwinServer } from './postmark-server.ts';
+import { createPostmarkMirrorServer } from './postmark-mirror-ui.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+
+if (cmd === 'serve') {
+  const s = await createPostmarkTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`postmark twin (transactional email API)${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'mirror') {
+  const s = await createPostmarkMirrorServer({ ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`postmark mirror UI (activity) at http://127.0.0.1:${s.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  // dev-only; lazy so the bin runs without @volter/world-tooling
+  const { checkPostmarkConformance, postmarkCoverage } = await import('./postmark-conformance.ts');
+  const report = checkPostmarkConformance({ ...(root ? { root } : {}) });
+  process.stdout.write(`${JSON.stringify({ ...report, coverage: postmarkCoverage({ ...(root ? { root } : {}) }) }, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-postmark serve|mirror|conformance [--port N] [--root DIR] [--read-only]\n');
+}

package/src/index.ts

@@ -0,0 +1,89 @@
+// @volter/twin-postmark — the Postmark transactional-email API twin (one vendor, one
+// package), built on the shared @volter/world-core kernel. REST transport over
+// api.postmarkapp.com shapes, `X-Postmark-Server-Token` / `X-Postmark-Account-Token` auth, a
+// deterministic OFFLINE delivery lifecycle that writes real `MessageEvents` and mints Bounce
+// records + suppressions, Postmark's real (unsigned, Basic-auth/custom-header) webhooks, and
+// a React activity-mirror UI. (Conformance/capability tooling lives in @volter/world-tooling,
+// a dev dependency — NOT shipped in the runtime API.)
+export { handlePostmarkTwinRequest, POSTMARK_ERRORS, POSTMARK_RESOURCE_TYPES } from './postmark-twin.ts';
+export type { PostmarkRequest, PostmarkResponse } from './postmark-twin.ts';
+export { createPostmarkTwinFetch, createPostmarkTwinServer, type PostmarkTwinFetchOptions } from './postmark-server.ts';
+export {
+  deliveryPlan,
+  emitPostmarkWebhook,
+  POSTMARK_RECORD_TYPES,
+  terminalEvent,
+  webhookHeaders,
+  webhooksFor,
+} from './postmark-events.ts';
+export type { PostmarkEventType, PostmarkRecordType, PostmarkWebhookDelivery, WebhookContext } from './postmark-events.ts';
+export {
+  mapBounce,
+  mapMessage,
+  mapMessageStream,
+  mapServer,
+  mapTemplate,
+  mapWebhook,
+  pullPostmarkBounces,
+  pullPostmarkMessages,
+  pullPostmarkMessageStreams,
+  pullPostmarkServer,
+  pullPostmarkTemplates,
+  pullPostmarkWebhooks,
+  pushPostmarkAction,
+  syncPostmarkFromReal,
+} from './postmark-connector.ts';
+export type {
+  PostmarkBounce, PostmarkClient, PostmarkMessageStream, PostmarkOutboundMessage,
+  PostmarkServer, PostmarkTemplate, PostmarkWebhookConfig,
+} from './postmark-connector.ts';
+export {
+  buildPostmarkMirrorClient,
+  createPostmarkMirrorServer,
+  POSTMARK_MIRROR_SECTIONS,
+  postmarkMirrorHtml,
+} from './postmark-mirror-ui.ts';
+
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack, type TwinPack } from '@volter/world-core';
+import { performPostmarkAction, syncPostmarkFromRemote } from './postmark-connector.ts';
+
+export const pack: TwinPack = {
+  // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of the real
+  // state system. Moved 2026-09-08.
+  protocol: '2',
+  refresh: { every: '5m', webhook: true, onDemand: { atMost: '30s' } },
+  stateSystem: { perform: performPostmarkAction, refresh: syncPostmarkFromRemote },
+  // the round trip: send a message — Postmark's own write, and a fresh id each time
+  roundTrip: { method: 'POST', path: '/email', body: { From: 'round@trip.test', To: 'round@trip.test', Subject: 'round trip', TextBody: 'round trip' }, headers: { 'x-postmark-server-token': 'round-trip' } },
+  parityOrigin: 'http://twin',
+  vendor: 'postmark',
+  transport: 'rest',
+  archetype: 'crud',
+  bin: 'world-postmark',
+  resources: ['message', 'bounce', 'template', 'message_stream', 'webhook', 'suppression', 'server', 'domain', 'sender_signature', 'inbound_rule'],
+  specSource: 'postmark-conformance.ts (inline per-object JSON Schemas derived from the official `postmark` SDK models + developer.postmarkapp.com)',
+  description: 'Postmark transactional email API twin — send/template/batch sends, outbound message activity, bounces + delivery stats, templates, message streams, suppressions, webhooks, domains and sender signatures, with an activity mirror UI.',
+  // Adoption + interception, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+  // 2026-08-31): the official `postmark` npm client and the POSTMARK_* credential
+  // stem, and the one API host the SDK talks to.
+  adoption: {
+    // COMMUNITY: Postmark ships no official Python SDK; `postmarker` is the de-facto client of the
+    // same api.postmarkapp.com surface.
+    pypi: ['postmarker'],
+    sdks: ['postmark'], envStems: ['POSTMARK'],
+  },
+  hosts: [{ host: 'api.postmarkapp.com' }],
+  // No `browserRouting` — deliberately, for two independent reasons (the algolia precedent).
+  // 1. Postmark is a SERVER-SIDE API: the server/account tokens are secrets and there is no
+  //    browser SDK, so forwarding it from a browser dev proxy is not a flow that exists.
+  // 2. There is no single stripeable API path prefix to route on. Postmark's routes sit at
+  //    the ROOT — /email, /messages/*, /bounces, /templates, /message-streams, /webhooks,
+  //    /stats/*, /domains, /senders — so any prefix narrow enough to be meaningful (e.g.
+  //    '/messages/') would silently fail to forward the headline /email send, and the only
+  //    prefix that covers everything is '/', which would capture the app's own routes too.
+  // Node-side zero-edit injection is unaffected: POSTMARK_TWIN_URL + the control-plane
+  // injector's `api.postmarkapp.com` matcher redirect the real SDK with no code change.
+};
+// registered at import: the kernel learns the pack's state system (protocol 2)
+registerPack(pack);