@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
@@ -12,6 +12,7 @@ import type { AgentOptions } from '../types.js';
12
12
 
13
13
  // ── Config types ────────────────────────────────────────────────────────────
14
14
 
15
+ /** Configuration for the {@link ConciergeAgent}. */
15
16
  export interface ConciergeConfig {
16
17
  /** Name of the venue or business (required). */
17
18
  venueName: string;
@@ -38,6 +39,27 @@ export interface ConciergeConfig {
38
39
  /**
39
40
  * Prefab agent that acts as a virtual concierge for a venue, providing information
40
41
  * about services, amenities, hours of operation, availability, and directions.
42
+ *
43
+ * @example Hotel concierge
44
+ * ```ts
45
+ * import { ConciergeAgent } from '@signalwire/sdk';
46
+ *
47
+ * const agent = new ConciergeAgent({
48
+ * venueName: 'The Park Hotel',
49
+ * services: ['Room service', 'Valet parking', 'Spa', 'Restaurant'],
50
+ * hoursOfOperation: {
51
+ * restaurant: '7 AM - 10 PM daily',
52
+ * spa: '9 AM - 9 PM daily',
53
+ * default: '24 hours',
54
+ * },
55
+ * amenities: {
56
+ * pool: { location: 'Rooftop', hours: '6 AM - 10 PM' },
57
+ * gym: { location: 'Floor 2', hours: '24 hours' },
58
+ * },
59
+ * });
60
+ *
61
+ * await agent.serve({ port: 3000 });
62
+ * ```
41
63
  */
42
64
  export class ConciergeAgent extends AgentBase {
43
65
  /** Name of the venue or business. */
@@ -14,6 +14,7 @@ import type { AgentOptions } from '../types.js';
14
14
 
15
15
  // ── Config types ────────────────────────────────────────────────────────────
16
16
 
17
+ /** A single frequently-asked-question entry consumed by {@link FAQBotAgent}. */
17
18
  export interface FAQEntry {
18
19
  /** The representative question text. */
19
20
  question: string;
@@ -25,6 +26,7 @@ export interface FAQEntry {
25
26
  categories?: string[];
26
27
  }
27
28
 
29
+ /** Configuration for the {@link FAQBotAgent}. */
28
30
  export interface FAQBotConfig {
29
31
  /** Agent display name (defaults to `"faq_bot"`). */
30
32
  name?: string;
@@ -48,7 +50,36 @@ export interface FAQBotConfig {
48
50
 
49
51
  // ── Agent ───────────────────────────────────────────────────────────────────
50
52
 
51
- /** Prefab agent that answers frequently asked questions using keyword matching with optional escalation to a live agent. */
53
+ /**
54
+ * Prefab agent that answers frequently asked questions using keyword matching with optional escalation to a live agent.
55
+ *
56
+ * Pass an array of `{ question, answer, keywords }` entries and the agent will
57
+ * fuzzy-match inbound utterances against them. If no match crosses the confidence
58
+ * threshold, the call can optionally escalate to a configured phone number.
59
+ *
60
+ * @example
61
+ * ```ts
62
+ * import { FAQBotAgent } from '@signalwire/sdk';
63
+ *
64
+ * const agent = new FAQBotAgent({
65
+ * faqs: [
66
+ * {
67
+ * question: 'What are your business hours?',
68
+ * answer: "We're open 9 AM to 5 PM Pacific, Monday through Friday.",
69
+ * keywords: ['hours', 'open', 'closed', 'time'],
70
+ * },
71
+ * {
72
+ * question: 'Where are you located?',
73
+ * answer: 'Our headquarters are in San Francisco, California.',
74
+ * keywords: ['location', 'address', 'office'],
75
+ * },
76
+ * ],
77
+ * escalationNumber: '+15551234567',
78
+ * });
79
+ *
80
+ * await agent.serve({ port: 3000 });
81
+ * ```
82
+ */
52
83
  export class FAQBotAgent extends AgentBase {
53
84
  /** The configured FAQ entries. */
54
85
  public faqs: FAQEntry[];
@@ -63,7 +63,47 @@ const FALLBACK_QUESTIONS: InfoGathererQuestion[] = [
63
63
  { key_name: 'message', question_text: 'How can I help you today?' },
64
64
  ];
65
65
 
66
- /** Prefab agent that gathers caller information one question at a time. */
66
+ /**
67
+ * Prefab agent that gathers caller information one question at a time.
68
+ *
69
+ * Supports two modes:
70
+ *
71
+ * - **Static** — provide `questions` at construction; the same questions are
72
+ * asked on every call.
73
+ * - **Dynamic** — leave `questions` unset and register a callback via
74
+ * `questionCallback` (or `setQuestionCallback()`); the callback decides which
75
+ * questions to ask per incoming call based on query params, body, or headers.
76
+ *
77
+ * @example Static questions
78
+ * ```ts
79
+ * import { InfoGathererAgent } from '@signalwire/sdk';
80
+ *
81
+ * const agent = new InfoGathererAgent({
82
+ * questions: [
83
+ * { key_name: 'name', question_text: 'What is your name?' },
84
+ * { key_name: 'email', question_text: 'What is your email address?', confirm: true },
85
+ * { key_name: 'issue', question_text: 'How can we help?' },
86
+ * ],
87
+ * });
88
+ *
89
+ * await agent.serve({ port: 3000 });
90
+ * ```
91
+ *
92
+ * @example Dynamic questions per request
93
+ * ```ts
94
+ * const agent = new InfoGathererAgent({
95
+ * questionCallback: async (query) => {
96
+ * if (query.intake === 'medical') {
97
+ * return [
98
+ * { key_name: 'dob', question_text: 'Date of birth?' },
99
+ * { key_name: 'insurance_id', question_text: 'Insurance member ID?' },
100
+ * ];
101
+ * }
102
+ * return [{ key_name: 'message', question_text: 'How can I help?' }];
103
+ * },
104
+ * });
105
+ * ```
106
+ */
67
107
  export class InfoGathererAgent extends AgentBase {
68
108
  private staticQuestions: InfoGathererQuestion[] | null;
69
109
  private questionCallback: InfoGathererQuestionCallback | null = null;
@@ -13,6 +13,7 @@ import type { AgentOptions } from '../types.js';
13
13
 
14
14
  // ── Config types ────────────────────────────────────────────────────────────
15
15
 
16
+ /** A department the receptionist can route callers to. */
16
17
  export interface ReceptionistDepartment {
17
18
  /** Department identifier (e.g. `"sales"`, `"support"`). */
18
19
  name: string;
@@ -22,6 +23,7 @@ export interface ReceptionistDepartment {
22
23
  number: string;
23
24
  }
24
25
 
26
+ /** Configuration for the {@link ReceptionistAgent}. */
25
27
  export interface ReceptionistConfig {
26
28
  /** Departments the agent can transfer callers to. */
27
29
  departments: ReceptionistDepartment[];
@@ -51,7 +53,34 @@ interface CheckInSession {
51
53
 
52
54
  // ── Agent ───────────────────────────────────────────────────────────────────
53
55
 
54
- /** Prefab agent that greets callers, collects basic information, and transfers them to the correct department. */
56
+ /**
57
+ * Prefab agent that greets callers, collects basic information, and transfers them to the correct department.
58
+ *
59
+ * Optionally supports visitor check-in — when enabled, the agent can collect a visitor's name
60
+ * and purpose-of-visit and invoke a callback (e.g., notify reception via Slack, write to a
61
+ * database). If not transferring, the call ends after check-in.
62
+ *
63
+ * @example
64
+ * ```ts
65
+ * import { ReceptionistAgent } from '@signalwire/sdk';
66
+ *
67
+ * const agent = new ReceptionistAgent({
68
+ * companyName: 'Acme Co',
69
+ * greeting: 'Thanks for calling Acme! How can I direct your call?',
70
+ * departments: [
71
+ * { name: 'sales', description: 'New customer inquiries', number: '+15551112222' },
72
+ * { name: 'support', description: 'Existing customer help', number: '+15553334444' },
73
+ * { name: 'billing', description: 'Billing and payments', number: '+15555556666' },
74
+ * ],
75
+ * checkInEnabled: true,
76
+ * onVisitorCheckIn: async (visitor) => {
77
+ * await notifyFrontDesk(visitor);
78
+ * },
79
+ * });
80
+ *
81
+ * await agent.serve({ port: 3000 });
82
+ * ```
83
+ */
55
84
  export class ReceptionistAgent extends AgentBase {
56
85
  private readonly greeting: string;
57
86
  private readonly departments: ReceptionistDepartment[];
@@ -13,6 +13,7 @@ import type { AgentOptions } from '../types.js';
13
13
 
14
14
  // ── Config types ────────────────────────────────────────────────────────────
15
15
 
16
+ /** A single survey question consumed by {@link SurveyAgent}. */
16
17
  export interface SurveyQuestion {
17
18
  /** Unique question identifier. */
18
19
  id: string;
@@ -47,6 +48,7 @@ export interface SurveyQuestion {
47
48
  points?: number | Record<string, number>;
48
49
  }
49
50
 
51
+ /** Configuration for the {@link SurveyAgent}. */
50
52
  export interface SurveyConfig {
51
53
  /** Human-readable survey name, used in prompts and global data. */
52
54
  surveyName: string;
@@ -82,7 +84,30 @@ interface SurveySession {
82
84
 
83
85
  // ── Agent ───────────────────────────────────────────────────────────────────
84
86
 
85
- /** Prefab agent that conducts surveys with branching logic, answer scoring, and conditional question flow. */
87
+ /**
88
+ * Prefab agent that conducts surveys with branching logic, answer scoring, and conditional question flow.
89
+ *
90
+ * Each survey question declares its response type (rating, yes/no, open text, etc.), an optional
91
+ * set of conditional follow-ups, and a scoring map. The agent walks the question tree, tallies a
92
+ * total score, and exposes the full response map at call end via `onSummary()`.
93
+ *
94
+ * @example Customer satisfaction survey
95
+ * ```ts
96
+ * import { SurveyAgent } from '@signalwire/sdk';
97
+ *
98
+ * const agent = new SurveyAgent({
99
+ * surveyName: 'CSAT',
100
+ * brandName: 'Acme Co',
101
+ * questions: [
102
+ * { id: 'q1', text: 'How satisfied were you with our service?', type: 'rating', scale: 5 },
103
+ * { id: 'q2', text: 'Would you recommend us to a friend?', type: 'yesno' },
104
+ * { id: 'q3', text: 'Anything else you want to share?', type: 'open' },
105
+ * ],
106
+ * });
107
+ *
108
+ * await agent.serve({ port: 3000 });
109
+ * ```
110
+ */
86
111
  export class SurveyAgent extends AgentBase {
87
112
  /** Human-readable survey name. */
88
113
  public surveyName: string;
@@ -27,23 +27,51 @@ import type { CompletedCallback } from './types.js';
27
27
 
28
28
  const logger = getLogger('relay_action');
29
29
 
30
- // Forward-reference to Call to avoid circular imports
30
+ /**
31
+ * Structural subset of {@link Call} that an Action needs — avoids a circular
32
+ * import between `Call.ts` and `Action.ts`.
33
+ */
31
34
  export interface CallLike {
32
35
  _execute(method: string, extraParams?: Record<string, unknown>): Promise<Record<string, unknown>>;
33
36
  }
34
37
 
35
38
  // ─── Base Action ─────────────────────────────────────────────────────
36
39
 
40
+ /**
41
+ * Async handle for a controllable call operation (play, record, tap, detect, etc.).
42
+ *
43
+ * An Action is returned from the async variants on {@link Call} (e.g. `call.playAsync`).
44
+ * It resolves when the server emits a terminal event for its `controlId`. Use
45
+ * {@link Action.wait} to await completion, or register an `onCompleted` callback.
46
+ *
47
+ * @example
48
+ * ```ts
49
+ * const play = await call.playAsync({ play: [{ type: 'tts', text: 'Hello!' }] });
50
+ * // do other work while the greeting plays...
51
+ * const event = await play.wait(10); // seconds
52
+ * console.log('Playback finished with state', event.params.state);
53
+ * ```
54
+ */
37
55
  export class Action {
56
+ /** Reference to the owning call. */
38
57
  readonly call: CallLike;
58
+ /** Unique control ID used by the server to route events back to this action. */
39
59
  readonly controlId: string;
40
60
  protected readonly _terminalEvent: string;
41
61
  protected readonly _terminalStates: readonly string[];
42
62
  /** @internal */ readonly _done: Deferred<RelayEvent>;
63
+ /** Final event once the action terminates, or `null` while still running. */
43
64
  result: RelayEvent | null = null;
65
+ /** Whether the action has reached a terminal state. */
44
66
  completed = false;
45
67
  /** @internal */ _onCompleted: CompletedCallback | null = null;
46
68
 
69
+ /**
70
+ * @param call - Owning call (via the structural {@link CallLike} interface).
71
+ * @param controlId - Unique control ID the server will echo on events.
72
+ * @param terminalEvent - Event type that carries terminal state transitions.
73
+ * @param terminalStates - State values that mark this action as completed.
74
+ */
47
75
  constructor(
48
76
  call: CallLike,
49
77
  controlId: string,
@@ -87,8 +115,12 @@ export class Action {
87
115
  }
88
116
 
89
117
  /**
90
- * Wait for the action to complete. Returns the terminal event.
91
- * @param timeout - Maximum time to wait in seconds (matches Python SDK convention).
118
+ * Wait for the action to complete.
119
+ *
120
+ * @param timeout - Maximum time to wait in **seconds** (matches the Python
121
+ * SDK convention — not milliseconds).
122
+ * @returns The terminal {@link RelayEvent} for this action.
123
+ * @throws {Error} When the optional timeout elapses before the action ends.
92
124
  */
93
125
  async wait(timeout?: number): Promise<RelayEvent> {
94
126
  if (timeout != null) {
@@ -97,16 +129,22 @@ export class Action {
97
129
  const timer = setTimeout(() => {
98
130
  reject(new Error(`Action wait timed out after ${timeout}s`));
99
131
  }, ms);
100
-
101
132
  this._done.promise.then(
102
- (v) => { clearTimeout(timer); resolve(v); },
103
- (e) => { clearTimeout(timer); reject(e); },
133
+ (v) => {
134
+ clearTimeout(timer);
135
+ resolve(v);
136
+ },
137
+ (e) => {
138
+ clearTimeout(timer);
139
+ reject(e);
140
+ },
104
141
  );
105
142
  });
106
143
  }
107
144
  return this._done.promise;
108
145
  }
109
146
 
147
+ /** True once the action has reached a terminal state. */
110
148
  get isDone(): boolean {
111
149
  return this._done.settled;
112
150
  }
@@ -114,23 +152,49 @@ export class Action {
114
152
 
115
153
  // ─── PlayAction ──────────────────────────────────────────────────────
116
154
 
155
+ /** Async handle for a `calling.call.play` action — controls playback in progress. */
117
156
  export class PlayAction extends Action {
118
157
  constructor(call: CallLike, controlId: string) {
119
158
  super(call, controlId, EVENT_CALL_PLAY, [PLAY_STATE_FINISHED, PLAY_STATE_ERROR]);
120
159
  }
121
160
 
161
+ /**
162
+ * Stop the playback.
163
+ *
164
+ * @returns The platform's stop response.
165
+ * @throws {RelayError} When the stop command is rejected.
166
+ */
122
167
  async stop(): Promise<Record<string, unknown>> {
123
168
  return this.call._execute('play.stop', { control_id: this.controlId });
124
169
  }
125
170
 
171
+ /**
172
+ * Pause active playback (resumable with {@link resume}).
173
+ *
174
+ * @returns The platform's pause response.
175
+ * @throws {RelayError} When the pause command is rejected.
176
+ */
126
177
  async pause(): Promise<Record<string, unknown>> {
127
178
  return this.call._execute('play.pause', { control_id: this.controlId });
128
179
  }
129
180
 
181
+ /**
182
+ * Resume playback paused by {@link pause}.
183
+ *
184
+ * @returns The platform's resume response.
185
+ * @throws {RelayError} When the resume command is rejected.
186
+ */
130
187
  async resume(): Promise<Record<string, unknown>> {
131
188
  return this.call._execute('play.resume', { control_id: this.controlId });
132
189
  }
133
190
 
191
+ /**
192
+ * Adjust playback volume.
193
+ *
194
+ * @param volume - Volume adjustment in dB.
195
+ * @returns The platform's volume response.
196
+ * @throws {RelayError} When the volume command is rejected.
197
+ */
134
198
  async volume(volume: number): Promise<Record<string, unknown>> {
135
199
  return this.call._execute('play.volume', { control_id: this.controlId, volume });
136
200
  }
@@ -138,21 +202,42 @@ export class PlayAction extends Action {
138
202
 
139
203
  // ─── RecordAction ────────────────────────────────────────────────────
140
204
 
205
+ /** Async handle for a `calling.call.record` action — controls recording in progress. */
141
206
  export class RecordAction extends Action {
142
207
  constructor(call: CallLike, controlId: string) {
143
208
  super(call, controlId, EVENT_CALL_RECORD, [RECORD_STATE_FINISHED, RECORD_STATE_NO_INPUT]);
144
209
  }
145
210
 
211
+ /**
212
+ * Stop the recording and finalise the file.
213
+ *
214
+ * @returns The platform's stop response.
215
+ * @throws {RelayError} When the stop command is rejected.
216
+ */
146
217
  async stop(): Promise<Record<string, unknown>> {
147
218
  return this.call._execute('record.stop', { control_id: this.controlId });
148
219
  }
149
220
 
221
+ /**
222
+ * Pause the recording (resumable with {@link resume}).
223
+ *
224
+ * @param behavior - Optional behaviour hint (e.g. `"silence"`) controlling
225
+ * what is recorded in place of paused audio.
226
+ * @returns The platform's pause response.
227
+ * @throws {RelayError} When the pause command is rejected.
228
+ */
150
229
  async pause(behavior?: string): Promise<Record<string, unknown>> {
151
230
  const params: Record<string, unknown> = { control_id: this.controlId };
152
231
  if (behavior) params.behavior = behavior;
153
232
  return this.call._execute('record.pause', params);
154
233
  }
155
234
 
235
+ /**
236
+ * Resume recording paused by {@link pause}.
237
+ *
238
+ * @returns The platform's resume response.
239
+ * @throws {RelayError} When the resume command is rejected.
240
+ */
156
241
  async resume(): Promise<Record<string, unknown>> {
157
242
  return this.call._execute('record.resume', { control_id: this.controlId });
158
243
  }
@@ -160,6 +245,7 @@ export class RecordAction extends Action {
160
245
 
161
246
  // ─── DetectAction ────────────────────────────────────────────────────
162
247
 
248
+ /** Async handle for a `calling.call.detect` action (machine / fax / digit). */
163
249
  export class DetectAction extends Action {
164
250
  constructor(call: CallLike, controlId: string) {
165
251
  super(call, controlId, EVENT_CALL_DETECT, ['finished', 'error']);
@@ -174,6 +260,12 @@ export class DetectAction extends Action {
174
260
  }
175
261
  }
176
262
 
263
+ /**
264
+ * Stop detection before the timeout elapses.
265
+ *
266
+ * @returns The platform's stop response.
267
+ * @throws {RelayError} When the stop command is rejected.
268
+ */
177
269
  async stop(): Promise<Record<string, unknown>> {
178
270
  return this.call._execute('detect.stop', { control_id: this.controlId });
179
271
  }
@@ -181,6 +273,7 @@ export class DetectAction extends Action {
181
273
 
182
274
  // ─── CollectAction ───────────────────────────────────────────────────
183
275
 
276
+ /** Async handle for a `play_and_collect` action (combined playback + input collection). */
184
277
  export class CollectAction extends Action {
185
278
  constructor(call: CallLike, controlId: string) {
186
279
  super(call, controlId, EVENT_CALL_COLLECT, ['finished', 'error', 'no_input', 'no_match']);
@@ -200,14 +293,34 @@ export class CollectAction extends Action {
200
293
  }
201
294
  }
202
295
 
296
+ /**
297
+ * Stop the play_and_collect operation.
298
+ *
299
+ * @returns The platform's stop response.
300
+ * @throws {RelayError} When the stop command is rejected.
301
+ */
203
302
  async stop(): Promise<Record<string, unknown>> {
204
303
  return this.call._execute('play_and_collect.stop', { control_id: this.controlId });
205
304
  }
206
305
 
306
+ /**
307
+ * Adjust playback volume of the prompt audio mid-collect.
308
+ *
309
+ * @param volume - Volume adjustment in dB.
310
+ * @returns The platform's volume response.
311
+ * @throws {RelayError} When the volume command is rejected.
312
+ */
207
313
  async volume(volume: number): Promise<Record<string, unknown>> {
208
314
  return this.call._execute('play_and_collect.volume', { control_id: this.controlId, volume });
209
315
  }
210
316
 
317
+ /**
318
+ * Start the collect input timers (useful when `initial_timeout` should be
319
+ * reset after an async side effect completes).
320
+ *
321
+ * @returns The platform's start_input_timers response.
322
+ * @throws {RelayError} When the command is rejected.
323
+ */
211
324
  async startInputTimers(): Promise<Record<string, unknown>> {
212
325
  return this.call._execute('collect.start_input_timers', { control_id: this.controlId });
213
326
  }
@@ -215,6 +328,7 @@ export class CollectAction extends Action {
215
328
 
216
329
  // ─── StandaloneCollectAction ─────────────────────────────────────────
217
330
 
331
+ /** Async handle for a bare `calling.call.collect` action (no accompanying play). */
218
332
  export class StandaloneCollectAction extends Action {
219
333
  constructor(call: CallLike, controlId: string) {
220
334
  super(call, controlId, EVENT_CALL_COLLECT, ['finished', 'error', 'no_input', 'no_match']);
@@ -229,10 +343,22 @@ export class StandaloneCollectAction extends Action {
229
343
  }
230
344
  }
231
345
 
346
+ /**
347
+ * Stop the collect operation before input is received.
348
+ *
349
+ * @returns The platform's stop response.
350
+ * @throws {RelayError} When the stop command is rejected.
351
+ */
232
352
  async stop(): Promise<Record<string, unknown>> {
233
353
  return this.call._execute('collect.stop', { control_id: this.controlId });
234
354
  }
235
355
 
356
+ /**
357
+ * Start the collect input timers.
358
+ *
359
+ * @returns The platform's start_input_timers response.
360
+ * @throws {RelayError} When the command is rejected.
361
+ */
236
362
  async startInputTimers(): Promise<Record<string, unknown>> {
237
363
  return this.call._execute('collect.start_input_timers', { control_id: this.controlId });
238
364
  }
@@ -240,6 +366,7 @@ export class StandaloneCollectAction extends Action {
240
366
 
241
367
  // ─── FaxAction ───────────────────────────────────────────────────────
242
368
 
369
+ /** Async handle for a `send_fax` or `receive_fax` action. */
243
370
  export class FaxAction extends Action {
244
371
  private _methodPrefix: string;
245
372
 
@@ -248,6 +375,12 @@ export class FaxAction extends Action {
248
375
  this._methodPrefix = methodPrefix;
249
376
  }
250
377
 
378
+ /**
379
+ * Stop the fax transfer mid-stream.
380
+ *
381
+ * @returns The platform's stop response.
382
+ * @throws {RelayError} When the stop command is rejected.
383
+ */
251
384
  async stop(): Promise<Record<string, unknown>> {
252
385
  return this.call._execute(`${this._methodPrefix}.stop`, { control_id: this.controlId });
253
386
  }
@@ -255,11 +388,18 @@ export class FaxAction extends Action {
255
388
 
256
389
  // ─── TapAction ───────────────────────────────────────────────────────
257
390
 
391
+ /** Async handle for a `calling.call.tap` action (media mirroring). */
258
392
  export class TapAction extends Action {
259
393
  constructor(call: CallLike, controlId: string) {
260
394
  super(call, controlId, EVENT_CALL_TAP, ['finished']);
261
395
  }
262
396
 
397
+ /**
398
+ * Stop the media tap.
399
+ *
400
+ * @returns The platform's stop response.
401
+ * @throws {RelayError} When the stop command is rejected.
402
+ */
263
403
  async stop(): Promise<Record<string, unknown>> {
264
404
  return this.call._execute('tap.stop', { control_id: this.controlId });
265
405
  }
@@ -267,11 +407,18 @@ export class TapAction extends Action {
267
407
 
268
408
  // ─── StreamAction ────────────────────────────────────────────────────
269
409
 
410
+ /** Async handle for a `calling.call.stream` action (outbound media stream). */
270
411
  export class StreamAction extends Action {
271
412
  constructor(call: CallLike, controlId: string) {
272
413
  super(call, controlId, EVENT_CALL_STREAM, ['finished']);
273
414
  }
274
415
 
416
+ /**
417
+ * Stop the outbound stream.
418
+ *
419
+ * @returns The platform's stop response.
420
+ * @throws {RelayError} When the stop command is rejected.
421
+ */
275
422
  async stop(): Promise<Record<string, unknown>> {
276
423
  return this.call._execute('stream.stop', { control_id: this.controlId });
277
424
  }
@@ -279,11 +426,18 @@ export class StreamAction extends Action {
279
426
 
280
427
  // ─── PayAction ───────────────────────────────────────────────────────
281
428
 
429
+ /** Async handle for a `calling.call.pay` action (PCI-compliant payment collection). */
282
430
  export class PayAction extends Action {
283
431
  constructor(call: CallLike, controlId: string) {
284
432
  super(call, controlId, EVENT_CALL_PAY, ['finished', 'error']);
285
433
  }
286
434
 
435
+ /**
436
+ * Cancel the payment collection before it completes.
437
+ *
438
+ * @returns The platform's stop response.
439
+ * @throws {RelayError} When the stop command is rejected.
440
+ */
287
441
  async stop(): Promise<Record<string, unknown>> {
288
442
  return this.call._execute('pay.stop', { control_id: this.controlId });
289
443
  }
@@ -291,11 +445,18 @@ export class PayAction extends Action {
291
445
 
292
446
  // ─── TranscribeAction ────────────────────────────────────────────────
293
447
 
448
+ /** Async handle for a `calling.call.transcribe` action (real-time transcription). */
294
449
  export class TranscribeAction extends Action {
295
450
  constructor(call: CallLike, controlId: string) {
296
451
  super(call, controlId, EVENT_CALL_TRANSCRIBE, ['finished']);
297
452
  }
298
453
 
454
+ /**
455
+ * Stop the transcription.
456
+ *
457
+ * @returns The platform's stop response.
458
+ * @throws {RelayError} When the stop command is rejected.
459
+ */
299
460
  async stop(): Promise<Record<string, unknown>> {
300
461
  return this.call._execute('transcribe.stop', { control_id: this.controlId });
301
462
  }
@@ -303,11 +464,18 @@ export class TranscribeAction extends Action {
303
464
 
304
465
  // ─── AIAction ────────────────────────────────────────────────────────
305
466
 
467
+ /** Async handle for a `calling.call.ai` action (on-call AI agent session). */
306
468
  export class AIAction extends Action {
307
469
  constructor(call: CallLike, controlId: string) {
308
470
  super(call, controlId, 'calling.call.ai', ['finished', 'error']);
309
471
  }
310
472
 
473
+ /**
474
+ * Stop the AI agent session.
475
+ *
476
+ * @returns The platform's stop response.
477
+ * @throws {RelayError} When the stop command is rejected.
478
+ */
311
479
  async stop(): Promise<Record<string, unknown>> {
312
480
  return this.call._execute('ai.stop', { control_id: this.controlId });
313
481
  }