@shware/workflow 5.0.1 → 6.1.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,35 +493,52 @@ 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; its preferences link is the config's
+`email.preferencesUrl` with the copy's message id, when the copy has one; a
+transactional email never has either (`resolveEmail` is the rule). A layout
+reads them from the render, never from a constant, so a template's own URL
+reaches its HTML and each copy's link names that copy; 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';
 
-const { unsubscribeUrl } = useEmailContext();
+const { unsubscribeUrl, preferencesUrl } = useEmailContext();
+{
+  preferencesUrl !== undefined && <Link href={preferencesUrl}>Email preferences</Link>;
+}
 {
   unsubscribeUrl !== undefined && <Link href={unsubscribeUrl}>Unsubscribe</Link>;
 }
@@ -501,6 +548,7 @@ const { unsubscribeUrl } = useEmailContext();
 // workflow.config.ts
 email: {
   unsubscribeUrl: 'https://acme.test/unsubscribe', // templates without their own
+  preferencesUrl: 'https://acme.test/settings/email', // the app's preference page
   tracking: { quickClickMs: 1_000 }, // the default
 },
 ```
@@ -527,10 +575,43 @@ 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.
+
+So a topic email carries two ways out, for two readers. The **header** is for the mail client:
+`List-Unsubscribe` points at the Worker's own `/t/u/<message>`, which a one-click POST or the
+Worker's plain confirmation page settles without the app. The **footer** is for the person:
+`preferencesUrl` is the app's own page, branded, signed in or not, reached as
+`https://acme.test/settings/email?m=<message id>` (the page's own query is kept, `m` set beside
+it). The message id in `m` is how the page knows the recipient without a login: it is the
+capability, an unguessable UUID that only ever reached that mailbox, the same trust `/t/u` runs
+on. The page's API calls `GET /subscriptions/by-message/<m>` with the bearer
+(`JourneyClient.getSubscriptionsByMessage`), gets the recipient's record plus
+`message: { channel, topic }` to highlight the topic that email belonged to, and writes with
+`PUT /subscriptions/by-message/<m>` (`setSubscriptionsByMessage`), the same patch as the user
+endpoint. An id that names no copy (never sent, or erased with its user by `/users/forget`) or a
+transactional one answers 404, the rule `/t/u` applies: show the link as expired. The Worker
+does not rate-limit these routes; the app's proxy does, as it sees fit. The link is tracked as
+an ordinary click (`/t/l/...`), never as an unsubscribe: `preferencesUrl` must not share its
+origin and path with `unsubscribeUrl` (or a template's own), and the config refuses one that
+does. Without reporting (no Postgres reporting or no `WORKFLOW_ORIGIN`) there is no message id,
+so `preferencesUrl` is `undefined` in the render and the footer shows nothing; a preview
+(`GET /preview` and the studio) renders it with a placeholder id, `PREVIEW_MESSAGE_ID`.
+
+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 +619,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 +634,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 +730,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?, preferencesUrl?, 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.
@@ -681,20 +775,60 @@ throws `JourneyClientError` with its status and body.
 const journeys = new JourneyClient({ contract, origin, token });
 ```
 
-| Method                                        | Endpoint                | Does                                                     |
-| --------------------------------------------- | ----------------------- | -------------------------------------------------------- |
-| `identify(userId, props)`                     | `POST /identify`        | Merge profile properties; `null` removes one             |
-| `track(userId, event, payload, { id?, ts? })` | `POST /events`          | Record an event; starts and wakes journeys               |
-| `registerDevice(userId, { token, platform })` | `POST /devices`         | Register a push token (`ios`, `android` or `web`)        |
-| `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) |
-| `forgetUser(userId)`                          | `POST /users/forget`    | Stop the user's journeys and erase their data            |
-| `deploy(bundle)`                              | `POST /deploy`          | Deploy a compiled bundle                                 |
+| Method                                        | Endpoint                          | Does                                                                      |
+| --------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------- |
+| `identify(userId, props)`                     | `POST /identify`                  | Merge profile properties; `null` removes one                              |
+| `track(userId, event, payload, { id?, ts? })` | `POST /events`                    | Record an event; starts and wakes journeys                                |
+| `registerDevice(userId, { token, platform })` | `POST /devices`                   | Register a push token (`ios`, `android` or `web`)                         |
+| `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                        |
+| `getSubscriptionsByMessage(messageId)`        | `GET /subscriptions/by-message/…` | The recipient's record by a copy's id, plus `message: { channel, topic }` |
+| `setSubscriptionsByMessage(messageId, patch)` | `PUT /subscriptions/by-message/…` | The same patch, for the copy's recipient; answers as the GET does         |
+| `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.
+
+The same page opened from an email's footer, with no session, reads the `m` query parameter the
+`preferencesUrl` link carries and goes by the copy instead of the user (see
+[Email](#email)); a 404 (`JourneyClientError` with `status` 404) is an expired link:
+
+```ts
+// GET /api/email-preferences?m=<message id>, proxied by the app's API, rate-limited there
+const { email, push, message } = await journeys.getSubscriptionsByMessage(m);
+// message: { channel: 'email', topic: 'promotions' } — the email this page was opened from
+await journeys.setSubscriptionsByMessage(m, { email: { topics: { [message.topic]: false } } });
+```
+
 ## Compiling and planning
 
 `compileConfig(config)` returns the `BundleIR` the Worker deploys. It is
@@ -1016,14 +1150,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 +1233,40 @@ 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')`.
+- `GET /subscriptions/by-message/:messageId` answers the same record for the
+  recipient of that copy, plus `message: { channel, topic }` (`channel` is
+  `email` or `push`, the channel the copy went out on); `PUT` takes the same
+  patch as `/subscriptions/:userId` and answers as the GET does. The message id
+  is the capability (the `m` of an email's `preferencesUrl` link), so the app
+  proxies and rate-limits these routes behind its own API; the bearer still
+  guards them. An id that names no copy — never sent, not a UUID, or erased
+  with its user — or a transactional copy (`topic` null) answers 404, the rule
+  `/t/u` applies; a user whose erasure is pending answers 410, as above.
+- `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/aws/index.cjs

@@ -1,11 +1,11 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_http2_client = require("../http2-client.cjs");
 const require_engine_retry = require("../engine/retry.cjs");
+const require_host_ingest = require("../host/ingest.cjs");
 const require_aws_engine_step = require("./engine-step.cjs");
 const require_aws_function_url = require("./function-url.cjs");
 const require_engine_duration = require("../engine/duration.cjs");
 const require_host_fresh_read = require("../host/fresh-read.cjs");
-const require_host_ingest = require("../host/ingest.cjs");
 const require_host_execute = require("../host/execute.cjs");
 const require_host_auth = require("../host/auth.cjs");
 const require_host_journey_host = require("../host/journey-host.cjs");

package/dist/aws/index.mjs

@@ -1,10 +1,10 @@
 import { http2Fetch } from "../http2-client.mjs";
 import { PermanentError } from "../engine/retry.mjs";
+import { sweepMaintenance, sweepSegmentsPaged } from "../host/ingest.mjs";
 import { AwsEngineStep, stepRetry } from "./engine-step.mjs";
 import { fromResponse, isFunctionUrlEvent, toRequest } from "./function-url.mjs";
 import { longestJourneyMs } from "../engine/duration.mjs";
 import { readWithRetry } from "../host/fresh-read.mjs";
-import { sweepMaintenance, sweepSegmentsPaged } from "../host/ingest.mjs";
 import { executeJourney } from "../host/execute.mjs";
 import { bearerMatches, timingSafeEqual } from "../host/auth.mjs";
 import { createJourneyHost } from "../host/journey-host.mjs";

package/dist/client.cjs

@@ -1,4 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_host_ingest = require("./host/ingest.cjs");
 // src/client.ts
 var JourneyClientError = class extends Error {
 	path;
@@ -104,22 +105,85 @@ var JourneyClient = class {
 	removeDevice(token) {
 		return this.post("/devices/remove", { token });
 	}
+	/**
+	* Where the user stands, topic × channel: for `email` and for `push`, `all` (false once they
+	* opted out of the whole channel) and each declared topic (false once they opted out of it on
+	* that channel) — the engine's record, which a preference page shows as it is. The two are
+	* independent flags: a topic answers its own opt-out even while `all` is false, so `all: false`
+	* masks every topic however they read (nothing is sent on the channel until it is true again).
+	* Rejects with a 410 for an erased user.
+	*/
+	getSubscriptions(userId) {
+		return this.request("GET", subscriptionsPath(userId));
+	}
+	/**
+	* Set subscriptions: only what the patch names changes, per channel (`{ email: { topics: {
+	* newsletter: false } } }` opts out of one topic's emails, `{ push: { all: false } }` of every
+	* push — the in-app opt-out App Store Review Guideline 4.5.4 asks for). `all: true` clears the
+	* channel-wide opt-out only: a topic opted out on its own stays off until the patch names it,
+	* so a preference page's "subscribe to all" sends `all: true` plus every topic `true`. Answers
+	* the subscriptions as they now stand. With a contract, a topic it does not declare is refused
+	* here, before the request; the engine refuses it too.
+	*/
+	setSubscriptions(userId, patch) {
+		const refused = this.undeclaredTopics(patch);
+		if (refused !== void 0) return Promise.reject(refused);
+		return this.request("PUT", subscriptionsPath(userId), patch);
+	}
+	/**
+	* `getSubscriptions` for the recipient of one copy, by the message id an email's preferences
+	* link carries (`email.preferencesUrl?m=<message id>`): how a preference page works without a
+	* sign-in. The answer adds `message: { channel, topic }`, the copy the page was opened from,
+	* so it can highlight that topic. Rejects with a 404 for an id that names no copy — never
+	* sent, or erased with its user — and for a transactional one; the page should show the link
+	* as expired. The message id is the capability, so the app proxies this behind its own API
+	* and rate-limits it.
+	*/
+	getSubscriptionsByMessage(messageId) {
+		return this.request("GET", subscriptionsByMessagePath(messageId));
+	}
+	/** `setSubscriptions` for the recipient of one copy; the patch and the answer are those of `getSubscriptionsByMessage`. */
+	setSubscriptionsByMessage(messageId, patch) {
+		const refused = this.undeclaredTopics(patch);
+		if (refused !== void 0) return Promise.reject(refused);
+		return this.request("PUT", subscriptionsByMessagePath(messageId), patch);
+	}
+	/** With a contract, the refusal of a patch naming a topic it does not declare; undefined when the patch is fine. */
+	undeclaredTopics(patch) {
+		const contract = this.options.contract;
+		if (contract === void 0) return void 0;
+		const issues = [];
+		for (const channel of require_host_ingest.SUBSCRIPTION_CHANNELS) for (const topic of Object.keys(patch[channel]?.topics ?? {})) {
+			if (contract.topics.includes(topic)) continue;
+			issues.push({
+				path: `${channel}.topics.${topic}`,
+				message: "not a declared topic"
+			});
+		}
+		return issues.length > 0 ? new JourneyValidationError("/subscriptions", void 0, issues) : void 0;
+	}
 	/** Deploy a compiled bundle (BundleIR). */
 	deploy(bundle) {
 		return this.post("/deploy", bundle);
 	}
-	async post(path, body) {
-		const headers = { "content-type": "application/json" };
+	post(path, body) {
+		return this.request("POST", path, body);
+	}
+	async request(method, path, body) {
+		const headers = {};
+		if (body !== void 0) headers["content-type"] = "application/json";
 		if (this.options.token !== void 0) headers.authorization = `Bearer ${this.options.token}`;
 		const response = await (this.options.fetch ?? fetch)(`${this.options.origin.replace(/\/$/, "")}${path}`, {
-			method: "POST",
+			method,
 			headers,
-			body: JSON.stringify(body)
+			...body === void 0 ? {} : { body: JSON.stringify(body) }
 		});
 		if (!response.ok) throw new JourneyClientError(path, response.status, await response.text());
 		return await response.json();
 	}
 };
+const subscriptionsPath = (userId) => `/subscriptions/${encodeURIComponent(userId)}`;
+const subscriptionsByMessagePath = (messageId) => `/subscriptions/by-message/${encodeURIComponent(messageId)}`;
 exports.JourneyClient = JourneyClient;
 exports.JourneyClientError = JourneyClientError;
 exports.JourneyValidationError = JourneyValidationError;

package/dist/client.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"client.cjs","names":[],"sources":["../src/client.ts"],"sourcesContent":["import type * as core from 'zod/v4/core';\nimport type { Contract, ContractIssue, ProfilePatch } from './contract';\nimport type { DeployResult, IdentifyResult, IngestResult } from './host/ingest';\nimport type { ProfileProps } from './store';\n\n/**\n * `@shware/workflow/client` — the producer side of the ingest API, for the\n * service that knows what users do (an api server, a webhook handler). Plain\n * fetch, no dependencies; errors carry the status and body so a caller can\n * log them without failing the request that triggered the report.\n */\n\nexport interface JourneyClientOptions<C extends Contract | undefined = undefined> {\n  /**\n   * The shared `defineContract(...)`: types `track` (the event name picks the\n   * payload type) and `identify`, and checks both before anything is sent.\n   */\n  contract?: C;\n  /** The journey Worker's origin, e.g. `https://workflow.example.com`. */\n  origin: string;\n  /** Its API_TOKEN, sent as a bearer; omit against an open local instance. */\n  token?: string;\n  /** Fetch implementation (defaults to the global one). */\n  fetch?: typeof fetch;\n}\n\nexport class JourneyClientError extends Error {\n  constructor(\n    readonly path: string,\n    readonly status: number,\n    readonly body: string\n  ) {\n    super(`journey ${path} failed: ${status} ${body}`);\n    this.name = 'JourneyClientError';\n  }\n}\n\n/** A payload or profile patch the contract refuses — raised before the request, with the field paths. */\nexport class JourneyValidationError extends Error {\n  constructor(\n    readonly path: string,\n    readonly event: string | undefined,\n    readonly issues: ContractIssue[]\n  ) {\n    super(\n      `journey ${path}${event === undefined ? '' : ` '${event}'`} refused by the contract: ${issues\n        .map((i) => `${i.path || '(root)'} ${i.message}`)\n        .join('; ')}`\n    );\n    this.name = 'JourneyValidationError';\n  }\n}\n\ntype EventsOf<C> = C extends Contract<infer E> ? E : never;\n/** Event names: the contract's, or any string without one. */\nexport type ClientEventName<C> = [C] extends [undefined] ? string : keyof EventsOf<C> & string;\ntype TrackArgs<C, K> = [C] extends [undefined]\n  ? [payload?: Record<string, unknown>, options?: TrackOptions]\n  : K extends keyof EventsOf<C>\n    ? [payload: core.input<EventsOf<C>[K]>, options?: TrackOptions]\n    : never;\ntype IdentifyProps<C> = [C] extends [undefined]\n  ? ProfileProps\n  : C extends Contract<Record<string, core.$ZodObject>, infer P>\n    ? ProfilePatch<P>\n    : never;\n\nexport interface TrackOptions {\n  /** The occurrence's identity: a retry with the same id is recorded once. */\n  id?: string;\n  /** When it happened (epoch ms); the Worker's clock when omitted. */\n  ts?: number;\n}\n\nexport class JourneyClient<C extends Contract | undefined = undefined> {\n  constructor(private readonly options: JourneyClientOptions<C>) {}\n\n  /** Merge profile properties (`null` clears one). Every property a journey reads must be identified before the event that starts it. */\n  identify(userId: string, props: IdentifyProps<C>): Promise<IdentifyResult> {\n    const contract = this.options.contract;\n    if (contract !== undefined) {\n      const result = contract.parseProfilePatch(props);\n      if (!result.ok)\n        return Promise.reject(new JourneyValidationError('/identify', undefined, result.issues));\n    }\n    return this.post<IdentifyResult>('/identify', { userId, props });\n  }\n\n  /**\n   * Record an event; the Worker starts every journey whose trigger matches it\n   * and wakes waits on it. A caller that retries should pass the same `id`\n   * each time: the Worker stores one occurrence per id, so a retry after a\n   * timeout cannot double-count the event. `ts` defaults to the Worker's clock.\n   */\n  track<K extends ClientEventName<C>>(\n    userId: string,\n    event: K,\n    ...args: TrackArgs<C, K>\n  ): Promise<IngestResult> {\n    const [payload = {}, options = {}] = args as [Record<string, unknown>?, TrackOptions?];\n    const contract = this.options.contract;\n    if (contract !== undefined) {\n      const result = contract.parseEvent(event, payload);\n      if (!result.ok)\n        return Promise.reject(new JourneyValidationError('/events', event, result.issues));\n    }\n    return this.post<IngestResult>('/events', {\n      userId,\n      event,\n      payload,\n      ...(options.id === undefined ? {} : { id: options.id }),\n      ...(options.ts === undefined ? {} : { ts: options.ts }),\n    });\n  }\n\n  /**\n   * A push token the app registered for the user (call it on every registration: a token moves\n   * to the latest user). The engine keeps devices itself — pushes go to them, a token APNs / FCM\n   * reports as gone is dropped — and journeys waiting on `reachable('push')` wake.\n   */\n  registerDevice(\n    userId: string,\n    device: { token: string; platform: 'ios' | 'android' | 'web'; ts?: number }\n  ): Promise<{ ok: true; woke: number }> {\n    const { token, platform, ts } = device;\n    return this.post('/devices', {\n      userId,\n      token,\n      platform,\n      ...(ts === undefined ? {} : { ts }),\n    });\n  }\n\n  /**\n   * A journey push tapped open: the `message_id` the push carried, reported for the user who\n   * tapped it. Recorded as a human open on the copy (an email's opens are tracked by the Worker).\n   */\n  messageOpened(userId: string, messageId: string): Promise<{ ok: true; recorded: boolean }> {\n    return this.post('/messages/opened', { userId, messageId });\n  }\n\n  /**\n   * A deleted account: the engine records the erasure, stops the user's running journeys, then\n   * erases everything it keeps about them (profile, devices, events, reporting). Once this\n   * resolves the request is durable: `erased: false` means an instance would not stop yet, and\n   * the Worker's scheduled sweep finishes the job.\n   */\n  forgetUser(userId: string): Promise<{ ok: true; erased: boolean; pending: string[] }> {\n    return this.post('/users/forget', { userId });\n  }\n\n  /** The user signed out on that device: the token stays registered, bound to nobody. */\n  unbindDevice(token: string): Promise<{ ok: true; woke: number }> {\n    return this.post('/devices/unbind', { token });\n  }\n\n  /** Forget a push token for good (an uninstall the app learned of, a token it replaced). */\n  removeDevice(token: string): Promise<{ ok: true; woke: number }> {\n    return this.post('/devices/remove', { token });\n  }\n\n  /** Deploy a compiled bundle (BundleIR). */\n  deploy(bundle: unknown): Promise<DeployResult> {\n    return this.post<DeployResult>('/deploy', bundle);\n  }\n\n  private async post<T>(path: string, body: unknown): Promise<T> {\n    const headers: Record<string, string> = { 'content-type': 'application/json' };\n    if (this.options.token !== undefined) headers.authorization = `Bearer ${this.options.token}`;\n    const doFetch = this.options.fetch ?? fetch;\n    const response = await doFetch(`${this.options.origin.replace(/\\/$/, '')}${path}`, {\n      method: 'POST',\n      headers,\n      body: JSON.stringify(body),\n    });\n    if (!response.ok) throw new JourneyClientError(path, response.status, await response.text());\n    return (await response.json()) as T;\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"client.cjs","names":["SUBSCRIPTION_CHANNELS"],"sources":["../src/client.ts"],"sourcesContent":["import type * as core from 'zod/v4/core';\nimport type { Contract, ContractIssue, ProfilePatch, Topic } from './contract';\nimport {\n  type DeployResult,\n  type IdentifyResult,\n  type IngestResult,\n  type MessageSubscriptions,\n  SUBSCRIPTION_CHANNELS,\n  type Subscriptions,\n  type SubscriptionsPatch,\n} from './host/ingest';\nimport type { ProfileProps } from './store';\n\n/**\n * `@shware/workflow/client` — the producer side of the ingest API, for the\n * service that knows what users do (an api server, a webhook handler). Plain\n * fetch, no dependencies; errors carry the status and body so a caller can\n * log them without failing the request that triggered the report.\n */\n\nexport interface JourneyClientOptions<C extends Contract | undefined = undefined> {\n  /**\n   * The shared `defineContract(...)`: types `track` (the event name picks the\n   * payload type) and `identify`, and checks both before anything is sent.\n   */\n  contract?: C;\n  /** The journey Worker's origin, e.g. `https://workflow.example.com`. */\n  origin: string;\n  /** Its API_TOKEN, sent as a bearer; omit against an open local instance. */\n  token?: string;\n  /** Fetch implementation (defaults to the global one). */\n  fetch?: typeof fetch;\n}\n\nexport class JourneyClientError extends Error {\n  constructor(\n    readonly path: string,\n    readonly status: number,\n    readonly body: string\n  ) {\n    super(`journey ${path} failed: ${status} ${body}`);\n    this.name = 'JourneyClientError';\n  }\n}\n\n/** A payload or profile patch the contract refuses — raised before the request, with the field paths. */\nexport class JourneyValidationError extends Error {\n  constructor(\n    readonly path: string,\n    readonly event: string | undefined,\n    readonly issues: ContractIssue[]\n  ) {\n    super(\n      `journey ${path}${event === undefined ? '' : ` '${event}'`} refused by the contract: ${issues\n        .map((i) => `${i.path || '(root)'} ${i.message}`)\n        .join('; ')}`\n    );\n    this.name = 'JourneyValidationError';\n  }\n}\n\ntype EventsOf<C> = C extends Contract<infer E> ? E : never;\n/** Event names: the contract's, or any string without one. */\nexport type ClientEventName<C> = [C] extends [undefined] ? string : keyof EventsOf<C> & string;\ntype TrackArgs<C, K> = [C] extends [undefined]\n  ? [payload?: Record<string, unknown>, options?: TrackOptions]\n  : K extends keyof EventsOf<C>\n    ? [payload: core.input<EventsOf<C>[K]>, options?: TrackOptions]\n    : never;\ntype IdentifyProps<C> = [C] extends [undefined]\n  ? ProfileProps\n  : C extends Contract<Record<string, core.$ZodObject>, infer P>\n    ? ProfilePatch<P>\n    : never;\n\n/** The topics the client's contract declares; any string without a contract. */\nexport type ClientTopic<C> = [C] extends [undefined] ? string : Topic<C>;\n\nexport type {\n  ChannelSubscriptions,\n  ChannelSubscriptionsPatch,\n  MessageOrigin,\n  MessageSubscriptions,\n  SubscriptionChannel,\n  Subscriptions,\n  SubscriptionsPatch,\n} from './host/ingest';\n\nexport interface TrackOptions {\n  /** The occurrence's identity: a retry with the same id is recorded once. */\n  id?: string;\n  /** When it happened (epoch ms); the Worker's clock when omitted. */\n  ts?: number;\n}\n\nexport class JourneyClient<C extends Contract | undefined = undefined> {\n  constructor(private readonly options: JourneyClientOptions<C>) {}\n\n  /** Merge profile properties (`null` clears one). Every property a journey reads must be identified before the event that starts it. */\n  identify(userId: string, props: IdentifyProps<C>): Promise<IdentifyResult> {\n    const contract = this.options.contract;\n    if (contract !== undefined) {\n      const result = contract.parseProfilePatch(props);\n      if (!result.ok)\n        return Promise.reject(new JourneyValidationError('/identify', undefined, result.issues));\n    }\n    return this.post<IdentifyResult>('/identify', { userId, props });\n  }\n\n  /**\n   * Record an event; the Worker starts every journey whose trigger matches it\n   * and wakes waits on it. A caller that retries should pass the same `id`\n   * each time: the Worker stores one occurrence per id, so a retry after a\n   * timeout cannot double-count the event. `ts` defaults to the Worker's clock.\n   */\n  track<K extends ClientEventName<C>>(\n    userId: string,\n    event: K,\n    ...args: TrackArgs<C, K>\n  ): Promise<IngestResult> {\n    const [payload = {}, options = {}] = args as [Record<string, unknown>?, TrackOptions?];\n    const contract = this.options.contract;\n    if (contract !== undefined) {\n      const result = contract.parseEvent(event, payload);\n      if (!result.ok)\n        return Promise.reject(new JourneyValidationError('/events', event, result.issues));\n    }\n    return this.post<IngestResult>('/events', {\n      userId,\n      event,\n      payload,\n      ...(options.id === undefined ? {} : { id: options.id }),\n      ...(options.ts === undefined ? {} : { ts: options.ts }),\n    });\n  }\n\n  /**\n   * A push token the app registered for the user (call it on every registration: a token moves\n   * to the latest user). The engine keeps devices itself — pushes go to them, a token APNs / FCM\n   * reports as gone is dropped — and journeys waiting on `reachable('push')` wake.\n   */\n  registerDevice(\n    userId: string,\n    device: { token: string; platform: 'ios' | 'android' | 'web'; ts?: number }\n  ): Promise<{ ok: true; woke: number }> {\n    const { token, platform, ts } = device;\n    return this.post('/devices', {\n      userId,\n      token,\n      platform,\n      ...(ts === undefined ? {} : { ts }),\n    });\n  }\n\n  /**\n   * A journey push tapped open: the `message_id` the push carried, reported for the user who\n   * tapped it. Recorded as a human open on the copy (an email's opens are tracked by the Worker).\n   */\n  messageOpened(userId: string, messageId: string): Promise<{ ok: true; recorded: boolean }> {\n    return this.post('/messages/opened', { userId, messageId });\n  }\n\n  /**\n   * A deleted account: the engine records the erasure, stops the user's running journeys, then\n   * erases everything it keeps about them (profile, devices, events, reporting). Once this\n   * resolves the request is durable: `erased: false` means an instance would not stop yet, and\n   * the Worker's scheduled sweep finishes the job.\n   */\n  forgetUser(userId: string): Promise<{ ok: true; erased: boolean; pending: string[] }> {\n    return this.post('/users/forget', { userId });\n  }\n\n  /** The user signed out on that device: the token stays registered, bound to nobody. */\n  unbindDevice(token: string): Promise<{ ok: true; woke: number }> {\n    return this.post('/devices/unbind', { token });\n  }\n\n  /** Forget a push token for good (an uninstall the app learned of, a token it replaced). */\n  removeDevice(token: string): Promise<{ ok: true; woke: number }> {\n    return this.post('/devices/remove', { token });\n  }\n\n  /**\n   * Where the user stands, topic × channel: for `email` and for `push`, `all` (false once they\n   * opted out of the whole channel) and each declared topic (false once they opted out of it on\n   * that channel) — the engine's record, which a preference page shows as it is. The two are\n   * independent flags: a topic answers its own opt-out even while `all` is false, so `all: false`\n   * masks every topic however they read (nothing is sent on the channel until it is true again).\n   * Rejects with a 410 for an erased user.\n   */\n  getSubscriptions(userId: string): Promise<Subscriptions<ClientTopic<C>>> {\n    return this.request('GET', subscriptionsPath(userId));\n  }\n\n  /**\n   * Set subscriptions: only what the patch names changes, per channel (`{ email: { topics: {\n   * newsletter: false } } }` opts out of one topic's emails, `{ push: { all: false } }` of every\n   * push — the in-app opt-out App Store Review Guideline 4.5.4 asks for). `all: true` clears the\n   * channel-wide opt-out only: a topic opted out on its own stays off until the patch names it,\n   * so a preference page's \"subscribe to all\" sends `all: true` plus every topic `true`. Answers\n   * the subscriptions as they now stand. With a contract, a topic it does not declare is refused\n   * here, before the request; the engine refuses it too.\n   */\n  setSubscriptions(\n    userId: string,\n    patch: SubscriptionsPatch<ClientTopic<C>>\n  ): Promise<Subscriptions<ClientTopic<C>>> {\n    const refused = this.undeclaredTopics(patch);\n    if (refused !== undefined) return Promise.reject(refused);\n    return this.request('PUT', subscriptionsPath(userId), patch);\n  }\n\n  /**\n   * `getSubscriptions` for the recipient of one copy, by the message id an email's preferences\n   * link carries (`email.preferencesUrl?m=<message id>`): how a preference page works without a\n   * sign-in. The answer adds `message: { channel, topic }`, the copy the page was opened from,\n   * so it can highlight that topic. Rejects with a 404 for an id that names no copy — never\n   * sent, or erased with its user — and for a transactional one; the page should show the link\n   * as expired. The message id is the capability, so the app proxies this behind its own API\n   * and rate-limits it.\n   */\n  getSubscriptionsByMessage(messageId: string): Promise<MessageSubscriptions<ClientTopic<C>>> {\n    return this.request('GET', subscriptionsByMessagePath(messageId));\n  }\n\n  /** `setSubscriptions` for the recipient of one copy; the patch and the answer are those of `getSubscriptionsByMessage`. */\n  setSubscriptionsByMessage(\n    messageId: string,\n    patch: SubscriptionsPatch<ClientTopic<C>>\n  ): Promise<MessageSubscriptions<ClientTopic<C>>> {\n    const refused = this.undeclaredTopics(patch);\n    if (refused !== undefined) return Promise.reject(refused);\n    return this.request('PUT', subscriptionsByMessagePath(messageId), patch);\n  }\n\n  /** With a contract, the refusal of a patch naming a topic it does not declare; undefined when the patch is fine. */\n  private undeclaredTopics(\n    patch: SubscriptionsPatch<ClientTopic<C>>\n  ): JourneyValidationError | undefined {\n    const contract = this.options.contract;\n    if (contract === undefined) return undefined;\n    const issues: ContractIssue[] = [];\n    for (const channel of SUBSCRIPTION_CHANNELS) {\n      for (const topic of Object.keys(patch[channel]?.topics ?? {})) {\n        // `includes`, not the predicate: narrowing `string` by a `topic is string` leaves `never`\n        if (contract.topics.includes(topic)) continue;\n        issues.push({ path: `${channel}.topics.${topic}`, message: 'not a declared topic' });\n      }\n    }\n    return issues.length > 0\n      ? new JourneyValidationError('/subscriptions', undefined, issues)\n      : undefined;\n  }\n\n  /** Deploy a compiled bundle (BundleIR). */\n  deploy(bundle: unknown): Promise<DeployResult> {\n    return this.post<DeployResult>('/deploy', bundle);\n  }\n\n  private post<T>(path: string, body: unknown): Promise<T> {\n    return this.request<T>('POST', path, body);\n  }\n\n  private async request<T>(\n    method: 'GET' | 'POST' | 'PUT',\n    path: string,\n    body?: unknown\n  ): Promise<T> {\n    const headers: Record<string, string> = {};\n    if (body !== undefined) headers['content-type'] = 'application/json';\n    if (this.options.token !== undefined) headers.authorization = `Bearer ${this.options.token}`;\n    const doFetch = this.options.fetch ?? fetch;\n    const response = await doFetch(`${this.options.origin.replace(/\\/$/, '')}${path}`, {\n      method,\n      headers,\n      ...(body === undefined ? {} : { body: JSON.stringify(body) }),\n    });\n    if (!response.ok) throw new JourneyClientError(path, response.status, await response.text());\n    return (await response.json()) as T;\n  }\n}\n\nconst subscriptionsPath = (userId: string) => `/subscriptions/${encodeURIComponent(userId)}`;\nconst subscriptionsByMessagePath = (messageId: string) =>\n  `/subscriptions/by-message/${encodeURIComponent(messageId)}`;\n"],"mappings":"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"}