npm - @equos/browser - Versions diffs - 1.0.1 - Mend

@equos/browser 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md +321 -0
package/dist/assets/worker-C27seias.js +1 -0
package/dist/assets/worker-tTICBjKA.js +1 -0
package/dist/index.d.ts +141 -0
package/dist/index.js +1 -0
package/package.json +52 -0

package/README.md ADDED Viewed

@@ -0,0 +1,321 @@
+# @equos/browser
+Browser SDK for building real-time conversational experiences with Equos characters. Provides audio and video pipelines that connect to the Equos platform via WebSocket.
+## Installation
+```bash
+npm install @equos/browser
+```
+### Peer dependencies
+The following packages must be installed by the consumer:
+```bash
+npm install onnxruntime-web @equos/audio-processor
+```
+## Quick start
+```ts
+import {
+  EquosPipelineFactory,
+  EquosPipelineEvents,
+  EquosUserAudioRecorder,
+} from '@equos/browser';
+import type { EquosPipelineConfig } from '@equos/browser';
+// 1. Create the pipeline
+const pipeline = EquosPipelineFactory.new({
+  accessToken: '<your-access-token>',
+  audio: { enabled: true },
+  video: {
+    enabled: true,
+    width: 450,
+    height: 800,
+    containerSelector: '#container',
+  },
+  debug: true,
+});
+// 2. Listen for events
+pipeline.on(EquosPipelineEvents.UTTERANCE, async (utterance) => {
+  console.log(`${utterance.author}: ${utterance.content}`);
+});
+pipeline.on(EquosPipelineEvents.ERROR, async (error) => {
+  console.error(`[${error.code}]: ${error.message}`);
+});
+// 3. Set up the microphone recorder
+const recorder = new EquosUserAudioRecorder((chunk) =>
+  pipeline.audio().pushUsrAudio(chunk),
+);
+// 4. Initialize both
+await Promise.all([pipeline.init(), recorder.init()]);
+// 5. Start a conversation
+await pipeline.start({});
+await recorder.start();
+// 6. Later — stop and clean up
+await recorder.stop();
+await pipeline.stop();
+await recorder.destroy();
+await pipeline.destroy();
+```
+## API reference
+### `EquosPipelineFactory`
+Static factory for creating pipeline instances.
+```ts
+const pipeline = EquosPipelineFactory.new(config);
+```
+### `EquosPipelineConfig`
+Configuration passed to `EquosPipelineFactory.new()`.
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `accessToken` | `string` | Yes | JWT token obtained from the Equos API. |
+| `audio` | `{ enabled: boolean }` | Yes | Whether audio output is enabled at creation. |
+| `video` | `object` | No | Video configuration (see below). |
+| `name` | `string` | No | Pipeline instance name (useful for debugging). |
+| `endpoint` | `string` | No | WebSocket endpoint URL. Defaults to the current host. |
+| `debug` | `boolean` | No | Enable debug logging to the console. |
+#### `video` object
+| Field | Type | Description |
+|---|---|---|
+| `enabled` | `boolean` | Whether video rendering is enabled at creation. |
+| `width` | `number` | Video canvas width in pixels. |
+| `height` | `number` | Video canvas height in pixels. |
+| `containerSelector` | `string` | CSS selector for the DOM element that will host the video. |
+### `EquosPipeline`
+Manages the full lifecycle of a real-time conversation session.
+#### Lifecycle methods
+| Method | Description |
+|---|---|
+| `init(): Promise<void>` | Initialize internal resources. Must be called before `start()`. |
+| `use(character: string): Promise<void>` | Select a character. Only needed when the access token is not scoped to a specific character. |
+| `start(conversation): Promise<void>` | Start a conversation session. |
+| `stop(): Promise<void>` | Stop the active conversation. The pipeline returns to a ready state and can be started again. |
+| `destroy(): Promise<void>` | Tear down all resources. The pipeline cannot be used after this. |
+| `getState(): EquosPipelineState` | Returns the current pipeline state. |
+#### `conversation` parameter
+The object passed to `start()` accepts the following optional fields:
+| Field | Type | Description |
+|---|---|---|
+| `prompt_ctx` | `string` | Additional context injected into the character prompt. |
+| `prompt_vars` | `Record<string, string>` | Key-value pairs substituted into prompt template variables. |
+| `max_seconds` | `number` | Maximum duration of the conversation in seconds. |
+#### Audio & video facades
+```ts
+// Audio
+pipeline.audio().enable();
+pipeline.audio().disable();
+pipeline.audio().pushUsrAudio(chunk); // Push a Float32Array audio chunk
+// Video
+pipeline.video().enable();
+pipeline.video().disable();
+```
+#### Events
+Register and unregister listeners with `on()` and `off()`:
+```ts
+pipeline.on(EquosPipelineEvents.UTTERANCE, callback);
+pipeline.off(EquosPipelineEvents.UTTERANCE, callback);
+```
+| Event | Callback signature | Description |
+|---|---|---|
+| `UTTERANCE` | `(utterance: EquosUtterance) => Promise<void>` | Fired when the agent or user produces an utterance. |
+| `INTERRUPT` | `() => Promise<void>` | Fired when the user interrupts the agent. |
+| `ERROR` | `(error: EquosPipelineError) => Promise<void>` | Fired on pipeline errors. |
+**`EquosUtterance`**
+| Field | Type | Description |
+|---|---|---|
+| `content` | `string` | The utterance text. |
+| `author` | `'agent' \| 'user'` | Who produced the utterance. |
+| `recordedAt` | `number` | Timestamp of the utterance. |
+### `EquosPipelineState`
+Enum representing the pipeline lifecycle.
+```
+CREATED → INITIALIZED → READY → STARTED → (back to READY on stop)
+                                          ↘ DESTROYED
+```
+| Value | Description |
+|---|---|
+| `CREATED` | Pipeline has been constructed but not initialized. |
+| `INITIALIZED` | `init()` has completed. |
+| `READY` | A character has been selected (via token or `use()`). Ready to start. |
+| `STARTED` | A conversation is active. |
+| `DESTROYED` | `destroy()` has been called. Terminal state. |
+### `EquosUserAudioRecorder`
+Captures microphone audio and forwards PCM chunks to the pipeline.
+```ts
+const recorder = new EquosUserAudioRecorder((chunk: Float32Array) => {
+  pipeline.audio().pushUsrAudio(chunk);
+});
+await recorder.init();    // Set up the AudioWorklet
+await recorder.start();   // Request mic permission and begin capture
+await recorder.stop();    // Stop capture and release the mic stream
+await recorder.destroy(); // Tear down the AudioContext
+```
+### `EquosPipelineError`
+Error class with a `code` property corresponding to `EquosPipelineErrors`.
+```ts
+pipeline.on(EquosPipelineEvents.ERROR, async (err) => {
+  console.error(err.code, err.message);
+});
+```
+### `EquosPipelineErrors`
+Enum of error codes.
+| Code | Meaning |
+|---|---|
+| `MUST_INIT` | `init()` must be called first. |
+| `MUST_USE` | `use()` must be called first (token has no character scope). |
+| `NOT_IDLE` | Operation requires the pipeline to be in `INITIALIZED` or `READY` state. |
+| `STARTED` | Operation cannot be performed while a conversation is active. |
+| `DESTROYED` | Operation cannot be performed after `destroy()`. |
+| `INVALID_TOKEN` | The access token could not be decoded. |
+| `CANNOT_USE_CHARACTER` | The token is scoped to a specific character; `use()` cannot override it. |
+| `NO_CONTAINER` | The video container element was not found in the DOM. |
+## Full example
+```ts
+import {
+  EquosPipelineFactory,
+  EquosPipeline,
+  EquosPipelineEvents,
+  EquosUserAudioRecorder,
+} from '@equos/browser';
+let pipeline: EquosPipeline | null = null;
+let recorder: EquosUserAudioRecorder | null = null;
+// ── Create & initialize ──────────────────────────────────
+async function initialize(accessToken: string) {
+  pipeline = EquosPipelineFactory.new({
+    name: 'example',
+    accessToken,
+    audio: { enabled: true },
+    video: {
+      enabled: true,
+      width: 450,
+      height: 800,
+      containerSelector: '#container',
+    },
+    debug: true,
+  });
+  pipeline.on(EquosPipelineEvents.UTTERANCE, async (u) => {
+    console.log(`Utterance (${u.author}): ${u.content}`);
+  });
+  pipeline.on(EquosPipelineEvents.INTERRUPT, async () => {
+    console.log('Interrupt');
+  });
+  pipeline.on(EquosPipelineEvents.ERROR, async (err) => {
+    console.error(`Error [${err.code}]: ${err.message}`);
+  });
+  recorder = new EquosUserAudioRecorder((chunk) =>
+    pipeline?.audio().pushUsrAudio(chunk),
+  );
+  await Promise.all([pipeline.init(), recorder.init()]);
+}
+// ── Start a conversation ─────────────────────────────────
+async function start() {
+  if (!pipeline || !recorder) return;
+  await pipeline.start({
+    prompt_ctx: 'The user is a first-time visitor.',
+    prompt_vars: { name: 'Alice' },
+    max_seconds: 300,
+  });
+  await recorder.start();
+}
+// ── Stop the conversation ────────────────────────────────
+async function stop() {
+  if (!pipeline || !recorder) return;
+  await recorder.stop();
+  await pipeline.stop();
+}
+// ── Toggle audio/video at runtime ────────────────────────
+async function toggleAudio(enabled: boolean) {
+  if (!pipeline) return;
+  if (enabled) {
+    await pipeline.audio().enable();
+  } else {
+    await pipeline.audio().disable();
+  }
+}
+async function toggleVideo(enabled: boolean) {
+  if (!pipeline) return;
+  if (enabled) {
+    await pipeline.video().enable();
+  } else {
+    await pipeline.video().disable();
+  }
+}
+// ── Tear down ────────────────────────────────────────────
+async function destroy() {
+  await recorder?.stop();
+  await recorder?.destroy();
+  await pipeline?.destroy();
+  pipeline = null;
+  recorder = null;
+}
+```

package/dist/assets/worker-C27seias.js ADDED Viewed

@@ -0,0 +1 @@

package/dist/assets/worker-tTICBjKA.js ADDED Viewed

@@ -0,0 +1 @@

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,141 @@
+declare interface Conversation {
+    prompt_ctx?: string;
+    prompt_vars?: Record<string, string>;
+    max_seconds?: number;
+}
+export declare abstract class EquosPipeline {
+    protected readonly config: EquosPipelineConfig;
+    private _state;
+    private listenerMap;
+    protected readonly endpoint: string;
+    protected readonly claims: EquosPipelineClaims;
+    protected character: string | null;
+    protected audioEnabled: boolean;
+    protected videoEnabled: boolean;
+    constructor(config: EquosPipelineConfig);
+    getState(): EquosPipelineState;
+    init(): Promise<void>;
+    use(character: string): Promise<void>;
+    start(conversation: Conversation): Promise<void>;
+    stop(): Promise<void>;
+    destroy(): Promise<void>;
+    on<E extends EquosPipelineEvents>(event: E, callback: EquosPipelineEventCallback<E>): void;
+    off<E extends EquosPipelineEvents>(event: E, callback: EquosPipelineEventCallback<E>): void;
+    protected emit<E extends EquosPipelineEvents>(event: E, ...args: Parameters<EquosPipelineEventCallback<E>>): Promise<void>;
+    video(): EquosPipelineVideoFacade;
+    audio(): EquosPipelineAudioFacade;
+    protected _info(msg: string): void;
+    protected _warn(msg: string): void;
+    private _getTokenClaims;
+    private _guardNotDestroyed;
+    private _guardReady;
+    private _guardReadyOrInitialized;
+    private _guardMandatoryCharacter;
+    protected abstract _init(): Promise<void>;
+    protected abstract _start(conversation: Conversation): Promise<void>;
+    protected abstract _stop(): Promise<void>;
+    protected abstract _destroy(): Promise<void>;
+    protected abstract _use(character: string): Promise<void>;
+    protected abstract _enableVideo(): Promise<void>;
+    protected abstract _disableVideo(): Promise<void>;
+    protected abstract _pushUsrAudio(chunk: Float32Array): Promise<void>;
+    protected abstract _enableAudio(): Promise<void>;
+    protected abstract _disableAudio(): Promise<void>;
+}
+export declare interface EquosPipelineAudioFacade {
+    pushUsrAudio(chunk: Float32Array): Promise<void>;
+    enable(): Promise<void>;
+    disable(): Promise<void>;
+}
+declare interface EquosPipelineClaims {
+    org: string;
+    user: string;
+    character?: string | null;
+}
+export declare interface EquosPipelineConfig {
+    name?: string;
+    accessToken: string;
+    audio: {
+        enabled: boolean;
+    };
+    video?: {
+        enabled: boolean;
+        height: number;
+        width: number;
+        containerSelector: string;
+    };
+    endpoint?: string;
+    debug?: boolean;
+}
+export declare class EquosPipelineError extends Error {
+    code: string;
+    constructor(message: string, code: string);
+}
+export declare enum EquosPipelineErrors {
+    MUST_INIT = "must call init()",
+    MUST_USE = "must call use()",
+    NOT_IDLE = "cannot call if not initialized or ready",
+    STARTED = "cannot call while started",
+    DESTROYED = "cannot call after destroy()",
+    INVALID_TOKEN = "could not read access token",
+    CANNOT_USE_CHARACTER = "pipeline is scoped to access token character",
+    NO_CONTAINER = "container not in DOM"
+}
+declare type EquosPipelineEventCallback<E extends EquosPipelineEvents> = EquosPipelineEventCallbackMap[E];
+declare type EquosPipelineEventCallbackMap = {
+    [EquosPipelineEvents.UTTERANCE]: (text: EquosUtterance) => Promise<void>;
+    [EquosPipelineEvents.INTERRUPT]: () => Promise<void>;
+    [EquosPipelineEvents.ERROR]: (error: EquosPipelineError) => Promise<void>;
+};
+export declare enum EquosPipelineEvents {
+    UTTERANCE = "utterance",
+    INTERRUPT = "interrupt",
+    ERROR = "error"
+}
+export declare class EquosPipelineFactory {
+    static new(config: EquosPipelineConfig): EquosPipeline;
+}
+export declare enum EquosPipelineState {
+    CREATED = "created",
+    INITIALIZED = "initialized",
+    READY = "ready",
+    STARTED = "started",
+    DESTROYED = "destroyed"
+}
+export declare interface EquosPipelineVideoFacade {
+    enable(): Promise<void>;
+    disable(): Promise<void>;
+}
+export declare class EquosUserAudioRecorder {
+    private readonly onAudio;
+    private ctx;
+    private stream;
+    private source;
+    private node;
+    constructor(onAudio: (chunk: Float32Array) => void);
+    init(): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    destroy(): Promise<void>;
+}
+declare interface EquosUtterance {
+    content: string;
+    author: 'agent' | 'user';
+    recordedAt: number;
+}
+export { }

package/dist/index.js ADDED Viewed

@@ -0,0 +1 @@

package/package.json ADDED Viewed

@@ -0,0 +1,52 @@
+{
+  "name": "@equos/browser",
+  "version": "1.0.1",
+  "description": "",
+  "license": "ISC",
+  "author": "",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "lint": "eslint \"src/**/*.ts\" --fix",
+    "prepublishOnly": "npm run lint && npm run build",
+    "test": "node tests",
+    "start": "npx serve ."
+  },
+  "devDependencies": {
+    "@equos/node-sdk": "^3.1.1-rc.1",
+    "@types/audioworklet": "^0.0.96",
+    "@types/dom-webcodecs": "^0.1.18",
+    "@eslint/js": "^9.0.0",
+    "@webgpu/types": "^0.1.69",
+    "eslint": "^10.0.0",
+    "eslint-config-prettier": "^10.0.0",
+    "eslint-plugin-prettier": "^5.0.0",
+    "typescript-eslint": "^8.56.0",
+    "javascript-obfuscator": "^5.3.0",
+    "prettier": "^3.8.1",
+    "terser": "^5.46.0",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-plugin-static-copy": "^3.2.0",
+    "vite-plugin-top-level-await": "^1.6.0",
+    "vite-plugin-wasm": "^3.5.0"
+  },
+  "peerDependencies": {
+    "@equos/audio-processor": "^0.2.1",
+    "onnxruntime-web": "^1.24.3"
+  }
+}