@avis-ai/sdk-js

Minimal, framework-agnostic JavaScript/TypeScript client for the Avis AI HTTP API. Use it anywhere you can run fetch: Vue, Svelte, Angular, vanilla sites, Electron, Node 18+, Deno, etc.

The React UI package @avis-ai/avischat uses this SDK internally (Avis + streaming). If you want the full chat widget (markdown, model picker, floating launcher), use AvisChat in React or load the hosted iframe embed (see Embedding without React).

Demo: https://demo-ai.avi-s.in

Install

npm install @avis-ai/sdk-js
pnpm add @avis-ai/sdk-js
yarn add @avis-ai/sdk-js

No peer dependency on React.

Quick start (non-streaming)

import { Avis, generateSessionId } from "@avis-ai/sdk-js";

const client = new Avis({
  apiKey: "your-api-key",
  // baseUrl: "https://api-ai.avi-s.in", // default; omit or set for self-hosted / proxy
});

const sessionId = generateSessionId();

const res = await client.chat({
  sessionId,
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Hello!" }],
});

const text = res.choices[0]?.message?.content ?? "";

Streaming

chatStream returns a ReadableStream<string> of assistant text deltas (decoded from SSE). Consume it in the browser or Node:

const stream = await client.chatStream({
  sessionId,
  messages: [{ role: "user", content: "Explain streaming in one sentence." }],
});

const reader = stream.getReader();
const decoder = new TextDecoder();
let full = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  full += value; // incremental assistant text
}

console.log(full);

For raw OpenAI-style SSE chunk objects, use chatStreamRaw (returns ReadableStream<StreamChunk>).

API

new Avis(options)

| Option | Type | Description | |--------|------|-------------| | apiKey | string | Required. Project API key (sk_live_…). | | baseUrl | string | API origin, no trailing slash. Default: https://api-ai.avi-s.in. |

The client sends Authorization: Bearer <apiKey> and posts JSON to POST /v1/chat/completions.

chat(options)

Non-streaming completion.

• messages: { role: "system" \| "user" \| "assistant"; content: string }[] — required.
• sessionId: optional; threads are keyed server-side by this id. If omitted, a new id is generated per call (via generateSessionId() inside the client). Reuse the same sessionId to continue a conversation.
• model: optional model id (must be allowed by your project/backend).
• signal: optional AbortSignal for cancellation.

Returns ChatCompletionResponse (choices, usage, etc.).

chatStream(options) / chatStreamRaw(options)

Same options shape as chat, with stream: true implied.

• chatStream: stream of text delta strings.
• chatStreamRaw: stream of parsed SSE JSON chunks.

generateSessionId()

Exported helper for creating a new conversation id when you manage sessions yourself.

Errors

Failed responses throw AvisError (message, code, statusCode, optional requestId). Import AvisError and parseErrorResponse from the package if you extend the client.

Security (browser)

If apiKey is constructed in the browser, the SDK logs a console warning (same as in @avis-ai/avischat). For production, proxy /v1/chat/completions through your origin, attach the key server-side, and point baseUrl at that proxy.

TypeScript

Exported types include ChatMessage, ChatCompletionOptions, ChatCompletionResponse, StreamChunk, AvisOptions.

Embedding without React

For sites that are not React:

1. Iframe + script tag — paste the loader from your API origin (same host you use for baseUrl / chat). The script injects a fixed iframe; your site does not need React.

   Production example (replace the API key with your project key). You should set data-embed-url to a public page that renders the chat (the default in widget.js is http://localhost:3002/embed, which only works on your dev machine):

   <script
     src="https://api-ai.avi-s.in/widget.js"
     data-api-key="sk_live_YOUR_API_KEY"
     data-embed-url="https://demo-ai.avi-s.in/embed"
   ></script>

   If you self-host the embed app, point data-embed-url at your own origin’s /embed (or equivalent) instead.

2. This SDK — build any UI and call Avis from your stack.

Related packages

| Package | Use case | |---------|----------| | @avis-ai/avischat | Pre-built React chat widget and useAvisChat hook. | | @avis-ai/sdk-js | Headless API client (this package). |