@contractspec/lib.metering 1.56.1 → 1.58.0

package/dist/browser/analytics/posthog-metering-reader.js

@@ -0,0 +1,266 @@
+// src/analytics/posthog-metering-reader.ts
+class PosthogMeteringReader {
+  reader;
+  eventPrefix;
+  constructor(reader, options = {}) {
+    this.reader = reader;
+    this.eventPrefix = options.eventPrefix ?? "metering";
+  }
+  async getUsageByMetric(input) {
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        "  properties.recordId as recordId,",
+        "  properties.metricKey as metricKey,",
+        "  properties.subjectType as subjectType,",
+        "  distinct_id as subjectId,",
+        "  properties.quantity as quantity,",
+        "  properties.source as source,",
+        "  timestamp as timestamp",
+        "from events",
+        `where ${buildUsageWhereClause(this.eventPrefix, input)}`,
+        "order by timestamp desc",
+        `limit ${input.limit ?? 200}`
+      ].join(`
+`),
+      values: buildUsageValues(input)
+    });
+    return mapUsageRecords(result);
+  }
+  async getUsageSummary(input) {
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        "  properties.summaryId as summaryId,",
+        "  properties.metricKey as metricKey,",
+        "  properties.subjectType as subjectType,",
+        "  distinct_id as subjectId,",
+        "  properties.periodType as periodType,",
+        "  properties.periodStart as periodStart,",
+        "  properties.periodEnd as periodEnd,",
+        "  properties.totalQuantity as totalQuantity,",
+        "  properties.recordCount as recordCount,",
+        "  timestamp as aggregatedAt",
+        "from events",
+        `where ${buildSummaryWhereClause(this.eventPrefix, input)}`,
+        "order by timestamp desc",
+        `limit ${input.limit ?? 200}`
+      ].join(`
+`),
+      values: buildSummaryValues(input)
+    });
+    return mapUsageSummaries(result);
+  }
+  async getUsageTrend(input) {
+    const result = await this.queryHogQL({
+      query: [
+        "select",
+        `  ${bucketExpression(input.bucket)} as bucketStart,`,
+        "  sum(properties.quantity) as totalQuantity,",
+        "  count() as recordCount",
+        "from events",
+        `where ${buildUsageWhereClause(this.eventPrefix, input)}`,
+        "group by bucketStart",
+        "order by bucketStart asc"
+      ].join(`
+`),
+      values: buildUsageValues(input)
+    });
+    return mapUsageTrend(result);
+  }
+  async queryHogQL(input) {
+    if (!this.reader.queryHogQL) {
+      throw new Error("Analytics reader does not support HogQL queries.");
+    }
+    return this.reader.queryHogQL(input);
+  }
+}
+function buildUsageWhereClause(eventPrefix, input) {
+  const clauses = [
+    `event = '${eventPrefix}.usage_recorded'`,
+    `properties.metricKey = {metricKey}`
+  ];
+  if (input.subjectId) {
+    clauses.push("distinct_id = {subjectId}");
+  }
+  if (input.dateRange?.from) {
+    clauses.push("timestamp >= {dateFrom}");
+  }
+  if (input.dateRange?.to) {
+    clauses.push("timestamp < {dateTo}");
+  }
+  return clauses.join(" and ");
+}
+function buildSummaryWhereClause(eventPrefix, input) {
+  const clauses = [
+    `event = '${eventPrefix}.usage_aggregated'`,
+    `properties.metricKey = {metricKey}`
+  ];
+  if (input.subjectId) {
+    clauses.push("distinct_id = {subjectId}");
+  }
+  if (input.periodType) {
+    clauses.push("properties.periodType = {periodType}");
+  }
+  if (input.dateRange?.from) {
+    clauses.push("timestamp >= {dateFrom}");
+  }
+  if (input.dateRange?.to) {
+    clauses.push("timestamp < {dateTo}");
+  }
+  return clauses.join(" and ");
+}
+function buildUsageValues(input) {
+  return {
+    metricKey: input.metricKey,
+    subjectId: input.subjectId,
+    dateFrom: toIsoString(input.dateRange?.from),
+    dateTo: toIsoString(input.dateRange?.to)
+  };
+}
+function buildSummaryValues(input) {
+  return {
+    metricKey: input.metricKey,
+    subjectId: input.subjectId,
+    periodType: input.periodType,
+    dateFrom: toIsoString(input.dateRange?.from),
+    dateTo: toIsoString(input.dateRange?.to)
+  };
+}
+function bucketExpression(bucket) {
+  switch (bucket) {
+    case "hour":
+      return "toStartOfHour(timestamp)";
+    case "week":
+      return "toStartOfWeek(timestamp)";
+    case "month":
+      return "toStartOfMonth(timestamp)";
+    case "day":
+    default:
+      return "toStartOfDay(timestamp)";
+  }
+}
+function mapUsageRecords(result) {
+  const rows = mapRows(result);
+  return rows.flatMap((row) => {
+    const metricKey = asString(row.metricKey);
+    const subjectType = asString(row.subjectType);
+    const subjectId = asString(row.subjectId);
+    const timestamp = asDate(row.timestamp);
+    if (!metricKey || !subjectType || !subjectId || !timestamp) {
+      return [];
+    }
+    return [
+      {
+        recordId: asOptionalString(row.recordId),
+        metricKey,
+        subjectType,
+        subjectId,
+        quantity: asNumber(row.quantity),
+        source: asOptionalString(row.source),
+        timestamp
+      }
+    ];
+  });
+}
+function mapUsageSummaries(result) {
+  const rows = mapRows(result);
+  return rows.flatMap((row) => {
+    const metricKey = asString(row.metricKey);
+    const subjectType = asString(row.subjectType);
+    const subjectId = asString(row.subjectId);
+    const periodType = asString(row.periodType);
+    const periodStart = asDate(row.periodStart);
+    const periodEnd = asDate(row.periodEnd);
+    const aggregatedAt = asDate(row.aggregatedAt);
+    if (!metricKey || !subjectType || !subjectId || !periodType || !periodStart || !periodEnd || !aggregatedAt) {
+      return [];
+    }
+    return [
+      {
+        summaryId: asOptionalString(row.summaryId),
+        metricKey,
+        subjectType,
+        subjectId,
+        periodType,
+        periodStart,
+        periodEnd,
+        totalQuantity: asNumber(row.totalQuantity),
+        recordCount: asNumber(row.recordCount),
+        aggregatedAt
+      }
+    ];
+  });
+}
+function mapUsageTrend(result) {
+  const rows = mapRows(result);
+  return rows.flatMap((row) => {
+    const bucketStart = asString(row.bucketStart);
+    if (!bucketStart)
+      return [];
+    return [
+      {
+        bucketStart,
+        totalQuantity: asNumber(row.totalQuantity),
+        recordCount: asNumber(row.recordCount)
+      }
+    ];
+  });
+}
+function mapRows(result) {
+  if (!Array.isArray(result.results) || !Array.isArray(result.columns)) {
+    return [];
+  }
+  const columns = result.columns;
+  return result.results.flatMap((row) => {
+    if (!Array.isArray(row))
+      return [];
+    const record = {};
+    columns.forEach((column, index) => {
+      record[column] = row[index];
+    });
+    return [record];
+  });
+}
+function asString(value) {
+  if (typeof value === "string" && value.trim())
+    return value;
+  if (typeof value === "number")
+    return String(value);
+  return null;
+}
+function asOptionalString(value) {
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "number")
+    return String(value);
+  return;
+}
+function asNumber(value) {
+  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 0;
+}
+function asDate(value) {
+  if (value instanceof Date)
+    return value;
+  if (typeof value === "string" || typeof value === "number") {
+    const date = new Date(value);
+    if (!Number.isNaN(date.getTime()))
+      return date;
+  }
+  return null;
+}
+function toIsoString(value) {
+  if (!value)
+    return;
+  return typeof value === "string" ? value : value.toISOString();
+}
+export {
+  PosthogMeteringReader
+};

package/dist/browser/analytics/posthog-metering.js

@@ -0,0 +1,45 @@
+// src/analytics/posthog-metering.ts
+class PosthogMeteringReporter {
+  provider;
+  eventPrefix;
+  includeSource;
+  constructor(provider, options = {}) {
+    this.provider = provider;
+    this.eventPrefix = options.eventPrefix ?? "metering";
+    this.includeSource = options.includeSource ?? true;
+  }
+  async captureUsageRecorded(record) {
+    await this.provider.capture({
+      distinctId: record.subjectId,
+      event: `${this.eventPrefix}.usage_recorded`,
+      timestamp: record.timestamp,
+      properties: {
+        recordId: record.recordId ?? null,
+        metricKey: record.metricKey,
+        subjectType: record.subjectType,
+        quantity: record.quantity,
+        ...this.includeSource && record.source ? { source: record.source } : {}
+      }
+    });
+  }
+  async captureUsageAggregated(summary) {
+    await this.provider.capture({
+      distinctId: summary.subjectId,
+      event: `${this.eventPrefix}.usage_aggregated`,
+      timestamp: summary.aggregatedAt,
+      properties: {
+        summaryId: summary.summaryId ?? null,
+        metricKey: summary.metricKey,
+        subjectType: summary.subjectType,
+        periodType: summary.periodType,
+        periodStart: summary.periodStart.toISOString(),
+        periodEnd: summary.periodEnd.toISOString(),
+        totalQuantity: summary.totalQuantity,
+        recordCount: summary.recordCount
+      }
+    });
+  }
+}
+export {
+  PosthogMeteringReporter
+};