npm package: @paygent_org/paygent-sdk-node
Description: A Node.js SDK for integrating with the Paygent API to track usage and costs for AI models
Author: Paygent
Latest version: 4.1.0

# Paygent SDK for Node.js

A comprehensive Node.js SDK for integrating with the Paygent API to track usage and costs for AI models. This SDK provides seamless integration with various AI providers including OpenAI, Anthropic, Google, Meta, AWS, Mistral, Cohere, and DeepSeek.

## Features

- 🚀 **Easy Integration**: Simple API for tracking AI model usage and costs
- 🔢 **Automatic Token Counting**: Built-in token counting using `tiktoken` for accurate cost calculation
- 💰 **Comprehensive Pricing**: Support for 50+ AI models with up-to-date pricing
- 🏷️ **Multi-Provider Support**: OpenAI, Anthropic, Google, Meta, AWS, Mistral, Cohere, DeepSeek
- 📊 **Usage Tracking**: Track usage by agent, customer, and indicator
- 🔧 **Flexible Configuration**: Customizable logging, timeouts, and base URLs
- 📝 **TypeScript Support**: Full TypeScript definitions included
- 🧪 **Well Tested**: Comprehensive test coverage

## Installation

```bash
npm install paygent-sdk-node
```

## Quick Start

### Basic Usage

```typescript
import { PaygentClient } from 'paygent-sdk-node';

// Create a client
const client = PaygentClient.newClient('your-api-key-here');

// Send usage data
await client.sendUsage(
  'agent-123',
  'customer-456',
  'chat-completion',
  {
    serviceProvider: 'OpenAI',
    model: 'gpt-4',
    promptTokens: 100,
    completionTokens: 50,
    totalTokens: 150,
  }
);
```

### Using SendUsageWithTokenString

The SDK can automatically count tokens from prompt and output strings:

```typescript
import { PaygentClient } from 'paygent-sdk-node';

const client = PaygentClient.newClient('your-api-key-here');

// Send usage data with automatic token counting
await client.sendUsageWithTokenString(
  'agent-123',
  'customer-456',
  'chat-completion',
  {
    serviceProvider: 'OpenAI',
    model: 'gpt-4',
    promptString: 'What is the capital of France?',
    outputString: 'The capital of France is Paris.',
  }
);
```

## Advanced Usage

### Custom Configuration

```typescript
import { PaygentClient, LogLevel } from 'paygent-sdk-node';

// Create client with custom options
const client = PaygentClient.newClientWithUrl(
  'your-api-key-here',
  'https://your-custom-api-url.com'
);

// Set debug logging
client.setLogLevel(LogLevel.DEBUG);
```

### Using Model Constants

The SDK provides predefined constants for all supported models and service providers:

```typescript
import { 
  PaygentClient, 
  OpenAIModels, 
  AnthropicModels,
  ServiceProvider,
  isModelSupported
} from 'paygent-sdk-node';

const client = PaygentClient.newClient('your-api-key-here');

// Use model constants
await client.sendUsage(
  'agent-123',
  'customer-456',
  'chat-completion',
  {
    serviceProvider: ServiceProvider.OPENAI,
    model: OpenAIModels.GPT_4O,
    promptTokens: 100,
    completionTokens: 50,
    totalTokens: 150,
  }
);

// Check if a model is supported
if (isModelSupported(OpenAIModels.GPT_5)) {
  console.log('GPT-5 is supported!');
}
```

### Available Model Constants

- **OpenAI**: `OpenAIModels.GPT_5`, `OpenAIModels.GPT_4O`, `OpenAIModels.GPT_4O_MINI`, `OpenAIModels.O1`, `OpenAIModels.O3`, etc.
- **Anthropic**: `AnthropicModels.SONNET_4_5`, `AnthropicModels.HAIKU_4_5`, `AnthropicModels.OPUS_4_1`, etc.
- **Google DeepMind**: `GoogleDeepMindModels.GEMINI_2_5_PRO`, `GoogleDeepMindModels.GEMINI_2_5_FLASH`, etc.
- **Meta**: `MetaModels.LLAMA_4_MAVERICK`, `MetaModels.LLAMA_3_1_405B_INSTRUCT_TURBO`, etc.
- **AWS**: `AWSModels.AMAZON_NOVA_PRO`, `AWSModels.AMAZON_NOVA_LITE`, etc.
- **Mistral AI**: `MistralAIModels.MISTRAL_LARGE`, `MistralAIModels.MISTRAL_MEDIUM`, etc.
- **Cohere**: `CohereModels.COMMAND_R_PLUS`, `CohereModels.COMMAND_R`, etc.
- **DeepSeek**: `DeepSeekModels.DEEPSEEK_R1_GLOBAL`, `DeepSeekModels.DEEPSEEK_REASONER`, etc.

### Multiple Models

```typescript
const models = [
  'gpt-3.5-turbo',
  'gpt-4',
  'claude-3-haiku',
  'claude-3-sonnet',
  'gemini-pro',
  'llama-2-7b',
];

for (const model of models) {
  await client.sendUsage(
    'agent-123',
    'customer-456',
    'multi-model-test',
    {
      model,
      promptTokens: 100,
      completionTokens: 50,
      totalTokens: 150,
    }
  );
}
```

## API Reference

### PaygentClient

#### Constructor

```typescript
new PaygentClient(options: ClientOptions)
```

#### Static Methods

- `PaygentClient.newClient(apiKey: string): PaygentClient`
- `PaygentClient.newClientWithUrl(apiKey: string, baseUrl: string): PaygentClient`

#### Instance Methods

- `sendUsage(agentId: string, customerId: string, indicator: string, usageData: UsageData): Promise<void>`
- `sendUsageWithTokenString(agentId: string, customerId: string, indicator: string, usageData: UsageDataWithStrings): Promise<void>`
- `setLogLevel(level: LogLevel): void`
- `getLogger(): Logger`

### Types

#### UsageData

```typescript
interface UsageData {
  serviceProvider: string;
  model: string;
  promptTokens: number;
  completionTokens: number;
  totalTokens: number;
}
```

#### UsageDataWithStrings

```typescript
interface UsageDataWithStrings {
  serviceProvider: string;
  model: string;
  promptString: string;
  outputString: string;
}
```

#### ClientOptions

```typescript
interface ClientOptions {
  apiKey: string;
  baseUrl?: string;
  timeout?: number;
  logLevel?: LogLevel;
}
```

### Enums

#### LogLevel

```typescript
enum LogLevel {
  DEBUG = 0,
  INFO = 1,
  WARN = 2,
  ERROR = 3,
}
```

## Supported Models

The SDK supports 50+ AI models with accurate pricing:

### OpenAI Models
- `gpt-3.5-turbo`, `gpt-3.5-turbo-16k`
- `gpt-4`, `gpt-4-turbo`, `gpt-4o`, `gpt-4o-mini`
- `gpt-5`

### Anthropic Models
- `claude-3-haiku`, `claude-3-sonnet`, `claude-3-opus`
- `claude-3.5-sonnet`

### Google DeepMind Models
- `gemini-pro`, `gemini-pro-vision`
- `gemini-1.5-pro`, `gemini-1.5-flash`

### Meta Llama Models
- `llama-2-7b`, `llama-2-13b`, `llama-2-70b`
- `llama-3-8b`, `llama-3-70b`

### AWS Models
- `claude-3-haiku-aws`, `claude-3-sonnet-aws`
- `titan-text-express`, `titan-text-lite`

### Mistral AI Models
- `mistral-7b`, `mistral-8x7b`, `mistral-nemo`, `mistral-large`

### Cohere Models
- `command`, `command-light`, `command-r`, `command-r-plus`

### DeepSeek Models
- `deepseek-chat`, `deepseek-coder`

## Token Counting

The SDK uses `tiktoken` for accurate token counting:

- **OpenAI GPT models**: Uses model-specific encodings
- **Anthropic Claude models**: Uses `cl100k_base` encoding
- **Google Gemini models**: Uses `cl100k_base` encoding
- **Meta Llama models**: Uses `cl100k_base` encoding
- **Other models**: Falls back to `cl100k_base` encoding
- **Fallback**: Word-based estimation (1.3 tokens per word)

## Error Handling

```typescript
try {
  await client.sendUsage('agent-123', 'customer-456', 'chat', usageData);
} catch (error) {
  if (error.statusCode) {
    console.error(`API Error ${error.statusCode}: ${error.message}`);
    console.error(`Response: ${error.responseBody}`);
  } else {
    console.error(`Network Error: ${error.message}`);
  }
}
```

## Examples

See the `examples/` directory for complete usage examples:

- `basic-usage.js` - Basic JavaScript usage
- `basic-usage.ts` - Basic TypeScript usage
- `advanced-usage.js` - Advanced JavaScript features
- `advanced-usage.ts` - Advanced TypeScript features

## Development

### Building

```bash
npm run build
```

### Testing

```bash
npm test
```

### Linting

```bash
npm run lint
```

### Development Mode

```bash
npm run dev
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

For support, email support@paygent.com or join our Slack channel.

## Changelog

### 1.0.0
- Initial release
- Support for 50+ AI models
- Automatic token counting
- TypeScript support
- Comprehensive pricing
- Multi-provider support