retrace-sdk 0.1.6 → 0.2.0

package/src/trace.ts

@@ -1,135 +0,0 @@
-import { genId, nowIso, utcNow } from "./utils.js";
-
-export enum SpanType {
-  LLM_CALL = "llm_call",
-  TOOL_CALL = "tool_call",
-  TOOL_RESULT = "tool_result",
-  REASONING = "reasoning",
-  ACTION = "action",
-  ERROR = "error",
-  FORK_POINT = "fork_point",
-}
-
-export enum TraceStatus {
-  RUNNING = "running",
-  COMPLETED = "completed",
-  FAILED = "failed",
-}
-
-export interface SpanData {
-  id: string;
-  trace_id: string;
-  parent_id: string | null;
-  span_type: string;
-  name: string;
-  model?: string;
-  input?: unknown;
-  output?: unknown;
-  input_tokens?: number;
-  output_tokens?: number;
-  cost?: number;
-  duration_ms?: number;
-  metadata?: Record<string, unknown>;
-  started_at: string;
-  ended_at?: string;
-  error?: string;
-}
-
-export interface TraceData {
-  id: string;
-  name?: string;
-  input?: unknown;
-  output?: unknown;
-  status: string;
-  total_tokens: number;
-  total_cost: number;
-  total_duration_ms: number;
-  metadata?: Record<string, unknown>;
-  started_at: string;
-  ended_at?: string;
-  spans?: SpanData[];
-  project_id?: string;
-}
-
-export class SpanBuilder {
-  private data: Partial<SpanData> & { id: string; span_type: string; name: string };
-  private _startTime?: Date;
-
-  constructor(name: string, spanType: SpanType) {
-    this.data = { id: genId(), span_type: spanType, name, trace_id: "", parent_id: null, started_at: nowIso() };
-  }
-
-  setModel(model: string) { this.data.model = model; return this; }
-  setInput(input: unknown) { this.data.input = input; return this; }
-  setOutput(output: unknown) { this.data.output = output; return this; }
-  setParentId(id: string) { this.data.parent_id = id; return this; }
-  setTraceId(id: string) { this.data.trace_id = id; return this; }
-  setMetadata(m: Record<string, unknown>) { this.data.metadata = m; return this; }
-
-  start(): this {
-    this._startTime = utcNow();
-    this.data.started_at = this._startTime.toISOString();
-    return this;
-  }
-
-  end(output?: unknown, error?: string): SpanData {
-    const now = utcNow();
-    this.data.ended_at = now.toISOString();
-    if (output !== undefined) this.data.output = output;
-    if (error) this.data.error = error;
-    if (this._startTime) {
-      this.data.duration_ms = now.getTime() - this._startTime.getTime();
-    }
-    return this.data as SpanData;
-  }
-
-  get id() { return this.data.id; }
-  toData(): SpanData { return this.data as SpanData; }
-}
-
-export class TraceBuilder {
-  private data: TraceData;
-  private _startTime?: Date;
-
-  constructor() {
-    this.data = {
-      id: genId(),
-      status: TraceStatus.RUNNING,
-      total_tokens: 0,
-      total_cost: 0,
-      total_duration_ms: 0,
-      started_at: nowIso(),
-      spans: [],
-    };
-  }
-
-  start(name?: string, input?: unknown): this {
-    this._startTime = utcNow();
-    this.data.started_at = this._startTime.toISOString();
-    if (name) this.data.name = name;
-    if (input !== undefined) this.data.input = input;
-    return this;
-  }
-
-  end(output?: unknown, status: TraceStatus = TraceStatus.COMPLETED): TraceData {
-    const now = utcNow();
-    this.data.ended_at = now.toISOString();
-    this.data.status = status;
-    if (output !== undefined) this.data.output = output;
-    if (this._startTime) {
-      this.data.total_duration_ms = now.getTime() - this._startTime.getTime();
-    }
-    return this.data;
-  }
-
-  addSpan(span: SpanData) {
-    this.data.spans!.push(span);
-    this.data.total_tokens += (span.input_tokens || 0) + (span.output_tokens || 0);
-    this.data.total_cost += span.cost || 0;
-  }
-
-  get id() { return this.data.id; }
-  setProjectId(id: string) { this.data.project_id = id; }
-  setMetadata(m: Record<string, unknown>) { this.data.metadata = m; }
-  toDict(): TraceData { return this.data; }
-}

package/src/transport.test.ts

@@ -1,80 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { configure } from "./config.js";
-
-// Mock WebSocket to never connect (simulates unreachable WS endpoint)
-const mockWsInstances: Array<Record<string, unknown>> = [];
-vi.mock("ws", () => {
-  const MockWebSocket = function (this: Record<string, unknown>) {
-    this.readyState = 0;
-    this._listeners = {} as Record<string, Array<() => void>>;
-    this.on = (event: string, cb: () => void) => { ((this._listeners as Record<string, Array<() => void>>)[event] ??= []).push(cb); return this; };
-    this.send = vi.fn();
-    this.close = vi.fn(() => {
-      this.readyState = 3;
-      for (const cb of ((this._listeners as Record<string, Array<() => void>>)["close"] ?? [])) cb();
-    });
-    mockWsInstances.push(this);
-  } as unknown as { new(): Record<string, unknown>; OPEN: number };
-  MockWebSocket.OPEN = 1;
-  return { default: MockWebSocket };
-});
-
-beforeEach(() => {
-  configure({ apiKey: "rt_live_test", baseUrl: "http://localhost:3001", enabled: true });
-  mockWsInstances.length = 0;
-});
-
-afterEach(() => {
-  vi.unstubAllGlobals();
-});
-
-describe("Auto transport fallback on early close()", () => {
-  it("flushes to HTTP when close() is called before WS connects", async () => {
-    const mockFetch = vi.fn().mockResolvedValue({ ok: true });
-    vi.stubGlobal("fetch", mockFetch);
-
-    const { createTransport } = await import("./transport.js");
-    const transport = createTransport("auto");
-
-    // Send trace events immediately (before WS could connect)
-    transport.send("trace_started", { id: "t1", name: "fast-trace", status: "running", started_at: "2026-01-01T00:00:00Z", total_tokens: 0, total_cost: 0, total_duration_ms: 0 });
-    transport.send("span_started", { id: "s1", trace_id: "t1", span_type: "llm_call", name: "call", started_at: "2026-01-01T00:00:00Z" });
-    transport.send("span_ended", { id: "s1", ended_at: "2026-01-01T00:00:01Z", output: "response" });
-    transport.send("trace_ended", { id: "t1", ended_at: "2026-01-01T00:00:01Z", status: "completed" });
-
-    // Close immediately — WS has NOT connected yet
-    transport.close();
-
-    // Should have fallen back to HTTP and flushed
-    expect(mockFetch).toHaveBeenCalledTimes(1);
-    const [url, opts] = mockFetch.mock.calls[0];
-    expect(url).toBe("http://localhost:3001/api/v1/traces");
-    const body = JSON.parse(opts.body);
-    expect(body.id).toBe("t1");
-    expect(body.name).toBe("fast-trace");
-    expect(body.spans).toHaveLength(1);
-    expect(body.spans[0].output).toBe("response");
-  });
-
-  it("does NOT reconnect after intentional close()", async () => {
-    vi.stubGlobal("fetch", vi.fn().mockResolvedValue({ ok: true }));
-
-    const { WSTransport } = await import("./transport.js");
-    const ws = new WSTransport();
-    ws.connect();
-
-    // Should have created a WS instance
-    expect(mockWsInstances.length).toBeGreaterThan(0);
-    const instanceCount = mockWsInstances.length;
-
-    // Close intentionally
-    ws.close();
-
-    // Trigger the "close" event that was registered — already fired by our mock's close()
-    // Wait a tick for any setTimeout reconnect to fire
-    await new Promise(r => setTimeout(r, 1100));
-
-    // Should NOT have created new WS instances (no reconnect)
-    expect(mockWsInstances.length).toBe(instanceCount);
-  });
-});

package/src/transport.ts

@@ -1,188 +0,0 @@
-import WebSocket from "ws";
-import { getConfig } from "./config.js";
-
-export interface Transport {
-  send(eventType: string, data: Record<string, unknown>): void;
-  close(): void;
-}
-
-export class WSTransport implements Transport {
-  private ws: WebSocket | null = null;
-  private connected = false;
-  private closed = false;
-  private backoff = 1000;
-  private queue: string[] = [];
-
-  get isConnected() { return this.connected; }
-
-  connect() {
-    if (this.closed) return;
-    const cfg = getConfig();
-    const url = `${cfg.wsUrl}/ws/v1/stream`;
-    this.ws = new WebSocket(url);
-
-    this.ws.on("open", () => {
-      this.ws!.send(JSON.stringify({ type: "auth", api_key: cfg.apiKey }));
-    });
-
-    this.ws.on("message", (raw) => {
-      const msg = JSON.parse(raw.toString());
-      if (msg.type === "auth_ok") {
-        this.connected = true;
-        this.backoff = 1000;
-        this.flushQueue();
-      } else if (msg.type === "ping") {
-        this.ws?.send(JSON.stringify({ type: "pong" }));
-      }
-    });
-
-    this.ws.on("close", () => {
-      this.connected = false;
-      this.ws = null;
-      if (!this.closed) {
-        setTimeout(() => this.reconnect(), this.backoff);
-        this.backoff = Math.min(this.backoff * 2, 30000);
-      }
-    });
-
-    this.ws.on("error", () => {
-      this.ws?.close();
-    });
-  }
-
-  private reconnect() {
-    if (!this.closed && !this.connected && !this.ws) this.connect();
-  }
-
-  private flushQueue() {
-    while (this.queue.length && this.connected) {
-      this.ws?.send(this.queue.shift()!);
-    }
-  }
-
-  send(eventType: string, data: Record<string, unknown>) {
-    const msg = JSON.stringify({ type: eventType, data });
-    if (this.connected && this.ws?.readyState === WebSocket.OPEN) {
-      this.ws.send(msg);
-    } else {
-      this.queue.push(msg);
-      if (!this.ws && !this.closed) this.connect();
-    }
-  }
-
-  close() {
-    this.closed = true;
-    if (this.ws) {
-      this.ws.close();
-      this.ws = null;
-    }
-    this.connected = false;
-  }
-}
-
-export class HTTPTransport implements Transport {
-  private traceData: Record<string, unknown> | null = null;
-  private spans: Record<string, unknown>[] = [];
-
-  send(eventType: string, data: Record<string, unknown>) {
-    if (eventType === "trace_started") {
-      this.traceData = data;
-    } else if (eventType === "span_started" || eventType === "span_ended") {
-      this.spans.push({ ...data, _event: eventType });
-    } else if (eventType === "trace_ended") {
-      if (this.traceData) Object.assign(this.traceData, data);
-      this.flush();
-    }
-  }
-
-  flush() {
-    if (!this.traceData) return;
-    const cfg = getConfig();
-    const url = `${cfg.baseUrl}/api/v1/traces`;
-    const body = { ...this.traceData, spans: this.buildSpans() };
-    fetch(url, {
-      method: "POST",
-      headers: { "x-retrace-key": cfg.apiKey, "Content-Type": "application/json" },
-      body: JSON.stringify(body),
-    }).catch(() => {});
-    this.traceData = null;
-    this.spans = [];
-  }
-
-  private buildSpans(): Record<string, unknown>[] {
-    const merged = new Map<string, Record<string, unknown>>();
-    for (const ev of this.spans) {
-      const { _event, ...rest } = ev;
-      const id = rest.id as string;
-      if (_event === "span_started") {
-        merged.set(id, rest);
-      } else if (_event === "span_ended" && merged.has(id)) {
-        Object.assign(merged.get(id)!, rest);
-      }
-    }
-    return [...merged.values()];
-  }
-
-  close() {
-    this.flush();
-  }
-}
-
-export function createTransport(mode: "ws" | "http" | "auto" = "auto"): Transport {
-  if (mode === "http") return new HTTPTransport();
-  if (mode === "ws") return new WSTransport();
-
-  // Auto: start with WS, fall back to HTTP if connection fails within timeout
-  const ws = new WSTransport();
-  const http = new HTTPTransport();
-  let useWs = true;
-  let decided = false;
-  const buffer: Array<{ eventType: string; data: Record<string, unknown> }> = [];
-
-  const fallbackTimer = setTimeout(() => {
-    if (!decided && !ws.isConnected) {
-      decided = true;
-      useWs = false;
-      ws.close();
-      for (const item of buffer.splice(0)) http.send(item.eventType, item.data);
-    }
-  }, 5000);
-
-  ws.connect();
-
-  const originalSend = ws.send.bind(ws);
-  const checkConnected = () => {
-    if (!decided && ws.isConnected) {
-      decided = true;
-      clearTimeout(fallbackTimer);
-      for (const item of buffer.splice(0)) originalSend(item.eventType, item.data);
-    }
-  };
-
-  return {
-    send(eventType: string, data: Record<string, unknown>) {
-      checkConnected();
-      if (decided) {
-        if (useWs) originalSend(eventType, data);
-        else http.send(eventType, data);
-      } else {
-        buffer.push({ eventType, data });
-      }
-    },
-    close() {
-      clearTimeout(fallbackTimer);
-      if (!decided) {
-        // WS not yet connected — force HTTP fallback to avoid data loss
-        decided = true;
-        useWs = false;
-        ws.close();
-        for (const item of buffer.splice(0)) http.send(item.eventType, item.data);
-        http.close();
-      } else if (useWs) {
-        ws.close();
-      } else {
-        http.close();
-      }
-    },
-  };
-}

package/src/utils.ts

@@ -1,23 +0,0 @@
-import { randomUUID } from "crypto";
-
-export function genId(): string {
-  return randomUUID();
-}
-
-export function nowIso(): string {
-  return new Date().toISOString();
-}
-
-export function utcNow(): Date {
-  return new Date();
-}
-
-export function truncateJson(obj: unknown, maxBytes = 10240): unknown {
-  try {
-    const s = JSON.stringify(obj);
-    if (Buffer.byteLength(s) <= maxBytes) return obj;
-    return JSON.parse(Buffer.from(s).subarray(0, maxBytes).toString());
-  } catch {
-    return String(obj).slice(0, maxBytes);
-  }
-}

package/tsconfig.json

@@ -1,18 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "outDir": "dist",
-    "rootDir": "src",
-    "declaration": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true,
-    "isolatedModules": true
-  },
-  "include": ["src"],
-  "exclude": ["node_modules", "dist"]
-}

package/vitest.config.ts

@@ -1,2 +0,0 @@
-import { defineConfig } from "vitest/config";
-export default defineConfig({ test: { globals: true, environment: "node", include: ["src/**/*.test.ts"] } });