@contractspec/lib.analytics 1.57.0 → 1.59.0

package/dist/browser/lifecycle/index.js

@@ -0,0 +1,287 @@
+// src/lifecycle/metric-collectors.ts
+var collectLifecycleMetrics = async (source) => {
+  const [
+    activeUsers,
+    weeklyActiveUsers,
+    retentionRate,
+    monthlyRecurringRevenue,
+    customerCount,
+    teamSize,
+    burnMultiple
+  ] = await Promise.all([
+    source.getActiveUsers(),
+    source.getWeeklyActiveUsers?.(),
+    source.getRetentionRate?.(),
+    source.getMonthlyRecurringRevenue?.(),
+    source.getCustomerCount?.(),
+    source.getTeamSize?.(),
+    source.getBurnMultiple?.()
+  ]);
+  return {
+    activeUsers,
+    weeklyActiveUsers,
+    retentionRate,
+    monthlyRecurringRevenue,
+    customerCount,
+    teamSize,
+    burnMultiple
+  };
+};
+var metricsToSignals = (metrics, tenantId) => Object.entries(metrics).filter(([, value]) => value !== undefined && value !== null).map(([metricKey, value]) => ({
+  id: `lifecycle-metric:${metricKey}`,
+  kind: "metric",
+  source: "analytics",
+  name: metricKey,
+  value,
+  weight: 1,
+  confidence: 0.8,
+  details: tenantId ? { tenantId } : undefined,
+  capturedAt: new Date().toISOString()
+}));
+var lifecycleEventNames = {
+  assessmentRun: "lifecycle_assessment_run",
+  stageChanged: "lifecycle_stage_changed",
+  guidanceConsumed: "lifecycle_guidance_consumed"
+};
+var createStageChangeEvent = (payload) => ({
+  name: lifecycleEventNames.stageChanged,
+  userId: "system",
+  tenantId: payload.tenantId,
+  timestamp: new Date,
+  properties: { ...payload }
+});
+
+// src/lifecycle/posthog-bridge.ts
+var trackLifecycleAssessment = async (client, tenantId, assessment) => {
+  await client.capture({
+    distinctId: tenantId,
+    event: lifecycleEventNames.assessmentRun,
+    properties: {
+      stage: assessment.stage,
+      confidence: assessment.confidence,
+      axes: assessment.axes
+    }
+  });
+};
+var trackLifecycleStageChange = async (client, tenantId, previousStage, nextStage) => {
+  await client.capture({
+    distinctId: tenantId,
+    event: lifecycleEventNames.stageChanged,
+    properties: {
+      previousStage,
+      nextStage
+    }
+  });
+};
+
+// src/lifecycle/posthog-metric-source.ts
+class PosthogLifecycleMetricSource {
+  reader;
+  activityEvents;
+  retentionWindowDays;
+  revenueEvent;
+  revenueProperty;
+  customerEvent;
+  customerProperty;
+  teamSizeEvent;
+  teamSizeProperty;
+  burnMultipleEvent;
+  burnMultipleProperty;
+  constructor(reader, options = {}) {
+    this.reader = reader;
+    this.activityEvents = options.activityEvents;
+    this.retentionWindowDays = options.retentionWindowDays ?? 7;
+    this.revenueEvent = options.revenueEvent;
+    this.revenueProperty = options.revenueProperty ?? "amount";
+    this.customerEvent = options.customerEvent;
+    this.customerProperty = options.customerProperty ?? "is_customer";
+    this.teamSizeEvent = options.teamSizeEvent;
+    this.teamSizeProperty = options.teamSizeProperty ?? "team_size";
+    this.burnMultipleEvent = options.burnMultipleEvent;
+    this.burnMultipleProperty = options.burnMultipleProperty ?? "burn_multiple";
+  }
+  async getActiveUsers() {
+    return this.countDistinctUsers(1);
+  }
+  async getWeeklyActiveUsers() {
+    return this.countDistinctUsers(7);
+  }
+  async getRetentionRate() {
+    const windowDays = this.retentionWindowDays;
+    const now = new Date;
+    const prevEnd = new Date(now.getTime() - windowDays * 24 * 60 * 60 * 1000);
+    const prevStart = new Date(now.getTime() - windowDays * 2 * 24 * 60 * 60 * 1000);
+    const returningUsers = await this.countReturningUsers(prevStart, prevEnd, now);
+    const prevUsers = await this.countDistinctUsersBetween(prevStart, prevEnd);
+    if (prevUsers === undefined || prevUsers === 0)
+      return;
+    return returningUsers / prevUsers;
+  }
+  async getMonthlyRecurringRevenue() {
+    if (!this.revenueEvent || !this.revenueProperty)
+      return;
+    return this.sumMetric(this.revenueEvent, this.revenueProperty);
+  }
+  async getCustomerCount() {
+    if (!this.customerEvent || !this.customerProperty)
+      return;
+    return this.countDistinctUsersByProperty(this.customerEvent, this.customerProperty);
+  }
+  async getTeamSize() {
+    if (!this.teamSizeEvent || !this.teamSizeProperty)
+      return;
+    return this.latestMetric(this.teamSizeEvent, this.teamSizeProperty);
+  }
+  async getBurnMultiple() {
+    if (!this.burnMultipleEvent || !this.burnMultipleProperty)
+      return;
+    return this.latestMetric(this.burnMultipleEvent, this.burnMultipleProperty);
+  }
+  async countDistinctUsers(days) {
+    const range = buildDateRange(days);
+    return this.countDistinctUsersBetween(range.from, range.to);
+  }
+  async countDistinctUsersBetween(from, to) {
+    const eventFilter = buildEventFilter(this.activityEvents, "activityEvent");
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        "  countDistinct(distinct_id) as total",
+        "from events",
+        `where timestamp >= {dateFrom} and timestamp < {dateTo}`,
+        eventFilter.clause ? `and ${eventFilter.clause}` : ""
+      ].filter(Boolean).join(`
+`),
+      values: {
+        dateFrom: from.toISOString(),
+        dateTo: to.toISOString(),
+        ...eventFilter.values
+      }
+    });
+    return readSingleNumber(result);
+  }
+  async countReturningUsers(previousStart, previousEnd, currentEnd) {
+    const eventFilter = buildEventFilter(this.activityEvents, "activityEvent");
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        "  countDistinct(distinct_id) as total",
+        "from events",
+        `where timestamp >= {currentFrom} and timestamp < {currentTo}`,
+        eventFilter.clause ? `and ${eventFilter.clause}` : "",
+        "and distinct_id in (",
+        "  select distinct_id from events",
+        "  where timestamp >= {previousFrom} and timestamp < {previousTo}",
+        eventFilter.clause ? `and ${eventFilter.clause}` : "",
+        ")"
+      ].join(`
+`),
+      values: {
+        currentFrom: previousEnd.toISOString(),
+        currentTo: currentEnd.toISOString(),
+        previousFrom: previousStart.toISOString(),
+        previousTo: previousEnd.toISOString(),
+        ...eventFilter.values
+      }
+    });
+    return readSingleNumber(result) ?? 0;
+  }
+  async sumMetric(eventName, propertyKey) {
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        `  sum(properties.${propertyKey}) as total`,
+        "from events",
+        "where event = {eventName}"
+      ].join(`
+`),
+      values: { eventName }
+    });
+    return readSingleNumber(result);
+  }
+  async countDistinctUsersByProperty(eventName, propertyKey) {
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        "  countDistinct(distinct_id) as total",
+        "from events",
+        "where event = {eventName}",
+        `and properties.${propertyKey} = {propertyValue}`
+      ].join(`
+`),
+      values: { eventName, propertyValue: true }
+    });
+    return readSingleNumber(result);
+  }
+  async latestMetric(eventName, propertyKey) {
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        `  properties.${propertyKey} as value`,
+        "from events",
+        "where event = {eventName}",
+        "order by timestamp desc",
+        "limit 1"
+      ].join(`
+`),
+      values: { eventName }
+    });
+    return readSingleNumber(result);
+  }
+  async queryHogQL(input) {
+    if (!this.reader.queryHogQL) {
+      throw new Error("Analytics reader does not support HogQL queries.");
+    }
+    return this.reader.queryHogQL(input);
+  }
+}
+function buildDateRange(days) {
+  const to = new Date;
+  const from = new Date(to.getTime() - days * 24 * 60 * 60 * 1000);
+  return { from, to };
+}
+function buildEventFilter(events, prefix) {
+  if (!events || events.length === 0)
+    return {};
+  if (events.length === 1) {
+    return {
+      clause: `event = {${prefix}0}`,
+      values: { [`${prefix}0`]: events[0] }
+    };
+  }
+  const clauses = events.map((_event, index) => `event = {${prefix}${index}}`);
+  const values = {};
+  events.forEach((event, index) => {
+    values[`${prefix}${index}`] = event;
+  });
+  return {
+    clause: `(${clauses.join(" or ")})`,
+    values
+  };
+}
+function readSingleNumber(result) {
+  if (!Array.isArray(result.results) || result.results.length === 0) {
+    return;
+  }
+  const firstRow = result.results[0];
+  if (Array.isArray(firstRow) && firstRow.length > 0) {
+    const value = firstRow[0];
+    if (typeof value === "number" && Number.isFinite(value))
+      return value;
+    if (typeof value === "string" && value.trim()) {
+      const parsed = Number(value);
+      if (Number.isFinite(parsed))
+        return parsed;
+    }
+  }
+  return;
+}
+export {
+  trackLifecycleStageChange,
+  trackLifecycleAssessment,
+  metricsToSignals,
+  lifecycleEventNames,
+  createStageChangeEvent,
+  collectLifecycleMetrics,
+  PosthogLifecycleMetricSource
+};

package/dist/browser/lifecycle/metric-collectors.js

@@ -0,0 +1,58 @@
+// src/lifecycle/metric-collectors.ts
+var collectLifecycleMetrics = async (source) => {
+  const [
+    activeUsers,
+    weeklyActiveUsers,
+    retentionRate,
+    monthlyRecurringRevenue,
+    customerCount,
+    teamSize,
+    burnMultiple
+  ] = await Promise.all([
+    source.getActiveUsers(),
+    source.getWeeklyActiveUsers?.(),
+    source.getRetentionRate?.(),
+    source.getMonthlyRecurringRevenue?.(),
+    source.getCustomerCount?.(),
+    source.getTeamSize?.(),
+    source.getBurnMultiple?.()
+  ]);
+  return {
+    activeUsers,
+    weeklyActiveUsers,
+    retentionRate,
+    monthlyRecurringRevenue,
+    customerCount,
+    teamSize,
+    burnMultiple
+  };
+};
+var metricsToSignals = (metrics, tenantId) => Object.entries(metrics).filter(([, value]) => value !== undefined && value !== null).map(([metricKey, value]) => ({
+  id: `lifecycle-metric:${metricKey}`,
+  kind: "metric",
+  source: "analytics",
+  name: metricKey,
+  value,
+  weight: 1,
+  confidence: 0.8,
+  details: tenantId ? { tenantId } : undefined,
+  capturedAt: new Date().toISOString()
+}));
+var lifecycleEventNames = {
+  assessmentRun: "lifecycle_assessment_run",
+  stageChanged: "lifecycle_stage_changed",
+  guidanceConsumed: "lifecycle_guidance_consumed"
+};
+var createStageChangeEvent = (payload) => ({
+  name: lifecycleEventNames.stageChanged,
+  userId: "system",
+  tenantId: payload.tenantId,
+  timestamp: new Date,
+  properties: { ...payload }
+});
+export {
+  metricsToSignals,
+  lifecycleEventNames,
+  createStageChangeEvent,
+  collectLifecycleMetrics
+};

package/dist/browser/lifecycle/posthog-bridge.js

@@ -0,0 +1,79 @@
+// src/lifecycle/metric-collectors.ts
+var collectLifecycleMetrics = async (source) => {
+  const [
+    activeUsers,
+    weeklyActiveUsers,
+    retentionRate,
+    monthlyRecurringRevenue,
+    customerCount,
+    teamSize,
+    burnMultiple
+  ] = await Promise.all([
+    source.getActiveUsers(),
+    source.getWeeklyActiveUsers?.(),
+    source.getRetentionRate?.(),
+    source.getMonthlyRecurringRevenue?.(),
+    source.getCustomerCount?.(),
+    source.getTeamSize?.(),
+    source.getBurnMultiple?.()
+  ]);
+  return {
+    activeUsers,
+    weeklyActiveUsers,
+    retentionRate,
+    monthlyRecurringRevenue,
+    customerCount,
+    teamSize,
+    burnMultiple
+  };
+};
+var metricsToSignals = (metrics, tenantId) => Object.entries(metrics).filter(([, value]) => value !== undefined && value !== null).map(([metricKey, value]) => ({
+  id: `lifecycle-metric:${metricKey}`,
+  kind: "metric",
+  source: "analytics",
+  name: metricKey,
+  value,
+  weight: 1,
+  confidence: 0.8,
+  details: tenantId ? { tenantId } : undefined,
+  capturedAt: new Date().toISOString()
+}));
+var lifecycleEventNames = {
+  assessmentRun: "lifecycle_assessment_run",
+  stageChanged: "lifecycle_stage_changed",
+  guidanceConsumed: "lifecycle_guidance_consumed"
+};
+var createStageChangeEvent = (payload) => ({
+  name: lifecycleEventNames.stageChanged,
+  userId: "system",
+  tenantId: payload.tenantId,
+  timestamp: new Date,
+  properties: { ...payload }
+});
+
+// src/lifecycle/posthog-bridge.ts
+var trackLifecycleAssessment = async (client, tenantId, assessment) => {
+  await client.capture({
+    distinctId: tenantId,
+    event: lifecycleEventNames.assessmentRun,
+    properties: {
+      stage: assessment.stage,
+      confidence: assessment.confidence,
+      axes: assessment.axes
+    }
+  });
+};
+var trackLifecycleStageChange = async (client, tenantId, previousStage, nextStage) => {
+  await client.capture({
+    distinctId: tenantId,
+    event: lifecycleEventNames.stageChanged,
+    properties: {
+      previousStage,
+      nextStage
+    }
+  });
+};
+export {
+  trackLifecycleStageChange,
+  trackLifecycleAssessment
+};

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

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