@elelem/answer-engine-client 1.0.0

package/dist/index.js

@@ -0,0 +1,265 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AnswerEngineClient: () => AnswerEngineClient
+});
+module.exports = __toCommonJS(index_exports);
+var import_socket = require("socket.io-client");
+var AnswerEngineClient = class {
+  constructor(config) {
+    this.config = config;
+    this.socket = null;
+    this.lastReceivedAt = 0;
+    this.status = "disconnected";
+    this.activeMessageID = null;
+    this.launchMessageID = null;
+    this.actionQueue = [];
+    this.isProcessingQueue = false;
+    // Callback stores
+    this.tokenCallbacks = [];
+    this.recommendationCallbacks = [];
+    this.statusCallbacks = [];
+    this.errorCallbacks = [];
+    if (!config.projectID) {
+      throw new Error("projectID is required");
+    }
+    if (!config.environmentID) {
+      throw new Error("environmentID is required");
+    }
+    this.userID = config.userID || "ae-sess-" + Date.now() + "-" + Math.random().toString(36).slice(2);
+  }
+  /**
+   * Initialize the Socket.IO connection and handshakes.
+   */
+  connect() {
+    if (this.socket) {
+      return Promise.resolve();
+    }
+    const socketUrl = this.config.socketUrl || "wss://general-runtime.answer-engine.elelem.ai";
+    const socketPath = this.config.socketPath || "/v3/interact/socket/";
+    this.updateStatus("connecting");
+    this.socket = (0, import_socket.io)(socketUrl, {
+      path: socketPath,
+      transports: ["websocket"],
+      reconnection: true
+    });
+    return new Promise((resolve, reject) => {
+      let isInit = true;
+      this.socket.on("connect", () => {
+        this.updateStatus("connected");
+        this.socket.emit("start", {
+          userID: this.userID,
+          projectID: this.config.projectID,
+          environmentID: this.config.environmentID,
+          lastReceivedAt: this.lastReceivedAt,
+          config: {
+            completionEvents: true,
+            audioEvents: false,
+            audioEncoding: "audio/pcm",
+            modality: "chat",
+            guidedNavigation: false,
+            userTimezone: this.config.userTimezone || Intl.DateTimeFormat().resolvedOptions().timeZone,
+            endAutomatically: false,
+            isTestSession: false
+          }
+        });
+      });
+      this.socket.on("start", (data) => {
+        this.updateStatus("ready");
+        if (isInit) {
+          isInit = false;
+          resolve();
+        }
+      });
+      this.socket.on("connect_error", (error) => {
+        this.handleError(error);
+        if (isInit) {
+          isInit = false;
+          reject(error);
+        }
+      });
+      this.socket.on("disconnect", (reason) => {
+        this.updateStatus("disconnected");
+        this.activeMessageID = null;
+        this.launchMessageID = null;
+      });
+      this.socket.on("action", (data) => {
+        if (data.status === "accepted") {
+          this.activeMessageID = data.messageID;
+        } else if (data.status === "completed" && data.messageID === this.activeMessageID) {
+          this.activeMessageID = null;
+          this.processNextInQueue();
+        }
+      });
+      this.socket.on("trace", (data) => {
+        const { trace } = data;
+        if (trace.time) {
+          this.lastReceivedAt = trace.time;
+        }
+        if (trace.type === "completion") {
+          if (trace.payload.state === "content") {
+            this.triggerToken(trace.payload.content);
+          }
+        } else if (trace.type === "Emit recommendations") {
+          this.triggerRecommendation({
+            doc_title: trace.payload.doc_title,
+            chunks: trace.payload.chunks,
+            url: trace.payload.url,
+            doc_title2: trace.payload.doc_title2,
+            chunks2: trace.payload.chunks2,
+            url2: trace.payload.url2
+          });
+        }
+      });
+    });
+  }
+  /**
+   * Terminate the connection.
+   */
+  disconnect() {
+    if (this.socket) {
+      this.socket.disconnect();
+      this.socket = null;
+    }
+    this.updateStatus("disconnected");
+    this.actionQueue = [];
+    this.isProcessingQueue = false;
+  }
+  /**
+   * Launch/initialize the conversational flow.
+   */
+  launch() {
+    return this.queueAction("launch");
+  }
+  /**
+   * Send a text message turn.
+   */
+  sendMessage(text) {
+    return this.queueAction("text", text);
+  }
+  /**
+   * Trigger a named flow intent event turn.
+   */
+  sendIntent(intentName, data = {}) {
+    return this.queueAction("intent", { name: intentName, data });
+  }
+  // --- Subscriptions ---
+  onToken(callback) {
+    this.tokenCallbacks.push(callback);
+    return () => {
+      this.tokenCallbacks = this.tokenCallbacks.filter((cb) => cb !== callback);
+    };
+  }
+  onRecommendations(callback) {
+    this.recommendationCallbacks.push(callback);
+    return () => {
+      this.recommendationCallbacks = this.recommendationCallbacks.filter((cb) => cb !== callback);
+    };
+  }
+  onStatusChange(callback) {
+    this.statusCallbacks.push(callback);
+    callback(this.status);
+    return () => {
+      this.statusCallbacks = this.statusCallbacks.filter((cb) => cb !== callback);
+    };
+  }
+  onError(callback) {
+    this.errorCallbacks.push(callback);
+    return () => {
+      this.errorCallbacks = this.errorCallbacks.filter((cb) => cb !== callback);
+    };
+  }
+  // --- Internals ---
+  queueAction(type, payload) {
+    return new Promise((resolve, reject) => {
+      this.actionQueue.push({ type, payload, resolve, reject });
+      this.processNextInQueue();
+    });
+  }
+  processNextInQueue() {
+    if (this.isProcessingQueue) {
+      return;
+    }
+    if (this.actionQueue.length === 0) {
+      return;
+    }
+    if (this.status !== "ready" || this.activeMessageID !== null) {
+      return;
+    }
+    this.isProcessingQueue = true;
+    const item = this.actionQueue.shift();
+    try {
+      if (!this.socket) {
+        throw new Error("Client is not connected. Call .connect() first.");
+      }
+      let payloadBlock = {};
+      if (item.type === "launch") {
+        payloadBlock = { type: "launch" };
+      } else if (item.type === "text") {
+        payloadBlock = { type: "text", payload: item.payload };
+      } else if (item.type === "intent") {
+        payloadBlock = {
+          type: "intent",
+          payload: {
+            intent: { name: item.payload.name },
+            data: item.payload.data,
+            label: `Intent: ${item.payload.name}`,
+            query: `Intent: ${item.payload.name}`
+          }
+        };
+      }
+      this.socket.emit("action", {
+        action: payloadBlock,
+        config: {
+          stateful: false,
+          audioEvents: false,
+          guidedNavigation: false
+        }
+      });
+      item.resolve();
+    } catch (err) {
+      item.reject(err);
+      this.handleError(err);
+    } finally {
+      this.isProcessingQueue = false;
+      setTimeout(() => this.processNextInQueue(), 0);
+    }
+  }
+  updateStatus(newStatus) {
+    this.status = newStatus;
+    this.statusCallbacks.forEach((cb) => cb(newStatus));
+  }
+  handleError(err) {
+    const errorObj = err instanceof Error ? err : new Error(String(err));
+    this.errorCallbacks.forEach((cb) => cb(errorObj));
+  }
+  triggerToken(token) {
+    this.tokenCallbacks.forEach((cb) => cb(token));
+  }
+  triggerRecommendation(rec) {
+    this.recommendationCallbacks.forEach((cb) => cb(rec));
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AnswerEngineClient
+});

package/dist/index.mjs

@@ -0,0 +1,240 @@
+// src/index.ts
+import { io } from "socket.io-client";
+var AnswerEngineClient = class {
+  constructor(config) {
+    this.config = config;
+    this.socket = null;
+    this.lastReceivedAt = 0;
+    this.status = "disconnected";
+    this.activeMessageID = null;
+    this.launchMessageID = null;
+    this.actionQueue = [];
+    this.isProcessingQueue = false;
+    // Callback stores
+    this.tokenCallbacks = [];
+    this.recommendationCallbacks = [];
+    this.statusCallbacks = [];
+    this.errorCallbacks = [];
+    if (!config.projectID) {
+      throw new Error("projectID is required");
+    }
+    if (!config.environmentID) {
+      throw new Error("environmentID is required");
+    }
+    this.userID = config.userID || "ae-sess-" + Date.now() + "-" + Math.random().toString(36).slice(2);
+  }
+  /**
+   * Initialize the Socket.IO connection and handshakes.
+   */
+  connect() {
+    if (this.socket) {
+      return Promise.resolve();
+    }
+    const socketUrl = this.config.socketUrl || "wss://general-runtime.answer-engine.elelem.ai";
+    const socketPath = this.config.socketPath || "/v3/interact/socket/";
+    this.updateStatus("connecting");
+    this.socket = io(socketUrl, {
+      path: socketPath,
+      transports: ["websocket"],
+      reconnection: true
+    });
+    return new Promise((resolve, reject) => {
+      let isInit = true;
+      this.socket.on("connect", () => {
+        this.updateStatus("connected");
+        this.socket.emit("start", {
+          userID: this.userID,
+          projectID: this.config.projectID,
+          environmentID: this.config.environmentID,
+          lastReceivedAt: this.lastReceivedAt,
+          config: {
+            completionEvents: true,
+            audioEvents: false,
+            audioEncoding: "audio/pcm",
+            modality: "chat",
+            guidedNavigation: false,
+            userTimezone: this.config.userTimezone || Intl.DateTimeFormat().resolvedOptions().timeZone,
+            endAutomatically: false,
+            isTestSession: false
+          }
+        });
+      });
+      this.socket.on("start", (data) => {
+        this.updateStatus("ready");
+        if (isInit) {
+          isInit = false;
+          resolve();
+        }
+      });
+      this.socket.on("connect_error", (error) => {
+        this.handleError(error);
+        if (isInit) {
+          isInit = false;
+          reject(error);
+        }
+      });
+      this.socket.on("disconnect", (reason) => {
+        this.updateStatus("disconnected");
+        this.activeMessageID = null;
+        this.launchMessageID = null;
+      });
+      this.socket.on("action", (data) => {
+        if (data.status === "accepted") {
+          this.activeMessageID = data.messageID;
+        } else if (data.status === "completed" && data.messageID === this.activeMessageID) {
+          this.activeMessageID = null;
+          this.processNextInQueue();
+        }
+      });
+      this.socket.on("trace", (data) => {
+        const { trace } = data;
+        if (trace.time) {
+          this.lastReceivedAt = trace.time;
+        }
+        if (trace.type === "completion") {
+          if (trace.payload.state === "content") {
+            this.triggerToken(trace.payload.content);
+          }
+        } else if (trace.type === "Emit recommendations") {
+          this.triggerRecommendation({
+            doc_title: trace.payload.doc_title,
+            chunks: trace.payload.chunks,
+            url: trace.payload.url,
+            doc_title2: trace.payload.doc_title2,
+            chunks2: trace.payload.chunks2,
+            url2: trace.payload.url2
+          });
+        }
+      });
+    });
+  }
+  /**
+   * Terminate the connection.
+   */
+  disconnect() {
+    if (this.socket) {
+      this.socket.disconnect();
+      this.socket = null;
+    }
+    this.updateStatus("disconnected");
+    this.actionQueue = [];
+    this.isProcessingQueue = false;
+  }
+  /**
+   * Launch/initialize the conversational flow.
+   */
+  launch() {
+    return this.queueAction("launch");
+  }
+  /**
+   * Send a text message turn.
+   */
+  sendMessage(text) {
+    return this.queueAction("text", text);
+  }
+  /**
+   * Trigger a named flow intent event turn.
+   */
+  sendIntent(intentName, data = {}) {
+    return this.queueAction("intent", { name: intentName, data });
+  }
+  // --- Subscriptions ---
+  onToken(callback) {
+    this.tokenCallbacks.push(callback);
+    return () => {
+      this.tokenCallbacks = this.tokenCallbacks.filter((cb) => cb !== callback);
+    };
+  }
+  onRecommendations(callback) {
+    this.recommendationCallbacks.push(callback);
+    return () => {
+      this.recommendationCallbacks = this.recommendationCallbacks.filter((cb) => cb !== callback);
+    };
+  }
+  onStatusChange(callback) {
+    this.statusCallbacks.push(callback);
+    callback(this.status);
+    return () => {
+      this.statusCallbacks = this.statusCallbacks.filter((cb) => cb !== callback);
+    };
+  }
+  onError(callback) {
+    this.errorCallbacks.push(callback);
+    return () => {
+      this.errorCallbacks = this.errorCallbacks.filter((cb) => cb !== callback);
+    };
+  }
+  // --- Internals ---
+  queueAction(type, payload) {
+    return new Promise((resolve, reject) => {
+      this.actionQueue.push({ type, payload, resolve, reject });
+      this.processNextInQueue();
+    });
+  }
+  processNextInQueue() {
+    if (this.isProcessingQueue) {
+      return;
+    }
+    if (this.actionQueue.length === 0) {
+      return;
+    }
+    if (this.status !== "ready" || this.activeMessageID !== null) {
+      return;
+    }
+    this.isProcessingQueue = true;
+    const item = this.actionQueue.shift();
+    try {
+      if (!this.socket) {
+        throw new Error("Client is not connected. Call .connect() first.");
+      }
+      let payloadBlock = {};
+      if (item.type === "launch") {
+        payloadBlock = { type: "launch" };
+      } else if (item.type === "text") {
+        payloadBlock = { type: "text", payload: item.payload };
+      } else if (item.type === "intent") {
+        payloadBlock = {
+          type: "intent",
+          payload: {
+            intent: { name: item.payload.name },
+            data: item.payload.data,
+            label: `Intent: ${item.payload.name}`,
+            query: `Intent: ${item.payload.name}`
+          }
+        };
+      }
+      this.socket.emit("action", {
+        action: payloadBlock,
+        config: {
+          stateful: false,
+          audioEvents: false,
+          guidedNavigation: false
+        }
+      });
+      item.resolve();
+    } catch (err) {
+      item.reject(err);
+      this.handleError(err);
+    } finally {
+      this.isProcessingQueue = false;
+      setTimeout(() => this.processNextInQueue(), 0);
+    }
+  }
+  updateStatus(newStatus) {
+    this.status = newStatus;
+    this.statusCallbacks.forEach((cb) => cb(newStatus));
+  }
+  handleError(err) {
+    const errorObj = err instanceof Error ? err : new Error(String(err));
+    this.errorCallbacks.forEach((cb) => cb(errorObj));
+  }
+  triggerToken(token) {
+    this.tokenCallbacks.forEach((cb) => cb(token));
+  }
+  triggerRecommendation(rec) {
+    this.recommendationCallbacks.forEach((cb) => cb(rec));
+  }
+};
+export {
+  AnswerEngineClient
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@elelem/answer-engine-client",
+  "version": "1.0.0",
+  "description": "Zero-dependency client SDK for the Elelem Answer Engine Realtime API",
+  "main": "./dist/index.cjs.js",
+  "module": "./dist/index.esm.js",
+  "types": "./dist/index.d.ts",
+  "browser": "./dist/index.global.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.cjs.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm,iife --global-name AnswerEngine --dts --clean"
+  },
+  "peerDependencies": {
+    "socket.io-client": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.5",
+    "tsup": "^8.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elelem/answer-engine-client.git"
+  },
+  "keywords": [
+    "answer-engine",
+    "realtime",
+    "socket.io",
+    "sdk",
+    "elelem"
+  ],
+  "author": "Elelem AI",
+  "license": "MIT"
+}