@voice-ai-labs/web-sdk 0.5.0 → 0.7.0

package/README.md

@@ -267,12 +267,17 @@ const stats = await voiceai.analytics.getStatsSummary();
 
 ## Webhooks
 
-Configure webhooks to receive real-time notifications when call events occur.
+Configure webhooks when creating or updating an agent.
 
-### Configure Webhook Events
+`webhooks.events` and `webhooks.tools` use different contracts:
+
+- `webhooks.events` supports `secret` (write-only on create/update) and `has_secret` (read-only on fetch).
+- `webhooks.tools` define outbound API calls and do not use `secret`.
+
+### Configure Webhook Events and Tools
 
 ```typescript
-// Create agent with webhook events
+// Create agent with webhook events and tools
 const agent = await voiceai.agents.create({
   name: 'Support Agent',
   config: {
@@ -280,11 +285,36 @@ const agent = await voiceai.agents.create({
     webhooks: {
       events: {
         url: 'https://your-server.com/webhooks/voice-events',
-        secret: 'your-hmac-secret',  // Optional: for signature verification
+        secret: 'your-hmac-secret',  // Event webhook signing secret
         events: ['call.started', 'call.completed'],  // Or omit for all events
         timeout: 5,
         enabled: true
-      }
+      },
+      tools: [
+        {
+          name: 'get_account_status',
+          description: 'Fetches current account status for a customer.',
+          url: 'https://your-server.com/webhooks/tools/account-status',
+          parameters: {
+            customer_id: 'string'
+          },
+          method: 'POST',
+          execution_mode: 'sync',
+          auth_type: 'api_key',
+          auth_token: 'your-api-key',
+          headers: {
+            'X-Service-Version': '2026-02'
+          },
+          response: {
+            type: 'object',
+            properties: {
+              status: { type: 'string' },
+              tier: { type: 'string' }
+            }
+          },
+          timeout: 10
+        }
+      ]
     }
   }
 });
@@ -297,12 +327,33 @@ await voiceai.agents.update(agentId, {
         url: 'https://your-server.com/webhooks',
         events: ['call.completed'],  // Only receive call.completed
         enabled: true
-      }
+      },
+      tools: [
+        {
+          name: 'search_knowledge_base',
+          description: 'Searches KB and returns ranked snippets.',
+          url: 'https://your-server.com/webhooks/tools/search-kb',
+          parameters: {
+            query: 'string',
+            top_k: 'number'
+          },
+          method: 'GET',
+          execution_mode: 'async',
+          auth_type: 'custom_headers',
+          headers: {
+            'X-Internal-Token': 'your-internal-token'
+          },
+          timeout: 20
+        }
+      ]
     }
   }
 });
 ```
 
+Required fields for each webhook tool: `name`, `description`, `parameters`, `url`, `method`, `execution_mode`, `auth_type`.  
+Optional fields: `auth_token`, `headers`, `response`, `timeout`.
+
 ### Event Types
 
 | Event | Description |
@@ -310,9 +361,9 @@ await voiceai.agents.update(agentId, {
 | `call.started` | Call connected, agent ready |
 | `call.completed` | Call ended, includes transcript and usage data |
 
-### Webhook Payload
+### Event Webhook Payload
 
-Your server receives POST requests with this structure:
+Your event webhook URL receives POST requests with this structure:
 
 ```typescript
 interface WebhookEvent {
@@ -328,14 +379,57 @@ interface WebhookEvent {
 }
 ```
 
-### Signature Verification
+### Webhook Tool Request Shape
+
+For webhook tools, Voice.ai makes outbound HTTP requests directly to each tool `url`.
+
+- `method: 'GET'`: tool arguments are sent as query parameters.
+- `method: 'POST' | 'PUT' | 'PATCH' | 'DELETE'`: tool arguments are sent as JSON body.
+- Metadata headers are always sent:
+  - `X-VoiceAI-Request-Id`
+  - `X-VoiceAI-Tool-Name`
+  - `X-VoiceAI-Agent-Id`
+  - `X-VoiceAI-Call-Id`
+
+```http
+GET /webhooks/tools/search-kb?query=refund+policy&top_k=3
+X-VoiceAI-Request-Id: req_123
+X-VoiceAI-Tool-Name: search_knowledge_base
+X-VoiceAI-Agent-Id: agent_123
+X-VoiceAI-Call-Id: call_123
+```
+
+```http
+POST /webhooks/tools/account-status
+Content-Type: application/json
+X-VoiceAI-Request-Id: req_456
+X-VoiceAI-Tool-Name: get_account_status
+X-VoiceAI-Agent-Id: agent_123
+X-VoiceAI-Call-Id: call_123
+
+{"customer_id":"cust_789"}
+```
+
+### Webhook Tool Authentication
+
+- `auth_type: 'none'`: no auth headers added.
+- `auth_type: 'bearer_token'`: sends `Authorization: Bearer <auth_token>`.
+- `auth_type: 'api_key'`: sends `X-API-Key: <auth_token>`.
+- `auth_type: 'custom_headers'`: sends your configured `headers` map.
+
+### Webhook Tool Response Behavior
+
+- `execution_mode: 'sync'`: waits for downstream response body; non-2xx fails the tool call.
+- `execution_mode: 'async'`: treats any 2xx as accepted and does not require a response payload.
+
+### Signature Verification (Event Webhooks)
 
-If you configure a `secret`, verify the HMAC-SHA256 signature:
+If you configure `webhooks.events.secret`, verify the HMAC-SHA256 signature:
 
 ```typescript
 import crypto from 'crypto';
 
-function verifyWebhook(body: string, headers: Headers, secret: string): boolean {
+function verifyEventWebhook(body: string, headers: Headers, secret: string): boolean {
   const signature = headers.get('x-webhook-signature');
   const timestamp = headers.get('x-webhook-timestamp');
   

package/dist/index.esm.js

@@ -7200,6 +7200,7 @@ var LoggerNames;
   LoggerNames["PCManager"] = "livekit-pc-manager";
   LoggerNames["PCTransport"] = "livekit-pc-transport";
   LoggerNames["E2EE"] = "lk-e2ee";
+  LoggerNames["DataTracks"] = "livekit-data-tracks";
 })(LoggerNames || (LoggerNames = {}));
 let livekitLogger = loglevelExports.getLogger('livekit');
 Object.values(LoggerNames).map(name => loglevelExports.getLogger(name));
@@ -10701,7 +10702,7 @@ function getMatch(exp, ua) {
 }
 function getOSVersion(ua) {
   return ua.includes('mac os') ? getMatch(/\(.+?(\d+_\d+(:?_\d+)?)/, ua, 1).replace(/_/g, '.') : undefined;
-}var version$1 = "2.17.1";const version = version$1;
+}var version$1 = "2.17.2";const version = version$1;
 const protocolVersion = 16;/** Base error that all LiveKit specific custom errors inherit from. */
 class LivekitError extends Error {
   constructor(code, message, options) {
@@ -15625,6 +15626,7 @@ class PCTransport extends eventsExports.EventEmitter {
             yield this._pc.setRemoteDescription(currentSD);
           } else {
             this.renegotiate = true;
+            this.log.debug('requesting renegotiation', Object.assign({}, this.logContext));
             return;
           }
         } else if (!this._pc || this._pc.signalingState === 'closed') {
@@ -16225,25 +16227,41 @@ class PCTransportManager {
   negotiate(abortController) {
     return __awaiter(this, void 0, void 0, function* () {
       return new TypedPromise((resolve, reject) => __awaiter(this, void 0, void 0, function* () {
-        const negotiationTimeout = setTimeout(() => {
+        let negotiationTimeout = setTimeout(() => {
           reject(new NegotiationError('negotiation timed out'));
         }, this.peerConnectionTimeout);
-        const abortHandler = () => {
+        const cleanup = () => {
           clearTimeout(negotiationTimeout);
+          this.publisher.off(PCEvents.NegotiationStarted, onNegotiationStarted);
+          abortController.signal.removeEventListener('abort', abortHandler);
+        };
+        const abortHandler = () => {
+          cleanup();
           reject(new NegotiationError('negotiation aborted'));
         };
-        abortController.signal.addEventListener('abort', abortHandler);
-        this.publisher.once(PCEvents.NegotiationStarted, () => {
+        // Reset the timeout each time a renegotiation cycle starts. This
+        // prevents premature timeouts when the negotiation machinery is
+        // actively renegotiating (offers going out, answers coming back) but
+        // NegotiationComplete hasn't fired yet because new requirements keep
+        // arriving between offer/answer round-trips.
+        const onNegotiationStarted = () => {
           if (abortController.signal.aborted) {
             return;
           }
-          this.publisher.once(PCEvents.NegotiationComplete, () => {
-            clearTimeout(negotiationTimeout);
-            resolve();
-          });
+          clearTimeout(negotiationTimeout);
+          negotiationTimeout = setTimeout(() => {
+            cleanup();
+            reject(new NegotiationError('negotiation timed out'));
+          }, this.peerConnectionTimeout);
+        };
+        abortController.signal.addEventListener('abort', abortHandler);
+        this.publisher.on(PCEvents.NegotiationStarted, onNegotiationStarted);
+        this.publisher.once(PCEvents.NegotiationComplete, () => {
+          cleanup();
+          resolve();
         });
         yield this.publisher.negotiate(e => {
-          clearTimeout(negotiationTimeout);
+          cleanup();
           if (e instanceof Error) {
             reject(e);
           } else {
@@ -16739,6 +16757,7 @@ class LocalTrack extends Track {
     let loggerOptions = arguments.length > 4 ? arguments[4] : undefined;
     super(mediaTrack, kind, loggerOptions);
     this.manuallyStopped = false;
+    this.pendingDeviceChange = false;
     this._isUpstreamPaused = false;
     this.handleTrackMuteEvent = () => this.debouncedTrackMuteHandler().catch(() => this.log.debug('track mute bounce got cancelled by an unmute event', this.logContext));
     this.debouncedTrackMuteHandler = r(() => __awaiter(this, void 0, void 0, function* () {
@@ -16914,6 +16933,7 @@ class LocalTrack extends Track {
       // when track is muted, underlying media stream track is stopped and
       // will be restarted later
       if (this.isMuted) {
+        this.pendingDeviceChange = true;
         return true;
       }
       yield this.restartTrack();
@@ -17033,6 +17053,7 @@ class LocalTrack extends Track {
         this.log.debug('re-acquired MediaStreamTrack', this.logContext);
         yield this.setMediaStreamTrack(newTrack);
         this._constraints = constraints;
+        this.pendingDeviceChange = false;
         this.emit(TrackEvent.Restarted, this);
         if (this.manuallyStopped) {
           this.log.warn('track was stopped during a restart, stopping restarted track', this.logContext);
@@ -17411,8 +17432,7 @@ class LocalTrack extends Track {
           this.log.debug('Track already unmuted', this.logContext);
           return this;
         }
-        const deviceHasChanged = this._constraints.deviceId && this._mediaStreamTrack.getSettings().deviceId !== unwrapConstraint(this._constraints.deviceId);
-        if (this.source === Track.Source.Microphone && (this.stopOnMute || this._mediaStreamTrack.readyState === 'ended' || deviceHasChanged) && !this.isUserProvided) {
+        if (this.source === Track.Source.Microphone && (this.stopOnMute || this._mediaStreamTrack.readyState === 'ended' || this.pendingDeviceChange) && !this.isUserProvided) {
           this.log.debug('reacquiring mic track', this.logContext);
           yield this.restartTrack();
         }
@@ -19739,8 +19759,8 @@ class RTCEngine extends eventsExports.EventEmitter {
     if (!this.pcManager) {
       return false;
     }
-    // primary connection
-    if (this.pcManager.currentState !== PCTransportState.CONNECTED) {
+    const allowedConnectionStates = [PCTransportState.CONNECTING, PCTransportState.CONNECTED];
+    if (!allowedConnectionStates.includes(this.pcManager.currentState)) {
       return false;
     }
     // ensure signal is connected
@@ -19774,6 +19794,7 @@ class RTCEngine extends eventsExports.EventEmitter {
           reject(new NegotiationError('cannot negotiate on closed engine'));
         }
         this.on(EngineEvent.Closing, handleClosed);
+        this.on(EngineEvent.Restarting, handleClosed);
         this.pcManager.publisher.once(PCEvents.RTPVideoPayloadTypes, rtpTypes => {
           const rtpMap = new Map();
           rtpTypes.forEach(rtp => {
@@ -19788,6 +19809,12 @@ class RTCEngine extends eventsExports.EventEmitter {
           yield this.pcManager.negotiate(abortController);
           resolve();
         } catch (e) {
+          if (abortController.signal.aborted) {
+            // negotiation was aborted due to engine close or restart, resolve
+            // cleanly to avoid triggering a cascading reconnect loop
+            resolve();
+            return;
+          }
           if (e instanceof NegotiationError) {
             this.fullReconnectOnNext = true;
           }
@@ -19799,6 +19826,7 @@ class RTCEngine extends eventsExports.EventEmitter {
           }
         } finally {
           this.off(EngineEvent.Closing, handleClosed);
+          this.off(EngineEvent.Restarting, handleClosed);
         }
       }));
     });
@@ -26016,7 +26044,7 @@ class Room extends eventsExports.EventEmitter {
           numFailures: consecutiveFailures,
           engine: this.engine ? {
             closed: this.engine.isClosed,
-            transportsConnected: this.engine.verifyTransport()
+            transportsConnectedOrConnecting: this.engine.verifyTransport()
           } : undefined
         }));
         if (consecutiveFailures >= 3) {
@@ -26212,7 +26240,56 @@ function mapArgs(args) {
     return arg;
   });
 }// This file was generated from JSON Schema using quicktype, do not modify it directly.
-var CheckStatus;
+var DataTrackDeserializeErrorReason;
+(function (DataTrackDeserializeErrorReason) {
+  DataTrackDeserializeErrorReason[DataTrackDeserializeErrorReason["TooShort"] = 0] = "TooShort";
+  DataTrackDeserializeErrorReason[DataTrackDeserializeErrorReason["HeaderOverrun"] = 1] = "HeaderOverrun";
+  DataTrackDeserializeErrorReason[DataTrackDeserializeErrorReason["MissingExtWords"] = 2] = "MissingExtWords";
+  DataTrackDeserializeErrorReason[DataTrackDeserializeErrorReason["UnsupportedVersion"] = 3] = "UnsupportedVersion";
+  DataTrackDeserializeErrorReason[DataTrackDeserializeErrorReason["InvalidHandle"] = 4] = "InvalidHandle";
+  DataTrackDeserializeErrorReason[DataTrackDeserializeErrorReason["MalformedExt"] = 5] = "MalformedExt";
+})(DataTrackDeserializeErrorReason || (DataTrackDeserializeErrorReason = {}));
+var DataTrackSerializeErrorReason;
+(function (DataTrackSerializeErrorReason) {
+  DataTrackSerializeErrorReason[DataTrackSerializeErrorReason["TooSmallForHeader"] = 0] = "TooSmallForHeader";
+  DataTrackSerializeErrorReason[DataTrackSerializeErrorReason["TooSmallForPayload"] = 1] = "TooSmallForPayload";
+})(DataTrackSerializeErrorReason || (DataTrackSerializeErrorReason = {}));
+var DataTrackExtensionTag;
+(function (DataTrackExtensionTag) {
+  DataTrackExtensionTag[DataTrackExtensionTag["UserTimestamp"] = 2] = "UserTimestamp";
+  DataTrackExtensionTag[DataTrackExtensionTag["E2ee"] = 1] = "E2ee";
+})(DataTrackExtensionTag || (DataTrackExtensionTag = {}));
+DataTrackExtensionTag.UserTimestamp;
+DataTrackExtensionTag.E2ee;
+var DataTrackHandleErrorReason;
+(function (DataTrackHandleErrorReason) {
+  DataTrackHandleErrorReason[DataTrackHandleErrorReason["Reserved"] = 0] = "Reserved";
+  DataTrackHandleErrorReason[DataTrackHandleErrorReason["TooLarge"] = 1] = "TooLarge";
+})(DataTrackHandleErrorReason || (DataTrackHandleErrorReason = {}));
+/** Marker indicating a packet's position in relation to a frame. */
+var FrameMarker;
+(function (FrameMarker) {
+  /** Packet is the first in a frame. */
+  FrameMarker[FrameMarker["Start"] = 0] = "Start";
+  /** Packet is within a frame. */
+  FrameMarker[FrameMarker["Inter"] = 1] = "Inter";
+  /** Packet is the last in a frame. */
+  FrameMarker[FrameMarker["Final"] = 2] = "Final";
+  /** Packet is the only one in a frame. */
+  FrameMarker[FrameMarker["Single"] = 3] = "Single";
+})(FrameMarker || (FrameMarker = {}));
+var DataTrackPacketizerReason;
+(function (DataTrackPacketizerReason) {
+  DataTrackPacketizerReason[DataTrackPacketizerReason["MtuTooShort"] = 0] = "MtuTooShort";
+})(DataTrackPacketizerReason || (DataTrackPacketizerReason = {}));getLogger(LoggerNames.DataTracks);
+/** Reason why a frame was dropped. */
+var DataTrackDepacketizerDropReason;
+(function (DataTrackDepacketizerDropReason) {
+  DataTrackDepacketizerDropReason[DataTrackDepacketizerDropReason["Interrupted"] = 0] = "Interrupted";
+  DataTrackDepacketizerDropReason[DataTrackDepacketizerDropReason["UnknownFrame"] = 1] = "UnknownFrame";
+  DataTrackDepacketizerDropReason[DataTrackDepacketizerDropReason["BufferFull"] = 2] = "BufferFull";
+  DataTrackDepacketizerDropReason[DataTrackDepacketizerDropReason["Incomplete"] = 3] = "Incomplete";
+})(DataTrackDepacketizerDropReason || (DataTrackDepacketizerDropReason = {}));var CheckStatus;
 (function (CheckStatus) {
   CheckStatus[CheckStatus["IDLE"] = 0] = "IDLE";
   CheckStatus[CheckStatus["RUNNING"] = 1] = "RUNNING";
@@ -27131,44 +27208,7 @@ class JWSSignatureVerificationFailed extends JOSEError {
     _defineProperty(this, "code", 'ERR_JWS_SIGNATURE_VERIFICATION_FAILED');
   }
 }
-_defineProperty(JWSSignatureVerificationFailed, "code", 'ERR_JWS_SIGNATURE_VERIFICATION_FAILED');var DataTrackHandleErrorReason;
-(function (DataTrackHandleErrorReason) {
-  DataTrackHandleErrorReason[DataTrackHandleErrorReason["Reserved"] = 0] = "Reserved";
-  DataTrackHandleErrorReason[DataTrackHandleErrorReason["TooLarge"] = 1] = "TooLarge";
-})(DataTrackHandleErrorReason || (DataTrackHandleErrorReason = {}));
-var DataTrackDeserializeErrorReason;
-(function (DataTrackDeserializeErrorReason) {
-  DataTrackDeserializeErrorReason[DataTrackDeserializeErrorReason["TooShort"] = 0] = "TooShort";
-  DataTrackDeserializeErrorReason[DataTrackDeserializeErrorReason["HeaderOverrun"] = 1] = "HeaderOverrun";
-  DataTrackDeserializeErrorReason[DataTrackDeserializeErrorReason["MissingExtWords"] = 2] = "MissingExtWords";
-  DataTrackDeserializeErrorReason[DataTrackDeserializeErrorReason["UnsupportedVersion"] = 3] = "UnsupportedVersion";
-  DataTrackDeserializeErrorReason[DataTrackDeserializeErrorReason["InvalidHandle"] = 4] = "InvalidHandle";
-  DataTrackDeserializeErrorReason[DataTrackDeserializeErrorReason["MalformedExt"] = 5] = "MalformedExt";
-})(DataTrackDeserializeErrorReason || (DataTrackDeserializeErrorReason = {}));
-var DataTrackSerializeErrorReason;
-(function (DataTrackSerializeErrorReason) {
-  DataTrackSerializeErrorReason[DataTrackSerializeErrorReason["TooSmallForHeader"] = 0] = "TooSmallForHeader";
-  DataTrackSerializeErrorReason[DataTrackSerializeErrorReason["TooSmallForPayload"] = 1] = "TooSmallForPayload";
-})(DataTrackSerializeErrorReason || (DataTrackSerializeErrorReason = {}));
-var DataTrackExtensionTag;
-(function (DataTrackExtensionTag) {
-  DataTrackExtensionTag[DataTrackExtensionTag["UserTimestamp"] = 2] = "UserTimestamp";
-  DataTrackExtensionTag[DataTrackExtensionTag["E2ee"] = 1] = "E2ee";
-})(DataTrackExtensionTag || (DataTrackExtensionTag = {}));
-DataTrackExtensionTag.UserTimestamp;
-DataTrackExtensionTag.E2ee;
-/** Marker indicating a packet's position in relation to a frame. */
-var FrameMarker;
-(function (FrameMarker) {
-  /** Packet is the first in a frame. */
-  FrameMarker[FrameMarker["Start"] = 0] = "Start";
-  /** Packet is within a frame. */
-  FrameMarker[FrameMarker["Inter"] = 1] = "Inter";
-  /** Packet is the last in a frame. */
-  FrameMarker[FrameMarker["Final"] = 2] = "Final";
-  /** Packet is the only one in a frame. */
-  FrameMarker[FrameMarker["Single"] = 3] = "Single";
-})(FrameMarker || (FrameMarker = {}));
+_defineProperty(JWSSignatureVerificationFailed, "code", 'ERR_JWS_SIGNATURE_VERIFICATION_FAILED');
 
 /**
  * Base HTTP Client for Voice.ai API