@shware/workflow 0.0.0-stage → 0.1.0

package/dist/reporting/tracking.cjs

@@ -0,0 +1,153 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_reporting_classify = require("./classify.cjs");
+//#region src/reporting/tracking.ts
+const GIF = Uint8Array.from(atob("R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"), (char) => char.charCodeAt(0));
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function requester(request) {
+	const cf = request.cf;
+	return {
+		method: request.method,
+		userAgent: request.headers.get("user-agent"),
+		asn: cf?.asn ?? null,
+		organization: cf?.asOrganization ?? null,
+		country: cf?.country ?? null
+	};
+}
+/** A `/t/...` request's response, or undefined when the path is not a tracking route. */
+async function handleTracking(request, reporting, options = {}) {
+	const [, root, kind, id, position] = new URL(request.url).pathname.split("/");
+	if (root !== "t" || id === void 0 || !UUID.test(id)) return void 0;
+	const who = requester(request);
+	const read = who.method === "GET" || who.method === "HEAD";
+	if (kind === "o" && read) {
+		await recordOpen(reporting, id, who, options);
+		return new Response(who.method === "HEAD" ? null : GIF, { headers: {
+			"content-type": "image/gif",
+			"cache-control": "no-store, max-age=0"
+		} });
+	}
+	if (kind === "c" && position !== void 0 && read) {
+		const target = await recordClick(reporting, id, Number(position), who, options);
+		if (target === void 0) return page(options, "This link has expired.", 404);
+		if (options.unsubscribe !== void 0 && sameLink(target, options.unsubscribe)) return page(options, `Unsubscribe from ${escape(options.product ?? "these")} emails?`, 200, `<form method="post" action="/t/u/${id}"><button type="submit">Unsubscribe</button></form>`);
+		return Response.redirect(target, 302);
+	}
+	if (kind === "d" && who.method === "POST") {
+		const known = await reporting.recordDeviceDelivered(id, Date.now());
+		return new Response(null, { status: known ? 204 : 404 });
+	}
+	if (kind === "p" && who.method === "POST") {
+		const at = Date.now();
+		let userId;
+		const known = await reporting.recordOpen(id, (message) => {
+			userId = message.userId;
+			return {
+				at,
+				machine: false,
+				reason: null,
+				...network(who)
+			};
+		});
+		if (known && userId !== void 0 && options.pushOpened !== void 0) try {
+			await options.pushOpened({
+				messageId: id,
+				userId,
+				at
+			});
+		} catch (error) {
+			console.error(`[workflow] recording push open ${id} as an event failed`, error);
+		}
+		return new Response(null, { status: known ? 204 : 404 });
+	}
+	if (kind === "u" && who.method === "POST") {
+		if (!await reporting.recordUnsubscribe(id, Date.now())) return page(options, "This link has expired.", 404);
+		return page(options, options.product === void 0 ? "You won't get these emails anymore." : `You won't get these emails from ${escape(options.product)} anymore.`);
+	}
+}
+/**
+* A journey push tapped open, as the app reports it (`JourneyClient.messageOpened`): an open on
+* the copy — only the recipient's own, and never a machine, since no proxy or scanner taps a
+* notification. False when the message is unknown or not the user's.
+*/
+async function recordPushOpen(reporting, userId, messageId, at = Date.now()) {
+	if (!UUID.test(messageId)) return false;
+	let recorded = false;
+	await reporting.recordOpen(messageId, (message) => {
+		if (message.userId !== userId) return void 0;
+		recorded = true;
+		return {
+			at,
+			machine: false,
+			reason: null,
+			userAgent: null,
+			asn: null,
+			organization: null,
+			country: null
+		};
+	});
+	return recorded;
+}
+async function recordOpen(reporting, id, who, options) {
+	const at = Date.now();
+	await reporting.recordOpen(id, (message) => ({
+		at,
+		...require_reporting_classify.classifyOpen({
+			...who,
+			sinceDeliveredMs: at - message.deliveredAt
+		}, { quickMs: options.quickMs }),
+		...network(who)
+	}));
+}
+const network = (who) => ({
+	userAgent: who.userAgent,
+	asn: who.asn,
+	organization: who.organization,
+	country: who.country
+});
+/** Records the click and answers the URL to send the visitor to, or undefined for an unknown link. */
+async function recordClick(reporting, id, position, who, options) {
+	if (!Number.isInteger(position) || position < 0) return void 0;
+	const at = Date.now();
+	return (await reporting.recordClick(id, position, at, require_reporting_classify.BURST_WINDOW_MS, (link) => {
+		const linksInBurst = (/* @__PURE__ */ new Set([position, ...link.recent.map((click) => click.position)])).size;
+		const verdict = require_reporting_classify.classifyClick({
+			...who,
+			sinceDeliveredMs: at - link.deliveredAt,
+			linksInBurst,
+			linkCount: link.linkCount
+		}, { quickMs: options.quickMs });
+		return {
+			engagement: {
+				at,
+				...verdict,
+				...network(who)
+			},
+			backdate: verdict.reason === "link_burst" || verdict.reason === "quick+link_pair"
+		};
+	}))?.url;
+}
+/** The unsubscribe link may carry its own query (a token, a list): the path names it. */
+function sameLink(target, unsubscribe) {
+	try {
+		const a = new URL(target);
+		const b = new URL(unsubscribe);
+		return a.origin === b.origin && a.pathname === b.pathname;
+	} catch {
+		return false;
+	}
+}
+function escape(text) {
+	return text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+}
+function page(options, message, status = 200, extra = "") {
+	const html = `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escape(options.product ?? "Email")}</title><style>body{font:16px system-ui;margin:0;display:grid;place-items:center;min-height:100vh;background:#fafafa;color:#18181b}main{text-align:center;padding:24px}button{font:inherit;padding:10px 20px;border-radius:9999px;border:0;background:#18181b;color:#fff;cursor:pointer}</style></head><body><main><p>${message}</p>${extra}</main></body></html>`;
+	return new Response(html, {
+		status,
+		headers: { "content-type": "text/html; charset=utf-8" }
+	});
+}
+//#endregion
+exports.handleTracking = handleTracking;
+exports.recordPushOpen = recordPushOpen;
+
+//# sourceMappingURL=tracking.cjs.map

package/dist/reporting/tracking.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking.cjs","names":["classifyOpen","BURST_WINDOW_MS","classifyClick"],"sources":["../../src/reporting/tracking.ts"],"sourcesContent":["import type { JourneyReporting } from '../store';\nimport { BURST_WINDOW_MS, classifyClick, classifyOpen } from './classify';\n\n/**\n * The endpoints a journey email's tracking points at (see ./observer.ts), served by journeyWorker\n * without a bearer — recipients open them:\n *\n *   GET /t/o/<message>             the open pixel: records the open, answers a 1×1 GIF\n *   GET /t/c/<message>/<position>  a link: records the click, redirects to the recorded URL\n *   POST /t/u/<message>            the unsubscribe confirmation\n *   POST /t/d/<message>            a push the device received (iOS's notification service\n *                                  extension, a browser's service worker)\n *   POST /t/p/<message>            a push opened, reported by a browser's service worker\n *\n * Every open and click is recorded with its verdict (./classify.ts), and the message keeps its\n * first open and click of each kind. The redirect goes only to the URL recorded for that position,\n * never to one the request carries, so the endpoint cannot bounce visitors anywhere else. The\n * config's unsubscribe link (`emails.unsubscribe`) is a tracked link too: following it shows a\n * confirmation page, and only the confirmation — a POST, which no link scanner sends — counts.\n */\n\nexport interface TrackingOptions {\n  /** `emails.unsubscribe` from the config: the footer link that asks for confirmation instead of redirecting. */\n  unsubscribe?: string | undefined;\n  /** The name the confirmation pages show (the config's `title`). */\n  product?: string | undefined;\n  /** `emails.tracking.quickClickMs`: how soon after delivery an open or click is a weak machine signal. */\n  quickMs?: number | undefined;\n  /** A browser reported a push tapped (`/t/p`): the host records it as an event too (`webPush.openedEvent`). */\n  pushOpened?:\n    | ((open: { messageId: string; userId: string; at: number }) => Promise<void>)\n    | undefined;\n}\n\nconst GIF = Uint8Array.from(\n  atob('R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7'),\n  (char) => char.charCodeAt(0)\n);\nconst UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\n\ninterface Requester {\n  method: string;\n  userAgent: string | null;\n  asn: number | null;\n  organization: string | null;\n  country: string | null;\n}\n\nfunction requester(request: Request): Requester {\n  const cf = (\n    request as Request & { cf?: { asn?: number; asOrganization?: string; country?: string } }\n  ).cf;\n  return {\n    method: request.method,\n    userAgent: request.headers.get('user-agent'),\n    asn: cf?.asn ?? null,\n    organization: cf?.asOrganization ?? null,\n    country: cf?.country ?? null,\n  };\n}\n\n/** A `/t/...` request's response, or undefined when the path is not a tracking route. */\nexport async function handleTracking(\n  request: Request,\n  reporting: JourneyReporting,\n  options: TrackingOptions = {}\n): Promise<Response | undefined> {\n  const url = new URL(request.url);\n  const [, root, kind, id, position] = url.pathname.split('/');\n  if (root !== 't' || id === undefined || !UUID.test(id)) return undefined;\n  const who = requester(request);\n  const read = who.method === 'GET' || who.method === 'HEAD';\n  if (kind === 'o' && read) {\n    await recordOpen(reporting, id, who, options);\n    return new Response(who.method === 'HEAD' ? null : GIF, {\n      headers: { 'content-type': 'image/gif', 'cache-control': 'no-store, max-age=0' },\n    });\n  }\n  if (kind === 'c' && position !== undefined && read) {\n    const target = await recordClick(reporting, id, Number(position), who, options);\n    if (target === undefined) return page(options, 'This link has expired.', 404);\n    if (options.unsubscribe !== undefined && sameLink(target, options.unsubscribe)) {\n      return page(\n        options,\n        `Unsubscribe from ${escape(options.product ?? 'these')} emails?`,\n        200,\n        `<form method=\"post\" action=\"/t/u/${id}\"><button type=\"submit\">Unsubscribe</button></form>`\n      );\n    }\n    return Response.redirect(target, 302);\n  }\n  if (kind === 'd' && who.method === 'POST') {\n    const known = await reporting.recordDeviceDelivered(id, Date.now());\n    return new Response(null, { status: known ? 204 : 404 });\n  }\n  if (kind === 'p' && who.method === 'POST') {\n    // A notification tap: a person, as the message id is what proves it is theirs\n    const at = Date.now();\n    let userId: string | undefined;\n    const known = await reporting.recordOpen(id, (message) => {\n      userId = message.userId;\n      return { at, machine: false, reason: null, ...network(who) };\n    });\n    if (known && userId !== undefined && options.pushOpened !== undefined) {\n      try {\n        await options.pushOpened({ messageId: id, userId, at });\n      } catch (error) {\n        // The open is recorded; the event is the host's extra, never a reason to fail the beacon\n        console.error(`[workflow] recording push open ${id} as an event failed`, error);\n      }\n    }\n    return new Response(null, { status: known ? 204 : 404 });\n  }\n  if (kind === 'u' && who.method === 'POST') {\n    const known = await reporting.recordUnsubscribe(id, Date.now());\n    if (!known) return page(options, 'This link has expired.', 404);\n    return page(\n      options,\n      options.product === undefined\n        ? \"You won't get these emails anymore.\"\n        : `You won't get these emails from ${escape(options.product)} anymore.`\n    );\n  }\n  return undefined;\n}\n\n/**\n * A journey push tapped open, as the app reports it (`JourneyClient.messageOpened`): an open on\n * the copy — only the recipient's own, and never a machine, since no proxy or scanner taps a\n * notification. False when the message is unknown or not the user's.\n */\nexport async function recordPushOpen(\n  reporting: JourneyReporting,\n  userId: string,\n  messageId: string,\n  at = Date.now()\n): Promise<boolean> {\n  if (!UUID.test(messageId)) return false;\n  let recorded = false;\n  await reporting.recordOpen(messageId, (message) => {\n    if (message.userId !== userId) return undefined;\n    recorded = true;\n    return {\n      at,\n      machine: false,\n      reason: null,\n      userAgent: null,\n      asn: null,\n      organization: null,\n      country: null,\n    };\n  });\n  return recorded;\n}\n\nasync function recordOpen(\n  reporting: JourneyReporting,\n  id: string,\n  who: Requester,\n  options: TrackingOptions\n) {\n  const at = Date.now();\n  await reporting.recordOpen(id, (message) => ({\n    at,\n    ...classifyOpen(\n      { ...who, sinceDeliveredMs: at - message.deliveredAt },\n      { quickMs: options.quickMs }\n    ),\n    ...network(who),\n  }));\n}\n\nconst network = (who: Requester) => ({\n  userAgent: who.userAgent,\n  asn: who.asn,\n  organization: who.organization,\n  country: who.country,\n});\n\n/** Records the click and answers the URL to send the visitor to, or undefined for an unknown link. */\nasync function recordClick(\n  reporting: JourneyReporting,\n  id: string,\n  position: number,\n  who: Requester,\n  options: TrackingOptions\n): Promise<string | undefined> {\n  if (!Number.isInteger(position) || position < 0) return undefined;\n  const at = Date.now();\n  const recorded = await reporting.recordClick(id, position, at, BURST_WINDOW_MS, (link) => {\n    const linksInBurst = new Set([position, ...link.recent.map((click) => click.position)]).size;\n    const verdict = classifyClick(\n      { ...who, sinceDeliveredMs: at - link.deliveredAt, linksInBurst, linkCount: link.linkCount },\n      { quickMs: options.quickMs }\n    );\n    return {\n      engagement: { at, ...verdict, ...network(who) },\n      backdate: verdict.reason === 'link_burst' || verdict.reason === 'quick+link_pair',\n    };\n  });\n  return recorded?.url;\n}\n\n/** The unsubscribe link may carry its own query (a token, a list): the path names it. */\nfunction sameLink(target: string, unsubscribe: string): boolean {\n  try {\n    const a = new URL(target);\n    const b = new URL(unsubscribe);\n    return a.origin === b.origin && a.pathname === b.pathname;\n  } catch {\n    return false;\n  }\n}\n\nfunction escape(text: string): string {\n  return text.replace(/[&<>\"']/g, (c) => `&#${c.charCodeAt(0)};`);\n}\n\nfunction page(options: TrackingOptions, message: string, status = 200, extra = ''): Response {\n  const title = escape(options.product ?? 'Email');\n  const html = `<!doctype html><html><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\"><title>${title}</title><style>body{font:16px system-ui;margin:0;display:grid;place-items:center;min-height:100vh;background:#fafafa;color:#18181b}main{text-align:center;padding:24px}button{font:inherit;padding:10px 20px;border-radius:9999px;border:0;background:#18181b;color:#fff;cursor:pointer}</style></head><body><main><p>${message}</p>${extra}</main></body></html>`;\n  return new Response(html, { status, headers: { 'content-type': 'text/html; charset=utf-8' } });\n}\n"],"mappings":";;;AAkCA,MAAM,MAAM,WAAW,KACrB,KAAK,0DAA0D,IAC9D,SAAS,KAAK,WAAW,CAAC,CAC7B;AACA,MAAM,OAAO;AAUb,SAAS,UAAU,SAA6B;CAC9C,MAAM,KACJ,QACA;CACF,OAAO;EACL,QAAQ,QAAQ;EAChB,WAAW,QAAQ,QAAQ,IAAI,YAAY;EAC3C,KAAK,IAAI,OAAO;EAChB,cAAc,IAAI,kBAAkB;EACpC,SAAS,IAAI,WAAW;CAC1B;AACF;;AAGA,eAAsB,eACpB,SACA,WACA,UAA2B,CAAC,GACG;CAE/B,MAAM,GAAG,MAAM,MAAM,IAAI,YAAY,IADrB,IAAI,QAAQ,GACW,CAAC,CAAC,SAAS,MAAM,GAAG;CAC3D,IAAI,SAAS,OAAO,OAAO,KAAA,KAAa,CAAC,KAAK,KAAK,EAAE,GAAG,OAAO,KAAA;CAC/D,MAAM,MAAM,UAAU,OAAO;CAC7B,MAAM,OAAO,IAAI,WAAW,SAAS,IAAI,WAAW;CACpD,IAAI,SAAS,OAAO,MAAM;EACxB,MAAM,WAAW,WAAW,IAAI,KAAK,OAAO;EAC5C,OAAO,IAAI,SAAS,IAAI,WAAW,SAAS,OAAO,KAAK,EACtD,SAAS;GAAE,gBAAgB;GAAa,iBAAiB;EAAsB,EACjF,CAAC;CACH;CACA,IAAI,SAAS,OAAO,aAAa,KAAA,KAAa,MAAM;EAClD,MAAM,SAAS,MAAM,YAAY,WAAW,IAAI,OAAO,QAAQ,GAAG,KAAK,OAAO;EAC9E,IAAI,WAAW,KAAA,GAAW,OAAO,KAAK,SAAS,0BAA0B,GAAG;EAC5E,IAAI,QAAQ,gBAAgB,KAAA,KAAa,SAAS,QAAQ,QAAQ,WAAW,GAC3E,OAAO,KACL,SACA,oBAAoB,OAAO,QAAQ,WAAW,OAAO,EAAE,WACvD,KACA,oCAAoC,GAAG,oDACzC;EAEF,OAAO,SAAS,SAAS,QAAQ,GAAG;CACtC;CACA,IAAI,SAAS,OAAO,IAAI,WAAW,QAAQ;EACzC,MAAM,QAAQ,MAAM,UAAU,sBAAsB,IAAI,KAAK,IAAI,CAAC;EAClE,OAAO,IAAI,SAAS,MAAM,EAAE,QAAQ,QAAQ,MAAM,IAAI,CAAC;CACzD;CACA,IAAI,SAAS,OAAO,IAAI,WAAW,QAAQ;EAEzC,MAAM,KAAK,KAAK,IAAI;EACpB,IAAI;EACJ,MAAM,QAAQ,MAAM,UAAU,WAAW,KAAK,YAAY;GACxD,SAAS,QAAQ;GACjB,OAAO;IAAE;IAAI,SAAS;IAAO,QAAQ;IAAM,GAAG,QAAQ,GAAG;GAAE;EAC7D,CAAC;EACD,IAAI,SAAS,WAAW,KAAA,KAAa,QAAQ,eAAe,KAAA,GAC1D,IAAI;GACF,MAAM,QAAQ,WAAW;IAAE,WAAW;IAAI;IAAQ;GAAG,CAAC;EACxD,SAAS,OAAO;GAEd,QAAQ,MAAM,kCAAkC,GAAG,sBAAsB,KAAK;EAChF;EAEF,OAAO,IAAI,SAAS,MAAM,EAAE,QAAQ,QAAQ,MAAM,IAAI,CAAC;CACzD;CACA,IAAI,SAAS,OAAO,IAAI,WAAW,QAAQ;EAEzC,IAAI,CAAC,MADe,UAAU,kBAAkB,IAAI,KAAK,IAAI,CAAC,GAClD,OAAO,KAAK,SAAS,0BAA0B,GAAG;EAC9D,OAAO,KACL,SACA,QAAQ,YAAY,KAAA,IAChB,wCACA,mCAAmC,OAAO,QAAQ,OAAO,EAAE,UACjE;CACF;AAEF;;;;;;AAOA,eAAsB,eACpB,WACA,QACA,WACA,KAAK,KAAK,IAAI,GACI;CAClB,IAAI,CAAC,KAAK,KAAK,SAAS,GAAG,OAAO;CAClC,IAAI,WAAW;CACf,MAAM,UAAU,WAAW,YAAY,YAAY;EACjD,IAAI,QAAQ,WAAW,QAAQ,OAAO,KAAA;EACtC,WAAW;EACX,OAAO;GACL;GACA,SAAS;GACT,QAAQ;GACR,WAAW;GACX,KAAK;GACL,cAAc;GACd,SAAS;EACX;CACF,CAAC;CACD,OAAO;AACT;AAEA,eAAe,WACb,WACA,IACA,KACA,SACA;CACA,MAAM,KAAK,KAAK,IAAI;CACpB,MAAM,UAAU,WAAW,KAAK,aAAa;EAC3C;EACA,GAAGA,2BAAAA,aACD;GAAE,GAAG;GAAK,kBAAkB,KAAK,QAAQ;EAAY,GACrD,EAAE,SAAS,QAAQ,QAAQ,CAC7B;EACA,GAAG,QAAQ,GAAG;CAChB,EAAE;AACJ;AAEA,MAAM,WAAW,SAAoB;CACnC,WAAW,IAAI;CACf,KAAK,IAAI;CACT,cAAc,IAAI;CAClB,SAAS,IAAI;AACf;;AAGA,eAAe,YACb,WACA,IACA,UACA,KACA,SAC6B;CAC7B,IAAI,CAAC,OAAO,UAAU,QAAQ,KAAK,WAAW,GAAG,OAAO,KAAA;CACxD,MAAM,KAAK,KAAK,IAAI;CAYpB,QAAO,MAXgB,UAAU,YAAY,IAAI,UAAU,IAAIC,2BAAAA,kBAAkB,SAAS;EACxF,MAAM,gCAAe,IAAI,IAAI,CAAC,UAAU,GAAG,KAAK,OAAO,KAAK,UAAU,MAAM,QAAQ,CAAC,CAAC,EAAA,CAAE;EACxF,MAAM,UAAUC,2BAAAA,cACd;GAAE,GAAG;GAAK,kBAAkB,KAAK,KAAK;GAAa;GAAc,WAAW,KAAK;EAAU,GAC3F,EAAE,SAAS,QAAQ,QAAQ,CAC7B;EACA,OAAO;GACL,YAAY;IAAE;IAAI,GAAG;IAAS,GAAG,QAAQ,GAAG;GAAE;GAC9C,UAAU,QAAQ,WAAW,gBAAgB,QAAQ,WAAW;EAClE;CACF,CAAC,EAAA,EACgB;AACnB;;AAGA,SAAS,SAAS,QAAgB,aAA8B;CAC9D,IAAI;EACF,MAAM,IAAI,IAAI,IAAI,MAAM;EACxB,MAAM,IAAI,IAAI,IAAI,WAAW;EAC7B,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE;CACnD,QAAQ;EACN,OAAO;CACT;AACF;AAEA,SAAS,OAAO,MAAsB;CACpC,OAAO,KAAK,QAAQ,aAAa,MAAM,KAAK,EAAE,WAAW,CAAC,EAAE,EAAE;AAChE;AAEA,SAAS,KAAK,SAA0B,SAAiB,SAAS,KAAK,QAAQ,IAAc;CAE3F,MAAM,OAAO,8HADC,OAAO,QAAQ,WAAW,OACuG,EAAE,wTAAwT,QAAQ,MAAM,MAAM;CAC7d,OAAO,IAAI,SAAS,MAAM;EAAE;EAAQ,SAAS,EAAE,gBAAgB,2BAA2B;CAAE,CAAC;AAC/F"}

package/dist/reporting/tracking.d.cts

@@ -0,0 +1,43 @@
+import { JourneyReporting } from "../store/index.cjs";
+//#region src/reporting/tracking.d.ts
+/**
+ * The endpoints a journey email's tracking points at (see ./observer.ts), served by journeyWorker
+ * without a bearer — recipients open them:
+ *
+ *   GET /t/o/<message>             the open pixel: records the open, answers a 1×1 GIF
+ *   GET /t/c/<message>/<position>  a link: records the click, redirects to the recorded URL
+ *   POST /t/u/<message>            the unsubscribe confirmation
+ *   POST /t/d/<message>            a push the device received (iOS's notification service
+ *                                  extension, a browser's service worker)
+ *   POST /t/p/<message>            a push opened, reported by a browser's service worker
+ *
+ * Every open and click is recorded with its verdict (./classify.ts), and the message keeps its
+ * first open and click of each kind. The redirect goes only to the URL recorded for that position,
+ * never to one the request carries, so the endpoint cannot bounce visitors anywhere else. The
+ * config's unsubscribe link (`emails.unsubscribe`) is a tracked link too: following it shows a
+ * confirmation page, and only the confirmation — a POST, which no link scanner sends — counts.
+ */
+export interface TrackingOptions {
+  /** `emails.unsubscribe` from the config: the footer link that asks for confirmation instead of redirecting. */
+  unsubscribe?: string | undefined;
+  /** The name the confirmation pages show (the config's `title`). */
+  product?: string | undefined;
+  /** `emails.tracking.quickClickMs`: how soon after delivery an open or click is a weak machine signal. */
+  quickMs?: number | undefined;
+  /** A browser reported a push tapped (`/t/p`): the host records it as an event too (`webPush.openedEvent`). */
+  pushOpened?: ((open: {
+    messageId: string;
+    userId: string;
+    at: number;
+  }) => Promise<void>) | undefined;
+}
+/** A `/t/...` request's response, or undefined when the path is not a tracking route. */
+export declare function handleTracking(request: Request, reporting: JourneyReporting, options?: TrackingOptions): Promise<Response | undefined>;
+/**
+ * A journey push tapped open, as the app reports it (`JourneyClient.messageOpened`): an open on
+ * the copy — only the recipient's own, and never a machine, since no proxy or scanner taps a
+ * notification. False when the message is unknown or not the user's.
+ */
+export declare function recordPushOpen(reporting: JourneyReporting, userId: string, messageId: string, at?: number): Promise<boolean>;
+//#endregion
+//# sourceMappingURL=tracking.d.cts.map

package/dist/reporting/tracking.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking.d.cts","names":[],"sources":["../../src/reporting/tracking.ts"],"mappings":";;;;;;;;;;;;;;;;;;;iBAqBiB;;EAEf;;EAEA;;EAEA;;EAEA,eACM;IAAQ;IAAmB;IAAgB;QAAiB;;;wBAgC9C,eACpB,SAAS,SACT,WAAW,kBACX,UAAS,kBACR,QAAQ;;;;;;wBAiEW,eACpB,WAAW,kBACX,gBACA,mBACA,cACC"}

package/dist/reporting/tracking.d.mts

@@ -0,0 +1,43 @@
+import { JourneyReporting } from "../store/index.mjs";
+//#region src/reporting/tracking.d.ts
+/**
+ * The endpoints a journey email's tracking points at (see ./observer.ts), served by journeyWorker
+ * without a bearer — recipients open them:
+ *
+ *   GET /t/o/<message>             the open pixel: records the open, answers a 1×1 GIF
+ *   GET /t/c/<message>/<position>  a link: records the click, redirects to the recorded URL
+ *   POST /t/u/<message>            the unsubscribe confirmation
+ *   POST /t/d/<message>            a push the device received (iOS's notification service
+ *                                  extension, a browser's service worker)
+ *   POST /t/p/<message>            a push opened, reported by a browser's service worker
+ *
+ * Every open and click is recorded with its verdict (./classify.ts), and the message keeps its
+ * first open and click of each kind. The redirect goes only to the URL recorded for that position,
+ * never to one the request carries, so the endpoint cannot bounce visitors anywhere else. The
+ * config's unsubscribe link (`emails.unsubscribe`) is a tracked link too: following it shows a
+ * confirmation page, and only the confirmation — a POST, which no link scanner sends — counts.
+ */
+export interface TrackingOptions {
+  /** `emails.unsubscribe` from the config: the footer link that asks for confirmation instead of redirecting. */
+  unsubscribe?: string | undefined;
+  /** The name the confirmation pages show (the config's `title`). */
+  product?: string | undefined;
+  /** `emails.tracking.quickClickMs`: how soon after delivery an open or click is a weak machine signal. */
+  quickMs?: number | undefined;
+  /** A browser reported a push tapped (`/t/p`): the host records it as an event too (`webPush.openedEvent`). */
+  pushOpened?: ((open: {
+    messageId: string;
+    userId: string;
+    at: number;
+  }) => Promise<void>) | undefined;
+}
+/** A `/t/...` request's response, or undefined when the path is not a tracking route. */
+export declare function handleTracking(request: Request, reporting: JourneyReporting, options?: TrackingOptions): Promise<Response | undefined>;
+/**
+ * A journey push tapped open, as the app reports it (`JourneyClient.messageOpened`): an open on
+ * the copy — only the recipient's own, and never a machine, since no proxy or scanner taps a
+ * notification. False when the message is unknown or not the user's.
+ */
+export declare function recordPushOpen(reporting: JourneyReporting, userId: string, messageId: string, at?: number): Promise<boolean>;
+//#endregion
+//# sourceMappingURL=tracking.d.mts.map

package/dist/reporting/tracking.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking.d.mts","names":[],"sources":["../../src/reporting/tracking.ts"],"mappings":";;;;;;;;;;;;;;;;;;;iBAqBiB;;EAEf;;EAEA;;EAEA;;EAEA,eACM;IAAQ;IAAmB;IAAgB;QAAiB;;;wBAgC9C,eACpB,SAAS,SACT,WAAW,kBACX,UAAS,kBACR,QAAQ;;;;;;wBAiEW,eACpB,WAAW,kBACX,gBACA,mBACA,cACC"}

package/dist/reporting/tracking.mjs

@@ -0,0 +1,151 @@
+import { BURST_WINDOW_MS, classifyClick, classifyOpen } from "./classify.mjs";
+//#region src/reporting/tracking.ts
+const GIF = Uint8Array.from(atob("R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"), (char) => char.charCodeAt(0));
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function requester(request) {
+	const cf = request.cf;
+	return {
+		method: request.method,
+		userAgent: request.headers.get("user-agent"),
+		asn: cf?.asn ?? null,
+		organization: cf?.asOrganization ?? null,
+		country: cf?.country ?? null
+	};
+}
+/** A `/t/...` request's response, or undefined when the path is not a tracking route. */
+async function handleTracking(request, reporting, options = {}) {
+	const [, root, kind, id, position] = new URL(request.url).pathname.split("/");
+	if (root !== "t" || id === void 0 || !UUID.test(id)) return void 0;
+	const who = requester(request);
+	const read = who.method === "GET" || who.method === "HEAD";
+	if (kind === "o" && read) {
+		await recordOpen(reporting, id, who, options);
+		return new Response(who.method === "HEAD" ? null : GIF, { headers: {
+			"content-type": "image/gif",
+			"cache-control": "no-store, max-age=0"
+		} });
+	}
+	if (kind === "c" && position !== void 0 && read) {
+		const target = await recordClick(reporting, id, Number(position), who, options);
+		if (target === void 0) return page(options, "This link has expired.", 404);
+		if (options.unsubscribe !== void 0 && sameLink(target, options.unsubscribe)) return page(options, `Unsubscribe from ${escape(options.product ?? "these")} emails?`, 200, `<form method="post" action="/t/u/${id}"><button type="submit">Unsubscribe</button></form>`);
+		return Response.redirect(target, 302);
+	}
+	if (kind === "d" && who.method === "POST") {
+		const known = await reporting.recordDeviceDelivered(id, Date.now());
+		return new Response(null, { status: known ? 204 : 404 });
+	}
+	if (kind === "p" && who.method === "POST") {
+		const at = Date.now();
+		let userId;
+		const known = await reporting.recordOpen(id, (message) => {
+			userId = message.userId;
+			return {
+				at,
+				machine: false,
+				reason: null,
+				...network(who)
+			};
+		});
+		if (known && userId !== void 0 && options.pushOpened !== void 0) try {
+			await options.pushOpened({
+				messageId: id,
+				userId,
+				at
+			});
+		} catch (error) {
+			console.error(`[workflow] recording push open ${id} as an event failed`, error);
+		}
+		return new Response(null, { status: known ? 204 : 404 });
+	}
+	if (kind === "u" && who.method === "POST") {
+		if (!await reporting.recordUnsubscribe(id, Date.now())) return page(options, "This link has expired.", 404);
+		return page(options, options.product === void 0 ? "You won't get these emails anymore." : `You won't get these emails from ${escape(options.product)} anymore.`);
+	}
+}
+/**
+* A journey push tapped open, as the app reports it (`JourneyClient.messageOpened`): an open on
+* the copy — only the recipient's own, and never a machine, since no proxy or scanner taps a
+* notification. False when the message is unknown or not the user's.
+*/
+async function recordPushOpen(reporting, userId, messageId, at = Date.now()) {
+	if (!UUID.test(messageId)) return false;
+	let recorded = false;
+	await reporting.recordOpen(messageId, (message) => {
+		if (message.userId !== userId) return void 0;
+		recorded = true;
+		return {
+			at,
+			machine: false,
+			reason: null,
+			userAgent: null,
+			asn: null,
+			organization: null,
+			country: null
+		};
+	});
+	return recorded;
+}
+async function recordOpen(reporting, id, who, options) {
+	const at = Date.now();
+	await reporting.recordOpen(id, (message) => ({
+		at,
+		...classifyOpen({
+			...who,
+			sinceDeliveredMs: at - message.deliveredAt
+		}, { quickMs: options.quickMs }),
+		...network(who)
+	}));
+}
+const network = (who) => ({
+	userAgent: who.userAgent,
+	asn: who.asn,
+	organization: who.organization,
+	country: who.country
+});
+/** Records the click and answers the URL to send the visitor to, or undefined for an unknown link. */
+async function recordClick(reporting, id, position, who, options) {
+	if (!Number.isInteger(position) || position < 0) return void 0;
+	const at = Date.now();
+	return (await reporting.recordClick(id, position, at, BURST_WINDOW_MS, (link) => {
+		const linksInBurst = (/* @__PURE__ */ new Set([position, ...link.recent.map((click) => click.position)])).size;
+		const verdict = classifyClick({
+			...who,
+			sinceDeliveredMs: at - link.deliveredAt,
+			linksInBurst,
+			linkCount: link.linkCount
+		}, { quickMs: options.quickMs });
+		return {
+			engagement: {
+				at,
+				...verdict,
+				...network(who)
+			},
+			backdate: verdict.reason === "link_burst" || verdict.reason === "quick+link_pair"
+		};
+	}))?.url;
+}
+/** The unsubscribe link may carry its own query (a token, a list): the path names it. */
+function sameLink(target, unsubscribe) {
+	try {
+		const a = new URL(target);
+		const b = new URL(unsubscribe);
+		return a.origin === b.origin && a.pathname === b.pathname;
+	} catch {
+		return false;
+	}
+}
+function escape(text) {
+	return text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+}
+function page(options, message, status = 200, extra = "") {
+	const html = `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escape(options.product ?? "Email")}</title><style>body{font:16px system-ui;margin:0;display:grid;place-items:center;min-height:100vh;background:#fafafa;color:#18181b}main{text-align:center;padding:24px}button{font:inherit;padding:10px 20px;border-radius:9999px;border:0;background:#18181b;color:#fff;cursor:pointer}</style></head><body><main><p>${message}</p>${extra}</main></body></html>`;
+	return new Response(html, {
+		status,
+		headers: { "content-type": "text/html; charset=utf-8" }
+	});
+}
+//#endregion
+export { handleTracking, recordPushOpen };
+
+//# sourceMappingURL=tracking.mjs.map

package/dist/reporting/tracking.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracking.mjs","names":[],"sources":["../../src/reporting/tracking.ts"],"sourcesContent":["import type { JourneyReporting } from '../store';\nimport { BURST_WINDOW_MS, classifyClick, classifyOpen } from './classify';\n\n/**\n * The endpoints a journey email's tracking points at (see ./observer.ts), served by journeyWorker\n * without a bearer — recipients open them:\n *\n *   GET /t/o/<message>             the open pixel: records the open, answers a 1×1 GIF\n *   GET /t/c/<message>/<position>  a link: records the click, redirects to the recorded URL\n *   POST /t/u/<message>            the unsubscribe confirmation\n *   POST /t/d/<message>            a push the device received (iOS's notification service\n *                                  extension, a browser's service worker)\n *   POST /t/p/<message>            a push opened, reported by a browser's service worker\n *\n * Every open and click is recorded with its verdict (./classify.ts), and the message keeps its\n * first open and click of each kind. The redirect goes only to the URL recorded for that position,\n * never to one the request carries, so the endpoint cannot bounce visitors anywhere else. The\n * config's unsubscribe link (`emails.unsubscribe`) is a tracked link too: following it shows a\n * confirmation page, and only the confirmation — a POST, which no link scanner sends — counts.\n */\n\nexport interface TrackingOptions {\n  /** `emails.unsubscribe` from the config: the footer link that asks for confirmation instead of redirecting. */\n  unsubscribe?: string | undefined;\n  /** The name the confirmation pages show (the config's `title`). */\n  product?: string | undefined;\n  /** `emails.tracking.quickClickMs`: how soon after delivery an open or click is a weak machine signal. */\n  quickMs?: number | undefined;\n  /** A browser reported a push tapped (`/t/p`): the host records it as an event too (`webPush.openedEvent`). */\n  pushOpened?:\n    | ((open: { messageId: string; userId: string; at: number }) => Promise<void>)\n    | undefined;\n}\n\nconst GIF = Uint8Array.from(\n  atob('R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7'),\n  (char) => char.charCodeAt(0)\n);\nconst UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\n\ninterface Requester {\n  method: string;\n  userAgent: string | null;\n  asn: number | null;\n  organization: string | null;\n  country: string | null;\n}\n\nfunction requester(request: Request): Requester {\n  const cf = (\n    request as Request & { cf?: { asn?: number; asOrganization?: string; country?: string } }\n  ).cf;\n  return {\n    method: request.method,\n    userAgent: request.headers.get('user-agent'),\n    asn: cf?.asn ?? null,\n    organization: cf?.asOrganization ?? null,\n    country: cf?.country ?? null,\n  };\n}\n\n/** A `/t/...` request's response, or undefined when the path is not a tracking route. */\nexport async function handleTracking(\n  request: Request,\n  reporting: JourneyReporting,\n  options: TrackingOptions = {}\n): Promise<Response | undefined> {\n  const url = new URL(request.url);\n  const [, root, kind, id, position] = url.pathname.split('/');\n  if (root !== 't' || id === undefined || !UUID.test(id)) return undefined;\n  const who = requester(request);\n  const read = who.method === 'GET' || who.method === 'HEAD';\n  if (kind === 'o' && read) {\n    await recordOpen(reporting, id, who, options);\n    return new Response(who.method === 'HEAD' ? null : GIF, {\n      headers: { 'content-type': 'image/gif', 'cache-control': 'no-store, max-age=0' },\n    });\n  }\n  if (kind === 'c' && position !== undefined && read) {\n    const target = await recordClick(reporting, id, Number(position), who, options);\n    if (target === undefined) return page(options, 'This link has expired.', 404);\n    if (options.unsubscribe !== undefined && sameLink(target, options.unsubscribe)) {\n      return page(\n        options,\n        `Unsubscribe from ${escape(options.product ?? 'these')} emails?`,\n        200,\n        `<form method=\"post\" action=\"/t/u/${id}\"><button type=\"submit\">Unsubscribe</button></form>`\n      );\n    }\n    return Response.redirect(target, 302);\n  }\n  if (kind === 'd' && who.method === 'POST') {\n    const known = await reporting.recordDeviceDelivered(id, Date.now());\n    return new Response(null, { status: known ? 204 : 404 });\n  }\n  if (kind === 'p' && who.method === 'POST') {\n    // A notification tap: a person, as the message id is what proves it is theirs\n    const at = Date.now();\n    let userId: string | undefined;\n    const known = await reporting.recordOpen(id, (message) => {\n      userId = message.userId;\n      return { at, machine: false, reason: null, ...network(who) };\n    });\n    if (known && userId !== undefined && options.pushOpened !== undefined) {\n      try {\n        await options.pushOpened({ messageId: id, userId, at });\n      } catch (error) {\n        // The open is recorded; the event is the host's extra, never a reason to fail the beacon\n        console.error(`[workflow] recording push open ${id} as an event failed`, error);\n      }\n    }\n    return new Response(null, { status: known ? 204 : 404 });\n  }\n  if (kind === 'u' && who.method === 'POST') {\n    const known = await reporting.recordUnsubscribe(id, Date.now());\n    if (!known) return page(options, 'This link has expired.', 404);\n    return page(\n      options,\n      options.product === undefined\n        ? \"You won't get these emails anymore.\"\n        : `You won't get these emails from ${escape(options.product)} anymore.`\n    );\n  }\n  return undefined;\n}\n\n/**\n * A journey push tapped open, as the app reports it (`JourneyClient.messageOpened`): an open on\n * the copy — only the recipient's own, and never a machine, since no proxy or scanner taps a\n * notification. False when the message is unknown or not the user's.\n */\nexport async function recordPushOpen(\n  reporting: JourneyReporting,\n  userId: string,\n  messageId: string,\n  at = Date.now()\n): Promise<boolean> {\n  if (!UUID.test(messageId)) return false;\n  let recorded = false;\n  await reporting.recordOpen(messageId, (message) => {\n    if (message.userId !== userId) return undefined;\n    recorded = true;\n    return {\n      at,\n      machine: false,\n      reason: null,\n      userAgent: null,\n      asn: null,\n      organization: null,\n      country: null,\n    };\n  });\n  return recorded;\n}\n\nasync function recordOpen(\n  reporting: JourneyReporting,\n  id: string,\n  who: Requester,\n  options: TrackingOptions\n) {\n  const at = Date.now();\n  await reporting.recordOpen(id, (message) => ({\n    at,\n    ...classifyOpen(\n      { ...who, sinceDeliveredMs: at - message.deliveredAt },\n      { quickMs: options.quickMs }\n    ),\n    ...network(who),\n  }));\n}\n\nconst network = (who: Requester) => ({\n  userAgent: who.userAgent,\n  asn: who.asn,\n  organization: who.organization,\n  country: who.country,\n});\n\n/** Records the click and answers the URL to send the visitor to, or undefined for an unknown link. */\nasync function recordClick(\n  reporting: JourneyReporting,\n  id: string,\n  position: number,\n  who: Requester,\n  options: TrackingOptions\n): Promise<string | undefined> {\n  if (!Number.isInteger(position) || position < 0) return undefined;\n  const at = Date.now();\n  const recorded = await reporting.recordClick(id, position, at, BURST_WINDOW_MS, (link) => {\n    const linksInBurst = new Set([position, ...link.recent.map((click) => click.position)]).size;\n    const verdict = classifyClick(\n      { ...who, sinceDeliveredMs: at - link.deliveredAt, linksInBurst, linkCount: link.linkCount },\n      { quickMs: options.quickMs }\n    );\n    return {\n      engagement: { at, ...verdict, ...network(who) },\n      backdate: verdict.reason === 'link_burst' || verdict.reason === 'quick+link_pair',\n    };\n  });\n  return recorded?.url;\n}\n\n/** The unsubscribe link may carry its own query (a token, a list): the path names it. */\nfunction sameLink(target: string, unsubscribe: string): boolean {\n  try {\n    const a = new URL(target);\n    const b = new URL(unsubscribe);\n    return a.origin === b.origin && a.pathname === b.pathname;\n  } catch {\n    return false;\n  }\n}\n\nfunction escape(text: string): string {\n  return text.replace(/[&<>\"']/g, (c) => `&#${c.charCodeAt(0)};`);\n}\n\nfunction page(options: TrackingOptions, message: string, status = 200, extra = ''): Response {\n  const title = escape(options.product ?? 'Email');\n  const html = `<!doctype html><html><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\"><title>${title}</title><style>body{font:16px system-ui;margin:0;display:grid;place-items:center;min-height:100vh;background:#fafafa;color:#18181b}main{text-align:center;padding:24px}button{font:inherit;padding:10px 20px;border-radius:9999px;border:0;background:#18181b;color:#fff;cursor:pointer}</style></head><body><main><p>${message}</p>${extra}</main></body></html>`;\n  return new Response(html, { status, headers: { 'content-type': 'text/html; charset=utf-8' } });\n}\n"],"mappings":"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"}

package/dist/runtime.cjs

@@ -0,0 +1,19 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/runtime.ts
+const DEFAULTS = {
+	timeScale: 1,
+	logMessages: false
+};
+/** The options for `mode`, defaults filled in; `config` may be absent altogether. */
+function resolveRuntime(config, mode) {
+	const entry = config?.[mode] ?? {};
+	const timeScale = entry.timeScale ?? DEFAULTS.timeScale;
+	return {
+		timeScale: Number.isFinite(timeScale) && timeScale > 0 ? timeScale : DEFAULTS.timeScale,
+		logMessages: entry.logMessages ?? DEFAULTS.logMessages
+	};
+}
+//#endregion
+exports.resolveRuntime = resolveRuntime;
+
+//# sourceMappingURL=runtime.cjs.map

package/dist/runtime.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.cjs","names":[],"sources":["../src/runtime.ts"],"sourcesContent":["/**\n * Runtime options — how the engine should behave in a given environment, as\n * typed configuration rather than loose environment variables. A project keeps\n * one `JourneyRuntimeConfig` (typically in its `workflow.config.ts`, next to the\n * studio settings) with one entry per mode; the host resolves the entry for\n * the environment it is running in and hands it to the runner.\n *\n * The only thing that should come from the environment is the mode itself —\n * which entry applies — never the values.\n */\n\nexport interface JourneyRuntimeOptions {\n  /**\n   * Fast-forward factor for every duration in a journey — delays, random\n   * delays, wait timeouts, goal and `performed(within)` windows scale\n   * together (see engine/time-scale.ts). 3600 turns \"2 days\" into 48 s.\n   * 1 (the default) is real time; anything else belongs to development only.\n   */\n  timeScale?: number;\n  /** Log every outbound message (channel, template, recipient, resolved props) as it is sent. */\n  logMessages?: boolean;\n}\n\n/** Environments a project distinguishes; any string works, these two are the conventional ones. */\nexport type JourneyMode = 'development' | 'production' | (string & {});\n\n/** One options entry per mode. Missing modes run with the defaults (real time, quiet). */\nexport type JourneyRuntimeConfig = Partial<Record<JourneyMode, JourneyRuntimeOptions>>;\n\nconst DEFAULTS: Required<JourneyRuntimeOptions> = { timeScale: 1, logMessages: false };\n\n/** The options for `mode`, defaults filled in; `config` may be absent altogether. */\nexport function resolveRuntime(\n  config: JourneyRuntimeConfig | undefined,\n  mode: JourneyMode\n): Required<JourneyRuntimeOptions> {\n  const entry = config?.[mode] ?? {};\n  const timeScale = entry.timeScale ?? DEFAULTS.timeScale;\n  return {\n    timeScale: Number.isFinite(timeScale) && timeScale > 0 ? timeScale : DEFAULTS.timeScale,\n    logMessages: entry.logMessages ?? DEFAULTS.logMessages,\n  };\n}\n"],"mappings":";;AA6BA,MAAM,WAA4C;CAAE,WAAW;CAAG,aAAa;AAAM;;AAGrF,SAAgB,eACd,QACA,MACiC;CACjC,MAAM,QAAQ,SAAS,SAAS,CAAC;CACjC,MAAM,YAAY,MAAM,aAAa,SAAS;CAC9C,OAAO;EACL,WAAW,OAAO,SAAS,SAAS,KAAK,YAAY,IAAI,YAAY,SAAS;EAC9E,aAAa,MAAM,eAAe,SAAS;CAC7C;AACF"}

package/dist/runtime.d.cts

@@ -0,0 +1,30 @@
+//#region src/runtime.d.ts
+/**
+ * Runtime options — how the engine should behave in a given environment, as
+ * typed configuration rather than loose environment variables. A project keeps
+ * one `JourneyRuntimeConfig` (typically in its `workflow.config.ts`, next to the
+ * studio settings) with one entry per mode; the host resolves the entry for
+ * the environment it is running in and hands it to the runner.
+ *
+ * The only thing that should come from the environment is the mode itself —
+ * which entry applies — never the values.
+ */
+export interface JourneyRuntimeOptions {
+  /**
+   * Fast-forward factor for every duration in a journey — delays, random
+   * delays, wait timeouts, goal and `performed(within)` windows scale
+   * together (see engine/time-scale.ts). 3600 turns "2 days" into 48 s.
+   * 1 (the default) is real time; anything else belongs to development only.
+   */
+  timeScale?: number;
+  /** Log every outbound message (channel, template, recipient, resolved props) as it is sent. */
+  logMessages?: boolean;
+}
+/** Environments a project distinguishes; any string works, these two are the conventional ones. */
+export type JourneyMode = 'development' | 'production' | (string & {});
+/** One options entry per mode. Missing modes run with the defaults (real time, quiet). */
+export type JourneyRuntimeConfig = Partial<Record<JourneyMode, JourneyRuntimeOptions>>;
+/** The options for `mode`, defaults filled in; `config` may be absent altogether. */
+export declare function resolveRuntime(config: JourneyRuntimeConfig | undefined, mode: JourneyMode): Required<JourneyRuntimeOptions>;
+//#endregion
+//# sourceMappingURL=runtime.d.cts.map

package/dist/runtime.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.cts","names":[],"sources":["../src/runtime.ts"],"mappings":";;;;;;;;;;;iBAWiB;;;;;;;EAOf;;EAEA;;;YAIU;;YAGA,uBAAuB,QAAQ,OAAO,aAAa;;wBAK/C,eACd,QAAQ,kCACR,MAAM,cACL,SAAS"}

package/dist/runtime.d.mts

@@ -0,0 +1,30 @@
+//#region src/runtime.d.ts
+/**
+ * Runtime options — how the engine should behave in a given environment, as
+ * typed configuration rather than loose environment variables. A project keeps
+ * one `JourneyRuntimeConfig` (typically in its `workflow.config.ts`, next to the
+ * studio settings) with one entry per mode; the host resolves the entry for
+ * the environment it is running in and hands it to the runner.
+ *
+ * The only thing that should come from the environment is the mode itself —
+ * which entry applies — never the values.
+ */
+export interface JourneyRuntimeOptions {
+  /**
+   * Fast-forward factor for every duration in a journey — delays, random
+   * delays, wait timeouts, goal and `performed(within)` windows scale
+   * together (see engine/time-scale.ts). 3600 turns "2 days" into 48 s.
+   * 1 (the default) is real time; anything else belongs to development only.
+   */
+  timeScale?: number;
+  /** Log every outbound message (channel, template, recipient, resolved props) as it is sent. */
+  logMessages?: boolean;
+}
+/** Environments a project distinguishes; any string works, these two are the conventional ones. */
+export type JourneyMode = 'development' | 'production' | (string & {});
+/** One options entry per mode. Missing modes run with the defaults (real time, quiet). */
+export type JourneyRuntimeConfig = Partial<Record<JourneyMode, JourneyRuntimeOptions>>;
+/** The options for `mode`, defaults filled in; `config` may be absent altogether. */
+export declare function resolveRuntime(config: JourneyRuntimeConfig | undefined, mode: JourneyMode): Required<JourneyRuntimeOptions>;
+//#endregion
+//# sourceMappingURL=runtime.d.mts.map

package/dist/runtime.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.mts","names":[],"sources":["../src/runtime.ts"],"mappings":";;;;;;;;;;;iBAWiB;;;;;;;EAOf;;EAEA;;;YAIU;;YAGA,uBAAuB,QAAQ,OAAO,aAAa;;wBAK/C,eACd,QAAQ,kCACR,MAAM,cACL,SAAS"}

package/dist/runtime.mjs

@@ -0,0 +1,18 @@
+//#region src/runtime.ts
+const DEFAULTS = {
+	timeScale: 1,
+	logMessages: false
+};
+/** The options for `mode`, defaults filled in; `config` may be absent altogether. */
+function resolveRuntime(config, mode) {
+	const entry = config?.[mode] ?? {};
+	const timeScale = entry.timeScale ?? DEFAULTS.timeScale;
+	return {
+		timeScale: Number.isFinite(timeScale) && timeScale > 0 ? timeScale : DEFAULTS.timeScale,
+		logMessages: entry.logMessages ?? DEFAULTS.logMessages
+	};
+}
+//#endregion
+export { resolveRuntime };
+
+//# sourceMappingURL=runtime.mjs.map

package/dist/runtime.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.mjs","names":[],"sources":["../src/runtime.ts"],"sourcesContent":["/**\n * Runtime options — how the engine should behave in a given environment, as\n * typed configuration rather than loose environment variables. A project keeps\n * one `JourneyRuntimeConfig` (typically in its `workflow.config.ts`, next to the\n * studio settings) with one entry per mode; the host resolves the entry for\n * the environment it is running in and hands it to the runner.\n *\n * The only thing that should come from the environment is the mode itself —\n * which entry applies — never the values.\n */\n\nexport interface JourneyRuntimeOptions {\n  /**\n   * Fast-forward factor for every duration in a journey — delays, random\n   * delays, wait timeouts, goal and `performed(within)` windows scale\n   * together (see engine/time-scale.ts). 3600 turns \"2 days\" into 48 s.\n   * 1 (the default) is real time; anything else belongs to development only.\n   */\n  timeScale?: number;\n  /** Log every outbound message (channel, template, recipient, resolved props) as it is sent. */\n  logMessages?: boolean;\n}\n\n/** Environments a project distinguishes; any string works, these two are the conventional ones. */\nexport type JourneyMode = 'development' | 'production' | (string & {});\n\n/** One options entry per mode. Missing modes run with the defaults (real time, quiet). */\nexport type JourneyRuntimeConfig = Partial<Record<JourneyMode, JourneyRuntimeOptions>>;\n\nconst DEFAULTS: Required<JourneyRuntimeOptions> = { timeScale: 1, logMessages: false };\n\n/** The options for `mode`, defaults filled in; `config` may be absent altogether. */\nexport function resolveRuntime(\n  config: JourneyRuntimeConfig | undefined,\n  mode: JourneyMode\n): Required<JourneyRuntimeOptions> {\n  const entry = config?.[mode] ?? {};\n  const timeScale = entry.timeScale ?? DEFAULTS.timeScale;\n  return {\n    timeScale: Number.isFinite(timeScale) && timeScale > 0 ? timeScale : DEFAULTS.timeScale,\n    logMessages: entry.logMessages ?? DEFAULTS.logMessages,\n  };\n}\n"],"mappings":";AA6BA,MAAM,WAA4C;CAAE,WAAW;CAAG,aAAa;AAAM;;AAGrF,SAAgB,eACd,QACA,MACiC;CACjC,MAAM,QAAQ,SAAS,SAAS,CAAC;CACjC,MAAM,YAAY,MAAM,aAAa,SAAS;CAC9C,OAAO;EACL,WAAW,OAAO,SAAS,SAAS,KAAK,YAAY,IAAI,YAAY,SAAS;EAC9E,aAAa,MAAM,eAAe,SAAS;CAC7C;AACF"}