@bernierllc/anthropic-client

Type-safe Anthropic Claude API client with automatic rate limiting, retry logic, streaming support, and cost tracking.

Installation

npm install @bernierllc/anthropic-client

Features

• Type-safe API: Full TypeScript support with strict typing
• Multiple Claude Models: Support for Claude 3 Opus, Sonnet, Haiku, and Sonnet 3.5
• Streaming Support: Real-time streaming responses with chunk callbacks
• Rate Limiting: Built-in rate limiting to respect API quotas
• Automatic Retries: Exponential backoff retry logic for failed requests
• Cost Tracking: Automatic tracking of token usage and costs
• Comprehensive Logging: Integration with @bernierllc/logger
• Error Handling: Structured error responses for robust error handling

Usage

Basic Completion

import { AnthropicClient, ClaudeModel } from '@bernierllc/anthropic-client';

const client = new AnthropicClient({
  apiKey: process.env.ANTHROPIC_API_KEY!
});

const result = await client.complete('Explain quantum computing in simple terms', {
  model: ClaudeModel.SONNET,
  maxTokens: 1024,
  temperature: 0.7
});

if (result.success) {
  console.log('Response:', result.content);
  console.log('Tokens used:', result.usage?.totalTokens);
  console.log('Cost:', `$${result.cost?.totalCost.toFixed(6)}`);
} else {
  console.error('Error:', result.error);
}

Streaming Response

const result = await client.stream(
  'Write a short story about space exploration',
  (chunk) => {
    // Process each chunk as it arrives
    process.stdout.write(chunk);
  },
  {
    model: ClaudeModel.OPUS,
    maxTokens: 2000
  }
);

console.log('\n\nTotal tokens:', result.usage?.totalTokens);
console.log('Total cost:', `$${result.cost?.totalCost.toFixed(6)}`);

Custom Configuration

const client = new AnthropicClient({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  defaultModel: ClaudeModel.HAIKU,
  maxRetries: 5,
  rateLimit: {
    requestsPerMinute: 100,
    tokensPerMinute: 50000
  },
  enableLogging: true
});

Disable Rate Limiting

const client = new AnthropicClient({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  rateLimit: null // Disable rate limiting
});

Usage Tracking

// Make multiple requests
await client.complete('First request');
await client.complete('Second request');
await client.complete('Third request');

// Get aggregated usage statistics
const usage = client.getUsage();
console.log('Total requests:', usage.totalRequests);
console.log('Total tokens:', usage.totalTokens);
console.log('Total cost:', `$${usage.totalCost.toFixed(6)}`);
console.log('Requests by model:', usage.requestsByModel);

// Reset usage statistics
client.resetUsage();

Rate Limit Status

const status = client.getRateLimitStatus();

if (status) {
  console.log('Requests remaining:', status.requestsRemaining);
  console.log('Reset time:', status.resetTime);
}

API Reference

AnthropicClient

Constructor

new AnthropicClient(config: AnthropicClientConfig)

Config Options:

• apiKey (string, required): Your Anthropic API key
• defaultModel (ClaudeModel, optional): Default model to use (default: ClaudeModel.SONNET)
• maxRetries (number, optional): Maximum number of retry attempts (default: 3)
• rateLimit (object | null, optional): Rate limiting configuration or null to disable (default: 50 requests/minute)
  • requestsPerMinute (number): Maximum requests per minute
  • tokensPerMinute (number): Maximum tokens per minute (not enforced by current rate limiter)
• enableLogging (boolean, optional): Enable detailed logging (default: true)

Methods

complete(prompt: string, options?: CompletionOptions): Promise

Send a completion request to Claude.

Options:

• model (ClaudeModel): Model to use for this request
• maxTokens (number): Maximum tokens to generate (default: 1024)
• temperature (number): Sampling temperature (0-1)
• topP (number): Nucleus sampling parameter
• topK (number): Top-k sampling parameter
• stopSequences (string[]): Sequences that stop generation
• systemPrompt (string): System prompt to use
• metadata (Record<string, unknown>): Additional metadata

Returns: CompletionResult object with:

• success (boolean): Whether the request succeeded
• content (string | undefined): Generated text
• usage (object | undefined): Token usage information
• cost (object | undefined): Cost breakdown
• model (string | undefined): Model used
• stopReason (string | undefined): Why generation stopped
• error (string | undefined): Error message if failed

stream(prompt: string, onChunk: StreamChunkCallback, options?: CompletionOptions): Promise

Stream a completion response from Claude.

Parameters:

• prompt (string): The prompt to send
• onChunk (function): Callback function called for each text chunk
• options (CompletionOptions): Same options as complete()

Returns: CompletionResult with the complete response

getUsage(): UsageStats

Get cumulative usage statistics.

Returns:

• totalRequests (number): Total number of requests made
• totalInputTokens (number): Total input tokens used
• totalOutputTokens (number): Total output tokens generated
• totalTokens (number): Total tokens (input + output)
• totalCost (number): Total cost in USD
• requestsByModel (Record<string, number>): Request count by model

resetUsage(): void

Reset all usage statistics to zero.

getRateLimitStatus(): RateLimitStatus | null

Get current rate limit status.

Returns:

• requestsRemaining (number): Requests remaining in current window
• tokensRemaining (number): Tokens remaining (not implemented)
• resetTime (Date): When the rate limit window resets

Returns null if rate limiting is disabled.

Claude Models

The following models are supported:

• ClaudeModel.OPUS - claude-3-opus-20240229 (most capable, highest cost)
• ClaudeModel.SONNET - claude-3-sonnet-20240229 (balanced performance and cost)
• ClaudeModel.SONNET_3_5 - claude-3-5-sonnet-20241022 (latest Sonnet version)
• ClaudeModel.HAIKU - claude-3-haiku-20240307 (fastest, lowest cost)

Cost Tracking

The client automatically tracks costs based on current Anthropic pricing:

| Model | Input Cost (per 1M tokens) | Output Cost (per 1M tokens) | |-------|---------------------------|------------------------------| | Opus | $15.00 | $75.00 | | Sonnet | $3.00 | $15.00 | | Sonnet 3.5 | $3.00 | $15.00 | | Haiku | $0.25 | $1.25 |

Error Handling

The client uses structured error responses:

const result = await client.complete('test prompt');

if (!result.success) {
  console.error('Request failed:', result.error);
  // Handle error appropriately
} else {
  // Process successful response
  console.log(result.content);
}

Integration Status

• Logger: ✅ Integrated - Uses @bernierllc/logger for structured logging of API calls, errors, and usage tracking
• Docs-Suite: ✅ Ready - Full TypeDoc documentation with API reference and usage examples
• NeverHub: 🔄 Optional - Supports graceful degradation. When NeverHub is available via @bernierllc/neverhub-adapter, the client can:
  • Emit ai.request.started and ai.request.completed events
  • Publish token usage and cost metrics
  • Subscribe to configuration updates
  • Register as an AI capability provider for service discovery
  • All core functionality works without NeverHub present

NeverHub Integration Example

import { AnthropicClient } from '@bernierllc/anthropic-client';
import { NeverHubAdapter } from '@bernierllc/neverhub-adapter';

const client = new AnthropicClient({
  apiKey: process.env.ANTHROPIC_API_KEY!
});

// Auto-detect and integrate with NeverHub if available
if (await NeverHubAdapter.detect()) {
  const neverhub = new NeverHubAdapter();
  await neverhub.register({
    type: 'ai-provider',
    name: '@bernierllc/anthropic-client',
    version: '1.0.0',
    capabilities: [
      { type: 'ai', name: 'text-completion', version: '1.0.0' },
      { type: 'ai', name: 'streaming', version: '1.0.0' }
    ]
  });

  // Client emits events automatically when integrated
}

// Works identically with or without NeverHub
const result = await client.complete('Your prompt here');

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build
npm run build

# Lint
npm run lint

License

Copyright (c) 2025 Bernier LLC

This file is licensed to the client under a limited-use license. The client may use and modify this code only within the scope of the project it was delivered for. Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.

See Also

• @bernierllc/logger - Structured logging
• @bernierllc/retry-policy - Retry logic with exponential backoff
• Anthropic API Documentation - Official API documentation