@relayburn/sdk 1.9.0 → 2.0.0

package/src/index.d.ts

@@ -0,0 +1,422 @@
+// Type surface for `@relayburn/sdk@2.x`.
+//
+// Mirrors `packages/sdk/index.d.ts` (the TS 1.x SDK) byte-for-byte modulo:
+//   - `bigint` is allowed alongside `number` for u64-typed token counts (the
+//     napi-rs binding emits `BigInt` for `u64`; the TS shape is widened so
+//     existing callers that pass through `number` keep type-checking once
+//     bound to the Rust impl).
+//   - Async fns return `Promise<T>` — the napi-rs binding uses `async fn`
+//     where the Rust SDK does, which is everywhere except the `Ledger.open`
+//     constructor.
+//
+// Source-of-truth comment: track `packages/sdk/index.d.ts`. Whenever a verb
+// shape changes in TS, mirror it here AND in the Rust napi-rs binding (#247-a).
+
+export interface LedgerOpenOptions { home?: string; contentHome?: string }
+/**
+ * Stateful ledger handle. The 1.x TS class only exposes the static
+ * `open()` constructor; instances are placeholders today, with `home`
+ * exposed for callers that want to confirm which ledger they attached
+ * to. Verb methods are a future PR.
+ */
+export declare class Ledger {
+  readonly home: string;
+  static open(opts?: LedgerOpenOptions): Promise<Ledger>;
+}
+
+export interface IngestOptions { sessionId?: string; harness?: 'claude-code'|'codex'|'opencode'; ledgerHome?: string }
+export interface IngestReport {
+  scannedSessions: number | bigint;
+  ingestedSessions: number | bigint;
+  appendedTurns: number | bigint;
+}
+export declare function ingest(opts?: IngestOptions): Promise<IngestReport>
+
+export interface SummaryOptions {
+  session?: string;
+  project?: string;
+  /** ISO timestamp (e.g. `2026-04-01T00:00:00Z`) or relative range (`24h`, `7d`, `4w`, `2m`). */
+  since?: string;
+  ledgerHome?: string;
+  /** Optional logger invoked when the SQLite archive read fails and the SDK falls back to a full ledger walk. */
+  onLog?: (msg: string) => void;
+}
+export declare function summary(opts?: SummaryOptions): Promise<{
+  totalTokens: number | bigint;
+  totalCost: number;
+  turnCount: number;
+  byTool: Array<{ tool: string; tokens: number | bigint; cost: number; count: number }>;
+  byModel: Array<{ model: string; tokens: number | bigint; cost: number }>;
+}>
+
+export interface SessionCostOptions {
+  /** Session id to total. Omit for `{ note: 'no session id provided' }`. */
+  session?: string;
+  ledgerHome?: string;
+  onLog?: (msg: string) => void;
+}
+export interface SessionCostResult {
+  sessionId: string | null;
+  totalUSD: number;
+  totalTokens: number | bigint;
+  turnCount: number;
+  models: string[];
+  note?: string;
+}
+/** Compact session-scoped cost shape; powers the MCP `burn__sessionCost` tool. */
+export declare function sessionCost(opts?: SessionCostOptions): Promise<SessionCostResult>
+
+export type OverheadFileKind = 'claude-md' | 'agents-md';
+export type OverheadHarness = 'claude-code' | 'codex' | 'opencode';
+
+export interface OverheadOptions {
+  project?: string;
+  since?: string;
+  kind?: OverheadFileKind;
+  ledgerHome?: string;
+  onLog?: (msg: string) => void;
+}
+
+export interface OverheadSection {
+  heading: string;
+  startLine: number;
+  endLine: number;
+  tokens: number | bigint;
+}
+
+export interface OverheadSectionCost {
+  filePath: string;
+  section: OverheadSection;
+  tokenShare: number;
+  costPerSession: number;
+  totalCost: number;
+}
+
+export interface OverheadAttributionDetail {
+  sessionCount: number;
+  perSessionAvg: number;
+  perSessionP95: number;
+  totalCost: number;
+  sectionCosts: OverheadSectionCost[];
+}
+
+export interface OverheadFileSummary {
+  kind: OverheadFileKind;
+  path: string;
+  appliesTo: OverheadHarness[];
+  totalLines: number;
+  bytes: number | bigint;
+  tokens: number | bigint;
+  sections: OverheadSection[];
+  groupingLevel: number;
+}
+
+export interface OverheadPerFileEntry {
+  path: string;
+  kind: OverheadFileKind;
+  appliesTo: OverheadHarness[];
+  attribution: OverheadAttributionDetail;
+}
+
+export interface OverheadResult {
+  project: string;
+  files: OverheadFileSummary[];
+  perFile: OverheadPerFileEntry[];
+  grandTotal: number;
+}
+
+/** Per-file + per-section overhead cost attribution. Powers `burn overhead`. */
+export declare function overhead(opts?: OverheadOptions): Promise<OverheadResult>
+
+export interface OverheadTrimOptions extends OverheadOptions {
+  top?: number;
+  includeDiff?: boolean;
+}
+
+export interface OverheadTrimRecommendation {
+  file: string;
+  kind: OverheadFileKind;
+  appliesTo: OverheadHarness[];
+  section: { heading: string; startLine: number; endLine: number; tokens: number | bigint };
+  projectedSavings: {
+    perSessionUsd: number;
+    acrossWindowUsd: number;
+    tokens: number | bigint;
+    tokenShare: number;
+  };
+  diff?: string;
+}
+
+export interface OverheadTrimResult {
+  project: string;
+  since: string;
+  recommendations: OverheadTrimRecommendation[];
+  summary: {
+    filesAnalyzed: number;
+    filesWithRecommendations: number;
+    totalRecommendations: number;
+    totalProjectedSavingsPerSession: number;
+    totalProjectedSavingsAcrossWindow: number;
+  };
+}
+
+/** Trim recommendations for high-cost overhead-file sections. Powers `burn overhead trim`. */
+export declare function overheadTrim(opts?: OverheadTrimOptions): Promise<OverheadTrimResult>
+
+export type HotspotsGroupBy = 'attribution' | 'bash' | 'bash-verb' | 'file' | 'subagent';
+
+export interface HotspotsOptions {
+  session?: string;
+  project?: string;
+  since?: string;
+  groupBy?: HotspotsGroupBy;
+  patterns?: string[];
+  ledgerHome?: string;
+  onLog?: (msg: string) => void;
+}
+
+export interface HotspotsFileRow {
+  path: string;
+  firstEmitTurnIndex: number;
+  initialTokens: number | bigint;
+  persistenceTokens: number | bigint;
+  ridingTurns: number;
+  totalCost: number;
+}
+
+export interface HotspotsBashRow {
+  command: string | undefined;
+  argsHash: string;
+  callCount: number;
+  initialTokens: number | bigint;
+  persistenceTokens: number | bigint;
+  totalCost: number;
+}
+
+export interface HotspotsBashVerbRow {
+  verb: string;
+  callCount: number;
+  distinctCommands: number;
+  initialTokens: number | bigint;
+  persistenceTokens: number | bigint;
+  avgPersistenceTurns: number;
+  totalCost: number;
+  topExamples: string[];
+}
+
+export interface HotspotsSubagentRow {
+  subagentType: string;
+  callCount: number;
+  initialTokens: number | bigint;
+  persistenceTokens: number | bigint;
+  totalCost: number;
+}
+
+export interface HotspotsSessionTotal {
+  sessionId: string;
+  grandCost: number;
+  attributedCost: number;
+  unattributedCost: number;
+  attributionMethod: 'sized' | 'even-split';
+}
+
+export interface HotspotsFidelityBlock {
+  analyzed: number;
+  excluded: number;
+  summary: unknown;
+  refused: boolean;
+}
+
+export interface HotspotsAttributionResult {
+  kind: 'attribution';
+  turnsAnalyzed: number;
+  grandTotal: number;
+  attributedTotal: number;
+  unattributedTotal: number;
+  attributionDegraded: boolean;
+  sessions: HotspotsSessionTotal[];
+  files: HotspotsFileRow[];
+  bashVerbs: HotspotsBashVerbRow[];
+  bash: HotspotsBashRow[];
+  subagents: HotspotsSubagentRow[];
+  fidelity: HotspotsFidelityBlock;
+  refused?: boolean;
+  refusalReason?: string;
+}
+
+export interface HotspotsBashResult { kind: 'bash'; rows: HotspotsBashRow[]; refused?: boolean; refusalReason?: string }
+export interface HotspotsBashVerbResult { kind: 'bash-verb'; rows: HotspotsBashVerbRow[]; refused?: boolean; refusalReason?: string }
+export interface HotspotsFileResult { kind: 'file'; rows: HotspotsFileRow[]; refused?: boolean; refusalReason?: string }
+export interface HotspotsSubagentResult { kind: 'subagent'; rows: HotspotsSubagentRow[]; refused?: boolean; refusalReason?: string }
+
+export interface HotspotsFinding {
+  kind: string;
+  severity: string;
+  sessionId: string;
+  title: string;
+  estimatedSavings: { usdPerSession?: number; [k: string]: unknown };
+  [k: string]: unknown;
+}
+
+export interface HotspotsFindingsResult {
+  kind: 'findings';
+  findings: HotspotsFinding[];
+  summary: unknown;
+}
+
+export type HotspotsResult =
+  | HotspotsAttributionResult
+  | HotspotsBashResult
+  | HotspotsBashVerbResult
+  | HotspotsFileResult
+  | HotspotsSubagentResult
+  | HotspotsFindingsResult;
+
+/**
+ * Per-axis hotspot attribution + pattern-finding queries. Returns a
+ * discriminated union — see `HotspotsResult`.
+ */
+export declare function hotspots(opts?: HotspotsOptions): Promise<HotspotsResult>
+
+export type FidelityClass = 'full' | 'usage-only' | 'aggregate-only' | 'cost-only' | 'partial';
+
+export interface FidelitySummaryShape {
+  total: number;
+  byClass: Record<FidelityClass, number>;
+  unknown: number;
+  missingCoverage: Record<string, number>;
+}
+
+export interface CompareExcludedBreakdown {
+  total: number;
+  aggregateOnly: number;
+  costOnly: number;
+  partial: number;
+  usageOnly: number;
+}
+
+export interface CompareCellResult {
+  model: string;
+  category: string;
+  turns: number;
+  editTurns: number;
+  oneShotTurns: number;
+  pricedTurns: number;
+  totalCost: number;
+  costPerTurn: number | null;
+  oneShotRate: number | null;
+  cacheHitRate: number | null;
+  medianRetries: number | null;
+  noData: boolean;
+  insufficientSample: boolean;
+}
+
+export interface CompareOptions {
+  models: string[];
+  session?: string;
+  project?: string;
+  since?: string;
+  workflow?: string;
+  agent?: string;
+  provider?: string[];
+  minSample?: number;
+  minFidelity?: FidelityClass;
+  ledgerHome?: string;
+  onLog?: (msg: string) => void;
+}
+
+export interface CompareResult {
+  analyzedTurns: number;
+  minSample: number;
+  models: string[];
+  categories: string[];
+  totals: Record<string, { turns: number; totalCost: number }>;
+  cells: CompareCellResult[];
+  fidelity: {
+    minimum: FidelityClass;
+    excluded: CompareExcludedBreakdown;
+    summary: FidelitySummaryShape;
+  };
+}
+
+/** Per-(model, activity) comparison shape. Powers `burn compare`. */
+export declare function compare(opts: CompareOptions): Promise<CompareResult>
+
+// ---------------------------------------------------------------------------
+// 2.x extensions — surfaces present in `relayburn-sdk` (the Rust crate)
+// but not in the TS 1.x `packages/sdk/index.d.ts`. Pre-1.0 widening per
+// the SDK shape rule; embedders that pinned to 1.x won't see these names
+// (the missing `onLog` etc. plus the absence of these is the only TS-vs-
+// napi gap the conformance gate measures).
+// ---------------------------------------------------------------------------
+
+export interface SearchQueryOptions {
+  /** FTS5 query string. Phrase, boolean, and prefix syntax supported. */
+  query: string;
+  /** Hit cap. Defaults to 25 when omitted. */
+  limit?: number | bigint;
+  /** Restrict to a single session_id. Omit to search all sessions. */
+  sessionId?: string;
+  ledgerHome?: string;
+}
+
+export interface SearchHit {
+  sessionId: string;
+  messageId: string;
+  source: string;
+  /** FTS5 BM25 rank (lower = better match). */
+  rank: number;
+  /** `<b>…</b>`-highlighted snippet around the matching tokens. */
+  snippet: string;
+}
+
+export interface SearchResult {
+  query: string;
+  hits: SearchHit[];
+}
+
+/** FTS5-backed message-content search. 2.x extension over the TS surface. */
+export declare function search(opts: SearchQueryOptions): Promise<SearchResult>
+
+export interface ExportLedgerOptions { ledgerHome?: string }
+export interface ExportStampsOptions { ledgerHome?: string }
+
+/**
+ * Stream every event row as a JSONL-shaped JSON object. Each value has
+ * the form `{ v: 1, kind: '<kind>', record: <json> }`. 2.x extension.
+ */
+export declare function exportLedger(opts?: ExportLedgerOptions): Promise<unknown[]>
+
+/** Stream every stamp row as a JSONL-shaped JSON object. 2.x extension. */
+export declare function exportStamps(opts?: ExportStampsOptions): Promise<unknown[]>
+
+/**
+ * Tagged error code surfaced on the thrown JS `Error.code` property.
+ * Sync verbs reject with one of these; the async `ingest` verb's
+ * rejection currently sets `code: 'GenericFailure'` — see the binding
+ * crate's `ingest` doc comment for the napi-rs-2.x rationale.
+ *
+ * The values are the literal strings written to `e.code`, matching the
+ * Rust constants `SDK_ERROR_CODE` / `IO_ERROR_CODE` / `INVALID_ARGUMENT_ERROR_CODE`.
+ */
+export declare const BurnErrorCode: {
+  readonly Sdk: 'BURN_SDK';
+  readonly Io: 'BURN_IO';
+  readonly InvalidArgument: 'BURN_INVALID_ARGUMENT';
+};
+export type BurnErrorCodeValue = (typeof BurnErrorCode)[keyof typeof BurnErrorCode];
+
+/** Wire-value enum for `OverheadOptions.kind` and `OverheadTrimOptions.kind`. */
+export declare const OverheadFileKind: {
+  readonly ClaudeMd: 'claude-md';
+  readonly AgentsMd: 'agents-md';
+};
+
+/** Wire-value enum for `HotspotsOptions.groupBy`. */
+export declare const HotspotsGroupBy: {
+  readonly Attribution: 'attribution';
+  readonly Bash: 'bash';
+  readonly BashVerb: 'bash-verb';
+  readonly File: 'file';
+  readonly Subagent: 'subagent';
+};

package/src/index.js

@@ -0,0 +1,144 @@
+// Thin ESM facade over the napi-rs binding. The verbs here re-export the
+// matching `#[napi]` exports from the platform package resolved by
+// `./binding.cjs`, with two adjustments to match the TS 1.x contract at
+// `packages/sdk/index.d.ts`:
+//
+//   1. The sync `#[napi]` verbs (`summary`, `sessionCost`, `overhead`,
+//      `overheadTrim`, `hotspots`, `compare`) are re-exported as `async`
+//      functions so callers receive `Promise<T>` (matching the 1.x
+//      `Promise<...>` return shape). Awaiting an `async` wrapper around a
+//      sync return is free and preserves the typed `e.code` thrown by the
+//      binding (`BurnErrorCode.Sdk` / `Io` / `InvalidArgument`).
+//   2. `Ledger.open()` is a JS-side wrapper around the binding's
+//      `ledgerOpen()` smoke verb. The 1.x `Ledger` class only exposes a
+//      static `open(opts)` that returns a placeholder instance, so we
+//      keep the same shape here without adding a stateful `#[napi]` class
+//      (which would force `Mutex<LedgerHandle>` plumbing for no benefit).
+//
+// All query / compute logic lives in the Rust SDK (`crates/relayburn-sdk`);
+// the binding crate (`crates/relayburn-sdk-node`) wraps it for napi-rs.
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const binding = require('./binding.cjs');
+
+// napi-rs serializes Rust `u64` / `i64` as JS `BigInt`, but the TS 1.x
+// `@relayburn/sdk` shape (mirrored in `src/index.d.ts`) emits plain
+// `Number` for the same fields. To keep the conformance gate's
+// `deepStrictEqual` checks honest — and to match the runtime shape that
+// 1.x callers expect (e.g. `result.turnCount === 0`, not `=== 0n`) — we
+// downcast every `BigInt` in a verb's return value to `Number` when it
+// fits in `[Number.MIN_SAFE_INTEGER, Number.MAX_SAFE_INTEGER]`. Values
+// outside that range are left as `BigInt`: realistic burn ledgers won't
+// hit 2^53 tokens, but if one ever does, leaking a `BigInt` that crashes
+// a `===` check is strictly safer than silently rounding to the nearest
+// 1024. The TS shape declares `number | bigint` everywhere this matters
+// so the type stays sound either way.
+const MIN_SAFE = BigInt(Number.MIN_SAFE_INTEGER);
+const MAX_SAFE = BigInt(Number.MAX_SAFE_INTEGER);
+
+function coerceBigInts(value) {
+  if (typeof value === 'bigint') {
+    return value >= MIN_SAFE && value <= MAX_SAFE ? Number(value) : value;
+  }
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      value[i] = coerceBigInts(value[i]);
+    }
+    return value;
+  }
+  if (value !== null && typeof value === 'object') {
+    // Skip class instances we don't own (Date, Map, Set, Buffer, …) —
+    // walking their guts would be both wasteful and risky. Plain objects
+    // produced by napi-rs serde have a null or Object prototype.
+    const proto = Object.getPrototypeOf(value);
+    if (proto === null || proto === Object.prototype) {
+      for (const key of Object.keys(value)) {
+        value[key] = coerceBigInts(value[key]);
+      }
+    }
+    return value;
+  }
+  return value;
+}
+
+/**
+ * Stateful ledger handle. Mirrors the TS 1.x `Ledger` class shape from
+ * `packages/sdk/index.d.ts`. The 1.x version only exposes the static
+ * `open(opts)` constructor — instance methods are reserved for a future
+ * PR — so we replicate that surface and stash the resolved home for
+ * introspection.
+ */
+export class Ledger {
+  constructor(home) {
+    /** @type {string} */
+    this.home = home;
+  }
+  /**
+   * Open and validate a ledger at `opts.home` (or `RELAYBURN_HOME`).
+   * Returns a `Promise<Ledger>` to mirror the 1.x async signature even
+   * though the underlying `ledgerOpen` binding is synchronous.
+   *
+   * @param {{ home?: string, contentHome?: string }} [opts]
+   * @returns {Promise<Ledger>}
+   */
+  static async open(opts) {
+    const home = binding.ledgerOpen(opts);
+    return new Ledger(home);
+  }
+}
+
+export async function ingest(opts) {
+  return coerceBigInts(await binding.ingest(opts));
+}
+
+export async function summary(opts) {
+  return coerceBigInts(await binding.summary(opts));
+}
+
+export async function sessionCost(opts) {
+  return coerceBigInts(await binding.sessionCost(opts));
+}
+
+export async function overhead(opts) {
+  return coerceBigInts(await binding.overhead(opts));
+}
+
+export async function overheadTrim(opts) {
+  return coerceBigInts(await binding.overheadTrim(opts));
+}
+
+export async function hotspots(opts) {
+  return coerceBigInts(await binding.hotspots(opts));
+}
+
+export async function compare(opts) {
+  return coerceBigInts(await binding.compare(opts));
+}
+
+// 2.x extensions — exposed by the Rust SDK but not declared in
+// `packages/sdk/index.d.ts` (the 1.x TS surface). Per the SDK shape rule,
+// pre-1.0 widening is allowed; these are surfaced here so embedders can
+// reach the FTS5 search index and the JSONL export iterators without
+// dropping into the binding directly.
+export async function search(opts) {
+  return coerceBigInts(await binding.search(opts));
+}
+
+export async function exportLedger(opts) {
+  return coerceBigInts(await binding.exportLedger(opts));
+}
+
+export async function exportStamps(opts) {
+  return coerceBigInts(await binding.exportStamps(opts));
+}
+
+// Re-exported enums from the Rust binding. These come across as plain
+// string-valued objects (`{ Sdk: 'BURN_SDK', ... }`) and let JS callers
+// branch on `e.code === BurnErrorCode.Sdk` without stringly-typed
+// literals. `OverheadFileKind` and `HotspotsGroupBy` are likewise the
+// canonical wire values for the matching option-struct fields.
+export const BurnErrorCode = binding.BurnErrorCode;
+export const OverheadFileKind = binding.OverheadFileKind;
+export const HotspotsGroupBy = binding.HotspotsGroupBy;