@signalwire/sdk 2.0.5 → 3.5.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 (656) hide show
  1. package/CHANGELOG.md +785 -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 +481 -126
  6. package/dist/AgentBase.js +1502 -438
  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 +158 -45
  21. package/dist/DataMap.js +167 -52
  22. package/dist/DataMap.js.map +1 -1
  23. package/dist/FunctionResult.d.ts +277 -83
  24. package/dist/FunctionResult.js +444 -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 +158 -58
  58. package/dist/SWMLService.js +435 -127
  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/ServerlessAdapter.d.ts +156 -7
  67. package/dist/ServerlessAdapter.js +399 -42
  68. package/dist/ServerlessAdapter.js.map +1 -1
  69. package/dist/SessionManager.d.ts +11 -2
  70. package/dist/SessionManager.js +50 -18
  71. package/dist/SessionManager.js.map +1 -1
  72. package/dist/SslConfig.d.ts +2 -1
  73. package/dist/SslConfig.js +4 -1
  74. package/dist/SslConfig.js.map +1 -1
  75. package/dist/SwaigActions.generated.d.ts +23 -0
  76. package/dist/SwaigActions.generated.js +8 -0
  77. package/dist/SwaigActions.generated.js.map +1 -0
  78. package/dist/SwaigContracts.d.ts +15 -0
  79. package/dist/SwaigContracts.generated.d.ts +264 -0
  80. package/dist/SwaigContracts.generated.js +12 -0
  81. package/dist/SwaigContracts.generated.js.map +1 -0
  82. package/dist/SwaigContracts.js +2 -0
  83. package/dist/SwaigContracts.js.map +1 -0
  84. package/dist/SwaigFunction.d.ts +110 -4
  85. package/dist/SwaigFunction.js +151 -19
  86. package/dist/SwaigFunction.js.map +1 -1
  87. package/dist/SwmlBuilder.d.ts +68 -19
  88. package/dist/SwmlBuilder.js +74 -38
  89. package/dist/SwmlBuilder.js.map +1 -1
  90. package/dist/SwmlVerbMethods.generated.d.ts +41 -4
  91. package/dist/SwmlVerbMethods.generated.js +1 -1
  92. package/dist/TypeInference.d.ts +39 -3
  93. package/dist/TypeInference.js +256 -16
  94. package/dist/TypeInference.js.map +1 -1
  95. package/dist/WebService.d.ts +79 -11
  96. package/dist/WebService.js +320 -109
  97. package/dist/WebService.js.map +1 -1
  98. package/dist/WebhookMiddleware.d.ts +119 -0
  99. package/dist/WebhookMiddleware.js +271 -0
  100. package/dist/WebhookMiddleware.js.map +1 -0
  101. package/dist/WebhookValidator.d.ts +92 -0
  102. package/dist/WebhookValidator.js +409 -0
  103. package/dist/WebhookValidator.js.map +1 -0
  104. package/dist/agents/BedrockAgent.d.ts +162 -0
  105. package/dist/agents/BedrockAgent.js +323 -0
  106. package/dist/agents/BedrockAgent.js.map +1 -0
  107. package/dist/ai-chat/AIChatClient.d.ts +316 -0
  108. package/dist/ai-chat/AIChatClient.js +535 -0
  109. package/dist/ai-chat/AIChatClient.js.map +1 -0
  110. package/dist/ai-chat/ChatGateway.d.ts +408 -0
  111. package/dist/ai-chat/ChatGateway.js +747 -0
  112. package/dist/ai-chat/ChatGateway.js.map +1 -0
  113. package/dist/ai-chat/HandoffRouter.d.ts +282 -0
  114. package/dist/ai-chat/HandoffRouter.js +518 -0
  115. package/dist/ai-chat/HandoffRouter.js.map +1 -0
  116. package/dist/ai-chat/index.d.ts +12 -0
  117. package/dist/ai-chat/index.js +10 -0
  118. package/dist/ai-chat/index.js.map +1 -0
  119. package/dist/capabilities.d.ts +64 -0
  120. package/dist/capabilities.js +95 -0
  121. package/dist/capabilities.js.map +1 -0
  122. package/dist/cli/agent-loader.d.ts +32 -6
  123. package/dist/cli/agent-loader.js +92 -33
  124. package/dist/cli/agent-loader.js.map +1 -1
  125. package/dist/cli/datamap-exec.d.ts +175 -0
  126. package/dist/cli/datamap-exec.js +1284 -0
  127. package/dist/cli/datamap-exec.js.map +1 -0
  128. package/dist/cli/function-args.d.ts +40 -0
  129. package/dist/cli/function-args.js +146 -0
  130. package/dist/cli/function-args.js.map +1 -0
  131. package/dist/cli/simulation.d.ts +99 -0
  132. package/dist/cli/simulation.js +490 -0
  133. package/dist/cli/simulation.js.map +1 -0
  134. package/dist/cli/swaig-test.d.ts +12 -25
  135. package/dist/cli/swaig-test.js +935 -371
  136. package/dist/cli/swaig-test.js.map +1 -1
  137. package/dist/cli/tsdocs/agentsNote.d.ts +30 -0
  138. package/dist/cli/tsdocs/agentsNote.js +92 -0
  139. package/dist/cli/tsdocs/agentsNote.js.map +1 -0
  140. package/dist/cli/tsdocs/api-index.json +1 -0
  141. package/dist/cli/tsdocs/api.d.ts +91 -0
  142. package/dist/cli/tsdocs/api.js +372 -0
  143. package/dist/cli/tsdocs/api.js.map +1 -0
  144. package/dist/cli/tsdocs/apiTypes.d.ts +64 -0
  145. package/dist/cli/tsdocs/apiTypes.js +7 -0
  146. package/dist/cli/tsdocs/apiTypes.js.map +1 -0
  147. package/dist/cli/tsdocs/bin.d.ts +6 -0
  148. package/dist/cli/tsdocs/bin.js +23 -0
  149. package/dist/cli/tsdocs/bin.js.map +1 -0
  150. package/dist/cli/tsdocs/files.d.ts +108 -0
  151. package/dist/cli/tsdocs/files.js +287 -0
  152. package/dist/cli/tsdocs/files.js.map +1 -0
  153. package/dist/cli/tsdocs/index.d.ts +28 -0
  154. package/dist/cli/tsdocs/index.js +307 -0
  155. package/dist/cli/tsdocs/index.js.map +1 -0
  156. package/dist/cli/tsdocs/live.d.ts +41 -0
  157. package/dist/cli/tsdocs/live.js +202 -0
  158. package/dist/cli/tsdocs/live.js.map +1 -0
  159. package/dist/cli/tsdocs/locate.d.ts +51 -0
  160. package/dist/cli/tsdocs/locate.js +75 -0
  161. package/dist/cli/tsdocs/locate.js.map +1 -0
  162. package/dist/cli/tsdocs/render.d.ts +75 -0
  163. package/dist/cli/tsdocs/render.js +323 -0
  164. package/dist/cli/tsdocs/render.js.map +1 -0
  165. package/dist/cli/tsdocs/topics.d.ts +43 -0
  166. package/dist/cli/tsdocs/topics.js +916 -0
  167. package/dist/cli/tsdocs/topics.js.map +1 -0
  168. package/dist/index.d.ts +47 -68
  169. package/dist/index.js +44 -73
  170. package/dist/index.js.map +1 -1
  171. package/dist/livewire/index.d.ts +229 -155
  172. package/dist/livewire/index.js +298 -195
  173. package/dist/livewire/index.js.map +1 -1
  174. package/dist/llms.txt +65 -0
  175. package/dist/prefabs/CallSessionStore.d.ts +52 -0
  176. package/dist/prefabs/CallSessionStore.js +72 -0
  177. package/dist/prefabs/CallSessionStore.js.map +1 -0
  178. package/dist/prefabs/ConciergeAgent.d.ts +13 -1
  179. package/dist/prefabs/ConciergeAgent.js +36 -31
  180. package/dist/prefabs/ConciergeAgent.js.map +1 -1
  181. package/dist/prefabs/FAQBotAgent.d.ts +9 -1
  182. package/dist/prefabs/FAQBotAgent.js +113 -47
  183. package/dist/prefabs/FAQBotAgent.js.map +1 -1
  184. package/dist/prefabs/InfoGathererAgent.d.ts +22 -3
  185. package/dist/prefabs/InfoGathererAgent.js +67 -58
  186. package/dist/prefabs/InfoGathererAgent.js.map +1 -1
  187. package/dist/prefabs/ReceptionistAgent.d.ts +16 -5
  188. package/dist/prefabs/ReceptionistAgent.js +39 -31
  189. package/dist/prefabs/ReceptionistAgent.js.map +1 -1
  190. package/dist/prefabs/SurveyAgent.d.ts +22 -4
  191. package/dist/prefabs/SurveyAgent.js +84 -68
  192. package/dist/prefabs/SurveyAgent.js.map +1 -1
  193. package/dist/relay/Action.d.ts +44 -21
  194. package/dist/relay/Action.js +75 -17
  195. package/dist/relay/Action.js.map +1 -1
  196. package/dist/relay/Call.d.ts +312 -47
  197. package/dist/relay/Call.js +369 -18
  198. package/dist/relay/Call.js.map +1 -1
  199. package/dist/relay/Deferred.js.map +1 -1
  200. package/dist/relay/Message.d.ts +26 -5
  201. package/dist/relay/Message.js +36 -6
  202. package/dist/relay/Message.js.map +1 -1
  203. package/dist/relay/RelayClient.d.ts +44 -17
  204. package/dist/relay/RelayClient.js +175 -65
  205. package/dist/relay/RelayClient.js.map +1 -1
  206. package/dist/relay/RelayError.d.ts +14 -0
  207. package/dist/relay/RelayError.js +15 -0
  208. package/dist/relay/RelayError.js.map +1 -1
  209. package/dist/relay/RelayEvent.d.ts +96 -65
  210. package/dist/relay/RelayEvent.js +85 -56
  211. package/dist/relay/RelayEvent.js.map +1 -1
  212. package/dist/relay/closedSets.d.ts +111 -0
  213. package/dist/relay/closedSets.js +83 -0
  214. package/dist/relay/closedSets.js.map +1 -0
  215. package/dist/relay/index.d.ts +3 -1
  216. package/dist/relay/index.js +1 -0
  217. package/dist/relay/index.js.map +1 -1
  218. package/dist/relay/normalize.js.map +1 -1
  219. package/dist/relay/protocol.types.generated.d.ts +1195 -0
  220. package/dist/relay/protocol.types.generated.js +8 -0
  221. package/dist/relay/protocol.types.generated.js.map +1 -0
  222. package/dist/relay/types.d.ts +73 -42
  223. package/dist/rest/HttpClient.d.ts +36 -8
  224. package/dist/rest/HttpClient.js +233 -40
  225. package/dist/rest/HttpClient.js.map +1 -1
  226. package/dist/rest/RequestOptions.d.ts +110 -0
  227. package/dist/rest/RequestOptions.js +113 -0
  228. package/dist/rest/RequestOptions.js.map +1 -0
  229. package/dist/rest/RestError.d.ts +52 -6
  230. package/dist/rest/RestError.js +89 -5
  231. package/dist/rest/RestError.js.map +1 -1
  232. package/dist/rest/base/CrudResource.d.ts +16 -26
  233. package/dist/rest/base/CrudResource.js +19 -33
  234. package/dist/rest/base/CrudResource.js.map +1 -1
  235. package/dist/rest/base/CrudWithAddresses.d.ts +3 -2
  236. package/dist/rest/base/CrudWithAddresses.js +2 -2
  237. package/dist/rest/base/CrudWithAddresses.js.map +1 -1
  238. package/dist/rest/base/FabricResource.d.ts +15 -0
  239. package/dist/rest/base/FabricResource.js +16 -0
  240. package/dist/rest/base/FabricResource.js.map +1 -0
  241. package/dist/rest/base/ReadResource.d.ts +62 -0
  242. package/dist/rest/base/ReadResource.js +69 -0
  243. package/dist/rest/base/ReadResource.js.map +1 -0
  244. package/dist/rest/callHandler.d.ts +5 -2
  245. package/dist/rest/callHandler.js +4 -1
  246. package/dist/rest/callHandler.js.map +1 -1
  247. package/dist/rest/index.d.ts +18 -77
  248. package/dist/rest/index.js +47 -120
  249. package/dist/rest/index.js.map +1 -1
  250. package/dist/rest/namespaces/_client_tree_generated.d.ts +103 -0
  251. package/dist/rest/namespaces/_client_tree_generated.js +171 -0
  252. package/dist/rest/namespaces/_client_tree_generated.js.map +1 -0
  253. package/dist/rest/namespaces/addresses.d.ts +3 -42
  254. package/dist/rest/namespaces/addresses.js +3 -50
  255. package/dist/rest/namespaces/addresses.js.map +1 -1
  256. package/dist/rest/namespaces/calling.d.ts +6 -378
  257. package/dist/rest/namespaces/calling.js +6 -473
  258. package/dist/rest/namespaces/calling.js.map +1 -1
  259. package/dist/rest/namespaces/calling.resources.generated.d.ts +165 -0
  260. package/dist/rest/namespaces/calling.resources.generated.js +477 -0
  261. package/dist/rest/namespaces/calling.resources.generated.js.map +1 -0
  262. package/dist/rest/namespaces/calling.types.generated.d.ts +2917 -0
  263. package/dist/rest/namespaces/calling.types.generated.js +8 -0
  264. package/dist/rest/namespaces/calling.types.generated.js.map +1 -0
  265. package/dist/rest/namespaces/chat.d.ts +4 -18
  266. package/dist/rest/namespaces/chat.js +4 -21
  267. package/dist/rest/namespaces/chat.js.map +1 -1
  268. package/dist/rest/namespaces/chat.resources.generated.d.ts +12 -0
  269. package/dist/rest/namespaces/chat.resources.generated.js +29 -0
  270. package/dist/rest/namespaces/chat.resources.generated.js.map +1 -0
  271. package/dist/rest/namespaces/chat.types.generated.d.ts +56 -0
  272. package/dist/rest/namespaces/chat.types.generated.js +8 -0
  273. package/dist/rest/namespaces/chat.types.generated.js.map +1 -0
  274. package/dist/rest/namespaces/datasphere.d.ts +6 -62
  275. package/dist/rest/namespaces/datasphere.js +6 -72
  276. package/dist/rest/namespaces/datasphere.js.map +1 -1
  277. package/dist/rest/namespaces/datasphere.resources.generated.d.ts +25 -0
  278. package/dist/rest/namespaces/datasphere.resources.generated.js +50 -0
  279. package/dist/rest/namespaces/datasphere.resources.generated.js.map +1 -0
  280. package/dist/rest/namespaces/datasphere.types.generated.d.ts +180 -0
  281. package/dist/rest/namespaces/datasphere.types.generated.js +8 -0
  282. package/dist/rest/namespaces/datasphere.types.generated.js.map +1 -0
  283. package/dist/rest/namespaces/fabric.d.ts +11 -327
  284. package/dist/rest/namespaces/fabric.js +14 -439
  285. package/dist/rest/namespaces/fabric.js.map +1 -1
  286. package/dist/rest/namespaces/fabric.resources.generated.d.ts +195 -0
  287. package/dist/rest/namespaces/fabric.resources.generated.js +399 -0
  288. package/dist/rest/namespaces/fabric.resources.generated.js.map +1 -0
  289. package/dist/rest/namespaces/fabric.types.generated.d.ts +4557 -0
  290. package/dist/rest/namespaces/fabric.types.generated.js +8 -0
  291. package/dist/rest/namespaces/fabric.types.generated.js.map +1 -0
  292. package/dist/rest/namespaces/fax.resources.generated.d.ts +6 -0
  293. package/dist/rest/namespaces/fax.resources.generated.js +14 -0
  294. package/dist/rest/namespaces/fax.resources.generated.js.map +1 -0
  295. package/dist/rest/namespaces/fax.types.generated.d.ts +131 -0
  296. package/dist/rest/namespaces/fax.types.generated.js +8 -0
  297. package/dist/rest/namespaces/fax.types.generated.js.map +1 -0
  298. package/dist/rest/namespaces/imported-numbers.d.ts +3 -18
  299. package/dist/rest/namespaces/imported-numbers.js +3 -21
  300. package/dist/rest/namespaces/imported-numbers.js.map +1 -1
  301. package/dist/rest/namespaces/logs.d.ts +10 -101
  302. package/dist/rest/namespaces/logs.js +10 -128
  303. package/dist/rest/namespaces/logs.js.map +1 -1
  304. package/dist/rest/namespaces/logs.resources.generated.d.ts +9 -0
  305. package/dist/rest/namespaces/logs.resources.generated.js +17 -0
  306. package/dist/rest/namespaces/logs.resources.generated.js.map +1 -0
  307. package/dist/rest/namespaces/logs.types.generated.d.ts +131 -0
  308. package/dist/rest/namespaces/logs.types.generated.js +8 -0
  309. package/dist/rest/namespaces/logs.types.generated.js.map +1 -0
  310. package/dist/rest/namespaces/lookup.d.ts +3 -25
  311. package/dist/rest/namespaces/lookup.js +3 -27
  312. package/dist/rest/namespaces/lookup.js.map +1 -1
  313. package/dist/rest/namespaces/message.resources.generated.d.ts +6 -0
  314. package/dist/rest/namespaces/message.resources.generated.js +14 -0
  315. package/dist/rest/namespaces/message.resources.generated.js.map +1 -0
  316. package/dist/rest/namespaces/message.types.generated.d.ts +122 -0
  317. package/dist/rest/namespaces/message.types.generated.js +8 -0
  318. package/dist/rest/namespaces/message.types.generated.js.map +1 -0
  319. package/dist/rest/namespaces/messages.resources.generated.d.ts +18 -0
  320. package/dist/rest/namespaces/messages.resources.generated.js +44 -0
  321. package/dist/rest/namespaces/messages.resources.generated.js.map +1 -0
  322. package/dist/rest/namespaces/messages.types.generated.d.ts +99 -0
  323. package/dist/rest/namespaces/messages.types.generated.js +8 -0
  324. package/dist/rest/namespaces/messages.types.generated.js.map +1 -0
  325. package/dist/rest/namespaces/mfa.d.ts +3 -42
  326. package/dist/rest/namespaces/mfa.js +3 -49
  327. package/dist/rest/namespaces/mfa.js.map +1 -1
  328. package/dist/rest/namespaces/number-groups.d.ts +3 -45
  329. package/dist/rest/namespaces/number-groups.js +3 -53
  330. package/dist/rest/namespaces/number-groups.js.map +1 -1
  331. package/dist/rest/namespaces/phone-numbers.d.ts +8 -196
  332. package/dist/rest/namespaces/phone-numbers.js +8 -230
  333. package/dist/rest/namespaces/phone-numbers.js.map +1 -1
  334. package/dist/rest/namespaces/project.d.ts +6 -42
  335. package/dist/rest/namespaces/project.js +6 -51
  336. package/dist/rest/namespaces/project.js.map +1 -1
  337. package/dist/rest/namespaces/project.resources.generated.d.ts +17 -0
  338. package/dist/rest/namespaces/project.resources.generated.js +44 -0
  339. package/dist/rest/namespaces/project.resources.generated.js.map +1 -0
  340. package/dist/rest/namespaces/project.types.generated.d.ts +58 -0
  341. package/dist/rest/namespaces/project.types.generated.js +8 -0
  342. package/dist/rest/namespaces/project.types.generated.js.map +1 -0
  343. package/dist/rest/namespaces/projects.resources.generated.d.ts +12 -0
  344. package/dist/rest/namespaces/projects.resources.generated.js +25 -0
  345. package/dist/rest/namespaces/projects.resources.generated.js.map +1 -0
  346. package/dist/rest/namespaces/projects.types.generated.d.ts +77 -0
  347. package/dist/rest/namespaces/projects.types.generated.js +8 -0
  348. package/dist/rest/namespaces/projects.types.generated.js.map +1 -0
  349. package/dist/rest/namespaces/pubsub.d.ts +4 -18
  350. package/dist/rest/namespaces/pubsub.js +4 -21
  351. package/dist/rest/namespaces/pubsub.js.map +1 -1
  352. package/dist/rest/namespaces/pubsub.resources.generated.d.ts +12 -0
  353. package/dist/rest/namespaces/pubsub.resources.generated.js +29 -0
  354. package/dist/rest/namespaces/pubsub.resources.generated.js.map +1 -0
  355. package/dist/rest/namespaces/pubsub.types.generated.d.ts +60 -0
  356. package/dist/rest/namespaces/pubsub.types.generated.js +8 -0
  357. package/dist/rest/namespaces/pubsub.types.generated.js.map +1 -0
  358. package/dist/rest/namespaces/queues.d.ts +3 -38
  359. package/dist/rest/namespaces/queues.js +3 -44
  360. package/dist/rest/namespaces/queues.js.map +1 -1
  361. package/dist/rest/namespaces/recordings.d.ts +3 -34
  362. package/dist/rest/namespaces/recordings.js +3 -40
  363. package/dist/rest/namespaces/recordings.js.map +1 -1
  364. package/dist/rest/namespaces/registry.d.ts +6 -137
  365. package/dist/rest/namespaces/registry.js +6 -173
  366. package/dist/rest/namespaces/registry.js.map +1 -1
  367. package/dist/rest/namespaces/relay-rest.resources.generated.d.ts +168 -0
  368. package/dist/rest/namespaces/relay-rest.resources.generated.js +430 -0
  369. package/dist/rest/namespaces/relay-rest.resources.generated.js.map +1 -0
  370. package/dist/rest/namespaces/relay-rest.types.generated.d.ts +1906 -0
  371. package/dist/rest/namespaces/relay-rest.types.generated.js +8 -0
  372. package/dist/rest/namespaces/relay-rest.types.generated.js.map +1 -0
  373. package/dist/rest/namespaces/short-codes.d.ts +3 -35
  374. package/dist/rest/namespaces/short-codes.js +3 -41
  375. package/dist/rest/namespaces/short-codes.js.map +1 -1
  376. package/dist/rest/namespaces/sip-profile.d.ts +3 -24
  377. package/dist/rest/namespaces/sip-profile.js +3 -29
  378. package/dist/rest/namespaces/sip-profile.js.map +1 -1
  379. package/dist/rest/namespaces/verified-callers.d.ts +3 -29
  380. package/dist/rest/namespaces/verified-callers.js +3 -34
  381. package/dist/rest/namespaces/verified-callers.js.map +1 -1
  382. package/dist/rest/namespaces/video.d.ts +10 -227
  383. package/dist/rest/namespaces/video.js +10 -288
  384. package/dist/rest/namespaces/video.js.map +1 -1
  385. package/dist/rest/namespaces/video.resources.generated.d.ts +81 -0
  386. package/dist/rest/namespaces/video.resources.generated.js +171 -0
  387. package/dist/rest/namespaces/video.resources.generated.js.map +1 -0
  388. package/dist/rest/namespaces/video.types.generated.d.ts +771 -0
  389. package/dist/rest/namespaces/video.types.generated.js +8 -0
  390. package/dist/rest/namespaces/video.types.generated.js.map +1 -0
  391. package/dist/rest/namespaces/voice.resources.generated.d.ts +9 -0
  392. package/dist/rest/namespaces/voice.resources.generated.js +17 -0
  393. package/dist/rest/namespaces/voice.resources.generated.js.map +1 -0
  394. package/dist/rest/namespaces/voice.types.generated.d.ts +214 -0
  395. package/dist/rest/namespaces/voice.types.generated.js +8 -0
  396. package/dist/rest/namespaces/voice.types.generated.js.map +1 -0
  397. package/dist/rest/pagination.d.ts +5 -1
  398. package/dist/rest/pagination.js +40 -20
  399. package/dist/rest/pagination.js.map +1 -1
  400. package/dist/rest/types.d.ts +21 -3
  401. package/dist/schema.json +299 -98
  402. package/dist/skills/SkillBase.d.ts +97 -20
  403. package/dist/skills/SkillBase.js +100 -17
  404. package/dist/skills/SkillBase.js.map +1 -1
  405. package/dist/skills/SkillManager.d.ts +66 -13
  406. package/dist/skills/SkillManager.js +101 -20
  407. package/dist/skills/SkillManager.js.map +1 -1
  408. package/dist/skills/SkillName.d.ts +44 -0
  409. package/dist/skills/SkillName.js +2 -0
  410. package/dist/skills/SkillName.js.map +1 -0
  411. package/dist/skills/SkillRegistry.d.ts +22 -11
  412. package/dist/skills/SkillRegistry.js +47 -17
  413. package/dist/skills/SkillRegistry.js.map +1 -1
  414. package/dist/skills/builtin/api_ninjas_trivia.d.ts +3 -1
  415. package/dist/skills/builtin/api_ninjas_trivia.js +18 -6
  416. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
  417. package/dist/skills/builtin/ask_claude.d.ts +14 -4
  418. package/dist/skills/builtin/ask_claude.js +36 -14
  419. package/dist/skills/builtin/ask_claude.js.map +1 -1
  420. package/dist/skills/builtin/claude_skills.d.ts +3 -1
  421. package/dist/skills/builtin/claude_skills.js +19 -15
  422. package/dist/skills/builtin/claude_skills.js.map +1 -1
  423. package/dist/skills/builtin/custom_skills.d.ts +10 -3
  424. package/dist/skills/builtin/custom_skills.js +26 -9
  425. package/dist/skills/builtin/custom_skills.js.map +1 -1
  426. package/dist/skills/builtin/datasphere.d.ts +5 -3
  427. package/dist/skills/builtin/datasphere.js +21 -22
  428. package/dist/skills/builtin/datasphere.js.map +1 -1
  429. package/dist/skills/builtin/datasphere_serverless.d.ts +12 -1
  430. package/dist/skills/builtin/datasphere_serverless.js +17 -6
  431. package/dist/skills/builtin/datasphere_serverless.js.map +1 -1
  432. package/dist/skills/builtin/datetime.d.ts +3 -1
  433. package/dist/skills/builtin/datetime.js +11 -7
  434. package/dist/skills/builtin/datetime.js.map +1 -1
  435. package/dist/skills/builtin/google_maps.d.ts +29 -14
  436. package/dist/skills/builtin/google_maps.js +89 -269
  437. package/dist/skills/builtin/google_maps.js.map +1 -1
  438. package/dist/skills/builtin/index.d.ts +8 -6
  439. package/dist/skills/builtin/index.js +8 -6
  440. package/dist/skills/builtin/index.js.map +1 -1
  441. package/dist/skills/builtin/info_gatherer.d.ts +4 -2
  442. package/dist/skills/builtin/info_gatherer.js +20 -12
  443. package/dist/skills/builtin/info_gatherer.js.map +1 -1
  444. package/dist/skills/builtin/joke.d.ts +16 -6
  445. package/dist/skills/builtin/joke.js +54 -37
  446. package/dist/skills/builtin/joke.js.map +1 -1
  447. package/dist/skills/builtin/math.d.ts +3 -1
  448. package/dist/skills/builtin/math.js +14 -9
  449. package/dist/skills/builtin/math.js.map +1 -1
  450. package/dist/skills/builtin/mcp_gateway.d.ts +34 -5
  451. package/dist/skills/builtin/mcp_gateway.js +77 -46
  452. package/dist/skills/builtin/mcp_gateway.js.map +1 -1
  453. package/dist/skills/builtin/native_vector_search.d.ts +19 -5
  454. package/dist/skills/builtin/native_vector_search.js +179 -61
  455. package/dist/skills/builtin/native_vector_search.js.map +1 -1
  456. package/dist/skills/builtin/play_background_file.d.ts +21 -15
  457. package/dist/skills/builtin/play_background_file.js +43 -122
  458. package/dist/skills/builtin/play_background_file.js.map +1 -1
  459. package/dist/skills/builtin/spider.d.ts +42 -4
  460. package/dist/skills/builtin/spider.js +277 -104
  461. package/dist/skills/builtin/spider.js.map +1 -1
  462. package/dist/skills/builtin/swml_transfer.d.ts +14 -3
  463. package/dist/skills/builtin/swml_transfer.js +45 -24
  464. package/dist/skills/builtin/swml_transfer.js.map +1 -1
  465. package/dist/skills/builtin/weather_api.d.ts +24 -13
  466. package/dist/skills/builtin/weather_api.js +38 -30
  467. package/dist/skills/builtin/weather_api.js.map +1 -1
  468. package/dist/skills/builtin/web_search.d.ts +48 -10
  469. package/dist/skills/builtin/web_search.js +294 -100
  470. package/dist/skills/builtin/web_search.js.map +1 -1
  471. package/dist/skills/builtin/wikipedia_search.d.ts +4 -2
  472. package/dist/skills/builtin/wikipedia_search.js +14 -13
  473. package/dist/skills/builtin/wikipedia_search.js.map +1 -1
  474. package/dist/skills/index.d.ts +3 -2
  475. package/dist/skills/index.js +1 -1
  476. package/dist/skills/index.js.map +1 -1
  477. package/dist/swml_verbs_generated.d.ts +2824 -0
  478. package/dist/swml_verbs_generated.js +12 -0
  479. package/dist/swml_verbs_generated.js.map +1 -0
  480. package/dist/types.d.ts +59 -6
  481. package/dist/web.d.ts +27 -0
  482. package/dist/web.js +20 -0
  483. package/dist/web.js.map +1 -0
  484. package/docs/agent-guide.md +1034 -0
  485. package/docs/ai_chat.md +560 -0
  486. package/docs/api-reference.md +3534 -0
  487. package/docs/architecture.md +846 -0
  488. package/docs/bedrock_agent.md +411 -0
  489. package/docs/cli-guide.md +403 -0
  490. package/docs/cloud_functions_guide.md +399 -0
  491. package/docs/configuration.md +548 -0
  492. package/docs/contexts-guide.md +884 -0
  493. package/docs/datamap-guide.md +1160 -0
  494. package/docs/developer_pain_points.md +548 -0
  495. package/docs/llm_parameters.md +298 -0
  496. package/docs/mcp_gateway_reference.md +354 -0
  497. package/docs/mcp_integration.md +162 -0
  498. package/docs/pgi_agent_guide.md +1820 -0
  499. package/docs/prefabs-guide.md +815 -0
  500. package/docs/programmatically_governed_inference.md +301 -0
  501. package/docs/sdk_features.md +501 -0
  502. package/docs/security.md +559 -0
  503. package/docs/serverless-guide.md +520 -0
  504. package/docs/skills-guide.md +1223 -0
  505. package/docs/skills-system.md +405 -0
  506. package/docs/skills_parameter_schema.md +417 -0
  507. package/docs/swaig-reference.md +1938 -0
  508. package/docs/swml_service_guide.md +573 -0
  509. package/docs/third_party_skills.md +410 -0
  510. package/docs/web_service.md +666 -0
  511. package/examples/README.md +202 -0
  512. package/examples/advanced-datamap.ts +108 -0
  513. package/examples/advanced-dynamic-config.ts +70 -0
  514. package/examples/auto-vivified.ts +95 -0
  515. package/examples/call-flow.ts +65 -0
  516. package/examples/comprehensive-dynamic.ts +125 -0
  517. package/examples/contexts-steps.ts +65 -0
  518. package/examples/custom-path.ts +45 -0
  519. package/examples/datamap-tools.ts +51 -0
  520. package/examples/datasphere-multi-instance.ts +66 -0
  521. package/examples/datasphere-serverless-env.ts +87 -0
  522. package/examples/datasphere-webhook-env.ts +65 -0
  523. package/examples/datasphere.ts +56 -0
  524. package/examples/declarative.ts +100 -0
  525. package/examples/dynamic-config.ts +54 -0
  526. package/examples/dynamic-info-gatherer.ts +69 -0
  527. package/examples/dynamic-swml-service.ts +67 -0
  528. package/examples/gather-info.ts +95 -0
  529. package/examples/gather-per-question-functions-demo.ts +139 -0
  530. package/examples/joke-agent.ts +34 -0
  531. package/examples/kubernetes-agent.ts +45 -0
  532. package/examples/llm-params.ts +75 -0
  533. package/examples/mcp-agent.ts +89 -0
  534. package/examples/mcp-gateway.ts +81 -0
  535. package/examples/multi-agent.ts +80 -0
  536. package/examples/multi-endpoint.ts +79 -0
  537. package/examples/pgi/case-domain.ts +114 -0
  538. package/examples/pgi/serve.ts +16 -0
  539. package/examples/pgi/support-agent.ts +265 -0
  540. package/examples/pom-prompt.ts +70 -0
  541. package/examples/prefab-concierge.ts +42 -0
  542. package/examples/prefab-faq.ts +58 -0
  543. package/examples/prefab-info-gatherer.ts +33 -0
  544. package/examples/prefab-receptionist.ts +36 -0
  545. package/examples/prefab-survey.ts +69 -0
  546. package/examples/quickstart-agent.ts +29 -0
  547. package/examples/quickstart-relay.ts +25 -0
  548. package/examples/quickstart-rest.ts +25 -0
  549. package/examples/record-call.ts +65 -0
  550. package/examples/relay-demo.ts +33 -0
  551. package/examples/room-and-sip.ts +93 -0
  552. package/examples/serverless-lambda.ts +43 -0
  553. package/examples/session-state.ts +83 -0
  554. package/examples/simple-agent.ts +36 -0
  555. package/examples/simple-static.ts +29 -0
  556. package/examples/skills-demo.ts +41 -0
  557. package/examples/step-function-inheritance-demo.ts +124 -0
  558. package/examples/swaig-features.ts +193 -0
  559. package/examples/swml-service-routing.ts +66 -0
  560. package/examples/swml-service.ts +38 -0
  561. package/examples/swmlservice_ai_sidecar.ts +104 -0
  562. package/examples/swmlservice_swaig_standalone.ts +79 -0
  563. package/examples/tap.ts +67 -0
  564. package/examples/typed-tools.ts +68 -0
  565. package/examples/verb-methods.ts +45 -0
  566. package/examples/web-search-multi-instance.ts +75 -0
  567. package/examples/web-search.ts +38 -0
  568. package/examples/wikipedia.ts +36 -0
  569. package/livewire/README.md +164 -0
  570. package/livewire/docs/migration-guide.md +251 -0
  571. package/livewire/examples/livewire-basic-agent.ts +74 -0
  572. package/livewire/examples/livewire-handoff.ts +196 -0
  573. package/livewire/examples/livewire-multi-tool.ts +121 -0
  574. package/package.json +85 -13
  575. package/relay/README.md +101 -0
  576. package/relay/docs/call-methods.md +622 -0
  577. package/relay/docs/client-reference.md +281 -0
  578. package/relay/docs/events.md +193 -0
  579. package/relay/docs/getting-started.md +221 -0
  580. package/relay/docs/guide.md +386 -0
  581. package/relay/docs/messaging.md +246 -0
  582. package/relay/examples/relay-inbound.ts +66 -0
  583. package/relay/examples/relay-messaging.ts +74 -0
  584. package/relay/examples/relay-outbound.ts +76 -0
  585. package/rest/README.md +141 -0
  586. package/rest/docs/calling.md +313 -0
  587. package/rest/docs/client-reference.md +149 -0
  588. package/rest/docs/fabric.md +192 -0
  589. package/rest/docs/getting-started.md +138 -0
  590. package/rest/docs/guide.md +421 -0
  591. package/rest/docs/namespaces.md +367 -0
  592. package/rest/docs/phone-binding.md +116 -0
  593. package/rest/examples/rest-10dlc-registration.ts +177 -0
  594. package/rest/examples/rest-bind-phone-to-swml-webhook.ts +66 -0
  595. package/rest/examples/rest-calling-ivr-and-ai.ts +136 -0
  596. package/rest/examples/rest-calling-play-and-record.ts +98 -0
  597. package/rest/examples/rest-client.ts +59 -0
  598. package/rest/examples/rest-datasphere-search.ts +81 -0
  599. package/rest/examples/rest-fabric-conferences-and-routing.ts +147 -0
  600. package/rest/examples/rest-fabric-subscribers-and-sip.ts +106 -0
  601. package/rest/examples/rest-fabric-swml-and-callflows.ts +101 -0
  602. package/rest/examples/rest-manage-resources.ts +64 -0
  603. package/rest/examples/rest-phone-number-management.ts +200 -0
  604. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  605. package/rest/examples/rest-video-rooms.ts +186 -0
  606. package/tutorial/fred/fred.ts +218 -0
  607. package/tutorial/fred/tutorial/01-introduction.md +141 -0
  608. package/tutorial/fred/tutorial/02-setup.md +304 -0
  609. package/tutorial/fred/tutorial/03-basic-agent.md +284 -0
  610. package/tutorial/fred/tutorial/04-wikipedia-skill.md +298 -0
  611. package/tutorial/fred/tutorial/05-custom-functions.md +347 -0
  612. package/tutorial/fred/tutorial/06-running-testing.md +642 -0
  613. package/tutorial/fred/tutorial/README.md +56 -0
  614. package/tutorial/fred/tutorial/appendix-complete-code.md +632 -0
  615. package/tutorial/fred/tutorial/appendix-docker-deployment.md +504 -0
  616. package/tutorial/full-guardrails-agent/handlers.ts +436 -0
  617. package/tutorial/full-guardrails-agent/penny.ts +305 -0
  618. package/tutorial/full-guardrails-agent/reservations.ts +1109 -0
  619. package/tutorial/full-guardrails-agent/tutorial/01-why-guardrails.md +149 -0
  620. package/tutorial/full-guardrails-agent/tutorial/02-design-first.md +139 -0
  621. package/tutorial/full-guardrails-agent/tutorial/03-rules-first.md +422 -0
  622. package/tutorial/full-guardrails-agent/tutorial/04-the-shell.md +238 -0
  623. package/tutorial/full-guardrails-agent/tutorial/05-steps-and-scoping.md +247 -0
  624. package/tutorial/full-guardrails-agent/tutorial/06-tools-that-decide.md +467 -0
  625. package/tutorial/full-guardrails-agent/tutorial/07-gather-and-projection.md +160 -0
  626. package/tutorial/full-guardrails-agent/tutorial/08-the-verification-gate.md +333 -0
  627. package/tutorial/full-guardrails-agent/tutorial/09-people-and-endings.md +313 -0
  628. package/tutorial/full-guardrails-agent/tutorial/10-testing-and-running.md +387 -0
  629. package/tutorial/full-guardrails-agent/tutorial/README.md +106 -0
  630. package/tutorial/full-guardrails-agent/tutorial/appendix-complete-code.md +2207 -0
  631. package/tutorial/full-guardrails-agent/tutorial/appendix-deployment.md +191 -0
  632. package/tutorial/full-guardrails-agent/tutorial/appendix-technique-map.md +117 -0
  633. package/tutorial/full-guardrails-agent/workflow.ts +219 -0
  634. package/tutorial/multi_agents/README.md +175 -0
  635. package/tutorial/multi_agents/advanced_agent.ts +395 -0
  636. package/tutorial/multi_agents/extending_agents.ts +641 -0
  637. package/tutorial/multi_agents/knowledge.ts +59 -0
  638. package/tutorial/multi_agents/lesson1_first_agent.md +368 -0
  639. package/tutorial/multi_agents/lesson2_knowledge_bases.md +404 -0
  640. package/tutorial/multi_agents/lesson3_multi_agent_systems.md +621 -0
  641. package/tutorial/multi_agents/lesson4_advanced_features.md +805 -0
  642. package/tutorial/multi_agents/lesson5_extending_agents.md +856 -0
  643. package/tutorial/multi_agents/pc_builder.ts +529 -0
  644. package/tutorial/multi_agents/sales_agent.ts +88 -0
  645. package/tutorial/multi_agents/sales_agent_with_search.ts +116 -0
  646. package/tutorial/multi_agents/sales_knowledge.md +139 -0
  647. package/tutorial/multi_agents/support_knowledge.md +256 -0
  648. package/dist/cli/mock-data.d.ts +0 -37
  649. package/dist/cli/mock-data.js +0 -80
  650. package/dist/cli/mock-data.js.map +0 -1
  651. package/dist/generateVerbTypes.d.ts +0 -11
  652. package/dist/generateVerbTypes.js +0 -265
  653. package/dist/generateVerbTypes.js.map +0 -1
  654. package/dist/rest/namespaces/compat.d.ts +0 -585
  655. package/dist/rest/namespaces/compat.js +0 -735
  656. 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.
13
80
  *
14
- * Return an instance (or a promise that resolves to one) from any SWAIG tool handler.
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).
91
+ *
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;
71
174
  return this;
72
175
  }
73
176
  /**
74
- * Enable or disable post-processing of actions.
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 = '';
202
+ return this;
203
+ }
204
+ /**
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) {
@@ -228,7 +412,7 @@ export class FunctionResult {
228
412
  return this;
229
413
  }
230
414
  /**
231
- * Set the silence duration that marks the end of a user's speech.
415
+ * Set the silence after detected speech that finalizes speech recognition.
232
416
  * @param milliseconds - Timeout in milliseconds.
233
417
  * @returns This instance for chaining.
234
418
  */
@@ -236,7 +420,8 @@ export class FunctionResult {
236
420
  return this.addAction('end_of_speech_timeout', milliseconds);
237
421
  }
238
422
  /**
239
- * Set the timeout for speech event detection.
423
+ * Set the time since the last speech detection event after which speech
424
+ * recognition is finalized. Suits noisy environments.
240
425
  * @param milliseconds - Timeout in milliseconds.
241
426
  * @returns This instance for chaining.
242
427
  */
@@ -245,7 +430,8 @@ export class FunctionResult {
245
430
  }
246
431
  // ── Data ────────────────────────────────────────────────────────────
247
432
  /**
248
- * Merge key-value pairs into the global data store shared across functions.
433
+ * Merge key-value pairs into the call's global data (`set_global_data`),
434
+ * which persists for the AI session and is readable by every function.
249
435
  * @param data - Key-value pairs to set or update.
250
436
  * @returns This instance for chaining.
251
437
  */
@@ -261,7 +447,8 @@ export class FunctionResult {
261
447
  return this.addAction('unset_global_data', keys);
262
448
  }
263
449
  /**
264
- * Set metadata key-value pairs on the current call.
450
+ * Set metadata (`set_meta_data`) scoped to the current function's
451
+ * `meta_data_token`. Functions sharing a token share the metadata.
265
452
  * @param data - Metadata key-value pairs to set.
266
453
  * @returns This instance for chaining.
267
454
  */
@@ -269,7 +456,8 @@ export class FunctionResult {
269
456
  return this.addAction('set_meta_data', data);
270
457
  }
271
458
  /**
272
- * Remove metadata keys from the current call.
459
+ * Remove metadata keys (`unset_meta_data`) from the current function's
460
+ * `meta_data_token` scope.
273
461
  * @param keys - A single key or array of keys to remove.
274
462
  * @returns This instance for chaining.
275
463
  */
@@ -279,9 +467,18 @@ export class FunctionResult {
279
467
  // ── SWML helpers ────────────────────────────────────────────────────
280
468
  /**
281
469
  * 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.
470
+ *
471
+ * A JSON string is parsed; a string that isn't JSON is sent as
472
+ * `{ raw_swml: <string> }`. An object with a `toDict()` method is converted
473
+ * through it, and a plain object is copied. Any other value throws.
474
+ *
475
+ * @param swmlContent - SWML as a JSON string, a plain object, or an object
476
+ * with `toDict()`.
477
+ * @param transfer - When `true`, emits `transfer: "true"` beside the `SWML`
478
+ * key, so the call leaves the agent for the SWML.
284
479
  * @returns This instance for chaining.
480
+ * @throws {Error} When `swmlContent` is not a string, a plain object, or an
481
+ * object with `toDict()` (for example a number, an array or `null`).
285
482
  */
286
483
  executeSwml(swmlContent, transfer = false) {
287
484
  let swmlData;
@@ -293,19 +490,38 @@ export class FunctionResult {
293
490
  swmlData = { raw_swml: swmlContent };
294
491
  }
295
492
  }
296
- else if (typeof swmlContent.toDict === 'function') {
493
+ else if (typeof swmlContent === 'object' &&
494
+ swmlContent !== null &&
495
+ typeof swmlContent.toDict === 'function') {
496
+ // SWML SDK object - convert via toDict(). The object/null check guards the
497
+ // property access (Python's hasattr is null-safe; TS member access is not).
297
498
  swmlData = swmlContent.toDict();
298
499
  }
299
- else {
500
+ else if (typeof swmlContent === 'object' &&
501
+ swmlContent !== null &&
502
+ !Array.isArray(swmlContent)) {
503
+ // Plain object (dict) - copy to avoid mutating the caller's data.
300
504
  swmlData = { ...swmlContent };
301
505
  }
302
- if (transfer) {
303
- swmlData['transfer'] = 'true';
506
+ else {
507
+ // Mirror Python's execute_swml: a non-string / non-toDict / non-dict value
508
+ // (number, array, null, ...) is a programming error. This is the shared sink
509
+ // for every SWML helper, so a bad value must fail loudly rather than spread.
510
+ throw new Error('swml_content must be string, dict, or SWML object');
304
511
  }
305
- return this.addAction('SWML', swmlData);
512
+ // transfer rides BESIDE the SWML document, not inside it: the same shape
513
+ // connect() and swmlTransfer() emit. Inside the document it isn't a SWML
514
+ // key, and the call never leaves the agent.
515
+ const action = { SWML: swmlData };
516
+ if (transfer)
517
+ action['transfer'] = 'true';
518
+ this.action.push(action);
519
+ return this;
306
520
  }
307
521
  /**
308
- * Change the current SWML step.
522
+ * Move the conversation to a step in the current context (`change_step`).
523
+ * The change applies at once, and the step must exist in the current
524
+ * context of the agent's contexts (see `defineContexts()`).
309
525
  * @param stepName - The name of the step to switch to.
310
526
  * @returns This instance for chaining.
311
527
  */
@@ -313,7 +529,8 @@ export class FunctionResult {
313
529
  return this.addAction('change_step', stepName);
314
530
  }
315
531
  /**
316
- * Change the current SWML context.
532
+ * Move the conversation to another context (`change_context`). The context
533
+ * must exist in the agent's contexts (see `defineContexts()`).
317
534
  * @param contextName - The name of the context to switch to.
318
535
  * @returns This instance for chaining.
319
536
  */
@@ -321,7 +538,8 @@ export class FunctionResult {
321
538
  return this.addAction('change_context', contextName);
322
539
  }
323
540
  /**
324
- * Emit a custom user event via SWML.
541
+ * Send an event to the client connected to the call, through an inline SWML
542
+ * `user_event` verb. The client receives it as a `user_event` event.
325
543
  * @param eventData - The event payload.
326
544
  * @returns This instance for chaining.
327
545
  */
@@ -332,8 +550,12 @@ export class FunctionResult {
332
550
  });
333
551
  }
334
552
  /**
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.
553
+ * Replace the agent's prompt mid-call (`context_switch`). With only
554
+ * `systemPrompt`, emits the prompt string; otherwise emits an object with the
555
+ * fields that are set.
556
+ * @param opts - The new system prompt, a user prompt to add, whether to
557
+ * summarize the conversation so far (`consolidate`), and whether to reset the
558
+ * context completely (`fullReset`).
337
559
  * @returns This instance for chaining.
338
560
  */
339
561
  switchContext(opts) {
@@ -365,7 +587,8 @@ export class FunctionResult {
365
587
  return this.addAction('toggle_functions', toggles);
366
588
  }
367
589
  /**
368
- * Control whether functions fire on speaker timeout.
590
+ * Control whether functions can be called on speaker timeout
591
+ * (`functions_on_speaker_timeout`).
369
592
  * @param enabled - Whether to enable function execution on timeout.
370
593
  * @returns This instance for chaining.
371
594
  */
@@ -373,7 +596,8 @@ export class FunctionResult {
373
596
  return this.addAction('functions_on_speaker_timeout', enabled);
374
597
  }
375
598
  /**
376
- * Update AI engine settings at runtime.
599
+ * Update AI settings at runtime (`settings`). The platform validates the
600
+ * keys, such as `temperature`, `top-p` and `barge-confidence`.
377
601
  * @param settings - Key-value pairs of settings to update.
378
602
  * @returns This instance for chaining.
379
603
  */
@@ -382,7 +606,7 @@ export class FunctionResult {
382
606
  }
383
607
  // ── User input / history ────────────────────────────────────────────
384
608
  /**
385
- * Inject text as if the user had spoken it.
609
+ * Queue text as if the user had said it (`user_input`).
386
610
  * @param text - The simulated user input text.
387
611
  * @returns This instance for chaining.
388
612
  */
@@ -390,16 +614,19 @@ export class FunctionResult {
390
614
  return this.addAction('user_input', text);
391
615
  }
392
616
  /**
393
- * Enable or disable extensive data reporting in function calls.
394
- * @param enabled - Whether to enable extensive data.
617
+ * Send the full data to the model for this turn only, then a smaller
618
+ * replacement in later turns (`extensive_data`).
619
+ * @param enabled - Whether to send extensive data this turn.
395
620
  * @returns This instance for chaining.
396
621
  */
397
622
  enableExtensiveData(enabled = true) {
398
623
  return this.addAction('extensive_data', enabled);
399
624
  }
400
625
  /**
401
- * Replace the function call output in conversation history.
402
- * @param text - Replacement text, or true to replace with the response.
626
+ * After the first send, replace this tool call and its result in the
627
+ * conversation history (`replace_in_history`).
628
+ * @param text - A string replaces the pair with an assistant message holding
629
+ * that text; `true` (default) removes the pair from the history.
403
630
  * @returns This instance for chaining.
404
631
  */
405
632
  replaceInHistory(text = true) {
@@ -409,8 +636,8 @@ export class FunctionResult {
409
636
  /**
410
637
  * Send an SMS or MMS message from within the call flow.
411
638
  *
412
- * @param opts - SMS parameters. Must include either `body` (text SMS) or
413
- * `media` (MMS) — supplying neither throws.
639
+ * @param opts - SMS parameters. Must include `body` (text SMS), `media`
640
+ * (MMS), or both; supplying neither throws.
414
641
  * @returns This instance for chaining.
415
642
  * @throws {Error} When neither `body` nor `media` is provided.
416
643
  */
@@ -436,7 +663,7 @@ export class FunctionResult {
436
663
  });
437
664
  }
438
665
  /**
439
- * Start recording the call.
666
+ * Start a background recording of the call (SWML `record_call`).
440
667
  * @param opts - Recording options including format, direction, and timeouts.
441
668
  * @returns This instance for chaining.
442
669
  */
@@ -482,16 +709,33 @@ export class FunctionResult {
482
709
  });
483
710
  }
484
711
  /**
485
- * Start a media tap to stream audio to an external URI.
712
+ * Start a media tap to stream audio to an external URI (`ws://`, `wss://` or
713
+ * `rtp://IP:port`). `direction` is always sent; `codec` and `rtpPtime` are
714
+ * sent only when they differ from `PCMU` and 20.
486
715
  * @param opts - Tap parameters including URI, direction, and codec.
716
+ * @throws {Error} On a `direction` or `codec` outside the allowed values, or
717
+ * an `rtpPtime` that isn't positive.
487
718
  * @returns This instance for chaining.
488
719
  */
489
720
  tap(opts) {
721
+ // Runtime guards matching the Python reference: a JS caller can pass any
722
+ // string, and the types can't express rtp_ptime > 0.
723
+ const direction = opts.direction ?? 'both';
724
+ if (!['speak', 'listen', 'both'].includes(direction)) {
725
+ throw new Error("direction must be one of ['speak', 'listen', 'both']");
726
+ }
727
+ if (opts.codec !== undefined && !['PCMU', 'PCMA'].includes(opts.codec)) {
728
+ throw new Error("codec must be one of ['PCMU', 'PCMA']");
729
+ }
730
+ if (opts.rtpPtime !== undefined && opts.rtpPtime <= 0) {
731
+ throw new Error('rtp_ptime must be a positive integer');
732
+ }
490
733
  const params = { uri: opts.uri };
491
734
  if (opts.controlId)
492
735
  params['control_id'] = opts.controlId;
493
- if (opts.direction && opts.direction !== 'both')
494
- params['direction'] = opts.direction;
736
+ // Always sent: the verb's own default is "speak", not this helper's
737
+ // "both", so leaving it out would tap less than the caller asked for.
738
+ params['direction'] = direction;
495
739
  if (opts.codec && opts.codec !== 'PCMU')
496
740
  params['codec'] = opts.codec;
497
741
  if (opts.rtpPtime && opts.rtpPtime !== 20)
@@ -519,7 +763,7 @@ export class FunctionResult {
519
763
  }
520
764
  // ── Rooms / Conferences ─────────────────────────────────────────────
521
765
  /**
522
- * Join a SignalWire room.
766
+ * Join a RELAY room by name (SWML `join_room`).
523
767
  * @param name - The room name to join.
524
768
  * @returns This instance for chaining.
525
769
  */
@@ -541,23 +785,49 @@ export class FunctionResult {
541
785
  });
542
786
  }
543
787
  /**
544
- * Join a conference by name with optional configuration.
788
+ * Join a conference by name with optional configuration. Options at their
789
+ * default value are left out; with none left, `join_conference` is the name
790
+ * string alone.
791
+ *
792
+ * `maxParticipants` is sent whenever it is given, as an integer of 2 or
793
+ * more: the platform refuses a conference of fewer than 2 and sets no upper
794
+ * limit (the SWML schema's cap of 100000 isn't enforced). A numeric string
795
+ * is converted, and a SWML variable reference such as `'${room_size}'` is
796
+ * passed through.
545
797
  * @param name - The conference name to join.
546
798
  * @param opts - Optional conference settings such as mute, recording, and callbacks.
799
+ * @throws {Error} When `name` is blank, or `maxParticipants` isn't an
800
+ * integer of at least 2 or a SWML variable reference.
547
801
  * @returns This instance for chaining.
548
802
  */
549
803
  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);
804
+ // Runtime guards matching the Python reference (beep/record/trim/method are
805
+ // covered at compile time by the literal-union types in the signature; these two cannot be).
806
+ if (!name.trim()) {
807
+ throw new Error('name cannot be empty');
808
+ }
809
+ // The platform refuses fewer than 2 members and has no upper limit.
810
+ const maxParticipants = opts?.maxParticipants !== undefined && opts.maxParticipants !== null
811
+ ? swmlInt('max_participants', opts.maxParticipants, 2)
812
+ : undefined;
813
+ const hasNonDefaults = opts &&
814
+ (opts.muted ||
815
+ (opts.beep && opts.beep !== 'true') ||
816
+ opts.startOnEnter === false ||
817
+ opts.endOnExit ||
818
+ opts.waitUrl ||
819
+ maxParticipants !== undefined ||
820
+ (opts.record && opts.record !== 'do-not-record') ||
821
+ opts.region ||
822
+ (opts.trim && opts.trim !== 'trim-silence') ||
823
+ opts.coach ||
824
+ opts.statusCallbackEvent ||
825
+ opts.statusCallback ||
826
+ (opts.statusCallbackMethod && opts.statusCallbackMethod !== 'POST') ||
827
+ opts.recordingStatusCallback ||
828
+ (opts.recordingStatusCallbackMethod && opts.recordingStatusCallbackMethod !== 'POST') ||
829
+ (opts.recordingStatusCallbackEvent && opts.recordingStatusCallbackEvent !== 'completed') ||
830
+ opts.result !== undefined);
561
831
  let joinParams;
562
832
  if (!hasNonDefaults) {
563
833
  joinParams = name;
@@ -574,8 +844,8 @@ export class FunctionResult {
574
844
  p['end_on_exit'] = opts.endOnExit;
575
845
  if (opts.waitUrl)
576
846
  p['wait_url'] = opts.waitUrl;
577
- if (opts.maxParticipants && opts.maxParticipants !== 250)
578
- p['max_participants'] = opts.maxParticipants;
847
+ if (maxParticipants !== undefined)
848
+ p['max_participants'] = maxParticipants;
579
849
  if (opts.record && opts.record !== 'do-not-record')
580
850
  p['record'] = opts.record;
581
851
  if (opts.region)
@@ -617,7 +887,11 @@ export class FunctionResult {
617
887
  rpcParams['call_id'] = opts.callId;
618
888
  if (opts.nodeId)
619
889
  rpcParams['node_id'] = opts.nodeId;
620
- if (opts.params)
890
+ // Match Python's `if params:`: a falsy/EMPTY params dict is dropped, so an
891
+ // empty `{}` (e.g. from rpcAiUnhold) emits no `params` key at all. A plain
892
+ // `if (opts.params)` would wrongly keep `{}` because every object is truthy
893
+ // in JS; gate on key count to mirror the reference (function_result.py:1324).
894
+ if (opts.params && Object.keys(opts.params).length > 0)
621
895
  rpcParams['params'] = opts.params;
622
896
  return this.executeSwml({
623
897
  version: '1.0.0',
@@ -625,10 +899,10 @@ export class FunctionResult {
625
899
  });
626
900
  }
627
901
  /**
628
- * Dial a number via RPC, optionally specifying device type.
902
+ * Dial out with the `dial` RPC method, optionally specifying device type.
629
903
  * @param toNumber - The destination phone number.
630
904
  * @param fromNumber - The caller ID number.
631
- * @param destSwml - The SWML destination for the dialed call.
905
+ * @param destSwml - URL of the SWML that handles the dialed call.
632
906
  * @param deviceType - The device type (defaults to "phone").
633
907
  * @returns This instance for chaining.
634
908
  */
@@ -645,21 +919,47 @@ export class FunctionResult {
645
919
  });
646
920
  }
647
921
  /**
648
- * Send an AI message to another call via RPC.
922
+ * Send a message and/or global data to an AI agent on another call.
923
+ *
924
+ * Two payloads, either or both: `messageText` lands as a turn in the other
925
+ * agent's conversation, where it competes with everything else arriving at
926
+ * that moment; `globalData` is merged into the other call's global data,
927
+ * where it stays silent until a prompt expands it with
928
+ * `${global_data.your_key}`. That makes data the better channel for content a
929
+ * later step needs to say.
930
+ *
649
931
  * @param callId - The target call ID.
650
- * @param messageText - The message text to inject.
651
- * @param role - The message role (defaults to "system").
932
+ * @param messageText - Message to inject into the other conversation.
933
+ * @param role - The message role (defaults to "system"); sent with the message.
934
+ * @param globalData - Object merged into the target call's global data.
652
935
  * @returns This instance for chaining.
936
+ * @throws Error when neither `messageText` nor `globalData` is given.
653
937
  */
654
- rpcAiMessage(callId, messageText, role = 'system') {
655
- return this.executeRpc({
656
- method: 'ai_message',
657
- callId,
658
- params: { role, message_text: messageText },
659
- });
938
+ rpcAiMessage(callId, messageText, role = 'system', globalData) {
939
+ const params = {};
940
+ if (messageText !== undefined && messageText !== null) {
941
+ params['role'] = role;
942
+ params['message_text'] = messageText;
943
+ }
944
+ if (globalData !== undefined)
945
+ params['global_data'] = globalData;
946
+ if (Object.keys(params).length === 0) {
947
+ throw new Error('rpc_ai_message needs message_text, global_data, or both');
948
+ }
949
+ return this.executeRpc({ method: 'ai_message', callId, params });
660
950
  }
661
951
  /**
662
- * Unhold a call that was previously placed on hold via RPC.
952
+ * Merge data into another call's global data, with no conversation turn.
953
+ * The other call's prompt reads it back with `${global_data.key}`.
954
+ * @param callId - The target call ID.
955
+ * @param data - Object merged into that call's global data.
956
+ * @returns This instance for chaining.
957
+ */
958
+ rpcAiGlobalData(callId, data) {
959
+ return this.rpcAiMessage(callId, undefined, 'system', data);
960
+ }
961
+ /**
962
+ * Take another call off hold with the `ai_unhold` RPC method.
663
963
  * @param callId - The target call ID to unhold.
664
964
  * @returns This instance for chaining.
665
965
  */
@@ -672,8 +972,22 @@ export class FunctionResult {
672
972
  }
673
973
  // ── Payment ─────────────────────────────────────────────────────────
674
974
  /**
675
- * Initiate a payment collection flow on the call.
975
+ * Start a payment collection flow on the call. Emits an inline SWML document
976
+ * that sets `ai_response` and then runs the `pay` verb.
977
+ *
978
+ * `timeout`, `max_attempts`, `min_postal_code_length`, `security_code` and
979
+ * `postal_code` are sent as strings, as the platform reads them: its SWML
980
+ * validator requires strings for `security_code` and `postal_code`, and the
981
+ * pay request reads all five as strings. Each input is checked first:
982
+ * `timeout`, `maxAttempts` and `minPostalCodeLength` must be integers (or
983
+ * numeric strings), and `securityCode` a boolean (or `"true"`/`"false"`).
984
+ * A SWML variable reference such as `'${timeout}'` is passed through.
985
+ * `postalCode` is a boolean (whether to ask for it) or the postal code
986
+ * itself, as a string.
676
987
  * @param opts - Payment configuration including connector URL, method, and prompt options.
988
+ * @throws {Error} When `timeout`, `maxAttempts` or `minPostalCodeLength`
989
+ * isn't an integer, or `securityCode` isn't a boolean, or a SWML variable
990
+ * reference.
677
991
  * @returns This instance for chaining.
678
992
  */
679
993
  pay(opts) {
@@ -681,18 +995,22 @@ export class FunctionResult {
681
995
  payment_connector_url: opts.paymentConnectorUrl,
682
996
  input: opts.inputMethod ?? 'dtmf',
683
997
  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),
998
+ // Checked as integers and a boolean, sent as strings: the platform's
999
+ // validator requires strings for security_code and postal_code, and its
1000
+ // pay request reads all five as strings (mod_infrastructure
1001
+ // swml_schema.c, relay.c generate_pay_request).
1002
+ timeout: String(swmlInt('timeout', opts.timeout ?? 5)),
1003
+ max_attempts: String(swmlInt('max_attempts', opts.maxAttempts ?? 1)),
1004
+ security_code: String(swmlBool('security_code', opts.securityCode ?? true)),
1005
+ min_postal_code_length: String(swmlInt('min_postal_code_length', opts.minPostalCodeLength ?? 0)),
688
1006
  token_type: opts.tokenType ?? 'reusable',
689
1007
  currency: opts.currency ?? 'usd',
690
1008
  language: opts.language ?? 'en-US',
691
1009
  voice: opts.voice ?? 'woman',
692
1010
  valid_card_types: opts.validCardTypes ?? 'visa mastercard amex',
693
1011
  };
694
- const postalCode = opts.postalCode ?? true;
695
- payParams['postal_code'] = typeof postalCode === 'boolean' ? String(postalCode) : postalCode;
1012
+ // A boolean (whether to ask for it) or the postal code itself, as a string
1013
+ payParams['postal_code'] = String(opts.postalCode ?? true);
696
1014
  if (opts.statusUrl)
697
1015
  payParams['status_url'] = opts.statusUrl;
698
1016
  if (opts.chargeAmount)
@@ -708,10 +1026,7 @@ export class FunctionResult {
708
1026
  return this.executeSwml({
709
1027
  version: '1.0.0',
710
1028
  sections: {
711
- main: [
712
- { set: { ai_response: aiResponse } },
713
- { pay: payParams },
714
- ],
1029
+ main: [{ set: { ai_response: aiResponse } }, { pay: payParams }],
715
1030
  },
716
1031
  });
717
1032
  }
@@ -734,8 +1049,8 @@ export class FunctionResult {
734
1049
  }
735
1050
  /**
736
1051
  * 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.
1052
+ * @param actionType - The action type: "Say" or "Play".
1053
+ * @param phrase - The text to say, or for "Play" the audio file URL.
739
1054
  * @returns A new PaymentAction object.
740
1055
  */
741
1056
  static createPaymentAction(actionType, phrase) {
@@ -757,19 +1072,32 @@ export class FunctionResult {
757
1072
  */
758
1073
  toDict() {
759
1074
  const result = {};
760
- if (this.response) {
761
- result['response'] = this.response;
1075
+ // The structured form counts only when it has a field, as an empty dict
1076
+ // is falsy in the reference.
1077
+ if (this._toolResponse && Object.keys(this._toolResponse).length > 0) {
1078
+ result.response = { ...this._toolResponse };
1079
+ }
1080
+ else if (this.response) {
1081
+ result.response = this.response;
762
1082
  }
763
1083
  if (this.action.length > 0) {
764
- result['action'] = this.action;
1084
+ result.action = this.action;
765
1085
  }
766
1086
  if (this.postProcess && this.action.length > 0) {
767
- result['post_process'] = true;
1087
+ result.post_process = true;
768
1088
  }
769
1089
  if (Object.keys(result).length === 0) {
770
- result['response'] = 'Action completed.';
1090
+ result.response = 'Action completed.';
771
1091
  }
772
1092
  return result;
773
1093
  }
1094
+ /**
1095
+ * TS-native serialization hook. `JSON.stringify(result)` emits the wire
1096
+ * shape (delegates to {@link FunctionResult.toDict}) instead of the
1097
+ * internal field layout. No Python counterpart.
1098
+ */
1099
+ toJSON() {
1100
+ return this.toDict();
1101
+ }
774
1102
  }
775
1103
  //# sourceMappingURL=FunctionResult.js.map