@signalwire/sdk 2.0.4 → 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 +550 -163
  6. package/dist/AgentBase.js +1640 -514
  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 +163 -0
  30. package/dist/POM/PromptObjectModel.js +481 -0
  31. package/dist/POM/PromptObjectModel.js.map +1 -0
  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 +28 -0
  42. package/dist/PomBuilder.js +81 -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 +29 -1
  48. package/dist/PromptManager.js +37 -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 +265 -66
  58. package/dist/SWMLService.js +652 -112
  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 +55 -8
  64. package/dist/SecurityUtils.js +162 -49
  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 +95 -34
  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 -367
  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 +102 -39
  169. package/dist/index.js +107 -30
  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 +79 -14
  204. package/dist/relay/RelayClient.js +268 -61
  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 +81 -39
  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 +63 -0
  245. package/dist/rest/callHandler.js +62 -0
  246. package/dist/rest/callHandler.js.map +1 -0
  247. package/dist/rest/index.d.ts +19 -76
  248. package/dist/rest/index.js +49 -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 -273
  284. package/dist/rest/namespaces/fabric.js +14 -363
  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 +9 -57
  332. package/dist/rest/namespaces/phone-numbers.js +9 -63
  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 +47 -7
  412. package/dist/skills/SkillRegistry.js +85 -13
  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 +24 -8
  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 +34 -25
  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 +46 -1
  460. package/dist/skills/builtin/spider.js +317 -101
  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 +57 -31
  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 +301 -84
  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 +32 -14
  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 +65 -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 +88 -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
@@ -22,9 +22,11 @@ export declare function safeAssign<T extends Record<string, unknown>>(target: T,
22
22
  export declare function filterSensitiveHeaders(headers: Record<string, string>): Record<string, string>;
23
23
  /**
24
24
  * Redact credentials embedded in a URL (e.g. `https://user:secret@host` -> `https://user:****@host`).
25
- * Returns the URL unchanged if no credentials are present.
26
- * @param url - The URL string to redact.
27
- * @returns The URL with the password portion replaced by `****`.
25
+ * Masks the password of every URL in the string, including one with an empty
26
+ * user (`http://:secret@host`). Returns the string unchanged if no credentials
27
+ * are present.
28
+ * @param url - The URL string (or a message containing URLs) to redact.
29
+ * @returns The string with each URL's password replaced by `****`.
28
30
  */
29
31
  export declare function redactUrl(url: string): string;
30
32
  /**
@@ -34,17 +36,48 @@ export declare function redactUrl(url: string): string;
34
36
  */
35
37
  export declare function isValidHostname(host: string): boolean;
36
38
  /**
37
- * Check whether an IP address belongs to a private/reserved range.
38
- * Covers RFC1918, loopback, link-local, IPv6 private (fc/fd, ::1, fe80).
39
+ * Check whether an address is one a user-supplied URL must not reach: a
40
+ * private, loopback, link-local or reserved address, or the unspecified
41
+ * address (`0.0.0.0` or `::`), which connects to the local host.
42
+ *
43
+ * Accepts IPv6 in brackets (as `URL.hostname` gives it) and with a zone id.
44
+ * An IPv4-mapped IPv6 address (`::ffff:169.254.169.254`, in any spelling)
45
+ * reaches the IPv4 host, so the IPv4 address it carries is what's checked.
46
+ * A string that isn't an IP address returns `false`.
47
+ *
39
48
  * @param ip - The IP address string to check.
40
- * @returns True if the IP is private/reserved.
49
+ * @returns True if the address is private, internal or unspecified.
41
50
  */
42
51
  export declare function isPrivateIp(ip: string): boolean;
52
+ /** True when the caller or `SWML_ALLOW_PRIVATE_URLS` (1/true/yes) permits private addresses. */
53
+ export declare function _privateUrlsAllowed(allowPrivate?: boolean): boolean;
54
+ /** A DNS lookup returning every address for a hostname (`dns.promises.lookup` with `all`). */
55
+ export type _LookupAll = (hostname: string) => Promise<{
56
+ address: string;
57
+ family: number;
58
+ }[]>;
59
+ /**
60
+ * Check a URL a user or the model supplied before fetching it. Throws with a
61
+ * reason when the URL isn't http(s), has no hostname, can't be resolved, or
62
+ * resolves to any private or internal address. Shared by
63
+ * {@link resolveAndValidateUrl} and the SDK's URL-fetching skills.
64
+ *
65
+ * @param url - The URL to check.
66
+ * @param allowPrivate - Skip the address checks (so does `SWML_ALLOW_PRIVATE_URLS`).
67
+ * @param resolve - The DNS lookup to use; tests pass their own.
68
+ */
69
+ export declare function _checkUrl(url: string, allowPrivate?: boolean, resolve?: _LookupAll): Promise<void>;
43
70
  /**
44
- * DNS-resolve a URL's hostname and reject it if it points to a private IP.
71
+ * Check that a URL is safe to fetch, and throw if it isn't.
72
+ *
73
+ * The URL must be http or https, and its hostname must resolve, with every
74
+ * address it resolves to outside the private and internal ranges (see
75
+ * {@link isPrivateIp}). A hostname that can't be resolved is refused.
76
+ *
45
77
  * @param url - The full URL to validate.
46
78
  * @param allowPrivate - When true, skip the private-IP check (default false).
47
- * @throws If the resolved IP is private and `allowPrivate` is false.
79
+ * `SWML_ALLOW_PRIVATE_URLS` (1/true/yes) does the same.
80
+ * @throws If the URL is invalid, can't be resolved, or reaches a private address.
48
81
  */
49
82
  export declare function resolveAndValidateUrl(url: string, allowPrivate?: boolean): Promise<void>;
50
83
  /**
@@ -58,3 +91,17 @@ export declare function resolveAndValidateUrl(url: string, allowPrivate?: boolea
58
91
  * @returns `true` if the URL is safe to fetch, `false` otherwise.
59
92
  */
60
93
  export declare function validateUrl(url: string, allowPrivate?: boolean): Promise<boolean>;
94
+ /**
95
+ * Whether the current process is running in a serverless environment
96
+ * (anything other than a long-lived ``server`` runtime).
97
+ *
98
+ * Python equivalent: ``signalwire.utils.is_serverless_mode``.
99
+ */
100
+ export declare function isServerlessMode(): boolean;
101
+ /**
102
+ * The CORS `origin` option from `SWML_CORS_ORIGINS`: `'*'` when it's unset or
103
+ * lists `*` (which allows every origin, as the Python SDK reads it), else the
104
+ * listed origins.
105
+ * @internal
106
+ */
107
+ export declare function corsOriginsFromEnv(value?: string | undefined): '*' | string[];
@@ -5,6 +5,8 @@
5
5
  * URL credential redaction, hostname validation, and input length limits.
6
6
  */
7
7
  import { lookup } from 'node:dns/promises';
8
+ import { BlockList, isIP } from 'node:net';
9
+ import { getExecutionMode } from './Logger.js';
8
10
  /** Maximum allowed input length for skill handler arguments (characters). */
9
11
  export const MAX_SKILL_INPUT_LENGTH = 1000;
10
12
  /** Keys that must never be copied via object spread or assign. */
@@ -48,12 +50,14 @@ export function filterSensitiveHeaders(headers) {
48
50
  }
49
51
  /**
50
52
  * Redact credentials embedded in a URL (e.g. `https://user:secret@host` -> `https://user:****@host`).
51
- * Returns the URL unchanged if no credentials are present.
52
- * @param url - The URL string to redact.
53
- * @returns The URL with the password portion replaced by `****`.
53
+ * Masks the password of every URL in the string, including one with an empty
54
+ * user (`http://:secret@host`). Returns the string unchanged if no credentials
55
+ * are present.
56
+ * @param url - The URL string (or a message containing URLs) to redact.
57
+ * @returns The string with each URL's password replaced by `****`.
54
58
  */
55
59
  export function redactUrl(url) {
56
- return url.replace(/:\/\/([^:@]+):([^@]+)@/, '://$1:****@');
60
+ return url.replace(/:\/\/([^:@/]*):([^@/]*)@/g, '://$1:****@');
57
61
  }
58
62
  /**
59
63
  * Validate that a hostname string does not contain whitespace, slashes, or control characters.
@@ -64,72 +68,156 @@ export function isValidHostname(host) {
64
68
  if (!host || host.length === 0)
65
69
  return false;
66
70
  // Reject whitespace, slashes, control chars
71
+ // eslint-disable-next-line no-control-regex -- intentional control-char rejection in hostname validation
67
72
  return !/[\s/\\]/.test(host) && !/[\x00-\x1f\x7f]/.test(host);
68
73
  }
74
+ /** Private and reserved networks a user-supplied URL must not reach. */
75
+ const BLOCKED_NETWORKS = (() => {
76
+ const list = new BlockList();
77
+ list.addSubnet('10.0.0.0', 8, 'ipv4');
78
+ list.addSubnet('172.16.0.0', 12, 'ipv4');
79
+ list.addSubnet('192.168.0.0', 16, 'ipv4');
80
+ list.addSubnet('127.0.0.0', 8, 'ipv4');
81
+ list.addSubnet('169.254.0.0', 16, 'ipv4'); // link-local, including cloud metadata
82
+ list.addSubnet('0.0.0.0', 8, 'ipv4');
83
+ list.addAddress('::1', 'ipv6');
84
+ list.addSubnet('fc00::', 7, 'ipv6'); // IPv6 private
85
+ list.addSubnet('fe80::', 10, 'ipv6'); // IPv6 link-local
86
+ return list;
87
+ })();
69
88
  /**
70
- * Check whether an IP address belongs to a private/reserved range.
71
- * Covers RFC1918, loopback, link-local, IPv6 private (fc/fd, ::1, fe80).
89
+ * Expand an IPv6 address to its eight 16-bit groups, or `null` if it isn't
90
+ * one. Handles `::` compression and a trailing dotted IPv4 part.
91
+ */
92
+ function ipv6Groups(addr) {
93
+ if (isIP(addr) !== 6)
94
+ return null;
95
+ // Rewrite a trailing dotted IPv4 part (::ffff:1.2.3.4) as two hex groups.
96
+ const text = addr.replace(/(\d+)\.(\d+)\.(\d+)\.(\d+)$/, (_m, a, b, c, d) => {
97
+ const hi = ((Number(a) << 8) | Number(b)).toString(16);
98
+ const lo = ((Number(c) << 8) | Number(d)).toString(16);
99
+ return `${hi}:${lo}`;
100
+ });
101
+ const parse = (part) => (part ? part.split(':').map((g) => parseInt(g, 16)) : []);
102
+ let groups;
103
+ if (text.includes('::')) {
104
+ const [head = '', tail = ''] = text.split('::');
105
+ const left = parse(head);
106
+ const right = parse(tail);
107
+ groups = [...left, ...new Array(8 - left.length - right.length).fill(0), ...right];
108
+ }
109
+ else {
110
+ groups = parse(text);
111
+ }
112
+ return groups.length === 8 ? groups : null;
113
+ }
114
+ /**
115
+ * Check whether an address is one a user-supplied URL must not reach: a
116
+ * private, loopback, link-local or reserved address, or the unspecified
117
+ * address (`0.0.0.0` or `::`), which connects to the local host.
118
+ *
119
+ * Accepts IPv6 in brackets (as `URL.hostname` gives it) and with a zone id.
120
+ * An IPv4-mapped IPv6 address (`::ffff:169.254.169.254`, in any spelling)
121
+ * reaches the IPv4 host, so the IPv4 address it carries is what's checked.
122
+ * A string that isn't an IP address returns `false`.
123
+ *
72
124
  * @param ip - The IP address string to check.
73
- * @returns True if the IP is private/reserved.
125
+ * @returns True if the address is private, internal or unspecified.
74
126
  */
75
127
  export function isPrivateIp(ip) {
76
- // IPv4
77
- if (/^127\./.test(ip))
78
- return true;
79
- if (/^10\./.test(ip))
80
- return true;
81
- if (/^172\.(1[6-9]|2\d|3[01])\./.test(ip))
82
- return true;
83
- if (/^192\.168\./.test(ip))
84
- return true;
85
- if (/^169\.254\./.test(ip))
86
- return true;
87
- if (ip === '0.0.0.0')
88
- return true;
89
- // IPv6
90
- if (ip === '::1')
91
- return true;
92
- if (/^f[cd]/i.test(ip))
128
+ let addr = ip.trim();
129
+ if (addr.startsWith('[') && addr.endsWith(']'))
130
+ addr = addr.slice(1, -1);
131
+ const zone = addr.indexOf('%');
132
+ if (zone !== -1)
133
+ addr = addr.slice(0, zone);
134
+ const family = isIP(addr);
135
+ if (family === 4)
136
+ return BLOCKED_NETWORKS.check(addr, 'ipv4');
137
+ if (family !== 6)
138
+ return false;
139
+ const groups = ipv6Groups(addr);
140
+ if (!groups)
141
+ return false;
142
+ if (groups.every((g) => g === 0))
93
143
  return true;
94
- if (/^fe80/i.test(ip))
144
+ const mapped = groups.slice(0, 5).every((g) => g === 0) && groups[5] === 0xffff;
145
+ if (mapped) {
146
+ const v4 = [groups[6] >> 8, groups[6] & 0xff, groups[7] >> 8, groups[7] & 0xff].join('.');
147
+ return BLOCKED_NETWORKS.check(v4, 'ipv4');
148
+ }
149
+ return BLOCKED_NETWORKS.check(addr, 'ipv6');
150
+ }
151
+ /** True when the caller or `SWML_ALLOW_PRIVATE_URLS` (1/true/yes) permits private addresses. */
152
+ export function _privateUrlsAllowed(allowPrivate = false) {
153
+ if (allowPrivate)
95
154
  return true;
96
- return false;
155
+ const env = (process.env['SWML_ALLOW_PRIVATE_URLS'] ?? '').toLowerCase();
156
+ return env === '1' || env === 'true' || env === 'yes';
97
157
  }
158
+ const lookupAll = (hostname) => lookup(hostname, { all: true });
98
159
  /**
99
- * DNS-resolve a URL's hostname and reject it if it points to a private IP.
100
- * @param url - The full URL to validate.
101
- * @param allowPrivate - When true, skip the private-IP check (default false).
102
- * @throws If the resolved IP is private and `allowPrivate` is false.
160
+ * Check a URL a user or the model supplied before fetching it. Throws with a
161
+ * reason when the URL isn't http(s), has no hostname, can't be resolved, or
162
+ * resolves to any private or internal address. Shared by
163
+ * {@link resolveAndValidateUrl} and the SDK's URL-fetching skills.
164
+ *
165
+ * @param url - The URL to check.
166
+ * @param allowPrivate - Skip the address checks (so does `SWML_ALLOW_PRIVATE_URLS`).
167
+ * @param resolve - The DNS lookup to use; tests pass their own.
103
168
  */
104
- export async function resolveAndValidateUrl(url, allowPrivate = false) {
105
- if (allowPrivate)
106
- return;
107
- let hostname;
169
+ export async function _checkUrl(url, allowPrivate = false, resolve = lookupAll) {
170
+ let parsed;
108
171
  try {
109
- hostname = new URL(url).hostname;
172
+ parsed = new URL(url);
110
173
  }
111
174
  catch {
112
- throw new Error(`Invalid URL: ${url}`);
175
+ throw new Error(`Invalid URL: ${redactUrl(url)}`);
113
176
  }
114
- // Direct IP check first
115
- if (isPrivateIp(hostname)) {
116
- throw new Error(`URL resolves to a private IP address: ${hostname}`);
177
+ if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
178
+ throw new Error(`URL rejected: invalid scheme ${parsed.protocol}`);
117
179
  }
118
- // DNS resolution
119
- try {
120
- const result = await lookup(hostname);
121
- if (isPrivateIp(result.address)) {
122
- throw new Error(`URL hostname '${hostname}' resolves to private IP: ${result.address}`);
180
+ let hostname = parsed.hostname;
181
+ if (hostname.startsWith('[') && hostname.endsWith(']'))
182
+ hostname = hostname.slice(1, -1);
183
+ if (!hostname)
184
+ throw new Error('URL rejected: no hostname');
185
+ if (_privateUrlsAllowed(allowPrivate))
186
+ return;
187
+ if (isIP(hostname)) {
188
+ if (isPrivateIp(hostname)) {
189
+ throw new Error(`URL rejected: ${hostname} is a private IP address`);
123
190
  }
191
+ return;
192
+ }
193
+ let addresses;
194
+ try {
195
+ addresses = await resolve(hostname);
124
196
  }
125
- catch (err) {
126
- // Re-throw our own errors; DNS failures are allowed (host may not resolve in test)
127
- if (err instanceof Error && err.message.includes('private IP')) {
128
- throw err;
197
+ catch {
198
+ throw new Error(`URL rejected: could not resolve hostname ${hostname}`);
199
+ }
200
+ for (const { address } of addresses) {
201
+ if (isPrivateIp(address)) {
202
+ throw new Error(`URL rejected: ${hostname} resolves to private IP ${address}`);
129
203
  }
130
- // DNS lookup failure - let the actual HTTP request handle it
131
204
  }
132
205
  }
206
+ /**
207
+ * Check that a URL is safe to fetch, and throw if it isn't.
208
+ *
209
+ * The URL must be http or https, and its hostname must resolve, with every
210
+ * address it resolves to outside the private and internal ranges (see
211
+ * {@link isPrivateIp}). A hostname that can't be resolved is refused.
212
+ *
213
+ * @param url - The full URL to validate.
214
+ * @param allowPrivate - When true, skip the private-IP check (default false).
215
+ * `SWML_ALLOW_PRIVATE_URLS` (1/true/yes) does the same.
216
+ * @throws If the URL is invalid, can't be resolved, or reaches a private address.
217
+ */
218
+ export async function resolveAndValidateUrl(url, allowPrivate = false) {
219
+ await _checkUrl(url, allowPrivate);
220
+ }
133
221
  /**
134
222
  * Validate that a URL is safe to fetch (not pointing to private/internal resources).
135
223
  *
@@ -149,4 +237,29 @@ export async function validateUrl(url, allowPrivate = false) {
149
237
  return false;
150
238
  }
151
239
  }
240
+ /**
241
+ * Whether the current process is running in a serverless environment
242
+ * (anything other than a long-lived ``server`` runtime).
243
+ *
244
+ * Python equivalent: ``signalwire.utils.is_serverless_mode``.
245
+ */
246
+ export function isServerlessMode() {
247
+ const mode = getExecutionMode();
248
+ return mode !== 'server';
249
+ }
250
+ /**
251
+ * The CORS `origin` option from `SWML_CORS_ORIGINS`: `'*'` when it's unset or
252
+ * lists `*` (which allows every origin, as the Python SDK reads it), else the
253
+ * listed origins.
254
+ * @internal
255
+ */
256
+ export function corsOriginsFromEnv(value = process.env['SWML_CORS_ORIGINS']) {
257
+ if (!value)
258
+ return '*';
259
+ const list = value
260
+ .split(',')
261
+ .map((o) => o.trim())
262
+ .filter(Boolean);
263
+ return list.length === 0 || list.includes('*') ? '*' : list;
264
+ }
152
265
  //# sourceMappingURL=SecurityUtils.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"SecurityUtils.js","sourceRoot":"","sources":["../src/SecurityUtils.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"SecurityUtils.js","sourceRoot":"","sources":["../src/SecurityUtils.ts"],"names":[],"mappings":"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"}
@@ -16,15 +16,92 @@ export interface ServerlessEvent {
16
16
  headers?: Record<string, string>;
17
17
  /** Request body, either raw JSON string or parsed object. */
18
18
  body?: string | Record<string, unknown>;
19
+ /** When true, `body` is base64-encoded (AWS API Gateway proxy integration). */
20
+ isBase64Encoded?: boolean;
19
21
  /** Request path. */
20
22
  path?: string;
21
23
  /** Raw request path (AWS API Gateway v2). */
22
24
  rawPath?: string;
23
25
  /** Query string parameters as key-value pairs. */
24
26
  queryStringParameters?: Record<string, string>;
27
+ /** Repeated query parameters (AWS API Gateway REST). */
28
+ multiValueQueryStringParameters?: Record<string, string[]>;
29
+ /** The raw, still-encoded query string (AWS API Gateway v2 and function URLs). */
30
+ rawQueryString?: string;
31
+ /** Path parameters; `proxy` is the path below a `{proxy+}` resource (AWS API Gateway REST). */
32
+ pathParameters?: Record<string, string>;
25
33
  /** Platform-specific request context metadata. */
26
34
  requestContext?: Record<string, unknown>;
27
35
  }
36
+ /** Minimal Google Cloud Functions request shape (Express-style) consumed by {@link ServerlessAdapter.createGcfHandler}. */
37
+ interface GcfRequest {
38
+ method?: string;
39
+ headers?: Record<string, string>;
40
+ body?: string | Record<string, unknown>;
41
+ /** The unparsed request body, as the platform received it. */
42
+ rawBody?: Buffer | string;
43
+ path?: string;
44
+ url?: string;
45
+ originalUrl?: string;
46
+ protocol?: string;
47
+ /** The client's address (Express). */
48
+ ip?: string;
49
+ socket?: {
50
+ remoteAddress?: string;
51
+ };
52
+ }
53
+ /** Minimal Google Cloud Functions response shape (Express-style) consumed by {@link ServerlessAdapter.createGcfHandler}. */
54
+ interface GcfResponse {
55
+ status(code: number): void;
56
+ set(field: string, value: string): void;
57
+ send(body: string): void;
58
+ }
59
+ /** Minimal Azure Functions request shape consumed by {@link ServerlessAdapter.createAzureHandler}. */
60
+ interface AzureRequest {
61
+ method?: string;
62
+ headers?: Record<string, string>;
63
+ body?: string | Record<string, unknown>;
64
+ /** The unparsed request body, as the platform received it. */
65
+ rawBody?: Buffer | string;
66
+ url?: string;
67
+ }
68
+ /**
69
+ * A URL a serverless request's webhook signature may have been computed over,
70
+ * with the path and query below the app's root to join to `SWML_PROXY_URL_BASE`.
71
+ * The adapter passes these to the app in Hono's `env` (see
72
+ * {@link _SIGNATURE_TARGETS_ENV_KEY}), where a client can't set them.
73
+ */
74
+ export interface _SignatureTarget {
75
+ /** The full URL the platform received the request on. */
76
+ url: string;
77
+ /** The path below the app's root, with the query, e.g. `/swaig?x=1`. */
78
+ pathAndQuery: string;
79
+ }
80
+ /** The Hono `env` key under which the adapter passes {@link _SignatureTarget}s. */
81
+ export declare const _SIGNATURE_TARGETS_ENV_KEY = "signalwireSignatureTargets";
82
+ /**
83
+ * The Hono `env` key under which the adapter passes the base URL the platform
84
+ * serves the function on, when the request shows it (Azure's
85
+ * `https://<app>.azurewebsites.net/api/<function>`, a Google Cloud Function's
86
+ * origin). An agent renders its webhook URLs from it, unless
87
+ * `SWML_PROXY_URL_BASE` is set.
88
+ */
89
+ export declare const _PLATFORM_BASE_ENV_KEY = "signalwirePlatformBase";
90
+ /**
91
+ * Hono env key for the client's address as the platform reports it (Lambda's
92
+ * requestContext source IP, a Cloud Function request's `ip`, CGI's
93
+ * REMOTE_ADDR), which the agent's rate limit keys on.
94
+ * @internal
95
+ */
96
+ export declare const _CLIENT_ADDRESS_ENV_KEY = "signalwireClientAddress";
97
+ /** Minimal Azure Functions invocation context consumed by {@link ServerlessAdapter.createAzureHandler}. */
98
+ interface AzureContext {
99
+ res?: {
100
+ status: number;
101
+ headers: Record<string, string>;
102
+ body: string;
103
+ };
104
+ }
28
105
  /** Normalized outgoing response returned to a serverless platform. */
29
106
  export interface ServerlessResponse {
30
107
  /** HTTP status code. */
@@ -47,7 +124,7 @@ export interface ServerlessResponse {
47
124
  * const agent = new AgentBase({ name: 'lambda', route: '/' });
48
125
  * agent.setPromptText('You are a helpful assistant.');
49
126
  *
50
- * const adapter = new ServerlessAdapter('aws');
127
+ * const adapter = new ServerlessAdapter('lambda');
51
128
  *
52
129
  * export const handler = async (event: any) => {
53
130
  * return adapter.handleRequest(agent.asRouter(), event);
@@ -73,13 +150,27 @@ export declare class ServerlessAdapter {
73
150
  getPlatform(): ServerlessPlatform;
74
151
  /**
75
152
  * Convert a serverless event into a standard Request, route it through the Hono app, and return a normalized response.
153
+ *
154
+ * The app also receives, in its `env`, the URL the platform was called on,
155
+ * so a webhook signature is checked against the URL SignalWire signed: with
156
+ * an API Gateway stage or other platform prefix, and the query as the
157
+ * platform received it (for API Gateway REST, which decodes the query, both
158
+ * common encodings are tried).
159
+ *
76
160
  * @param app - A Hono-compatible application with a `fetch` method.
77
161
  * @param event - The incoming serverless event to process.
78
162
  * @returns The normalized serverless response.
79
163
  */
80
164
  handleRequest(app: {
81
- fetch: (req: Request) => Promise<Response>;
165
+ fetch: (req: Request, env?: Record<string, unknown>) => Response | Promise<Response>;
82
166
  }, event: ServerlessEvent): Promise<ServerlessResponse>;
167
+ /**
168
+ * Reduce a Lambda-style event (a function URL, API Gateway REST or HTTP API
169
+ * event, or a hand-built event) to a {@link PlatformRequest}.
170
+ */
171
+ private static fromEvent;
172
+ /** Route one reduced request through the app and normalize its response. */
173
+ private dispatch;
83
174
  /**
84
175
  * Generate the platform-specific invocation URL for a deployed function.
85
176
  * @param opts - Optional overrides for region, project, function name, stage, or API ID.
@@ -98,7 +189,7 @@ export declare class ServerlessAdapter {
98
189
  * @returns A function that accepts a Lambda event and returns a promise of a serverless response.
99
190
  */
100
191
  static createLambdaHandler(app: {
101
- fetch: (req: Request) => Promise<Response>;
192
+ fetch: (req: Request, env?: Record<string, unknown>) => Response | Promise<Response>;
102
193
  }): (event: ServerlessEvent) => Promise<ServerlessResponse>;
103
194
  /**
104
195
  * Create a Google Cloud Functions-compatible handler from a Hono app.
@@ -106,14 +197,72 @@ export declare class ServerlessAdapter {
106
197
  * @returns A function that accepts GCF request/response objects.
107
198
  */
108
199
  static createGcfHandler(app: {
109
- fetch: (req: Request) => Promise<Response>;
110
- }): (req: any, res: any) => Promise<void>;
200
+ fetch: (req: Request, env?: Record<string, unknown>) => Response | Promise<Response>;
201
+ }): (req: GcfRequest, res: GcfResponse) => Promise<void>;
202
+ /**
203
+ * Reduce a Google Cloud Functions (Express-style) request. The signature is
204
+ * checked over the raw body, since a re-serialized parsed body can differ
205
+ * from the bytes SignalWire signed, and over the URL with its query.
206
+ */
207
+ private static fromGcfRequest;
208
+ /**
209
+ * Reduce an Azure Functions request. Its URL is absolute, e.g.
210
+ * `https://app.azurewebsites.net/api/<function>/swaig?code=...`; the path
211
+ * below `/api/<function>` is routed, and the whole URL is what was signed.
212
+ */
213
+ private static fromAzureRequest;
214
+ /**
215
+ * Reduce a CGI request from its environment and the body read from stdin.
216
+ * `PATH_INFO` is routed; the signed URL includes the script's own path
217
+ * (`SCRIPT_NAME`), as `REQUEST_URI` gives it.
218
+ */
219
+ private static fromCgiEnv;
220
+ /** Maximum CGI request body size (10MB), matching Python's `MAX_CGI_BODY_SIZE`. */
221
+ static readonly MAX_CGI_BODY_SIZE: number;
222
+ /**
223
+ * Build a {@link ServerlessEvent} from a CGI environment + request body.
224
+ *
225
+ * CGI has no "event" object: the request is described by environment variables
226
+ * (`REQUEST_METHOD`, `PATH_INFO`, `QUERY_STRING`, `CONTENT_TYPE`, `HTTP_*`) and
227
+ * the body arrives on stdin. This reconstructs the normalized event so a CGI
228
+ * invocation dispatches through the same Hono routing as Lambda/GCF/Azure
229
+ * (mirrors Python `serverless_mixin` CGI mode: `PATH_INFO` + stdin body).
230
+ *
231
+ * @param env - The process environment (defaults to `process.env`).
232
+ * @param body - The already-read request body from stdin (optional).
233
+ * @returns A normalized serverless event.
234
+ */
235
+ static buildCgiEvent(env?: NodeJS.ProcessEnv, body?: string): ServerlessEvent;
236
+ /**
237
+ * Create a CGI handler that reads the request from the CGI environment + stdin,
238
+ * routes it through the Hono app, and writes a CGI response (status line,
239
+ * headers, blank line, body) to stdout.
240
+ *
241
+ * @param app - A Hono-compatible application with a `fetch` method.
242
+ * @returns An async function that performs one CGI request/response cycle.
243
+ */
244
+ static createCgiHandler(app: {
245
+ fetch: (req: Request, env?: Record<string, unknown>) => Response | Promise<Response>;
246
+ }): () => Promise<void>;
247
+ /**
248
+ * Run one CGI request/response cycle: read the body from stdin, route the
249
+ * request, write the CGI response to stdout, and return it.
250
+ * @internal Used by {@link createCgiHandler} and `AgentBase.runServerless`.
251
+ */
252
+ _runCgi(app: {
253
+ fetch: (req: Request, env?: Record<string, unknown>) => Response | Promise<Response>;
254
+ }, env: NodeJS.ProcessEnv, body?: string, write?: (text: string) => void): Promise<ServerlessResponse>;
255
+ /** A complete CGI response: a status line, headers, a blank line, then the body. */
256
+ private static cgiResponseText;
257
+ /** Read the request body from stdin, honoring `CONTENT_LENGTH` when present. */
258
+ private readStdin;
111
259
  /**
112
260
  * Create an Azure Functions-compatible handler from a Hono app.
113
261
  * @param app - A Hono-compatible application with a `fetch` method.
114
262
  * @returns A function that accepts an Azure context and request object.
115
263
  */
116
264
  static createAzureHandler(app: {
117
- fetch: (req: Request) => Promise<Response>;
118
- }): (context: any, req: any) => Promise<void>;
265
+ fetch: (req: Request, env?: Record<string, unknown>) => Response | Promise<Response>;
266
+ }): (context: AzureContext, req: AzureRequest) => Promise<void>;
119
267
  }
268
+ export {};