@evalage/sdk-core 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# @evalage/sdk-core
+
+Minimal core transport SDK for the ReplicaVAPi voice service.
+
+## Install
+
+```bash
+npm install @evalage/sdk-core
+```
+
+## Usage
+
+```ts
+import { EvalageCoreClient } from '@evalage/sdk-core';
+
+const core = new EvalageCoreClient({
+  serverUrl: process.env.VITE_SERVER_URL!,
+  platformApiKey: process.env.VITE_PLATFORM_API_KEY!,
+  assistantId: process.env.VITE_ASSISTANT_ID!,
+});
+
+core.on('call-ended', (e) => {
+  console.log('call ended', e);
+});
+
+await core.connect();
+core.startCall({});
+
+// later
+core.endCall();
+```
+
+## What it does
+
+- Connects to the Socket.IO `/voice` namespace
+- Authenticates with `{ platformApiKey, assistantId }`
+- Emits typed events like `call-started`, `call-ended`, `session-var-updated`, `agent-ready/open/close`
+- Lets you send audio via `emitAudioChunk(ArrayBuffer)` and receive with `onAgentAudioChunk(...)`

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+import { Socket } from 'socket.io-client';
+
+type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type SessionVars = Record<string, JsonValue>;
+type StartCallPayload = {
+    userName?: string;
+    vars?: SessionVars;
+};
+type CallStartedEvent = {
+    callId?: string;
+    [key: string]: unknown;
+};
+type CallEndedEvent = {
+    callId?: string | null;
+    reason?: string;
+    tool?: string;
+    [key: string]: unknown;
+};
+type SessionVarUpdatedEvent = {
+    callId?: string;
+    key: string;
+    value: JsonValue;
+    type?: string;
+};
+type SdkError = {
+    message: string;
+    code?: string;
+    raw?: unknown;
+};
+type CoreClientEvents = {
+    connected: {
+        socketId: string;
+    };
+    disconnected: {
+        reason: string;
+    };
+    'call-started': CallStartedEvent;
+    'call-ended': CallEndedEvent;
+    'agent-ready': void;
+    'agent-open': void;
+    'agent-close': void;
+    'agent-error': SdkError;
+    error: SdkError;
+    'session-var-updated': SessionVarUpdatedEvent;
+    '_socket-connect-error': SdkError;
+};
+
+type CoreClientOptions = {
+    serverUrl: string;
+    platformApiKey: string;
+    assistantId: string;
+    transports?: Array<'websocket' | 'polling'>;
+    debug?: boolean;
+};
+type InterruptPayload = {
+    type: string;
+    [key: string]: unknown;
+};
+declare class EvalageCoreClient {
+    private readonly opts;
+    private socket;
+    private emitter;
+    private connected;
+    constructor(options: CoreClientOptions);
+    on<K extends keyof CoreClientEvents>(event: K, handler: (payload: CoreClientEvents[K]) => void): () => void;
+    off<K extends keyof CoreClientEvents>(event: K, handler: (payload: CoreClientEvents[K]) => void): void;
+    getSocket(): Socket | null;
+    isConnected(): boolean;
+    connect(): Promise<void>;
+    startCall(payload?: StartCallPayload): void;
+    endCall(): void;
+    interrupt(payload: InterruptPayload): void;
+    emitAudioChunk(pcm16Buffer: ArrayBufferLike): void;
+    onAgentAudioChunk(handler: (pcm16: ArrayBuffer) => void): () => void;
+    disconnect(): void;
+}
+
+export { type CallEndedEvent, type CallStartedEvent, type CoreClientEvents, type CoreClientOptions, EvalageCoreClient, type InterruptPayload, type SdkError, type SessionVarUpdatedEvent, type StartCallPayload };

package/dist/index.js

@@ -0,0 +1,196 @@
+// src/index.ts
+import { io } from "socket.io-client";
+
+// src/tinyEmitter.ts
+var TinyEmitter = class {
+  constructor() {
+    this.handlers = /* @__PURE__ */ new Map();
+  }
+  on(event, handler) {
+    const set = this.handlers.get(event) || /* @__PURE__ */ new Set();
+    set.add(handler);
+    this.handlers.set(event, set);
+    return () => this.off(event, handler);
+  }
+  off(event, handler) {
+    const set = this.handlers.get(event);
+    if (!set) return;
+    set.delete(handler);
+    if (set.size === 0) this.handlers.delete(event);
+  }
+  emit(event, payload) {
+    const set = this.handlers.get(event);
+    if (!set || set.size === 0) return;
+    for (const handler of Array.from(set)) {
+      try {
+        handler(payload);
+      } catch {
+      }
+    }
+  }
+};
+
+// src/index.ts
+var toError = (e, fallbackMessage) => {
+  if (e && typeof e === "object") {
+    const anyE = e;
+    return {
+      message: String(anyE?.message || fallbackMessage),
+      code: anyE?.code ? String(anyE.code) : void 0,
+      raw: e
+    };
+  }
+  return { message: fallbackMessage, raw: e };
+};
+var EvalageCoreClient = class {
+  constructor(options) {
+    this.socket = null;
+    this.emitter = new TinyEmitter();
+    this.connected = false;
+    this.opts = {
+      transports: ["websocket"],
+      debug: false,
+      ...options
+    };
+    if (!this.opts.serverUrl || !this.opts.serverUrl.trim()) {
+      throw new Error("EvalageCoreClient: missing serverUrl");
+    }
+    if (!this.opts.platformApiKey || !this.opts.platformApiKey.trim()) {
+      throw new Error("EvalageCoreClient: missing platformApiKey");
+    }
+    if (!this.opts.assistantId || !this.opts.assistantId.trim()) {
+      throw new Error("EvalageCoreClient: missing assistantId");
+    }
+  }
+  on(event, handler) {
+    return this.emitter.on(event, handler);
+  }
+  off(event, handler) {
+    this.emitter.off(event, handler);
+  }
+  getSocket() {
+    return this.socket;
+  }
+  isConnected() {
+    return this.connected;
+  }
+  async connect() {
+    if (this.socket && this.connected) return;
+    const url = this.opts.serverUrl.replace(/\/$/, "");
+    const socket = io(`${url}/voice`, {
+      transports: this.opts.transports,
+      auth: {
+        platformApiKey: this.opts.platformApiKey,
+        assistantId: this.opts.assistantId
+      }
+    });
+    this.socket = socket;
+    socket.on("connect", () => {
+      this.connected = true;
+      const socketId = socket.id ?? "";
+      this.emitter.emit("connected", { socketId });
+      if (this.opts.debug) console.log("[evalage/sdk-core] connected", { socketId });
+    });
+    socket.on("disconnect", (reason) => {
+      this.connected = false;
+      this.emitter.emit("disconnected", { reason: String(reason || "") });
+      if (this.opts.debug) console.log("[evalage/sdk-core] disconnected", reason);
+    });
+    socket.on("connect_error", (err) => {
+      const e = toError(err, "socket connect_error");
+      this.emitter.emit("_socket-connect-error", e);
+      this.emitter.emit("error", e);
+      if (this.opts.debug) console.log("[evalage/sdk-core] connect_error", e);
+    });
+    socket.on("error", (err) => {
+      const e = toError(err, "server error");
+      this.emitter.emit("error", e);
+      if (this.opts.debug) console.log("[evalage/sdk-core] error", e);
+    });
+    socket.on("agent-error", (err) => {
+      const e = toError(err, "agent error");
+      this.emitter.emit("agent-error", e);
+      if (this.opts.debug) console.log("[evalage/sdk-core] agent-error", e);
+    });
+    socket.on("agent-ready", () => {
+      this.emitter.emit("agent-ready", void 0);
+      if (this.opts.debug) console.log("[evalage/sdk-core] agent-ready");
+    });
+    socket.on("agent-open", () => {
+      this.emitter.emit("agent-open", void 0);
+      if (this.opts.debug) console.log("[evalage/sdk-core] agent-open");
+    });
+    socket.on("agent-close", () => {
+      this.emitter.emit("agent-close", void 0);
+      if (this.opts.debug) console.log("[evalage/sdk-core] agent-close");
+    });
+    socket.on("call-started", (data) => {
+      this.emitter.emit("call-started", data);
+      if (this.opts.debug) console.log("[evalage/sdk-core] call-started", data);
+    });
+    socket.on("call-ended", (data) => {
+      this.emitter.emit("call-ended", data);
+      if (this.opts.debug) console.log("[evalage/sdk-core] call-ended", data);
+    });
+    socket.on("session-var-updated", (data) => {
+      this.emitter.emit("session-var-updated", data);
+      if (this.opts.debug) console.log("[evalage/sdk-core] session-var-updated", data);
+    });
+    await new Promise((resolve) => {
+      const done = () => resolve();
+      socket.once("connect", done);
+      socket.once("connect_error", done);
+    });
+  }
+  startCall(payload = {}) {
+    if (!this.socket) throw new Error("EvalageCoreClient: not connected");
+    this.socket.emit("agent-start", payload);
+    if (this.opts.debug) console.log("[evalage/sdk-core] agent-start emitted", payload);
+  }
+  endCall() {
+    if (!this.socket) return;
+    try {
+      this.socket.emit("agent-end");
+    } catch {
+    }
+    try {
+      this.socket.disconnect();
+    } catch {
+    }
+  }
+  interrupt(payload) {
+    if (!this.socket) throw new Error("EvalageCoreClient: not connected");
+    this.socket.emit("agent-interrupt", payload);
+    if (this.opts.debug) console.log("[evalage/sdk-core] agent-interrupt emitted", payload);
+  }
+  emitAudioChunk(pcm16Buffer) {
+    if (!this.socket) throw new Error("EvalageCoreClient: not connected");
+    this.socket.emit("agent-audio-chunk", pcm16Buffer);
+  }
+  onAgentAudioChunk(handler) {
+    if (!this.socket) throw new Error("EvalageCoreClient: not connected");
+    const h = (data) => {
+      const bytes = data instanceof ArrayBuffer ? data : data?.buffer instanceof ArrayBuffer ? data.buffer : null;
+      if (bytes) handler(bytes);
+    };
+    this.socket.on("agent-audio-chunk", h);
+    return () => {
+      try {
+        this.socket?.off("agent-audio-chunk", h);
+      } catch {
+      }
+    };
+  }
+  disconnect() {
+    if (!this.socket) return;
+    try {
+      this.socket.disconnect();
+    } catch {
+    }
+    this.socket = null;
+    this.connected = false;
+  }
+};
+export {
+  EvalageCoreClient
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@evalage/sdk-core",
+  "version": "0.1.0",
+  "description": "Core client SDK for ReplicaVAPi voice service (transport + events).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "socket.io-client": "^4.8.1"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.2",
+    "typescript": "^5.6.3"
+  }
+}