npm package: @offsetour/sdk
Description: OffsetOur.ai SDK — AI governance tracking, carbon accounting, and system auto-discovery
Author: OffsetOur.ai
Latest version: 0.1.0

# @offsetour/sdk

OffsetOur.ai SDK for AI governance tracking, carbon accounting, and system auto-discovery.

Track every AI API call your organization makes. Usage data flows into your OffsetOur.ai governance dashboard — keeping your AI Systems Registry current, calculating carbon footprint, and generating audit-ready evidence.

## Install

```bash
npm install @offsetour/sdk
```

Peer dependencies (install whichever providers you use):
```bash
npm install openai        # For OpenAI wrapper
npm install @anthropic-ai/sdk  # For Anthropic wrapper
```

## Quick Start

### Option 1: Provider Wrappers (Recommended)

Drop-in replacements for OpenAI and Anthropic clients. Your existing code stays the same — tracking happens automatically.

```javascript
const { createOpenAIClient } = require('@offsetour/sdk');

const openai = createOpenAIClient({
  openaiApiKey: process.env.OPENAI_API_KEY,
  offsetourApiKey: process.env.OFFSETOUR_API_KEY,
  aiSystemId: 'sys_YOUR_SYSTEM_ID',  // From your AI Systems Registry
});

// Use exactly as before — tracking happens automatically
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello' }],
});
```

```javascript
const { createAnthropicClient } = require('@offsetour/sdk');

const anthropic = createAnthropicClient({
  anthropicApiKey: process.env.ANTHROPIC_API_KEY,
  offsetourApiKey: process.env.OFFSETOUR_API_KEY,
  aiSystemId: 'sys_YOUR_SYSTEM_ID',
});

const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello' }],
});
```

### Option 2: Manual Tracking

For custom integrations or providers we don't wrap yet.

```javascript
const { OffsetOurClient } = require('@offsetour/sdk');

const tracker = new OffsetOurClient({
  apiKey: process.env.OFFSETOUR_API_KEY,
  aiSystemId: 'sys_YOUR_SYSTEM_ID',
});

// Record a single event immediately
await tracker.usage.record({
  model: 'gpt-4o',
  inputTokens: 150,
  outputTokens: 250,
  sessionId: 'chat-session-123',
});

// Or batch multiple events
await tracker.usage.recordBatch({
  items: [
    { model: 'gpt-4o', inputTokens: 100, outputTokens: 50 },
    { model: 'claude-sonnet-4-20250514', inputTokens: 200, outputTokens: 100 },
  ],
});
```

### Option 3: Buffered Tracking

For high-volume applications. Records are buffered and sent in batches every 10 seconds.

```javascript
const tracker = new OffsetOurClient({
  apiKey: process.env.OFFSETOUR_API_KEY,
  aiSystemId: 'sys_YOUR_SYSTEM_ID',
  autoFlush: true,        // default
  flushIntervalMs: 10000, // default: 10 seconds
  batchSize: 50,          // default: 50 records per batch
});

// Enqueue records (non-blocking)
tracker.enqueue({ model: 'gpt-4o', inputTokens: 100, outputTokens: 50 });
tracker.enqueue({ model: 'gpt-4o', inputTokens: 200, outputTokens: 100 });

// Flush manually if needed
await tracker.flush();

// On process exit, flush remaining records
await tracker.shutdown();
```

## AI System Attribution

The `aiSystemId` parameter links usage data to entries in your AI Systems Registry. When the backend detects usage from a model not yet registered, it flags it for review — keeping your inventory current with zero manual effort.

Get your AI system IDs from the OffsetOur.ai dashboard under **AI Systems > Registry**.

## Graceful Shutdown

Both the provider wrappers and manual tracker buffer records. To ensure nothing is lost on process exit:

```javascript
process.on('SIGTERM', async () => {
  // Provider wrapper
  await openai._offsetour.shutdown();

  // Or manual tracker
  await tracker.shutdown();

  process.exit(0);
});
```

## API Reference

### `OffsetOurClient(options)`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiKey` | string | *required* | OffsetOur API key |
| `aiSystemId` | string | null | Default AI system ID |
| `baseUrl` | string | `https://api.offsetour.ai/api/v1` | API base URL |
| `autoFlush` | boolean | true | Auto-flush buffered records |
| `flushIntervalMs` | number | 10000 | Auto-flush interval (ms) |
| `batchSize` | number | 50 | Max records per batch |
| `debug` | boolean | false | Enable debug logging |

### `createOpenAIClient(options)` / `createAnthropicClient(options)`

Returns a standard provider client with tracking injected. All original methods work identically.

Tracked endpoints:
- **OpenAI**: `chat.completions.create`, `responses.create`, `embeddings.create`
- **Anthropic**: `messages.create`

## License

MIT