@shware/workflow 0.0.0-stage → 0.1.0

package/dist/apns.d.cts

@@ -0,0 +1,63 @@
+import { MessageSender, OutboundMessage, SendResult } from "./engine/ports.cjs";
+import "./engine/index.cjs";
+import { PushRenderer } from "./push.cjs";
+//#region src/apns.d.ts
+/**
+ * `@shware/workflow/apns` — iOS push delivery straight to the Apple Push
+ * Notification service, token-based (an APNs auth key, the `.p8` file from the
+ * developer portal). No Firebase in between: the app registers the APNs device
+ * token in its own device table, and the host's DeviceDirectory hands it to the
+ * engine, which sends one message per device.
+ * No dependencies: the provider JWT is ES256-signed with WebCrypto.
+ *
+ * APNs speaks HTTP/2 only. A deployed Worker's `fetch` negotiates it, but
+ * workerd under `wrangler dev` does not (the connection is dropped), so a local
+ * host points `origin` at the Node relay in `@shware/workflow/apns-relay`.
+ */
+export interface ApnsPushOptions {
+  /** The key's 10-character id, shown next to it in the developer portal. */
+  keyId: string;
+  /** The Apple Developer team id. */
+  teamId: string;
+  /** The `.p8` file's contents: PEM, `-----BEGIN PRIVATE KEY-----` (PKCS #8, P-256). */
+  privateKey: string;
+  /** The app's bundle id — APNs's `apns-topic`. */
+  topic: string;
+  /**
+   * Which APNs environment the device tokens come from: `sandbox` for builds
+   * signed with `aps-environment: development` (Xcode, the simulator),
+   * `production` for App Store and TestFlight builds. A token from one is
+   * `BadDeviceToken` on the other.
+   */
+  environment: 'sandbox' | 'production';
+  render: PushRenderer;
+  /**
+   * POST here instead of Apple's host — the dev relay, which forwards over
+   * HTTP/2. The real host still travels along (`apns-relay-upstream`), so the
+   * relay needs no configuration of its own.
+   */
+  origin?: string;
+  /** Fetch implementation (defaults to the global one). */
+  fetch?: typeof fetch;
+  /** Called for a token APNs reports as gone (`Unregistered`, `BadDeviceToken`); `channelsFromConfig` passes it on to the DeviceDirectory's `disable`. */
+  onUnregistered?: (message: OutboundMessage) => Promise<void> | void;
+}
+export declare const APNS_HOSTS: {
+  readonly sandbox: 'https://api.sandbox.push.apple.com';
+  readonly production: 'https://api.push.apple.com';
+};
+export declare class ApnsPushSender implements MessageSender {
+  private readonly options;
+  private token;
+  constructor(options: ApnsPushOptions);
+  send(message: OutboundMessage): Promise<void | SendResult>;
+  private providerToken;
+}
+/** APNs error bodies are `{ "reason": "…" }`. */
+export declare function apnsReason(body: string): string;
+/** ES256-sign the APNs provider token: header `kid`, claims `iss` (team) and `iat`. */
+export declare function signApnsJwt(key: Pick<ApnsPushOptions, 'keyId' | 'teamId' | 'privateKey'>, nowMs?: number): Promise<string>;
+/** The `.p8` as it is usually shipped in a secret: base64 of the file. */
+export declare function apnsKeyFromBase64(value: string): string;
+//#endregion
+//# sourceMappingURL=apns.d.cts.map

package/dist/apns.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apns.d.cts","names":[],"sources":["../src/apns.ts"],"mappings":";;;;;;;;;;;;;;;;iBAiBiB;;EAEf;;EAEA;;EAEA;;EAEA;;;;;;;EAOA;EACA,QAAQ;;;;;;EAMR;;EAEA,eAAe;;EAEf,kBAAkB,SAAS,oBAAoB;;qBAGpC;WACX;WACA;;qBAcW,0BAA0B;mBAGR;UAFrB;EAER,YAA6B,SAAS;EAEhC,KAAK,SAAS,kBAAkB,eAAe;UAsDvC;;;wBAYA,WAAW;;wBAUL,YACpB,KAAK,KAAK,qDACV,iBACC;;wBAoBa,kBAAkB"}

package/dist/apns.d.mts

@@ -0,0 +1,63 @@
+import { MessageSender, OutboundMessage, SendResult } from "./engine/ports.mjs";
+import "./engine/index.mjs";
+import { PushRenderer } from "./push.mjs";
+//#region src/apns.d.ts
+/**
+ * `@shware/workflow/apns` — iOS push delivery straight to the Apple Push
+ * Notification service, token-based (an APNs auth key, the `.p8` file from the
+ * developer portal). No Firebase in between: the app registers the APNs device
+ * token in its own device table, and the host's DeviceDirectory hands it to the
+ * engine, which sends one message per device.
+ * No dependencies: the provider JWT is ES256-signed with WebCrypto.
+ *
+ * APNs speaks HTTP/2 only. A deployed Worker's `fetch` negotiates it, but
+ * workerd under `wrangler dev` does not (the connection is dropped), so a local
+ * host points `origin` at the Node relay in `@shware/workflow/apns-relay`.
+ */
+export interface ApnsPushOptions {
+  /** The key's 10-character id, shown next to it in the developer portal. */
+  keyId: string;
+  /** The Apple Developer team id. */
+  teamId: string;
+  /** The `.p8` file's contents: PEM, `-----BEGIN PRIVATE KEY-----` (PKCS #8, P-256). */
+  privateKey: string;
+  /** The app's bundle id — APNs's `apns-topic`. */
+  topic: string;
+  /**
+   * Which APNs environment the device tokens come from: `sandbox` for builds
+   * signed with `aps-environment: development` (Xcode, the simulator),
+   * `production` for App Store and TestFlight builds. A token from one is
+   * `BadDeviceToken` on the other.
+   */
+  environment: 'sandbox' | 'production';
+  render: PushRenderer;
+  /**
+   * POST here instead of Apple's host — the dev relay, which forwards over
+   * HTTP/2. The real host still travels along (`apns-relay-upstream`), so the
+   * relay needs no configuration of its own.
+   */
+  origin?: string;
+  /** Fetch implementation (defaults to the global one). */
+  fetch?: typeof fetch;
+  /** Called for a token APNs reports as gone (`Unregistered`, `BadDeviceToken`); `channelsFromConfig` passes it on to the DeviceDirectory's `disable`. */
+  onUnregistered?: (message: OutboundMessage) => Promise<void> | void;
+}
+export declare const APNS_HOSTS: {
+  readonly sandbox: 'https://api.sandbox.push.apple.com';
+  readonly production: 'https://api.push.apple.com';
+};
+export declare class ApnsPushSender implements MessageSender {
+  private readonly options;
+  private token;
+  constructor(options: ApnsPushOptions);
+  send(message: OutboundMessage): Promise<void | SendResult>;
+  private providerToken;
+}
+/** APNs error bodies are `{ "reason": "…" }`. */
+export declare function apnsReason(body: string): string;
+/** ES256-sign the APNs provider token: header `kid`, claims `iss` (team) and `iat`. */
+export declare function signApnsJwt(key: Pick<ApnsPushOptions, 'keyId' | 'teamId' | 'privateKey'>, nowMs?: number): Promise<string>;
+/** The `.p8` as it is usually shipped in a secret: base64 of the file. */
+export declare function apnsKeyFromBase64(value: string): string;
+//#endregion
+//# sourceMappingURL=apns.d.mts.map

package/dist/apns.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apns.d.mts","names":[],"sources":["../src/apns.ts"],"mappings":";;;;;;;;;;;;;;;;iBAiBiB;;EAEf;;EAEA;;EAEA;;EAEA;;;;;;;EAOA;EACA,QAAQ;;;;;;EAMR;;EAEA,eAAe;;EAEf,kBAAkB,SAAS,oBAAoB;;qBAGpC;WACX;WACA;;qBAcW,0BAA0B;mBAGR;UAFrB;EAER,YAA6B,SAAS;EAEhC,KAAK,SAAS,kBAAkB,eAAe;UAsDvC;;;wBAYA,WAAW;;wBAUL,YACpB,KAAK,KAAK,qDACV,iBACC;;wBAoBa,kBAAkB"}

package/dist/apns.mjs

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

package/dist/apns.mjs.map

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

package/dist/client.cjs

@@ -0,0 +1,125 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#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
+exports.JourneyClient = JourneyClient;
+exports.JourneyClientError = JourneyClientError;
+exports.JourneyValidationError = JourneyValidationError;
+
+//# sourceMappingURL=client.cjs.map

package/dist/client.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.cjs","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/client.d.cts

@@ -0,0 +1,108 @@
+import { Contract, ContractIssue, ProfilePatch } from "./contract.cjs";
+import { ProfileProps } from "./store/index.cjs";
+import { DeployResult, IdentifyResult, IngestResult } from "./cloudflare/router.cjs";
+import "./cloudflare/index.cjs";
+import * as core from "zod/v4/core";
+//#region src/client.d.ts
+/**
+ * `@shware/workflow/client` — the producer side of the ingest API, for the
+ * service that knows what users do (an api server, a webhook handler). Plain
+ * fetch, no dependencies; errors carry the status and body so a caller can
+ * log them without failing the request that triggered the report.
+ */
+export interface JourneyClientOptions<C extends Contract | undefined = undefined> {
+  /**
+   * The shared `defineContract(...)`: types `track` (the event name picks the
+   * payload type) and `identify`, and checks both before anything is sent.
+   */
+  contract?: C;
+  /** The journey Worker's origin, e.g. `https://workflow.example.com`. */
+  origin: string;
+  /** Its API_TOKEN, sent as a bearer; omit against an open local instance. */
+  token?: string;
+  /** Fetch implementation (defaults to the global one). */
+  fetch?: typeof fetch;
+}
+export declare class JourneyClientError extends Error {
+  readonly path: string;
+  readonly status: number;
+  readonly body: string;
+  constructor(path: string, status: number, body: string);
+}
+/** A payload or profile patch the contract refuses — raised before the request, with the field paths. */
+export declare class JourneyValidationError extends Error {
+  readonly path: string;
+  readonly event: string | undefined;
+  readonly issues: ContractIssue[];
+  constructor(path: string, event: string | undefined, issues: ContractIssue[]);
+}
+type EventsOf<C> = C extends Contract<infer E> ? E : never;
+/** Event names: the contract's, or any string without one. */
+export type ClientEventName<C> = [C] extends [undefined] ? string : keyof EventsOf<C> & string;
+type TrackArgs<C, K> = [C] extends [undefined] ? [payload?: Record<string, unknown>, options?: TrackOptions] : K extends keyof EventsOf<C> ? [payload: core.input<EventsOf<C>[K]>, options?: TrackOptions] : never;
+type IdentifyProps<C> = [C] extends [undefined] ? ProfileProps : C extends Contract<Record<string, core.$ZodObject>, infer P> ? ProfilePatch<P> : never;
+export interface TrackOptions {
+  /** The occurrence's identity: a retry with the same id is recorded once. */
+  id?: string;
+  /** When it happened (epoch ms); the Worker's clock when omitted. */
+  ts?: number;
+}
+export declare class JourneyClient<C extends Contract | undefined = undefined> {
+  private readonly options;
+  constructor(options: JourneyClientOptions<C>);
+  /** Merge profile properties (`null` clears one). Every property a journey reads must be identified before the event that starts it. */
+  identify(userId: string, props: IdentifyProps<C>): Promise<IdentifyResult>;
+  /**
+   * 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<K extends ClientEventName<C>>(userId: string, event: K, ...args: TrackArgs<C, K>): Promise<IngestResult>;
+  /**
+   * 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: string, device: {
+    token: string;
+    platform: 'ios' | 'android' | 'web';
+  }): Promise<{
+    ok: true;
+    woke: number;
+  }>;
+  /**
+   * 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: string, messageId: string): Promise<{
+    ok: true;
+    recorded: boolean;
+  }>;
+  /**
+   * 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: string): Promise<{
+    ok: true;
+    erased: boolean;
+    pending: string[];
+  }>;
+  /** The user signed out on that device: the token stays registered, bound to nobody. */
+  unbindDevice(token: string): Promise<{
+    ok: true;
+    woke: number;
+  }>;
+  /** Forget a push token for good (an uninstall the app learned of, a token it replaced). */
+  removeDevice(token: string): Promise<{
+    ok: true;
+    woke: number;
+  }>;
+  /** Deploy a compiled bundle (BundleIR). */
+  deploy(bundle: unknown): Promise<DeployResult>;
+  private post;
+}
+//#endregion
+//# sourceMappingURL=client.d.cts.map

package/dist/client.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.cts","names":[],"sources":["../src/client.ts"],"mappings":";;;;;;;;;;;;iBAYiB,qBAAqB,UAAU;;;;;EAK9C,WAAW;;EAEX;;EAEA;;EAEA,eAAe;;qBAGJ,2BAA2B;WAE3B;WACA;WACA;EAHX,YACW,cACA,gBACA;;;qBAQA,+BAA+B;WAE/B;WACA;WACA,QAAQ;EAHnB,YACW,cACA,2BACA,QAAQ;;KAWhB,SAAS,KAAK,UAAU,eAAe,KAAK;;YAErC,gBAAgB,MAAM,wCAAwC,SAAS;KAC9E,UAAU,GAAG,MAAM,0BACnB,UAAU,yBAAyB,UAAU,gBAC9C,gBAAgB,SAAS,MACtB,SAAS,KAAK,MAAM,SAAS,GAAG,KAAK,UAAU;KAEjD,cAAc,MAAM,yBACrB,eACA,UAAU,SAAS,eAAe,KAAK,mBAAmB,KACxD,aAAa;iBAGF;;EAEf;;EAEA;;qBAGW,cAAc,UAAU;mBACN;EAA7B,YAA6B,SAAS,qBAAqB;;EAG3D,SAAS,gBAAgB,OAAO,cAAc,KAAK,QAAQ;;;;;;;EAgB3D,MAAM,UAAU,gBAAgB,IAC9B,gBACA,OAAO,MACJ,MAAM,UAAU,GAAG,KACrB,QAAQ;;;;;;EAsBX,eACE,gBACA;IAAU;IAAe;MACxB;IAAU;IAAU;;;;;;EAQvB,cAAc,gBAAgB,oBAAoB;IAAU;IAAU;;;;;;;;EAUtE,WAAW,iBAAiB;IAAU;IAAU;IAAiB;;;EAKjE,aAAa,gBAAgB;IAAU;IAAU;;;EAKjD,aAAa,gBAAgB;IAAU;IAAU;;;EAKjD,OAAO,kBAAkB,QAAQ;UAInB"}

package/dist/client.d.mts

@@ -0,0 +1,108 @@
+import { Contract, ContractIssue, ProfilePatch } from "./contract.mjs";
+import { ProfileProps } from "./store/index.mjs";
+import { DeployResult, IdentifyResult, IngestResult } from "./cloudflare/router.mjs";
+import "./cloudflare/index.mjs";
+import * as core from "zod/v4/core";
+//#region src/client.d.ts
+/**
+ * `@shware/workflow/client` — the producer side of the ingest API, for the
+ * service that knows what users do (an api server, a webhook handler). Plain
+ * fetch, no dependencies; errors carry the status and body so a caller can
+ * log them without failing the request that triggered the report.
+ */
+export interface JourneyClientOptions<C extends Contract | undefined = undefined> {
+  /**
+   * The shared `defineContract(...)`: types `track` (the event name picks the
+   * payload type) and `identify`, and checks both before anything is sent.
+   */
+  contract?: C;
+  /** The journey Worker's origin, e.g. `https://workflow.example.com`. */
+  origin: string;
+  /** Its API_TOKEN, sent as a bearer; omit against an open local instance. */
+  token?: string;
+  /** Fetch implementation (defaults to the global one). */
+  fetch?: typeof fetch;
+}
+export declare class JourneyClientError extends Error {
+  readonly path: string;
+  readonly status: number;
+  readonly body: string;
+  constructor(path: string, status: number, body: string);
+}
+/** A payload or profile patch the contract refuses — raised before the request, with the field paths. */
+export declare class JourneyValidationError extends Error {
+  readonly path: string;
+  readonly event: string | undefined;
+  readonly issues: ContractIssue[];
+  constructor(path: string, event: string | undefined, issues: ContractIssue[]);
+}
+type EventsOf<C> = C extends Contract<infer E> ? E : never;
+/** Event names: the contract's, or any string without one. */
+export type ClientEventName<C> = [C] extends [undefined] ? string : keyof EventsOf<C> & string;
+type TrackArgs<C, K> = [C] extends [undefined] ? [payload?: Record<string, unknown>, options?: TrackOptions] : K extends keyof EventsOf<C> ? [payload: core.input<EventsOf<C>[K]>, options?: TrackOptions] : never;
+type IdentifyProps<C> = [C] extends [undefined] ? ProfileProps : C extends Contract<Record<string, core.$ZodObject>, infer P> ? ProfilePatch<P> : never;
+export interface TrackOptions {
+  /** The occurrence's identity: a retry with the same id is recorded once. */
+  id?: string;
+  /** When it happened (epoch ms); the Worker's clock when omitted. */
+  ts?: number;
+}
+export declare class JourneyClient<C extends Contract | undefined = undefined> {
+  private readonly options;
+  constructor(options: JourneyClientOptions<C>);
+  /** Merge profile properties (`null` clears one). Every property a journey reads must be identified before the event that starts it. */
+  identify(userId: string, props: IdentifyProps<C>): Promise<IdentifyResult>;
+  /**
+   * 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<K extends ClientEventName<C>>(userId: string, event: K, ...args: TrackArgs<C, K>): Promise<IngestResult>;
+  /**
+   * 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: string, device: {
+    token: string;
+    platform: 'ios' | 'android' | 'web';
+  }): Promise<{
+    ok: true;
+    woke: number;
+  }>;
+  /**
+   * 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: string, messageId: string): Promise<{
+    ok: true;
+    recorded: boolean;
+  }>;
+  /**
+   * 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: string): Promise<{
+    ok: true;
+    erased: boolean;
+    pending: string[];
+  }>;
+  /** The user signed out on that device: the token stays registered, bound to nobody. */
+  unbindDevice(token: string): Promise<{
+    ok: true;
+    woke: number;
+  }>;
+  /** Forget a push token for good (an uninstall the app learned of, a token it replaced). */
+  removeDevice(token: string): Promise<{
+    ok: true;
+    woke: number;
+  }>;
+  /** Deploy a compiled bundle (BundleIR). */
+  deploy(bundle: unknown): Promise<DeployResult>;
+  private post;
+}
+//#endregion
+//# sourceMappingURL=client.d.mts.map

package/dist/client.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.mts","names":[],"sources":["../src/client.ts"],"mappings":";;;;;;;;;;;;iBAYiB,qBAAqB,UAAU;;;;;EAK9C,WAAW;;EAEX;;EAEA;;EAEA,eAAe;;qBAGJ,2BAA2B;WAE3B;WACA;WACA;EAHX,YACW,cACA,gBACA;;;qBAQA,+BAA+B;WAE/B;WACA;WACA,QAAQ;EAHnB,YACW,cACA,2BACA,QAAQ;;KAWhB,SAAS,KAAK,UAAU,eAAe,KAAK;;YAErC,gBAAgB,MAAM,wCAAwC,SAAS;KAC9E,UAAU,GAAG,MAAM,0BACnB,UAAU,yBAAyB,UAAU,gBAC9C,gBAAgB,SAAS,MACtB,SAAS,KAAK,MAAM,SAAS,GAAG,KAAK,UAAU;KAEjD,cAAc,MAAM,yBACrB,eACA,UAAU,SAAS,eAAe,KAAK,mBAAmB,KACxD,aAAa;iBAGF;;EAEf;;EAEA;;qBAGW,cAAc,UAAU;mBACN;EAA7B,YAA6B,SAAS,qBAAqB;;EAG3D,SAAS,gBAAgB,OAAO,cAAc,KAAK,QAAQ;;;;;;;EAgB3D,MAAM,UAAU,gBAAgB,IAC9B,gBACA,OAAO,MACJ,MAAM,UAAU,GAAG,KACrB,QAAQ;;;;;;EAsBX,eACE,gBACA;IAAU;IAAe;MACxB;IAAU;IAAU;;;;;;EAQvB,cAAc,gBAAgB,oBAAoB;IAAU;IAAU;;;;;;;;EAUtE,WAAW,iBAAiB;IAAU;IAAU;IAAiB;;;EAKjE,aAAa,gBAAgB;IAAU;IAAU;;;EAKjD,aAAa,gBAAgB;IAAU;IAAU;;;EAKjD,OAAO,kBAAkB,QAAQ;UAInB"}