@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
@@ -0,0 +1,573 @@
1
+ # SignalWire SWML Service Guide
2
+
3
+ `SWMLService` builds a SWML document from verbs and serves it over HTTP. This guide covers building documents, serving them, authentication, dynamic documents and routing callbacks.
4
+
5
+ <!-- snippet-setup -->
6
+ ```ts
7
+ export {}; // treat each example as a module (top-level await)
8
+ declare global {
9
+ const SWMLService: typeof import('@signalwire/sdk').SWMLService;
10
+ const SwmlBuilder: typeof import('@signalwire/sdk').SwmlBuilder;
11
+ const service: import('@signalwire/sdk').SWMLService;
12
+ }
13
+ ```
14
+
15
+ ## Table of Contents
16
+ - [Introduction](#introduction)
17
+ - [Installation](#installation)
18
+ - [Basic Usage](#basic-usage)
19
+ - [Logging](#logging)
20
+ - [SWML Document Creation](#swml-document-creation)
21
+ - [Verb Handling](#verb-handling)
22
+ - [Web Service Features](#web-service-features)
23
+ - [Custom Routing Callbacks](#custom-routing-callbacks)
24
+ - [Advanced Usage](#advanced-usage)
25
+ - [API Reference](#api-reference)
26
+ - [Examples](#examples)
27
+
28
+ ## Introduction
29
+
30
+ `SWMLService` creates and serves SignalWire Markup Language (SWML) documents, the JSON call-flow instructions SignalWire runs on a call. `AgentBase` extends it, so an agent has the same document, serving and routing methods, plus the AI verb and its tools. `SWMLService` handles these tasks:
31
+
32
+ - SWML document creation and manipulation
33
+ - Schema validation of each verb
34
+ - HTTP serving (built on [Hono](https://hono.dev/))
35
+ - Basic authentication
36
+ - Structured logging
37
+
38
+ Use `SWMLService` for a call flow that doesn't need AI: call routing, IVR-style menus, recording, or playback. For an AI voice agent, use [`AgentBase`](agent-guide.md) instead.
39
+
40
+ ## Installation
41
+
42
+ The `SWMLService` class is part of the SignalWire SDK package:
43
+
44
+ ```bash
45
+ npm install @signalwire/sdk
46
+ ```
47
+
48
+ The package requires Node.js 22 or later.
49
+
50
+ ## Basic Usage
51
+
52
+ This service subclasses `SWMLService` and builds a static document in its constructor:
53
+
54
+ <!-- snippet: no-run starts a blocking HTTP server via service.serve() -->
55
+ ```typescript
56
+ import { SWMLService } from '@signalwire/sdk';
57
+
58
+ class SimpleVoiceService extends SWMLService {
59
+ constructor() {
60
+ super({ name: 'voice-service', route: '/voice', port: 3000 });
61
+ this.buildDocument();
62
+ }
63
+
64
+ buildDocument(): void {
65
+ // Reset the document to start fresh
66
+ this.resetDocument();
67
+
68
+ // Add verbs to the main section
69
+ this.addVerb('answer', {});
70
+ this.addVerb('play', { url: 'say:Hello, thank you for calling our service.' });
71
+ this.addVerb('hangup', {});
72
+ }
73
+ }
74
+
75
+ // Create and start the service
76
+ const service = new SimpleVoiceService();
77
+ await service.serve();
78
+ ```
79
+
80
+ The service answers `GET` and `POST` on `/voice` with the document. SignalWire requests a document with a `POST`; a `GET` works too, which is handy for testing with a browser or `curl`.
81
+
82
+ You can also build the document with the `SwmlBuilder` that `getBuilder()` returns. It has a method for each verb in the SWML schema, and each returns the builder:
83
+
84
+ <!-- snippet: no-run starts a blocking HTTP server via service.serve() -->
85
+ ```typescript
86
+ const service = new SWMLService({ name: 'greeter', route: '/', port: 3000 });
87
+ service
88
+ .getBuilder()
89
+ .answer()
90
+ .play({ url: 'https://cdn.example.com/welcome.mp3' })
91
+ .hangup();
92
+
93
+ await service.serve();
94
+ ```
95
+
96
+ ## Logging
97
+
98
+ Every `SWMLService` instance has a logger on its public `log` property. The SDK's `Logger` module configures logging for the whole process.
99
+
100
+ ### Using the Logger
101
+
102
+ A subclass method logs through `this.log`, with optional data:
103
+
104
+ <!-- snippet: no-compile fragment from inside an SWMLService subclass method; uses `this.log` / `document` -->
105
+ ```typescript
106
+ // Basic logging
107
+ this.log.info('service_started');
108
+
109
+ // Logging with context
110
+ this.log.debug('document_created', { size: document.length });
111
+
112
+ // Error logging
113
+ try {
114
+ // Some operation
115
+ } catch (e) {
116
+ this.log.error('operation_failed', { error: String(e) });
117
+ }
118
+ ```
119
+
120
+ ### Log Levels
121
+
122
+ The logger has four levels, in increasing order of severity:
123
+ - `debug`: Detailed information for debugging
124
+ - `info`: General information about operation
125
+ - `warn`: Warning about potential issues
126
+ - `error`: Error information when operations fail
127
+
128
+ ### Controlling Log Output
129
+
130
+ Environment variables set the level and mode when the process starts:
131
+
132
+ ```bash
133
+ export SIGNALWIRE_LOG_LEVEL=warn # debug | info | warn | error
134
+ export SIGNALWIRE_LOG_MODE=off # off | stderr | auto
135
+ ```
136
+
137
+ The `Logger` functions change them at runtime:
138
+
139
+ ```typescript
140
+ import { setGlobalLogLevel, suppressAllLogs } from '@signalwire/sdk';
141
+
142
+ setGlobalLogLevel('warn'); // Only show warnings and errors
143
+ suppressAllLogs(true); // Suppress everything
144
+ ```
145
+
146
+ For the log format, colors and the other settings, see [Logging](configuration.md#logging) in the configuration guide.
147
+
148
+ ## SWML Document Creation
149
+
150
+ `SWMLService` has methods to create and change its SWML document.
151
+
152
+ ### Document Structure
153
+
154
+ A SWML document has a `version` and named `sections`. The call starts at `main`:
155
+
156
+ ```json
157
+ {
158
+ "version": "1.0.0",
159
+ "sections": {
160
+ "main": [
161
+ { "verb1": { } },
162
+ { "verb2": { } }
163
+ ],
164
+ "section1": [
165
+ { "verb3": { } }
166
+ ]
167
+ }
168
+ }
169
+ ```
170
+
171
+ A `transfer` or `execute` verb with a section name as its `dest` moves the call to that section. The SWML schema bundled with the SDK (`src/schema.json`) describes both verbs.
172
+
173
+ ### Document Methods
174
+
175
+ These methods build and read the document:
176
+
177
+ - `resetDocument()`: Reset the document to an empty `main` section
178
+ - `addVerb(verbName, config)`: Add a verb to the main section
179
+ - `addSection(sectionName)`: Add an empty section, if it doesn't exist
180
+ - `addVerbToSection(sectionName, verbName, config)`: Add a verb to a section, creating the section if needed
181
+ - `getDocument()`: Get the current document as an object
182
+ - `renderDocument()`: Get the current document as a JSON string
183
+ - `getBuilder()`: Get the underlying `SwmlBuilder`, which has a method for each verb
184
+
185
+ ## Verb Handling
186
+
187
+ `SWMLService` validates each verb against the SWML schema bundled with the SDK.
188
+
189
+ ### Verb Validation
190
+
191
+ `addVerb()` and `addVerbToSection()` check the verb name and its configuration against the schema. An unknown verb, an unknown property or a wrong type throws a `SchemaValidationError`:
192
+
193
+ <!-- snippet: no-compile fragment from inside an SWMLService subclass method; uses `this.addVerb` -->
194
+ ```typescript
195
+ // Valid: play takes a url and a volume
196
+ this.addVerb('play', { url: 'say:Hello, world!', volume: 5 });
197
+
198
+ // Throws: play has no invalid_param property
199
+ this.addVerb('play', { invalid_param: 'value' });
200
+ ```
201
+
202
+ The second call throws with this message:
203
+
204
+ ```text
205
+ Schema validation failed for 'play': Schema validation error for 'play': /play unknown property 'invalid_param'
206
+ ```
207
+
208
+ Set `SWML_SKIP_SCHEMA_VALIDATION=true`, or pass `schemaValidation: false`, to turn validation off. `schemaPath` validates verbs against another schema file.
209
+
210
+ ### Custom Verb Handlers
211
+
212
+ `registerVerbHandler()` stores an object that implements the `SWMLVerbHandler` interface in the service's `verbRegistry`, keyed by verb name:
213
+
214
+ <!-- snippet: no-run illustrative fragment: references the assumed `service` object established earlier on the page -->
215
+ ```typescript
216
+ import type { SWMLVerbHandler } from '@signalwire/sdk';
217
+
218
+ const customPlayHandler: SWMLVerbHandler = {
219
+ getVerbName: () => 'play',
220
+ validateConfig: (config) => [true, []], // [isValid, errorMessages]
221
+ buildConfig: (kwargs) => kwargs,
222
+ };
223
+
224
+ service.registerVerbHandler(customPlayHandler);
225
+ const handler = service.verbRegistry.getHandler('play');
226
+ ```
227
+
228
+ `addVerb()` doesn't consult the registry, so a registered handler doesn't change how verbs are validated or added. Call the handler's methods from your own code.
229
+
230
+ ## Web Service Features
231
+
232
+ `SWMLService` serves its document over HTTP with a [Hono](https://hono.dev/) app.
233
+
234
+ ### Endpoints
235
+
236
+ A service answers these requests, where `{route}` is the `route` option (default `/`):
237
+
238
+ - `GET {route}` and `POST {route}`: Return the SWML document
239
+ - `GET {route}/swaig`: Return the SWML document
240
+ - `POST {route}/swaig`: Run a SWAIG function registered with `defineTool()`
241
+ - `GET /health` and `GET /ready`: Return `{"status":"ok"}` and `{"status":"ready"}`
242
+ - Each routing-callback path, at the server root: see [Custom Routing Callbacks](#custom-routing-callbacks)
243
+
244
+ With the default route `/`, the SWAIG path is `/swaig`. A trailing slash is a different path: `GET /voice/` gets `404` when the route is `/voice`. `serve()` binds to the `host` and `port` options (defaults `0.0.0.0` and `PORT` or `3000`).
245
+
246
+ Every response carries `X-Content-Type-Options`, `X-Frame-Options`, `X-XSS-Protection`, `Referrer-Policy`, `Content-Security-Policy` and `Permissions-Policy` headers. CORS allows the origins in `SWML_CORS_ORIGINS`, or any origin when it's unset.
247
+
248
+ ### SWAIG Functions
249
+
250
+ A `SWMLService` can register tools with `defineTool()` and run them on `POST {route}/swaig`. The request body names the function in `function`, and its arguments in `argument.parsed[0]` or `arguments`:
251
+
252
+ <!-- snippet: no-run illustrative fragment: references the assumed `service` object established earlier on the page -->
253
+ ```typescript
254
+ import { FunctionResult } from '@signalwire/sdk';
255
+
256
+ // Your own asynchronous lookup, such as a database query
257
+ async function lookUpHours(day: string): Promise<string> {
258
+ return day.toLowerCase() === 'sunday' ? 'from noon to 5 PM' : 'from 9 AM to 5 PM';
259
+ }
260
+
261
+ service.defineTool({
262
+ name: 'get_hours',
263
+ description: 'Get the office hours for a day of the week.',
264
+ parameters: { day: { type: 'string', description: 'Day of the week' } },
265
+ handler: async (args) => {
266
+ const hours = await lookUpHours(String(args.day));
267
+ return new FunctionResult(`The office is open ${hours} on ${args.day}.`);
268
+ },
269
+ });
270
+ ```
271
+
272
+ The route awaits the handler, so an `async` handler's result is sent once it resolves. A `FunctionResult` is sent as its `toDict()` form, a string is wrapped in a `FunctionResult`, and an object is sent as it is. The `response` text is context for the model on the call, not speech: the model decides what to say.
273
+
274
+ These requests don't run a handler:
275
+
276
+ - A body that isn't JSON gets `400` `{"error":"Invalid JSON"}`.
277
+ - A missing function name gets `400`, and a name that isn't a valid identifier gets `400`.
278
+ - A function the service doesn't have gets `404` `{"error":"Unknown function: <name>"}`.
279
+
280
+ `SWMLService` doesn't check per-call tokens. A tool's `secure` setting takes effect on `AgentBase`, which renders the tokens into its SWML and checks them on `/swaig`. On a plain `SWMLService`, basic auth is the only protection for `/swaig`.
281
+
282
+ ### Authentication
283
+
284
+ `SWMLService` resolves basic-auth credentials in this order:
285
+
286
+ 1. The `basicAuth` constructor option.
287
+ 2. The config file's `security.auth.basic` (or `security.basicAuth`) password, when you pass `configFile`.
288
+ 3. `SWML_BASIC_AUTH_PASSWORD`, with `SWML_BASIC_AUTH_USER` or `signalwire` as the username.
289
+ 4. Generated credentials: the service name as the username and a random password.
290
+
291
+ The service enforces the first three on every route, including `/health` and `/ready`. It doesn't enforce generated credentials: with no option, config file or environment variable, the service serves every route, `/swaig` included, without authentication, and `serve()` logs a warning saying so. The Python SDK's service always requires them. `getBasicAuthCredentials(true)` returns the credentials and their source (`provided`, `config file`, `environment` or `generated`).
292
+
293
+ This service requires basic auth:
294
+
295
+ ```typescript
296
+ const service = new SWMLService({
297
+ name: 'my-service',
298
+ basicAuth: ['username', 'a-long-random-password'],
299
+ });
300
+ ```
301
+
302
+ When credentials are enforced, the routes and `handleRequest()`, the framework-free dispatch method, check them through `validateBasicAuth()`, which a subclass can override.
303
+
304
+ ### Dynamic SWML Generation
305
+
306
+ Each request for the document runs the first of these that applies:
307
+
308
+ 1. The protected `buildSwmlForRequest(queryParams, bodyParams, headers)` hook. Return a `SwmlBuilder` to send its document, or `null` to fall through.
309
+ 2. The callback set with `setOnRequestCallback()`. It returns a `SwmlBuilder`, or a promise of one.
310
+ 3. The service's own document.
311
+
312
+ `bodyParams` is the request's JSON body, or an empty object for a `GET`. This subclass builds a different document for each request:
313
+
314
+ ```typescript
315
+ import { SWMLService, SwmlBuilder } from '@signalwire/sdk';
316
+
317
+ class DynamicService extends SWMLService {
318
+ protected override buildSwmlForRequest(
319
+ queryParams: Record<string, string>,
320
+ bodyParams: Record<string, unknown>,
321
+ headers: Record<string, string>,
322
+ ): SwmlBuilder | null {
323
+ const builder = new SwmlBuilder();
324
+ builder.answer();
325
+
326
+ // Customize the document based on request data
327
+ if (queryParams['caller_type'] === 'vip') {
328
+ builder.play({ url: 'say:Welcome, VIP caller.' });
329
+ } else {
330
+ builder.play({ url: 'say:Welcome, caller.' });
331
+ }
332
+
333
+ return builder;
334
+ }
335
+ }
336
+ ```
337
+
338
+ `buildSwmlForRequest()` is synchronous. To build the document with asynchronous work, register a callback instead:
339
+
340
+ <!-- snippet: no-run illustrative fragment: references the assumed `service` object established earlier on the page -->
341
+ ```typescript
342
+ service.setOnRequestCallback(async (queryParams, bodyParams, headers) => {
343
+ const builder = new SwmlBuilder();
344
+ builder.answer().play({ url: 'say:Hello!' }).hangup();
345
+ return builder;
346
+ });
347
+ ```
348
+
349
+ ## Custom Routing Callbacks
350
+
351
+ A routing callback inspects a request at a path you choose, and either redirects it or lets the service answer it.
352
+
353
+ ### Registering a Routing Callback
354
+
355
+ `registerRoutingCallback(callbackFn, path)` adds `GET` and `POST` routes at `path` (default `/sip`). The path is at the server root, not under the service's `route`. The callback receives the request's JSON body and its headers, and returns a route string or `null`:
356
+
357
+ <!-- snippet: no-run illustrative fragment: references the assumed `service` object established earlier on the page -->
358
+ ```typescript
359
+ import type { SwmlRequestData } from '@signalwire/sdk';
360
+
361
+ function myRoutingCallback(body: SwmlRequestData): string | null {
362
+ // Route based on a field in the request body
363
+ if (body['customer_id']) {
364
+ return `/customer/${body['customer_id']}`;
365
+ }
366
+ // Serve the service's document
367
+ return null;
368
+ }
369
+
370
+ // Register the callback for a specific path
371
+ service.registerRoutingCallback(myRoutingCallback, '/customer');
372
+ ```
373
+
374
+ ### How Routing Works
375
+
376
+ A request to a callback path goes through these steps:
377
+
378
+ 1. For a `POST` with a JSON body, the route calls the callback with the body and the headers, and awaits it. A `GET`, or a `POST` with no body, skips the callback.
379
+ 2. If the callback returns a string, the response is a `307` redirect with that string as the `Location`.
380
+ 3. Otherwise, or if the callback throws, the response is the service's SWML for the request, built as the main route builds it.
381
+
382
+ The callback can return its route directly or as a `Promise`.
383
+
384
+ ### Example: Routing by SIP Username
385
+
386
+ This service serves one document at `/main`, and a callback at `/sip` sends calls for the SIP user `sales` to another route:
387
+
388
+ ```typescript
389
+ import { SWMLService } from '@signalwire/sdk';
390
+ import type { SwmlRequestData } from '@signalwire/sdk';
391
+
392
+ class FrontDoorService extends SWMLService {
393
+ constructor() {
394
+ super({ name: 'front-door', route: '/main' });
395
+
396
+ // The main document: a greeting, then the menu section
397
+ this.addVerb('answer', {});
398
+ this.addVerb('play', { url: 'say:Hello from the main service.' });
399
+ this.addVerb('transfer', { dest: 'menu' });
400
+
401
+ // A second section, reached by the transfer verb
402
+ this.addVerbToSection('menu', 'play', { url: 'say:Goodbye.' });
403
+ this.addVerbToSection('menu', 'hangup', {});
404
+
405
+ this.registerRoutingCallback((body: SwmlRequestData) => {
406
+ const user = SWMLService.extractSipUsername(body);
407
+ if (user === 'sales') {
408
+ this.log.info('routing_to_sales');
409
+ return '/sales';
410
+ }
411
+ return null;
412
+ }, '/sip');
413
+ }
414
+ }
415
+ ```
416
+
417
+ A `POST /sip` whose body has `call.to` set to `sip:sales@example.sip.signalwire.com` gets a `307` to `/sales`. Any other request to `/sip` gets the service's document. `SWMLService.extractSipUsername()` returns the user part of a `sip:` or `sips:` address, the number of a `tel:` address, or the `call.to` value as it is.
418
+
419
+ ## Advanced Usage
420
+
421
+ ### Mounting into a Larger App
422
+
423
+ `getApp()` returns the service's Hono app, so you can mount it in a larger application. `asRouter()` returns the same app:
424
+
425
+ ```typescript
426
+ import { Hono } from 'hono';
427
+
428
+ const app = new Hono();
429
+ const service = new SWMLService({ name: 'my-service' });
430
+ app.route('/voice', service.getApp());
431
+ ```
432
+
433
+ Mounted this way, the service's routes are under `/voice`: its document at `/voice` and its SWAIG route at `/voice/swaig`.
434
+
435
+ ### Serving HTTPS
436
+
437
+ `serve()` serves HTTPS when SSL is enabled and both a certificate and a key path are set. The paths come from the `serve()` options, then the config file's `security.ssl` keys, then `SWML_SSL_ENABLED`, `SWML_SSL_CERT_PATH` and `SWML_SSL_KEY_PATH`:
438
+
439
+ <!-- snippet: no-run starts a blocking HTTPS server via service.serve() -->
440
+ ```typescript
441
+ const service = new SWMLService({ name: 'my-service', port: 8443 });
442
+ service.addVerb('answer', {});
443
+ await service.serve({
444
+ sslEnabled: true,
445
+ sslCert: '/etc/ssl/certs/voice.example.com.pem',
446
+ sslKey: '/etc/ssl/private/voice.example.com.key',
447
+ });
448
+ ```
449
+
450
+ Without all three, `serve()` serves plain HTTP. HTTPS responses don't carry a `Strict-Transport-Security` header. `AgentBase` overrides `serve()` and serves HTTPS from the same settings; see [SSL/TLS](configuration.md#ssltls) in the configuration guide.
451
+
452
+ ## API Reference
453
+
454
+ ### Constructor Options (`SWMLServiceOptions`)
455
+
456
+ The constructor takes these options:
457
+
458
+ - `name`: Service name (required)
459
+ - `route`: HTTP route path (default `'/'`)
460
+ - `host`: Host to bind to (default `'0.0.0.0'`)
461
+ - `port`: Port to bind to (default `PORT` or `3000`)
462
+ - `basicAuth`: Optional `[username, password]` tuple
463
+ - `schemaPath`: Path to a SWML schema file that verbs are validated against
464
+ - `configFile`: Path to a JSON config file; the service reads its `security.ssl` and basic-auth keys
465
+ - `schemaValidation`: `false` turns off verb validation (default `true`)
466
+
467
+ ### Document Methods
468
+
469
+ The document methods listed in [Document Methods](#document-methods) are the public API:
470
+
471
+ - `resetDocument()`
472
+ - `addVerb(verbName, config)`
473
+ - `addSection(sectionName)`
474
+ - `addVerbToSection(sectionName, verbName, config)`
475
+ - `getDocument()`
476
+ - `renderDocument()`
477
+ - `getBuilder()`
478
+
479
+ ### Service Methods
480
+
481
+ These methods serve, configure and inspect the service:
482
+
483
+ - `getApp()`: Get the underlying Hono app
484
+ - `asRouter()`: Return the same app as `getApp()`, to mount in a host app
485
+ - `serve(hostOrOptions?, port?, sslOptions?)`: Start the HTTP or HTTPS server
486
+ - `stop()`: Stop the server
487
+ - `handleRequest(method, url, headers, body?)`: Answer a request without Hono, returning `[status, headers, body]`
488
+ - `getBasicAuthCredentials(includeSource?)`: Get the basic-auth credentials
489
+ - `setOnRequestCallback(cb)`: Set a per-request SWML-builder callback
490
+ - `defineTool(opts)`: Register a SWAIG function
491
+ - `registerVerbHandler(handler)`: Store a custom verb handler in `verbRegistry`
492
+ - `registerRoutingCallback(callbackFn, path?)`: Register a request-routing callback
493
+ - `manualSetProxyUrl(url)`: Set the external base URL for webhook URLs
494
+ - `SWMLService.extractSipUsername(body)`: Get the user part of `call.to`
495
+
496
+ ## Examples
497
+
498
+ ### Basic Voicemail Service
499
+
500
+ This service answers, plays a greeting and a beep, and records a message:
501
+
502
+ ```typescript
503
+ import { SWMLService } from '@signalwire/sdk';
504
+
505
+ class VoicemailService extends SWMLService {
506
+ constructor() {
507
+ super({ name: 'voicemail', route: '/voicemail', port: 3000 });
508
+ this.buildVoicemailDocument();
509
+ }
510
+
511
+ buildVoicemailDocument(): void {
512
+ this.resetDocument();
513
+ this.addVerb('answer', {});
514
+ this.addVerb('play', {
515
+ url: "say:Hello, you've reached the voicemail service. Please leave a message after the beep.",
516
+ });
517
+ this.addVerb('play', { url: 'https://example.com/beep.wav' });
518
+ this.addVerb('record', {
519
+ format: 'mp3',
520
+ stereo: false,
521
+ max_length: 120, // 2 minutes max
522
+ terminators: '#',
523
+ });
524
+ this.addVerb('play', { url: 'say:Thank you for your message. Goodbye.' });
525
+ this.addVerb('hangup', {});
526
+ this.log.debug('voicemail_document_built');
527
+ }
528
+ }
529
+ ```
530
+
531
+ ### Dynamic Call Routing Service
532
+
533
+ This service builds a document for each request from a `department` value in the request body. Without one, it returns `null`, and the service sends its own document:
534
+
535
+ ```typescript
536
+ import { SWMLService, SwmlBuilder } from '@signalwire/sdk';
537
+
538
+ class CallRouterService extends SWMLService {
539
+ protected override buildSwmlForRequest(
540
+ queryParams: Record<string, string>,
541
+ bodyParams: Record<string, unknown>,
542
+ ): SwmlBuilder | null {
543
+ const department = String(bodyParams['department'] ?? '').toLowerCase();
544
+ if (!department) {
545
+ this.log.debug('no_department_using_default');
546
+ return null;
547
+ }
548
+
549
+ const builder = new SwmlBuilder();
550
+ builder.answer();
551
+ builder.play({
552
+ url: `say:Thank you for calling our ${department} department. Please hold.`,
553
+ });
554
+
555
+ const phoneNumbers: Record<string, string> = {
556
+ sales: '+15551112222',
557
+ support: '+15553334444',
558
+ billing: '+15555556666',
559
+ };
560
+ const toNumber = phoneNumbers[department] ?? '+15559990000';
561
+
562
+ builder.connect({ to: toNumber, timeout: 30, answer_on_bridge: true });
563
+ builder.play({
564
+ url: "say:We're sorry, but all of our agents are busy. Please try again later.",
565
+ });
566
+ builder.hangup();
567
+
568
+ return builder;
569
+ }
570
+ }
571
+ ```
572
+
573
+ For more examples, see the `examples` directory in the SDK repository.