@lanefoundry/gatelane-sdk 0.0.0-stage → 0.1.0

package/src/storage-http.ts

@@ -0,0 +1,143 @@
+/**
+ * HTTP storage adapter — sends capture records to a gatelane Worker endpoint.
+ *
+ * Production: `https://<your-worker>.workers.dev/v1/capture`
+ * Local dev:  `http://localhost:8787/v1/capture`
+ *
+ * The Worker writes the record body to R2 (raw blob) and the metadata to D1.
+ * This adapter only handles transport; the storage / persistence happens server-side.
+ *
+ * Retries: 3 attempts with exponential backoff on 5xx / network errors.
+ *
+ * @see docs/prd.md §6.1 — Cloudflare-first deployment
+ */
+
+import type { CaptureRecord, StorageAdapter, WriteResult } from './storage.js';
+
+export type HttpStorageOptions = {
+  /** Base URL of the gatelane Worker, no trailing slash. */
+  readonly endpoint: string;
+  /** Bearer token for the `/v1/capture` route. */
+  readonly token: string;
+  /** Max retry attempts on transient failures. Defaults to 3. */
+  readonly maxRetries?: number;
+  /** Initial backoff in ms. Doubles each retry. Defaults to 200. */
+  readonly initialBackoffMs?: number;
+  /** Override fetch for testing. Defaults to global fetch. */
+  readonly fetchImpl?: typeof fetch;
+};
+
+export class HttpStorage implements StorageAdapter {
+  readonly name: string;
+  private readonly endpoint: string;
+  private readonly token: string;
+  private readonly maxRetries: number;
+  private readonly initialBackoffMs: number;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(opts: HttpStorageOptions) {
+    this.endpoint = opts.endpoint.replace(/\/$/, '');
+    this.token = opts.token;
+    this.maxRetries = opts.maxRetries ?? 3;
+    this.initialBackoffMs = opts.initialBackoffMs ?? 200;
+    this.fetchImpl = opts.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    this.name = `http(${new URL(this.endpoint).host})`;
+  }
+
+  async write(record: CaptureRecord): Promise<WriteResult> {
+    const url = `${this.endpoint}/v1/capture`;
+    let lastErr: unknown = null;
+    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+      try {
+        const response = await this.fetchImpl(url, {
+          method: 'POST',
+          headers: {
+            'content-type': 'application/json',
+            authorization: `Bearer ${this.token}`,
+            'x-gatelane-span-kind': record.span_kind ?? 'gate.replay',
+          },
+          body: JSON.stringify(record),
+        });
+        if (response.ok) {
+          const body = (await response.json()) as { id: string; stored_at: string };
+          return { id: body.id, stored_at: body.stored_at, backend: this.name };
+        }
+        // 4xx is fatal — don't retry. 5xx is transient — retry.
+        if (response.status >= 400 && response.status < 500) {
+          throw new Error(`capture write rejected: ${response.status} ${response.statusText}`);
+        }
+        lastErr = new Error(`capture write failed: ${response.status} ${response.statusText}`);
+      } catch (err) {
+        // Re-throw 4xx immediately so the caller sees the rejection; only network / 5xx retries.
+        if (err instanceof Error && err.message.startsWith('capture write rejected')) {
+          throw err;
+        }
+        lastErr = err;
+      }
+      // Backoff before next attempt (5xx / network path).
+      if (attempt < this.maxRetries - 1) {
+        const delay = this.initialBackoffMs * Math.pow(2, attempt);
+        const { promise, resolve } = Promise.withResolvers<void>();
+        setTimeout(resolve, delay);
+        await promise;
+      }
+    }
+    throw new Error(`capture write failed after ${this.maxRetries} attempts: ${String(lastErr)}`);
+  }
+
+  async read(_id: string): Promise<CaptureRecord | null> {
+    // Worker exposes GET /v1/capture/:id in v0.2. Stub: return null.
+    // Returning null means "not in local cache; ask the Worker". Tests don't depend on read.
+    return null;
+  }
+
+  async list(filter: { source_kind?: string; since?: string; limit?: number } = {}): Promise<ReadonlyArray<CaptureRecord>> {
+    const params = new URLSearchParams();
+    if (filter.since !== undefined) params.set('since', filter.since);
+    if (filter.limit !== undefined) params.set('limit', String(filter.limit));
+    const url = `${this.endpoint}/v1/captures${params.size > 0 ? '?' + params.toString() : ''}`;
+    const response = await this.fetchImpl(url, {
+      headers: { authorization: `Bearer ${this.token}` },
+    });
+    if (!response.ok) {
+      throw new Error(`capture list failed: ${response.status} ${response.statusText}`);
+    }
+    const body = (await response.json()) as { captures: WireCaptureRecord[] };
+    let out = body.captures.map(wireToLocal);
+    if (filter.source_kind !== undefined) {
+      out = out.filter((r) => r.input.metadata?.['source_kind'] === filter.source_kind);
+    }
+    return out;
+  }
+}
+
+/** Wire shape returned by GET /v1/captures (matches packages/shared/src/types.ts CaptureRecord). */
+type WireCaptureRecord = {
+  readonly id: string;
+  readonly traceId: string;
+  readonly prompt: ReadonlyArray<{ role: string; content: string }>;
+  readonly response: unknown;
+  readonly model: string;
+  readonly provider: string;
+  readonly costCents: number;
+  readonly latencyMs: number;
+  readonly metadata: Record<string, unknown>;
+  readonly createdAt: string;
+};
+
+/** Convert a wire capture row back into the SDK's CapturedCall shape. */
+function wireToLocal(row: WireCaptureRecord): CaptureRecord {
+  return {
+    id: row.id,
+    input: {
+      prompt: row.prompt,
+      model: row.model,
+      metadata: row.metadata,
+    },
+    output: row.response,
+    started_at: row.createdAt,
+    completed_at: row.createdAt,
+    cost_usd: row.costCents / 100,
+    latency_ms: row.latencyMs,
+  };
+}

package/src/storage.ts

@@ -0,0 +1,97 @@
+/**
+ * Storage adapter — pluggable back-end for capture records.
+ *
+ * gatelane's capture SDK is host-agnostic: the same SDK can write to in-memory
+ * (tests), filesystem (local dev), or HTTP (production, talking to a Cloudflare
+ * Worker that writes to R2/D1).
+ *
+ * @see docs/prd.md §5.4 — Shared engine
+ */
+
+export type D1DatabaseLike = {
+  prepare(query: string): D1PreparedStatementLike;
+};
+
+export type D1PreparedStatementLike = {
+  bind(...values: unknown[]): D1PreparedStatementLike;
+  first<T = unknown>(column?: string): Promise<T | null>;
+  run(): Promise<{ success: boolean }>;
+  all<T = unknown>(): Promise<{ results: T[] }>;
+};
+
+export type R2BucketLike = {
+  put(key: string, value: ReadableStream | ArrayBuffer | string, options?: { httpMetadata?: { contentType?: string } }): Promise<unknown>;
+  get(key: string): Promise<{ body: ReadableStream; httpMetadata?: { contentType?: string } } | null>;
+  delete(key: string): Promise<void>;
+};
+
+import type { CapturedCall } from './capture.js';
+export type CaptureRecord = CapturedCall;
+
+/** Result of a successful write. */
+export type WriteResult = {
+  readonly id: string;
+  readonly stored_at: string;
+  readonly backend: string;
+};
+
+/** Storage back-end interface. All implementations must be safe to call concurrently. */
+export interface StorageAdapter {
+  /** Persist a capture record. Returns the canonical id + storage timestamp. */
+  write(record: CaptureRecord): Promise<WriteResult>;
+  /** Read back a record by id. Returns null if not found. */
+  read(id: string): Promise<CaptureRecord | null>;
+  /** List records matching a filter. Used by the freeze-slice tool. */
+  list(filter: { source_kind?: string; since?: string; limit?: number }): Promise<ReadonlyArray<CaptureRecord>>;
+  /** Identity of the backend (for debugging + audit). */
+  readonly name: string;
+}
+
+/** In-memory adapter. Default for tests; never persisted across restarts. */
+export class InMemoryStorage implements StorageAdapter {
+  readonly name = 'memory';
+  private readonly records = new Map<string, CaptureRecord>();
+
+  async write(record: CaptureRecord): Promise<WriteResult> {
+    this.records.set(record.id, record);
+    return {
+      id: record.id,
+      stored_at: new Date().toISOString(),
+      backend: this.name,
+    };
+  }
+
+  async read(id: string): Promise<CaptureRecord | null> {
+    return this.records.get(id) ?? null;
+  }
+
+  async list(filter: { source_kind?: string; since?: string; limit?: number }): Promise<ReadonlyArray<CaptureRecord>> {
+    let out = Array.from(this.records.values());
+    if (filter.source_kind !== undefined) {
+      out = out.filter((r) => r.input.metadata?.['source_kind'] === filter.source_kind);
+    }
+    if (filter.since !== undefined) {
+      const since = Date.parse(filter.since);
+      out = out.filter((r) => Date.parse(r.started_at) >= since);
+    }
+    if (filter.limit !== undefined) {
+      out = out.slice(0, filter.limit);
+    }
+    return out;
+  }
+}
+
+/** Active storage. Module-level mutable singleton — initialized once. */
+let activeStorage: StorageAdapter = new InMemoryStorage();
+
+/** Replace the active storage backend. Returns the previous backend for restoration in tests. */
+export function setStorage(adapter: StorageAdapter): StorageAdapter {
+  const previous = activeStorage;
+  activeStorage = adapter;
+  return previous;
+}
+
+/** Get the active storage backend. */
+export function getStorage(): StorageAdapter {
+  return activeStorage;
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.