@contractspec/lib.analytics 1.57.0 → 1.59.0

package/dist/lifecycle/posthog-metric-source.d.ts

@@ -1,47 +1,43 @@
-import { LifecycleMetricSource } from "./metric-collectors.js";
-import { AnalyticsReader } from "@contractspec/lib.contracts/integrations/providers/analytics";
-
-//#region src/lifecycle/posthog-metric-source.d.ts
-interface PosthogLifecycleMetricSourceOptions {
-  activityEvents?: string[];
-  retentionWindowDays?: number;
-  revenueEvent?: string;
-  revenueProperty?: string;
-  customerEvent?: string;
-  customerProperty?: string;
-  teamSizeEvent?: string;
-  teamSizeProperty?: string;
-  burnMultipleEvent?: string;
-  burnMultipleProperty?: string;
+import type { AnalyticsReader } from '@contractspec/lib.contracts/integrations/providers/analytics';
+import type { LifecycleMetricSource } from './metric-collectors';
+export interface PosthogLifecycleMetricSourceOptions {
+    activityEvents?: string[];
+    retentionWindowDays?: number;
+    revenueEvent?: string;
+    revenueProperty?: string;
+    customerEvent?: string;
+    customerProperty?: string;
+    teamSizeEvent?: string;
+    teamSizeProperty?: string;
+    burnMultipleEvent?: string;
+    burnMultipleProperty?: string;
 }
-declare class PosthogLifecycleMetricSource implements LifecycleMetricSource {
-  private readonly reader;
-  private readonly activityEvents?;
-  private readonly retentionWindowDays;
-  private readonly revenueEvent?;
-  private readonly revenueProperty?;
-  private readonly customerEvent?;
-  private readonly customerProperty?;
-  private readonly teamSizeEvent?;
-  private readonly teamSizeProperty?;
-  private readonly burnMultipleEvent?;
-  private readonly burnMultipleProperty?;
-  constructor(reader: AnalyticsReader, options?: PosthogLifecycleMetricSourceOptions);
-  getActiveUsers(): Promise<number | undefined>;
-  getWeeklyActiveUsers(): Promise<number | undefined>;
-  getRetentionRate(): Promise<number | undefined>;
-  getMonthlyRecurringRevenue(): Promise<number | undefined>;
-  getCustomerCount(): Promise<number | undefined>;
-  getTeamSize(): Promise<number | undefined>;
-  getBurnMultiple(): Promise<number | undefined>;
-  private countDistinctUsers;
-  private countDistinctUsersBetween;
-  private countReturningUsers;
-  private sumMetric;
-  private countDistinctUsersByProperty;
-  private latestMetric;
-  private queryHogQL;
+export declare class PosthogLifecycleMetricSource implements LifecycleMetricSource {
+    private readonly reader;
+    private readonly activityEvents?;
+    private readonly retentionWindowDays;
+    private readonly revenueEvent?;
+    private readonly revenueProperty?;
+    private readonly customerEvent?;
+    private readonly customerProperty?;
+    private readonly teamSizeEvent?;
+    private readonly teamSizeProperty?;
+    private readonly burnMultipleEvent?;
+    private readonly burnMultipleProperty?;
+    constructor(reader: AnalyticsReader, options?: PosthogLifecycleMetricSourceOptions);
+    getActiveUsers(): Promise<number | undefined>;
+    getWeeklyActiveUsers(): Promise<number | undefined>;
+    getRetentionRate(): Promise<number | undefined>;
+    getMonthlyRecurringRevenue(): Promise<number | undefined>;
+    getCustomerCount(): Promise<number | undefined>;
+    getTeamSize(): Promise<number | undefined>;
+    getBurnMultiple(): Promise<number | undefined>;
+    private countDistinctUsers;
+    private countDistinctUsersBetween;
+    private countReturningUsers;
+    private sumMetric;
+    private countDistinctUsersByProperty;
+    private latestMetric;
+    private queryHogQL;
 }
-//#endregion
-export { PosthogLifecycleMetricSource, PosthogLifecycleMetricSourceOptions };
 //# sourceMappingURL=posthog-metric-source.d.ts.map

package/dist/lifecycle/posthog-metric-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"posthog-metric-source.d.ts","names":[],"sources":["../../src/lifecycle/posthog-metric-source.ts"],"mappings":";;;;UAMiB,mCAAA;EACf,cAAA;EACA,mBAAA;EACA,YAAA;EACA,eAAA;EACA,aAAA;EACA,gBAAA;EACA,aAAA;EACA,gBAAA;EACA,iBAAA;EACA,oBAAA;AAAA;AAAA,cAGW,4BAAA,YAAwC,qBAAA;EAAA,iBAClC,MAAA;EAAA,iBACA,cAAA;EAAA,iBACA,mBAAA;EAAA,iBACA,YAAA;EAAA,iBACA,eAAA;EAAA,iBACA,aAAA;EAAA,iBACA,gBAAA;EAAA,iBACA,aAAA;EAAA,iBACA,gBAAA;EAAA,iBACA,iBAAA;EAAA,iBACA,oBAAA;cAGf,MAAA,EAAQ,eAAA,EACR,OAAA,GAAS,mCAAA;EAeL,cAAA,CAAA,GAAkB,OAAA;EAIlB,oBAAA,CAAA,GAAwB,OAAA;EAIxB,gBAAA,CAAA,GAAoB,OAAA;EAkBpB,0BAAA,CAAA,GAA8B,OAAA;EAK9B,gBAAA,CAAA,GAAoB,OAAA;EAQpB,WAAA,CAAA,GAAe,OAAA;EAKf,eAAA,CAAA,GAAmB,OAAA;EAAA,QAKX,kBAAA;EAAA,QAKA,yBAAA;EAAA,QAwBA,mBAAA;EAAA,QA8BA,SAAA;EAAA,QAgBA,4BAAA;EAAA,QAiBA,YAAA;EAAA,QAkBA,UAAA;AAAA"}
+{"version":3,"file":"posthog-metric-source.d.ts","sourceRoot":"","sources":["../../src/lifecycle/posthog-metric-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,eAAe,EAChB,MAAM,8DAA8D,CAAC;AACtE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEjE,MAAM,WAAW,mCAAmC;IAClD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,qBAAa,4BAA6B,YAAW,qBAAqB;IACxE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAW;IAC3C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CAAS;gBAG7C,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,mCAAwC;IAe7C,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAI7C,oBAAoB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAInD,gBAAgB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAkB/C,0BAA0B,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAKzD,gBAAgB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAQ/C,WAAW,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAK1C,eAAe,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;YAKtC,kBAAkB;YAKlB,yBAAyB;YAwBzB,mBAAmB;YA8BnB,SAAS;YAgBT,4BAA4B;YAiB5B,YAAY;YAkBZ,UAAU;CASzB"}

package/dist/lifecycle/posthog-metric-source.js

@@ -1,186 +1,206 @@
-//#region src/lifecycle/posthog-metric-source.ts
-var PosthogLifecycleMetricSource = class {
-	reader;
-	activityEvents;
-	retentionWindowDays;
-	revenueEvent;
-	revenueProperty;
-	customerEvent;
-	customerProperty;
-	teamSizeEvent;
-	teamSizeProperty;
-	burnMultipleEvent;
-	burnMultipleProperty;
-	constructor(reader, options = {}) {
-		this.reader = reader;
-		this.activityEvents = options.activityEvents;
-		this.retentionWindowDays = options.retentionWindowDays ?? 7;
-		this.revenueEvent = options.revenueEvent;
-		this.revenueProperty = options.revenueProperty ?? "amount";
-		this.customerEvent = options.customerEvent;
-		this.customerProperty = options.customerProperty ?? "is_customer";
-		this.teamSizeEvent = options.teamSizeEvent;
-		this.teamSizeProperty = options.teamSizeProperty ?? "team_size";
-		this.burnMultipleEvent = options.burnMultipleEvent;
-		this.burnMultipleProperty = options.burnMultipleProperty ?? "burn_multiple";
-	}
-	async getActiveUsers() {
-		return this.countDistinctUsers(1);
-	}
-	async getWeeklyActiveUsers() {
-		return this.countDistinctUsers(7);
-	}
-	async getRetentionRate() {
-		const windowDays = this.retentionWindowDays;
-		const now = /* @__PURE__ */ new Date();
-		const prevEnd = /* @__PURE__ */ new Date(now.getTime() - windowDays * 24 * 60 * 60 * 1e3);
-		const prevStart = /* @__PURE__ */ new Date(now.getTime() - windowDays * 2 * 24 * 60 * 60 * 1e3);
-		const returningUsers = await this.countReturningUsers(prevStart, prevEnd, now);
-		const prevUsers = await this.countDistinctUsersBetween(prevStart, prevEnd);
-		if (prevUsers === void 0 || prevUsers === 0) return void 0;
-		return returningUsers / prevUsers;
-	}
-	async getMonthlyRecurringRevenue() {
-		if (!this.revenueEvent || !this.revenueProperty) return void 0;
-		return this.sumMetric(this.revenueEvent, this.revenueProperty);
-	}
-	async getCustomerCount() {
-		if (!this.customerEvent || !this.customerProperty) return void 0;
-		return this.countDistinctUsersByProperty(this.customerEvent, this.customerProperty);
-	}
-	async getTeamSize() {
-		if (!this.teamSizeEvent || !this.teamSizeProperty) return void 0;
-		return this.latestMetric(this.teamSizeEvent, this.teamSizeProperty);
-	}
-	async getBurnMultiple() {
-		if (!this.burnMultipleEvent || !this.burnMultipleProperty) return void 0;
-		return this.latestMetric(this.burnMultipleEvent, this.burnMultipleProperty);
-	}
-	async countDistinctUsers(days) {
-		const range = buildDateRange(days);
-		return this.countDistinctUsersBetween(range.from, range.to);
-	}
-	async countDistinctUsersBetween(from, to) {
-		const eventFilter = buildEventFilter(this.activityEvents, "activityEvent");
-		return readSingleNumber(await this.queryHogQL({
-			query: [
-				"select",
-				"  countDistinct(distinct_id) as total",
-				"from events",
-				`where timestamp >= {dateFrom} and timestamp < {dateTo}`,
-				eventFilter.clause ? `and ${eventFilter.clause}` : ""
-			].filter(Boolean).join("\n"),
-			values: {
-				dateFrom: from.toISOString(),
-				dateTo: to.toISOString(),
-				...eventFilter.values
-			}
-		}));
-	}
-	async countReturningUsers(previousStart, previousEnd, currentEnd) {
-		const eventFilter = buildEventFilter(this.activityEvents, "activityEvent");
-		return readSingleNumber(await this.queryHogQL({
-			query: [
-				"select",
-				"  countDistinct(distinct_id) as total",
-				"from events",
-				`where timestamp >= {currentFrom} and timestamp < {currentTo}`,
-				eventFilter.clause ? `and ${eventFilter.clause}` : "",
-				"and distinct_id in (",
-				"  select distinct_id from events",
-				"  where timestamp >= {previousFrom} and timestamp < {previousTo}",
-				eventFilter.clause ? `and ${eventFilter.clause}` : "",
-				")"
-			].join("\n"),
-			values: {
-				currentFrom: previousEnd.toISOString(),
-				currentTo: currentEnd.toISOString(),
-				previousFrom: previousStart.toISOString(),
-				previousTo: previousEnd.toISOString(),
-				...eventFilter.values
-			}
-		})) ?? 0;
-	}
-	async sumMetric(eventName, propertyKey) {
-		return readSingleNumber(await this.queryHogQL({
-			query: [
-				"select",
-				`  sum(properties.${propertyKey}) as total`,
-				"from events",
-				"where event = {eventName}"
-			].join("\n"),
-			values: { eventName }
-		}));
-	}
-	async countDistinctUsersByProperty(eventName, propertyKey) {
-		return readSingleNumber(await this.queryHogQL({
-			query: [
-				"select",
-				"  countDistinct(distinct_id) as total",
-				"from events",
-				"where event = {eventName}",
-				`and properties.${propertyKey} = {propertyValue}`
-			].join("\n"),
-			values: {
-				eventName,
-				propertyValue: true
-			}
-		}));
-	}
-	async latestMetric(eventName, propertyKey) {
-		return readSingleNumber(await this.queryHogQL({
-			query: [
-				"select",
-				`  properties.${propertyKey} as value`,
-				"from events",
-				"where event = {eventName}",
-				"order by timestamp desc",
-				"limit 1"
-			].join("\n"),
-			values: { eventName }
-		}));
-	}
-	async queryHogQL(input) {
-		if (!this.reader.queryHogQL) throw new Error("Analytics reader does not support HogQL queries.");
-		return this.reader.queryHogQL(input);
-	}
-};
+// @bun
+// src/lifecycle/posthog-metric-source.ts
+class PosthogLifecycleMetricSource {
+  reader;
+  activityEvents;
+  retentionWindowDays;
+  revenueEvent;
+  revenueProperty;
+  customerEvent;
+  customerProperty;
+  teamSizeEvent;
+  teamSizeProperty;
+  burnMultipleEvent;
+  burnMultipleProperty;
+  constructor(reader, options = {}) {
+    this.reader = reader;
+    this.activityEvents = options.activityEvents;
+    this.retentionWindowDays = options.retentionWindowDays ?? 7;
+    this.revenueEvent = options.revenueEvent;
+    this.revenueProperty = options.revenueProperty ?? "amount";
+    this.customerEvent = options.customerEvent;
+    this.customerProperty = options.customerProperty ?? "is_customer";
+    this.teamSizeEvent = options.teamSizeEvent;
+    this.teamSizeProperty = options.teamSizeProperty ?? "team_size";
+    this.burnMultipleEvent = options.burnMultipleEvent;
+    this.burnMultipleProperty = options.burnMultipleProperty ?? "burn_multiple";
+  }
+  async getActiveUsers() {
+    return this.countDistinctUsers(1);
+  }
+  async getWeeklyActiveUsers() {
+    return this.countDistinctUsers(7);
+  }
+  async getRetentionRate() {
+    const windowDays = this.retentionWindowDays;
+    const now = new Date;
+    const prevEnd = new Date(now.getTime() - windowDays * 24 * 60 * 60 * 1000);
+    const prevStart = new Date(now.getTime() - windowDays * 2 * 24 * 60 * 60 * 1000);
+    const returningUsers = await this.countReturningUsers(prevStart, prevEnd, now);
+    const prevUsers = await this.countDistinctUsersBetween(prevStart, prevEnd);
+    if (prevUsers === undefined || prevUsers === 0)
+      return;
+    return returningUsers / prevUsers;
+  }
+  async getMonthlyRecurringRevenue() {
+    if (!this.revenueEvent || !this.revenueProperty)
+      return;
+    return this.sumMetric(this.revenueEvent, this.revenueProperty);
+  }
+  async getCustomerCount() {
+    if (!this.customerEvent || !this.customerProperty)
+      return;
+    return this.countDistinctUsersByProperty(this.customerEvent, this.customerProperty);
+  }
+  async getTeamSize() {
+    if (!this.teamSizeEvent || !this.teamSizeProperty)
+      return;
+    return this.latestMetric(this.teamSizeEvent, this.teamSizeProperty);
+  }
+  async getBurnMultiple() {
+    if (!this.burnMultipleEvent || !this.burnMultipleProperty)
+      return;
+    return this.latestMetric(this.burnMultipleEvent, this.burnMultipleProperty);
+  }
+  async countDistinctUsers(days) {
+    const range = buildDateRange(days);
+    return this.countDistinctUsersBetween(range.from, range.to);
+  }
+  async countDistinctUsersBetween(from, to) {
+    const eventFilter = buildEventFilter(this.activityEvents, "activityEvent");
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        "  countDistinct(distinct_id) as total",
+        "from events",
+        `where timestamp >= {dateFrom} and timestamp < {dateTo}`,
+        eventFilter.clause ? `and ${eventFilter.clause}` : ""
+      ].filter(Boolean).join(`
+`),
+      values: {
+        dateFrom: from.toISOString(),
+        dateTo: to.toISOString(),
+        ...eventFilter.values
+      }
+    });
+    return readSingleNumber(result);
+  }
+  async countReturningUsers(previousStart, previousEnd, currentEnd) {
+    const eventFilter = buildEventFilter(this.activityEvents, "activityEvent");
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        "  countDistinct(distinct_id) as total",
+        "from events",
+        `where timestamp >= {currentFrom} and timestamp < {currentTo}`,
+        eventFilter.clause ? `and ${eventFilter.clause}` : "",
+        "and distinct_id in (",
+        "  select distinct_id from events",
+        "  where timestamp >= {previousFrom} and timestamp < {previousTo}",
+        eventFilter.clause ? `and ${eventFilter.clause}` : "",
+        ")"
+      ].join(`
+`),
+      values: {
+        currentFrom: previousEnd.toISOString(),
+        currentTo: currentEnd.toISOString(),
+        previousFrom: previousStart.toISOString(),
+        previousTo: previousEnd.toISOString(),
+        ...eventFilter.values
+      }
+    });
+    return readSingleNumber(result) ?? 0;
+  }
+  async sumMetric(eventName, propertyKey) {
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        `  sum(properties.${propertyKey}) as total`,
+        "from events",
+        "where event = {eventName}"
+      ].join(`
+`),
+      values: { eventName }
+    });
+    return readSingleNumber(result);
+  }
+  async countDistinctUsersByProperty(eventName, propertyKey) {
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        "  countDistinct(distinct_id) as total",
+        "from events",
+        "where event = {eventName}",
+        `and properties.${propertyKey} = {propertyValue}`
+      ].join(`
+`),
+      values: { eventName, propertyValue: true }
+    });
+    return readSingleNumber(result);
+  }
+  async latestMetric(eventName, propertyKey) {
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        `  properties.${propertyKey} as value`,
+        "from events",
+        "where event = {eventName}",
+        "order by timestamp desc",
+        "limit 1"
+      ].join(`
+`),
+      values: { eventName }
+    });
+    return readSingleNumber(result);
+  }
+  async queryHogQL(input) {
+    if (!this.reader.queryHogQL) {
+      throw new Error("Analytics reader does not support HogQL queries.");
+    }
+    return this.reader.queryHogQL(input);
+  }
+}
 function buildDateRange(days) {
-	const to = /* @__PURE__ */ new Date();
-	return {
-		from: /* @__PURE__ */ new Date(to.getTime() - days * 24 * 60 * 60 * 1e3),
-		to
-	};
+  const to = new Date;
+  const from = new Date(to.getTime() - days * 24 * 60 * 60 * 1000);
+  return { from, to };
 }
 function buildEventFilter(events, prefix) {
-	if (!events || events.length === 0) return {};
-	if (events.length === 1) return {
-		clause: `event = {${prefix}0}`,
-		values: { [`${prefix}0`]: events[0] }
-	};
-	const clauses = events.map((_event, index) => `event = {${prefix}${index}}`);
-	const values = {};
-	events.forEach((event, index) => {
-		values[`${prefix}${index}`] = event;
-	});
-	return {
-		clause: `(${clauses.join(" or ")})`,
-		values
-	};
+  if (!events || events.length === 0)
+    return {};
+  if (events.length === 1) {
+    return {
+      clause: `event = {${prefix}0}`,
+      values: { [`${prefix}0`]: events[0] }
+    };
+  }
+  const clauses = events.map((_event, index) => `event = {${prefix}${index}}`);
+  const values = {};
+  events.forEach((event, index) => {
+    values[`${prefix}${index}`] = event;
+  });
+  return {
+    clause: `(${clauses.join(" or ")})`,
+    values
+  };
 }
 function readSingleNumber(result) {
-	if (!Array.isArray(result.results) || result.results.length === 0) return;
-	const firstRow = result.results[0];
-	if (Array.isArray(firstRow) && firstRow.length > 0) {
-		const value = firstRow[0];
-		if (typeof value === "number" && Number.isFinite(value)) return value;
-		if (typeof value === "string" && value.trim()) {
-			const parsed = Number(value);
-			if (Number.isFinite(parsed)) return parsed;
-		}
-	}
+  if (!Array.isArray(result.results) || result.results.length === 0) {
+    return;
+  }
+  const firstRow = result.results[0];
+  if (Array.isArray(firstRow) && firstRow.length > 0) {
+    const value = firstRow[0];
+    if (typeof value === "number" && Number.isFinite(value))
+      return value;
+    if (typeof value === "string" && value.trim()) {
+      const parsed = Number(value);
+      if (Number.isFinite(parsed))
+        return parsed;
+    }
+  }
+  return;
 }
-
-//#endregion
-export { PosthogLifecycleMetricSource };
-//# sourceMappingURL=posthog-metric-source.js.map
+export {
+  PosthogLifecycleMetricSource
+};

package/dist/node/churn/index.js

@@ -0,0 +1,77 @@
+// src/churn/predictor.ts
+import dayjs from "dayjs";
+
+class ChurnPredictor {
+  recencyWeight;
+  frequencyWeight;
+  errorWeight;
+  decayDays;
+  constructor(options) {
+    this.recencyWeight = options?.recencyWeight ?? 0.5;
+    this.frequencyWeight = options?.frequencyWeight ?? 0.3;
+    this.errorWeight = options?.errorWeight ?? 0.2;
+    this.decayDays = options?.decayDays ?? 14;
+  }
+  score(events) {
+    const grouped = groupBy(events, (event) => event.userId);
+    const signals = [];
+    for (const [userId, userEvents] of grouped.entries()) {
+      const score = this.computeScore(userEvents);
+      signals.push({
+        userId,
+        score,
+        bucket: score >= 0.7 ? "high" : score >= 0.4 ? "medium" : "low",
+        drivers: this.drivers(userEvents)
+      });
+    }
+    return signals.sort((a, b) => b.score - a.score);
+  }
+  computeScore(events) {
+    if (!events.length)
+      return 0;
+    const sorted = events.sort((a, b) => dateMs(a) - dateMs(b));
+    const lastEvent = sorted[sorted.length - 1];
+    if (!lastEvent)
+      return 0;
+    const daysSinceLast = dayjs().diff(dayjs(lastEvent.timestamp), "day");
+    const recencyScore = Math.max(0, 1 - daysSinceLast / this.decayDays);
+    const windowStart = dayjs().subtract(this.decayDays, "day");
+    const recentEvents = sorted.filter((event) => dayjs(event.timestamp).isAfter(windowStart));
+    const averagePerDay = recentEvents.length / Math.max(this.decayDays, 1);
+    const frequencyScore = Math.min(1, averagePerDay * 5);
+    const errorEvents = recentEvents.filter((event) => typeof event.properties?.error !== "undefined" || /error|failed/i.test(event.name)).length;
+    const errorScore = Math.min(1, errorEvents / 3);
+    const score = recencyScore * this.recencyWeight + frequencyScore * this.frequencyWeight + (1 - errorScore) * this.errorWeight;
+    return Number(score.toFixed(3));
+  }
+  drivers(events) {
+    const drivers = [];
+    const sorted = events.sort((a, b) => dateMs(a) - dateMs(b));
+    const lastEvent = sorted[sorted.length - 1];
+    if (lastEvent) {
+      const days = dayjs().diff(dayjs(lastEvent.timestamp), "day");
+      if (days > this.decayDays)
+        drivers.push(`Inactive for ${days} days`);
+    }
+    const errorEvents = events.filter((event) => typeof event.properties?.error !== "undefined" || /error|failed/i.test(event.name));
+    if (errorEvents.length)
+      drivers.push(`${errorEvents.length} errors logged`);
+    return drivers;
+  }
+}
+function groupBy(items, selector) {
+  const map = new Map;
+  for (const item of items) {
+    const key = selector(item);
+    const list = map.get(key) ?? [];
+    list.push(item);
+    map.set(key, list);
+  }
+  return map;
+}
+function dateMs(event) {
+  return new Date(event.timestamp).getTime();
+}
+export {
+  ChurnPredictor
+};

package/dist/node/churn/predictor.js

@@ -0,0 +1,77 @@
+// src/churn/predictor.ts
+import dayjs from "dayjs";
+
+class ChurnPredictor {
+  recencyWeight;
+  frequencyWeight;
+  errorWeight;
+  decayDays;
+  constructor(options) {
+    this.recencyWeight = options?.recencyWeight ?? 0.5;
+    this.frequencyWeight = options?.frequencyWeight ?? 0.3;
+    this.errorWeight = options?.errorWeight ?? 0.2;
+    this.decayDays = options?.decayDays ?? 14;
+  }
+  score(events) {
+    const grouped = groupBy(events, (event) => event.userId);
+    const signals = [];
+    for (const [userId, userEvents] of grouped.entries()) {
+      const score = this.computeScore(userEvents);
+      signals.push({
+        userId,
+        score,
+        bucket: score >= 0.7 ? "high" : score >= 0.4 ? "medium" : "low",
+        drivers: this.drivers(userEvents)
+      });
+    }
+    return signals.sort((a, b) => b.score - a.score);
+  }
+  computeScore(events) {
+    if (!events.length)
+      return 0;
+    const sorted = events.sort((a, b) => dateMs(a) - dateMs(b));
+    const lastEvent = sorted[sorted.length - 1];
+    if (!lastEvent)
+      return 0;
+    const daysSinceLast = dayjs().diff(dayjs(lastEvent.timestamp), "day");
+    const recencyScore = Math.max(0, 1 - daysSinceLast / this.decayDays);
+    const windowStart = dayjs().subtract(this.decayDays, "day");
+    const recentEvents = sorted.filter((event) => dayjs(event.timestamp).isAfter(windowStart));
+    const averagePerDay = recentEvents.length / Math.max(this.decayDays, 1);
+    const frequencyScore = Math.min(1, averagePerDay * 5);
+    const errorEvents = recentEvents.filter((event) => typeof event.properties?.error !== "undefined" || /error|failed/i.test(event.name)).length;
+    const errorScore = Math.min(1, errorEvents / 3);
+    const score = recencyScore * this.recencyWeight + frequencyScore * this.frequencyWeight + (1 - errorScore) * this.errorWeight;
+    return Number(score.toFixed(3));
+  }
+  drivers(events) {
+    const drivers = [];
+    const sorted = events.sort((a, b) => dateMs(a) - dateMs(b));
+    const lastEvent = sorted[sorted.length - 1];
+    if (lastEvent) {
+      const days = dayjs().diff(dayjs(lastEvent.timestamp), "day");
+      if (days > this.decayDays)
+        drivers.push(`Inactive for ${days} days`);
+    }
+    const errorEvents = events.filter((event) => typeof event.properties?.error !== "undefined" || /error|failed/i.test(event.name));
+    if (errorEvents.length)
+      drivers.push(`${errorEvents.length} errors logged`);
+    return drivers;
+  }
+}
+function groupBy(items, selector) {
+  const map = new Map;
+  for (const item of items) {
+    const key = selector(item);
+    const list = map.get(key) ?? [];
+    list.push(item);
+    map.set(key, list);
+  }
+  return map;
+}
+function dateMs(event) {
+  return new Date(event.timestamp).getTime();
+}
+export {
+  ChurnPredictor
+};