{"_id":"@aiaggregator/sdk","name":"@aiaggregator/sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aiaggregator/sdk","version":"0.1.0","description":"JavaScript SDK for AI Aggregator async API","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","publishConfig":{"access":"public"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest","test:run":"vitest run","lint":"eslint src","typecheck":"tsc --noEmit","prepublishOnly":"pnpm build"},"keywords":["ai","openai","claude","llm","aggregator","sdk"],"author":"","license":"MIT","devDependencies":{"@types/node":"^20.10.0","eslint":"^8.55.0","tsup":"^8.0.1","typescript":"^5.3.0","vitest":"^1.0.0"},"engines":{"node":">=18.0.0"},"gitHead":"b5f8bf068c8cbdfad12f2501719ace2c94bc4c12","_id":"@aiaggregator/sdk@0.1.0","_nodeVersion":"24.10.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-u2O24pApzv8en3r8HK3dePZLcIS8vtE/QCkoEx6fqA9Y+i4Ew8rV22WhYpMqDNjeCiCCeTK+J3NaTCJmUBQwzA==","shasum":"8e12343b92f561943f112bcb93cbc6fe92759b0c","tarball":"https://registry.npmjs.org/@aiaggregator/sdk/-/sdk-0.1.0.tgz","fileCount":8,"unpackedSize":130275,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDozhEM61kCPjYxh7zsle9ZAl01hKOeHnNvPuzibS2faAiEA7JkeQs4W411KRHEWJuYD39w7gI+SQuqNe6QNILmyJOE="}]},"_npmUser":{"name":"supostat","email":"ipugachev84@gmail.com"},"directories":{},"maintainers":[{"name":"supostat","email":"ipugachev84@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.0_1767009212345_0.1680853287669617"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-29T11:53:32.275Z","0.1.0":"2025-12-29T11:53:32.497Z","modified":"2025-12-29T11:53:32.789Z"},"maintainers":[{"name":"supostat","email":"ipugachev84@gmail.com"}],"description":"JavaScript SDK for AI Aggregator async API","keywords":["ai","openai","claude","llm","aggregator","sdk"],"license":"MIT","readme":"# @aiaggregator/sdk\n\nJavaScript/TypeScript SDK for AI Aggregator async API.\n\n## Features\n\n- 🚀 **Async job-based API** — no timeout issues with long-running requests\n- 📡 **SSE support** — real-time updates via Server-Sent Events\n- 🔄 **Automatic retry** — exponential backoff for transient failures\n- ⏹️ **Cancellation** — abort any request with `AbortController`\n- 🔧 **Tool/function calling** — OpenAI and Claude compatible\n- 📦 **Zero dependencies** — uses native `fetch`\n\n## Installation\n\n```bash\nnpm install @aiaggregator/sdk\n# or\npnpm add @aiaggregator/sdk\n# or\nyarn add @aiaggregator/sdk\n```\n\n## Quick Start\n\n```typescript\nimport { AIAggregator } from '@aiaggregator/sdk'\n\nconst client = new AIAggregator({\n  baseUrl: 'https://api.example.com',\n  apiKey: 'your-api-key',\n})\n\n// Simple chat - returns Promise that resolves when job completes\nconst result = await client.chat({\n  messages: [{ role: 'user', content: 'Hello!' }],\n  provider: 'openai',\n  model: 'gpt-4o-mini',\n})\n\nconsole.log(result.content)\nconsole.log(result.usage) // { tokensIn: 10, tokensOut: 20, cost: 0.001 }\n```\n\n## How It Works\n\nThe SDK uses an async job-based API:\n\n1. **`client.chat()`** sends request to `/api/chat`\n2. The server creates a job and returns `{ jobId, status }`\n3. SDK uses SSE (or polls) `/api/chat/{jobId}/events` for updates\n4. When job completes, the Promise resolves with the result\n\nThis approach allows for:\n- Long-running AI requests without timeout issues\n- Real-time status updates via SSE\n- Job tracking and cancellation\n- Better resource management on the server\n\n## Usage\n\n### Basic Chat\n\n```typescript\nconst result = await client.chat({\n  prompt: 'Write a haiku about programming',\n  provider: 'claude',\n  model: 'claude-3-haiku-20240307',\n  maxTokens: 100,\n})\n\nconsole.log(result.content)\n```\n\n### Async Chat (Non-blocking)\n\n```typescript\n// Create job without waiting\nconst { jobId, status } = await client.chatAsync({\n  messages: [{ role: 'user', content: 'Hello!' }],\n})\n\nconsole.log(`Job created: ${jobId}`) // Immediately available\n\n// Do other work...\n\n// Later: wait for result\nconst result = await client.waitForJob(jobId)\nconsole.log(result.content)\n```\n\n### With Cancellation\n\n```typescript\nconst controller = new AbortController()\n\n// Cancel after 10 seconds\nsetTimeout(() => controller.abort(), 10000)\n\ntry {\n  const result = await client.chat(\n    { prompt: 'Write a long essay...' },\n    controller.signal\n  )\n} catch (error) {\n  if (error.code === 'aborted') {\n    console.log('Request was cancelled')\n  }\n}\n```\n\n### Check Job Status\n\n```typescript\nconst job = await client.getJobStatus(jobId)\n\nconsole.log(job.status) // 'pending' | 'processing' | 'completed' | 'failed'\nconsole.log(job.output) // Result when completed\n```\n\n### Cancel Job\n\n```typescript\nawait client.cancelJob(jobId)\n```\n\n### With Tools/Functions\n\n```typescript\nconst result = await client.chat({\n  messages: [{ role: 'user', content: \"What's the weather in Paris?\" }],\n  tools: [\n    {\n      type: 'function',\n      function: {\n        name: 'get_weather',\n        description: 'Get weather for a location',\n        parameters: {\n          type: 'object',\n          properties: {\n            location: { type: 'string', description: 'City name' },\n          },\n          required: ['location'],\n        },\n      },\n    },\n  ],\n  toolChoice: 'auto',\n})\n\nif (result.toolCalls) {\n  for (const call of result.toolCalls) {\n    console.log(call.function.name) // 'get_weather'\n    console.log(call.function.arguments) // '{\"location\": \"Paris\"}'\n  }\n}\n```\n\n## Configuration\n\n```typescript\nimport { AIAggregator } from '@aiaggregator/sdk'\n\nconst client = new AIAggregator({\n  // Required\n  baseUrl: 'https://api.example.com',\n  apiKey: 'your-api-key',\n\n  // Optional\n  defaultProvider: 'openai',      // Default provider for requests\n  defaultModel: 'gpt-4o-mini',    // Default model\n  timeout: 300000,                // Request timeout (ms) - default 5 min\n  pollingInterval: 1000,          // Job polling interval (ms)\n  maxPollingAttempts: 300,        // Max polling attempts (5 min default)\n  useSSE: 'auto',                 // SSE mode: 'auto' | true | false\n})\n```\n\n### SSE Configuration\n\n| Value | Behavior |\n|-------|----------|\n| `'auto'` (default) | Use SSE if `fetch` is available (Node.js 18+ or browser) |\n| `true` | Always use SSE |\n| `false` | Always use polling |\n\n## Error Handling\n\n```typescript\nimport { AIAggregatorError, ERROR_CODES } from '@aiaggregator/sdk'\n\ntry {\n  const result = await client.chat({ prompt: 'Hello' })\n} catch (error) {\n  if (error instanceof AIAggregatorError) {\n    console.error('Code:', error.code)\n    console.error('Message:', error.message)\n    console.error('Status:', error.status)  // HTTP status if applicable\n    console.error('Details:', error.details)\n\n    // Handle specific errors\n    switch (error.code) {\n      case ERROR_CODES.TIMEOUT:\n        console.log('Request timed out')\n        break\n      case ERROR_CODES.JOB_FAILED:\n        console.log('Job failed:', error.details)\n        break\n      case ERROR_CODES.ABORTED:\n        console.log('Request was cancelled')\n        break\n    }\n  }\n}\n```\n\n### Error Codes\n\n| Code | Description |\n|------|-------------|\n| `timeout` | Request or polling timeout exceeded |\n| `job_failed` | Job failed on the server |\n| `request_failed` | HTTP request failed |\n| `network_error` | Network connection error |\n| `sse_failed` | SSE connection failed |\n| `validation_error` | Invalid input parameters |\n| `aborted` | Request was cancelled via AbortSignal |\n\n## Types\n\nAll types are exported for TypeScript users:\n\n```typescript\nimport type {\n  SDKConfig,\n  ChatResult,\n  ChatResponse,\n  CreateChatRequest,\n  Job,\n  JobStatus,\n  JobType,\n  ChatMessage,\n  MessageRole,\n  Tool,\n  ToolFunction,\n  ToolCall,\n} from '@aiaggregator/sdk'\n\n// Constants\nimport { DEFAULT_CONFIG, ENDPOINTS, ERROR_CODES } from '@aiaggregator/sdk'\n```\n\n## API Reference\n\n### `client.chat(request, signal?)`\n\nSend a chat request and wait for the result.\n\n**Parameters:**\n- `request: CreateChatRequest`\n  - `prompt?: string` - Simple text prompt\n  - `messages?: ChatMessage[]` - Chat messages array\n  - `provider?: string` - AI provider (openai, claude, ollama)\n  - `model?: string` - Model name\n  - `maxTokens?: number` - Maximum tokens to generate\n  - `temperature?: number` - Temperature (0-2)\n  - `tools?: Tool[]` - Tools/functions for AI to call\n  - `toolChoice?: string` - Tool choice mode\n  - `metadata?: Record<string, unknown>` - Custom metadata\n- `signal?: AbortSignal` - Optional signal to cancel request\n\n**Returns:** `Promise<ChatResult>`\n\n```typescript\ninterface ChatResult {\n  content: string\n  toolCalls?: ToolCall[]\n  finishReason: string\n  usage: { tokensIn: number; tokensOut: number; cost: number }\n  jobId: string\n  provider?: string\n  model?: string\n}\n```\n\n### `client.chatAsync(request, signal?)`\n\nSend a chat request without waiting for completion.\n\n**Returns:** `Promise<ChatResponse>` with `{ jobId, status }`\n\n### `client.waitForJob(jobId, signal?)`\n\nWait for a job to complete. Uses SSE when available, falls back to polling.\n\n**Returns:** `Promise<ChatResult>`\n\n### `client.getJobStatus(jobId, signal?)`\n\nGet current job status.\n\n**Returns:** `Promise<Job>`\n\n### `client.cancelJob(jobId, signal?)`\n\nCancel a pending job.\n\n**Returns:** `Promise<void>`\n\n## Node.js Compatibility\n\n| Node.js Version | Support |\n|-----------------|---------|\n| 18+ | ✅ Full support (native fetch) |\n| 16-17 | ⚠️ Requires fetch polyfill |\n| < 16 | ❌ Not supported |\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Build\npnpm build\n\n# Watch mode\npnpm dev\n\n# Run tests\npnpm test\n\n# Type check\npnpm typecheck\n```\n\n## Architecture\n\n```\nsrc/\n├── client.ts      # Main AIAggregator class\n├── constants.ts   # Configuration defaults and error codes\n├── http.ts        # HTTP client with retry logic\n├── sse.ts         # SSE client for real-time updates\n├── types.ts       # TypeScript types and interfaces\n└── index.ts       # Public exports\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-9c563763495d05ed816e26a9dc160ef8"}