@shware/workflow 5.0.0 → 6.0.0

package/README.md

@@ -54,6 +54,7 @@ export const contract = defineContract({
     purchase: looseObject({ transaction_id: string(), currency: string(), value: number() }),
   },
   profile: strictObject({ email: optional(email()), name: string() }),
+  subscriptions: { topics: ['promotions', 'newsletter', 'tips'] },
 });
 
 /** The DSL's reference tables: `e.login`, `u.name`. */
@@ -66,6 +67,16 @@ The profile is a flat object of string, number, boolean, enum and literal
 fields. Defaults, transforms, coercion and custom refinements are refused when
 the contract is defined, because input and output must mean the same JSON.
 
+`subscriptions.topics` lists the subscription topics: content categories
+("offers", "tips"), not channels — ids only (a plain token; the app's i18n gives
+them names). A plain array literal is enough: `defineContract` keeps the
+literals, and the union they form types every email and push template's
+`topic`, the config and `JourneyClient.setSubscriptions`. A user opts out of a
+topic per channel (the preference page is topic × channel), or of a whole
+channel; the engine keeps that record and is the one source of truth for it
+(see [Email](#email), [Push](#push) and [`JourneyClient`](#journeyclient)).
+Leave the field out when every email and push is transactional.
+
 ### 2. Templates
 
 One object per template, identified by its own `id` (unique per channel): the
@@ -74,14 +85,20 @@ stable and rename `title` instead. Its strict Zod `props` schema is the only
 source of the props type: the DSL's arguments, the `preview` and the component
 are all derived from it, and every send parses the props against it first.
 
+```ts
+// src/contract.ts (continued): the template factories bound to the contract
+export const { emailTemplate, pushTemplate } = templatesFor(contract);
+```
+
 ```tsx
 // src/email/welcome.tsx
 import { Html, Text } from '@react-email/components';
-import { emailTemplate } from '@shware/workflow';
 import { strictObject, string } from 'zod/mini';
+import { emailTemplate } from '../contract';
 
 export default emailTemplate({
   id: 'welcome',
+  transactional: true,
   from: { email: 'noreply@acme.test', name: 'Acme' },
   title: 'Welcome',
   props: strictObject({ name: string() }),
@@ -95,6 +112,17 @@ export default emailTemplate({
 });
 ```
 
+Every email and push template says what it is: `topic: 'tips'` (a topic the
+contract declares, which the user can opt out of on that channel) or
+`transactional: true` (a receipt, a code, an invite: sent whatever they opted
+out of; for an email, with no unsubscribe link). Leaving both out, or giving
+both, is a type error and a compile error, and the error says so in words.
+`templatesFor(contract)` gives the factories with the topic typed by the
+contract, so a topic it does not declare is an error at the template's own
+`topic` line, in the editor and when the module loads; the bare `emailTemplate`
+/ `pushTemplate` from `@shware/workflow` are for a project without a contract
+(transactional templates only), and the compile checks every template again.
+
 Gather them per channel; the workflows send the definitions and the config
 registers the whole:
 
@@ -113,11 +141,13 @@ import { email } from './email';
 export const templates = { email };
 ```
 
-`tip.tsx` is written the same way. The property names are JavaScript names
-only. `.email(email.welcome, props)` checks `props` against that template's
-schema, and a push template is not accepted where an email is. The compile
-refuses an id registered twice in a channel, and a workflow sending a
-definition other than the one registered under its id.
+`tip.tsx` is written the same way, with `topic: 'tips'`, and so is a
+`pushTemplate`. The property names are JavaScript names only. `.email(email.welcome, props)` checks `props`
+against that template's schema, and a push template is not accepted where an
+email is. The compile refuses an id registered twice in a channel, a workflow
+sending a definition other than the one registered under its id, and a topic
+the contract does not declare (with a `contract` in the config, the editor
+refuses it first).
 
 ### 3. A workflow
 
@@ -463,30 +493,42 @@ the compile fails.
 
 ### Email
 
-`emailTemplate({ id, from, replyTo?, unsubscribeUrl?, title, description?, props, subject, preview, component })`
+`emailTemplate({ id, topic | transactional, from, replyTo?, unsubscribeUrl?, title, description?, props, subject, preview, component })`
 declares one. The Worker renders it with `@shware/workflow/react-email` (React's
 streaming renderer, which waits for react-email's `<Tailwind>`) and sends it
 through the host's email transport, from the template's own `from`:
 
 ```ts
-// src/email/welcome.tsx
+// src/email/tip.tsx
 export default emailTemplate({
-  id: 'welcome',
+  id: 'tip',
+  topic: 'tips',
   from: { email: 'noreply@acme.test', name: 'Acme' },
   replyTo: { email: 'support@acme.test', name: 'Acme Support' }, // left out: no Reply-To
-  title: 'Welcome',
+  title: 'Weekly tip',
   props: strictObject({ name: string() }),
-  subject: 'Welcome to Acme',
+  subject: 'One thing to try this week',
   preview: { name: 'John Doe' },
   component: ({ name }) => <Layout name={name}>…</Layout>,
 });
 ```
 
-There is no global sender: share addresses through a module of your own. The
-unsubscribe link is the template's `unsubscribeUrl`, else the config's
-`email.unsubscribeUrl`, else none (`resolveEmail` is the rule). A layout reads
-it from the render, never from a constant, so a template's own URL reaches
-its HTML:
+Every template is one of two kinds, by type: a **topic** email names one of the
+contract's `subscriptions.topics`, and a **transactional** email says
+`transactional: true` (and takes no `unsubscribeUrl`). The kind decides what
+the engine does before and after the send:
+
+| Email         | Before sending                                                 | Unsubscribe link, `List-Unsubscribe`  |
+| ------------- | -------------------------------------------------------------- | ------------------------------------- |
+| topic         | skipped when the user opted out of that topic, or of all email | yes                                   |
+| transactional | always sent (a receipt, a code, an invite)                     | none, whatever `email.unsubscribeUrl` |
+
+There is no global sender: share addresses through a module of your own. A
+topic email's unsubscribe link is the template's `unsubscribeUrl`, else the
+config's `email.unsubscribeUrl`, else none; a transactional email never has one
+(`resolveEmail` is the rule). A layout reads it from the render, never from a
+constant, so a template's own URL reaches its HTML; the resolved `topic` is
+there too, for a line like "you get these because you subscribed to tips":
 
 ```tsx
 import { useEmailContext } from '@shware/workflow/email-context';
@@ -527,10 +569,23 @@ An email with an unsubscribe link also carries `List-Unsubscribe` (RFC 2369), so
 a mail client's own unsubscribe button works. With reporting on (a Postgres store and
 `WORKFLOW_ORIGIN`), it names the copy's one-click endpoint `/t/u/<message>`, together with
 `List-Unsubscribe-Post: List-Unsubscribe=One-Click` (RFC 8058). Gmail and Yahoo require
-one-click unsubscribe for bulk senders. The provider's POST there unsubscribes at once, and the
-same URL opened in a browser asks first. Without reporting, the header names the template's own
-unsubscribe link, with no one-click claim. Only https URLs are named, so a local `http://`
-origin sends no header.
+one-click unsubscribe for bulk senders. The provider's POST there unsubscribes at once from
+the email's topic; the same URL opened in a browser (and the email's own link) asks first, with
+two buttons: the email's topic, and all email. Without reporting, the header names the
+template's own unsubscribe link, with no one-click claim. Only https URLs are named, so a local
+`http://` origin sends no header.
+
+What a user opted out of is the engine's record, per topic and channel: a topic email is
+skipped while its topic (on email) or all email is opted out, a transactional email never is,
+and `reachable('email')` reads the all-email opt-out only — a user unsubscribed from one topic
+is still reachable, so an `exitWhen: not(reachable('email'))` fires on "all email", not on a
+topic. An email opt-out says nothing about push: the same topic is opted out per channel. The
+app reads and sets the record through `GET` / `PUT /subscriptions/:userId`
+(`JourneyClient.getSubscriptions` / `setSubscriptions`), which is how a signed-in preference
+page is built: the engine holds the truth, the page shows it. The all-email opt-out and the
+topic opt-outs are separate records: `all: false` masks every topic, whatever its own flag says,
+and `all: true` clears only the all-email opt-out — a topic opted out on its own stays off until
+a patch names it.
 
 An email step refuses to send when the profile has no `email`.
 `GET /preview/<id>?props=<JSON>` renders a template, with the subject in the
@@ -538,13 +593,14 @@ An email step refuses to send when the profile has no `email`.
 
 ### Push
 
-`pushTemplate({ id, title, description?, props, preview, content })`, where
-`content(props)` returns `{ title, body, image?, url? }`: final text, never
+`pushTemplate({ id, topic | transactional, title, description?, props, preview, content })`,
+where `content(props)` returns `{ title, body, image?, url? }`: final text, never
 placeholder-expanded. `url` is the page a browser push opens.
 
 ```ts
 export default pushTemplate({
   id: 'onboarding_tip_push',
+  topic: 'tips',
   title: 'Onboarding tip (push)',
   props: strictObject({ name: string() }),
   preview: { name: 'John Doe' },
@@ -552,6 +608,18 @@ export default pushTemplate({
 });
 ```
 
+A push is a **topic** push (one of the contract's `subscriptions.topics`) or a
+**transactional** one (`transactional: true`: a code, a receipt, a reply), like
+an email. A topic push is skipped while the user opted out of that topic on
+push, or of all push; a transactional push always goes. The app records the
+opt-outs through `PUT /subscriptions/:userId` (`JourneyClient.setSubscriptions`
+with `{ push: { all?, topics? } }`), which is the in-app switch App Store Review
+Guideline 4.5.4 requires for marketing pushes: `push.all: false` is "no
+promotional notifications", a topic `false` is one category off. The opt-outs are
+per channel: a topic switched off for push is still sent by email.
+`reachable('push')` is a device plus no all-push opt-out; a topic opt-out leaves
+it true. Changing `push.all` wakes the waits on it, as a device change does.
+
 Pushes go to the devices the engine keeps. The app registers each token with
 `JourneyClient.registerDevice(userId, { token, platform })`, and a token moves
 to the latest user that registers it. Each platform is turned on by the config,
@@ -636,20 +704,20 @@ Discord; supply anything else with `journeyWorker({ messages })`.
 
 `defineConfig` takes:
 
-| Field       | Holds                                                                          |
-| ----------- | ------------------------------------------------------------------------------ |
-| `title`     | The Studio title                                                               |
-| `contract`  | The `defineContract(...)` every `/events` and `/identify` is validated against |
-| `workflows` | The workflows to deploy                                                        |
-| `segments`  | Named segments                                                                 |
-| `actions`   | Custom actions `.run()` uses                                                   |
-| `templates` | The registries: `{ email?, push?, discord?, slack? }`                          |
-| `email`     | `{ unsubscribeUrl?, tracking? }`: what every email template shares             |
-| `runtime`   | Per mode (`development`, `production`, …): `{ timeScale?, logMessages? }`      |
-| `apns`      | `{ topic, keyId, teamId, environment? }`                                       |
-| `fcm`       | `{ androidChannelId? }`                                                        |
-| `webPush`   | `{ subject, openedEvent? }`                                                    |
-| `database`  | `{ schema? }`: the Postgres schema, `workflow` by default                      |
+| Field       | Holds                                                                               |
+| ----------- | ----------------------------------------------------------------------------------- |
+| `title`     | The Studio title                                                                    |
+| `contract`  | The `defineContract(...)` every `/events` and `/identify` is validated against      |
+| `workflows` | The workflows to deploy                                                             |
+| `segments`  | Named segments                                                                      |
+| `actions`   | Custom actions `.run()` uses                                                        |
+| `templates` | The registries: `{ email?, push?, discord?, slack? }`; topics typed by the contract |
+| `email`     | `{ unsubscribeUrl?, tracking? }`: what every topic email template shares            |
+| `runtime`   | Per mode (`development`, `production`, …): `{ timeScale?, logMessages? }`           |
+| `apns`      | `{ topic, keyId, teamId, environment? }`                                            |
+| `fcm`       | `{ androidChannelId? }`                                                             |
+| `webPush`   | `{ subject, openedEvent? }`                                                         |
+| `database`  | `{ schema? }`: the Postgres schema, `workflow` by default                           |
 
 The `ENVIRONMENT` var picks the `runtime` entry (production when unset).
 `timeScale` fast-forwards every duration: 600 turns "1 day" into 2.4 minutes.
@@ -689,12 +757,39 @@ const journeys = new JourneyClient({ contract, origin, token });
 | `unbindDevice(token)`                         | `POST /devices/unbind`  | Signed out: the token stays, bound to nobody             |
 | `removeDevice(token)`                         | `POST /devices/remove`  | Forget a token for good                                  |
 | `messageOpened(userId, messageId)`            | `POST /messages/opened` | A journey push tapped open (the `message_id` it carried) |
+| `getSubscriptions(userId)`                    | `GET /subscriptions/…`  | `{ email, push }`, each `{ all, topics }`, `true` = on   |
+| `setSubscriptions(userId, patch)`             | `PUT /subscriptions/…`  | Change what the patch names; answers the new state       |
 | `forgetUser(userId)`                          | `POST /users/forget`    | Stop the user's journeys and erase their data            |
 | `deploy(bundle)`                              | `POST /deploy`          | Deploy a compiled bundle                                 |
 
 Pass an `id` to `track` whenever a caller may retry; see
 [Give each event an `id`](#give-each-event-an-id).
 
+`getSubscriptions` and `setSubscriptions` are typed by the contract's
+`subscriptions.topics`, and a topic it does not declare is refused before the
+request. The record is topic × channel: `email` and `push` each list every
+topic. A preference page is a thin proxy over them:
+
+```ts
+const { email, push } = await journeys.getSubscriptions(userId);
+// email: { all: false, topics: { promotions: false, newsletter: true, tips: true } }
+// push:  { all: true, topics: { promotions: true, newsletter: true, tips: true } }
+// `all: false` masks every topic: newsletter reads true, but no email is sent until `all` is
+// true again. Each flag is its own record, so a preference page shows `all` as the master
+// switch and the topics as they are. Push is untouched by the email record.
+await journeys.setSubscriptions(userId, { email: { all: true } });
+// email: { all: true, topics: { promotions: false, newsletter: true, tips: true } }
+// `all: true` cleared only the all-email opt-out; promotions stays off until named:
+await journeys.setSubscriptions(userId, { email: { topics: { promotions: true } } });
+await journeys.setSubscriptions(userId, { email: { all: false } }); // unsubscribe from everything
+await journeys.setSubscriptions(userId, { push: { all: false } }); // the in-app "no promotional pushes"
+await journeys.setSubscriptions(userId, { push: { topics: { promotions: false } } }); // one category off, on push only
+```
+
+A "subscribe to all" button sends `all: true` plus every topic `true`; an
+"unsubscribe from all" sends `all: false` and leaves the topics as they are, so
+turning `all` back on restores the user's own choices.
+
 ## Compiling and planning
 
 `compileConfig(config)` returns the `BundleIR` the Worker deploys. It is
@@ -1016,14 +1111,25 @@ 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. The unique index
+Run `--check` in CI to catch an SDK upgrade that changed them. The file is laid
+out the way a prettier-compatible formatter at 100 columns lays it out, so
+formatting it changes nothing and a regeneration shows only real changes. The unique index
 on `event` is on `(user_id, event_id)`: regenerate and migrate before deploying —
-the deploy check verifies the unique indexes as well as the columns, and refuses
+the deploy check verifies the unique indexes and constraints as well as the columns, and refuses
 to run until they match. 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.
 
+**Upgrading to 6.0 (topics).** `suppression` gains a nullable `topic`
+column, loses its `(user_id, channel)` primary key and gets a
+`UNIQUE NULLS NOT DISTINCT (user_id, channel, topic)` constraint (Postgres 15+),
+and `message` gains a nullable `topic` (written for email and push copies).
+Regenerate the drizzle file and let drizzle-kit write the migration; it needs no
+data step. Rows from before keep their meaning: a `suppression` row whose
+`topic` is null is an opt-out from the whole channel, which is what every
+unsubscribe recorded before topics was.
+
 ### Deploying is `wrangler deploy`
 
 The journeys are compiled into the Worker, so a new version carries its own
@@ -1088,14 +1194,31 @@ On Postgres the engine also keeps:
 - `POST /devices` takes `{ userId, token, platform, ts? }`;
   `POST /devices/unbind` and `POST /devices/remove` take `{ token }`.
 - `POST /messages/opened` takes `{ userId, messageId }`.
-- `POST /users/forget` takes `{ userId }`.
+- `GET /subscriptions/:userId` answers `{ email: { all, topics }, push: { all, topics } }`
+  (`true` is subscribed; each channel's `topics` has one key per topic the
+  deployed bundle declares). `PUT /subscriptions/:userId` takes a partial body
+  `{ email?: { all?, topics? }, push?: { all?, topics? } }` and changes only
+  what it names, per channel: `all: false` opts out of the whole channel,
+  `topics: { newsletter: false }` of one topic on it, and `all: true` clears
+  the channel-wide opt-out only (a topic opted out on its own stays off until
+  named). An answer's `all: false` masks every topic of that channel, whatever
+  the topic's own flag says. An undeclared topic, an unknown channel or a
+  non-boolean answers 400 with the field paths; an erased user 410. Changing
+  `email.all` wakes the waits on `reachable('email')`, `push.all` those on
+  `reachable('push')`.
+- `POST /users/forget` takes `{ userId }`; the erasure takes the user's opt-outs
+  with the rest, since nothing is ever sent to that id again.
 - `POST /deploy` takes a compiled bundle and swaps the routing table atomically.
 
 `journeyWorker` adds `GET /bundle` (the compiled config), `POST /bundle/deploy`
 (deploy it), `GET /preview/<key>`, `POST /segments/sweep`, and the `/t/...`
-tracking routes recipients open, which need no bearer. With a contract, an
-event or identify it refuses is answered with a 400 and the field paths, before
-anything is stored, woken or started.
+tracking routes recipients open, which need no bearer. `POST /t/u/<message>`
+(the one-click unsubscribe, and the confirmation page's first button) opts the
+recipient out of that email's topic; with `?scope=all` (the second button) out
+of every email. A transactional email never carried the link, so every `/t/u`
+variant answers 404 for it. With a contract, an event or identify it refuses is
+answered with a 400 and the field paths, before anything is stored, woken or
+started.
 
 ### Give each event an `id`
 

package/dist/_virtual/_rolldown/runtime.cjs

@@ -1,4 +1,4 @@
-//#region \0rolldown/runtime.js
+// \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -19,5 +19,4 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	value: mod,
 	enumerable: true
 }) : target, mod));
-//#endregion
 exports.__toESM = __toESM;

package/dist/apns-relay.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_http2_client = require("./http2-client.cjs");
 let node_http = require("node:http");
-//#region src/apns-relay.ts
+// 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 = [
@@ -86,7 +86,6 @@ function startApnsRelay(options) {
 		});
 	});
 }
-//#endregion
 exports.startApnsRelay = startApnsRelay;
 
 //# sourceMappingURL=apns-relay.cjs.map

package/dist/apns-relay.d.cts

@@ -1,4 +1,3 @@
-//#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`.
@@ -24,5 +23,4 @@ export interface ApnsRelay {
   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

@@ -1 +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"}
+{"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

@@ -1,4 +1,3 @@
-//#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`.
@@ -24,5 +23,4 @@ export interface ApnsRelay {
   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

@@ -1 +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"}
+{"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

@@ -1,6 +1,6 @@
 import { http2Sessions } from "./http2-client.mjs";
 import { createServer } from "node:http";
-//#region src/apns-relay.ts
+// 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 = [
@@ -85,7 +85,6 @@ function startApnsRelay(options) {
 		});
 	});
 }
-//#endregion
 export { startApnsRelay };
 
 //# sourceMappingURL=apns-relay.mjs.map

package/dist/apns.cjs

@@ -2,7 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_engine_retry = require("./engine/retry.cjs");
 const require_jwt = require("./jwt.cjs");
 let node_buffer = require("node:buffer");
-//#region src/apns.ts
+// src/apns.ts
 const APNS_HOSTS = {
 	sandbox: "https://api.sandbox.push.apple.com",
 	production: "https://api.push.apple.com"
@@ -196,7 +196,6 @@ function apnsKeyFromBase64(value) {
 	if (!pem.includes("-----BEGIN PRIVATE KEY-----")) throw new require_engine_retry.PermanentError("APNs key is not a PKCS #8 PEM (.p8) file");
 	return pem;
 }
-//#endregion
 exports.APNS_HOSTS = APNS_HOSTS;
 exports.ApnsProviderToken = ApnsProviderToken;
 exports.ApnsPushSender = ApnsPushSender;

package/dist/apns.d.cts

@@ -1,7 +1,6 @@
 import { MessageSender, OutboundMessage, SendResult } from "./engine/ports.cjs";
 import "./engine/index.cjs";
 import { PushRenderer } from "./push.cjs";
-//#region src/apns.d.ts
 /**
  * `@shware/workflow/apns` — iOS push delivery straight to the Apple Push
  * Notification service, token-based (an APNs auth key, the `.p8` file from the
@@ -105,5 +104,4 @@ export declare function apnsReason(body: string): string;
 export declare function signApnsJwt(key: ApnsProviderTokenOptions, nowMs?: number): Promise<string>;
 /** The `.p8` as it is usually shipped in a secret: base64 of the file. */
 export declare function apnsKeyFromBase64(value: string): string;
-//#endregion
 //# sourceMappingURL=apns.d.cts.map

package/dist/apns.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"apns.d.cts","names":[],"sources":["../src/apns.ts"],"mappings":";;;;;;;;;;;;;;;;;iBAoBiB;;EAEf;;EAEA;;EAEA;;iBAGe;;EAEf,aAAa;;EAEb;;;;;;;EAOA;EACA,QAAQ;;;;;;EAMR;;EAEA,eAAe;;qBAGJ;WACX;WACA;;;;;;;;;;;;;;;;;;;;;qBAsBW,oBAAoB;;;;;;;;wBAsBX,cAAc,yBAAyB;;;;;;;;qBAqBhD;mBAIkB;UAHrB;UACA;EAER,YAA6B,SAAS;;EAGhC,MAAM,eAAmB;;EAgB/B;;qBAKW,0BAA0B;mBACR;EAA7B,YAA6B,SAAS;EAEhC,KAAK,SAAS,kBAAkB,eAAe;;;wBAkFvC,WAAW;;wBAUL,YACpB,KAAK,0BACL,iBACC;;wBAoBa,kBAAkB"}
+{"version":3,"file":"apns.d.cts","names":[],"sources":["../src/apns.ts"],"mappings":";;;;;;;;;;;;;;;;iBAoBiB;;EAEf;;EAEA;;EAEA;;iBAGe;;EAEf,aAAa;;EAEb;;;;;;;EAOA;EACA,QAAQ;;;;;;EAMR;;EAEA,eAAe;;qBAGJ;WACX;WACA;;;;;;;;;;;;;;;;;;;;;qBAsBW,oBAAoB;;;;;;;;wBAsBX,cAAc,yBAAyB;;;;;;;;qBAqBhD;mBAIkB;UAHrB;UACA;EAER,YAA6B,SAAS;;EAGhC,MAAM,eAAmB;;EAgB/B;;qBAKW,0BAA0B;mBACR;EAA7B,YAA6B,SAAS;EAEhC,KAAK,SAAS,kBAAkB,eAAe;;;wBAkFvC,WAAW;;wBAUL,YACpB,KAAK,0BACL,iBACC;;wBAoBa,kBAAkB"}

package/dist/apns.d.mts

@@ -1,7 +1,6 @@
 import { MessageSender, OutboundMessage, SendResult } from "./engine/ports.mjs";
 import "./engine/index.mjs";
 import { PushRenderer } from "./push.mjs";
-//#region src/apns.d.ts
 /**
  * `@shware/workflow/apns` — iOS push delivery straight to the Apple Push
  * Notification service, token-based (an APNs auth key, the `.p8` file from the
@@ -105,5 +104,4 @@ export declare function apnsReason(body: string): string;
 export declare function signApnsJwt(key: ApnsProviderTokenOptions, nowMs?: number): Promise<string>;
 /** The `.p8` as it is usually shipped in a secret: base64 of the file. */
 export declare function apnsKeyFromBase64(value: string): string;
-//#endregion
 //# sourceMappingURL=apns.d.mts.map

package/dist/apns.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"apns.d.mts","names":[],"sources":["../src/apns.ts"],"mappings":";;;;;;;;;;;;;;;;;iBAoBiB;;EAEf;;EAEA;;EAEA;;iBAGe;;EAEf,aAAa;;EAEb;;;;;;;EAOA;EACA,QAAQ;;;;;;EAMR;;EAEA,eAAe;;qBAGJ;WACX;WACA;;;;;;;;;;;;;;;;;;;;;qBAsBW,oBAAoB;;;;;;;;wBAsBX,cAAc,yBAAyB;;;;;;;;qBAqBhD;mBAIkB;UAHrB;UACA;EAER,YAA6B,SAAS;;EAGhC,MAAM,eAAmB;;EAgB/B;;qBAKW,0BAA0B;mBACR;EAA7B,YAA6B,SAAS;EAEhC,KAAK,SAAS,kBAAkB,eAAe;;;wBAkFvC,WAAW;;wBAUL,YACpB,KAAK,0BACL,iBACC;;wBAoBa,kBAAkB"}
+{"version":3,"file":"apns.d.mts","names":[],"sources":["../src/apns.ts"],"mappings":";;;;;;;;;;;;;;;;iBAoBiB;;EAEf;;EAEA;;EAEA;;iBAGe;;EAEf,aAAa;;EAEb;;;;;;;EAOA;EACA,QAAQ;;;;;;EAMR;;EAEA,eAAe;;qBAGJ;WACX;WACA;;;;;;;;;;;;;;;;;;;;;qBAsBW,oBAAoB;;;;;;;;wBAsBX,cAAc,yBAAyB;;;;;;;;qBAqBhD;mBAIkB;UAHrB;UACA;EAER,YAA6B,SAAS;;EAGhC,MAAM,eAAmB;;EAgB/B;;qBAKW,0BAA0B;mBACR;EAA7B,YAA6B,SAAS;EAEhC,KAAK,SAAS,kBAAkB,eAAe;;;wBAkFvC,WAAW;;wBAUL,YACpB,KAAK,0BACL,iBACC;;wBAoBa,kBAAkB"}

package/dist/apns.mjs

@@ -1,7 +1,7 @@
 import { PermanentError, isRetryableStatus } from "./engine/retry.mjs";
 import { base64url, pemToDer } from "./jwt.mjs";
 import { Buffer } from "node:buffer";
-//#region src/apns.ts
+// src/apns.ts
 const APNS_HOSTS = {
 	sandbox: "https://api.sandbox.push.apple.com",
 	production: "https://api.push.apple.com"
@@ -195,7 +195,6 @@ function apnsKeyFromBase64(value) {
 	if (!pem.includes("-----BEGIN PRIVATE KEY-----")) throw new PermanentError("APNs key is not a PKCS #8 PEM (.p8) file");
 	return pem;
 }
-//#endregion
 export { APNS_HOSTS, ApnsProviderToken, ApnsPushSender, DEAD_TOKEN_REASONS, apnsIdFromKey, apnsKeyFromBase64, apnsReason, signApnsJwt };
 
 //# sourceMappingURL=apns.mjs.map

package/dist/aws/engine-step.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_engine_retry = require("../engine/retry.cjs");
 let _aws_durable_execution_sdk_js = require("@aws/durable-execution-sdk-js");
-//#region src/aws/engine-step.ts
+// src/aws/engine-step.ts
 /**
 * EngineStep over a Lambda durable execution.
 *
@@ -96,7 +96,6 @@ var AwsEngineStep = class {
 		}
 	}
 };
-//#endregion
 exports.AwsEngineStep = AwsEngineStep;
 exports.stepRetry = stepRetry;
 

package/dist/aws/engine-step.d.cts

@@ -2,7 +2,6 @@ import { EngineStep } from "../engine/ports.cjs";
 import { ExecutionRegistry, JourneyStore } from "../store/index.cjs";
 import { LambdaApi } from "./lambda-api.cjs";
 import { DurableContext, RetryDecision } from "@aws/durable-execution-sdk-js";
-//#region src/aws/engine-step.d.ts
 /**
  * EngineStep over a Lambda durable execution.
  *
@@ -40,5 +39,4 @@ export declare class AwsEngineStep implements EngineStep {
     deadlineMs: number;
   }): Promise<'event' | 'timeout'>;
 }
-//#endregion
 //# sourceMappingURL=engine-step.d.cts.map

package/dist/aws/engine-step.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"engine-step.d.cts","names":[],"sources":["../../src/aws/engine-step.ts"],"mappings":";;;;;;;;;;;;;;;;wBAuBgB,UAAU,OAAO,OAAO,kBAAkB;qBAa7C,yBAAyB;mBAKjB;mBACA;mBACA;mBACA;mBACA;mBACA;UATX;UACA;EAER,YACmB,SAAS,gBACT,OAAO,cACP,YAAY,mBACZ,QAAQ,WACR,gBACA;EAGnB,GAAG,GAAG,cAAc,UAAU,QAAQ,KAAK,QAAQ;EAI7C,MAAM,cAAc,aAAa;EAMjC,UACJ,cACA,2BACA;IAAW;MACV;EAoCG,YAAY,eAAe;;;;;EAsB3B,YACJ,cACA;IAAS;IAAmB;MAC3B"}
+{"version":3,"file":"engine-step.d.cts","names":[],"sources":["../../src/aws/engine-step.ts"],"mappings":";;;;;;;;;;;;;;;wBAuBgB,UAAU,OAAO,OAAO,kBAAkB;qBAa7C,yBAAyB;mBAKjB;mBACA;mBACA;mBACA;mBACA;mBACA;UATX;UACA;EAER,YACmB,SAAS,gBACT,OAAO,cACP,YAAY,mBACZ,QAAQ,WACR,gBACA;EAGnB,GAAG,GAAG,cAAc,UAAU,QAAQ,KAAK,QAAQ;EAI7C,MAAM,cAAc,aAAa;EAMjC,UACJ,cACA,2BACA;IAAW;MACV;EAoCG,YAAY,eAAe;;;;;EAsB3B,YACJ,cACA;IAAS;IAAmB;MAC3B"}

package/dist/aws/engine-step.d.mts

@@ -2,7 +2,6 @@ import { EngineStep } from "../engine/ports.mjs";
 import { ExecutionRegistry, JourneyStore } from "../store/index.mjs";
 import { LambdaApi } from "./lambda-api.mjs";
 import { DurableContext, RetryDecision } from "@aws/durable-execution-sdk-js";
-//#region src/aws/engine-step.d.ts
 /**
  * EngineStep over a Lambda durable execution.
  *
@@ -40,5 +39,4 @@ export declare class AwsEngineStep implements EngineStep {
     deadlineMs: number;
   }): Promise<'event' | 'timeout'>;
 }
-//#endregion
 //# sourceMappingURL=engine-step.d.mts.map

package/dist/aws/engine-step.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"engine-step.d.mts","names":[],"sources":["../../src/aws/engine-step.ts"],"mappings":";;;;;;;;;;;;;;;;wBAuBgB,UAAU,OAAO,OAAO,kBAAkB;qBAa7C,yBAAyB;mBAKjB;mBACA;mBACA;mBACA;mBACA;mBACA;UATX;UACA;EAER,YACmB,SAAS,gBACT,OAAO,cACP,YAAY,mBACZ,QAAQ,WACR,gBACA;EAGnB,GAAG,GAAG,cAAc,UAAU,QAAQ,KAAK,QAAQ;EAI7C,MAAM,cAAc,aAAa;EAMjC,UACJ,cACA,2BACA;IAAW;MACV;EAoCG,YAAY,eAAe;;;;;EAsB3B,YACJ,cACA;IAAS;IAAmB;MAC3B"}
+{"version":3,"file":"engine-step.d.mts","names":[],"sources":["../../src/aws/engine-step.ts"],"mappings":";;;;;;;;;;;;;;;wBAuBgB,UAAU,OAAO,OAAO,kBAAkB;qBAa7C,yBAAyB;mBAKjB;mBACA;mBACA;mBACA;mBACA;mBACA;UATX;UACA;EAER,YACmB,SAAS,gBACT,OAAO,cACP,YAAY,mBACZ,QAAQ,WACR,gBACA;EAGnB,GAAG,GAAG,cAAc,UAAU,QAAQ,KAAK,QAAQ;EAI7C,MAAM,cAAc,aAAa;EAMjC,UACJ,cACA,2BACA;IAAW;MACV;EAoCG,YAAY,eAAe;;;;;EAsB3B,YACJ,cACA;IAAS;IAAmB;MAC3B"}

package/dist/aws/engine-step.mjs

@@ -1,6 +1,6 @@
 import { isRetryable } from "../engine/retry.mjs";
 import { CallbackTimeoutError } from "@aws/durable-execution-sdk-js";
-//#region src/aws/engine-step.ts
+// src/aws/engine-step.ts
 /**
 * EngineStep over a Lambda durable execution.
 *
@@ -95,7 +95,6 @@ var AwsEngineStep = class {
 		}
 	}
 };
-//#endregion
 export { AwsEngineStep, stepRetry };
 
 //# sourceMappingURL=engine-step.mjs.map

package/dist/aws/function-url.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let node_buffer = require("node:buffer");
-//#region src/aws/function-url.ts
+// src/aws/function-url.ts
 /**
 * An HTTP request, told apart by the event's own top-level shape — the Function URL wraps
 * every request in `requestContext.http`, so no request body can pass for anything else.
@@ -46,7 +46,6 @@ async function fromResponse(response, method) {
 		isBase64Encoded: !textual
 	};
 }
-//#endregion
 exports.fromResponse = fromResponse;
 exports.isFunctionUrlEvent = isFunctionUrlEvent;
 exports.toRequest = toRequest;

package/dist/aws/function-url.d.cts

@@ -1,4 +1,3 @@
-//#region src/aws/function-url.d.ts
 /**
  * Lambda Function URL events (payload format 2.0) as fetch `Request`s, and `Response`s back as
  * the result Lambda turns into the HTTP response — so the host's HTTP API runs unchanged.
@@ -34,5 +33,4 @@ export interface FunctionUrlResult {
 export declare function isFunctionUrlEvent(event: unknown): event is FunctionUrlEvent;
 export declare function toRequest(event: FunctionUrlEvent): Request;
 export declare function fromResponse(response: Response, method: string): Promise<FunctionUrlResult>;
-//#endregion
 //# sourceMappingURL=function-url.d.cts.map

package/dist/aws/function-url.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"function-url.d.cts","names":[],"sources":["../../src/aws/function-url.ts"],"mappings":";;;;;iBAMiB;EACf;EACA;EACA;EACA,UAAU;EACV;EACA;EACA;EACA;IACE;IACA;MAAQ;MAAgB;MAAmB;;;;iBAI9B;EACf;EACA,SAAS;EACT;EACA;EACA;;;;;;wBAOc,mBAAmB,iBAAiB,SAAS;wBAoB7C,UAAU,OAAO,mBAAmB;wBA4B9B,aAAa,UAAU,UAAU,iBAAiB,QAAQ"}
+{"version":3,"file":"function-url.d.cts","names":[],"sources":["../../src/aws/function-url.ts"],"mappings":";;;;iBAMiB;EACf;EACA;EACA;EACA,UAAU;EACV;EACA;EACA;EACA;IACE;IACA;MAAQ;MAAgB;MAAmB;;;;iBAI9B;EACf;EACA,SAAS;EACT;EACA;EACA;;;;;;wBAOc,mBAAmB,iBAAiB,SAAS;wBAoB7C,UAAU,OAAO,mBAAmB;wBA4B9B,aAAa,UAAU,UAAU,iBAAiB,QAAQ"}

package/dist/aws/function-url.d.mts

@@ -1,4 +1,3 @@
-//#region src/aws/function-url.d.ts
 /**
  * Lambda Function URL events (payload format 2.0) as fetch `Request`s, and `Response`s back as
  * the result Lambda turns into the HTTP response — so the host's HTTP API runs unchanged.
@@ -34,5 +33,4 @@ export interface FunctionUrlResult {
 export declare function isFunctionUrlEvent(event: unknown): event is FunctionUrlEvent;
 export declare function toRequest(event: FunctionUrlEvent): Request;
 export declare function fromResponse(response: Response, method: string): Promise<FunctionUrlResult>;
-//#endregion
 //# sourceMappingURL=function-url.d.mts.map

package/dist/aws/function-url.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"function-url.d.mts","names":[],"sources":["../../src/aws/function-url.ts"],"mappings":";;;;;iBAMiB;EACf;EACA;EACA;EACA,UAAU;EACV;EACA;EACA;EACA;IACE;IACA;MAAQ;MAAgB;MAAmB;;;;iBAI9B;EACf;EACA,SAAS;EACT;EACA;EACA;;;;;;wBAOc,mBAAmB,iBAAiB,SAAS;wBAoB7C,UAAU,OAAO,mBAAmB;wBA4B9B,aAAa,UAAU,UAAU,iBAAiB,QAAQ"}
+{"version":3,"file":"function-url.d.mts","names":[],"sources":["../../src/aws/function-url.ts"],"mappings":";;;;iBAMiB;EACf;EACA;EACA;EACA,UAAU;EACV;EACA;EACA;EACA;IACE;IACA;MAAQ;MAAgB;MAAmB;;;;iBAI9B;EACf;EACA,SAAS;EACT;EACA;EACA;;;;;;wBAOc,mBAAmB,iBAAiB,SAAS;wBAoB7C,UAAU,OAAO,mBAAmB;wBA4B9B,aAAa,UAAU,UAAU,iBAAiB,QAAQ"}