anva-sdk 0.1.0

package/README.md

@@ -0,0 +1,26 @@
+# anva — JavaScript / TypeScript SDK
+
+Official JS/TS SDK for [Anva](https://anva.ai) — live AI avatars.
+ESM, zero dependencies, typed. Node 18+ and modern browsers (keep your API
+key server-side; hand only the `embed_url` to clients).
+
+```bash
+npm install anva-sdk
+```
+
+```js
+import { Anva } from "anva-sdk";
+
+const client = new Anva(process.env.ANVA_KEY);
+
+const session = await client.createSession({ characterId: "char_..." });
+console.log(session.embed_url);
+
+await client.sendMessage(session.session_id, "Welcome!");
+
+for await (const event of client.events(session.session_id)) {
+  console.log(event);
+}
+```
+
+Errors throw `AnvaError` with `.status` and `.code`. MIT © Penguin Robotics

package/index.d.ts

@@ -0,0 +1,81 @@
+/** Official JavaScript/TypeScript SDK for Anva (https://anva.ai). */
+
+export interface AnvaOptions {
+  /** Override for self-hosted / testing setups. Default: https://anva.ai */
+  baseUrl?: string;
+}
+
+export interface CreateSessionParams {
+  characterId: string;
+  /** Omit for the built-in conversation engine, or "external" to drive the LLM yourself. */
+  llmMode?: "external";
+  webhookUrl?: string;
+  webhookSecret?: string;
+}
+
+export interface Session {
+  session_id: string;
+  session_token: string;
+  character_id: string;
+  llm_mode?: string;
+  expires_at: string;
+  /** Ready to drop into an <iframe allow="camera; microphone; autoplay">. */
+  embed_url: string;
+  events_ws_url: string;
+  [key: string]: unknown;
+}
+
+export interface Character {
+  id: string;
+  name: string;
+  visual_character_id: string;
+  system_prompt: string;
+  voice_id: string;
+  language_code?: string;
+  disabled: boolean;
+  active: boolean;
+  [key: string]: unknown;
+}
+
+export interface SessionEvent {
+  type: string;
+  [key: string]: unknown;
+}
+
+export interface EventsOptions {
+  /** A WebSocket-compatible constructor (e.g. `ws` in older Node versions). */
+  WebSocketImpl?: new (url: string) => WebSocket;
+}
+
+export declare class AnvaError extends Error {
+  status: number;
+  code: string;
+}
+
+export declare class Anva {
+  constructor(apiKey: string, opts?: AnvaOptions);
+  apiKey: string;
+  baseUrl: string;
+
+  createSession(params: CreateSessionParams): Promise<Session>;
+  getSession(sessionId: string): Promise<Record<string, unknown>>;
+  endSession(sessionId: string): Promise<Record<string, unknown>>;
+  sendMessage(sessionId: string, text: string): Promise<{ status: string }>;
+  interrupt(sessionId: string): Promise<{ status: string }>;
+  triggerAction(sessionId: string, name: string): Promise<{ status: string }>;
+  eventsUrl(sessionId: string): string;
+  events(sessionId: string, opts?: EventsOptions): AsyncGenerator<SessionEvent, void, void>;
+
+  listCharacters(): Promise<{ characters: Character[] }>;
+  createCharacter(params: {
+    name: string;
+    visualCharacterId?: string;
+    systemPrompt?: string;
+    voiceId?: string;
+    languageCode?: string;
+  }): Promise<Character>;
+  getCharacter(characterId: string): Promise<Character>;
+  deleteCharacter(characterId: string): Promise<{ id: string; status: string }>;
+}
+
+export default Anva;

package/index.js

@@ -0,0 +1,181 @@
+/**
+ * Official JavaScript/TypeScript SDK for Anva (https://anva.ai).
+ *
+ *   import { Anva } from "anva";
+ *   const client = new Anva(process.env.ANVA_KEY);
+ *   const session = await client.createSession({ characterId: "char_..." });
+ *   // put session.embed_url in an <iframe allow="camera; microphone; autoplay">
+ *
+ * Works in Node 18+ (global fetch/WebSocket) and modern browsers — but keep
+ * your API key server-side; mint sessions on your backend and hand the
+ * embed_url to the client.
+ */
+
+const DEFAULT_BASE_URL = "https://anva.ai";
+
+export class AnvaError extends Error {
+  constructor(status, code, message) {
+    super(`${code}: ${message} (HTTP ${status})`);
+    this.name = "AnvaError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export class Anva {
+  /**
+   * @param {string} apiKey an API key from the dashboard (anva_key_...)
+   * @param {{baseUrl?: string}} [opts]
+   */
+  constructor(apiKey, opts = {}) {
+    if (!apiKey || !apiKey.trim()) throw new Error("apiKey is required");
+    this.apiKey = apiKey.trim();
+    this.baseUrl = (opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+  }
+
+  // -- sessions -------------------------------------------------------------
+
+  /**
+   * Create a live session. Returns { session_id, session_token, embed_url,
+   * events_ws_url, expires_at, ... }.
+   */
+  createSession({ characterId, llmMode, webhookUrl, webhookSecret }) {
+    const body = { character_id: characterId };
+    if (llmMode) body.llm_mode = llmMode;
+    if (webhookUrl) body.webhook_url = webhookUrl;
+    if (webhookSecret) body.webhook_secret = webhookSecret;
+    return this._request("POST", "/api/v1/sessions", body);
+  }
+
+  getSession(sessionId) {
+    return this._request("GET", `/api/v1/sessions/${enc(sessionId)}`);
+  }
+
+  endSession(sessionId) {
+    return this._request("DELETE", `/api/v1/sessions/${enc(sessionId)}`);
+  }
+
+  /** Have the avatar speak `text` to the user. */
+  sendMessage(sessionId, text) {
+    return this._request("POST", `/api/v1/sessions/${enc(sessionId)}/messages`, { text });
+  }
+
+  /** Stop the avatar mid-sentence. */
+  interrupt(sessionId) {
+    return this._request("POST", `/api/v1/sessions/${enc(sessionId)}/interrupt`, {});
+  }
+
+  triggerAction(sessionId, name) {
+    return this._request("POST", `/api/v1/sessions/${enc(sessionId)}/actions`, { name });
+  }
+
+  /** The authenticated WebSocket URL for the session's event stream. */
+  eventsUrl(sessionId) {
+    const ws = this.baseUrl.replace(/^http/, "ws");
+    return `${ws}/api/v1/sessions/${enc(sessionId)}/events?api_key=${encodeURIComponent(this.apiKey)}`;
+  }
+
+  /**
+   * Async-iterate live events (transcripts, state changes):
+   *
+   *   for await (const event of client.events(sessionId)) { ... }
+   */
+  async *events(sessionId, { WebSocketImpl } = {}) {
+    const WS = WebSocketImpl || globalThis.WebSocket;
+    if (!WS) throw new Error("no WebSocket implementation available — pass { WebSocketImpl }");
+    const ws = new WS(this.eventsUrl(sessionId));
+    const queue = [];
+    let notify = null;
+    let done = false;
+    let failure = null;
+    ws.onmessage = (m) => {
+      try {
+        queue.push(JSON.parse(m.data));
+      } catch {
+        /* non-JSON frame */
+      }
+      if (notify) notify();
+    };
+    ws.onclose = () => {
+      done = true;
+      if (notify) notify();
+    };
+    ws.onerror = () => {
+      failure = new Error("events socket error");
+      done = true;
+      if (notify) notify();
+    };
+    try {
+      while (!done || queue.length) {
+        if (!queue.length) {
+          await new Promise((resolve) => (notify = resolve));
+          notify = null;
+          continue;
+        }
+        yield queue.shift();
+      }
+      if (failure) throw failure;
+    } finally {
+      try {
+        ws.close();
+      } catch {
+        /* already closed */
+      }
+    }
+  }
+
+  // -- characters -----------------------------------------------------------
+
+  listCharacters() {
+    return this._request("GET", "/api/v1/characters");
+  }
+
+  createCharacter({ name, visualCharacterId, systemPrompt, voiceId, languageCode }) {
+    const body = { name };
+    if (visualCharacterId) body.visual_character_id = visualCharacterId;
+    if (systemPrompt) body.system_prompt = systemPrompt;
+    if (voiceId) body.voice_id = voiceId;
+    if (languageCode) body.language_code = languageCode;
+    return this._request("POST", "/api/v1/characters", body);
+  }
+
+  getCharacter(characterId) {
+    return this._request("GET", `/api/v1/characters/${enc(characterId)}`);
+  }
+
+  deleteCharacter(characterId) {
+    return this._request("DELETE", `/api/v1/characters/${enc(characterId)}`);
+  }
+
+  // -- plumbing -------------------------------------------------------------
+
+  async _request(method, path, body) {
+    const res = await fetch(this.baseUrl + path, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+        "User-Agent": "anva-js/0.1.0",
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const raw = await res.text();
+    let payload = {};
+    try {
+      payload = raw ? JSON.parse(raw) : {};
+    } catch {
+      payload = { message: raw.slice(0, 300) };
+    }
+    if (!res.ok) {
+      const err = payload.error || payload;
+      throw new AnvaError(res.status, err.code || "request_failed", err.message || "request failed");
+    }
+    return payload;
+  }
+}
+
+function enc(part) {
+  return encodeURIComponent(String(part));
+}
+
+export default Anva;

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "anva-sdk",
+  "version": "0.1.0",
+  "description": "Official JavaScript/TypeScript SDK for Anva \u2014 live AI avatars for your product.",
+  "keywords": [
+    "avatar",
+    "ai",
+    "webrtc",
+    "voice",
+    "anva"
+  ],
+  "homepage": "https://anva.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Anva-avatars/anva-sdk.git",
+    "directory": "js"
+  },
+  "license": "MIT",
+  "author": "Anva <anva.ai.2026@gmail.com>",
+  "type": "module",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}