SDK Reference

import { BearLumen } from '@bearlumen/node-sdk';

// apiKey is required — the SDK does NOT read an env var for you, so pass it in.
const bear = new BearLumen({
  apiKey: process.env.BEAR_LUMEN_API_KEY!,
  // environment: 'staging',          // optional: targets api.staging.bearlumen.com
  // baseUrl: 'https://api.bearlumen.com',  // optional: overrides environment
  // timeout: 30000,                   // optional: ms (default 30000)
});

const { ok, organizationId } = await bear.ping();
console.log(ok, organizationId);

import OpenAI from 'openai';
const openai = new OpenAI();

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }],
});

// Hand the raw provider response to Bear Lumen — it auto-detects the provider,
// extracts token usage, and queues a usage event for background delivery.
const result = bear.track(response);
console.log(result.model, result.inputTokens, result.outputTokens);

// Streaming: track() returns a pass-through wrapper. Iterate as normal,
// then await .result for the final usage once the stream is consumed.
const stream = bear.track(response, { model: 'anthropic.claude-3-5-sonnet' });
for await (const chunk of stream) {
  // chunks pass through unchanged
}
const result = await stream.result;
console.log(result.inputTokens, result.outputTokens);

import { Provider } from '@bearlumen/node-sdk';

// No LLM response? Track non-token services (TTS, images, GPU seconds) or a
// pre-calculated cost by passing null with explicit options. model is required.
bear.track(null, {
  model: 'eleven_multilingual_v2',
  provider: Provider.ELEVENLABS,
  feature: 'narration',
  units: { characters: 1500 },
});

const page = await bear.usage.events({
  startDate: '2026-01-01',
  endDate: '2026-01-31',
  limit: 100,        // optional (default 100, max 1000)
  offset: 0,         // optional
});
for (const e of page.events) console.log(e.model, e.inputTokens);

const s = await bear.usage.summary({ startDate: '2026-01-01', endDate: '2026-01-31' });
console.log(s.totalEvents, s.totalInputTokens, s.totalOutputTokens);

const byModel = await bear.costs.byModel({ startDate: '2026-01-01', endDate: '2026-01-31' });
for (const item of byModel.items) {
  console.log(item.attributionValue, item.totalCost, item.percentOfTotal);
}
console.log('Total:', byModel.totalCost);

// Scope any cost query to one end user by external id.
const user = bear.costs.forUser('user_123');
const summary = await user.summary({ startDate: '2026-01-01', endDate: '2026-01-31' });
const byModel = await user.byModel({ startDate: '2026-01-01', endDate: '2026-01-31' });

// Break cost down by any custom dimension you tagged events with.
const result = await bear.attribution.byDimension({
  dimension: 'team',
  startDate: '2026-01-01',
  endDate: '2026-01-31',
});
for (const item of result.items) console.log(item.attributionValue, item.totalCost);

// List the agents / workflows that have data in a range:
const { agents } = await bear.attribution.agents({ startDate: '2026-01-01', endDate: '2026-01-31' });

const result = await bear.margins.summary({ startDate: '2026-01-01', endDate: '2026-01-31' });
console.log(result.summary.marginPercent);

const byUser = await bear.margins.byEndUser({ startDate: '2026-01-01', endDate: '2026-01-31' });
for (const u of byUser.endUsers) console.log(u.endUserName, u.marginPercent);

const result = await bear.insights.summary({
  start: '2026-01-01',
  end: '2026-01-31',
  include: ['distributions'],
  limit: 10,
});
console.log(result.totals);

import { BearLumen, BearLumenApiError } from '@bearlumen/node-sdk';

try {
  await bear.margins.summary({ startDate: '2026-01-01', endDate: '2026-01-31' });
} catch (error) {
  if (error instanceof BearLumenApiError) {
    if (error.code === 'rate_limit_exceeded') {
      console.error('Rate limited, retry after', error.retryAfter, 'seconds');
    }
    console.error('Error', error.code, error.message);
    console.error('Request ID:', error.correlationId); // include in support tickets
  }
}