@tchavi/sdk 0.1.1

package/README.md

@@ -0,0 +1,247 @@
+# @tchavi/sdk
+
+Official Node.js SDK for the [Tchavi](https://tchavi.io) AI API gateway — use OpenAI-compatible models with credit-based billing, without managing provider keys yourself.
+
+[![npm version](https://img.shields.io/npm/v/@tchavi/sdk)](https://www.npmjs.com/package/@tchavi/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Requirements
+
+- Node.js **20+** (uses native `fetch` and `ReadableStream`)
+- TypeScript **5+** (optional but recommended)
+
+## Installation
+
+```bash
+npm install @tchavi/sdk
+# or
+pnpm add @tchavi/sdk
+# or
+yarn add @tchavi/sdk
+```
+
+## Quick start
+
+```ts
+import Tchavi from '@tchavi/sdk';
+
+const client = new Tchavi({ apiKey: 'sk-tch-...' });
+
+const response = await client.chat.completions.create({
+  model: 'gpt-4o-mini',
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+
+console.log(response.choices[0].message.content);
+console.log('Credits used:', response.tchavi.credits_used);
+```
+
+Get your API key from the [Tchavi dashboard](https://app.tchavi.io).
+
+---
+
+## Chat completions
+
+### Non-streaming
+
+```ts
+const completion = await client.chat.completions.create({
+  model: 'gpt-4o-mini',
+  messages: [
+    { role: 'system', content: 'You are a helpful assistant.' },
+    { role: 'user', content: 'What is the capital of France?' },
+  ],
+  temperature: 0.7,
+  max_tokens: 256,
+});
+
+console.log(completion.choices[0].message.content);
+// Credit metadata appended by Tchavi:
+console.log(completion.tchavi.credits_used);
+console.log(completion.tchavi.credits_remaining);
+```
+
+### Streaming
+
+```ts
+const stream = await client.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [{ role: 'user', content: 'Tell me a story.' }],
+  stream: true,
+});
+
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
+}
+
+// Credit metadata available after iteration completes:
+const meta = stream.finalMeta();
+console.log('\nCredits used:', meta?.credits_used);
+```
+
+---
+
+## Embeddings
+
+```ts
+const result = await client.embeddings.create({
+  model: 'text-embedding-3-small',
+  input: 'The quick brown fox jumps over the lazy dog',
+});
+
+console.log(result.data[0].embedding); // number[]
+```
+
+---
+
+## Image generation
+
+```ts
+const result = await client.images.generations.create({
+  prompt: 'A futuristic city skyline at sunset',
+  model: 'dall-e-3',
+  n: 1,
+  size: '1024x1024',
+});
+
+console.log(result.data[0].url);
+```
+
+---
+
+## Error handling
+
+```ts
+import Tchavi, {
+  TchaviAuthenticationError,
+  TchaviInsufficientCreditsError,
+  TchaviRateLimitError,
+  TchaviAPIError,
+  TchaviError,
+} from '@tchavi/sdk';
+
+try {
+  const response = await client.chat.completions.create({ ... });
+} catch (err) {
+  if (err instanceof TchaviInsufficientCreditsError) {
+    // 402 — top up credits
+    console.log('Credits remaining:', err.creditsRemaining);
+  } else if (err instanceof TchaviRateLimitError) {
+    // 429 — back off and retry
+    console.log('Retry after (s):', err.retryAfter); // number | null
+  } else if (err instanceof TchaviAuthenticationError) {
+    // 401 — invalid or revoked API key
+    console.log('Check your API key');
+  } else if (err instanceof TchaviAPIError) {
+    // Other HTTP errors
+    console.log(err.statusCode, err.errorCode, err.message);
+  } else if (err instanceof TchaviError) {
+    // Network/timeout errors
+    console.log('Network error:', err.message);
+  }
+}
+```
+
+| Error class | Status | Extra fields |
+|---|---|---|
+| `TchaviError` | — | Base class for all SDK errors |
+| `TchaviAPIError` | any | `statusCode`, `errorCode`, `headers` |
+| `TchaviAuthenticationError` | 401 | — |
+| `TchaviInsufficientCreditsError` | 402 | `creditsRemaining: number` |
+| `TchaviRateLimitError` | 429 | `retryAfter: number \| null` |
+
+---
+
+## Account management
+
+These methods use **JWT auth** — pass `email` and `password` instead of `apiKey`:
+
+```ts
+const client = new Tchavi({
+  email: 'me@example.com',
+  password: 'my-password',
+});
+```
+
+### Credits
+
+```ts
+const { creditsBalance } = await client.credits.getBalance();
+const packs = await client.credits.listPacks(); // available credit packs
+```
+
+### API keys
+
+```ts
+// List all keys
+const keys = await client.apiKeys.list();
+
+// Create a new key (full secret shown only once)
+const { plaintext, ...key } = await client.apiKeys.create({ name: 'Production' });
+console.log('Save this:', plaintext);
+
+// Retrieve / update / delete
+const key = await client.apiKeys.retrieve('key-id');
+await client.apiKeys.update('key-id', { name: 'Renamed', status: 'INACTIVE' });
+await client.apiKeys.delete('key-id');
+```
+
+### Usage
+
+```ts
+const stats = await client.usage.getStats({ period: '30d' });
+const history = await client.usage.getHistory({ page: 1, limit: 20 });
+```
+
+### Payments
+
+```ts
+// Initiate a credit purchase
+const payment = await client.payments.initiate({ packId: 'pack-id', phone: '+22900000000' });
+
+// Check payment status
+const status = await client.payments.getStatus(payment.id);
+
+// Payment history
+const history = await client.payments.getHistory();
+```
+
+### Available models
+
+```ts
+const models = await client.models.list();
+// models[].id — use this as the `model` field in requests
+```
+
+---
+
+## Configuration
+
+```ts
+const client = new Tchavi({
+  // Authentication (one of):
+  apiKey: 'sk-tch-...',         // For proxy endpoints (chat, embeddings, images)
+  email: 'me@example.com',      // For account management endpoints
+  password: 'my-password',      //   (requires email)
+
+  // Optional:
+  baseURL: 'https://tchavi.com',  // Default: http://localhost:3001
+  maxRetries: 2,                     // Retries on 429/502/503. Default: 2
+  timeout: 60_000,                   // Request timeout in ms. Default: 60000
+});
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | — | API key (`sk-tch-...`) for proxy auth |
+| `email` | `string` | — | Email for JWT auth |
+| `password` | `string` | — | Password for JWT auth |
+| `baseURL` | `string` | `http://localhost:3001` | API base URL (set to your production URL in deployed apps) |
+| `maxRetries` | `number` | `2` | Max retries on transient errors |
+| `timeout` | `number` | `60000` | Request timeout (ms) |
+
+---
+
+## License
+
+MIT