@elsium-ai/client

HTTP client SDK for talking to an ElsiumAI server — a typed client for chat, completion, health, metrics, and agent endpoints, plus a helper for parsing Server-Sent Events (SSE) streams.

Install

npm install @elsium-ai/client

Peer dependency @elsium-ai/core is pulled in automatically within the ElsiumAI monorepo. In standalone usage, install it explicitly:

npm install @elsium-ai/client @elsium-ai/core

import { createClient, parseSSEStream } from '@elsium-ai/client'

What’s Inside

Client

createClient

Returns an ElsiumClient configured to call the given baseUrl. Requests send Content-Type: application/json and, when apiKey is set, an Authorization: Bearer <apiKey> header. Each request is aborted after timeout milliseconds (default 30000).

import { createClient } from '@elsium-ai/client'

const client = createClient({
  baseUrl: 'https://api.example.com',
  apiKey: process.env.ELSIUM_API_KEY,
  timeout: 30_000,
})

const response = await client.chat({ message: 'Hello', agent: 'support' })
console.log(response.message, response.usage.totalTokens)

ClientConfig

interface ClientConfig {
  baseUrl: string    // Base URL of the ElsiumAI server
  apiKey?: string    // Optional bearer token
  timeout?: number   // Per-request timeout in ms (default: 30000)
}

ElsiumClient

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[] }>
}

Chat

const res = await client.chat({ message: 'Summarize this thread', agent: 'support' })
// res => { message, usage: { inputTokens, outputTokens, totalTokens, cost }, model, traceId }

ChatRequest

interface ChatRequest {
  message: string
  agent?: string    // Named agent to route to
  stream?: boolean  // Forced internally per method; not required by callers
}

ChatResponse

interface ChatResponse {
  message: string
  usage: {
    inputTokens: number
    outputTokens: number
    totalTokens: number
    cost: number
  }
  model: string
  traceId: string
}

Complete

Lower-level completion endpoint that accepts an explicit message array and model parameters.

const res = await client.complete({
  messages: [{ role: 'user', content: 'Translate "hello" to French' }],
  model: 'claude-sonnet-4-5',
  system: 'You are a translator.',
  maxTokens: 256,
  temperature: 0.2,
})
// res => { id, message, model, usage, cost, traceId }

CompleteRequest

interface CompleteRequest {
  messages: Array<{ role: string; content: string }>
  model?: string
  system?: string
  maxTokens?: number
  temperature?: number
  stream?: boolean
}

CompleteResponse

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
}

Streaming

chatStream and completeStream return an AsyncIterable<StreamEvent>. Iterate with for await; the underlying SSE parsing is handled for you.

for await (const event of client.chatStream({ message: 'Tell me a story' })) {
  if (event.type === 'text_delta') {
    process.stdout.write(event.text)
  }
}

StreamEvent is re-used from @elsium-ai/core and is a discriminated union over type (text_delta, thinking_delta, tool_call_start, message_end, error, and more). See the core API reference for the full shape.

SSE Parsing

parseSSEStream

Consumes a streaming Response body, splits it on newlines, and yields one StreamEvent per valid data: line. Throws if response.body is null. event: error lines, blank lines, [DONE] sentinels, and malformed JSON are skipped.

Use this directly when you make your own fetch to an SSE endpoint instead of going through chatStream / completeStream.

import { parseSSEStream } from '@elsium-ai/client'

const response = await fetch('https://api.example.com/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ message: 'Hello', stream: true }),
})

for await (const event of parseSSEStream(response)) {
  if (event.type === 'text_delta') {
    process.stdout.write(event.text)
  }
}

Server Info

HealthResponse

interface HealthResponse {
  status: 'ok' | 'degraded'
  version: string
  uptime: number
  providers: string[]
}

MetricsResponse

interface MetricsResponse {
  uptime: number
  totalRequests: number
  totalTokens: number
  totalCost: number
  byModel: Record<string, { requests: number; tokens: number; cost: number }>
}

AgentInfo

interface AgentInfo {
  name: string
  model: string
  tools: string[]
}

const { agents } = await client.agents()
for (const agent of agents) {
  console.log(agent.name, agent.model, agent.tools)
}

Types

Part of ElsiumAI

This package is the HTTP client SDK of the ElsiumAI framework — the consumer side of an @elsium-ai/app server. See the Getting Started guide or the Fundamentals for comprehensive coverage of every feature.

License

MIT