The TypeScript SDK (sdk/typescript, package name @ledger/sdk) is the reference implementation — full parity, including auto-instrumentation for Anthropic and OpenAI clients.
Not yet published to npm. Vendor sdk/typescript into your project for now — copy the directory in, or reference it as a local/git dependency:
npm install <path-to-repo>/sdk/typescript
import { init } from "@ledger/sdk";
const ledger = init({
endpoint: process.env.LEDGER_ENDPOINT ?? "http://127.0.0.1:4010",
ingestKey: process.env.LEDGER_INGEST_KEY ?? "",
agentId: "urn:agent:research-assistant",
onError: (e) => console.error("[ledger]", e),
});
const t0 = new Date();
// ... do the work ...
const t1 = new Date();
ledger.record({
action_type: "llm_call",
provider: "anthropic",
model: "claude-fable-5",
started_at: t0,
ended_at: t1,
status: "success",
usage: { tokens_in: 420, tokens_out: 180 },
payloads: [
{ kind: "prompt", content: "Summarize the policy for the client memo." },
{ kind: "response", content: "The policy provides that…" },
],
trigger: { type: "human", subject: "person@example.com" },
});
await ledger.flush();
await ledger.shutdown();
shutdown() does a best-effort final flush with a hard deadline (default 2s) — call it before your process exits so buffered events aren't lost.
For Anthropic or OpenAI, skip manual record() calls entirely — wrap the client once and every call after that is captured automatically, including streaming:
import { init } from "@ledger/sdk";
import Anthropic from "@anthropic-ai/sdk";
const ledger = init({
endpoint: process.env.LEDGER_ENDPOINT ?? "http://127.0.0.1:4010",
ingestKey: process.env.LEDGER_INGEST_KEY ?? "",
agentId: "urn:agent:research-assistant",
});
ledger.setTrigger({ type: "human", subject: "person@example.com" });
const anthropic = ledger.instrumentAnthropic(new Anthropic());
// unmodified application code from here down — no ledger references needed
const res = await anthropic.messages.create({
model: "claude-fable-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Draft the client memo." }],
});
instrumentOpenAI(client) works the same way for OpenAI's client. Both are duck-typed wrappers — zero provider SDK dependencies inside @ledger/sdk itself.
const { spanId } = ledger.record({ action_type: "search", /* ... */ });
ledger.within(spanId, async () => {
// anything recorded in here defaults its parent_ref to spanId
const anthropic = ledger.instrumentAnthropic(client);
await anthropic.messages.create(/* ... */);
});
Pass parentRef explicitly on a record() call to override the ambient parent.
const { blob_id } = await ledger.uploadBlob(fileBuffer, "application/pdf");
ledger.record({
action_type: "data_read",
payloads: [{ kind: "artifact", blob_ref: blob_id }],
// ...
});
If you already run an OTel pipeline, plug the ledger in as an exporter or span processor instead of hand-instrumenting:
import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
provider.addSpanProcessor(ledger.otelSpanProcessor());
// or: new BatchSpanProcessor(ledger.otelExporter())
Every gen_ai.* span becomes a ledger event; other spans pass through untouched.