@signalwire/sdk 2.0.5 → 3.6.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 (659) hide show
  1. package/CHANGELOG.md +821 -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 +510 -126
  6. package/dist/AgentBase.js +1581 -455
  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 +186 -45
  21. package/dist/DataMap.js +210 -52
  22. package/dist/DataMap.js.map +1 -1
  23. package/dist/FunctionResult.d.ts +309 -83
  24. package/dist/FunctionResult.js +483 -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 +169 -59
  58. package/dist/SWMLService.js +456 -129
  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/SemanticGate.d.ts +183 -0
  67. package/dist/SemanticGate.js +533 -0
  68. package/dist/SemanticGate.js.map +1 -0
  69. package/dist/ServerlessAdapter.d.ts +156 -7
  70. package/dist/ServerlessAdapter.js +399 -42
  71. package/dist/ServerlessAdapter.js.map +1 -1
  72. package/dist/SessionManager.d.ts +11 -2
  73. package/dist/SessionManager.js +50 -18
  74. package/dist/SessionManager.js.map +1 -1
  75. package/dist/SslConfig.d.ts +2 -1
  76. package/dist/SslConfig.js +4 -1
  77. package/dist/SslConfig.js.map +1 -1
  78. package/dist/SwaigActions.generated.d.ts +23 -0
  79. package/dist/SwaigActions.generated.js +8 -0
  80. package/dist/SwaigActions.generated.js.map +1 -0
  81. package/dist/SwaigContracts.d.ts +15 -0
  82. package/dist/SwaigContracts.generated.d.ts +264 -0
  83. package/dist/SwaigContracts.generated.js +12 -0
  84. package/dist/SwaigContracts.generated.js.map +1 -0
  85. package/dist/SwaigContracts.js +2 -0
  86. package/dist/SwaigContracts.js.map +1 -0
  87. package/dist/SwaigFunction.d.ts +139 -7
  88. package/dist/SwaigFunction.js +170 -22
  89. package/dist/SwaigFunction.js.map +1 -1
  90. package/dist/SwmlBuilder.d.ts +68 -19
  91. package/dist/SwmlBuilder.js +74 -38
  92. package/dist/SwmlBuilder.js.map +1 -1
  93. package/dist/SwmlVerbMethods.generated.d.ts +41 -4
  94. package/dist/SwmlVerbMethods.generated.js +1 -1
  95. package/dist/TypeInference.d.ts +39 -3
  96. package/dist/TypeInference.js +256 -16
  97. package/dist/TypeInference.js.map +1 -1
  98. package/dist/WebService.d.ts +79 -11
  99. package/dist/WebService.js +320 -109
  100. package/dist/WebService.js.map +1 -1
  101. package/dist/WebhookMiddleware.d.ts +119 -0
  102. package/dist/WebhookMiddleware.js +271 -0
  103. package/dist/WebhookMiddleware.js.map +1 -0
  104. package/dist/WebhookValidator.d.ts +92 -0
  105. package/dist/WebhookValidator.js +409 -0
  106. package/dist/WebhookValidator.js.map +1 -0
  107. package/dist/agents/BedrockAgent.d.ts +162 -0
  108. package/dist/agents/BedrockAgent.js +323 -0
  109. package/dist/agents/BedrockAgent.js.map +1 -0
  110. package/dist/ai-chat/AIChatClient.d.ts +316 -0
  111. package/dist/ai-chat/AIChatClient.js +535 -0
  112. package/dist/ai-chat/AIChatClient.js.map +1 -0
  113. package/dist/ai-chat/ChatGateway.d.ts +408 -0
  114. package/dist/ai-chat/ChatGateway.js +747 -0
  115. package/dist/ai-chat/ChatGateway.js.map +1 -0
  116. package/dist/ai-chat/HandoffRouter.d.ts +282 -0
  117. package/dist/ai-chat/HandoffRouter.js +518 -0
  118. package/dist/ai-chat/HandoffRouter.js.map +1 -0
  119. package/dist/ai-chat/index.d.ts +12 -0
  120. package/dist/ai-chat/index.js +10 -0
  121. package/dist/ai-chat/index.js.map +1 -0
  122. package/dist/capabilities.d.ts +64 -0
  123. package/dist/capabilities.js +95 -0
  124. package/dist/capabilities.js.map +1 -0
  125. package/dist/cli/agent-loader.d.ts +32 -6
  126. package/dist/cli/agent-loader.js +92 -33
  127. package/dist/cli/agent-loader.js.map +1 -1
  128. package/dist/cli/datamap-exec.d.ts +175 -0
  129. package/dist/cli/datamap-exec.js +1284 -0
  130. package/dist/cli/datamap-exec.js.map +1 -0
  131. package/dist/cli/function-args.d.ts +40 -0
  132. package/dist/cli/function-args.js +146 -0
  133. package/dist/cli/function-args.js.map +1 -0
  134. package/dist/cli/simulation.d.ts +99 -0
  135. package/dist/cli/simulation.js +490 -0
  136. package/dist/cli/simulation.js.map +1 -0
  137. package/dist/cli/swaig-test.d.ts +12 -25
  138. package/dist/cli/swaig-test.js +935 -371
  139. package/dist/cli/swaig-test.js.map +1 -1
  140. package/dist/cli/tsdocs/agentsNote.d.ts +30 -0
  141. package/dist/cli/tsdocs/agentsNote.js +92 -0
  142. package/dist/cli/tsdocs/agentsNote.js.map +1 -0
  143. package/dist/cli/tsdocs/api-index.json +1 -0
  144. package/dist/cli/tsdocs/api.d.ts +91 -0
  145. package/dist/cli/tsdocs/api.js +372 -0
  146. package/dist/cli/tsdocs/api.js.map +1 -0
  147. package/dist/cli/tsdocs/apiTypes.d.ts +64 -0
  148. package/dist/cli/tsdocs/apiTypes.js +7 -0
  149. package/dist/cli/tsdocs/apiTypes.js.map +1 -0
  150. package/dist/cli/tsdocs/bin.d.ts +6 -0
  151. package/dist/cli/tsdocs/bin.js +23 -0
  152. package/dist/cli/tsdocs/bin.js.map +1 -0
  153. package/dist/cli/tsdocs/files.d.ts +108 -0
  154. package/dist/cli/tsdocs/files.js +287 -0
  155. package/dist/cli/tsdocs/files.js.map +1 -0
  156. package/dist/cli/tsdocs/index.d.ts +28 -0
  157. package/dist/cli/tsdocs/index.js +307 -0
  158. package/dist/cli/tsdocs/index.js.map +1 -0
  159. package/dist/cli/tsdocs/live.d.ts +41 -0
  160. package/dist/cli/tsdocs/live.js +202 -0
  161. package/dist/cli/tsdocs/live.js.map +1 -0
  162. package/dist/cli/tsdocs/locate.d.ts +51 -0
  163. package/dist/cli/tsdocs/locate.js +75 -0
  164. package/dist/cli/tsdocs/locate.js.map +1 -0
  165. package/dist/cli/tsdocs/render.d.ts +75 -0
  166. package/dist/cli/tsdocs/render.js +323 -0
  167. package/dist/cli/tsdocs/render.js.map +1 -0
  168. package/dist/cli/tsdocs/topics.d.ts +43 -0
  169. package/dist/cli/tsdocs/topics.js +920 -0
  170. package/dist/cli/tsdocs/topics.js.map +1 -0
  171. package/dist/index.d.ts +49 -68
  172. package/dist/index.js +45 -73
  173. package/dist/index.js.map +1 -1
  174. package/dist/livewire/index.d.ts +229 -155
  175. package/dist/livewire/index.js +298 -195
  176. package/dist/livewire/index.js.map +1 -1
  177. package/dist/llms.txt +65 -0
  178. package/dist/prefabs/CallSessionStore.d.ts +52 -0
  179. package/dist/prefabs/CallSessionStore.js +72 -0
  180. package/dist/prefabs/CallSessionStore.js.map +1 -0
  181. package/dist/prefabs/ConciergeAgent.d.ts +13 -1
  182. package/dist/prefabs/ConciergeAgent.js +36 -31
  183. package/dist/prefabs/ConciergeAgent.js.map +1 -1
  184. package/dist/prefabs/FAQBotAgent.d.ts +9 -1
  185. package/dist/prefabs/FAQBotAgent.js +113 -47
  186. package/dist/prefabs/FAQBotAgent.js.map +1 -1
  187. package/dist/prefabs/InfoGathererAgent.d.ts +22 -3
  188. package/dist/prefabs/InfoGathererAgent.js +67 -58
  189. package/dist/prefabs/InfoGathererAgent.js.map +1 -1
  190. package/dist/prefabs/ReceptionistAgent.d.ts +16 -5
  191. package/dist/prefabs/ReceptionistAgent.js +39 -31
  192. package/dist/prefabs/ReceptionistAgent.js.map +1 -1
  193. package/dist/prefabs/SurveyAgent.d.ts +22 -4
  194. package/dist/prefabs/SurveyAgent.js +84 -68
  195. package/dist/prefabs/SurveyAgent.js.map +1 -1
  196. package/dist/relay/Action.d.ts +44 -21
  197. package/dist/relay/Action.js +75 -17
  198. package/dist/relay/Action.js.map +1 -1
  199. package/dist/relay/Call.d.ts +312 -47
  200. package/dist/relay/Call.js +369 -18
  201. package/dist/relay/Call.js.map +1 -1
  202. package/dist/relay/Deferred.js.map +1 -1
  203. package/dist/relay/Message.d.ts +26 -5
  204. package/dist/relay/Message.js +36 -6
  205. package/dist/relay/Message.js.map +1 -1
  206. package/dist/relay/RelayClient.d.ts +44 -17
  207. package/dist/relay/RelayClient.js +175 -65
  208. package/dist/relay/RelayClient.js.map +1 -1
  209. package/dist/relay/RelayError.d.ts +14 -0
  210. package/dist/relay/RelayError.js +15 -0
  211. package/dist/relay/RelayError.js.map +1 -1
  212. package/dist/relay/RelayEvent.d.ts +96 -65
  213. package/dist/relay/RelayEvent.js +85 -56
  214. package/dist/relay/RelayEvent.js.map +1 -1
  215. package/dist/relay/closedSets.d.ts +111 -0
  216. package/dist/relay/closedSets.js +83 -0
  217. package/dist/relay/closedSets.js.map +1 -0
  218. package/dist/relay/index.d.ts +3 -1
  219. package/dist/relay/index.js +1 -0
  220. package/dist/relay/index.js.map +1 -1
  221. package/dist/relay/normalize.js.map +1 -1
  222. package/dist/relay/protocol.types.generated.d.ts +1195 -0
  223. package/dist/relay/protocol.types.generated.js +8 -0
  224. package/dist/relay/protocol.types.generated.js.map +1 -0
  225. package/dist/relay/types.d.ts +73 -42
  226. package/dist/rest/HttpClient.d.ts +36 -8
  227. package/dist/rest/HttpClient.js +233 -40
  228. package/dist/rest/HttpClient.js.map +1 -1
  229. package/dist/rest/RequestOptions.d.ts +110 -0
  230. package/dist/rest/RequestOptions.js +113 -0
  231. package/dist/rest/RequestOptions.js.map +1 -0
  232. package/dist/rest/RestError.d.ts +52 -6
  233. package/dist/rest/RestError.js +89 -5
  234. package/dist/rest/RestError.js.map +1 -1
  235. package/dist/rest/base/CrudResource.d.ts +16 -26
  236. package/dist/rest/base/CrudResource.js +19 -33
  237. package/dist/rest/base/CrudResource.js.map +1 -1
  238. package/dist/rest/base/CrudWithAddresses.d.ts +3 -2
  239. package/dist/rest/base/CrudWithAddresses.js +2 -2
  240. package/dist/rest/base/CrudWithAddresses.js.map +1 -1
  241. package/dist/rest/base/FabricResource.d.ts +15 -0
  242. package/dist/rest/base/FabricResource.js +16 -0
  243. package/dist/rest/base/FabricResource.js.map +1 -0
  244. package/dist/rest/base/ReadResource.d.ts +62 -0
  245. package/dist/rest/base/ReadResource.js +69 -0
  246. package/dist/rest/base/ReadResource.js.map +1 -0
  247. package/dist/rest/callHandler.d.ts +5 -2
  248. package/dist/rest/callHandler.js +4 -1
  249. package/dist/rest/callHandler.js.map +1 -1
  250. package/dist/rest/index.d.ts +18 -77
  251. package/dist/rest/index.js +47 -120
  252. package/dist/rest/index.js.map +1 -1
  253. package/dist/rest/namespaces/_client_tree_generated.d.ts +103 -0
  254. package/dist/rest/namespaces/_client_tree_generated.js +171 -0
  255. package/dist/rest/namespaces/_client_tree_generated.js.map +1 -0
  256. package/dist/rest/namespaces/addresses.d.ts +3 -42
  257. package/dist/rest/namespaces/addresses.js +3 -50
  258. package/dist/rest/namespaces/addresses.js.map +1 -1
  259. package/dist/rest/namespaces/calling.d.ts +6 -378
  260. package/dist/rest/namespaces/calling.js +6 -473
  261. package/dist/rest/namespaces/calling.js.map +1 -1
  262. package/dist/rest/namespaces/calling.resources.generated.d.ts +165 -0
  263. package/dist/rest/namespaces/calling.resources.generated.js +477 -0
  264. package/dist/rest/namespaces/calling.resources.generated.js.map +1 -0
  265. package/dist/rest/namespaces/calling.types.generated.d.ts +2917 -0
  266. package/dist/rest/namespaces/calling.types.generated.js +8 -0
  267. package/dist/rest/namespaces/calling.types.generated.js.map +1 -0
  268. package/dist/rest/namespaces/chat.d.ts +4 -18
  269. package/dist/rest/namespaces/chat.js +4 -21
  270. package/dist/rest/namespaces/chat.js.map +1 -1
  271. package/dist/rest/namespaces/chat.resources.generated.d.ts +12 -0
  272. package/dist/rest/namespaces/chat.resources.generated.js +29 -0
  273. package/dist/rest/namespaces/chat.resources.generated.js.map +1 -0
  274. package/dist/rest/namespaces/chat.types.generated.d.ts +56 -0
  275. package/dist/rest/namespaces/chat.types.generated.js +8 -0
  276. package/dist/rest/namespaces/chat.types.generated.js.map +1 -0
  277. package/dist/rest/namespaces/datasphere.d.ts +6 -62
  278. package/dist/rest/namespaces/datasphere.js +6 -72
  279. package/dist/rest/namespaces/datasphere.js.map +1 -1
  280. package/dist/rest/namespaces/datasphere.resources.generated.d.ts +25 -0
  281. package/dist/rest/namespaces/datasphere.resources.generated.js +50 -0
  282. package/dist/rest/namespaces/datasphere.resources.generated.js.map +1 -0
  283. package/dist/rest/namespaces/datasphere.types.generated.d.ts +180 -0
  284. package/dist/rest/namespaces/datasphere.types.generated.js +8 -0
  285. package/dist/rest/namespaces/datasphere.types.generated.js.map +1 -0
  286. package/dist/rest/namespaces/fabric.d.ts +11 -327
  287. package/dist/rest/namespaces/fabric.js +14 -439
  288. package/dist/rest/namespaces/fabric.js.map +1 -1
  289. package/dist/rest/namespaces/fabric.resources.generated.d.ts +195 -0
  290. package/dist/rest/namespaces/fabric.resources.generated.js +399 -0
  291. package/dist/rest/namespaces/fabric.resources.generated.js.map +1 -0
  292. package/dist/rest/namespaces/fabric.types.generated.d.ts +4557 -0
  293. package/dist/rest/namespaces/fabric.types.generated.js +8 -0
  294. package/dist/rest/namespaces/fabric.types.generated.js.map +1 -0
  295. package/dist/rest/namespaces/fax.resources.generated.d.ts +6 -0
  296. package/dist/rest/namespaces/fax.resources.generated.js +14 -0
  297. package/dist/rest/namespaces/fax.resources.generated.js.map +1 -0
  298. package/dist/rest/namespaces/fax.types.generated.d.ts +131 -0
  299. package/dist/rest/namespaces/fax.types.generated.js +8 -0
  300. package/dist/rest/namespaces/fax.types.generated.js.map +1 -0
  301. package/dist/rest/namespaces/imported-numbers.d.ts +3 -18
  302. package/dist/rest/namespaces/imported-numbers.js +3 -21
  303. package/dist/rest/namespaces/imported-numbers.js.map +1 -1
  304. package/dist/rest/namespaces/logs.d.ts +10 -101
  305. package/dist/rest/namespaces/logs.js +10 -128
  306. package/dist/rest/namespaces/logs.js.map +1 -1
  307. package/dist/rest/namespaces/logs.resources.generated.d.ts +9 -0
  308. package/dist/rest/namespaces/logs.resources.generated.js +17 -0
  309. package/dist/rest/namespaces/logs.resources.generated.js.map +1 -0
  310. package/dist/rest/namespaces/logs.types.generated.d.ts +131 -0
  311. package/dist/rest/namespaces/logs.types.generated.js +8 -0
  312. package/dist/rest/namespaces/logs.types.generated.js.map +1 -0
  313. package/dist/rest/namespaces/lookup.d.ts +3 -25
  314. package/dist/rest/namespaces/lookup.js +3 -27
  315. package/dist/rest/namespaces/lookup.js.map +1 -1
  316. package/dist/rest/namespaces/message.resources.generated.d.ts +6 -0
  317. package/dist/rest/namespaces/message.resources.generated.js +14 -0
  318. package/dist/rest/namespaces/message.resources.generated.js.map +1 -0
  319. package/dist/rest/namespaces/message.types.generated.d.ts +122 -0
  320. package/dist/rest/namespaces/message.types.generated.js +8 -0
  321. package/dist/rest/namespaces/message.types.generated.js.map +1 -0
  322. package/dist/rest/namespaces/messages.resources.generated.d.ts +18 -0
  323. package/dist/rest/namespaces/messages.resources.generated.js +44 -0
  324. package/dist/rest/namespaces/messages.resources.generated.js.map +1 -0
  325. package/dist/rest/namespaces/messages.types.generated.d.ts +99 -0
  326. package/dist/rest/namespaces/messages.types.generated.js +8 -0
  327. package/dist/rest/namespaces/messages.types.generated.js.map +1 -0
  328. package/dist/rest/namespaces/mfa.d.ts +3 -42
  329. package/dist/rest/namespaces/mfa.js +3 -49
  330. package/dist/rest/namespaces/mfa.js.map +1 -1
  331. package/dist/rest/namespaces/number-groups.d.ts +3 -45
  332. package/dist/rest/namespaces/number-groups.js +3 -53
  333. package/dist/rest/namespaces/number-groups.js.map +1 -1
  334. package/dist/rest/namespaces/phone-numbers.d.ts +8 -196
  335. package/dist/rest/namespaces/phone-numbers.js +8 -230
  336. package/dist/rest/namespaces/phone-numbers.js.map +1 -1
  337. package/dist/rest/namespaces/project.d.ts +6 -42
  338. package/dist/rest/namespaces/project.js +6 -51
  339. package/dist/rest/namespaces/project.js.map +1 -1
  340. package/dist/rest/namespaces/project.resources.generated.d.ts +17 -0
  341. package/dist/rest/namespaces/project.resources.generated.js +44 -0
  342. package/dist/rest/namespaces/project.resources.generated.js.map +1 -0
  343. package/dist/rest/namespaces/project.types.generated.d.ts +58 -0
  344. package/dist/rest/namespaces/project.types.generated.js +8 -0
  345. package/dist/rest/namespaces/project.types.generated.js.map +1 -0
  346. package/dist/rest/namespaces/projects.resources.generated.d.ts +12 -0
  347. package/dist/rest/namespaces/projects.resources.generated.js +25 -0
  348. package/dist/rest/namespaces/projects.resources.generated.js.map +1 -0
  349. package/dist/rest/namespaces/projects.types.generated.d.ts +77 -0
  350. package/dist/rest/namespaces/projects.types.generated.js +8 -0
  351. package/dist/rest/namespaces/projects.types.generated.js.map +1 -0
  352. package/dist/rest/namespaces/pubsub.d.ts +4 -18
  353. package/dist/rest/namespaces/pubsub.js +4 -21
  354. package/dist/rest/namespaces/pubsub.js.map +1 -1
  355. package/dist/rest/namespaces/pubsub.resources.generated.d.ts +12 -0
  356. package/dist/rest/namespaces/pubsub.resources.generated.js +29 -0
  357. package/dist/rest/namespaces/pubsub.resources.generated.js.map +1 -0
  358. package/dist/rest/namespaces/pubsub.types.generated.d.ts +60 -0
  359. package/dist/rest/namespaces/pubsub.types.generated.js +8 -0
  360. package/dist/rest/namespaces/pubsub.types.generated.js.map +1 -0
  361. package/dist/rest/namespaces/queues.d.ts +3 -38
  362. package/dist/rest/namespaces/queues.js +3 -44
  363. package/dist/rest/namespaces/queues.js.map +1 -1
  364. package/dist/rest/namespaces/recordings.d.ts +3 -34
  365. package/dist/rest/namespaces/recordings.js +3 -40
  366. package/dist/rest/namespaces/recordings.js.map +1 -1
  367. package/dist/rest/namespaces/registry.d.ts +6 -137
  368. package/dist/rest/namespaces/registry.js +6 -173
  369. package/dist/rest/namespaces/registry.js.map +1 -1
  370. package/dist/rest/namespaces/relay-rest.resources.generated.d.ts +168 -0
  371. package/dist/rest/namespaces/relay-rest.resources.generated.js +430 -0
  372. package/dist/rest/namespaces/relay-rest.resources.generated.js.map +1 -0
  373. package/dist/rest/namespaces/relay-rest.types.generated.d.ts +1906 -0
  374. package/dist/rest/namespaces/relay-rest.types.generated.js +8 -0
  375. package/dist/rest/namespaces/relay-rest.types.generated.js.map +1 -0
  376. package/dist/rest/namespaces/short-codes.d.ts +3 -35
  377. package/dist/rest/namespaces/short-codes.js +3 -41
  378. package/dist/rest/namespaces/short-codes.js.map +1 -1
  379. package/dist/rest/namespaces/sip-profile.d.ts +3 -24
  380. package/dist/rest/namespaces/sip-profile.js +3 -29
  381. package/dist/rest/namespaces/sip-profile.js.map +1 -1
  382. package/dist/rest/namespaces/verified-callers.d.ts +3 -29
  383. package/dist/rest/namespaces/verified-callers.js +3 -34
  384. package/dist/rest/namespaces/verified-callers.js.map +1 -1
  385. package/dist/rest/namespaces/video.d.ts +10 -227
  386. package/dist/rest/namespaces/video.js +10 -288
  387. package/dist/rest/namespaces/video.js.map +1 -1
  388. package/dist/rest/namespaces/video.resources.generated.d.ts +81 -0
  389. package/dist/rest/namespaces/video.resources.generated.js +171 -0
  390. package/dist/rest/namespaces/video.resources.generated.js.map +1 -0
  391. package/dist/rest/namespaces/video.types.generated.d.ts +771 -0
  392. package/dist/rest/namespaces/video.types.generated.js +8 -0
  393. package/dist/rest/namespaces/video.types.generated.js.map +1 -0
  394. package/dist/rest/namespaces/voice.resources.generated.d.ts +9 -0
  395. package/dist/rest/namespaces/voice.resources.generated.js +17 -0
  396. package/dist/rest/namespaces/voice.resources.generated.js.map +1 -0
  397. package/dist/rest/namespaces/voice.types.generated.d.ts +214 -0
  398. package/dist/rest/namespaces/voice.types.generated.js +8 -0
  399. package/dist/rest/namespaces/voice.types.generated.js.map +1 -0
  400. package/dist/rest/pagination.d.ts +5 -1
  401. package/dist/rest/pagination.js +40 -20
  402. package/dist/rest/pagination.js.map +1 -1
  403. package/dist/rest/types.d.ts +21 -3
  404. package/dist/schema.json +299 -98
  405. package/dist/skills/SkillBase.d.ts +111 -21
  406. package/dist/skills/SkillBase.js +100 -17
  407. package/dist/skills/SkillBase.js.map +1 -1
  408. package/dist/skills/SkillManager.d.ts +66 -13
  409. package/dist/skills/SkillManager.js +101 -20
  410. package/dist/skills/SkillManager.js.map +1 -1
  411. package/dist/skills/SkillName.d.ts +44 -0
  412. package/dist/skills/SkillName.js +2 -0
  413. package/dist/skills/SkillName.js.map +1 -0
  414. package/dist/skills/SkillRegistry.d.ts +22 -11
  415. package/dist/skills/SkillRegistry.js +47 -17
  416. package/dist/skills/SkillRegistry.js.map +1 -1
  417. package/dist/skills/builtin/api_ninjas_trivia.d.ts +3 -1
  418. package/dist/skills/builtin/api_ninjas_trivia.js +18 -6
  419. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
  420. package/dist/skills/builtin/ask_claude.d.ts +14 -4
  421. package/dist/skills/builtin/ask_claude.js +36 -14
  422. package/dist/skills/builtin/ask_claude.js.map +1 -1
  423. package/dist/skills/builtin/claude_skills.d.ts +3 -1
  424. package/dist/skills/builtin/claude_skills.js +19 -15
  425. package/dist/skills/builtin/claude_skills.js.map +1 -1
  426. package/dist/skills/builtin/custom_skills.d.ts +10 -3
  427. package/dist/skills/builtin/custom_skills.js +26 -9
  428. package/dist/skills/builtin/custom_skills.js.map +1 -1
  429. package/dist/skills/builtin/datasphere.d.ts +5 -3
  430. package/dist/skills/builtin/datasphere.js +21 -22
  431. package/dist/skills/builtin/datasphere.js.map +1 -1
  432. package/dist/skills/builtin/datasphere_serverless.d.ts +12 -1
  433. package/dist/skills/builtin/datasphere_serverless.js +17 -6
  434. package/dist/skills/builtin/datasphere_serverless.js.map +1 -1
  435. package/dist/skills/builtin/datetime.d.ts +3 -1
  436. package/dist/skills/builtin/datetime.js +11 -7
  437. package/dist/skills/builtin/datetime.js.map +1 -1
  438. package/dist/skills/builtin/google_maps.d.ts +29 -14
  439. package/dist/skills/builtin/google_maps.js +89 -269
  440. package/dist/skills/builtin/google_maps.js.map +1 -1
  441. package/dist/skills/builtin/index.d.ts +8 -6
  442. package/dist/skills/builtin/index.js +8 -6
  443. package/dist/skills/builtin/index.js.map +1 -1
  444. package/dist/skills/builtin/info_gatherer.d.ts +4 -2
  445. package/dist/skills/builtin/info_gatherer.js +20 -12
  446. package/dist/skills/builtin/info_gatherer.js.map +1 -1
  447. package/dist/skills/builtin/joke.d.ts +16 -6
  448. package/dist/skills/builtin/joke.js +54 -37
  449. package/dist/skills/builtin/joke.js.map +1 -1
  450. package/dist/skills/builtin/math.d.ts +3 -1
  451. package/dist/skills/builtin/math.js +14 -9
  452. package/dist/skills/builtin/math.js.map +1 -1
  453. package/dist/skills/builtin/mcp_gateway.d.ts +34 -5
  454. package/dist/skills/builtin/mcp_gateway.js +77 -46
  455. package/dist/skills/builtin/mcp_gateway.js.map +1 -1
  456. package/dist/skills/builtin/native_vector_search.d.ts +19 -5
  457. package/dist/skills/builtin/native_vector_search.js +179 -61
  458. package/dist/skills/builtin/native_vector_search.js.map +1 -1
  459. package/dist/skills/builtin/play_background_file.d.ts +21 -15
  460. package/dist/skills/builtin/play_background_file.js +43 -122
  461. package/dist/skills/builtin/play_background_file.js.map +1 -1
  462. package/dist/skills/builtin/spider.d.ts +42 -4
  463. package/dist/skills/builtin/spider.js +277 -104
  464. package/dist/skills/builtin/spider.js.map +1 -1
  465. package/dist/skills/builtin/swml_transfer.d.ts +14 -3
  466. package/dist/skills/builtin/swml_transfer.js +45 -24
  467. package/dist/skills/builtin/swml_transfer.js.map +1 -1
  468. package/dist/skills/builtin/weather_api.d.ts +24 -13
  469. package/dist/skills/builtin/weather_api.js +38 -30
  470. package/dist/skills/builtin/weather_api.js.map +1 -1
  471. package/dist/skills/builtin/web_search.d.ts +48 -10
  472. package/dist/skills/builtin/web_search.js +294 -100
  473. package/dist/skills/builtin/web_search.js.map +1 -1
  474. package/dist/skills/builtin/wikipedia_search.d.ts +4 -2
  475. package/dist/skills/builtin/wikipedia_search.js +14 -13
  476. package/dist/skills/builtin/wikipedia_search.js.map +1 -1
  477. package/dist/skills/index.d.ts +3 -2
  478. package/dist/skills/index.js +1 -1
  479. package/dist/skills/index.js.map +1 -1
  480. package/dist/swml_verbs_generated.d.ts +2824 -0
  481. package/dist/swml_verbs_generated.js +12 -0
  482. package/dist/swml_verbs_generated.js.map +1 -0
  483. package/dist/types.d.ts +59 -6
  484. package/dist/web.d.ts +27 -0
  485. package/dist/web.js +20 -0
  486. package/dist/web.js.map +1 -0
  487. package/docs/agent-guide.md +1034 -0
  488. package/docs/ai_chat.md +560 -0
  489. package/docs/api-reference.md +3641 -0
  490. package/docs/architecture.md +846 -0
  491. package/docs/bedrock_agent.md +411 -0
  492. package/docs/cli-guide.md +403 -0
  493. package/docs/cloud_functions_guide.md +399 -0
  494. package/docs/configuration.md +548 -0
  495. package/docs/contexts-guide.md +884 -0
  496. package/docs/datamap-guide.md +1207 -0
  497. package/docs/developer_pain_points.md +548 -0
  498. package/docs/llm_parameters.md +298 -0
  499. package/docs/mcp_gateway_reference.md +354 -0
  500. package/docs/mcp_integration.md +162 -0
  501. package/docs/pgi_agent_guide.md +1820 -0
  502. package/docs/prefabs-guide.md +815 -0
  503. package/docs/programmatically_governed_inference.md +301 -0
  504. package/docs/sdk_features.md +501 -0
  505. package/docs/security.md +559 -0
  506. package/docs/serverless-guide.md +520 -0
  507. package/docs/skills-guide.md +1223 -0
  508. package/docs/skills-system.md +405 -0
  509. package/docs/skills_parameter_schema.md +417 -0
  510. package/docs/swaig-reference.md +1986 -0
  511. package/docs/swml_service_guide.md +573 -0
  512. package/docs/third_party_skills.md +410 -0
  513. package/docs/web_service.md +666 -0
  514. package/examples/README.md +202 -0
  515. package/examples/advanced-datamap.ts +108 -0
  516. package/examples/advanced-dynamic-config.ts +70 -0
  517. package/examples/auto-vivified.ts +95 -0
  518. package/examples/call-flow.ts +65 -0
  519. package/examples/comprehensive-dynamic.ts +125 -0
  520. package/examples/contexts-steps.ts +65 -0
  521. package/examples/custom-path.ts +45 -0
  522. package/examples/datamap-tools.ts +51 -0
  523. package/examples/datasphere-multi-instance.ts +66 -0
  524. package/examples/datasphere-serverless-env.ts +87 -0
  525. package/examples/datasphere-webhook-env.ts +65 -0
  526. package/examples/datasphere.ts +56 -0
  527. package/examples/declarative.ts +100 -0
  528. package/examples/dynamic-config.ts +54 -0
  529. package/examples/dynamic-info-gatherer.ts +69 -0
  530. package/examples/dynamic-swml-service.ts +67 -0
  531. package/examples/gather-info.ts +95 -0
  532. package/examples/gather-per-question-functions-demo.ts +139 -0
  533. package/examples/joke-agent.ts +34 -0
  534. package/examples/kubernetes-agent.ts +45 -0
  535. package/examples/llm-params.ts +75 -0
  536. package/examples/mcp-agent.ts +89 -0
  537. package/examples/mcp-gateway.ts +81 -0
  538. package/examples/multi-agent.ts +80 -0
  539. package/examples/multi-endpoint.ts +79 -0
  540. package/examples/pgi/case-domain.ts +114 -0
  541. package/examples/pgi/serve.ts +16 -0
  542. package/examples/pgi/support-agent.ts +265 -0
  543. package/examples/pom-prompt.ts +70 -0
  544. package/examples/prefab-concierge.ts +42 -0
  545. package/examples/prefab-faq.ts +58 -0
  546. package/examples/prefab-info-gatherer.ts +33 -0
  547. package/examples/prefab-receptionist.ts +36 -0
  548. package/examples/prefab-survey.ts +69 -0
  549. package/examples/quickstart-agent.ts +29 -0
  550. package/examples/quickstart-relay.ts +25 -0
  551. package/examples/quickstart-rest.ts +25 -0
  552. package/examples/record-call.ts +65 -0
  553. package/examples/relay-demo.ts +33 -0
  554. package/examples/room-and-sip.ts +93 -0
  555. package/examples/serverless-lambda.ts +43 -0
  556. package/examples/session-state.ts +83 -0
  557. package/examples/simple-agent.ts +36 -0
  558. package/examples/simple-static.ts +29 -0
  559. package/examples/skills-demo.ts +41 -0
  560. package/examples/step-function-inheritance-demo.ts +124 -0
  561. package/examples/swaig-features.ts +193 -0
  562. package/examples/swml-service-routing.ts +66 -0
  563. package/examples/swml-service.ts +38 -0
  564. package/examples/swmlservice_ai_sidecar.ts +104 -0
  565. package/examples/swmlservice_swaig_standalone.ts +79 -0
  566. package/examples/tap.ts +67 -0
  567. package/examples/typed-tools.ts +68 -0
  568. package/examples/verb-methods.ts +45 -0
  569. package/examples/web-search-multi-instance.ts +75 -0
  570. package/examples/web-search.ts +38 -0
  571. package/examples/wikipedia.ts +36 -0
  572. package/livewire/README.md +164 -0
  573. package/livewire/docs/migration-guide.md +251 -0
  574. package/livewire/examples/livewire-basic-agent.ts +74 -0
  575. package/livewire/examples/livewire-handoff.ts +196 -0
  576. package/livewire/examples/livewire-multi-tool.ts +121 -0
  577. package/package.json +85 -13
  578. package/relay/README.md +101 -0
  579. package/relay/docs/call-methods.md +622 -0
  580. package/relay/docs/client-reference.md +281 -0
  581. package/relay/docs/events.md +193 -0
  582. package/relay/docs/getting-started.md +221 -0
  583. package/relay/docs/guide.md +386 -0
  584. package/relay/docs/messaging.md +246 -0
  585. package/relay/examples/relay-inbound.ts +66 -0
  586. package/relay/examples/relay-messaging.ts +74 -0
  587. package/relay/examples/relay-outbound.ts +76 -0
  588. package/rest/README.md +141 -0
  589. package/rest/docs/calling.md +313 -0
  590. package/rest/docs/client-reference.md +149 -0
  591. package/rest/docs/fabric.md +192 -0
  592. package/rest/docs/getting-started.md +138 -0
  593. package/rest/docs/guide.md +421 -0
  594. package/rest/docs/namespaces.md +367 -0
  595. package/rest/docs/phone-binding.md +116 -0
  596. package/rest/examples/rest-10dlc-registration.ts +177 -0
  597. package/rest/examples/rest-bind-phone-to-swml-webhook.ts +66 -0
  598. package/rest/examples/rest-calling-ivr-and-ai.ts +136 -0
  599. package/rest/examples/rest-calling-play-and-record.ts +98 -0
  600. package/rest/examples/rest-client.ts +59 -0
  601. package/rest/examples/rest-datasphere-search.ts +81 -0
  602. package/rest/examples/rest-fabric-conferences-and-routing.ts +147 -0
  603. package/rest/examples/rest-fabric-subscribers-and-sip.ts +106 -0
  604. package/rest/examples/rest-fabric-swml-and-callflows.ts +101 -0
  605. package/rest/examples/rest-manage-resources.ts +64 -0
  606. package/rest/examples/rest-phone-number-management.ts +200 -0
  607. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  608. package/rest/examples/rest-video-rooms.ts +186 -0
  609. package/tutorial/fred/fred.ts +218 -0
  610. package/tutorial/fred/tutorial/01-introduction.md +141 -0
  611. package/tutorial/fred/tutorial/02-setup.md +304 -0
  612. package/tutorial/fred/tutorial/03-basic-agent.md +284 -0
  613. package/tutorial/fred/tutorial/04-wikipedia-skill.md +298 -0
  614. package/tutorial/fred/tutorial/05-custom-functions.md +347 -0
  615. package/tutorial/fred/tutorial/06-running-testing.md +642 -0
  616. package/tutorial/fred/tutorial/README.md +56 -0
  617. package/tutorial/fred/tutorial/appendix-complete-code.md +632 -0
  618. package/tutorial/fred/tutorial/appendix-docker-deployment.md +504 -0
  619. package/tutorial/full-guardrails-agent/handlers.ts +436 -0
  620. package/tutorial/full-guardrails-agent/penny.ts +305 -0
  621. package/tutorial/full-guardrails-agent/reservations.ts +1109 -0
  622. package/tutorial/full-guardrails-agent/tutorial/01-why-guardrails.md +149 -0
  623. package/tutorial/full-guardrails-agent/tutorial/02-design-first.md +139 -0
  624. package/tutorial/full-guardrails-agent/tutorial/03-rules-first.md +422 -0
  625. package/tutorial/full-guardrails-agent/tutorial/04-the-shell.md +238 -0
  626. package/tutorial/full-guardrails-agent/tutorial/05-steps-and-scoping.md +247 -0
  627. package/tutorial/full-guardrails-agent/tutorial/06-tools-that-decide.md +467 -0
  628. package/tutorial/full-guardrails-agent/tutorial/07-gather-and-projection.md +160 -0
  629. package/tutorial/full-guardrails-agent/tutorial/08-the-verification-gate.md +333 -0
  630. package/tutorial/full-guardrails-agent/tutorial/09-people-and-endings.md +313 -0
  631. package/tutorial/full-guardrails-agent/tutorial/10-testing-and-running.md +387 -0
  632. package/tutorial/full-guardrails-agent/tutorial/README.md +106 -0
  633. package/tutorial/full-guardrails-agent/tutorial/appendix-complete-code.md +2207 -0
  634. package/tutorial/full-guardrails-agent/tutorial/appendix-deployment.md +191 -0
  635. package/tutorial/full-guardrails-agent/tutorial/appendix-technique-map.md +117 -0
  636. package/tutorial/full-guardrails-agent/workflow.ts +219 -0
  637. package/tutorial/multi_agents/README.md +175 -0
  638. package/tutorial/multi_agents/advanced_agent.ts +395 -0
  639. package/tutorial/multi_agents/extending_agents.ts +641 -0
  640. package/tutorial/multi_agents/knowledge.ts +59 -0
  641. package/tutorial/multi_agents/lesson1_first_agent.md +368 -0
  642. package/tutorial/multi_agents/lesson2_knowledge_bases.md +404 -0
  643. package/tutorial/multi_agents/lesson3_multi_agent_systems.md +621 -0
  644. package/tutorial/multi_agents/lesson4_advanced_features.md +805 -0
  645. package/tutorial/multi_agents/lesson5_extending_agents.md +856 -0
  646. package/tutorial/multi_agents/pc_builder.ts +529 -0
  647. package/tutorial/multi_agents/sales_agent.ts +88 -0
  648. package/tutorial/multi_agents/sales_agent_with_search.ts +116 -0
  649. package/tutorial/multi_agents/sales_knowledge.md +139 -0
  650. package/tutorial/multi_agents/support_knowledge.md +256 -0
  651. package/dist/cli/mock-data.d.ts +0 -37
  652. package/dist/cli/mock-data.js +0 -80
  653. package/dist/cli/mock-data.js.map +0 -1
  654. package/dist/generateVerbTypes.d.ts +0 -11
  655. package/dist/generateVerbTypes.js +0 -265
  656. package/dist/generateVerbTypes.js.map +0 -1
  657. package/dist/rest/namespaces/compat.d.ts +0 -585
  658. package/dist/rest/namespaces/compat.js +0 -735
  659. 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
  /**
@@ -62,6 +95,13 @@ export declare function validateUrl(url: string, allowPrivate?: boolean): Promis
62
95
  * Whether the current process is running in a serverless environment
63
96
  * (anything other than a long-lived ``server`` runtime).
64
97
  *
65
- * Python parity: ``signalwire.utils.is_serverless_mode``.
98
+ * Python equivalent: ``signalwire.utils.is_serverless_mode``.
66
99
  */
67
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,7 @@
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';
8
9
  import { getExecutionMode } from './Logger.js';
9
10
  /** Maximum allowed input length for skill handler arguments (characters). */
10
11
  export const MAX_SKILL_INPUT_LENGTH = 1000;
@@ -49,12 +50,14 @@ export function filterSensitiveHeaders(headers) {
49
50
  }
50
51
  /**
51
52
  * Redact credentials embedded in a URL (e.g. `https://user:secret@host` -> `https://user:****@host`).
52
- * Returns the URL unchanged if no credentials are present.
53
- * @param url - The URL string to redact.
54
- * @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 `****`.
55
58
  */
56
59
  export function redactUrl(url) {
57
- return url.replace(/:\/\/([^:@]+):([^@]+)@/, '://$1:****@');
60
+ return url.replace(/:\/\/([^:@/]*):([^@/]*)@/g, '://$1:****@');
58
61
  }
59
62
  /**
60
63
  * Validate that a hostname string does not contain whitespace, slashes, or control characters.
@@ -65,72 +68,156 @@ export function isValidHostname(host) {
65
68
  if (!host || host.length === 0)
66
69
  return false;
67
70
  // Reject whitespace, slashes, control chars
71
+ // eslint-disable-next-line no-control-regex -- intentional control-char rejection in hostname validation
68
72
  return !/[\s/\\]/.test(host) && !/[\x00-\x1f\x7f]/.test(host);
69
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
+ })();
70
88
  /**
71
- * Check whether an IP address belongs to a private/reserved range.
72
- * 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
+ *
73
124
  * @param ip - The IP address string to check.
74
- * @returns True if the IP is private/reserved.
125
+ * @returns True if the address is private, internal or unspecified.
75
126
  */
76
127
  export function isPrivateIp(ip) {
77
- // IPv4
78
- if (/^127\./.test(ip))
79
- return true;
80
- if (/^10\./.test(ip))
81
- return true;
82
- if (/^172\.(1[6-9]|2\d|3[01])\./.test(ip))
83
- return true;
84
- if (/^192\.168\./.test(ip))
85
- return true;
86
- if (/^169\.254\./.test(ip))
87
- return true;
88
- if (ip === '0.0.0.0')
89
- return true;
90
- // IPv6
91
- if (ip === '::1')
92
- return true;
93
- 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))
94
143
  return true;
95
- 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)
96
154
  return true;
97
- return false;
155
+ const env = (process.env['SWML_ALLOW_PRIVATE_URLS'] ?? '').toLowerCase();
156
+ return env === '1' || env === 'true' || env === 'yes';
98
157
  }
158
+ const lookupAll = (hostname) => lookup(hostname, { all: true });
99
159
  /**
100
- * DNS-resolve a URL's hostname and reject it if it points to a private IP.
101
- * @param url - The full URL to validate.
102
- * @param allowPrivate - When true, skip the private-IP check (default false).
103
- * @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.
104
168
  */
105
- export async function resolveAndValidateUrl(url, allowPrivate = false) {
106
- if (allowPrivate)
107
- return;
108
- let hostname;
169
+ export async function _checkUrl(url, allowPrivate = false, resolve = lookupAll) {
170
+ let parsed;
109
171
  try {
110
- hostname = new URL(url).hostname;
172
+ parsed = new URL(url);
111
173
  }
112
174
  catch {
113
- throw new Error(`Invalid URL: ${url}`);
175
+ throw new Error(`Invalid URL: ${redactUrl(url)}`);
114
176
  }
115
- // Direct IP check first
116
- if (isPrivateIp(hostname)) {
117
- 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}`);
118
179
  }
119
- // DNS resolution
120
- try {
121
- const result = await lookup(hostname);
122
- if (isPrivateIp(result.address)) {
123
- 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`);
124
190
  }
191
+ return;
125
192
  }
126
- catch (err) {
127
- // Re-throw our own errors; DNS failures are allowed (host may not resolve in test)
128
- if (err instanceof Error && err.message.includes('private IP')) {
129
- throw err;
193
+ let addresses;
194
+ try {
195
+ addresses = await resolve(hostname);
196
+ }
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}`);
130
203
  }
131
- // DNS lookup failure - let the actual HTTP request handle it
132
204
  }
133
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
+ }
134
221
  /**
135
222
  * Validate that a URL is safe to fetch (not pointing to private/internal resources).
136
223
  *
@@ -154,10 +241,25 @@ export async function validateUrl(url, allowPrivate = false) {
154
241
  * Whether the current process is running in a serverless environment
155
242
  * (anything other than a long-lived ``server`` runtime).
156
243
  *
157
- * Python parity: ``signalwire.utils.is_serverless_mode``.
244
+ * Python equivalent: ``signalwire.utils.is_serverless_mode``.
158
245
  */
159
246
  export function isServerlessMode() {
160
- const [mode] = getExecutionMode();
247
+ const mode = getExecutionMode();
161
248
  return mode !== 'server';
162
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
+ }
163
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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"}
@@ -0,0 +1,183 @@
1
+ /**
2
+ * Semantic gates: natural-language preconditions on a SWAIG function.
3
+ *
4
+ * A semantic gate is a yes/no question a decision model answers about the call
5
+ * right before the platform dispatches the function. Every gate on the function
6
+ * must pass for it to run. When one doesn't, the function isn't dispatched, and
7
+ * the model gets that gate's `on_fail` output instead, as if a data_map had
8
+ * returned it.
9
+ *
10
+ * The platform refuses the whole function when any of its gates is invalid, so
11
+ * the SDK checks gates by the platform's rules when a tool is defined, and
12
+ * throws instead of sending a function the platform would drop. A platform
13
+ * release without semantic gates ignores them and runs the function ungated.
14
+ *
15
+ * Python equivalent: `signalwire/core/semantic_gate.py`.
16
+ */
17
+ import { FunctionResult } from './FunctionResult.js';
18
+ /**
19
+ * Phrases a function says, keyed by language code, `"auto"` (translated into
20
+ * the call's language on first use) or `"default"`. An entry is a phrase, or a
21
+ * list of phrases, a wait script, spoken one at a time while the call waits.
22
+ */
23
+ export type FillerPhrases = Record<string, ReadonlyArray<string | readonly string[]>>;
24
+ /** The most gates one function can carry. */
25
+ export declare const MAX_GATES = 8;
26
+ /** The longest gate question, in UTF-8 bytes. */
27
+ export declare const MAX_QUESTION_BYTES = 8192;
28
+ /** The longest `criteria.true` or `criteria.false`, in UTF-8 bytes. */
29
+ export declare const MAX_CRITERIA_BYTES = 2048;
30
+ /** The largest `on_fail` output, as compact JSON in UTF-8 bytes. */
31
+ export declare const MAX_ON_FAIL_BYTES = 8192;
32
+ /**
33
+ * Hooks the platform calls itself, the function it intercepts by name, and the
34
+ * built-in function names: gates on any of them are refused.
35
+ */
36
+ export declare const RESERVED_FUNCTION_NAMES: ReadonlySet<string>;
37
+ /** Options for {@link SemanticGate} besides its question, threshold and `on_fail`. */
38
+ export interface SemanticGateOptions {
39
+ /**
40
+ * The gate's id, 1 to 64 letters, digits or underscores, unique within the
41
+ * function. Defaults to `gate_<n>`, 1-based.
42
+ */
43
+ id?: string;
44
+ /** What yes means, at most 2 KB. */
45
+ trueMeans?: string;
46
+ /** What no means, at most 2 KB. */
47
+ falseMeans?: string;
48
+ }
49
+ /**
50
+ * One semantic gate: a yes/no question about the call, and what the model gets
51
+ * when the answer isn't yes.
52
+ *
53
+ * The decision model sees the recent dialogue as `conversation`, the call's
54
+ * `global_data.semantic_state` as `semantic_state`, and the proposed call as
55
+ * `proposed_function`. Write each question as one proposition and name what
56
+ * it's about with those field names, in backticks. The model reads literally
57
+ * and doesn't do arithmetic or compare dates, so put a computed result in
58
+ * `semantic_state` instead of asking for it.
59
+ *
60
+ * The gate is checked when the tool that carries it is defined, not when it's
61
+ * built.
62
+ *
63
+ * @example
64
+ * ```typescript
65
+ * new SemanticGate(
66
+ * 'Has the caller explicitly asked to cancel their account in `conversation`?',
67
+ * 0.95,
68
+ * new FunctionResult()
69
+ * .setToolResponse(
70
+ * 'cancel_account was not run.',
71
+ * 'Ask the caller to confirm that they want to cancel.',
72
+ * )
73
+ * .updateGlobalData({ cancel_attempted: true }),
74
+ * {
75
+ * id: 'explicit_request',
76
+ * trueMeans: 'The caller says they want to cancel.',
77
+ * falseMeans: 'The caller asked about cancelling, or said something else.',
78
+ * },
79
+ * );
80
+ * ```
81
+ */
82
+ export declare class SemanticGate {
83
+ /** The yes/no question. */
84
+ question: string;
85
+ /** The probability of yes, above 0 and at most 1, at or above which the gate passes. */
86
+ threshold: number;
87
+ /** The gate's id, or undefined for the default `gate_<n>`. */
88
+ id?: string;
89
+ /** What yes and no mean, keyed `true` and `false`. */
90
+ criteria: {
91
+ true?: string;
92
+ false?: string;
93
+ };
94
+ /** The output the model gets when this is the first gate that fails. */
95
+ onFail: Record<string, unknown>;
96
+ /**
97
+ * @param question - The yes/no question, at most 8 KB. Its `${...}`
98
+ * variables are expanded from the call's global data when the gate is
99
+ * checked; `@{...}` functions are not.
100
+ * @param threshold - The probability of yes, above 0 and at most 1, at or
101
+ * above which the gate passes. Thresholds are calibrated per decision model
102
+ * version.
103
+ * @param onFail - What the model gets when this is the first gate that fails:
104
+ * the tool result text, a FunctionResult, or a data_map output object. A
105
+ * FunctionResult's response and actions are used; its `tool_prompt` becomes
106
+ * a system message after the tool result in the text pipeline, which OpenAI
107
+ * Realtime agents don't use. The actions run as written, without template
108
+ * expansion.
109
+ * @param opts - The gate's id, and what yes and no mean.
110
+ * @throws {Error} When `onFail` has no response: a blocked call must never
111
+ * read as a success.
112
+ */
113
+ constructor(question: string, threshold: number, onFail: string | FunctionResult | Record<string, unknown>, opts?: SemanticGateOptions);
114
+ /**
115
+ * The gate as the platform reads it.
116
+ * @returns The gate object: `id` (when set), `question`, `criteria` (when
117
+ * set), `threshold` and `on_fail`.
118
+ */
119
+ toDict(): Record<string, unknown>;
120
+ }
121
+ /**
122
+ * Whether a function definition has a `gates` or `gate_fillers` key, found as
123
+ * the platform finds it: without regard to ASCII case.
124
+ *
125
+ * Internal: AgentBase and SWMLService use it to decide what to check.
126
+ * @param fields - A function definition.
127
+ * @returns True when either key is present.
128
+ */
129
+ export declare function _hasGateFields(fields: Record<string, unknown>): boolean;
130
+ /**
131
+ * How many bytes cJSON_PrintUnformatted gives the JSON value, as the platform
132
+ * measures it. Exported for tests; the emitted values aren't changed.
133
+ */
134
+ export declare function _cjsonPrintedLength(value: unknown): number;
135
+ /**
136
+ * Return a function's gates as the platform reads them.
137
+ *
138
+ * Every way to define a tool runs this through {@link applyGateFields}.
139
+ * @param gates - SemanticGate objects or gate objects, 1 to 8.
140
+ * @param functionName - The function's name.
141
+ * @returns Each gate as a plain object, deep-copied.
142
+ * @throws {Error} For anything that would make the platform refuse the
143
+ * function, with the platform's reason.
144
+ */
145
+ export declare function gateDefinitions(gates: ReadonlyArray<SemanticGate | Record<string, unknown>>, functionName: string): Record<string, unknown>[];
146
+ /**
147
+ * Check and normalize `gates` and `gate_fillers` in a function's fields, in
148
+ * place.
149
+ *
150
+ * `fields` is a function definition, or the extra fields of one. Its `gates`
151
+ * become the objects the platform reads. A `gate_fillers` left out or `null`
152
+ * is removed, as the platform ignores it.
153
+ * @param fields - The function definition or its extra fields.
154
+ * @param functionName - The function's name.
155
+ * @param opts - Options.
156
+ * @param opts.definition - True when `fields` is a whole function definition
157
+ * sent as written, such as a DataMap's or a raw one. Then its `gates` and
158
+ * `gate_fillers` keys are found as the platform finds them, without regard
159
+ * to case; `gates: null` is refused, as the platform refuses the function
160
+ * for a JSON null; and a gated function needs a description. Otherwise a
161
+ * null or undefined `gates` means no gates, as an option left out does.
162
+ * @throws {Error} For gates the platform would refuse, `gate_fillers` on a
163
+ * function without gates, which the platform ignores, or a gated
164
+ * definition without a description.
165
+ */
166
+ export declare function applyGateFields(fields: Record<string, unknown>, functionName: string, opts?: {
167
+ definition?: boolean;
168
+ }): void;
169
+ /**
170
+ * Check a gated function as it will be sent, after every merge and expansion.
171
+ *
172
+ * Besides its gates, the platform needs a gated function to have a name, a
173
+ * description (`description` or `purpose`), and a `web_hook_url` or a
174
+ * `data_map`; a function without them isn't registered at all. The SWAIG
175
+ * `defaults.web_hook_url` counts as its URL.
176
+ *
177
+ * Internal: AgentBase calls it on each function it renders.
178
+ * @param definition - The function definition as it will be sent.
179
+ * @param defaultWebhookUrl - The SWAIG defaults `web_hook_url`, if any.
180
+ * @throws {Error} For gates the platform would refuse, or a gated function
181
+ * the platform wouldn't register.
182
+ */
183
+ export declare function _checkGatedFunction(definition: Record<string, unknown>, defaultWebhookUrl?: string): void;