@contractspec/lib.observability 1.56.0 → 1.57.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @contractspec/lib.observability
 
+## 1.57.0
+
+### Minor Changes
+
+- 8ecf3c1: Add typed PostHog read APIs and readers across contracts, providers, metering, evolution, analytics, observability, and examples.
+- ad9d10a: feat: improve posthog integration
+- 11a5a05: feat: improve product intent
+
+### Patch Changes
+
+- Updated dependencies [8ecf3c1]
+- Updated dependencies [47c48c2]
+- Updated dependencies [a119963]
+- Updated dependencies [4651e06]
+- Updated dependencies [ad9d10a]
+- Updated dependencies [11a5a05]
+  - @contractspec/lib.contracts@1.57.0
+  - @contractspec/lib.lifecycle@1.57.0
+
+## 1.56.1
+
+### Patch Changes
+
+- fix: improve publish config
+- Updated dependencies
+  - @contractspec/lib.lifecycle@1.56.1
+
 ## 1.56.0
 
 ### Minor Changes

package/dist/index.d.mts

@@ -10,4 +10,6 @@ import { TracingMiddlewareOptions, createTracingMiddleware } from "./tracing/mid
 import { IntentDetector, IntentSignal, IntentSignalType } from "./intent/detector.mjs";
 import { EvolutionPipeline, EvolutionPipelineEvent, EvolutionPipelineOptions } from "./pipeline/evolution-pipeline.mjs";
 import { LifecycleKpiPipeline, LifecycleKpiPipelineOptions, LifecyclePipelineEvent } from "./pipeline/lifecycle-pipeline.mjs";
-export { AlertManager, AnomalyDetector, type AnomalySignal, type AnomalyThresholds, BaselineCalculator, EvolutionPipeline, type EvolutionPipelineEvent, type EvolutionPipelineOptions, IntentAggregator, type IntentAggregatorSnapshot, IntentDetector, type IntentSignal, type IntentSignalType, LifecycleKpiPipeline, type LifecycleKpiPipelineOptions, type LifecyclePipelineEvent, type LogEntry, type LogLevel, Logger, type RootCauseAnalysis, RootCauseAnalyzer, type TelemetrySample, type TracingMiddlewareOptions, createCounter, createHistogram, createTracingMiddleware, createUpDownCounter, getMeter, getTracer, logger, standardMetrics, traceAsync, traceSync };
+import { PosthogTelemetryProvider, PosthogTelemetryProviderOptions } from "./telemetry/posthog-telemetry.mjs";
+import { PosthogBaselineReader } from "./telemetry/posthog-baseline-reader.mjs";
+export { AlertManager, AnomalyDetector, type AnomalySignal, type AnomalyThresholds, BaselineCalculator, EvolutionPipeline, type EvolutionPipelineEvent, type EvolutionPipelineOptions, IntentAggregator, type IntentAggregatorSnapshot, IntentDetector, type IntentSignal, type IntentSignalType, LifecycleKpiPipeline, type LifecycleKpiPipelineOptions, type LifecyclePipelineEvent, type LogEntry, type LogLevel, Logger, PosthogBaselineReader, PosthogTelemetryProvider, type PosthogTelemetryProviderOptions, type RootCauseAnalysis, RootCauseAnalyzer, type TelemetrySample, type TracingMiddlewareOptions, createCounter, createHistogram, createTracingMiddleware, createUpDownCounter, getMeter, getTracer, logger, standardMetrics, traceAsync, traceSync };

package/dist/index.mjs

@@ -6,9 +6,11 @@ import { IntentAggregator } from "./intent/aggregator.mjs";
 import { IntentDetector } from "./intent/detector.mjs";
 import { EvolutionPipeline } from "./pipeline/evolution-pipeline.mjs";
 import { LifecycleKpiPipeline } from "./pipeline/lifecycle-pipeline.mjs";
+import { PosthogTelemetryProvider } from "./telemetry/posthog-telemetry.mjs";
+import { PosthogBaselineReader } from "./telemetry/posthog-baseline-reader.mjs";
 import { BaselineCalculator } from "./anomaly/baseline-calculator.mjs";
 import { AnomalyDetector } from "./anomaly/anomaly-detector.mjs";
 import { RootCauseAnalyzer } from "./anomaly/root-cause-analyzer.mjs";
 import { AlertManager } from "./anomaly/alert-manager.mjs";
 
-export { AlertManager, AnomalyDetector, BaselineCalculator, EvolutionPipeline, IntentAggregator, IntentDetector, LifecycleKpiPipeline, Logger, RootCauseAnalyzer, createCounter, createHistogram, createTracingMiddleware, createUpDownCounter, getMeter, getTracer, logger, standardMetrics, traceAsync, traceSync };
+export { AlertManager, AnomalyDetector, BaselineCalculator, EvolutionPipeline, IntentAggregator, IntentDetector, LifecycleKpiPipeline, Logger, PosthogBaselineReader, PosthogTelemetryProvider, RootCauseAnalyzer, createCounter, createHistogram, createTracingMiddleware, createUpDownCounter, getMeter, getTracer, logger, standardMetrics, traceAsync, traceSync };

package/dist/telemetry/posthog-baseline-reader.d.mts

@@ -0,0 +1,31 @@
+import { AggregatedOperationMetrics, OperationSequence, TelemetrySample } from "../intent/aggregator.mjs";
+import { AnalyticsReader, DateRangeInput } from "@contractspec/lib.contracts/integrations/providers/analytics";
+
+//#region src/telemetry/posthog-baseline-reader.d.ts
+interface ReadTelemetrySamplesInput {
+  operations?: {
+    name: string;
+    version: string;
+  }[];
+  dateRange?: DateRangeInput;
+  limit?: number;
+}
+interface PosthogBaselineReaderOptions {
+  eventPrefix?: string;
+}
+declare class PosthogBaselineReader {
+  private readonly reader;
+  private readonly eventPrefix;
+  constructor(reader: AnalyticsReader, options?: PosthogBaselineReaderOptions);
+  readSamples(input: ReadTelemetrySamplesInput): Promise<TelemetrySample[]>;
+  readAggregatedMetrics(operation: {
+    name: string;
+    version: string;
+  }, windowDays?: number): Promise<AggregatedOperationMetrics | null>;
+  readOperationSequences(dateRange?: DateRangeInput): Promise<OperationSequence[]>;
+  private readTopErrors;
+  private queryHogQL;
+}
+//#endregion
+export { PosthogBaselineReader, PosthogBaselineReaderOptions, ReadTelemetrySamplesInput };
+//# sourceMappingURL=posthog-baseline-reader.d.mts.map

package/dist/telemetry/posthog-baseline-reader.mjs

@@ -0,0 +1,266 @@
+//#region src/telemetry/posthog-baseline-reader.ts
+var PosthogBaselineReader = class {
+	reader;
+	eventPrefix;
+	constructor(reader, options = {}) {
+		this.reader = reader;
+		this.eventPrefix = options.eventPrefix ?? "observability";
+	}
+	async readSamples(input) {
+		return mapTelemetrySamples(await this.queryHogQL({
+			query: [
+				"select",
+				"  properties.operation as operationName,",
+				"  properties.version as version,",
+				"  properties.durationMs as durationMs,",
+				"  properties.success as success,",
+				"  properties.errorCode as errorCode,",
+				"  properties.tenantId as tenantId,",
+				"  properties.traceId as traceId,",
+				"  properties.metadata as metadata,",
+				"  distinct_id as actorId,",
+				"  timestamp as timestamp",
+				"from events",
+				`where ${buildOperationWhereClause(this.eventPrefix, input)}`,
+				"order by timestamp desc",
+				`limit ${input.limit ?? 1e3}`
+			].join("\n"),
+			values: buildOperationValues(input)
+		}));
+	}
+	async readAggregatedMetrics(operation, windowDays = 7) {
+		const dateRange = buildWindowRange(windowDays);
+		const stats = mapAggregatedMetrics(await this.queryHogQL({
+			query: [
+				"select",
+				"  count() as totalCalls,",
+				"  avg(properties.durationMs) as averageLatencyMs,",
+				"  quantile(0.95)(properties.durationMs) as p95LatencyMs,",
+				"  quantile(0.99)(properties.durationMs) as p99LatencyMs,",
+				"  max(properties.durationMs) as maxLatencyMs,",
+				"  sum(if(properties.success = 1, 1, 0)) as successCount,",
+				"  sum(if(properties.success = 0, 1, 0)) as errorCount",
+				"from events",
+				`where ${buildOperationWhereClause(this.eventPrefix, {
+					operations: [operation],
+					dateRange
+				})}`
+			].join("\n"),
+			values: buildOperationValues({
+				operations: [operation],
+				dateRange
+			})
+		}), operation, dateRange);
+		if (!stats) return null;
+		const topErrors = await this.readTopErrors(operation, dateRange);
+		return {
+			...stats,
+			topErrors
+		};
+	}
+	async readOperationSequences(dateRange) {
+		return mergeSequences(await this.queryHogQL({
+			query: [
+				"select",
+				"  properties.sequences as sequences",
+				"from events",
+				`where event = {eventName}`,
+				dateRange?.from ? "and timestamp >= {dateFrom}" : "",
+				dateRange?.to ? "and timestamp < {dateTo}" : "",
+				"order by timestamp desc",
+				"limit 50"
+			].filter(Boolean).join("\n"),
+			values: {
+				eventName: `${this.eventPrefix}.window`,
+				dateFrom: toIsoString(dateRange?.from),
+				dateTo: toIsoString(dateRange?.to)
+			}
+		}));
+	}
+	async readTopErrors(operation, dateRange) {
+		return mapRows(await this.queryHogQL({
+			query: [
+				"select",
+				"  properties.errorCode as errorCode,",
+				"  count() as errorCount",
+				"from events",
+				`where ${buildOperationWhereClause(this.eventPrefix, {
+					operations: [operation],
+					dateRange
+				})} and properties.success = 0`,
+				"group by errorCode",
+				"order by errorCount desc",
+				"limit 5"
+			].join("\n"),
+			values: buildOperationValues({
+				operations: [operation],
+				dateRange
+			})
+		})).reduce((acc, row) => {
+			const code = asString(row.errorCode);
+			if (!code) return acc;
+			acc[code] = asNumber(row.errorCount);
+			return acc;
+		}, {});
+	}
+	async queryHogQL(input) {
+		if (!this.reader.queryHogQL) throw new Error("Analytics reader does not support HogQL queries.");
+		return this.reader.queryHogQL(input);
+	}
+};
+function buildOperationWhereClause(eventPrefix, input) {
+	const clauses = [`event = '${eventPrefix}.operation'`];
+	if (input.operations?.length) clauses.push(`(${buildOperationFilters(input.operations)})`);
+	if (input.dateRange?.from) clauses.push("timestamp >= {dateFrom}");
+	if (input.dateRange?.to) clauses.push("timestamp < {dateTo}");
+	return clauses.join(" and ");
+}
+function buildOperationValues(input) {
+	const values = {
+		dateFrom: toIsoString(input.dateRange?.from),
+		dateTo: toIsoString(input.dateRange?.to)
+	};
+	input.operations?.forEach((op, index) => {
+		values[`operationName${index}`] = op.name;
+		values[`operationVersion${index}`] = op.version;
+	});
+	return values;
+}
+function buildOperationFilters(operations) {
+	return operations.map((_op, index) => `(properties.operation = {operationName${index}} and properties.version = {operationVersion${index}})`).join(" or ");
+}
+function mapTelemetrySamples(result) {
+	return mapRows(result).flatMap((row) => {
+		const operationName = asString(row.operationName);
+		const version = asString(row.version);
+		const timestamp = asDate(row.timestamp);
+		if (!operationName || !version || !timestamp) return [];
+		return [{
+			operation: {
+				name: operationName,
+				version
+			},
+			durationMs: asNumber(row.durationMs),
+			success: asBoolean(row.success),
+			timestamp,
+			errorCode: asOptionalString(row.errorCode) ?? void 0,
+			tenantId: asOptionalString(row.tenantId) ?? void 0,
+			traceId: asOptionalString(row.traceId) ?? void 0,
+			actorId: asOptionalString(row.actorId) ?? void 0,
+			metadata: isRecord(row.metadata) ? row.metadata : void 0
+		}];
+	});
+}
+function mapAggregatedMetrics(result, operation, dateRange) {
+	const row = mapRows(result)[0];
+	if (!row) return null;
+	const totalCalls = asNumber(row.totalCalls);
+	if (!totalCalls) return null;
+	const successCount = asNumber(row.successCount);
+	const errorCount = asNumber(row.errorCount);
+	const windowStart = toDate(dateRange.from) ?? /* @__PURE__ */ new Date();
+	const windowEnd = toDate(dateRange.to) ?? /* @__PURE__ */ new Date();
+	return {
+		operation,
+		totalCalls,
+		successRate: totalCalls ? successCount / totalCalls : 0,
+		errorRate: totalCalls ? errorCount / totalCalls : 0,
+		averageLatencyMs: asNumber(row.averageLatencyMs),
+		p95LatencyMs: asNumber(row.p95LatencyMs),
+		p99LatencyMs: asNumber(row.p99LatencyMs),
+		maxLatencyMs: asNumber(row.maxLatencyMs),
+		windowStart,
+		windowEnd,
+		topErrors: {}
+	};
+}
+function mergeSequences(result) {
+	const rows = mapRows(result);
+	const merged = /* @__PURE__ */ new Map();
+	rows.forEach((row) => {
+		const sequences = row.sequences;
+		if (!Array.isArray(sequences)) return;
+		sequences.forEach((sequence) => {
+			if (!isRecord(sequence)) return;
+			const steps = Array.isArray(sequence.steps) ? sequence.steps.filter((step) => typeof step === "string") : [];
+			if (steps.length === 0) return;
+			const tenantId = typeof sequence.tenantId === "string" ? sequence.tenantId : void 0;
+			const count = typeof sequence.count === "number" && Number.isFinite(sequence.count) ? sequence.count : 0;
+			const key = `${tenantId ?? "global"}:${steps.join(">")}`;
+			const existing = merged.get(key);
+			if (existing) existing.count += count;
+			else merged.set(key, {
+				steps,
+				tenantId,
+				count
+			});
+		});
+	});
+	return [...merged.values()];
+}
+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 buildWindowRange(windowDays) {
+	const windowEnd = /* @__PURE__ */ new Date();
+	return {
+		from: /* @__PURE__ */ new Date(windowEnd.getTime() - windowDays * 24 * 60 * 60 * 1e3),
+		to: windowEnd
+	};
+}
+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 null;
+}
+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 asBoolean(value) {
+	if (typeof value === "boolean") return value;
+	if (typeof value === "number") return value !== 0;
+	if (typeof value === "string") return value.toLowerCase() === "true";
+	return false;
+}
+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 void 0;
+	return typeof value === "string" ? value : value.toISOString();
+}
+function toDate(value) {
+	if (!value) return null;
+	return value instanceof Date ? value : new Date(value);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+
+//#endregion
+export { PosthogBaselineReader };
+//# sourceMappingURL=posthog-baseline-reader.mjs.map

package/dist/telemetry/posthog-telemetry.d.mts

@@ -0,0 +1,19 @@
+import { IntentAggregatorSnapshot, TelemetrySample } from "../intent/aggregator.mjs";
+import { AnalyticsProvider } from "@contractspec/lib.contracts/integrations/providers/analytics";
+
+//#region src/telemetry/posthog-telemetry.d.ts
+interface PosthogTelemetryProviderOptions {
+  eventPrefix?: string;
+  includeMetadata?: boolean;
+}
+declare class PosthogTelemetryProvider {
+  private readonly provider;
+  private readonly eventPrefix;
+  private readonly includeMetadata;
+  constructor(provider: AnalyticsProvider, options?: PosthogTelemetryProviderOptions);
+  captureSample(sample: TelemetrySample): Promise<void>;
+  captureSnapshot(snapshot: IntentAggregatorSnapshot): Promise<void>;
+}
+//#endregion
+export { PosthogTelemetryProvider, PosthogTelemetryProviderOptions };
+//# sourceMappingURL=posthog-telemetry.d.mts.map

package/dist/telemetry/posthog-telemetry.mjs

@@ -0,0 +1,61 @@
+//#region src/telemetry/posthog-telemetry.ts
+var PosthogTelemetryProvider = class {
+	provider;
+	eventPrefix;
+	includeMetadata;
+	constructor(provider, options = {}) {
+		this.provider = provider;
+		this.eventPrefix = options.eventPrefix ?? "observability";
+		this.includeMetadata = options.includeMetadata ?? false;
+	}
+	async captureSample(sample) {
+		await this.provider.capture({
+			distinctId: sample.actorId ?? sample.tenantId ?? "unknown",
+			event: `${this.eventPrefix}.operation`,
+			timestamp: sample.timestamp,
+			properties: {
+				operation: sample.operation.name,
+				version: sample.operation.version,
+				durationMs: sample.durationMs,
+				success: sample.success,
+				errorCode: sample.errorCode ?? null,
+				tenantId: sample.tenantId ?? null,
+				traceId: sample.traceId ?? null,
+				...this.includeMetadata && sample.metadata ? { metadata: sample.metadata } : {}
+			}
+		});
+	}
+	async captureSnapshot(snapshot) {
+		await this.provider.capture({
+			distinctId: "system",
+			event: `${this.eventPrefix}.window`,
+			timestamp: snapshot.windowEnd ?? /* @__PURE__ */ new Date(),
+			properties: {
+				sampleCount: snapshot.sampleCount,
+				metricsCount: snapshot.metrics.length,
+				sequencesCount: snapshot.sequences.length,
+				windowStart: snapshot.windowStart?.toISOString() ?? null,
+				windowEnd: snapshot.windowEnd?.toISOString() ?? null,
+				...this.includeMetadata ? {
+					metrics: snapshot.metrics.map((metric) => ({
+						operation: metric.operation.name,
+						version: metric.operation.version,
+						totalCalls: metric.totalCalls,
+						successRate: metric.successRate,
+						errorRate: metric.errorRate,
+						averageLatencyMs: metric.averageLatencyMs,
+						p95LatencyMs: metric.p95LatencyMs,
+						p99LatencyMs: metric.p99LatencyMs,
+						maxLatencyMs: metric.maxLatencyMs,
+						topErrors: metric.topErrors
+					})),
+					sequences: snapshot.sequences
+				} : {}
+			}
+		});
+	}
+};
+
+//#endregion
+export { PosthogTelemetryProvider };
+//# sourceMappingURL=posthog-telemetry.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/lib.observability",
-  "version": "1.56.0",
+  "version": "1.57.0",
   "description": "OpenTelemetry-based observability primitives",
   "keywords": [
     "contractspec",
@@ -25,14 +25,15 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@contractspec/lib.lifecycle": "1.56.0"
+    "@contractspec/lib.lifecycle": "1.57.0",
+    "@contractspec/lib.contracts": "1.57.0"
   },
   "peerDependencies": {
     "@opentelemetry/api": "*"
   },
   "devDependencies": {
-    "@contractspec/tool.tsdown": "1.56.0",
-    "@contractspec/tool.typescript": "1.56.0",
+    "@contractspec/tool.tsdown": "1.57.0",
+    "@contractspec/tool.typescript": "1.57.0",
     "typescript": "^5.9.3"
   },
   "exports": {
@@ -47,6 +48,8 @@
     "./metrics": "./dist/metrics/index.mjs",
     "./pipeline/evolution-pipeline": "./dist/pipeline/evolution-pipeline.mjs",
     "./pipeline/lifecycle-pipeline": "./dist/pipeline/lifecycle-pipeline.mjs",
+    "./telemetry/posthog-baseline-reader": "./dist/telemetry/posthog-baseline-reader.mjs",
+    "./telemetry/posthog-telemetry": "./dist/telemetry/posthog-telemetry.mjs",
     "./tracing": "./dist/tracing/index.mjs",
     "./tracing/middleware": "./dist/tracing/middleware.mjs",
     "./*": "./*"
@@ -65,6 +68,7 @@
       "./metrics": "./dist/metrics/index.mjs",
       "./pipeline/evolution-pipeline": "./dist/pipeline/evolution-pipeline.mjs",
       "./pipeline/lifecycle-pipeline": "./dist/pipeline/lifecycle-pipeline.mjs",
+      "./telemetry/posthog-baseline-reader": "./dist/telemetry/posthog-baseline-reader.mjs",
       "./tracing": "./dist/tracing/index.mjs",
       "./tracing/middleware": "./dist/tracing/middleware.mjs",
       "./*": "./*"