@relayburn/sdk 1.5.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to `@relayburn/sdk`.
+
+## [Unreleased]
+
+## [1.5.0] - 2026-05-01
+
+### Added
+
+- Initial release with embedded `Ledger.open()`, `ingest()`, `summary()`, and `hotspots()` helpers.

package/README.md

@@ -0,0 +1,12 @@
+# @relayburn/sdk
+
+Embeddable Relayburn SDK for in-process ingestion and analysis.
+
+```ts
+import { Ledger, ingest, summary, hotspots } from '@relayburn/sdk';
+
+await Ledger.open({ home: '/tmp/relayburn-home' });
+await ingest({ ledgerHome: '/tmp/relayburn-home' });
+const stats = await summary({ session: 'session-id', ledgerHome: '/tmp/relayburn-home' });
+const findings = await hotspots({ session: 'session-id', patterns: ['retry-loop'] });
+```

package/index.d.ts

@@ -0,0 +1,11 @@
+export interface LedgerOpenOptions { home?: string }
+export declare class Ledger { static open(opts?: LedgerOpenOptions): Promise<Ledger> }
+
+export interface IngestOptions { sessionId?: string; harness?: 'claude-code'|'codex'|'opencode'; ledgerHome?: string }
+export declare function ingest(opts?: IngestOptions): Promise<unknown>
+
+export interface SummaryOptions { session?: string; project?: string; since?: string; ledgerHome?: string }
+export declare function summary(opts?: SummaryOptions): Promise<{ totalTokens: number; totalCost: number; byTool: Array<{tool:string;tokens:number;cost:number;count:number}>; byModel: Array<{model:string;tokens:number;cost:number}> }>
+
+export interface HotspotsOptions { session?: string; patterns?: string[]; ledgerHome?: string }
+export declare function hotspots(opts?: HotspotsOptions): Promise<unknown>

package/index.js

@@ -0,0 +1,81 @@
+import { queryAll, queryUserTurns } from '@relayburn/ledger';
+import { loadPricing, costForTurn, attributeHotspots, detectPatterns, findingsFromPatterns } from '@relayburn/analyze';
+import { ingestAll } from '@relayburn/cli';
+
+function withHome(home, fn) {
+  const prev = process.env.RELAYBURN_HOME;
+  if (home) process.env.RELAYBURN_HOME = home;
+  return Promise.resolve(fn()).finally(() => {
+    if (home) {
+      if (prev === undefined) delete process.env.RELAYBURN_HOME;
+      else process.env.RELAYBURN_HOME = prev;
+    }
+  });
+}
+
+export class Ledger {
+  static async open(opts = {}) {
+    return new Ledger(opts.home);
+  }
+
+  constructor(home) {
+    this.home = home;
+  }
+}
+
+export async function ingest(opts = {}) {
+  return withHome(opts.ledgerHome, async () => ingestAll());
+}
+
+export async function summary(opts = {}) {
+  return withHome(opts.ledgerHome, async () => {
+    const q = { sessionId: opts.session, project: opts.project, since: opts.since };
+    const turns = await queryAll(q);
+    const pricing = await loadPricing();
+    const byTool = new Map();
+    const byModel = new Map();
+    let totalTokens = 0;
+    let totalCost = 0;
+
+    for (const t of turns) {
+      const c = costForTurn(t, pricing)?.total ?? 0;
+      const usage =
+        t.usage.input +
+        t.usage.output +
+        t.usage.reasoning +
+        t.usage.cacheRead +
+        t.usage.cacheCreate5m +
+        t.usage.cacheCreate1h;
+      totalTokens += usage;
+      totalCost += c;
+
+      const model = byModel.get(t.model) ?? { model: t.model, tokens: 0, cost: 0 };
+      model.tokens += usage;
+      model.cost += c;
+      byModel.set(t.model, model);
+
+      for (const call of t.toolCalls) {
+        const tool = byTool.get(call.name) ?? { tool: call.name, tokens: 0, cost: 0, count: 0 };
+        tool.tokens += usage;
+        tool.cost += c;
+        tool.count += 1;
+        byTool.set(call.name, tool);
+      }
+    }
+
+    return { totalTokens, totalCost, byTool: [...byTool.values()], byModel: [...byModel.values()] };
+  });
+}
+
+export async function hotspots(opts = {}) {
+  return withHome(opts.ledgerHome, async () => {
+    const turns = await queryAll({ sessionId: opts.session });
+    const userTurns = await queryUserTurns({ sessionId: opts.session });
+    const attribution = attributeHotspots({ turns, userTurns });
+
+    if (!opts.patterns || opts.patterns.length === 0) return attribution;
+
+    const detected = detectPatterns({ turns, userTurns, hotspots: attribution });
+    return findingsFromPatterns(detected).filter((f) => opts.patterns.includes(f.kind));
+  });
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@relayburn/sdk",
+  "version": "1.5.0",
+  "description": "Embeddable Relayburn SDK for in-process ingest, summary, and hotspots queries",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@relayburn/analyze": "1.5.0",
+    "@relayburn/ledger": "1.5.0",
+    "@relayburn/cli": "1.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AgentWorkforce/burn",
+    "directory": "packages/sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node -e \"process.exit(0)\""
+  }
+}