@codetunezstudios/token-kit

Beta — This SDK is under active development. APIs may change before 1.0.

Official TypeScript/JavaScript SDK for token-kit — the AI token infrastructure platform for developers.

token-kit enables developers to integrate LLM features into their applications using an end-user-funded token model. Users purchase tokens, developers consume them for AI operations.

Features

• Simple API — Intuitive methods for chat completions
• TypeScript First — Full type safety and IntelliSense support
• Multiple Models — Support for Claude, GPT-4o, Amazon Nova (more coming)
• Token Management — Built-in balance checking and validation
• Error Handling — Comprehensive typed error classes
• Lightweight — Single runtime dependency (axios)

Installation

npm install @codetunezstudios/token-kit

yarn add @codetunezstudios/token-kit

pnpm add @codetunezstudios/token-kit

Quick Start

import TokenKit from '@codetunezstudios/token-kit';

// Initialize with your developer API key
const tk = new TokenKit({
  apiKey: process.env.TOKENKIT_API_KEY!,
});

// Make a chat request
const res = await tk.chat('user_token_here', [
  TokenKit.user('What is token-kit?'),
]);

console.log(res.message.content);
console.log('Tokens used:', res.tokensDeducted);
console.log('Balance:', res.userBalance);

API Reference

Constructor

const tk = new TokenKit(config);

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | apiKey | string | Yes | — | Developer API key | | baseUrl | string | No | https://api.token-kit.com/api/v1 | API base URL | | timeout | number | No | 60000 | Request timeout (ms) |

Methods

tk.chat(userToken, messages, options?)

Send a chat completion request.

const res = await tk.chat('user_token', [
  TokenKit.system('You are a helpful assistant.'),
  TokenKit.user('Explain quantum computing simply.'),
], {
  model: 'gpt-4o',
  maxTokens: 200,
  temperature: 0.8,
});

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | model | string | gpt-4o-mini | LLM model to use | | maxTokens | number | 500 | Max tokens in response | | temperature | number | 0.7 | Randomness (0–2) |

Returns ChatResponse:

{
  id: string;
  model: string;
  message: { role: 'assistant'; content: string };
  tokensUsed: { prompt: number; completion: number; total: number };
  tokensDeducted: number;
  finishReason: string;
  userBalance?: number;
  latency?: number;
}

tk.setUserToken(userToken)

Set the user token for subsequent requests so you don't have to pass it each time.

tk.setUserToken('user_token');

// Now you can omit the userToken parameter
const res = await tk.chat([TokenKit.user('Hello!')]);

tk.validateToken(userToken?)

Validate a user token and check balance/limits.

const info = await tk.validateToken('user_token');
if (info.valid) {
  console.log('Balance:', info.balance);
}

tk.getBalance(userToken?)

Get the current token balance.

const balance = await tk.getBalance('user_token');

tk.getModels()

List available LLM models.

const models = await tk.getModels();
// ['gpt-4o-mini', 'gpt-4o', 'claude-3.5-haiku', 'claude-sonnet-4', 'nova-micro', 'nova-lite']

Helper Methods

TokenKit.user('message')       // { role: 'user', content: 'message' }
TokenKit.system('message')     // { role: 'system', content: 'message' }
TokenKit.assistant('message')  // { role: 'assistant', content: 'message' }

Error Handling

import TokenKit, { TokenKitAPIError } from '@codetunezstudios/token-kit';

try {
  const res = await tk.chat(userToken, messages);
} catch (err) {
  if (err instanceof TokenKitAPIError) {
    console.error(err.code);       // 'INSUFFICIENT_BALANCE'
    console.error(err.statusCode); // 402
    console.error(err.message);    // 'Insufficient token balance'
  }
}

Error codes:

| Code | Status | Description | |------|--------|-------------| | INVALID_API_KEY | 401 | Developer API key is invalid | | INVALID_TOKEN | 401 | User token is invalid or expired | | INSUFFICIENT_BALANCE | 402 | Not enough tokens | | RATE_LIMIT_EXCEEDED | 429 | Too many requests | | DAILY_LIMIT_EXCEEDED | 429 | Daily spending limit reached | | MONTHLY_LIMIT_EXCEEDED | 429 | Monthly spending limit reached | | MODEL_NOT_SUPPORTED | 400 | Requested model is not available | | TIMEOUT | 504 | Request timed out | | NETWORK_ERROR | 503 | Cannot reach token-kit API |

Express Integration Example

import express from 'express';
import TokenKit from '@codetunezstudios/token-kit';

const app = express();
const tk = new TokenKit({ apiKey: process.env.TOKENKIT_API_KEY! });

app.post('/api/chat', async (req, res) => {
  try {
    const { userToken, message } = req.body;
    const result = await tk.chat(userToken, [TokenKit.user(message)]);
    res.json({ reply: result.message.content, balance: result.userBalance });
  } catch (err) {
    res.status(500).json({ error: 'Chat failed' });
  }
});

Security: Never expose your developer API key in client-side code. Always proxy requests through your backend.

Token Pricing

Different models consume tokens at different rates:

| Model | Rate | 1,000 TK tokens = | |-------|------|-------------------| | GPT-4o Mini | 1.0x | 1,000 LLM tokens | | Claude 3.5 Haiku | 1.0x | 1,000 LLM tokens | | Amazon Nova Micro | 1.0x | 1,000 LLM tokens | | Amazon Nova Lite | 1.0x | 1,000 LLM tokens | | GPT-4o | 2.0x | 500 LLM tokens | | Claude Sonnet 4 | 3.0x | 333 LLM tokens |

See token-kit.com for current package pricing and details.

Requirements

• Node.js >= 18
• TypeScript >= 5.0 (recommended)

Development

git clone https://github.com/codetunez-studios/token-kit.git
cd token-kit
npm install     # Install dependencies
npm run build   # Build (CJS + ESM + types)
npm test        # Run tests
npm run typecheck  # Type checking

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

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

License

MIT © Codetunez Studios

Links

• token-kit Platform
• User Token Portal
• Documentation
• npm Package
• GitHub Issues