@shware/workflow 0.0.0-stage → 0.1.0

package/dist/cloudflare/runner.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.mjs","names":[],"sources":["../../src/cloudflare/runner.ts"],"sourcesContent":["import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from 'cloudflare:workers';\nimport { NonRetryableError } from 'cloudflare:workflows';\nimport { type Contract, ContractValidationError, checkEvent } from '../contract';\nimport { type RegisteredAction, RegistryActionInvoker } from '../engine/actions';\nimport { runJourney } from '../engine/interpreter';\nimport type {\n  ActionInvoker,\n  EngineStep,\n  EventSink,\n  JourneyObserver,\n  JourneyOutcome,\n  MessageSender,\n  MessageValidator,\n} from '../engine/ports';\nimport { scaleDurations } from '../engine/time-scale';\nimport { type JourneyRuntimeOptions, resolveRuntime } from '../runtime';\nimport { JourneyFactSource } from '../store/facts';\nimport type { JourneyStore } from '../store/index';\nimport { type JourneyEnv, type JourneyParams, WAKE_EVENT_TYPE, wakeExpired } from './bindings';\nimport { d1Store } from './d1-env';\nimport { ingestEvent } from './router';\nimport { LogMessageSender, WebhookMessageSender } from './senders';\n\n/**\n * Adapts CF's WorkflowStep to EngineStep.\n * subscribe/unsubscribe write the subscription table inside durable steps (the\n * router wakes instances from that table); waitForWake parks on CF's\n * waitForEvent, which signals a timeout by throwing — and so does every other\n * failure in there, so only the clock can tell them apart (see wakeExpired).\n */\n/** Refusals a retry would only repeat: a template's props, an emitted event's payload. */\nconst NON_RETRYABLE = new Set(['TemplateValidationError', 'ContractValidationError']);\n\nclass CfEngineStep implements EngineStep {\n  constructor(\n    private readonly step: WorkflowStep,\n    private readonly store: JourneyStore,\n    private readonly userId: string,\n    private readonly instanceId: string\n  ) {}\n\n  /**\n   * A template refusing its props, or the contract refusing an emitted event,\n   * is deterministic — a retry hits the same refusal — so it ends the step at\n   * once instead of burning the retry budget.\n   */\n  do<T>(name: string, fn: () => Promise<T>): Promise<T> {\n    return this.step.do(name, async () => {\n      try {\n        return await fn();\n      } catch (error) {\n        if (error instanceof Error && NON_RETRYABLE.has(error.name)) {\n          throw new NonRetryableError(error.message, error.name);\n        }\n        throw error;\n      }\n    });\n  }\n\n  sleep(name: string, ms: number): Promise<void> {\n    return this.step.sleep(name, ms);\n  }\n\n  sleepUntil(name: string, timestampMs: number): Promise<void> {\n    return this.step.sleepUntil(name, timestampMs);\n  }\n\n  subscribe(name: string, events: readonly string[]): Promise<void> {\n    // Idempotent in the store: the interpreter re-subscribes on every wait\n    // attempt (one-shot-callback contract) and registrations persist here.\n    return this.step.do(name, () =>\n      this.store.subscribe(this.instanceId, this.userId, events, Date.now())\n    );\n  }\n\n  unsubscribe(name: string): Promise<void> {\n    return this.step.do(name, () => this.store.unsubscribe(this.instanceId));\n  }\n\n  async waitForWake(name: string, timeoutMs: number): Promise<'event' | 'timeout'> {\n    const startedAt = Date.now();\n    try {\n      await this.step.waitForEvent(name, { type: WAKE_EVENT_TYPE, timeout: timeoutMs });\n      return 'event';\n    } catch (error) {\n      /*\n       * Only the deadline can tell a real timeout from a failure (see\n       * wakeExpired). `startedAt` is not replay-stable, but it is read only\n       * inside the step body below, and a step body runs on the live attempt\n       * alone — a replay returns the persisted verdict without touching the\n       * clock.\n       */\n      const timedOut = await this.step.do(`${name}:timed-out`, async () =>\n        wakeExpired(startedAt, timeoutMs, Date.now())\n      );\n      if (timedOut) return 'timeout';\n      throw error;\n    }\n  }\n}\n\n/** Development aid: echo each outbound message before handing it to the real sender. */\nfunction logging(sender: MessageSender): MessageSender {\n  return {\n    async send(message) {\n      console.log(\n        `[journey] ${message.channel} ${message.template} → ${message.recipient ?? message.userId} ${JSON.stringify(message.props)}`\n      );\n      return sender.send(message);\n    },\n  };\n}\n\n/**\n * The generic journey executor: one class runs every workflow, because IR is\n * data. It is loaded from the store by the contentHash pinned at entry —\n * content addressing makes it immutable, so reading it outside a step is\n * replay-safe.\n */\nexport class JourneyRunner extends WorkflowEntrypoint<JourneyEnv, JourneyParams> {\n  /**\n   * The data plane. D1 + KV from the env by default; an app on Postgres\n   * overrides this (and `closeStore` if its client needs closing):\n   *\n   *   protected override createStore() { return new PostgresJourneyStore(client(this.env)); }\n   */\n  protected createStore(): JourneyStore {\n    return d1Store(this.env);\n  }\n\n  /** Called once `run` is over, success or not — release whatever `createStore` opened. */\n  protected async closeStore(_store: JourneyStore): Promise<void> {}\n\n  /**\n   * Runtime options for this instance — typed configuration, resolved by the app (typically\n   * `resolveRuntime(config.runtime, mode)` over its workflow.config.ts, with the mode coming from\n   * an ENVIRONMENT var). The instance params are passed so the decision can also be per user:\n   * a tester account in production can run in fast-forward while everyone else runs in real\n   * time. Defaults: real time, quiet.\n   *\n   *   protected override runtime({ userId }) {\n   *     return resolveRuntime(workflowConfig.runtime, isTester(userId) ? 'test' : this.env.ENVIRONMENT);\n   *   }\n   */\n  protected runtime(_params: JourneyParams): JourneyRuntimeOptions {\n    return resolveRuntime(undefined, 'production');\n  }\n\n  /**\n   * Message outlet; an app overrides this to plug in real channels (say\n   * CfEmailSender with a react-email renderer). By default it picks the webhook\n   * or logging sender based on the environment.\n   */\n  protected createMessageSender(): MessageSender {\n    return this.env.MESSAGE_WEBHOOK_URL\n      ? new WebhookMessageSender(this.env.MESSAGE_WEBHOOK_URL)\n      : new LogMessageSender();\n  }\n\n  /**\n   * Custom-action registry; an app overrides this returning the same\n   * `action(...)` objects its workflows reference (an ActionRef is a\n   * RegisteredAction structurally) — the code plane of the dual-plane model:\n   *\n   *   protected override actions() { return [syncCrm, issueCoupon]; }\n   */\n  protected actions(): readonly RegisteredAction[] {\n    return [];\n  }\n\n  /**\n   * The contract events this journey emits (`.sendEvent()`) are checked\n   * against, exactly like ingest; journeyWorker passes its config's.\n   */\n  protected contract(): Contract | undefined {\n    return undefined;\n  }\n\n  /**\n   * Template props check before every send; an app overrides this with\n   * `registryValidator({ emails, pushes })` (journeyWorker does it from its\n   * registries). By default props go out as resolved.\n   */\n  protected createMessageValidator(): MessageValidator | undefined {\n    return undefined;\n  }\n\n  /**\n   * Reporting hooks: node arrivals, every copy sent, how each instance ended. The host stores\n   * what it needs for its dashboards; by default nothing is reported.\n   */\n  protected createObserver(_store: JourneyStore): JourneyObserver | undefined {\n    return undefined;\n  }\n\n  /** Override for a different version policy ('warn' by default) or a fully custom invoker (e.g. webhook degradation for hosted tenants). */\n  protected createActionInvoker(): ActionInvoker {\n    return new RegistryActionInvoker(this.actions());\n  }\n\n  async run(event: WorkflowEvent<JourneyParams>, step: WorkflowStep): Promise<JourneyOutcome> {\n    const store = this.createStore();\n    try {\n      return await this.execute(event, step, store);\n    } finally {\n      await this.closeStore(store);\n    }\n  }\n\n  private async execute(\n    event: WorkflowEvent<JourneyParams>,\n    step: WorkflowStep,\n    store: JourneyStore\n  ): Promise<JourneyOutcome> {\n    const { workflowId, contentHash, userId } = event.payload;\n    const env = this.env;\n\n    const stored = await store.getWorkflowIR(contentHash);\n    if (stored === undefined) {\n      throw new Error(`WorkflowIR not found: ${workflowId}@${contentHash}`);\n    }\n    const runtime = resolveRuntime({ current: this.runtime(event.payload) }, 'current');\n    // Development runs the journey in fast-forward; the pinned hash still names the version.\n    const ir = scaleDurations(stored, runtime.timeScale);\n\n    const observer = this.createObserver(store);\n    const finished = (status: JourneyOutcome['status'] | 'failed', convertedAt?: number) =>\n      observer?.finished?.({\n        workflow: workflowId,\n        instanceId: event.instanceId,\n        userId,\n        status,\n        at: Date.now(),\n        ...(convertedAt === undefined ? {} : { convertedAt }),\n      });\n\n    const messages = runtime.logMessages\n      ? logging(this.createMessageSender())\n      : this.createMessageSender();\n\n    // send_event feeds straight back into the router logic — an in-Worker call\n    // forming the event edge between workflows. The step's identity travels as\n    // the event id, so a retried emit records the occurrence once.\n    // An emitted event passes the same contract check as one arriving over HTTP.\n    const contract = this.contract();\n    const events: EventSink = {\n      emit: async (name, payload, id) => {\n        let accepted: Record<string, unknown> = payload;\n        if (contract !== undefined) {\n          const verdict = checkEvent(contract, name, payload);\n          if (!verdict.ok) throw new ContractValidationError(name, verdict.issues);\n          accepted = verdict.data;\n        }\n        await ingestEvent(env, { id, userId, event: name, payload: accepted }, store);\n      },\n    };\n\n    let outcome: JourneyOutcome;\n    try {\n      outcome = await runJourney(ir, {\n        userId,\n        instanceId: event.instanceId,\n        // Trigger-event creation time: replay-stable, unlike Date.now() here\n        enteredAtMs: event.timestamp.getTime(),\n        step: new CfEngineStep(step, store, userId, event.instanceId),\n        facts: new JourneyFactSource(store, userId),\n        messages,\n        events,\n        actions: this.createActionInvoker(),\n        validator: this.createMessageValidator(),\n        observer,\n      });\n    } catch (error) {\n      /*\n       * An error escaping run() ends the instance, and the ledger is the only\n       * place anyone looks afterwards: leaving it at 'running' meant a dead\n       * journey stayed indistinguishable from a waiting one, in the dashboard\n       * and in the once-policy, forever.\n       *\n       * Subscriptions are deliberately left in place. They are cleaned up on\n       * every ordinary ending, but here the wake rows are the only evidence of\n       * what the instance was waiting for, and dropping them would also break\n       * the instance if the platform does re-run it.\n       */\n      await step.do('finalize:failed', async () => {\n        await store.setEntryStatus(event.instanceId, 'failed');\n        await finished('failed');\n      });\n      throw error;\n    }\n\n    await step.do('finalize', async () => {\n      await store.setEntryStatus(event.instanceId, outcome.status);\n      await store.unsubscribe(event.instanceId);\n      await finished(outcome.status, outcome.convertedAt);\n    });\n\n    return outcome;\n  }\n}\n"],"mappings":"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"}

package/dist/cloudflare/schema.sql

@@ -0,0 +1,127 @@
+-- Journey engine data plane (D1). Conditions are evaluated by querying at
+-- decision time: lazy, with no real-time segment materialisation.
+
+-- Raw event log. Every count- and window-based condition reads this table, so a
+-- duplicated row silently changes a journey's behaviour, and `id` is what stops
+-- that: it is the occurrence's identity, chosen by whoever sent it, and the key
+-- constraint makes a second delivery of the same occurrence a no-op. Ingest is
+-- reachable from two retrying callers (a client retrying a 500, and the
+-- interpreter's send_event step being retried after it already committed its
+-- row), so both pass an id they can reproduce.
+--
+-- Only the sender knows whether two deliveries describe one occurrence or two,
+-- so the engine never invents that answer: an ingest that arrives without an id
+-- is given a fresh one, which is a truthful "this is its own occurrence" rather
+-- than a guess.
+CREATE TABLE IF NOT EXISTS events (
+  id      TEXT PRIMARY KEY NOT NULL,
+  user_id TEXT NOT NULL,
+  name    TEXT NOT NULL,
+  ts      INTEGER NOT NULL,
+  payload TEXT NOT NULL DEFAULT '{}'
+);
+CREATE INDEX IF NOT EXISTS idx_events_user_name_ts ON events (user_id, name, ts);
+
+CREATE TABLE IF NOT EXISTS profiles (
+  user_id TEXT PRIMARY KEY,
+  props   TEXT NOT NULL DEFAULT '{}'
+);
+
+-- Deploy artefacts: segment definitions (resolved by id during evaluation)
+-- and the trigger routing table.
+-- Push devices: one row per provider token, owned by the user who registered it last.
+-- user_id is null for a device whose user signed out: it stays registered until the next
+-- sign-in binds it again. A database created while it was NOT NULL needs the table rebuilt.
+CREATE TABLE IF NOT EXISTS devices (
+  token    TEXT PRIMARY KEY,
+  user_id  TEXT,
+  platform TEXT NOT NULL,
+  ts       INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_devices_user_ts ON devices (user_id, ts);
+
+CREATE TABLE IF NOT EXISTS segments (
+  id        TEXT PRIMARY KEY,
+  condition TEXT NOT NULL,
+  hash      TEXT NOT NULL
+);
+
+-- Event trigger routes. `where` gates on the triggering event's payload
+-- (a payload-only condition tree); `filter` gates on the profile.
+CREATE TABLE IF NOT EXISTS triggers (
+  workflow  TEXT PRIMARY KEY,
+  hash      TEXT NOT NULL,
+  event     TEXT NOT NULL,
+  "where"   TEXT,
+  filter    TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_triggers_event ON triggers (event);
+
+-- Segment-entry trigger routes.
+CREATE TABLE IF NOT EXISTS segment_triggers (
+  workflow TEXT PRIMARY KEY,
+  hash     TEXT NOT NULL,
+  segment  TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_segment_triggers_segment ON segment_triggers (segment);
+
+-- Lazily maintained segment membership, covering only segments that something
+-- triggers on. Transitions are re-evaluated when the user is ingested or
+-- identified, and by the scheduled sweep (journeyWorker's `scheduled`), which
+-- also catches drift driven purely by the clock.
+CREATE TABLE IF NOT EXISTS segment_members (
+  segment TEXT NOT NULL,
+  user_id TEXT NOT NULL,
+  ts      INTEGER NOT NULL,
+  PRIMARY KEY (segment, user_id)
+);
+
+-- Workflows a segment entry still has to start for a member: written with the
+-- membership, removed as each starts, so a failed start is retried by the next
+-- evaluation instead of being hidden behind the membership.
+CREATE TABLE IF NOT EXISTS segment_starts (
+  segment  TEXT NOT NULL,
+  workflow TEXT NOT NULL,
+  user_id  TEXT NOT NULL,
+  ts       INTEGER NOT NULL,
+  PRIMARY KEY (segment, workflow, user_id)
+);
+
+-- Erasures in progress (forgetUser): the user's data stays until every running
+-- instance is stopped, and the scheduled sweep retries what is left.
+CREATE TABLE IF NOT EXISTS erasures (
+  user_id TEXT PRIMARY KEY,
+  ts      INTEGER NOT NULL
+);
+
+-- Entry ledger: the once-per-user policy, instance addressing, and the audit
+-- trail of which IR version each user was pinned to.
+--
+-- The primary key is what makes the policy atomic, and it is also the whole
+-- policy: a user who has entered cannot enter again. The one exception is a
+-- row left at 'failed', which records an instance that died rather than a
+-- journey the user received; the router takes such a row over so the entry can
+-- be retried (see startJourney). A general re-entry policy is a separate
+-- design question and deliberately not encoded here.
+CREATE TABLE IF NOT EXISTS entries (
+  workflow    TEXT NOT NULL,
+  user_id     TEXT NOT NULL,
+  instance_id TEXT NOT NULL,
+  hash        TEXT NOT NULL,
+  status      TEXT NOT NULL,
+  ts          INTEGER NOT NULL,
+  PRIMARY KEY (workflow, user_id)
+);
+
+-- wait_until wake routing. `wake_handle` is an opaque handle (the instance id
+-- on Cloudflare, a callback id on AWS). The primary key makes the interpreter's
+-- re-subscription on every wait attempt idempotent, which its one-shot-callback
+-- contract requires.
+CREATE TABLE IF NOT EXISTS subscriptions (
+  user_id     TEXT NOT NULL,
+  event       TEXT NOT NULL,
+  wake_handle TEXT NOT NULL,
+  ts          INTEGER NOT NULL,
+  PRIMARY KEY (wake_handle, event)
+);
+CREATE INDEX IF NOT EXISTS idx_subs_user_event ON subscriptions (user_id, event);

package/dist/cloudflare/senders.cjs

@@ -0,0 +1,114 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/cloudflare/senders.ts
+/**
+* Send straight through Cloudflare Email Service — a binding call, no outbound
+* HTTP. Throwing hands retries to the CF step, and the message's
+* idempotencyKey travels with the call so the binding can drop the duplicate a
+* retry or replay produces.
+*/
+var CfEmailSender = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	async send(message) {
+		if (message.channel !== "email") throw new Error(`CfEmailSender: unsupported channel '${message.channel}'`);
+		if (message.recipient === void 0) throw new Error(`CfEmailSender: no recipient for user '${message.userId}'`);
+		const { subject, html } = await this.options.render(message.template, message.props);
+		const tracked = message.tracking === void 0 ? html : trackEmail(html, message.tracking);
+		await message.tracking?.commit?.();
+		await this.options.binding.send({
+			from: this.options.from,
+			to: message.recipient,
+			...this.options.replyTo === void 0 ? {} : { replyTo: this.options.replyTo },
+			subject,
+			html: tracked,
+			idempotencyKey: message.idempotencyKey
+		});
+	}
+};
+const LINK = /(<a\b[^>]*?\shref\s*=\s*)(["'])(https?:\/\/[^"']+)\2/gi;
+/**
+* An email's tracking applied to its rendered HTML: every `http(s)` anchor routed through
+* `link` (the original URL decoded from its attribute escaping, the tracking URL escaped back),
+* and the open pixel appended before `</body>`, or at the end when there is none.
+*/
+function trackEmail(html, tracking) {
+	const { link, pixel } = tracking;
+	let out = html;
+	if (link !== void 0) out = out.replace(LINK, (_, start, quote, url) => `${start}${quote}${escapeAttribute(link(unescapeAttribute(url)))}${quote}`);
+	if (pixel !== void 0) {
+		const image = `<img src="${escapeAttribute(pixel)}" width="1" height="1" alt="" style="display:block;border:0;width:1px;height:1px" />`;
+		out = /<\/body>/i.test(out) ? out.replace(/<\/body>/i, `${image}</body>`) : `${out}${image}`;
+	}
+	return out;
+}
+function unescapeAttribute(value) {
+	return value.replaceAll("&amp;", "&").replaceAll("&quot;", "\"").replaceAll("&#x27;", "'");
+}
+function escapeAttribute(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("\"", "&quot;");
+}
+/** Development sender: structured logs, for eyeballing the pipeline. */
+var LogMessageSender = class {
+	async send(message) {
+		const { tracking: _tracking, ...logged } = message;
+		console.log(`[send] ${JSON.stringify(logged)}`);
+	}
+};
+/**
+* Webhook sender: POST to an external delivery service (a Resend/SES gateway,
+* say). The idempotency key travels with it, so the receiver de-duplicates
+* retries and replays on idempotencyKey.
+*/
+var WebhookMessageSender = class {
+	url;
+	constructor(url) {
+		this.url = url;
+	}
+	async send(message) {
+		const response = await fetch(this.url, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				"idempotency-key": message.idempotencyKey
+			},
+			body: JSON.stringify(message)
+		});
+		if (!response.ok) throw new Error(`message webhook failed: ${response.status}`);
+	}
+};
+/**
+* One sender per channel: the runner has a single outlet, this fans it out.
+* A channel without a sender fails the send (a misconfiguration, not a retry).
+*/
+function routeByChannel(senders) {
+	return { async send(message) {
+		const sender = senders[message.channel];
+		if (sender === void 0) throw new Error(`no sender configured for channel '${message.channel}'`);
+		return sender.send(message);
+	} };
+}
+/**
+* One push outlet per platform, chosen by the device each copy goes to (the
+* engine sends one message per device, and the host's directory says which
+* platform a token belongs to): `ios` straight to APNs, `android` through FCM,
+* say. A platform with no sender fails the step rather than guessing.
+*/
+function routeByPlatform(senders) {
+	return { async send(message) {
+		const platform = message.device?.platform;
+		if (platform === void 0) throw new Error(`push for user '${message.userId}' carries no device`);
+		if (!Object.hasOwn(senders, platform)) throw new Error(`no push sender configured for platform '${platform}'`);
+		return senders[platform].send(message);
+	} };
+}
+//#endregion
+exports.CfEmailSender = CfEmailSender;
+exports.LogMessageSender = LogMessageSender;
+exports.WebhookMessageSender = WebhookMessageSender;
+exports.routeByChannel = routeByChannel;
+exports.routeByPlatform = routeByPlatform;
+exports.trackEmail = trackEmail;
+
+//# sourceMappingURL=senders.cjs.map

package/dist/cloudflare/senders.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"senders.cjs","names":[],"sources":["../../src/cloudflare/senders.ts"],"sourcesContent":["import type { EmailAddress } from '../config';\nimport type { MessageSender, MessageTracking, OutboundMessage } from '../engine';\nimport type { ScalarIR } from '../ir';\nimport type { EmailBindingLike } from './bindings';\n\nexport type { EmailAddress } from '../config';\nexport type { EmailBindingLike } from './bindings';\n\n/**\n * Template renderer, injected by the app — this package's core stays free of\n * any react-email dependency (`@shware/workflow/react-email` ships one over a\n * registry). The subject comes back final: it is sent exactly as written.\n */\nexport type EmailRenderer = (\n  template: string,\n  props: Record<string, ScalarIR | undefined>\n) => Promise<{ subject: string; html: string }>;\n\nexport interface CfEmailOptions {\n  /** The Worker's `send_email` binding. */\n  binding: EmailBindingLike;\n  from: EmailAddress;\n  replyTo?: EmailAddress;\n  render: EmailRenderer;\n}\n\n/**\n * Send straight through Cloudflare Email Service — a binding call, no outbound\n * HTTP. Throwing hands retries to the CF step, and the message's\n * idempotencyKey travels with the call so the binding can drop the duplicate a\n * retry or replay produces.\n */\nexport class CfEmailSender implements MessageSender {\n  constructor(private readonly options: CfEmailOptions) {}\n\n  async send(message: OutboundMessage): Promise<void> {\n    if (message.channel !== 'email') {\n      throw new Error(`CfEmailSender: unsupported channel '${message.channel}'`);\n    }\n    if (message.recipient === undefined) {\n      throw new Error(`CfEmailSender: no recipient for user '${message.userId}'`);\n    }\n    const { subject, html } = await this.options.render(message.template, message.props);\n    const tracked = message.tracking === undefined ? html : trackEmail(html, message.tracking);\n    // The tracked links resolve before the email exists anywhere a scanner could follow them\n    await message.tracking?.commit?.();\n    await this.options.binding.send({\n      from: this.options.from,\n      to: message.recipient,\n      ...(this.options.replyTo === undefined ? {} : { replyTo: this.options.replyTo }),\n      subject,\n      html: tracked,\n      idempotencyKey: message.idempotencyKey,\n    });\n  }\n}\n\nconst LINK = /(<a\\b[^>]*?\\shref\\s*=\\s*)([\"'])(https?:\\/\\/[^\"']+)\\2/gi;\n\n/**\n * An email's tracking applied to its rendered HTML: every `http(s)` anchor routed through\n * `link` (the original URL decoded from its attribute escaping, the tracking URL escaped back),\n * and the open pixel appended before `</body>`, or at the end when there is none.\n */\nexport function trackEmail(html: string, tracking: MessageTracking): string {\n  const { link, pixel } = tracking;\n  let out = html;\n  if (link !== undefined) {\n    out = out.replace(\n      LINK,\n      (_, start: string, quote: string, url: string) =>\n        `${start}${quote}${escapeAttribute(link(unescapeAttribute(url)))}${quote}`\n    );\n  }\n  if (pixel !== undefined) {\n    const image = `<img src=\"${escapeAttribute(pixel)}\" width=\"1\" height=\"1\" alt=\"\" style=\"display:block;border:0;width:1px;height:1px\" />`;\n    out = /<\\/body>/i.test(out) ? out.replace(/<\\/body>/i, `${image}</body>`) : `${out}${image}`;\n  }\n  return out;\n}\n\nfunction unescapeAttribute(value: string): string {\n  return value.replaceAll('&amp;', '&').replaceAll('&quot;', '\"').replaceAll('&#x27;', \"'\");\n}\n\nfunction escapeAttribute(value: string): string {\n  return value.replaceAll('&', '&amp;').replaceAll('\"', '&quot;');\n}\n\n/** Development sender: structured logs, for eyeballing the pipeline. */\nexport class LogMessageSender implements MessageSender {\n  async send(message: OutboundMessage): Promise<void> {\n    const { tracking: _tracking, ...logged } = message;\n    console.log(`[send] ${JSON.stringify(logged)}`);\n  }\n}\n\n/**\n * Webhook sender: POST to an external delivery service (a Resend/SES gateway,\n * say). The idempotency key travels with it, so the receiver de-duplicates\n * retries and replays on idempotencyKey.\n */\nexport class WebhookMessageSender implements MessageSender {\n  constructor(private readonly url: string) {}\n\n  async send(message: OutboundMessage): Promise<void> {\n    const response = await fetch(this.url, {\n      method: 'POST',\n      headers: {\n        'content-type': 'application/json',\n        'idempotency-key': message.idempotencyKey,\n      },\n      body: JSON.stringify(message),\n    });\n    if (!response.ok) {\n      throw new Error(`message webhook failed: ${response.status}`);\n    }\n  }\n}\n\n/**\n * One sender per channel: the runner has a single outlet, this fans it out.\n * A channel without a sender fails the send (a misconfiguration, not a retry).\n */\nexport function routeByChannel(\n  senders: Partial<Record<OutboundMessage['channel'], MessageSender>>\n): MessageSender {\n  return {\n    async send(message) {\n      const sender = senders[message.channel];\n      if (sender === undefined) {\n        throw new Error(`no sender configured for channel '${message.channel}'`);\n      }\n      return sender.send(message);\n    },\n  };\n}\n\n/**\n * One push outlet per platform, chosen by the device each copy goes to (the\n * engine sends one message per device, and the host's directory says which\n * platform a token belongs to): `ios` straight to APNs, `android` through FCM,\n * say. A platform with no sender fails the step rather than guessing.\n */\nexport function routeByPlatform(senders: Record<string, MessageSender>): MessageSender {\n  return {\n    async send(message) {\n      const platform = message.device?.platform;\n      if (platform === undefined) {\n        throw new Error(`push for user '${message.userId}' carries no device`);\n      }\n      if (!Object.hasOwn(senders, platform)) {\n        throw new Error(`no push sender configured for platform '${platform}'`);\n      }\n      return senders[platform].send(message);\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/cloudflare/senders.d.cts

@@ -0,0 +1,68 @@
+import { ScalarIR } from "../ir.cjs";
+import { MessageSender, MessageTracking, OutboundMessage } from "../engine/ports.cjs";
+import "../engine/index.cjs";
+import { EmailAddress } from "../config.cjs";
+import { EmailBindingLike } from "./bindings.cjs";
+//#region src/cloudflare/senders.d.ts
+/**
+ * Template renderer, injected by the app — this package's core stays free of
+ * any react-email dependency (`@shware/workflow/react-email` ships one over a
+ * registry). The subject comes back final: it is sent exactly as written.
+ */
+export type EmailRenderer = (template: string, props: Record<string, ScalarIR | undefined>) => Promise<{
+  subject: string;
+  html: string;
+}>;
+export interface CfEmailOptions {
+  /** The Worker's `send_email` binding. */
+  binding: EmailBindingLike;
+  from: EmailAddress;
+  replyTo?: EmailAddress;
+  render: EmailRenderer;
+}
+/**
+ * Send straight through Cloudflare Email Service — a binding call, no outbound
+ * HTTP. Throwing hands retries to the CF step, and the message's
+ * idempotencyKey travels with the call so the binding can drop the duplicate a
+ * retry or replay produces.
+ */
+export declare class CfEmailSender implements MessageSender {
+  private readonly options;
+  constructor(options: CfEmailOptions);
+  send(message: OutboundMessage): Promise<void>;
+}
+/**
+ * An email's tracking applied to its rendered HTML: every `http(s)` anchor routed through
+ * `link` (the original URL decoded from its attribute escaping, the tracking URL escaped back),
+ * and the open pixel appended before `</body>`, or at the end when there is none.
+ */
+export declare function trackEmail(html: string, tracking: MessageTracking): string;
+/** Development sender: structured logs, for eyeballing the pipeline. */
+export declare class LogMessageSender implements MessageSender {
+  send(message: OutboundMessage): Promise<void>;
+}
+/**
+ * Webhook sender: POST to an external delivery service (a Resend/SES gateway,
+ * say). The idempotency key travels with it, so the receiver de-duplicates
+ * retries and replays on idempotencyKey.
+ */
+export declare class WebhookMessageSender implements MessageSender {
+  private readonly url;
+  constructor(url: string);
+  send(message: OutboundMessage): Promise<void>;
+}
+/**
+ * One sender per channel: the runner has a single outlet, this fans it out.
+ * A channel without a sender fails the send (a misconfiguration, not a retry).
+ */
+export declare function routeByChannel(senders: Partial<Record<OutboundMessage['channel'], MessageSender>>): MessageSender;
+/**
+ * One push outlet per platform, chosen by the device each copy goes to (the
+ * engine sends one message per device, and the host's directory says which
+ * platform a token belongs to): `ios` straight to APNs, `android` through FCM,
+ * say. A platform with no sender fails the step rather than guessing.
+ */
+export declare function routeByPlatform(senders: Record<string, MessageSender>): MessageSender;
+//#endregion
+export type { EmailAddress, EmailBindingLike };
+//# sourceMappingURL=senders.d.cts.map

package/dist/cloudflare/senders.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"senders.d.cts","names":[],"sources":["../../src/cloudflare/senders.ts"],"mappings":";;;;;;;;;;;YAaY,iBACV,kBACA,OAAO,eAAe,0BACnB;EAAU;EAAiB;;iBAEf;;EAEf,SAAS;EACT,MAAM;EACN,UAAU;EACV,QAAQ;;;;;;;;qBASG,yBAAyB;mBACP;EAA7B,YAA6B,SAAS;EAEhC,KAAK,SAAS,kBAAkB;;;;;;;wBA6BxB,WAAW,cAAc,UAAU;;qBA0BtC,4BAA4B;EACjC,KAAK,SAAS,kBAAkB;;;;;;;qBAW3B,gCAAgC;mBACd;EAA7B,YAA6B;EAEvB,KAAK,SAAS,kBAAkB;;;;;;wBAmBxB,eACd,SAAS,QAAQ,OAAO,4BAA4B,kBACnD;;;;;;;wBAkBa,gBAAgB,SAAS,eAAe,iBAAiB"}

package/dist/cloudflare/senders.d.mts

@@ -0,0 +1,68 @@
+import { ScalarIR } from "../ir.mjs";
+import { MessageSender, MessageTracking, OutboundMessage } from "../engine/ports.mjs";
+import "../engine/index.mjs";
+import { EmailAddress } from "../config.mjs";
+import { EmailBindingLike } from "./bindings.mjs";
+//#region src/cloudflare/senders.d.ts
+/**
+ * Template renderer, injected by the app — this package's core stays free of
+ * any react-email dependency (`@shware/workflow/react-email` ships one over a
+ * registry). The subject comes back final: it is sent exactly as written.
+ */
+export type EmailRenderer = (template: string, props: Record<string, ScalarIR | undefined>) => Promise<{
+  subject: string;
+  html: string;
+}>;
+export interface CfEmailOptions {
+  /** The Worker's `send_email` binding. */
+  binding: EmailBindingLike;
+  from: EmailAddress;
+  replyTo?: EmailAddress;
+  render: EmailRenderer;
+}
+/**
+ * Send straight through Cloudflare Email Service — a binding call, no outbound
+ * HTTP. Throwing hands retries to the CF step, and the message's
+ * idempotencyKey travels with the call so the binding can drop the duplicate a
+ * retry or replay produces.
+ */
+export declare class CfEmailSender implements MessageSender {
+  private readonly options;
+  constructor(options: CfEmailOptions);
+  send(message: OutboundMessage): Promise<void>;
+}
+/**
+ * An email's tracking applied to its rendered HTML: every `http(s)` anchor routed through
+ * `link` (the original URL decoded from its attribute escaping, the tracking URL escaped back),
+ * and the open pixel appended before `</body>`, or at the end when there is none.
+ */
+export declare function trackEmail(html: string, tracking: MessageTracking): string;
+/** Development sender: structured logs, for eyeballing the pipeline. */
+export declare class LogMessageSender implements MessageSender {
+  send(message: OutboundMessage): Promise<void>;
+}
+/**
+ * Webhook sender: POST to an external delivery service (a Resend/SES gateway,
+ * say). The idempotency key travels with it, so the receiver de-duplicates
+ * retries and replays on idempotencyKey.
+ */
+export declare class WebhookMessageSender implements MessageSender {
+  private readonly url;
+  constructor(url: string);
+  send(message: OutboundMessage): Promise<void>;
+}
+/**
+ * One sender per channel: the runner has a single outlet, this fans it out.
+ * A channel without a sender fails the send (a misconfiguration, not a retry).
+ */
+export declare function routeByChannel(senders: Partial<Record<OutboundMessage['channel'], MessageSender>>): MessageSender;
+/**
+ * One push outlet per platform, chosen by the device each copy goes to (the
+ * engine sends one message per device, and the host's directory says which
+ * platform a token belongs to): `ios` straight to APNs, `android` through FCM,
+ * say. A platform with no sender fails the step rather than guessing.
+ */
+export declare function routeByPlatform(senders: Record<string, MessageSender>): MessageSender;
+//#endregion
+export type { EmailAddress, EmailBindingLike };
+//# sourceMappingURL=senders.d.mts.map

package/dist/cloudflare/senders.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"senders.d.mts","names":[],"sources":["../../src/cloudflare/senders.ts"],"mappings":";;;;;;;;;;;YAaY,iBACV,kBACA,OAAO,eAAe,0BACnB;EAAU;EAAiB;;iBAEf;;EAEf,SAAS;EACT,MAAM;EACN,UAAU;EACV,QAAQ;;;;;;;;qBASG,yBAAyB;mBACP;EAA7B,YAA6B,SAAS;EAEhC,KAAK,SAAS,kBAAkB;;;;;;;wBA6BxB,WAAW,cAAc,UAAU;;qBA0BtC,4BAA4B;EACjC,KAAK,SAAS,kBAAkB;;;;;;;qBAW3B,gCAAgC;mBACd;EAA7B,YAA6B;EAEvB,KAAK,SAAS,kBAAkB;;;;;;wBAmBxB,eACd,SAAS,QAAQ,OAAO,4BAA4B,kBACnD;;;;;;;wBAkBa,gBAAgB,SAAS,eAAe,iBAAiB"}

package/dist/cloudflare/senders.mjs

@@ -0,0 +1,108 @@
+//#region src/cloudflare/senders.ts
+/**
+* Send straight through Cloudflare Email Service — a binding call, no outbound
+* HTTP. Throwing hands retries to the CF step, and the message's
+* idempotencyKey travels with the call so the binding can drop the duplicate a
+* retry or replay produces.
+*/
+var CfEmailSender = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	async send(message) {
+		if (message.channel !== "email") throw new Error(`CfEmailSender: unsupported channel '${message.channel}'`);
+		if (message.recipient === void 0) throw new Error(`CfEmailSender: no recipient for user '${message.userId}'`);
+		const { subject, html } = await this.options.render(message.template, message.props);
+		const tracked = message.tracking === void 0 ? html : trackEmail(html, message.tracking);
+		await message.tracking?.commit?.();
+		await this.options.binding.send({
+			from: this.options.from,
+			to: message.recipient,
+			...this.options.replyTo === void 0 ? {} : { replyTo: this.options.replyTo },
+			subject,
+			html: tracked,
+			idempotencyKey: message.idempotencyKey
+		});
+	}
+};
+const LINK = /(<a\b[^>]*?\shref\s*=\s*)(["'])(https?:\/\/[^"']+)\2/gi;
+/**
+* An email's tracking applied to its rendered HTML: every `http(s)` anchor routed through
+* `link` (the original URL decoded from its attribute escaping, the tracking URL escaped back),
+* and the open pixel appended before `</body>`, or at the end when there is none.
+*/
+function trackEmail(html, tracking) {
+	const { link, pixel } = tracking;
+	let out = html;
+	if (link !== void 0) out = out.replace(LINK, (_, start, quote, url) => `${start}${quote}${escapeAttribute(link(unescapeAttribute(url)))}${quote}`);
+	if (pixel !== void 0) {
+		const image = `<img src="${escapeAttribute(pixel)}" width="1" height="1" alt="" style="display:block;border:0;width:1px;height:1px" />`;
+		out = /<\/body>/i.test(out) ? out.replace(/<\/body>/i, `${image}</body>`) : `${out}${image}`;
+	}
+	return out;
+}
+function unescapeAttribute(value) {
+	return value.replaceAll("&amp;", "&").replaceAll("&quot;", "\"").replaceAll("&#x27;", "'");
+}
+function escapeAttribute(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("\"", "&quot;");
+}
+/** Development sender: structured logs, for eyeballing the pipeline. */
+var LogMessageSender = class {
+	async send(message) {
+		const { tracking: _tracking, ...logged } = message;
+		console.log(`[send] ${JSON.stringify(logged)}`);
+	}
+};
+/**
+* Webhook sender: POST to an external delivery service (a Resend/SES gateway,
+* say). The idempotency key travels with it, so the receiver de-duplicates
+* retries and replays on idempotencyKey.
+*/
+var WebhookMessageSender = class {
+	url;
+	constructor(url) {
+		this.url = url;
+	}
+	async send(message) {
+		const response = await fetch(this.url, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				"idempotency-key": message.idempotencyKey
+			},
+			body: JSON.stringify(message)
+		});
+		if (!response.ok) throw new Error(`message webhook failed: ${response.status}`);
+	}
+};
+/**
+* One sender per channel: the runner has a single outlet, this fans it out.
+* A channel without a sender fails the send (a misconfiguration, not a retry).
+*/
+function routeByChannel(senders) {
+	return { async send(message) {
+		const sender = senders[message.channel];
+		if (sender === void 0) throw new Error(`no sender configured for channel '${message.channel}'`);
+		return sender.send(message);
+	} };
+}
+/**
+* One push outlet per platform, chosen by the device each copy goes to (the
+* engine sends one message per device, and the host's directory says which
+* platform a token belongs to): `ios` straight to APNs, `android` through FCM,
+* say. A platform with no sender fails the step rather than guessing.
+*/
+function routeByPlatform(senders) {
+	return { async send(message) {
+		const platform = message.device?.platform;
+		if (platform === void 0) throw new Error(`push for user '${message.userId}' carries no device`);
+		if (!Object.hasOwn(senders, platform)) throw new Error(`no push sender configured for platform '${platform}'`);
+		return senders[platform].send(message);
+	} };
+}
+//#endregion
+export { CfEmailSender, LogMessageSender, WebhookMessageSender, routeByChannel, routeByPlatform, trackEmail };
+
+//# sourceMappingURL=senders.mjs.map

package/dist/cloudflare/senders.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"senders.mjs","names":[],"sources":["../../src/cloudflare/senders.ts"],"sourcesContent":["import type { EmailAddress } from '../config';\nimport type { MessageSender, MessageTracking, OutboundMessage } from '../engine';\nimport type { ScalarIR } from '../ir';\nimport type { EmailBindingLike } from './bindings';\n\nexport type { EmailAddress } from '../config';\nexport type { EmailBindingLike } from './bindings';\n\n/**\n * Template renderer, injected by the app — this package's core stays free of\n * any react-email dependency (`@shware/workflow/react-email` ships one over a\n * registry). The subject comes back final: it is sent exactly as written.\n */\nexport type EmailRenderer = (\n  template: string,\n  props: Record<string, ScalarIR | undefined>\n) => Promise<{ subject: string; html: string }>;\n\nexport interface CfEmailOptions {\n  /** The Worker's `send_email` binding. */\n  binding: EmailBindingLike;\n  from: EmailAddress;\n  replyTo?: EmailAddress;\n  render: EmailRenderer;\n}\n\n/**\n * Send straight through Cloudflare Email Service — a binding call, no outbound\n * HTTP. Throwing hands retries to the CF step, and the message's\n * idempotencyKey travels with the call so the binding can drop the duplicate a\n * retry or replay produces.\n */\nexport class CfEmailSender implements MessageSender {\n  constructor(private readonly options: CfEmailOptions) {}\n\n  async send(message: OutboundMessage): Promise<void> {\n    if (message.channel !== 'email') {\n      throw new Error(`CfEmailSender: unsupported channel '${message.channel}'`);\n    }\n    if (message.recipient === undefined) {\n      throw new Error(`CfEmailSender: no recipient for user '${message.userId}'`);\n    }\n    const { subject, html } = await this.options.render(message.template, message.props);\n    const tracked = message.tracking === undefined ? html : trackEmail(html, message.tracking);\n    // The tracked links resolve before the email exists anywhere a scanner could follow them\n    await message.tracking?.commit?.();\n    await this.options.binding.send({\n      from: this.options.from,\n      to: message.recipient,\n      ...(this.options.replyTo === undefined ? {} : { replyTo: this.options.replyTo }),\n      subject,\n      html: tracked,\n      idempotencyKey: message.idempotencyKey,\n    });\n  }\n}\n\nconst LINK = /(<a\\b[^>]*?\\shref\\s*=\\s*)([\"'])(https?:\\/\\/[^\"']+)\\2/gi;\n\n/**\n * An email's tracking applied to its rendered HTML: every `http(s)` anchor routed through\n * `link` (the original URL decoded from its attribute escaping, the tracking URL escaped back),\n * and the open pixel appended before `</body>`, or at the end when there is none.\n */\nexport function trackEmail(html: string, tracking: MessageTracking): string {\n  const { link, pixel } = tracking;\n  let out = html;\n  if (link !== undefined) {\n    out = out.replace(\n      LINK,\n      (_, start: string, quote: string, url: string) =>\n        `${start}${quote}${escapeAttribute(link(unescapeAttribute(url)))}${quote}`\n    );\n  }\n  if (pixel !== undefined) {\n    const image = `<img src=\"${escapeAttribute(pixel)}\" width=\"1\" height=\"1\" alt=\"\" style=\"display:block;border:0;width:1px;height:1px\" />`;\n    out = /<\\/body>/i.test(out) ? out.replace(/<\\/body>/i, `${image}</body>`) : `${out}${image}`;\n  }\n  return out;\n}\n\nfunction unescapeAttribute(value: string): string {\n  return value.replaceAll('&amp;', '&').replaceAll('&quot;', '\"').replaceAll('&#x27;', \"'\");\n}\n\nfunction escapeAttribute(value: string): string {\n  return value.replaceAll('&', '&amp;').replaceAll('\"', '&quot;');\n}\n\n/** Development sender: structured logs, for eyeballing the pipeline. */\nexport class LogMessageSender implements MessageSender {\n  async send(message: OutboundMessage): Promise<void> {\n    const { tracking: _tracking, ...logged } = message;\n    console.log(`[send] ${JSON.stringify(logged)}`);\n  }\n}\n\n/**\n * Webhook sender: POST to an external delivery service (a Resend/SES gateway,\n * say). The idempotency key travels with it, so the receiver de-duplicates\n * retries and replays on idempotencyKey.\n */\nexport class WebhookMessageSender implements MessageSender {\n  constructor(private readonly url: string) {}\n\n  async send(message: OutboundMessage): Promise<void> {\n    const response = await fetch(this.url, {\n      method: 'POST',\n      headers: {\n        'content-type': 'application/json',\n        'idempotency-key': message.idempotencyKey,\n      },\n      body: JSON.stringify(message),\n    });\n    if (!response.ok) {\n      throw new Error(`message webhook failed: ${response.status}`);\n    }\n  }\n}\n\n/**\n * One sender per channel: the runner has a single outlet, this fans it out.\n * A channel without a sender fails the send (a misconfiguration, not a retry).\n */\nexport function routeByChannel(\n  senders: Partial<Record<OutboundMessage['channel'], MessageSender>>\n): MessageSender {\n  return {\n    async send(message) {\n      const sender = senders[message.channel];\n      if (sender === undefined) {\n        throw new Error(`no sender configured for channel '${message.channel}'`);\n      }\n      return sender.send(message);\n    },\n  };\n}\n\n/**\n * One push outlet per platform, chosen by the device each copy goes to (the\n * engine sends one message per device, and the host's directory says which\n * platform a token belongs to): `ios` straight to APNs, `android` through FCM,\n * say. A platform with no sender fails the step rather than guessing.\n */\nexport function routeByPlatform(senders: Record<string, MessageSender>): MessageSender {\n  return {\n    async send(message) {\n      const platform = message.device?.platform;\n      if (platform === undefined) {\n        throw new Error(`push for user '${message.userId}' carries no device`);\n      }\n      if (!Object.hasOwn(senders, platform)) {\n        throw new Error(`no push sender configured for platform '${platform}'`);\n      }\n      return senders[platform].send(message);\n    },\n  };\n}\n"],"mappings":"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"}