@contractspec/lib.analytics 1.57.0 → 1.58.0

package/dist/browser/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/browser/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
+};

package/dist/browser/cohort/index.js

@@ -0,0 +1,117 @@
+// src/cohort/tracker.ts
+import dayjs from "dayjs";
+
+class CohortTracker {
+  analyze(events, definition) {
+    const groupedByUser = groupBy(events, (event) => event.userId);
+    const cohorts = new Map;
+    for (const [userId, userEvents] of groupedByUser.entries()) {
+      userEvents.sort((a, b) => dateMs(a) - dateMs(b));
+      const signup = userEvents[0];
+      if (!signup)
+        continue;
+      const cohortKey = bucketKey(signup.timestamp, definition.bucket);
+      const builder = cohorts.get(cohortKey) ?? new CohortStatsBuilder(cohortKey, definition);
+      builder.addUser(userId);
+      for (const event of userEvents) {
+        builder.addEvent(userId, event);
+      }
+      cohorts.set(cohortKey, builder);
+    }
+    return {
+      definition,
+      cohorts: [...cohorts.values()].map((builder) => builder.build())
+    };
+  }
+}
+
+class CohortStatsBuilder {
+  key;
+  definition;
+  users = new Set;
+  retentionMap = new Map;
+  ltv = 0;
+  constructor(key, definition) {
+    this.key = key;
+    this.definition = definition;
+  }
+  addUser(userId) {
+    this.users.add(userId);
+  }
+  addEvent(userId, event) {
+    const period = bucketDiff(this.key, event.timestamp, this.definition.bucket);
+    if (period < 0 || period >= this.definition.periods)
+      return;
+    const bucket = this.retentionMap.get(period) ?? new Set;
+    bucket.add(userId);
+    this.retentionMap.set(period, bucket);
+    const amount = typeof event.properties?.amount === "number" ? event.properties.amount : 0;
+    this.ltv += amount;
+  }
+  build() {
+    const totalUsers = this.users.size || 1;
+    const retention = [];
+    for (let period = 0;period < this.definition.periods; period++) {
+      const active = this.retentionMap.get(period)?.size ?? 0;
+      retention.push(Number((active / totalUsers).toFixed(3)));
+    }
+    return {
+      cohortKey: this.key,
+      users: this.users.size,
+      retention,
+      ltv: Number(this.ltv.toFixed(2))
+    };
+  }
+}
+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 bucketKey(timestamp, bucket) {
+  const dt = dayjs(timestamp);
+  switch (bucket) {
+    case "day":
+      return dt.startOf("day").format("YYYY-MM-DD");
+    case "week":
+      return dt.startOf("week").format("YYYY-[W]WW");
+    case "month":
+    default:
+      return dt.startOf("month").format("YYYY-MM");
+  }
+}
+function bucketDiff(cohortKey, timestamp, bucket) {
+  const start = parseBucketKey(cohortKey, bucket);
+  const target = dayjs(timestamp);
+  switch (bucket) {
+    case "day":
+      return target.diff(start, "day");
+    case "week":
+      return target.diff(start, "week");
+    case "month":
+    default:
+      return target.diff(start, "month");
+  }
+}
+function parseBucketKey(key, bucket) {
+  switch (bucket) {
+    case "day":
+      return dayjs(key, "YYYY-MM-DD");
+    case "week":
+      return dayjs(key.replace("W", ""), "YYYY-ww");
+    case "month":
+    default:
+      return dayjs(key, "YYYY-MM");
+  }
+}
+function dateMs(event) {
+  return new Date(event.timestamp).getTime();
+}
+export {
+  CohortTracker
+};

package/dist/browser/cohort/tracker.js

@@ -0,0 +1,117 @@
+// src/cohort/tracker.ts
+import dayjs from "dayjs";
+
+class CohortTracker {
+  analyze(events, definition) {
+    const groupedByUser = groupBy(events, (event) => event.userId);
+    const cohorts = new Map;
+    for (const [userId, userEvents] of groupedByUser.entries()) {
+      userEvents.sort((a, b) => dateMs(a) - dateMs(b));
+      const signup = userEvents[0];
+      if (!signup)
+        continue;
+      const cohortKey = bucketKey(signup.timestamp, definition.bucket);
+      const builder = cohorts.get(cohortKey) ?? new CohortStatsBuilder(cohortKey, definition);
+      builder.addUser(userId);
+      for (const event of userEvents) {
+        builder.addEvent(userId, event);
+      }
+      cohorts.set(cohortKey, builder);
+    }
+    return {
+      definition,
+      cohorts: [...cohorts.values()].map((builder) => builder.build())
+    };
+  }
+}
+
+class CohortStatsBuilder {
+  key;
+  definition;
+  users = new Set;
+  retentionMap = new Map;
+  ltv = 0;
+  constructor(key, definition) {
+    this.key = key;
+    this.definition = definition;
+  }
+  addUser(userId) {
+    this.users.add(userId);
+  }
+  addEvent(userId, event) {
+    const period = bucketDiff(this.key, event.timestamp, this.definition.bucket);
+    if (period < 0 || period >= this.definition.periods)
+      return;
+    const bucket = this.retentionMap.get(period) ?? new Set;
+    bucket.add(userId);
+    this.retentionMap.set(period, bucket);
+    const amount = typeof event.properties?.amount === "number" ? event.properties.amount : 0;
+    this.ltv += amount;
+  }
+  build() {
+    const totalUsers = this.users.size || 1;
+    const retention = [];
+    for (let period = 0;period < this.definition.periods; period++) {
+      const active = this.retentionMap.get(period)?.size ?? 0;
+      retention.push(Number((active / totalUsers).toFixed(3)));
+    }
+    return {
+      cohortKey: this.key,
+      users: this.users.size,
+      retention,
+      ltv: Number(this.ltv.toFixed(2))
+    };
+  }
+}
+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 bucketKey(timestamp, bucket) {
+  const dt = dayjs(timestamp);
+  switch (bucket) {
+    case "day":
+      return dt.startOf("day").format("YYYY-MM-DD");
+    case "week":
+      return dt.startOf("week").format("YYYY-[W]WW");
+    case "month":
+    default:
+      return dt.startOf("month").format("YYYY-MM");
+  }
+}
+function bucketDiff(cohortKey, timestamp, bucket) {
+  const start = parseBucketKey(cohortKey, bucket);
+  const target = dayjs(timestamp);
+  switch (bucket) {
+    case "day":
+      return target.diff(start, "day");
+    case "week":
+      return target.diff(start, "week");
+    case "month":
+    default:
+      return target.diff(start, "month");
+  }
+}
+function parseBucketKey(key, bucket) {
+  switch (bucket) {
+    case "day":
+      return dayjs(key, "YYYY-MM-DD");
+    case "week":
+      return dayjs(key.replace("W", ""), "YYYY-ww");
+    case "month":
+    default:
+      return dayjs(key, "YYYY-MM");
+  }
+}
+function dateMs(event) {
+  return new Date(event.timestamp).getTime();
+}
+export {
+  CohortTracker
+};

package/dist/browser/funnel/analyzer.js

@@ -0,0 +1,68 @@
+// src/funnel/analyzer.ts
+class FunnelAnalyzer {
+  analyze(events, definition) {
+    const windowMs = (definition.windowHours ?? 72) * 60 * 60 * 1000;
+    const eventsByUser = groupByUser(events);
+    const stepCounts = definition.steps.map(() => 0);
+    for (const userEvents of eventsByUser.values()) {
+      const completionIndex = this.evaluateUser(userEvents, definition.steps, windowMs);
+      completionIndex.forEach((hit, stepIdx) => {
+        if (hit) {
+          stepCounts[stepIdx] = (stepCounts[stepIdx] ?? 0) + 1;
+        }
+      });
+    }
+    const totalUsers = eventsByUser.size;
+    const steps = definition.steps.map((step, index) => {
+      const prevCount = index === 0 ? totalUsers : stepCounts[index - 1] || 1;
+      const count = stepCounts[index] ?? 0;
+      const conversionRate = prevCount === 0 ? 0 : Number((count / prevCount).toFixed(3));
+      const dropOffRate = Number((1 - conversionRate).toFixed(3));
+      return { step, count, conversionRate, dropOffRate };
+    });
+    return {
+      definition,
+      totalUsers,
+      steps
+    };
+  }
+  evaluateUser(events, steps, windowMs) {
+    const sorted = [...events].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    const completion = Array(steps.length).fill(false);
+    let cursor = 0;
+    let anchorTime;
+    for (const event of sorted) {
+      const step = steps[cursor];
+      if (!step)
+        break;
+      if (event.name !== step.eventName)
+        continue;
+      if (step.match && !step.match(event))
+        continue;
+      const eventTime = new Date(event.timestamp).getTime();
+      if (cursor === 0) {
+        anchorTime = eventTime;
+        completion[cursor] = true;
+        cursor += 1;
+        continue;
+      }
+      if (anchorTime && eventTime - anchorTime <= windowMs) {
+        completion[cursor] = true;
+        cursor += 1;
+      }
+    }
+    return completion;
+  }
+}
+function groupByUser(events) {
+  const map = new Map;
+  for (const event of events) {
+    const list = map.get(event.userId) ?? [];
+    list.push(event);
+    map.set(event.userId, list);
+  }
+  return map;
+}
+export {
+  FunnelAnalyzer
+};

package/dist/browser/funnel/index.js

@@ -0,0 +1,68 @@
+// src/funnel/analyzer.ts
+class FunnelAnalyzer {
+  analyze(events, definition) {
+    const windowMs = (definition.windowHours ?? 72) * 60 * 60 * 1000;
+    const eventsByUser = groupByUser(events);
+    const stepCounts = definition.steps.map(() => 0);
+    for (const userEvents of eventsByUser.values()) {
+      const completionIndex = this.evaluateUser(userEvents, definition.steps, windowMs);
+      completionIndex.forEach((hit, stepIdx) => {
+        if (hit) {
+          stepCounts[stepIdx] = (stepCounts[stepIdx] ?? 0) + 1;
+        }
+      });
+    }
+    const totalUsers = eventsByUser.size;
+    const steps = definition.steps.map((step, index) => {
+      const prevCount = index === 0 ? totalUsers : stepCounts[index - 1] || 1;
+      const count = stepCounts[index] ?? 0;
+      const conversionRate = prevCount === 0 ? 0 : Number((count / prevCount).toFixed(3));
+      const dropOffRate = Number((1 - conversionRate).toFixed(3));
+      return { step, count, conversionRate, dropOffRate };
+    });
+    return {
+      definition,
+      totalUsers,
+      steps
+    };
+  }
+  evaluateUser(events, steps, windowMs) {
+    const sorted = [...events].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    const completion = Array(steps.length).fill(false);
+    let cursor = 0;
+    let anchorTime;
+    for (const event of sorted) {
+      const step = steps[cursor];
+      if (!step)
+        break;
+      if (event.name !== step.eventName)
+        continue;
+      if (step.match && !step.match(event))
+        continue;
+      const eventTime = new Date(event.timestamp).getTime();
+      if (cursor === 0) {
+        anchorTime = eventTime;
+        completion[cursor] = true;
+        cursor += 1;
+        continue;
+      }
+      if (anchorTime && eventTime - anchorTime <= windowMs) {
+        completion[cursor] = true;
+        cursor += 1;
+      }
+    }
+    return completion;
+  }
+}
+function groupByUser(events) {
+  const map = new Map;
+  for (const event of events) {
+    const list = map.get(event.userId) ?? [];
+    list.push(event);
+    map.set(event.userId, list);
+  }
+  return map;
+}
+export {
+  FunnelAnalyzer
+};

package/dist/browser/growth/hypothesis-generator.js

@@ -0,0 +1,46 @@
+// src/growth/hypothesis-generator.ts
+class GrowthHypothesisGenerator {
+  minDelta;
+  constructor(options) {
+    this.minDelta = options?.minDelta ?? 0.05;
+  }
+  generate(metrics) {
+    return metrics.map((metric) => this.fromMetric(metric)).filter((hypothesis) => Boolean(hypothesis));
+  }
+  fromMetric(metric) {
+    const change = this.delta(metric);
+    if (Math.abs(change) < this.minDelta)
+      return null;
+    const direction = change > 0 ? "rising" : "declining";
+    const statement = this.statement(metric, change, direction);
+    return {
+      statement,
+      metric: metric.name,
+      confidence: Math.abs(change) > 0.2 ? "high" : "medium",
+      impact: this.impact(metric)
+    };
+  }
+  delta(metric) {
+    if (metric.previous == null)
+      return 0;
+    const prev = metric.previous || 1;
+    return (metric.current - prev) / Math.abs(prev);
+  }
+  impact(metric) {
+    if (metric.target && metric.current < metric.target * 0.8)
+      return "high";
+    if (metric.target && metric.current < metric.target)
+      return "medium";
+    return "low";
+  }
+  statement(metric, change, direction) {
+    const percent = Math.abs(parseFloat((change * 100).toFixed(1)));
+    if (direction === "declining") {
+      return `${metric.name} is down ${percent}% vs last period; test new onboarding prompts to recover activation.`;
+    }
+    return `${metric.name} grew ${percent}% period-over-period; double down with expanded experiment or pricing test.`;
+  }
+}
+export {
+  GrowthHypothesisGenerator
+};

package/dist/browser/growth/index.js

@@ -0,0 +1,46 @@
+// src/growth/hypothesis-generator.ts
+class GrowthHypothesisGenerator {
+  minDelta;
+  constructor(options) {
+    this.minDelta = options?.minDelta ?? 0.05;
+  }
+  generate(metrics) {
+    return metrics.map((metric) => this.fromMetric(metric)).filter((hypothesis) => Boolean(hypothesis));
+  }
+  fromMetric(metric) {
+    const change = this.delta(metric);
+    if (Math.abs(change) < this.minDelta)
+      return null;
+    const direction = change > 0 ? "rising" : "declining";
+    const statement = this.statement(metric, change, direction);
+    return {
+      statement,
+      metric: metric.name,
+      confidence: Math.abs(change) > 0.2 ? "high" : "medium",
+      impact: this.impact(metric)
+    };
+  }
+  delta(metric) {
+    if (metric.previous == null)
+      return 0;
+    const prev = metric.previous || 1;
+    return (metric.current - prev) / Math.abs(prev);
+  }
+  impact(metric) {
+    if (metric.target && metric.current < metric.target * 0.8)
+      return "high";
+    if (metric.target && metric.current < metric.target)
+      return "medium";
+    return "low";
+  }
+  statement(metric, change, direction) {
+    const percent = Math.abs(parseFloat((change * 100).toFixed(1)));
+    if (direction === "declining") {
+      return `${metric.name} is down ${percent}% vs last period; test new onboarding prompts to recover activation.`;
+    }
+    return `${metric.name} grew ${percent}% period-over-period; double down with expanded experiment or pricing test.`;
+  }
+}
+export {
+  GrowthHypothesisGenerator
+};