@elsium-ai/client 0.3.0 → 0.4.0

package/README.md

@@ -148,6 +148,145 @@ interface ElsiumClient {
 
 ---
 
+## Type Definitions
+
+### `ClientConfig`
+
+Configuration for creating a client instance.
+
+```typescript
+interface ClientConfig {
+  baseUrl: string
+  apiKey?: string
+  timeout?: number
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `baseUrl` | `string` | **(required)** | The base URL of the ElsiumAI server. |
+| `apiKey` | `string` | `undefined` | API token sent as `Authorization: Bearer` header. |
+| `timeout` | `number` | `30000` | Request timeout in milliseconds. |
+
+### `ChatRequest`
+
+```typescript
+interface ChatRequest {
+  message: string
+  agent?: string
+  stream?: boolean
+}
+```
+
+### `ChatResponse`
+
+```typescript
+interface ChatResponse {
+  message: string
+  usage: { inputTokens: number; outputTokens: number; totalTokens: number; cost: number }
+  model: string
+  traceId: string
+}
+```
+
+### `CompleteRequest`
+
+```typescript
+interface CompleteRequest {
+  messages: Array<{ role: string; content: string }>
+  model?: string
+  system?: string
+  maxTokens?: number
+  temperature?: number
+  stream?: boolean
+}
+```
+
+### `CompleteResponse`
+
+```typescript
+interface CompleteResponse {
+  message: string
+  usage: { inputTokens: number; outputTokens: number; totalTokens: number }
+  model: string
+  stopReason: string
+}
+```
+
+### `HealthResponse`
+
+```typescript
+interface HealthResponse {
+  status: 'ok' | 'degraded'
+  version: string
+  uptime: number
+  providers: string[]
+}
+```
+
+### `MetricsResponse`
+
+```typescript
+interface MetricsResponse {
+  uptime: number
+  totalRequests: number
+  totalTokens: number
+  totalCost: number
+  byModel: Record<string, { requests: number; tokens: number; cost: number }>
+}
+```
+
+### `AgentInfo`
+
+```typescript
+interface AgentInfo {
+  name: string
+  model?: string
+  tools: string[]
+  description?: string
+}
+```
+
+### `StreamEvent`
+
+```typescript
+type StreamEvent =
+  | { type: 'text_delta'; text: string }
+  | { type: 'message_end'; usage: { inputTokens: number; outputTokens: number; totalTokens: number } }
+  | { type: 'error'; error: string }
+```
+
+---
+
+## Error Handling
+
+The client throws errors with descriptive messages for common failure cases. Wrap calls in try/catch for robust error handling:
+
+```typescript
+import { createClient } from '@elsium-ai/client'
+
+const client = createClient({
+  baseUrl: 'http://localhost:3000',
+  apiKey: 'my-token',
+})
+
+try {
+  const response = await client.chat({ message: 'Hello' })
+  console.log(response.message)
+} catch (error) {
+  if (error instanceof Error) {
+    // Common errors:
+    // - Network errors (server unreachable)
+    // - 401 Unauthorized (invalid or missing API key)
+    // - 429 Too Many Requests (rate limited)
+    // - 500 Internal Server Error
+    console.error('Request failed:', error.message)
+  }
+}
+```
+
+---
+
 ## License
 
 [MIT](https://github.com/elsium-ai/elsium-ai/blob/main/LICENSE) - Copyright (c) 2026 Eric Utrera

package/dist/index.js

@@ -1,9 +1,22 @@
 // src/sse-parser.ts
-async function* parseSSEStream(response) {
-  if (!response.body) {
-    throw new Error("Response body is null");
+function parseSSELine(line) {
+  if (line.startsWith("event: error"))
+    return;
+  if (!line.startsWith("data: "))
+    return;
+  const data = line.slice(6).trim();
+  if (!data || data === "[DONE]")
+    return;
+  try {
+    return JSON.parse(data);
+  } catch {
+    return;
   }
-  const reader = response.body.getReader();
+}
+async function* readSSELines(response) {
+  const reader = response.body?.getReader();
+  if (!reader)
+    return;
   const decoder = new TextDecoder;
   let buffer = "";
   try {
@@ -16,24 +29,23 @@ async function* parseSSEStream(response) {
 `);
       buffer = lines.pop() ?? "";
       for (const line of lines) {
-        if (line.startsWith("event: error")) {
-          continue;
-        }
-        if (!line.startsWith("data: "))
-          continue;
-        const data = line.slice(6).trim();
-        if (!data || data === "[DONE]")
-          continue;
-        try {
-          const event = JSON.parse(data);
-          yield event;
-        } catch {}
+        yield line;
       }
     }
   } finally {
     reader.releaseLock();
   }
 }
+async function* parseSSEStream(response) {
+  if (!response.body) {
+    throw new Error("Response body is null");
+  }
+  for await (const line of readSSELines(response)) {
+    const event = parseSSELine(line);
+    if (event)
+      yield event;
+  }
+}
 
 // src/client.ts
 function createClient(config) {

package/dist/sse-parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sse-parser.d.ts","sourceRoot":"","sources":["../src/sse-parser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAElD,wBAAuB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,aAAa,CAAC,WAAW,CAAC,CAsCpF"}
+{"version":3,"file":"sse-parser.d.ts","sourceRoot":"","sources":["../src/sse-parser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AA2ClD,wBAAuB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,aAAa,CAAC,WAAW,CAAC,CASpF"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@elsium-ai/client",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "HTTP client SDK for ElsiumAI server",
 	"license": "MIT",
 	"author": "Eric Utrera <ebutrera9103@gmail.com>",
@@ -26,7 +26,7 @@
 		"dev": "bun --watch src/index.ts"
 	},
 	"dependencies": {
-		"@elsium-ai/core": "^0.3.0"
+		"@elsium-ai/core": "^0.4.0"
 	},
 	"devDependencies": {
 		"typescript": "^5.7.0"