@nuancelabs/js-sdk 0.14.1 → 0.15.0

package/index.d.ts

@@ -739,8 +739,8 @@ export declare interface SessionPersonality {
 
 /**
  * What your server sends to `POST /session-tokens` with its API key. Every
- * field is fixed for the conversation the token starts; send `{}` for the
- * defaults.
+ * field is fixed for the conversation the token starts. Send `end_user_id`
+ * with every token; leave the other fields out for the defaults.
  */
 export declare interface SessionTokenRequest {
     /** Who the avatar is in the conversation. Leave it out for the default personality. */

package/index.js

@@ -4,7 +4,7 @@ function isRecord(value) {
 }
 
 // src/core/sdk-version.ts
-var SDK_HEADER = `js/${"0.14.1"}`;
+var SDK_HEADER = `js/${"0.15.0"}`;
 
 // src/utils.ts
 function normalizeHost(host) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuancelabs/js-sdk",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "JavaScript SDK for Nuance Labs conversation video AI avatar",
   "license": "UNLICENSED",
   "repository": {
@@ -16,10 +16,22 @@
     ".": {
       "types": "./index.d.ts",
       "import": "./index.js"
+    },
+    "./react": {
+      "types": "./react/index.d.ts",
+      "import": "./react/index.js"
     }
   },
   "sideEffects": false,
   "dependencies": {
     "livekit-client": "^2.18.4"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   }
 }

package/react/index.d.ts

@@ -0,0 +1,52 @@
+import type { Conversation } from '@nuancelabs/js-sdk';
+import type { ConversationStateValue } from '@nuancelabs/js-sdk';
+import type { CreateNuanceConversationOptions } from '@nuancelabs/js-sdk';
+
+/** What {@link useNuanceConversation} returns. */
+export declare interface NuanceConversationHook {
+    /** The conversation's state; `"idle"` before the first start. */
+    readonly state: ConversationStateValue;
+    /**
+     * Why the last start or end failed, as thrown: test it with `instanceof`
+     * (`ApiError`, `MediaAccessError`, ...). Null after a start succeeds.
+     */
+    readonly error: Error | null;
+    /**
+     * The latest conversation, for anything the hook does not cover; kept after
+     * it ends, for its id. Null before the first start.
+     */
+    readonly conversation: Conversation | null;
+    /** Pass to a `<video>`'s `ref`: the avatar's video plays there. */
+    readonly videoRef: (element: HTMLVideoElement | null) => void;
+    /** Pass to an `<audio autoPlay>`'s `ref`: the avatar's voice plays there. */
+    readonly audioRef: (element: HTMLAudioElement | null) => void;
+    /** Starts a conversation, ending any current one. Call it from a click. */
+    readonly start: () => Promise<void>;
+    /** Ends the current conversation. */
+    readonly end: () => Promise<void>;
+}
+
+/**
+ * One conversation at a time in a React component: its state and error, refs
+ * for the elements the avatar plays in, and start and end. The hook leaves the
+ * conversation when the session ends (so the camera and microphone turn off)
+ * and when the component unmounts. Each start uses the options of the latest
+ * render.
+ *
+ * @example
+ * ```tsx
+ * const { state, error, videoRef, audioRef, start, end } =
+ *   useNuanceConversation({ token: fetchToken });
+ *
+ * return (
+ *   <>
+ *     <video ref={videoRef} autoPlay playsInline />
+ *     <audio ref={audioRef} autoPlay />
+ *     <button onClick={start}>Start</button>
+ *   </>
+ * );
+ * ```
+ */
+export declare function useNuanceConversation(options: CreateNuanceConversationOptions): NuanceConversationHook;
+
+export { }

package/react/index.js

@@ -0,0 +1,166 @@
+// src/react/index.ts
+import { useEffect, useState, useSyncExternalStore } from "react";
+
+// src/react/store.ts
+import {
+  createNuanceConversation
+} from "@nuancelabs/js-sdk";
+var IDLE = {
+  state: "idle",
+  error: null,
+  conversation: null
+};
+function asError(cause) {
+  return cause instanceof Error ? cause : new Error(String(cause));
+}
+
+class ConversationStore {
+  options;
+  create;
+  snapshot = IDLE;
+  listeners = new Set;
+  current = null;
+  unsubscribe = null;
+  video = null;
+  audio = null;
+  playingVideo = null;
+  playingAudio = null;
+  leaving = Promise.resolve();
+  constructor(options, create = createNuanceConversation) {
+    this.options = options;
+    this.create = create;
+  }
+  setOptions(options) {
+    this.options = options;
+  }
+  subscribe = (listener) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+  getSnapshot = () => this.snapshot;
+  setVideo = (element) => {
+    if (element === this.video)
+      return;
+    this.playingVideo?.detach();
+    this.playingVideo = null;
+    this.video = element;
+    this.attach();
+  };
+  setAudio = (element) => {
+    if (element === this.audio)
+      return;
+    this.playingAudio?.detach();
+    this.playingAudio = null;
+    this.audio = element;
+    this.attach();
+  };
+  start = async () => {
+    let conversation;
+    try {
+      conversation = this.create(this.options);
+    } catch (cause) {
+      this.update({ error: asError(cause) });
+      return;
+    }
+    const previous = this.release();
+    this.current = conversation;
+    this.unsubscribe = conversation.onChange((event) => {
+      if (this.current !== conversation)
+        return;
+      if (event.type === "state-changed")
+        this.update({ state: event.state });
+      if (event.type === "tracks-changed")
+        this.attach();
+      if (event.type === "session-ended")
+        this.end();
+    });
+    this.update({ state: conversation.state, error: null, conversation });
+    if (previous)
+      this.leave(previous).catch(() => {});
+    await this.leaving;
+    if (this.current !== conversation)
+      return;
+    try {
+      await conversation.connect();
+    } catch (cause) {
+      if (this.current === conversation)
+        this.update({ error: asError(cause) });
+    }
+  };
+  end = async () => {
+    const conversation = this.release();
+    if (!conversation)
+      return;
+    try {
+      await this.leave(conversation);
+    } catch (cause) {
+      if (this.current === null)
+        this.update({ error: asError(cause) });
+    }
+    if (this.current === null)
+      this.update({ state: conversation.state });
+  };
+  leave(conversation) {
+    const done = conversation.disconnect();
+    this.leaving = Promise.all([this.leaving, done.catch(() => {})]);
+    return done;
+  }
+  release() {
+    const conversation = this.current;
+    this.unsubscribe?.();
+    this.unsubscribe = null;
+    this.current = null;
+    this.playingVideo?.detach();
+    this.playingAudio?.detach();
+    this.playingVideo = null;
+    this.playingAudio = null;
+    return conversation;
+  }
+  attach() {
+    const conversation = this.current;
+    if (!conversation)
+      return;
+    let avatar;
+    try {
+      avatar = conversation.avatar;
+    } catch {
+      return;
+    }
+    const { videoTrack, audioTrack } = avatar;
+    if (this.video && videoTrack && videoTrack !== this.playingVideo) {
+      this.playingVideo?.detach();
+      videoTrack.attach(this.video);
+      this.playingVideo = videoTrack;
+    }
+    if (this.audio && audioTrack && audioTrack !== this.playingAudio) {
+      this.playingAudio?.detach();
+      audioTrack.attach(this.audio);
+      this.playingAudio = audioTrack;
+    }
+  }
+  update(change) {
+    this.snapshot = { ...this.snapshot, ...change };
+    for (const listener of this.listeners)
+      listener();
+  }
+}
+
+// src/react/index.ts
+function useNuanceConversation(options) {
+  const [store] = useState(() => new ConversationStore(options));
+  useEffect(() => store.setOptions(options));
+  const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+  useEffect(() => () => {
+    store.end();
+  }, [store]);
+  return {
+    ...snapshot,
+    videoRef: store.setVideo,
+    audioRef: store.setAudio,
+    start: store.start,
+    end: store.end
+  };
+}
+export {
+  useNuanceConversation
+};