npm package: @lavapayments/nodejs
Description: Backend SDK for Lava Payments API - enabling usage-based billing for AI services
Author: Lava
Latest version: 11.2.0

# @lavapayments/nodejs

Backend SDK for Lava Payments API — enabling usage-based billing for AI services.

## Installation

```bash
npm install @lavapayments/nodejs
```

Requires Node.js 18.0.0 or higher. Zero runtime dependencies.

## Quick Start

```typescript
import { Lava } from '@lavapayments/nodejs';

// Reads from LAVA_SECRET_KEY environment variable automatically
const lava = new Lava();

// Or pass explicitly
const lava = new Lava('aks_live_...');
```

## Resources

| Resource | Purpose | Key Methods |
|----------|---------|-------------|
| `checkoutSessions` | Create payment flows | `create()` |
| `customers` | Manage customer links | `list()`, `retrieve()`, `getSubscription()`, `delete()` |
| `requests` | Track API usage | `list()`, `create()`, `retrieve()` |
| `usage` | Aggregate usage stats | `retrieve()` |
| `subscriptions` | Manage billing plans | `listPlans()`, `retrievePlan()`, `createPlan()`, `updatePlan()`, `deletePlan()`, `list()`, `update()`, `cancel()` |
| `meters` | Pricing configuration | `list()`, `retrieve()`, `create()`, `update()`, `delete()` |
| `creditBundles` | Add-on credit packs | `list()`, `retrieve()` |
| `webhooks` | Event notifications | `list()`, `retrieve()`, `create()`, `update()`, `delete()` |
| `secretKeys` | API key management | `list()`, `create()`, `delete()` |
| `spendKeys` | Wallet spend keys | `list()`, `retrieve()`, `create()`, `update()`, `revoke()`, `rotate()` |
| `models` | Model discovery | `list()` |

Plus utility methods:
- `gateway()` — Make requests through Lava's gateway in a single call
- `generateForwardToken()` — Create authentication tokens for AI requests
- `Lava.login()` — Browser-based CLI authentication (static)
- `Lava.exchangeAuthCode()` — Exchange auth code for credentials (static)

## Gateway Requests

Make requests through Lava's gateway in a single call. The `gateway()` method handles forward token generation, URL construction, and body serialization automatically.

```typescript
const data = await lava.gateway('https://api.openai.com/v1/chat/completions', {
  body: {
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Hello!' }],
  },
});
```

**With customer billing** — charge a customer's wallet:

```typescript
const data = await lava.gateway('https://api.openai.com/v1/chat/completions', {
  body: { model: 'gpt-4o', messages: [{ role: 'user', content: 'Hello!' }] },
  customer_id: 'cus_123',
  meter_slug: 'ai-usage',
});
```

**With custom headers** (e.g., Anthropic):

```typescript
const data = await lava.gateway('https://api.anthropic.com/v1/messages', {
  body: { model: 'claude-sonnet-4-20250514', max_tokens: 1024, messages: [{ role: 'user', content: 'Hello!' }] },
  headers: { 'anthropic-version': '2023-06-01' },
});
```

> **Note:** Pass the raw provider URL (e.g., `https://api.openai.com/v1/chat/completions`), not `lava.providers.*` URLs. The `gateway()` method constructs the forwarding URL internally.

## Forward Tokens

Generate forward tokens to authenticate AI requests through Lava's proxy.

**Customer billing** — charge a customer's wallet with your pricing:

```typescript
const forwardToken = lava.generateForwardToken({
  customer_id: 'conn_abc123',
  meter_slug: 'my-meter',
});

const response = await fetch(lava.providers.openai + '/chat/completions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${forwardToken}`,
  },
  body: JSON.stringify({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: 'Hello!' }],
  }),
});
```

**Meter-only** — track usage on a meter without billing a customer:

```typescript
const forwardToken = lava.generateForwardToken({
  meter_slug: 'my-meter',
});
```

**Billing disabled** — proxy through a customer's meter without charging:

```typescript
const forwardToken = lava.generateForwardToken({
  customer_id: 'conn_abc123',
  meter_slug: 'my-meter',
  disable_billing: true,
});
```

**Unmanaged (BYOK)** — bring your own provider key for tracking only:

```typescript
const forwardToken = lava.generateForwardToken({
  customer_id: null,
  meter_slug: null,
  provider_key: process.env.OPENAI_API_KEY!,
});
```

## Supported Providers

Pre-configured provider URLs are available via `lava.providers.*` for 27 AI providers including OpenAI, Anthropic, Google, Mistral, DeepSeek, xAI, Groq, Together, Fireworks, Cohere, and more.

```typescript
// Use a pre-configured provider URL
const response = await fetch(lava.providers.anthropic + '/messages', { ... });

// Or use any provider via the forward endpoint directly
const url = 'https://api.lava.so/v1/forward?u=' +
  encodeURIComponent('https://api.yourprovider.com/endpoint');
```

The SDK automatically routes to sandbox (`sandbox-api.lava.so`) or production (`api.lava.so`) based on your secret key prefix (`aks_test_*` vs `aks_live_*`).

## Documentation

For complete documentation, visit [lava.so/docs/sdk/nodejs](https://www.lava.so/docs/sdk/nodejs).