@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
package/dist/DataMap.d.ts CHANGED
@@ -5,11 +5,19 @@
5
5
  * without requiring webhook endpoints.
6
6
  */
7
7
  import { FunctionResult } from './FunctionResult.js';
8
+ import { SemanticGate, type FillerPhrases } from './SemanticGate.js';
8
9
  /**
9
10
  * Set the global allowed env var prefixes for `${ENV.*}` expansion.
10
11
  *
11
- * Only environment variables whose names start with one of these prefixes
12
- * will be expanded. An empty array allows all variables (escape hatch).
12
+ * This is the default list for every DataMap that has no list of its own
13
+ * (see {@link DataMap.setAllowedEnvPrefixes}), read when each DataMap's
14
+ * `toSwaigFunction()` runs. Only variables whose names start with one of
15
+ * these prefixes are expanded; any other `${ENV.NAME}` becomes an empty
16
+ * string. The default is `['SIGNALWIRE_', 'SWML_', 'SW_']`.
17
+ *
18
+ * Expanded values are written into the SWML document, so the list limits
19
+ * which variables a template can publish there. An empty array allows every
20
+ * variable and removes that protection.
13
21
  *
14
22
  * @param prefixes - Array of prefix strings to allow.
15
23
  */
@@ -22,9 +30,19 @@ export declare function getAllowedEnvPrefixes(): string[];
22
30
  /**
23
31
  * Fluent builder for SWAIG data_map configurations.
24
32
  *
25
- * Creates server-side tool definitions that execute on SignalWire's infrastructure
26
- * **without** requiring a webhook endpoint in your application. Ideal for simple
27
- * third-party API integrations (REST calls + pattern-matched response shaping).
33
+ * Builds a SWAIG function whose `data_map` the SignalWire platform runs, so
34
+ * the tool needs no webhook endpoint in your application. The platform makes
35
+ * the HTTP requests, matches the expressions and expands the templates; this
36
+ * class only builds the definition.
37
+ *
38
+ * What a template can read depends on where it is. A webhook's `url` and
39
+ * `params`, the top-level expressions and the fallback output read the call
40
+ * data, where the arguments are `${args.city}`. A webhook's `output`,
41
+ * `expressions` and `foreach` read that webhook's response instead: a JSON
42
+ * object's fields from the root (`${temp}`), a JSON array under `array`
43
+ * (`${array[0].joke}`), and the call data under `input`, so the arguments
44
+ * there are `${input.args.city}`; `${args.city}` expands to nothing.
45
+ * Header values are sent as written, with no templates expanded.
28
46
  *
29
47
  * @example Simple webhook-driven tool (no handler needed)
30
48
  * ```ts
@@ -32,9 +50,9 @@ export declare function getAllowedEnvPrefixes(): string[];
32
50
  *
33
51
  * const weather = new DataMap('get_weather')
34
52
  * .purpose('Look up the current weather for a city')
35
- * .parameter('city', 'string', 'The city name', true)
36
- * .webhook('GET', 'https://api.example.com/weather?city=${args.city}')
37
- * .output(new FunctionResult('In ${city} it is ${response.temp}°F and ${response.condition}.'));
53
+ * .parameter('city', 'string', 'The city name', { required: true })
54
+ * .webhook('GET', 'https://api.example.com/weather?city=${enc:args.city}')
55
+ * .output(new FunctionResult('In ${input.args.city} it is ${temp}°F and ${condition}.'));
38
56
  *
39
57
  * // Register onto an agent:
40
58
  * agent.registerSwaigFunction(weather.toSwaigFunction());
@@ -44,14 +62,14 @@ export declare function getAllowedEnvPrefixes(): string[];
44
62
  * ```ts
45
63
  * new DataMap('classify_intent')
46
64
  * .purpose('Route callers to the right department.')
47
- * .parameter('utterance', 'string', 'What the caller said', true)
48
- * .expression('${args.utterance}', /billing|invoice|charge/i, new FunctionResult('billing'))
49
- * .expression('${args.utterance}', /tech|broken|error/i, new FunctionResult('support'));
65
+ * .parameter('utterance', 'string', 'What the caller said', { required: true })
66
+ * .expression('${lc:args.utterance}', 'billing|invoice|charge', new FunctionResult('billing'))
67
+ * .expression('${lc:args.utterance}', 'tech|broken|error', new FunctionResult('support'));
50
68
  * ```
51
69
  *
52
- * @see {@link FunctionResult} — response shape used in `.output()` / `.expression()`
53
- * @see {@link createSimpleApiTool} — one-liner helper for REST API tools
54
- * @see {@link AgentBase.defineTool} — alternative for tools that run in your process
70
+ * @see {@link FunctionResult}: the response shape used in `.output()` and `.expression()`
71
+ * @see {@link createSimpleApiTool}: a helper for a tool with one webhook and one output
72
+ * @see {@link AgentBase.defineTool}: for tools that run in your process
55
73
  */
56
74
  export declare class DataMap {
57
75
  /** The name of the SWAIG function this data map defines. */
@@ -62,6 +80,8 @@ export declare class DataMap {
62
80
  private _webhooks;
63
81
  private _output;
64
82
  private _errorKeys;
83
+ private _gates;
84
+ private _gateFillers;
65
85
  private _expandEnv;
66
86
  private _allowedEnvPrefixes;
67
87
  /**
@@ -69,31 +89,37 @@ export declare class DataMap {
69
89
  */
70
90
  constructor(functionName: string);
71
91
  /**
72
- * Enable `${ENV.*}` variable expansion in URLs, bodies, and outputs.
73
- * @param enabled - Whether to enable expansion (defaults to true).
92
+ * Turn on `${ENV.NAME}` expansion for this DataMap (off until called).
93
+ *
94
+ * The SDK, not the platform, does this expansion: `toSwaigFunction()`
95
+ * replaces each `${ENV.NAME}` in every string of the definition with
96
+ * `process.env.NAME`, or with an empty string when the variable is unset or
97
+ * its name has no allowed prefix (see {@link DataMap.setAllowedEnvPrefixes}).
98
+ * The values are written into the SWML document.
99
+ *
100
+ * @param enabled - Whether to turn expansion on (defaults to true).
74
101
  * @returns This instance for chaining.
75
102
  */
76
103
  enableEnvExpansion(enabled?: boolean): this;
77
104
  /**
78
105
  * Set the allowed env var prefixes for this DataMap instance.
79
106
  *
80
- * Overrides the global defaults. Only env vars whose names start with
81
- * one of these prefixes will be expanded. An empty array allows all.
107
+ * Replaces the global default list (`SIGNALWIRE_`, `SWML_`, `SW_` unless
108
+ * changed with the exported `setAllowedEnvPrefixes()`) for this DataMap.
109
+ * Only variables whose names start with one of these prefixes are
110
+ * expanded. An empty array allows every variable.
82
111
  *
83
112
  * @param prefixes - Array of prefix strings to allow.
84
113
  * @returns This instance for chaining.
85
114
  */
86
115
  setAllowedEnvPrefixes(prefixes: string[]): this;
87
116
  /**
88
- * Set the purpose (description) for this data-map tool — READ BY THE LLM.
117
+ * Set the purpose (description) for this data-map tool. The model reads it.
89
118
  *
90
- * This string is rendered into the OpenAI tool schema `description`
91
- * field and sent to the model on every turn. The model uses it to
92
- * decide WHEN to call this tool. It is **prompt engineering**, not
93
- * developer documentation.
94
- *
95
- * A vague `purpose()` is the #1 cause of "the model has the right tool
96
- * but doesn't call it" failures with data-map tools.
119
+ * This string becomes the function's `description` in the SWML, which the
120
+ * model reads to decide WHEN to call this tool. Write it as a prompt, not
121
+ * as developer documentation. With a vague `purpose()`, the model can have
122
+ * the right tool and not call it.
97
123
  *
98
124
  * ### Bad vs good
99
125
  *
@@ -119,12 +145,12 @@ export declare class DataMap {
119
145
  */
120
146
  description(description: string): this;
121
147
  /**
122
- * Define a parameter for this data-map tool — `description` is READ BY THE LLM.
148
+ * Define a parameter for this data-map tool. The model reads its `description`.
123
149
  *
124
- * Each parameter `description` is rendered into the OpenAI tool schema
125
- * under `parameters.properties.<name>.description` and sent to the
126
- * model. The model uses it to decide HOW to fill in the argument from
127
- * user speech. It is **prompt engineering**, not developer FYI.
150
+ * Each parameter's `description` becomes
151
+ * `parameters.properties.<name>.description` in the SWML. The model reads
152
+ * it to decide HOW to fill in the argument from what the caller said.
153
+ * Write it as a prompt, not as developer documentation.
128
154
  *
129
155
  * ### Bad vs good
130
156
  *
@@ -140,7 +166,8 @@ export declare class DataMap {
140
166
  * @param paramType - The JSON Schema type (e.g., "string", "number").
141
167
  * @param description - Prompt-engineering description telling the model
142
168
  * how to extract this value from the user's utterance. Read by the LLM.
143
- * @param opts - Optional flags for required and enum constraints.
169
+ * @param opts - Options object: `{ required: true }` lists the parameter in the
170
+ * schema's `required` array, and `enum` restricts its values.
144
171
  * @returns This instance for chaining.
145
172
  */
146
173
  parameter(name: string, paramType: string, description: string, opts?: {
@@ -149,18 +176,50 @@ export declare class DataMap {
149
176
  }): this;
150
177
  /**
151
178
  * Add a pattern-matching expression that evaluates a test value against a regex.
152
- * @param testValue - The string or template variable to test.
153
- * @param pattern - A regex pattern (string or RegExp) to match against.
179
+ *
180
+ * The platform expands `testValue` against the call data, where an
181
+ * argument is `${args.command}`, and searches it for `pattern`, which can
182
+ * match anywhere in the value. It tries the expressions in order and stops
183
+ * at the first that produces a result: a match gives its `output`, and a
184
+ * non-match gives its `nomatch-output` when it has one, so no expression
185
+ * after one with a `nomatchOutput` runs. The top-level expressions run
186
+ * before any webhook, and one that produces a result ends the function.
187
+ * @param testValue - The string or template variable to test, such as `'${args.input}'`.
188
+ * @param pattern - A regex pattern (string or RegExp) to match against. The
189
+ * platform wraps a pattern that doesn't start with `/` as `/pattern/i`, so
190
+ * matching is case-insensitive by default. To match case-sensitively, write
191
+ * the pattern as `'/pattern/'`. For a RegExp only `.source` is kept, so its
192
+ * flags are dropped and it matches case-insensitively.
154
193
  * @param output - The result to return when the pattern matches.
155
- * @param nomatchOutput - Optional result to return when the pattern does not match.
194
+ * @param nomatchOutput - Optional result, written as `nomatch-output`, which the
195
+ * platform returns when the pattern doesn't match; later expressions are then
196
+ * not tried. The SWML schema's expression object doesn't define that key.
156
197
  * @returns This instance for chaining.
157
198
  */
158
199
  expression(testValue: string, pattern: string | RegExp, output: FunctionResult, nomatchOutput?: FunctionResult): this;
159
200
  /**
160
201
  * Add a webhook that is called when this data map tool is invoked.
161
- * @param method - HTTP method (e.g., "GET", "POST").
162
- * @param url - The webhook URL to call.
163
- * @param opts - Optional headers, form parameter name, and argument settings.
202
+ *
203
+ * The platform sends GET and POST requests only. A webhook is sent as a
204
+ * POST when `method` is `POST` or when it has params (see
205
+ * {@link DataMap.params}), and as a GET otherwise, so `PUT`, `PATCH` and
206
+ * `DELETE` are sent as GET.
207
+ *
208
+ * The platform tries the webhooks in order, skipping one whose
209
+ * `requireArgs` are all absent. The first one it requests decides the
210
+ * result: if it fails, the fallback output is used and no later webhook is
211
+ * tried. A later webhook is useful only when the earlier ones can be skipped
212
+ * by their `requireArgs`.
213
+ * @param method - HTTP method: `GET` or `POST`. It is uppercased.
214
+ * @param url - The webhook URL to call. The platform expands templates in
215
+ * it against the call data, such as `${enc:args.city}`.
216
+ * @param opts - Optional `headers` (sent as written, with no templates
217
+ * expanded), `formParam` (sends the JSON params URL-encoded as one form
218
+ * field with this name; written as `form_param`, which the SWML schema
219
+ * doesn't define), `inputArgsAsParams` (merges the function's arguments
220
+ * into params, which makes the request a POST) and `requireArgs` (the
221
+ * webhook is skipped, without a request, unless at least one of these
222
+ * arguments is present).
164
223
  * @returns This instance for chaining.
165
224
  */
166
225
  webhook(method: string, url: string, opts?: {
@@ -171,24 +230,51 @@ export declare class DataMap {
171
230
  }): this;
172
231
  /**
173
232
  * Set pattern-matching expressions on the most recently added webhook.
233
+ *
234
+ * They run after the webhook's foreach, against its response, and the first
235
+ * one that produces an output replaces the webhook's own output. Their
236
+ * templates read the response's fields from the root, and the call data
237
+ * under `input`, such as `${input.args.query}`.
174
238
  * @param expressions - Array of expression objects to evaluate against the webhook response.
175
239
  * @returns This instance for chaining.
176
240
  */
177
241
  webhookExpressions(expressions: Record<string, unknown>[]): this;
178
242
  /**
179
- * Set the JSON body for the most recently added webhook.
180
- * @param data - The request body object.
243
+ * Set the JSON request body for the most recently added webhook; the same
244
+ * as {@link DataMap.params}.
245
+ *
246
+ * The platform reads a webhook's request body from its `params` field and
247
+ * has no `body` field, so this sets `params`, replacing any `params`
248
+ * already set. See {@link DataMap.params} for how the body is sent.
249
+ * @param data - The request body object. Values can contain templates.
181
250
  * @returns This instance for chaining.
182
251
  */
183
252
  body(data: Record<string, unknown>): this;
184
253
  /**
185
- * Set query or form parameters for the most recently added webhook.
186
- * @param data - The parameters object.
254
+ * Set the JSON request body for the most recently added webhook, written as
255
+ * its `params`.
256
+ *
257
+ * The platform sends `params` as the request's JSON body, not as URL query
258
+ * parameters, expanding templates in its values first (against the call
259
+ * data, so arguments are `${args.name}`), and a webhook with `params` is
260
+ * always a POST, whatever its method. Put query-string values for a GET
261
+ * request in the URL instead.
262
+ * @param data - The request body object. Values can contain templates.
187
263
  * @returns This instance for chaining.
188
264
  */
189
265
  params(data: Record<string, unknown>): this;
190
266
  /**
191
267
  * Configure iteration over an array in the webhook response.
268
+ *
269
+ * `input_key` is the path to the array in the webhook's template data, such
270
+ * as `"orders"` or `"data.items"` (a path, not a template). `append` is
271
+ * expanded once per element, reading an object element's fields as
272
+ * `${this.field}` and a string or number element as `${this}`, along with
273
+ * the response and `${input.args.name}`. The joined text is stored under
274
+ * `output_key`, which the webhook's output reads as `${<output_key>}`.
275
+ * `max`, when above 0, limits the elements used. The platform runs the
276
+ * foreach before the webhook's expressions and output, and skips a foreach
277
+ * that lacks `input_key`, `output_key` or `append`.
192
278
  * @param config - Foreach configuration with input/output keys, append template, and optional max.
193
279
  * @returns This instance for chaining.
194
280
  */
@@ -200,28 +286,73 @@ export declare class DataMap {
200
286
  }): this;
201
287
  /**
202
288
  * Set the output template for the most recently added webhook.
289
+ *
290
+ * Its templates read the webhook's JSON response: an object's fields from
291
+ * the root, such as `${current.temp_f}`, or `${array[0].x}` for an array.
292
+ * The call data is under `input`, so an argument is `${input.args.city}`;
293
+ * `${args.city}` is empty here. A foreach's text is `${<output_key>}`.
203
294
  * @param result - The FunctionResult to use as the output template.
204
295
  * @returns This instance for chaining.
205
296
  */
206
297
  output(result: FunctionResult): this;
207
298
  /**
208
- * Set a fallback output used when no webhook or expression matches.
299
+ * Set a fallback output: the `data_map`'s own `output`, used when no
300
+ * expression matched and no webhook produced a result (the webhook failed,
301
+ * none was requested, or its expressions didn't match and it has no
302
+ * output). Its templates read the call data, so arguments are `${args.name}`.
209
303
  * @param result - The FunctionResult to use as the fallback.
210
304
  * @returns This instance for chaining.
211
305
  */
212
306
  fallbackOutput(result: FunctionResult): this;
213
307
  /**
214
308
  * Set error keys on the most recently added webhook, or globally if no webhook exists.
215
- * @param keys - Response keys that indicate an error occurred.
309
+ *
310
+ * The platform fails the webhook when any of these keys is present at the
311
+ * top level of its JSON object response, whatever the value (`"errors": []`,
312
+ * `false` and `null` count). An HTTP status outside 200-299 isn't a failure
313
+ * by itself: the platform adds an `http_code` key to such a response, so
314
+ * `'http_code'` in this list fails the webhook on any such status. A failed
315
+ * webhook gives the fallback output; the next webhook isn't tried.
316
+ *
317
+ * The platform reads error keys only on a webhook. Called before any
318
+ * webhook, this sets a top-level `error_keys` field, which the platform
319
+ * ignores (see {@link DataMap.globalErrorKeys}).
320
+ * @param keys - Response keys whose presence marks the response as a failure.
216
321
  * @returns This instance for chaining.
217
322
  */
218
323
  errorKeys(keys: string[]): this;
219
324
  /**
220
- * Set error keys at the top-level data map scope, regardless of webhook context.
325
+ * Set `error_keys` on the `data_map` object itself, regardless of webhook context.
326
+ *
327
+ * The SWML schema defines `error_keys` only on a webhook, and the platform
328
+ * reads it only there, so these keys fail no request. Use
329
+ * {@link DataMap.errorKeys} after each webhook.
221
330
  * @param keys - Response keys that indicate an error occurred.
222
331
  * @returns This instance for chaining.
223
332
  */
224
333
  globalErrorKeys(keys: string[]): this;
334
+ /**
335
+ * Add a semantic gate: a yes/no precondition a decision model checks right
336
+ * before the platform runs this function.
337
+ *
338
+ * Every gate must pass for the function to run. When one doesn't, the
339
+ * data_map doesn't run, and the model gets that gate's `on_fail` output.
340
+ * Call once per gate, up to 8. The gates are checked by the platform's rules
341
+ * when the function is built ({@link DataMap.toSwaigFunction}).
342
+ * @param gate - A {@link SemanticGate}, or a gate object.
343
+ * @returns This instance for chaining.
344
+ */
345
+ gate(gate: SemanticGate | Record<string, unknown>): this;
346
+ /**
347
+ * Set what the AI says while this function's gates are checked.
348
+ *
349
+ * Shaped like a function's fillers: phrases keyed by language code,
350
+ * `"auto"` or `"default"`. Without them, the AI says nothing while the gates
351
+ * are checked. Only for a function with gates.
352
+ * @param fillers - Phrases by language.
353
+ * @returns This instance for chaining.
354
+ */
355
+ gateFillers(fillers: FillerPhrases): this;
225
356
  /**
226
357
  * Register this DataMap tool with an AgentBase instance.
227
358
  * @param agent - An object with a registerSwaigFunction method (typically an AgentBase).
@@ -233,11 +364,21 @@ export declare class DataMap {
233
364
  /**
234
365
  * Serialize this data map to a SWAIG function definition object.
235
366
  * @returns A plain object suitable for inclusion in the SWML SWAIG array.
367
+ * @throws {Error} For gates the platform would refuse, or gate fillers
368
+ * without gates. They are checked after environment variables are
369
+ * expanded, as they will be sent.
236
370
  */
237
371
  toSwaigFunction(): Record<string, unknown>;
238
372
  }
239
373
  /**
240
374
  * Create a DataMap tool that calls a single API endpoint and formats the response.
375
+ *
376
+ * `url` reads the arguments as `${args.name}`. `responseTemplate` becomes
377
+ * the webhook's output, which reads the response's fields from the root,
378
+ * such as `${current.temp_f}`, and the arguments as `${input.args.name}`.
379
+ * `body` is set as the webhook's params (see {@link DataMap.body}), so a
380
+ * tool with a body is sent as a POST. `method` defaults to `GET`; headers
381
+ * are sent as written.
241
382
  * @param opts - Configuration including name, URL, response template, and optional parameters.
242
383
  * @returns A configured DataMap instance ready for registration.
243
384
  */