@listo-ai/mcp-observability 0.2.0

package/dist/remote-sink.d.ts

@@ -0,0 +1,26 @@
+import type { EventSink, ObservabilityEvent } from './index.js';
+export type RemoteSinkOptions = {
+    endpoint: string;
+    apiKey: string;
+    batchSize?: number;
+    flushIntervalMs?: number;
+    maxRetries?: number;
+    maxBufferSize?: number;
+    debug?: boolean;
+    onError?: (error: Error, events: ObservabilityEvent[]) => void;
+};
+export declare class RemoteSink implements EventSink {
+    private buffer;
+    private readonly options;
+    private flushTimer;
+    private isFlushing;
+    constructor(options: RemoteSinkOptions);
+    emit(event: ObservabilityEvent): void;
+    flush(): Promise<void>;
+    private sendBatch;
+    private delay;
+    private startFlushTimer;
+    destroy(): void;
+}
+export declare function createRemoteSink(options: RemoteSinkOptions): EventSink;
+//# sourceMappingURL=remote-sink.d.ts.map

package/dist/remote-sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-sink.d.ts","sourceRoot":"","sources":["../src/remote-sink.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAShE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,KAAK,IAAI,CAAC;CAChE,CAAC;AAEF,qBAAa,UAAW,YAAW,SAAS;IAC1C,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IACtD,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,UAAU,CAAS;gBAEf,OAAO,EAAE,iBAAiB;IAatC,IAAI,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI;IAgB/B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAed,SAAS;IA2DvB,OAAO,CAAC,KAAK;IAIb,OAAO,CAAC,eAAe;IAMvB,OAAO,IAAI,IAAI;CAOhB;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,CAEtE"}

package/dist/remote-sink.js

@@ -0,0 +1,123 @@
+class ClientError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ClientError';
+    }
+}
+export class RemoteSink {
+    buffer = [];
+    options;
+    flushTimer = null;
+    isFlushing = false;
+    constructor(options) {
+        this.options = {
+            batchSize: 50,
+            flushIntervalMs: 5000,
+            maxRetries: 3,
+            maxBufferSize: 10_000,
+            debug: false,
+            onError: (err) => console.error('[RemoteSink] Error:', err.message),
+            ...options,
+        };
+        this.startFlushTimer();
+    }
+    emit(event) {
+        if (this.options.debug) {
+            console.log(`[RemoteSink] Buffering event: type=${event.type}${'name' in event ? ` name=${event.name}` : ''}`);
+        }
+        this.buffer.push(event);
+        // Drop oldest events if buffer exceeds max size
+        while (this.buffer.length > this.options.maxBufferSize) {
+            this.buffer.shift();
+        }
+        if (this.buffer.length >= this.options.batchSize) {
+            this.flush().catch(() => { });
+        }
+    }
+    async flush() {
+        if (this.buffer.length === 0 || this.isFlushing)
+            return;
+        this.isFlushing = true;
+        const events = this.buffer.splice(0, this.options.batchSize);
+        try {
+            await this.sendBatch(events);
+        }
+        catch (error) {
+            this.options.onError(error, events);
+        }
+        finally {
+            this.isFlushing = false;
+        }
+    }
+    async sendBatch(events) {
+        // Transform events for API compatibility:
+        // - timestamp: Unix ms (number) -> ISO string
+        // - latencyMs: float -> integer
+        const transformedEvents = events.map((event) => ({
+            ...event,
+            timestamp: new Date(event.timestamp).toISOString(),
+            // Round latencyMs to integer if present
+            ...('latencyMs' in event && typeof event.latencyMs === 'number'
+                ? { latencyMs: Math.round(event.latencyMs) }
+                : {}),
+        }));
+        if (this.options.debug) {
+            const eventTypes = transformedEvents.map((e) => e.type);
+            console.log(`[RemoteSink] Sending batch of ${transformedEvents.length} events to ${this.options.endpoint}: types=${[...new Set(eventTypes)].join(',')}`);
+        }
+        for (let attempt = 0; attempt < this.options.maxRetries; attempt++) {
+            try {
+                const response = await fetch(this.options.endpoint, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-API-Key': this.options.apiKey,
+                    },
+                    body: JSON.stringify({ events: transformedEvents }),
+                });
+                if (response.ok) {
+                    if (this.options.debug) {
+                        console.log(`[RemoteSink] Batch sent successfully`);
+                    }
+                    return;
+                }
+                // Do not retry client errors — they won't succeed on retry
+                if (response.status >= 400 && response.status < 500) {
+                    const body = await response.text().catch(() => '');
+                    throw new ClientError(`Client error ${response.status}: ${body}`);
+                }
+                if (attempt < this.options.maxRetries - 1) {
+                    await this.delay(Math.pow(2, attempt) * 1000);
+                }
+            }
+            catch (error) {
+                if (error instanceof ClientError) {
+                    throw error;
+                }
+                if (attempt === this.options.maxRetries - 1) {
+                    throw error;
+                }
+                await this.delay(Math.pow(2, attempt) * 1000);
+            }
+        }
+    }
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    startFlushTimer() {
+        this.flushTimer = setInterval(() => {
+            this.flush().catch(() => { });
+        }, this.options.flushIntervalMs);
+    }
+    destroy() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        this.flush().catch(() => { });
+    }
+}
+export function createRemoteSink(options) {
+    return new RemoteSink(options);
+}
+//# sourceMappingURL=remote-sink.js.map

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@listo-ai/mcp-observability",
+  "version": "0.2.0",
+  "description": "Lightweight telemetry SDK for MCP servers and web applications. Captures HTTP requests, MCP tool invocations, business events, and UI interactions with built-in payload sanitization.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Listo-Labs-Ltd/mcp-observability.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "observability",
+    "telemetry",
+    "model-context-protocol",
+    "analytics",
+    "monitoring"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "dependencies": {},
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.10.0",
+    "eslint": "^9.17.0",
+    "eslint-config-prettier": "^10.0.0",
+    "eslint-plugin-prettier": "^5.2.0",
+    "prettier": "^3.4.0",
+    "typescript": "^5.7.0",
+    "typescript-eslint": "^8.18.0",
+    "vitest": "^3.0.0"
+  }
+}