better-ship 0.43.0 → 0.45.0

package/dist/posthog/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","names":[],"sources":["../../src/infrastructure/posthog/server.ts"],"mappings":";;;;;;iBAiBiB;WACN;WACA;WACA;WACA,YAAY,SAAS;WACrB,UAAU,KACjB;aAGS,UAAU,KAAK,YAAY;;;;qBAK3B,mCAAmC;;WAMnC,SAAS;mBACD;;WALV,SAAS;UAEX;;SASA,OAAO,QAAQ,yBAAyB;;EAqB/C,SAAS,oBAAoB,aAAa;;EAO1C,MAAM,oBAAoB;;EAK1B,MACE,cACA,YAAY,mCACZ,QAAQ;;EAMV,eACE,cACA,YAAY,mCACZ,QAAQ;UAKF"}
+{"version":3,"file":"server.d.ts","names":[],"sources":["../../src/infrastructure/posthog/server.ts"],"mappings":";;;;;;iBAkBiB;WACN;WACA;WACA;WACA,YAAY,SAAS;WACrB,UAAU,KACjB;aAGS,UAAU,KAAK,YAAY;;;;qBAK3B,mCAAmC;;WAMnC,SAAS;mBACD;;WALV,SAAS;UAEX;;SASA,OAAO,QAAQ,yBAAyB;;EAqB/C,SAAS,oBAAoB,aAAa;;EAO1C,MAAM,oBAAoB;;EAK1B,MACE,cACA,YAAY,mCACZ,QAAQ;;EAMV,eACE,cACA,YAAY,mCACZ,QAAQ;UAKF"}

package/dist/posthog/server.js

@@ -1,5 +1,6 @@
 import { nt as MissingConfigurationError } from "../core-CGj1ukXV.js";
 import { t as PostHogMetricsService } from "../metrics-CWv37yf9.js";
+import { t as currentPostHogSession } from "../request-session-Qe_Q_u9G.js";
 import { v5, validate } from "uuid";
 import { PostHog } from "posthog-node";
 
@@ -60,7 +61,11 @@ var PostHogAnalyticsService = class PostHogAnalyticsService {
 		this.capture(name, properties, target, "anonymous");
 	}
 	capture(name, eventProperties, target, profile) {
-		const properties = { ...eventProperties };
+		const sessionId = currentPostHogSession();
+		const properties = sessionId ? {
+			$session_id: sessionId,
+			...eventProperties
+		} : { ...eventProperties };
 		const payload = {
 			distinctId: target.distinctId,
 			event: name,

package/dist/posthog/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","names":["isUuid","uuidv5"],"sources":["../../src/infrastructure/posthog/server.ts"],"sourcesContent":["import { PostHog, type PostHogOptions } from 'posthog-node'\nimport { validate as isUuid, v5 as uuidv5 } from 'uuid'\n\nimport type { AnalyticsService } from '@/application'\nimport {\n  MissingConfigurationError,\n  type AnalyticsEventInput,\n  type AnalyticsProperties,\n  type AnalyticsTarget,\n} from '@/core'\n\nimport { PostHogMetricsService } from './metrics.ts'\n\n// Fixed forever: changing it changes every derived UUID, so PostHog would keep a repeat.\nconst EVENT_ID_NAMESPACE = '53d7af30-65cb-4176-b2c9-f1ed42367ab1'\n\n/** Deployment values and SDK options; the runtime owns delivery promises. */\nexport interface PostHogAnalyticsConfig {\n  readonly apiKey: string\n  readonly environment: string\n  readonly source: string\n  readonly waitUntil: (promise: Promise<unknown>) => void\n  readonly options?: Omit<\n    PostHogOptions,\n    'waitUntil' | 'flushAt' | 'flushInterval' | 'metrics' | 'disabled'\n  > & {\n    readonly metrics?: Omit<NonNullable<PostHogOptions['metrics']>, 'serviceName' | 'environment'>\n  }\n}\n\n/** Worker analytics ported from Typist; disabled applications select Porte's NULL_ANALYTICS instead. */\nexport class PostHogAnalyticsService implements AnalyticsService {\n  /** Metrics share this service's SDK client and delivery lifetime. */\n  readonly metrics: PostHogMetricsService\n\n  private constructor(\n    /** Raw SDK access for integrations such as PostHog AI tracing. */\n    readonly posthog: PostHog,\n    private readonly waitUntil: (promise: Promise<unknown>) => void,\n  ) {\n    this.metrics = new PostHogMetricsService(posthog, waitUntil)\n  }\n\n  /** Construct once per Worker invocation; a blank key throws MissingConfigurationError. */\n  static create(config: PostHogAnalyticsConfig): PostHogAnalyticsService {\n    const apiKey = config.apiKey.trim()\n    if (apiKey.length === 0) throw new MissingConfigurationError('POSTHOG_API_KEY')\n    const client = new PostHog(apiKey, {\n      host: 'https://us.i.posthog.com',\n      ...config.options,\n      flushAt: 1,\n      flushInterval: 0,\n      waitUntil: config.waitUntil,\n      metrics: {\n        ...config.options?.metrics,\n        environment: config.environment,\n        serviceName: config.source,\n      },\n    })\n    // The SDK applies in-memory super properties synchronously before this promise resolves.\n    void client.register({ environment: config.environment, source: config.source })\n    return new PostHogAnalyticsService(client, config.waitUntil)\n  }\n\n  /** Schedule person properties; the SDK's waitUntil option protects queued delivery. */\n  identify(distinctId: string, properties?: AnalyticsProperties): void {\n    const payload: Parameters<PostHog['identify']>[0] = { distinctId }\n    if (properties !== undefined) payload.properties = properties\n    this.posthog.identify(payload)\n  }\n\n  /** Schedule an irreversible person merge; only alias IDs the application proves belong to one person. */\n  alias(distinctId: string, previousDistinctId: string): void {\n    this.waitUntil(this.posthog.aliasImmediate({ distinctId, alias: previousDistinctId }))\n  }\n\n  /** Schedule an event; without an event ID the SDK sets a new UUID and the capture time. */\n  track(\n    name: string,\n    properties: AnalyticsEventInput['properties'],\n    target: AnalyticsTarget,\n  ): void {\n    this.capture(name, properties, target, 'person')\n  }\n\n  /** Schedule an event without creating a person profile for an attempt or resource ID. */\n  trackAnonymous(\n    name: string,\n    properties: AnalyticsEventInput['properties'],\n    target: AnalyticsTarget,\n  ): void {\n    this.capture(name, properties, target, 'anonymous')\n  }\n\n  private capture(\n    name: string,\n    eventProperties: AnalyticsEventInput['properties'],\n    target: AnalyticsTarget,\n    profile: 'person' | 'anonymous',\n  ): void {\n    const properties = { ...eventProperties }\n    const payload: Parameters<PostHog['captureImmediate']>[0] = {\n      distinctId: target.distinctId,\n      event: name,\n      properties,\n    }\n    if (profile === 'anonymous')\n      payload.properties = { ...properties, $process_person_profile: false }\n    if (target.eventId !== undefined) {\n      // PostHog drops a repeat only when its uuid and timestamp match the first event.\n      payload.uuid = isUuid(target.eventId)\n        ? target.eventId\n        : uuidv5(target.eventId, EVENT_ID_NAMESPACE)\n      payload.timestamp = new Date(target.occurredAt)\n    }\n    this.waitUntil(this.posthog.captureImmediate(payload))\n  }\n}\n"],"mappings":";;;;;;AAcA,MAAM,qBAAqB;;AAiB3B,IAAa,0BAAb,MAAa,wBAAoD;CAMpD;CACQ;;CALnB,AAAS;CAET,AAAQ,YAEN,AAAS,SACT,AAAiB,WACjB;EAFS;EACQ;EAEjB,KAAK,UAAU,IAAI,sBAAsB,SAAS,SAAS;CAC7D;;CAGA,OAAO,OAAO,QAAyD;EACrE,MAAM,SAAS,OAAO,OAAO,KAAK;EAClC,IAAI,OAAO,WAAW,GAAG,MAAM,IAAI,0BAA0B,iBAAiB;EAC9E,MAAM,SAAS,IAAI,QAAQ,QAAQ;GACjC,MAAM;GACN,GAAG,OAAO;GACV,SAAS;GACT,eAAe;GACf,WAAW,OAAO;GAClB,SAAS;IACP,GAAG,OAAO,SAAS;IACnB,aAAa,OAAO;IACpB,aAAa,OAAO;GACtB;EACF,CAAC;EAED,AAAK,OAAO,SAAS;GAAE,aAAa,OAAO;GAAa,QAAQ,OAAO;EAAO,CAAC;EAC/E,OAAO,IAAI,wBAAwB,QAAQ,OAAO,SAAS;CAC7D;;CAGA,SAAS,YAAoB,YAAwC;EACnE,MAAM,UAA8C,EAAE,WAAW;EACjE,IAAI,eAAe,QAAW,QAAQ,aAAa;EACnD,KAAK,QAAQ,SAAS,OAAO;CAC/B;;CAGA,MAAM,YAAoB,oBAAkC;EAC1D,KAAK,UAAU,KAAK,QAAQ,eAAe;GAAE;GAAY,OAAO;EAAmB,CAAC,CAAC;CACvF;;CAGA,MACE,MACA,YACA,QACM;EACN,KAAK,QAAQ,MAAM,YAAY,QAAQ,QAAQ;CACjD;;CAGA,eACE,MACA,YACA,QACM;EACN,KAAK,QAAQ,MAAM,YAAY,QAAQ,WAAW;CACpD;CAEA,AAAQ,QACN,MACA,iBACA,QACA,SACM;EACN,MAAM,aAAa,EAAE,GAAG,gBAAgB;EACxC,MAAM,UAAsD;GAC1D,YAAY,OAAO;GACnB,OAAO;GACP;EACF;EACA,IAAI,YAAY,aACd,QAAQ,aAAa;GAAE,GAAG;GAAY,yBAAyB;EAAM;EACvE,IAAI,OAAO,YAAY,QAAW;GAEhC,QAAQ,OAAOA,SAAO,OAAO,OAAO,IAChC,OAAO,UACPC,GAAO,OAAO,SAAS,kBAAkB;GAC7C,QAAQ,YAAY,IAAI,KAAK,OAAO,UAAU;EAChD;EACA,KAAK,UAAU,KAAK,QAAQ,iBAAiB,OAAO,CAAC;CACvD;AACF"}
+{"version":3,"file":"server.js","names":["isUuid","uuidv5"],"sources":["../../src/infrastructure/posthog/server.ts"],"sourcesContent":["import { PostHog, type PostHogOptions } from 'posthog-node'\nimport { validate as isUuid, v5 as uuidv5 } from 'uuid'\n\nimport type { AnalyticsService } from '@/application'\nimport {\n  MissingConfigurationError,\n  type AnalyticsEventInput,\n  type AnalyticsProperties,\n  type AnalyticsTarget,\n} from '@/core'\n\nimport { PostHogMetricsService } from './metrics.ts'\nimport { currentPostHogSession } from './request-session.ts'\n\n// Fixed forever: changing it changes every derived UUID, so PostHog would keep a repeat.\nconst EVENT_ID_NAMESPACE = '53d7af30-65cb-4176-b2c9-f1ed42367ab1'\n\n/** Deployment values and SDK options; the runtime owns delivery promises. */\nexport interface PostHogAnalyticsConfig {\n  readonly apiKey: string\n  readonly environment: string\n  readonly source: string\n  readonly waitUntil: (promise: Promise<unknown>) => void\n  readonly options?: Omit<\n    PostHogOptions,\n    'waitUntil' | 'flushAt' | 'flushInterval' | 'metrics' | 'disabled'\n  > & {\n    readonly metrics?: Omit<NonNullable<PostHogOptions['metrics']>, 'serviceName' | 'environment'>\n  }\n}\n\n/** Worker analytics ported from Typist; disabled applications select Porte's NULL_ANALYTICS instead. */\nexport class PostHogAnalyticsService implements AnalyticsService {\n  /** Metrics share this service's SDK client and delivery lifetime. */\n  readonly metrics: PostHogMetricsService\n\n  private constructor(\n    /** Raw SDK access for integrations such as PostHog AI tracing. */\n    readonly posthog: PostHog,\n    private readonly waitUntil: (promise: Promise<unknown>) => void,\n  ) {\n    this.metrics = new PostHogMetricsService(posthog, waitUntil)\n  }\n\n  /** Construct once per Worker invocation; a blank key throws MissingConfigurationError. */\n  static create(config: PostHogAnalyticsConfig): PostHogAnalyticsService {\n    const apiKey = config.apiKey.trim()\n    if (apiKey.length === 0) throw new MissingConfigurationError('POSTHOG_API_KEY')\n    const client = new PostHog(apiKey, {\n      host: 'https://us.i.posthog.com',\n      ...config.options,\n      flushAt: 1,\n      flushInterval: 0,\n      waitUntil: config.waitUntil,\n      metrics: {\n        ...config.options?.metrics,\n        environment: config.environment,\n        serviceName: config.source,\n      },\n    })\n    // The SDK applies in-memory super properties synchronously before this promise resolves.\n    void client.register({ environment: config.environment, source: config.source })\n    return new PostHogAnalyticsService(client, config.waitUntil)\n  }\n\n  /** Schedule person properties; the SDK's waitUntil option protects queued delivery. */\n  identify(distinctId: string, properties?: AnalyticsProperties): void {\n    const payload: Parameters<PostHog['identify']>[0] = { distinctId }\n    if (properties !== undefined) payload.properties = properties\n    this.posthog.identify(payload)\n  }\n\n  /** Schedule an irreversible person merge; only alias IDs the application proves belong to one person. */\n  alias(distinctId: string, previousDistinctId: string): void {\n    this.waitUntil(this.posthog.aliasImmediate({ distinctId, alias: previousDistinctId }))\n  }\n\n  /** Schedule an event; without an event ID the SDK sets a new UUID and the capture time. */\n  track(\n    name: string,\n    properties: AnalyticsEventInput['properties'],\n    target: AnalyticsTarget,\n  ): void {\n    this.capture(name, properties, target, 'person')\n  }\n\n  /** Schedule an event without creating a person profile for an attempt or resource ID. */\n  trackAnonymous(\n    name: string,\n    properties: AnalyticsEventInput['properties'],\n    target: AnalyticsTarget,\n  ): void {\n    this.capture(name, properties, target, 'anonymous')\n  }\n\n  private capture(\n    name: string,\n    eventProperties: AnalyticsEventInput['properties'],\n    target: AnalyticsTarget,\n    profile: 'person' | 'anonymous',\n  ): void {\n    const sessionId = currentPostHogSession()\n    // An application's own `$session_id` wins over the request's.\n    const properties = sessionId\n      ? { $session_id: sessionId, ...eventProperties }\n      : { ...eventProperties }\n    const payload: Parameters<PostHog['captureImmediate']>[0] = {\n      distinctId: target.distinctId,\n      event: name,\n      properties,\n    }\n    if (profile === 'anonymous')\n      payload.properties = { ...properties, $process_person_profile: false }\n    if (target.eventId !== undefined) {\n      // PostHog drops a repeat only when its uuid and timestamp match the first event.\n      payload.uuid = isUuid(target.eventId)\n        ? target.eventId\n        : uuidv5(target.eventId, EVENT_ID_NAMESPACE)\n      payload.timestamp = new Date(target.occurredAt)\n    }\n    this.waitUntil(this.posthog.captureImmediate(payload))\n  }\n}\n"],"mappings":";;;;;;;AAeA,MAAM,qBAAqB;;AAiB3B,IAAa,0BAAb,MAAa,wBAAoD;CAMpD;CACQ;;CALnB,AAAS;CAET,AAAQ,YAEN,AAAS,SACT,AAAiB,WACjB;EAFS;EACQ;EAEjB,KAAK,UAAU,IAAI,sBAAsB,SAAS,SAAS;CAC7D;;CAGA,OAAO,OAAO,QAAyD;EACrE,MAAM,SAAS,OAAO,OAAO,KAAK;EAClC,IAAI,OAAO,WAAW,GAAG,MAAM,IAAI,0BAA0B,iBAAiB;EAC9E,MAAM,SAAS,IAAI,QAAQ,QAAQ;GACjC,MAAM;GACN,GAAG,OAAO;GACV,SAAS;GACT,eAAe;GACf,WAAW,OAAO;GAClB,SAAS;IACP,GAAG,OAAO,SAAS;IACnB,aAAa,OAAO;IACpB,aAAa,OAAO;GACtB;EACF,CAAC;EAED,AAAK,OAAO,SAAS;GAAE,aAAa,OAAO;GAAa,QAAQ,OAAO;EAAO,CAAC;EAC/E,OAAO,IAAI,wBAAwB,QAAQ,OAAO,SAAS;CAC7D;;CAGA,SAAS,YAAoB,YAAwC;EACnE,MAAM,UAA8C,EAAE,WAAW;EACjE,IAAI,eAAe,QAAW,QAAQ,aAAa;EACnD,KAAK,QAAQ,SAAS,OAAO;CAC/B;;CAGA,MAAM,YAAoB,oBAAkC;EAC1D,KAAK,UAAU,KAAK,QAAQ,eAAe;GAAE;GAAY,OAAO;EAAmB,CAAC,CAAC;CACvF;;CAGA,MACE,MACA,YACA,QACM;EACN,KAAK,QAAQ,MAAM,YAAY,QAAQ,QAAQ;CACjD;;CAGA,eACE,MACA,YACA,QACM;EACN,KAAK,QAAQ,MAAM,YAAY,QAAQ,WAAW;CACpD;CAEA,AAAQ,QACN,MACA,iBACA,QACA,SACM;EACN,MAAM,YAAY,sBAAsB;EAExC,MAAM,aAAa,YACf;GAAE,aAAa;GAAW,GAAG;EAAgB,IAC7C,EAAE,GAAG,gBAAgB;EACzB,MAAM,UAAsD;GAC1D,YAAY,OAAO;GACnB,OAAO;GACP;EACF;EACA,IAAI,YAAY,aACd,QAAQ,aAAa;GAAE,GAAG;GAAY,yBAAyB;EAAM;EACvE,IAAI,OAAO,YAAY,QAAW;GAEhC,QAAQ,OAAOA,SAAO,OAAO,OAAO,IAChC,OAAO,UACPC,GAAO,OAAO,SAAS,kBAAkB;GAC7C,QAAQ,YAAY,IAAI,KAAK,OAAO,UAAU;EAChD;EACA,KAAK,UAAU,KAAK,QAAQ,iBAAiB,OAAO,CAAC;CACvD;AACF"}

package/dist/posthog/tanstack.d.ts

@@ -0,0 +1,9 @@
+//#region src/infrastructure/posthog/tanstack.d.ts
+/**
+ * Link Worker events to the browser session that sent the request.
+ * Register it in `requestMiddleware`. Each `PostHogAnalyticsService` event in that request then
+ * gets `$session_id`. A request without the header, and queue, cron, and Workflow code, add nothing.
+ */
+export declare const posthogRequestMiddleware: import("@tanstack/react-start").RequestMiddlewareAfterServer<{}, undefined, undefined>;
+//#endregion
+//# sourceMappingURL=tanstack.d.ts.map

package/dist/posthog/tanstack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tanstack.d.ts","names":[],"sources":["../../src/infrastructure/posthog/tanstack.ts"],"mappings":";;;;;;qBAUa,0DAAwB"}

package/dist/posthog/tanstack.js

@@ -0,0 +1,19 @@
+import { createMiddleware } from "@tanstack/react-start";
+
+//#region src/infrastructure/posthog/tanstack.ts
+const SESSION_HEADER = "x-posthog-session-id";
+/**
+* Link Worker events to the browser session that sent the request.
+* Register it in `requestMiddleware`. Each `PostHogAnalyticsService` event in that request then
+* gets `$session_id`. A request without the header, and queue, cron, and Workflow code, add nothing.
+*/
+const posthogRequestMiddleware = createMiddleware({ type: "request" }).server(async ({ request, next }) => {
+	const sessionId = request.headers.get(SESSION_HEADER)?.trim();
+	if (!sessionId) return next();
+	const { runWithPostHogSession } = await import("../request-session-D1r9ZvcS.js");
+	return runWithPostHogSession(sessionId, () => next());
+});
+
+//#endregion
+export { posthogRequestMiddleware };
+//# sourceMappingURL=tanstack.js.map

package/dist/posthog/tanstack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tanstack.js","names":[],"sources":["../../src/infrastructure/posthog/tanstack.ts"],"sourcesContent":["import { createMiddleware } from '@tanstack/react-start'\n\n// posthog-js sends this header when the browser sets `tracing_headers` for the application host.\nconst SESSION_HEADER = 'x-posthog-session-id'\n\n/**\n * Link Worker events to the browser session that sent the request.\n * Register it in `requestMiddleware`. Each `PostHogAnalyticsService` event in that request then\n * gets `$session_id`. A request without the header, and queue, cron, and Workflow code, add nothing.\n */\nexport const posthogRequestMiddleware = createMiddleware({ type: 'request' }).server(\n  async ({ request, next }) => {\n    const sessionId = request.headers.get(SESSION_HEADER)?.trim()\n    if (!sessionId) return next()\n    // The browser evaluates this module, so the Node async scope loads inside `.server()`.\n    const { runWithPostHogSession } = await import('./request-session.ts')\n    return runWithPostHogSession(sessionId, () => next())\n  },\n)\n"],"mappings":";;;AAGA,MAAM,iBAAiB;;;;;;AAOvB,MAAa,2BAA2B,iBAAiB,EAAE,MAAM,UAAU,CAAC,CAAC,CAAC,OAC5E,OAAO,EAAE,SAAS,WAAW;CAC3B,MAAM,YAAY,QAAQ,QAAQ,IAAI,cAAc,CAAC,EAAE,KAAK;CAC5D,IAAI,CAAC,WAAW,OAAO,KAAK;CAE5B,MAAM,EAAE,0BAA0B,MAAM,OAAO;CAC/C,OAAO,sBAAsB,iBAAiB,KAAK,CAAC;AACtD,CACF"}

package/dist/request-session-D1r9ZvcS.js

@@ -0,0 +1,3 @@
+import { n as runWithPostHogSession, t as currentPostHogSession } from "./request-session-Qe_Q_u9G.js";
+
+export { runWithPostHogSession };

package/dist/request-session-Qe_Q_u9G.js

@@ -0,0 +1,16 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+//#region src/infrastructure/posthog/request-session.ts
+const storage = new AsyncLocalStorage();
+/** Run the rest of one request with the browser's PostHog session ID. */
+function runWithPostHogSession(sessionId, work) {
+	return storage.run(sessionId, work);
+}
+/** The current request's PostHog session ID, or undefined outside such a request. */
+function currentPostHogSession() {
+	return storage.getStore();
+}
+
+//#endregion
+export { runWithPostHogSession as n, currentPostHogSession as t };
+//# sourceMappingURL=request-session-Qe_Q_u9G.js.map

package/dist/request-session-Qe_Q_u9G.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-session-Qe_Q_u9G.js","names":[],"sources":["../src/infrastructure/posthog/request-session.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks'\n\n// One async scope per request keeps each browser session ID apart from concurrent requests.\nconst storage = new AsyncLocalStorage<string>()\n\n/** Run the rest of one request with the browser's PostHog session ID. */\nexport function runWithPostHogSession<T>(sessionId: string, work: () => T): T {\n  return storage.run(sessionId, work)\n}\n\n/** The current request's PostHog session ID, or undefined outside such a request. */\nexport function currentPostHogSession(): string | undefined {\n  return storage.getStore()\n}\n"],"mappings":";;;AAGA,MAAM,UAAU,IAAI,kBAA0B;;AAG9C,SAAgB,sBAAyB,WAAmB,MAAkB;CAC5E,OAAO,QAAQ,IAAI,WAAW,IAAI;AACpC;;AAGA,SAAgB,wBAA4C;CAC1D,OAAO,QAAQ,SAAS;AAC1B"}

package/dist/stripe/event-map.d.ts

@@ -4,10 +4,12 @@ type EventObject<K extends Stripe.Event['type']> = Extract<Stripe.Event, {
   type: K;
 }>['data']['object'];
 /**
- * Convert verified Stripe events with callbacks typed to each event's object.
- * Unmapped events return undefined. Applications own validation and payment policy.
+ * Convert one verified Stripe event with callbacks typed to that event's object.
+ * An entry is one callback or an array of callbacks. Results stay in entry order.
+ * A callback returns `undefined` to ignore the event; the result omits it.
+ * An unmapped event returns `[]`. Applications own validation and payment policy.
  */
-export declare function stripeEventMap<T>(map: { [K in Stripe.Event['type']]?: (object: EventObject<K>) => T; }): (event: Stripe.Event) => T | undefined;
+export declare function stripeEventMap<T>(map: { [K in Stripe.Event['type']]?: ((object: EventObject<K>) => T | undefined) | readonly ((object: EventObject<K>) => T | undefined)[]; }): (event: Stripe.Event) => T[];
 /** Identify one Stripe event delivery; different events for one payment retain different IDs. */
 export declare function stripeEventId(event: Stripe.Event): string;
 //#endregion

package/dist/stripe/event-map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-map.d.ts","names":[],"sources":["../../src/infrastructure/stripe/event-map.ts"],"mappings":";;KAEK,YAAY,UAAU,OAAO,iBAAiB,QACjD,OAAO;EACL,MAAM;;;;;;wBAOM,eAAe,GAAG,QAC/B,KAAK,OAAO,kBAAkB,QAAQ,YAAY,OAAO,QACvD,OAAO,OAAO,UAAU;;wBASb,cAAc,OAAO,OAAO"}
+{"version":3,"file":"event-map.d.ts","names":[],"sources":["../../src/infrastructure/stripe/event-map.ts"],"mappings":";;KAEK,YAAY,UAAU,OAAO,iBAAiB,QACjD,OAAO;EACL,MAAM;;;;;;;;wBAWM,eAAe,GAAG,QAC/B,KAAK,OAAO,mBACP,QAAQ,YAAY,OAAO,4BAClB,QAAQ,YAAY,OAAO,uBACvC,OAAO,OAAO,UAAU;;wBAwBb,cAAc,OAAO,OAAO"}

package/dist/stripe/event-map.js

@@ -1,14 +1,24 @@
 //#region src/infrastructure/stripe/event-map.ts
 /**
-* Convert verified Stripe events with callbacks typed to each event's object.
-* Unmapped events return undefined. Applications own validation and payment policy.
+* Convert one verified Stripe event with callbacks typed to that event's object.
+* An entry is one callback or an array of callbacks. Results stay in entry order.
+* A callback returns `undefined` to ignore the event; the result omits it.
+* An unmapped event returns `[]`. Applications own validation and payment policy.
 */
 function stripeEventMap(map) {
 	const handlers = map;
 	return (event) => {
-		return handlers[event.type]?.(event.data.object);
+		const entry = handlers[event.type];
+		if (entry === void 0) return [];
+		return (isCallbackList(entry) ? entry : [entry]).flatMap((callback) => {
+			const result = callback(event.data.object);
+			return result === void 0 ? [] : [result];
+		});
 	};
 }
+function isCallbackList(entry) {
+	return Array.isArray(entry);
+}
 /** Identify one Stripe event delivery; different events for one payment retain different IDs. */
 function stripeEventId(event) {
 	return `stripe:event:${event.id}`;

package/dist/stripe/event-map.js.map

@@ -1 +1 @@
-{"version":3,"file":"event-map.js","names":[],"sources":["../../src/infrastructure/stripe/event-map.ts"],"sourcesContent":["import type Stripe from 'stripe'\n\ntype EventObject<K extends Stripe.Event['type']> = Extract<\n  Stripe.Event,\n  { type: K }\n>['data']['object']\n\n/**\n * Convert verified Stripe events with callbacks typed to each event's object.\n * Unmapped events return undefined. Applications own validation and payment policy.\n */\nexport function stripeEventMap<T>(map: {\n  [K in Stripe.Event['type']]?: (object: EventObject<K>) => T\n}): (event: Stripe.Event) => T | undefined {\n  const handlers: Partial<Record<Stripe.Event['type'], (object: never) => T>> = map\n  return (event) => {\n    // SAFETY: The map binds each event type to its object; indexed lookup loses that correlation.\n    return handlers[event.type]?.(event.data.object as never)\n  }\n}\n\n/** Identify one Stripe event delivery; different events for one payment retain different IDs. */\nexport function stripeEventId(event: Stripe.Event): string {\n  return `stripe:event:${event.id}`\n}\n"],"mappings":";;;;;AAWA,SAAgB,eAAkB,KAES;CACzC,MAAM,WAAwE;CAC9E,QAAQ,UAAU;EAEhB,OAAO,SAAS,MAAM,KAAK,GAAG,MAAM,KAAK,MAAe;CAC1D;AACF;;AAGA,SAAgB,cAAc,OAA6B;CACzD,OAAO,gBAAgB,MAAM;AAC/B"}
+{"version":3,"file":"event-map.js","names":[],"sources":["../../src/infrastructure/stripe/event-map.ts"],"sourcesContent":["import type Stripe from 'stripe'\n\ntype EventObject<K extends Stripe.Event['type']> = Extract<\n  Stripe.Event,\n  { type: K }\n>['data']['object']\n\ntype EventCallback<T> = (object: never) => T | undefined\n\n/**\n * Convert one verified Stripe event with callbacks typed to that event's object.\n * An entry is one callback or an array of callbacks. Results stay in entry order.\n * A callback returns `undefined` to ignore the event; the result omits it.\n * An unmapped event returns `[]`. Applications own validation and payment policy.\n */\nexport function stripeEventMap<T>(map: {\n  [K in Stripe.Event['type']]?:\n    | ((object: EventObject<K>) => T | undefined)\n    | readonly ((object: EventObject<K>) => T | undefined)[]\n}): (event: Stripe.Event) => T[] {\n  const handlers: Partial<\n    Record<Stripe.Event['type'], EventCallback<T> | readonly EventCallback<T>[]>\n  > = map\n  return (event) => {\n    const entry = handlers[event.type]\n    if (entry === undefined) return []\n    const callbacks = isCallbackList(entry) ? entry : [entry]\n    return callbacks.flatMap((callback) => {\n      // SAFETY: The map binds each event type to its object; indexed lookup loses that correlation.\n      const result = callback(event.data.object as never)\n      return result === undefined ? [] : [result]\n    })\n  }\n}\n\n// Array.isArray widens to any[], so the predicate restores the callback list type.\nfunction isCallbackList<T>(\n  entry: EventCallback<T> | readonly EventCallback<T>[],\n): entry is readonly EventCallback<T>[] {\n  return Array.isArray(entry)\n}\n\n/** Identify one Stripe event delivery; different events for one payment retain different IDs. */\nexport function stripeEventId(event: Stripe.Event): string {\n  return `stripe:event:${event.id}`\n}\n"],"mappings":";;;;;;;AAeA,SAAgB,eAAkB,KAID;CAC/B,MAAM,WAEF;CACJ,QAAQ,UAAU;EAChB,MAAM,QAAQ,SAAS,MAAM;EAC7B,IAAI,UAAU,QAAW,OAAO,CAAC;EAEjC,QADkB,eAAe,KAAK,IAAI,QAAQ,CAAC,KAAK,EACxC,CAAC,SAAS,aAAa;GAErC,MAAM,SAAS,SAAS,MAAM,KAAK,MAAe;GAClD,OAAO,WAAW,SAAY,CAAC,IAAI,CAAC,MAAM;EAC5C,CAAC;CACH;AACF;AAGA,SAAS,eACP,OACsC;CACtC,OAAO,MAAM,QAAQ,KAAK;AAC5B;;AAGA,SAAgB,cAAc,OAA6B;CACzD,OAAO,gBAAgB,MAAM;AAC/B"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "better-ship",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "description": "Foundation for applications on Cloudflare Workers: logger, errors, message bus, infrastructure adapters, and UI primitives",
   "license": "Apache-2.0",
   "repository": {
@@ -52,6 +52,7 @@
     "./posthog/metrics": "./dist/posthog/metrics.js",
     "./posthog/proxy": "./dist/posthog/proxy.js",
     "./posthog/server": "./dist/posthog/server.js",
+    "./posthog/tanstack": "./dist/posthog/tanstack.js",
     "./resend": "./dist/resend.js",
     "./sentry/client": "./dist/sentry/client.js",
     "./sentry/server": "./dist/sentry/server.js",

package/src/infrastructure/posthog/request-session.ts

@@ -0,0 +1,14 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
+
+// One async scope per request keeps each browser session ID apart from concurrent requests.
+const storage = new AsyncLocalStorage<string>()
+
+/** Run the rest of one request with the browser's PostHog session ID. */
+export function runWithPostHogSession<T>(sessionId: string, work: () => T): T {
+  return storage.run(sessionId, work)
+}
+
+/** The current request's PostHog session ID, or undefined outside such a request. */
+export function currentPostHogSession(): string | undefined {
+  return storage.getStore()
+}

package/src/infrastructure/posthog/server.ts

@@ -10,6 +10,7 @@ import {
 } from '@/core'
 
 import { PostHogMetricsService } from './metrics.ts'
+import { currentPostHogSession } from './request-session.ts'
 
 // Fixed forever: changing it changes every derived UUID, so PostHog would keep a repeat.
 const EVENT_ID_NAMESPACE = '53d7af30-65cb-4176-b2c9-f1ed42367ab1'
@@ -98,7 +99,11 @@ export class PostHogAnalyticsService implements AnalyticsService {
     target: AnalyticsTarget,
     profile: 'person' | 'anonymous',
   ): void {
-    const properties = { ...eventProperties }
+    const sessionId = currentPostHogSession()
+    // An application's own `$session_id` wins over the request's.
+    const properties = sessionId
+      ? { $session_id: sessionId, ...eventProperties }
+      : { ...eventProperties }
     const payload: Parameters<PostHog['captureImmediate']>[0] = {
       distinctId: target.distinctId,
       event: name,

package/src/infrastructure/posthog/tanstack.ts

@@ -0,0 +1,19 @@
+import { createMiddleware } from '@tanstack/react-start'
+
+// posthog-js sends this header when the browser sets `tracing_headers` for the application host.
+const SESSION_HEADER = 'x-posthog-session-id'
+
+/**
+ * Link Worker events to the browser session that sent the request.
+ * Register it in `requestMiddleware`. Each `PostHogAnalyticsService` event in that request then
+ * gets `$session_id`. A request without the header, and queue, cron, and Workflow code, add nothing.
+ */
+export const posthogRequestMiddleware = createMiddleware({ type: 'request' }).server(
+  async ({ request, next }) => {
+    const sessionId = request.headers.get(SESSION_HEADER)?.trim()
+    if (!sessionId) return next()
+    // The browser evaluates this module, so the Node async scope loads inside `.server()`.
+    const { runWithPostHogSession } = await import('./request-session.ts')
+    return runWithPostHogSession(sessionId, () => next())
+  },
+)

package/src/infrastructure/stripe/event-map.ts

@@ -5,20 +5,41 @@ type EventObject<K extends Stripe.Event['type']> = Extract<
   { type: K }
 >['data']['object']
 
+type EventCallback<T> = (object: never) => T | undefined
+
 /**
- * Convert verified Stripe events with callbacks typed to each event's object.
- * Unmapped events return undefined. Applications own validation and payment policy.
+ * Convert one verified Stripe event with callbacks typed to that event's object.
+ * An entry is one callback or an array of callbacks. Results stay in entry order.
+ * A callback returns `undefined` to ignore the event; the result omits it.
+ * An unmapped event returns `[]`. Applications own validation and payment policy.
  */
 export function stripeEventMap<T>(map: {
-  [K in Stripe.Event['type']]?: (object: EventObject<K>) => T
-}): (event: Stripe.Event) => T | undefined {
-  const handlers: Partial<Record<Stripe.Event['type'], (object: never) => T>> = map
+  [K in Stripe.Event['type']]?:
+    | ((object: EventObject<K>) => T | undefined)
+    | readonly ((object: EventObject<K>) => T | undefined)[]
+}): (event: Stripe.Event) => T[] {
+  const handlers: Partial<
+    Record<Stripe.Event['type'], EventCallback<T> | readonly EventCallback<T>[]>
+  > = map
   return (event) => {
-    // SAFETY: The map binds each event type to its object; indexed lookup loses that correlation.
-    return handlers[event.type]?.(event.data.object as never)
+    const entry = handlers[event.type]
+    if (entry === undefined) return []
+    const callbacks = isCallbackList(entry) ? entry : [entry]
+    return callbacks.flatMap((callback) => {
+      // SAFETY: The map binds each event type to its object; indexed lookup loses that correlation.
+      const result = callback(event.data.object as never)
+      return result === undefined ? [] : [result]
+    })
   }
 }
 
+// Array.isArray widens to any[], so the predicate restores the callback list type.
+function isCallbackList<T>(
+  entry: EventCallback<T> | readonly EventCallback<T>[],
+): entry is readonly EventCallback<T>[] {
+  return Array.isArray(entry)
+}
+
 /** Identify one Stripe event delivery; different events for one payment retain different IDs. */
 export function stripeEventId(event: Stripe.Event): string {
   return `stripe:event:${event.id}`