npm package: @lekha-dev/sdk
Description: Official SDK for Lekha — financial document intelligence API for AI agents
Author: Lekha
Latest version: 0.1.0

# lekha

Official SDK for [Lekha](https://lekha.dev) -- financial document intelligence API for AI agents.

Send any Indian financial document (bank statement, CAS report, salary slip) and get back clean, structured JSON.

## Installation

```bash
npm install @lekha-dev/sdk
```

## Quick Start

```typescript
import { Lekha } from "@lekha-dev/sdk";
import { readFileSync } from "fs";

const lekha = new Lekha("lk_live_your_api_key");

// Extract data from a bank statement
const result = await lekha.extract({
  document: readFileSync("statement.pdf").toString("base64"),
  type: "bank_statement",
});

console.log(result.data); // Structured JSON with account, transactions, summary
```

## API Reference

### `new Lekha(apiKey)`

Create a client with an API key string:

```typescript
const lekha = new Lekha("lk_live_your_api_key");
```

Or with a config object:

```typescript
const lekha = new Lekha({
  apiKey: "lk_live_your_api_key",
  baseUrl: "https://custom-endpoint.example.com", // optional
});
```

### `lekha.extract(options)`

Extract structured data from a financial document.

```typescript
const result = await lekha.extract({
  document: base64String, // base64-encoded PDF, PNG, or JPEG
  type: "auto", // "auto" | "bank_statement" | "cas" | "salary_slip" | "itr" | "cibil" | "gst_invoice"
  options: {
    categorize_transactions: true, // default: true
    include_confidence_scores: true, // default: true
    include_raw_text: false, // default: false
  },
});
```

**Returns:** `ExtractResponse` with `document_type`, `institution`, `confidence`, `data`, `validation`, and `metadata`.

### `lekha.supported()`

List supported document types and institutions.

```typescript
const supported = await lekha.supported();
// { document_types: { bank_statement: { supported_institutions: [...], extracted_fields: [...] } } }
```

### `lekha.usage()`

Check your API usage for the current billing period.

```typescript
const usage = await lekha.usage();
// { plan: "free", usage: { extractions_used: 42, extractions_limit: 100, extractions_remaining: 58 } }
```

## Agent Framework Integrations

### Claude Tool Use (Anthropic SDK)

```typescript
import Anthropic from "@anthropic-ai/sdk";
import { lekhaToolDefinition } from "@lekha-dev/sdk/tool-definition";
import { Lekha } from "@lekha-dev/sdk";

const anthropic = new Anthropic();
const lekha = new Lekha("lk_live_your_api_key");

// Register as a tool
const response = await anthropic.messages.create({
  model: "claude-sonnet-4-20250514",
  tools: [lekhaToolDefinition],
  messages: [{ role: "user", content: "Analyze my bank statement" }],
});

// Handle tool calls
for (const block of response.content) {
  if (block.type === "tool_use" && block.name === "extract_financial_document") {
    const input = block.input as { document: string; type?: string };
    const result = await lekha.extract({
      document: input.document,
      type: (input.type as "auto" | "bank_statement") ?? "auto",
    });
    // Return result to Claude...
  }
}
```

### LangChain

```typescript
import { createLekhaLangChainTool } from "@lekha-dev/sdk/integrations/langchain";

const tool = createLekhaLangChainTool({ apiKey: "lk_live_your_api_key" });
// Use `tool` with LangChain's agent executor
```

### Vercel AI SDK

```typescript
import { createLekhaVercelTool } from "@lekha-dev/sdk/integrations/vercel-ai";

const tool = createLekhaVercelTool({ apiKey: "lk_live_your_api_key" });
// Use with Vercel AI SDK's `tools` parameter
```

## Error Handling

All API errors throw a `LekhaError` with structured information:

```typescript
import { Lekha, LekhaError } from "@lekha-dev/sdk";

try {
  await lekha.extract({ document: "..." });
} catch (err) {
  if (err instanceof LekhaError) {
    console.error(err.code);       // "INVALID_API_KEY"
    console.error(err.message);    // "Invalid key"
    console.error(err.status);     // 401
    console.error(err.suggestion); // "Check your API key in the dashboard"
  }
}
```

## License

MIT