ironside 0.1.0

package/LICENSE.md

@@ -0,0 +1,58 @@
+# Ironside Sustainable Use License v1.0
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject to the limitations below.
+
+## Limitations
+
+**Use.** You may use, modify, and self-host the software — including for your own commercial internal business purposes — subject to the limitations below.
+
+**Competing Use.** You may not use the software to create a product or service that competes with the software or any product or service offered by the licensor. You may not offer the software to third parties on a hosted or managed basis (i.e. running it as a service on your infrastructure for other organizations to use), or embed the software into a product or service you provide to third parties, without a separate commercial agreement with the licensor. Self-hosting the software for your own organization's own use is always permitted and is not a competing use.
+
+**SDK Integration Exception.** Notwithstanding the Competing Use and Distribution limitations, you may use, copy, modify, embed, and distribute the `ironside` client package as part of a product or service you provide to third parties, including for commercial purposes, solely to instrument that product or service and send telemetry to an Ironside deployment. This exception does not permit you to offer Ironside itself as a hosted or managed service for third parties, distribute the SDK as a standalone paid product, or use the SDK to create a product or service that competes with Ironside.
+
+**Distribution.** You may distribute the software or provide it to others only if you do so free of charge for non-commercial purposes, or with a separate commercial agreement with the licensor.
+
+**Attribution.** You may not alter, remove, or obscure any licensing, copyright, or other notices of the licensor in the software. Any use of the licensor's trademarks is subject to applicable law.
+
+## Patent License
+
+The licensor grants you a license, under any patent claims the licensor can license or becomes able to license, to make, have made, use, sell, offer for sale, import, and have imported the software, in each case subject to the limitations and conditions in this license. This patent license does not cover any patent claims that you cause to be infringed by modifications or additions to the software. If you or your company make any written claim that the software infringes or contributes to the infringement of any patent, your patent license for the software granted under these terms ends immediately.
+
+## Distribution Requirements
+
+If you distribute copies or modifications of the software, you must:
+
+1. Give each recipient a copy of this license.
+2. Include a prominent notice in any modified version stating that you have modified the software.
+
+## Fair Use
+
+This license is not intended to limit any rights you have under applicable copyright doctrines of fair use, fair dealing, or other equivalents.
+
+## Termination
+
+If you use the software in violation of this license, such use is not licensed, and your license will automatically terminate. If the licensor provides you with a notice of your violation, and you cease all violation of this license no later than 30 days after you receive that notice, your license will be reinstated. If you violate these license terms after such reinstatement, any further violation of these terms will cause your license to terminate automatically and permanently.
+
+## No Liability
+
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.
+
+## Definitions
+
+The **licensor** is the entity offering these terms — Luka Živković.
+
+The **software** is the software the licensor makes available under these terms, including any portion of it.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. Control means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+---
+
+Copyright 2026 Luka Živković. All rights reserved.

package/README.md

@@ -0,0 +1,91 @@
+# `ironside`
+
+The official Node.js/TypeScript client for sending LLM traces directly to Ironside. It provides automatic OpenAI and Anthropic instrumentation, manual trace/span/generation handles, media uploads, and score recording.
+
+Requires Node.js 20 or newer. The package is ESM-only.
+
+## Install
+
+Install the SDK together with whichever provider client your application uses:
+
+```sh
+npm install ironside openai
+# or: npm install ironside @anthropic-ai/sdk
+```
+
+Provider packages are not runtime dependencies of `ironside`; the wrappers accept the client instance already used by your application.
+
+## Provider wrappers
+
+```ts
+import OpenAI from "openai";
+import { init, wrapOpenAI } from "ironside";
+
+const ironside = init({
+  apiKey: process.env.IRONSIDE_API_KEY!,
+  host: process.env.IRONSIDE_HOST ?? "http://localhost:8788",
+  onError(error) {
+    console.error("Ironside ingest failed", error);
+  }
+});
+
+const openai = wrapOpenAI(
+  new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+  ironside
+);
+
+await openai.chat.completions.create({
+  model: "gpt-4o",
+  messages: [{ role: "user", content: "Hello" }]
+});
+
+await ironside.shutdown();
+```
+
+`wrapAnthropic(client, ironside)` instruments `messages.create()` in the same way. Both wrappers mutate and return the same provider client, preserve streaming behavior, and record input/output, model, token usage, and common sampling parameters. For OpenAI streaming token usage, request `stream_options: { include_usage: true }`.
+
+## Manual instrumentation
+
+```ts
+import { init } from "ironside";
+
+const ironside = init({
+  apiKey: process.env.IRONSIDE_API_KEY!,
+  host: "https://ironside.example.com"
+});
+
+const trace = ironside.trace({
+  name: "answer-question",
+  userId: "user-123",
+  input: { question: "Why is the sky blue?" }
+});
+
+const generation = trace.generation({
+  name: "generate-answer",
+  model: "example-model",
+  input: { prompt: "Why is the sky blue?" }
+});
+
+generation.end({
+  output: { answer: "Rayleigh scattering." },
+  usageDetails: { input_tokens: 8, output_tokens: 4 },
+  costDetails: { total_usd: 0.00012 }
+});
+
+trace.score({ name: "correctness", value: 1, source: "eval" });
+trace.update({ output: { answer: "Rayleigh scattering." } });
+
+await ironside.shutdown();
+```
+
+Instrumentation calls buffer events and do not block application requests. Call `flush()` at a lifecycle boundary when needed, and always call `shutdown()` during graceful process termination so buffered and in-flight events finish sending. Failed background batches are reported through `onError`; they are not thrown into the instrumented request path.
+
+`recordGenerateTextResult()` is available for results returned by the Vercel AI SDK. `uploadMedia()` stores binary content separately and returns an `ironside://media/...` reference suitable for trace input or output.
+
+## Choosing an integration
+
+This package is the ergonomic Node.js integration and supports Ironside-specific cost and score fields. Third-party frameworks and non-Node runtimes should prefer Ironside's canonical OTLP/HTTP endpoint with OpenTelemetry `gen_ai.*` attributes. Low-level integrations can send the native JSON envelope directly at `POST /api/v1/ingest`.
+
+## License
+
+[Ironside Sustainable Use License v1.0](./LICENSE.md), including its SDK Integration Exception for embedding and distributing this package as part of commercial applications that send telemetry to Ironside.

package/dist/src/batcher.d.ts

@@ -0,0 +1,51 @@
+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;
+}
+/**
+ * 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 declare class EventBatcher {
+    private readonly apiKey;
+    private readonly host;
+    private readonly maxBatchSize;
+    private readonly flushIntervalMs;
+    private readonly fetchImpl;
+    private readonly onError;
+    private buffer;
+    private timer;
+    private inFlight;
+    private closed;
+    constructor(options: BatcherOptions);
+    enqueue(event: IngestRequestEvent): void;
+    /** Sends whatever is currently buffered. Safe to call concurrently — flushes serialize via inFlight. */
+    flush(): Promise<void>;
+    private send;
+    /**
+     * 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.
+     */
+    close(): Promise<void>;
+}

package/dist/src/batcher.js

@@ -0,0 +1,90 @@
+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 {
+    apiKey;
+    host;
+    maxBatchSize;
+    flushIntervalMs;
+    fetchImpl;
+    onError;
+    buffer = [];
+    timer = null;
+    inFlight = Promise.resolve();
+    closed = false;
+    constructor(options) {
+        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) {
+        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() {
+        if (this.buffer.length === 0)
+            return;
+        const events = this.buffer;
+        this.buffer = [];
+        this.inFlight = this.inFlight.then(() => this.send(events));
+        await this.inFlight;
+    }
+    async send(events) {
+        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() {
+        this.closed = true;
+        if (this.timer)
+            clearInterval(this.timer);
+        await this.flush();
+        await this.inFlight;
+    }
+}
+//# sourceMappingURL=batcher.js.map

package/dist/src/batcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batcher.js","sourceRoot":"","sources":["../../src/batcher.ts"],"names":[],"mappings":"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"}

package/dist/src/client.d.ts

@@ -0,0 +1,70 @@
+import { 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 declare function init(options: IronsideClientOptions): IronsideClient;

package/dist/src/client.js

@@ -0,0 +1,171 @@
+import { ulid } from "ulid";
+import { EventBatcher } from "./batcher.js";
+/**
+ * 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) {
+    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, observationId, scoreOptions) {
+        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, traceId, type, parentObservationId, startOptions) {
+        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) {
+            return (options = {}) => makeObservationHandle(ulid(), traceId, childType, id, options);
+        }
+        return {
+            id,
+            span: child("span"),
+            generation: child("generation"),
+            end(endOptions = {}) {
+                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) => enqueueScore(traceId, id, scoreOptions)
+        };
+    }
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const host = options.host.replace(/\/$/, "");
+    return {
+        async uploadMedia(uploadOptions) {
+            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
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                throw new Error(`media upload failed: ${res.status}${text ? ` ${text}` : ""}`);
+            }
+            return (await res.json());
+        },
+        trace(startOptions = {}) {
+            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 = {}) => makeObservationHandle(ulid(), id, "span", undefined, options),
+                generation: (options = {}) => makeObservationHandle(ulid(), id, "generation", undefined, options),
+                update(updateOptions) {
+                    // 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) => enqueueScore(id, undefined, scoreOptions)
+            };
+        },
+        flush: () => batcher.flush(),
+        shutdown: () => batcher.close()
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/src/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -0,0 +1,9 @@
+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/dist/src/index.js

@@ -0,0 +1,5 @@
+export { init } from "./client.js";
+export { wrapOpenAI } from "./wrappers/openai.js";
+export { wrapAnthropic } from "./wrappers/anthropic.js";
+export { recordGenerateTextResult } from "./wrappers/vercel-ai.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAkBnC,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAExD,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/src/types.d.ts

@@ -0,0 +1,64 @@
+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;
+}
+export {};

package/dist/src/types.js

@@ -0,0 +1,6 @@
+// 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 {};
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,2EAA2E;AAC3E,wEAAwE;AACxE,oCAAoC"}