@signalwire/sdk 2.0.0 → 2.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 (75) hide show
  1. package/package.json +1 -1
  2. package/src/AgentBase.ts +113 -4
  3. package/src/AgentServer.ts +31 -4
  4. package/src/ContextBuilder.ts +33 -2
  5. package/src/DataMap.ts +30 -2
  6. package/src/FunctionResult.ts +40 -3
  7. package/src/PomBuilder.ts +29 -1
  8. package/src/SWMLService.ts +38 -6
  9. package/src/ServerlessAdapter.ts +20 -1
  10. package/src/SwmlBuilder.ts +26 -1
  11. package/src/TypeInference.ts +27 -9
  12. package/src/WebService.ts +27 -5
  13. package/src/index.ts +73 -7
  14. package/src/livewire/index.ts +343 -41
  15. package/src/prefabs/ConciergeAgent.ts +22 -0
  16. package/src/prefabs/FAQBotAgent.ts +32 -1
  17. package/src/prefabs/InfoGathererAgent.ts +41 -1
  18. package/src/prefabs/ReceptionistAgent.ts +30 -1
  19. package/src/prefabs/SurveyAgent.ts +26 -1
  20. package/src/relay/Action.ts +174 -6
  21. package/src/relay/Call.ts +459 -43
  22. package/src/relay/Deferred.ts +27 -4
  23. package/src/relay/Message.ts +54 -3
  24. package/src/relay/RelayClient.ts +167 -18
  25. package/src/relay/RelayError.ts +7 -1
  26. package/src/relay/RelayEvent.ts +52 -0
  27. package/src/rest/HttpClient.ts +61 -0
  28. package/src/rest/RestError.ts +14 -0
  29. package/src/rest/base/BaseResource.ts +16 -3
  30. package/src/rest/base/CrudResource.ts +52 -5
  31. package/src/rest/base/CrudWithAddresses.ts +12 -1
  32. package/src/rest/index.ts +30 -0
  33. package/src/rest/namespaces/addresses.ts +33 -1
  34. package/src/rest/namespaces/calling.ts +348 -1
  35. package/src/rest/namespaces/chat.ts +13 -2
  36. package/src/rest/namespaces/compat.ts +469 -9
  37. package/src/rest/namespaces/datasphere.ts +48 -5
  38. package/src/rest/namespaces/fabric.ts +197 -2
  39. package/src/rest/namespaces/imported-numbers.ts +13 -2
  40. package/src/rest/namespaces/logs.ts +68 -1
  41. package/src/rest/namespaces/lookup.ts +19 -2
  42. package/src/rest/namespaces/mfa.ts +35 -4
  43. package/src/rest/namespaces/number-groups.ts +35 -5
  44. package/src/rest/namespaces/phone-numbers.ts +35 -3
  45. package/src/rest/namespaces/project.ts +30 -1
  46. package/src/rest/namespaces/pubsub.ts +13 -2
  47. package/src/rest/namespaces/queues.ts +29 -4
  48. package/src/rest/namespaces/recordings.ts +26 -1
  49. package/src/rest/namespaces/registry.ts +100 -1
  50. package/src/rest/namespaces/short-codes.ts +27 -1
  51. package/src/rest/namespaces/sip-profile.ts +18 -3
  52. package/src/rest/namespaces/verified-callers.ts +22 -3
  53. package/src/rest/namespaces/video.ts +168 -1
  54. package/src/rest/pagination.ts +22 -8
  55. package/src/skills/SkillBase.ts +37 -2
  56. package/src/skills/SkillManager.ts +8 -4
  57. package/src/skills/builtin/api_ninjas_trivia.ts +5 -0
  58. package/src/skills/builtin/ask_claude.ts +5 -0
  59. package/src/skills/builtin/claude_skills.ts +5 -0
  60. package/src/skills/builtin/custom_skills.ts +15 -0
  61. package/src/skills/builtin/datasphere.ts +9 -0
  62. package/src/skills/builtin/datasphere_serverless.ts +8 -0
  63. package/src/skills/builtin/datetime.ts +7 -0
  64. package/src/skills/builtin/google_maps.ts +5 -0
  65. package/src/skills/builtin/info_gatherer.ts +10 -0
  66. package/src/skills/builtin/joke.ts +5 -0
  67. package/src/skills/builtin/math.ts +7 -0
  68. package/src/skills/builtin/mcp_gateway.ts +8 -0
  69. package/src/skills/builtin/native_vector_search.ts +9 -0
  70. package/src/skills/builtin/play_background_file.ts +9 -0
  71. package/src/skills/builtin/spider.ts +5 -0
  72. package/src/skills/builtin/swml_transfer.ts +10 -0
  73. package/src/skills/builtin/weather_api.ts +7 -0
  74. package/src/skills/builtin/web_search.ts +9 -0
  75. package/src/skills/builtin/wikipedia_search.ts +5 -0
package/src/relay/Call.ts CHANGED
@@ -35,16 +35,48 @@ export interface RelayClientLike {
35
35
  execute(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
36
36
  }
37
37
 
38
+ /**
39
+ * Live RELAY call with command methods.
40
+ *
41
+ * Don't construct directly — `Call` instances are created by {@link RelayClient}
42
+ * for inbound calls (delivered to your `onCall` handler) and for outbound dials.
43
+ *
44
+ * Each command method (`answer()`, `play()`, `record()`, etc.) returns when the
45
+ * platform acknowledges the command; event-driven completion is exposed via
46
+ * {@link Action} objects returned from the async "play/record/..." variants.
47
+ *
48
+ * @example Inside an onCall handler
49
+ * ```ts
50
+ * client.onCall(async (call) => {
51
+ * await call.answer();
52
+ * const play = await call.playAsync({ play: [{ type: 'tts', text: 'Hello!' }] });
53
+ * await play.wait();
54
+ * await call.hangup();
55
+ * });
56
+ * ```
57
+ *
58
+ * @see {@link RelayClient}
59
+ * @see {@link Action}
60
+ */
38
61
  export class Call {
39
62
  /** @internal */ readonly _client: RelayClientLike;
63
+ /** Unique call identifier assigned by the platform. */
40
64
  callId: string;
65
+ /** RELAY node that owns this call. */
41
66
  nodeId: string;
67
+ /** SignalWire project ID. */
42
68
  projectId: string;
69
+ /** RELAY context this call was received on. */
43
70
  context: string;
71
+ /** Opaque correlation tag attached at dial time. */
44
72
  tag: string;
73
+ /** `"inbound"` or `"outbound"`. */
45
74
  direction: string;
75
+ /** Device descriptor the call is associated with (phone, SIP, etc.). */
46
76
  device: Record<string, any>;
77
+ /** Current call state (e.g. `"created"`, `"answered"`, `"ended"`). */
47
78
  state: string;
79
+ /** Call segment ID used for event correlation. */
48
80
  segmentId: string;
49
81
 
50
82
  /** @internal */ readonly _listeners: Map<string, EventHandler[]> = new Map();
@@ -103,7 +135,16 @@ export class Call {
103
135
 
104
136
  // ─── Event Plumbing ──────────────────────────────────────────────
105
137
 
106
- /** Register an event listener for this call. */
138
+ /**
139
+ * Register an event listener for this call.
140
+ *
141
+ * Multiple listeners for the same event type are supported. Listener errors
142
+ * are logged but do not disrupt dispatch to other listeners.
143
+ *
144
+ * @param eventType - Fully-qualified event type (e.g.
145
+ * `"calling.call.state"`, `"calling.call.play"`).
146
+ * @param handler - Callback invoked for each matching event.
147
+ */
107
148
  on(eventType: string, handler: EventHandler): void {
108
149
  const handlers = this._listeners.get(eventType) ?? [];
109
150
  handlers.push(handler);
@@ -147,7 +188,19 @@ export class Call {
147
188
  }
148
189
  }
149
190
 
150
- /** Wait for a specific event, optionally filtered by predicate. */
191
+ /**
192
+ * Wait for a specific event, optionally filtered by predicate.
193
+ *
194
+ * Registers a one-shot listener that is removed after resolving (or after
195
+ * the timeout elapses). Useful for awaiting a specific state transition.
196
+ *
197
+ * @param eventType - Event type to wait for.
198
+ * @param predicate - Optional filter — only events for which this returns
199
+ * `true` resolve the wait.
200
+ * @param timeout - Optional timeout in milliseconds. Omit to wait forever.
201
+ * @returns The first matching {@link RelayEvent}.
202
+ * @throws {Error} When the optional timeout elapses before a match.
203
+ */
151
204
  async waitFor(
152
205
  eventType: string,
153
206
  predicate?: (event: RelayEvent) => boolean,
@@ -186,7 +239,13 @@ export class Call {
186
239
  }
187
240
  }
188
241
 
189
- /** Wait for the call to reach the ended state. */
242
+ /**
243
+ * Wait for the call to reach the `ended` state.
244
+ *
245
+ * @param timeout - Optional timeout in milliseconds.
246
+ * @returns The terminating `calling.call.state` {@link RelayEvent}.
247
+ * @throws {Error} When the optional timeout elapses before the call ends.
248
+ */
190
249
  async waitForEnded(timeout?: number): Promise<RelayEvent> {
191
250
  if (timeout != null) {
192
251
  return new Promise<RelayEvent>((resolve, reject) => {
@@ -243,24 +302,63 @@ export class Call {
243
302
 
244
303
  // ─── Call Lifecycle Methods ──────────────────────────────────────
245
304
 
246
- /** Answer an inbound call. */
305
+ /**
306
+ * Answer an inbound call.
307
+ *
308
+ * @param extra - Optional additional params merged into the answer request
309
+ * (e.g. SIP headers, codec hints).
310
+ * @returns The platform's answer response.
311
+ * @throws {RelayError} When the answer command is rejected.
312
+ */
247
313
  async answer(extra?: Record<string, unknown>): Promise<Record<string, unknown>> {
248
314
  return this._execute('answer', extra);
249
315
  }
250
316
 
251
- /** End/hang up the call. */
317
+ /**
318
+ * End / hang up the call.
319
+ *
320
+ * @param reason - Hangup reason delivered to the platform. Defaults to
321
+ * `"hangup"`.
322
+ * @returns The platform's end response.
323
+ * @throws {RelayError} When the end command is rejected.
324
+ */
252
325
  async hangup(reason = 'hangup'): Promise<Record<string, unknown>> {
253
326
  return this._execute('end', { reason });
254
327
  }
255
328
 
256
- /** Decline control of an inbound call, returning it to routing. */
329
+ /**
330
+ * Decline control of an inbound call, returning it to routing.
331
+ *
332
+ * Use instead of {@link answer} when you want the call to fall through to
333
+ * the next matching route rather than be handled by this client.
334
+ *
335
+ * @returns The platform's pass response.
336
+ * @throws {RelayError} When the pass command is rejected.
337
+ */
257
338
  async pass(): Promise<Record<string, unknown>> {
258
339
  return this._execute('pass');
259
340
  }
260
341
 
261
342
  // ─── Audio Playback ──────────────────────────────────────────────
262
343
 
263
- /** Play audio content. Returns a PlayAction for stop/pause/resume/wait. */
344
+ /**
345
+ * Play audio content on the call.
346
+ *
347
+ * Returns immediately with a {@link PlayAction} — `await action.wait()` to
348
+ * block until playback finishes, or call `stop()` / `pause()` / `resume()`
349
+ * / `volume()` on it to control playback.
350
+ *
351
+ * @param media - Platform-shaped play items (TTS, audio URLs, silence, etc.).
352
+ * @param options - Optional playback controls.
353
+ * @param options.volume - Volume adjustment in dB.
354
+ * @param options.direction - `"speak"`, `"hear"`, or `"both"`.
355
+ * @param options.loop - Number of times to loop the playback.
356
+ * @param options.controlId - Explicit control ID. Auto-generated when omitted.
357
+ * @param options.onCompleted - Callback fired when playback reaches a
358
+ * terminal state.
359
+ * @returns A {@link PlayAction} for control and completion tracking.
360
+ * @throws {RelayError} When the play command is rejected.
361
+ */
264
362
  async play(
265
363
  media: Record<string, unknown>[],
266
364
  options: {
@@ -282,7 +380,18 @@ export class Call {
282
380
 
283
381
  // ─── Recording ───────────────────────────────────────────────────
284
382
 
285
- /** Record audio from the call. Returns a RecordAction. */
383
+ /**
384
+ * Record audio from the call.
385
+ *
386
+ * @param audio - Platform-shaped audio recording options (direction, codec,
387
+ * timeouts, etc.). Defaults to `{}`.
388
+ * @param options - Recording behaviour.
389
+ * @param options.controlId - Explicit control ID. Auto-generated when omitted.
390
+ * @param options.onCompleted - Callback fired when the recording reaches a
391
+ * terminal state.
392
+ * @returns A {@link RecordAction} for control and completion tracking.
393
+ * @throws {RelayError} When the record command is rejected.
394
+ */
286
395
  async record(
287
396
  audio?: Record<string, unknown>,
288
397
  options: {
@@ -299,7 +408,20 @@ export class Call {
299
408
 
300
409
  // ─── Input Collection ────────────────────────────────────────────
301
410
 
302
- /** Play audio and collect digit/speech input. Returns a CollectAction. */
411
+ /**
412
+ * Play audio and collect digit / speech input in a single operation.
413
+ *
414
+ * Convenient for IVR prompts — playback stops as soon as input is received.
415
+ *
416
+ * @param media - Audio items to play while collecting.
417
+ * @param collect - Platform-shaped collect config (`digits`, `speech`, etc.).
418
+ * @param options - Playback and collection behaviour.
419
+ * @param options.volume - Playback volume adjustment in dB.
420
+ * @param options.controlId - Explicit control ID. Auto-generated when omitted.
421
+ * @param options.onCompleted - Callback fired when collect completes.
422
+ * @returns A {@link CollectAction} for the combined play-and-collect flow.
423
+ * @throws {RelayError} When the play_and_collect command is rejected.
424
+ */
303
425
  async playAndCollect(
304
426
  media: Record<string, unknown>[],
305
427
  collect: Record<string, unknown>,
@@ -320,7 +442,22 @@ export class Call {
320
442
  return this._startAction(action, 'play_and_collect', params, options.onCompleted);
321
443
  }
322
444
 
323
- /** Collect digit/speech input without playing media. Returns a StandaloneCollectAction. */
445
+ /**
446
+ * Collect digit / speech input without playing media.
447
+ *
448
+ * @param options - Collect configuration.
449
+ * @param options.digits - DTMF digit-collection config.
450
+ * @param options.speech - Speech-recognition config.
451
+ * @param options.initialTimeout - Seconds to wait for the first input.
452
+ * @param options.partialResults - Emit partial (interim) results.
453
+ * @param options.continuous - Keep collecting until explicitly stopped.
454
+ * @param options.sendStartOfInput - Emit a start-of-input event when detected.
455
+ * @param options.startInputTimers - Start input timers immediately.
456
+ * @param options.controlId - Explicit control ID. Auto-generated when omitted.
457
+ * @param options.onCompleted - Callback fired when collect completes.
458
+ * @returns A {@link StandaloneCollectAction} for control and completion tracking.
459
+ * @throws {RelayError} When the collect command is rejected.
460
+ */
324
461
  async collect(options: {
325
462
  digits?: Record<string, unknown>;
326
463
  speech?: Record<string, unknown>;
@@ -347,7 +484,20 @@ export class Call {
347
484
 
348
485
  // ─── Bridging & Connectivity ─────────────────────────────────────
349
486
 
350
- /** Bridge the call to one or more destinations. */
487
+ /**
488
+ * Bridge the call to one or more destinations.
489
+ *
490
+ * @param devices - Serial/parallel dial plan — outer array of serial groups,
491
+ * inner arrays dialled in parallel.
492
+ * @param options - Connect behaviour.
493
+ * @param options.ringback - Ringback media played to the originating party.
494
+ * @param options.tag - Tag for event correlation.
495
+ * @param options.maxDuration - Maximum connect duration in seconds.
496
+ * @param options.maxPricePerMinute - Price cap per minute.
497
+ * @param options.statusUrl - Webhook URL for status events.
498
+ * @returns The platform's connect response.
499
+ * @throws {RelayError} When the connect command is rejected.
500
+ */
351
501
  async connect(
352
502
  devices: Record<string, unknown>[][],
353
503
  options: {
@@ -367,14 +517,26 @@ export class Call {
367
517
  return this._execute('connect', params);
368
518
  }
369
519
 
370
- /** Disconnect (unbridge) a connected call. */
520
+ /**
521
+ * Disconnect (unbridge) a connected call.
522
+ *
523
+ * @returns The platform's disconnect response.
524
+ * @throws {RelayError} When the disconnect command is rejected.
525
+ */
371
526
  async disconnect(): Promise<Record<string, unknown>> {
372
527
  return this._execute('disconnect');
373
528
  }
374
529
 
375
530
  // ─── DTMF ────────────────────────────────────────────────────────
376
531
 
377
- /** Send DTMF digits on the call. */
532
+ /**
533
+ * Send DTMF digits on the call.
534
+ *
535
+ * @param digits - The DTMF digit string to send (e.g. `"1234#"`, `"ww*9"`).
536
+ * @param controlId - Explicit control ID. Auto-generated when omitted.
537
+ * @returns The platform's send-digits response.
538
+ * @throws {RelayError} When the send_digits command is rejected.
539
+ */
378
540
  async sendDigits(digits: string, controlId?: string): Promise<Record<string, unknown>> {
379
541
  const cid = controlId ?? randomUUID();
380
542
  return this._execute('send_digits', { control_id: cid, digits });
@@ -382,7 +544,17 @@ export class Call {
382
544
 
383
545
  // ─── Detection ───────────────────────────────────────────────────
384
546
 
385
- /** Start audio detection (machine, fax, digit). Returns a DetectAction. */
547
+ /**
548
+ * Start audio detection (answering machine, fax, DTMF).
549
+ *
550
+ * @param detect - Platform-shaped detect configuration.
551
+ * @param options - Detection behaviour.
552
+ * @param options.timeout - Detection timeout in seconds.
553
+ * @param options.controlId - Explicit control ID. Auto-generated when omitted.
554
+ * @param options.onCompleted - Callback fired when detection completes.
555
+ * @returns A {@link DetectAction} for control and completion tracking.
556
+ * @throws {RelayError} When the detect command is rejected.
557
+ */
386
558
  async detect(
387
559
  detect: Record<string, unknown>,
388
560
  options: {
@@ -400,7 +572,15 @@ export class Call {
400
572
 
401
573
  // ─── SIP Refer ───────────────────────────────────────────────────
402
574
 
403
- /** Transfer a SIP call via REFER. */
575
+ /**
576
+ * Transfer a SIP call via REFER.
577
+ *
578
+ * @param device - Platform-shaped SIP target device descriptor.
579
+ * @param options - Optional REFER behaviour.
580
+ * @param options.statusUrl - Webhook URL for REFER status events.
581
+ * @returns The platform's refer response.
582
+ * @throws {RelayError} When the refer command is rejected.
583
+ */
404
584
  async refer(
405
585
  device: Record<string, unknown>,
406
586
  options: { statusUrl?: string } = {},
@@ -412,7 +592,16 @@ export class Call {
412
592
 
413
593
  // ─── Payment ─────────────────────────────────────────────────────
414
594
 
415
- /** Start a payment collection. Returns a PayAction. */
595
+ /**
596
+ * Start a PCI-compliant payment collection flow.
597
+ *
598
+ * @param paymentConnectorUrl - URL of the configured payment connector to
599
+ * tokenise the card with.
600
+ * @param options - Payment configuration — card-type filters, prompts,
601
+ * charge amount, etc. See the SignalWire pay documentation for field details.
602
+ * @returns A {@link PayAction} tracking the payment-collection flow.
603
+ * @throws {RelayError} When the pay command is rejected.
604
+ */
416
605
  async pay(
417
606
  paymentConnectorUrl: string,
418
607
  options: {
@@ -465,7 +654,18 @@ export class Call {
465
654
 
466
655
  // ─── Faxing ──────────────────────────────────────────────────────
467
656
 
468
- /** Send a fax document. Returns a FaxAction. */
657
+ /**
658
+ * Send a fax document.
659
+ *
660
+ * @param document - URL of the document to fax (TIFF or PDF).
661
+ * @param options - Fax behaviour.
662
+ * @param options.identity - Caller identity string sent in the fax header.
663
+ * @param options.headerInfo - Additional fax header text.
664
+ * @param options.controlId - Explicit control ID. Auto-generated when omitted.
665
+ * @param options.onCompleted - Callback fired when the fax completes.
666
+ * @returns A {@link FaxAction} for control and completion tracking.
667
+ * @throws {RelayError} When the send_fax command is rejected.
668
+ */
469
669
  async sendFax(
470
670
  document: string,
471
671
  options: {
@@ -483,7 +683,15 @@ export class Call {
483
683
  return this._startAction(action, 'send_fax', params, options.onCompleted);
484
684
  }
485
685
 
486
- /** Receive a fax. Returns a FaxAction. */
686
+ /**
687
+ * Receive a fax and save it server-side.
688
+ *
689
+ * @param options - Fax reception behaviour.
690
+ * @param options.controlId - Explicit control ID. Auto-generated when omitted.
691
+ * @param options.onCompleted - Callback fired when the fax completes.
692
+ * @returns A {@link FaxAction} for control and completion tracking.
693
+ * @throws {RelayError} When the receive_fax command is rejected.
694
+ */
487
695
  async receiveFax(
488
696
  options: {
489
697
  controlId?: string;
@@ -498,7 +706,17 @@ export class Call {
498
706
 
499
707
  // ─── Tap (Media Interception) ────────────────────────────────────
500
708
 
501
- /** Intercept call media and stream it. Returns a TapAction. */
709
+ /**
710
+ * Intercept call media and stream it to an external destination.
711
+ *
712
+ * @param tap - Platform-shaped tap configuration (direction, codec, etc.).
713
+ * @param device - Destination device descriptor (WebSocket URL, etc.).
714
+ * @param options - Tap behaviour.
715
+ * @param options.controlId - Explicit control ID. Auto-generated when omitted.
716
+ * @param options.onCompleted - Callback fired when the tap completes.
717
+ * @returns A {@link TapAction} for control and completion tracking.
718
+ * @throws {RelayError} When the tap command is rejected.
719
+ */
502
720
  async tap(
503
721
  tap: Record<string, unknown>,
504
722
  device: Record<string, unknown>,
@@ -515,7 +733,24 @@ export class Call {
515
733
 
516
734
  // ─── Streaming ───────────────────────────────────────────────────
517
735
 
518
- /** Start streaming call audio to a WebSocket endpoint. Returns a StreamAction. */
736
+ /**
737
+ * Start streaming call audio to a WebSocket endpoint.
738
+ *
739
+ * @param url - WebSocket URL to stream audio to.
740
+ * @param options - Stream behaviour.
741
+ * @param options.name - Friendly name for the stream.
742
+ * @param options.codec - Audio codec (e.g. `"PCMU"`, `"PCMA"`).
743
+ * @param options.track - Which track to send: `"inbound"`, `"outbound"`, or
744
+ * `"both"`.
745
+ * @param options.statusUrl - Webhook URL for stream status events.
746
+ * @param options.statusUrlMethod - HTTP method for `statusUrl` requests.
747
+ * @param options.authorizationBearerToken - Bearer token sent to the stream endpoint.
748
+ * @param options.customParameters - Extra parameters forwarded to the stream endpoint.
749
+ * @param options.controlId - Explicit control ID. Auto-generated when omitted.
750
+ * @param options.onCompleted - Callback fired when the stream completes.
751
+ * @returns A {@link StreamAction} for control and completion tracking.
752
+ * @throws {RelayError} When the stream command is rejected.
753
+ */
519
754
  async stream(
520
755
  url: string,
521
756
  options: {
@@ -545,7 +780,14 @@ export class Call {
545
780
 
546
781
  // ─── Transfer ────────────────────────────────────────────────────
547
782
 
548
- /** Transfer call control to another RELAY app or SWML script. */
783
+ /**
784
+ * Transfer call control to another RELAY app or SWML script.
785
+ *
786
+ * @param dest - Destination identifier (RELAY context, SWML URL, etc.).
787
+ * @param extra - Optional additional params merged into the transfer request.
788
+ * @returns The platform's transfer response.
789
+ * @throws {RelayError} When the transfer command is rejected.
790
+ */
549
791
  async transfer(dest: string, extra?: Record<string, unknown>): Promise<Record<string, unknown>> {
550
792
  const params: Record<string, unknown> = { dest, ...extra };
551
793
  return this._execute('transfer', params);
@@ -553,7 +795,14 @@ export class Call {
553
795
 
554
796
  // ─── Conference ──────────────────────────────────────────────────
555
797
 
556
- /** Join an ad-hoc audio conference. */
798
+ /**
799
+ * Join an ad-hoc audio conference.
800
+ *
801
+ * @param name - Conference name. Participants on the same name hear each other.
802
+ * @param options - Conference behaviour (muting, recording, status callbacks, etc.).
803
+ * @returns The platform's join-conference response.
804
+ * @throws {RelayError} When the join_conference command is rejected.
805
+ */
557
806
  async joinConference(
558
807
  name: string,
559
808
  options: {
@@ -601,38 +850,74 @@ export class Call {
601
850
  return this._execute('join_conference', params);
602
851
  }
603
852
 
604
- /** Leave an audio conference. */
853
+ /**
854
+ * Leave an audio conference.
855
+ *
856
+ * @param conferenceId - Identifier of the conference to leave.
857
+ * @param extra - Optional additional params merged into the request.
858
+ * @returns The platform's leave-conference response.
859
+ * @throws {RelayError} When the leave_conference command is rejected.
860
+ */
605
861
  async leaveConference(conferenceId: string, extra?: Record<string, unknown>): Promise<Record<string, unknown>> {
606
862
  return this._execute('leave_conference', { conference_id: conferenceId, ...extra });
607
863
  }
608
864
 
609
865
  // ─── Hold / Unhold ───────────────────────────────────────────────
610
866
 
611
- /** Put the call on hold. */
867
+ /**
868
+ * Put the call on hold.
869
+ *
870
+ * @returns The platform's hold response.
871
+ * @throws {RelayError} When the hold command is rejected.
872
+ */
612
873
  async hold(): Promise<Record<string, unknown>> {
613
874
  return this._execute('hold');
614
875
  }
615
876
 
616
- /** Release the call from hold. */
877
+ /**
878
+ * Release the call from hold.
879
+ *
880
+ * @returns The platform's unhold response.
881
+ * @throws {RelayError} When the unhold command is rejected.
882
+ */
617
883
  async unhold(): Promise<Record<string, unknown>> {
618
884
  return this._execute('unhold');
619
885
  }
620
886
 
621
887
  // ─── Denoise ─────────────────────────────────────────────────────
622
888
 
623
- /** Start noise reduction on the call. */
889
+ /**
890
+ * Start noise reduction on the call.
891
+ *
892
+ * @returns The platform's denoise response.
893
+ * @throws {RelayError} When the denoise command is rejected.
894
+ */
624
895
  async denoise(): Promise<Record<string, unknown>> {
625
896
  return this._execute('denoise');
626
897
  }
627
898
 
628
- /** Stop noise reduction on the call. */
899
+ /**
900
+ * Stop noise reduction on the call.
901
+ *
902
+ * @returns The platform's denoise-stop response.
903
+ * @throws {RelayError} When the denoise.stop command is rejected.
904
+ */
629
905
  async denoiseStop(): Promise<Record<string, unknown>> {
630
906
  return this._execute('denoise.stop');
631
907
  }
632
908
 
633
909
  // ─── Transcribe ──────────────────────────────────────────────────
634
910
 
635
- /** Start transcribing the call. Returns a TranscribeAction. */
911
+ /**
912
+ * Start transcribing the call.
913
+ *
914
+ * @param options - Transcription behaviour.
915
+ * @param options.controlId - Explicit control ID. Auto-generated when omitted.
916
+ * @param options.statusUrl - Webhook URL for transcription status events.
917
+ * @param options.onCompleted - Callback fired when transcription completes.
918
+ * @returns A {@link TranscribeAction} for control and completion tracking.
919
+ * @throws {RelayError} When the transcribe command is rejected.
920
+ */
636
921
  async transcribe(
637
922
  options: {
638
923
  controlId?: string;
@@ -649,7 +934,15 @@ export class Call {
649
934
 
650
935
  // ─── Echo ────────────────────────────────────────────────────────
651
936
 
652
- /** Echo audio back to the caller (useful for testing). */
937
+ /**
938
+ * Echo audio back to the caller (useful for testing network round-trip).
939
+ *
940
+ * @param options - Echo behaviour.
941
+ * @param options.timeout - How long to echo, in seconds.
942
+ * @param options.statusUrl - Webhook URL for echo status events.
943
+ * @returns The platform's echo response.
944
+ * @throws {RelayError} When the echo command is rejected.
945
+ */
653
946
  async echo(options: { timeout?: number; statusUrl?: string } = {}): Promise<Record<string, unknown>> {
654
947
  const params: Record<string, unknown> = {};
655
948
  if (options.timeout != null) params.timeout = options.timeout;
@@ -659,7 +952,19 @@ export class Call {
659
952
 
660
953
  // ─── Digit Bindings ──────────────────────────────────────────────
661
954
 
662
- /** Bind a DTMF digit sequence to trigger a RELAY method. */
955
+ /**
956
+ * Bind a DTMF digit sequence to trigger a RELAY method automatically when
957
+ * the caller presses it.
958
+ *
959
+ * @param digits - DTMF sequence that triggers the binding (e.g. `"*9"`).
960
+ * @param bindMethod - RELAY method to invoke when the sequence is detected.
961
+ * @param options - Binding behaviour.
962
+ * @param options.bindParams - Params forwarded to `bindMethod` on trigger.
963
+ * @param options.realm - Optional realm label so bindings can be cleared in groups.
964
+ * @param options.maxTriggers - Maximum number of times the binding can fire.
965
+ * @returns The platform's bind_digit response.
966
+ * @throws {RelayError} When the bind_digit command is rejected.
967
+ */
663
968
  async bindDigit(
664
969
  digits: string,
665
970
  bindMethod: string,
@@ -679,7 +984,13 @@ export class Call {
679
984
  return this._execute('bind_digit', params);
680
985
  }
681
986
 
682
- /** Clear all digit bindings, optionally filtered by realm. */
987
+ /**
988
+ * Clear all digit bindings, optionally filtered by realm.
989
+ *
990
+ * @param realm - When provided, only bindings with this realm label are cleared.
991
+ * @returns The platform's clear_digit_bindings response.
992
+ * @throws {RelayError} When the clear_digit_bindings command is rejected.
993
+ */
683
994
  async clearDigitBindings(realm?: string): Promise<Record<string, unknown>> {
684
995
  const params: Record<string, unknown> = {};
685
996
  if (realm != null) params.realm = realm;
@@ -688,12 +999,29 @@ export class Call {
688
999
 
689
1000
  // ─── Live Transcribe / Translate ─────────────────────────────────
690
1001
 
691
- /** Start or stop live transcription on the call. */
1002
+ /**
1003
+ * Start or stop live transcription on the call.
1004
+ *
1005
+ * @param action - Platform-shaped action block (`start` or `stop` plus
1006
+ * configuration).
1007
+ * @param extra - Optional additional params merged into the request.
1008
+ * @returns The platform's live_transcribe response.
1009
+ * @throws {RelayError} When the live_transcribe command is rejected.
1010
+ */
692
1011
  async liveTranscribe(action: Record<string, unknown>, extra?: Record<string, unknown>): Promise<Record<string, unknown>> {
693
1012
  return this._execute('live_transcribe', { action, ...extra });
694
1013
  }
695
1014
 
696
- /** Start or stop live translation on the call. */
1015
+ /**
1016
+ * Start or stop live translation on the call.
1017
+ *
1018
+ * @param action - Platform-shaped action block (`start` or `stop` plus
1019
+ * source/target languages).
1020
+ * @param options - Live-translate behaviour.
1021
+ * @param options.statusUrl - Webhook URL for translation status events.
1022
+ * @returns The platform's live_translate response.
1023
+ * @throws {RelayError} When the live_translate command is rejected.
1024
+ */
697
1025
  async liveTranslate(
698
1026
  action: Record<string, unknown>,
699
1027
  options: { statusUrl?: string } = {},
@@ -705,7 +1033,15 @@ export class Call {
705
1033
 
706
1034
  // ─── Room ────────────────────────────────────────────────────────
707
1035
 
708
- /** Join a video/audio room. */
1036
+ /**
1037
+ * Join a video / audio room.
1038
+ *
1039
+ * @param name - Room name — callers on the same name share the same room.
1040
+ * @param options - Room behaviour.
1041
+ * @param options.statusUrl - Webhook URL for room status events.
1042
+ * @returns The platform's join_room response.
1043
+ * @throws {RelayError} When the join_room command is rejected.
1044
+ */
709
1045
  async joinRoom(
710
1046
  name: string,
711
1047
  options: { statusUrl?: string } = {},
@@ -715,14 +1051,26 @@ export class Call {
715
1051
  return this._execute('join_room', params);
716
1052
  }
717
1053
 
718
- /** Leave the current room. */
1054
+ /**
1055
+ * Leave the current room.
1056
+ *
1057
+ * @param extra - Optional additional params merged into the request.
1058
+ * @returns The platform's leave_room response.
1059
+ * @throws {RelayError} When the leave_room command is rejected.
1060
+ */
719
1061
  async leaveRoom(extra?: Record<string, unknown>): Promise<Record<string, unknown>> {
720
1062
  return this._execute('leave_room', extra);
721
1063
  }
722
1064
 
723
1065
  // ─── AI Agent ────────────────────────────────────────────────────
724
1066
 
725
- /** Start an AI agent session on the call. Returns an AIAction. */
1067
+ /**
1068
+ * Start an AI agent session on the call.
1069
+ *
1070
+ * @param options - AI configuration — prompts, voices, tools, languages, etc.
1071
+ * @returns An {@link AIAction} for control and completion tracking.
1072
+ * @throws {RelayError} When the ai command is rejected.
1073
+ */
726
1074
  async ai(options: {
727
1075
  controlId?: string;
728
1076
  agent?: string;
@@ -757,7 +1105,19 @@ export class Call {
757
1105
  return this._startAction(action, 'ai', params, options.onCompleted);
758
1106
  }
759
1107
 
760
- /** Connect to an Amazon Bedrock AI agent. */
1108
+ /**
1109
+ * Connect the call to an Amazon Bedrock AI agent.
1110
+ *
1111
+ * @param options - Bedrock agent configuration.
1112
+ * @param options.prompt - Prompt to send to the Bedrock agent.
1113
+ * @param options.SWAIG - SWAIG configuration (functions, includes, etc.).
1114
+ * @param options.aiParams - AI engine parameters.
1115
+ * @param options.globalData - Global-data object available to SWAIG tools.
1116
+ * @param options.postPrompt - Post-prompt configuration.
1117
+ * @param options.postPromptUrl - URL to POST the final summary to.
1118
+ * @returns The platform's amazon_bedrock response.
1119
+ * @throws {RelayError} When the amazon_bedrock command is rejected.
1120
+ */
761
1121
  async amazonBedrock(options: {
762
1122
  prompt?: unknown;
763
1123
  SWAIG?: Record<string, unknown>;
@@ -776,7 +1136,17 @@ export class Call {
776
1136
  return this._execute('amazon_bedrock', params);
777
1137
  }
778
1138
 
779
- /** Send a message to an active AI agent session. */
1139
+ /**
1140
+ * Send a message into an active AI agent session.
1141
+ *
1142
+ * @param options - Message parameters.
1143
+ * @param options.messageText - Text content to inject into the conversation.
1144
+ * @param options.role - Speaker role (`"system"`, `"user"`, or `"assistant"`).
1145
+ * @param options.reset - Reset directives for the conversation state.
1146
+ * @param options.globalData - Global-data updates to merge.
1147
+ * @returns The platform's ai_message response.
1148
+ * @throws {RelayError} When the ai_message command is rejected.
1149
+ */
780
1150
  async aiMessage(options: {
781
1151
  messageText?: string;
782
1152
  role?: string;
@@ -791,7 +1161,15 @@ export class Call {
791
1161
  return this._execute('ai_message', params);
792
1162
  }
793
1163
 
794
- /** Put an AI agent session on hold. */
1164
+ /**
1165
+ * Put the AI agent session on hold (pause turn-taking).
1166
+ *
1167
+ * @param options - Hold behaviour.
1168
+ * @param options.timeout - Maximum hold duration.
1169
+ * @param options.prompt - Prompt played to the caller during the hold.
1170
+ * @returns The platform's ai_hold response.
1171
+ * @throws {RelayError} When the ai_hold command is rejected.
1172
+ */
795
1173
  async aiHold(options: { timeout?: string; prompt?: string } = {}): Promise<Record<string, unknown>> {
796
1174
  const params: Record<string, unknown> = {};
797
1175
  if (options.timeout != null) params.timeout = options.timeout;
@@ -799,7 +1177,14 @@ export class Call {
799
1177
  return this._execute('ai_hold', Object.keys(params).length ? params : undefined);
800
1178
  }
801
1179
 
802
- /** Resume an AI agent session from hold. */
1180
+ /**
1181
+ * Resume an AI agent session from hold.
1182
+ *
1183
+ * @param options - Unhold behaviour.
1184
+ * @param options.prompt - Prompt played to the caller on resume.
1185
+ * @returns The platform's ai_unhold response.
1186
+ * @throws {RelayError} When the ai_unhold command is rejected.
1187
+ */
803
1188
  async aiUnhold(options: { prompt?: string } = {}): Promise<Record<string, unknown>> {
804
1189
  const params: Record<string, unknown> = {};
805
1190
  if (options.prompt != null) params.prompt = options.prompt;
@@ -808,7 +1193,14 @@ export class Call {
808
1193
 
809
1194
  // ─── User Events ─────────────────────────────────────────────────
810
1195
 
811
- /** Send a custom user-defined event. */
1196
+ /**
1197
+ * Emit a custom user-defined event on the call for your webhooks.
1198
+ *
1199
+ * @param options - Freeform event payload. Set `options.event` for the
1200
+ * event name and include any additional fields your webhook expects.
1201
+ * @returns The platform's user_event response.
1202
+ * @throws {RelayError} When the user_event command is rejected.
1203
+ */
812
1204
  async userEvent(options: { event?: string } & Record<string, unknown> = {}): Promise<Record<string, unknown>> {
813
1205
  const params: Record<string, unknown> = {};
814
1206
  if (options.event != null) params.event = options.event;
@@ -817,7 +1209,16 @@ export class Call {
817
1209
 
818
1210
  // ─── Queue ───────────────────────────────────────────────────────
819
1211
 
820
- /** Place the call in a queue. */
1212
+ /**
1213
+ * Place the call into a named queue.
1214
+ *
1215
+ * @param queueName - Name of the queue to enter.
1216
+ * @param options - Queue-entry behaviour.
1217
+ * @param options.controlId - Explicit control ID. Auto-generated when omitted.
1218
+ * @param options.statusUrl - Webhook URL for queue status events.
1219
+ * @returns The platform's queue.enter response.
1220
+ * @throws {RelayError} When the queue.enter command is rejected.
1221
+ */
821
1222
  async queueEnter(
822
1223
  queueName: string,
823
1224
  options: { controlId?: string; statusUrl?: string } = {},
@@ -831,7 +1232,17 @@ export class Call {
831
1232
  return this._execute('queue.enter', params);
832
1233
  }
833
1234
 
834
- /** Remove the call from a queue. */
1235
+ /**
1236
+ * Remove the call from a queue.
1237
+ *
1238
+ * @param queueName - Name of the queue to leave.
1239
+ * @param options - Queue-exit behaviour.
1240
+ * @param options.controlId - Explicit control ID. Auto-generated when omitted.
1241
+ * @param options.queueId - Queue ID override (when multiple queues share a name).
1242
+ * @param options.statusUrl - Webhook URL for queue status events.
1243
+ * @returns The platform's queue.leave response.
1244
+ * @throws {RelayError} When the queue.leave command is rejected.
1245
+ */
835
1246
  async queueLeave(
836
1247
  queueName: string,
837
1248
  options: { controlId?: string; queueId?: string; statusUrl?: string } = {},
@@ -848,6 +1259,11 @@ export class Call {
848
1259
 
849
1260
  // ─── Repr ────────────────────────────────────────────────────────
850
1261
 
1262
+ /**
1263
+ * Return a human-readable diagnostic string.
1264
+ *
1265
+ * @returns `<Call id=... state=... direction=...>` — handy for log output.
1266
+ */
851
1267
  toString(): string {
852
1268
  return `<Call id=${this.callId} state=${this.state} direction=${this.direction}>`;
853
1269
  }