npm package: @split-router/splitrouter-sdk
Description: JavaScript SDK for SplitRouter AI API Gateway
Author: SplitRouter
Latest version: 1.0.4

# SplitRouter JavaScript SDK

A comprehensive JavaScript SDK for the SplitRouter AI API Gateway. SplitRouter provides a unified interface to multiple AI providers (OpenAI, Anthropic Claude, Google Gemini, and DeepSeek) with advanced features like cost tracking, credit management, and analytics.

## Features

- 🚀 **Multi-Provider Support**: Access OpenAI, Anthropic, Gemini, and DeepSeek through a single API
- 🔄 **Smart Routing**: Automatic model selection based on request characteristics
- 💰 **Cost Tracking**: Detailed usage and cost analytics
- 🎯 **Credit System**: Flexible credit management for end users
- 🔑 **API Key Management**: Full API key lifecycle management
- 📈 **Project Management**: Organize end users by projects with custom pricing tiers
- 🛡️ **Error Handling**: Comprehensive error handling with detailed error types
- 📝 **TypeScript Support**: Full TypeScript definitions included

## Installation

```bash
npm install @split-router/splitrouter-sdk
```

## Quick Start

```javascript
import SplitRouterClient from '@split-router/splitrouter-sdk';

// Initialize the client
const client = new SplitRouterClient({
  apiKey: 'sk-your-developer-api-key-here', // Must start with 'sk-' for developer keys
   // Optional, defaults to https://test.splitrouter.ai/ for development
});

// Test the connection
const status = await client.testConnection();
console.log('Connection status:', status);

// Create a chat completion
const response = await client.chat.create({
  model: 'gpt-4o',
  messages: [
    { role: 'user', content: 'Hello, how are you?' }
  ]
});

console.log('AI Response:', response.choices[0].message.content);
```

## Configuration

### API Key Format

SplitRouter uses specific API key formats:

- **Developer Keys**: Must start with `sk-` (e.g., `sk-dev-1234567890abcdef...`)
- **End User Keys**: Must start with `pk_` (e.g., `pk_project_user_hash...`)

You can obtain your developer API key from the SplitRouter dashboard. End user keys are generated automatically when you create end users through your projects.

### Client Configuration

```javascript
const client = new SplitRouterClient({
  apiKey: 'your-api-key-here',          // Required: Your SplitRouter API key
  baseURL: 'https://test.splitrouter.ai/', // Optional: API base URL (development default)
  timeout: 30000,                        // Optional: Request timeout in ms
  defaultHeaders: {                      // Optional: Default headers
    'X-Custom-Header': 'value'
  }
});
```

## API Reference

### Chat Completions

Create AI chat completions using various models:

```javascript
// Standard chat completion
const response = await client.chat.create({
  model: 'gpt-4o',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Explain quantum computing' }
  ],
  max_tokens: 1000,
  temperature: 0.7
});

// Smart routing (automatically selects best model)
const smartResponse = await client.chat.createWithSmartRouting({
  messages: [
    { role: 'user', content: 'Write a Python function to sort a list' }
  ]
});

// General AI request (supports both chat and completion)
const generalResponse = await client.chat.createRequest({
  model: 'claude-3-5-sonnet',
  type: 'chat',
  messages: [
    { role: 'user', content: 'Hello!' }
  ]
});
```

### Project Management

Organize your end users into projects with custom pricing tiers:

```javascript
// Create a project
const project = await client.projects.create({
  name: 'My AI App',
  markup_tiers: {
    'basic': 10,     // 10% markup
    'premium': 5,    // 5% markup
    'enterprise': 0  // No markup
  }
});

// List projects
const projects = await client.projects.list({
  status: 'active',
  limit: 50,
  offset: 0
});

// Get specific project
const projectDetails = await client.projects.get(project.id);

// Update project
const updatedProject = await client.projects.update(project.id, {
  name: 'Updated App Name',
  markup_tiers: {
    'basic': 15,
    'premium': 8,
    'enterprise': 2
  }
});

// Delete project
await client.projects.delete(project.id);
```

### End User Management

Manage end users within your projects:

```javascript
// Create an end user
const endUser = await client.endUsers.create({
  project_id: 'project-id',
  developer_user_id: 'user@example.com',
  markup_tier: 'premium'
});

// List end users
const endUsers = await client.endUsers.list({
  project_id: 'project-id',
  status: 'active',
  markup_tier: 'premium',
  search: 'user@example.com',
  limit: 50
});

// Get end user API keys
const keys = await client.endUsers.getKeys(endUser.id);

// Update end user
const updatedUser = await client.endUsers.update(endUser.id, {
  markup_tier: 'enterprise',
  status: 'active'
});

// Suspend end user
await client.endUsers.suspend(endUser.id, 'Policy violation');

// Reactivate end user
await client.endUsers.reactivate(endUser.id);

// Get end user statistics
const stats = await client.endUsers.getStats(endUser.id, { days: 30 });
```

### Credit Management

Handle credit purchases and balance management:

```javascript
// Get your credit balance
const balance = await client.credits.getBalance();

// Get end user credit balance
const userBalance = await client.credits.getEndUserBalance(endUser.id);

// Calculate purchase total
const calculation = await client.credits.calculateTotal({
  end_user_id: endUser.id,
  credit_amount: 100.00
});

// Initiate credit purchase
const purchase = await client.credits.purchase({
  end_user_id: endUser.id,
  credit_amount: 100.00,
  return_url: 'https://yourapp.com/success',
  cancel_url: 'https://yourapp.com/cancel'
});

// Redirect user to purchase.checkout_url

// Get transaction history
const transactions = await client.credits.getTransactions({
  end_user_id: endUser.id,
  type: 'purchase',
  limit: 50
});

// Transfer credits (admin only)
await client.credits.transfer({
  from_end_user_id: 'user1',
  to_end_user_id: 'user2',
  amount: 50.00,
  reason: 'Refund processing'
});

// Add bonus credits (admin only)
await client.credits.addBonus({
  end_user_id: endUser.id,
  amount: 25.00,
  reason: 'Welcome bonus'
});
```





### API Key Management

Manage your API keys programmatically:

```javascript
// List API keys
const keys = await client.apiKeys.list({
  status: 'active',
  limit: 50
});

// Create new API key
const newKey = await client.apiKeys.create({
  name: 'Production Key',
  description: 'Key for production environment',
  scopes: ['chat', 'models', 'usage'],
  rate_limits: {
    requests_per_minute: 1000,
    requests_per_day: 50000
  },
  custom_markup: 5,
  expires_at: '2025-12-31T23:59:59Z'
});

// Get key details
const keyDetails = await client.apiKeys.get(newKey.id);

// Update API key
const updatedKey = await client.apiKeys.update(newKey.id, {
  name: 'Updated Production Key',
  custom_markup: 7
});

// Test key validity
const testResult = await client.apiKeys.test(newKey.id);

// Update rate limits
await client.apiKeys.updateRateLimits(newKey.id, {
  requests_per_minute: 2000,
  tokens_per_minute: 100000
});

// Revoke API key
await client.apiKeys.revoke(newKey.id, 'Security breach');

// Regenerate API key
const regenerated = await client.apiKeys.regenerate(newKey.id);
```



## Error Handling

The SDK provides comprehensive error handling with specific error types:

```javascript
import { SplitRouterError, APIError, AuthenticationError, ValidationError } from '@split-router/splitrouter-sdk';

try {
  const response = await client.chat.create({
    model: 'invalid-model',
    messages: []
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Authentication failed:', error.message);
    // Handle auth error (redirect to login, refresh token, etc.)
  } else if (error instanceof ValidationError) {
    console.error('Validation error:', error.message);
    console.error('Field:', error.field);
    // Handle validation error (show user feedback, fix input, etc.)
  } else if (error instanceof APIError) {
    console.error('API error:', error.message);
    console.error('Status:', error.status);
    console.error('Code:', error.code);
    // Handle API error (retry, fallback, etc.)
  } else if (error instanceof SplitRouterError) {
    console.error('SDK error:', error.message);
    // Handle general SDK error
  } else {
    console.error('Unexpected error:', error);
    // Handle unexpected errors
  }
}
```

## TypeScript Support

The SDK includes full TypeScript definitions:

```typescript
import SplitRouterClient, { ChatCompletionParams, Project, EndUser } from '@split-router/splitrouter-sdk';

const client = new SplitRouterClient({
  apiKey: process.env.SPLITROUTER_API_KEY!
});

// TypeScript will provide full intellisense and type checking
const params: ChatCompletionParams = {
  model: 'gpt-4o',
  messages: [
    { role: 'user', content: 'Hello!' }
  ],
  temperature: 0.7
};

const response = await client.chat.create(params);
```

## Environment Variables

For security, store your API key in environment variables:

```bash
# .env file
SPLITROUTER_API_KEY=your-api-key-here
SPLITROUTER_BASE_URL=https://your-instance.com  # Optional
```

```javascript
// Load from environment
const client = new SplitRouterClient({
  apiKey: process.env.SPLITROUTER_API_KEY,
  baseURL: process.env.SPLITROUTER_BASE_URL
});
```

## Rate Limiting

The SDK handles rate limiting automatically and will throw appropriate errors when limits are exceeded. You can check rate limit status:

```javascript
// Check rate limit status for a specific API key
const rateLimitStatus = await client.apiKeys.getRateLimitStatus('key-id');
console.log('Remaining requests:', rateLimitStatus.remaining_requests);
console.log('Reset time:', rateLimitStatus.reset_time);
```

## Examples

### Complete Chat Application

```javascript
import SplitRouterClient from '@split-router/splitrouter-sdk';

class ChatApp {
  constructor(apiKey) {
    this.client = new SplitRouterClient({ apiKey });
    this.conversation = [];
  }

  async sendMessage(message) {
    try {
      // Add user message to conversation
      this.conversation.push({ role: 'user', content: message });

      // Get AI response with smart routing
      const response = await this.client.chat.createWithSmartRouting({
        messages: this.conversation,
        temperature: 0.7
      });

      // Add AI response to conversation
      const aiMessage = response.choices[0].message;
      this.conversation.push(aiMessage);

      return aiMessage.content;
    } catch (error) {
      console.error('Chat error:', error);
      throw error;
    }
  }

  async getCreditBalance() {
    return await this.client.credits.getBalance();
  }
}

// Usage
const app = new ChatApp('your-api-key');
const response = await app.sendMessage('Hello, how are you?');
console.log('AI:', response);
```

### Multi-Tenant SaaS Application

```javascript
class SaaSPlatform {
  constructor(apiKey) {
    this.client = new SplitRouterClient({ apiKey });
  }

  async onboardCustomer(customerData) {
    // Create project for the customer
    const project = await this.client.projects.create({
      name: customerData.companyName,
      markup_tiers: {
        'starter': 20,    // 20% markup for starter plan
        'professional': 10, // 10% markup for pro plan
        'enterprise': 5   // 5% markup for enterprise
      }
    });

    // Create end user
    const endUser = await this.client.endUsers.create({
      project_id: project.id,
      developer_user_id: customerData.email,
      markup_tier: customerData.plan // 'starter', 'professional', or 'enterprise'
    });

    // Get API keys for the end user
    const keys = await this.client.endUsers.getKeys(endUser.id);

    return {
      project,
      endUser,
      apiKey: keys.provisional_key
    };
  }

  async getCustomerInfo(projectId) {
    // Get basic project and user information
    const project = await this.client.projects.get(projectId);
    const endUsers = await this.client.endUsers.list({ project_id: projectId });

    return { project, endUsers };
  }
}
```

## Troubleshooting

### Common Issues

#### Insufficient Credits Error
```
Error: Insufficient credits
Details: { required: 0.000243, available: 0, message: 'You need at least $0.0002 credits...' }
```
**Solution**: Add credits to your SplitRouter account through the dashboard or purchase credits programmatically using the SDK's credit management features.

#### Invalid API Key Format
```
Error: Invalid API key format
```
**Solution**: Ensure your API key starts with `sk-` for developer keys or `pk_` for end-user keys.

#### Network Error / Connection Failed
```
Error: Network error: No response received
```
**Solution**: 
- Check if the SplitRouter API is running
- Verify the `baseURL` configuration
- For development, ensure the server is running on the correct port



### Environment Setup

For development, create a `.env` file:
```
SPLITROUTER_API_KEY=sk-your-developer-key-here
SPLITROUTER_BASE_URL=https://test.splitrouter.ai/
```

## 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

- 📧 Email: support@splitrouter.ai
- 📖 Documentation: [https://docs.splitrouter.com](https://docs.splitrouter.ai)
- 🐛 Issues: [GitHub Issues](https://github.com/ZeitbyteRepo/split-router-sdk)

## Changelog

### v1.0.0
- Initial release
- Full API coverage for SplitRouter
- TypeScript support
- Comprehensive error handling
- Complete documentation and examples