@costgov/node

Official Node.js SDK for CostGovernor - Usage tracking and rate limiting protection for your applications.

Installation

npm install @costgov/node
# or
pnpm add @costgov/node
# or
yarn add @costgov/node

Quick Start

import { CostGovernor } from '@costgov/node';

// Initialize the client
const client = new CostGovernor({
  apiKey: 'your_api_key',
  projectId: 'your_project_id',
  apiUrl: 'https://your-costgov-instance.com', // Optional, defaults to your instance
});

// Track usage
client.track('api.openai.completion', 1500); // Track tokens used
client.track('email.send', 1); // Track email sent
client.track('database.query', 1); // Track database query

// Flush events (automatically done on shutdown)
await client.shutdown();

Features

• Usage Tracking: Track any metric (API calls, tokens, database queries, etc.)
• Rate Limiting: Built-in token bucket rate limiting
• Batch Processing: Automatically batches events for efficient delivery
• Auto-flush: Handles flushing on process exit
• TypeScript: Full TypeScript support with type definitions

Configuration

const client = new CostGovernor({
  apiKey: string;           // Required: Your CostGov API key
  projectId: string;        // Required: Your project ID
  apiUrl?: string;          // Optional: Custom API URL
  flushInterval?: number;   // Optional: Batch flush interval (default: 5000ms)
  maxBatchSize?: number;    // Optional: Max events per batch (default: 100)
});

Usage Examples

Track OpenAI API Calls

// After making an OpenAI API call
const response = await openai.chat.completions.create({...});
client.track('openai.tokens', response.usage.total_tokens);

Track Email Sends

await sendEmail(to, subject, body);
client.track('email.send', 1);

Track Database Queries

const results = await db.query('SELECT * FROM users');
client.track('db.query.select', 1);

Track Custom Metrics

client.track('custom.metric.name', value);

API Reference

client.track(metric: string, units: number)

Track usage for a specific metric.

• metric: String identifier for the metric (e.g., 'openai.tokens', 'email.send')
• units: Number of units to track

client.shutdown(): Promise<void>

Flush all pending events and close connections. Call this before your application exits.

process.on('SIGINT', async () => {
  await client.shutdown();
  process.exit(0);
});

Best Practices

1. Initialize once: Create a single client instance and reuse it
2. Use descriptive metrics: Name your metrics clearly (e.g., 'openai.gpt4.tokens')
3. Call shutdown: Always call shutdown() before your app exits
4. Error handling: Wrap track calls in try-catch if needed

Get Your API Key

1. Sign up at your CostGov instance
2. Create a new project
3. Copy your API key and project ID
4. Add them to your environment variables:

COSTGOV_API_KEY=cg_xxxxx
COSTGOV_PROJECT_ID=proj_xxxxx

License

MIT

Support

• Documentation: https://docs.costgov.com (if available)
• Issues: https://github.com/your-org/costgov/issues
• Email: [email protected] (update with actual support email)