@lssm/lib.analytics 0.0.0-canary-20251206160926

package/README.md

@@ -0,0 +1,10 @@
+# @lssm/lib.analytics
+
+Zero-dependency analytics toolkit used by Phase 2 AI-Native Ops. It ingests telemetry events and outputs:
+
+- Funnel conversion reports with drop-off detection.
+- Cohort retention curves and LTV summaries.
+- Churn predictors that flag risky accounts.
+- Growth hypothesis generator that suggests experiments.
+
+All utilities operate on plain JSON events so they can run in jobs, background workers, or MCP agents without a warehouse.

package/dist/churn/index.d.ts

@@ -0,0 +1,2 @@
+import { ChurnPredictor, ChurnPredictorOptions } from "./predictor.js";
+export { ChurnPredictor, ChurnPredictorOptions };

package/dist/churn/index.js

@@ -0,0 +1 @@
+import{ChurnPredictor as e}from"./predictor.js";export{e as ChurnPredictor};

package/dist/churn/predictor.d.ts

@@ -0,0 +1,21 @@
+import { AnalyticsEvent, ChurnSignal } from "../types.js";
+
+//#region src/churn/predictor.d.ts
+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;
+}
+//#endregion
+export { ChurnPredictor, ChurnPredictorOptions };

package/dist/churn/predictor.js

@@ -0,0 +1 @@
+import e from"dayjs";var t=class{recencyWeight;frequencyWeight;errorWeight;decayDays;constructor(e){this.recencyWeight=e?.recencyWeight??.5,this.frequencyWeight=e?.frequencyWeight??.3,this.errorWeight=e?.errorWeight??.2,this.decayDays=e?.decayDays??14}score(e){let t=n(e,e=>e.userId),r=[];for(let[e,n]of t.entries()){let t=this.computeScore(n);r.push({userId:e,score:t,bucket:t>=.7?`high`:t>=.4?`medium`:`low`,drivers:this.drivers(n)})}return r.sort((e,t)=>t.score-e.score)}computeScore(t){if(!t.length)return 0;let n=t.sort((e,t)=>r(e)-r(t)),i=n[n.length-1];if(!i)return 0;let a=e().diff(e(i.timestamp),`day`),o=Math.max(0,1-a/this.decayDays),s=e().subtract(this.decayDays,`day`),c=n.filter(t=>e(t.timestamp).isAfter(s)),l=c.length/Math.max(this.decayDays,1),u=Math.min(1,l*5),d=c.filter(e=>e.properties?.error!==void 0||/error|failed/i.test(e.name)).length,f=Math.min(1,d/3),p=o*this.recencyWeight+u*this.frequencyWeight+(1-f)*this.errorWeight;return Number(p.toFixed(3))}drivers(t){let n=[],i=t.sort((e,t)=>r(e)-r(t)),a=i[i.length-1];if(a){let t=e().diff(e(a.timestamp),`day`);t>this.decayDays&&n.push(`Inactive for ${t} days`)}let o=t.filter(e=>e.properties?.error!==void 0||/error|failed/i.test(e.name));return o.length&&n.push(`${o.length} errors logged`),n}};function n(e,t){let n=new Map;for(let r of e){let e=t(r),i=n.get(e)??[];i.push(r),n.set(e,i)}return n}function r(e){return new Date(e.timestamp).getTime()}export{t as ChurnPredictor};

package/dist/cohort/index.d.ts

@@ -0,0 +1,2 @@
+import { CohortTracker } from "./tracker.js";
+export { CohortTracker };

package/dist/cohort/index.js

@@ -0,0 +1 @@
+import{CohortTracker as e}from"./tracker.js";export{e as CohortTracker};

package/dist/cohort/tracker.d.ts

@@ -0,0 +1,8 @@
+import { AnalyticsEvent, CohortAnalysis, CohortDefinition } from "../types.js";
+
+//#region src/cohort/tracker.d.ts
+declare class CohortTracker {
+  analyze(events: AnalyticsEvent[], definition: CohortDefinition): CohortAnalysis;
+}
+//#endregion
+export { CohortTracker };

package/dist/cohort/tracker.js

@@ -0,0 +1 @@
+import e from"dayjs";var t=class{analyze(e,t){let a=r(e,e=>e.userId),o=new Map;for(let[e,r]of a.entries()){r.sort((e,t)=>s(e)-s(t));let a=r[0];if(!a)continue;let c=i(a.timestamp,t.bucket),l=o.get(c)??new n(c,t);l.addUser(e);for(let t of r)l.addEvent(e,t);o.set(c,l)}return{definition:t,cohorts:[...o.values()].map(e=>e.build())}}},n=class{users=new Set;retentionMap=new Map;ltv=0;constructor(e,t){this.key=e,this.definition=t}addUser(e){this.users.add(e)}addEvent(e,t){let n=a(this.key,t.timestamp,this.definition.bucket);if(n<0||n>=this.definition.periods)return;let r=this.retentionMap.get(n)??new Set;r.add(e),this.retentionMap.set(n,r);let i=typeof t.properties?.amount==`number`?t.properties.amount:0;this.ltv+=i}build(){let e=this.users.size||1,t=[];for(let n=0;n<this.definition.periods;n++){let r=this.retentionMap.get(n)?.size??0;t.push(Number((r/e).toFixed(3)))}return{cohortKey:this.key,users:this.users.size,retention:t,ltv:Number(this.ltv.toFixed(2))}}};function r(e,t){let n=new Map;for(let r of e){let e=t(r),i=n.get(e)??[];i.push(r),n.set(e,i)}return n}function i(t,n){let r=e(t);switch(n){case`day`:return r.startOf(`day`).format(`YYYY-MM-DD`);case`week`:return r.startOf(`week`).format(`YYYY-[W]WW`);case`month`:default:return r.startOf(`month`).format(`YYYY-MM`)}}function a(t,n,r){let i=o(t,r),a=e(n);switch(r){case`day`:return a.diff(i,`day`);case`week`:return a.diff(i,`week`);case`month`:default:return a.diff(i,`month`)}}function o(t,n){switch(n){case`day`:return e(t,`YYYY-MM-DD`);case`week`:return e(t.replace(`W`,``),`YYYY-ww`);case`month`:default:return e(t,`YYYY-MM`)}}function s(e){return new Date(e.timestamp).getTime()}export{t as CohortTracker};

package/dist/funnel/analyzer.d.ts

@@ -0,0 +1,9 @@
+import { AnalyticsEvent, FunnelAnalysis, FunnelDefinition } from "../types.js";
+
+//#region src/funnel/analyzer.d.ts
+declare class FunnelAnalyzer {
+  analyze(events: AnalyticsEvent[], definition: FunnelDefinition): FunnelAnalysis;
+  private evaluateUser;
+}
+//#endregion
+export { FunnelAnalyzer };

package/dist/funnel/analyzer.js

@@ -0,0 +1 @@
+var e=class{analyze(e,n){let r=(n.windowHours??72)*60*60*1e3,i=t(e),a=n.steps.map(()=>0);for(let e of i.values())this.evaluateUser(e,n.steps,r).forEach((e,t)=>{e&&(a[t]=(a[t]??0)+1)});let o=i.size;return{definition:n,totalUsers:o,steps:n.steps.map((e,t)=>{let n=t===0?o:a[t-1]||1,r=a[t]??0,i=n===0?0:Number((r/n).toFixed(3));return{step:e,count:r,conversionRate:i,dropOffRate:Number((1-i).toFixed(3))}})}}evaluateUser(e,t,n){let r=[...e].sort((e,t)=>new Date(e.timestamp).getTime()-new Date(t.timestamp).getTime()),i=Array(t.length).fill(!1),a=0,o;for(let e of r){let r=t[a];if(!r)break;if(e.name!==r.eventName||r.match&&!r.match(e))continue;let s=new Date(e.timestamp).getTime();if(a===0){o=s,i[a]=!0,a+=1;continue}o&&s-o<=n&&(i[a]=!0,a+=1)}return i}};function t(e){let t=new Map;for(let n of e){let e=t.get(n.userId)??[];e.push(n),t.set(n.userId,e)}return t}export{e as FunnelAnalyzer};

package/dist/funnel/index.d.ts

@@ -0,0 +1,2 @@
+import { FunnelAnalyzer } from "./analyzer.js";
+export { FunnelAnalyzer };

package/dist/funnel/index.js

@@ -0,0 +1 @@
+import{FunnelAnalyzer as e}from"./analyzer.js";export{e as FunnelAnalyzer};

package/dist/growth/hypothesis-generator.d.ts

@@ -0,0 +1,17 @@
+import { GrowthHypothesis, GrowthMetric } from "../types.js";
+
+//#region src/growth/hypothesis-generator.d.ts
+interface HypothesisGeneratorOptions {
+  minDelta?: number;
+}
+declare class GrowthHypothesisGenerator {
+  private readonly minDelta;
+  constructor(options?: HypothesisGeneratorOptions);
+  generate(metrics: GrowthMetric[]): GrowthHypothesis[];
+  private fromMetric;
+  private delta;
+  private impact;
+  private statement;
+}
+//#endregion
+export { GrowthHypothesisGenerator, HypothesisGeneratorOptions };

package/dist/growth/hypothesis-generator.js

@@ -0,0 +1 @@
+var e=class{minDelta;constructor(e){this.minDelta=e?.minDelta??.05}generate(e){return e.map(e=>this.fromMetric(e)).filter(e=>!!e)}fromMetric(e){let t=this.delta(e);if(Math.abs(t)<this.minDelta)return null;let n=t>0?`rising`:`declining`;return{statement:this.statement(e,t,n),metric:e.name,confidence:Math.abs(t)>.2?`high`:`medium`,impact:this.impact(e)}}delta(e){if(e.previous==null)return 0;let t=e.previous||1;return(e.current-t)/Math.abs(t)}impact(e){return e.target&&e.current<e.target*.8?`high`:e.target&&e.current<e.target?`medium`:`low`}statement(e,t,n){let r=Math.abs(parseFloat((t*100).toFixed(1)));return n===`declining`?`${e.name} is down ${r}% vs last period; test new onboarding prompts to recover activation.`:`${e.name} grew ${r}% period-over-period; double down with expanded experiment or pricing test.`}};export{e as GrowthHypothesisGenerator};

package/dist/growth/index.d.ts

@@ -0,0 +1,2 @@
+import { GrowthHypothesisGenerator, HypothesisGeneratorOptions } from "./hypothesis-generator.js";
+export { GrowthHypothesisGenerator, HypothesisGeneratorOptions };

package/dist/growth/index.js

@@ -0,0 +1 @@
+import{GrowthHypothesisGenerator as e}from"./hypothesis-generator.js";export{e as GrowthHypothesisGenerator};

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { AnalyticsEvent, ChurnSignal, CohortAnalysis, CohortDefinition, CohortEvent, CohortStats, FunnelAnalysis, FunnelDefinition, FunnelStep, FunnelStepResult, GrowthHypothesis, GrowthMetric } from "./types.js";
+import { ChurnPredictor, ChurnPredictorOptions } from "./churn/predictor.js";
+import { CohortTracker } from "./cohort/tracker.js";
+import { FunnelAnalyzer } from "./funnel/analyzer.js";
+import { GrowthHypothesisGenerator, HypothesisGeneratorOptions } from "./growth/hypothesis-generator.js";
+import { LifecycleMetricSource, LifecycleStageChangePayload, collectLifecycleMetrics, createStageChangeEvent, lifecycleEventNames, metricsToSignals } from "./lifecycle/metric-collectors.js";
+import { PostHogLikeClient, trackLifecycleAssessment, trackLifecycleStageChange } from "./lifecycle/posthog-bridge.js";
+export { AnalyticsEvent, ChurnPredictor, ChurnPredictorOptions, ChurnSignal, CohortAnalysis, CohortDefinition, CohortEvent, CohortStats, CohortTracker, FunnelAnalysis, FunnelAnalyzer, FunnelDefinition, FunnelStep, FunnelStepResult, GrowthHypothesis, GrowthHypothesisGenerator, GrowthMetric, HypothesisGeneratorOptions, LifecycleMetricSource, LifecycleStageChangePayload, PostHogLikeClient, collectLifecycleMetrics, createStageChangeEvent, lifecycleEventNames, metricsToSignals, trackLifecycleAssessment, trackLifecycleStageChange };

package/dist/index.js

@@ -0,0 +1 @@
+import{FunnelAnalyzer as e}from"./funnel/analyzer.js";import{CohortTracker as t}from"./cohort/tracker.js";import"./cohort/index.js";import{ChurnPredictor as n}from"./churn/predictor.js";import"./churn/index.js";import{GrowthHypothesisGenerator as r}from"./growth/hypothesis-generator.js";import{collectLifecycleMetrics as i,createStageChangeEvent as a,lifecycleEventNames as o,metricsToSignals as s}from"./lifecycle/metric-collectors.js";import{trackLifecycleAssessment as c,trackLifecycleStageChange as l}from"./lifecycle/posthog-bridge.js";export{n as ChurnPredictor,t as CohortTracker,e as FunnelAnalyzer,r as GrowthHypothesisGenerator,i as collectLifecycleMetrics,a as createStageChangeEvent,o as lifecycleEventNames,s as metricsToSignals,c as trackLifecycleAssessment,l as trackLifecycleStageChange};

package/dist/lifecycle/index.d.ts

@@ -0,0 +1,3 @@
+import { LifecycleMetricSource, LifecycleStageChangePayload, collectLifecycleMetrics, createStageChangeEvent, lifecycleEventNames, metricsToSignals } from "./metric-collectors.js";
+import { PostHogLikeClient, trackLifecycleAssessment, trackLifecycleStageChange } from "./posthog-bridge.js";
+export { LifecycleMetricSource, LifecycleStageChangePayload, PostHogLikeClient, collectLifecycleMetrics, createStageChangeEvent, lifecycleEventNames, metricsToSignals, trackLifecycleAssessment, trackLifecycleStageChange };

package/dist/lifecycle/index.js

@@ -0,0 +1 @@
+import{collectLifecycleMetrics as e,createStageChangeEvent as t,lifecycleEventNames as n,metricsToSignals as r}from"./metric-collectors.js";import{trackLifecycleAssessment as i,trackLifecycleStageChange as a}from"./posthog-bridge.js";export{e as collectLifecycleMetrics,t as createStageChangeEvent,n as lifecycleEventNames,r as metricsToSignals,i as trackLifecycleAssessment,a as trackLifecycleStageChange};

package/dist/lifecycle/metric-collectors.d.ts

@@ -0,0 +1,29 @@
+import { AnalyticsEvent } from "../types.js";
+import { LifecycleMetricSnapshot, LifecycleSignal, LifecycleStage } from "@lssm/lib.lifecycle";
+
+//#region src/lifecycle/metric-collectors.d.ts
+interface LifecycleMetricSource {
+  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>;
+}
+declare const collectLifecycleMetrics: (source: LifecycleMetricSource) => Promise<LifecycleMetricSnapshot>;
+declare const metricsToSignals: (metrics: LifecycleMetricSnapshot, tenantId?: string) => LifecycleSignal[];
+declare const lifecycleEventNames: {
+  readonly assessmentRun: "lifecycle_assessment_run";
+  readonly stageChanged: "lifecycle_stage_changed";
+  readonly guidanceConsumed: "lifecycle_guidance_consumed";
+};
+interface LifecycleStageChangePayload {
+  tenantId?: string;
+  previousStage?: LifecycleStage;
+  nextStage: LifecycleStage;
+  confidence: number;
+}
+declare const createStageChangeEvent: (payload: LifecycleStageChangePayload) => AnalyticsEvent;
+//#endregion
+export { LifecycleMetricSource, LifecycleStageChangePayload, collectLifecycleMetrics, createStageChangeEvent, lifecycleEventNames, metricsToSignals };

package/dist/lifecycle/metric-collectors.js

@@ -0,0 +1 @@
+const e=async e=>{let[t,n,r,i,a,o,s]=await Promise.all([e.getActiveUsers(),e.getWeeklyActiveUsers?.(),e.getRetentionRate?.(),e.getMonthlyRecurringRevenue?.(),e.getCustomerCount?.(),e.getTeamSize?.(),e.getBurnMultiple?.()]);return{activeUsers:t,weeklyActiveUsers:n,retentionRate:r,monthlyRecurringRevenue:i,customerCount:a,teamSize:o,burnMultiple:s}},t=(e,t)=>Object.entries(e).filter(([,e])=>e!=null).map(([e,n])=>({id:`lifecycle-metric:${e}`,kind:`metric`,source:`analytics`,name:e,value:n,weight:1,confidence:.8,details:t?{tenantId:t}:void 0,capturedAt:new Date().toISOString()})),n={assessmentRun:`lifecycle_assessment_run`,stageChanged:`lifecycle_stage_changed`,guidanceConsumed:`lifecycle_guidance_consumed`},r=e=>({name:n.stageChanged,userId:`system`,tenantId:e.tenantId,timestamp:new Date,properties:{...e}});export{e as collectLifecycleMetrics,r as createStageChangeEvent,n as lifecycleEventNames,t as metricsToSignals};

package/dist/lifecycle/posthog-bridge.d.ts

@@ -0,0 +1,14 @@
+import { LifecycleAssessment } from "@lssm/lib.lifecycle";
+
+//#region src/lifecycle/posthog-bridge.d.ts
+interface PostHogLikeClient {
+  capture: (event: {
+    distinctId: string;
+    event: string;
+    properties?: Record<string, unknown>;
+  }) => Promise<void> | void;
+}
+declare const trackLifecycleAssessment: (client: PostHogLikeClient, tenantId: string, assessment: LifecycleAssessment) => Promise<void>;
+declare const trackLifecycleStageChange: (client: PostHogLikeClient, tenantId: string, previousStage: number | undefined, nextStage: number) => Promise<void>;
+//#endregion
+export { PostHogLikeClient, trackLifecycleAssessment, trackLifecycleStageChange };

package/dist/lifecycle/posthog-bridge.js

@@ -0,0 +1 @@
+import{lifecycleEventNames as e}from"./metric-collectors.js";const t=async(t,n,r)=>{await t.capture({distinctId:n,event:e.assessmentRun,properties:{stage:r.stage,confidence:r.confidence,axes:r.axes}})},n=async(t,n,r,i)=>{await t.capture({distinctId:n,event:e.stageChanged,properties:{previousStage:r,nextStage:i}})};export{t as trackLifecycleAssessment,n as trackLifecycleStageChange};

package/dist/types.d.ts

@@ -0,0 +1,67 @@
+//#region src/types.d.ts
+interface AnalyticsEvent {
+  name: string;
+  userId: string;
+  tenantId?: string;
+  timestamp: string | Date;
+  properties?: Record<string, unknown>;
+}
+interface FunnelStep {
+  id: string;
+  eventName: string;
+  match?: (event: AnalyticsEvent) => boolean;
+}
+interface FunnelDefinition {
+  name: string;
+  steps: FunnelStep[];
+  windowHours?: number;
+}
+interface FunnelStepResult {
+  step: FunnelStep;
+  count: number;
+  conversionRate: number;
+  dropOffRate: number;
+}
+interface FunnelAnalysis {
+  definition: FunnelDefinition;
+  totalUsers: number;
+  steps: FunnelStepResult[];
+}
+interface CohortEvent extends AnalyticsEvent {
+  amount?: number;
+}
+interface CohortDefinition {
+  bucket: 'day' | 'week' | 'month';
+  periods: number;
+  startDate?: Date;
+}
+interface CohortStats {
+  cohortKey: string;
+  users: number;
+  retention: number[];
+  ltv: number;
+}
+interface CohortAnalysis {
+  definition: CohortDefinition;
+  cohorts: CohortStats[];
+}
+interface ChurnSignal {
+  userId: string;
+  score: number;
+  bucket: 'low' | 'medium' | 'high';
+  drivers: string[];
+}
+interface GrowthMetric {
+  name: string;
+  current: number;
+  previous?: number;
+  target?: number;
+}
+interface GrowthHypothesis {
+  statement: string;
+  metric: string;
+  confidence: 'low' | 'medium' | 'high';
+  impact: 'low' | 'medium' | 'high';
+}
+//#endregion
+export { AnalyticsEvent, ChurnSignal, CohortAnalysis, CohortDefinition, CohortEvent, CohortStats, FunnelAnalysis, FunnelDefinition, FunnelStep, FunnelStepResult, GrowthHypothesis, GrowthMetric };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@lssm/lib.analytics",
+  "version": "0.0.0-canary-20251206160926",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "publish:pkg": "bun publish --tolerate-republish --ignore-scripts --verbose",
+    "build": "bun build:bundle && bun build:types",
+    "build:bundle": "tsdown",
+    "build:types": "tsc --noEmit",
+    "dev": "bun build:bundle --watch",
+    "clean": "rimraf dist .turbo",
+    "lint": "bun lint:fix",
+    "lint:fix": "eslint src --fix",
+    "lint:check": "eslint src",
+    "test": "bun run"
+  },
+  "dependencies": {
+    "@lssm/lib.lifecycle": "workspace:*",
+    "dayjs": "^1.11.13"
+  },
+  "devDependencies": {
+    "@lssm/tool.tsdown": "workspace:*",
+    "@lssm/tool.typescript": "workspace:*",
+    "tsdown": "^0.17.0",
+    "typescript": "^5.9.3"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./churn": "./dist/churn/index.js",
+    "./churn/predictor": "./dist/churn/predictor.js",
+    "./cohort": "./dist/cohort/index.js",
+    "./cohort/tracker": "./dist/cohort/tracker.js",
+    "./funnel": "./dist/funnel/index.js",
+    "./funnel/analyzer": "./dist/funnel/analyzer.js",
+    "./growth": "./dist/growth/index.js",
+    "./growth/hypothesis-generator": "./dist/growth/hypothesis-generator.js",
+    "./lifecycle": "./dist/lifecycle/index.js",
+    "./lifecycle/metric-collectors": "./dist/lifecycle/metric-collectors.js",
+    "./lifecycle/posthog-bridge": "./dist/lifecycle/posthog-bridge.js",
+    "./types": "./dist/types.js",
+    "./*": "./*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}