@codetunezstudios/token-kit 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Codetunez Studios
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,258 @@
+# @codetunezstudios/token-kit
+
+[![npm version](https://img.shields.io/npm/v/@codetunezstudios/token-kit.svg)](https://www.npmjs.com/package/@codetunezstudios/token-kit)
+[![license](https://img.shields.io/npm/l/@codetunezstudios/token-kit.svg)](https://github.com/codetunez-studios/token-kit/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green)](https://nodejs.org/)
+
+> **Beta** — This SDK is under active development. APIs may change before 1.0.
+
+Official TypeScript/JavaScript SDK for [token-kit](https://token-kit.com) — 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 GPT-3.5, GPT-4, GPT-4 Turbo (more coming)
+- **Token Management** — Built-in balance checking and validation
+- **Error Handling** — Comprehensive typed error classes
+- **Lightweight** — Single runtime dependency (axios)
+
+## Installation
+
+```bash
+npm install @codetunezstudios/token-kit
+```
+
+```bash
+yarn add @codetunezstudios/token-kit
+```
+
+```bash
+pnpm add @codetunezstudios/token-kit
+```
+
+## Quick Start
+
+```typescript
+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
+
+```typescript
+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.
+
+```typescript
+const res = await tk.chat('user_token', [
+  TokenKit.system('You are a helpful assistant.'),
+  TokenKit.user('Explain quantum computing simply.'),
+], {
+  model: 'gpt-4',
+  maxTokens: 200,
+  temperature: 0.8,
+});
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `model` | `string` | `gpt-3.5-turbo` | LLM model to use |
+| `maxTokens` | `number` | `500` | Max tokens in response |
+| `temperature` | `number` | `0.7` | Randomness (0–2) |
+
+**Returns** `ChatResponse`:
+
+```typescript
+{
+  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.
+
+```typescript
+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.
+
+```typescript
+const info = await tk.validateToken('user_token');
+if (info.valid) {
+  console.log('Balance:', info.balance);
+}
+```
+
+#### `tk.getBalance(userToken?)`
+
+Get the current token balance.
+
+```typescript
+const balance = await tk.getBalance('user_token');
+```
+
+#### `tk.getModels()`
+
+List available LLM models.
+
+```typescript
+const models = await tk.getModels();
+// ['gpt-3.5-turbo', 'gpt-4', 'gpt-4-turbo']
+```
+
+### Helper Methods
+
+```typescript
+TokenKit.user('message')       // { role: 'user', content: 'message' }
+TokenKit.system('message')     // { role: 'system', content: 'message' }
+TokenKit.assistant('message')  // { role: 'assistant', content: 'message' }
+```
+
+## Error Handling
+
+```typescript
+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
+
+```typescript
+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-3.5 Turbo | 1.0x | 1,000 LLM tokens |
+| GPT-4 Turbo | 2.0x | 500 LLM tokens |
+| GPT-4 | 3.0x | 333 LLM tokens |
+
+See [token-kit.com](https://token-kit.com) for current package pricing and details.
+
+## Requirements
+
+- Node.js >= 18
+- TypeScript >= 5.0 (recommended)
+
+## Development
+
+```bash
+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](LICENSE) © [Codetunez Studios](https://github.com/codetunez-studios)
+
+## Links
+
+- [token-kit Platform](https://token-kit.com)
+- [User Token Portal](https://ai-tokens.me)
+- [Documentation](https://token-kit.com/sdk)
+- [npm Package](https://www.npmjs.com/package/@codetunezstudios/token-kit)
+- [GitHub Issues](https://github.com/codetunez-studios/token-kit/issues)

package/dist/index.d.mts

@@ -0,0 +1,232 @@
+/**
+ * Token-Kit SDK - Type Definitions
+ * TypeScript types for the Token-Kit SDK
+ */
+type MessageRole = 'system' | 'user' | 'assistant';
+interface Message {
+    role: MessageRole;
+    content: string;
+}
+interface ChatOptions {
+    /** LLM model to use (default: 'gpt-3.5-turbo') */
+    model?: string;
+    /** Maximum tokens in response (default: 500) */
+    maxTokens?: number;
+    /** Temperature for response randomness 0-2 (default: 0.7) */
+    temperature?: number;
+}
+interface ChatResponse {
+    /** Unique chat completion ID */
+    id: string;
+    /** Model used for completion */
+    model: string;
+    /** Assistant's response message */
+    message: Message;
+    /** Token usage statistics */
+    tokensUsed: {
+        prompt: number;
+        completion: number;
+        total: number;
+    };
+    /** Number of tokens deducted from user balance */
+    tokensDeducted: number;
+    /** Reason completion finished */
+    finishReason: string;
+    /** User's remaining token balance */
+    userBalance?: number;
+    /** Response latency in milliseconds */
+    latency?: number;
+}
+interface TokenValidationResponse {
+    /** Whether the token is valid */
+    valid: boolean;
+    /** User information */
+    user?: {
+        id: string;
+        email: string;
+    };
+    /** Current token balance */
+    balance?: number;
+    /** Daily spending so far */
+    dailySpending?: number;
+    /** Monthly spending so far */
+    monthlySpending?: number;
+    /** Spending limits */
+    limits?: {
+        dailyLimit: number;
+        monthlyLimit: number;
+        perRequestLimit: number;
+    };
+}
+interface ModelInfo {
+    /** Model identifier */
+    name: string;
+    /** Human-readable model name */
+    displayName: string;
+    /** Token rate multiplier */
+    tokenRate: number;
+    /** Default max tokens */
+    defaultMaxTokens: number;
+}
+interface ModelsResponse {
+    models: string[];
+    count: number;
+}
+interface TokenKitError extends Error {
+    /** Error code */
+    code: string;
+    /** HTTP status code */
+    statusCode?: number;
+    /** Additional error details */
+    details?: unknown;
+}
+declare class TokenKitAPIError extends Error implements TokenKitError {
+    code: string;
+    statusCode?: number;
+    details?: unknown;
+    constructor(message: string, code: string, statusCode?: number, details?: unknown);
+}
+interface TokenKitConfig {
+    /** Developer API key */
+    apiKey: string;
+    /** API Gateway base URL (default: https://api.token-kit.com) */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 60000) */
+    timeout?: number;
+}
+
+/**
+ * Token-Kit SDK - Main Entry Point
+ * Official TypeScript SDK for Token-Kit platform
+ */
+
+/**
+ * TokenKit - Main SDK class
+ *
+ * Example usage:
+ * ```typescript
+ * const tokenKit = new TokenKit({ apiKey: 'your-api-key' });
+ *
+ * const response = await tokenKit.chat('user-token', [
+ *   { role: 'user', content: 'Hello!' }
+ * ]);
+ *
+ * console.log(response.message.content);
+ * ```
+ */
+declare class TokenKit {
+    private client;
+    private userToken;
+    /**
+     * Create a new TokenKit instance
+     *
+     * @param config - Configuration options
+     * @param config.apiKey - Your developer API key
+     * @param config.baseUrl - API base URL (optional, defaults to production)
+     * @param config.timeout - Request timeout in ms (optional, defaults to 60000)
+     */
+    constructor(config: TokenKitConfig);
+    /**
+     * Set the user token for subsequent requests
+     * This allows you to omit the userToken parameter in other methods
+     *
+     * @param userToken - The user's token
+     */
+    setUserToken(userToken: string): void;
+    /**
+     * Send a chat completion request
+     *
+     * @param userTokenOrMessages - User token string OR array of messages (if user token was set)
+     * @param messagesOrOptions - Array of messages OR chat options (if first param is user token)
+     * @param options - Chat options (only if first two params are provided)
+     * @returns Chat completion response
+     *
+     * @example
+     * ```typescript
+     * // With explicit user token
+     * const response = await tokenKit.chat('user-token', [
+     *   { role: 'user', content: 'What is Token-Kit?' }
+     * ]);
+     *
+     * // With pre-set user token
+     * tokenKit.setUserToken('user-token');
+     * const response = await tokenKit.chat([
+     *   { role: 'user', content: 'What is Token-Kit?' }
+     * ]);
+     *
+     * // With options
+     * const response = await tokenKit.chat('user-token', [
+     *   { role: 'system', content: 'You are a helpful assistant.' },
+     *   { role: 'user', content: 'Hello!' }
+     * ], {
+     *   model: 'gpt-4',
+     *   maxTokens: 200,
+     *   temperature: 0.8
+     * });
+     * ```
+     */
+    chat(userTokenOrMessages: string | Message[], messagesOrOptions?: Message[] | ChatOptions, options?: ChatOptions): Promise<ChatResponse>;
+    /**
+     * Validate a user token and check balance
+     *
+     * @param userToken - User token to validate (optional if already set)
+     * @returns Token validation response with balance and limits
+     *
+     * @example
+     * ```typescript
+     * const validation = await tokenKit.validateToken('user-token');
+     * console.log('Balance:', validation.balance);
+     * console.log('Daily spending:', validation.dailySpending);
+     * ```
+     */
+    validateToken(userToken?: string): Promise<TokenValidationResponse>;
+    /**
+     * Get balance for the current user token
+     *
+     * @param userToken - User token (optional if already set)
+     * @returns Current token balance
+     *
+     * @example
+     * ```typescript
+     * const balance = await tokenKit.getBalance('user-token');
+     * console.log(`You have ${balance} tokens remaining`);
+     * ```
+     */
+    getBalance(userToken?: string): Promise<number>;
+    /**
+     * Get list of available LLM models
+     *
+     * @returns Array of model names
+     *
+     * @example
+     * ```typescript
+     * const models = await tokenKit.getModels();
+     * console.log('Available models:', models);
+     * // ['gpt-3.5-turbo', 'gpt-4', 'gpt-4-turbo']
+     * ```
+     */
+    getModels(): Promise<string[]>;
+    /**
+     * Helper method to create a simple user message
+     *
+     * @param content - Message content
+     * @returns Message object
+     */
+    static user(content: string): Message;
+    /**
+     * Helper method to create a system message
+     *
+     * @param content - Message content
+     * @returns Message object
+     */
+    static system(content: string): Message;
+    /**
+     * Helper method to create an assistant message
+     *
+     * @param content - Message content
+     * @returns Message object
+     */
+    static assistant(content: string): Message;
+}
+
+export { type ChatOptions, type ChatResponse, type Message, type MessageRole, type ModelInfo, type ModelsResponse, TokenKit, TokenKitAPIError, type TokenKitConfig, type TokenValidationResponse, TokenKit as default };