npm package: @orbithq/sdk
Description: Orbit - AI Cost Analytics SDK. Track, monitor, and optimize your AI spend.
Author: OrbitHQ
Latest version: 0.1.2

# Orbit SDK

Track, monitor, and optimize your AI spend across OpenAI, Anthropic, and other LLM providers.

## Installation

```bash
npm install @orbithq/sdk
# or
yarn add @orbithq/sdk
# or
pnpm add @orbithq/sdk
```

## Quick Start

### 1. Get your API key

Sign up at [Orbit](https://orbit-analytics.vercel.app) and create an API key.

### 2. Initialize the SDK

```typescript
import { Orbit } from '@orbithq/sdk';

const orbit = new Orbit({
  apiKey: 'orb_live_xxxxxxxxxxxxxxxxxxxxxxxx',
  defaultFeature: 'my-app', // Optional: default feature for all events
});
```

### 3. Track your LLM calls

#### Option A: Automatic tracking (Recommended)

Wrap your OpenAI or Anthropic client for automatic tracking:

```typescript
import OpenAI from 'openai';
import { Orbit } from '@orbithq/sdk';

const orbit = new Orbit({ apiKey: 'orb_live_xxx' });
const openai = orbit.wrapOpenAI(new OpenAI(), {
  feature: 'chat-assistant', // Attribute all calls to this feature
});

// All API calls are now automatically tracked!
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello, world!' }],
});
```

Works with Anthropic too:

```typescript
import Anthropic from '@anthropic-ai/sdk';
import { Orbit } from '@orbithq/sdk';

const orbit = new Orbit({ apiKey: 'orb_live_xxx' });
const anthropic = orbit.wrapAnthropic(new Anthropic(), {
  feature: 'document-analysis',
});

const message = await anthropic.messages.create({
  model: 'claude-3-opus-20240229',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Analyze this document...' }],
});
```

#### Option B: Manual tracking

For other providers or custom implementations:

```typescript
import { Orbit } from '@orbithq/sdk';

const orbit = new Orbit({ apiKey: 'orb_live_xxx' });

// Track a successful request
await orbit.track({
  model: 'gpt-4o',
  input_tokens: 150,
  output_tokens: 50,
  latency_ms: 1234,
  feature: 'summarization',
  environment: 'production',
});

// Track an error
await orbit.trackError('gpt-4o', 'rate_limit_exceeded', 'Rate limit exceeded', {
  feature: 'chat-assistant',
  input_tokens: 150,
});
```

## Configuration

```typescript
const orbit = new Orbit({
  // Required
  apiKey: 'orb_live_xxx',

  // Optional
  baseUrl: 'https://orbit-analytics.vercel.app/api/v1', // Custom API endpoint
  defaultFeature: 'my-app',                   // Default feature name
  defaultEnvironment: 'production',            // 'production' | 'staging' | 'development'
  debug: false,                                // Enable debug logging

  // Batching (for high-volume applications)
  batchEvents: true,       // Batch events before sending
  batchSize: 10,           // Max events per batch
  batchInterval: 5000,     // Max ms before sending batch

  // Reliability
  retry: true,             // Retry failed requests
  maxRetries: 3,           // Max retry attempts
});
```

## Event Properties

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `model` | string | Yes | Model name (e.g., 'gpt-4o', 'claude-3-opus') |
| `input_tokens` | number | Yes | Number of input tokens |
| `output_tokens` | number | Yes | Number of output tokens |
| `provider` | string | No | Provider name (auto-detected if not provided) |
| `latency_ms` | number | No | Request latency in milliseconds |
| `feature` | string | No | Feature name for attribution |
| `environment` | string | No | Environment ('production', 'staging', 'development') |
| `status` | string | No | Request status ('success', 'error', 'timeout') |
| `error_type` | string | No | Error type if status is 'error' |
| `error_message` | string | No | Error message if status is 'error' |
| `user_id` | string | No | Your application's user ID |
| `session_id` | string | No | Session ID for grouping requests |
| `request_id` | string | No | Unique request ID for tracing |
| `metadata` | object | No | Additional key-value metadata |

## Feature Attribution

Features are Orbit's killer feature - they let you see exactly which parts of your application are consuming AI resources:

```typescript
// Track different features
await orbit.track({
  model: 'gpt-4o',
  input_tokens: 100,
  output_tokens: 50,
  feature: 'chat-assistant',  // <-- Attribute to chat feature
});

await orbit.track({
  model: 'gpt-4o',
  input_tokens: 500,
  output_tokens: 200,
  feature: 'document-analysis',  // <-- Attribute to doc analysis
});
```

Then in the Orbit dashboard, you'll see:
- Cost breakdown by feature
- Request volume by feature
- Error rates by feature
- And more!

## Environments

Track usage across different environments:

```typescript
const orbit = new Orbit({
  apiKey: 'orb_live_xxx',
  defaultEnvironment: process.env.NODE_ENV === 'production' ? 'production' : 'development',
});
```

## Graceful Shutdown

For serverless or short-lived processes, flush events before exit:

```typescript
// Before your process exits
await orbit.shutdown();
```

## TypeScript Support

Full TypeScript support with exported types:

```typescript
import { Orbit, OrbitEvent, OrbitConfig } from '@orbithq/sdk';

const config: OrbitConfig = {
  apiKey: 'orb_live_xxx',
};

const event: OrbitEvent = {
  model: 'gpt-4o',
  input_tokens: 100,
  output_tokens: 50,
};
```

## License

MIT