@lavapayments/nodejs

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

Installation

npm install @lavapayments/nodejs

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

Quick Start

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.

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:

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):

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:

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:

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

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

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:

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.

// 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.