@contractspec/lib.analytics 1.57.0 → 1.59.0

package/dist/browser/posthog/event-source.js

@@ -0,0 +1,138 @@
+// src/posthog/event-source.ts
+class PosthogAnalyticsEventSource {
+  reader;
+  limitPerEvent;
+  tenantPropertyKey;
+  defaultRangeDays;
+  constructor(reader, options = {}) {
+    this.reader = reader;
+    this.limitPerEvent = options.limitPerEvent ?? 1000;
+    this.tenantPropertyKey = options.tenantPropertyKey ?? "tenantId";
+    this.defaultRangeDays = options.defaultRangeDays ?? 30;
+  }
+  async getEventsForFunnel(definition, dateRange) {
+    const eventNames = definition.steps.map((step) => step.eventName);
+    return this.getEventsByNames(eventNames, dateRange);
+  }
+  async getEventsForCohort(definition, dateRange, eventNames) {
+    const events = eventNames && eventNames.length > 0 ? eventNames : ["*"];
+    if (events[0] === "*") {
+      return this.getEventsByNames([], dateRange, definition.periods * 500);
+    }
+    return this.getEventsByNames(events, dateRange, definition.periods * 500);
+  }
+  async getUserActivity(userId, dateRange, limit = 1000) {
+    if (!this.reader.getEvents) {
+      throw new Error("Analytics reader does not support event queries.");
+    }
+    const response = await this.reader.getEvents({
+      distinctId: userId,
+      dateRange,
+      limit
+    });
+    return response.results.map((event) => toAnalyticsEvent(event, this.tenantPropertyKey));
+  }
+  async getGrowthMetrics(metricNames, dateRange) {
+    const range = resolveRange(dateRange, this.defaultRangeDays);
+    const previous = shiftRange(range);
+    const results = [];
+    for (const metricName of metricNames) {
+      const current = await this.countEvents(metricName, range);
+      const previousCount = await this.countEvents(metricName, previous);
+      results.push({
+        name: metricName,
+        current,
+        previous: previousCount
+      });
+    }
+    return results;
+  }
+  async getEventsByNames(eventNames, dateRange, limitPerEvent = this.limitPerEvent) {
+    if (!this.reader.getEvents) {
+      throw new Error("Analytics reader does not support event queries.");
+    }
+    if (eventNames.length === 0) {
+      const response = await this.reader.getEvents({
+        dateRange,
+        limit: limitPerEvent
+      });
+      return response.results.map((event) => toAnalyticsEvent(event, this.tenantPropertyKey));
+    }
+    const events = [];
+    for (const eventName of eventNames) {
+      const response = await this.reader.getEvents({
+        event: eventName,
+        dateRange,
+        limit: limitPerEvent
+      });
+      response.results.forEach((event) => {
+        events.push(toAnalyticsEvent(event, this.tenantPropertyKey));
+      });
+    }
+    return events;
+  }
+  async countEvents(eventName, range) {
+    if (!this.reader.queryHogQL) {
+      throw new Error("Analytics reader does not support HogQL queries.");
+    }
+    const result = await this.reader.queryHogQL({
+      query: [
+        "select",
+        "  count() as total",
+        "from events",
+        "where event = {eventName}",
+        "and timestamp >= {dateFrom}",
+        "and timestamp < {dateTo}"
+      ].join(`
+`),
+      values: {
+        eventName,
+        dateFrom: range.from.toISOString(),
+        dateTo: range.to.toISOString()
+      }
+    });
+    return readSingleNumber(result) ?? 0;
+  }
+}
+function toAnalyticsEvent(event, tenantPropertyKey) {
+  const tenantIdValue = event.properties?.[tenantPropertyKey] ?? event.properties?.tenantId;
+  return {
+    name: event.event,
+    userId: event.distinctId,
+    tenantId: typeof tenantIdValue === "string" ? tenantIdValue : undefined,
+    timestamp: event.timestamp,
+    properties: event.properties
+  };
+}
+function resolveRange(dateRange, defaultDays) {
+  const to = dateRange?.to instanceof Date ? dateRange.to : dateRange?.to ? new Date(dateRange.to) : new Date;
+  const from = dateRange?.from instanceof Date ? dateRange.from : dateRange?.from ? new Date(dateRange.from) : new Date(to.getTime() - defaultDays * 24 * 60 * 60 * 1000);
+  return { from, to };
+}
+function shiftRange(range) {
+  const duration = range.to.getTime() - range.from.getTime();
+  return {
+    from: new Date(range.from.getTime() - duration),
+    to: new Date(range.to.getTime() - duration)
+  };
+}
+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;
+    }
+  }
+  return;
+}
+export {
+  PosthogAnalyticsEventSource
+};

package/dist/browser/posthog/index.js

@@ -0,0 +1,138 @@
+// src/posthog/event-source.ts
+class PosthogAnalyticsEventSource {
+  reader;
+  limitPerEvent;
+  tenantPropertyKey;
+  defaultRangeDays;
+  constructor(reader, options = {}) {
+    this.reader = reader;
+    this.limitPerEvent = options.limitPerEvent ?? 1000;
+    this.tenantPropertyKey = options.tenantPropertyKey ?? "tenantId";
+    this.defaultRangeDays = options.defaultRangeDays ?? 30;
+  }
+  async getEventsForFunnel(definition, dateRange) {
+    const eventNames = definition.steps.map((step) => step.eventName);
+    return this.getEventsByNames(eventNames, dateRange);
+  }
+  async getEventsForCohort(definition, dateRange, eventNames) {
+    const events = eventNames && eventNames.length > 0 ? eventNames : ["*"];
+    if (events[0] === "*") {
+      return this.getEventsByNames([], dateRange, definition.periods * 500);
+    }
+    return this.getEventsByNames(events, dateRange, definition.periods * 500);
+  }
+  async getUserActivity(userId, dateRange, limit = 1000) {
+    if (!this.reader.getEvents) {
+      throw new Error("Analytics reader does not support event queries.");
+    }
+    const response = await this.reader.getEvents({
+      distinctId: userId,
+      dateRange,
+      limit
+    });
+    return response.results.map((event) => toAnalyticsEvent(event, this.tenantPropertyKey));
+  }
+  async getGrowthMetrics(metricNames, dateRange) {
+    const range = resolveRange(dateRange, this.defaultRangeDays);
+    const previous = shiftRange(range);
+    const results = [];
+    for (const metricName of metricNames) {
+      const current = await this.countEvents(metricName, range);
+      const previousCount = await this.countEvents(metricName, previous);
+      results.push({
+        name: metricName,
+        current,
+        previous: previousCount
+      });
+    }
+    return results;
+  }
+  async getEventsByNames(eventNames, dateRange, limitPerEvent = this.limitPerEvent) {
+    if (!this.reader.getEvents) {
+      throw new Error("Analytics reader does not support event queries.");
+    }
+    if (eventNames.length === 0) {
+      const response = await this.reader.getEvents({
+        dateRange,
+        limit: limitPerEvent
+      });
+      return response.results.map((event) => toAnalyticsEvent(event, this.tenantPropertyKey));
+    }
+    const events = [];
+    for (const eventName of eventNames) {
+      const response = await this.reader.getEvents({
+        event: eventName,
+        dateRange,
+        limit: limitPerEvent
+      });
+      response.results.forEach((event) => {
+        events.push(toAnalyticsEvent(event, this.tenantPropertyKey));
+      });
+    }
+    return events;
+  }
+  async countEvents(eventName, range) {
+    if (!this.reader.queryHogQL) {
+      throw new Error("Analytics reader does not support HogQL queries.");
+    }
+    const result = await this.reader.queryHogQL({
+      query: [
+        "select",
+        "  count() as total",
+        "from events",
+        "where event = {eventName}",
+        "and timestamp >= {dateFrom}",
+        "and timestamp < {dateTo}"
+      ].join(`
+`),
+      values: {
+        eventName,
+        dateFrom: range.from.toISOString(),
+        dateTo: range.to.toISOString()
+      }
+    });
+    return readSingleNumber(result) ?? 0;
+  }
+}
+function toAnalyticsEvent(event, tenantPropertyKey) {
+  const tenantIdValue = event.properties?.[tenantPropertyKey] ?? event.properties?.tenantId;
+  return {
+    name: event.event,
+    userId: event.distinctId,
+    tenantId: typeof tenantIdValue === "string" ? tenantIdValue : undefined,
+    timestamp: event.timestamp,
+    properties: event.properties
+  };
+}
+function resolveRange(dateRange, defaultDays) {
+  const to = dateRange?.to instanceof Date ? dateRange.to : dateRange?.to ? new Date(dateRange.to) : new Date;
+  const from = dateRange?.from instanceof Date ? dateRange.from : dateRange?.from ? new Date(dateRange.from) : new Date(to.getTime() - defaultDays * 24 * 60 * 60 * 1000);
+  return { from, to };
+}
+function shiftRange(range) {
+  const duration = range.to.getTime() - range.from.getTime();
+  return {
+    from: new Date(range.from.getTime() - duration),
+    to: new Date(range.to.getTime() - duration)
+  };
+}
+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;
+    }
+  }
+  return;
+}
+export {
+  PosthogAnalyticsEventSource
+};

package/dist/churn/index.d.ts

@@ -1,2 +1,2 @@
-import { ChurnPredictor, ChurnPredictorOptions } from "./predictor.js";
-export { ChurnPredictor, ChurnPredictorOptions };
+export * from './predictor';
+//# sourceMappingURL=index.d.ts.map

package/dist/churn/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/churn/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}

package/dist/churn/index.js

@@ -1,3 +1,78 @@
-import { ChurnPredictor } from "./predictor.js";
+// @bun
+// src/churn/predictor.ts
+import dayjs from "dayjs";
 
-export { ChurnPredictor };
+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/churn/predictor.d.ts

@@ -1,22 +1,18 @@
-import { AnalyticsEvent, ChurnSignal } from "../types.js";
-
-//#region src/churn/predictor.d.ts
-interface ChurnPredictorOptions {
-  recencyWeight?: number;
-  frequencyWeight?: number;
-  errorWeight?: number;
-  decayDays?: number;
+import type { AnalyticsEvent, ChurnSignal } from '../types';
+export interface ChurnPredictorOptions {
+    recencyWeight?: number;
+    frequencyWeight?: number;
+    errorWeight?: number;
+    decayDays?: number;
 }
-declare class ChurnPredictor {
-  private readonly recencyWeight;
-  private readonly frequencyWeight;
-  private readonly errorWeight;
-  private readonly decayDays;
-  constructor(options?: ChurnPredictorOptions);
-  score(events: AnalyticsEvent[]): ChurnSignal[];
-  private computeScore;
-  private drivers;
+export declare class ChurnPredictor {
+    private readonly recencyWeight;
+    private readonly frequencyWeight;
+    private readonly errorWeight;
+    private readonly decayDays;
+    constructor(options?: ChurnPredictorOptions);
+    score(events: AnalyticsEvent[]): ChurnSignal[];
+    private computeScore;
+    private drivers;
 }
-//#endregion
-export { ChurnPredictor, ChurnPredictorOptions };
 //# sourceMappingURL=predictor.d.ts.map

package/dist/churn/predictor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"predictor.d.ts","names":[],"sources":["../../src/churn/predictor.ts"],"mappings":";;;UAGiB,qBAAA;EACf,aAAA;EACA,eAAA;EACA,WAAA;EACA,SAAA;AAAA;AAAA,cAGW,cAAA;EAAA,iBACM,aAAA;EAAA,iBACA,eAAA;EAAA,iBACA,WAAA;EAAA,iBACA,SAAA;cAEL,OAAA,GAAU,qBAAA;EAOtB,KAAA,CAAM,MAAA,EAAQ,cAAA,KAAmB,WAAA;EAAA,QAezB,YAAA;EAAA,QA6BA,OAAA;AAAA"}
+{"version":3,"file":"predictor.d.ts","sourceRoot":"","sources":["../../src/churn/predictor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5D,MAAM,WAAW,qBAAqB;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,OAAO,CAAC,EAAE,qBAAqB;IAO3C,KAAK,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,WAAW,EAAE;IAe9C,OAAO,CAAC,YAAY;IA6BpB,OAAO,CAAC,OAAO;CAgBhB"}

package/dist/churn/predictor.js

@@ -1,74 +1,78 @@
+// @bun
+// src/churn/predictor.ts
 import dayjs from "dayjs";
 
-//#region src/churn/predictor.ts
-var ChurnPredictor = class {
-	recencyWeight;
-	frequencyWeight;
-	errorWeight;
-	decayDays;
-	constructor(options) {
-		this.recencyWeight = options?.recencyWeight ?? .5;
-		this.frequencyWeight = options?.frequencyWeight ?? .3;
-		this.errorWeight = options?.errorWeight ?? .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 >= .7 ? "high" : score >= .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;
-	}
-};
+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 = /* @__PURE__ */ 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;
+  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();
+  return new Date(event.timestamp).getTime();
 }
-
-//#endregion
-export { ChurnPredictor };
-//# sourceMappingURL=predictor.js.map
+export {
+  ChurnPredictor
+};

package/dist/cohort/index.d.ts

@@ -1,2 +1,2 @@
-import { CohortTracker } from "./tracker.js";
-export { CohortTracker };
+export * from './tracker';
+//# sourceMappingURL=index.d.ts.map

package/dist/cohort/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cohort/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC"}