@agent-ledger/sdk-ts 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+export type EventType = "llm_call" | "tool_call" | "tool_result" | "session_start" | "session_end";
+export interface AgentLedgerClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+export type BudgetGuardrailDetails = {
+    agentName: string;
+    dailyLimitUsd: number;
+    spentTodayUsd: number;
+    attemptedCostUsd: number;
+    projectedCostUsd: number;
+    remainingBudgetUsd: number;
+};
+export declare class BudgetGuardrailError extends Error {
+    readonly details: BudgetGuardrailDetails;
+    constructor(message: string, details: BudgetGuardrailDetails);
+}
+export declare class AgentLedgerClient {
+    private apiKey;
+    private baseUrl;
+    constructor(opts: AgentLedgerClientOptions);
+    startSession(agentName: string): Promise<string>;
+    endSession(sessionId: string, status: "success" | "error", opts?: {
+        errorMessage?: string;
+    }): Promise<void>;
+    logEvents(sessionId: string, events: any[]): Promise<void>;
+    logLLMCall(sessionId: string, e: Omit<LlmCallEvent, "type">): Promise<void>;
+    logToolCall(sessionId: string, e: Omit<ToolCallEvent, "type">): Promise<void>;
+    logToolResult(sessionId: string, e: Omit<ToolResultEvent, "type">): Promise<void>;
+}
+export type LlmCallEvent = {
+    type: "llm_call";
+    stepIndex: number;
+    model: string;
+    provider: string;
+    prompt: string;
+    response: string;
+    tokensIn: number;
+    tokensOut: number;
+    latencyMs: number;
+};
+export type ToolCallEvent = {
+    type: "tool_call";
+    stepIndex: number;
+    toolName: string;
+    toolInput: any;
+};
+export type ToolResultEvent = {
+    type: "tool_result";
+    stepIndex: number;
+    toolName: string;
+    toolOutput: any;
+    latencyMs: number;
+};
+export type AnyEvent = LlmCallEvent | ToolCallEvent | ToolResultEvent;

package/dist/index.js

@@ -0,0 +1,100 @@
+const PROD_BASE_URL = "https://agent-ledger-api.azurewebsites.net";
+const DEV_BASE_URL = "http://localhost:3000";
+const nodeProcess = typeof globalThis !== "undefined" && globalThis.process ? globalThis.process : undefined;
+function resolveBaseUrl(explicit) {
+    if (explicit)
+        return explicit;
+    const envVars = nodeProcess?.env;
+    if (envVars) {
+        if (envVars.AGENT_LEDGER_BASE_URL) {
+            return envVars.AGENT_LEDGER_BASE_URL;
+        }
+        const env = envVars.NODE_ENV;
+        if (env && env !== "development") {
+            return PROD_BASE_URL;
+        }
+    }
+    return DEV_BASE_URL;
+}
+export class BudgetGuardrailError extends Error {
+    constructor(message, details) {
+        super(message);
+        this.name = "BudgetGuardrailError";
+        this.details = details;
+    }
+}
+export class AgentLedgerClient {
+    constructor(opts) {
+        this.apiKey = opts.apiKey;
+        const resolvedBaseUrl = resolveBaseUrl(opts.baseUrl).trim();
+        this.baseUrl = resolvedBaseUrl.replace(/\/$/, "");
+    }
+    async startSession(agentName) {
+        const res = await fetch(`${this.baseUrl}/v1/sessions`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-api-key": this.apiKey
+            },
+            body: JSON.stringify({ agentName })
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(text || `Failed to start session: ${res.statusText}`);
+        }
+        const data = await res.json();
+        return data.id;
+    }
+    async endSession(sessionId, status, opts) {
+        const res = await fetch(`${this.baseUrl}/v1/sessions/${sessionId}/end`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-api-key": this.apiKey
+            },
+            body: JSON.stringify({ status, errorMessage: opts?.errorMessage ?? null })
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(text || `Failed to end session: ${res.statusText}`);
+        }
+    }
+    async logEvents(sessionId, events) {
+        const res = await fetch(`${this.baseUrl}/v1/events`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-api-key": this.apiKey
+            },
+            body: JSON.stringify({ sessionId, events })
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            let payload = null;
+            try {
+                payload = text ? JSON.parse(text) : null;
+            }
+            catch {
+                payload = null;
+            }
+            if (res.status === 429 && payload?.details) {
+                throw new BudgetGuardrailError(payload?.error ?? "Budget limit exceeded", payload.details);
+            }
+            const message = payload?.error || text || "Failed to log events";
+            throw new Error(message);
+        }
+    }
+    async logLLMCall(sessionId, e) {
+        const event = { type: "llm_call", ...e };
+        return this.logEvents(sessionId, [event]);
+    }
+    async logToolCall(sessionId, e) {
+        const event = { type: "tool_call", ...e };
+        return this.logEvents(sessionId, [event]);
+    }
+    async logToolResult(sessionId, e) {
+        const event = { type: "tool_result", ...e };
+        return this.logEvents(sessionId, [event]);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@agent-ledger/sdk-ts",
+  "version": "0.0.1",
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -w -p tsconfig.build.json"
+  }
+}

package/src/index.ts

@@ -0,0 +1,181 @@
+export type EventType =
+  | "llm_call"
+  | "tool_call"
+  | "tool_result"
+  | "session_start"
+  | "session_end";
+
+export interface AgentLedgerClientOptions {
+  apiKey: string;
+  baseUrl?: string;
+}
+
+const PROD_BASE_URL = "https://agent-ledger-api.azurewebsites.net";
+const DEV_BASE_URL = "http://localhost:3000";
+const nodeProcess: { env?: Record<string, string | undefined>; } | undefined =
+  typeof globalThis !== "undefined" && (globalThis as any).process ? (globalThis as any).process : undefined;
+
+function resolveBaseUrl(explicit?: string) {
+  if (explicit) return explicit;
+  const envVars = nodeProcess?.env;
+  if (envVars) {
+    if (envVars.AGENT_LEDGER_BASE_URL) {
+      return envVars.AGENT_LEDGER_BASE_URL;
+    }
+    const env = envVars.NODE_ENV;
+    if (env && env !== "development") {
+      return PROD_BASE_URL;
+    }
+  }
+  return DEV_BASE_URL;
+}
+
+export type BudgetGuardrailDetails = {
+  agentName: string;
+  dailyLimitUsd: number;
+  spentTodayUsd: number;
+  attemptedCostUsd: number;
+  projectedCostUsd: number;
+  remainingBudgetUsd: number;
+};
+
+export class BudgetGuardrailError extends Error {
+  readonly details: BudgetGuardrailDetails;
+
+  constructor(message: string, details: BudgetGuardrailDetails) {
+    super(message);
+    this.name = "BudgetGuardrailError";
+    this.details = details;
+  }
+}
+
+export class AgentLedgerClient {
+  private apiKey: string;
+  private baseUrl: string;
+
+  constructor(opts: AgentLedgerClientOptions) {
+    this.apiKey = opts.apiKey;
+    const resolvedBaseUrl = resolveBaseUrl(opts.baseUrl).trim();
+    this.baseUrl = resolvedBaseUrl.replace(/\/$/, "");
+  }
+
+  async startSession(agentName: string): Promise<string> {
+    const res = await fetch(`${this.baseUrl}/v1/sessions`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": this.apiKey
+      },
+      body: JSON.stringify({ agentName })
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(text || `Failed to start session: ${res.statusText}`);
+    }
+
+    const data = await res.json();
+    return data.id as string;
+  }
+
+  async endSession(
+    sessionId: string,
+    status: "success" | "error",
+    opts?: { errorMessage?: string }
+  ) {
+    const res = await fetch(`${this.baseUrl}/v1/sessions/${sessionId}/end`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": this.apiKey
+      },
+      body: JSON.stringify({ status, errorMessage: opts?.errorMessage ?? null })
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(text || `Failed to end session: ${res.statusText}`);
+    }
+  }
+
+  async logEvents(sessionId: string, events: any[]) {
+    const res = await fetch(`${this.baseUrl}/v1/events`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": this.apiKey
+      },
+      body: JSON.stringify({ sessionId, events })
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      let payload: any = null;
+      try {
+        payload = text ? JSON.parse(text) : null;
+      } catch {
+        payload = null;
+      }
+
+      if (res.status === 429 && payload?.details) {
+        throw new BudgetGuardrailError(payload?.error ?? "Budget limit exceeded", payload.details);
+      }
+
+      const message = payload?.error || text || "Failed to log events";
+      throw new Error(message);
+    }
+  }
+
+  async logLLMCall(
+    sessionId: string,
+    e: Omit<LlmCallEvent, "type">
+  ) {
+    const event: LlmCallEvent = { type: "llm_call", ...e };
+    return this.logEvents(sessionId, [event]);
+  }
+
+  async logToolCall(
+    sessionId: string,
+    e: Omit<ToolCallEvent, "type">
+  ) {
+    const event: ToolCallEvent = { type: "tool_call", ...e };
+    return this.logEvents(sessionId, [event]);
+  }
+
+  async logToolResult(
+    sessionId: string,
+    e: Omit<ToolResultEvent, "type">
+  ) {
+    const event: ToolResultEvent = { type: "tool_result", ...e };
+    return this.logEvents(sessionId, [event]);
+  }
+}
+
+export type LlmCallEvent = {
+  type: "llm_call";
+  stepIndex: number;
+  model: string;
+  provider: string;
+  prompt: string;
+  response: string;
+  tokensIn: number;
+  tokensOut: number;
+  latencyMs: number;
+};
+
+export type ToolCallEvent = {
+  type: "tool_call";
+  stepIndex: number;
+  toolName: string;
+  toolInput: any;
+};
+
+export type ToolResultEvent = {
+  type: "tool_result";
+  stepIndex: number;
+  toolName: string;
+  toolOutput: any;
+  latencyMs: number;
+};
+
+export type AnyEvent = LlmCallEvent | ToolCallEvent | ToolResultEvent;

package/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true
+  },
+  "include": ["src"]
+}