wiretap-llm 0.1.0

package/README.md

@@ -0,0 +1,112 @@
+# wiretap-llm
+
+Telemetry client for sending LLM logs to your Wiretap instance.
+
+## Installation
+
+```bash
+npm install wiretap-llm
+# or
+bun add wiretap-llm
+```
+
+## Quick Start
+
+```ts
+import { TelemetryClient, createId, toIso } from "wiretap-llm";
+
+// Create client
+const client = new TelemetryClient({
+  baseUrl: process.env.WIRETAP_BASE_URL!,
+  apiKey: process.env.WIRETAP_API_KEY!,
+});
+
+// Send a log
+client.report({
+  id: createId(),
+  timestamp: toIso(new Date()),
+  project: "",  // Inferred from API key
+  source: "openrouter",
+  method: "POST",
+  url: "https://openrouter.ai/api/v1/chat/completions",
+  path: "/v1/chat/completions",
+  model: "anthropic/claude-sonnet-4",
+  streamed: true,
+  timing: {
+    started_at: toIso(startTime),
+    ended_at: toIso(endTime),
+    duration_ms: endTime.getTime() - startTime.getTime(),
+  },
+  request: {
+    body_json: requestBody,
+  },
+  stream: {
+    output_text: "Hello!",
+    finish_reason: "stop",
+    usage: { prompt_tokens: 10, completion_tokens: 5 },
+  },
+});
+
+// On app shutdown
+await client.shutdown();
+```
+
+## Configuration
+
+### TelemetryClient Options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `baseUrl` | string | Yes | - | Your Wiretap instance URL |
+| `apiKey` | string | Yes | - | Your Wiretap API key |
+| `project` | string | No | - | Project slug (usually inferred from API key) |
+| `environment` | string | No | - | Environment name (e.g., "production") |
+| `defaultMetadata` | object | No | - | Metadata added to all logs |
+| `timeoutMs` | number | No | 5000 | Request timeout |
+| `maxBatchSize` | number | No | 25 | Max logs per batch |
+| `flushIntervalMs` | number | No | 2000 | Auto-flush interval |
+| `maxLogBytes` | number | No | 1000000 | Max log size before truncation |
+| `onError` | function | No | - | Error handler |
+
+## API
+
+### `client.report(log: TelemetryLog)`
+
+Queue a log for sending. Logs are batched and sent automatically.
+
+### `client.flush()`
+
+Manually flush pending logs.
+
+### `client.shutdown()`
+
+Flush remaining logs and stop the client. Call on app shutdown.
+
+## Helper Utilities
+
+```ts
+import { createId, toIso, sanitizeHeaders, safeJsonParse } from "wiretap-llm";
+
+// Generate unique ID
+const id = createId();  // "abc123..."
+
+// ISO timestamp
+const ts = toIso(new Date());  // "2024-01-20T..."
+
+// Remove sensitive headers
+const headers = sanitizeHeaders(req.headers);  // Strips auth headers
+
+// Safe JSON parse
+const { ok, value } = safeJsonParse(jsonString);
+```
+
+## Environment Variables
+
+```bash
+WIRETAP_BASE_URL=https://your-wiretap-instance.com
+WIRETAP_API_KEY=wt_your_api_key
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,35 @@
+import type { JsonValue } from "./json";
+import type { TelemetryLog } from "./types/telemetry";
+export type TelemetryClientOptions = {
+    baseUrl: string;
+    apiKey: string;
+    /** Optional - project is automatically inferred from API key on server */
+    project?: string;
+    environment?: string;
+    defaultMetadata?: Record<string, JsonValue>;
+    timeoutMs?: number;
+    maxBatchSize?: number;
+    flushIntervalMs?: number;
+    maxLogBytes?: number;
+    onError?: (err: unknown) => void;
+};
+export declare class TelemetryClient {
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    readonly project?: string;
+    readonly environment?: string;
+    readonly defaultMetadata?: Record<string, JsonValue>;
+    private timeoutMs;
+    private maxBatchSize;
+    private flushIntervalMs;
+    private maxLogBytes;
+    private queue;
+    private flushing;
+    private timer;
+    private onError?;
+    constructor(opts: TelemetryClientOptions);
+    report(log: TelemetryLog): void;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAExC,OAAO,KAAK,EAAyB,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE7E,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CAClC,CAAC;AAEF,qBAAa,eAAe;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAErD,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,WAAW,CAAS;IAE5B,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,KAAK,CAA+C;IAE5D,OAAO,CAAC,OAAO,CAAC,CAAyB;gBAE7B,IAAI,EAAE,sBAAsB;IAuBxC,MAAM,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI;IAmCzB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0EtB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAQhC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { TelemetryClient } from "./client";
+export type { TelemetryClientOptions } from "./client";
+export type { TelemetryBatchPayload, TelemetryLog, TelemetryTrace, } from "./types/telemetry";
+export { createId, safeJsonParse, sanitizeHeaders, toIso, truncateUtf8 } from "./json";
+export type { JsonPrimitive, JsonValue } from "./json";
+//# 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":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,YAAY,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAGvD,YAAY,EACV,qBAAqB,EACrB,YAAY,EACZ,cAAc,GACf,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,eAAe,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACvF,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC"}

package/dist/index.js

@@ -0,0 +1,192 @@
+// src/json.ts
+function toIso(d) {
+  return d.toISOString();
+}
+function createId() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID)
+    return c.randomUUID();
+  return `id_${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`;
+}
+function safeJsonParse(text) {
+  try {
+    const v = JSON.parse(text);
+    return { ok: true, value: v };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : "Invalid JSON" };
+  }
+}
+var SENSITIVE_HEADERS = new Set([
+  "authorization",
+  "cookie",
+  "set-cookie",
+  "x-api-key",
+  "api-key"
+]);
+function sanitizeHeaders(headers) {
+  const out = {};
+  if (!headers)
+    return out;
+  const set = (k, v) => {
+    const key = k.toLowerCase();
+    if (SENSITIVE_HEADERS.has(key))
+      return;
+    out[key] = v;
+  };
+  if (headers instanceof Headers) {
+    headers.forEach((v, k) => set(k, v));
+  } else if (Array.isArray(headers)) {
+    for (const [k, v] of headers)
+      set(k, v);
+  } else {
+    for (const [k, v] of Object.entries(headers))
+      set(k, String(v));
+  }
+  return out;
+}
+function truncateUtf8(input, maxBytes) {
+  const enc = new TextEncoder;
+  const bytes = enc.encode(input);
+  if (bytes.length <= maxBytes)
+    return { text: input, truncated: false };
+  const sliced = bytes.slice(0, maxBytes);
+  const dec = new TextDecoder("utf-8", { fatal: false });
+  return { text: dec.decode(sliced), truncated: true };
+}
+
+// src/client.ts
+class TelemetryClient {
+  baseUrl;
+  apiKey;
+  project;
+  environment;
+  defaultMetadata;
+  timeoutMs;
+  maxBatchSize;
+  flushIntervalMs;
+  maxLogBytes;
+  queue = [];
+  flushing = false;
+  timer = null;
+  onError;
+  constructor(opts) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.apiKey = opts.apiKey;
+    this.project = opts.project;
+    this.environment = opts.environment;
+    this.defaultMetadata = opts.defaultMetadata;
+    this.timeoutMs = opts.timeoutMs ?? 5000;
+    this.maxBatchSize = opts.maxBatchSize ?? 25;
+    this.flushIntervalMs = opts.flushIntervalMs ?? 2000;
+    this.maxLogBytes = opts.maxLogBytes ?? 1e6;
+    this.onError = opts.onError;
+    if (this.flushIntervalMs > 0) {
+      this.timer = setInterval(() => void this.flush(), this.flushIntervalMs);
+      if (typeof this.timer === "object" && "unref" in this.timer) {
+        this.timer.unref();
+      }
+    }
+  }
+  report(log) {
+    if (this.project) {
+      log.project = log.project || this.project;
+    }
+    log.environment = log.environment ?? this.environment;
+    if (this.defaultMetadata) {
+      log.metadata = { ...this.defaultMetadata, ...log.metadata ?? {} };
+    }
+    const raw = JSON.stringify(log);
+    const truncated = truncateUtf8(raw, this.maxLogBytes);
+    if (!truncated.truncated) {
+      this.queue.push(log);
+    } else {
+      this.queue.push({
+        ...log,
+        request: {
+          ...log.request,
+          body_text: "[truncated - log exceeded maxLogBytes]",
+          body_truncated: true
+        },
+        error: log.error ?? { message: "Log truncated to maxLogBytes" }
+      });
+    }
+    if (this.queue.length >= this.maxBatchSize) {
+      this.flush();
+    }
+  }
+  async flush() {
+    if (this.flushing)
+      return;
+    if (this.queue.length === 0)
+      return;
+    this.flushing = true;
+    const batch = this.queue.splice(0, this.maxBatchSize);
+    try {
+      const payload = { logs: batch };
+      const ctrl = new AbortController;
+      const t = setTimeout(() => ctrl.abort(), this.timeoutMs);
+      const res = await fetch(`${this.baseUrl}/v1/logs/batch`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify(payload),
+        signal: ctrl.signal
+      });
+      clearTimeout(t);
+      if (res.status === 207) {
+        const body = await res.json().catch(() => null);
+        const failedIds = new Set;
+        if (body && typeof body === "object") {
+          const failed = body.failed;
+          if (Array.isArray(failed)) {
+            for (const item of failed) {
+              if (item && typeof item === "object") {
+                const id = item.id;
+                if (typeof id === "string") {
+                  failedIds.add(id);
+                }
+              }
+            }
+          }
+        }
+        if (failedIds.size > 0) {
+          const retry = batch.filter((log) => failedIds.has(log.id));
+          if (retry.length > 0) {
+            this.queue.unshift(...retry);
+          }
+        }
+        const partialMessage = body && typeof body === "object" ? body.partial_success?.error_message : undefined;
+        const message = typeof partialMessage === "string" ? partialMessage : "Telemetry partial success";
+        this.onError?.(new Error(message));
+        return;
+      }
+      if (!res.ok) {
+        this.queue.unshift(...batch);
+        const errorText = await res.text().catch(() => "");
+        throw new Error(`Telemetry ingest failed: ${res.status} ${res.statusText} - ${errorText}`);
+      }
+    } catch (err) {
+      this.queue.unshift(...batch);
+      this.onError?.(err);
+    } finally {
+      this.flushing = false;
+    }
+  }
+  async shutdown() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    await this.flush();
+  }
+}
+export {
+  truncateUtf8,
+  toIso,
+  sanitizeHeaders,
+  safeJsonParse,
+  createId,
+  TelemetryClient
+};

package/dist/json.d.ts

@@ -0,0 +1,19 @@
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare function toIso(d: Date): string;
+export declare function createId(): string;
+export declare function safeJsonParse(text: string): {
+    ok: true;
+    value: JsonValue;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function sanitizeHeaders(headers: HeadersInit | undefined): Record<string, string>;
+export declare function truncateUtf8(input: string, maxBytes: number): {
+    text: string;
+    truncated: boolean;
+};
+//# sourceMappingURL=json.d.ts.map

package/dist/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAC7D,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEnF,wBAAgB,KAAK,CAAC,CAAC,EAAE,IAAI,GAAG,MAAM,CAErC;AAED,wBAAgB,QAAQ,IAAI,MAAM,CAIjC;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAOzG;AAUD,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBxF;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAQlG"}

package/dist/types/telemetry.d.ts

@@ -0,0 +1,56 @@
+import type { JsonValue } from "../json";
+export type TelemetryTrace = {
+    trace_id?: string;
+    span_id?: string;
+    parent_span_id?: string;
+};
+export type TelemetryLog = {
+    id: string;
+    timestamp: string;
+    project: string;
+    environment?: string;
+    source: string;
+    method: string;
+    url: string;
+    path: string;
+    model?: string;
+    generation_id?: string;
+    streamed: boolean;
+    timing: {
+        started_at: string;
+        ended_at?: string;
+        duration_ms?: number;
+    };
+    metadata?: Record<string, JsonValue>;
+    trace?: TelemetryTrace;
+    request: {
+        headers?: Record<string, string>;
+        body_json?: JsonValue;
+        body_text?: string;
+        body_truncated?: boolean;
+    };
+    response?: {
+        status: number;
+        headers?: Record<string, string>;
+        body_json?: JsonValue;
+        body_text?: string;
+        body_truncated?: boolean;
+    };
+    stream?: {
+        sse_events?: JsonValue[];
+        sse_events_truncated?: boolean;
+        output_text?: string;
+        tool_calls?: JsonValue;
+        finish_reason?: string | null;
+        usage?: JsonValue;
+    };
+    usage?: JsonValue;
+    error?: {
+        message: string;
+        stack?: string;
+    };
+};
+export type TelemetryBatchPayload = {
+    logs: TelemetryLog[];
+};
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/types/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/types/telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAElB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IAEb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAElB,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IAEF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACrC,KAAK,CAAC,EAAE,cAAc,CAAC;IAEvB,OAAO,EAAE;QACP,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,cAAc,CAAC,EAAE,OAAO,CAAC;KAC1B,CAAC;IAEF,QAAQ,CAAC,EAAE;QACT,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,cAAc,CAAC,EAAE,OAAO,CAAC;KAC1B,CAAC;IAEF,MAAM,CAAC,EAAE;QACP,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC;QACzB,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,CAAC,EAAE,SAAS,CAAC;QACvB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC9B,KAAK,CAAC,EAAE,SAAS,CAAC;KACnB,CAAC;IAEF,KAAK,CAAC,EAAE,SAAS,CAAC;IAElB,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,YAAY,EAAE,CAAC;CACtB,CAAC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "wiretap-llm",
+  "version": "0.1.0",
+  "description": "Telemetry client for sending LLM logs to Wiretap",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target node && tsc --emitDeclarationOnly",
+    "dev": "bun build ./src/index.ts --outdir ./dist --target node --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "llm",
+    "telemetry",
+    "openrouter",
+    "openai",
+    "observability",
+    "monitoring",
+    "ai",
+    "wiretap"
+  ],
+  "author": "Saint",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kingbootoshi/wiretap.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/kingbootoshi/wiretap/issues"
+  },
+  "homepage": "https://github.com/kingbootoshi/wiretap/tree/main/packages/sdk#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  }
+}