@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
@@ -8,12 +8,15 @@
8
8
  import { Hono } from 'hono';
9
9
  import { basicAuth } from 'hono/basic-auth';
10
10
  import { cors } from 'hono/cors';
11
- import { readFile, stat, readdir } from 'node:fs/promises';
12
- import { join, extname, normalize, resolve, basename } from 'node:path';
11
+ import { readFile, stat, readdir, realpath } from 'node:fs/promises';
12
+ import { join, extname, normalize, relative, resolve, basename, sep } from 'node:path';
13
13
  import { existsSync, statSync } from 'node:fs';
14
+ import { randomBytes } from 'node:crypto';
14
15
  import { getLogger } from './Logger.js';
15
16
  import { ConfigLoader } from './ConfigLoader.js';
16
17
  import { SslConfig } from './SslConfig.js';
18
+ import { SecurityConfig } from './SWMLService.js';
19
+ import { corsOriginsFromEnv } from './SecurityUtils.js';
17
20
  /** Common MIME types for static file serving. */
18
21
  const MIME_TYPES = {
19
22
  '.html': 'text/html',
@@ -54,6 +57,47 @@ function escapeHtml(str) {
54
57
  .replace(/"/g, '"')
55
58
  .replace(/'/g, ''');
56
59
  }
60
+ /** Whether `path` is `root` or inside it (both absolute, already resolved). */
61
+ function isWithin(path, root) {
62
+ return path === root || path.startsWith(root.endsWith(sep) ? root : root + sep);
63
+ }
64
+ /** The components of a path, split on either separator, without empty ones. */
65
+ function pathParts(path) {
66
+ return path.split(/[\\/]+/).filter(Boolean);
67
+ }
68
+ /**
69
+ * Decode a route parameter as Hono does: `decodeURIComponent` when it holds a
70
+ * `%`, and on a malformed sequence, each decodable run of escapes alone.
71
+ */
72
+ function decodeParam(value) {
73
+ if (!value.includes('%'))
74
+ return value;
75
+ try {
76
+ return decodeURIComponent(value);
77
+ }
78
+ catch {
79
+ return value.replace(/(?:%[0-9A-Fa-f]{2})+/g, (run) => {
80
+ try {
81
+ return decodeURIComponent(run);
82
+ }
83
+ catch {
84
+ return run;
85
+ }
86
+ });
87
+ }
88
+ }
89
+ /** Route parameter holding the part of the path below the app's own root. */
90
+ const TAIL_PARAM = 'webServicePath';
91
+ /**
92
+ * The request's path with a trailing slash, as a redirect on this host. It's
93
+ * built from the path as the client sent it, still percent-encoded, so a
94
+ * directory named `my dir` keeps its encoding and `%2F` isn't decoded into a
95
+ * separator. Leading slashes are collapsed to one, so `//example.org` can't
96
+ * become a Location a browser reads as another host.
97
+ */
98
+ function sameOriginRedirect(url) {
99
+ return `/${new URL(url).pathname.replace(/^\/+/, '')}/`;
100
+ }
57
101
  /** Format a file size in bytes to a human-readable string. */
58
102
  function formatSize(bytes) {
59
103
  if (bytes < 1024)
@@ -69,8 +113,13 @@ function formatSize(bytes) {
69
113
  * extension filtering, file size limits, HTTP Basic Auth, CORS, directory
70
114
  * browsing, and optional SSL/TLS. Mirrors the Python SDK's `WebService` class.
71
115
  *
72
- * Useful when an agent or prefab needs to serve supporting assets — prompts, audio
73
- * files, images — from the same process without running a separate nginx / CDN.
116
+ * Useful when an agent or prefab needs to serve supporting assets (prompts, audio
117
+ * files, images) from the same process without running a separate nginx or CDN.
118
+ *
119
+ * Every route but `/health` requires HTTP Basic Authentication, and `start()`
120
+ * refuses to run until credentials are configured: the `basicAuth` option, the
121
+ * config file's `security.auth.basic`, or `SWML_BASIC_AUTH_USER` /
122
+ * `SWML_BASIC_AUTH_PASSWORD`.
74
123
  *
75
124
  * @example Serve a directory of audio files
76
125
  * ```ts
@@ -79,10 +128,11 @@ function formatSize(bytes) {
79
128
  * const web = new WebService({
80
129
  * port: 8080,
81
130
  * directories: { '/audio': './public/audio' },
131
+ * basicAuth: ['audio', process.env['AUDIO_PASSWORD'] ?? ''],
82
132
  * allowedExtensions: ['.mp3', '.wav'],
83
133
  * });
84
134
  *
85
- * await web.serve();
135
+ * await web.start();
86
136
  * // GET http://host:8080/audio/greeting.mp3
87
137
  * ```
88
138
  */
@@ -103,13 +153,23 @@ export class WebService {
103
153
  directories;
104
154
  _app;
105
155
  _basicAuth;
156
+ /** Where the credentials came from: 'provided', 'environment', 'config file' or 'generated'. */
157
+ _basicAuthSource;
106
158
  _ssl;
107
159
  _server = null;
108
160
  log = getLogger('WebService');
109
161
  /** Default blocked extensions and file names (security-sensitive files). */
110
162
  static DEFAULT_BLOCKED = [
111
- '.env', '.git', '.gitignore', '.key', '.pem', '.crt',
112
- '.pyc', '__pycache__', '.DS_Store', '.swp',
163
+ '.env',
164
+ '.git',
165
+ '.gitignore',
166
+ '.key',
167
+ '.pem',
168
+ '.crt',
169
+ '.pyc',
170
+ '__pycache__',
171
+ '.DS_Store',
172
+ '.swp',
113
173
  ];
114
174
  /**
115
175
  * Create a WebService.
@@ -119,15 +179,35 @@ export class WebService {
119
179
  // Load configuration from file first (if provided), then override with
120
180
  // explicit constructor parameters, mirroring the Python SDK's precedence.
121
181
  const fileConfig = this._loadConfig(options?.configFile);
182
+ const security = new SecurityConfig({ configFile: fileConfig.configPath });
122
183
  this.port = options?.port ?? fileConfig.port ?? 8002;
123
184
  this.directories = { ...(fileConfig.directories ?? {}), ...(options?.directories ?? {}) };
124
- this._basicAuth = options?.basicAuth ?? null;
185
+ // Basic auth, as the Python reference resolves it: the basicAuth option,
186
+ // then the config file's security.auth.basic, then SWML_BASIC_AUTH_USER /
187
+ // SWML_BASIC_AUTH_PASSWORD (the user defaults to 'signalwire'). With none,
188
+ // a generated password that nothing shows: every request is refused, and
189
+ // start() throws rather than serve that way.
190
+ const configured = security.getBasicAuth();
191
+ if (options?.basicAuth?.[1]) {
192
+ this._basicAuth = options.basicAuth;
193
+ this._basicAuthSource = 'provided';
194
+ }
195
+ else if (configured) {
196
+ this._basicAuth = configured;
197
+ this._basicAuthSource = security.basicAuthSource ?? 'environment';
198
+ }
199
+ else {
200
+ this._basicAuth = ['signalwire', randomBytes(24).toString('base64url')];
201
+ this._basicAuthSource = 'generated';
202
+ this.log.warn('No basic-auth password configured: WebService refuses every request and start() ' +
203
+ 'will throw. Set SWML_BASIC_AUTH_USER and SWML_BASIC_AUTH_PASSWORD, pass ' +
204
+ 'basicAuth: [user, password], or set security.auth.basic in the config file.');
205
+ }
125
206
  this.enableDirectoryBrowsing =
126
207
  options?.enableDirectoryBrowsing ?? fileConfig.enableDirectoryBrowsing ?? false;
127
- this.allowedExtensions =
128
- options?.allowedExtensions ?? fileConfig.allowedExtensions ?? null;
129
- this.blockedExtensions =
130
- options?.blockedExtensions ?? fileConfig.blockedExtensions ?? [...WebService.DEFAULT_BLOCKED];
208
+ this.allowedExtensions = options?.allowedExtensions ?? fileConfig.allowedExtensions ?? null;
209
+ this.blockedExtensions = options?.blockedExtensions ??
210
+ fileConfig.blockedExtensions ?? [...WebService.DEFAULT_BLOCKED];
131
211
  this.maxFileSize = options?.maxFileSize ?? fileConfig.maxFileSize ?? 100 * 1024 * 1024;
132
212
  this.enableCors = options?.enableCors ?? fileConfig.enableCors ?? true;
133
213
  this._ssl = new SslConfig(options?.ssl);
@@ -138,7 +218,8 @@ export class WebService {
138
218
  }
139
219
  // ── Public API ─────────────────────────────────────────────────────
140
220
  /**
141
- * Add a new directory to serve at a URL route prefix.
221
+ * Add a new directory to serve at a URL route prefix. Works before or after
222
+ * the service starts; the route serves from the next request.
142
223
  * @param route - URL prefix (e.g. '/docs').
143
224
  * @param directory - Local directory path to serve.
144
225
  * @throws If the directory does not exist or is not a directory.
@@ -153,19 +234,18 @@ export class WebService {
153
234
  throw new Error(`Path is not a directory: ${directory}`);
154
235
  }
155
236
  this.directories[r] = directory;
156
- this._mountSingleDirectory(r, directory);
237
+ this.log.info(`Serving static files from ${dirPath} at ${WebService._normalizeRoute(r)}`);
157
238
  }
158
239
  /**
159
- * Remove a previously added directory route from the bookkeeping map.
160
- *
161
- * Note: Hono does not support dynamic route removal; a server restart
162
- * is required for the route to fully stop responding.
240
+ * Stop serving a directory. The route stops responding at once, including
241
+ * on a running service.
163
242
  * @param route - The URL route prefix to remove.
164
243
  */
165
244
  removeDirectory(route) {
166
- const r = route.startsWith('/') ? route : `/${route}`;
167
- if (r in this.directories) {
168
- delete this.directories[r];
245
+ const r = WebService._normalizeRoute(route);
246
+ for (const key of Object.keys(this.directories)) {
247
+ if (WebService._normalizeRoute(key) === r)
248
+ delete this.directories[key];
169
249
  }
170
250
  }
171
251
  /**
@@ -196,6 +276,10 @@ export class WebService {
196
276
  * When `SWAIG_CLI_MODE=true` is set in the environment, the call is a
197
277
  * no-op so config can be inspected without binding a port.
198
278
  *
279
+ * @throws If no basic-auth credentials are configured (the `basicAuth`
280
+ * option, the config file's `security.auth.basic`, or
281
+ * `SWML_BASIC_AUTH_USER` / `SWML_BASIC_AUTH_PASSWORD`).
282
+ *
199
283
  * @param host - Bind address. Defaults to `'0.0.0.0'`.
200
284
  * @param port - Port override. Defaults to `this.port`.
201
285
  * @param sslCert - Path to SSL certificate file (overrides `SslConfig`).
@@ -206,6 +290,12 @@ export class WebService {
206
290
  // When loaded by the CLI tool, skip server startup.
207
291
  if (process.env['SWAIG_CLI_MODE'] === 'true')
208
292
  return;
293
+ if (this._basicAuthSource === 'generated') {
294
+ throw new Error('WebService needs basic-auth credentials: set SWML_BASIC_AUTH_USER and ' +
295
+ 'SWML_BASIC_AUTH_PASSWORD, pass basicAuth: [user, password], or set ' +
296
+ 'security.auth.basic in the config file. A generated password is never ' +
297
+ 'shown, so every file request would be refused.');
298
+ }
209
299
  const h = host ?? '0.0.0.0';
210
300
  const p = port ?? this.port;
211
301
  // Determine SSL configuration
@@ -217,7 +307,7 @@ export class WebService {
217
307
  this.log.info(`WebService starting on ${scheme}://${h}:${p}`);
218
308
  this.log.info(`Directories: ${Object.keys(this.directories).join(', ') || 'None'}`);
219
309
  this.log.info(`Directory Browsing: ${this.enableDirectoryBrowsing ? 'Enabled' : 'Disabled'}`);
220
- this.log.info(`Basic Auth: ${this._basicAuth ? 'Enabled' : 'Disabled'}`);
310
+ this.log.info(`Basic Auth: ${this._basicAuth[0]}:(credentials configured) (source: ${this._basicAuthSource})`);
221
311
  if (useHttps) {
222
312
  this.log.info('SSL: Enabled');
223
313
  }
@@ -255,19 +345,25 @@ export class WebService {
255
345
  /** Intermediate config shape returned by the file loader. */
256
346
  _loadConfig(configFile) {
257
347
  const result = {};
258
- if (!configFile) {
259
- // Search standard locations for a web-service config
260
- const loader = ConfigLoader.search('web_service.json');
348
+ // Without configFile, search the standard locations for a web-service
349
+ // config. A file that can't be read or parsed is skipped with a warning,
350
+ // whether it was passed or found, as the Python reference's ConfigLoader
351
+ // logs the error and continues without it.
352
+ try {
353
+ const loader = configFile
354
+ ? new ConfigLoader(configFile)
355
+ : ConfigLoader.search('web_service.json');
261
356
  if (!loader)
262
357
  return result;
263
- return this._extractServiceConfig(loader);
264
- }
265
- try {
266
- const loader = new ConfigLoader(configFile);
267
- return this._extractServiceConfig(loader);
358
+ const extracted = this._extractServiceConfig(loader);
359
+ const configPath = loader.getConfigFile();
360
+ if (configPath)
361
+ extracted.configPath = configPath;
362
+ return extracted;
268
363
  }
269
- catch {
270
- this.log.warn(`Failed to load config file: ${configFile}`);
364
+ catch (err) {
365
+ const reason = err instanceof Error ? err.message : String(err);
366
+ this.log.warn(`Failed to load config file: ${configFile ?? 'web_service.json'}: ${reason}`);
271
367
  return result;
272
368
  }
273
369
  }
@@ -311,7 +407,7 @@ export class WebService {
311
407
  // CORS
312
408
  if (this.enableCors) {
313
409
  const corsOrigins = process.env['SWML_CORS_ORIGINS'];
314
- const corsOrigin = corsOrigins ? corsOrigins.split(',').map((o) => o.trim()) : '*';
410
+ const corsOrigin = corsOriginsFromEnv(corsOrigins);
315
411
  const corsCredentials = corsOrigin !== '*';
316
412
  this._app.use('*', cors({ origin: corsOrigin, credentials: corsCredentials }));
317
413
  }
@@ -319,36 +415,54 @@ export class WebService {
319
415
  if (this._ssl.isConfigured()) {
320
416
  this._app.use('*', this._ssl.hstsMiddleware());
321
417
  }
322
- // Basic auth (applied to all routes if configured)
323
- if (this._basicAuth) {
324
- const [user, pass] = this._basicAuth;
325
- this._app.use('*', basicAuth({ username: user, password: pass }));
326
- }
327
- }
328
- // ── Route setup ────────────────────────────────────────────────────
329
- _setupRoutes() {
330
- // Health endpoint
418
+ // Health endpoint, which load balancers probe without credentials (as the
419
+ // Python reference and AgentBase do). It's registered before the auth
420
+ // middleware, so the handler itself is exempt: a path comparison would
421
+ // miss when a parent app mounts this one under a prefix.
331
422
  this._app.get('/health', (c) => c.json({
332
423
  status: 'healthy',
333
424
  directories: Object.keys(this.directories),
334
425
  sslEnabled: this._ssl.isConfigured(),
335
- authRequired: Boolean(this._basicAuth),
426
+ authRequired: true,
336
427
  directoryBrowsing: this.enableDirectoryBrowsing,
337
428
  }));
429
+ // Basic auth on every route registered after this point
430
+ const [user, pass] = this._basicAuth;
431
+ this._app.use('*', basicAuth({ username: user, password: pass }));
432
+ }
433
+ // ── Route setup ────────────────────────────────────────────────────
434
+ _setupRoutes() {
338
435
  // Root endpoint showing available directories
339
- this._app.get('/', (c) => {
340
- const dirEntries = Object.entries(this.directories);
341
- if (dirEntries.length === 0) {
342
- return c.json({
343
- service: 'SignalWire Web Service',
344
- directories: [],
345
- });
346
- }
347
- const items = dirEntries
348
- .map(([route, localPath]) => `<li><a href="${escapeHtml(route)}">${escapeHtml(route)}</a>` +
349
- ` <span class="path">&rarr; ${escapeHtml(localPath)}</span></li>`)
350
- .join('\n');
351
- const html = `<!DOCTYPE html>
436
+ // At this app's root; under a parent app's prefix, the path is the prefix
437
+ this._app.get('/', (c) => this._serveOverview(c, c.req.path.replace(/\/+$/, '')));
438
+ // Mounted directories: one handler that consults `directories` on each
439
+ // request, so mounts added or removed after the first request apply. The
440
+ // parameter captures the path below this app's root, which is how the
441
+ // prefix a parent app mounts this one under is found, however the
442
+ // parent's pattern is written. The wildcard route catches what the
443
+ // parameter can't match: `${prefix}/`, whose part below the root is
444
+ // empty, and on older Hono versions a part that starts with `/`.
445
+ this._app.get(`/:${TAIL_PARAM}{.+}`, (c) => this._serveMounted(c));
446
+ this._app.get('*', (c) => this._serveMounted(c));
447
+ }
448
+ /**
449
+ * The page at `/` that links to each mounted directory. Its links carry the
450
+ * prefix a parent app mounts this one under.
451
+ */
452
+ _serveOverview(c, base) {
453
+ const dirEntries = Object.entries(this.directories);
454
+ if (dirEntries.length === 0) {
455
+ return c.json({
456
+ service: 'SignalWire Web Service',
457
+ directories: [],
458
+ });
459
+ }
460
+ const items = dirEntries
461
+ .map(([route, localPath]) => `<li><a href="${escapeHtml(base + WebService._normalizeRoute(route))}">` +
462
+ `${escapeHtml(route)}</a>` +
463
+ ` <span class="path">&rarr; ${escapeHtml(localPath)}</span></li>`)
464
+ .join('\n');
465
+ const html = `<!DOCTYPE html>
352
466
  <html>
353
467
  <head>
354
468
  <title>SignalWire Web Service</title>
@@ -370,11 +484,15 @@ export class WebService {
370
484
  </ul>
371
485
  </body>
372
486
  </html>`;
373
- c.header('Content-Type', 'text/html');
374
- return c.body(html);
375
- });
487
+ c.header('Content-Type', 'text/html');
488
+ return c.body(html);
376
489
  }
377
490
  // ── Directory mounting ─────────────────────────────────────────────
491
+ /** Normalize a route prefix: leading slash, no trailing slash ('/' stays '/'). */
492
+ static _normalizeRoute(route) {
493
+ const withSlash = route.startsWith('/') ? route : `/${route}`;
494
+ return withSlash.replace(/\/+$/, '') || '/';
495
+ }
378
496
  _mountDirectories() {
379
497
  for (const [route, dir] of Object.entries(this.directories)) {
380
498
  const dirPath = resolve(dir);
@@ -382,76 +500,168 @@ export class WebService {
382
500
  this.log.warn(`Directory does not exist: ${dir}`);
383
501
  continue;
384
502
  }
385
- this._mountSingleDirectory(route, dir);
503
+ this.log.info(`Serving static files from ${dirPath} at ${WebService._normalizeRoute(route)}`);
386
504
  }
387
505
  }
388
- _mountSingleDirectory(route, directory) {
389
- const baseDir = resolve(directory);
390
- const routePrefix = route.replace(/\/+$/, '') || '/';
391
- this._app.get(`${routePrefix}/*`, async (c) => {
392
- const requestedPath = c.req.path.slice(routePrefix.length);
393
- // Path traversal protection: reject any path containing ".."
394
- if (requestedPath.includes('..')) {
395
- return c.json({ error: 'Forbidden' }, 403);
506
+ /**
507
+ * Find the mount serving a request path: the longest route prefix in
508
+ * `directories` that equals the path or is followed by `/` in it. Consulted
509
+ * on every request, so `addDirectory()` and `removeDirectory()` take effect
510
+ * at once.
511
+ */
512
+ _findMount(path) {
513
+ let best = null;
514
+ for (const [route, directory] of Object.entries(this.directories)) {
515
+ const prefix = WebService._normalizeRoute(route);
516
+ const matches = prefix === '/' ? true : path === prefix || path.startsWith(`${prefix}/`);
517
+ if (matches && (!best || prefix.length > best.prefix.length)) {
518
+ best = { prefix, directory };
519
+ }
520
+ }
521
+ return best;
522
+ }
523
+ /**
524
+ * Split the request path into the prefix a parent app mounts this one
525
+ * under with `route()` (Python's `root_path`; empty when it isn't mounted)
526
+ * and the path below it, which starts with `/`. The route parameter holds
527
+ * what this app's own route matched, decoded, so the prefix is the part of
528
+ * the path before the `/` whose remainder decodes to it. That holds however
529
+ * the parent's pattern is written (`/assets`, `/:tenant`,
530
+ * `/:tenant{[a-z]+}`), and puts the split at a path-segment boundary. The
531
+ * remainder keeps the path's own encoding, as `c.req.path` has it. Null if
532
+ * no split matches.
533
+ */
534
+ static _splitBase(c) {
535
+ // Reached through the wildcard route, the part below the root is taken
536
+ // to be empty, so only `${prefix}/` splits; anything else is a 404.
537
+ const tail = c.req.param(TAIL_PARAM) ?? '';
538
+ const path = c.req.path;
539
+ for (let i = path.indexOf('/'); i !== -1; i = path.indexOf('/', i + 1)) {
540
+ if (decodeParam(path.slice(i + 1)) === tail) {
541
+ return { base: path.slice(0, i), path: path.slice(i) };
396
542
  }
397
- const normalizedPath = normalize(requestedPath);
398
- const fullPath = resolve(join(baseDir, normalizedPath));
399
- // Double-check the resolved path is within the base directory
400
- if (!fullPath.startsWith(baseDir)) {
543
+ }
544
+ return null;
545
+ }
546
+ /**
547
+ * Serve a GET request under a mounted directory, or 404 when no mount
548
+ * matches. Every check sees the path below the parent app's prefix.
549
+ */
550
+ async _serveMounted(c) {
551
+ const split = WebService._splitBase(c);
552
+ if (!split)
553
+ return c.notFound();
554
+ const { path } = split;
555
+ const mount = this._findMount(path);
556
+ // `${prefix}/` under a parent app reaches this route rather than `/`
557
+ if (!mount)
558
+ return path === '/' ? this._serveOverview(c, split.base) : c.notFound();
559
+ const baseDir = resolve(mount.directory);
560
+ const requestedPath = mount.prefix === '/' ? path : path.slice(mount.prefix.length);
561
+ // Path traversal protection: reject any path containing "..", and any
562
+ // hidden or blocked component, whether the path exists or not.
563
+ if (requestedPath.includes('..') || !this._isPathAllowed(pathParts(requestedPath))) {
564
+ return c.json({ error: 'Forbidden' }, 403);
565
+ }
566
+ const normalizedPath = normalize(requestedPath);
567
+ const fullPath = resolve(join(baseDir, normalizedPath));
568
+ // Double-check the resolved path is within the base directory
569
+ if (!isWithin(fullPath, baseDir)) {
570
+ return c.json({ error: 'Forbidden' }, 403);
571
+ }
572
+ try {
573
+ // Symbolic links: the file actually read must be inside the mount's
574
+ // real root, so a link inside the mount can't serve a file outside it,
575
+ // and its path there passes the same component checks, so a link can't
576
+ // reach into a hidden or blocked directory either.
577
+ const realBase = await realpath(baseDir);
578
+ const realPath = await realpath(fullPath);
579
+ if (!isWithin(realPath, realBase) ||
580
+ !this._isPathAllowed(pathParts(relative(realBase, realPath)))) {
401
581
  return c.json({ error: 'Forbidden' }, 403);
402
582
  }
403
- try {
404
- const fileStat = await stat(fullPath);
405
- // Handle directory requests
406
- if (fileStat.isDirectory()) {
407
- if (!this.enableDirectoryBrowsing) {
408
- // Try index.html fallback
409
- const indexPath = join(fullPath, 'index.html');
410
- try {
411
- const idxStat = await stat(indexPath);
412
- if (idxStat.isFile() && this._isFileAllowed(indexPath, idxStat.size)) {
413
- return this._serveFile(c, indexPath);
414
- }
415
- }
416
- catch {
417
- // No index.html found
583
+ const fileStat = await stat(fullPath);
584
+ // Handle directory requests
585
+ if (fileStat.isDirectory()) {
586
+ // Relative links in a listing or an index page need the slash
587
+ if (!c.req.path.endsWith('/')) {
588
+ return c.redirect(sameOriginRedirect(c.req.url), 307);
589
+ }
590
+ if (!this.enableDirectoryBrowsing) {
591
+ // Try index.html fallback
592
+ const indexPath = join(fullPath, 'index.html');
593
+ try {
594
+ const idxStat = await stat(indexPath);
595
+ const idxReal = await realpath(indexPath);
596
+ if (isWithin(idxReal, realBase) &&
597
+ idxStat.isFile() &&
598
+ this._isServable(relative(baseDir, indexPath), relative(realBase, idxReal), idxStat.size)) {
599
+ return this._serveFile(c, indexPath);
418
600
  }
419
- return c.json({ error: 'Directory browsing disabled' }, 403);
420
601
  }
421
- return this._serveDirectoryListing(c, fullPath, c.req.path);
422
- }
423
- // Regular file
424
- if (!fileStat.isFile()) {
425
- return c.json({ error: 'Not found' }, 404);
426
- }
427
- if (!this._isFileAllowed(fullPath, fileStat.size)) {
428
- return c.json({ error: 'File type not allowed' }, 403);
602
+ catch {
603
+ // No index.html found
604
+ }
605
+ return c.json({ error: 'Directory browsing disabled' }, 403);
429
606
  }
430
- return this._serveFile(c, fullPath);
607
+ return this._serveDirectoryListing(c, fullPath, c.req.path, baseDir, realBase);
431
608
  }
432
- catch {
609
+ // Regular file
610
+ if (!fileStat.isFile()) {
433
611
  return c.json({ error: 'Not found' }, 404);
434
612
  }
435
- });
436
- this.log.info(`Serving static files from ${baseDir} at ${routePrefix}/*`);
613
+ if (!this._isServable(relative(baseDir, fullPath), relative(realBase, realPath), fileStat.size)) {
614
+ return c.json({ error: 'File type not allowed' }, 403);
615
+ }
616
+ return this._serveFile(c, fullPath);
617
+ }
618
+ catch {
619
+ return c.json({ error: 'Not found' }, 404);
620
+ }
437
621
  }
438
622
  // ── File checks ────────────────────────────────────────────────────
439
- _isFileAllowed(fullPath, size) {
623
+ /**
624
+ * Whether the components of a path below a mounted directory may be served.
625
+ * A component that starts with a dot is refused wherever it appears, so
626
+ * nothing under `.git` or `.ssh` is served and neither is a file such as
627
+ * `.env.production`. The exception is `.well-known`, the standard public
628
+ * location for ACME challenges and `security.txt`. Directory listings hide
629
+ * dot entries. A component equal to a blocked entry is refused too, so a
630
+ * blocked name covers a directory as well as a file.
631
+ */
632
+ _isPathAllowed(parts) {
633
+ const blocked = new Set(this.blockedExtensions);
634
+ return !parts.some((part) => (part.startsWith('.') && part !== '.well-known') || blocked.has(part));
635
+ }
636
+ /**
637
+ * Whether a file may be served. The path checks, size limit, blocklist and
638
+ * allowlist apply both to the path requested and to the file actually read
639
+ * (its canonical path), each relative to the mount, so a symbolic link such
640
+ * as `alias.txt -> .env` can't serve a blocked file under an allowed name.
641
+ */
642
+ _isServable(requestedRel, realRel, size) {
643
+ return this._isFileAllowed(requestedRel, size) && this._isFileAllowed(realRel, size);
644
+ }
645
+ /** Whether a file, by its path relative to the mount, may be served. */
646
+ _isFileAllowed(relPath, size) {
440
647
  // Check file size
441
648
  if (size > this.maxFileSize)
442
649
  return false;
443
- const ext = extname(fullPath).toLowerCase();
444
- const name = basename(fullPath);
650
+ // Hidden and blocked components anywhere below the mount
651
+ if (!this._isPathAllowed(pathParts(relPath)))
652
+ return false;
653
+ const ext = extname(relPath).toLowerCase();
654
+ const name = basename(relPath);
445
655
  // Check blocked extensions and names
446
656
  for (const blocked of this.blockedExtensions) {
447
657
  if (blocked.startsWith('.')) {
448
- // Check both as extension and as full name (for files like .env, .gitignore)
658
+ // As an extension (.key, .pem)
449
659
  if (ext === blocked || name === blocked)
450
660
  return false;
451
661
  }
452
662
  else {
453
663
  // Check as a file name or as a substring of the path
454
- if (name === blocked || fullPath.includes(blocked))
664
+ if (name === blocked || relPath.includes(blocked))
455
665
  return false;
456
666
  }
457
667
  }
@@ -471,11 +681,11 @@ export class WebService {
471
681
  return c.body(content);
472
682
  }
473
683
  // ── Directory listing ──────────────────────────────────────────────
474
- async _serveDirectoryListing(c, dirPath, urlPath) {
684
+ async _serveDirectoryListing(c, dirPath, urlPath, baseDir, realBase) {
475
685
  const entries = await readdir(dirPath, { withFileTypes: true });
476
- // Sort entries alphabetically
686
+ // Sort entries alphabetically, without hidden or blocked names
477
687
  const sorted = entries
478
- .filter((e) => !e.name.startsWith('.'))
688
+ .filter((e) => !e.name.startsWith('.') && this._isPathAllowed([e.name]))
479
689
  .sort((a, b) => a.name.localeCompare(b.name));
480
690
  const items = [];
481
691
  // Add parent directory link if not at root
@@ -494,7 +704,8 @@ export class WebService {
494
704
  const entryPath = join(dirPath, entry.name);
495
705
  try {
496
706
  const entryStat = await stat(entryPath);
497
- if (this._isFileAllowed(entryPath, entryStat.size)) {
707
+ const entryReal = await realpath(entryPath);
708
+ if (this._isServable(relative(baseDir, entryPath), relative(realBase, entryReal), entryStat.size)) {
498
709
  const safeName = escapeHtml(entry.name);
499
710
  const sizeStr = formatSize(entryStat.size);
500
711
  items.push(`<li><a href="${safeName}">${safeName}</a> (${sizeStr})</li>`);