@signalwire/sdk 2.0.5 → 3.6.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 (659) hide show
  1. package/CHANGELOG.md +821 -0
  2. package/LICENSE +21 -0
  3. package/README.md +163 -68
  4. package/dist/AGENTS.md +13 -0
  5. package/dist/AgentBase.d.ts +510 -126
  6. package/dist/AgentBase.js +1581 -455
  7. package/dist/AgentBase.js.map +1 -1
  8. package/dist/AgentServer.d.ts +21 -0
  9. package/dist/AgentServer.js +154 -47
  10. package/dist/AgentServer.js.map +1 -1
  11. package/dist/AuthHandler.d.ts +14 -2
  12. package/dist/AuthHandler.js +7 -2
  13. package/dist/AuthHandler.js.map +1 -1
  14. package/dist/ConfigLoader.d.ts +5 -13
  15. package/dist/ConfigLoader.js +15 -29
  16. package/dist/ConfigLoader.js.map +1 -1
  17. package/dist/ContextBuilder.d.ts +202 -9
  18. package/dist/ContextBuilder.js +219 -36
  19. package/dist/ContextBuilder.js.map +1 -1
  20. package/dist/DataMap.d.ts +186 -45
  21. package/dist/DataMap.js +210 -52
  22. package/dist/DataMap.js.map +1 -1
  23. package/dist/FunctionResult.d.ts +309 -83
  24. package/dist/FunctionResult.js +483 -116
  25. package/dist/FunctionResult.js.map +1 -1
  26. package/dist/Logger.d.ts +30 -5
  27. package/dist/Logger.js +77 -19
  28. package/dist/Logger.js.map +1 -1
  29. package/dist/POM/PromptObjectModel.d.ts +12 -1
  30. package/dist/POM/PromptObjectModel.js +25 -9
  31. package/dist/POM/PromptObjectModel.js.map +1 -1
  32. package/dist/ParameterSchema.d.ts +306 -0
  33. package/dist/ParameterSchema.js +251 -0
  34. package/dist/ParameterSchema.js.map +1 -0
  35. package/dist/PlatformContracts.d.ts +21 -0
  36. package/dist/PlatformContracts.generated.d.ts +109 -0
  37. package/dist/PlatformContracts.generated.js +8 -0
  38. package/dist/PlatformContracts.generated.js.map +1 -0
  39. package/dist/PlatformContracts.js +2 -0
  40. package/dist/PlatformContracts.js.map +1 -0
  41. package/dist/PomBuilder.d.ts +18 -0
  42. package/dist/PomBuilder.js +53 -3
  43. package/dist/PomBuilder.js.map +1 -1
  44. package/dist/PostPrompt.d.ts +110 -0
  45. package/dist/PostPrompt.js +204 -0
  46. package/dist/PostPrompt.js.map +1 -0
  47. package/dist/PromptManager.d.ts +22 -1
  48. package/dist/PromptManager.js +28 -1
  49. package/dist/PromptManager.js.map +1 -1
  50. package/dist/PublicFetch.d.ts +132 -0
  51. package/dist/PublicFetch.js +311 -0
  52. package/dist/PublicFetch.js.map +1 -0
  53. package/dist/RobotsTxt.d.ts +41 -0
  54. package/dist/RobotsTxt.js +152 -0
  55. package/dist/RobotsTxt.js.map +1 -0
  56. package/dist/SWMLHandler.js.map +1 -1
  57. package/dist/SWMLService.d.ts +169 -59
  58. package/dist/SWMLService.js +456 -129
  59. package/dist/SWMLService.js.map +1 -1
  60. package/dist/SchemaUtils.d.ts +115 -2
  61. package/dist/SchemaUtils.js +444 -12
  62. package/dist/SchemaUtils.js.map +1 -1
  63. package/dist/SecurityUtils.d.ts +49 -9
  64. package/dist/SecurityUtils.js +153 -51
  65. package/dist/SecurityUtils.js.map +1 -1
  66. package/dist/SemanticGate.d.ts +183 -0
  67. package/dist/SemanticGate.js +533 -0
  68. package/dist/SemanticGate.js.map +1 -0
  69. package/dist/ServerlessAdapter.d.ts +156 -7
  70. package/dist/ServerlessAdapter.js +399 -42
  71. package/dist/ServerlessAdapter.js.map +1 -1
  72. package/dist/SessionManager.d.ts +11 -2
  73. package/dist/SessionManager.js +50 -18
  74. package/dist/SessionManager.js.map +1 -1
  75. package/dist/SslConfig.d.ts +2 -1
  76. package/dist/SslConfig.js +4 -1
  77. package/dist/SslConfig.js.map +1 -1
  78. package/dist/SwaigActions.generated.d.ts +23 -0
  79. package/dist/SwaigActions.generated.js +8 -0
  80. package/dist/SwaigActions.generated.js.map +1 -0
  81. package/dist/SwaigContracts.d.ts +15 -0
  82. package/dist/SwaigContracts.generated.d.ts +264 -0
  83. package/dist/SwaigContracts.generated.js +12 -0
  84. package/dist/SwaigContracts.generated.js.map +1 -0
  85. package/dist/SwaigContracts.js +2 -0
  86. package/dist/SwaigContracts.js.map +1 -0
  87. package/dist/SwaigFunction.d.ts +139 -7
  88. package/dist/SwaigFunction.js +170 -22
  89. package/dist/SwaigFunction.js.map +1 -1
  90. package/dist/SwmlBuilder.d.ts +68 -19
  91. package/dist/SwmlBuilder.js +74 -38
  92. package/dist/SwmlBuilder.js.map +1 -1
  93. package/dist/SwmlVerbMethods.generated.d.ts +41 -4
  94. package/dist/SwmlVerbMethods.generated.js +1 -1
  95. package/dist/TypeInference.d.ts +39 -3
  96. package/dist/TypeInference.js +256 -16
  97. package/dist/TypeInference.js.map +1 -1
  98. package/dist/WebService.d.ts +79 -11
  99. package/dist/WebService.js +320 -109
  100. package/dist/WebService.js.map +1 -1
  101. package/dist/WebhookMiddleware.d.ts +119 -0
  102. package/dist/WebhookMiddleware.js +271 -0
  103. package/dist/WebhookMiddleware.js.map +1 -0
  104. package/dist/WebhookValidator.d.ts +92 -0
  105. package/dist/WebhookValidator.js +409 -0
  106. package/dist/WebhookValidator.js.map +1 -0
  107. package/dist/agents/BedrockAgent.d.ts +162 -0
  108. package/dist/agents/BedrockAgent.js +323 -0
  109. package/dist/agents/BedrockAgent.js.map +1 -0
  110. package/dist/ai-chat/AIChatClient.d.ts +316 -0
  111. package/dist/ai-chat/AIChatClient.js +535 -0
  112. package/dist/ai-chat/AIChatClient.js.map +1 -0
  113. package/dist/ai-chat/ChatGateway.d.ts +408 -0
  114. package/dist/ai-chat/ChatGateway.js +747 -0
  115. package/dist/ai-chat/ChatGateway.js.map +1 -0
  116. package/dist/ai-chat/HandoffRouter.d.ts +282 -0
  117. package/dist/ai-chat/HandoffRouter.js +518 -0
  118. package/dist/ai-chat/HandoffRouter.js.map +1 -0
  119. package/dist/ai-chat/index.d.ts +12 -0
  120. package/dist/ai-chat/index.js +10 -0
  121. package/dist/ai-chat/index.js.map +1 -0
  122. package/dist/capabilities.d.ts +64 -0
  123. package/dist/capabilities.js +95 -0
  124. package/dist/capabilities.js.map +1 -0
  125. package/dist/cli/agent-loader.d.ts +32 -6
  126. package/dist/cli/agent-loader.js +92 -33
  127. package/dist/cli/agent-loader.js.map +1 -1
  128. package/dist/cli/datamap-exec.d.ts +175 -0
  129. package/dist/cli/datamap-exec.js +1284 -0
  130. package/dist/cli/datamap-exec.js.map +1 -0
  131. package/dist/cli/function-args.d.ts +40 -0
  132. package/dist/cli/function-args.js +146 -0
  133. package/dist/cli/function-args.js.map +1 -0
  134. package/dist/cli/simulation.d.ts +99 -0
  135. package/dist/cli/simulation.js +490 -0
  136. package/dist/cli/simulation.js.map +1 -0
  137. package/dist/cli/swaig-test.d.ts +12 -25
  138. package/dist/cli/swaig-test.js +935 -371
  139. package/dist/cli/swaig-test.js.map +1 -1
  140. package/dist/cli/tsdocs/agentsNote.d.ts +30 -0
  141. package/dist/cli/tsdocs/agentsNote.js +92 -0
  142. package/dist/cli/tsdocs/agentsNote.js.map +1 -0
  143. package/dist/cli/tsdocs/api-index.json +1 -0
  144. package/dist/cli/tsdocs/api.d.ts +91 -0
  145. package/dist/cli/tsdocs/api.js +372 -0
  146. package/dist/cli/tsdocs/api.js.map +1 -0
  147. package/dist/cli/tsdocs/apiTypes.d.ts +64 -0
  148. package/dist/cli/tsdocs/apiTypes.js +7 -0
  149. package/dist/cli/tsdocs/apiTypes.js.map +1 -0
  150. package/dist/cli/tsdocs/bin.d.ts +6 -0
  151. package/dist/cli/tsdocs/bin.js +23 -0
  152. package/dist/cli/tsdocs/bin.js.map +1 -0
  153. package/dist/cli/tsdocs/files.d.ts +108 -0
  154. package/dist/cli/tsdocs/files.js +287 -0
  155. package/dist/cli/tsdocs/files.js.map +1 -0
  156. package/dist/cli/tsdocs/index.d.ts +28 -0
  157. package/dist/cli/tsdocs/index.js +307 -0
  158. package/dist/cli/tsdocs/index.js.map +1 -0
  159. package/dist/cli/tsdocs/live.d.ts +41 -0
  160. package/dist/cli/tsdocs/live.js +202 -0
  161. package/dist/cli/tsdocs/live.js.map +1 -0
  162. package/dist/cli/tsdocs/locate.d.ts +51 -0
  163. package/dist/cli/tsdocs/locate.js +75 -0
  164. package/dist/cli/tsdocs/locate.js.map +1 -0
  165. package/dist/cli/tsdocs/render.d.ts +75 -0
  166. package/dist/cli/tsdocs/render.js +323 -0
  167. package/dist/cli/tsdocs/render.js.map +1 -0
  168. package/dist/cli/tsdocs/topics.d.ts +43 -0
  169. package/dist/cli/tsdocs/topics.js +920 -0
  170. package/dist/cli/tsdocs/topics.js.map +1 -0
  171. package/dist/index.d.ts +49 -68
  172. package/dist/index.js +45 -73
  173. package/dist/index.js.map +1 -1
  174. package/dist/livewire/index.d.ts +229 -155
  175. package/dist/livewire/index.js +298 -195
  176. package/dist/livewire/index.js.map +1 -1
  177. package/dist/llms.txt +65 -0
  178. package/dist/prefabs/CallSessionStore.d.ts +52 -0
  179. package/dist/prefabs/CallSessionStore.js +72 -0
  180. package/dist/prefabs/CallSessionStore.js.map +1 -0
  181. package/dist/prefabs/ConciergeAgent.d.ts +13 -1
  182. package/dist/prefabs/ConciergeAgent.js +36 -31
  183. package/dist/prefabs/ConciergeAgent.js.map +1 -1
  184. package/dist/prefabs/FAQBotAgent.d.ts +9 -1
  185. package/dist/prefabs/FAQBotAgent.js +113 -47
  186. package/dist/prefabs/FAQBotAgent.js.map +1 -1
  187. package/dist/prefabs/InfoGathererAgent.d.ts +22 -3
  188. package/dist/prefabs/InfoGathererAgent.js +67 -58
  189. package/dist/prefabs/InfoGathererAgent.js.map +1 -1
  190. package/dist/prefabs/ReceptionistAgent.d.ts +16 -5
  191. package/dist/prefabs/ReceptionistAgent.js +39 -31
  192. package/dist/prefabs/ReceptionistAgent.js.map +1 -1
  193. package/dist/prefabs/SurveyAgent.d.ts +22 -4
  194. package/dist/prefabs/SurveyAgent.js +84 -68
  195. package/dist/prefabs/SurveyAgent.js.map +1 -1
  196. package/dist/relay/Action.d.ts +44 -21
  197. package/dist/relay/Action.js +75 -17
  198. package/dist/relay/Action.js.map +1 -1
  199. package/dist/relay/Call.d.ts +312 -47
  200. package/dist/relay/Call.js +369 -18
  201. package/dist/relay/Call.js.map +1 -1
  202. package/dist/relay/Deferred.js.map +1 -1
  203. package/dist/relay/Message.d.ts +26 -5
  204. package/dist/relay/Message.js +36 -6
  205. package/dist/relay/Message.js.map +1 -1
  206. package/dist/relay/RelayClient.d.ts +44 -17
  207. package/dist/relay/RelayClient.js +175 -65
  208. package/dist/relay/RelayClient.js.map +1 -1
  209. package/dist/relay/RelayError.d.ts +14 -0
  210. package/dist/relay/RelayError.js +15 -0
  211. package/dist/relay/RelayError.js.map +1 -1
  212. package/dist/relay/RelayEvent.d.ts +96 -65
  213. package/dist/relay/RelayEvent.js +85 -56
  214. package/dist/relay/RelayEvent.js.map +1 -1
  215. package/dist/relay/closedSets.d.ts +111 -0
  216. package/dist/relay/closedSets.js +83 -0
  217. package/dist/relay/closedSets.js.map +1 -0
  218. package/dist/relay/index.d.ts +3 -1
  219. package/dist/relay/index.js +1 -0
  220. package/dist/relay/index.js.map +1 -1
  221. package/dist/relay/normalize.js.map +1 -1
  222. package/dist/relay/protocol.types.generated.d.ts +1195 -0
  223. package/dist/relay/protocol.types.generated.js +8 -0
  224. package/dist/relay/protocol.types.generated.js.map +1 -0
  225. package/dist/relay/types.d.ts +73 -42
  226. package/dist/rest/HttpClient.d.ts +36 -8
  227. package/dist/rest/HttpClient.js +233 -40
  228. package/dist/rest/HttpClient.js.map +1 -1
  229. package/dist/rest/RequestOptions.d.ts +110 -0
  230. package/dist/rest/RequestOptions.js +113 -0
  231. package/dist/rest/RequestOptions.js.map +1 -0
  232. package/dist/rest/RestError.d.ts +52 -6
  233. package/dist/rest/RestError.js +89 -5
  234. package/dist/rest/RestError.js.map +1 -1
  235. package/dist/rest/base/CrudResource.d.ts +16 -26
  236. package/dist/rest/base/CrudResource.js +19 -33
  237. package/dist/rest/base/CrudResource.js.map +1 -1
  238. package/dist/rest/base/CrudWithAddresses.d.ts +3 -2
  239. package/dist/rest/base/CrudWithAddresses.js +2 -2
  240. package/dist/rest/base/CrudWithAddresses.js.map +1 -1
  241. package/dist/rest/base/FabricResource.d.ts +15 -0
  242. package/dist/rest/base/FabricResource.js +16 -0
  243. package/dist/rest/base/FabricResource.js.map +1 -0
  244. package/dist/rest/base/ReadResource.d.ts +62 -0
  245. package/dist/rest/base/ReadResource.js +69 -0
  246. package/dist/rest/base/ReadResource.js.map +1 -0
  247. package/dist/rest/callHandler.d.ts +5 -2
  248. package/dist/rest/callHandler.js +4 -1
  249. package/dist/rest/callHandler.js.map +1 -1
  250. package/dist/rest/index.d.ts +18 -77
  251. package/dist/rest/index.js +47 -120
  252. package/dist/rest/index.js.map +1 -1
  253. package/dist/rest/namespaces/_client_tree_generated.d.ts +103 -0
  254. package/dist/rest/namespaces/_client_tree_generated.js +171 -0
  255. package/dist/rest/namespaces/_client_tree_generated.js.map +1 -0
  256. package/dist/rest/namespaces/addresses.d.ts +3 -42
  257. package/dist/rest/namespaces/addresses.js +3 -50
  258. package/dist/rest/namespaces/addresses.js.map +1 -1
  259. package/dist/rest/namespaces/calling.d.ts +6 -378
  260. package/dist/rest/namespaces/calling.js +6 -473
  261. package/dist/rest/namespaces/calling.js.map +1 -1
  262. package/dist/rest/namespaces/calling.resources.generated.d.ts +165 -0
  263. package/dist/rest/namespaces/calling.resources.generated.js +477 -0
  264. package/dist/rest/namespaces/calling.resources.generated.js.map +1 -0
  265. package/dist/rest/namespaces/calling.types.generated.d.ts +2917 -0
  266. package/dist/rest/namespaces/calling.types.generated.js +8 -0
  267. package/dist/rest/namespaces/calling.types.generated.js.map +1 -0
  268. package/dist/rest/namespaces/chat.d.ts +4 -18
  269. package/dist/rest/namespaces/chat.js +4 -21
  270. package/dist/rest/namespaces/chat.js.map +1 -1
  271. package/dist/rest/namespaces/chat.resources.generated.d.ts +12 -0
  272. package/dist/rest/namespaces/chat.resources.generated.js +29 -0
  273. package/dist/rest/namespaces/chat.resources.generated.js.map +1 -0
  274. package/dist/rest/namespaces/chat.types.generated.d.ts +56 -0
  275. package/dist/rest/namespaces/chat.types.generated.js +8 -0
  276. package/dist/rest/namespaces/chat.types.generated.js.map +1 -0
  277. package/dist/rest/namespaces/datasphere.d.ts +6 -62
  278. package/dist/rest/namespaces/datasphere.js +6 -72
  279. package/dist/rest/namespaces/datasphere.js.map +1 -1
  280. package/dist/rest/namespaces/datasphere.resources.generated.d.ts +25 -0
  281. package/dist/rest/namespaces/datasphere.resources.generated.js +50 -0
  282. package/dist/rest/namespaces/datasphere.resources.generated.js.map +1 -0
  283. package/dist/rest/namespaces/datasphere.types.generated.d.ts +180 -0
  284. package/dist/rest/namespaces/datasphere.types.generated.js +8 -0
  285. package/dist/rest/namespaces/datasphere.types.generated.js.map +1 -0
  286. package/dist/rest/namespaces/fabric.d.ts +11 -327
  287. package/dist/rest/namespaces/fabric.js +14 -439
  288. package/dist/rest/namespaces/fabric.js.map +1 -1
  289. package/dist/rest/namespaces/fabric.resources.generated.d.ts +195 -0
  290. package/dist/rest/namespaces/fabric.resources.generated.js +399 -0
  291. package/dist/rest/namespaces/fabric.resources.generated.js.map +1 -0
  292. package/dist/rest/namespaces/fabric.types.generated.d.ts +4557 -0
  293. package/dist/rest/namespaces/fabric.types.generated.js +8 -0
  294. package/dist/rest/namespaces/fabric.types.generated.js.map +1 -0
  295. package/dist/rest/namespaces/fax.resources.generated.d.ts +6 -0
  296. package/dist/rest/namespaces/fax.resources.generated.js +14 -0
  297. package/dist/rest/namespaces/fax.resources.generated.js.map +1 -0
  298. package/dist/rest/namespaces/fax.types.generated.d.ts +131 -0
  299. package/dist/rest/namespaces/fax.types.generated.js +8 -0
  300. package/dist/rest/namespaces/fax.types.generated.js.map +1 -0
  301. package/dist/rest/namespaces/imported-numbers.d.ts +3 -18
  302. package/dist/rest/namespaces/imported-numbers.js +3 -21
  303. package/dist/rest/namespaces/imported-numbers.js.map +1 -1
  304. package/dist/rest/namespaces/logs.d.ts +10 -101
  305. package/dist/rest/namespaces/logs.js +10 -128
  306. package/dist/rest/namespaces/logs.js.map +1 -1
  307. package/dist/rest/namespaces/logs.resources.generated.d.ts +9 -0
  308. package/dist/rest/namespaces/logs.resources.generated.js +17 -0
  309. package/dist/rest/namespaces/logs.resources.generated.js.map +1 -0
  310. package/dist/rest/namespaces/logs.types.generated.d.ts +131 -0
  311. package/dist/rest/namespaces/logs.types.generated.js +8 -0
  312. package/dist/rest/namespaces/logs.types.generated.js.map +1 -0
  313. package/dist/rest/namespaces/lookup.d.ts +3 -25
  314. package/dist/rest/namespaces/lookup.js +3 -27
  315. package/dist/rest/namespaces/lookup.js.map +1 -1
  316. package/dist/rest/namespaces/message.resources.generated.d.ts +6 -0
  317. package/dist/rest/namespaces/message.resources.generated.js +14 -0
  318. package/dist/rest/namespaces/message.resources.generated.js.map +1 -0
  319. package/dist/rest/namespaces/message.types.generated.d.ts +122 -0
  320. package/dist/rest/namespaces/message.types.generated.js +8 -0
  321. package/dist/rest/namespaces/message.types.generated.js.map +1 -0
  322. package/dist/rest/namespaces/messages.resources.generated.d.ts +18 -0
  323. package/dist/rest/namespaces/messages.resources.generated.js +44 -0
  324. package/dist/rest/namespaces/messages.resources.generated.js.map +1 -0
  325. package/dist/rest/namespaces/messages.types.generated.d.ts +99 -0
  326. package/dist/rest/namespaces/messages.types.generated.js +8 -0
  327. package/dist/rest/namespaces/messages.types.generated.js.map +1 -0
  328. package/dist/rest/namespaces/mfa.d.ts +3 -42
  329. package/dist/rest/namespaces/mfa.js +3 -49
  330. package/dist/rest/namespaces/mfa.js.map +1 -1
  331. package/dist/rest/namespaces/number-groups.d.ts +3 -45
  332. package/dist/rest/namespaces/number-groups.js +3 -53
  333. package/dist/rest/namespaces/number-groups.js.map +1 -1
  334. package/dist/rest/namespaces/phone-numbers.d.ts +8 -196
  335. package/dist/rest/namespaces/phone-numbers.js +8 -230
  336. package/dist/rest/namespaces/phone-numbers.js.map +1 -1
  337. package/dist/rest/namespaces/project.d.ts +6 -42
  338. package/dist/rest/namespaces/project.js +6 -51
  339. package/dist/rest/namespaces/project.js.map +1 -1
  340. package/dist/rest/namespaces/project.resources.generated.d.ts +17 -0
  341. package/dist/rest/namespaces/project.resources.generated.js +44 -0
  342. package/dist/rest/namespaces/project.resources.generated.js.map +1 -0
  343. package/dist/rest/namespaces/project.types.generated.d.ts +58 -0
  344. package/dist/rest/namespaces/project.types.generated.js +8 -0
  345. package/dist/rest/namespaces/project.types.generated.js.map +1 -0
  346. package/dist/rest/namespaces/projects.resources.generated.d.ts +12 -0
  347. package/dist/rest/namespaces/projects.resources.generated.js +25 -0
  348. package/dist/rest/namespaces/projects.resources.generated.js.map +1 -0
  349. package/dist/rest/namespaces/projects.types.generated.d.ts +77 -0
  350. package/dist/rest/namespaces/projects.types.generated.js +8 -0
  351. package/dist/rest/namespaces/projects.types.generated.js.map +1 -0
  352. package/dist/rest/namespaces/pubsub.d.ts +4 -18
  353. package/dist/rest/namespaces/pubsub.js +4 -21
  354. package/dist/rest/namespaces/pubsub.js.map +1 -1
  355. package/dist/rest/namespaces/pubsub.resources.generated.d.ts +12 -0
  356. package/dist/rest/namespaces/pubsub.resources.generated.js +29 -0
  357. package/dist/rest/namespaces/pubsub.resources.generated.js.map +1 -0
  358. package/dist/rest/namespaces/pubsub.types.generated.d.ts +60 -0
  359. package/dist/rest/namespaces/pubsub.types.generated.js +8 -0
  360. package/dist/rest/namespaces/pubsub.types.generated.js.map +1 -0
  361. package/dist/rest/namespaces/queues.d.ts +3 -38
  362. package/dist/rest/namespaces/queues.js +3 -44
  363. package/dist/rest/namespaces/queues.js.map +1 -1
  364. package/dist/rest/namespaces/recordings.d.ts +3 -34
  365. package/dist/rest/namespaces/recordings.js +3 -40
  366. package/dist/rest/namespaces/recordings.js.map +1 -1
  367. package/dist/rest/namespaces/registry.d.ts +6 -137
  368. package/dist/rest/namespaces/registry.js +6 -173
  369. package/dist/rest/namespaces/registry.js.map +1 -1
  370. package/dist/rest/namespaces/relay-rest.resources.generated.d.ts +168 -0
  371. package/dist/rest/namespaces/relay-rest.resources.generated.js +430 -0
  372. package/dist/rest/namespaces/relay-rest.resources.generated.js.map +1 -0
  373. package/dist/rest/namespaces/relay-rest.types.generated.d.ts +1906 -0
  374. package/dist/rest/namespaces/relay-rest.types.generated.js +8 -0
  375. package/dist/rest/namespaces/relay-rest.types.generated.js.map +1 -0
  376. package/dist/rest/namespaces/short-codes.d.ts +3 -35
  377. package/dist/rest/namespaces/short-codes.js +3 -41
  378. package/dist/rest/namespaces/short-codes.js.map +1 -1
  379. package/dist/rest/namespaces/sip-profile.d.ts +3 -24
  380. package/dist/rest/namespaces/sip-profile.js +3 -29
  381. package/dist/rest/namespaces/sip-profile.js.map +1 -1
  382. package/dist/rest/namespaces/verified-callers.d.ts +3 -29
  383. package/dist/rest/namespaces/verified-callers.js +3 -34
  384. package/dist/rest/namespaces/verified-callers.js.map +1 -1
  385. package/dist/rest/namespaces/video.d.ts +10 -227
  386. package/dist/rest/namespaces/video.js +10 -288
  387. package/dist/rest/namespaces/video.js.map +1 -1
  388. package/dist/rest/namespaces/video.resources.generated.d.ts +81 -0
  389. package/dist/rest/namespaces/video.resources.generated.js +171 -0
  390. package/dist/rest/namespaces/video.resources.generated.js.map +1 -0
  391. package/dist/rest/namespaces/video.types.generated.d.ts +771 -0
  392. package/dist/rest/namespaces/video.types.generated.js +8 -0
  393. package/dist/rest/namespaces/video.types.generated.js.map +1 -0
  394. package/dist/rest/namespaces/voice.resources.generated.d.ts +9 -0
  395. package/dist/rest/namespaces/voice.resources.generated.js +17 -0
  396. package/dist/rest/namespaces/voice.resources.generated.js.map +1 -0
  397. package/dist/rest/namespaces/voice.types.generated.d.ts +214 -0
  398. package/dist/rest/namespaces/voice.types.generated.js +8 -0
  399. package/dist/rest/namespaces/voice.types.generated.js.map +1 -0
  400. package/dist/rest/pagination.d.ts +5 -1
  401. package/dist/rest/pagination.js +40 -20
  402. package/dist/rest/pagination.js.map +1 -1
  403. package/dist/rest/types.d.ts +21 -3
  404. package/dist/schema.json +299 -98
  405. package/dist/skills/SkillBase.d.ts +111 -21
  406. package/dist/skills/SkillBase.js +100 -17
  407. package/dist/skills/SkillBase.js.map +1 -1
  408. package/dist/skills/SkillManager.d.ts +66 -13
  409. package/dist/skills/SkillManager.js +101 -20
  410. package/dist/skills/SkillManager.js.map +1 -1
  411. package/dist/skills/SkillName.d.ts +44 -0
  412. package/dist/skills/SkillName.js +2 -0
  413. package/dist/skills/SkillName.js.map +1 -0
  414. package/dist/skills/SkillRegistry.d.ts +22 -11
  415. package/dist/skills/SkillRegistry.js +47 -17
  416. package/dist/skills/SkillRegistry.js.map +1 -1
  417. package/dist/skills/builtin/api_ninjas_trivia.d.ts +3 -1
  418. package/dist/skills/builtin/api_ninjas_trivia.js +18 -6
  419. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
  420. package/dist/skills/builtin/ask_claude.d.ts +14 -4
  421. package/dist/skills/builtin/ask_claude.js +36 -14
  422. package/dist/skills/builtin/ask_claude.js.map +1 -1
  423. package/dist/skills/builtin/claude_skills.d.ts +3 -1
  424. package/dist/skills/builtin/claude_skills.js +19 -15
  425. package/dist/skills/builtin/claude_skills.js.map +1 -1
  426. package/dist/skills/builtin/custom_skills.d.ts +10 -3
  427. package/dist/skills/builtin/custom_skills.js +26 -9
  428. package/dist/skills/builtin/custom_skills.js.map +1 -1
  429. package/dist/skills/builtin/datasphere.d.ts +5 -3
  430. package/dist/skills/builtin/datasphere.js +21 -22
  431. package/dist/skills/builtin/datasphere.js.map +1 -1
  432. package/dist/skills/builtin/datasphere_serverless.d.ts +12 -1
  433. package/dist/skills/builtin/datasphere_serverless.js +17 -6
  434. package/dist/skills/builtin/datasphere_serverless.js.map +1 -1
  435. package/dist/skills/builtin/datetime.d.ts +3 -1
  436. package/dist/skills/builtin/datetime.js +11 -7
  437. package/dist/skills/builtin/datetime.js.map +1 -1
  438. package/dist/skills/builtin/google_maps.d.ts +29 -14
  439. package/dist/skills/builtin/google_maps.js +89 -269
  440. package/dist/skills/builtin/google_maps.js.map +1 -1
  441. package/dist/skills/builtin/index.d.ts +8 -6
  442. package/dist/skills/builtin/index.js +8 -6
  443. package/dist/skills/builtin/index.js.map +1 -1
  444. package/dist/skills/builtin/info_gatherer.d.ts +4 -2
  445. package/dist/skills/builtin/info_gatherer.js +20 -12
  446. package/dist/skills/builtin/info_gatherer.js.map +1 -1
  447. package/dist/skills/builtin/joke.d.ts +16 -6
  448. package/dist/skills/builtin/joke.js +54 -37
  449. package/dist/skills/builtin/joke.js.map +1 -1
  450. package/dist/skills/builtin/math.d.ts +3 -1
  451. package/dist/skills/builtin/math.js +14 -9
  452. package/dist/skills/builtin/math.js.map +1 -1
  453. package/dist/skills/builtin/mcp_gateway.d.ts +34 -5
  454. package/dist/skills/builtin/mcp_gateway.js +77 -46
  455. package/dist/skills/builtin/mcp_gateway.js.map +1 -1
  456. package/dist/skills/builtin/native_vector_search.d.ts +19 -5
  457. package/dist/skills/builtin/native_vector_search.js +179 -61
  458. package/dist/skills/builtin/native_vector_search.js.map +1 -1
  459. package/dist/skills/builtin/play_background_file.d.ts +21 -15
  460. package/dist/skills/builtin/play_background_file.js +43 -122
  461. package/dist/skills/builtin/play_background_file.js.map +1 -1
  462. package/dist/skills/builtin/spider.d.ts +42 -4
  463. package/dist/skills/builtin/spider.js +277 -104
  464. package/dist/skills/builtin/spider.js.map +1 -1
  465. package/dist/skills/builtin/swml_transfer.d.ts +14 -3
  466. package/dist/skills/builtin/swml_transfer.js +45 -24
  467. package/dist/skills/builtin/swml_transfer.js.map +1 -1
  468. package/dist/skills/builtin/weather_api.d.ts +24 -13
  469. package/dist/skills/builtin/weather_api.js +38 -30
  470. package/dist/skills/builtin/weather_api.js.map +1 -1
  471. package/dist/skills/builtin/web_search.d.ts +48 -10
  472. package/dist/skills/builtin/web_search.js +294 -100
  473. package/dist/skills/builtin/web_search.js.map +1 -1
  474. package/dist/skills/builtin/wikipedia_search.d.ts +4 -2
  475. package/dist/skills/builtin/wikipedia_search.js +14 -13
  476. package/dist/skills/builtin/wikipedia_search.js.map +1 -1
  477. package/dist/skills/index.d.ts +3 -2
  478. package/dist/skills/index.js +1 -1
  479. package/dist/skills/index.js.map +1 -1
  480. package/dist/swml_verbs_generated.d.ts +2824 -0
  481. package/dist/swml_verbs_generated.js +12 -0
  482. package/dist/swml_verbs_generated.js.map +1 -0
  483. package/dist/types.d.ts +59 -6
  484. package/dist/web.d.ts +27 -0
  485. package/dist/web.js +20 -0
  486. package/dist/web.js.map +1 -0
  487. package/docs/agent-guide.md +1034 -0
  488. package/docs/ai_chat.md +560 -0
  489. package/docs/api-reference.md +3641 -0
  490. package/docs/architecture.md +846 -0
  491. package/docs/bedrock_agent.md +411 -0
  492. package/docs/cli-guide.md +403 -0
  493. package/docs/cloud_functions_guide.md +399 -0
  494. package/docs/configuration.md +548 -0
  495. package/docs/contexts-guide.md +884 -0
  496. package/docs/datamap-guide.md +1207 -0
  497. package/docs/developer_pain_points.md +548 -0
  498. package/docs/llm_parameters.md +298 -0
  499. package/docs/mcp_gateway_reference.md +354 -0
  500. package/docs/mcp_integration.md +162 -0
  501. package/docs/pgi_agent_guide.md +1820 -0
  502. package/docs/prefabs-guide.md +815 -0
  503. package/docs/programmatically_governed_inference.md +301 -0
  504. package/docs/sdk_features.md +501 -0
  505. package/docs/security.md +559 -0
  506. package/docs/serverless-guide.md +520 -0
  507. package/docs/skills-guide.md +1223 -0
  508. package/docs/skills-system.md +405 -0
  509. package/docs/skills_parameter_schema.md +417 -0
  510. package/docs/swaig-reference.md +1986 -0
  511. package/docs/swml_service_guide.md +573 -0
  512. package/docs/third_party_skills.md +410 -0
  513. package/docs/web_service.md +666 -0
  514. package/examples/README.md +202 -0
  515. package/examples/advanced-datamap.ts +108 -0
  516. package/examples/advanced-dynamic-config.ts +70 -0
  517. package/examples/auto-vivified.ts +95 -0
  518. package/examples/call-flow.ts +65 -0
  519. package/examples/comprehensive-dynamic.ts +125 -0
  520. package/examples/contexts-steps.ts +65 -0
  521. package/examples/custom-path.ts +45 -0
  522. package/examples/datamap-tools.ts +51 -0
  523. package/examples/datasphere-multi-instance.ts +66 -0
  524. package/examples/datasphere-serverless-env.ts +87 -0
  525. package/examples/datasphere-webhook-env.ts +65 -0
  526. package/examples/datasphere.ts +56 -0
  527. package/examples/declarative.ts +100 -0
  528. package/examples/dynamic-config.ts +54 -0
  529. package/examples/dynamic-info-gatherer.ts +69 -0
  530. package/examples/dynamic-swml-service.ts +67 -0
  531. package/examples/gather-info.ts +95 -0
  532. package/examples/gather-per-question-functions-demo.ts +139 -0
  533. package/examples/joke-agent.ts +34 -0
  534. package/examples/kubernetes-agent.ts +45 -0
  535. package/examples/llm-params.ts +75 -0
  536. package/examples/mcp-agent.ts +89 -0
  537. package/examples/mcp-gateway.ts +81 -0
  538. package/examples/multi-agent.ts +80 -0
  539. package/examples/multi-endpoint.ts +79 -0
  540. package/examples/pgi/case-domain.ts +114 -0
  541. package/examples/pgi/serve.ts +16 -0
  542. package/examples/pgi/support-agent.ts +265 -0
  543. package/examples/pom-prompt.ts +70 -0
  544. package/examples/prefab-concierge.ts +42 -0
  545. package/examples/prefab-faq.ts +58 -0
  546. package/examples/prefab-info-gatherer.ts +33 -0
  547. package/examples/prefab-receptionist.ts +36 -0
  548. package/examples/prefab-survey.ts +69 -0
  549. package/examples/quickstart-agent.ts +29 -0
  550. package/examples/quickstart-relay.ts +25 -0
  551. package/examples/quickstart-rest.ts +25 -0
  552. package/examples/record-call.ts +65 -0
  553. package/examples/relay-demo.ts +33 -0
  554. package/examples/room-and-sip.ts +93 -0
  555. package/examples/serverless-lambda.ts +43 -0
  556. package/examples/session-state.ts +83 -0
  557. package/examples/simple-agent.ts +36 -0
  558. package/examples/simple-static.ts +29 -0
  559. package/examples/skills-demo.ts +41 -0
  560. package/examples/step-function-inheritance-demo.ts +124 -0
  561. package/examples/swaig-features.ts +193 -0
  562. package/examples/swml-service-routing.ts +66 -0
  563. package/examples/swml-service.ts +38 -0
  564. package/examples/swmlservice_ai_sidecar.ts +104 -0
  565. package/examples/swmlservice_swaig_standalone.ts +79 -0
  566. package/examples/tap.ts +67 -0
  567. package/examples/typed-tools.ts +68 -0
  568. package/examples/verb-methods.ts +45 -0
  569. package/examples/web-search-multi-instance.ts +75 -0
  570. package/examples/web-search.ts +38 -0
  571. package/examples/wikipedia.ts +36 -0
  572. package/livewire/README.md +164 -0
  573. package/livewire/docs/migration-guide.md +251 -0
  574. package/livewire/examples/livewire-basic-agent.ts +74 -0
  575. package/livewire/examples/livewire-handoff.ts +196 -0
  576. package/livewire/examples/livewire-multi-tool.ts +121 -0
  577. package/package.json +85 -13
  578. package/relay/README.md +101 -0
  579. package/relay/docs/call-methods.md +622 -0
  580. package/relay/docs/client-reference.md +281 -0
  581. package/relay/docs/events.md +193 -0
  582. package/relay/docs/getting-started.md +221 -0
  583. package/relay/docs/guide.md +386 -0
  584. package/relay/docs/messaging.md +246 -0
  585. package/relay/examples/relay-inbound.ts +66 -0
  586. package/relay/examples/relay-messaging.ts +74 -0
  587. package/relay/examples/relay-outbound.ts +76 -0
  588. package/rest/README.md +141 -0
  589. package/rest/docs/calling.md +313 -0
  590. package/rest/docs/client-reference.md +149 -0
  591. package/rest/docs/fabric.md +192 -0
  592. package/rest/docs/getting-started.md +138 -0
  593. package/rest/docs/guide.md +421 -0
  594. package/rest/docs/namespaces.md +367 -0
  595. package/rest/docs/phone-binding.md +116 -0
  596. package/rest/examples/rest-10dlc-registration.ts +177 -0
  597. package/rest/examples/rest-bind-phone-to-swml-webhook.ts +66 -0
  598. package/rest/examples/rest-calling-ivr-and-ai.ts +136 -0
  599. package/rest/examples/rest-calling-play-and-record.ts +98 -0
  600. package/rest/examples/rest-client.ts +59 -0
  601. package/rest/examples/rest-datasphere-search.ts +81 -0
  602. package/rest/examples/rest-fabric-conferences-and-routing.ts +147 -0
  603. package/rest/examples/rest-fabric-subscribers-and-sip.ts +106 -0
  604. package/rest/examples/rest-fabric-swml-and-callflows.ts +101 -0
  605. package/rest/examples/rest-manage-resources.ts +64 -0
  606. package/rest/examples/rest-phone-number-management.ts +200 -0
  607. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  608. package/rest/examples/rest-video-rooms.ts +186 -0
  609. package/tutorial/fred/fred.ts +218 -0
  610. package/tutorial/fred/tutorial/01-introduction.md +141 -0
  611. package/tutorial/fred/tutorial/02-setup.md +304 -0
  612. package/tutorial/fred/tutorial/03-basic-agent.md +284 -0
  613. package/tutorial/fred/tutorial/04-wikipedia-skill.md +298 -0
  614. package/tutorial/fred/tutorial/05-custom-functions.md +347 -0
  615. package/tutorial/fred/tutorial/06-running-testing.md +642 -0
  616. package/tutorial/fred/tutorial/README.md +56 -0
  617. package/tutorial/fred/tutorial/appendix-complete-code.md +632 -0
  618. package/tutorial/fred/tutorial/appendix-docker-deployment.md +504 -0
  619. package/tutorial/full-guardrails-agent/handlers.ts +436 -0
  620. package/tutorial/full-guardrails-agent/penny.ts +305 -0
  621. package/tutorial/full-guardrails-agent/reservations.ts +1109 -0
  622. package/tutorial/full-guardrails-agent/tutorial/01-why-guardrails.md +149 -0
  623. package/tutorial/full-guardrails-agent/tutorial/02-design-first.md +139 -0
  624. package/tutorial/full-guardrails-agent/tutorial/03-rules-first.md +422 -0
  625. package/tutorial/full-guardrails-agent/tutorial/04-the-shell.md +238 -0
  626. package/tutorial/full-guardrails-agent/tutorial/05-steps-and-scoping.md +247 -0
  627. package/tutorial/full-guardrails-agent/tutorial/06-tools-that-decide.md +467 -0
  628. package/tutorial/full-guardrails-agent/tutorial/07-gather-and-projection.md +160 -0
  629. package/tutorial/full-guardrails-agent/tutorial/08-the-verification-gate.md +333 -0
  630. package/tutorial/full-guardrails-agent/tutorial/09-people-and-endings.md +313 -0
  631. package/tutorial/full-guardrails-agent/tutorial/10-testing-and-running.md +387 -0
  632. package/tutorial/full-guardrails-agent/tutorial/README.md +106 -0
  633. package/tutorial/full-guardrails-agent/tutorial/appendix-complete-code.md +2207 -0
  634. package/tutorial/full-guardrails-agent/tutorial/appendix-deployment.md +191 -0
  635. package/tutorial/full-guardrails-agent/tutorial/appendix-technique-map.md +117 -0
  636. package/tutorial/full-guardrails-agent/workflow.ts +219 -0
  637. package/tutorial/multi_agents/README.md +175 -0
  638. package/tutorial/multi_agents/advanced_agent.ts +395 -0
  639. package/tutorial/multi_agents/extending_agents.ts +641 -0
  640. package/tutorial/multi_agents/knowledge.ts +59 -0
  641. package/tutorial/multi_agents/lesson1_first_agent.md +368 -0
  642. package/tutorial/multi_agents/lesson2_knowledge_bases.md +404 -0
  643. package/tutorial/multi_agents/lesson3_multi_agent_systems.md +621 -0
  644. package/tutorial/multi_agents/lesson4_advanced_features.md +805 -0
  645. package/tutorial/multi_agents/lesson5_extending_agents.md +856 -0
  646. package/tutorial/multi_agents/pc_builder.ts +529 -0
  647. package/tutorial/multi_agents/sales_agent.ts +88 -0
  648. package/tutorial/multi_agents/sales_agent_with_search.ts +116 -0
  649. package/tutorial/multi_agents/sales_knowledge.md +139 -0
  650. package/tutorial/multi_agents/support_knowledge.md +256 -0
  651. package/dist/cli/mock-data.d.ts +0 -37
  652. package/dist/cli/mock-data.js +0 -80
  653. package/dist/cli/mock-data.js.map +0 -1
  654. package/dist/generateVerbTypes.d.ts +0 -11
  655. package/dist/generateVerbTypes.js +0 -265
  656. package/dist/generateVerbTypes.js.map +0 -1
  657. package/dist/rest/namespaces/compat.d.ts +0 -585
  658. package/dist/rest/namespaces/compat.js +0 -735
  659. package/dist/rest/namespaces/compat.js.map +0 -1
@@ -1,17 +1,96 @@
1
1
  /**
2
- * FunctionResult - Builder for SWAIG function responses.
2
+ * FunctionResult: builder for SWAIG function responses.
3
3
  *
4
- * Carries response text and a list of structured actions (connect, hangup, SMS, etc.).
5
- * Every mutating method returns `this` for fluent chaining.
4
+ * Carries a response for the model and a list of structured actions (connect,
5
+ * hangup, SMS and others). Every mutating method returns `this` for fluent chaining.
6
6
  */
7
+ /**
8
+ * A SWML variable reference, such as `${timeout}` or `%{timeout}`, which the
9
+ * SWML schema accepts wherever it accepts an integer or a boolean.
10
+ */
11
+ const SWML_VAR = /^[$%]\{.*\}$/;
12
+ /** Show a rejected value in an error message: strings quoted, the rest as written. */
13
+ function showValue(value) {
14
+ return typeof value === 'string' ? JSON.stringify(value) : String(value);
15
+ }
16
+ /**
17
+ * Return `value` as an integer for a SWML verb, or throw.
18
+ *
19
+ * Accepts an integer, a string of digits (optionally negative, surrounding
20
+ * spaces ignored), or a SWML variable reference, which is passed through as
21
+ * written. An integer must be within `minimum` and `maximum` when they are
22
+ * given. Mirrors Python's `_swml_int()`.
23
+ */
24
+ function swmlInt(name, value, minimum, maximum) {
25
+ let num;
26
+ if (typeof value === 'string') {
27
+ const text = value.trim();
28
+ if (SWML_VAR.test(text))
29
+ return text;
30
+ if (/^-?\d+$/.test(text))
31
+ num = Number(text);
32
+ }
33
+ else if (typeof value === 'number' && Number.isInteger(value)) {
34
+ num = value;
35
+ }
36
+ const inRange = num !== undefined &&
37
+ (minimum === undefined || num >= minimum) &&
38
+ (maximum === undefined || num <= maximum);
39
+ if (!inRange) {
40
+ let expected = 'an integer';
41
+ if (minimum !== undefined && maximum !== undefined) {
42
+ expected = `an integer from ${minimum} to ${maximum}`;
43
+ }
44
+ else if (minimum !== undefined) {
45
+ expected = `an integer of at least ${minimum}`;
46
+ }
47
+ else if (maximum !== undefined) {
48
+ expected = `an integer of at most ${maximum}`;
49
+ }
50
+ throw new Error(`${name} must be ${expected}, got ${showValue(value)}`);
51
+ }
52
+ return num; // inRange implies num is set
53
+ }
54
+ /**
55
+ * Return `value` as a boolean for a SWML verb, or throw.
56
+ *
57
+ * Accepts a boolean, the strings `"true"` and `"false"` in any case, or a
58
+ * SWML variable reference, which is passed through as written. Mirrors
59
+ * Python's `_swml_bool()`.
60
+ */
61
+ function swmlBool(name, value) {
62
+ if (typeof value === 'boolean')
63
+ return value;
64
+ if (typeof value === 'string') {
65
+ const text = value.trim();
66
+ const lower = text.toLowerCase();
67
+ if (lower === 'true' || lower === 'false')
68
+ return lower === 'true';
69
+ if (SWML_VAR.test(text))
70
+ return text;
71
+ }
72
+ throw new Error(`${name} must be a boolean, got ${showValue(value)}`);
73
+ }
7
74
  /**
8
75
  * Builder for SWAIG function responses.
9
76
  *
10
- * Carries response text (what the AI says to the caller) and a list of structured
11
- * actions (connect, hangup, SMS, record, transfer, etc.) that the SignalWire platform
12
- * executes after the AI speaks. Every mutating method returns `this` for fluent chaining.
77
+ * Carries a response and a list of structured actions (connect, hangup, SMS,
78
+ * record, transfer and others) that the SignalWire platform executes. Every
79
+ * mutating method returns `this` for fluent chaining.
80
+ *
81
+ * The response is context for the model, not speech played to the caller. The
82
+ * model reads it and decides what to say. It can carry facts, an instruction, or
83
+ * both. The clearest form keeps them apart with {@link setToolResponse}, or the
84
+ * constructor's `toolResult` and `toolPrompt`: `tool_result` holds the facts and
85
+ * `tool_prompt` the instruction. A plain string of facts ("Order 1234 shipped
86
+ * Tuesday.") or an instruction ("Tell the caller their order shipped Tuesday.")
87
+ * also works. Avoid a line written for the caller ("Your order shipped
88
+ * Tuesday."): the model interprets it rather than speaking it, so it can drift
89
+ * or be rephrased. Set `postProcess` when the caller must hear something before
90
+ * an action takes effect (hold, connect, transfer, hangup).
13
91
  *
14
- * Return an instance (or a promise that resolves to one) from any SWAIG tool handler.
92
+ * Return an instance (or a promise that resolves to one) from any SWAIG tool
93
+ * handler. Handlers receive `(args, rawData, agent)`.
15
94
  *
16
95
  * @example Simple text response
17
96
  * ```ts
@@ -19,7 +98,7 @@
19
98
  * name: 'say_hi',
20
99
  * description: 'Say hello.',
21
100
  * parameters: { type: 'object', properties: {} },
22
- * handler: () => new FunctionResult('Hello there!'),
101
+ * handler: () => new FunctionResult('Greet the caller warmly.'),
23
102
  * });
24
103
  * ```
25
104
  *
@@ -30,48 +109,101 @@
30
109
  * description: 'Forward the caller to sales.',
31
110
  * parameters: { type: 'object', properties: {} },
32
111
  * handler: () =>
33
- * new FunctionResult('Connecting you to sales now.').connect('+15551112222'),
112
+ * new FunctionResult('Tell the caller you are connecting them to sales.', true).connect(
113
+ * '+15551112222',
114
+ * ),
34
115
  * });
35
116
  * ```
36
117
  *
37
118
  * @example Chained actions
38
119
  * ```ts
39
- * new FunctionResult("Thanks, you're all set.")
120
+ * new FunctionResult('Tell the caller they are all set and say goodbye.', true)
40
121
  * .sendSms({ toNumber: '+15551234567', fromNumber: '+15559998888', body: 'Confirmation!' })
41
122
  * .hangup();
42
123
  * ```
43
124
  *
44
- * @see {@link AgentBase.defineTool} — where handlers return a `FunctionResult`
45
- * @see {@link DataMap} — alternative for purely data-driven (no handler) tools
125
+ * @see {@link AgentBase.defineTool}, where handlers return a `FunctionResult`
126
+ * @see {@link DataMap}, an alternative for data-driven tools with no handler
46
127
  */
47
128
  export class FunctionResult {
48
- /** The text response returned to the AI agent. */
129
+ /**
130
+ * The response string returned to the model as context. When the structured
131
+ * form is set ({@link setToolResponse}), that is sent instead.
132
+ */
49
133
  response;
134
+ /** The structured response set by {@link setToolResponse}, sent instead of `response`. */
135
+ _toolResponse = null;
50
136
  /** Ordered list of actions to execute after the response. */
51
137
  action;
52
138
  /** Whether actions should be post-processed after the AI responds. */
53
139
  postProcess;
54
140
  /**
55
- * @param response - Initial response text; defaults to empty string.
56
- * @param postProcess - Whether to enable post-processing of actions.
141
+ * @param response - Initial response: a string of context for the model
142
+ * (facts or an instruction), or the structured `{ tool_result, tool_prompt }`
143
+ * form. Defaults to an empty string.
144
+ * @param postProcess - Whether the model takes one more turn before the
145
+ * actions execute (set it when the caller must hear something first).
146
+ * @param toolResult - Sets the structured response's `tool_result` (see
147
+ * {@link setToolResponse}).
148
+ * @param toolPrompt - Sets the structured response's `tool_prompt`.
57
149
  */
58
- constructor(response, postProcess = false) {
59
- this.response = response ?? '';
150
+ constructor(response, postProcess = false, toolResult, toolPrompt) {
60
151
  this.action = [];
61
152
  this.postProcess = postProcess;
153
+ if (typeof response === 'object' && response !== null) {
154
+ this.response = '';
155
+ this._toolResponse = { ...response };
156
+ }
157
+ else {
158
+ this.response = response ?? '';
159
+ }
160
+ if (toolResult !== undefined || toolPrompt !== undefined) {
161
+ this.setToolResponse(toolResult, toolPrompt);
162
+ }
62
163
  }
63
164
  // ── Core ────────────────────────────────────────────────────────────
64
165
  /**
65
- * Set the response text returned to the AI agent.
66
- * @param response - The response text.
166
+ * Set the response string returned to the model as context. Clears any
167
+ * structured response set by {@link setToolResponse}.
168
+ * @param response - The response text: facts or an instruction.
67
169
  * @returns This instance for chaining.
68
170
  */
69
171
  setResponse(response) {
70
172
  this.response = response;
173
+ this._toolResponse = null;
174
+ return this;
175
+ }
176
+ /**
177
+ * Set the structured response, separating facts from instruction:
178
+ * `{ tool_result, tool_prompt }`. Replaces any string response.
179
+ *
180
+ * - `toolResult`: what the tool did or found. Facts for the model to reason
181
+ * from ("hold initiated", "payment declined", "3 seats left").
182
+ * - `toolPrompt`: what the model should do next. An instruction, such as
183
+ * "Tell the caller how many seats are left."
184
+ *
185
+ * Splitting them keeps the model from reading a status line aloud, and keeps
186
+ * the instruction from being mistaken for data.
187
+ *
188
+ * @param toolResult - Facts from the call; omit if there is nothing to
189
+ * report beyond the instruction.
190
+ * @param toolPrompt - Instruction for what to do next; omit for a
191
+ * facts-only result.
192
+ * @returns This instance for chaining.
193
+ */
194
+ setToolResponse(toolResult, toolPrompt) {
195
+ const payload = {};
196
+ if (toolResult !== undefined)
197
+ payload.tool_result = toolResult;
198
+ if (toolPrompt !== undefined)
199
+ payload.tool_prompt = toolPrompt;
200
+ this._toolResponse = payload;
201
+ this.response = '';
71
202
  return this;
72
203
  }
73
204
  /**
74
- * Enable or disable post-processing of actions.
205
+ * Enable or disable post-processing. When enabled, the model takes one more
206
+ * turn before the actions execute, so it can tell the caller something first.
75
207
  * @param postProcess - Whether to post-process actions.
76
208
  * @returns This instance for chaining.
77
209
  */
@@ -100,9 +232,11 @@ export class FunctionResult {
100
232
  }
101
233
  // ── Call control ────────────────────────────────────────────────────
102
234
  /**
103
- * Connect the call to another destination via SWML transfer.
235
+ * Connect the call to another destination with an inline SWML `connect`
236
+ * document, emitted with `transfer: "true"` or `"false"` beside it.
104
237
  * @param destination - The destination address (phone number or SIP URI).
105
- * @param final - Whether this is a final transfer that ends the AI session.
238
+ * @param final - `true` (default) for a permanent transfer that leaves the
239
+ * agent; `false` returns the call to the agent when the far end hangs up.
106
240
  * @param fromAddr - Optional caller ID to use for the outbound leg.
107
241
  * @returns This instance for chaining.
108
242
  */
@@ -121,10 +255,12 @@ export class FunctionResult {
121
255
  return this;
122
256
  }
123
257
  /**
124
- * Transfer the call to a SWML destination with a custom AI response.
125
- * @param dest - The transfer destination.
126
- * @param aiResponse - The AI response text to set before transferring.
127
- * @param final - Whether this is a final transfer.
258
+ * Transfer the call with an inline SWML document that sets `ai_response` and
259
+ * then runs the `transfer` verb, emitted with `transfer` beside it.
260
+ * @param dest - The transfer destination (a SWML URL, SIP address or similar).
261
+ * @param aiResponse - Stored as `ai_response`, for the agent to use when a
262
+ * non-final transfer returns the call.
263
+ * @param final - `true` (default) for a permanent transfer; `false` to return.
128
264
  * @returns This instance for chaining.
129
265
  */
130
266
  swmlTransfer(dest, aiResponse, final = true) {
@@ -132,10 +268,7 @@ export class FunctionResult {
132
268
  SWML: {
133
269
  version: '1.0.0',
134
270
  sections: {
135
- main: [
136
- { set: { ai_response: aiResponse } },
137
- { transfer: { dest } },
138
- ],
271
+ main: [{ set: { ai_response: aiResponse } }, { transfer: { dest } }],
139
272
  },
140
273
  },
141
274
  transfer: String(final),
@@ -143,23 +276,72 @@ export class FunctionResult {
143
276
  return this;
144
277
  }
145
278
  /**
146
- * Hang up the call.
279
+ * Hang up the call. Emits `{ hangup: true }`.
147
280
  * @returns This instance for chaining.
148
281
  */
149
282
  hangup() {
150
283
  return this.addAction('hangup', true);
151
284
  }
152
285
  /**
153
- * Place the call on hold for a specified duration.
154
- * @param timeout - Hold duration in seconds, clamped to 0-900.
286
+ * Put the call on hold, optionally announcing it and routing what happens next.
287
+ *
288
+ * The hold action carries no prompt of its own, and during a hold speech
289
+ * detection is paused and the agent doesn't respond, so anything the caller
290
+ * needs to hear has to be said before the hold takes effect. Passing `prompt`
291
+ * does that: it becomes the structured response's `tool_prompt` (with
292
+ * `tool_result: "status: on hold"`) and turns on `postProcess`, so the model
293
+ * takes one more turn, and can tell the caller, before the hold runs.
294
+ *
295
+ * `step` and `timeoutStep` move the call to a step when the hold ends:
296
+ * `step` when it's taken off hold, `timeoutStep` when the hold times out.
297
+ * They fire when the hold ends, unlike {@link swmlChangeStep}, which applies
298
+ * at once and would move the caller before the hold begins. Omit one, and a
299
+ * hold that ends that way resumes in the current step. Omitting both emits
300
+ * the bare timeout (`{ hold: 300 }`); either one emits
301
+ * `{ hold: { timeout, step?, timeout_step? } }`.
302
+ *
303
+ * @example
304
+ * ```ts
305
+ * new FunctionResult().hold('Tell the caller you are checking if they are available.', 300,
306
+ * 'back_with_agent', 'take_a_message');
307
+ * ```
308
+ *
309
+ * @param prompt - Instruction for the model to act on before the hold. A
310
+ * number here is taken as `timeout`, so `hold(120)` keeps working.
311
+ * @param timeout - Hold duration in seconds, clamped to 0-900 (default 300).
312
+ * @param step - Step to move to when the call is taken off hold.
313
+ * @param timeoutStep - Step to move to when the hold times out.
155
314
  * @returns This instance for chaining.
156
315
  */
157
- hold(timeout = 300) {
158
- return this.addAction('hold', Math.max(0, Math.min(timeout, 900)));
316
+ hold(prompt, timeout = 300, step, timeoutStep) {
317
+ let text;
318
+ if (typeof prompt === 'number') {
319
+ timeout = prompt;
320
+ }
321
+ else {
322
+ text = prompt;
323
+ }
324
+ if (text !== undefined) {
325
+ this.setToolResponse('status: on hold', text);
326
+ this.postProcess = true;
327
+ }
328
+ const clamped = Math.max(0, Math.min(timeout, 900));
329
+ if (step === undefined && timeoutStep === undefined) {
330
+ return this.addAction('hold', clamped);
331
+ }
332
+ const config = { timeout: clamped };
333
+ if (step !== undefined)
334
+ config['step'] = step;
335
+ if (timeoutStep !== undefined)
336
+ config['timeout_step'] = timeoutStep;
337
+ return this.addAction('hold', config);
159
338
  }
160
339
  /**
161
- * Wait for user input before continuing.
162
- * @param opts - Options controlling wait behavior: enable/disable, timeout, or answer-first mode.
340
+ * Emit a `wait_for_user` action. The first option set wins, in this order:
341
+ * `answerFirst` (emits `"answer_first"`), `timeout`, `enabled`; with none,
342
+ * it emits `true`.
343
+ * @param opts - Options controlling wait behavior: enable/disable, timeout in
344
+ * seconds, or answer-first mode.
163
345
  * @returns This instance for chaining.
164
346
  */
165
347
  waitForUser(opts) {
@@ -176,7 +358,7 @@ export class FunctionResult {
176
358
  return this.addAction('wait_for_user', value);
177
359
  }
178
360
  /**
179
- * Stop the AI session.
361
+ * Stop the AI conversation. Emits `{ stop: true }`.
180
362
  * @returns This instance for chaining.
181
363
  */
182
364
  stop() {
@@ -184,7 +366,8 @@ export class FunctionResult {
184
366
  }
185
367
  // ── Audio ───────────────────────────────────────────────────────────
186
368
  /**
187
- * Speak text to the caller via TTS.
369
+ * Speak text to the caller via TTS. Unlike the response, this text is
370
+ * spoken to the caller.
188
371
  * @param text - The text to speak.
189
372
  * @returns This instance for chaining.
190
373
  */
@@ -194,7 +377,8 @@ export class FunctionResult {
194
377
  /**
195
378
  * Play an audio file in the background during the call.
196
379
  * @param filename - URL or path of the audio file.
197
- * @param wait - Whether to wait for playback to complete before continuing.
380
+ * @param wait - Whether to wait for playback to finish before continuing.
381
+ * `true` emits `{ file, wait: true }`; `false` emits the file name alone.
198
382
  * @returns This instance for chaining.
199
383
  */
200
384
  playBackgroundFile(filename, wait = false) {
@@ -210,6 +394,28 @@ export class FunctionResult {
210
394
  stopBackgroundFile() {
211
395
  return this.addAction('stop_playback_bg', true);
212
396
  }
397
+ /**
398
+ * Change the agent's voice for the rest of the call.
399
+ *
400
+ * The voice is an `engine.voice:model` spec — the same form a language's voice
401
+ * takes in the SWML `languages` list (e.g. `"elevenlabs.rachel"`); the
402
+ * `engine.` prefix and the `:model` suffix are optional. It replaces the voice
403
+ * of the language currently in use, and switching to a voice on a different
404
+ * TTS engine is allowed. The platform applies it at the next speech batch
405
+ * boundary (never mid-utterance), and it then persists for that language for
406
+ * the rest of the call. If the new voice cannot be opened, the platform falls
407
+ * back to its fallback voice. The platform ignores an empty spec, so the SDK
408
+ * refuses one.
409
+ * @param voice - Voice spec in `engine.voice:model` form.
410
+ * @returns This instance for chaining.
411
+ * @throws {Error} When `voice` is empty or only whitespace.
412
+ */
413
+ changeVoice(voice) {
414
+ if (typeof voice !== 'string' || !voice.trim()) {
415
+ throw new Error('voice must be a non-empty string');
416
+ }
417
+ return this.addAction('change_voice', voice);
418
+ }
213
419
  // ── Speech ──────────────────────────────────────────────────────────
214
420
  /**
215
421
  * Add dynamic speech recognition hints to improve transcription accuracy.
@@ -228,7 +434,7 @@ export class FunctionResult {
228
434
  return this;
229
435
  }
230
436
  /**
231
- * Set the silence duration that marks the end of a user's speech.
437
+ * Set the silence after detected speech that finalizes speech recognition.
232
438
  * @param milliseconds - Timeout in milliseconds.
233
439
  * @returns This instance for chaining.
234
440
  */
@@ -236,7 +442,8 @@ export class FunctionResult {
236
442
  return this.addAction('end_of_speech_timeout', milliseconds);
237
443
  }
238
444
  /**
239
- * Set the timeout for speech event detection.
445
+ * Set the time since the last speech detection event after which speech
446
+ * recognition is finalized. Suits noisy environments.
240
447
  * @param milliseconds - Timeout in milliseconds.
241
448
  * @returns This instance for chaining.
242
449
  */
@@ -245,13 +452,31 @@ export class FunctionResult {
245
452
  }
246
453
  // ── Data ────────────────────────────────────────────────────────────
247
454
  /**
248
- * Merge key-value pairs into the global data store shared across functions.
455
+ * Merge key-value pairs into the call's global data (`set_global_data`),
456
+ * which persists for the AI session and is readable by every function.
249
457
  * @param data - Key-value pairs to set or update.
250
458
  * @returns This instance for chaining.
251
459
  */
252
460
  updateGlobalData(data) {
253
461
  return this.addAction('set_global_data', data);
254
462
  }
463
+ /**
464
+ * Set the semantic state the call's semantic gates judge, besides the
465
+ * dialogue.
466
+ *
467
+ * The state is `global_data.semantic_state`, and this replaces it as a whole:
468
+ * to change one field, send the whole state with that field changed, and
469
+ * send `{}` to reset it. Keep it to what the application has established,
470
+ * such as an order the caller confirmed, rather than what the caller claims.
471
+ * It's the only global data copied into the decision model's state; a gate
472
+ * question can still bring in other global data with a `${global_data.x}`
473
+ * template.
474
+ * @param state - The semantic state.
475
+ * @returns This instance for chaining.
476
+ */
477
+ setSemanticState(state) {
478
+ return this.updateGlobalData({ semantic_state: state });
479
+ }
255
480
  /**
256
481
  * Remove keys from the global data store.
257
482
  * @param keys - A single key or array of keys to remove.
@@ -261,7 +486,8 @@ export class FunctionResult {
261
486
  return this.addAction('unset_global_data', keys);
262
487
  }
263
488
  /**
264
- * Set metadata key-value pairs on the current call.
489
+ * Set metadata (`set_meta_data`) scoped to the current function's
490
+ * `meta_data_token`. Functions sharing a token share the metadata.
265
491
  * @param data - Metadata key-value pairs to set.
266
492
  * @returns This instance for chaining.
267
493
  */
@@ -269,7 +495,8 @@ export class FunctionResult {
269
495
  return this.addAction('set_meta_data', data);
270
496
  }
271
497
  /**
272
- * Remove metadata keys from the current call.
498
+ * Remove metadata keys (`unset_meta_data`) from the current function's
499
+ * `meta_data_token` scope.
273
500
  * @param keys - A single key or array of keys to remove.
274
501
  * @returns This instance for chaining.
275
502
  */
@@ -279,9 +506,18 @@ export class FunctionResult {
279
506
  // ── SWML helpers ────────────────────────────────────────────────────
280
507
  /**
281
508
  * Execute arbitrary SWML content as an action.
282
- * @param swmlContent - SWML as a JSON string or object.
283
- * @param transfer - Whether this SWML execution should transfer the call.
509
+ *
510
+ * A JSON string is parsed; a string that isn't JSON is sent as
511
+ * `{ raw_swml: <string> }`. An object with a `toDict()` method is converted
512
+ * through it, and a plain object is copied. Any other value throws.
513
+ *
514
+ * @param swmlContent - SWML as a JSON string, a plain object, or an object
515
+ * with `toDict()`.
516
+ * @param transfer - When `true`, emits `transfer: "true"` beside the `SWML`
517
+ * key, so the call leaves the agent for the SWML.
284
518
  * @returns This instance for chaining.
519
+ * @throws {Error} When `swmlContent` is not a string, a plain object, or an
520
+ * object with `toDict()` (for example a number, an array or `null`).
285
521
  */
286
522
  executeSwml(swmlContent, transfer = false) {
287
523
  let swmlData;
@@ -293,19 +529,38 @@ export class FunctionResult {
293
529
  swmlData = { raw_swml: swmlContent };
294
530
  }
295
531
  }
296
- else if (typeof swmlContent.toDict === 'function') {
532
+ else if (typeof swmlContent === 'object' &&
533
+ swmlContent !== null &&
534
+ typeof swmlContent.toDict === 'function') {
535
+ // SWML SDK object - convert via toDict(). The object/null check guards the
536
+ // property access (Python's hasattr is null-safe; TS member access is not).
297
537
  swmlData = swmlContent.toDict();
298
538
  }
299
- else {
539
+ else if (typeof swmlContent === 'object' &&
540
+ swmlContent !== null &&
541
+ !Array.isArray(swmlContent)) {
542
+ // Plain object (dict) - copy to avoid mutating the caller's data.
300
543
  swmlData = { ...swmlContent };
301
544
  }
302
- if (transfer) {
303
- swmlData['transfer'] = 'true';
545
+ else {
546
+ // Mirror Python's execute_swml: a non-string / non-toDict / non-dict value
547
+ // (number, array, null, ...) is a programming error. This is the shared sink
548
+ // for every SWML helper, so a bad value must fail loudly rather than spread.
549
+ throw new Error('swml_content must be string, dict, or SWML object');
304
550
  }
305
- return this.addAction('SWML', swmlData);
551
+ // transfer rides BESIDE the SWML document, not inside it: the same shape
552
+ // connect() and swmlTransfer() emit. Inside the document it isn't a SWML
553
+ // key, and the call never leaves the agent.
554
+ const action = { SWML: swmlData };
555
+ if (transfer)
556
+ action['transfer'] = 'true';
557
+ this.action.push(action);
558
+ return this;
306
559
  }
307
560
  /**
308
- * Change the current SWML step.
561
+ * Move the conversation to a step in the current context (`change_step`).
562
+ * The change applies at once, and the step must exist in the current
563
+ * context of the agent's contexts (see `defineContexts()`).
309
564
  * @param stepName - The name of the step to switch to.
310
565
  * @returns This instance for chaining.
311
566
  */
@@ -313,7 +568,8 @@ export class FunctionResult {
313
568
  return this.addAction('change_step', stepName);
314
569
  }
315
570
  /**
316
- * Change the current SWML context.
571
+ * Move the conversation to another context (`change_context`). The context
572
+ * must exist in the agent's contexts (see `defineContexts()`).
317
573
  * @param contextName - The name of the context to switch to.
318
574
  * @returns This instance for chaining.
319
575
  */
@@ -321,7 +577,8 @@ export class FunctionResult {
321
577
  return this.addAction('change_context', contextName);
322
578
  }
323
579
  /**
324
- * Emit a custom user event via SWML.
580
+ * Send an event to the client connected to the call, through an inline SWML
581
+ * `user_event` verb. The client receives it as a `user_event` event.
325
582
  * @param eventData - The event payload.
326
583
  * @returns This instance for chaining.
327
584
  */
@@ -332,8 +589,12 @@ export class FunctionResult {
332
589
  });
333
590
  }
334
591
  /**
335
- * Switch the AI context with optional new prompts and reset options.
336
- * @param opts - Context switch options including system/user prompts and reset flags.
592
+ * Replace the agent's prompt mid-call (`context_switch`). With only
593
+ * `systemPrompt`, emits the prompt string; otherwise emits an object with the
594
+ * fields that are set.
595
+ * @param opts - The new system prompt, a user prompt to add, whether to
596
+ * summarize the conversation so far (`consolidate`), and whether to reset the
597
+ * context completely (`fullReset`).
337
598
  * @returns This instance for chaining.
338
599
  */
339
600
  switchContext(opts) {
@@ -365,7 +626,8 @@ export class FunctionResult {
365
626
  return this.addAction('toggle_functions', toggles);
366
627
  }
367
628
  /**
368
- * Control whether functions fire on speaker timeout.
629
+ * Control whether functions can be called on speaker timeout
630
+ * (`functions_on_speaker_timeout`).
369
631
  * @param enabled - Whether to enable function execution on timeout.
370
632
  * @returns This instance for chaining.
371
633
  */
@@ -373,7 +635,8 @@ export class FunctionResult {
373
635
  return this.addAction('functions_on_speaker_timeout', enabled);
374
636
  }
375
637
  /**
376
- * Update AI engine settings at runtime.
638
+ * Update AI settings at runtime (`settings`). The platform validates the
639
+ * keys, such as `temperature`, `top-p` and `barge-confidence`.
377
640
  * @param settings - Key-value pairs of settings to update.
378
641
  * @returns This instance for chaining.
379
642
  */
@@ -382,7 +645,7 @@ export class FunctionResult {
382
645
  }
383
646
  // ── User input / history ────────────────────────────────────────────
384
647
  /**
385
- * Inject text as if the user had spoken it.
648
+ * Queue text as if the user had said it (`user_input`).
386
649
  * @param text - The simulated user input text.
387
650
  * @returns This instance for chaining.
388
651
  */
@@ -390,16 +653,19 @@ export class FunctionResult {
390
653
  return this.addAction('user_input', text);
391
654
  }
392
655
  /**
393
- * Enable or disable extensive data reporting in function calls.
394
- * @param enabled - Whether to enable extensive data.
656
+ * Send the full data to the model for this turn only, then a smaller
657
+ * replacement in later turns (`extensive_data`).
658
+ * @param enabled - Whether to send extensive data this turn.
395
659
  * @returns This instance for chaining.
396
660
  */
397
661
  enableExtensiveData(enabled = true) {
398
662
  return this.addAction('extensive_data', enabled);
399
663
  }
400
664
  /**
401
- * Replace the function call output in conversation history.
402
- * @param text - Replacement text, or true to replace with the response.
665
+ * After the first send, replace this tool call and its result in the
666
+ * conversation history (`replace_in_history`).
667
+ * @param text - A string replaces the pair with an assistant message holding
668
+ * that text; `true` (default) removes the pair from the history.
403
669
  * @returns This instance for chaining.
404
670
  */
405
671
  replaceInHistory(text = true) {
@@ -409,8 +675,8 @@ export class FunctionResult {
409
675
  /**
410
676
  * Send an SMS or MMS message from within the call flow.
411
677
  *
412
- * @param opts - SMS parameters. Must include either `body` (text SMS) or
413
- * `media` (MMS) — supplying neither throws.
678
+ * @param opts - SMS parameters. Must include `body` (text SMS), `media`
679
+ * (MMS), or both; supplying neither throws.
414
680
  * @returns This instance for chaining.
415
681
  * @throws {Error} When neither `body` nor `media` is provided.
416
682
  */
@@ -436,7 +702,7 @@ export class FunctionResult {
436
702
  });
437
703
  }
438
704
  /**
439
- * Start recording the call.
705
+ * Start a background recording of the call (SWML `record_call`).
440
706
  * @param opts - Recording options including format, direction, and timeouts.
441
707
  * @returns This instance for chaining.
442
708
  */
@@ -482,16 +748,33 @@ export class FunctionResult {
482
748
  });
483
749
  }
484
750
  /**
485
- * Start a media tap to stream audio to an external URI.
751
+ * Start a media tap to stream audio to an external URI (`ws://`, `wss://` or
752
+ * `rtp://IP:port`). `direction` is always sent; `codec` and `rtpPtime` are
753
+ * sent only when they differ from `PCMU` and 20.
486
754
  * @param opts - Tap parameters including URI, direction, and codec.
755
+ * @throws {Error} On a `direction` or `codec` outside the allowed values, or
756
+ * an `rtpPtime` that isn't positive.
487
757
  * @returns This instance for chaining.
488
758
  */
489
759
  tap(opts) {
760
+ // Runtime guards matching the Python reference: a JS caller can pass any
761
+ // string, and the types can't express rtp_ptime > 0.
762
+ const direction = opts.direction ?? 'both';
763
+ if (!['speak', 'listen', 'both'].includes(direction)) {
764
+ throw new Error("direction must be one of ['speak', 'listen', 'both']");
765
+ }
766
+ if (opts.codec !== undefined && !['PCMU', 'PCMA'].includes(opts.codec)) {
767
+ throw new Error("codec must be one of ['PCMU', 'PCMA']");
768
+ }
769
+ if (opts.rtpPtime !== undefined && opts.rtpPtime <= 0) {
770
+ throw new Error('rtp_ptime must be a positive integer');
771
+ }
490
772
  const params = { uri: opts.uri };
491
773
  if (opts.controlId)
492
774
  params['control_id'] = opts.controlId;
493
- if (opts.direction && opts.direction !== 'both')
494
- params['direction'] = opts.direction;
775
+ // Always sent: the verb's own default is "speak", not this helper's
776
+ // "both", so leaving it out would tap less than the caller asked for.
777
+ params['direction'] = direction;
495
778
  if (opts.codec && opts.codec !== 'PCMU')
496
779
  params['codec'] = opts.codec;
497
780
  if (opts.rtpPtime && opts.rtpPtime !== 20)
@@ -519,7 +802,7 @@ export class FunctionResult {
519
802
  }
520
803
  // ── Rooms / Conferences ─────────────────────────────────────────────
521
804
  /**
522
- * Join a SignalWire room.
805
+ * Join a RELAY room by name (SWML `join_room`).
523
806
  * @param name - The room name to join.
524
807
  * @returns This instance for chaining.
525
808
  */
@@ -541,23 +824,49 @@ export class FunctionResult {
541
824
  });
542
825
  }
543
826
  /**
544
- * Join a conference by name with optional configuration.
827
+ * Join a conference by name with optional configuration. Options at their
828
+ * default value are left out; with none left, `join_conference` is the name
829
+ * string alone.
830
+ *
831
+ * `maxParticipants` is sent whenever it is given, as an integer of 2 or
832
+ * more: the platform refuses a conference of fewer than 2 and sets no upper
833
+ * limit (the SWML schema's cap of 100000 isn't enforced). A numeric string
834
+ * is converted, and a SWML variable reference such as `'${room_size}'` is
835
+ * passed through.
545
836
  * @param name - The conference name to join.
546
837
  * @param opts - Optional conference settings such as mute, recording, and callbacks.
838
+ * @throws {Error} When `name` is blank, or `maxParticipants` isn't an
839
+ * integer of at least 2 or a SWML variable reference.
547
840
  * @returns This instance for chaining.
548
841
  */
549
842
  joinConference(name, opts) {
550
- const hasNonDefaults = opts && (opts.muted || (opts.beep && opts.beep !== 'true') ||
551
- opts.startOnEnter === false || opts.endOnExit ||
552
- opts.waitUrl || (opts.maxParticipants && opts.maxParticipants !== 250) ||
553
- (opts.record && opts.record !== 'do-not-record') || opts.region ||
554
- (opts.trim && opts.trim !== 'trim-silence') || opts.coach ||
555
- opts.statusCallbackEvent || opts.statusCallback ||
556
- (opts.statusCallbackMethod && opts.statusCallbackMethod !== 'POST') ||
557
- opts.recordingStatusCallback ||
558
- (opts.recordingStatusCallbackMethod && opts.recordingStatusCallbackMethod !== 'POST') ||
559
- (opts.recordingStatusCallbackEvent && opts.recordingStatusCallbackEvent !== 'completed') ||
560
- opts.result !== undefined);
843
+ // Runtime guards matching the Python reference (beep/record/trim/method are
844
+ // covered at compile time by the literal-union types in the signature; these two cannot be).
845
+ if (!name.trim()) {
846
+ throw new Error('name cannot be empty');
847
+ }
848
+ // The platform refuses fewer than 2 members and has no upper limit.
849
+ const maxParticipants = opts?.maxParticipants !== undefined && opts.maxParticipants !== null
850
+ ? swmlInt('max_participants', opts.maxParticipants, 2)
851
+ : undefined;
852
+ const hasNonDefaults = opts &&
853
+ (opts.muted ||
854
+ (opts.beep && opts.beep !== 'true') ||
855
+ opts.startOnEnter === false ||
856
+ opts.endOnExit ||
857
+ opts.waitUrl ||
858
+ maxParticipants !== undefined ||
859
+ (opts.record && opts.record !== 'do-not-record') ||
860
+ opts.region ||
861
+ (opts.trim && opts.trim !== 'trim-silence') ||
862
+ opts.coach ||
863
+ opts.statusCallbackEvent ||
864
+ opts.statusCallback ||
865
+ (opts.statusCallbackMethod && opts.statusCallbackMethod !== 'POST') ||
866
+ opts.recordingStatusCallback ||
867
+ (opts.recordingStatusCallbackMethod && opts.recordingStatusCallbackMethod !== 'POST') ||
868
+ (opts.recordingStatusCallbackEvent && opts.recordingStatusCallbackEvent !== 'completed') ||
869
+ opts.result !== undefined);
561
870
  let joinParams;
562
871
  if (!hasNonDefaults) {
563
872
  joinParams = name;
@@ -574,8 +883,8 @@ export class FunctionResult {
574
883
  p['end_on_exit'] = opts.endOnExit;
575
884
  if (opts.waitUrl)
576
885
  p['wait_url'] = opts.waitUrl;
577
- if (opts.maxParticipants && opts.maxParticipants !== 250)
578
- p['max_participants'] = opts.maxParticipants;
886
+ if (maxParticipants !== undefined)
887
+ p['max_participants'] = maxParticipants;
579
888
  if (opts.record && opts.record !== 'do-not-record')
580
889
  p['record'] = opts.record;
581
890
  if (opts.region)
@@ -617,7 +926,11 @@ export class FunctionResult {
617
926
  rpcParams['call_id'] = opts.callId;
618
927
  if (opts.nodeId)
619
928
  rpcParams['node_id'] = opts.nodeId;
620
- if (opts.params)
929
+ // Match Python's `if params:`: a falsy/EMPTY params dict is dropped, so an
930
+ // empty `{}` (e.g. from rpcAiUnhold) emits no `params` key at all. A plain
931
+ // `if (opts.params)` would wrongly keep `{}` because every object is truthy
932
+ // in JS; gate on key count to mirror the reference (function_result.py:1324).
933
+ if (opts.params && Object.keys(opts.params).length > 0)
621
934
  rpcParams['params'] = opts.params;
622
935
  return this.executeSwml({
623
936
  version: '1.0.0',
@@ -625,10 +938,10 @@ export class FunctionResult {
625
938
  });
626
939
  }
627
940
  /**
628
- * Dial a number via RPC, optionally specifying device type.
941
+ * Dial out with the `dial` RPC method, optionally specifying device type.
629
942
  * @param toNumber - The destination phone number.
630
943
  * @param fromNumber - The caller ID number.
631
- * @param destSwml - The SWML destination for the dialed call.
944
+ * @param destSwml - URL of the SWML that handles the dialed call.
632
945
  * @param deviceType - The device type (defaults to "phone").
633
946
  * @returns This instance for chaining.
634
947
  */
@@ -645,21 +958,47 @@ export class FunctionResult {
645
958
  });
646
959
  }
647
960
  /**
648
- * Send an AI message to another call via RPC.
961
+ * Send a message and/or global data to an AI agent on another call.
962
+ *
963
+ * Two payloads, either or both: `messageText` lands as a turn in the other
964
+ * agent's conversation, where it competes with everything else arriving at
965
+ * that moment; `globalData` is merged into the other call's global data,
966
+ * where it stays silent until a prompt expands it with
967
+ * `${global_data.your_key}`. That makes data the better channel for content a
968
+ * later step needs to say.
969
+ *
649
970
  * @param callId - The target call ID.
650
- * @param messageText - The message text to inject.
651
- * @param role - The message role (defaults to "system").
971
+ * @param messageText - Message to inject into the other conversation.
972
+ * @param role - The message role (defaults to "system"); sent with the message.
973
+ * @param globalData - Object merged into the target call's global data.
652
974
  * @returns This instance for chaining.
975
+ * @throws Error when neither `messageText` nor `globalData` is given.
653
976
  */
654
- rpcAiMessage(callId, messageText, role = 'system') {
655
- return this.executeRpc({
656
- method: 'ai_message',
657
- callId,
658
- params: { role, message_text: messageText },
659
- });
977
+ rpcAiMessage(callId, messageText, role = 'system', globalData) {
978
+ const params = {};
979
+ if (messageText !== undefined && messageText !== null) {
980
+ params['role'] = role;
981
+ params['message_text'] = messageText;
982
+ }
983
+ if (globalData !== undefined)
984
+ params['global_data'] = globalData;
985
+ if (Object.keys(params).length === 0) {
986
+ throw new Error('rpc_ai_message needs message_text, global_data, or both');
987
+ }
988
+ return this.executeRpc({ method: 'ai_message', callId, params });
660
989
  }
661
990
  /**
662
- * Unhold a call that was previously placed on hold via RPC.
991
+ * Merge data into another call's global data, with no conversation turn.
992
+ * The other call's prompt reads it back with `${global_data.key}`.
993
+ * @param callId - The target call ID.
994
+ * @param data - Object merged into that call's global data.
995
+ * @returns This instance for chaining.
996
+ */
997
+ rpcAiGlobalData(callId, data) {
998
+ return this.rpcAiMessage(callId, undefined, 'system', data);
999
+ }
1000
+ /**
1001
+ * Take another call off hold with the `ai_unhold` RPC method.
663
1002
  * @param callId - The target call ID to unhold.
664
1003
  * @returns This instance for chaining.
665
1004
  */
@@ -672,8 +1011,22 @@ export class FunctionResult {
672
1011
  }
673
1012
  // ── Payment ─────────────────────────────────────────────────────────
674
1013
  /**
675
- * Initiate a payment collection flow on the call.
1014
+ * Start a payment collection flow on the call. Emits an inline SWML document
1015
+ * that sets `ai_response` and then runs the `pay` verb.
1016
+ *
1017
+ * `timeout`, `max_attempts`, `min_postal_code_length`, `security_code` and
1018
+ * `postal_code` are sent as strings, as the platform reads them: its SWML
1019
+ * validator requires strings for `security_code` and `postal_code`, and the
1020
+ * pay request reads all five as strings. Each input is checked first:
1021
+ * `timeout`, `maxAttempts` and `minPostalCodeLength` must be integers (or
1022
+ * numeric strings), and `securityCode` a boolean (or `"true"`/`"false"`).
1023
+ * A SWML variable reference such as `'${timeout}'` is passed through.
1024
+ * `postalCode` is a boolean (whether to ask for it) or the postal code
1025
+ * itself, as a string.
676
1026
  * @param opts - Payment configuration including connector URL, method, and prompt options.
1027
+ * @throws {Error} When `timeout`, `maxAttempts` or `minPostalCodeLength`
1028
+ * isn't an integer, or `securityCode` isn't a boolean, or a SWML variable
1029
+ * reference.
677
1030
  * @returns This instance for chaining.
678
1031
  */
679
1032
  pay(opts) {
@@ -681,18 +1034,22 @@ export class FunctionResult {
681
1034
  payment_connector_url: opts.paymentConnectorUrl,
682
1035
  input: opts.inputMethod ?? 'dtmf',
683
1036
  payment_method: opts.paymentMethod ?? 'credit-card',
684
- timeout: String(opts.timeout ?? 5),
685
- max_attempts: String(opts.maxAttempts ?? 1),
686
- security_code: String(opts.securityCode ?? true),
687
- min_postal_code_length: String(opts.minPostalCodeLength ?? 0),
1037
+ // Checked as integers and a boolean, sent as strings: the platform's
1038
+ // validator requires strings for security_code and postal_code, and its
1039
+ // pay request reads all five as strings (mod_infrastructure
1040
+ // swml_schema.c, relay.c generate_pay_request).
1041
+ timeout: String(swmlInt('timeout', opts.timeout ?? 5)),
1042
+ max_attempts: String(swmlInt('max_attempts', opts.maxAttempts ?? 1)),
1043
+ security_code: String(swmlBool('security_code', opts.securityCode ?? true)),
1044
+ min_postal_code_length: String(swmlInt('min_postal_code_length', opts.minPostalCodeLength ?? 0)),
688
1045
  token_type: opts.tokenType ?? 'reusable',
689
1046
  currency: opts.currency ?? 'usd',
690
1047
  language: opts.language ?? 'en-US',
691
1048
  voice: opts.voice ?? 'woman',
692
1049
  valid_card_types: opts.validCardTypes ?? 'visa mastercard amex',
693
1050
  };
694
- const postalCode = opts.postalCode ?? true;
695
- payParams['postal_code'] = typeof postalCode === 'boolean' ? String(postalCode) : postalCode;
1051
+ // A boolean (whether to ask for it) or the postal code itself, as a string
1052
+ payParams['postal_code'] = String(opts.postalCode ?? true);
696
1053
  if (opts.statusUrl)
697
1054
  payParams['status_url'] = opts.statusUrl;
698
1055
  if (opts.chargeAmount)
@@ -708,10 +1065,7 @@ export class FunctionResult {
708
1065
  return this.executeSwml({
709
1066
  version: '1.0.0',
710
1067
  sections: {
711
- main: [
712
- { set: { ai_response: aiResponse } },
713
- { pay: payParams },
714
- ],
1068
+ main: [{ set: { ai_response: aiResponse } }, { pay: payParams }],
715
1069
  },
716
1070
  });
717
1071
  }
@@ -734,8 +1088,8 @@ export class FunctionResult {
734
1088
  }
735
1089
  /**
736
1090
  * Create a payment action for use within a payment prompt.
737
- * @param actionType - The action type (e.g., "say", "play").
738
- * @param phrase - The phrase or URL for this action.
1091
+ * @param actionType - The action type: "Say" or "Play".
1092
+ * @param phrase - The text to say, or for "Play" the audio file URL.
739
1093
  * @returns A new PaymentAction object.
740
1094
  */
741
1095
  static createPaymentAction(actionType, phrase) {
@@ -757,19 +1111,32 @@ export class FunctionResult {
757
1111
  */
758
1112
  toDict() {
759
1113
  const result = {};
760
- if (this.response) {
761
- result['response'] = this.response;
1114
+ // The structured form counts only when it has a field, as an empty dict
1115
+ // is falsy in the reference.
1116
+ if (this._toolResponse && Object.keys(this._toolResponse).length > 0) {
1117
+ result.response = { ...this._toolResponse };
1118
+ }
1119
+ else if (this.response) {
1120
+ result.response = this.response;
762
1121
  }
763
1122
  if (this.action.length > 0) {
764
- result['action'] = this.action;
1123
+ result.action = this.action;
765
1124
  }
766
1125
  if (this.postProcess && this.action.length > 0) {
767
- result['post_process'] = true;
1126
+ result.post_process = true;
768
1127
  }
769
1128
  if (Object.keys(result).length === 0) {
770
- result['response'] = 'Action completed.';
1129
+ result.response = 'Action completed.';
771
1130
  }
772
1131
  return result;
773
1132
  }
1133
+ /**
1134
+ * TS-native serialization hook. `JSON.stringify(result)` emits the wire
1135
+ * shape (delegates to {@link FunctionResult.toDict}) instead of the
1136
+ * internal field layout. No Python counterpart.
1137
+ */
1138
+ toJSON() {
1139
+ return this.toDict();
1140
+ }
774
1141
  }
775
1142
  //# sourceMappingURL=FunctionResult.js.map