@costgov/node

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

Installation

npm install costgov
# or
pnpm add costgov
# or
yarn add costgov

Quick Start

import { CostGov } from 'costgov';

// Initialize the client
const client = new CostGov({
  apiKey: process.env.COSTGOV_API_KEY,
  projectId: process.env.COSTGOV_PROJECT_ID,
  apiUrl: process.env.COSTGOV_API_URL || 'https://ingest.costgov.com',
});

// 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();

Test Your Setup

After installation, verify everything works with the built-in test CLI:

# Set up your .env file with:
# COSTGOV_API_KEY=cg_prod_xxxxx
# COSTGOV_PROJECT_ID=proj_xxxxx
# COSTGOV_API_URL=https://ingest.costgov.com

npx costgov

You should see:

🔍 CostGov SDK Test

API Key: cg_prod_xxxx...xxxx
Project: proj_xxxxxxxxxxxxx
API URL: https://ingest.costgov.com

📤 Sending test event...

✅ Test event sent successfully!

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
• Test CLI: Built-in verification tool

Configuration

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

Environment Variables

COSTGOV_API_KEY=cg_prod_xxxxx
COSTGOV_PROJECT_ID=proj_xxxxx
COSTGOV_API_URL=https://ingest.costgov.com

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

Graceful Shutdown

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

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.

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: The SDK is fail-open - tracking errors won't crash your app

Get Your API Key

1. Sign up at https://costgov.com
2. Create a new project in the onboarding flow
3. Copy your API key and project ID
4. Add them to your environment variables

License

MIT

Support

• Documentation: https://costgov.com/docs
• Issues: https://github.com/costgov/costgov/issues
• Email: [email protected]