@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,666 @@
1
+ # WebService Documentation
2
+
3
+ The `WebService` class serves static files from local directories over HTTP or HTTPS. It's built on [Hono](https://hono.dev/) and runs on its own port, standalone or next to your agents.
4
+
5
+ <!-- snippet-setup -->
6
+ ```ts
7
+ export {}; // treat each example as a module (top-level await)
8
+ declare global {
9
+ const WebService: typeof import('@signalwire/sdk').WebService;
10
+ }
11
+ ```
12
+
13
+ ## Table of Contents
14
+ - [Overview](#overview)
15
+ - [Installation](#installation)
16
+ - [Quick Start](#quick-start)
17
+ - [Configuration](#configuration)
18
+ - [Security Features](#security-features)
19
+ - [HTTPS/SSL Support](#httpsssl-support)
20
+ - [API Endpoints](#api-endpoints)
21
+ - [Usage Examples](#usage-examples)
22
+ - [Deployment Patterns](#deployment-patterns)
23
+ - [Best Practices](#best-practices)
24
+ - [API Reference](#api-reference)
25
+ - [Integration with SignalWire Agents](#integration-with-signalwire-agents)
26
+
27
+ ## Overview
28
+
29
+ `WebService` serves files from local directories, each at its own URL prefix. You can use it to serve:
30
+ - Audio files that an agent's SWML plays
31
+ - Documentation, API specs and reports
32
+ - Static assets such as images, CSS and JavaScript
33
+
34
+ It has these features:
35
+ - Several directories, each mounted at its own URL prefix
36
+ - HTTP Basic Authentication on every route but `/health`, CORS and security headers
37
+ - An allowlist and a blocklist of file extensions, and a maximum file size
38
+ - Optional HTML directory listings
39
+ - A content type chosen from the file extension
40
+ - HTTPS from PEM certificate and key files
41
+
42
+ ## Installation
43
+
44
+ `WebService` is part of the SignalWire SDK package:
45
+
46
+ ```bash
47
+ npm install @signalwire/sdk
48
+ ```
49
+
50
+ The package requires Node.js 22 or later.
51
+
52
+ ## Quick Start
53
+
54
+ This service serves two directories on port 8002, to clients that send its credentials:
55
+
56
+ ```bash
57
+ export SWML_BASIC_AUTH_USER="admin"
58
+ export SWML_BASIC_AUTH_PASSWORD="a-long-random-password"
59
+ ```
60
+
61
+ <!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
62
+ ```typescript
63
+ import { WebService } from '@signalwire/sdk';
64
+
65
+ // Create a service to serve files
66
+ const service = new WebService({
67
+ port: 8002,
68
+ directories: {
69
+ '/docs': './documentation',
70
+ '/assets': './static/assets',
71
+ },
72
+ });
73
+
74
+ // Start the service
75
+ await service.start();
76
+ // Service available at http://localhost:8002, with the credentials above
77
+ ```
78
+
79
+ `start()` throws if no credentials are configured. See [Basic Authentication](#basic-authentication).
80
+
81
+ ## Configuration
82
+
83
+ Constructor options override values from a config file. For each setting, the constructor option wins, then the config file, then the default.
84
+
85
+ ### 1. Constructor Options
86
+
87
+ The constructor takes a `WebServiceOptions` object:
88
+
89
+ ```typescript
90
+ const service = new WebService({
91
+ port: 8002, // Port to bind to (default 8002)
92
+ directories: { // URL prefix to directory mappings
93
+ '/docs': './documentation',
94
+ '/assets': './static',
95
+ },
96
+ basicAuth: ['admin', 'a-long-random-password'], // [username, password]
97
+ enableDirectoryBrowsing: true, // Allow directory listings
98
+ allowedExtensions: ['.html', '.css', '.js'], // Allowlist extensions
99
+ blockedExtensions: ['.env', '.key'], // Replaces the default blocklist
100
+ maxFileSize: 100 * 1024 * 1024, // Max file size (100 MB)
101
+ enableCors: true, // Enable CORS headers (default true)
102
+ });
103
+ ```
104
+
105
+ ### 2. Environment Variables
106
+
107
+ `WebService` reads these environment variables:
108
+
109
+ ```bash
110
+ # Basic auth credentials, used when neither the basicAuth option nor the config file sets them
111
+ export SWML_BASIC_AUTH_USER="admin" # defaults to signalwire
112
+ export SWML_BASIC_AUTH_PASSWORD="a-long-random-password"
113
+
114
+ # SSL/HTTPS configuration (via SslConfig), used when the ssl option doesn't set them
115
+ export SWML_SSL_ENABLED=true
116
+ export SWML_SSL_CERT_PATH="/path/to/cert.pem"
117
+ export SWML_SSL_KEY_PATH="/path/to/key.pem"
118
+
119
+ # CORS origins (comma-separated; defaults to *)
120
+ export SWML_CORS_ORIGINS="https://app.example.com"
121
+ ```
122
+
123
+ It doesn't read `PORT`; set the `port` option or the config file's `service.port`.
124
+
125
+ ### 3. Configuration File
126
+
127
+ Pass `configFile` to load a JSON file. The values under the `service` key map to the constructor options:
128
+
129
+ ```json
130
+ {
131
+ "service": {
132
+ "port": 8002,
133
+ "directories": {
134
+ "/docs": "./documentation",
135
+ "/api": "./api-specs",
136
+ "/reports": "./generated/reports"
137
+ },
138
+ "enableDirectoryBrowsing": true,
139
+ "maxFileSize": 52428800,
140
+ "allowedExtensions": [".html", ".css", ".js", ".json", ".pdf"],
141
+ "blockedExtensions": [".env", ".key", ".pem"],
142
+ "enableCors": true
143
+ }
144
+ }
145
+ ```
146
+
147
+ This constructor loads that file:
148
+
149
+ ```typescript
150
+ const service = new WebService({ configFile: './web_service.json' });
151
+ ```
152
+
153
+ The file can set credentials under `security.auth.basic` (`{"user": ..., "password": ...}`), but not `ssl`. Directories from the file and from the `directories` option are merged, and the option wins for the same prefix. Relative directory paths resolve against the process's working directory. A `configFile` that is missing or isn't valid JSON is skipped with a warning.
154
+
155
+ Without `configFile`, the constructor looks for `web_service.json` in the working directory, `./config/`, `~/.signalwire/`, `./.swml/`, `~/.swml/` and `/etc/swml/`, and loads the first one it finds. If that file isn't valid JSON, the constructor logs a warning and starts from its other settings. See [Search Paths](configuration.md#search-paths) in the configuration guide.
156
+
157
+ ## Security Features
158
+
159
+ ### Basic Authentication
160
+
161
+ The service takes its credentials from the first of these that sets a password:
162
+
163
+ 1. The `basicAuth: ['username', 'password']` option
164
+ 2. The config file's `security.auth.basic` `user` and `password`
165
+ 3. The `SWML_BASIC_AUTH_USER` and `SWML_BASIC_AUTH_PASSWORD` environment variables
166
+
167
+ The user defaults to `signalwire` when only a password is set, and an empty password doesn't count. Every route except `/health` requires HTTP Basic Authentication, `/` included.
168
+
169
+ Without credentials from any of these, the service generates a password it never shows, so `getApp()` refuses every request but `/health` with `401`, and `start()` throws:
170
+
171
+ ```text
172
+ WebService needs basic-auth credentials: set SWML_BASIC_AUTH_USER and SWML_BASIC_AUTH_PASSWORD, pass basicAuth: [user, password], or set security.auth.basic in the config file. A generated password is never shown, so every file request would be refused.
173
+ ```
174
+
175
+ `start()` logs the user and where the credentials came from (`provided`, `config file` or `environment`), not the password.
176
+
177
+ ### File Security
178
+
179
+ #### Default Blocked Extensions and Files
180
+
181
+ The default blocklist refuses these files:
182
+ - `.env`, `.git`, `.gitignore`
183
+ - `.key`, `.pem`, `.crt`
184
+ - `.pyc`, `__pycache__`
185
+ - `.DS_Store`, `.swp`
186
+
187
+ An entry that starts with a dot matches a file extension or a whole file name. Any other entry matches a file name, or any part of the file's path below the mount. Every entry also matches a directory on the path below the mount, so `__pycache__` blocks `/__pycache__/data.txt`. Passing `blockedExtensions` replaces the default list, so include the defaults you still want.
188
+
189
+ #### Hidden Files and Directories
190
+
191
+ Whatever `blockedExtensions` holds, the service refuses with `403` any path whose components below the mount include one that starts with a dot, whether the file exists or not. That covers `/.env.production`, anything under `/.git/`, `/.ssh/` or `/.aws/`, and the encoded form `/%2eenv`. The one exception is `.well-known`, so ACME challenges and `security.txt` are served from `/.well-known/`, though a dot-named file inside it isn't. A directory mounted from a path that itself contains a dot directory, such as `~/.site/public`, is served normally: only the components below the mount count. Directory listings hide dot entries and blocked names.
192
+
193
+ The blocklist, the hidden-path rule and `allowedExtensions` apply both to the path in the request and to the file actually read. A symbolic link inside the mount, such as `alias.txt` pointing to `.env`, `keys` pointing to `.ssh`, or a link into a `__pycache__` directory, gets `403` like the file it points to. The same goes for a directory's `index.html`.
194
+
195
+ #### Path Traversal Protection
196
+
197
+ `WebService` refuses a path containing `..` with `403`, and checks that the resolved path is inside the mounted directory. A `..` segment in a request URL is resolved when the URL is parsed, before routing, so `GET /docs/../../etc/passwd` becomes `GET /etc/passwd`. That path matches no mount and gets `404`.
198
+
199
+ The check follows symbolic links. A link inside a mounted directory serves its target only when the target is also inside the directory; a link to a file or directory outside it gets `403`. A directory listing doesn't show symbolic links.
200
+
201
+ #### File Size Limits
202
+
203
+ A file larger than `maxFileSize` gets `403`, like a blocked file type. The default maximum is 100 MB. This service sets 50 MB:
204
+
205
+ ```typescript
206
+ const service = new WebService({ maxFileSize: 50 * 1024 * 1024 }); // 50 MB
207
+ ```
208
+
209
+ ### Security Headers
210
+
211
+ Every response carries these headers:
212
+ - `X-Content-Type-Options: nosniff`
213
+ - `X-Frame-Options: DENY`
214
+ - `X-XSS-Protection: 1; mode=block`
215
+ - `Referrer-Policy: strict-origin-when-cross-origin`
216
+ - `Content-Security-Policy: default-src 'none'; frame-ancestors 'none'`
217
+ - `Permissions-Policy: camera=(), microphone=(), geolocation=()`
218
+ - `Strict-Transport-Security: max-age=31536000; includeSubDomains`, when SSL is configured through the `ssl` option or the `SWML_SSL_ENABLED`, `SWML_SSL_CERT_PATH` and `SWML_SSL_KEY_PATH` variables
219
+
220
+ With `enableCors` (the default), CORS allows the origins in `SWML_CORS_ORIGINS`, or any origin when it's unset or lists `*`.
221
+
222
+ ## HTTPS/SSL Support
223
+
224
+ `WebService` serves HTTPS when SSL is enabled and both the certificate and the key files exist. If either file is missing, it serves plain HTTP. `start()` logs the scheme it uses.
225
+
226
+ ### Method 1: Environment Variables
227
+
228
+ `SslConfig` reads the SSL settings from the environment:
229
+
230
+ ```bash
231
+ export SWML_SSL_ENABLED=true
232
+ export SWML_SSL_CERT_PATH="/path/to/cert.pem"
233
+ export SWML_SSL_KEY_PATH="/path/to/key.pem"
234
+ ```
235
+
236
+ ### Method 2: Constructor `ssl` Option
237
+
238
+ The `ssl` option sets the same values. A field it leaves out falls back to its environment variable:
239
+
240
+ <!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
241
+ ```typescript
242
+ const service = new WebService({
243
+ directories: { '/docs': './docs' },
244
+ ssl: { enabled: true, certPath: '/path/to/cert.pem', keyPath: '/path/to/key.pem' },
245
+ });
246
+ await service.start();
247
+ // Service available at https://localhost:8002
248
+ ```
249
+
250
+ ### Method 3: `start()` Parameters
251
+
252
+ `start(host, port, sslCert, sslKey)` takes the certificate and key paths directly. They replace the other SSL settings for that server:
253
+
254
+ <!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
255
+ ```typescript
256
+ const service = new WebService({ directories: { '/docs': './docs' } });
257
+ await service.start('0.0.0.0', 8002, '/path/to/cert.pem', '/path/to/key.pem');
258
+ ```
259
+
260
+ With this method alone, responses don't carry the `Strict-Transport-Security` header, because that header depends on the `ssl` option or the environment variables.
261
+
262
+ ### Generating Self-Signed Certificates
263
+
264
+ For development and testing, `openssl` can create a self-signed certificate:
265
+
266
+ ```bash
267
+ # Generate a self-signed certificate
268
+ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \
269
+ -days 365 -nodes -subj "/CN=localhost"
270
+
271
+ # Use with WebService
272
+ export SWML_SSL_ENABLED=true
273
+ export SWML_SSL_CERT_PATH="cert.pem"
274
+ export SWML_SSL_KEY_PATH="key.pem"
275
+ ```
276
+
277
+ ## API Endpoints
278
+
279
+ ### GET /health
280
+
281
+ `GET /health` reports the service's configuration. It needs no credentials, so a load balancer can probe it. `authRequired` is always `true`.
282
+
283
+ **Response:**
284
+ ```json
285
+ {
286
+ "status": "healthy",
287
+ "directories": ["/docs", "/assets"],
288
+ "sslEnabled": false,
289
+ "authRequired": true,
290
+ "directoryBrowsing": true
291
+ }
292
+ ```
293
+
294
+ ### GET /
295
+
296
+ `GET /` returns an HTML page that links to each mounted directory. With no directories, it returns `{"service":"SignalWire Web Service","directories":[]}`.
297
+
298
+ ### GET /{route}/{filePath}
299
+
300
+ `GET` on a mounted prefix serves a file from that directory. `route` is the mounted prefix (for example, `/docs`), and `filePath` is the path of a file inside the directory.
301
+
302
+ **Response:**
303
+ - The file, with a content type from its extension (`application/octet-stream` for an unknown one) and `Cache-Control: public, max-age=3600`
304
+ - `404` if the file doesn't exist
305
+ - `403` if the path contains `..` or a component below the mount that starts with a dot (other than `.well-known`), resolves (through a symbolic link) to a file outside the mounted directory or under a hidden or blocked directory, or the file is blocked, isn't allowed, or is larger than `maxFileSize`
306
+ - `307` to the same path with a trailing slash, for a directory requested without one (`/docs/guide` redirects to `/docs/guide/`), so relative links in its `index.html` or listing resolve inside it. The `Location` is a path on this host, built from the path as the client sent it, still percent-encoded (`/docs/my%20dir` redirects to `/docs/my%20dir/`), without the query string and with leading slashes collapsed to one, so `//example.org` can't send the browser to another host.
307
+ - `401` without valid credentials
308
+ - For a directory requested with its trailing slash: with `enableDirectoryBrowsing`, an HTML listing of its subdirectories and allowed files, without dot files. Without it, the directory's `index.html` if that exists and is allowed, otherwise `403`.
309
+
310
+ ## Usage Examples
311
+
312
+ The examples that don't pass `basicAuth` take their credentials from `SWML_BASIC_AUTH_USER` and `SWML_BASIC_AUTH_PASSWORD`, as in the [Quick Start](#quick-start).
313
+
314
+ ### Basic File Serving
315
+
316
+ This service serves two directories on the default port:
317
+
318
+ <!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
319
+ ```typescript
320
+ import { WebService } from '@signalwire/sdk';
321
+
322
+ // Serve documentation
323
+ const service = new WebService({
324
+ directories: {
325
+ '/docs': './documentation',
326
+ '/api': './api-specs',
327
+ },
328
+ });
329
+ await service.start();
330
+
331
+ // Files accessible at:
332
+ // http://localhost:8002/docs/index.html
333
+ // http://localhost:8002/api/swagger.json
334
+ ```
335
+
336
+ ### With Directory Browsing
337
+
338
+ This service lists the contents of `./public`:
339
+
340
+ <!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
341
+ ```typescript
342
+ const service = new WebService({
343
+ directories: { '/files': './public' },
344
+ enableDirectoryBrowsing: true, // Allow browsing directories
345
+ });
346
+ await service.start();
347
+
348
+ // Browse files at: http://localhost:8002/files/
349
+ ```
350
+
351
+ ### Restricted File Types
352
+
353
+ This service serves only web assets:
354
+
355
+ ```typescript
356
+ // Only serve web assets
357
+ const service = new WebService({
358
+ directories: { '/web': './www' },
359
+ allowedExtensions: ['.html', '.css', '.js', '.png', '.jpg', '.woff2'],
360
+ enableDirectoryBrowsing: false,
361
+ });
362
+ ```
363
+
364
+ ### Dynamic Directory Management
365
+
366
+ `addDirectory()` mounts a directory after construction, and `removeDirectory()` unmounts one. Both work on a running service and take effect from the next request.
367
+
368
+ <!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
369
+ ```typescript
370
+ const service = new WebService();
371
+ service.addDirectory('/docs', './documentation');
372
+ await service.start();
373
+
374
+ // Later, while the service runs
375
+ service.addDirectory('/reports', './generated/reports');
376
+ service.removeDirectory('/docs'); // GET /docs/... now returns 404
377
+ ```
378
+
379
+ When prefixes overlap, the longest one that matches the request path serves it. A directory mounted at `/` serves every path except `/` and `/health`.
380
+
381
+ `addDirectory()` throws if the directory doesn't exist or isn't a directory.
382
+
383
+ ### With Credentials in Code
384
+
385
+ This service takes its credentials from the `basicAuth` option instead of the environment:
386
+
387
+ <!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
388
+ ```typescript
389
+ const service = new WebService({
390
+ directories: { '/private': './sensitive-docs' },
391
+ basicAuth: ['admin', 'a-long-random-password'],
392
+ });
393
+ await service.start();
394
+ ```
395
+
396
+ ### HTTPS with an Existing Certificate
397
+
398
+ This service uses certificate files from a certificate authority, passed to `start()`:
399
+
400
+ <!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
401
+ ```typescript
402
+ const service = new WebService({
403
+ directories: { '/secure': './secure-files' },
404
+ });
405
+ await service.start(
406
+ '0.0.0.0',
407
+ 8002,
408
+ '/etc/letsencrypt/live/example.com/fullchain.pem',
409
+ '/etc/letsencrypt/live/example.com/privkey.pem',
410
+ );
411
+ // Service available at https://example.com:8002
412
+ ```
413
+
414
+ ### Multi-Environment Configuration
415
+
416
+ This setup serves HTTPS in production and a browsable directory in development:
417
+
418
+ <!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
419
+ ```typescript
420
+ import { WebService } from '@signalwire/sdk';
421
+
422
+ let service: WebService;
423
+
424
+ if (process.env.NODE_ENV === 'production') {
425
+ service = new WebService({
426
+ port: 443,
427
+ directories: { '/': './dist' },
428
+ enableDirectoryBrowsing: false,
429
+ ssl: {
430
+ enabled: true,
431
+ certPath: '/etc/ssl/certs/production.crt',
432
+ keyPath: '/etc/ssl/private/production.key',
433
+ },
434
+ });
435
+ } else {
436
+ service = new WebService({
437
+ port: 8002,
438
+ directories: { '/': './src' },
439
+ enableDirectoryBrowsing: true,
440
+ });
441
+ }
442
+
443
+ await service.start();
444
+ ```
445
+
446
+ ## Deployment Patterns
447
+
448
+ ### Standalone Service
449
+
450
+ This script (`web-server.ts`) runs `WebService` as a dedicated static file server:
451
+
452
+ <!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
453
+ ```typescript
454
+ import { WebService } from '@signalwire/sdk';
455
+
456
+ const service = new WebService({
457
+ port: 8002,
458
+ directories: {
459
+ '/docs': '/var/www/docs',
460
+ '/assets': '/var/www/assets',
461
+ '/downloads': '/var/www/downloads',
462
+ },
463
+ });
464
+
465
+ await service.start();
466
+ ```
467
+
468
+ ### Alongside AI Agents
469
+
470
+ This script (`main.ts`) runs `WebService` on one port and an agent on another:
471
+
472
+ <!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
473
+ ```typescript
474
+ import { AgentBase, WebService } from '@signalwire/sdk';
475
+
476
+ // Start WebService for documentation on port 8002
477
+ const web = new WebService({
478
+ port: 8002,
479
+ directories: { '/docs': './agent-docs' },
480
+ });
481
+ await web.start();
482
+
483
+ // Run the agent on port 3000
484
+ const agent = new AgentBase({ name: 'My Agent' });
485
+ agent.setPromptText('You are a helpful assistant.');
486
+ await agent.serve({ port: 3000 });
487
+ ```
488
+
489
+ ### Inside Another Hono App
490
+
491
+ `getApp()` returns a Hono app that a parent app can mount under a prefix with `route()`:
492
+
493
+ ```typescript
494
+ import { Hono } from 'hono';
495
+ import { WebService } from '@signalwire/sdk';
496
+
497
+ const web = new WebService({ directories: { '/docs': './documentation' } });
498
+ const app = new Hono();
499
+ app.route('/static', web.getApp());
500
+ // GET /static/docs/index.html serves ./documentation/index.html
501
+ // GET /static/health is the health check, without credentials
502
+ ```
503
+
504
+ The service resolves its mounts against the path below the prefix the request matched, at a path-segment boundary, so `/staticx/docs/...` isn't served. A parameterized prefix such as `/:tenant`, or one with a regular expression such as `/:tenant{[a-z]+}`, works too. The directory redirect keeps the prefix (`/static/docs/guide` redirects to `/static/docs/guide/`), and so do the links on the `/static` overview page.
505
+
506
+ Use `route()`, not `mount()`. `mount()` hands the service a request with the prefix removed from its URL, so files are served, but a directory redirect points at the path without the prefix.
507
+
508
+ ### Docker Deployment
509
+
510
+ This Dockerfile runs the compiled `web-server.ts` from the standalone example. It assumes you compile it to `dist/web-server.js` before the build:
511
+
512
+ ```dockerfile
513
+ FROM node:22-slim
514
+
515
+ WORKDIR /app
516
+
517
+ # Install dependencies (including @signalwire/sdk)
518
+ COPY package*.json ./
519
+ RUN npm ci --omit=dev
520
+
521
+ # Copy app + static files
522
+ COPY ./dist ./dist
523
+ COPY ./static /app/static
524
+ COPY ./web_service.json /app/web_service.json
525
+
526
+ # Expose port
527
+ EXPOSE 8002
528
+
529
+ # Run WebService
530
+ CMD ["node", "dist/web-server.js"]
531
+ ```
532
+
533
+ The service finds `/app/web_service.json` because the working directory is `/app`.
534
+
535
+ ### Nginx Reverse Proxy
536
+
537
+ For production, Nginx in front of the service can terminate TLS:
538
+
539
+ ```nginx
540
+ server {
541
+ listen 80;
542
+ server_name static.example.com;
543
+
544
+ # Redirect to HTTPS
545
+ return 301 https://$server_name$request_uri;
546
+ }
547
+
548
+ server {
549
+ listen 443 ssl http2;
550
+ server_name static.example.com;
551
+
552
+ ssl_certificate /etc/ssl/certs/example.com.crt;
553
+ ssl_certificate_key /etc/ssl/private/example.com.key;
554
+
555
+ location / {
556
+ proxy_pass http://localhost:8002;
557
+ proxy_set_header Host $host;
558
+ proxy_set_header X-Real-IP $remote_addr;
559
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
560
+ proxy_set_header X-Forwarded-Proto $scheme;
561
+ }
562
+ }
563
+ ```
564
+
565
+ ## Best Practices
566
+
567
+ These practices apply to a production deployment:
568
+
569
+ 1. Serve HTTPS, from the service or from a proxy in front of it.
570
+ 2. Use a long random password (the `basicAuth` option or `SWML_BASIC_AUTH_PASSWORD`), and send it only over HTTPS, since basic auth sends it with every request.
571
+ 3. Use `allowedExtensions` to serve only the file types you intend.
572
+ 4. Turn off directory browsing.
573
+ 5. Mount only directories whose contents you control.
574
+ 6. Tune `maxFileSize`, and use a CDN for large or busy static assets.
575
+
576
+ ## API Reference
577
+
578
+ ### WebService Class
579
+
580
+ The class has these public members:
581
+
582
+ <!-- snippet: no-compile class API-signature reference (declaration-only, no bodies), not runnable -->
583
+ ```typescript
584
+ class WebService {
585
+ constructor(options?: WebServiceOptions);
586
+
587
+ readonly port: number;
588
+ readonly directories: Record<string, string>;
589
+ readonly enableDirectoryBrowsing: boolean;
590
+ readonly allowedExtensions: string[] | null;
591
+ readonly blockedExtensions: string[];
592
+ readonly maxFileSize: number;
593
+ readonly enableCors: boolean;
594
+
595
+ addDirectory(route: string, directory: string): void;
596
+ removeDirectory(route: string): void;
597
+ getApp(): Hono;
598
+ get sslConfig(): SslConfig;
599
+ start(host?: string, port?: number, sslCert?: string, sslKey?: string): Promise<void>;
600
+ stop(): void;
601
+ }
602
+ ```
603
+
604
+ #### WebServiceOptions
605
+
606
+ | Option | Type | Default | Description |
607
+ |--------|------|---------|-------------|
608
+ | `port` | `number` | `8002` | Port to bind to. |
609
+ | `directories` | `Record<string, string>` | `{}` | URL prefix to local directory mappings. |
610
+ | `basicAuth` | `[string, string]` | config file, then environment | `[username, password]` for basic auth. Required from one of the three sources. |
611
+ | `configFile` | `string` | none | Path to a JSON config file. Without it, the constructor searches for `web_service.json`. |
612
+ | `enableDirectoryBrowsing` | `boolean` | `false` | Serve HTML listings for directories. |
613
+ | `allowedExtensions` | `string[]` | all | Allowlist of file extensions, such as `.html`. |
614
+ | `blockedExtensions` | `string[]` | (defaults) | Blocklist of extensions and names. Replaces the default list. |
615
+ | `maxFileSize` | `number` | `104857600` | Maximum file size in bytes (100 MB). |
616
+ | `enableCors` | `boolean` | `true` | Add CORS headers. |
617
+ | `ssl` | `SslOptions` | none | SSL settings: `enabled`, `certPath`, `keyPath`, `domain`, `hsts`, `hstsMaxAge`. |
618
+
619
+ #### Methods
620
+
621
+ These methods manage the service:
622
+
623
+ - `addDirectory(route, directory)`: Mount a directory at a URL prefix, before or after the service starts. Throws if the directory doesn't exist or isn't a directory.
624
+ - `removeDirectory(route)`: Unmount the prefix. Its route returns `404` from the next request.
625
+ - `getApp()`: Return the underlying Hono app, to mount or test.
626
+ - `start(host?, port?, sslCert?, sslKey?)`: Start the HTTP or HTTPS server. `host` defaults to `0.0.0.0`. Throws if no credentials are configured. With `SWAIG_CLI_MODE=true`, it does nothing.
627
+ - `stop()`: Stop the server.
628
+
629
+ ## Integration with SignalWire Agents
630
+
631
+ An agent can point callers or the model at files the service serves. This agent's tool returns a documentation link, and the agent and the service run in the same process on different ports:
632
+
633
+ <!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
634
+ ```typescript
635
+ import { AgentBase, FunctionResult, WebService } from '@signalwire/sdk';
636
+
637
+ class DocumentationAgent extends AgentBase {
638
+ protected override defineTools(): void {
639
+ this.defineTool({
640
+ name: 'get_doc_link',
641
+ description: 'Get a link to a documentation page.',
642
+ parameters: {
643
+ doc_name: { type: 'string', description: 'Name of the documentation page' },
644
+ },
645
+ required: ['doc_name'],
646
+ handler: (args) =>
647
+ new FunctionResult(
648
+ `Documentation available at: https://example.com:8002/docs/${args.doc_name}.html`,
649
+ ),
650
+ });
651
+ }
652
+ }
653
+
654
+ // Start WebService for documentation
655
+ const web = new WebService({ port: 8002, directories: { '/docs': './documentation' } });
656
+ await web.start();
657
+
658
+ // Start the agent
659
+ const agent = new DocumentationAgent({ name: 'Documentation Assistant' });
660
+ agent.promptAddSection('Documentation', {
661
+ body: 'User documentation is available at https://example.com:8002/docs/',
662
+ });
663
+ await agent.serve({ port: 3000 });
664
+ ```
665
+
666
+ The tool's response is context for the model, not speech: the model decides how to pass the link on. For audio, a SWML `play` verb, or a `FunctionResult` action such as `playBackgroundFile()`, can use a URL the service serves. Every file the service serves needs its credentials, so a URL that someone or something else fetches has to carry them, for example `https://user:password@example.com:8002/audio/greeting.mp3`.