ironside 0.1.0

package/src/batcher.ts

@@ -0,0 +1,109 @@
+import type { IngestRequestEvent } from "./types.js";
+
+export interface BatcherOptions {
+  apiKey: string;
+  host: string;
+  /** Flush automatically once this many events are buffered. */
+  maxBatchSize?: number;
+  /** Flush automatically after this many ms, even if under maxBatchSize. */
+  flushIntervalMs?: number;
+  /** Injectable for tests; defaults to global fetch. */
+  fetchImpl?: typeof fetch;
+  /** Called with a failed batch's events + the error; default: console.error. Never throws back into the caller's hot path. */
+  onError?: (error: unknown, events: IngestRequestEvent[]) => void;
+}
+
+const DEFAULT_MAX_BATCH_SIZE = 50;
+const DEFAULT_FLUSH_INTERVAL_MS = 5000;
+
+/**
+ * Buffers ingest events in memory and flushes them to POST /api/v1/ingest
+ * in the background — instrumentation calls (trace/span/generation) never
+ * block on network I/O. Flushes are fire-and-forget from the caller's
+ * perspective; failures are reported via onError, not thrown, since a
+ * trace SDK must never be the reason an application request fails.
+ */
+export class EventBatcher {
+  private readonly apiKey: string;
+  private readonly host: string;
+  private readonly maxBatchSize: number;
+  private readonly flushIntervalMs: number;
+  private readonly fetchImpl: typeof fetch;
+  private readonly onError: (error: unknown, events: IngestRequestEvent[]) => void;
+
+  private buffer: IngestRequestEvent[] = [];
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private inFlight: Promise<void> = Promise.resolve();
+  private closed = false;
+
+  constructor(options: BatcherOptions) {
+    this.apiKey = options.apiKey;
+    this.host = options.host.replace(/\/$/, "");
+    this.maxBatchSize = options.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE;
+    this.flushIntervalMs = options.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+    this.fetchImpl = options.fetchImpl ?? fetch;
+    this.onError =
+      options.onError ??
+      ((error) => console.error("[ironside] failed to send trace events:", error));
+
+    this.timer = setInterval(() => void this.flush(), this.flushIntervalMs);
+    // Don't let the flush timer keep the process alive on its own.
+    this.timer.unref?.();
+  }
+
+  enqueue(event: IngestRequestEvent): void {
+    if (this.closed) return;
+    this.buffer.push(event);
+    if (this.buffer.length >= this.maxBatchSize) {
+      void this.flush();
+    }
+  }
+
+  /** Sends whatever is currently buffered. Safe to call concurrently — flushes serialize via inFlight. */
+  async flush(): Promise<void> {
+    if (this.buffer.length === 0) return;
+    const events = this.buffer;
+    this.buffer = [];
+
+    this.inFlight = this.inFlight.then(() => this.send(events));
+    await this.inFlight;
+  }
+
+  private async send(events: IngestRequestEvent[]): Promise<void> {
+    try {
+      const res = await this.fetchImpl(`${this.host}/api/v1/ingest`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({ events })
+      });
+      if (!res.ok) {
+        this.onError(new Error(`ingest request failed: HTTP ${res.status}`), events);
+      }
+    } catch (error) {
+      this.onError(error, events);
+    }
+  }
+
+  /**
+   * Stops the background timer and flushes any remaining buffered events.
+   * Call on process shutdown.
+   *
+   * Must wait on `inFlight` explicitly, not just call `flush()` — if a
+   * different caller (the interval timer, or an enqueue() that just hit
+   * maxBatchSize) already claimed the buffer into its own in-progress
+   * send() moments earlier, flush() here sees an empty buffer and returns
+   * immediately without waiting for that still-pending request. Without
+   * this, shutdown() could resolve while a real network request is still
+   * in flight, and an immediately-following process.exit() would silently
+   * drop that batch.
+   */
+  async close(): Promise<void> {
+    this.closed = true;
+    if (this.timer) clearInterval(this.timer);
+    await this.flush();
+    await this.inFlight;
+  }
+}

package/src/client.ts

@@ -0,0 +1,267 @@
+import { ulid } from "ulid";
+import { EventBatcher, type BatcherOptions } from "./batcher.js";
+import type {
+  EndObservationOptions,
+  ScoreOptions,
+  StartGenerationOptions,
+  StartSpanOptions,
+  StartTraceOptions,
+  UpdateTraceOptions
+} from "./types.js";
+
+export interface IronsideClientOptions {
+  apiKey: string;
+  /** Ironside API host, e.g. "https://ironside.example.com" or "http://localhost:8788". */
+  host: string;
+  maxBatchSize?: number;
+  flushIntervalMs?: number;
+  fetchImpl?: BatcherOptions["fetchImpl"];
+  onError?: BatcherOptions["onError"];
+}
+
+export interface ObservationHandle {
+  readonly id: string;
+  /** Starts a child span nested under this observation. */
+  span(options?: StartSpanOptions): ObservationHandle;
+  /** Starts a child generation nested under this observation. */
+  generation(options?: StartGenerationOptions): ObservationHandle;
+  /** Marks this observation complete. Safe to call at most once meaningfully; a second call overwrites endTime. */
+  end(options?: EndObservationOptions): void;
+  /** Records a score (user feedback, eval result, ...) attached to this observation. */
+  score(options: ScoreOptions): void;
+}
+
+export interface TraceHandle {
+  readonly id: string;
+  span(options?: StartSpanOptions): ObservationHandle;
+  generation(options?: StartGenerationOptions): ObservationHandle;
+  update(options: UpdateTraceOptions): void;
+  /** Records a score (user feedback, eval result, ...) attached to this trace. */
+  score(options: ScoreOptions): void;
+}
+
+export interface UploadMediaOptions {
+  /** The raw bytes to store. */
+  data: Uint8Array | ArrayBuffer;
+  /** Real content type of the bytes, e.g. "image/png". */
+  contentType: string;
+}
+
+export interface UploadedMedia {
+  id: string;
+  /** Compact ref string ("ironside://media/<id>") to embed in trace input/output/metadata. */
+  ref: string;
+  contentType: string;
+  sizeBytes: number;
+  sha256: string;
+}
+
+export interface IronsideClient {
+  trace(options?: StartTraceOptions): TraceHandle;
+  /**
+   * Uploads a media blob (image, audio, document, ...) and returns a
+   * compact ref string to embed in trace input/output instead of the
+   * bytes themselves — base64 payloads inside trace JSON bloat the
+   * columnar store. Content-addressed: uploading identical bytes twice
+   * returns the same asset. Unlike instrumentation calls this awaits the
+   * network (the ref doesn't exist until the server has the bytes).
+   */
+  uploadMedia(options: UploadMediaOptions): Promise<UploadedMedia>;
+  /** Sends buffered events immediately instead of waiting for the next automatic flush. */
+  flush(): Promise<void>;
+  /** Stops background flushing and sends any remaining buffered events. Call before process exit. */
+  shutdown(): Promise<void>;
+}
+
+/**
+ * Creates an Ironside client. Instrumentation calls (trace/span/generation)
+ * never block on network I/O — events are buffered and flushed in the
+ * background. Deliberately does NOT auto-register a process-exit handler:
+ * doing that inside a library is a footgun (can't be un-registered,
+ * surprising under multiple init() calls or in serverless runtimes with
+ * their own lifecycle hooks). Call `shutdown()` explicitly wherever your
+ * app already handles graceful shutdown.
+ */
+export function init(options: IronsideClientOptions): IronsideClient {
+  const batcher = new EventBatcher({
+    apiKey: options.apiKey,
+    host: options.host,
+    ...(options.maxBatchSize !== undefined && { maxBatchSize: options.maxBatchSize }),
+    ...(options.flushIntervalMs !== undefined && { flushIntervalMs: options.flushIntervalMs }),
+    ...(options.fetchImpl !== undefined && { fetchImpl: options.fetchImpl }),
+    ...(options.onError !== undefined && { onError: options.onError })
+  });
+
+  function enqueueScore(
+    traceId: string,
+    observationId: string | undefined,
+    scoreOptions: ScoreOptions
+  ): void {
+    batcher.enqueue({
+      type: "score-upsert",
+      body: {
+        id: scoreOptions.id ?? ulid(),
+        traceId,
+        ...(observationId && { observationId }),
+        name: scoreOptions.name,
+        dataType: scoreOptions.value !== undefined ? "numeric" : "categorical",
+        source: scoreOptions.source ?? "api",
+        ...(scoreOptions.value !== undefined && { value: scoreOptions.value }),
+        ...(scoreOptions.stringValue !== undefined && { stringValue: scoreOptions.stringValue }),
+        ...(scoreOptions.comment && { comment: scoreOptions.comment }),
+        timestamp: new Date().toISOString(),
+        metadata: scoreOptions.metadata ?? {}
+      }
+    });
+  }
+
+  function makeObservationHandle(
+    id: string,
+    traceId: string,
+    type: "span" | "generation",
+    parentObservationId: string | undefined,
+    startOptions: StartSpanOptions | StartGenerationOptions
+  ): ObservationHandle {
+    const startTime = new Date().toISOString();
+    const model = "model" in startOptions ? startOptions.model : undefined;
+    const modelParameters =
+      "modelParameters" in startOptions ? startOptions.modelParameters : undefined;
+
+    batcher.enqueue({
+      type: "observation-upsert",
+      body: {
+        id,
+        traceId,
+        ...(parentObservationId && { parentObservationId }),
+        type,
+        ...(startOptions.name && { name: startOptions.name }),
+        startTime,
+        ...(model && { model }),
+        ...(modelParameters && { modelParameters }),
+        ...(startOptions.input !== undefined && { input: startOptions.input }),
+        metadata: startOptions.metadata ?? {}
+      }
+    });
+
+    function child(childType: "span" | "generation") {
+      return (options: StartSpanOptions | StartGenerationOptions = {}) =>
+        makeObservationHandle(ulid(), traceId, childType, id, options);
+    }
+
+    return {
+      id,
+      span: child("span"),
+      generation: child("generation"),
+      end(endOptions: EndObservationOptions = {}) {
+        batcher.enqueue({
+          type: "observation-upsert",
+          body: {
+            id,
+            traceId,
+            ...(parentObservationId && { parentObservationId }),
+            type,
+            ...(startOptions.name && { name: startOptions.name }),
+            startTime,
+            endTime: new Date().toISOString(),
+            level: endOptions.level ?? "default",
+            ...(model && { model }),
+            ...(modelParameters && { modelParameters }),
+            ...(startOptions.input !== undefined && { input: startOptions.input }),
+            ...(endOptions.output !== undefined && { output: endOptions.output }),
+            ...(endOptions.statusMessage && { statusMessage: endOptions.statusMessage }),
+            ...(endOptions.usageDetails && { usageDetails: endOptions.usageDetails }),
+            ...(endOptions.costDetails && { costDetails: endOptions.costDetails }),
+            metadata: { ...startOptions.metadata, ...endOptions.metadata }
+          }
+        });
+      },
+      score: (scoreOptions: ScoreOptions) => enqueueScore(traceId, id, scoreOptions)
+    };
+  }
+
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const host = options.host.replace(/\/$/, "");
+
+  return {
+    async uploadMedia(uploadOptions: UploadMediaOptions): Promise<UploadedMedia> {
+      const body =
+        uploadOptions.data instanceof ArrayBuffer
+          ? new Uint8Array(uploadOptions.data)
+          : uploadOptions.data;
+      const res = await fetchImpl(`${host}/api/v1/media`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${options.apiKey}`,
+          "content-type": uploadOptions.contentType
+        },
+        // DOM's BodyInit type isn't in the SDK's lib set; Uint8Array is a
+        // valid fetch body in Node 18+ and browsers alike.
+        body: body as unknown as NonNullable<RequestInit["body"]>
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`media upload failed: ${res.status}${text ? ` ${text}` : ""}`);
+      }
+      return (await res.json()) as UploadedMedia;
+    },
+
+    trace(startOptions: StartTraceOptions = {}) {
+      const id = startOptions.id ?? ulid();
+      // Fixed at trace-start time and reused by update() below — the trace's
+      // timestamp must not drift to "whenever update() happened to be
+      // called" (e.g. re-stamping it at completion time would corrupt the
+      // recorded start time on every partial update).
+      const timestamp = new Date().toISOString();
+      batcher.enqueue({
+        type: "trace-upsert",
+        body: {
+          id,
+          timestamp,
+          ...(startOptions.name && { name: startOptions.name }),
+          ...(startOptions.userId && { userId: startOptions.userId }),
+          ...(startOptions.sessionId && { sessionId: startOptions.sessionId }),
+          ...(startOptions.environment && { environment: startOptions.environment }),
+          ...(startOptions.release && { release: startOptions.release }),
+          ...(startOptions.version && { version: startOptions.version }),
+          tags: startOptions.tags ?? [],
+          metadata: startOptions.metadata ?? {},
+          ...(startOptions.input !== undefined && { input: startOptions.input })
+        }
+      });
+
+      return {
+        id,
+        span: (options: StartSpanOptions = {}) =>
+          makeObservationHandle(ulid(), id, "span", undefined, options),
+        generation: (options: StartGenerationOptions = {}) =>
+          makeObservationHandle(ulid(), id, "generation", undefined, options),
+        update(updateOptions: UpdateTraceOptions) {
+          // A trace-upsert replaces the whole row (ClickHouse
+          // ReplacingMergeTree has no field-level merge) — every field set
+          // by trace() must be carried forward here too, or update() would
+          // silently wipe name/userId/sessionId/input back to absent.
+          batcher.enqueue({
+            type: "trace-upsert",
+            body: {
+              id,
+              timestamp,
+              ...(startOptions.name && { name: startOptions.name }),
+              ...(startOptions.userId && { userId: startOptions.userId }),
+              ...(startOptions.sessionId && { sessionId: startOptions.sessionId }),
+              ...(startOptions.environment && { environment: startOptions.environment }),
+              ...(startOptions.release && { release: startOptions.release }),
+              ...(startOptions.version && { version: startOptions.version }),
+              tags: startOptions.tags ?? [],
+              ...(startOptions.input !== undefined && { input: startOptions.input }),
+              ...(updateOptions.output !== undefined && { output: updateOptions.output }),
+              metadata: { ...startOptions.metadata, ...updateOptions.metadata }
+            }
+          });
+        },
+        score: (scoreOptions: ScoreOptions) => enqueueScore(id, undefined, scoreOptions)
+      };
+    },
+    flush: () => batcher.flush(),
+    shutdown: () => batcher.close()
+  };
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+export { init } from "./client.js";
+export type {
+  IronsideClient,
+  IronsideClientOptions,
+  TraceHandle,
+  ObservationHandle,
+  UploadMediaOptions,
+  UploadedMedia
+} from "./client.js";
+export type {
+  StartTraceOptions,
+  UpdateTraceOptions,
+  StartSpanOptions,
+  StartGenerationOptions,
+  EndObservationOptions,
+  ScoreOptions
+} from "./types.js";
+
+export { wrapOpenAI } from "./wrappers/openai.js";
+export type { WrapOpenAIOptions } from "./wrappers/openai.js";
+export { wrapAnthropic } from "./wrappers/anthropic.js";
+export type { WrapAnthropicOptions } from "./wrappers/anthropic.js";
+export { recordGenerateTextResult } from "./wrappers/vercel-ai.js";
+export type { RecordGenerateTextOptions } from "./wrappers/vercel-ai.js";

package/src/types.ts

@@ -0,0 +1,75 @@
+// Wire-contract types, deliberately duplicated from (not imported from)
+// @ironside/shared: this package ships standalone to npm and cannot depend
+// on a private workspace package. Kept intentionally minimal — only the
+// fields the SDK itself constructs.
+
+export interface StartTraceOptions {
+  id?: string;
+  name?: string;
+  userId?: string;
+  sessionId?: string;
+  environment?: string;
+  release?: string;
+  version?: string;
+  tags?: string[];
+  metadata?: Record<string, string>;
+  input?: unknown;
+}
+
+export interface UpdateTraceOptions {
+  output?: unknown;
+  metadata?: Record<string, string>;
+}
+
+interface ScoreOptionsBase {
+  id?: string;
+  /** Attaches the score to a specific observation instead of the trace as a whole. */
+  observationId?: string;
+  name: string;
+  source?: "api" | "eval" | "annotation";
+  comment?: string;
+  metadata?: Record<string, string>;
+}
+
+/**
+ * Exactly one of value/stringValue — enforced at the type level (not just
+ * documented) so a caller can't produce a score with neither (dropped
+ * server-side against the domain schema's invariant, silently, since the
+ * SDK's ingest is fire-and-forget) or both (an internally inconsistent
+ * dataType/payload pairing).
+ */
+export type ScoreOptions =
+  | (ScoreOptionsBase & { value: number; stringValue?: undefined })
+  | (ScoreOptionsBase & { stringValue: string; value?: undefined });
+
+export interface StartSpanOptions {
+  id?: string;
+  name?: string;
+  input?: unknown;
+  metadata?: Record<string, string>;
+}
+
+export interface StartGenerationOptions extends StartSpanOptions {
+  model?: string;
+  modelParameters?: Record<string, string | number | boolean | null>;
+}
+
+export interface EndObservationOptions {
+  output?: unknown;
+  statusMessage?: string;
+  level?: "debug" | "default" | "warning" | "error";
+  usageDetails?: Record<string, number>;
+  costDetails?: Record<string, number>;
+  metadata?: Record<string, string>;
+}
+
+export type IngestEventType =
+  | "trace-upsert"
+  | "observation-upsert"
+  | "score-upsert";
+
+export interface IngestRequestEvent {
+  id?: string;
+  type: IngestEventType;
+  body: unknown;
+}