@signalwire/sdk 2.0.0

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 (325) hide show
  1. package/.github/workflows/publish.yml +27 -0
  2. package/.github/workflows/test.yml +17 -0
  3. package/CLAUDE.md +112 -0
  4. package/README.md +254 -0
  5. package/docs/MIGRATION-2.0.md +81 -0
  6. package/docs/agent-guide.md +869 -0
  7. package/docs/agent_guide.md +1026 -0
  8. package/docs/api-reference.md +2420 -0
  9. package/docs/api_reference.md +1301 -0
  10. package/docs/architecture.md +843 -0
  11. package/docs/cli-guide.md +579 -0
  12. package/docs/cli_guide.md +448 -0
  13. package/docs/cloud_functions_guide.md +474 -0
  14. package/docs/configuration.md +422 -0
  15. package/docs/contexts-guide.md +787 -0
  16. package/docs/contexts_guide.md +511 -0
  17. package/docs/datamap-guide.md +1141 -0
  18. package/docs/datamap_guide.md +595 -0
  19. package/docs/llm_parameters.md +239 -0
  20. package/docs/mcp_gateway_reference.md +648 -0
  21. package/docs/mcp_integration.md +108 -0
  22. package/docs/prefabs-guide.md +800 -0
  23. package/docs/sdk_features.md +477 -0
  24. package/docs/security.md +436 -0
  25. package/docs/serverless-guide.md +513 -0
  26. package/docs/skills-guide.md +857 -0
  27. package/docs/skills-system.md +301 -0
  28. package/docs/skills_parameter_schema.md +392 -0
  29. package/docs/skills_system.md +467 -0
  30. package/docs/swaig-reference.md +1627 -0
  31. package/docs/swaig_reference.md +910 -0
  32. package/docs/swml_service_guide.md +600 -0
  33. package/docs/third_party_skills.md +533 -0
  34. package/docs/web_service.md +677 -0
  35. package/examples/README.md +131 -0
  36. package/examples/advanced-datamap.ts +100 -0
  37. package/examples/advanced-dynamic-config.ts +70 -0
  38. package/examples/auto-vivified.ts +94 -0
  39. package/examples/call-flow.ts +63 -0
  40. package/examples/comprehensive-dynamic.ts +125 -0
  41. package/examples/contexts-steps.ts +65 -0
  42. package/examples/custom-path.ts +45 -0
  43. package/examples/datamap-tools.ts +55 -0
  44. package/examples/datasphere-multi-instance.ts +63 -0
  45. package/examples/datasphere-serverless-env.ts +68 -0
  46. package/examples/datasphere-webhook-env.ts +66 -0
  47. package/examples/datasphere.ts +37 -0
  48. package/examples/declarative.ts +100 -0
  49. package/examples/dynamic-config.ts +54 -0
  50. package/examples/dynamic-info-gatherer.ts +69 -0
  51. package/examples/dynamic-swml-service.ts +67 -0
  52. package/examples/gather-info.ts +71 -0
  53. package/examples/gather-per-question-functions-demo.ts +140 -0
  54. package/examples/joke-agent.ts +34 -0
  55. package/examples/kubernetes-agent.ts +45 -0
  56. package/examples/llm-params.ts +69 -0
  57. package/examples/mcp-agent.ts +84 -0
  58. package/examples/mcp-gateway.ts +35 -0
  59. package/examples/multi-agent.ts +73 -0
  60. package/examples/multi-endpoint.ts +79 -0
  61. package/examples/pom-prompt.ts +71 -0
  62. package/examples/prefab-concierge.ts +47 -0
  63. package/examples/prefab-faq.ts +54 -0
  64. package/examples/prefab-info-gatherer.ts +33 -0
  65. package/examples/prefab-receptionist.ts +36 -0
  66. package/examples/prefab-survey.ts +68 -0
  67. package/examples/record-call.ts +67 -0
  68. package/examples/relay-demo.ts +33 -0
  69. package/examples/room-and-sip.ts +94 -0
  70. package/examples/serverless-lambda.ts +35 -0
  71. package/examples/session-state.ts +83 -0
  72. package/examples/simple-agent.ts +36 -0
  73. package/examples/simple-static.ts +29 -0
  74. package/examples/skills-demo.ts +38 -0
  75. package/examples/step-function-inheritance-demo.ts +124 -0
  76. package/examples/swaig-features.ts +187 -0
  77. package/examples/swml-service-routing.ts +66 -0
  78. package/examples/swml-service.ts +38 -0
  79. package/examples/tap.ts +68 -0
  80. package/examples/verb-methods.ts +45 -0
  81. package/examples/web-search-multi-instance.ts +72 -0
  82. package/examples/web-search.ts +38 -0
  83. package/examples/wikipedia.ts +36 -0
  84. package/livewire/README.md +140 -0
  85. package/livewire/docs/migration-guide.md +228 -0
  86. package/livewire/examples/livewire-basic-agent.ts +74 -0
  87. package/livewire/examples/livewire-handoff.ts +197 -0
  88. package/livewire/examples/livewire-multi-tool.ts +117 -0
  89. package/package.json +38 -0
  90. package/relay/README.md +70 -0
  91. package/relay/RELAY_IMPLEMENTATION_GUIDE.md +1257 -0
  92. package/relay/docs/call-methods.md +474 -0
  93. package/relay/docs/client-reference.md +142 -0
  94. package/relay/docs/events.md +134 -0
  95. package/relay/docs/getting-started.md +134 -0
  96. package/relay/docs/guide.md +306 -0
  97. package/relay/docs/messaging.md +182 -0
  98. package/relay/examples/relay-inbound.ts +66 -0
  99. package/relay/examples/relay-messaging.ts +71 -0
  100. package/relay/examples/relay-outbound.ts +76 -0
  101. package/rest/README.md +95 -0
  102. package/rest/docs/calling.md +273 -0
  103. package/rest/docs/client-reference.md +107 -0
  104. package/rest/docs/compat.md +204 -0
  105. package/rest/docs/fabric.md +183 -0
  106. package/rest/docs/getting-started.md +110 -0
  107. package/rest/docs/guide.md +351 -0
  108. package/rest/docs/namespaces.md +285 -0
  109. package/rest/examples/rest-10dlc-registration.ts +161 -0
  110. package/rest/examples/rest-calling-ivr-and-ai.ts +102 -0
  111. package/rest/examples/rest-calling-play-and-record.ts +91 -0
  112. package/rest/examples/rest-client.ts +65 -0
  113. package/rest/examples/rest-compat-laml.ts +210 -0
  114. package/rest/examples/rest-datasphere-search.ts +82 -0
  115. package/rest/examples/rest-fabric-conferences-and-routing.ts +144 -0
  116. package/rest/examples/rest-fabric-subscribers-and-sip.ts +108 -0
  117. package/rest/examples/rest-fabric-swml-and-callflows.ts +99 -0
  118. package/rest/examples/rest-manage-resources.ts +65 -0
  119. package/rest/examples/rest-phone-number-management.ts +197 -0
  120. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  121. package/rest/examples/rest-video-rooms.ts +186 -0
  122. package/src/AgentBase.ts +2489 -0
  123. package/src/AgentServer.ts +415 -0
  124. package/src/AuthHandler.ts +256 -0
  125. package/src/ConfigLoader.ts +447 -0
  126. package/src/ContextBuilder.ts +1150 -0
  127. package/src/DataMap.ts +449 -0
  128. package/src/FunctionResult.ts +866 -0
  129. package/src/Logger.ts +337 -0
  130. package/src/PomBuilder.ts +439 -0
  131. package/src/PromptManager.ts +133 -0
  132. package/src/SWMLHandler.ts +298 -0
  133. package/src/SWMLService.ts +717 -0
  134. package/src/SchemaUtils.ts +361 -0
  135. package/src/SecurityUtils.ts +153 -0
  136. package/src/ServerlessAdapter.ts +221 -0
  137. package/src/SessionManager.ts +311 -0
  138. package/src/SslConfig.ts +118 -0
  139. package/src/SwaigFunction.ts +276 -0
  140. package/src/SwmlBuilder.ts +258 -0
  141. package/src/SwmlVerbMethods.generated.ts +234 -0
  142. package/src/TypeInference.ts +181 -0
  143. package/src/WebService.ts +619 -0
  144. package/src/cli/agent-loader.ts +166 -0
  145. package/src/cli/mock-data.ts +111 -0
  146. package/src/cli/swaig-test.ts +452 -0
  147. package/src/generateVerbTypes.ts +322 -0
  148. package/src/index.ts +167 -0
  149. package/src/livewire/index.ts +950 -0
  150. package/src/prefabs/ConciergeAgent.ts +287 -0
  151. package/src/prefabs/FAQBotAgent.ts +384 -0
  152. package/src/prefabs/InfoGathererAgent.ts +339 -0
  153. package/src/prefabs/ReceptionistAgent.ts +366 -0
  154. package/src/prefabs/SurveyAgent.ts +646 -0
  155. package/src/prefabs/index.ts +27 -0
  156. package/src/relay/Action.ts +314 -0
  157. package/src/relay/Call.ts +854 -0
  158. package/src/relay/Deferred.ts +71 -0
  159. package/src/relay/Message.ts +148 -0
  160. package/src/relay/RelayClient.ts +1036 -0
  161. package/src/relay/RelayError.ts +14 -0
  162. package/src/relay/RelayEvent.ts +892 -0
  163. package/src/relay/constants.ts +132 -0
  164. package/src/relay/index.ts +123 -0
  165. package/src/relay/types.ts +149 -0
  166. package/src/rest/HttpClient.ts +103 -0
  167. package/src/rest/RestError.ts +31 -0
  168. package/src/rest/base/BaseResource.ts +19 -0
  169. package/src/rest/base/CrudResource.ts +51 -0
  170. package/src/rest/base/CrudWithAddresses.ts +26 -0
  171. package/src/rest/index.ts +200 -0
  172. package/src/rest/namespaces/addresses.ts +32 -0
  173. package/src/rest/namespaces/calling.ts +187 -0
  174. package/src/rest/namespaces/chat.ts +20 -0
  175. package/src/rest/namespaces/compat.ts +352 -0
  176. package/src/rest/namespaces/datasphere.ts +45 -0
  177. package/src/rest/namespaces/fabric.ts +222 -0
  178. package/src/rest/namespaces/imported-numbers.ts +20 -0
  179. package/src/rest/namespaces/logs.ts +84 -0
  180. package/src/rest/namespaces/lookup.ts +21 -0
  181. package/src/rest/namespaces/mfa.ts +30 -0
  182. package/src/rest/namespaces/number-groups.ts +38 -0
  183. package/src/rest/namespaces/phone-numbers.ts +44 -0
  184. package/src/rest/namespaces/project.ts +36 -0
  185. package/src/rest/namespaces/pubsub.ts +20 -0
  186. package/src/rest/namespaces/queues.ts +33 -0
  187. package/src/rest/namespaces/recordings.ts +28 -0
  188. package/src/rest/namespaces/registry.ts +101 -0
  189. package/src/rest/namespaces/short-codes.ts +28 -0
  190. package/src/rest/namespaces/sip-profile.ts +25 -0
  191. package/src/rest/namespaces/verified-callers.ts +27 -0
  192. package/src/rest/namespaces/video.ts +165 -0
  193. package/src/rest/pagination.ts +84 -0
  194. package/src/rest/types.ts +61 -0
  195. package/src/schema.json +12250 -0
  196. package/src/skills/SkillBase.ts +547 -0
  197. package/src/skills/SkillManager.ts +415 -0
  198. package/src/skills/SkillRegistry.ts +367 -0
  199. package/src/skills/builtin/api_ninjas_trivia.ts +280 -0
  200. package/src/skills/builtin/ask_claude.ts +241 -0
  201. package/src/skills/builtin/claude_skills.ts +978 -0
  202. package/src/skills/builtin/custom_skills.ts +312 -0
  203. package/src/skills/builtin/datasphere.ts +438 -0
  204. package/src/skills/builtin/datasphere_serverless.ts +339 -0
  205. package/src/skills/builtin/datetime.ts +130 -0
  206. package/src/skills/builtin/google_maps.ts +651 -0
  207. package/src/skills/builtin/index.ts +88 -0
  208. package/src/skills/builtin/info_gatherer.ts +405 -0
  209. package/src/skills/builtin/joke.ts +191 -0
  210. package/src/skills/builtin/math.ts +142 -0
  211. package/src/skills/builtin/mcp_gateway.ts +677 -0
  212. package/src/skills/builtin/native_vector_search.ts +901 -0
  213. package/src/skills/builtin/play_background_file.ts +358 -0
  214. package/src/skills/builtin/spider.ts +869 -0
  215. package/src/skills/builtin/swml_transfer.ts +635 -0
  216. package/src/skills/builtin/weather_api.ts +248 -0
  217. package/src/skills/builtin/web_search.ts +1074 -0
  218. package/src/skills/builtin/wikipedia_search.ts +299 -0
  219. package/src/skills/index.ts +12 -0
  220. package/src/types.ts +132 -0
  221. package/tests/AgentBase.test.ts +1093 -0
  222. package/tests/AgentServer.test.ts +126 -0
  223. package/tests/AuthHandler.test.ts +133 -0
  224. package/tests/ConfigLoader.test.ts +151 -0
  225. package/tests/ContextBuilder.test.ts +108 -0
  226. package/tests/DataMap.test.ts +367 -0
  227. package/tests/EphemeralSkillCopy.test.ts +107 -0
  228. package/tests/FunctionResult.test.ts +298 -0
  229. package/tests/GracefulShutdown.test.ts +46 -0
  230. package/tests/Logger.test.ts +420 -0
  231. package/tests/PomBuilder.test.ts +228 -0
  232. package/tests/ProxyDetection.test.ts +228 -0
  233. package/tests/SWMLService.test.ts +320 -0
  234. package/tests/SWMLVerbHandler.test.ts +523 -0
  235. package/tests/SchemaUtils.test.ts +106 -0
  236. package/tests/SchemaUtils.verb.test.ts +206 -0
  237. package/tests/SecurityUtils.test.ts +192 -0
  238. package/tests/ServerlessAdapter.test.ts +222 -0
  239. package/tests/SessionManager.test.ts +257 -0
  240. package/tests/SkillBaseFeatures.test.ts +130 -0
  241. package/tests/SkillMultiInstance.test.ts +102 -0
  242. package/tests/SkillParameterSchemas.test.ts +134 -0
  243. package/tests/SkillRegistrySchema.test.ts +84 -0
  244. package/tests/SslConfig.test.ts +97 -0
  245. package/tests/SwmlBuilder.test.ts +400 -0
  246. package/tests/TypeInference.test.ts +165 -0
  247. package/tests/VerbHandlerRegistry.test.ts +128 -0
  248. package/tests/cli/mock-data.test.ts +113 -0
  249. package/tests/cli/swaig-test.test.ts +108 -0
  250. package/tests/examples.test.ts +194 -0
  251. package/tests/fixtures/scrape-parity/README.md +53 -0
  252. package/tests/fixtures/scrape-parity/expected/01_simple_article.json +5 -0
  253. package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +5 -0
  254. package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +5 -0
  255. package/tests/fixtures/scrape-parity/expected/04_bare_body.json +5 -0
  256. package/tests/fixtures/scrape-parity/expected/05_malformed.json +5 -0
  257. package/tests/fixtures/scrape-parity/expected/06_multi_class.json +5 -0
  258. package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +5 -0
  259. package/tests/fixtures/scrape-parity/expected/08_inline_script.json +5 -0
  260. package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +5 -0
  261. package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +5 -0
  262. package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +5 -0
  263. package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +5 -0
  264. package/tests/fixtures/scrape-parity/html/01_simple_article.html +18 -0
  265. package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +18 -0
  266. package/tests/fixtures/scrape-parity/html/03_nested_containers.html +13 -0
  267. package/tests/fixtures/scrape-parity/html/04_bare_body.html +9 -0
  268. package/tests/fixtures/scrape-parity/html/05_malformed.html +11 -0
  269. package/tests/fixtures/scrape-parity/html/06_multi_class.html +18 -0
  270. package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +12 -0
  271. package/tests/fixtures/scrape-parity/html/08_inline_script.html +17 -0
  272. package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +21 -0
  273. package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +10 -0
  274. package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +13 -0
  275. package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +24 -0
  276. package/tests/fixtures/scrape-parity/python_extract.py +109 -0
  277. package/tests/livewire/livewire.test.ts +780 -0
  278. package/tests/mcp.test.ts +221 -0
  279. package/tests/prefabs/prefabs.test.ts +1093 -0
  280. package/tests/relay/Action.test.ts +392 -0
  281. package/tests/relay/Call.test.ts +535 -0
  282. package/tests/relay/Deferred.test.ts +71 -0
  283. package/tests/relay/Message.test.ts +164 -0
  284. package/tests/relay/RelayClient.test.ts +779 -0
  285. package/tests/relay/RelayEvent.test.ts +463 -0
  286. package/tests/relay/helpers.ts +79 -0
  287. package/tests/rest/HttpClient.test.ts +274 -0
  288. package/tests/rest/RestError.test.ts +53 -0
  289. package/tests/rest/calling.test.ts +156 -0
  290. package/tests/rest/client.test.ts +197 -0
  291. package/tests/rest/compat.test.ts +335 -0
  292. package/tests/rest/datasphere.test.ts +71 -0
  293. package/tests/rest/fabric.test.ts +186 -0
  294. package/tests/rest/helpers.ts +95 -0
  295. package/tests/rest/logs.test.ts +68 -0
  296. package/tests/rest/pagination.test.ts +133 -0
  297. package/tests/rest/registry.test.ts +94 -0
  298. package/tests/rest/relay-rest.test.ts +290 -0
  299. package/tests/rest/video.test.ts +173 -0
  300. package/tests/setup.ts +6 -0
  301. package/tests/skills/SkillBase.test.ts +108 -0
  302. package/tests/skills/SkillManager.test.ts +268 -0
  303. package/tests/skills/SkillRegistry.test.ts +176 -0
  304. package/tests/skills/builtin.test.ts +1472 -0
  305. package/tests/skills/claude-skills.test.ts +54 -0
  306. package/tests/skills/custom-skills.test.ts +53 -0
  307. package/tests/skills/datasphere-serverless.test.ts +70 -0
  308. package/tests/skills/datasphere.test.ts +107 -0
  309. package/tests/skills/datetime.test.ts +101 -0
  310. package/tests/skills/google-maps.test.ts +78 -0
  311. package/tests/skills/info-gatherer.test.ts +411 -0
  312. package/tests/skills/joke.test.ts +81 -0
  313. package/tests/skills/math.test.ts +68 -0
  314. package/tests/skills/mcp-gateway.test.ts +101 -0
  315. package/tests/skills/play-background.test.ts +54 -0
  316. package/tests/skills/spider.test.ts +108 -0
  317. package/tests/skills/swml-transfer.test.ts +178 -0
  318. package/tests/skills/trivia.test.ts +54 -0
  319. package/tests/skills/vector-search.test.ts +135 -0
  320. package/tests/skills/weather-api.test.ts +77 -0
  321. package/tests/skills/web-search-parity.test.ts +59 -0
  322. package/tests/skills/web-search.test.ts +103 -0
  323. package/tests/skills/wikipedia.test.ts +63 -0
  324. package/tsconfig.json +18 -0
  325. package/vitest.config.ts +9 -0
@@ -0,0 +1,854 @@
1
+ /**
2
+ * Call object — represents a live RELAY call with command methods.
3
+ *
4
+ * Created by RelayClient on inbound calling.call.receive events or
5
+ * outbound dial responses.
6
+ */
7
+
8
+ /* eslint-disable @typescript-eslint/no-explicit-any */
9
+
10
+ import { randomUUID } from 'node:crypto';
11
+ import { getLogger } from '../Logger.js';
12
+ import {
13
+ Action,
14
+ PlayAction,
15
+ RecordAction,
16
+ DetectAction,
17
+ CollectAction,
18
+ StandaloneCollectAction,
19
+ FaxAction,
20
+ TapAction,
21
+ StreamAction,
22
+ PayAction,
23
+ TranscribeAction,
24
+ AIAction,
25
+ } from './Action.js';
26
+ import { createDeferred, type Deferred } from './Deferred.js';
27
+ import { CALL_STATE_ENDED, EVENT_CALL_COLLECT, EVENT_CALL_STATE } from './constants.js';
28
+ import { RelayEvent, parseEvent } from './RelayEvent.js';
29
+ import type { CompletedCallback, EventHandler } from './types.js';
30
+
31
+ const logger = getLogger('relay_call');
32
+
33
+ /** Interface the Call needs from RelayClient (avoids circular import). */
34
+ export interface RelayClientLike {
35
+ execute(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
36
+ }
37
+
38
+ export class Call {
39
+ /** @internal */ readonly _client: RelayClientLike;
40
+ callId: string;
41
+ nodeId: string;
42
+ projectId: string;
43
+ context: string;
44
+ tag: string;
45
+ direction: string;
46
+ device: Record<string, any>;
47
+ state: string;
48
+ segmentId: string;
49
+
50
+ /** @internal */ readonly _listeners: Map<string, EventHandler[]> = new Map();
51
+ /** @internal */ readonly _actions: Map<string, Action> = new Map();
52
+ /** @internal */ readonly _ended: Deferred<RelayEvent>;
53
+
54
+ constructor(
55
+ client: RelayClientLike,
56
+ callId: string,
57
+ nodeId: string,
58
+ projectId: string,
59
+ context: string,
60
+ options: {
61
+ tag?: string;
62
+ direction?: string;
63
+ device?: Record<string, any>;
64
+ state?: string;
65
+ segmentId?: string;
66
+ } = {},
67
+ ) {
68
+ this._client = client;
69
+ this.callId = callId;
70
+ this.nodeId = nodeId;
71
+ this.projectId = projectId;
72
+ this.context = context;
73
+ this.tag = options.tag ?? '';
74
+ this.direction = options.direction ?? '';
75
+ this.device = options.device ?? {};
76
+ this.state = options.state ?? '';
77
+ this.segmentId = options.segmentId ?? '';
78
+ this._ended = createDeferred<RelayEvent>();
79
+ }
80
+
81
+ // ─── Internal RPC Primitive ──────────────────────────────────────
82
+
83
+ /** @internal Send a calling.<method> JSON-RPC request for this call. */
84
+ async _execute(method: string, extraParams?: Record<string, unknown>): Promise<Record<string, unknown>> {
85
+ const rpcMethod = `calling.${method}`;
86
+ const params: Record<string, unknown> = {
87
+ node_id: this.nodeId,
88
+ call_id: this.callId,
89
+ };
90
+ if (extraParams) {
91
+ Object.assign(params, extraParams);
92
+ }
93
+ try {
94
+ return await this._client.execute(rpcMethod, params);
95
+ } catch (err: any) {
96
+ if (err?.code !== undefined) {
97
+ logger.warn(`Call ${this.callId} error during ${method} (code=${err.code}): ${err}`);
98
+ return {};
99
+ }
100
+ throw err;
101
+ }
102
+ }
103
+
104
+ // ─── Event Plumbing ──────────────────────────────────────────────
105
+
106
+ /** Register an event listener for this call. */
107
+ on(eventType: string, handler: EventHandler): void {
108
+ const handlers = this._listeners.get(eventType) ?? [];
109
+ handlers.push(handler);
110
+ this._listeners.set(eventType, handlers);
111
+ }
112
+
113
+ /** @internal Called by RelayClient when an event arrives for this call. */
114
+ async _dispatchEvent(payload: Record<string, unknown>): Promise<void> {
115
+ const event = parseEvent(payload as Record<string, any>);
116
+ const eventType = event.eventType;
117
+
118
+ // Update call state
119
+ if (eventType === EVENT_CALL_STATE) {
120
+ const callState = (event.params.call_state ?? this.state) as string;
121
+ this.state = callState;
122
+ if (this.state === CALL_STATE_ENDED && !this._ended.settled) {
123
+ this._ended.resolve(event);
124
+ }
125
+ }
126
+
127
+ // Route to active actions by control_id
128
+ const controlId = (event.params.control_id ?? '') as string;
129
+ if (controlId) {
130
+ const action = this._actions.get(controlId);
131
+ if (action) {
132
+ action._checkEvent(event);
133
+ if (action.completed) {
134
+ this._actions.delete(controlId);
135
+ }
136
+ }
137
+ }
138
+
139
+ // Notify registered listeners (snapshot to allow modification during iteration)
140
+ const handlers = [...(this._listeners.get(eventType) ?? [])];
141
+ for (const handler of handlers) {
142
+ try {
143
+ await handler(event);
144
+ } catch (err) {
145
+ logger.error(`Error in event handler for ${eventType}: ${err}`);
146
+ }
147
+ }
148
+ }
149
+
150
+ /** Wait for a specific event, optionally filtered by predicate. */
151
+ async waitFor(
152
+ eventType: string,
153
+ predicate?: (event: RelayEvent) => boolean,
154
+ timeout?: number,
155
+ ): Promise<RelayEvent> {
156
+ const deferred = createDeferred<RelayEvent>();
157
+
158
+ const handler: EventHandler = (event: RelayEvent) => {
159
+ if (deferred.settled) return;
160
+ if (predicate == null || predicate(event)) {
161
+ deferred.resolve(event);
162
+ }
163
+ };
164
+
165
+ this.on(eventType, handler);
166
+ try {
167
+ if (timeout != null) {
168
+ return await new Promise<RelayEvent>((resolve, reject) => {
169
+ const timer = setTimeout(() => {
170
+ reject(new Error(`waitFor(${eventType}) timed out after ${timeout}ms`));
171
+ }, timeout);
172
+ deferred.promise.then(
173
+ (v) => { clearTimeout(timer); resolve(v); },
174
+ (e) => { clearTimeout(timer); reject(e); },
175
+ );
176
+ });
177
+ }
178
+ return await deferred.promise;
179
+ } finally {
180
+ // Clean up the one-shot handler
181
+ const list = this._listeners.get(eventType);
182
+ if (list) {
183
+ const idx = list.indexOf(handler);
184
+ if (idx !== -1) list.splice(idx, 1);
185
+ }
186
+ }
187
+ }
188
+
189
+ /** Wait for the call to reach the ended state. */
190
+ async waitForEnded(timeout?: number): Promise<RelayEvent> {
191
+ if (timeout != null) {
192
+ return new Promise<RelayEvent>((resolve, reject) => {
193
+ const timer = setTimeout(() => {
194
+ reject(new Error(`waitForEnded timed out after ${timeout}ms`));
195
+ }, timeout);
196
+ this._ended.promise.then(
197
+ (v) => { clearTimeout(timer); resolve(v); },
198
+ (e) => { clearTimeout(timer); reject(e); },
199
+ );
200
+ });
201
+ }
202
+ return this._ended.promise;
203
+ }
204
+
205
+ // ─── Action Helper ───────────────────────────────────────────────
206
+
207
+ /** @internal Register an action, execute the RPC, clean up on failure. */
208
+ async _startAction<T extends Action>(
209
+ action: T,
210
+ method: string,
211
+ params: Record<string, unknown>,
212
+ onCompleted?: CompletedCallback | null,
213
+ ): Promise<T> {
214
+ if (this.state === CALL_STATE_ENDED) {
215
+ logger.warn(`Call ${this.callId} already ended, skipping ${method}`);
216
+ const goneEvent = new RelayEvent('', {});
217
+ action._resolve(goneEvent);
218
+ return action;
219
+ }
220
+ if (onCompleted) action._onCompleted = onCompleted;
221
+ this._actions.set(action.controlId, action);
222
+ try {
223
+ const result = await this._execute(method, params);
224
+ // _execute returns {} when the call is gone (404/410) — resolve immediately
225
+ if (!result || Object.keys(result).length === 0) {
226
+ this._actions.delete(action.controlId);
227
+ if (!action._done.settled) {
228
+ const goneEvent = new RelayEvent('', {});
229
+ action._resolve(goneEvent);
230
+ }
231
+ }
232
+ } catch (err) {
233
+ this._actions.delete(action.controlId);
234
+ if (!action._done.settled) {
235
+ action._done.reject(err);
236
+ // Suppress unhandled rejection — the caller gets the error via the rethrown exception
237
+ action._done.promise.catch(() => {});
238
+ }
239
+ throw err;
240
+ }
241
+ return action;
242
+ }
243
+
244
+ // ─── Call Lifecycle Methods ──────────────────────────────────────
245
+
246
+ /** Answer an inbound call. */
247
+ async answer(extra?: Record<string, unknown>): Promise<Record<string, unknown>> {
248
+ return this._execute('answer', extra);
249
+ }
250
+
251
+ /** End/hang up the call. */
252
+ async hangup(reason = 'hangup'): Promise<Record<string, unknown>> {
253
+ return this._execute('end', { reason });
254
+ }
255
+
256
+ /** Decline control of an inbound call, returning it to routing. */
257
+ async pass(): Promise<Record<string, unknown>> {
258
+ return this._execute('pass');
259
+ }
260
+
261
+ // ─── Audio Playback ──────────────────────────────────────────────
262
+
263
+ /** Play audio content. Returns a PlayAction for stop/pause/resume/wait. */
264
+ async play(
265
+ media: Record<string, unknown>[],
266
+ options: {
267
+ volume?: number;
268
+ direction?: string;
269
+ loop?: number;
270
+ controlId?: string;
271
+ onCompleted?: CompletedCallback;
272
+ } = {},
273
+ ): Promise<PlayAction> {
274
+ const cid = options.controlId ?? randomUUID();
275
+ const params: Record<string, unknown> = { control_id: cid, play: media };
276
+ if (options.volume != null) params.volume = options.volume;
277
+ if (options.direction != null) params.direction = options.direction;
278
+ if (options.loop != null) params.loop = options.loop;
279
+ const action = new PlayAction(this, cid);
280
+ return this._startAction(action, 'play', params, options.onCompleted);
281
+ }
282
+
283
+ // ─── Recording ───────────────────────────────────────────────────
284
+
285
+ /** Record audio from the call. Returns a RecordAction. */
286
+ async record(
287
+ audio?: Record<string, unknown>,
288
+ options: {
289
+ controlId?: string;
290
+ onCompleted?: CompletedCallback;
291
+ } = {},
292
+ ): Promise<RecordAction> {
293
+ const cid = options.controlId ?? randomUUID();
294
+ const recordObj = { audio: audio ?? {} };
295
+ const params: Record<string, unknown> = { control_id: cid, record: recordObj };
296
+ const action = new RecordAction(this, cid);
297
+ return this._startAction(action, 'record', params, options.onCompleted);
298
+ }
299
+
300
+ // ─── Input Collection ────────────────────────────────────────────
301
+
302
+ /** Play audio and collect digit/speech input. Returns a CollectAction. */
303
+ async playAndCollect(
304
+ media: Record<string, unknown>[],
305
+ collect: Record<string, unknown>,
306
+ options: {
307
+ volume?: number;
308
+ controlId?: string;
309
+ onCompleted?: CompletedCallback;
310
+ } = {},
311
+ ): Promise<CollectAction> {
312
+ const cid = options.controlId ?? randomUUID();
313
+ const params: Record<string, unknown> = {
314
+ control_id: cid,
315
+ play: media,
316
+ collect,
317
+ };
318
+ if (options.volume != null) params.volume = options.volume;
319
+ const action = new CollectAction(this, cid);
320
+ return this._startAction(action, 'play_and_collect', params, options.onCompleted);
321
+ }
322
+
323
+ /** Collect digit/speech input without playing media. Returns a StandaloneCollectAction. */
324
+ async collect(options: {
325
+ digits?: Record<string, unknown>;
326
+ speech?: Record<string, unknown>;
327
+ initialTimeout?: number;
328
+ partialResults?: boolean;
329
+ continuous?: boolean;
330
+ sendStartOfInput?: boolean;
331
+ startInputTimers?: boolean;
332
+ controlId?: string;
333
+ onCompleted?: CompletedCallback;
334
+ } = {}): Promise<StandaloneCollectAction> {
335
+ const cid = options.controlId ?? randomUUID();
336
+ const params: Record<string, unknown> = { control_id: cid };
337
+ if (options.digits != null) params.digits = options.digits;
338
+ if (options.speech != null) params.speech = options.speech;
339
+ if (options.initialTimeout != null) params.initial_timeout = options.initialTimeout;
340
+ if (options.partialResults != null) params.partial_results = options.partialResults;
341
+ if (options.continuous != null) params.continuous = options.continuous;
342
+ if (options.sendStartOfInput != null) params.send_start_of_input = options.sendStartOfInput;
343
+ if (options.startInputTimers != null) params.start_input_timers = options.startInputTimers;
344
+ const action = new StandaloneCollectAction(this, cid);
345
+ return this._startAction(action, 'collect', params, options.onCompleted);
346
+ }
347
+
348
+ // ─── Bridging & Connectivity ─────────────────────────────────────
349
+
350
+ /** Bridge the call to one or more destinations. */
351
+ async connect(
352
+ devices: Record<string, unknown>[][],
353
+ options: {
354
+ ringback?: Record<string, unknown>[];
355
+ tag?: string;
356
+ maxDuration?: number;
357
+ maxPricePerMinute?: number;
358
+ statusUrl?: string;
359
+ } = {},
360
+ ): Promise<Record<string, unknown>> {
361
+ const params: Record<string, unknown> = { devices };
362
+ if (options.ringback != null) params.ringback = options.ringback;
363
+ if (options.tag != null) params.tag = options.tag;
364
+ if (options.maxDuration != null) params.max_duration = options.maxDuration;
365
+ if (options.maxPricePerMinute != null) params.max_price_per_minute = options.maxPricePerMinute;
366
+ if (options.statusUrl != null) params.status_url = options.statusUrl;
367
+ return this._execute('connect', params);
368
+ }
369
+
370
+ /** Disconnect (unbridge) a connected call. */
371
+ async disconnect(): Promise<Record<string, unknown>> {
372
+ return this._execute('disconnect');
373
+ }
374
+
375
+ // ─── DTMF ────────────────────────────────────────────────────────
376
+
377
+ /** Send DTMF digits on the call. */
378
+ async sendDigits(digits: string, controlId?: string): Promise<Record<string, unknown>> {
379
+ const cid = controlId ?? randomUUID();
380
+ return this._execute('send_digits', { control_id: cid, digits });
381
+ }
382
+
383
+ // ─── Detection ───────────────────────────────────────────────────
384
+
385
+ /** Start audio detection (machine, fax, digit). Returns a DetectAction. */
386
+ async detect(
387
+ detect: Record<string, unknown>,
388
+ options: {
389
+ timeout?: number;
390
+ controlId?: string;
391
+ onCompleted?: CompletedCallback;
392
+ } = {},
393
+ ): Promise<DetectAction> {
394
+ const cid = options.controlId ?? randomUUID();
395
+ const params: Record<string, unknown> = { control_id: cid, detect };
396
+ if (options.timeout != null) params.timeout = options.timeout;
397
+ const action = new DetectAction(this, cid);
398
+ return this._startAction(action, 'detect', params, options.onCompleted);
399
+ }
400
+
401
+ // ─── SIP Refer ───────────────────────────────────────────────────
402
+
403
+ /** Transfer a SIP call via REFER. */
404
+ async refer(
405
+ device: Record<string, unknown>,
406
+ options: { statusUrl?: string } = {},
407
+ ): Promise<Record<string, unknown>> {
408
+ const params: Record<string, unknown> = { device };
409
+ if (options.statusUrl != null) params.status_url = options.statusUrl;
410
+ return this._execute('refer', params);
411
+ }
412
+
413
+ // ─── Payment ─────────────────────────────────────────────────────
414
+
415
+ /** Start a payment collection. Returns a PayAction. */
416
+ async pay(
417
+ paymentConnectorUrl: string,
418
+ options: {
419
+ controlId?: string;
420
+ inputMethod?: string;
421
+ statusUrl?: string;
422
+ paymentMethod?: string;
423
+ timeout?: string;
424
+ maxAttempts?: string;
425
+ securityCode?: string;
426
+ postalCode?: string;
427
+ minPostalCodeLength?: string;
428
+ tokenType?: string;
429
+ chargeAmount?: string;
430
+ currency?: string;
431
+ language?: string;
432
+ voice?: string;
433
+ description?: string;
434
+ validCardTypes?: string;
435
+ parameters?: Record<string, unknown>[];
436
+ prompts?: Record<string, unknown>[];
437
+ onCompleted?: CompletedCallback;
438
+ } = {},
439
+ ): Promise<PayAction> {
440
+ const cid = options.controlId ?? randomUUID();
441
+ const params: Record<string, unknown> = {
442
+ control_id: cid,
443
+ payment_connector_url: paymentConnectorUrl,
444
+ };
445
+ if (options.inputMethod != null) params.input = options.inputMethod;
446
+ if (options.statusUrl != null) params.status_url = options.statusUrl;
447
+ if (options.paymentMethod != null) params.payment_method = options.paymentMethod;
448
+ if (options.timeout != null) params.timeout = options.timeout;
449
+ if (options.maxAttempts != null) params.max_attempts = options.maxAttempts;
450
+ if (options.securityCode != null) params.security_code = options.securityCode;
451
+ if (options.postalCode != null) params.postal_code = options.postalCode;
452
+ if (options.minPostalCodeLength != null) params.min_postal_code_length = options.minPostalCodeLength;
453
+ if (options.tokenType != null) params.token_type = options.tokenType;
454
+ if (options.chargeAmount != null) params.charge_amount = options.chargeAmount;
455
+ if (options.currency != null) params.currency = options.currency;
456
+ if (options.language != null) params.language = options.language;
457
+ if (options.voice != null) params.voice = options.voice;
458
+ if (options.description != null) params.description = options.description;
459
+ if (options.validCardTypes != null) params.valid_card_types = options.validCardTypes;
460
+ if (options.parameters != null) params.parameters = options.parameters;
461
+ if (options.prompts != null) params.prompts = options.prompts;
462
+ const action = new PayAction(this, cid);
463
+ return this._startAction(action, 'pay', params, options.onCompleted);
464
+ }
465
+
466
+ // ─── Faxing ──────────────────────────────────────────────────────
467
+
468
+ /** Send a fax document. Returns a FaxAction. */
469
+ async sendFax(
470
+ document: string,
471
+ options: {
472
+ identity?: string;
473
+ headerInfo?: string;
474
+ controlId?: string;
475
+ onCompleted?: CompletedCallback;
476
+ } = {},
477
+ ): Promise<FaxAction> {
478
+ const cid = options.controlId ?? randomUUID();
479
+ const params: Record<string, unknown> = { control_id: cid, document };
480
+ if (options.identity != null) params.identity = options.identity;
481
+ if (options.headerInfo != null) params.header_info = options.headerInfo;
482
+ const action = new FaxAction(this, cid, 'send_fax');
483
+ return this._startAction(action, 'send_fax', params, options.onCompleted);
484
+ }
485
+
486
+ /** Receive a fax. Returns a FaxAction. */
487
+ async receiveFax(
488
+ options: {
489
+ controlId?: string;
490
+ onCompleted?: CompletedCallback;
491
+ } = {},
492
+ ): Promise<FaxAction> {
493
+ const cid = options.controlId ?? randomUUID();
494
+ const params: Record<string, unknown> = { control_id: cid };
495
+ const action = new FaxAction(this, cid, 'receive_fax');
496
+ return this._startAction(action, 'receive_fax', params, options.onCompleted);
497
+ }
498
+
499
+ // ─── Tap (Media Interception) ────────────────────────────────────
500
+
501
+ /** Intercept call media and stream it. Returns a TapAction. */
502
+ async tap(
503
+ tap: Record<string, unknown>,
504
+ device: Record<string, unknown>,
505
+ options: {
506
+ controlId?: string;
507
+ onCompleted?: CompletedCallback;
508
+ } = {},
509
+ ): Promise<TapAction> {
510
+ const cid = options.controlId ?? randomUUID();
511
+ const params: Record<string, unknown> = { control_id: cid, tap, device };
512
+ const action = new TapAction(this, cid);
513
+ return this._startAction(action, 'tap', params, options.onCompleted);
514
+ }
515
+
516
+ // ─── Streaming ───────────────────────────────────────────────────
517
+
518
+ /** Start streaming call audio to a WebSocket endpoint. Returns a StreamAction. */
519
+ async stream(
520
+ url: string,
521
+ options: {
522
+ name?: string;
523
+ codec?: string;
524
+ track?: string;
525
+ statusUrl?: string;
526
+ statusUrlMethod?: string;
527
+ authorizationBearerToken?: string;
528
+ customParameters?: Record<string, unknown>;
529
+ controlId?: string;
530
+ onCompleted?: CompletedCallback;
531
+ } = {},
532
+ ): Promise<StreamAction> {
533
+ const cid = options.controlId ?? randomUUID();
534
+ const params: Record<string, unknown> = { control_id: cid, url };
535
+ if (options.name != null) params.name = options.name;
536
+ if (options.codec != null) params.codec = options.codec;
537
+ if (options.track != null) params.track = options.track;
538
+ if (options.statusUrl != null) params.status_url = options.statusUrl;
539
+ if (options.statusUrlMethod != null) params.status_url_method = options.statusUrlMethod;
540
+ if (options.authorizationBearerToken != null) params.authorization_bearer_token = options.authorizationBearerToken;
541
+ if (options.customParameters != null) params.custom_parameters = options.customParameters;
542
+ const action = new StreamAction(this, cid);
543
+ return this._startAction(action, 'stream', params, options.onCompleted);
544
+ }
545
+
546
+ // ─── Transfer ────────────────────────────────────────────────────
547
+
548
+ /** Transfer call control to another RELAY app or SWML script. */
549
+ async transfer(dest: string, extra?: Record<string, unknown>): Promise<Record<string, unknown>> {
550
+ const params: Record<string, unknown> = { dest, ...extra };
551
+ return this._execute('transfer', params);
552
+ }
553
+
554
+ // ─── Conference ──────────────────────────────────────────────────
555
+
556
+ /** Join an ad-hoc audio conference. */
557
+ async joinConference(
558
+ name: string,
559
+ options: {
560
+ muted?: boolean;
561
+ beep?: string;
562
+ startOnEnter?: boolean;
563
+ endOnExit?: boolean;
564
+ waitUrl?: string;
565
+ maxParticipants?: number;
566
+ record?: string;
567
+ region?: string;
568
+ trim?: string;
569
+ coach?: string;
570
+ statusCallback?: string;
571
+ statusCallbackEvent?: string;
572
+ statusCallbackEventType?: string;
573
+ statusCallbackMethod?: string;
574
+ recordingStatusCallback?: string;
575
+ recordingStatusCallbackEvent?: string;
576
+ recordingStatusCallbackEventType?: string;
577
+ recordingStatusCallbackMethod?: string;
578
+ stream?: Record<string, unknown>;
579
+ } = {},
580
+ ): Promise<Record<string, unknown>> {
581
+ const params: Record<string, unknown> = { name };
582
+ if (options.muted != null) params.muted = options.muted;
583
+ if (options.beep != null) params.beep = options.beep;
584
+ if (options.startOnEnter != null) params.start_on_enter = options.startOnEnter;
585
+ if (options.endOnExit != null) params.end_on_exit = options.endOnExit;
586
+ if (options.waitUrl != null) params.wait_url = options.waitUrl;
587
+ if (options.maxParticipants != null) params.max_participants = options.maxParticipants;
588
+ if (options.record != null) params.record = options.record;
589
+ if (options.region != null) params.region = options.region;
590
+ if (options.trim != null) params.trim = options.trim;
591
+ if (options.coach != null) params.coach = options.coach;
592
+ if (options.statusCallback != null) params.status_callback = options.statusCallback;
593
+ if (options.statusCallbackEvent != null) params.status_callback_event = options.statusCallbackEvent;
594
+ if (options.statusCallbackEventType != null) params.status_callback_event_type = options.statusCallbackEventType;
595
+ if (options.statusCallbackMethod != null) params.status_callback_method = options.statusCallbackMethod;
596
+ if (options.recordingStatusCallback != null) params.recording_status_callback = options.recordingStatusCallback;
597
+ if (options.recordingStatusCallbackEvent != null) params.recording_status_callback_event = options.recordingStatusCallbackEvent;
598
+ if (options.recordingStatusCallbackEventType != null) params.recording_status_callback_event_type = options.recordingStatusCallbackEventType;
599
+ if (options.recordingStatusCallbackMethod != null) params.recording_status_callback_method = options.recordingStatusCallbackMethod;
600
+ if (options.stream != null) params.stream = options.stream;
601
+ return this._execute('join_conference', params);
602
+ }
603
+
604
+ /** Leave an audio conference. */
605
+ async leaveConference(conferenceId: string, extra?: Record<string, unknown>): Promise<Record<string, unknown>> {
606
+ return this._execute('leave_conference', { conference_id: conferenceId, ...extra });
607
+ }
608
+
609
+ // ─── Hold / Unhold ───────────────────────────────────────────────
610
+
611
+ /** Put the call on hold. */
612
+ async hold(): Promise<Record<string, unknown>> {
613
+ return this._execute('hold');
614
+ }
615
+
616
+ /** Release the call from hold. */
617
+ async unhold(): Promise<Record<string, unknown>> {
618
+ return this._execute('unhold');
619
+ }
620
+
621
+ // ─── Denoise ─────────────────────────────────────────────────────
622
+
623
+ /** Start noise reduction on the call. */
624
+ async denoise(): Promise<Record<string, unknown>> {
625
+ return this._execute('denoise');
626
+ }
627
+
628
+ /** Stop noise reduction on the call. */
629
+ async denoiseStop(): Promise<Record<string, unknown>> {
630
+ return this._execute('denoise.stop');
631
+ }
632
+
633
+ // ─── Transcribe ──────────────────────────────────────────────────
634
+
635
+ /** Start transcribing the call. Returns a TranscribeAction. */
636
+ async transcribe(
637
+ options: {
638
+ controlId?: string;
639
+ statusUrl?: string;
640
+ onCompleted?: CompletedCallback;
641
+ } = {},
642
+ ): Promise<TranscribeAction> {
643
+ const cid = options.controlId ?? randomUUID();
644
+ const params: Record<string, unknown> = { control_id: cid };
645
+ if (options.statusUrl != null) params.status_url = options.statusUrl;
646
+ const action = new TranscribeAction(this, cid);
647
+ return this._startAction(action, 'transcribe', params, options.onCompleted);
648
+ }
649
+
650
+ // ─── Echo ────────────────────────────────────────────────────────
651
+
652
+ /** Echo audio back to the caller (useful for testing). */
653
+ async echo(options: { timeout?: number; statusUrl?: string } = {}): Promise<Record<string, unknown>> {
654
+ const params: Record<string, unknown> = {};
655
+ if (options.timeout != null) params.timeout = options.timeout;
656
+ if (options.statusUrl != null) params.status_url = options.statusUrl;
657
+ return this._execute('echo', Object.keys(params).length ? params : undefined);
658
+ }
659
+
660
+ // ─── Digit Bindings ──────────────────────────────────────────────
661
+
662
+ /** Bind a DTMF digit sequence to trigger a RELAY method. */
663
+ async bindDigit(
664
+ digits: string,
665
+ bindMethod: string,
666
+ options: {
667
+ bindParams?: Record<string, unknown>;
668
+ realm?: string;
669
+ maxTriggers?: number;
670
+ } = {},
671
+ ): Promise<Record<string, unknown>> {
672
+ const params: Record<string, unknown> = {
673
+ digits,
674
+ bind_method: bindMethod,
675
+ };
676
+ if (options.bindParams != null) params.params = options.bindParams;
677
+ if (options.realm != null) params.realm = options.realm;
678
+ if (options.maxTriggers != null) params.max_triggers = options.maxTriggers;
679
+ return this._execute('bind_digit', params);
680
+ }
681
+
682
+ /** Clear all digit bindings, optionally filtered by realm. */
683
+ async clearDigitBindings(realm?: string): Promise<Record<string, unknown>> {
684
+ const params: Record<string, unknown> = {};
685
+ if (realm != null) params.realm = realm;
686
+ return this._execute('clear_digit_bindings', Object.keys(params).length ? params : undefined);
687
+ }
688
+
689
+ // ─── Live Transcribe / Translate ─────────────────────────────────
690
+
691
+ /** Start or stop live transcription on the call. */
692
+ async liveTranscribe(action: Record<string, unknown>, extra?: Record<string, unknown>): Promise<Record<string, unknown>> {
693
+ return this._execute('live_transcribe', { action, ...extra });
694
+ }
695
+
696
+ /** Start or stop live translation on the call. */
697
+ async liveTranslate(
698
+ action: Record<string, unknown>,
699
+ options: { statusUrl?: string } = {},
700
+ ): Promise<Record<string, unknown>> {
701
+ const params: Record<string, unknown> = { action };
702
+ if (options.statusUrl != null) params.status_url = options.statusUrl;
703
+ return this._execute('live_translate', params);
704
+ }
705
+
706
+ // ─── Room ────────────────────────────────────────────────────────
707
+
708
+ /** Join a video/audio room. */
709
+ async joinRoom(
710
+ name: string,
711
+ options: { statusUrl?: string } = {},
712
+ ): Promise<Record<string, unknown>> {
713
+ const params: Record<string, unknown> = { name };
714
+ if (options.statusUrl != null) params.status_url = options.statusUrl;
715
+ return this._execute('join_room', params);
716
+ }
717
+
718
+ /** Leave the current room. */
719
+ async leaveRoom(extra?: Record<string, unknown>): Promise<Record<string, unknown>> {
720
+ return this._execute('leave_room', extra);
721
+ }
722
+
723
+ // ─── AI Agent ────────────────────────────────────────────────────
724
+
725
+ /** Start an AI agent session on the call. Returns an AIAction. */
726
+ async ai(options: {
727
+ controlId?: string;
728
+ agent?: string;
729
+ prompt?: Record<string, unknown>;
730
+ postPrompt?: Record<string, unknown>;
731
+ postPromptUrl?: string;
732
+ postPromptAuthUser?: string;
733
+ postPromptAuthPassword?: string;
734
+ globalData?: Record<string, unknown>;
735
+ pronounce?: Record<string, unknown>[];
736
+ hints?: string[];
737
+ languages?: Record<string, unknown>[];
738
+ SWAIG?: Record<string, unknown>;
739
+ aiParams?: Record<string, unknown>;
740
+ onCompleted?: CompletedCallback;
741
+ } = {}): Promise<AIAction> {
742
+ const cid = options.controlId ?? randomUUID();
743
+ const params: Record<string, unknown> = { control_id: cid };
744
+ if (options.agent != null) params.agent = options.agent;
745
+ if (options.prompt != null) params.prompt = options.prompt;
746
+ if (options.postPrompt != null) params.post_prompt = options.postPrompt;
747
+ if (options.postPromptUrl != null) params.post_prompt_url = options.postPromptUrl;
748
+ if (options.postPromptAuthUser != null) params.post_prompt_auth_user = options.postPromptAuthUser;
749
+ if (options.postPromptAuthPassword != null) params.post_prompt_auth_password = options.postPromptAuthPassword;
750
+ if (options.globalData != null) params.global_data = options.globalData;
751
+ if (options.pronounce != null) params.pronounce = options.pronounce;
752
+ if (options.hints != null) params.hints = options.hints;
753
+ if (options.languages != null) params.languages = options.languages;
754
+ if (options.SWAIG != null) params.SWAIG = options.SWAIG;
755
+ if (options.aiParams != null) params.params = options.aiParams;
756
+ const action = new AIAction(this, cid);
757
+ return this._startAction(action, 'ai', params, options.onCompleted);
758
+ }
759
+
760
+ /** Connect to an Amazon Bedrock AI agent. */
761
+ async amazonBedrock(options: {
762
+ prompt?: unknown;
763
+ SWAIG?: Record<string, unknown>;
764
+ aiParams?: Record<string, unknown>;
765
+ globalData?: Record<string, unknown>;
766
+ postPrompt?: Record<string, unknown>;
767
+ postPromptUrl?: string;
768
+ } = {}): Promise<Record<string, unknown>> {
769
+ const params: Record<string, unknown> = {};
770
+ if (options.prompt != null) params.prompt = options.prompt;
771
+ if (options.SWAIG != null) params.SWAIG = options.SWAIG;
772
+ if (options.aiParams != null) params.params = options.aiParams;
773
+ if (options.globalData != null) params.global_data = options.globalData;
774
+ if (options.postPrompt != null) params.post_prompt = options.postPrompt;
775
+ if (options.postPromptUrl != null) params.post_prompt_url = options.postPromptUrl;
776
+ return this._execute('amazon_bedrock', params);
777
+ }
778
+
779
+ /** Send a message to an active AI agent session. */
780
+ async aiMessage(options: {
781
+ messageText?: string;
782
+ role?: string;
783
+ reset?: Record<string, unknown>;
784
+ globalData?: Record<string, unknown>;
785
+ } = {}): Promise<Record<string, unknown>> {
786
+ const params: Record<string, unknown> = {};
787
+ if (options.messageText != null) params.message_text = options.messageText;
788
+ if (options.role != null) params.role = options.role;
789
+ if (options.reset != null) params.reset = options.reset;
790
+ if (options.globalData != null) params.global_data = options.globalData;
791
+ return this._execute('ai_message', params);
792
+ }
793
+
794
+ /** Put an AI agent session on hold. */
795
+ async aiHold(options: { timeout?: string; prompt?: string } = {}): Promise<Record<string, unknown>> {
796
+ const params: Record<string, unknown> = {};
797
+ if (options.timeout != null) params.timeout = options.timeout;
798
+ if (options.prompt != null) params.prompt = options.prompt;
799
+ return this._execute('ai_hold', Object.keys(params).length ? params : undefined);
800
+ }
801
+
802
+ /** Resume an AI agent session from hold. */
803
+ async aiUnhold(options: { prompt?: string } = {}): Promise<Record<string, unknown>> {
804
+ const params: Record<string, unknown> = {};
805
+ if (options.prompt != null) params.prompt = options.prompt;
806
+ return this._execute('ai_unhold', Object.keys(params).length ? params : undefined);
807
+ }
808
+
809
+ // ─── User Events ─────────────────────────────────────────────────
810
+
811
+ /** Send a custom user-defined event. */
812
+ async userEvent(options: { event?: string } & Record<string, unknown> = {}): Promise<Record<string, unknown>> {
813
+ const params: Record<string, unknown> = {};
814
+ if (options.event != null) params.event = options.event;
815
+ return this._execute('user_event', params);
816
+ }
817
+
818
+ // ─── Queue ───────────────────────────────────────────────────────
819
+
820
+ /** Place the call in a queue. */
821
+ async queueEnter(
822
+ queueName: string,
823
+ options: { controlId?: string; statusUrl?: string } = {},
824
+ ): Promise<Record<string, unknown>> {
825
+ const cid = options.controlId ?? randomUUID();
826
+ const params: Record<string, unknown> = {
827
+ control_id: cid,
828
+ queue_name: queueName,
829
+ };
830
+ if (options.statusUrl != null) params.status_url = options.statusUrl;
831
+ return this._execute('queue.enter', params);
832
+ }
833
+
834
+ /** Remove the call from a queue. */
835
+ async queueLeave(
836
+ queueName: string,
837
+ options: { controlId?: string; queueId?: string; statusUrl?: string } = {},
838
+ ): Promise<Record<string, unknown>> {
839
+ const cid = options.controlId ?? randomUUID();
840
+ const params: Record<string, unknown> = {
841
+ control_id: cid,
842
+ queue_name: queueName,
843
+ };
844
+ if (options.queueId != null) params.queue_id = options.queueId;
845
+ if (options.statusUrl != null) params.status_url = options.statusUrl;
846
+ return this._execute('queue.leave', params);
847
+ }
848
+
849
+ // ─── Repr ────────────────────────────────────────────────────────
850
+
851
+ toString(): string {
852
+ return `<Call id=${this.callId} state=${this.state} direction=${this.direction}>`;
853
+ }
854
+ }