@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
@@ -0,0 +1,221 @@
1
+ # Getting Started with RELAY
2
+
3
+ The RELAY client holds a WebSocket connection to SignalWire and gives you real-time control over phone calls and messages with `async`/`await`. This page installs the SDK, connects a client and places a first call.
4
+
5
+ <!-- snippet-setup -->
6
+ ```ts
7
+ export {}; // treat each example as a module so top-level `await` is allowed
8
+ // `await using` needs the disposable global types + Symbol members absent from
9
+ // the harness's ES2020 lib set. Declared here so the `await using` example compiles.
10
+ declare global {
11
+ interface SymbolConstructor {
12
+ readonly dispose: unique symbol;
13
+ readonly asyncDispose: unique symbol;
14
+ }
15
+ interface Disposable {
16
+ [Symbol.dispose](): void;
17
+ }
18
+ interface AsyncDisposable {
19
+ [Symbol.asyncDispose](): PromiseLike<void>;
20
+ }
21
+ }
22
+ ```
23
+
24
+ ## Installation
25
+
26
+ The RELAY client is part of the `@signalwire/sdk` package. Install it with npm:
27
+
28
+ ```bash
29
+ npm install @signalwire/sdk
30
+ ```
31
+
32
+ The package requires Node.js 22 or later. Its WebSocket dependency, `ws`, installs with it.
33
+
34
+ ## Configuration
35
+
36
+ The client needs a project ID, an API token and your space's hostname:
37
+
38
+ | Option | Env Var | Description |
39
+ |--------|---------|-------------|
40
+ | `project` | `SIGNALWIRE_PROJECT_ID` | Your SignalWire project ID |
41
+ | `token` | `SIGNALWIRE_API_TOKEN` | Your SignalWire API token |
42
+ | `host` | `SIGNALWIRE_SPACE` | Your space hostname (for example, `example.signalwire.com`) |
43
+
44
+ You can authenticate with a JWT in place of the project and token:
45
+
46
+ | Option | Env Var | Description |
47
+ |--------|---------|-------------|
48
+ | `jwtToken` | `SIGNALWIRE_JWT_TOKEN` | A SignalWire JWT |
49
+
50
+ The constructor throws when it has neither a JWT nor both a project and a token. It also throws when `host` isn't a bare hostname, for example when you pass a URL.
51
+
52
+ ## Minimal Example
53
+
54
+ This program connects with explicit credentials and answers every call on the `default` context:
55
+
56
+ <!-- snippet: no-run client.run() opens a live WebSocket to SIGNALWIRE_SPACE and runs until SIGINT/SIGTERM; it can't reach the loopback mock standalone -->
57
+ ```typescript
58
+ import { RelayClient } from '@signalwire/sdk';
59
+
60
+ const client = new RelayClient({
61
+ project: 'your-project-id',
62
+ token: 'your-api-token',
63
+ host: 'example.signalwire.com',
64
+ contexts: ['default'],
65
+ });
66
+
67
+ client.onCall(async (call) => {
68
+ await call.answer();
69
+ const action = await call.play([{ type: 'tts', params: { text: 'Hello!' } }]);
70
+ await action.wait();
71
+ await call.hangup();
72
+ });
73
+
74
+ // Connect, then reconnect after any dropped connection until SIGINT/SIGTERM
75
+ await client.run();
76
+ ```
77
+
78
+ You can set the credentials as environment variables instead:
79
+
80
+ ```bash
81
+ export SIGNALWIRE_PROJECT_ID=your-project-id
82
+ export SIGNALWIRE_API_TOKEN=your-api-token
83
+ export SIGNALWIRE_SPACE=example.signalwire.com
84
+ ```
85
+
86
+ With those set, the constructor needs only the contexts:
87
+
88
+ <!-- snippet: no-run client.run() opens a live WebSocket to SIGNALWIRE_SPACE and runs until SIGINT/SIGTERM; it can't reach the loopback mock standalone -->
89
+ ```typescript
90
+ import { RelayClient } from '@signalwire/sdk';
91
+
92
+ const client = new RelayClient({ contexts: ['default'] });
93
+
94
+ client.onCall(async (call) => {
95
+ await call.answer();
96
+ await call.hangup();
97
+ });
98
+
99
+ await client.run();
100
+ ```
101
+
102
+ ## Contexts
103
+
104
+ Contexts are the topics your client subscribes to for inbound calls and messages. When a call arrives on a subscribed context, the client calls your `onCall` handler with a `Call` object.
105
+
106
+ Set contexts in the constructor, or change them on a connected client:
107
+
108
+ <!-- snippet: no-run client.receive() opens a live WebSocket to SIGNALWIRE_SPACE; it can't reach the loopback mock standalone -->
109
+ ```typescript
110
+ import { RelayClient } from '@signalwire/sdk';
111
+
112
+ // Subscribe when the client connects
113
+ const client = new RelayClient({ contexts: ['sales', 'support'] });
114
+ await client.connect();
115
+
116
+ // Change the subscription later
117
+ await client.receive(['billing']);
118
+ await client.unreceive(['sales']);
119
+ ```
120
+
121
+ ## Making Outbound Calls
122
+
123
+ Use `client.dial()` to place an outbound call. It resolves with a `Call` once a device answers:
124
+
125
+ <!-- snippet: no-run client.dial() opens a live WebSocket to SIGNALWIRE_SPACE; it can't reach the loopback mock standalone -->
126
+ ```typescript
127
+ import { RelayClient } from '@signalwire/sdk';
128
+ const client = new RelayClient({ contexts: ['default'] });
129
+ await client.connect();
130
+
131
+ const call = await client.dial([
132
+ [{ type: 'phone', to: '+15551234567', from: '+15559876543' }],
133
+ ]);
134
+ // call is now a live Call object
135
+ const action = await call.play([{ type: 'tts', params: { text: 'This is an outbound call.' } }]);
136
+ await action.wait();
137
+ await call.hangup();
138
+ ```
139
+
140
+ The SDK sends a phone device's `to` and `from` as the wire fields `to_number` and `from_number`. You can also pass the wire shape, `{ type: 'phone', params: { to_number, from_number } }`.
141
+
142
+ The outer array holds serial attempts, and each inner array holds devices dialed in parallel. This call rings two numbers at the same time:
143
+
144
+ <!-- snippet: no-run client.dial() opens a live WebSocket to SIGNALWIRE_SPACE; it can't reach the loopback mock standalone -->
145
+ ```typescript
146
+ import { RelayClient } from '@signalwire/sdk';
147
+ const client = new RelayClient({ contexts: ['default'] });
148
+ await client.connect();
149
+ const call = await client.dial([
150
+ [
151
+ { type: 'phone', to: '+15551111111', from: '+15559876543' },
152
+ { type: 'phone', to: '+15552222222', from: '+15559876543' },
153
+ ],
154
+ ]);
155
+ ```
156
+
157
+ `dial()` takes an options object as its second argument: `tag`, `maxDuration` (minutes) and `dialTimeout` (seconds, default 120). This call gives up after 30 seconds:
158
+
159
+ <!-- snippet: no-run client.dial() opens a live WebSocket to SIGNALWIRE_SPACE; it can't reach the loopback mock standalone -->
160
+ ```typescript
161
+ import { RelayClient } from '@signalwire/sdk';
162
+ const client = new RelayClient({ contexts: ['default'] });
163
+ await client.connect();
164
+ const call = await client.dial(
165
+ [[{ type: 'phone', to: '+15551234567', from: '+15559876543' }]],
166
+ { dialTimeout: 30 },
167
+ );
168
+ ```
169
+
170
+ `dial()` rejects with a `RelayError` when the dial fails, when `dialTimeout` passes first, or when the connection closes.
171
+
172
+ ## Debug Logging
173
+
174
+ Set the log level to `debug` to log the WebSocket traffic:
175
+
176
+ ```bash
177
+ export SIGNALWIRE_LOG_LEVEL=debug
178
+ ```
179
+
180
+ The debug log masks the project, token, JWT and authorization-state values.
181
+
182
+ ## Cleanup with `await using`
183
+
184
+ `RelayClient` implements `Symbol.asyncDispose`, so `await using` disconnects it when the scope exits:
185
+
186
+ <!-- snippet: no-run client.connect()/dial() opens a live WebSocket to SIGNALWIRE_SPACE; it can't reach the loopback mock standalone -->
187
+ ```typescript
188
+ import { RelayClient } from '@signalwire/sdk';
189
+ await using client = new RelayClient({ contexts: ['default'] });
190
+ await client.connect();
191
+ const call = await client.dial([
192
+ [{ type: 'phone', to: '+15551234567', from: '+15559876543' }],
193
+ ]);
194
+ await call.hangup();
195
+ // client.disconnect() runs automatically at end of scope
196
+ ```
197
+
198
+ If your toolchain doesn't support `await using`, call `disconnect()` in a `finally` block:
199
+
200
+ <!-- snippet: no-run client.connect() opens a live WebSocket to SIGNALWIRE_SPACE; it can't reach the loopback mock standalone -->
201
+ ```typescript
202
+ import { RelayClient } from '@signalwire/sdk';
203
+ const client = new RelayClient({ contexts: ['default'] });
204
+ try {
205
+ await client.connect();
206
+ // ... use client
207
+ } finally {
208
+ await client.disconnect();
209
+ }
210
+ ```
211
+
212
+ A client started with `connect()` doesn't reconnect by itself. Use `run()` for a long-running process that should survive dropped connections.
213
+
214
+ ## Next Steps
215
+
216
+ Continue with these pages:
217
+
218
+ - [Call Methods Reference](call-methods.md): the methods on a `Call` object
219
+ - [Events](events.md): handling real-time call events
220
+ - [Client Reference](client-reference.md): `RelayClient` options and methods
221
+ - [Messaging](messaging.md): sending and receiving SMS/MMS
@@ -0,0 +1,386 @@
1
+ # RELAY Client Guide
2
+
3
+ The RELAY client controls live calls and messages over a persistent WebSocket connection to SignalWire. An agent built on `AgentBase` answers HTTP requests from the platform. A RELAY client holds the connection open instead: it receives events as they happen and sends commands for a call in progress. This guide shows the common tasks and links to the reference pages for the details.
4
+
5
+ <!-- snippet-setup -->
6
+ ```ts
7
+ export {}; // treat each example as a module so top-level `await` is allowed
8
+ // Shared context the fragments on this page assume.
9
+ declare const client: import('@signalwire/sdk').RelayClient;
10
+ declare const call: import('@signalwire/sdk').Call;
11
+ ```
12
+
13
+ ## Authentication
14
+
15
+ Pass the project ID, API token and space hostname to the constructor, along with the contexts to subscribe to:
16
+
17
+ ```typescript
18
+ import { RelayClient } from '@signalwire/sdk';
19
+
20
+ function makeClient() {
21
+ return new RelayClient({
22
+ project: 'your-project-id', // or env: SIGNALWIRE_PROJECT_ID
23
+ token: 'your-api-token', // or env: SIGNALWIRE_API_TOKEN
24
+ host: 'your-space.signalwire.com', // or env: SIGNALWIRE_SPACE
25
+ contexts: ['office', 'support'],
26
+ });
27
+ }
28
+ ```
29
+
30
+ Each credential falls back to an environment variable when you omit it:
31
+
32
+ - `SIGNALWIRE_PROJECT_ID`: your SignalWire project ID
33
+ - `SIGNALWIRE_API_TOKEN`: your SignalWire API token, or `SIGNALWIRE_JWT_TOKEN` for JWT authentication
34
+ - `SIGNALWIRE_SPACE`: your space hostname
35
+
36
+ ## Handling Inbound Calls
37
+
38
+ Register a handler with `onCall()`, then start the client with `run()`:
39
+
40
+ <!-- snippet: no-run client.run() opens a live WebSocket to SIGNALWIRE_SPACE and runs until SIGINT/SIGTERM; it can't reach the loopback mock standalone -->
41
+ ```typescript
42
+ client.onCall(async (call) => {
43
+ console.log(`Inbound call: ${call.callId}`);
44
+
45
+ await call.answer();
46
+
47
+ const action = await call.play([
48
+ { type: 'tts', params: { text: 'Thanks for calling.' } },
49
+ ]);
50
+ await action.wait();
51
+
52
+ await call.hangup();
53
+ });
54
+
55
+ // Connect, and reconnect after dropped connections, until SIGINT/SIGTERM
56
+ await client.run();
57
+ ```
58
+
59
+ ## Making Outbound Calls
60
+
61
+ Connect the client, then call `dial()` with a nested array of devices. It resolves with a `Call` once a device answers:
62
+
63
+ ```typescript
64
+ async function placeCall() {
65
+ await client.connect();
66
+
67
+ const call = await client.dial(
68
+ [[{ type: 'phone', to: '+15551234567', from: '+15559876543' }]],
69
+ { dialTimeout: 30 }, // seconds
70
+ );
71
+
72
+ console.log(`Call answered: ${call.callId}`);
73
+ const action = await call.play([{ type: 'tts', params: { text: 'Hello from RELAY.' } }]);
74
+ await action.wait();
75
+ await call.hangup();
76
+ }
77
+ ```
78
+
79
+ ### How dial() Finds the Call
80
+
81
+ `dial()` doesn't read a call ID from the `calling.dial` response. It tags the request, then waits for a `calling.call.dial` event with that tag and a `dial_state` of `answered`. At that point it resolves with a `Call` built from the event. A `failed` dial state, the `dialTimeout` passing, or a closed connection rejects it with a `RelayError`.
82
+
83
+ ## Call Methods
84
+
85
+ The [Call Methods Reference](call-methods.md) documents every method. This section shows the common ones.
86
+
87
+ ### Lifecycle
88
+
89
+ A call has these lifecycle methods:
90
+
91
+ - `call.answer()`: answer an inbound call
92
+ - `call.hangup(reason?)`: end the call
93
+ - `call.pass()`: decline control and return the call to routing
94
+
95
+ ### Audio Playback
96
+
97
+ `play()` takes a list of media items and returns a `PlayAction` you can control or wait on:
98
+
99
+ ```typescript
100
+ const action = await call.play([
101
+ { type: 'tts', params: { text: 'Hello world', language: 'en-US' } },
102
+ { type: 'audio', params: { url: 'https://example.com/greeting.mp3' } },
103
+ { type: 'silence', params: { duration: 2 } },
104
+ ]);
105
+
106
+ // Control playback
107
+ await action.pause();
108
+ await action.resume();
109
+ await action.volume(-3);
110
+
111
+ // Wait for playback to finish
112
+ const event = await action.wait();
113
+ ```
114
+
115
+ The SDK also accepts a flat form, `{ type: 'tts', text: 'Hello world' }`, and nests the fields under `params` for you.
116
+
117
+ ### Recording
118
+
119
+ `record()` returns a `RecordAction`. After it completes, `RecordEvent.url` holds the recording URL:
120
+
121
+ ```typescript
122
+ import { RecordEvent } from '@signalwire/sdk';
123
+
124
+ const action = await call.record({ format: 'mp3' });
125
+ // ... later
126
+ await action.stop();
127
+ const event = await action.wait();
128
+ if (event instanceof RecordEvent) {
129
+ console.log(`Recording URL: ${event.url}`);
130
+ }
131
+ ```
132
+
133
+ ### Input Collection
134
+
135
+ `playAndCollect()` plays a prompt and collects input; `collect()` collects without a prompt:
136
+
137
+ ```typescript
138
+ // Play and collect (combined)
139
+ const action = await call.playAndCollect(
140
+ [{ type: 'tts', params: { text: 'Enter your PIN.' } }],
141
+ { digits: { max: 4, terminators: '#' } },
142
+ );
143
+ const event = await action.wait();
144
+
145
+ // Standalone collect (no media)
146
+ const collectAction = await call.collect({
147
+ speech: { end_silence_timeout: 2 },
148
+ });
149
+ ```
150
+
151
+ ### Detection
152
+
153
+ `detect()` returns a `DetectAction`, which resolves on the first detection result:
154
+
155
+ ```typescript
156
+ const action = await call.detect(
157
+ { type: 'machine', params: { initial_timeout: 5 } },
158
+ { timeout: 10 },
159
+ );
160
+ const event = await action.wait();
161
+ // DetectAction resolves on the first event with a detect result, or on finished/error
162
+ ```
163
+
164
+ `detectAnsweringMachine()`, `detectDigit()` and `detectFax()` build the `detect` object for you.
165
+
166
+ ### Connectivity
167
+
168
+ A call has these methods for bridging and transfers:
169
+
170
+ - `call.connect(devices, options?)`: bridge to another endpoint
171
+ - `call.disconnect()`: unbridge a connected call
172
+ - `call.transfer(dest, extra?)`: transfer control to another RELAY app or SWML script
173
+ - `call.refer(device, options?)`: transfer a SIP call with SIP REFER
174
+
175
+ ### Other Methods
176
+
177
+ A call also has these methods:
178
+
179
+ - `call.sendDigits(digits)`: send DTMF
180
+ - `call.hold()` / `call.unhold()`: put the call on hold, or take it off hold
181
+ - `call.denoise()` / `call.denoiseStop()`: start or stop noise reduction
182
+ - `call.joinConference(name, options?)` / `call.leaveConference(conferenceId)`: join or leave a conference
183
+ - `call.joinRoom(name, options?)` / `call.leaveRoom()`: join or leave a room
184
+ - `call.stream(url, options?)`: stream audio to a WebSocket
185
+ - `call.tap(tap, device, options?)`: copy media to an RTP or WebSocket endpoint
186
+ - `call.transcribe(options?)`: start transcription
187
+ - `call.liveTranscribe(action)` / `call.liveTranslate(action, options?)`: start or stop live transcription or translation
188
+ - `call.pay(paymentConnectorUrl, options?)`: collect a payment
189
+ - `call.sendFax(document, options?)` / `call.receiveFax(options?)`: send or receive a fax
190
+ - `call.ai(options?)`: start an AI agent session
191
+ - `call.queueEnter(queueName)` / `call.queueLeave(queueName)`: enter or leave a queue
192
+ - `call.bindDigit(digits, bindMethod, options?)` / `call.clearDigitBindings(realm?)`: bind DTMF sequences to RELAY methods
193
+ - `call.echo(options?)`: echo audio back, for testing
194
+
195
+ ## Actions
196
+
197
+ Methods for long-running operations return an `Action` that tracks the operation's lifecycle:
198
+
199
+ ```typescript
200
+ const action = await call.play([{ type: 'tts', params: { text: 'Hello' } }]);
201
+
202
+ // Check status
203
+ console.log(action.completed); // false until the terminal event arrives
204
+
205
+ // Wait for completion, with a timeout in seconds
206
+ const event = await action.wait(10);
207
+
208
+ // Or continue without waiting, and handle completion in a callback
209
+ await call.play(
210
+ [{ type: 'tts', params: { text: 'Background music' } }],
211
+ {
212
+ onCompleted: (event) => console.log('Playback finished'),
213
+ },
214
+ );
215
+ ```
216
+
217
+ `action.wait()` takes its timeout in seconds, while `call.waitFor()` and the `call.waitFor*()` helpers take milliseconds.
218
+
219
+ ### Action Types
220
+
221
+ Each action class has these methods, and completes on these states:
222
+
223
+ | Action | Methods | Terminal States |
224
+ |--------|---------|----------------|
225
+ | `PlayAction` | stop, pause, resume, volume | finished, error |
226
+ | `RecordAction` | stop, pause, resume | finished, no_input |
227
+ | `DetectAction` | stop | finished, error, or the first detect result |
228
+ | `CollectAction` | stop, pause, resume, volume, startInputTimers | finished, error, no_input, no_match, or a result |
229
+ | `StandaloneCollectAction` | stop, startInputTimers | finished, error, no_input, no_match, or a result |
230
+ | `FaxAction` | stop | finished, error |
231
+ | `TapAction` | stop | finished |
232
+ | `StreamAction` | stop | finished |
233
+ | `PayAction` | stop | finished, error |
234
+ | `TranscribeAction` | stop | finished |
235
+ | `AIAction` | stop | finished, error |
236
+
237
+ ## Event Listening
238
+
239
+ Listen on a call with `call.on()`, or wait for one event with `call.waitFor()`:
240
+
241
+ ```typescript
242
+ // Listen for specific events on a call
243
+ call.on('calling.call.play', (event) => {
244
+ console.log(`Play state: ${event.params.state}`);
245
+ });
246
+
247
+ // Wait for a specific event (timeout in milliseconds)
248
+ const event = await call.waitFor('calling.call.state',
249
+ (e) => e.params.call_state === 'answered',
250
+ 10_000,
251
+ );
252
+
253
+ // Wait for the call to end (timeout in milliseconds)
254
+ const endEvent = await call.waitForEnded(60_000);
255
+ ```
256
+
257
+ ## Messaging
258
+
259
+ `sendMessage()` sends an SMS or MMS, and `onMessage()` receives them:
260
+
261
+ ```typescript
262
+ // Send SMS
263
+ const message = await client.sendMessage({
264
+ toNumber: '+15551234567',
265
+ fromNumber: '+15559876543',
266
+ body: 'Hello from RELAY.',
267
+ });
268
+
269
+ // Track delivery (timeout in seconds)
270
+ const event = await message.wait(30);
271
+ console.log(`State: ${message.state}`); // delivered, undelivered or failed
272
+
273
+ // Receive inbound messages
274
+ client.onMessage(async (message) => {
275
+ console.log(`From ${message.fromNumber}: ${message.body}`);
276
+ });
277
+ ```
278
+
279
+ For more information, see [Messaging](messaging.md).
280
+
281
+ ## Reconnection
282
+
283
+ `run()` reconnects after a dropped connection, with exponential backoff:
284
+
285
+ <!-- snippet: no-run client.run() opens a live WebSocket to SIGNALWIRE_SPACE and runs until SIGINT/SIGTERM; it can't reach the loopback mock standalone -->
286
+ ```typescript
287
+ await client.run(); // resolves after SIGINT/SIGTERM shuts the client down
288
+ ```
289
+
290
+ Reconnection works like this:
291
+
292
+ - The first delay is 1 second.
293
+ - The delay doubles after each attempt, up to 30 seconds.
294
+ - On each reconnect, the client sends back the protocol string and authorization state it stored from the server.
295
+ - Requests made while the client is disconnected wait in a queue and go out after it authenticates again. Requests already sent when the connection dropped are rejected.
296
+ - `SIGINT` or `SIGTERM` shuts the client down cleanly.
297
+
298
+ A client started with `connect()` doesn't reconnect by itself. Use `connect()` and `disconnect()` when your own code manages the connection:
299
+
300
+ ```typescript
301
+ await client.connect();
302
+ // ... use client
303
+ await client.disconnect();
304
+ ```
305
+
306
+ ## Dynamic Context Subscription
307
+
308
+ Change the contexts a connected client subscribes to with `receive()` and `unreceive()`:
309
+
310
+ ```typescript
311
+ await client.connect();
312
+
313
+ // Subscribe to new contexts at runtime
314
+ await client.receive(['sales', 'support']);
315
+
316
+ // Unsubscribe
317
+ await client.unreceive(['sales']);
318
+ ```
319
+
320
+ ## Error Handling
321
+
322
+ Catch `RelayError` for failed commands. Its `serverMessage` holds the server's text, and `message` already includes the code:
323
+
324
+ ```typescript
325
+ import { RelayError } from '@signalwire/sdk';
326
+
327
+ try {
328
+ await call.answer();
329
+ } catch (err) {
330
+ if (err instanceof RelayError) {
331
+ console.error(`RELAY error ${err.code}: ${err.serverMessage}`);
332
+ }
333
+ }
334
+ ```
335
+
336
+ ### Call-Gone Handling
337
+
338
+ When the platform answers 404 or 410, the call no longer exists. `Call` methods then resolve with `{}` in place of throwing, and an action method returns an action that has already completed, so `await action.wait()` doesn't hang:
339
+
340
+ ```typescript
341
+ const action = await call.play([{ type: 'tts', params: { text: 'hello' } }]);
342
+ // If the call ended before the platform handled the request, action.completed is true
343
+ ```
344
+
345
+ When `call.state` is already `ended`, action methods skip the request and return a completed action.
346
+
347
+ ## Typed Events
348
+
349
+ Events that reach `call.on()` listeners are instances of typed classes, which you can check with `instanceof`:
350
+
351
+ ```typescript
352
+ import { CallStateEvent } from '@signalwire/sdk';
353
+
354
+ call.on('calling.call.state', (event) => {
355
+ if (event instanceof CallStateEvent) {
356
+ console.log(event.callState); // 'answered', 'ended', etc.
357
+ console.log(event.endReason); // 'hangup', 'busy', etc.
358
+ }
359
+ });
360
+ ```
361
+
362
+ [Events](events.md) lists the typed event classes and their properties.
363
+
364
+ ## Environment Variables
365
+
366
+ The client reads these variables:
367
+
368
+ | Variable | Purpose |
369
+ |----------|---------|
370
+ | `SIGNALWIRE_PROJECT_ID` | Project ID for authentication |
371
+ | `SIGNALWIRE_API_TOKEN` | API token for authentication |
372
+ | `SIGNALWIRE_JWT_TOKEN` | JWT (alternative to project and token) |
373
+ | `SIGNALWIRE_SPACE` | Space hostname (default: `relay.signalwire.com`) |
374
+ | `RELAY_MAX_ACTIVE_CALLS` | Maximum calls one client tracks (default 1000) |
375
+ | `RELAY_MAX_CONNECTIONS` | Maximum connected clients per process (default 1) |
376
+ | `SIGNALWIRE_RELAY_CA_FILE` | CA bundle for the WebSocket connection's TLS |
377
+ | `SIGNALWIRE_LOG_LEVEL` | Log level: `debug`, `info`, `warn`, `error` |
378
+ | `SIGNALWIRE_LOG_MODE` | Set to `off` to turn off logging |
379
+
380
+ ## Examples
381
+
382
+ The `relay/examples/` directory has these programs:
383
+
384
+ - [relay-inbound.ts](../examples/relay-inbound.ts): answer calls, play TTS, collect digits
385
+ - [relay-outbound.ts](../examples/relay-outbound.ts): dial out, detect an answering machine, play a message
386
+ - [relay-messaging.ts](../examples/relay-messaging.ts): send and receive SMS