@listo-ai/mcp-observability 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,305 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export type EventStatus = 'ok' | 'error';
+export type HttpRequestEvent = {
+    type: 'http_request';
+    timestamp: number;
+    service: string;
+    serviceVersion?: string;
+    environment?: string;
+    requestId: string;
+    method: string;
+    path: string;
+    route: string;
+    statusCode: number;
+    status: EventStatus;
+    latencyMs: number;
+    tenantId?: string;
+    sessionId?: string;
+    bytesOut?: number;
+    error?: string;
+};
+export type McpRequestEvent = {
+    type: 'mcp_request';
+    timestamp: number;
+    service: string;
+    serviceVersion?: string;
+    environment?: string;
+    requestId: string;
+    requestKind: string;
+    toolName?: string;
+    resourceUri?: string;
+    status: EventStatus;
+    latencyMs: number;
+    tenantId?: string;
+    sessionId?: string;
+    locale?: string;
+    userAgent?: string;
+    argsHash?: string;
+    inputBytes?: number;
+    outputBytes?: number;
+    samplePayload?: unknown;
+    argsPreview?: unknown;
+    resultPreview?: unknown;
+    resultHash?: string;
+    conversationId?: string;
+    userQueryHash?: string;
+    userQueryPreview?: string;
+    error?: string;
+};
+export type McpSessionEvent = {
+    type: 'mcp_session';
+    timestamp: number;
+    service: string;
+    serviceVersion?: string;
+    environment?: string;
+    action: 'open' | 'close';
+    sessionId: string;
+};
+export type BusinessEvent = {
+    type: 'business_event';
+    timestamp: number;
+    service: string;
+    serviceVersion?: string;
+    environment?: string;
+    name: string;
+    status?: EventStatus;
+    properties?: Record<string, unknown>;
+};
+export type UiEvent = {
+    type: 'ui_event';
+    timestamp: number;
+    service: string;
+    serviceVersion?: string;
+    environment?: string;
+    name: string;
+    action?: string;
+    widgetId?: string;
+    toolName?: string;
+    sessionId?: string;
+    tenantId?: string;
+    locale?: string;
+    properties?: Record<string, unknown>;
+};
+export type ObservabilityEvent = HttpRequestEvent | McpRequestEvent | McpSessionEvent | BusinessEvent | UiEvent;
+export type EventSink = {
+    emit: (event: ObservabilityEvent) => void | Promise<void>;
+};
+export type ObservabilityOptions = {
+    serviceName: string;
+    serviceVersion?: string;
+    environment?: string;
+    sinks?: EventSink[];
+    sampleRate?: number;
+    redactKeys?: string[];
+    capturePayloads?: boolean;
+    tenantResolver?: (req: IncomingMessage) => string | undefined;
+};
+type HttpTrackingContext = {
+    setRoute: (route: string) => void;
+    setTenant: (tenantId?: string | null) => void;
+};
+type McpTrackingContext = {
+    sessionId?: string;
+    tenantId?: string;
+    locale?: string;
+    userAgent?: string;
+    requestId?: string;
+    toolName?: string;
+    resourceUri?: string;
+    args?: unknown;
+    conversationId?: string;
+    userQuery?: string;
+    resultPreview?: (result: unknown) => unknown;
+};
+export declare class InMemorySink implements EventSink {
+    private events;
+    private readonly limit;
+    constructor(options?: {
+        limit?: number;
+    });
+    emit(event: ObservabilityEvent): void;
+    getEvents(): ObservabilityEvent[];
+    getMetrics(): {
+        totals: {
+            events: number;
+            http: number;
+            mcp: number;
+            sessions: number;
+            ui: number;
+            business: number;
+        };
+        http: {
+            overall: {
+                count: number;
+                errors: number;
+                avgMs?: undefined;
+                p50?: undefined;
+                p95?: undefined;
+                p99?: undefined;
+            } | {
+                count: number;
+                errors: number;
+                avgMs: number;
+                p50: number | null;
+                p95: number | null;
+                p99: number | null;
+            };
+            byRoute: Record<string, {
+                count: number;
+                errors: number;
+                avgMs?: undefined;
+                p50?: undefined;
+                p95?: undefined;
+                p99?: undefined;
+            } | {
+                count: number;
+                errors: number;
+                avgMs: number;
+                p50: number | null;
+                p95: number | null;
+                p99: number | null;
+            }>;
+        };
+        mcp: {
+            byKind: Record<string, {
+                count: number;
+                errors: number;
+                avgMs?: undefined;
+                p50?: undefined;
+                p95?: undefined;
+                p99?: undefined;
+            } | {
+                count: number;
+                errors: number;
+                avgMs: number;
+                p50: number | null;
+                p95: number | null;
+                p99: number | null;
+            }>;
+            tools: Record<string, {
+                count: number;
+                errors: number;
+                avgMs?: undefined;
+                p50?: undefined;
+                p95?: undefined;
+                p99?: undefined;
+            } | {
+                count: number;
+                errors: number;
+                avgMs: number;
+                p50: number | null;
+                p95: number | null;
+                p99: number | null;
+            }>;
+        };
+        sessions: {
+            open: number;
+            close: number;
+        };
+        ui: {
+            byName: Record<string, number>;
+            byAction: Record<string, number>;
+            byWidget: Record<string, number>;
+            total: number;
+        };
+        business: {
+            byName: Record<string, {
+                count: number;
+                ok: number;
+                error: number;
+            }>;
+        };
+        analytics: {
+            search: {
+                topQueries: CountEntry[];
+                topKeywords: CountEntry[];
+                minRatings: CountEntry[];
+                priceLevels: CountEntry[];
+                neighborhoods: CountEntry[];
+                styles: CountEntry[];
+                limits: CountEntry[];
+            };
+            geo: {
+                topCities: CountEntry[];
+                topCountries: CountEntry[];
+            };
+            hotels: {
+                topViewed: {
+                    id: string;
+                    name?: string;
+                    count: number;
+                }[];
+                topBookingClicks: {
+                    id: string;
+                    name?: string;
+                    count: number;
+                }[];
+                topBookingCtr: {
+                    id: string;
+                    name: string | undefined;
+                    clicks: number;
+                    views: number;
+                    ctr: number | null;
+                }[];
+                topWebsiteClicks: {
+                    id: string;
+                    name?: string;
+                    count: number;
+                }[];
+                viewedPriceLevels: CountEntry[];
+                viewedStyles: CountEntry[];
+                viewedCategories: CountEntry[];
+                viewedNeighborhoods: CountEntry[];
+            };
+            ctr: {
+                impressions: number;
+                clicks: number;
+                detailViews: number;
+                bookingClicks: number;
+                websiteClicks: number;
+                bookingPerImpression: number | null;
+                bookingPerDetailView: number | null;
+            };
+            sessions: {
+                total: number;
+                converted: number;
+                booking: number;
+                website: number;
+                conversionRate: number | null;
+                unknownSessionUiEvents: number;
+            };
+        };
+    };
+}
+export declare function createConsoleSink(options?: {
+    logSuccess?: boolean;
+}): EventSink;
+export declare function combineSinks(...sinks: EventSink[]): EventSink;
+export declare class McpObservability {
+    private readonly serviceName;
+    private readonly serviceVersion?;
+    private readonly environment?;
+    private readonly sinks;
+    private readonly sampleRate;
+    private readonly redactKeys;
+    private readonly capturePayloads;
+    private readonly tenantResolver?;
+    constructor(options: ObservabilityOptions);
+    recordUiEvent(event: Omit<UiEvent, 'timestamp' | 'service' | 'type'>): void;
+    trackHttpRequest(req: IncomingMessage, res: ServerResponse, handler: (ctx: HttpTrackingContext) => Promise<void>): Promise<void>;
+    wrapMcpHandler<TRequest, TResponse>(requestKind: string, handler: (request: TRequest) => Promise<TResponse> | TResponse, context?: (request: TRequest) => McpTrackingContext): (request: TRequest) => Promise<TResponse>;
+    recordSession(event: Omit<McpSessionEvent, 'timestamp' | 'service'>): void;
+    recordBusinessEvent(name: string, properties?: Record<string, unknown>, status?: EventStatus): void;
+    private baseMcpFields;
+    private sanitizePayload;
+    private safeEmit;
+}
+export declare function createMcpObservability(options: ObservabilityOptions): McpObservability;
+type CountEntry = {
+    value: string;
+    count: number;
+};
+export { RemoteSink, createRemoteSink, type RemoteSinkOptions, } from './remote-sink.js';
+export { createMcpObservabilityEasy, type EasySetupConfig, } from './easy-setup.js';
+export { createTelemetryRouter, expressTelemetry } from './endpoints.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}