npm package: @langspend/node
Description: LangSpend Node SDK - Track LLM costs and usage with customer attribution. Requires LangSpend API key for production use.
Author: LangSpend
Latest version: 1.0.1

# LangSpend Node.js SDK

Track LLM costs and usage with customer attribution for OpenAI, Anthropic, AWS Bedrock, and Google Vertex AI.

## Features

- **Customer Attribution**: Track costs per customer and feature
- **Auto-Track**: Zero setup automatic tracking
- **Manual Wrapping**: Full control over tracking
- **Multi-Provider Support**: OpenAI, Anthropic, AWS Bedrock, Google Vertex AI
- **Streaming Support**: Works with streaming responses
- **Error Resilience**: Never breaks your LLM calls

## Installation

```bash
npm install @langspend/node
```

## Get Your API Key

**LangSpend is a commercial SaaS product with a free tier available.**

Get your LangSpend API key at [langspend.com](https://langspend.com)

> **Note**: An API key is required for production use. The SDK includes a free tier for development and evaluation.

## Quick Start

### 1. Install the SDK

```bash
npm install @langspend/node
```

### 2. Get Your API Key

Sign up at [app.langspend.com](https://app.langspend.com) to get your free API key.

Your API key will look something like `lsp_your_api_key`.

### 3. Wrap Your LLM Client

```typescript
import { LangSpend, wrapOpenAI } from '@langspend/node'
import OpenAI from 'openai'

const langspend = new LangSpend({ 
  apiKey: process.env.LANGSPEND_API_KEY!,
  tags: {
    customer?: {
      id: 'user_123',
      name: 'John Doe',
      email?: 'john@example.com'
    },
    environment: process.env.NODE_ENV || 'development'
  }
})

export const openai = wrapOpenAI(new OpenAI({
  apiKey: process.env.OPENAI_API_KEY, 
}), langspend)
```

### 4. Start Tracking

```typescript
async function main() {
  const completion = await openai.chat.completions.create({
    messages: [{ role: 'user', content: 'Analyze this complex dataset and provide insights.' }],
    model: 'gpt-4',
  });
  console.log(completion.choices[0].message.content);
}

main();
```

## Option 2: Auto-Track (Zero Setup, no customer level tracking)

```typescript
// One line setup
import '@langspend/node/auto-track'

// Now all your LLM calls are automatically tracked
import OpenAI from 'openai'
import Anthropic from '@anthropic-ai/sdk'
import { BedrockRuntimeClient } from '@aws-sdk/client-bedrock-runtime'
import { VertexAI } from '@google-cloud/vertexai'

const openai = new OpenAI()
const anthropic = new Anthropic()
const bedrock = new BedrockRuntimeClient()
const vertex = new VertexAI({ project: 'your-project', location: 'us-central1' })

// All calls are automatically tracked
```

### Environment Variables

```bash
# Required
LANGSPEND_API_KEY=your_api_key_here

# Optional
LANGSPEND_DEBUG=true                    # Enable debug logging
LANGSPEND_AUTO_RESOLVE_CUSTOMERS=true   # Enable Supabase auto-resolution
LANGSPEND_BASE_URL=https://platform.langspend.com
LANGSPEND_AUTO_TRACK=false             # Disable auto-track
```

### Customer and Feature Tracking

The SDK supports rich customer and feature attribution through the `tags` configuration:

```typescript
const langspend = new LangSpend({ 
  apiKey: process.env.LANGSPEND_API_KEY!,
  tags: {
    customer?: {
      id: 'user_123',           // Required: Unique customer identifier
      name: 'John Doe',         // Optional: Customer name
      email?: 'john@example.com' // Optional: Customer email
    },
    feature?: 'chat-api',       // Optional: Feature name
    environment: 'production'    // Optional: Environment
  }
})
```

## Supported Providers

LangSpend supports OpenAI, Anthropic, AWS Bedrock, and Google Vertex AI. See the [examples directory](examples/) for integration examples with each provider.

## Demo Application

A complete Next.js + FastAPI demo is available in [`examples/nextjs-chat-demo/`](examples/nextjs-chat-demo/):

```bash
cd examples/nextjs-chat-demo/backend
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
cp env.example .env
# Edit .env with your API keys
python main.py
```

## Examples

See the [`examples/`](examples/) directory for comprehensive usage examples:

- `basic-usage.ts` - Basic usage examples
- `with-customer-tags.ts` - Customer attribution examples
- `anthropic-usage.ts` - Anthropic integration
- `bedrock-usage.ts` - AWS Bedrock integration
- `vertex-usage.ts` - Google Vertex AI integration
- `express-api.ts` - Express.js integration
- `nextjs-api-route.ts` - Next.js API route integration
- `streaming.ts` - Streaming responses
- `multi-model.ts` - Multiple providers
- `nextjs-chat-demo/` - Complete Next.js + FastAPI demo

## Configuration

### Auto-Track Configuration

```typescript
import { configureAutoTrack } from '@langspend/node'

configureAutoTrack({
  apiKey: 'lsp_your_api_key',        // Required: Your LangSpend API key
  baseURL: 'https://platform.langspend.com', // Optional: Custom API endpoint
  debug: false,                       // Optional: Enable debug logging
  autoResolveCustomers: false,        // Optional: Enable Supabase auto-resolution
  maxRetries: 3,                      // Optional: Max retry attempts for tracking
  enabled: true                       // Optional: Enable/disable auto-track
})
```

### Manual Wrapping Configuration

```typescript
const langspend = new LangSpend({
  apiKey: 'lsp_your_api_key',        // Required: Your LangSpend API key
  baseURL: 'https://platform.langspend.com', // Optional: Custom API endpoint
  debug: false,                       // Optional: Enable debug logging
  autoResolveCustomers: false,        // Optional: Enable Supabase auto-resolution
  maxRetries: 3                       // Optional: Max retry attempts for tracking
})
```

## Error Handling

The SDK never throws errors for tracking failures. All tracking happens asynchronously and failures are silent by default.

Enable debug mode to log tracking errors:

```typescript
// Auto-track debug mode
LANGSPEND_DEBUG=true

// Manual wrapping debug mode
const langspend = new LangSpend({
  apiKey: 'lsp_your_api_key',
  debug: true // Logs tracking errors to console
})
```

## TypeScript Support

The SDK is written in TypeScript and includes full type definitions. The `tags` property provides rich typing for customer and feature attribution.

```typescript
import type { LangSpendTags } from '@langspend/node'

const tags: LangSpendTags = {
  customer?: {
    id: 'user_123',
    name: 'John Doe',
    email?: 'john@example.com'
  },
  feature?: 'chat-api',
  environment: 'production'
}
```

## License

MIT