@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,13 +8,15 @@
8
8
  import { Hono } from 'hono';
9
9
  import { cors } from 'hono/cors';
10
10
  import { basicAuth } from 'hono/basic-auth';
11
- import { randomBytes } from 'node:crypto';
11
+ import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
12
+ import { corsOriginsFromEnv } from './SecurityUtils.js';
12
13
  import { SwmlBuilder } from './SwmlBuilder.js';
13
14
  import { SchemaUtils } from './SchemaUtils.js';
14
15
  import { SslConfig } from './SslConfig.js';
15
16
  import { ConfigLoader } from './ConfigLoader.js';
16
17
  import { getLogger } from './Logger.js';
17
18
  import { SwaigFunction } from './SwaigFunction.js';
19
+ import { FunctionResult } from './FunctionResult.js';
18
20
  /**
19
21
  * Registry for custom SWML verb handlers.
20
22
  * Mirrors Python SDK's `VerbHandlerRegistry`.
@@ -52,6 +54,20 @@ export class SecurityConfig {
52
54
  basicAuthUser;
53
55
  /** Basic auth password from config, or null. */
54
56
  basicAuthPassword;
57
+ /**
58
+ * Where {@link basicAuthPassword} came from: `'environment'`
59
+ * (`SWML_BASIC_AUTH_PASSWORD`), `'config file'` (which takes precedence), or
60
+ * `null` when neither set one.
61
+ */
62
+ basicAuthSource;
63
+ /** Allowed request hosts (`['*']` = allow all). */
64
+ allowedHosts;
65
+ /** Allowed CORS origins. */
66
+ corsOrigins;
67
+ /** Whether to emit an HSTS header on HTTPS responses. */
68
+ useHsts;
69
+ /** HSTS `max-age` in seconds. */
70
+ hstsMaxAge;
55
71
  sslConfig;
56
72
  constructor(opts) {
57
73
  // Load SSL config from env vars / options
@@ -60,14 +76,50 @@ export class SecurityConfig {
60
76
  this.sslCertPath = this.sslConfig.certPath;
61
77
  this.sslKeyPath = this.sslConfig.keyPath;
62
78
  this.domain = this.sslConfig.domain;
63
- // Auth defaults from env vars
64
- this.basicAuthUser = process.env['SWML_BASIC_AUTH_USER'] ?? null;
65
- this.basicAuthPassword = process.env['SWML_BASIC_AUTH_PASSWORD'] ?? null;
79
+ // Auth + host/CORS/HSTS defaults from env vars
80
+ this.basicAuthUser = process.env['SWML_BASIC_AUTH_USER'] || null;
81
+ this.basicAuthPassword = process.env['SWML_BASIC_AUTH_PASSWORD'] || null;
82
+ this.basicAuthSource = this.basicAuthPassword ? 'environment' : null;
83
+ this.allowedHosts = ['*'];
84
+ this.corsOrigins = ['*'];
85
+ this.useHsts = true;
86
+ this.hstsMaxAge = 31536000;
87
+ this.loadFromEnv();
66
88
  // Load from config file if available
67
89
  if (opts?.configFile) {
68
90
  this.loadFromConfigFile(opts.configFile);
69
91
  }
70
92
  }
93
+ /** Split a comma-separated env value into a trimmed, non-empty list. */
94
+ static parseList(value) {
95
+ if (value === undefined)
96
+ return null;
97
+ const items = value
98
+ .split(',')
99
+ .map((s) => s.trim())
100
+ .filter((s) => s.length > 0);
101
+ return items.length > 0 ? items : null;
102
+ }
103
+ /**
104
+ * (Re)load host/CORS/HSTS settings from environment variables. Mirrors Python
105
+ * SDK's `SecurityConfig.load_from_env()`. SSL/auth are loaded in the constructor
106
+ * from their own env vars; this refreshes the network-policy fields.
107
+ */
108
+ loadFromEnv() {
109
+ const hosts = SecurityConfig.parseList(process.env['SWML_ALLOWED_HOSTS']);
110
+ if (hosts)
111
+ this.allowedHosts = hosts;
112
+ const cors = SecurityConfig.parseList(process.env['SWML_CORS_ORIGINS']);
113
+ if (cors)
114
+ this.corsOrigins = cors;
115
+ if (process.env['SWML_USE_HSTS'] !== undefined) {
116
+ this.useHsts = process.env['SWML_USE_HSTS'] === 'true';
117
+ }
118
+ const maxAge = process.env['SWML_HSTS_MAX_AGE'];
119
+ if (maxAge !== undefined && !Number.isNaN(Number(maxAge))) {
120
+ this.hstsMaxAge = Number(maxAge);
121
+ }
122
+ }
71
123
  loadFromConfigFile(filePath) {
72
124
  try {
73
125
  const loader = new ConfigLoader(filePath);
@@ -82,22 +134,35 @@ export class SecurityConfig {
82
134
  if (typeof ssl['domain'] === 'string')
83
135
  this.domain = ssl['domain'];
84
136
  }
85
- const auth = loader.get('security.basicAuth');
86
- if (auth) {
87
- if (typeof auth['user'] === 'string')
137
+ // `security.auth.basic` is the reference's key; `security.basicAuth` is
138
+ // this SDK's earlier spelling, still read. The config file takes
139
+ // precedence over the environment.
140
+ for (const key of ['security.basicAuth', 'security.auth.basic']) {
141
+ const auth = loader.get(key);
142
+ if (!auth || typeof auth !== 'object')
143
+ continue;
144
+ // An empty value sets nothing: an empty password would otherwise
145
+ // erase a working one from the environment and leave the service
146
+ // with no configured credentials.
147
+ if (typeof auth['user'] === 'string' && auth['user'])
88
148
  this.basicAuthUser = auth['user'];
89
- if (typeof auth['password'] === 'string')
149
+ if (typeof auth['password'] === 'string' && auth['password']) {
90
150
  this.basicAuthPassword = auth['password'];
151
+ this.basicAuthSource = 'config file';
152
+ }
91
153
  }
92
154
  }
93
155
  catch {
94
156
  // Config file load failures are non-fatal
95
157
  }
96
158
  }
97
- /** Get basic auth credentials from security config, or null if not configured. */
159
+ /**
160
+ * Get basic auth credentials from the config file or environment, or null
161
+ * when no password is configured. The user defaults to `signalwire`.
162
+ */
98
163
  getBasicAuth() {
99
- if (this.basicAuthUser && this.basicAuthPassword) {
100
- return [this.basicAuthUser, this.basicAuthPassword];
164
+ if (this.basicAuthPassword) {
165
+ return [this.basicAuthUser || 'signalwire', this.basicAuthPassword];
101
166
  }
102
167
  return null;
103
168
  }
@@ -111,6 +176,85 @@ export class SecurityConfig {
111
176
  return [false, 'SSL key path not configured'];
112
177
  return this.sslConfig.isConfigured() ? [true, null] : [false, 'SSL cert or key file not found'];
113
178
  }
179
+ /**
180
+ * Build the SSL parameters for the HTTPS server, as a plain dictionary of
181
+ * primitive filesystem paths. Mirrors Python's
182
+ * `SecurityConfig.get_ssl_context_kwargs()` verbatim: the reference targets
183
+ * uvicorn's `ssl_certfile`/`ssl_keyfile` kwargs, and this returns the exact
184
+ * same primitive path pair (the TS HTTPS server passes them to
185
+ * `node:https.createServer` / `readFileSync`). Returns an empty object when
186
+ * SSL is disabled or the cert/key files fail validation.
187
+ * @returns `{ ssl_certfile, ssl_keyfile }` path strings, or `{}` when unavailable.
188
+ */
189
+ getSslContextKwargs() {
190
+ if (!this.sslEnabled)
191
+ return {};
192
+ const [isValid] = this.validateSslConfig();
193
+ if (!isValid)
194
+ return {};
195
+ return {
196
+ ssl_certfile: this.sslCertPath,
197
+ ssl_keyfile: this.sslKeyPath,
198
+ };
199
+ }
200
+ /** Get the URL scheme based on SSL configuration. Mirrors Python's `get_url_scheme()`. */
201
+ getUrlScheme() {
202
+ return this.sslEnabled ? 'https' : 'http';
203
+ }
204
+ /**
205
+ * Check whether a host is allowed. Mirrors Python's `should_allow_host()`:
206
+ * a wildcard `*` in the allow-list permits any host.
207
+ */
208
+ shouldAllowHost(host) {
209
+ if (this.allowedHosts.includes('*'))
210
+ return true;
211
+ return this.allowedHosts.includes(host);
212
+ }
213
+ /**
214
+ * Get CORS configuration. Mirrors Python's `get_cors_config()`.
215
+ * @returns An object of CORS settings (origins, credentials, methods, headers).
216
+ */
217
+ getCorsConfig() {
218
+ return {
219
+ allow_origins: this.corsOrigins,
220
+ allow_credentials: true,
221
+ allow_methods: ['*'],
222
+ allow_headers: ['*'],
223
+ };
224
+ }
225
+ /**
226
+ * Get the security headers to add to responses. Mirrors Python's
227
+ * `get_security_headers()`; adds an HSTS header when the request is HTTPS and
228
+ * HSTS is enabled.
229
+ * @param isHttps - Whether the connection is over HTTPS.
230
+ */
231
+ getSecurityHeaders(isHttps = false) {
232
+ const headers = {
233
+ 'X-Content-Type-Options': 'nosniff',
234
+ 'X-Frame-Options': 'DENY',
235
+ 'X-XSS-Protection': '1; mode=block',
236
+ 'Referrer-Policy': 'strict-origin-when-cross-origin',
237
+ };
238
+ if (isHttps && this.useHsts) {
239
+ headers['Strict-Transport-Security'] = `max-age=${this.hstsMaxAge}; includeSubDomains`;
240
+ }
241
+ return headers;
242
+ }
243
+ /**
244
+ * Log the current security configuration. Mirrors Python's `log_config()`.
245
+ * @param serviceName - The service name to tag the log line with.
246
+ */
247
+ logConfig(serviceName) {
248
+ getLogger('SecurityConfig').info('security_config_loaded', {
249
+ service: serviceName,
250
+ ssl_enabled: this.sslEnabled,
251
+ domain: this.domain,
252
+ allowed_hosts: this.allowedHosts,
253
+ cors_origins: this.corsOrigins,
254
+ use_hsts: this.useHsts,
255
+ has_basic_auth: !!(this.basicAuthUser && this.basicAuthPassword),
256
+ });
257
+ }
114
258
  }
115
259
  // ── SWMLService class ──────────────────────────────────────────────────
116
260
  /**
@@ -136,6 +280,21 @@ export class SecurityConfig {
136
280
  * @see {@link SwmlBuilder} — the underlying SWML document builder
137
281
  * @see {@link AgentBase} — AI-powered alternative
138
282
  */
283
+ /**
284
+ * Services constructed while swaig-test imports a file (SWAIG_CLI_MODE). Kept
285
+ * on globalThis under a registered symbol, so it's one list even when the
286
+ * agent file loads its own copy of the SDK (a CommonJS file, or another
287
+ * build of the package) from the one swaig-test runs.
288
+ */
289
+ const cliLoadedServices = (globalThis[Symbol.for('signalwire.swaigTest.loadedServices')] ??= []);
290
+ /**
291
+ * The services constructed since the last call, while swaig-test was
292
+ * importing a file, in construction order; clears the list. Internal to the
293
+ * CLI's loader.
294
+ */
295
+ export function _takeCliLoadedServices() {
296
+ return cliLoadedServices.splice(0);
297
+ }
139
298
  export class SWMLService {
140
299
  /** Service display name. */
141
300
  name;
@@ -159,6 +318,10 @@ export class SWMLService {
159
318
  sslKeyPath;
160
319
  /** Schema validation utilities. Mirrors Python's `self.schema_utils`. */
161
320
  schemaUtils;
321
+ /** @internal The schema settings every SwmlBuilder this service creates uses. */
322
+ _builderSchemaOptions = {
323
+ enableValidation: true,
324
+ };
162
325
  /** Custom verb handler registry. Mirrors Python's `self.verb_registry`. */
163
326
  verbRegistry;
164
327
  swmlBuilder;
@@ -168,7 +331,7 @@ export class SWMLService {
168
331
  authCredentials;
169
332
  authSource = 'generated';
170
333
  /** Validate provided basic-auth credentials against the configured ones
171
- * using a constant-time comparison. (Python parity:
334
+ * using a constant-time comparison. (Python equivalent:
172
335
  * ``AuthMixin.validate_basic_auth(username, password)``.) */
173
336
  validateBasicAuth(username, password) {
174
337
  const [u, p] = this.authCredentials ?? ['', ''];
@@ -177,12 +340,9 @@ export class SWMLService {
177
340
  return this.timingSafeEqual(username, u) && this.timingSafeEqual(password, p);
178
341
  }
179
342
  timingSafeEqual(a, b) {
180
- if (a.length !== b.length)
181
- return false;
182
- let diff = 0;
183
- for (let i = 0; i < a.length; i++)
184
- diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
185
- return diff === 0;
343
+ // Compare digests, so neither the content nor the length leaks.
344
+ const digest = (v) => createHash('sha256').update(v, 'utf8').digest();
345
+ return timingSafeEqual(digest(a), digest(b));
186
346
  }
187
347
  _proxyUrlBase = process.env['SWML_PROXY_URL_BASE'] ?? null;
188
348
  _proxyUrlBaseFromEnv = !!process.env['SWML_PROXY_URL_BASE'];
@@ -193,6 +353,9 @@ export class SWMLService {
193
353
  // for DataMap-style functions. AgentBase reads/writes this same registry.
194
354
  toolRegistry = new Map();
195
355
  constructor(opts) {
356
+ // swaig-test finds services a file constructs without exporting them.
357
+ if (process.env['SWAIG_CLI_MODE'] === 'true')
358
+ cliLoadedServices.push(this);
196
359
  this.name = opts?.name ?? 'swml-service';
197
360
  this.route = opts?.route ?? '/';
198
361
  this.host = opts?.host ?? '0.0.0.0';
@@ -215,9 +378,14 @@ export class SWMLService {
215
378
  skipValidation,
216
379
  ...(opts?.schemaPath !== undefined ? { schemaPath: opts.schemaPath } : {}),
217
380
  });
381
+ // The builder that renders the SWML validates verbs with the same settings.
382
+ this._builderSchemaOptions = {
383
+ enableValidation: !skipValidation,
384
+ ...(opts?.schemaPath !== undefined ? { schemaPath: opts.schemaPath } : {}),
385
+ };
218
386
  // Verb handler registry
219
387
  this.verbRegistry = new VerbHandlerRegistry();
220
- // Auth resolution: provided > env > security config > generated
388
+ // Auth resolution: provided > config file > environment > generated
221
389
  // Track whether auth was explicitly provided (enforced on HTTP) vs auto-generated (available but not enforced)
222
390
  let enforceAuth = false;
223
391
  if (opts?.basicAuth) {
@@ -226,30 +394,25 @@ export class SWMLService {
226
394
  enforceAuth = true;
227
395
  }
228
396
  else {
229
- const envUser = process.env['SWML_BASIC_AUTH_USER'];
230
- const envPass = process.env['SWML_BASIC_AUTH_PASSWORD'];
231
- if (envUser && envPass) {
232
- this.authCredentials = [envUser, envPass];
233
- this.authSource = 'environment';
397
+ // The config file, then the environment: SecurityConfig applies that
398
+ // precedence and records which one supplied the password.
399
+ const configured = this.security.getBasicAuth();
400
+ if (configured) {
401
+ this.authCredentials = configured;
402
+ this.authSource = this.security.basicAuthSource ?? 'environment';
234
403
  enforceAuth = true;
235
404
  }
236
405
  else {
237
- const fromConfig = this.security.getBasicAuth();
238
- if (fromConfig) {
239
- this.authCredentials = fromConfig;
240
- this.authSource = 'environment';
241
- enforceAuth = true;
242
- }
243
- else {
244
- // Auto-generate credentials like AgentBase does
245
- const username = this.name.replace(/[^a-zA-Z0-9_-]/g, '_');
246
- this.authCredentials = [username, randomBytes(16).toString('hex')];
247
- this.authSource = 'generated';
248
- // Not enforced on HTTP — available via getBasicAuthCredentials()
249
- }
406
+ // Auto-generate credentials like AgentBase does
407
+ const username = this.name.replace(/[^a-zA-Z0-9_-]/g, '_');
408
+ this.authCredentials = [username, randomBytes(16).toString('hex')];
409
+ this.authSource = 'generated';
410
+ // Not enforced on HTTP — available via getBasicAuthCredentials()
250
411
  }
251
412
  }
252
- this.swmlBuilder = new SwmlBuilder();
413
+ // `service: this` is the builder's public back-reference (the reference's
414
+ // `SWMLBuilder(service)`), so a caller holding the builder can reach its service.
415
+ this.swmlBuilder = new SwmlBuilder({ service: this, ...this._builderSchemaOptions });
253
416
  this._app = new Hono();
254
417
  // Security headers
255
418
  this._app.use('*', async (c, next) => {
@@ -263,53 +426,22 @@ export class SWMLService {
263
426
  });
264
427
  // CORS — credentials only when origin is explicitly configured (wildcard + credentials violates spec)
265
428
  const corsOrigins = process.env['SWML_CORS_ORIGINS'];
266
- const corsOrigin = corsOrigins ? corsOrigins.split(',').map((o) => o.trim()) : '*';
429
+ const corsOrigin = corsOriginsFromEnv(corsOrigins);
267
430
  const corsCredentials = corsOrigin !== '*';
268
431
  this._app.use('*', cors({ origin: corsOrigin, credentials: corsCredentials }));
269
432
  // Basic auth — only enforced when explicitly provided or from env, not auto-generated
270
433
  if (enforceAuth && this.authCredentials) {
271
- const [user, pass] = this.authCredentials;
272
- this._app.use('*', basicAuth({ username: user, password: pass }));
434
+ this._app.use('*', basicAuth({
435
+ verifyUser: (username, password) => this.validateBasicAuth(username, password),
436
+ }));
273
437
  }
274
438
  // Health endpoints
275
439
  this._app.get('/health', (c) => c.json({ status: 'ok' }));
276
440
  this._app.get('/ready', (c) => c.json({ status: 'ready' }));
277
441
  // Main SWML endpoint — serves on both GET and POST
278
442
  const handler = async (c) => {
279
- let doc;
280
- // Always parse request params so onRequest() hook and onRequestCallback
281
- // can both receive them (mirrors Python's _handle_request param extraction).
282
- const url = new URL(c.req.url);
283
- const queryParams = {};
284
- url.searchParams.forEach((v, k) => { queryParams[k] = v; });
285
- let bodyParams = {};
286
- if (c.req.method === 'POST') {
287
- try {
288
- bodyParams = await c.req.json();
289
- }
290
- catch {
291
- // empty body is fine
292
- }
293
- }
294
- const headers = {};
295
- c.req.raw.headers.forEach((v, k) => { headers[k] = v; });
296
- // Protected override hook (Service-side SWML builder dispatch).
297
- // Try buildSwmlForRequest() first; if it returns a SwmlBuilder use
298
- // that document. This is distinct from WebMixin's onRequest hook
299
- // (a public 2-arg variant on AgentBase that mirrors Python's
300
- // on_request → on_swml_request delegation chain).
301
- const hookResult = this.buildSwmlForRequest(queryParams, bodyParams, headers);
302
- if (hookResult !== null) {
303
- doc = hookResult.getDocument();
304
- }
305
- else if (this.onRequestCallback) {
306
- const builder = await this.onRequestCallback(queryParams, bodyParams, headers);
307
- doc = builder.getDocument();
308
- }
309
- else {
310
- doc = this.swmlBuilder.getDocument();
311
- }
312
- return c.json(doc);
443
+ const { bodyParams, headers } = await this._readRequest(c);
444
+ return c.json(await this._documentForRequest(c, bodyParams, headers));
313
445
  };
314
446
  const routePath = this.route === '/' ? '/' : this.route;
315
447
  const swaigPath = this.route === '/' ? '/swaig' : `${this.route}/swaig`;
@@ -321,7 +453,7 @@ export class SWMLService {
321
453
  if (c.req.method === 'GET') {
322
454
  return handler(c);
323
455
  }
324
- let payload = {};
456
+ let payload;
325
457
  try {
326
458
  payload = (await c.req.json());
327
459
  }
@@ -338,7 +470,10 @@ export class SWMLService {
338
470
  // Argument extraction: nested {argument:{parsed}} OR flat {arguments}
339
471
  let args = {};
340
472
  const argument = payload['argument'];
341
- if (argument && typeof argument === 'object' && Array.isArray(argument['parsed']) && argument['parsed'].length > 0) {
473
+ if (argument &&
474
+ typeof argument === 'object' &&
475
+ Array.isArray(argument['parsed']) &&
476
+ argument['parsed'].length > 0) {
342
477
  const first = argument['parsed'][0];
343
478
  if (first && typeof first === 'object')
344
479
  args = first;
@@ -352,10 +487,15 @@ export class SWMLService {
352
487
  if (shortCircuit !== null && shortCircuit !== undefined) {
353
488
  return c.json(shortCircuit);
354
489
  }
355
- const result = target.onFunctionCall(fnName, args, payload);
490
+ // A handler may be async: await it, or its Promise serializes as {}.
491
+ const result = await target.onFunctionCall(fnName, args, payload);
356
492
  if (result === null || result === undefined) {
357
493
  return c.json({ error: `Unknown function: ${fnName}` }, 404);
358
494
  }
495
+ if (result instanceof FunctionResult)
496
+ return c.json(result.toDict());
497
+ if (typeof result === 'string')
498
+ return c.json(new FunctionResult(result).toDict());
359
499
  return c.json(result);
360
500
  };
361
501
  this._app.get(swaigPath, swaigHandler);
@@ -374,12 +514,27 @@ export class SWMLService {
374
514
  * parameter descriptions are LLM-facing prompt engineering — see
375
515
  * PORTING_GUIDE for guidance on writing them.
376
516
  *
377
- * Accepts the full SwaigFunctionOptions surface so AgentBase's richer
378
- * call sites (fillers, secure tokens, wait files, extra fields) work
379
- * without overriding this method on the subclass.
517
+ * Generic over the `parameters` schema (`P`) and `required` list (`R`): when
518
+ * `parameters` is written as a FLAT inline map (`{ name: { type, … } }`), the
519
+ * `const` type parameters capture its literals and the handler's `args` is
520
+ * inferred precisely — `args.phone` typed `string`, an `enum` prop narrowed to
521
+ * its literal union, `required` keys present and the rest optional (see
522
+ * {@link ToolArgs}/{@link InferArgs}). The WRAPPED JSON-Schema object
523
+ * (`{ type:'object', properties }`) and a pre-built `Record` are still
524
+ * accepted and keep the prior open-record `args` behavior. The args type is a
525
+ * compile-time authoring convenience — at runtime args is the JSON the model
526
+ * extracted, so the handler is the ordinary {@link SwaigHandler}.
380
527
  */
381
528
  defineTool(opts) {
382
- const fn = new SwaigFunction(opts);
529
+ const fn = new SwaigFunction({
530
+ ...opts,
531
+ parameters: opts.parameters,
532
+ required: opts.required,
533
+ // Single type-erasure boundary: at runtime the handler is the ordinary
534
+ // (args: Record<string,unknown>, rawData) SwaigHandler; the inferred-args
535
+ // view is compile-time only.
536
+ handler: opts.handler,
537
+ });
383
538
  this.toolRegistry.set(opts.name, fn);
384
539
  return this;
385
540
  }
@@ -417,17 +572,17 @@ export class SWMLService {
417
572
  return this.toolRegistry.has(name);
418
573
  }
419
574
  /** Whether a SWAIG function with the given name is registered.
420
- * (Python parity: ``ToolRegistry.has_function``.) */
575
+ * (Python equivalent: ``ToolRegistry.has_function``.) */
421
576
  hasFunction(name) {
422
577
  return this.toolRegistry.has(name);
423
578
  }
424
579
  /** Get a registered SWAIG function entry, or undefined.
425
- * (Python parity: ``ToolRegistry.get_function``.) */
580
+ * (Python equivalent: ``ToolRegistry.get_function``.) */
426
581
  getFunction(name) {
427
582
  return this.toolRegistry.get(name);
428
583
  }
429
584
  /** Snapshot of all registered SWAIG functions keyed by name.
430
- * (Python parity: ``ToolRegistry.get_all_functions``.) */
585
+ * (Python equivalent: ``ToolRegistry.get_all_functions``.) */
431
586
  getAllFunctions() {
432
587
  const out = {};
433
588
  for (const [name, fn] of this.toolRegistry) {
@@ -436,7 +591,7 @@ export class SWMLService {
436
591
  return out;
437
592
  }
438
593
  /** Remove a registered SWAIG function. Returns true when removed,
439
- * false when not found. (Python parity:
594
+ * false when not found. (Python equivalent:
440
595
  * ``ToolRegistry.remove_function``.) */
441
596
  removeFunction(name) {
442
597
  return this.toolRegistry.delete(name);
@@ -460,10 +615,12 @@ export class SWMLService {
460
615
  tools.push({ name, description: fn.description, parameters: fn.parameters });
461
616
  }
462
617
  else {
618
+ // DataMap.toSwaigFunction() writes description/parameters; a hand-built
619
+ // SWAIG dict may use the older purpose/argument names.
463
620
  tools.push({
464
621
  name,
465
- description: fn['purpose'] ?? '',
466
- parameters: fn['argument'] ?? {},
622
+ description: (fn['description'] ?? fn['purpose']) ?? '',
623
+ parameters: (fn['parameters'] ?? fn['argument']) ?? {},
467
624
  });
468
625
  }
469
626
  }
@@ -540,7 +697,7 @@ export class SWMLService {
540
697
  * @returns This service for chaining.
541
698
  */
542
699
  addSection(sectionName) {
543
- const doc = this.swmlBuilder.getDocument();
700
+ const doc = this.swmlBuilder.build();
544
701
  if (!(sectionName in doc.sections)) {
545
702
  doc.sections[sectionName] = [];
546
703
  }
@@ -578,15 +735,14 @@ export class SWMLService {
578
735
  * @returns The SWML document (object) or its serialized form (subclass).
579
736
  */
580
737
  renderSwml(_callId, _modifications) {
581
- return this.swmlBuilder.getDocument();
738
+ return this.swmlBuilder.build();
582
739
  }
583
740
  /**
584
- * Get the SWML document as a dictionary.
585
- * Alias for `renderSwml()` that matches Python's `get_document()` name.
741
+ * Get the SWML document as a dictionary. Matches Python's `get_document()`.
586
742
  * @returns The SWML document.
587
743
  */
588
744
  getDocument() {
589
- return this.swmlBuilder.getDocument();
745
+ return this.swmlBuilder.build();
590
746
  }
591
747
  /**
592
748
  * Render the SWML document as a JSON string.
@@ -594,7 +750,121 @@ export class SWMLService {
594
750
  * @returns JSON-encoded SWML document.
595
751
  */
596
752
  renderDocument() {
597
- return this.swmlBuilder.renderDocument();
753
+ return this.swmlBuilder.render();
754
+ }
755
+ /**
756
+ * Framework-free request-dispatch core.
757
+ *
758
+ * The primitive dispatch surface the SDK ports share (mirrors Python's
759
+ * `SWMLService.handle_request(method, url, headers, body)` and, e.g., the
760
+ * dotnet `(int, Dictionary, string) HandleRequest(...)`). It performs the
761
+ * routing-callback check, `on_request` modification, and basic-auth exactly as
762
+ * the Hono handler path does, but over plain primitives instead of Hono
763
+ * `Context`/`Response` objects — so both paths produce identical responses.
764
+ *
765
+ * @param method HTTP method, e.g. `"GET"` or `"POST"`.
766
+ * @param url The full request URL (used to derive the callback path).
767
+ * @param headers Request headers as a plain dict.
768
+ * @param body The already-parsed JSON body for POST requests, or `undefined`.
769
+ * @returns A `[status, responseHeaders, bodyString]` triple. For a routing
770
+ * redirect the status is 307 with a `Location` header and an empty body; an
771
+ * auth failure is 401 with `WWW-Authenticate: Basic`; otherwise 200 with the
772
+ * SWML document as the body string.
773
+ */
774
+ async handleRequest(method, url, headers, body) {
775
+ const parsedBody = body ?? {};
776
+ const callbackPath = this._callbackPathForUrl(url);
777
+ // Auth check over primitives.
778
+ if (!(await this._checkBasicAuthHeaders(headers))) {
779
+ return [401, { 'WWW-Authenticate': 'Basic' }, JSON.stringify({ error: 'Unauthorized' })];
780
+ }
781
+ // Routing callback: (body, headers) -> route | null. Only runs for a POST
782
+ // with a non-empty parsed body targeting a registered callback path.
783
+ if (method === 'POST' &&
784
+ Object.keys(parsedBody).length > 0 &&
785
+ callbackPath &&
786
+ this._routingCallbacks.has(callbackPath)) {
787
+ const callbackFn = this._routingCallbacks.get(callbackPath);
788
+ try {
789
+ const route = await callbackFn(parsedBody, headers);
790
+ if (route != null) {
791
+ this.log.info(`routing_request route=${route}`);
792
+ return [307, { Location: route }, ''];
793
+ }
794
+ }
795
+ catch (err) {
796
+ this.log.error(`error_in_routing_callback error=${err instanceof Error ? err.message : String(err)}`);
797
+ }
798
+ }
799
+ // Allow customized handling in subclasses (the SWML-builder hook analog of
800
+ // Python's on_request modification merge).
801
+ const queryParams = {};
802
+ try {
803
+ new URL(url).searchParams.forEach((v, k) => {
804
+ queryParams[k] = v;
805
+ });
806
+ }
807
+ catch {
808
+ /* url may be a bare path — no query params to extract */
809
+ }
810
+ const hookResult = this.buildSwmlForRequest(queryParams, parsedBody, headers, callbackPath ?? undefined);
811
+ if (hookResult !== null) {
812
+ return [200, {}, JSON.stringify(hookResult.build())];
813
+ }
814
+ return [200, {}, this.renderDocument()];
815
+ }
816
+ /**
817
+ * Derive the registered routing-callback path (if any) a URL targets. Mirrors
818
+ * Python's `_callback_path_for_url` — the primitive `handleRequest` recovers
819
+ * the equivalent of the router's `request.state.callback_path` by matching the
820
+ * URL's normalized path against the registered callbacks.
821
+ */
822
+ _callbackPathForUrl(url) {
823
+ if (this._routingCallbacks.size === 0)
824
+ return null;
825
+ let path = url;
826
+ try {
827
+ path = new URL(url).pathname;
828
+ }
829
+ catch {
830
+ /* bare path — use as-is */
831
+ }
832
+ // Collapse repeated slashes, as the router does when it picks the route,
833
+ // so /agent/handoff//next finds the callback registered at /handoff/next.
834
+ const trimmed = path.replace(/\/{2,}/g, '/').replace(/^\/+|\/+$/g, '');
835
+ const normalized = trimmed ? `/${trimmed}` : path.replace(/\/+$/, '');
836
+ for (const cbPath of this._routingCallbacks.keys()) {
837
+ if (normalized === cbPath || normalized.endsWith(cbPath))
838
+ return cbPath;
839
+ }
840
+ return null;
841
+ }
842
+ /**
843
+ * Validate HTTP basic-auth from a plain headers dict (the primitive analog of
844
+ * the Hono `basicAuth` middleware). Returns true when auth is not enforced or
845
+ * the provided credentials match.
846
+ */
847
+ async _checkBasicAuthHeaders(headers) {
848
+ // Auth is only enforced when credentials were explicitly provided or came
849
+ // from the environment; auto-generated credentials are not enforced.
850
+ if (!this.authCredentials || this.authSource === 'generated')
851
+ return true;
852
+ const authHeader = headers['authorization'] ?? headers['Authorization'];
853
+ if (!authHeader || !authHeader.startsWith('Basic '))
854
+ return false;
855
+ let decoded;
856
+ try {
857
+ decoded = Buffer.from(authHeader.slice(6), 'base64').toString('utf-8');
858
+ }
859
+ catch {
860
+ return false;
861
+ }
862
+ const idx = decoded.indexOf(':');
863
+ if (idx < 0)
864
+ return false;
865
+ const user = decoded.slice(0, idx);
866
+ const pass = decoded.slice(idx + 1);
867
+ return await this.validateBasicAuth(user, pass);
598
868
  }
599
869
  // ── Verb handler registration ────────────────────────────────────────
600
870
  /**
@@ -624,28 +894,65 @@ export class SWMLService {
624
894
  }
625
895
  this.log.info(`Registering routing callback at ${normalized}`);
626
896
  this._routingCallbacks.set(normalized, callbackFn);
627
- // Install an endpoint on the Hono app for this callback path
897
+ // Install an endpoint on the Hono app for this callback path. It runs
898
+ // this callback (awaited) for a POST, redirects with 307 when it returns
899
+ // a route, and otherwise serves the SWML for the request as the main
900
+ // route does, as the reference does. Auth is the app's middleware.
628
901
  const routeHandler = async (c) => {
629
- let body = {};
630
- if (c.req.method === 'POST') {
902
+ const { bodyParams, headers } = await this._readRequest(c);
903
+ if (c.req.method === 'POST' && Object.keys(bodyParams).length > 0) {
631
904
  try {
632
- body = await c.req.json();
905
+ const route = await callbackFn(bodyParams, headers);
906
+ if (route != null) {
907
+ this.log.info(`routing_request route=${route}`);
908
+ return c.redirect(route, 307);
909
+ }
633
910
  }
634
- catch {
635
- // empty body
911
+ catch (err) {
912
+ this.log.error(`error_in_routing_callback error=${err instanceof Error ? err.message : String(err)}`);
636
913
  }
637
914
  }
638
- const route = callbackFn(body);
639
- if (route !== null) {
640
- return c.redirect(route, 307);
641
- }
642
- // No redirect — serve normal SWML
643
- const doc = this.swmlBuilder.getDocument();
644
- return c.json(doc);
915
+ return c.json(await this._documentForRequest(c, bodyParams, headers));
645
916
  };
646
917
  this._app.get(normalized, routeHandler);
647
918
  this._app.post(normalized, routeHandler);
648
919
  }
920
+ /** The body (for a POST) and headers of a served request. */
921
+ async _readRequest(c) {
922
+ let bodyParams = {};
923
+ if (c.req.method === 'POST') {
924
+ try {
925
+ bodyParams = await c.req.json();
926
+ }
927
+ catch {
928
+ // empty body is fine
929
+ }
930
+ }
931
+ const headers = {};
932
+ c.req.raw.headers.forEach((v, k) => {
933
+ headers[k] = v;
934
+ });
935
+ return { bodyParams, headers };
936
+ }
937
+ /**
938
+ * The SWML document for a served request: buildSwmlForRequest(), then the
939
+ * setOnRequestCallback() callback, then the service's own document (as
940
+ * Python's _handle_request does).
941
+ */
942
+ async _documentForRequest(c, bodyParams, headers) {
943
+ const queryParams = {};
944
+ new URL(c.req.url).searchParams.forEach((v, k) => {
945
+ queryParams[k] = v;
946
+ });
947
+ const hookResult = this.buildSwmlForRequest(queryParams, bodyParams, headers);
948
+ if (hookResult !== null)
949
+ return hookResult.build();
950
+ if (this.onRequestCallback) {
951
+ const builder = await this.onRequestCallback(queryParams, bodyParams, headers);
952
+ return builder.build();
953
+ }
954
+ return this.swmlBuilder.build();
955
+ }
649
956
  // ── Static utilities ─────────────────────────────────────────────────
650
957
  /**
651
958
  * Extract the SIP username from a request body's call.to field.
@@ -661,7 +968,7 @@ export class SWMLService {
661
968
  return null;
662
969
  // Handle SIP URIs like "sip:username@domain" or "sips:username@domain"
663
970
  if (toField.startsWith('sip:') || toField.startsWith('sips:')) {
664
- let uri = toField.replace(/^sips?:/, '');
971
+ const uri = toField.replace(/^sips?:/, '');
665
972
  const atIdx = uri.indexOf('@');
666
973
  if (atIdx > 0)
667
974
  return uri.substring(0, atIdx);
@@ -748,23 +1055,28 @@ export class SWMLService {
748
1055
  return this._app;
749
1056
  }
750
1057
  /**
751
- * Alias for `getApp()`. Provided for cross-SDK consistency with Python's
752
- * `as_router()` method — allows Python callers porting to TypeScript to use
753
- * the familiar name without changes.
754
- * @returns The configured Hono app.
1058
+ * Get a router to embed this service's routes in a host web app.
1059
+ *
1060
+ * Returns the fully-wired Hono app as a mountable sub-app; the host mounts it
1061
+ * with `hostApp.route(path, service.asRouter())`. This is the TypeScript
1062
+ * realization of Python's `as_router()`; the named {@link HostAppRouter} type
1063
+ * is the cross-port "embed my routes in a host app" contract.
1064
+ *
1065
+ * @returns A mountable Hono sub-app carrying this service's routes.
755
1066
  */
756
1067
  asRouter() {
757
1068
  return this.getApp();
758
1069
  }
759
1070
  /**
760
- * Start the HTTP server.
1071
+ * Start the HTTP server. Canonical entrypoint, matching Python's
1072
+ * `SWMLService.serve()`.
761
1073
  *
762
1074
  * Matches Python's `serve()` parameters including SSL options. When
763
1075
  * `SWAIG_CLI_MODE=true` is set in the environment (e.g. while running the
764
1076
  * `swaig-test` CLI) the call is a no-op.
765
1077
  *
766
- * @param host - Hostname. Defaults to `this.host` (constructor value) or
767
- * `'0.0.0.0'`.
1078
+ * @param hostOrOpts - Hostname, or an options object. Defaults to `this.host`
1079
+ * (constructor value) or `'0.0.0.0'`.
768
1080
  * @param port - Port. Defaults to `this.port` (constructor value) or `3000`.
769
1081
  * @param opts - Optional SSL/TLS configuration overrides.
770
1082
  * @param opts.sslCert - Path to the PEM certificate file.
@@ -773,7 +1085,7 @@ export class SWMLService {
773
1085
  * @param opts.domain - Domain used for HSTS header configuration.
774
1086
  * @returns Resolves once the server has begun listening.
775
1087
  */
776
- async run(hostOrOpts, port, opts) {
1088
+ async serve(hostOrOpts, port, opts) {
777
1089
  if (process.env['SWAIG_CLI_MODE'] === 'true')
778
1090
  return;
779
1091
  // Normalize: accept either positional (host, port, opts) or single
@@ -792,6 +1104,13 @@ export class SWMLService {
792
1104
  opts = resolvedOpts;
793
1105
  const h = host ?? this.host;
794
1106
  const p = port ?? this.port;
1107
+ // A service with generated credentials doesn't require them (a TypeScript
1108
+ // divergence from the reference, which always does: PORT_BEHAVIORAL_NOTES.md).
1109
+ if (this.authSource === 'generated') {
1110
+ this.log.warn(`${this.name} is serving without basic auth: its credentials were generated, and ` +
1111
+ 'generated credentials are not enforced. Pass basicAuth, or set ' +
1112
+ 'SWML_BASIC_AUTH_USER and SWML_BASIC_AUTH_PASSWORD, to require them.');
1113
+ }
795
1114
  // Determine effective SSL state (param > instance > env)
796
1115
  const effectiveSslEnabled = opts?.sslEnabled ?? this.sslEnabled;
797
1116
  const effectiveSslCert = opts?.sslCert ?? this.sslCertPath;
@@ -817,17 +1136,6 @@ export class SWMLService {
817
1136
  this._server = serve({ fetch: this._app.fetch, port: p, hostname: h });
818
1137
  }
819
1138
  }
820
- /**
821
- * Start the HTTP server. Alias for {@link run} provided for cross-SDK
822
- * consistency with Python's `serve()` method — callers porting from
823
- * Python can use this name without changes.
824
- *
825
- * @param args - Forwarded unchanged to {@link run}.
826
- * @returns Resolves once the server has begun listening.
827
- */
828
- async serve(...args) {
829
- return this.run(...args);
830
- }
831
1139
  /**
832
1140
  * Stop the HTTP server.
833
1141
  * Mirrors Python's `stop()`.