@elsium-ai/client 0.3.0

package/README.md

@@ -0,0 +1,153 @@
+# @elsium-ai/client
+
+TypeScript HTTP client for consuming ElsiumAI servers, with full SSE streaming support.
+
+[![npm](https://img.shields.io/npm/v/@elsium-ai/client.svg)](https://www.npmjs.com/package/@elsium-ai/client)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/elsium-ai/elsium-ai/blob/main/LICENSE)
+
+---
+
+## Install
+
+```bash
+npm install @elsium-ai/client
+```
+
+---
+
+## What's Inside
+
+| Category | Exports |
+|----------|---------|
+| **Client** | `createClient` |
+| **Types** | `ElsiumClient`, `ClientConfig`, `ChatRequest`, `ChatResponse`, `CompleteRequest`, `CompleteResponse`, `HealthResponse`, `MetricsResponse`, `AgentInfo` |
+| **SSE** | `parseSSEStream` |
+
+---
+
+## Usage
+
+### Creating a client
+
+```typescript
+import { createClient } from '@elsium-ai/client'
+
+const client = createClient({
+  baseUrl: 'http://localhost:3000',
+  apiKey: 'my-api-token',       // Optional — sent as Authorization: Bearer header
+  timeout: 30_000,               // Optional — request timeout in ms
+})
+```
+
+### Chat with an agent
+
+```typescript
+const response = await client.chat({
+  agent: 'support-agent',
+  message: 'How do I return my order?',
+})
+
+console.log(response.message)  // Agent's response text
+```
+
+### Raw LLM completion
+
+```typescript
+const response = await client.complete({
+  messages: [{ role: 'user', content: 'Explain TypeScript generics.' }],
+  model: 'claude-sonnet-4-6',
+})
+
+console.log(response.message)
+console.log(response.usage)    // { inputTokens, outputTokens, totalTokens }
+```
+
+### Streaming (SSE)
+
+```typescript
+// Stream chat responses
+for await (const event of client.chatStream({
+  agent: 'support-agent',
+  message: 'Write a poem about coding',
+})) {
+  if (event.type === 'text_delta') {
+    process.stdout.write(event.text)
+  } else if (event.type === 'message_end') {
+    console.log('\nDone:', event.usage)
+  }
+}
+
+// Stream completions
+for await (const event of client.completeStream({
+  messages: [{ role: 'user', content: 'Count to 10 slowly' }],
+})) {
+  if (event.type === 'text_delta') {
+    process.stdout.write(event.text)
+  }
+}
+```
+
+### Health check
+
+```typescript
+const health = await client.health()
+console.log(health.status) // 'ok'
+```
+
+### List agents
+
+```typescript
+const agents = await client.agents()
+for (const agent of agents) {
+  console.log(`${agent.name}: ${agent.description}`)
+}
+```
+
+### Metrics
+
+```typescript
+const metrics = await client.metrics()
+console.log(metrics)
+```
+
+---
+
+## SSE Parser
+
+Use the SSE parser standalone to parse any Server-Sent Events response:
+
+```typescript
+import { parseSSEStream } from '@elsium-ai/client'
+
+const response = await fetch('http://localhost:3000/chat', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ agent: 'assistant', message: 'Hello', stream: true }),
+})
+
+for await (const event of parseSSEStream(response)) {
+  console.log(event.type, event)
+}
+```
+
+---
+
+## ElsiumClient Interface
+
+```typescript
+interface ElsiumClient {
+  chat(req: ChatRequest): Promise<ChatResponse>
+  chatStream(req: ChatRequest): AsyncIterable<StreamEvent>
+  complete(req: CompleteRequest): Promise<CompleteResponse>
+  completeStream(req: CompleteRequest): AsyncIterable<StreamEvent>
+  health(): Promise<HealthResponse>
+  metrics(): Promise<MetricsResponse>
+  agents(): Promise<AgentInfo[]>
+}
+```
+
+---
+
+## License
+
+[MIT](https://github.com/elsium-ai/elsium-ai/blob/main/LICENSE) - Copyright (c) 2026 Eric Utrera

package/dist/client.d.ts

@@ -0,0 +1,85 @@
+import type { StreamEvent } from '@elsium-ai/core';
+export interface ClientConfig {
+    baseUrl: string;
+    apiKey?: string;
+    timeout?: number;
+}
+export interface ChatRequest {
+    message: string;
+    agent?: string;
+    stream?: boolean;
+}
+export interface ChatResponse {
+    message: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cost: number;
+    };
+    model: string;
+    traceId: string;
+}
+export interface CompleteRequest {
+    messages: Array<{
+        role: string;
+        content: string;
+    }>;
+    model?: string;
+    system?: string;
+    maxTokens?: number;
+    temperature?: number;
+    stream?: boolean;
+}
+export interface CompleteResponse {
+    id: string;
+    message: string;
+    model: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    cost: {
+        inputCost: number;
+        outputCost: number;
+        totalCost: number;
+        currency: string;
+    };
+    traceId: string;
+}
+export interface HealthResponse {
+    status: 'ok' | 'degraded';
+    version: string;
+    uptime: number;
+    providers: string[];
+}
+export interface MetricsResponse {
+    uptime: number;
+    totalRequests: number;
+    totalTokens: number;
+    totalCost: number;
+    byModel: Record<string, {
+        requests: number;
+        tokens: number;
+        cost: number;
+    }>;
+}
+export interface AgentInfo {
+    name: string;
+    model: string;
+    tools: string[];
+}
+export interface ElsiumClient {
+    chat(req: ChatRequest): Promise<ChatResponse>;
+    chatStream(req: ChatRequest): AsyncIterable<StreamEvent>;
+    complete(req: CompleteRequest): Promise<CompleteResponse>;
+    completeStream(req: CompleteRequest): AsyncIterable<StreamEvent>;
+    health(): Promise<HealthResponse>;
+    metrics(): Promise<MetricsResponse>;
+    agents(): Promise<{
+        agents: AgentInfo[];
+    }>;
+}
+export declare function createClient(config: ClientConfig): ElsiumClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createClient } from './client';
+export type { ElsiumClient, ClientConfig, ChatRequest, ChatResponse, CompleteRequest, CompleteResponse, HealthResponse, MetricsResponse, AgentInfo, } from './client';
+export { parseSSEStream } from './sse-parser';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACvC,YAAY,EACX,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,SAAS,GACT,MAAM,UAAU,CAAA;AAEjB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -0,0 +1,119 @@
+// src/sse-parser.ts
+async function* parseSSEStream(response) {
+  if (!response.body) {
+    throw new Error("Response body is null");
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder;
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split(`
+`);
+      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 {}
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+// src/client.ts
+function createClient(config) {
+  const { baseUrl, apiKey, timeout = 30000 } = config;
+  function headers() {
+    const h = {
+      "Content-Type": "application/json"
+    };
+    if (apiKey) {
+      h.Authorization = `Bearer ${apiKey}`;
+    }
+    return h;
+  }
+  async function request(method, path, body) {
+    const controller = new AbortController;
+    const timer = setTimeout(() => controller.abort(), timeout);
+    try {
+      const response = await fetch(`${baseUrl}${path}`, {
+        method,
+        headers: headers(),
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const errorBody = await response.text().catch(() => "Unknown error");
+        throw new Error(`HTTP ${response.status}: ${errorBody}`);
+      }
+      return await response.json();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async function streamRequest(path, body) {
+    const controller = new AbortController;
+    const timer = setTimeout(() => controller.abort(), timeout);
+    try {
+      const response = await fetch(`${baseUrl}${path}`, {
+        method: "POST",
+        headers: headers(),
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        const errorBody = await response.text().catch(() => "Unknown error");
+        clearTimeout(timer);
+        throw new Error(`HTTP ${response.status}: ${errorBody}`);
+      }
+      return response;
+    } catch (err) {
+      clearTimeout(timer);
+      throw err;
+    }
+  }
+  return {
+    async chat(req) {
+      return request("POST", "/chat", { ...req, stream: false });
+    },
+    async* chatStream(req) {
+      const response = await streamRequest("/chat", { ...req, stream: true });
+      yield* parseSSEStream(response);
+    },
+    async complete(req) {
+      return request("POST", "/complete", { ...req, stream: false });
+    },
+    async* completeStream(req) {
+      const response = await streamRequest("/complete", { ...req, stream: true });
+      yield* parseSSEStream(response);
+    },
+    async health() {
+      return request("GET", "/health");
+    },
+    async metrics() {
+      return request("GET", "/metrics");
+    },
+    async agents() {
+      return request("GET", "/agents");
+    }
+  };
+}
+export {
+  parseSSEStream,
+  createClient
+};

package/dist/sse-parser.d.ts

@@ -0,0 +1,3 @@
+import type { StreamEvent } from '@elsium-ai/core';
+export declare function parseSSEStream(response: Response): AsyncIterable<StreamEvent>;
+//# sourceMappingURL=sse-parser.d.ts.map

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

@@ -0,0 +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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@elsium-ai/client",
+	"version": "0.3.0",
+	"description": "HTTP client SDK for ElsiumAI server",
+	"license": "MIT",
+	"author": "Eric Utrera <ebutrera9103@gmail.com>",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/elsium-ai/elsium-ai.git",
+		"directory": "packages/client"
+	},
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "bun build ./src/index.ts --outdir ./dist --target node && bun x tsc -p tsconfig.build.json --emitDeclarationOnly",
+		"dev": "bun --watch src/index.ts"
+	},
+	"dependencies": {
+		"@elsium-ai/core": "^0.3.0"
+	},
+	"devDependencies": {
+		"typescript": "^5.7.0"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	}
+}