@aispendguard/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AISpendGuard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,288 @@
+# AISpendGuard SDK
+
+Tags-only SDK for sending AI usage events to AISpendGuard.
+
+## What it enforces
+- No prompt/output/content fields
+- Strict event validation
+- Required tags: `task_type`, `feature`, `route`
+- Custom tags allowed (lowercase snake_case keys), for example: `team`, `project_code`, `region`
+- Custom tag values can be either string values or array values (`string[]`)
+- API key auth via `x-api-key`
+
+## Install
+```bash
+npm install @aispendguard/sdk
+```
+
+## Quick start
+```ts
+import { init, trackUsage } from "@aispendguard/sdk";
+
+init({
+  apiKey: process.env.AISPENDGUARD_API_KEY!,
+  endpoint: "https://www.aispendguard.com/api/ingest",
+});
+
+await trackUsage({
+  provider: "openai",
+  model: "gpt-4o-mini",
+  inputTokens: 120,
+  outputTokens: 12,
+  latencyMs: 840,
+  costUsd: 0.0021,
+  timestamp: new Date(),
+  tags: {
+    task_type: "classify",
+    feature: "lead_classifier",
+    route: "POST /api/ai/classify",
+    environment: "prod",
+    customer_plan: "free"
+  }
+});
+```
+
+## OpenAI helper
+```ts
+import { init, trackUsage, createOpenAIUsageEvent } from "@aispendguard/sdk";
+
+init({
+  apiKey: process.env.AISPENDGUARD_API_KEY!,
+  endpoint: "https://www.aispendguard.com/api/ingest",
+});
+
+const startedAt = Date.now();
+const response = await openai.responses.create({
+  model: "gpt-4o-mini",
+  input: "Classify this lead"
+});
+
+const event = createOpenAIUsageEvent({
+  model: "gpt-4o-mini",
+  resolvedModel: response.model,       // "gpt-4o-mini-2024-07-18" — pinned version
+  usage: response.usage,               // auto-extracts tokens, cache hits, reasoning tokens
+  latencyMs: Date.now() - startedAt,
+  tags: {
+    task_type: "classify",
+    feature: "lead_classifier",
+    route: "POST /api/ai/classify"
+  }
+});
+
+await trackUsage(event);
+```
+
+## Anthropic helper
+```ts
+import { init, trackUsage, createAnthropicUsageEvent } from "@aispendguard/sdk";
+
+init({
+  apiKey: process.env.AISPENDGUARD_API_KEY!,
+  endpoint: "https://www.aispendguard.com/api/ingest"
+});
+
+const startedAt = Date.now();
+const message = await anthropic.messages.create({
+  model: "claude-3-5-sonnet-latest",
+  max_tokens: 200,
+  messages: [{ role: "user", content: "Summarize this thread." }]
+});
+
+const event = createAnthropicUsageEvent({
+  model: "claude-3-5-sonnet-latest",
+  resolvedModel: message.model,        // "claude-3-5-sonnet-20241022" — pinned version
+  usage: message.usage,                // auto-extracts tokens, cache_read, cache_creation
+  latencyMs: Date.now() - startedAt,
+  tags: {
+    task_type: "summarize",
+    feature: "support_summary",
+    route: "POST /api/support/summary"
+  }
+});
+
+await trackUsage(event);
+```
+
+## Gemini helper
+```ts
+import { init, trackUsage, createGeminiUsageEvent } from "@aispendguard/sdk";
+
+init({
+  apiKey: process.env.AISPENDGUARD_API_KEY!,
+  endpoint: "https://www.aispendguard.com/api/ingest"
+});
+
+const startedAt = Date.now();
+const response = await gemini.models.generateContent({
+  model: "gemini-2.0-flash",
+  contents: [{ role: "user", parts: [{ text: "Translate this to French." }] }]
+});
+
+const event = createGeminiUsageEvent({
+  model: "gemini-2.0-flash",
+  resolvedModel: response.modelVersion, // "gemini-2.0-flash-001" — pinned version
+  usage: response.usageMetadata,        // auto-extracts tokens, cachedContent, thoughts
+  latencyMs: Date.now() - startedAt,
+  tags: {
+    task_type: "translate",
+    feature: "ui_i18n",
+    route: "POST /api/translate"
+  }
+});
+
+await trackUsage(event);
+```
+
+## API
+- `init(config)`
+- `trackUsage(event | event[])`
+- `createOpenAIUsageEvent(params)` — OpenAI Chat Completions + Responses API
+- `createAnthropicUsageEvent(params)` — Anthropic Messages API
+- `createGeminiUsageEvent(params)` — Google Gemini generateContent API
+- `new AISpendGuardClient(config).trackUsage(...)` — direct client usage (used by OpenClaw plugin)
+
+## Config
+- `apiKey` (required)
+- `endpoint` (default: `https://www.aispendguard.com/api/ingest`)
+- `timeoutMs` (default: `5000`)
+- `maxRetries` (default: `2`)
+- `strict` (default: `false`, if `true` throws on errors)
+
+## Notes
+- Non-strict mode logs and returns `{ ok: false, error }`.
+- Strict mode throws on validation/network/ingest errors.
+
+## Validation Limits
+- Required tags: `task_type`, `feature`, `route` (must be non-empty strings)
+- Known optional tags: `customer_plan`, `customer_id`, `provider`, `model`, `environment`, `agent_name`
+- Custom tag keys: lowercase snake_case only, regex `^[a-z][a-z0-9_]{1,63}$`
+- Custom tag values: `string` or `string[]`
+- Max tags per event: `24`
+- Max values in a single array tag: `16`
+- Max length per string value: `120`
+- Forbidden keys (blocked): prompt/content/output/message/attachment-like fields
+
+## Extended token fields (optional)
+
+These optional fields give AISpendGuard the data it needs for accurate cost calculation and cost-spike detection. The provider helpers extract them automatically from `response.usage`.
+
+| Field | Type | What it is | Provider |
+|-------|------|-----------|----------|
+| `resolvedModel` | `string` | Pinned model version from response (e.g. `gpt-4o-mini-2024-07-18`) | All |
+| `inputTokensCached` | `number` | Cache read tokens — already in `inputTokens`, billed cheaper | OpenAI (0.5×) · Anthropic (0.1×) · Gemini |
+| `inputTokensCacheWrite` | `number` | Cache write tokens — already in `inputTokens`, billed at premium | Anthropic only (1.25×) |
+| `thinkingTokens` | `number` | Reasoning/thinking tokens — already in `outputTokens`, billed at full output rate | OpenAI o1/o3 · Gemini 2.5 |
+
+> **Anthropic note:** Extended thinking tokens (`claude-3-7-sonnet` with `thinking: enabled`) are
+> included in `output_tokens` but NOT separately reported in the `usage` object. You can count
+> `content` blocks of type `"thinking"` manually if you need the split.
+
+### Why these matter
+
+Without them, cost calculations are inaccurate:
+- **Cache read tokens** cost 10–50% of normal — without tracking, you overstate spend on cached calls.
+- **Cache write tokens** (Anthropic) cost 25% more — without tracking, you understate spend when building cache.
+- **Thinking tokens** for o1/o3 can be 3–10× the visible output — without tracking, cost spikes are invisible.
+- **Resolved model** lets AISpendGuard detect silent provider upgrades between versions.
+
+### Manual override (no helper)
+
+If you aren't using a helper, pass them directly in `trackUsage`:
+```ts
+await trackUsage({
+  provider: "openai",
+  model: "gpt-4o-mini",
+  resolvedModel: response.model,
+  inputTokens: 1000,
+  outputTokens: 50,
+  inputTokensCached: 800,      // 800 of the 1000 input tokens were cache hits
+  thinkingTokens: 0,
+  latencyMs: 320,
+  timestamp: new Date(),
+  tags: { task_type: "classify", feature: "router", route: "POST /api/route" }
+});
+```
+
+## task_type values
+
+Pick the value that describes what the model is being asked to **produce**.
+The right `task_type` is what enables AISpendGuard's waste detection rules.
+
+| Value | What it does | Output size | Best model tier |
+|-------|-------------|-------------|-----------------|
+| `answer` | Q&A, RAG responses, knowledge retrieval | 100–800 tok | standard |
+| `classify` | Label, categorize, detect intent | **1–10 tok** | **micro** |
+| `extract` | Pull structured fields from text | 50–300 tok | micro |
+| `summarize` | Condense long content, TLDR | 100–500 tok | standard |
+| `generate` | Write/draft new content | 300–2000 tok | standard |
+| `rewrite` | Paraphrase, tone-adjust, edit | ≈ input | standard |
+| `translate` | Language translation | ≈ input | micro |
+| `code` | Generate, review, explain code | 200–1500 tok | premium |
+| `eval` | LLM-as-judge, quality score | **10–50 tok** | **micro** |
+| `embed` | Text embedding / vector | fixed vector | embedding models |
+| `route` | Decide which tool/path/agent | **1–20 tok** | **micro** |
+| `plan` | Decompose tasks, strategy | 100–500 tok | premium |
+| `agent_step` | Single step in agent loop | 50–800 tok | varies |
+| `vision` | Image/PDF/screenshot understanding | 100–600 tok | standard |
+| `chat` | Multi-turn stateful conversation | 100–500 tok | standard |
+| `other` | None of the above (avoid — disables waste detection) | — | — |
+
+**Model tiers:**
+- `micro` — haiku / gpt-4o-mini / flash-lite (80–95% cheaper than premium for short-output tasks)
+- `standard` — sonnet / gpt-4o / flash (best quality/cost balance for most workloads)
+- `premium` — opus / o1 / o3 / gpt-4-turbo (complex reasoning, nuanced code, planning)
+- `embedding` — text-embedding-3-small / embed-english-v3 (never use chat models for embeddings)
+
+**Waste rule:** if `classify`, `route`, or `eval` uses a `premium` model with avg output < 100 tokens,
+AISpendGuard will flag this and calculate the exact monthly saving from switching to `micro` tier.
+
+## OpenClaw plugin
+
+Track every LLM call made by an [OpenClaw](https://openclaw.ai/) AI agent automatically — no code changes in the agent itself.
+
+The `@aispendguard/openclaw-plugin` hooks into OpenClaw's `llm_output` lifecycle event and forwards token-usage data to AISpendGuard.
+
+### What gets tracked per LLM call
+
+| Field | Source |
+|---|---|
+| `provider` | hook — openai, anthropic, google, deepseek |
+| `model` | hook — e.g. claude-sonnet-4-20250514, gpt-4o |
+| `input_tokens` | `usage.input` |
+| `output_tokens` | `usage.output` |
+| `input_tokens_cached` | `usage.cacheRead` (when cache is used) |
+| `input_tokens_cache_write` | `usage.cacheWrite` (when cache is written) |
+| `cache_ttl` | plugin config — `"5m"` (1.25×) or `"1h"` (2.0×) |
+| `agent_name` | `ctx.agentId` |
+| `session_id` | `ctx.sessionId` |
+
+### Setup
+
+```bash
+# Set env vars for the OpenClaw plugin
+AISG_ENDPOINT=https://www.aispendguard.com/api/ingest
+AISG_API_KEY=ask_xxxxxxxxxxxxxxxx
+AISG_CACHE_TTL=5m  # "5m" (default) or "1h" for extended Anthropic caching
+```
+
+Install the plugin into OpenClaw:
+```bash
+cp -r openclaw-aispendguard-plugin ~/.openclaw/plugins/aispendguard
+cd ~/.openclaw/plugins/aispendguard
+npm install && npm run build
+```
+
+See `openclaw-aispendguard-plugin/README.md` for full docs.
+
+## Tests
+Run unit-style tests:
+```bash
+npm test
+```
+
+Run live ingest integration test (requires local app running and valid key/workspace):
+```bash
+AISPENDGUARD_API_KEY=asg_xxx \
+AISPENDGUARD_ENDPOINT=https://www.aispendguard.com/api/ingest \
+npm test
+```

package/dist/anthropic.d.ts

@@ -0,0 +1,49 @@
+import type { UsageEventInput, UsageTags } from "./types";
+/**
+ * Anthropic Messages API response.usage shape.
+ *
+ * Cache tokens (prompt caching feature):
+ *   - cache_read_input_tokens    → cache read hits  — billed at 0.1× base input price (very cheap)
+ *   - cache_creation_input_tokens → cache writes    — billed at 1.25× base input price (slightly expensive)
+ *   Both are already counted in input_tokens; store separately for accurate cost calculation.
+ *
+ * Extended thinking (claude-3-7-sonnet with thinking: { type: "enabled", budget_tokens: N }):
+ *   - Thinking tokens are NOT reported separately in the usage object.
+ *   - They are included in output_tokens along with visible text tokens.
+ *   - If you need them separately, count content blocks of type "thinking" manually.
+ */
+type AnthropicUsageLike = {
+    input_tokens?: number;
+    output_tokens?: number;
+    /** Cache read tokens — billed at 0.1× base input price. Included in input_tokens. */
+    cache_read_input_tokens?: number;
+    /** Cache write tokens — billed at 1.25× base input price. Included in input_tokens. */
+    cache_creation_input_tokens?: number;
+};
+export type AnthropicEventParams = {
+    model: string;
+    /**
+     * The resolved model name as returned in response.model
+     * (e.g. "claude-3-5-sonnet-20241022" when you passed "claude-3-5-sonnet-latest").
+     * Pass message.model here for accurate model version tracking.
+     */
+    resolvedModel?: string;
+    usage: AnthropicUsageLike | null | undefined;
+    latencyMs: number;
+    timestamp?: string | Date;
+    costUsd?: number;
+    tags: UsageTags;
+    eventId?: string;
+    /** Cache write TTL: "5m" (default, 1.25× input) or "1h" (extended, 2.0× input). */
+    cacheTtl?: "5m" | "1h";
+    /** Number of web search tool calls in this request. */
+    webSearchCount?: number;
+    /** Number of web fetch tool calls in this request. */
+    webFetchCount?: number;
+    /** Whether this request used the Batch API (50% discount). */
+    isBatchApi?: boolean;
+    /** Whether fast mode was used (6× multiplier). */
+    isFastMode?: boolean;
+};
+export declare function createAnthropicUsageEvent(params: AnthropicEventParams): UsageEventInput;
+export {};

package/dist/anthropic.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAnthropicUsageEvent = createAnthropicUsageEvent;
+function createAnthropicUsageEvent(params) {
+    const usage = params.usage;
+    const cacheRead = usage?.cache_read_input_tokens;
+    const cacheWrite = usage?.cache_creation_input_tokens;
+    return {
+        eventId: params.eventId,
+        provider: "anthropic",
+        model: params.model,
+        resolvedModel: params.resolvedModel,
+        inputTokens: usage?.input_tokens ?? 0,
+        outputTokens: usage?.output_tokens ?? 0,
+        ...(typeof cacheRead === "number" ? { inputTokensCached: cacheRead } : {}),
+        ...(typeof cacheWrite === "number" ? { inputTokensCacheWrite: cacheWrite } : {}),
+        ...(params.cacheTtl ? { cacheTtl: params.cacheTtl } : {}),
+        ...(typeof params.webSearchCount === "number" ? { webSearchCount: params.webSearchCount } : {}),
+        ...(typeof params.webFetchCount === "number" ? { webFetchCount: params.webFetchCount } : {}),
+        ...(params.isBatchApi ? { isBatchApi: true } : {}),
+        ...(params.isFastMode ? { isFastMode: true } : {}),
+        latencyMs: params.latencyMs,
+        costUsd: params.costUsd,
+        timestamp: params.timestamp ?? new Date(),
+        tags: params.tags
+    };
+}

package/dist/client.d.ts

@@ -0,0 +1,14 @@
+import type { ClientConfig, TrackResult, UsageEventBatchInput, UsageTags } from "./types";
+export declare class AISpendGuardClient {
+    private readonly apiKey;
+    private readonly endpoint;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly strict;
+    readonly defaultTags?: UsageTags;
+    private readonly logger;
+    constructor(config: ClientConfig);
+    trackUsage(events: UsageEventBatchInput): Promise<TrackResult>;
+    private sendWithRetry;
+    private send;
+}

package/dist/client.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AISpendGuardClient = void 0;
+const validate_1 = require("./validate");
+const DEFAULT_ENDPOINT = "https://www.aispendguard.com/api/ingest";
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_MAX_RETRIES = 2;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+class AISpendGuardClient {
+    constructor(config) {
+        if (!config.apiKey || config.apiKey.trim().length === 0) {
+            throw new Error("apiKey is required");
+        }
+        this.apiKey = config.apiKey.trim();
+        this.endpoint = (config.endpoint ?? DEFAULT_ENDPOINT).trim();
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.strict = config.strict ?? false;
+        this.defaultTags = config.defaultTags;
+        this.logger = config.logger ?? console;
+    }
+    async trackUsage(events) {
+        try {
+            const list = Array.isArray(events) ? events : [events];
+            if (list.length === 0) {
+                throw new Error("at least one event is required");
+            }
+            const payload = {
+                events: list.map((e) => (0, validate_1.normalizeEvent)(e))
+            };
+            const response = await this.sendWithRetry(payload);
+            return { ok: true, response };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "unknown SDK error";
+            if (this.strict) {
+                throw error;
+            }
+            this.logger.warn(`[aispendguard-sdk] ${message}`);
+            return { ok: false, error: message };
+        }
+    }
+    async sendWithRetry(payload) {
+        let attempt = 0;
+        let lastError = null;
+        while (attempt <= this.maxRetries) {
+            try {
+                return await this.send(payload);
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt === this.maxRetries) {
+                    break;
+                }
+                const backoffMs = Math.min(1000 * 2 ** attempt, 4000);
+                await sleep(backoffMs);
+            }
+            attempt += 1;
+        }
+        throw lastError instanceof Error ? lastError : new Error("request failed");
+    }
+    async send(payload) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await fetch(this.endpoint, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    "x-api-key": this.apiKey
+                },
+                body: JSON.stringify(payload),
+                signal: controller.signal
+            });
+            const raw = (await response.json().catch(() => null));
+            if (!response.ok) {
+                const msg = raw?.errors?.join("; ") || `HTTP ${response.status}`;
+                throw new Error(`ingest failed: ${msg}`);
+            }
+            if (!raw) {
+                throw new Error("ingest failed: empty response body");
+            }
+            return raw;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}
+exports.AISpendGuardClient = AISpendGuardClient;

package/dist/gemini.d.ts

@@ -0,0 +1,40 @@
+import type { UsageEventInput, UsageTags } from "./types";
+/**
+ * Google Gemini generateContent / generateContentStream response.usageMetadata shape.
+ *
+ *   promptTokenCount      → input tokens
+ *   candidatesTokenCount  → output tokens (visible text)
+ *   cachedContentTokenCount → context cache hits — billed at reduced price (~0.1×)
+ *   thoughtsTokenCount    → Gemini 2.5 thinking tokens — billed separately (in addition to output)
+ *   totalTokenCount       → sum of all above
+ *
+ * Notes:
+ *   - cachedContentTokenCount is only present when you use the Context Caching API.
+ *   - thoughtsTokenCount is only present for Gemini 2.5 Flash/Pro with thinking enabled.
+ *   - candidatesTokenCount does NOT include thoughtsTokenCount (unlike Anthropic).
+ *     Gemini bills thinking tokens on top of output tokens.
+ */
+type GeminiUsageLike = {
+    promptTokenCount?: number;
+    candidatesTokenCount?: number;
+    cachedContentTokenCount?: number;
+    thoughtsTokenCount?: number;
+    totalTokenCount?: number;
+};
+export type GeminiEventParams = {
+    model: string;
+    /**
+     * The resolved model version as returned in response.modelVersion
+     * (e.g. "gemini-2.0-flash-001" when you passed "gemini-2.0-flash").
+     * Pass response.modelVersion here for accurate model version tracking.
+     */
+    resolvedModel?: string;
+    usage: GeminiUsageLike | null | undefined;
+    latencyMs: number;
+    timestamp?: string | Date;
+    costUsd?: number;
+    tags: UsageTags;
+    eventId?: string;
+};
+export declare function createGeminiUsageEvent(params: GeminiEventParams): UsageEventInput;
+export {};

package/dist/gemini.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGeminiUsageEvent = createGeminiUsageEvent;
+function createGeminiUsageEvent(params) {
+    const usage = params.usage;
+    const cached = usage?.cachedContentTokenCount;
+    const thinking = usage?.thoughtsTokenCount;
+    return {
+        eventId: params.eventId,
+        provider: "google",
+        model: params.model,
+        resolvedModel: params.resolvedModel,
+        inputTokens: usage?.promptTokenCount ?? 0,
+        outputTokens: usage?.candidatesTokenCount ?? 0,
+        ...(typeof cached === "number" ? { inputTokensCached: cached } : {}),
+        ...(typeof thinking === "number" ? { thinkingTokens: thinking } : {}),
+        latencyMs: params.latencyMs,
+        costUsd: params.costUsd,
+        timestamp: params.timestamp ?? new Date(),
+        tags: params.tags
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import { AISpendGuardClient } from "./client";
+import type { ClientConfig, TrackResult, UsageEventBatchInput } from "./types";
+export declare function init(config: ClientConfig): AISpendGuardClient;
+export declare function getClient(): AISpendGuardClient;
+export declare function trackUsage(events: UsageEventBatchInput): Promise<TrackResult>;
+export { AISpendGuardClient };
+export { createOpenAIUsageEvent } from "./openai";
+export { createAnthropicUsageEvent } from "./anthropic";
+export { createGeminiUsageEvent } from "./gemini";
+export { AISpendGuardCallbackHandler } from "./langchain";
+export { wrapOpenAI } from "./wrap-openai";
+export { wrapAnthropic } from "./wrap-anthropic";
+export { wrapGemini } from "./wrap-gemini";
+export type { LangChainHandlerConfig } from "./langchain";
+export type { AnthropicEventParams } from "./anthropic";
+export type { OpenAIEventParams } from "./openai";
+export type { GeminiEventParams } from "./gemini";
+export type { AllowedTagKey, ClientConfig, IngestEventPayload, IngestRequestPayload, IngestResponse, TrackResult, UsageEventBatchInput, UsageEventInput, UsageTags } from "./types";

package/dist/index.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapGemini = exports.wrapAnthropic = exports.wrapOpenAI = exports.AISpendGuardCallbackHandler = exports.createGeminiUsageEvent = exports.createAnthropicUsageEvent = exports.createOpenAIUsageEvent = exports.AISpendGuardClient = void 0;
+exports.init = init;
+exports.getClient = getClient;
+exports.trackUsage = trackUsage;
+const client_1 = require("./client");
+Object.defineProperty(exports, "AISpendGuardClient", { enumerable: true, get: function () { return client_1.AISpendGuardClient; } });
+let defaultClient = null;
+function init(config) {
+    defaultClient = new client_1.AISpendGuardClient(config);
+    return defaultClient;
+}
+function getClient() {
+    if (!defaultClient) {
+        throw new Error("AISpendGuard SDK is not initialized. Call init(...) first.");
+    }
+    return defaultClient;
+}
+async function trackUsage(events) {
+    return getClient().trackUsage(events);
+}
+var openai_1 = require("./openai");
+Object.defineProperty(exports, "createOpenAIUsageEvent", { enumerable: true, get: function () { return openai_1.createOpenAIUsageEvent; } });
+var anthropic_1 = require("./anthropic");
+Object.defineProperty(exports, "createAnthropicUsageEvent", { enumerable: true, get: function () { return anthropic_1.createAnthropicUsageEvent; } });
+var gemini_1 = require("./gemini");
+Object.defineProperty(exports, "createGeminiUsageEvent", { enumerable: true, get: function () { return gemini_1.createGeminiUsageEvent; } });
+var langchain_1 = require("./langchain");
+Object.defineProperty(exports, "AISpendGuardCallbackHandler", { enumerable: true, get: function () { return langchain_1.AISpendGuardCallbackHandler; } });
+var wrap_openai_1 = require("./wrap-openai");
+Object.defineProperty(exports, "wrapOpenAI", { enumerable: true, get: function () { return wrap_openai_1.wrapOpenAI; } });
+var wrap_anthropic_1 = require("./wrap-anthropic");
+Object.defineProperty(exports, "wrapAnthropic", { enumerable: true, get: function () { return wrap_anthropic_1.wrapAnthropic; } });
+var wrap_gemini_1 = require("./wrap-gemini");
+Object.defineProperty(exports, "wrapGemini", { enumerable: true, get: function () { return wrap_gemini_1.wrapGemini; } });

package/dist/langchain.d.ts

@@ -0,0 +1,61 @@
+/**
+ * LangChain.js callback handler for AISpendGuard.
+ *
+ * Tracks LLM token usage from LangChain invocations via the SDK singleton.
+ * Never reads prompt content or model outputs — only metadata and token counts.
+ *
+ * Usage:
+ *   import { init, AISpendGuardCallbackHandler } from "@aispendguard/sdk";
+ *
+ *   init({ apiKey: "asg_..." });
+ *   const handler = new AISpendGuardCallbackHandler({
+ *     defaultTags: { feature: "chatbot", route: "/api/chat" },
+ *   });
+ *
+ *   const llm = new ChatOpenAI({ callbacks: [handler] });
+ */
+interface Serialized {
+    id?: string[];
+    name?: string;
+    type?: string;
+    lc?: number;
+    [key: string]: unknown;
+}
+interface Generation {
+    text: string;
+    generationInfo?: Record<string, unknown>;
+}
+interface LLMResult {
+    generations: Generation[][];
+    llmOutput?: Record<string, unknown>;
+}
+/**
+ * Minimal abstract base we implement. At runtime LangChain will duck-type
+ * check the handler; it doesn't require `extends BaseCallbackHandler` from
+ * the exact same package version — it only needs the method signatures and
+ * the `name` property.
+ */
+declare abstract class BaseCallbackHandlerCompat {
+    abstract name: string;
+    lc_serializable: boolean;
+    ignoreLLM: boolean;
+    ignoreChain: boolean;
+    ignoreAgent: boolean;
+    ignoreRetriever: boolean;
+    ignoreCustomEvent: boolean;
+}
+export interface LangChainHandlerConfig {
+    /** Default tags merged into every event. */
+    defaultTags?: Record<string, string>;
+}
+export declare class AISpendGuardCallbackHandler extends BaseCallbackHandlerCompat {
+    name: string;
+    private readonly defaultTags;
+    private readonly runs;
+    constructor(config?: LangChainHandlerConfig);
+    handleLLMStart(serialized: Serialized, _prompts: string[], runId?: string, _parentRunId?: string, _extraParams?: Record<string, unknown>, _tags?: string[], _metadata?: Record<string, unknown>, _name?: string): void;
+    handleChatModelStart(serialized: Serialized, _messages: unknown[][], runId?: string, _parentRunId?: string, _extraParams?: Record<string, unknown>, _tags?: string[], _metadata?: Record<string, unknown>, _name?: string): void;
+    handleLLMEnd(output: LLMResult, runId?: string, _parentRunId?: string, _tags?: string[]): void;
+    handleLLMError(_err: Error, runId?: string): void;
+}
+export {};