@contractspec/lib.analytics 1.56.1 → 1.58.0

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

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

package/dist/node/posthog/index.js

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

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

@@ -0,0 +1,21 @@
+import type { AnalyticsReader, DateRangeInput } from '@contractspec/lib.contracts/integrations/providers/analytics';
+import type { AnalyticsEvent, CohortDefinition, FunnelDefinition, GrowthMetric } from '../types';
+export interface PosthogAnalyticsEventSourceOptions {
+    limitPerEvent?: number;
+    tenantPropertyKey?: string;
+    defaultRangeDays?: number;
+}
+export 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;
+}
+//# sourceMappingURL=event-source.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"event-source.d.ts","sourceRoot":"","sources":["../../src/posthog/event-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACf,MAAM,8DAA8D,CAAC;AACtE,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,YAAY,EACb,MAAM,UAAU,CAAC;AAElB,MAAM,WAAW,kCAAkC;IACjD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,2BAA2B;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;gBAGxC,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,kCAAuC;IAQ5C,kBAAkB,CACtB,UAAU,EAAE,gBAAgB,EAC5B,SAAS,CAAC,EAAE,cAAc,GACzB,OAAO,CAAC,cAAc,EAAE,CAAC;IAKtB,kBAAkB,CACtB,UAAU,EAAE,gBAAgB,EAC5B,SAAS,CAAC,EAAE,cAAc,EAC1B,UAAU,CAAC,EAAE,MAAM,EAAE,GACpB,OAAO,CAAC,cAAc,EAAE,CAAC;IAQtB,eAAe,CACnB,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,cAAc,EAC1B,KAAK,SAAO,GACX,OAAO,CAAC,cAAc,EAAE,CAAC;IActB,gBAAgB,CACpB,WAAW,EAAE,MAAM,EAAE,EACrB,SAAS,CAAC,EAAE,cAAc,GACzB,OAAO,CAAC,YAAY,EAAE,CAAC;YAgBZ,gBAAgB;YA+BhB,WAAW;CAwB1B"}

package/dist/posthog/event-source.js

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

package/dist/posthog/index.d.ts

@@ -0,0 +1,2 @@
+export * from './event-source';
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/posthog/index.js

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