@nuancelabs/js-sdk 0.5.0 → 0.9.0

package/index.d.ts

@@ -212,6 +212,8 @@ export declare type ConversationEvent =
 * Emitted only while waiting. `estimatedWaitSeconds` never increases for a
 * given session: a wait that grows reads as the service failing, and arriving
 * early is forgiven. Null when there is no serving capacity to estimate from.
+* `preparing` is true once the session is next and an avatar is held for it
+* while it gets ready; the session connects when it is.
 */
 /**
 * How long the live session has left, when it is capped.
@@ -229,16 +231,20 @@ export declare type ConversationEvent =
 * A runtime that stops at its limit does not necessarily leave the transport,
 * so a caller cannot infer this from the connection alone. `reason` is
 * `"time-limit"` when the session was capped and ran out its clock,
-* `"policy-violation"` when the runtime ended it for content.
+* `"policy-violation"` when the runtime ended it for content, `"refused"`
+* when the runtime would not start it, with its reason in `message` when it
+* gave one.
 */
 | {
     type: "session-ended";
     reason: SessionEndReason;
+    message?: string;
 } | {
     type: "queue-changed";
     position: number;
     estimatedWaitSeconds: number | null;
     poolSlots: number | null;
+    preparing: boolean;
 };
 
 /**
@@ -338,6 +344,12 @@ export declare interface CreateNuanceConversationOptions {
      * ```
      */
     personality?: PersonalityChoice;
+    /**
+     * The longest the conversation may run, in seconds. The server holds it to
+     * the account's maximum, so a longer value runs for that maximum; left out,
+     * the conversation runs for the maximum.
+     */
+    maxSessionSeconds?: number;
     /**
      * Capture constraints for the user's camera.
      *
@@ -444,9 +456,10 @@ export declare class PolicyCurfewError extends Error {
 /**
  * Why a session is over. `"time-limit"`: the capped session ran out its clock.
  * `"policy-violation"`: the runtime ended it for content that breaks the usage
- * policy. `"ended"`: any other server-side end.
+ * policy. `"refused"`: the runtime would not start it, for the reason in the
+ * event's `message`. `"ended"`: any other server-side end.
  */
-export declare type SessionEndReason = "time-limit" | "ended" | "policy-violation" | "connection-lost";
+export declare type SessionEndReason = "time-limit" | "ended" | "policy-violation" | "refused" | "connection-lost";
 
 
 
@@ -458,6 +471,12 @@ export declare interface SessionPersonality {
      * before a call, in plain text.
      */
     system_prompt?: string;
+    /**
+     * The face the avatar is drawn as, by the id Nuance gave your organization.
+     * Leave it out for the default face. A face your organization has not been
+     * given is refused when the token is minted.
+     */
+    face_id?: string;
 }
 
 /**

package/index.js

@@ -4,7 +4,7 @@ function isRecord(value) {
 }
 
 // src/core/sdk-version.ts
-var SDK_HEADER = `js/${"0.5.0"}`;
+var SDK_HEADER = `js/${"0.9.0"}`;
 
 // src/utils.ts
 function normalizeHost(host) {
@@ -1063,6 +1063,9 @@ function endReason(reason) {
     return "policy-violation";
   if (reason === "time_limit")
     return "time-limit";
+  if (reason === "invalid_spec" || reason === "runtime_failed") {
+    return "refused";
+  }
   return "ended";
 }
 function parseSessionEvent(payload) {
@@ -1093,7 +1096,15 @@ function parseSessionEvent(payload) {
     };
   }
   if (decoded.type === "error" && decoded.fatal === true) {
-    return { type: "ended", reason: endReason(decoded.code), byClient: false };
+    const ended = {
+      type: "ended",
+      reason: endReason(decoded.code),
+      byClient: false
+    };
+    if (typeof decoded.message === "string" && decoded.message !== "") {
+      ended.message = decoded.message;
+    }
+    return ended;
   }
   if (decoded.type === "error" && decoded.code === "bad_command") {
     return { type: "command-unreadable" };
@@ -1528,6 +1539,7 @@ var CLOCK_SYNC_TOPIC = "clock-sync";
 var STATS_FLUSH_TIMEOUT_MS = 300;
 var SESSION_END_TIMEOUT_MS = 300;
 var SESSION_END_ID = "client-session-end";
+var REFUSAL_REASON_WAIT_MS = 500;
 var COMMAND_TIMEOUT_MS = 5000;
 var BACKGROUND_ID = /^[a-z0-9][a-z0-9_-]{0,63}$/;
 var AVATAR_RETURN_TIMEOUT_MS = 8000;
@@ -1578,6 +1590,7 @@ class LiveKitConversation {
   network = "good";
   eventsRegistered = false;
   sessionEnded = false;
+  refusal = null;
   speaksProtocol = false;
   avatarSpeaking = false;
   answered = null;
@@ -1698,6 +1711,7 @@ class LiveKitConversation {
     this.stopReadyFallback();
     this.stopLayerFallback();
     this.clearAway();
+    this.stopRefusal();
     this._user?.cleanup();
     this._user?.releaseDevices();
     await this.flushStats();
@@ -1731,6 +1745,15 @@ class LiveKitConversation {
       throw new Error("Nothing to send: the text is blank");
     return this.command({ type: "input.text", text: line, respond: true });
   }
+  async holdAgent() {
+    await this.command({ type: "agent.stop" }).catch(() => {
+      return;
+    });
+    return this.command({ type: "floor.hold" });
+  }
+  async releaseAgent() {
+    return this.command({ type: "floor.release" });
+  }
   onChange(handler) {
     return this.onEvent((event) => {
       if (event.type !== "data-event" && event.type !== "screen-share-changed")
@@ -1976,12 +1999,16 @@ class LiveKitConversation {
     } else if (event.type === "ended") {
       this.answered?.();
       if (!event.byClient)
-        this.reportEnd(event.reason);
+        this.reportEnd(event.reason, event.message);
     }
   }
   handleRuntimeSignal(payload) {
     const signal = parseRuntimeSignal(payload);
     if (signal?.type === "session-ended") {
+      if (signal.reason === "refused") {
+        this.refusal ??= setTimeout(() => this.reportEnd("refused"), REFUSAL_REASON_WAIT_MS);
+        return;
+      }
       this.reportEnd(signal.reason);
     } else if (signal?.type === "output-ready") {
       this.markAvatarReady();
@@ -2120,11 +2147,18 @@ class LiveKitConversation {
     this.presentation?.stop();
     this.presentation = null;
   }
-  reportEnd(reason) {
+  reportEnd(reason, message) {
+    this.stopRefusal();
     if (this.sessionEnded)
       return;
     this.sessionEnded = true;
-    this.emit({ type: "session-ended", reason });
+    this.emit(message === undefined ? { type: "session-ended", reason } : { type: "session-ended", reason, message });
+  }
+  stopRefusal() {
+    if (this.refusal === null)
+      return;
+    clearTimeout(this.refusal);
+    this.refusal = null;
   }
   handleClockSyncPing(payload) {
     const reply = clockSyncPong(payload, Date.now() / 1000, () => Date.now() / 1000);
@@ -2202,6 +2236,7 @@ class NuanceConversation {
   sessionOverrides;
   personality;
   variant;
+  maxSessionSeconds;
   videoCapture;
   startOn;
   mediaDevices;
@@ -2239,6 +2274,7 @@ class NuanceConversation {
     this.sessionOverrides = options.sessionOverrides ?? {};
     this.personality = options.personality;
     this.variant = options.variant;
+    this.maxSessionSeconds = options.maxSessionSeconds;
     this.videoCapture = options.videoCapture;
     this.startOn = options.startOn ?? "first-frame";
     this.mediaDevices = options.mediaDevices;
@@ -2275,6 +2311,9 @@ class NuanceConversation {
           request.personality = this.personality;
         if (this.variant)
           request.variant = this.variant;
+        if (this.maxSessionSeconds !== undefined) {
+          request.max_session_seconds = this.maxSessionSeconds;
+        }
         conversation = await this.createWhenNotBusy(request, attempt);
       } catch (error) {
         if (error instanceof ApiError && error.status === 409) {
@@ -2305,10 +2344,10 @@ class NuanceConversation {
           this.setState(event.state);
           return;
         }
-        if (event.type === "session-ended" && event.reason === "connection-lost") {
+        if (event.type === "session-ended" && (event.reason === "connection-lost" || event.reason === "refused")) {
           const held = this.held;
           this.held = null;
-          this.endSession(event.reason);
+          this.endSession(event.reason, event.message);
           this.disconnect().catch(() => {});
           if (held !== null) {
             this.api.abandonConversation(held).catch(() => {});
@@ -2316,7 +2355,7 @@ class NuanceConversation {
           return;
         }
         if (event.type === "session-ended") {
-          this.endSession(event.reason);
+          this.endSession(event.reason, event.message);
           return;
         }
         this.emit(event);
@@ -2379,6 +2418,18 @@ class NuanceConversation {
     }
     return this.delegate.sendText(text);
   }
+  async holdAgent() {
+    if (!this.delegate) {
+      throw new Error("Not connected — call connect() first");
+    }
+    return this.delegate.holdAgent();
+  }
+  async releaseAgent() {
+    if (!this.delegate) {
+      throw new Error("Not connected — call connect() first");
+    }
+    return this.delegate.releaseAgent();
+  }
   onChange(handler) {
     return this.onEvent((event) => {
       if (event.type !== "data-event" && event.type !== "screen-share-changed")
@@ -2455,7 +2506,7 @@ class NuanceConversation {
             throw new TerminalStatusError(event.reason);
           }
           if (event.type === "queued" && event.position != null) {
-            this.reportPlace(event.position, event.estimated_wait_seconds ?? null, null);
+            this.reportPlace(event.position, event.estimated_wait_seconds ?? null, null, event.preparing ?? false);
           }
         }
       }
@@ -2639,9 +2690,9 @@ class NuanceConversation {
     if (state.status !== "queued" || state.position == null) {
       return;
     }
-    this.reportPlace(state.position, state.estimated_wait_seconds ?? null, state.pool_slots ?? null);
+    this.reportPlace(state.position, state.estimated_wait_seconds ?? null, state.pool_slots ?? null, state.preparing ?? false);
   }
-  reportPlace(position, estimate, poolSlots) {
+  reportPlace(position, estimate, poolSlots, preparing) {
     if (this._state !== "queued") {
       this.setState("queued");
     }
@@ -2649,7 +2700,8 @@ class NuanceConversation {
       type: "queue-changed",
       position,
       estimatedWaitSeconds: this.smoothEstimate(position, estimate),
-      poolSlots
+      poolSlots,
+      preparing
     });
   }
   smoothEstimate(position, estimate) {
@@ -2685,14 +2737,14 @@ class NuanceConversation {
     }
     await this.api.abandonConversation(held).catch(() => {});
   }
-  endSession(reason) {
+  endSession(reason, message) {
     if (this.ended) {
       return;
     }
     this.ended = true;
     this.clearLimit();
     this.stopHeartbeat();
-    this.emit({ type: "session-ended", reason });
+    this.emit(message === undefined ? { type: "session-ended", reason } : { type: "session-ended", reason, message });
   }
   stopHeartbeat() {
     this.stopBeats?.();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuancelabs/js-sdk",
-  "version": "0.5.0",
+  "version": "0.9.0",
   "description": "JavaScript SDK for Nuance Labs conversation video AI avatar",
   "license": "UNLICENSED",
   "repository": {