@nuancelabs/js-sdk 0.1.2 → 0.2.1

package/index.d.ts

@@ -157,10 +157,10 @@ export declare type ConversationEvent =
     type: "avatar-ready";
 }
 /**
-* The avatar is presented as she should be seen: her video has reached its
-* full size and held it, or the wait for it ran out. Follows `avatar-ready`.
-* The session opens on it: her first words, and its recording. Reveal her
-* fully on this; between the two she is in view but not yet speaking.
+* The avatar starts speaking: her first words, and the session's recording.
+* Follows `avatar-ready`, at once by default. With `startOn: "full-quality"`
+* it waits until her video has reached its full size and held it, or the
+* wait ran out; in between she is in view but not yet speaking.
 */
 | {
     type: "avatar-presented";
@@ -296,6 +296,9 @@ export declare type ConversationStateValue = `${ConversationState}`;
  */
 export declare function createNuanceConversation(options?: CreateNuanceConversationOptions): Conversation;
 
+/**
+ * Options for creating a Nuance conversation.
+ */
 export declare interface CreateNuanceConversationOptions {
     /**
      * Fetches a session token, for authenticating from a web page.
@@ -324,6 +327,20 @@ export declare interface CreateNuanceConversationOptions {
     videoCapture?: VideoCaptureConstraints;
     /** Local capture preferences, resolved once for each connection attempt. */
     mediaDevices?: MediaDevicePreferences | (() => MediaDevicePreferences);
+    /**
+     * When the avatar starts speaking.
+     *
+     * - `"first-frame"`: as soon as her first frame reaches the page.
+     *   `avatar-presented` follows `avatar-ready` at once. Her video may be
+     *   soft for its first few seconds while the connection ramps up.
+     * - `"full-quality"`: once her video has reached its full size and held
+     *   it, or after at most about 12 seconds. She is in view but silent in
+     *   between, so a page using this should cover her until
+     *   `avatar-presented`.
+     *
+     * @defaultValue `"first-frame"`
+     */
+    startOn?: StartOn;
 }
 
 
@@ -412,6 +429,9 @@ export declare type SessionEndReason = "time-limit" | "ended" | "policy-violatio
 
 
 
+/** When the avatar starts speaking: see {@link CreateNuanceConversationOptions.startOn}. */
+export declare type StartOn = "first-frame" | "full-quality";
+
 
 /**
  * The local user participant in a conversation.

package/index.js

@@ -4,7 +4,7 @@ function isRecord(value) {
 }
 
 // src/core/sdk-version.ts
-var SDK_HEADER = `js/${"0.1.2"}`;
+var SDK_HEADER = `js/${"0.2.1"}`;
 
 // src/utils.ts
 function normalizeHost(host) {
@@ -2086,6 +2086,8 @@ var DEFAULT_HOST = "https://api.nuancelabs.ai";
 var QUEUE_HEARTBEAT_INTERVAL_MS = 5000;
 var HEARTBEAT_INTERVAL_MS = 5000;
 var ADMISSION_FAILED_BEATS = 6;
+var BUSY_RETRY_LIMIT_MS = 60000;
+var BUSY_RETRY_DEFAULT_MS = 3000;
 var LOST_WINDOW_MS = 30000;
 function createNuanceConversation(options = {}) {
   return new NuanceConversation(options);
@@ -2115,6 +2117,9 @@ function isLegalRequiredBody(body) {
 function isMaintenanceBody(body) {
   return isRecord(body) && body.code === "maintenance";
 }
+function isBusyBody(body) {
+  return isRecord(body) && body.code === "busy";
+}
 function isCurfewBody(body) {
   return isRecord(body) && body.code === "policy_curfew";
 }
@@ -2141,6 +2146,7 @@ class NuanceConversation {
   personality;
   variant;
   videoCapture;
+  startOn;
   mediaDevices;
   resilientReconnect;
   delegate = null;
@@ -2176,6 +2182,7 @@ class NuanceConversation {
     this.personality = options.personality;
     this.variant = options.variant;
     this.videoCapture = options.videoCapture;
+    this.startOn = options.startOn ?? "first-frame";
     this.mediaDevices = options.mediaDevices;
     this.resilientReconnect = options.resilientReconnect ?? false;
   }
@@ -2201,7 +2208,7 @@ class NuanceConversation {
       try {
         const request = {
           session_overrides: this.sessionOverrides,
-          client_ready: true
+          client_ready: this.startOn === "full-quality"
         };
         const timezone = this.timezone();
         if (timezone)
@@ -2210,7 +2217,7 @@ class NuanceConversation {
           request.personality = this.personality;
         if (this.variant)
           request.variant = this.variant;
-        conversation = await this.api.createConversation(request);
+        conversation = await this.createWhenNotBusy(request, attempt);
       } catch (error) {
         if (error instanceof ApiError && error.status === 409) {
           throw new ActiveSessionError;
@@ -2352,6 +2359,26 @@ class NuanceConversation {
       resilientReconnect: this.resilient
     });
   }
+  async createWhenNotBusy(request, attempt) {
+    const giveUpAt = Date.now() + BUSY_RETRY_LIMIT_MS;
+    for (;; ) {
+      try {
+        return await this.api.createConversation(request);
+      } catch (error) {
+        if (!(error instanceof ApiError) || error.status !== 503 || !isBusyBody(error.body) || attempt !== this.attempt) {
+          throw error;
+        }
+        const waitMs = typeof error.body.retry_after_seconds === "number" ? error.body.retry_after_seconds * 1000 : BUSY_RETRY_DEFAULT_MS;
+        if (Date.now() + waitMs > giveUpAt)
+          throw error;
+        if (this._state !== "queued")
+          this.setState("queued");
+        await new Promise((resolve) => setTimeout(resolve, waitMs));
+        if (attempt !== this.attempt)
+          throw error;
+      }
+    }
+  }
   startHeartbeat(conversationId, intervalMs) {
     this.stopHeartbeat();
     this.failedBeats = 0;

package/package.json

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