@contractspec/lib.observability 1.57.0 → 1.59.0

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

@@ -1,266 +0,0 @@
-//#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

@@ -1,19 +0,0 @@
-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

@@ -1,61 +0,0 @@
-//#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/dist/tracing/index.d.mts

@@ -1,9 +0,0 @@
-import { Span, Tracer } from "@opentelemetry/api";
-
-//#region src/tracing/index.d.ts
-declare function getTracer(name?: string): Tracer;
-declare function traceAsync<T>(name: string, fn: (span: Span) => Promise<T>, tracerName?: string): Promise<T>;
-declare function traceSync<T>(name: string, fn: (span: Span) => T, tracerName?: string): T;
-//#endregion
-export { getTracer, traceAsync, traceSync };
-//# sourceMappingURL=index.d.mts.map

package/dist/tracing/index.mjs

@@ -1,47 +0,0 @@
-import { SpanStatusCode, trace } from "@opentelemetry/api";
-
-//#region src/tracing/index.ts
-const DEFAULT_TRACER_NAME = "@contractspec/lib.observability";
-function getTracer(name = DEFAULT_TRACER_NAME) {
-	return trace.getTracer(name);
-}
-async function traceAsync(name, fn, tracerName) {
-	return getTracer(tracerName).startActiveSpan(name, async (span) => {
-		try {
-			const result = await fn(span);
-			span.setStatus({ code: SpanStatusCode.OK });
-			return result;
-		} catch (error) {
-			span.recordException(error);
-			span.setStatus({
-				code: SpanStatusCode.ERROR,
-				message: error instanceof Error ? error.message : String(error)
-			});
-			throw error;
-		} finally {
-			span.end();
-		}
-	});
-}
-function traceSync(name, fn, tracerName) {
-	return getTracer(tracerName).startActiveSpan(name, (span) => {
-		try {
-			const result = fn(span);
-			span.setStatus({ code: SpanStatusCode.OK });
-			return result;
-		} catch (error) {
-			span.recordException(error);
-			span.setStatus({
-				code: SpanStatusCode.ERROR,
-				message: error instanceof Error ? error.message : String(error)
-			});
-			throw error;
-		} finally {
-			span.end();
-		}
-	});
-}
-
-//#endregion
-export { getTracer, traceAsync, traceSync };
-//# sourceMappingURL=index.mjs.map

package/dist/tracing/middleware.d.mts

@@ -1,19 +0,0 @@
-import { TelemetrySample } from "../intent/aggregator.mjs";
-
-//#region src/tracing/middleware.d.ts
-interface TracingMiddlewareOptions {
-  resolveOperation?: (input: {
-    req: Request;
-    res?: Response;
-  }) => {
-    name: string;
-    version: string;
-  } | undefined;
-  onSample?: (sample: TelemetrySample) => void;
-  tenantResolver?: (req: Request) => string | undefined;
-  actorResolver?: (req: Request) => string | undefined;
-}
-declare function createTracingMiddleware(options?: TracingMiddlewareOptions): (req: Request, next: () => Promise<Response>) => Promise<Response>;
-//#endregion
-export { TracingMiddlewareOptions, createTracingMiddleware };
-//# sourceMappingURL=middleware.d.mts.map

package/dist/tracing/middleware.mjs

@@ -1,80 +0,0 @@
-import { traceAsync } from "./index.mjs";
-import { standardMetrics } from "../metrics/index.mjs";
-
-//#region src/tracing/middleware.ts
-function createTracingMiddleware(options = {}) {
-	return async (req, next) => {
-		const method = req.method;
-		const path = new URL(req.url).pathname;
-		standardMetrics.httpRequests.add(1, {
-			method,
-			path
-		});
-		const startTime = performance.now();
-		return traceAsync(`HTTP ${method} ${path}`, async (span) => {
-			span.setAttribute("http.method", method);
-			span.setAttribute("http.url", req.url);
-			try {
-				const response = await next();
-				span.setAttribute("http.status_code", response.status);
-				const duration = (performance.now() - startTime) / 1e3;
-				standardMetrics.httpDuration.record(duration, {
-					method,
-					path,
-					status: response.status.toString()
-				});
-				emitTelemetrySample({
-					req,
-					res: response,
-					span,
-					success: true,
-					durationMs: duration * 1e3,
-					options
-				});
-				return response;
-			} catch (error) {
-				standardMetrics.operationErrors.add(1, {
-					method,
-					path
-				});
-				emitTelemetrySample({
-					req,
-					span,
-					success: false,
-					durationMs: performance.now() - startTime,
-					error,
-					options
-				});
-				throw error;
-			}
-		});
-	};
-}
-function emitTelemetrySample({ req, res, span, success, durationMs, error, options }) {
-	if (!options.onSample || !options.resolveOperation) return;
-	const operation = options.resolveOperation({
-		req,
-		res
-	});
-	if (!operation) return;
-	const sample = {
-		operation,
-		durationMs,
-		success,
-		timestamp: /* @__PURE__ */ new Date(),
-		errorCode: !success && error instanceof Error ? error.name : success ? void 0 : "unknown",
-		tenantId: options.tenantResolver?.(req),
-		actorId: options.actorResolver?.(req),
-		traceId: span.spanContext().traceId,
-		metadata: {
-			method: req.method,
-			path: new URL(req.url).pathname,
-			status: res?.status
-		}
-	};
-	options.onSample(sample);
-}
-
-//#endregion
-export { createTracingMiddleware };
-//# sourceMappingURL=middleware.mjs.map