@shware/workflow 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shware Inc.
+
+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

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+# @shware/workflow
 
-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.
+Code-first customer journeys. Workflows are written as TypeScript, compiled to a
+versioned IR, and executed by a single generic runner: the IR is data, so one
+deployed Worker runs every journey.
+
+```ts
+const welcome = workflow({ id: 'welcome', trigger: trigger.event(e.sign_up) })
+  .email(gettingStarted)
+  .delay('3 days')
+  .waitUntil(performed(e.activated), {
+    timeout: '7 days',
+    onTimeout: (w) => w.email(nudge),
+  });
+```
+
+## The three planes
+
+| Plane     | What it is                                 | Where it lives                |
+| --------- | ------------------------------------------ | ----------------------------- |
+| Authoring | The DSL, compiled to IR by `compileBundle` | `@shware/workflow`            |
+| Execution | The interpreter, over abstract ports       | `@shware/workflow/engine`     |
+| Adapter   | Cloudflare bindings, ingest, runner        | `@shware/workflow/cloudflare` |
+
+The interpreter never touches a database or a network. Everything it needs
+arrives through the ports in `engine/ports.ts`, which is what makes a journey
+testable without deploying one.
+
+## Versioning
+
+Every workflow carries a `contentHash` over its own IR, with metadata excluded,
+so a reworded description is not a new version but a changed delay is. The hash
+is the KV address the IR is stored under, and a journey is pinned to the hash it
+entered on. An in-flight journey therefore finishes on the version it started,
+however many times you deploy underneath it.
+
+`plan()` diffs a compiled bundle against what is deployed and reports which
+workflows actually changed. Deploy recomputes every declared hash and refuses a
+bundle whose hashes do not describe its contents.
+
+## Cloudflare setup
+
+The adapter needs three bindings, named as in `JourneyEnv`:
+
+| Binding       | Type         | Holds                                     |
+| ------------- | ------------ | ----------------------------------------- |
+| `WORKFLOW_KV` | KV namespace | Compiled IR, content-addressed by hash    |
+| `DB`          | D1 database  | Events, profiles, routing, entries, wakes |
+| `JOURNEY`     | Workflow     | The `JourneyRunner` entrypoint            |
+
+Set `API_TOKEN` in production. Without it every mutating endpoint is open, and
+`/deploy` rewrites the whole routing table.
+
+The D1 schema ships with the package. Apply it before the first deploy:
+
+```bash
+wrangler d1 execute <database> --file node_modules/@shware/workflow/dist/cloudflare/schema.sql
+```
+
+Nothing in the adapter creates these tables at runtime, so this step is not
+optional. The same file lives at `src/cloudflare/schema.sql` in this repo and is
+the single source for both.
+
+There are no migrations, and re-applying the file is not one: every statement is
+`CREATE TABLE IF NOT EXISTS`, so an existing database keeps its old tables and
+the first insert needing a new column fails. Recreate it instead. The demo has
+`pnpm db:reset`.
+
+## Postgres
+
+A host on Postgres (through Hyperdrive, say) keeps Cloudflare Workflows for
+execution and the data in its own database:
+
+```ts
+const journeys = journeyWorker<Env>({
+  config,
+  store: (env, database) => postgresJsStore(env.HYPERDRIVE.connectionString, database),
+});
+export default { fetch: journeys.fetch, scheduled: journeys.scheduled };
+```
+
+The engine's tables live in one Postgres schema, `workflow` unless the config
+says `database: { schema }`, so their short names never meet the app's. The
+host owns the migrations. `npx workflow-ui generate --out <file>` (from
+`@shware/workflow-ui`) writes the tables as one drizzle file on that schema;
+re-export it from your drizzle schema and let drizzle-kit write the migration.
+Run `--check` in CI to catch an SDK upgrade that changed them. Without drizzle,
+`renderPostgresDdl()` returns the same tables as plain DDL. Nothing creates or
+alters them at runtime: `POST /bundle/deploy` checks the live database first
+and answers 503 with every missing table or column.
+
+On Postgres the engine also keeps:
+
+- **Push devices.** The app registers each token with
+  `JourneyClient.registerDevice(userId, { token, platform })` and forgets one
+  with `removeDevice(token)`. Tokens APNs / FCM report as gone are dropped.
+- **Reporting.** Instances, every message copy, opens and clicks, recorded
+  by the default observer. With `WORKFLOW_ORIGIN` set, email links and an open
+  pixel are tracked through the Worker's `/t/...` routes. Each open and click
+  is classified as a person's or a machine's (Apple Mail Privacy Protection,
+  link scanners, prefetches). `emails.unsubscribe` gets a confirmation page.
+  A push carries `message_id`; report the tap with `messageOpened`.
+- **Segments.** The cron trigger runs `sweepSegments`, which keeps every
+  segment's membership and size and starts the journeys of segments entered by
+  the clock alone. `POST /segments/sweep` runs it on demand.
+
+`@shware/workflow-ui/postgres` reads all of it for the studio.
+
+## HTTP surface
+
+`handleRequest` serves four endpoints.
+
+- `GET /health` is the only unauthenticated one.
+- `POST /events` takes `{ userId, event, payload?, ts?, id? }` and answers with
+  the id the occurrence was recorded under. Event names beginning with `$` are
+  reserved for internal use.
+- `POST /identify` takes `{ userId, props }` and merges the properties into the
+  profile. A property set to `null` is removed, which is the only way to unset
+  one.
+- `POST /deploy` takes a compiled bundle and swaps the routing table atomically.
+
+### Give each event an `id`
+
+`id` is the occurrence's identity, and sending the same one twice records it
+once. This matters because every count- and window-based condition reads the
+event log, so a second copy of one event silently changes what a journey
+decides.
+
+Only the sender knows whether two deliveries describe one occurrence or two, so
+the engine never guesses. An event that arrives without an id is given a fresh
+one, which records it as its own occurrence. If you retry a request, send an id
+you can reproduce and the retry costs nothing.
+
+```json
+{ "id": "order-8841-confirmed", "userId": "u_123", "event": "purchase" }
+```
+
+Use something that identifies the occurrence, not the event name: a row id from
+your own system, an upstream webhook's delivery id, or a message id from your
+queue. Workflows emitting events through `send_event` already do this, passing
+the node's identity within the running instance.
+
+## Entry policy
+
+A user enters a workflow at most once. The entry ledger's primary key enforces
+it, which also makes the check atomic under concurrent ingests. The one
+exception is an entry whose instance died: that row records a failure, not a
+journey the user received, so the next trigger reclaims it. Re-entry beyond that
+is a design question this package does not yet answer.
+
+## Testing
+
+See [TESTING.md](./TESTING.md). The interpreter runs against in-memory ports and
+the Cloudflare adapter against fakes that dispatch on the exact SQL strings the
+real code sends, so changing a query means updating the fake, deliberately.

package/dist/_virtual/_rolldown/runtime.cjs

@@ -0,0 +1,23 @@
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+//#endregion
+exports.__toESM = __toESM;

package/dist/apns-relay.cjs

@@ -0,0 +1,105 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_http = require("node:http");
+let node_http2 = require("node:http2");
+//#region src/apns-relay.ts
+const DEFAULT_ALLOW = ["https://api.push.apple.com", "https://api.sandbox.push.apple.com"];
+/** Request headers APNs reads; everything else (host, content-length, …) is the relay's own business. */
+const FORWARDED = [
+	"authorization",
+	"apns-topic",
+	"apns-push-type",
+	"apns-priority",
+	"apns-expiration",
+	"apns-collapse-id",
+	"apns-id",
+	"content-type"
+];
+function startApnsRelay(options) {
+	const allow = new Set(options.allow ?? DEFAULT_ALLOW);
+	const sessions = /* @__PURE__ */ new Map();
+	function session(upstream) {
+		const existing = sessions.get(upstream);
+		if (existing !== void 0 && !existing.closed && !existing.destroyed) return existing;
+		const created = (0, node_http2.connect)(upstream);
+		const forget = () => {
+			if (sessions.get(upstream) === created) sessions.delete(upstream);
+		};
+		created.on("error", forget);
+		created.on("close", forget);
+		sessions.set(upstream, created);
+		return created;
+	}
+	function relay(req, res) {
+		const upstreamHeader = req.headers["apns-relay-upstream"];
+		const upstream = Array.isArray(upstreamHeader) ? upstreamHeader[0] : upstreamHeader;
+		if (upstream === void 0 || !allow.has(upstream)) {
+			res.writeHead(400, { "content-type": "application/json" });
+			res.end(JSON.stringify({
+				reason: "RelayUpstreamNotAllowed",
+				upstream: upstream ?? null
+			}));
+			return;
+		}
+		const chunks = [];
+		req.on("data", (chunk) => chunks.push(chunk));
+		req.on("end", () => {
+			const headers = {
+				":method": req.method ?? "POST",
+				":path": req.url ?? "/"
+			};
+			for (const name of FORWARDED) {
+				const value = req.headers[name];
+				if (typeof value === "string") headers[name] = value;
+			}
+			let stream;
+			try {
+				stream = session(upstream).request(headers);
+			} catch (error) {
+				res.writeHead(502, { "content-type": "application/json" });
+				res.end(JSON.stringify({
+					reason: "RelayConnectFailed",
+					error: String(error)
+				}));
+				return;
+			}
+			const body = [];
+			stream.on("response", (responseHeaders) => {
+				const status = responseHeaders[":status"] ?? 502;
+				const apnsId = responseHeaders["apns-id"];
+				res.writeHead(status, {
+					"content-type": "application/json",
+					...typeof apnsId === "string" ? { "apns-id": apnsId } : {}
+				});
+			});
+			stream.on("data", (chunk) => body.push(chunk));
+			stream.on("end", () => res.end(Buffer.concat(body)));
+			stream.on("error", (error) => {
+				if (!res.headersSent) res.writeHead(502, { "content-type": "application/json" });
+				res.end(JSON.stringify({
+					reason: "RelayUpstreamError",
+					error: String(error)
+				}));
+			});
+			stream.end(Buffer.concat(chunks));
+		});
+	}
+	const server = (0, node_http.createServer)(relay);
+	return new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(options.port, options.hostname ?? "127.0.0.1", () => {
+			const address = server.address();
+			resolve({
+				port: typeof address === "object" && address !== null ? address.port : options.port,
+				close: () => new Promise((done) => {
+					for (const open of sessions.values()) open.close();
+					sessions.clear();
+					server.close(() => done());
+				})
+			});
+		});
+	});
+}
+//#endregion
+exports.startApnsRelay = startApnsRelay;
+
+//# sourceMappingURL=apns-relay.cjs.map

package/dist/apns-relay.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apns-relay.cjs","names":["connect","createServer"],"sources":["../src/apns-relay.ts"],"sourcesContent":["import { type IncomingMessage, type ServerResponse, createServer } from 'node:http';\nimport { type ClientHttp2Session, connect } from 'node:http2';\n\n/**\n * `@shware/workflow/apns-relay` — a development-only HTTP/1.1 → HTTP/2 relay\n * for APNs, run under Node next to `wrangler dev`.\n *\n * APNs accepts HTTP/2 only, and workerd (the local Workers runtime) cannot\n * make an HTTP/2 subrequest, so a journey that pushes to an iPhone from a\n * local Worker has nowhere to go. A deployed Worker needs none of this: its\n * `fetch` negotiates HTTP/2 with Apple. The relay forwards each request to the\n * origin named in its `apns-relay-upstream` header (the sender sets it along\n * with `origin`), keeping one HTTP/2 session per upstream.\n *\n * Only Apple's two hosts are relayed by default; `allow` widens that for tests.\n */\n\nexport interface ApnsRelayOptions {\n  port: number;\n  /** Interface to listen on; loopback by default — the relay has no auth of its own. */\n  hostname?: string;\n  /** Upstream origins that may be relayed; Apple's production and sandbox hosts by default. */\n  allow?: readonly string[];\n}\n\nexport interface ApnsRelay {\n  port: number;\n  close(): Promise<void>;\n}\n\nconst DEFAULT_ALLOW = ['https://api.push.apple.com', 'https://api.sandbox.push.apple.com'];\n\n/** Request headers APNs reads; everything else (host, content-length, …) is the relay's own business. */\nconst FORWARDED = [\n  'authorization',\n  'apns-topic',\n  'apns-push-type',\n  'apns-priority',\n  'apns-expiration',\n  'apns-collapse-id',\n  'apns-id',\n  'content-type',\n];\n\nexport function startApnsRelay(options: ApnsRelayOptions): Promise<ApnsRelay> {\n  const allow = new Set(options.allow ?? DEFAULT_ALLOW);\n  const sessions = new Map<string, ClientHttp2Session>();\n\n  function session(upstream: string): ClientHttp2Session {\n    const existing = sessions.get(upstream);\n    if (existing !== undefined && !existing.closed && !existing.destroyed) return existing;\n    const created = connect(upstream);\n    const forget = () => {\n      if (sessions.get(upstream) === created) sessions.delete(upstream);\n    };\n    created.on('error', forget);\n    created.on('close', forget);\n    sessions.set(upstream, created);\n    return created;\n  }\n\n  function relay(req: IncomingMessage, res: ServerResponse): void {\n    const upstreamHeader = req.headers['apns-relay-upstream'];\n    const upstream = Array.isArray(upstreamHeader) ? upstreamHeader[0] : upstreamHeader;\n    if (upstream === undefined || !allow.has(upstream)) {\n      res.writeHead(400, { 'content-type': 'application/json' });\n      res.end(JSON.stringify({ reason: 'RelayUpstreamNotAllowed', upstream: upstream ?? null }));\n      return;\n    }\n\n    const chunks: Buffer[] = [];\n    req.on('data', (chunk: Buffer) => chunks.push(chunk));\n    req.on('end', () => {\n      const headers: Record<string, string> = {\n        ':method': req.method ?? 'POST',\n        ':path': req.url ?? '/',\n      };\n      for (const name of FORWARDED) {\n        const value = req.headers[name];\n        if (typeof value === 'string') headers[name] = value;\n      }\n      let stream;\n      try {\n        stream = session(upstream).request(headers);\n      } catch (error) {\n        res.writeHead(502, { 'content-type': 'application/json' });\n        res.end(JSON.stringify({ reason: 'RelayConnectFailed', error: String(error) }));\n        return;\n      }\n      const body: Buffer[] = [];\n      stream.on('response', (responseHeaders) => {\n        const status = responseHeaders[':status'] ?? 502;\n        const apnsId = responseHeaders['apns-id'];\n        res.writeHead(status, {\n          'content-type': 'application/json',\n          ...(typeof apnsId === 'string' ? { 'apns-id': apnsId } : {}),\n        });\n      });\n      stream.on('data', (chunk: Buffer) => body.push(chunk));\n      stream.on('end', () => res.end(Buffer.concat(body)));\n      stream.on('error', (error) => {\n        if (!res.headersSent) res.writeHead(502, { 'content-type': 'application/json' });\n        res.end(JSON.stringify({ reason: 'RelayUpstreamError', error: String(error) }));\n      });\n      stream.end(Buffer.concat(chunks));\n    });\n  }\n\n  const server = createServer(relay);\n  return new Promise((resolve, reject) => {\n    server.once('error', reject);\n    server.listen(options.port, options.hostname ?? '127.0.0.1', () => {\n      const address = server.address();\n      const port = typeof address === 'object' && address !== null ? address.port : options.port;\n      resolve({\n        port,\n        close: () =>\n          new Promise((done) => {\n            for (const open of sessions.values()) open.close();\n            sessions.clear();\n            server.close(() => done());\n          }),\n      });\n    });\n  });\n}\n"],"mappings":"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"}

package/dist/apns-relay.d.cts

@@ -0,0 +1,28 @@
+//#region src/apns-relay.d.ts
+/**
+ * `@shware/workflow/apns-relay` — a development-only HTTP/1.1 → HTTP/2 relay
+ * for APNs, run under Node next to `wrangler dev`.
+ *
+ * APNs accepts HTTP/2 only, and workerd (the local Workers runtime) cannot
+ * make an HTTP/2 subrequest, so a journey that pushes to an iPhone from a
+ * local Worker has nowhere to go. A deployed Worker needs none of this: its
+ * `fetch` negotiates HTTP/2 with Apple. The relay forwards each request to the
+ * origin named in its `apns-relay-upstream` header (the sender sets it along
+ * with `origin`), keeping one HTTP/2 session per upstream.
+ *
+ * Only Apple's two hosts are relayed by default; `allow` widens that for tests.
+ */
+export interface ApnsRelayOptions {
+  port: number;
+  /** Interface to listen on; loopback by default — the relay has no auth of its own. */
+  hostname?: string;
+  /** Upstream origins that may be relayed; Apple's production and sandbox hosts by default. */
+  allow?: readonly string[];
+}
+export interface ApnsRelay {
+  port: number;
+  close(): Promise<void>;
+}
+export declare function startApnsRelay(options: ApnsRelayOptions): Promise<ApnsRelay>;
+//#endregion
+//# sourceMappingURL=apns-relay.d.cts.map

package/dist/apns-relay.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apns-relay.d.cts","names":[],"sources":["../src/apns-relay.ts"],"mappings":";;;;;;;;;;;;;;iBAiBiB;EACf;;EAEA;;EAEA;;iBAGe;EACf;EACA,SAAS;;wBAiBK,eAAe,SAAS,mBAAmB,QAAQ"}

package/dist/apns-relay.d.mts

@@ -0,0 +1,28 @@
+//#region src/apns-relay.d.ts
+/**
+ * `@shware/workflow/apns-relay` — a development-only HTTP/1.1 → HTTP/2 relay
+ * for APNs, run under Node next to `wrangler dev`.
+ *
+ * APNs accepts HTTP/2 only, and workerd (the local Workers runtime) cannot
+ * make an HTTP/2 subrequest, so a journey that pushes to an iPhone from a
+ * local Worker has nowhere to go. A deployed Worker needs none of this: its
+ * `fetch` negotiates HTTP/2 with Apple. The relay forwards each request to the
+ * origin named in its `apns-relay-upstream` header (the sender sets it along
+ * with `origin`), keeping one HTTP/2 session per upstream.
+ *
+ * Only Apple's two hosts are relayed by default; `allow` widens that for tests.
+ */
+export interface ApnsRelayOptions {
+  port: number;
+  /** Interface to listen on; loopback by default — the relay has no auth of its own. */
+  hostname?: string;
+  /** Upstream origins that may be relayed; Apple's production and sandbox hosts by default. */
+  allow?: readonly string[];
+}
+export interface ApnsRelay {
+  port: number;
+  close(): Promise<void>;
+}
+export declare function startApnsRelay(options: ApnsRelayOptions): Promise<ApnsRelay>;
+//#endregion
+//# sourceMappingURL=apns-relay.d.mts.map

package/dist/apns-relay.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apns-relay.d.mts","names":[],"sources":["../src/apns-relay.ts"],"mappings":";;;;;;;;;;;;;;iBAiBiB;EACf;;EAEA;;EAEA;;iBAGe;EACf;EACA,SAAS;;wBAiBK,eAAe,SAAS,mBAAmB,QAAQ"}

package/dist/apns-relay.mjs

@@ -0,0 +1,104 @@
+import { createServer } from "node:http";
+import { connect } from "node:http2";
+//#region src/apns-relay.ts
+const DEFAULT_ALLOW = ["https://api.push.apple.com", "https://api.sandbox.push.apple.com"];
+/** Request headers APNs reads; everything else (host, content-length, …) is the relay's own business. */
+const FORWARDED = [
+	"authorization",
+	"apns-topic",
+	"apns-push-type",
+	"apns-priority",
+	"apns-expiration",
+	"apns-collapse-id",
+	"apns-id",
+	"content-type"
+];
+function startApnsRelay(options) {
+	const allow = new Set(options.allow ?? DEFAULT_ALLOW);
+	const sessions = /* @__PURE__ */ new Map();
+	function session(upstream) {
+		const existing = sessions.get(upstream);
+		if (existing !== void 0 && !existing.closed && !existing.destroyed) return existing;
+		const created = connect(upstream);
+		const forget = () => {
+			if (sessions.get(upstream) === created) sessions.delete(upstream);
+		};
+		created.on("error", forget);
+		created.on("close", forget);
+		sessions.set(upstream, created);
+		return created;
+	}
+	function relay(req, res) {
+		const upstreamHeader = req.headers["apns-relay-upstream"];
+		const upstream = Array.isArray(upstreamHeader) ? upstreamHeader[0] : upstreamHeader;
+		if (upstream === void 0 || !allow.has(upstream)) {
+			res.writeHead(400, { "content-type": "application/json" });
+			res.end(JSON.stringify({
+				reason: "RelayUpstreamNotAllowed",
+				upstream: upstream ?? null
+			}));
+			return;
+		}
+		const chunks = [];
+		req.on("data", (chunk) => chunks.push(chunk));
+		req.on("end", () => {
+			const headers = {
+				":method": req.method ?? "POST",
+				":path": req.url ?? "/"
+			};
+			for (const name of FORWARDED) {
+				const value = req.headers[name];
+				if (typeof value === "string") headers[name] = value;
+			}
+			let stream;
+			try {
+				stream = session(upstream).request(headers);
+			} catch (error) {
+				res.writeHead(502, { "content-type": "application/json" });
+				res.end(JSON.stringify({
+					reason: "RelayConnectFailed",
+					error: String(error)
+				}));
+				return;
+			}
+			const body = [];
+			stream.on("response", (responseHeaders) => {
+				const status = responseHeaders[":status"] ?? 502;
+				const apnsId = responseHeaders["apns-id"];
+				res.writeHead(status, {
+					"content-type": "application/json",
+					...typeof apnsId === "string" ? { "apns-id": apnsId } : {}
+				});
+			});
+			stream.on("data", (chunk) => body.push(chunk));
+			stream.on("end", () => res.end(Buffer.concat(body)));
+			stream.on("error", (error) => {
+				if (!res.headersSent) res.writeHead(502, { "content-type": "application/json" });
+				res.end(JSON.stringify({
+					reason: "RelayUpstreamError",
+					error: String(error)
+				}));
+			});
+			stream.end(Buffer.concat(chunks));
+		});
+	}
+	const server = createServer(relay);
+	return new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(options.port, options.hostname ?? "127.0.0.1", () => {
+			const address = server.address();
+			resolve({
+				port: typeof address === "object" && address !== null ? address.port : options.port,
+				close: () => new Promise((done) => {
+					for (const open of sessions.values()) open.close();
+					sessions.clear();
+					server.close(() => done());
+				})
+			});
+		});
+	});
+}
+//#endregion
+export { startApnsRelay };
+
+//# sourceMappingURL=apns-relay.mjs.map

package/dist/apns-relay.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apns-relay.mjs","names":[],"sources":["../src/apns-relay.ts"],"sourcesContent":["import { type IncomingMessage, type ServerResponse, createServer } from 'node:http';\nimport { type ClientHttp2Session, connect } from 'node:http2';\n\n/**\n * `@shware/workflow/apns-relay` — a development-only HTTP/1.1 → HTTP/2 relay\n * for APNs, run under Node next to `wrangler dev`.\n *\n * APNs accepts HTTP/2 only, and workerd (the local Workers runtime) cannot\n * make an HTTP/2 subrequest, so a journey that pushes to an iPhone from a\n * local Worker has nowhere to go. A deployed Worker needs none of this: its\n * `fetch` negotiates HTTP/2 with Apple. The relay forwards each request to the\n * origin named in its `apns-relay-upstream` header (the sender sets it along\n * with `origin`), keeping one HTTP/2 session per upstream.\n *\n * Only Apple's two hosts are relayed by default; `allow` widens that for tests.\n */\n\nexport interface ApnsRelayOptions {\n  port: number;\n  /** Interface to listen on; loopback by default — the relay has no auth of its own. */\n  hostname?: string;\n  /** Upstream origins that may be relayed; Apple's production and sandbox hosts by default. */\n  allow?: readonly string[];\n}\n\nexport interface ApnsRelay {\n  port: number;\n  close(): Promise<void>;\n}\n\nconst DEFAULT_ALLOW = ['https://api.push.apple.com', 'https://api.sandbox.push.apple.com'];\n\n/** Request headers APNs reads; everything else (host, content-length, …) is the relay's own business. */\nconst FORWARDED = [\n  'authorization',\n  'apns-topic',\n  'apns-push-type',\n  'apns-priority',\n  'apns-expiration',\n  'apns-collapse-id',\n  'apns-id',\n  'content-type',\n];\n\nexport function startApnsRelay(options: ApnsRelayOptions): Promise<ApnsRelay> {\n  const allow = new Set(options.allow ?? DEFAULT_ALLOW);\n  const sessions = new Map<string, ClientHttp2Session>();\n\n  function session(upstream: string): ClientHttp2Session {\n    const existing = sessions.get(upstream);\n    if (existing !== undefined && !existing.closed && !existing.destroyed) return existing;\n    const created = connect(upstream);\n    const forget = () => {\n      if (sessions.get(upstream) === created) sessions.delete(upstream);\n    };\n    created.on('error', forget);\n    created.on('close', forget);\n    sessions.set(upstream, created);\n    return created;\n  }\n\n  function relay(req: IncomingMessage, res: ServerResponse): void {\n    const upstreamHeader = req.headers['apns-relay-upstream'];\n    const upstream = Array.isArray(upstreamHeader) ? upstreamHeader[0] : upstreamHeader;\n    if (upstream === undefined || !allow.has(upstream)) {\n      res.writeHead(400, { 'content-type': 'application/json' });\n      res.end(JSON.stringify({ reason: 'RelayUpstreamNotAllowed', upstream: upstream ?? null }));\n      return;\n    }\n\n    const chunks: Buffer[] = [];\n    req.on('data', (chunk: Buffer) => chunks.push(chunk));\n    req.on('end', () => {\n      const headers: Record<string, string> = {\n        ':method': req.method ?? 'POST',\n        ':path': req.url ?? '/',\n      };\n      for (const name of FORWARDED) {\n        const value = req.headers[name];\n        if (typeof value === 'string') headers[name] = value;\n      }\n      let stream;\n      try {\n        stream = session(upstream).request(headers);\n      } catch (error) {\n        res.writeHead(502, { 'content-type': 'application/json' });\n        res.end(JSON.stringify({ reason: 'RelayConnectFailed', error: String(error) }));\n        return;\n      }\n      const body: Buffer[] = [];\n      stream.on('response', (responseHeaders) => {\n        const status = responseHeaders[':status'] ?? 502;\n        const apnsId = responseHeaders['apns-id'];\n        res.writeHead(status, {\n          'content-type': 'application/json',\n          ...(typeof apnsId === 'string' ? { 'apns-id': apnsId } : {}),\n        });\n      });\n      stream.on('data', (chunk: Buffer) => body.push(chunk));\n      stream.on('end', () => res.end(Buffer.concat(body)));\n      stream.on('error', (error) => {\n        if (!res.headersSent) res.writeHead(502, { 'content-type': 'application/json' });\n        res.end(JSON.stringify({ reason: 'RelayUpstreamError', error: String(error) }));\n      });\n      stream.end(Buffer.concat(chunks));\n    });\n  }\n\n  const server = createServer(relay);\n  return new Promise((resolve, reject) => {\n    server.once('error', reject);\n    server.listen(options.port, options.hostname ?? '127.0.0.1', () => {\n      const address = server.address();\n      const port = typeof address === 'object' && address !== null ? address.port : options.port;\n      resolve({\n        port,\n        close: () =>\n          new Promise((done) => {\n            for (const open of sessions.values()) open.close();\n            sessions.clear();\n            server.close(() => done());\n          }),\n      });\n    });\n  });\n}\n"],"mappings":"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"}

package/dist/apns.cjs

@@ -0,0 +1,121 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_jwt = require("./jwt.cjs");
+//#region src/apns.ts
+const APNS_HOSTS = {
+	sandbox: "https://api.sandbox.push.apple.com",
+	production: "https://api.push.apple.com"
+};
+/** Reasons APNs gives for a token that will never deliver again — not worth a retry. */
+const DEAD_TOKEN_REASONS = /* @__PURE__ */ new Set([
+	"Unregistered",
+	"BadDeviceToken",
+	"DeviceTokenNotForTopic",
+	"ExpiredToken"
+]);
+/** Apple: reuse a provider token for at least 20 minutes, never past 60. */
+const TOKEN_TTL_MS = 3e6;
+var ApnsPushSender = class {
+	options;
+	token;
+	constructor(options) {
+		this.options = options;
+	}
+	async send(message) {
+		if (message.channel !== "push") throw new Error(`ApnsPushSender: unsupported channel '${message.channel}'`);
+		if (message.recipient === void 0) throw new Error(`ApnsPushSender: no push token for user '${message.userId}'`);
+		const { title, body, image, url } = await this.options.render(message.template, message.props);
+		const mutable = image !== void 0 || message.tracking?.data?.delivered_url !== void 0;
+		const upstream = APNS_HOSTS[this.options.environment];
+		const origin = this.options.origin ?? upstream;
+		const response = await (this.options.fetch ?? fetch)(`${origin}/3/device/${message.recipient}`, {
+			method: "POST",
+			headers: {
+				authorization: `bearer ${await this.providerToken()}`,
+				"apns-topic": this.options.topic,
+				"apns-push-type": "alert",
+				"apns-priority": "10",
+				"content-type": "application/json",
+				...this.options.origin === void 0 ? {} : { "apns-relay-upstream": upstream }
+			},
+			body: JSON.stringify({
+				aps: {
+					alert: {
+						title,
+						body
+					},
+					sound: "default",
+					...mutable ? { "mutable-content": 1 } : {}
+				},
+				template: message.template,
+				idempotencyKey: message.idempotencyKey,
+				...image === void 0 ? {} : { image },
+				...url === void 0 ? {} : { url },
+				...message.tracking?.data
+			})
+		});
+		if (response.ok) return;
+		const text = await response.text();
+		const reason = apnsReason(text);
+		if (response.status === 410 || DEAD_TOKEN_REASONS.has(reason)) {
+			console.warn(`[apns] token gone for user ${message.userId}: ${reason || response.status}`);
+			await this.options.onUnregistered?.(message);
+			return {
+				delivered: false,
+				reason: reason || `HTTP ${response.status}`
+			};
+		}
+		throw new Error(`APNs send failed: ${response.status} ${text}`);
+	}
+	async providerToken() {
+		const now = Date.now();
+		if (this.token !== void 0 && now - this.token.issuedAt < TOKEN_TTL_MS) return this.token.value;
+		const value = await signApnsJwt(this.options, now);
+		this.token = {
+			value,
+			issuedAt: now
+		};
+		return value;
+	}
+};
+/** APNs error bodies are `{ "reason": "…" }`. */
+function apnsReason(body) {
+	try {
+		return JSON.parse(body).reason ?? "";
+	} catch {
+		return "";
+	}
+}
+/** ES256-sign the APNs provider token: header `kid`, claims `iss` (team) and `iat`. */
+async function signApnsJwt(key, nowMs = Date.now()) {
+	const header = require_jwt.base64url(JSON.stringify({
+		alg: "ES256",
+		kid: key.keyId
+	}));
+	const claims = require_jwt.base64url(JSON.stringify({
+		iss: key.teamId,
+		iat: Math.floor(nowMs / 1e3)
+	}));
+	const cryptoKey = await crypto.subtle.importKey("pkcs8", require_jwt.pemToDer(key.privateKey), {
+		name: "ECDSA",
+		namedCurve: "P-256"
+	}, false, ["sign"]);
+	const signature = await crypto.subtle.sign({
+		name: "ECDSA",
+		hash: "SHA-256"
+	}, cryptoKey, new TextEncoder().encode(`${header}.${claims}`));
+	return `${header}.${claims}.${require_jwt.base64url(new Uint8Array(signature))}`;
+}
+/** The `.p8` as it is usually shipped in a secret: base64 of the file. */
+function apnsKeyFromBase64(value) {
+	const pem = atob(value);
+	if (!pem.includes("-----BEGIN PRIVATE KEY-----")) throw new Error("APNs key is not a PKCS #8 PEM (.p8) file");
+	return pem;
+}
+//#endregion
+exports.APNS_HOSTS = APNS_HOSTS;
+exports.ApnsPushSender = ApnsPushSender;
+exports.apnsKeyFromBase64 = apnsKeyFromBase64;
+exports.apnsReason = apnsReason;
+exports.signApnsJwt = signApnsJwt;
+
+//# sourceMappingURL=apns.cjs.map

package/dist/apns.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apns.cjs","names":["base64url","pemToDer"],"sources":["../src/apns.ts"],"sourcesContent":["import type { MessageSender, OutboundMessage, SendResult } from './engine';\nimport { base64url, pemToDer } from './jwt';\nimport type { PushRenderer } from './push';\n\n/**\n * `@shware/workflow/apns` — iOS push delivery straight to the Apple Push\n * Notification service, token-based (an APNs auth key, the `.p8` file from the\n * developer portal). No Firebase in between: the app registers the APNs device\n * token in its own device table, and the host's DeviceDirectory hands it to the\n * engine, which sends one message per device.\n * No dependencies: the provider JWT is ES256-signed with WebCrypto.\n *\n * APNs speaks HTTP/2 only. A deployed Worker's `fetch` negotiates it, but\n * workerd under `wrangler dev` does not (the connection is dropped), so a local\n * host points `origin` at the Node relay in `@shware/workflow/apns-relay`.\n */\n\nexport interface ApnsPushOptions {\n  /** The key's 10-character id, shown next to it in the developer portal. */\n  keyId: string;\n  /** The Apple Developer team id. */\n  teamId: string;\n  /** The `.p8` file's contents: PEM, `-----BEGIN PRIVATE KEY-----` (PKCS #8, P-256). */\n  privateKey: string;\n  /** The app's bundle id — APNs's `apns-topic`. */\n  topic: string;\n  /**\n   * Which APNs environment the device tokens come from: `sandbox` for builds\n   * signed with `aps-environment: development` (Xcode, the simulator),\n   * `production` for App Store and TestFlight builds. A token from one is\n   * `BadDeviceToken` on the other.\n   */\n  environment: 'sandbox' | 'production';\n  render: PushRenderer;\n  /**\n   * POST here instead of Apple's host — the dev relay, which forwards over\n   * HTTP/2. The real host still travels along (`apns-relay-upstream`), so the\n   * relay needs no configuration of its own.\n   */\n  origin?: string;\n  /** Fetch implementation (defaults to the global one). */\n  fetch?: typeof fetch;\n  /** Called for a token APNs reports as gone (`Unregistered`, `BadDeviceToken`); `channelsFromConfig` passes it on to the DeviceDirectory's `disable`. */\n  onUnregistered?: (message: OutboundMessage) => Promise<void> | void;\n}\n\nexport const APNS_HOSTS = {\n  sandbox: 'https://api.sandbox.push.apple.com',\n  production: 'https://api.push.apple.com',\n} as const;\n\n/** Reasons APNs gives for a token that will never deliver again — not worth a retry. */\nconst DEAD_TOKEN_REASONS = new Set([\n  'Unregistered',\n  'BadDeviceToken',\n  'DeviceTokenNotForTopic',\n  'ExpiredToken',\n]);\n\n/** Apple: reuse a provider token for at least 20 minutes, never past 60. */\nconst TOKEN_TTL_MS = 50 * 60_000;\n\nexport class ApnsPushSender implements MessageSender {\n  private token: { value: string; issuedAt: number } | undefined;\n\n  constructor(private readonly options: ApnsPushOptions) {}\n\n  async send(message: OutboundMessage): Promise<void | SendResult> {\n    if (message.channel !== 'push') {\n      throw new Error(`ApnsPushSender: unsupported channel '${message.channel}'`);\n    }\n    if (message.recipient === undefined) {\n      throw new Error(`ApnsPushSender: no push token for user '${message.userId}'`);\n    }\n    const { title, body, image, url } = await this.options.render(message.template, message.props);\n    // A notification service extension runs only for a mutable push: it attaches the image and\n    // reports the device delivery (`delivered_url`)\n    const mutable = image !== undefined || message.tracking?.data?.delivered_url !== undefined;\n    const upstream = APNS_HOSTS[this.options.environment];\n    const origin = this.options.origin ?? upstream;\n    const doFetch = this.options.fetch ?? fetch;\n\n    const response = await doFetch(`${origin}/3/device/${message.recipient}`, {\n      method: 'POST',\n      headers: {\n        authorization: `bearer ${await this.providerToken()}`,\n        'apns-topic': this.options.topic,\n        'apns-push-type': 'alert',\n        'apns-priority': '10',\n        'content-type': 'application/json',\n        ...(this.options.origin === undefined ? {} : { 'apns-relay-upstream': upstream }),\n      },\n      body: JSON.stringify({\n        aps: {\n          alert: { title, body },\n          sound: 'default',\n          ...(mutable ? { 'mutable-content': 1 } : {}),\n        },\n        // The template key travels so the app can route a tap; the idempotency\n        // key lets the app de-duplicate a redelivered push.\n        template: message.template,\n        idempotencyKey: message.idempotencyKey,\n        ...(image === undefined ? {} : { image }),\n        ...(url === undefined ? {} : { url }),\n        ...message.tracking?.data,\n      }),\n    });\n    if (response.ok) return;\n\n    const text = await response.text();\n    const reason = apnsReason(text);\n    if (response.status === 410 || DEAD_TOKEN_REASONS.has(reason)) {\n      // A dead token is a fact about the recipient, not a transient failure:\n      // report it and move on, so the step does not retry into the same wall.\n      console.warn(`[apns] token gone for user ${message.userId}: ${reason || response.status}`);\n      await this.options.onUnregistered?.(message);\n      return { delivered: false, reason: reason || `HTTP ${response.status}` };\n    }\n    throw new Error(`APNs send failed: ${response.status} ${text}`);\n  }\n\n  private async providerToken(): Promise<string> {\n    const now = Date.now();\n    if (this.token !== undefined && now - this.token.issuedAt < TOKEN_TTL_MS) {\n      return this.token.value;\n    }\n    const value = await signApnsJwt(this.options, now);\n    this.token = { value, issuedAt: now };\n    return value;\n  }\n}\n\n/** APNs error bodies are `{ \"reason\": \"…\" }`. */\nexport function apnsReason(body: string): string {\n  try {\n    const parsed = JSON.parse(body) as { reason?: string };\n    return parsed.reason ?? '';\n  } catch {\n    return '';\n  }\n}\n\n/** ES256-sign the APNs provider token: header `kid`, claims `iss` (team) and `iat`. */\nexport async function signApnsJwt(\n  key: Pick<ApnsPushOptions, 'keyId' | 'teamId' | 'privateKey'>,\n  nowMs = Date.now()\n): Promise<string> {\n  const header = base64url(JSON.stringify({ alg: 'ES256', kid: key.keyId }));\n  const claims = base64url(JSON.stringify({ iss: key.teamId, iat: Math.floor(nowMs / 1000) }));\n  const cryptoKey = await crypto.subtle.importKey(\n    'pkcs8',\n    pemToDer(key.privateKey),\n    { name: 'ECDSA', namedCurve: 'P-256' },\n    false,\n    ['sign']\n  );\n  // WebCrypto's ECDSA signature is the raw r‖s pair, which is exactly JWS's ES256 encoding.\n  const signature = await crypto.subtle.sign(\n    { name: 'ECDSA', hash: 'SHA-256' },\n    cryptoKey,\n    new TextEncoder().encode(`${header}.${claims}`)\n  );\n  return `${header}.${claims}.${base64url(new Uint8Array(signature))}`;\n}\n\n/** The `.p8` as it is usually shipped in a secret: base64 of the file. */\nexport function apnsKeyFromBase64(value: string): string {\n  const pem = atob(value);\n  if (!pem.includes('-----BEGIN PRIVATE KEY-----')) {\n    throw new Error('APNs key is not a PKCS #8 PEM (.p8) file');\n  }\n  return pem;\n}\n"],"mappings":"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"}