@contractspec/lib.analytics 1.56.0 → 1.57.0

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

@@ -1 +1 @@
-{"version":3,"file":"predictor.d.ts","names":[],"sources":["../../src/churn/predictor.ts"],"sourcesContent":[],"mappings":";;;UAGiB,qBAAA;;EAAA,eAAA,CAAA,EAAA,MAAqB;EAOzB,WAAA,CAAA,EAAA,MAAc;EAMH,SAAA,CAAA,EAAA,MAAA;;AAOW,cAbtB,cAAA,CAasB;EAAW,iBAAA,aAAA;;;;wBAPtB;gBAOR,mBAAmB"}
+{"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"tracker.d.ts","names":[],"sources":["../../src/cohort/tracker.ts"],"sourcesContent":[],"mappings":";;;cAQa,aAAA;kBAED,8BACI,mBACX;AAJL"}
+{"version":3,"file":"tracker.d.ts","names":[],"sources":["../../src/cohort/tracker.ts"],"mappings":";;;cAQa,aAAA;EACX,OAAA,CACE,MAAA,EAAQ,cAAA,IACR,UAAA,EAAY,gBAAA,GACX,cAAA;AAAA"}

package/dist/cohort/tracker.js

@@ -71,7 +71,6 @@ function bucketKey(timestamp, bucket) {
 	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");
 	}
 }
@@ -81,7 +80,6 @@ function bucketDiff(cohortKey, timestamp, bucket) {
 	switch (bucket) {
 		case "day": return target.diff(start, "day");
 		case "week": return target.diff(start, "week");
-		case "month":
 		default: return target.diff(start, "month");
 	}
 }
@@ -89,7 +87,6 @@ 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");
 	}
 }

package/dist/cohort/tracker.js.map

@@ -1 +1 @@
-{"version":3,"file":"tracker.js","names":[],"sources":["../../src/cohort/tracker.ts"],"sourcesContent":["import dayjs from 'dayjs';\nimport type {\n  AnalyticsEvent,\n  CohortAnalysis,\n  CohortDefinition,\n  CohortStats,\n} from '../types';\n\nexport class CohortTracker {\n  analyze(\n    events: AnalyticsEvent[],\n    definition: CohortDefinition\n  ): CohortAnalysis {\n    const groupedByUser = groupBy(events, (event) => event.userId);\n    const cohorts = new Map<string, CohortStatsBuilder>();\n\n    for (const [userId, userEvents] of groupedByUser.entries()) {\n      userEvents.sort((a, b) => dateMs(a) - dateMs(b));\n      const signup = userEvents[0];\n      if (!signup) continue;\n      const cohortKey = bucketKey(signup.timestamp, definition.bucket);\n      const builder =\n        cohorts.get(cohortKey) ?? new CohortStatsBuilder(cohortKey, definition);\n      builder.addUser(userId);\n      for (const event of userEvents) {\n        builder.addEvent(userId, event);\n      }\n      cohorts.set(cohortKey, builder);\n    }\n\n    return {\n      definition,\n      cohorts: [...cohorts.values()].map((builder) => builder.build()),\n    };\n  }\n}\n\nclass CohortStatsBuilder {\n  private readonly users = new Set<string>();\n  private readonly retentionMap = new Map<number, Set<string>>();\n  private ltv = 0;\n  constructor(\n    private readonly key: string,\n    private readonly definition: CohortDefinition\n  ) {}\n\n  addUser(userId: string) {\n    this.users.add(userId);\n  }\n\n  addEvent(userId: string, event: AnalyticsEvent) {\n    const period = bucketDiff(\n      this.key,\n      event.timestamp,\n      this.definition.bucket\n    );\n    if (period < 0 || period >= this.definition.periods) return;\n    const bucket = this.retentionMap.get(period) ?? new Set<string>();\n    bucket.add(userId);\n    this.retentionMap.set(period, bucket);\n    const amount =\n      typeof event.properties?.amount === 'number'\n        ? event.properties.amount\n        : 0;\n    this.ltv += amount;\n  }\n\n  build(): CohortStats {\n    const totalUsers = this.users.size || 1;\n    const retention: number[] = [];\n    for (let period = 0; period < this.definition.periods; period++) {\n      const active = this.retentionMap.get(period)?.size ?? 0;\n      retention.push(Number((active / totalUsers).toFixed(3)));\n    }\n    return {\n      cohortKey: this.key,\n      users: this.users.size,\n      retention,\n      ltv: Number(this.ltv.toFixed(2)),\n    };\n  }\n}\n\nfunction groupBy<T>(\n  items: T[],\n  selector: (item: T) => string\n): Map<string, T[]> {\n  const map = new Map<string, T[]>();\n  for (const item of items) {\n    const key = selector(item);\n    const list = map.get(key) ?? [];\n    list.push(item);\n    map.set(key, list);\n  }\n  return map;\n}\n\nfunction bucketKey(\n  timestamp: string | Date,\n  bucket: CohortDefinition['bucket']\n): string {\n  const dt = dayjs(timestamp);\n  switch (bucket) {\n    case 'day':\n      return dt.startOf('day').format('YYYY-MM-DD');\n    case 'week':\n      return dt.startOf('week').format('YYYY-[W]WW');\n    case 'month':\n    default:\n      return dt.startOf('month').format('YYYY-MM');\n  }\n}\n\nfunction bucketDiff(\n  cohortKey: string,\n  timestamp: string | Date,\n  bucket: CohortDefinition['bucket']\n): number {\n  const start = parseBucketKey(cohortKey, bucket);\n  const target = dayjs(timestamp);\n  switch (bucket) {\n    case 'day':\n      return target.diff(start, 'day');\n    case 'week':\n      return target.diff(start, 'week');\n    case 'month':\n    default:\n      return target.diff(start, 'month');\n  }\n}\n\nfunction parseBucketKey(key: string, bucket: CohortDefinition['bucket']) {\n  switch (bucket) {\n    case 'day':\n      return dayjs(key, 'YYYY-MM-DD');\n    case 'week':\n      return dayjs(key.replace('W', ''), 'YYYY-ww');\n    case 'month':\n    default:\n      return dayjs(key, 'YYYY-MM');\n  }\n}\n\nfunction dateMs(event: AnalyticsEvent) {\n  return new Date(event.timestamp).getTime();\n}\n"],"mappings":"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"}
+{"version":3,"file":"tracker.js","names":[],"sources":["../../src/cohort/tracker.ts"],"sourcesContent":["import dayjs from 'dayjs';\nimport type {\n  AnalyticsEvent,\n  CohortAnalysis,\n  CohortDefinition,\n  CohortStats,\n} from '../types';\n\nexport class CohortTracker {\n  analyze(\n    events: AnalyticsEvent[],\n    definition: CohortDefinition\n  ): CohortAnalysis {\n    const groupedByUser = groupBy(events, (event) => event.userId);\n    const cohorts = new Map<string, CohortStatsBuilder>();\n\n    for (const [userId, userEvents] of groupedByUser.entries()) {\n      userEvents.sort((a, b) => dateMs(a) - dateMs(b));\n      const signup = userEvents[0];\n      if (!signup) continue;\n      const cohortKey = bucketKey(signup.timestamp, definition.bucket);\n      const builder =\n        cohorts.get(cohortKey) ?? new CohortStatsBuilder(cohortKey, definition);\n      builder.addUser(userId);\n      for (const event of userEvents) {\n        builder.addEvent(userId, event);\n      }\n      cohorts.set(cohortKey, builder);\n    }\n\n    return {\n      definition,\n      cohorts: [...cohorts.values()].map((builder) => builder.build()),\n    };\n  }\n}\n\nclass CohortStatsBuilder {\n  private readonly users = new Set<string>();\n  private readonly retentionMap = new Map<number, Set<string>>();\n  private ltv = 0;\n  constructor(\n    private readonly key: string,\n    private readonly definition: CohortDefinition\n  ) {}\n\n  addUser(userId: string) {\n    this.users.add(userId);\n  }\n\n  addEvent(userId: string, event: AnalyticsEvent) {\n    const period = bucketDiff(\n      this.key,\n      event.timestamp,\n      this.definition.bucket\n    );\n    if (period < 0 || period >= this.definition.periods) return;\n    const bucket = this.retentionMap.get(period) ?? new Set<string>();\n    bucket.add(userId);\n    this.retentionMap.set(period, bucket);\n    const amount =\n      typeof event.properties?.amount === 'number'\n        ? event.properties.amount\n        : 0;\n    this.ltv += amount;\n  }\n\n  build(): CohortStats {\n    const totalUsers = this.users.size || 1;\n    const retention: number[] = [];\n    for (let period = 0; period < this.definition.periods; period++) {\n      const active = this.retentionMap.get(period)?.size ?? 0;\n      retention.push(Number((active / totalUsers).toFixed(3)));\n    }\n    return {\n      cohortKey: this.key,\n      users: this.users.size,\n      retention,\n      ltv: Number(this.ltv.toFixed(2)),\n    };\n  }\n}\n\nfunction groupBy<T>(\n  items: T[],\n  selector: (item: T) => string\n): Map<string, T[]> {\n  const map = new Map<string, T[]>();\n  for (const item of items) {\n    const key = selector(item);\n    const list = map.get(key) ?? [];\n    list.push(item);\n    map.set(key, list);\n  }\n  return map;\n}\n\nfunction bucketKey(\n  timestamp: string | Date,\n  bucket: CohortDefinition['bucket']\n): string {\n  const dt = dayjs(timestamp);\n  switch (bucket) {\n    case 'day':\n      return dt.startOf('day').format('YYYY-MM-DD');\n    case 'week':\n      return dt.startOf('week').format('YYYY-[W]WW');\n    case 'month':\n    default:\n      return dt.startOf('month').format('YYYY-MM');\n  }\n}\n\nfunction bucketDiff(\n  cohortKey: string,\n  timestamp: string | Date,\n  bucket: CohortDefinition['bucket']\n): number {\n  const start = parseBucketKey(cohortKey, bucket);\n  const target = dayjs(timestamp);\n  switch (bucket) {\n    case 'day':\n      return target.diff(start, 'day');\n    case 'week':\n      return target.diff(start, 'week');\n    case 'month':\n    default:\n      return target.diff(start, 'month');\n  }\n}\n\nfunction parseBucketKey(key: string, bucket: CohortDefinition['bucket']) {\n  switch (bucket) {\n    case 'day':\n      return dayjs(key, 'YYYY-MM-DD');\n    case 'week':\n      return dayjs(key.replace('W', ''), 'YYYY-ww');\n    case 'month':\n    default:\n      return dayjs(key, 'YYYY-MM');\n  }\n}\n\nfunction dateMs(event: AnalyticsEvent) {\n  return new Date(event.timestamp).getTime();\n}\n"],"mappings":"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"}

package/dist/funnel/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","names":[],"sources":["../../src/funnel/analyzer.ts"],"sourcesContent":[],"mappings":";;;cAQa,cAAA;kBAED,8BACI,mBACX;EAJQ,QAAA,YAAc"}
+{"version":3,"file":"analyzer.d.ts","names":[],"sources":["../../src/funnel/analyzer.ts"],"mappings":";;;cAQa,cAAA;EACX,OAAA,CACE,MAAA,EAAQ,cAAA,IACR,UAAA,EAAY,gBAAA,GACX,cAAA;EAAA,QAmCK,YAAA;AAAA"}

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

@@ -1 +1 @@
-{"version":3,"file":"hypothesis-generator.d.ts","names":[],"sources":["../../src/growth/hypothesis-generator.ts"],"sourcesContent":[],"mappings":";;;UAEiB,0BAAA;;AAAjB;AAIa,cAAA,yBAAA,CAAyB;EAGd,iBAAA,QAAA;EAIJ,WAAA,CAAA,OAAA,CAAA,EAJI,0BAIJ;EAAiB,QAAA,CAAA,OAAA,EAAjB,YAAiB,EAAA,CAAA,EAAA,gBAAA,EAAA;EAAgB,QAAA,UAAA"}
+{"version":3,"file":"hypothesis-generator.d.ts","names":[],"sources":["../../src/growth/hypothesis-generator.ts"],"mappings":";;;UAEiB,0BAAA;EACf,QAAA;AAAA;AAAA,cAGW,yBAAA;EAAA,iBACM,QAAA;cAEL,OAAA,GAAU,0BAAA;EAItB,QAAA,CAAS,OAAA,EAAS,YAAA,KAAiB,gBAAA;EAAA,QAQ3B,UAAA;EAAA,QAaA,KAAA;EAAA,QAMA,MAAA;EAAA,QAMA,SAAA;AAAA"}

package/dist/index.d.ts

@@ -5,4 +5,6 @@ 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 };
+import { PosthogLifecycleMetricSource, PosthogLifecycleMetricSourceOptions } from "./lifecycle/posthog-metric-source.js";
+import { PosthogAnalyticsEventSource, PosthogAnalyticsEventSourceOptions } from "./posthog/event-source.js";
+export { AnalyticsEvent, ChurnPredictor, ChurnPredictorOptions, ChurnSignal, CohortAnalysis, CohortDefinition, CohortEvent, CohortStats, CohortTracker, FunnelAnalysis, FunnelAnalyzer, FunnelDefinition, FunnelStep, FunnelStepResult, GrowthHypothesis, GrowthHypothesisGenerator, GrowthMetric, HypothesisGeneratorOptions, LifecycleMetricSource, LifecycleStageChangePayload, PostHogLikeClient, PosthogAnalyticsEventSource, PosthogAnalyticsEventSourceOptions, PosthogLifecycleMetricSource, PosthogLifecycleMetricSourceOptions, collectLifecycleMetrics, createStageChangeEvent, lifecycleEventNames, metricsToSignals, trackLifecycleAssessment, trackLifecycleStageChange };

package/dist/index.js

@@ -6,5 +6,7 @@ import "./churn/index.js";
 import { GrowthHypothesisGenerator } from "./growth/hypothesis-generator.js";
 import { collectLifecycleMetrics, createStageChangeEvent, lifecycleEventNames, metricsToSignals } from "./lifecycle/metric-collectors.js";
 import { trackLifecycleAssessment, trackLifecycleStageChange } from "./lifecycle/posthog-bridge.js";
+import { PosthogLifecycleMetricSource } from "./lifecycle/posthog-metric-source.js";
+import { PosthogAnalyticsEventSource } from "./posthog/event-source.js";
 
-export { ChurnPredictor, CohortTracker, FunnelAnalyzer, GrowthHypothesisGenerator, collectLifecycleMetrics, createStageChangeEvent, lifecycleEventNames, metricsToSignals, trackLifecycleAssessment, trackLifecycleStageChange };
+export { ChurnPredictor, CohortTracker, FunnelAnalyzer, GrowthHypothesisGenerator, PosthogAnalyticsEventSource, PosthogLifecycleMetricSource, collectLifecycleMetrics, createStageChangeEvent, lifecycleEventNames, metricsToSignals, trackLifecycleAssessment, trackLifecycleStageChange };

package/dist/lifecycle/index.d.ts

@@ -1,3 +1,4 @@
 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 };
+import { PosthogLifecycleMetricSource, PosthogLifecycleMetricSourceOptions } from "./posthog-metric-source.js";
+export { LifecycleMetricSource, LifecycleStageChangePayload, PostHogLikeClient, PosthogLifecycleMetricSource, PosthogLifecycleMetricSourceOptions, collectLifecycleMetrics, createStageChangeEvent, lifecycleEventNames, metricsToSignals, trackLifecycleAssessment, trackLifecycleStageChange };

package/dist/lifecycle/index.js

@@ -1,4 +1,5 @@
 import { collectLifecycleMetrics, createStageChangeEvent, lifecycleEventNames, metricsToSignals } from "./metric-collectors.js";
 import { trackLifecycleAssessment, trackLifecycleStageChange } from "./posthog-bridge.js";
+import { PosthogLifecycleMetricSource } from "./posthog-metric-source.js";
 
-export { collectLifecycleMetrics, createStageChangeEvent, lifecycleEventNames, metricsToSignals, trackLifecycleAssessment, trackLifecycleStageChange };
+export { PosthogLifecycleMetricSource, collectLifecycleMetrics, createStageChangeEvent, lifecycleEventNames, metricsToSignals, trackLifecycleAssessment, trackLifecycleStageChange };

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

@@ -1 +1 @@
-{"version":3,"file":"metric-collectors.d.ts","names":[],"sources":["../../src/lifecycle/metric-collectors.ts"],"sourcesContent":[],"mappings":";;;;UAOiB,qBAAA;oBACG;EADH,oBAAA,GAAA,EAEU,OAFW,CAAA,MAAA,GAAA,SAAA,CAAA;EAClB,gBAAA,GAAA,EAEG,OAFH,CAAA,MAAA,GAAA,SAAA,CAAA;EACO,0BAAA,GAAA,EAEM,OAFN,CAAA,MAAA,GAAA,SAAA,CAAA;EACJ,gBAAA,GAAA,EAEA,OAFA,CAAA,MAAA,GAAA,SAAA,CAAA;EACU,WAAA,GAAA,EAEf,OAFe,CAAA,MAAA,GAAA,SAAA,CAAA;EACV,eAAA,GAAA,EAED,OAFC,CAAA,MAAA,GAAA,SAAA,CAAA;;AAED,cAGT,uBAHS,EAAA,CAAA,MAAA,EAIZ,qBAJY,EAAA,GAKnB,OALmB,CAKX,uBALW,CAAA;AAAO,cAmChB,gBAnCgB,EAAA,CAAA,OAAA,EAoClB,uBApCkB,EAAA,QAAA,CAAA,EAAA,MAAA,EAAA,GAsC1B,eAtC0B,EAAA;AAGhB,cAkDA,mBApBZ,EAAA;EA7BS,SAAA,aAAA,EAAA,0BAAA;EACC,SAAA,YAAA,EAAA,yBAAA;EAAR,SAAA,gBAAA,EAAA,6BAAA;CAAO;AA8BG,UAwBI,2BAAA,CAvBN;EAiBE,QAAA,CAAA,EAAA,MAAA;EAMI,aAAA,CAAA,EAEC,cAF0B;EAO/B,SAAA,EAJA,cAYX;;;cARW,kCACF,gCACR"}
+{"version":3,"file":"metric-collectors.d.ts","names":[],"sources":["../../src/lifecycle/metric-collectors.ts"],"mappings":";;;;UAOiB,qBAAA;EACf,cAAA,IAAkB,OAAA;EAClB,oBAAA,KAAyB,OAAA;EACzB,gBAAA,KAAqB,OAAA;EACrB,0BAAA,KAA+B,OAAA;EAC/B,gBAAA,KAAqB,OAAA;EACrB,WAAA,KAAgB,OAAA;EAChB,eAAA,KAAoB,OAAA;AAAA;AAAA,cAGT,uBAAA,GACX,MAAA,EAAQ,qBAAA,KACP,OAAA,CAAQ,uBAAA;AAAA,cA8BE,gBAAA,GACX,OAAA,EAAS,uBAAA,EACT,QAAA,cACC,eAAA;AAAA,cAeU,mBAAA;EAAA;;;;UAMI,2BAAA;EACf,QAAA;EACA,aAAA,GAAgB,cAAA;EAChB,SAAA,EAAW,cAAA;EACX,UAAA;AAAA;AAAA,cAGW,sBAAA,GACX,OAAA,EAAS,2BAAA,KACR,cAAA"}

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

@@ -1 +1 @@
-{"version":3,"file":"posthog-bridge.d.ts","names":[],"sources":["../../src/lifecycle/posthog-bridge.ts"],"sourcesContent":[],"mappings":";;;UAGiB,iBAAA;;IAAA,UAAA,EAAA,MAAiB;IAQrB,KAAA,EAAA,MAAA;IACH,UAAA,CAAA,EALO,MAKP,CAAA,MAAA,EAAA,OAAA,CAAA;EAEI,CAAA,EAAA,GANN,OAMM,CAAA,IAAA,CAAA,GAAA,IAAA;;AAAmB,cAHpB,wBAGoB,EAAA,CAAA,MAAA,EAFvB,iBAEuB,EAAA,QAAA,EAAA,MAAA,EAAA,UAAA,EAAnB,mBAAmB,EAAA,GAAA,OAAA,CAAA,IAAA,CAAA;AAapB,cAAA,yBACH,EAAA,CAAA,MAAA,EAAA,iBAGS,EAAA,QAAA,EAAA,MAAA,EAAA,aAAA,EAAA,MAAA,GAAA,SAAA,EAAA,SAAA,EAAA,MAAA,EAAA,GAAA,OAAA,CAAA,IAAA,CAAA"}
+{"version":3,"file":"posthog-bridge.d.ts","names":[],"sources":["../../src/lifecycle/posthog-bridge.ts"],"mappings":";;;UAGiB,iBAAA;EACf,OAAA,GAAU,KAAA;IACR,UAAA;IACA,KAAA;IACA,UAAA,GAAa,MAAA;EAAA,MACT,OAAA;AAAA;AAAA,cAGK,wBAAA,GACX,MAAA,EAAQ,iBAAA,EACR,QAAA,UACA,UAAA,EAAY,mBAAA,KAAmB,OAAA;AAAA,cAapB,yBAAA,GACX,MAAA,EAAQ,iBAAA,EACR,QAAA,UACA,aAAA,sBACA,SAAA,aAAiB,OAAA"}

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

@@ -0,0 +1,47 @@
+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;
+}
+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

@@ -0,0 +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"}

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

@@ -0,0 +1,186 @@
+//#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);
+	}
+};
+function buildDateRange(days) {
+	const to = /* @__PURE__ */ new Date();
+	return {
+		from: /* @__PURE__ */ new Date(to.getTime() - days * 24 * 60 * 60 * 1e3),
+		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
+	};
+}
+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;
+		}
+	}
+}
+
+//#endregion
+export { PosthogLifecycleMetricSource };
+//# sourceMappingURL=posthog-metric-source.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"posthog-metric-source.js","names":[],"sources":["../../src/lifecycle/posthog-metric-source.ts"],"sourcesContent":["import type {\n  AnalyticsQueryResult,\n  AnalyticsReader,\n} from '@contractspec/lib.contracts/integrations/providers/analytics';\nimport type { LifecycleMetricSource } from './metric-collectors';\n\nexport interface PosthogLifecycleMetricSourceOptions {\n  activityEvents?: string[];\n  retentionWindowDays?: number;\n  revenueEvent?: string;\n  revenueProperty?: string;\n  customerEvent?: string;\n  customerProperty?: string;\n  teamSizeEvent?: string;\n  teamSizeProperty?: string;\n  burnMultipleEvent?: string;\n  burnMultipleProperty?: string;\n}\n\nexport class PosthogLifecycleMetricSource implements LifecycleMetricSource {\n  private readonly reader: AnalyticsReader;\n  private readonly activityEvents?: string[];\n  private readonly retentionWindowDays: number;\n  private readonly revenueEvent?: string;\n  private readonly revenueProperty?: string;\n  private readonly customerEvent?: string;\n  private readonly customerProperty?: string;\n  private readonly teamSizeEvent?: string;\n  private readonly teamSizeProperty?: string;\n  private readonly burnMultipleEvent?: string;\n  private readonly burnMultipleProperty?: string;\n\n  constructor(\n    reader: AnalyticsReader,\n    options: PosthogLifecycleMetricSourceOptions = {}\n  ) {\n    this.reader = reader;\n    this.activityEvents = options.activityEvents;\n    this.retentionWindowDays = options.retentionWindowDays ?? 7;\n    this.revenueEvent = options.revenueEvent;\n    this.revenueProperty = options.revenueProperty ?? 'amount';\n    this.customerEvent = options.customerEvent;\n    this.customerProperty = options.customerProperty ?? 'is_customer';\n    this.teamSizeEvent = options.teamSizeEvent;\n    this.teamSizeProperty = options.teamSizeProperty ?? 'team_size';\n    this.burnMultipleEvent = options.burnMultipleEvent;\n    this.burnMultipleProperty = options.burnMultipleProperty ?? 'burn_multiple';\n  }\n\n  async getActiveUsers(): Promise<number | undefined> {\n    return this.countDistinctUsers(1);\n  }\n\n  async getWeeklyActiveUsers(): Promise<number | undefined> {\n    return this.countDistinctUsers(7);\n  }\n\n  async getRetentionRate(): Promise<number | undefined> {\n    const windowDays = this.retentionWindowDays;\n    const now = new Date();\n    const prevEnd = new Date(now.getTime() - windowDays * 24 * 60 * 60 * 1000);\n    const prevStart = new Date(\n      now.getTime() - windowDays * 2 * 24 * 60 * 60 * 1000\n    );\n\n    const returningUsers = await this.countReturningUsers(\n      prevStart,\n      prevEnd,\n      now\n    );\n    const prevUsers = await this.countDistinctUsersBetween(prevStart, prevEnd);\n    if (prevUsers === undefined || prevUsers === 0) return undefined;\n    return returningUsers / prevUsers;\n  }\n\n  async getMonthlyRecurringRevenue(): Promise<number | undefined> {\n    if (!this.revenueEvent || !this.revenueProperty) return undefined;\n    return this.sumMetric(this.revenueEvent, this.revenueProperty);\n  }\n\n  async getCustomerCount(): Promise<number | undefined> {\n    if (!this.customerEvent || !this.customerProperty) return undefined;\n    return this.countDistinctUsersByProperty(\n      this.customerEvent,\n      this.customerProperty\n    );\n  }\n\n  async getTeamSize(): Promise<number | undefined> {\n    if (!this.teamSizeEvent || !this.teamSizeProperty) return undefined;\n    return this.latestMetric(this.teamSizeEvent, this.teamSizeProperty);\n  }\n\n  async getBurnMultiple(): Promise<number | undefined> {\n    if (!this.burnMultipleEvent || !this.burnMultipleProperty) return undefined;\n    return this.latestMetric(this.burnMultipleEvent, this.burnMultipleProperty);\n  }\n\n  private async countDistinctUsers(days: number): Promise<number | undefined> {\n    const range = buildDateRange(days);\n    return this.countDistinctUsersBetween(range.from, range.to);\n  }\n\n  private async countDistinctUsersBetween(\n    from: Date,\n    to: Date\n  ): Promise<number | undefined> {\n    const eventFilter = buildEventFilter(this.activityEvents, 'activityEvent');\n    const result = await this.queryHogQL({\n      query: [\n        'select',\n        '  countDistinct(distinct_id) as total',\n        'from events',\n        `where timestamp >= {dateFrom} and timestamp < {dateTo}`,\n        eventFilter.clause ? `and ${eventFilter.clause}` : '',\n      ]\n        .filter(Boolean)\n        .join('\\n'),\n      values: {\n        dateFrom: from.toISOString(),\n        dateTo: to.toISOString(),\n        ...eventFilter.values,\n      },\n    });\n    return readSingleNumber(result);\n  }\n\n  private async countReturningUsers(\n    previousStart: Date,\n    previousEnd: Date,\n    currentEnd: Date\n  ): Promise<number> {\n    const eventFilter = buildEventFilter(this.activityEvents, 'activityEvent');\n    const result = await this.queryHogQL({\n      query: [\n        'select',\n        '  countDistinct(distinct_id) as total',\n        'from events',\n        `where timestamp >= {currentFrom} and timestamp < {currentTo}`,\n        eventFilter.clause ? `and ${eventFilter.clause}` : '',\n        'and distinct_id in (',\n        '  select distinct_id from events',\n        '  where timestamp >= {previousFrom} and timestamp < {previousTo}',\n        eventFilter.clause ? `and ${eventFilter.clause}` : '',\n        ')',\n      ].join('\\n'),\n      values: {\n        currentFrom: previousEnd.toISOString(),\n        currentTo: currentEnd.toISOString(),\n        previousFrom: previousStart.toISOString(),\n        previousTo: previousEnd.toISOString(),\n        ...eventFilter.values,\n      },\n    });\n    return readSingleNumber(result) ?? 0;\n  }\n\n  private async sumMetric(\n    eventName: string,\n    propertyKey: string\n  ): Promise<number | undefined> {\n    const result = await this.queryHogQL({\n      query: [\n        'select',\n        `  sum(properties.${propertyKey}) as total`,\n        'from events',\n        'where event = {eventName}',\n      ].join('\\n'),\n      values: { eventName },\n    });\n    return readSingleNumber(result);\n  }\n\n  private async countDistinctUsersByProperty(\n    eventName: string,\n    propertyKey: string\n  ): Promise<number | undefined> {\n    const result = await this.queryHogQL({\n      query: [\n        'select',\n        '  countDistinct(distinct_id) as total',\n        'from events',\n        'where event = {eventName}',\n        `and properties.${propertyKey} = {propertyValue}`,\n      ].join('\\n'),\n      values: { eventName, propertyValue: true },\n    });\n    return readSingleNumber(result);\n  }\n\n  private async latestMetric(\n    eventName: string,\n    propertyKey: string\n  ): Promise<number | undefined> {\n    const result = await this.queryHogQL({\n      query: [\n        'select',\n        `  properties.${propertyKey} as value`,\n        'from events',\n        'where event = {eventName}',\n        'order by timestamp desc',\n        'limit 1',\n      ].join('\\n'),\n      values: { eventName },\n    });\n    return readSingleNumber(result);\n  }\n\n  private async queryHogQL(input: {\n    query: string;\n    values: Record<string, unknown>;\n  }): Promise<AnalyticsQueryResult> {\n    if (!this.reader.queryHogQL) {\n      throw new Error('Analytics reader does not support HogQL queries.');\n    }\n    return this.reader.queryHogQL(input);\n  }\n}\n\nfunction buildDateRange(days: number): { from: Date; to: Date } {\n  const to = new Date();\n  const from = new Date(to.getTime() - days * 24 * 60 * 60 * 1000);\n  return { from, to };\n}\n\nfunction buildEventFilter(\n  events: string[] | undefined,\n  prefix: string\n): { clause?: string; values?: Record<string, unknown> } {\n  if (!events || events.length === 0) return {};\n  if (events.length === 1) {\n    return {\n      clause: `event = {${prefix}0}`,\n      values: { [`${prefix}0`]: events[0] },\n    };\n  }\n  const clauses = events.map((_event, index) => `event = {${prefix}${index}}`);\n  const values: Record<string, unknown> = {};\n  events.forEach((event, index) => {\n    values[`${prefix}${index}`] = event;\n  });\n  return {\n    clause: `(${clauses.join(' or ')})`,\n    values,\n  };\n}\n\nfunction readSingleNumber(result: AnalyticsQueryResult): number | undefined {\n  if (!Array.isArray(result.results) || result.results.length === 0) {\n    return undefined;\n  }\n  const firstRow = result.results[0];\n  if (Array.isArray(firstRow) && firstRow.length > 0) {\n    const value = firstRow[0];\n    if (typeof value === 'number' && Number.isFinite(value)) return value;\n    if (typeof value === 'string' && value.trim()) {\n      const parsed = Number(value);\n      if (Number.isFinite(parsed)) return parsed;\n    }\n  }\n  return undefined;\n}\n"],"mappings":"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"}

package/dist/posthog/event-source.d.ts

@@ -0,0 +1,25 @@
+import { AnalyticsEvent, CohortDefinition, FunnelDefinition, GrowthMetric } from "../types.js";
+import { AnalyticsReader, DateRangeInput } from "@contractspec/lib.contracts/integrations/providers/analytics";
+
+//#region src/posthog/event-source.d.ts
+interface PosthogAnalyticsEventSourceOptions {
+  limitPerEvent?: number;
+  tenantPropertyKey?: string;
+  defaultRangeDays?: number;
+}
+declare class PosthogAnalyticsEventSource {
+  private readonly reader;
+  private readonly limitPerEvent;
+  private readonly tenantPropertyKey;
+  private readonly defaultRangeDays;
+  constructor(reader: AnalyticsReader, options?: PosthogAnalyticsEventSourceOptions);
+  getEventsForFunnel(definition: FunnelDefinition, dateRange?: DateRangeInput): Promise<AnalyticsEvent[]>;
+  getEventsForCohort(definition: CohortDefinition, dateRange?: DateRangeInput, eventNames?: string[]): Promise<AnalyticsEvent[]>;
+  getUserActivity(userId: string, dateRange?: DateRangeInput, limit?: number): Promise<AnalyticsEvent[]>;
+  getGrowthMetrics(metricNames: string[], dateRange?: DateRangeInput): Promise<GrowthMetric[]>;
+  private getEventsByNames;
+  private countEvents;
+}
+//#endregion
+export { PosthogAnalyticsEventSource, PosthogAnalyticsEventSourceOptions };
+//# sourceMappingURL=event-source.d.ts.map

package/dist/posthog/event-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-source.d.ts","names":[],"sources":["../../src/posthog/event-source.ts"],"mappings":";;;;UAWiB,kCAAA;EACf,aAAA;EACA,iBAAA;EACA,gBAAA;AAAA;AAAA,cAGW,2BAAA;EAAA,iBACM,MAAA;EAAA,iBACA,aAAA;EAAA,iBACA,iBAAA;EAAA,iBACA,gBAAA;cAGf,MAAA,EAAQ,eAAA,EACR,OAAA,GAAS,kCAAA;EAQL,kBAAA,CACJ,UAAA,EAAY,gBAAA,EACZ,SAAA,GAAY,cAAA,GACX,OAAA,CAAQ,cAAA;EAKL,kBAAA,CACJ,UAAA,EAAY,gBAAA,EACZ,SAAA,GAAY,cAAA,EACZ,UAAA,cACC,OAAA,CAAQ,cAAA;EAQL,eAAA,CACJ,MAAA,UACA,SAAA,GAAY,cAAA,EACZ,KAAA,YACC,OAAA,CAAQ,cAAA;EAcL,gBAAA,CACJ,WAAA,YACA,SAAA,GAAY,cAAA,GACX,OAAA,CAAQ,YAAA;EAAA,QAgBG,gBAAA;EAAA,QA+BA,WAAA;AAAA"}

package/dist/posthog/event-source.js

@@ -0,0 +1,119 @@
+//#region src/posthog/event-source.ts
+var PosthogAnalyticsEventSource = class {
+	reader;
+	limitPerEvent;
+	tenantPropertyKey;
+	defaultRangeDays;
+	constructor(reader, options = {}) {
+		this.reader = reader;
+		this.limitPerEvent = options.limitPerEvent ?? 1e3;
+		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 = 1e3) {
+		if (!this.reader.getEvents) throw new Error("Analytics reader does not support event queries.");
+		return (await this.reader.getEvents({
+			distinctId: userId,
+			dateRange,
+			limit
+		})).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) return (await this.reader.getEvents({
+			dateRange,
+			limit: limitPerEvent
+		})).results.map((event) => toAnalyticsEvent(event, this.tenantPropertyKey));
+		const events = [];
+		for (const eventName of eventNames) (await this.reader.getEvents({
+			event: eventName,
+			dateRange,
+			limit: limitPerEvent
+		})).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.");
+		return readSingleNumber(await this.reader.queryHogQL({
+			query: [
+				"select",
+				"  count() as total",
+				"from events",
+				"where event = {eventName}",
+				"and timestamp >= {dateFrom}",
+				"and timestamp < {dateTo}"
+			].join("\n"),
+			values: {
+				eventName,
+				dateFrom: range.from.toISOString(),
+				dateTo: range.to.toISOString()
+			}
+		})) ?? 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 : void 0,
+		timestamp: event.timestamp,
+		properties: event.properties
+	};
+}
+function resolveRange(dateRange, defaultDays) {
+	const to = dateRange?.to instanceof Date ? dateRange.to : dateRange?.to ? new Date(dateRange.to) : /* @__PURE__ */ new Date();
+	return {
+		from: dateRange?.from instanceof Date ? dateRange.from : dateRange?.from ? new Date(dateRange.from) : /* @__PURE__ */ new Date(to.getTime() - defaultDays * 24 * 60 * 60 * 1e3),
+		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;
+		}
+	}
+}
+
+//#endregion
+export { PosthogAnalyticsEventSource };
+//# sourceMappingURL=event-source.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"event-source.js","names":[],"sources":["../../src/posthog/event-source.ts"],"sourcesContent":["import type {\n  AnalyticsReader,\n  DateRangeInput,\n} from '@contractspec/lib.contracts/integrations/providers/analytics';\nimport type {\n  AnalyticsEvent,\n  CohortDefinition,\n  FunnelDefinition,\n  GrowthMetric,\n} from '../types';\n\nexport interface PosthogAnalyticsEventSourceOptions {\n  limitPerEvent?: number;\n  tenantPropertyKey?: string;\n  defaultRangeDays?: number;\n}\n\nexport class PosthogAnalyticsEventSource {\n  private readonly reader: AnalyticsReader;\n  private readonly limitPerEvent: number;\n  private readonly tenantPropertyKey: string;\n  private readonly defaultRangeDays: number;\n\n  constructor(\n    reader: AnalyticsReader,\n    options: PosthogAnalyticsEventSourceOptions = {}\n  ) {\n    this.reader = reader;\n    this.limitPerEvent = options.limitPerEvent ?? 1000;\n    this.tenantPropertyKey = options.tenantPropertyKey ?? 'tenantId';\n    this.defaultRangeDays = options.defaultRangeDays ?? 30;\n  }\n\n  async getEventsForFunnel(\n    definition: FunnelDefinition,\n    dateRange?: DateRangeInput\n  ): Promise<AnalyticsEvent[]> {\n    const eventNames = definition.steps.map((step) => step.eventName);\n    return this.getEventsByNames(eventNames, dateRange);\n  }\n\n  async getEventsForCohort(\n    definition: CohortDefinition,\n    dateRange?: DateRangeInput,\n    eventNames?: string[]\n  ): Promise<AnalyticsEvent[]> {\n    const events = eventNames && eventNames.length > 0 ? eventNames : ['*'];\n    if (events[0] === '*') {\n      return this.getEventsByNames([], dateRange, definition.periods * 500);\n    }\n    return this.getEventsByNames(events, dateRange, definition.periods * 500);\n  }\n\n  async getUserActivity(\n    userId: string,\n    dateRange?: DateRangeInput,\n    limit = 1000\n  ): Promise<AnalyticsEvent[]> {\n    if (!this.reader.getEvents) {\n      throw new Error('Analytics reader does not support event queries.');\n    }\n    const response = await this.reader.getEvents({\n      distinctId: userId,\n      dateRange,\n      limit,\n    });\n    return response.results.map((event) =>\n      toAnalyticsEvent(event, this.tenantPropertyKey)\n    );\n  }\n\n  async getGrowthMetrics(\n    metricNames: string[],\n    dateRange?: DateRangeInput\n  ): Promise<GrowthMetric[]> {\n    const range = resolveRange(dateRange, this.defaultRangeDays);\n    const previous = shiftRange(range);\n    const results: GrowthMetric[] = [];\n    for (const metricName of metricNames) {\n      const current = await this.countEvents(metricName, range);\n      const previousCount = await this.countEvents(metricName, previous);\n      results.push({\n        name: metricName,\n        current,\n        previous: previousCount,\n      });\n    }\n    return results;\n  }\n\n  private async getEventsByNames(\n    eventNames: string[],\n    dateRange?: DateRangeInput,\n    limitPerEvent = this.limitPerEvent\n  ): Promise<AnalyticsEvent[]> {\n    if (!this.reader.getEvents) {\n      throw new Error('Analytics reader does not support event queries.');\n    }\n    if (eventNames.length === 0) {\n      const response = await this.reader.getEvents({\n        dateRange,\n        limit: limitPerEvent,\n      });\n      return response.results.map((event) =>\n        toAnalyticsEvent(event, this.tenantPropertyKey)\n      );\n    }\n    const events: AnalyticsEvent[] = [];\n    for (const eventName of eventNames) {\n      const response = await this.reader.getEvents({\n        event: eventName,\n        dateRange,\n        limit: limitPerEvent,\n      });\n      response.results.forEach((event) => {\n        events.push(toAnalyticsEvent(event, this.tenantPropertyKey));\n      });\n    }\n    return events;\n  }\n\n  private async countEvents(\n    eventName: string,\n    range: { from: Date; to: Date }\n  ): Promise<number> {\n    if (!this.reader.queryHogQL) {\n      throw new Error('Analytics reader does not support HogQL queries.');\n    }\n    const result = await this.reader.queryHogQL({\n      query: [\n        'select',\n        '  count() as total',\n        'from events',\n        'where event = {eventName}',\n        'and timestamp >= {dateFrom}',\n        'and timestamp < {dateTo}',\n      ].join('\\n'),\n      values: {\n        eventName,\n        dateFrom: range.from.toISOString(),\n        dateTo: range.to.toISOString(),\n      },\n    });\n    return readSingleNumber(result) ?? 0;\n  }\n}\n\nfunction toAnalyticsEvent(\n  event: {\n    event: string;\n    distinctId: string;\n    properties?: Record<string, unknown>;\n    timestamp: string;\n  },\n  tenantPropertyKey: string\n): AnalyticsEvent {\n  const tenantIdValue =\n    event.properties?.[tenantPropertyKey] ?? event.properties?.tenantId;\n  return {\n    name: event.event,\n    userId: event.distinctId,\n    tenantId: typeof tenantIdValue === 'string' ? tenantIdValue : undefined,\n    timestamp: event.timestamp,\n    properties: event.properties,\n  };\n}\n\nfunction resolveRange(\n  dateRange: DateRangeInput | undefined,\n  defaultDays: number\n): { from: Date; to: Date } {\n  const to =\n    dateRange?.to instanceof Date\n      ? dateRange.to\n      : dateRange?.to\n        ? new Date(dateRange.to)\n        : new Date();\n  const from =\n    dateRange?.from instanceof Date\n      ? dateRange.from\n      : dateRange?.from\n        ? new Date(dateRange.from)\n        : new Date(to.getTime() - defaultDays * 24 * 60 * 60 * 1000);\n  return { from, to };\n}\n\nfunction shiftRange(range: { from: Date; to: Date }): {\n  from: Date;\n  to: Date;\n} {\n  const duration = range.to.getTime() - range.from.getTime();\n  return {\n    from: new Date(range.from.getTime() - duration),\n    to: new Date(range.to.getTime() - duration),\n  };\n}\n\nfunction readSingleNumber(result: { results: unknown }): number | undefined {\n  if (!Array.isArray(result.results) || result.results.length === 0) {\n    return undefined;\n  }\n  const firstRow = result.results[0];\n  if (Array.isArray(firstRow) && firstRow.length > 0) {\n    const value = firstRow[0];\n    if (typeof value === 'number' && Number.isFinite(value)) return value;\n    if (typeof value === 'string' && value.trim()) {\n      const parsed = Number(value);\n      if (Number.isFinite(parsed)) return parsed;\n    }\n  }\n  return undefined;\n}\n"],"mappings":"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"}

package/dist/posthog/index.d.ts

@@ -0,0 +1,2 @@
+import { PosthogAnalyticsEventSource, PosthogAnalyticsEventSourceOptions } from "./event-source.js";
+export { PosthogAnalyticsEventSource, PosthogAnalyticsEventSourceOptions };

package/dist/posthog/index.js

@@ -0,0 +1,3 @@
+import { PosthogAnalyticsEventSource } from "./event-source.js";
+
+export { PosthogAnalyticsEventSource };

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"sourcesContent":[],"mappings":";UAAiB,cAAA;EAAA,IAAA,EAAA,MAAA;EAQA,MAAA,EAAA,MAAU;EAMV,QAAA,CAAA,EAAA,MAAA;EAMA,SAAA,EAAA,MAAA,GAhBK,IAgBW;EAOhB,UAAA,CAAA,EAtBF,MAsBgB,CAAA,MAAA,EACjB,OAAA,CAAA;AAKd;AAIiB,UA7BA,UAAA,CA6BgB;EAMhB,EAAA,EAAA,MAAA;EAOA,SAAA,EAAA,MAAc;EAKd,KAAA,CAAA,EAAA,CAAA,KAAW,EA5CV,cA4CU,EAAA,GAAA,OAAA;AAO5B;AAOiB,UAvDA,gBAAA,CAuDgB;;SArDxB;;;UAIQ,gBAAA;QACT;;;;;UAMS,cAAA;cACH;;SAEL;;UAGQ,WAAA,SAAoB;;;UAIpB,gBAAA;;;cAGH;;UAGG,WAAA;;;;;;UAOA,cAAA;cACH;WACH;;UAGM,WAAA;;;;;;UAOA,YAAA;;;;;;UAOA,gBAAA"}
+{"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";UAAiB,cAAA;EACf,IAAA;EACA,MAAA;EACA,QAAA;EACA,SAAA,WAAoB,IAAA;EACpB,UAAA,GAAa,MAAA;AAAA;AAAA,UAGE,UAAA;EACf,EAAA;EACA,SAAA;EACA,KAAA,IAAS,KAAA,EAAO,cAAA;AAAA;AAAA,UAGD,gBAAA;EACf,IAAA;EACA,KAAA,EAAO,UAAA;EACP,WAAA;AAAA;AAAA,UAGe,gBAAA;EACf,IAAA,EAAM,UAAA;EACN,KAAA;EACA,cAAA;EACA,WAAA;AAAA;AAAA,UAGe,cAAA;EACf,UAAA,EAAY,gBAAA;EACZ,UAAA;EACA,KAAA,EAAO,gBAAA;AAAA;AAAA,UAGQ,WAAA,SAAoB,cAAA;EACnC,MAAA;AAAA;AAAA,UAGe,gBAAA;EACf,MAAA;EACA,OAAA;EACA,SAAA,GAAY,IAAA;AAAA;AAAA,UAGG,WAAA;EACf,SAAA;EACA,KAAA;EACA,SAAA;EACA,GAAA;AAAA;AAAA,UAGe,cAAA;EACf,UAAA,EAAY,gBAAA;EACZ,OAAA,EAAS,WAAA;AAAA;AAAA,UAGM,WAAA;EACf,MAAA;EACA,KAAA;EACA,MAAA;EACA,OAAA;AAAA;AAAA,UAGe,YAAA;EACf,IAAA;EACA,OAAA;EACA,QAAA;EACA,MAAA;AAAA;AAAA,UAGe,gBAAA;EACf,SAAA;EACA,MAAA;EACA,UAAA;EACA,MAAA;AAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/lib.analytics",
-  "version": "1.56.0",
+  "version": "1.57.0",
   "description": "Product analytics and growth metrics",
   "keywords": [
     "contractspec",
@@ -30,13 +30,14 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@contractspec/lib.lifecycle": "1.56.0",
+    "@contractspec/lib.contracts": "1.57.0",
+    "@contractspec/lib.lifecycle": "1.57.0",
     "dayjs": "^1.11.13"
   },
   "devDependencies": {
-    "@contractspec/tool.tsdown": "1.56.0",
-    "@contractspec/tool.typescript": "1.56.0",
-    "tsdown": "^0.19.0",
+    "@contractspec/tool.tsdown": "1.57.0",
+    "@contractspec/tool.typescript": "1.57.0",
+    "tsdown": "^0.20.3",
     "typescript": "^5.9.3"
   },
   "exports": {
@@ -52,6 +53,9 @@
     "./lifecycle": "./dist/lifecycle/index.js",
     "./lifecycle/metric-collectors": "./dist/lifecycle/metric-collectors.js",
     "./lifecycle/posthog-bridge": "./dist/lifecycle/posthog-bridge.js",
+    "./lifecycle/posthog-metric-source": "./dist/lifecycle/posthog-metric-source.js",
+    "./posthog": "./dist/posthog/index.js",
+    "./posthog/event-source": "./dist/posthog/event-source.js",
     "./types": "./dist/types.js",
     "./*": "./*"
   },
@@ -70,6 +74,9 @@
       "./lifecycle": "./dist/lifecycle/index.js",
       "./lifecycle/metric-collectors": "./dist/lifecycle/metric-collectors.js",
       "./lifecycle/posthog-bridge": "./dist/lifecycle/posthog-bridge.js",
+      "./lifecycle/posthog-metric-source": "./dist/lifecycle/posthog-metric-source.js",
+      "./posthog": "./dist/posthog/index.js",
+      "./posthog/event-source": "./dist/posthog/event-source.js",
       "./types": "./dist/types.js",
       "./*": "./*"
     },