@shware/workflow 0.0.0-stage → 0.0.0

package/dist/client.mjs

@@ -0,0 +1,122 @@
+//#region src/client.ts
+var JourneyClientError = class extends Error {
+	path;
+	status;
+	body;
+	constructor(path, status, body) {
+		super(`journey ${path} failed: ${status} ${body}`);
+		this.path = path;
+		this.status = status;
+		this.body = body;
+		this.name = "JourneyClientError";
+	}
+};
+/** A payload or profile patch the contract refuses — raised before the request, with the field paths. */
+var JourneyValidationError = class extends Error {
+	path;
+	event;
+	issues;
+	constructor(path, event, issues) {
+		super(`journey ${path}${event === void 0 ? "" : ` '${event}'`} refused by the contract: ${issues.map((i) => `${i.path || "(root)"} ${i.message}`).join("; ")}`);
+		this.path = path;
+		this.event = event;
+		this.issues = issues;
+		this.name = "JourneyValidationError";
+	}
+};
+var JourneyClient = class {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	/** Merge profile properties (`null` clears one). Every property a journey reads must be identified before the event that starts it. */
+	identify(userId, props) {
+		const contract = this.options.contract;
+		if (contract !== void 0) {
+			const result = contract.parseProfilePatch(props);
+			if (!result.ok) return Promise.reject(new JourneyValidationError("/identify", void 0, result.issues));
+		}
+		return this.post("/identify", {
+			userId,
+			props
+		});
+	}
+	/**
+	* Record an event; the Worker starts every journey whose trigger matches it
+	* and wakes waits on it. A caller that retries should pass the same `id`
+	* each time: the Worker stores one occurrence per id, so a retry after a
+	* timeout cannot double-count the event. `ts` defaults to the Worker's clock.
+	*/
+	track(userId, event, ...args) {
+		const [payload = {}, options = {}] = args;
+		const contract = this.options.contract;
+		if (contract !== void 0) {
+			const result = contract.parseEvent(event, payload);
+			if (!result.ok) return Promise.reject(new JourneyValidationError("/events", event, result.issues));
+		}
+		return this.post("/events", {
+			userId,
+			event,
+			payload,
+			...options.id === void 0 ? {} : { id: options.id },
+			...options.ts === void 0 ? {} : { ts: options.ts }
+		});
+	}
+	/**
+	* A push token the app registered for the user (call it on every registration: a token moves
+	* to the latest user). The engine keeps devices itself — pushes go to them, a token APNs / FCM
+	* reports as gone is dropped — and journeys waiting on `reachable('push')` wake.
+	*/
+	registerDevice(userId, device) {
+		return this.post("/devices", {
+			userId,
+			...device
+		});
+	}
+	/**
+	* A journey push tapped open: the `message_id` the push carried, reported for the user who
+	* tapped it. Recorded as a human open on the copy (an email's opens are tracked by the Worker).
+	*/
+	messageOpened(userId, messageId) {
+		return this.post("/messages/opened", {
+			userId,
+			messageId
+		});
+	}
+	/**
+	* A deleted account: the engine records the erasure, stops the user's running journeys, then
+	* erases everything it keeps about them (profile, devices, events, reporting). Once this
+	* resolves the request is durable: `erased: false` means an instance would not stop yet, and
+	* the Worker's scheduled sweep finishes the job.
+	*/
+	forgetUser(userId) {
+		return this.post("/users/forget", { userId });
+	}
+	/** The user signed out on that device: the token stays registered, bound to nobody. */
+	unbindDevice(token) {
+		return this.post("/devices/unbind", { token });
+	}
+	/** Forget a push token for good (an uninstall the app learned of, a token it replaced). */
+	removeDevice(token) {
+		return this.post("/devices/remove", { token });
+	}
+	/** Deploy a compiled bundle (BundleIR). */
+	deploy(bundle) {
+		return this.post("/deploy", bundle);
+	}
+	async post(path, body) {
+		const 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",
+			headers,
+			body: JSON.stringify(body)
+		});
+		if (!response.ok) throw new JourneyClientError(path, response.status, await response.text());
+		return await response.json();
+	}
+};
+//#endregion
+export { JourneyClient, JourneyClientError, JourneyValidationError };
+
+//# sourceMappingURL=client.mjs.map

package/dist/client.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.mjs","names":[],"sources":["../src/client.ts"],"sourcesContent":["import type * as core from 'zod/v4/core';\nimport type { DeployResult, IdentifyResult, IngestResult } from './cloudflare';\nimport type { Contract, ContractIssue, ProfilePatch } from './contract';\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' }\n  ): Promise<{ ok: true; woke: number }> {\n    return this.post('/devices', { userId, ...device });\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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"}

package/dist/cloudflare/bindings.cjs

@@ -0,0 +1,28 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/cloudflare/bindings.ts
+/** The event type the router uses to wake waiting instances (sendEvent's `type`). */
+const WAKE_EVENT_TYPE = "wake";
+/**
+* Slack on the deadline when deciding whether a thrown wait was a timeout: the
+* platform may surface the expiry a moment early, and a wait shorter than this
+* has no room to tell the two apart anyway.
+*/
+const WAKE_TIMEOUT_TOLERANCE_MS = 5e3;
+/**
+* Did a wait that threw actually reach its deadline?
+*
+* CF signals a wait timeout by throwing, and so does every other failure in
+* there — a broken binding, an evicted instance, a malformed timeout. The
+* adapter used to read them all as timeouts, which made an infrastructure
+* fault indistinguishable from "the user never did it": the journey took its
+* onTimeout branch, early and silently. Only the clock can tell them apart.
+*/
+function wakeExpired(startedAt, timeoutMs, now) {
+	return now - startedAt >= Math.max(0, timeoutMs - WAKE_TIMEOUT_TOLERANCE_MS);
+}
+//#endregion
+exports.WAKE_EVENT_TYPE = WAKE_EVENT_TYPE;
+exports.WAKE_TIMEOUT_TOLERANCE_MS = WAKE_TIMEOUT_TOLERANCE_MS;
+exports.wakeExpired = wakeExpired;
+
+//# sourceMappingURL=bindings.cjs.map

package/dist/cloudflare/bindings.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.cjs","names":[],"sources":["../../src/cloudflare/bindings.ts"],"sourcesContent":["import type { EmailAddress } from '../config';\n\n/**\n * A minimal structural interface over the Cloudflare bindings.\n *\n * @cloudflare/workers-types is deliberately not used: the global types it\n * injects clash with the DOM lib this package's react side needs. A structural\n * subset plus the ambient cloudflare:workers declaration is enough to compile,\n * and the real bindings satisfy it structurally at runtime.\n */\n\nexport interface KVNamespaceLike {\n  get(key: string): Promise<string | null>;\n  put(key: string, value: string): Promise<void>;\n}\n\n/** Structural subset of D1Result: `meta.changes` is how INSERT OR IGNORE reports whether it inserted. */\nexport interface D1RunResultLike {\n  meta?: { changes?: number };\n}\n\nexport interface D1PreparedStatementLike {\n  bind(...values: unknown[]): D1PreparedStatementLike;\n  first<T = Record<string, unknown>>(): Promise<T | null>;\n  all<T = Record<string, unknown>>(): Promise<{ results: T[] }>;\n  run(): Promise<D1RunResultLike>;\n}\n\nexport interface D1DatabaseLike {\n  prepare(sql: string): D1PreparedStatementLike;\n  /** Statements run in order inside one transaction (real D1 semantics) — deploy relies on the atomicity. */\n  batch(statements: D1PreparedStatementLike[]): Promise<unknown>;\n}\n\nexport interface WorkflowInstanceLike {\n  id: string;\n  sendEvent(event: { type: string; payload?: unknown }): Promise<void>;\n  /** Stop the instance for good (Cloudflare Workflows' `terminate`). */\n  terminate?(): Promise<void>;\n  /** Where it stands (`complete`, `errored`, `terminated`, `running`, …). */\n  status?(): Promise<{ status: string }>;\n}\n\nexport interface WorkflowBindingLike {\n  create(options: { id: string; params: unknown }): Promise<WorkflowInstanceLike>;\n  get(id: string): Promise<WorkflowInstanceLike>;\n}\n\n/**\n * Cloudflare Email Service's send_email binding (structural subset).\n *\n * `idempotencyKey` is part of the call because the send happens inside a\n * `step.do`: a step body re-runs after its fn resolved but before the\n * checkpoint committed, so a binding that drops the key mails the user twice.\n * The binding is app-supplied glue (nothing here can de-duplicate — there is\n * no state between two runs of the same step), which is why the port makes the\n * key impossible to miss rather than merely available.\n */\nexport interface EmailBindingLike {\n  send(message: {\n    from: EmailAddress;\n    to: EmailAddress;\n    replyTo?: EmailAddress;\n    subject: string;\n    html: string;\n    /** `${instanceId}:${nodeId}`: stable across replays and retries — drop a send whose key was already delivered. */\n    idempotencyKey: string;\n  }): Promise<unknown>;\n}\n\n/** Every binding the journey engine needs (names match the wrangler config). */\nexport interface JourneyEnv {\n  /**\n   * BundleIR storage for the default D1 store (`wf:${contentHash}` → WorkflowIR JSON). Optional:\n   * a Worker on another JourneyStore (Postgres, say) does not declare it.\n   */\n  WORKFLOW_KV?: KVNamespaceLike;\n  /** Tables of the default D1 store (events / profiles / segments / triggers / entries / subscriptions). Optional, as above. */\n  DB?: D1DatabaseLike;\n  /** JourneyRunner's workflow binding (creating instances and waking them). */\n  JOURNEY: WorkflowBindingLike;\n  /** Optional message-delivery webhook (defaults to the console logging sender). */\n  MESSAGE_WEBHOOK_URL?: string;\n  /**\n   * Bearer token required on every mutating HTTP endpoint (`Authorization:\n   * Bearer <token>`). Unset = open — acceptable only for local dev; /deploy in\n   * particular rewrites the whole routing table, so production must set this.\n   */\n  API_TOKEN?: string;\n  /**\n   * This Worker's public origin. With a store that keeps reporting (Postgres), journey emails'\n   * links and open pixel point at its `/t/...` routes; without it emails go out untracked.\n   */\n  WORKFLOW_ORIGIN?: string;\n  /** Which `workflow.config.ts` entry applies (`development`, `production`, …); production when unset. */\n  ENVIRONMENT?: string;\n  /** Cloudflare Email Sending, when the config has `emails`. */\n  EMAIL?: EmailBindingLike;\n  /** The APNs auth key (`.p8`, base64) named by the config's `apns.keyId`. */\n  APNS_PRIVATE_KEY_BASE64?: string;\n  /** The Firebase service account (base64 JSON) the config's `fcm` sends with. */\n  GOOGLE_APPLICATION_CREDENTIALS_BASE64?: string;\n  /** The VAPID key pair web pushes are signed with (`generateVapidKeys`); the config's `webPush` turns the channel on. */\n  VAPID_PUBLIC_KEY?: string;\n  VAPID_PRIVATE_KEY?: string;\n  /** Development only: the HTTP/2 relay `wrangler dev` sends APNs requests through (see `@shware/workflow/apns-relay`). */\n  APNS_RELAY_ORIGIN?: string;\n}\n\n/** The event type the router uses to wake waiting instances (sendEvent's `type`). */\nexport const WAKE_EVENT_TYPE = 'wake';\n\n/** Journey instance parameters, passed by the ingest router when it creates one. */\nexport interface JourneyParams {\n  workflowId: string;\n  /** The IR version pinned at entry. */\n  contentHash: string;\n  userId: string;\n  trigger: { event: string; payload: Record<string, unknown> };\n  [key: string]: unknown;\n}\n\n/**\n * Slack on the deadline when deciding whether a thrown wait was a timeout: the\n * platform may surface the expiry a moment early, and a wait shorter than this\n * has no room to tell the two apart anyway.\n */\nexport const WAKE_TIMEOUT_TOLERANCE_MS = 5_000;\n\n/**\n * Did a wait that threw actually reach its deadline?\n *\n * CF signals a wait timeout by throwing, and so does every other failure in\n * there — a broken binding, an evicted instance, a malformed timeout. The\n * adapter used to read them all as timeouts, which made an infrastructure\n * fault indistinguishable from \"the user never did it\": the journey took its\n * onTimeout branch, early and silently. Only the clock can tell them apart.\n */\nexport function wakeExpired(startedAt: number, timeoutMs: number, now: number): boolean {\n  return now - startedAt >= Math.max(0, timeoutMs - WAKE_TIMEOUT_TOLERANCE_MS);\n}\n"],"mappings":";;;AA8GA,MAAa,kBAAkB;;;;;;AAiB/B,MAAa,4BAA4B;;;;;;;;;;AAWzC,SAAgB,YAAY,WAAmB,WAAmB,KAAsB;CACtF,OAAO,MAAM,aAAa,KAAK,IAAI,GAAG,YAAY,yBAAyB;AAC7E"}

package/dist/cloudflare/bindings.d.cts

@@ -0,0 +1,144 @@
+import { EmailAddress } from "../config.cjs";
+//#region src/cloudflare/bindings.d.ts
+/**
+ * A minimal structural interface over the Cloudflare bindings.
+ *
+ * @cloudflare/workers-types is deliberately not used: the global types it
+ * injects clash with the DOM lib this package's react side needs. A structural
+ * subset plus the ambient cloudflare:workers declaration is enough to compile,
+ * and the real bindings satisfy it structurally at runtime.
+ */
+export interface KVNamespaceLike {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string): Promise<void>;
+}
+/** Structural subset of D1Result: `meta.changes` is how INSERT OR IGNORE reports whether it inserted. */
+export interface D1RunResultLike {
+  meta?: {
+    changes?: number;
+  };
+}
+export interface D1PreparedStatementLike {
+  bind(...values: unknown[]): D1PreparedStatementLike;
+  first<T = Record<string, unknown>>(): Promise<T | null>;
+  all<T = Record<string, unknown>>(): Promise<{
+    results: T[];
+  }>;
+  run(): Promise<D1RunResultLike>;
+}
+export interface D1DatabaseLike {
+  prepare(sql: string): D1PreparedStatementLike;
+  /** Statements run in order inside one transaction (real D1 semantics) — deploy relies on the atomicity. */
+  batch(statements: D1PreparedStatementLike[]): Promise<unknown>;
+}
+export interface WorkflowInstanceLike {
+  id: string;
+  sendEvent(event: {
+    type: string;
+    payload?: unknown;
+  }): Promise<void>;
+  /** Stop the instance for good (Cloudflare Workflows' `terminate`). */
+  terminate?(): Promise<void>;
+  /** Where it stands (`complete`, `errored`, `terminated`, `running`, …). */
+  status?(): Promise<{
+    status: string;
+  }>;
+}
+export interface WorkflowBindingLike {
+  create(options: {
+    id: string;
+    params: unknown;
+  }): Promise<WorkflowInstanceLike>;
+  get(id: string): Promise<WorkflowInstanceLike>;
+}
+/**
+ * Cloudflare Email Service's send_email binding (structural subset).
+ *
+ * `idempotencyKey` is part of the call because the send happens inside a
+ * `step.do`: a step body re-runs after its fn resolved but before the
+ * checkpoint committed, so a binding that drops the key mails the user twice.
+ * The binding is app-supplied glue (nothing here can de-duplicate — there is
+ * no state between two runs of the same step), which is why the port makes the
+ * key impossible to miss rather than merely available.
+ */
+export interface EmailBindingLike {
+  send(message: {
+    from: EmailAddress;
+    to: EmailAddress;
+    replyTo?: EmailAddress;
+    subject: string;
+    html: string;
+    /** `${instanceId}:${nodeId}`: stable across replays and retries — drop a send whose key was already delivered. */
+    idempotencyKey: string;
+  }): Promise<unknown>;
+}
+/** Every binding the journey engine needs (names match the wrangler config). */
+export interface JourneyEnv {
+  /**
+   * BundleIR storage for the default D1 store (`wf:${contentHash}` → WorkflowIR JSON). Optional:
+   * a Worker on another JourneyStore (Postgres, say) does not declare it.
+   */
+  WORKFLOW_KV?: KVNamespaceLike;
+  /** Tables of the default D1 store (events / profiles / segments / triggers / entries / subscriptions). Optional, as above. */
+  DB?: D1DatabaseLike;
+  /** JourneyRunner's workflow binding (creating instances and waking them). */
+  JOURNEY: WorkflowBindingLike;
+  /** Optional message-delivery webhook (defaults to the console logging sender). */
+  MESSAGE_WEBHOOK_URL?: string;
+  /**
+   * Bearer token required on every mutating HTTP endpoint (`Authorization:
+   * Bearer <token>`). Unset = open — acceptable only for local dev; /deploy in
+   * particular rewrites the whole routing table, so production must set this.
+   */
+  API_TOKEN?: string;
+  /**
+   * This Worker's public origin. With a store that keeps reporting (Postgres), journey emails'
+   * links and open pixel point at its `/t/...` routes; without it emails go out untracked.
+   */
+  WORKFLOW_ORIGIN?: string;
+  /** Which `workflow.config.ts` entry applies (`development`, `production`, …); production when unset. */
+  ENVIRONMENT?: string;
+  /** Cloudflare Email Sending, when the config has `emails`. */
+  EMAIL?: EmailBindingLike;
+  /** The APNs auth key (`.p8`, base64) named by the config's `apns.keyId`. */
+  APNS_PRIVATE_KEY_BASE64?: string;
+  /** The Firebase service account (base64 JSON) the config's `fcm` sends with. */
+  GOOGLE_APPLICATION_CREDENTIALS_BASE64?: string;
+  /** The VAPID key pair web pushes are signed with (`generateVapidKeys`); the config's `webPush` turns the channel on. */
+  VAPID_PUBLIC_KEY?: string;
+  VAPID_PRIVATE_KEY?: string;
+  /** Development only: the HTTP/2 relay `wrangler dev` sends APNs requests through (see `@shware/workflow/apns-relay`). */
+  APNS_RELAY_ORIGIN?: string;
+}
+/** The event type the router uses to wake waiting instances (sendEvent's `type`). */
+export declare const WAKE_EVENT_TYPE = "wake";
+/** Journey instance parameters, passed by the ingest router when it creates one. */
+export interface JourneyParams {
+  workflowId: string;
+  /** The IR version pinned at entry. */
+  contentHash: string;
+  userId: string;
+  trigger: {
+    event: string;
+    payload: Record<string, unknown>;
+  };
+  [key: string]: unknown;
+}
+/**
+ * Slack on the deadline when deciding whether a thrown wait was a timeout: the
+ * platform may surface the expiry a moment early, and a wait shorter than this
+ * has no room to tell the two apart anyway.
+ */
+export declare const WAKE_TIMEOUT_TOLERANCE_MS = 5000;
+/**
+ * Did a wait that threw actually reach its deadline?
+ *
+ * CF signals a wait timeout by throwing, and so does every other failure in
+ * there — a broken binding, an evicted instance, a malformed timeout. The
+ * adapter used to read them all as timeouts, which made an infrastructure
+ * fault indistinguishable from "the user never did it": the journey took its
+ * onTimeout branch, early and silently. Only the clock can tell them apart.
+ */
+export declare function wakeExpired(startedAt: number, timeoutMs: number, now: number): boolean;
+//#endregion
+//# sourceMappingURL=bindings.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.d.cts","names":[],"sources":["../../src/cloudflare/bindings.ts"],"mappings":";;;;;;;;;;iBAWiB;EACf,IAAI,cAAc;EAClB,IAAI,aAAa,gBAAgB;;;iBAIlB;EACf;IAAS;;;iBAGM;EACf,QAAQ,oBAAoB;EAC5B,MAAM,IAAI,4BAA4B,QAAQ;EAC9C,IAAI,IAAI,4BAA4B;IAAU,SAAS;;EACvD,OAAO,QAAQ;;iBAGA;EACf,QAAQ,cAAc;;EAEtB,MAAM,YAAY,4BAA4B;;iBAG/B;EACf;EACA,UAAU;IAAS;IAAc;MAAsB;;EAEvD,cAAc;;EAEd,WAAW;IAAU;;;iBAGN;EACf,OAAO;IAAW;IAAY;MAAoB,QAAQ;EAC1D,IAAI,aAAa,QAAQ;;;;;;;;;;;;iBAaV;EACf,KAAK;IACH,MAAM;IACN,IAAI;IACJ,UAAU;IACV;IACA;;IAEA;MACE;;;iBAIW;;;;;EAKf,cAAc;;EAEd,KAAK;;EAEL,SAAS;;EAET;;;;;;EAMA;;;;;EAKA;;EAEA;;EAEA,QAAQ;;EAER;;EAEA;;EAEA;EACA;;EAEA;;;qBAIW;;iBAGI;EACf;;EAEA;EACA;EACA;IAAW;IAAe,SAAS;;GAClC;;;;;;;qBAQU;;;;;;;;;;wBAWG,YAAY,mBAAmB,mBAAmB"}

package/dist/cloudflare/bindings.d.mts

@@ -0,0 +1,144 @@
+import { EmailAddress } from "../config.mjs";
+//#region src/cloudflare/bindings.d.ts
+/**
+ * A minimal structural interface over the Cloudflare bindings.
+ *
+ * @cloudflare/workers-types is deliberately not used: the global types it
+ * injects clash with the DOM lib this package's react side needs. A structural
+ * subset plus the ambient cloudflare:workers declaration is enough to compile,
+ * and the real bindings satisfy it structurally at runtime.
+ */
+export interface KVNamespaceLike {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string): Promise<void>;
+}
+/** Structural subset of D1Result: `meta.changes` is how INSERT OR IGNORE reports whether it inserted. */
+export interface D1RunResultLike {
+  meta?: {
+    changes?: number;
+  };
+}
+export interface D1PreparedStatementLike {
+  bind(...values: unknown[]): D1PreparedStatementLike;
+  first<T = Record<string, unknown>>(): Promise<T | null>;
+  all<T = Record<string, unknown>>(): Promise<{
+    results: T[];
+  }>;
+  run(): Promise<D1RunResultLike>;
+}
+export interface D1DatabaseLike {
+  prepare(sql: string): D1PreparedStatementLike;
+  /** Statements run in order inside one transaction (real D1 semantics) — deploy relies on the atomicity. */
+  batch(statements: D1PreparedStatementLike[]): Promise<unknown>;
+}
+export interface WorkflowInstanceLike {
+  id: string;
+  sendEvent(event: {
+    type: string;
+    payload?: unknown;
+  }): Promise<void>;
+  /** Stop the instance for good (Cloudflare Workflows' `terminate`). */
+  terminate?(): Promise<void>;
+  /** Where it stands (`complete`, `errored`, `terminated`, `running`, …). */
+  status?(): Promise<{
+    status: string;
+  }>;
+}
+export interface WorkflowBindingLike {
+  create(options: {
+    id: string;
+    params: unknown;
+  }): Promise<WorkflowInstanceLike>;
+  get(id: string): Promise<WorkflowInstanceLike>;
+}
+/**
+ * Cloudflare Email Service's send_email binding (structural subset).
+ *
+ * `idempotencyKey` is part of the call because the send happens inside a
+ * `step.do`: a step body re-runs after its fn resolved but before the
+ * checkpoint committed, so a binding that drops the key mails the user twice.
+ * The binding is app-supplied glue (nothing here can de-duplicate — there is
+ * no state between two runs of the same step), which is why the port makes the
+ * key impossible to miss rather than merely available.
+ */
+export interface EmailBindingLike {
+  send(message: {
+    from: EmailAddress;
+    to: EmailAddress;
+    replyTo?: EmailAddress;
+    subject: string;
+    html: string;
+    /** `${instanceId}:${nodeId}`: stable across replays and retries — drop a send whose key was already delivered. */
+    idempotencyKey: string;
+  }): Promise<unknown>;
+}
+/** Every binding the journey engine needs (names match the wrangler config). */
+export interface JourneyEnv {
+  /**
+   * BundleIR storage for the default D1 store (`wf:${contentHash}` → WorkflowIR JSON). Optional:
+   * a Worker on another JourneyStore (Postgres, say) does not declare it.
+   */
+  WORKFLOW_KV?: KVNamespaceLike;
+  /** Tables of the default D1 store (events / profiles / segments / triggers / entries / subscriptions). Optional, as above. */
+  DB?: D1DatabaseLike;
+  /** JourneyRunner's workflow binding (creating instances and waking them). */
+  JOURNEY: WorkflowBindingLike;
+  /** Optional message-delivery webhook (defaults to the console logging sender). */
+  MESSAGE_WEBHOOK_URL?: string;
+  /**
+   * Bearer token required on every mutating HTTP endpoint (`Authorization:
+   * Bearer <token>`). Unset = open — acceptable only for local dev; /deploy in
+   * particular rewrites the whole routing table, so production must set this.
+   */
+  API_TOKEN?: string;
+  /**
+   * This Worker's public origin. With a store that keeps reporting (Postgres), journey emails'
+   * links and open pixel point at its `/t/...` routes; without it emails go out untracked.
+   */
+  WORKFLOW_ORIGIN?: string;
+  /** Which `workflow.config.ts` entry applies (`development`, `production`, …); production when unset. */
+  ENVIRONMENT?: string;
+  /** Cloudflare Email Sending, when the config has `emails`. */
+  EMAIL?: EmailBindingLike;
+  /** The APNs auth key (`.p8`, base64) named by the config's `apns.keyId`. */
+  APNS_PRIVATE_KEY_BASE64?: string;
+  /** The Firebase service account (base64 JSON) the config's `fcm` sends with. */
+  GOOGLE_APPLICATION_CREDENTIALS_BASE64?: string;
+  /** The VAPID key pair web pushes are signed with (`generateVapidKeys`); the config's `webPush` turns the channel on. */
+  VAPID_PUBLIC_KEY?: string;
+  VAPID_PRIVATE_KEY?: string;
+  /** Development only: the HTTP/2 relay `wrangler dev` sends APNs requests through (see `@shware/workflow/apns-relay`). */
+  APNS_RELAY_ORIGIN?: string;
+}
+/** The event type the router uses to wake waiting instances (sendEvent's `type`). */
+export declare const WAKE_EVENT_TYPE = "wake";
+/** Journey instance parameters, passed by the ingest router when it creates one. */
+export interface JourneyParams {
+  workflowId: string;
+  /** The IR version pinned at entry. */
+  contentHash: string;
+  userId: string;
+  trigger: {
+    event: string;
+    payload: Record<string, unknown>;
+  };
+  [key: string]: unknown;
+}
+/**
+ * Slack on the deadline when deciding whether a thrown wait was a timeout: the
+ * platform may surface the expiry a moment early, and a wait shorter than this
+ * has no room to tell the two apart anyway.
+ */
+export declare const WAKE_TIMEOUT_TOLERANCE_MS = 5000;
+/**
+ * Did a wait that threw actually reach its deadline?
+ *
+ * CF signals a wait timeout by throwing, and so does every other failure in
+ * there — a broken binding, an evicted instance, a malformed timeout. The
+ * adapter used to read them all as timeouts, which made an infrastructure
+ * fault indistinguishable from "the user never did it": the journey took its
+ * onTimeout branch, early and silently. Only the clock can tell them apart.
+ */
+export declare function wakeExpired(startedAt: number, timeoutMs: number, now: number): boolean;
+//#endregion
+//# sourceMappingURL=bindings.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.d.mts","names":[],"sources":["../../src/cloudflare/bindings.ts"],"mappings":";;;;;;;;;;iBAWiB;EACf,IAAI,cAAc;EAClB,IAAI,aAAa,gBAAgB;;;iBAIlB;EACf;IAAS;;;iBAGM;EACf,QAAQ,oBAAoB;EAC5B,MAAM,IAAI,4BAA4B,QAAQ;EAC9C,IAAI,IAAI,4BAA4B;IAAU,SAAS;;EACvD,OAAO,QAAQ;;iBAGA;EACf,QAAQ,cAAc;;EAEtB,MAAM,YAAY,4BAA4B;;iBAG/B;EACf;EACA,UAAU;IAAS;IAAc;MAAsB;;EAEvD,cAAc;;EAEd,WAAW;IAAU;;;iBAGN;EACf,OAAO;IAAW;IAAY;MAAoB,QAAQ;EAC1D,IAAI,aAAa,QAAQ;;;;;;;;;;;;iBAaV;EACf,KAAK;IACH,MAAM;IACN,IAAI;IACJ,UAAU;IACV;IACA;;IAEA;MACE;;;iBAIW;;;;;EAKf,cAAc;;EAEd,KAAK;;EAEL,SAAS;;EAET;;;;;;EAMA;;;;;EAKA;;EAEA;;EAEA,QAAQ;;EAER;;EAEA;;EAEA;EACA;;EAEA;;;qBAIW;;iBAGI;EACf;;EAEA;EACA;EACA;IAAW;IAAe,SAAS;;GAClC;;;;;;;qBAQU;;;;;;;;;;wBAWG,YAAY,mBAAmB,mBAAmB"}

package/dist/cloudflare/bindings.mjs

@@ -0,0 +1,25 @@
+//#region src/cloudflare/bindings.ts
+/** The event type the router uses to wake waiting instances (sendEvent's `type`). */
+const WAKE_EVENT_TYPE = "wake";
+/**
+* Slack on the deadline when deciding whether a thrown wait was a timeout: the
+* platform may surface the expiry a moment early, and a wait shorter than this
+* has no room to tell the two apart anyway.
+*/
+const WAKE_TIMEOUT_TOLERANCE_MS = 5e3;
+/**
+* Did a wait that threw actually reach its deadline?
+*
+* CF signals a wait timeout by throwing, and so does every other failure in
+* there — a broken binding, an evicted instance, a malformed timeout. The
+* adapter used to read them all as timeouts, which made an infrastructure
+* fault indistinguishable from "the user never did it": the journey took its
+* onTimeout branch, early and silently. Only the clock can tell them apart.
+*/
+function wakeExpired(startedAt, timeoutMs, now) {
+	return now - startedAt >= Math.max(0, timeoutMs - WAKE_TIMEOUT_TOLERANCE_MS);
+}
+//#endregion
+export { WAKE_EVENT_TYPE, WAKE_TIMEOUT_TOLERANCE_MS, wakeExpired };
+
+//# sourceMappingURL=bindings.mjs.map

package/dist/cloudflare/bindings.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.mjs","names":[],"sources":["../../src/cloudflare/bindings.ts"],"sourcesContent":["import type { EmailAddress } from '../config';\n\n/**\n * A minimal structural interface over the Cloudflare bindings.\n *\n * @cloudflare/workers-types is deliberately not used: the global types it\n * injects clash with the DOM lib this package's react side needs. A structural\n * subset plus the ambient cloudflare:workers declaration is enough to compile,\n * and the real bindings satisfy it structurally at runtime.\n */\n\nexport interface KVNamespaceLike {\n  get(key: string): Promise<string | null>;\n  put(key: string, value: string): Promise<void>;\n}\n\n/** Structural subset of D1Result: `meta.changes` is how INSERT OR IGNORE reports whether it inserted. */\nexport interface D1RunResultLike {\n  meta?: { changes?: number };\n}\n\nexport interface D1PreparedStatementLike {\n  bind(...values: unknown[]): D1PreparedStatementLike;\n  first<T = Record<string, unknown>>(): Promise<T | null>;\n  all<T = Record<string, unknown>>(): Promise<{ results: T[] }>;\n  run(): Promise<D1RunResultLike>;\n}\n\nexport interface D1DatabaseLike {\n  prepare(sql: string): D1PreparedStatementLike;\n  /** Statements run in order inside one transaction (real D1 semantics) — deploy relies on the atomicity. */\n  batch(statements: D1PreparedStatementLike[]): Promise<unknown>;\n}\n\nexport interface WorkflowInstanceLike {\n  id: string;\n  sendEvent(event: { type: string; payload?: unknown }): Promise<void>;\n  /** Stop the instance for good (Cloudflare Workflows' `terminate`). */\n  terminate?(): Promise<void>;\n  /** Where it stands (`complete`, `errored`, `terminated`, `running`, …). */\n  status?(): Promise<{ status: string }>;\n}\n\nexport interface WorkflowBindingLike {\n  create(options: { id: string; params: unknown }): Promise<WorkflowInstanceLike>;\n  get(id: string): Promise<WorkflowInstanceLike>;\n}\n\n/**\n * Cloudflare Email Service's send_email binding (structural subset).\n *\n * `idempotencyKey` is part of the call because the send happens inside a\n * `step.do`: a step body re-runs after its fn resolved but before the\n * checkpoint committed, so a binding that drops the key mails the user twice.\n * The binding is app-supplied glue (nothing here can de-duplicate — there is\n * no state between two runs of the same step), which is why the port makes the\n * key impossible to miss rather than merely available.\n */\nexport interface EmailBindingLike {\n  send(message: {\n    from: EmailAddress;\n    to: EmailAddress;\n    replyTo?: EmailAddress;\n    subject: string;\n    html: string;\n    /** `${instanceId}:${nodeId}`: stable across replays and retries — drop a send whose key was already delivered. */\n    idempotencyKey: string;\n  }): Promise<unknown>;\n}\n\n/** Every binding the journey engine needs (names match the wrangler config). */\nexport interface JourneyEnv {\n  /**\n   * BundleIR storage for the default D1 store (`wf:${contentHash}` → WorkflowIR JSON). Optional:\n   * a Worker on another JourneyStore (Postgres, say) does not declare it.\n   */\n  WORKFLOW_KV?: KVNamespaceLike;\n  /** Tables of the default D1 store (events / profiles / segments / triggers / entries / subscriptions). Optional, as above. */\n  DB?: D1DatabaseLike;\n  /** JourneyRunner's workflow binding (creating instances and waking them). */\n  JOURNEY: WorkflowBindingLike;\n  /** Optional message-delivery webhook (defaults to the console logging sender). */\n  MESSAGE_WEBHOOK_URL?: string;\n  /**\n   * Bearer token required on every mutating HTTP endpoint (`Authorization:\n   * Bearer <token>`). Unset = open — acceptable only for local dev; /deploy in\n   * particular rewrites the whole routing table, so production must set this.\n   */\n  API_TOKEN?: string;\n  /**\n   * This Worker's public origin. With a store that keeps reporting (Postgres), journey emails'\n   * links and open pixel point at its `/t/...` routes; without it emails go out untracked.\n   */\n  WORKFLOW_ORIGIN?: string;\n  /** Which `workflow.config.ts` entry applies (`development`, `production`, …); production when unset. */\n  ENVIRONMENT?: string;\n  /** Cloudflare Email Sending, when the config has `emails`. */\n  EMAIL?: EmailBindingLike;\n  /** The APNs auth key (`.p8`, base64) named by the config's `apns.keyId`. */\n  APNS_PRIVATE_KEY_BASE64?: string;\n  /** The Firebase service account (base64 JSON) the config's `fcm` sends with. */\n  GOOGLE_APPLICATION_CREDENTIALS_BASE64?: string;\n  /** The VAPID key pair web pushes are signed with (`generateVapidKeys`); the config's `webPush` turns the channel on. */\n  VAPID_PUBLIC_KEY?: string;\n  VAPID_PRIVATE_KEY?: string;\n  /** Development only: the HTTP/2 relay `wrangler dev` sends APNs requests through (see `@shware/workflow/apns-relay`). */\n  APNS_RELAY_ORIGIN?: string;\n}\n\n/** The event type the router uses to wake waiting instances (sendEvent's `type`). */\nexport const WAKE_EVENT_TYPE = 'wake';\n\n/** Journey instance parameters, passed by the ingest router when it creates one. */\nexport interface JourneyParams {\n  workflowId: string;\n  /** The IR version pinned at entry. */\n  contentHash: string;\n  userId: string;\n  trigger: { event: string; payload: Record<string, unknown> };\n  [key: string]: unknown;\n}\n\n/**\n * Slack on the deadline when deciding whether a thrown wait was a timeout: the\n * platform may surface the expiry a moment early, and a wait shorter than this\n * has no room to tell the two apart anyway.\n */\nexport const WAKE_TIMEOUT_TOLERANCE_MS = 5_000;\n\n/**\n * Did a wait that threw actually reach its deadline?\n *\n * CF signals a wait timeout by throwing, and so does every other failure in\n * there — a broken binding, an evicted instance, a malformed timeout. The\n * adapter used to read them all as timeouts, which made an infrastructure\n * fault indistinguishable from \"the user never did it\": the journey took its\n * onTimeout branch, early and silently. Only the clock can tell them apart.\n */\nexport function wakeExpired(startedAt: number, timeoutMs: number, now: number): boolean {\n  return now - startedAt >= Math.max(0, timeoutMs - WAKE_TIMEOUT_TOLERANCE_MS);\n}\n"],"mappings":";;AA8GA,MAAa,kBAAkB;;;;;;AAiB/B,MAAa,4BAA4B;;;;;;;;;;AAWzC,SAAgB,YAAY,WAAmB,WAAmB,KAAsB;CACtF,OAAO,MAAM,aAAa,KAAK,IAAI,GAAG,YAAY,yBAAyB;AAC7E"}