@signalwire/sdk 2.0.0 → 2.0.2

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 (612) hide show
  1. package/dist/AgentBase.d.ts +1045 -0
  2. package/dist/AgentBase.js +2375 -0
  3. package/dist/AgentBase.js.map +1 -0
  4. package/dist/AgentServer.d.ts +146 -0
  5. package/dist/AgentServer.js +388 -0
  6. package/dist/AgentServer.js.map +1 -0
  7. package/dist/AuthHandler.d.ts +127 -0
  8. package/dist/AuthHandler.js +212 -0
  9. package/dist/AuthHandler.js.map +1 -0
  10. package/dist/ConfigLoader.d.ts +170 -0
  11. package/dist/ConfigLoader.js +393 -0
  12. package/dist/ConfigLoader.js.map +1 -0
  13. package/dist/ContextBuilder.d.ts +652 -0
  14. package/dist/ContextBuilder.js +1115 -0
  15. package/dist/ContextBuilder.js.map +1 -0
  16. package/dist/DataMap.d.ts +271 -0
  17. package/dist/DataMap.js +430 -0
  18. package/dist/DataMap.js.map +1 -0
  19. package/dist/FunctionResult.d.ts +481 -0
  20. package/dist/FunctionResult.js +775 -0
  21. package/dist/FunctionResult.js.map +1 -0
  22. package/dist/Logger.d.ts +113 -0
  23. package/dist/Logger.js +320 -0
  24. package/dist/Logger.js.map +1 -0
  25. package/dist/PomBuilder.d.ts +208 -0
  26. package/dist/PomBuilder.js +409 -0
  27. package/dist/PomBuilder.js.map +1 -0
  28. package/dist/PromptManager.d.ts +85 -0
  29. package/dist/PromptManager.js +108 -0
  30. package/dist/PromptManager.js.map +1 -0
  31. package/dist/SWMLHandler.d.ts +159 -0
  32. package/dist/SWMLHandler.js +229 -0
  33. package/dist/SWMLHandler.js.map +1 -0
  34. package/dist/SWMLService.d.ts +326 -0
  35. package/dist/SWMLService.js +610 -0
  36. package/dist/SWMLService.js.map +1 -0
  37. package/dist/SchemaUtils.d.ts +108 -0
  38. package/dist/SchemaUtils.js +317 -0
  39. package/dist/SchemaUtils.js.map +1 -0
  40. package/dist/SecurityUtils.d.ts +60 -0
  41. package/{src/SecurityUtils.ts → dist/SecurityUtils.js} +82 -83
  42. package/dist/SecurityUtils.js.map +1 -0
  43. package/dist/ServerlessAdapter.d.ts +119 -0
  44. package/dist/ServerlessAdapter.js +188 -0
  45. package/dist/ServerlessAdapter.js.map +1 -0
  46. package/dist/SessionManager.d.ts +142 -0
  47. package/dist/SessionManager.js +260 -0
  48. package/dist/SessionManager.js.map +1 -0
  49. package/dist/SslConfig.d.ts +77 -0
  50. package/dist/SslConfig.js +100 -0
  51. package/dist/SslConfig.js.map +1 -0
  52. package/dist/SwaigFunction.d.ts +159 -0
  53. package/dist/SwaigFunction.js +209 -0
  54. package/dist/SwaigFunction.js.map +1 -0
  55. package/dist/SwmlBuilder.d.ts +165 -0
  56. package/dist/SwmlBuilder.js +247 -0
  57. package/dist/SwmlBuilder.js.map +1 -0
  58. package/dist/SwmlVerbMethods.generated.d.ts +254 -0
  59. package/dist/SwmlVerbMethods.generated.js +9 -0
  60. package/dist/SwmlVerbMethods.generated.js.map +1 -0
  61. package/dist/TypeInference.d.ts +71 -0
  62. package/dist/TypeInference.js +164 -0
  63. package/dist/TypeInference.js.map +1 -0
  64. package/dist/WebService.d.ts +148 -0
  65. package/dist/WebService.js +532 -0
  66. package/dist/WebService.js.map +1 -0
  67. package/dist/cli/agent-loader.d.ts +22 -0
  68. package/dist/cli/agent-loader.js +144 -0
  69. package/dist/cli/agent-loader.js.map +1 -0
  70. package/dist/cli/mock-data.d.ts +37 -0
  71. package/dist/cli/mock-data.js +80 -0
  72. package/dist/cli/mock-data.js.map +1 -0
  73. package/dist/cli/swaig-test.d.ts +32 -0
  74. package/dist/cli/swaig-test.js +418 -0
  75. package/dist/cli/swaig-test.js.map +1 -0
  76. package/dist/generateVerbTypes.d.ts +11 -0
  77. package/dist/generateVerbTypes.js +265 -0
  78. package/dist/generateVerbTypes.js.map +1 -0
  79. package/dist/index.d.ts +146 -0
  80. package/dist/index.js +152 -0
  81. package/dist/index.js.map +1 -0
  82. package/dist/livewire/index.d.ts +653 -0
  83. package/dist/livewire/index.js +992 -0
  84. package/dist/livewire/index.js.map +1 -0
  85. package/dist/prefabs/ConciergeAgent.d.ts +89 -0
  86. package/dist/prefabs/ConciergeAgent.js +245 -0
  87. package/dist/prefabs/ConciergeAgent.js.map +1 -0
  88. package/dist/prefabs/FAQBotAgent.d.ts +113 -0
  89. package/dist/prefabs/FAQBotAgent.js +329 -0
  90. package/dist/prefabs/FAQBotAgent.js.map +1 -0
  91. package/dist/prefabs/InfoGathererAgent.d.ts +126 -0
  92. package/dist/prefabs/InfoGathererAgent.js +287 -0
  93. package/dist/prefabs/InfoGathererAgent.js.map +1 -0
  94. package/dist/prefabs/ReceptionistAgent.d.ts +104 -0
  95. package/dist/prefabs/ReceptionistAgent.js +303 -0
  96. package/dist/prefabs/ReceptionistAgent.js.map +1 -0
  97. package/dist/prefabs/SurveyAgent.d.ts +148 -0
  98. package/dist/prefabs/SurveyAgent.js +540 -0
  99. package/dist/prefabs/SurveyAgent.js.map +1 -0
  100. package/{src/prefabs/index.ts → dist/prefabs/index.d.ts} +1 -15
  101. package/dist/prefabs/index.js +14 -0
  102. package/dist/prefabs/index.js.map +1 -0
  103. package/dist/relay/Action.d.ts +258 -0
  104. package/dist/relay/Action.js +402 -0
  105. package/dist/relay/Action.js.map +1 -0
  106. package/dist/relay/Call.d.ts +697 -0
  107. package/dist/relay/Call.js +1062 -0
  108. package/dist/relay/Call.js.map +1 -0
  109. package/dist/relay/Deferred.d.ts +44 -0
  110. package/dist/relay/Deferred.js +69 -0
  111. package/dist/relay/Deferred.js.map +1 -0
  112. package/dist/relay/Message.d.ts +103 -0
  113. package/dist/relay/Message.js +169 -0
  114. package/dist/relay/Message.js.map +1 -0
  115. package/dist/relay/RelayClient.d.ts +302 -0
  116. package/dist/relay/RelayClient.js +1019 -0
  117. package/dist/relay/RelayClient.js.map +1 -0
  118. package/dist/relay/RelayError.d.ts +15 -0
  119. package/dist/relay/RelayError.js +20 -0
  120. package/dist/relay/RelayError.js.map +1 -0
  121. package/dist/relay/RelayEvent.d.ts +254 -0
  122. package/dist/relay/RelayEvent.js +509 -0
  123. package/dist/relay/RelayEvent.js.map +1 -0
  124. package/dist/relay/constants.d.ts +90 -0
  125. package/{src/relay/constants.ts → dist/relay/constants.js} +11 -29
  126. package/dist/relay/constants.js.map +1 -0
  127. package/dist/relay/index.d.ts +16 -0
  128. package/dist/relay/index.js +18 -0
  129. package/dist/relay/index.js.map +1 -0
  130. package/dist/relay/types.d.ts +142 -0
  131. package/dist/relay/types.js +5 -0
  132. package/dist/relay/types.js.map +1 -0
  133. package/dist/rest/HttpClient.d.ts +80 -0
  134. package/dist/rest/HttpClient.js +148 -0
  135. package/dist/rest/HttpClient.js.map +1 -0
  136. package/dist/rest/RestError.d.ts +30 -0
  137. package/dist/rest/RestError.js +39 -0
  138. package/dist/rest/RestError.js.map +1 -0
  139. package/dist/rest/base/BaseResource.d.ts +24 -0
  140. package/dist/rest/base/BaseResource.js +29 -0
  141. package/dist/rest/base/BaseResource.js.map +1 -0
  142. package/dist/rest/base/CrudResource.d.ts +68 -0
  143. package/dist/rest/base/CrudResource.js +82 -0
  144. package/dist/rest/base/CrudResource.js.map +1 -0
  145. package/dist/rest/base/CrudWithAddresses.d.ts +22 -0
  146. package/dist/rest/base/CrudWithAddresses.js +25 -0
  147. package/dist/rest/base/CrudWithAddresses.js.map +1 -0
  148. package/{src/rest/index.ts → dist/rest/index.d.ts} +53 -122
  149. package/dist/rest/index.js +195 -0
  150. package/dist/rest/index.js.map +1 -0
  151. package/dist/rest/namespaces/addresses.d.ts +46 -0
  152. package/dist/rest/namespaces/addresses.js +55 -0
  153. package/dist/rest/namespaces/addresses.js.map +1 -0
  154. package/dist/rest/namespaces/calling.d.ts +382 -0
  155. package/dist/rest/namespaces/calling.js +478 -0
  156. package/dist/rest/namespaces/calling.js.map +1 -0
  157. package/dist/rest/namespaces/chat.d.ts +22 -0
  158. package/dist/rest/namespaces/chat.js +26 -0
  159. package/dist/rest/namespaces/chat.js.map +1 -0
  160. package/dist/rest/namespaces/compat.d.ts +585 -0
  161. package/dist/rest/namespaces/compat.js +735 -0
  162. package/dist/rest/namespaces/compat.js.map +1 -0
  163. package/dist/rest/namespaces/datasphere.d.ts +66 -0
  164. package/dist/rest/namespaces/datasphere.js +77 -0
  165. package/dist/rest/namespaces/datasphere.js.map +1 -0
  166. package/dist/rest/namespaces/fabric.d.ts +282 -0
  167. package/dist/rest/namespaces/fabric.js +373 -0
  168. package/dist/rest/namespaces/fabric.js.map +1 -0
  169. package/dist/rest/namespaces/imported-numbers.d.ts +22 -0
  170. package/dist/rest/namespaces/imported-numbers.js +26 -0
  171. package/dist/rest/namespaces/imported-numbers.js.map +1 -0
  172. package/dist/rest/namespaces/logs.d.ts +105 -0
  173. package/dist/rest/namespaces/logs.js +133 -0
  174. package/dist/rest/namespaces/logs.js.map +1 -0
  175. package/dist/rest/namespaces/lookup.d.ts +29 -0
  176. package/dist/rest/namespaces/lookup.js +32 -0
  177. package/dist/rest/namespaces/lookup.js.map +1 -0
  178. package/dist/rest/namespaces/mfa.d.ts +46 -0
  179. package/dist/rest/namespaces/mfa.js +54 -0
  180. package/dist/rest/namespaces/mfa.js.map +1 -0
  181. package/dist/rest/namespaces/number-groups.d.ts +49 -0
  182. package/dist/rest/namespaces/number-groups.js +58 -0
  183. package/dist/rest/namespaces/number-groups.js.map +1 -0
  184. package/dist/rest/namespaces/phone-numbers.d.ts +60 -0
  185. package/dist/rest/namespaces/phone-numbers.js +67 -0
  186. package/dist/rest/namespaces/phone-numbers.js.map +1 -0
  187. package/dist/rest/namespaces/project.d.ts +46 -0
  188. package/dist/rest/namespaces/project.js +56 -0
  189. package/dist/rest/namespaces/project.js.map +1 -0
  190. package/dist/rest/namespaces/pubsub.d.ts +22 -0
  191. package/dist/rest/namespaces/pubsub.js +26 -0
  192. package/dist/rest/namespaces/pubsub.js.map +1 -0
  193. package/dist/rest/namespaces/queues.d.ts +42 -0
  194. package/dist/rest/namespaces/queues.js +49 -0
  195. package/dist/rest/namespaces/queues.js.map +1 -0
  196. package/dist/rest/namespaces/recordings.d.ts +38 -0
  197. package/dist/rest/namespaces/recordings.js +45 -0
  198. package/dist/rest/namespaces/recordings.js.map +1 -0
  199. package/dist/rest/namespaces/registry.d.ts +141 -0
  200. package/dist/rest/namespaces/registry.js +178 -0
  201. package/dist/rest/namespaces/registry.js.map +1 -0
  202. package/dist/rest/namespaces/short-codes.d.ts +39 -0
  203. package/dist/rest/namespaces/short-codes.js +46 -0
  204. package/dist/rest/namespaces/short-codes.js.map +1 -0
  205. package/dist/rest/namespaces/sip-profile.d.ts +28 -0
  206. package/dist/rest/namespaces/sip-profile.js +34 -0
  207. package/dist/rest/namespaces/sip-profile.js.map +1 -0
  208. package/dist/rest/namespaces/verified-callers.d.ts +33 -0
  209. package/dist/rest/namespaces/verified-callers.js +39 -0
  210. package/dist/rest/namespaces/verified-callers.js.map +1 -0
  211. package/dist/rest/namespaces/video.d.ts +235 -0
  212. package/dist/rest/namespaces/video.js +297 -0
  213. package/dist/rest/namespaces/video.js.map +1 -0
  214. package/dist/rest/pagination.d.ts +39 -0
  215. package/dist/rest/pagination.js +78 -0
  216. package/dist/rest/pagination.js.map +1 -0
  217. package/dist/rest/types.d.ts +54 -0
  218. package/dist/rest/types.js +5 -0
  219. package/dist/rest/types.js.map +1 -0
  220. package/dist/skills/SkillBase.d.ts +404 -0
  221. package/dist/skills/SkillBase.js +471 -0
  222. package/dist/skills/SkillBase.js.map +1 -0
  223. package/dist/skills/SkillManager.d.ts +195 -0
  224. package/dist/skills/SkillManager.js +378 -0
  225. package/dist/skills/SkillManager.js.map +1 -0
  226. package/dist/skills/SkillRegistry.d.ts +176 -0
  227. package/dist/skills/SkillRegistry.js +310 -0
  228. package/dist/skills/SkillRegistry.js.map +1 -0
  229. package/dist/skills/builtin/api_ninjas_trivia.d.ts +47 -0
  230. package/dist/skills/builtin/api_ninjas_trivia.js +211 -0
  231. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -0
  232. package/dist/skills/builtin/ask_claude.d.ts +37 -0
  233. package/dist/skills/builtin/ask_claude.js +162 -0
  234. package/dist/skills/builtin/ask_claude.js.map +1 -0
  235. package/dist/skills/builtin/claude_skills.d.ts +75 -0
  236. package/dist/skills/builtin/claude_skills.js +753 -0
  237. package/dist/skills/builtin/claude_skills.js.map +1 -0
  238. package/dist/skills/builtin/custom_skills.d.ts +79 -0
  239. package/dist/skills/builtin/custom_skills.js +227 -0
  240. package/dist/skills/builtin/custom_skills.js.map +1 -0
  241. package/dist/skills/builtin/datasphere.d.ts +73 -0
  242. package/dist/skills/builtin/datasphere.js +350 -0
  243. package/dist/skills/builtin/datasphere.js.map +1 -0
  244. package/dist/skills/builtin/datasphere_serverless.d.ts +89 -0
  245. package/dist/skills/builtin/datasphere_serverless.js +291 -0
  246. package/dist/skills/builtin/datasphere_serverless.js.map +1 -0
  247. package/dist/skills/builtin/datetime.d.ts +40 -0
  248. package/dist/skills/builtin/datetime.js +118 -0
  249. package/dist/skills/builtin/datetime.js.map +1 -0
  250. package/dist/skills/builtin/google_maps.d.ts +48 -0
  251. package/dist/skills/builtin/google_maps.js +470 -0
  252. package/dist/skills/builtin/google_maps.js.map +1 -0
  253. package/dist/skills/builtin/index.d.ts +31 -0
  254. package/{src/skills/builtin/index.ts → dist/skills/builtin/index.js} +30 -36
  255. package/dist/skills/builtin/index.js.map +1 -0
  256. package/dist/skills/builtin/info_gatherer.d.ts +115 -0
  257. package/dist/skills/builtin/info_gatherer.js +328 -0
  258. package/dist/skills/builtin/info_gatherer.js.map +1 -0
  259. package/dist/skills/builtin/joke.d.ts +41 -0
  260. package/dist/skills/builtin/joke.js +156 -0
  261. package/dist/skills/builtin/joke.js.map +1 -0
  262. package/dist/skills/builtin/math.d.ts +39 -0
  263. package/dist/skills/builtin/math.js +119 -0
  264. package/dist/skills/builtin/math.js.map +1 -0
  265. package/dist/skills/builtin/mcp_gateway.d.ts +82 -0
  266. package/dist/skills/builtin/mcp_gateway.js +574 -0
  267. package/dist/skills/builtin/mcp_gateway.js.map +1 -0
  268. package/dist/skills/builtin/native_vector_search.d.ts +128 -0
  269. package/dist/skills/builtin/native_vector_search.js +752 -0
  270. package/dist/skills/builtin/native_vector_search.js.map +1 -0
  271. package/dist/skills/builtin/play_background_file.d.ts +59 -0
  272. package/dist/skills/builtin/play_background_file.js +274 -0
  273. package/dist/skills/builtin/play_background_file.js.map +1 -0
  274. package/dist/skills/builtin/spider.d.ts +91 -0
  275. package/dist/skills/builtin/spider.js +758 -0
  276. package/dist/skills/builtin/spider.js.map +1 -0
  277. package/dist/skills/builtin/swml_transfer.d.ts +66 -0
  278. package/dist/skills/builtin/swml_transfer.js +475 -0
  279. package/dist/skills/builtin/swml_transfer.js.map +1 -0
  280. package/dist/skills/builtin/weather_api.d.ts +59 -0
  281. package/dist/skills/builtin/weather_api.js +196 -0
  282. package/dist/skills/builtin/weather_api.js.map +1 -0
  283. package/dist/skills/builtin/web_search.d.ts +160 -0
  284. package/dist/skills/builtin/web_search.js +894 -0
  285. package/dist/skills/builtin/web_search.js.map +1 -0
  286. package/dist/skills/builtin/wikipedia_search.d.ts +77 -0
  287. package/dist/skills/builtin/wikipedia_search.js +241 -0
  288. package/dist/skills/builtin/wikipedia_search.js.map +1 -0
  289. package/{src/skills/index.ts → dist/skills/index.d.ts} +0 -1
  290. package/dist/skills/index.js +10 -0
  291. package/dist/skills/index.js.map +1 -0
  292. package/dist/types.d.ts +118 -0
  293. package/dist/types.js +5 -0
  294. package/dist/types.js.map +1 -0
  295. package/package.json +7 -1
  296. package/.github/workflows/publish.yml +0 -27
  297. package/.github/workflows/test.yml +0 -17
  298. package/CLAUDE.md +0 -112
  299. package/docs/MIGRATION-2.0.md +0 -81
  300. package/docs/agent-guide.md +0 -869
  301. package/docs/agent_guide.md +0 -1026
  302. package/docs/api-reference.md +0 -2420
  303. package/docs/api_reference.md +0 -1301
  304. package/docs/architecture.md +0 -843
  305. package/docs/cli-guide.md +0 -579
  306. package/docs/cli_guide.md +0 -448
  307. package/docs/cloud_functions_guide.md +0 -474
  308. package/docs/configuration.md +0 -422
  309. package/docs/contexts-guide.md +0 -787
  310. package/docs/contexts_guide.md +0 -511
  311. package/docs/datamap-guide.md +0 -1141
  312. package/docs/datamap_guide.md +0 -595
  313. package/docs/llm_parameters.md +0 -239
  314. package/docs/mcp_gateway_reference.md +0 -648
  315. package/docs/mcp_integration.md +0 -108
  316. package/docs/prefabs-guide.md +0 -800
  317. package/docs/sdk_features.md +0 -477
  318. package/docs/security.md +0 -436
  319. package/docs/serverless-guide.md +0 -513
  320. package/docs/skills-guide.md +0 -857
  321. package/docs/skills-system.md +0 -301
  322. package/docs/skills_parameter_schema.md +0 -392
  323. package/docs/skills_system.md +0 -467
  324. package/docs/swaig-reference.md +0 -1627
  325. package/docs/swaig_reference.md +0 -910
  326. package/docs/swml_service_guide.md +0 -600
  327. package/docs/third_party_skills.md +0 -533
  328. package/docs/web_service.md +0 -677
  329. package/examples/README.md +0 -131
  330. package/examples/advanced-datamap.ts +0 -100
  331. package/examples/advanced-dynamic-config.ts +0 -70
  332. package/examples/auto-vivified.ts +0 -94
  333. package/examples/call-flow.ts +0 -63
  334. package/examples/comprehensive-dynamic.ts +0 -125
  335. package/examples/contexts-steps.ts +0 -65
  336. package/examples/custom-path.ts +0 -45
  337. package/examples/datamap-tools.ts +0 -55
  338. package/examples/datasphere-multi-instance.ts +0 -63
  339. package/examples/datasphere-serverless-env.ts +0 -68
  340. package/examples/datasphere-webhook-env.ts +0 -66
  341. package/examples/datasphere.ts +0 -37
  342. package/examples/declarative.ts +0 -100
  343. package/examples/dynamic-config.ts +0 -54
  344. package/examples/dynamic-info-gatherer.ts +0 -69
  345. package/examples/dynamic-swml-service.ts +0 -67
  346. package/examples/gather-info.ts +0 -71
  347. package/examples/gather-per-question-functions-demo.ts +0 -140
  348. package/examples/joke-agent.ts +0 -34
  349. package/examples/kubernetes-agent.ts +0 -45
  350. package/examples/llm-params.ts +0 -69
  351. package/examples/mcp-agent.ts +0 -84
  352. package/examples/mcp-gateway.ts +0 -35
  353. package/examples/multi-agent.ts +0 -73
  354. package/examples/multi-endpoint.ts +0 -79
  355. package/examples/pom-prompt.ts +0 -71
  356. package/examples/prefab-concierge.ts +0 -47
  357. package/examples/prefab-faq.ts +0 -54
  358. package/examples/prefab-info-gatherer.ts +0 -33
  359. package/examples/prefab-receptionist.ts +0 -36
  360. package/examples/prefab-survey.ts +0 -68
  361. package/examples/record-call.ts +0 -67
  362. package/examples/relay-demo.ts +0 -33
  363. package/examples/room-and-sip.ts +0 -94
  364. package/examples/serverless-lambda.ts +0 -35
  365. package/examples/session-state.ts +0 -83
  366. package/examples/simple-agent.ts +0 -36
  367. package/examples/simple-static.ts +0 -29
  368. package/examples/skills-demo.ts +0 -38
  369. package/examples/step-function-inheritance-demo.ts +0 -124
  370. package/examples/swaig-features.ts +0 -187
  371. package/examples/swml-service-routing.ts +0 -66
  372. package/examples/swml-service.ts +0 -38
  373. package/examples/tap.ts +0 -68
  374. package/examples/verb-methods.ts +0 -45
  375. package/examples/web-search-multi-instance.ts +0 -72
  376. package/examples/web-search.ts +0 -38
  377. package/examples/wikipedia.ts +0 -36
  378. package/livewire/README.md +0 -140
  379. package/livewire/docs/migration-guide.md +0 -228
  380. package/livewire/examples/livewire-basic-agent.ts +0 -74
  381. package/livewire/examples/livewire-handoff.ts +0 -197
  382. package/livewire/examples/livewire-multi-tool.ts +0 -117
  383. package/relay/README.md +0 -70
  384. package/relay/RELAY_IMPLEMENTATION_GUIDE.md +0 -1257
  385. package/relay/docs/call-methods.md +0 -474
  386. package/relay/docs/client-reference.md +0 -142
  387. package/relay/docs/events.md +0 -134
  388. package/relay/docs/getting-started.md +0 -134
  389. package/relay/docs/guide.md +0 -306
  390. package/relay/docs/messaging.md +0 -182
  391. package/relay/examples/relay-inbound.ts +0 -66
  392. package/relay/examples/relay-messaging.ts +0 -71
  393. package/relay/examples/relay-outbound.ts +0 -76
  394. package/rest/README.md +0 -95
  395. package/rest/docs/calling.md +0 -273
  396. package/rest/docs/client-reference.md +0 -107
  397. package/rest/docs/compat.md +0 -204
  398. package/rest/docs/fabric.md +0 -183
  399. package/rest/docs/getting-started.md +0 -110
  400. package/rest/docs/guide.md +0 -351
  401. package/rest/docs/namespaces.md +0 -285
  402. package/rest/examples/rest-10dlc-registration.ts +0 -161
  403. package/rest/examples/rest-calling-ivr-and-ai.ts +0 -102
  404. package/rest/examples/rest-calling-play-and-record.ts +0 -91
  405. package/rest/examples/rest-client.ts +0 -65
  406. package/rest/examples/rest-compat-laml.ts +0 -210
  407. package/rest/examples/rest-datasphere-search.ts +0 -82
  408. package/rest/examples/rest-fabric-conferences-and-routing.ts +0 -144
  409. package/rest/examples/rest-fabric-subscribers-and-sip.ts +0 -108
  410. package/rest/examples/rest-fabric-swml-and-callflows.ts +0 -99
  411. package/rest/examples/rest-manage-resources.ts +0 -65
  412. package/rest/examples/rest-phone-number-management.ts +0 -197
  413. package/rest/examples/rest-queues-mfa-and-recordings.ts +0 -143
  414. package/rest/examples/rest-video-rooms.ts +0 -186
  415. package/src/AgentBase.ts +0 -2489
  416. package/src/AgentServer.ts +0 -415
  417. package/src/AuthHandler.ts +0 -256
  418. package/src/ConfigLoader.ts +0 -447
  419. package/src/ContextBuilder.ts +0 -1150
  420. package/src/DataMap.ts +0 -449
  421. package/src/FunctionResult.ts +0 -866
  422. package/src/Logger.ts +0 -337
  423. package/src/PomBuilder.ts +0 -439
  424. package/src/PromptManager.ts +0 -133
  425. package/src/SWMLHandler.ts +0 -298
  426. package/src/SWMLService.ts +0 -717
  427. package/src/SchemaUtils.ts +0 -361
  428. package/src/ServerlessAdapter.ts +0 -221
  429. package/src/SessionManager.ts +0 -311
  430. package/src/SslConfig.ts +0 -118
  431. package/src/SwaigFunction.ts +0 -276
  432. package/src/SwmlBuilder.ts +0 -258
  433. package/src/SwmlVerbMethods.generated.ts +0 -234
  434. package/src/TypeInference.ts +0 -181
  435. package/src/WebService.ts +0 -619
  436. package/src/cli/agent-loader.ts +0 -166
  437. package/src/cli/mock-data.ts +0 -111
  438. package/src/cli/swaig-test.ts +0 -452
  439. package/src/generateVerbTypes.ts +0 -322
  440. package/src/index.ts +0 -167
  441. package/src/livewire/index.ts +0 -950
  442. package/src/prefabs/ConciergeAgent.ts +0 -287
  443. package/src/prefabs/FAQBotAgent.ts +0 -384
  444. package/src/prefabs/InfoGathererAgent.ts +0 -339
  445. package/src/prefabs/ReceptionistAgent.ts +0 -366
  446. package/src/prefabs/SurveyAgent.ts +0 -646
  447. package/src/relay/Action.ts +0 -314
  448. package/src/relay/Call.ts +0 -854
  449. package/src/relay/Deferred.ts +0 -71
  450. package/src/relay/Message.ts +0 -148
  451. package/src/relay/RelayClient.ts +0 -1036
  452. package/src/relay/RelayError.ts +0 -14
  453. package/src/relay/RelayEvent.ts +0 -892
  454. package/src/relay/index.ts +0 -123
  455. package/src/relay/types.ts +0 -149
  456. package/src/rest/HttpClient.ts +0 -103
  457. package/src/rest/RestError.ts +0 -31
  458. package/src/rest/base/BaseResource.ts +0 -19
  459. package/src/rest/base/CrudResource.ts +0 -51
  460. package/src/rest/base/CrudWithAddresses.ts +0 -26
  461. package/src/rest/namespaces/addresses.ts +0 -32
  462. package/src/rest/namespaces/calling.ts +0 -187
  463. package/src/rest/namespaces/chat.ts +0 -20
  464. package/src/rest/namespaces/compat.ts +0 -352
  465. package/src/rest/namespaces/datasphere.ts +0 -45
  466. package/src/rest/namespaces/fabric.ts +0 -222
  467. package/src/rest/namespaces/imported-numbers.ts +0 -20
  468. package/src/rest/namespaces/logs.ts +0 -84
  469. package/src/rest/namespaces/lookup.ts +0 -21
  470. package/src/rest/namespaces/mfa.ts +0 -30
  471. package/src/rest/namespaces/number-groups.ts +0 -38
  472. package/src/rest/namespaces/phone-numbers.ts +0 -44
  473. package/src/rest/namespaces/project.ts +0 -36
  474. package/src/rest/namespaces/pubsub.ts +0 -20
  475. package/src/rest/namespaces/queues.ts +0 -33
  476. package/src/rest/namespaces/recordings.ts +0 -28
  477. package/src/rest/namespaces/registry.ts +0 -101
  478. package/src/rest/namespaces/short-codes.ts +0 -28
  479. package/src/rest/namespaces/sip-profile.ts +0 -25
  480. package/src/rest/namespaces/verified-callers.ts +0 -27
  481. package/src/rest/namespaces/video.ts +0 -165
  482. package/src/rest/pagination.ts +0 -84
  483. package/src/rest/types.ts +0 -61
  484. package/src/skills/SkillBase.ts +0 -547
  485. package/src/skills/SkillManager.ts +0 -415
  486. package/src/skills/SkillRegistry.ts +0 -367
  487. package/src/skills/builtin/api_ninjas_trivia.ts +0 -280
  488. package/src/skills/builtin/ask_claude.ts +0 -241
  489. package/src/skills/builtin/claude_skills.ts +0 -978
  490. package/src/skills/builtin/custom_skills.ts +0 -312
  491. package/src/skills/builtin/datasphere.ts +0 -438
  492. package/src/skills/builtin/datasphere_serverless.ts +0 -339
  493. package/src/skills/builtin/datetime.ts +0 -130
  494. package/src/skills/builtin/google_maps.ts +0 -651
  495. package/src/skills/builtin/info_gatherer.ts +0 -405
  496. package/src/skills/builtin/joke.ts +0 -191
  497. package/src/skills/builtin/math.ts +0 -142
  498. package/src/skills/builtin/mcp_gateway.ts +0 -677
  499. package/src/skills/builtin/native_vector_search.ts +0 -901
  500. package/src/skills/builtin/play_background_file.ts +0 -358
  501. package/src/skills/builtin/spider.ts +0 -869
  502. package/src/skills/builtin/swml_transfer.ts +0 -635
  503. package/src/skills/builtin/weather_api.ts +0 -248
  504. package/src/skills/builtin/web_search.ts +0 -1074
  505. package/src/skills/builtin/wikipedia_search.ts +0 -299
  506. package/src/types.ts +0 -132
  507. package/tests/AgentBase.test.ts +0 -1093
  508. package/tests/AgentServer.test.ts +0 -126
  509. package/tests/AuthHandler.test.ts +0 -133
  510. package/tests/ConfigLoader.test.ts +0 -151
  511. package/tests/ContextBuilder.test.ts +0 -108
  512. package/tests/DataMap.test.ts +0 -367
  513. package/tests/EphemeralSkillCopy.test.ts +0 -107
  514. package/tests/FunctionResult.test.ts +0 -298
  515. package/tests/GracefulShutdown.test.ts +0 -46
  516. package/tests/Logger.test.ts +0 -420
  517. package/tests/PomBuilder.test.ts +0 -228
  518. package/tests/ProxyDetection.test.ts +0 -228
  519. package/tests/SWMLService.test.ts +0 -320
  520. package/tests/SWMLVerbHandler.test.ts +0 -523
  521. package/tests/SchemaUtils.test.ts +0 -106
  522. package/tests/SchemaUtils.verb.test.ts +0 -206
  523. package/tests/SecurityUtils.test.ts +0 -192
  524. package/tests/ServerlessAdapter.test.ts +0 -222
  525. package/tests/SessionManager.test.ts +0 -257
  526. package/tests/SkillBaseFeatures.test.ts +0 -130
  527. package/tests/SkillMultiInstance.test.ts +0 -102
  528. package/tests/SkillParameterSchemas.test.ts +0 -134
  529. package/tests/SkillRegistrySchema.test.ts +0 -84
  530. package/tests/SslConfig.test.ts +0 -97
  531. package/tests/SwmlBuilder.test.ts +0 -400
  532. package/tests/TypeInference.test.ts +0 -165
  533. package/tests/VerbHandlerRegistry.test.ts +0 -128
  534. package/tests/cli/mock-data.test.ts +0 -113
  535. package/tests/cli/swaig-test.test.ts +0 -108
  536. package/tests/examples.test.ts +0 -194
  537. package/tests/fixtures/scrape-parity/README.md +0 -53
  538. package/tests/fixtures/scrape-parity/expected/01_simple_article.json +0 -5
  539. package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +0 -5
  540. package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +0 -5
  541. package/tests/fixtures/scrape-parity/expected/04_bare_body.json +0 -5
  542. package/tests/fixtures/scrape-parity/expected/05_malformed.json +0 -5
  543. package/tests/fixtures/scrape-parity/expected/06_multi_class.json +0 -5
  544. package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +0 -5
  545. package/tests/fixtures/scrape-parity/expected/08_inline_script.json +0 -5
  546. package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +0 -5
  547. package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +0 -5
  548. package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +0 -5
  549. package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +0 -5
  550. package/tests/fixtures/scrape-parity/html/01_simple_article.html +0 -18
  551. package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +0 -18
  552. package/tests/fixtures/scrape-parity/html/03_nested_containers.html +0 -13
  553. package/tests/fixtures/scrape-parity/html/04_bare_body.html +0 -9
  554. package/tests/fixtures/scrape-parity/html/05_malformed.html +0 -11
  555. package/tests/fixtures/scrape-parity/html/06_multi_class.html +0 -18
  556. package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +0 -12
  557. package/tests/fixtures/scrape-parity/html/08_inline_script.html +0 -17
  558. package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +0 -21
  559. package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +0 -10
  560. package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +0 -13
  561. package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +0 -24
  562. package/tests/fixtures/scrape-parity/python_extract.py +0 -109
  563. package/tests/livewire/livewire.test.ts +0 -780
  564. package/tests/mcp.test.ts +0 -221
  565. package/tests/prefabs/prefabs.test.ts +0 -1093
  566. package/tests/relay/Action.test.ts +0 -392
  567. package/tests/relay/Call.test.ts +0 -535
  568. package/tests/relay/Deferred.test.ts +0 -71
  569. package/tests/relay/Message.test.ts +0 -164
  570. package/tests/relay/RelayClient.test.ts +0 -779
  571. package/tests/relay/RelayEvent.test.ts +0 -463
  572. package/tests/relay/helpers.ts +0 -79
  573. package/tests/rest/HttpClient.test.ts +0 -274
  574. package/tests/rest/RestError.test.ts +0 -53
  575. package/tests/rest/calling.test.ts +0 -156
  576. package/tests/rest/client.test.ts +0 -197
  577. package/tests/rest/compat.test.ts +0 -335
  578. package/tests/rest/datasphere.test.ts +0 -71
  579. package/tests/rest/fabric.test.ts +0 -186
  580. package/tests/rest/helpers.ts +0 -95
  581. package/tests/rest/logs.test.ts +0 -68
  582. package/tests/rest/pagination.test.ts +0 -133
  583. package/tests/rest/registry.test.ts +0 -94
  584. package/tests/rest/relay-rest.test.ts +0 -290
  585. package/tests/rest/video.test.ts +0 -173
  586. package/tests/setup.ts +0 -6
  587. package/tests/skills/SkillBase.test.ts +0 -108
  588. package/tests/skills/SkillManager.test.ts +0 -268
  589. package/tests/skills/SkillRegistry.test.ts +0 -176
  590. package/tests/skills/builtin.test.ts +0 -1472
  591. package/tests/skills/claude-skills.test.ts +0 -54
  592. package/tests/skills/custom-skills.test.ts +0 -53
  593. package/tests/skills/datasphere-serverless.test.ts +0 -70
  594. package/tests/skills/datasphere.test.ts +0 -107
  595. package/tests/skills/datetime.test.ts +0 -101
  596. package/tests/skills/google-maps.test.ts +0 -78
  597. package/tests/skills/info-gatherer.test.ts +0 -411
  598. package/tests/skills/joke.test.ts +0 -81
  599. package/tests/skills/math.test.ts +0 -68
  600. package/tests/skills/mcp-gateway.test.ts +0 -101
  601. package/tests/skills/play-background.test.ts +0 -54
  602. package/tests/skills/spider.test.ts +0 -108
  603. package/tests/skills/swml-transfer.test.ts +0 -178
  604. package/tests/skills/trivia.test.ts +0 -54
  605. package/tests/skills/vector-search.test.ts +0 -135
  606. package/tests/skills/weather-api.test.ts +0 -77
  607. package/tests/skills/web-search-parity.test.ts +0 -59
  608. package/tests/skills/web-search.test.ts +0 -103
  609. package/tests/skills/wikipedia.test.ts +0 -63
  610. package/tsconfig.json +0 -18
  611. package/vitest.config.ts +0 -9
  612. /package/{src → dist}/schema.json +0 -0
@@ -1,1141 +0,0 @@
1
- # DataMap Guide
2
-
3
- Comprehensive guide to the `DataMap` class in the SignalWire AI Agents TypeScript SDK.
4
-
5
- ---
6
-
7
- ## Table of Contents
8
-
9
- - [Overview](#overview)
10
- - [Creating a DataMap](#creating-a-datamap)
11
- - [Configuration](#configuration)
12
- - [purpose / description](#purpose--description)
13
- - [parameter](#parameter)
14
- - [Webhooks](#webhooks)
15
- - [webhook](#webhook)
16
- - [body](#body)
17
- - [params](#params)
18
- - [Webhook Headers](#webhook-headers)
19
- - [Expressions](#expressions)
20
- - [expression](#expression)
21
- - [Response Processing](#response-processing)
22
- - [output](#output)
23
- - [webhookExpressions](#webhookexpressions)
24
- - [Error Handling](#error-handling)
25
- - [fallbackOutput](#fallbackoutput)
26
- - [errorKeys](#errorkeys)
27
- - [globalErrorKeys](#globalerrorkeys)
28
- - [Iteration](#iteration)
29
- - [foreach](#foreach)
30
- - [Environment Variables](#environment-variables)
31
- - [enableEnvExpansion](#enableenvexpansion)
32
- - [Registration](#registration)
33
- - [registerWithAgent](#registerwithagent)
34
- - [toSwaigFunction](#toswaigfunction)
35
- - [Helper Functions](#helper-functions)
36
- - [createSimpleApiTool](#createsimpleapitool)
37
- - [createExpressionTool](#createexpressiontool)
38
- - [Template Variables Reference](#template-variables-reference)
39
- - [Complete Examples](#complete-examples)
40
-
41
- ---
42
-
43
- ## Overview
44
-
45
- `DataMap` creates server-side tool definitions that execute entirely on the SignalWire platform without requiring your own webhook endpoints for the tool handler. Instead of writing a handler function that runs on your server, you describe what HTTP call to make (or what expression to evaluate), how to process the response, and what to return to the AI -- all as configuration.
46
-
47
- ### When to use DataMap vs. defineTool
48
-
49
- | Feature | `defineTool()` | `DataMap` |
50
- |--------------------|--------------------------------------------|-------------------------------------------------|
51
- | Execution location | Your server | SignalWire platform |
52
- | Custom logic | Full TypeScript/JavaScript | Template variables and pattern matching |
53
- | External API calls | You make them in your handler | SignalWire makes them for you |
54
- | Webhook required | Yes (your agent server must be reachable) | No (the data_map config is embedded in SWML) |
55
- | Best for | Complex logic, database access, auth flows | Simple API lookups, pattern matching, transforms |
56
-
57
- ### How it works
58
-
59
- 1. You define a `DataMap` with a name, parameters, and either webhooks or expressions.
60
- 2. You register it with an agent via `registerWithAgent()` or `toSwaigFunction()`.
61
- 3. When the AI decides to call this tool, SignalWire executes the data_map configuration directly:
62
- - For **webhooks**: SignalWire makes the HTTP request, processes the response through your output template, and returns the result to the AI.
63
- - For **expressions**: SignalWire evaluates the test value against the regex pattern and returns the matching output.
64
-
65
- ### Architecture
66
-
67
- ```
68
- Caller <-> SignalWire AI <-> DataMap (runs on SignalWire)
69
- |
70
- +--> External API (optional webhook call)
71
- ```
72
-
73
- No traffic flows to your server for DataMap tool invocations. Your server only serves the initial SWML document that contains the data_map configuration.
74
-
75
- ---
76
-
77
- ## Creating a DataMap
78
-
79
- The `DataMap` constructor takes a single argument: the function name.
80
-
81
- ```typescript
82
- import { DataMap, FunctionResult } from '@anthropic/@signalwire/sdk';
83
-
84
- const tool = new DataMap('get_weather');
85
- ```
86
-
87
- | Parameter | Type | Description |
88
- |----------------|----------|------------------------------------------|
89
- | `functionName` | `string` | Unique name for this data map tool. |
90
-
91
- All subsequent configuration is done via fluent method chaining:
92
-
93
- ```typescript
94
- const tool = new DataMap('get_weather')
95
- .purpose('Get current weather for a city')
96
- .parameter('city', 'string', 'The city name', { required: true })
97
- .webhook('GET', 'https://wttr.in/${lc:args.city}?format=j1')
98
- .output(new FunctionResult('Temperature: ${response.temp_F}F'))
99
- .fallbackOutput(new FunctionResult('Weather data unavailable.'));
100
- ```
101
-
102
- ---
103
-
104
- ## Configuration
105
-
106
- ### purpose / description
107
-
108
- Set the tool description that the AI sees. The AI uses this description to decide when to call the tool. `description()` is an alias for `purpose()`.
109
-
110
- ```typescript
111
- purpose(description: string): this
112
- description(description: string): this
113
- ```
114
-
115
- | Parameter | Type | Description |
116
- |---------------|----------|----------------------------------------------------|
117
- | `description` | `string` | Human-readable description of what the tool does. |
118
-
119
- If not set, the description defaults to `"Execute <functionName>"`.
120
-
121
- ```typescript
122
- const tool = new DataMap('lookup_order')
123
- .purpose('Look up an order by its ID and return the status');
124
-
125
- // Equivalent:
126
- const tool2 = new DataMap('lookup_order')
127
- .description('Look up an order by its ID and return the status');
128
- ```
129
-
130
- ---
131
-
132
- ### parameter
133
-
134
- Define a parameter that the AI should extract from the conversation and pass to this tool.
135
-
136
- ```typescript
137
- parameter(
138
- name: string,
139
- paramType: string,
140
- description: string,
141
- opts?: { required?: boolean; enum?: string[] }
142
- ): this
143
- ```
144
-
145
- | Parameter | Type | Description |
146
- |-------------------|------------|----------------------------------------------------------|
147
- | `name` | `string` | Parameter name (used in `${args.name}` templates). |
148
- | `paramType` | `string` | JSON Schema type: `"string"`, `"number"`, `"boolean"`, `"integer"`, `"array"`, `"object"`. |
149
- | `description` | `string` | Description shown to the AI to explain what this parameter is. |
150
- | `opts.required` | `boolean` | If `true`, the AI must provide this parameter. |
151
- | `opts.enum` | `string[]` | Restrict the parameter to a fixed set of allowed values. |
152
-
153
- Multiple calls to `parameter()` define multiple parameters. Required parameters are tracked internally via a `_required` array in the parameter schema.
154
-
155
- ```typescript
156
- const tool = new DataMap('search_products')
157
- .purpose('Search for products in the catalog')
158
- .parameter('query', 'string', 'Search query text', { required: true })
159
- .parameter('category', 'string', 'Product category filter', {
160
- enum: ['electronics', 'clothing', 'home', 'sports'],
161
- })
162
- .parameter('max_results', 'integer', 'Maximum number of results to return');
163
- ```
164
-
165
- The generated parameter schema:
166
-
167
- ```json
168
- {
169
- "type": "object",
170
- "properties": {
171
- "query": { "type": "string", "description": "Search query text" },
172
- "category": {
173
- "type": "string",
174
- "description": "Product category filter",
175
- "enum": ["electronics", "clothing", "home", "sports"]
176
- },
177
- "max_results": { "type": "integer", "description": "Maximum number of results to return" }
178
- },
179
- "required": ["query"]
180
- }
181
- ```
182
-
183
- ---
184
-
185
- ## Webhooks
186
-
187
- ### webhook
188
-
189
- Add a webhook that SignalWire calls when the tool is invoked. You can add multiple webhooks to a single DataMap.
190
-
191
- ```typescript
192
- webhook(
193
- method: string,
194
- url: string,
195
- opts?: {
196
- headers?: Record<string, string>;
197
- formParam?: string;
198
- inputArgsAsParams?: boolean;
199
- requireArgs?: string[];
200
- }
201
- ): this
202
- ```
203
-
204
- | Parameter | Type | Description |
205
- |------------------------|--------------------------|------------------------------------------------------------|
206
- | `method` | `string` | HTTP method (`"GET"`, `"POST"`, `"PUT"`, etc.). Automatically uppercased. |
207
- | `url` | `string` | The webhook URL. Supports template variables like `${args.city}`. |
208
- | `opts.headers` | `Record<string, string>` | Custom HTTP headers for the request. |
209
- | `opts.formParam` | `string` | Name of the form parameter to send the body as. |
210
- | `opts.inputArgsAsParams` | `boolean` | If `true`, pass all input arguments as query/form parameters. |
211
- | `opts.requireArgs` | `string[]` | Arguments that must be present for this webhook to fire. |
212
-
213
- **Returns:** `this` for chaining.
214
-
215
- ```typescript
216
- // Simple GET request with URL template
217
- const tool = new DataMap('get_stock_price')
218
- .purpose('Get the current stock price')
219
- .parameter('symbol', 'string', 'Stock ticker symbol', { required: true })
220
- .webhook('GET', 'https://api.stocks.example.com/v1/price/${uc:args.symbol}');
221
-
222
- // POST with authentication header
223
- const tool2 = new DataMap('create_ticket')
224
- .purpose('Create a support ticket')
225
- .parameter('subject', 'string', 'Ticket subject', { required: true })
226
- .parameter('description', 'string', 'Ticket description', { required: true })
227
- .webhook('POST', 'https://api.helpdesk.example.com/tickets', {
228
- headers: {
229
- 'Authorization': 'Bearer ${ENV.HELPDESK_API_KEY}',
230
- 'Content-Type': 'application/json',
231
- },
232
- });
233
- ```
234
-
235
- ---
236
-
237
- ### body
238
-
239
- Set the JSON body for the most recently added webhook. Must be called after `webhook()`.
240
-
241
- ```typescript
242
- body(data: Record<string, unknown>): this
243
- ```
244
-
245
- | Parameter | Type | Description |
246
- |-----------|----------------------------|----------------------------|
247
- | `data` | `Record<string, unknown>` | The request body object. |
248
-
249
- **Throws:** `Error` if no webhook has been added yet.
250
-
251
- **Returns:** `this` for chaining.
252
-
253
- ```typescript
254
- const tool = new DataMap('create_ticket')
255
- .purpose('Create a support ticket')
256
- .parameter('subject', 'string', 'Ticket subject', { required: true })
257
- .parameter('priority', 'string', 'Priority level', { enum: ['low', 'medium', 'high'] })
258
- .webhook('POST', 'https://api.helpdesk.example.com/tickets', {
259
- headers: { 'Authorization': 'Bearer my-api-key' },
260
- })
261
- .body({
262
- subject: '${args.subject}',
263
- priority: '${args.priority}',
264
- source: 'phone-call',
265
- });
266
- ```
267
-
268
- ---
269
-
270
- ### params
271
-
272
- Set query or form parameters for the most recently added webhook. Must be called after `webhook()`.
273
-
274
- ```typescript
275
- params(data: Record<string, unknown>): this
276
- ```
277
-
278
- | Parameter | Type | Description |
279
- |-----------|----------------------------|--------------------------|
280
- | `data` | `Record<string, unknown>` | The parameters object. |
281
-
282
- **Throws:** `Error` if no webhook has been added yet.
283
-
284
- **Returns:** `this` for chaining.
285
-
286
- ```typescript
287
- const tool = new DataMap('search_kb')
288
- .purpose('Search the knowledge base')
289
- .parameter('query', 'string', 'Search query', { required: true })
290
- .webhook('GET', 'https://api.kb.example.com/search')
291
- .params({
292
- q: '${args.query}',
293
- limit: 5,
294
- format: 'json',
295
- });
296
- ```
297
-
298
- ---
299
-
300
- ### Webhook Headers
301
-
302
- Headers are set via the `opts.headers` parameter of `webhook()`. Template variables are supported in header values.
303
-
304
- ```typescript
305
- const tool = new DataMap('authenticated_lookup')
306
- .purpose('Look up data from an authenticated API')
307
- .parameter('id', 'string', 'Record ID', { required: true })
308
- .enableEnvExpansion()
309
- .webhook('GET', 'https://api.example.com/records/${args.id}', {
310
- headers: {
311
- 'Authorization': 'Bearer ${ENV.API_TOKEN}',
312
- 'X-Request-Source': 'signalwire-agent',
313
- },
314
- });
315
- ```
316
-
317
- ---
318
-
319
- ## Expressions
320
-
321
- ### expression
322
-
323
- Add a pattern-matching expression that evaluates a test value against a regex pattern. Expressions work without making any HTTP calls -- they are evaluated entirely on the SignalWire platform.
324
-
325
- ```typescript
326
- expression(
327
- testValue: string,
328
- pattern: string | RegExp,
329
- output: FunctionResult,
330
- nomatchOutput?: FunctionResult
331
- ): this
332
- ```
333
-
334
- | Parameter | Type | Description |
335
- |-----------------|----------------------------|----------------------------------------------------------|
336
- | `testValue` | `string` | The string or template variable to test (e.g., `"${args.input}"`). |
337
- | `pattern` | `string \| RegExp` | Regex pattern to match against. If a `RegExp`, the `.source` is used. |
338
- | `output` | `FunctionResult` | Result returned when the pattern matches. |
339
- | `nomatchOutput` | `FunctionResult` | Optional result returned when the pattern does not match.|
340
-
341
- **Returns:** `this` for chaining.
342
-
343
- You can add multiple expressions. They are evaluated in order; the first match wins.
344
-
345
- ```typescript
346
- const tool = new DataMap('validate_email')
347
- .purpose('Validate an email address format')
348
- .parameter('email', 'string', 'The email address to validate', { required: true })
349
- .expression(
350
- '${args.email}',
351
- /^[^@]+@[^@]+\.[^@]+$/,
352
- new FunctionResult('The email address ${args.email} is valid.'),
353
- new FunctionResult('The email address ${args.email} is not valid. Please ask for a correct email.'),
354
- );
355
- ```
356
-
357
- Multiple expressions for different test values:
358
-
359
- ```typescript
360
- const tool = new DataMap('classify_input')
361
- .purpose('Classify user input as a question or command')
362
- .parameter('input', 'string', 'The user input to classify', { required: true })
363
- .expression(
364
- '${args.input}',
365
- '^(what|how|why|when|where|who|is|are|can|do|does)',
366
- new FunctionResult('The input is a question.'),
367
- )
368
- .expression(
369
- '${args.input}',
370
- '^(please|set|change|update|delete|create|send)',
371
- new FunctionResult('The input is a command.'),
372
- new FunctionResult('The input type could not be determined.'),
373
- );
374
- ```
375
-
376
- ---
377
-
378
- ## Response Processing
379
-
380
- ### output
381
-
382
- Set the output template for the most recently added webhook. The template uses `${response.*}` variables to reference fields in the webhook's JSON response and `${args.*}` to reference the tool's input arguments.
383
-
384
- ```typescript
385
- output(result: FunctionResult): this
386
- ```
387
-
388
- | Parameter | Type | Description |
389
- |-----------|-----------------------|------------------------------------------------------|
390
- | `result` | `FunctionResult` | The result template. Use template variables in the response text. |
391
-
392
- **Throws:** `Error` if no webhook has been added yet.
393
-
394
- **Returns:** `this` for chaining.
395
-
396
- ```typescript
397
- const tool = new DataMap('get_weather')
398
- .purpose('Get current weather')
399
- .parameter('city', 'string', 'City name', { required: true })
400
- .webhook('GET', 'https://wttr.in/${lc:args.city}?format=j1')
401
- .output(
402
- new FunctionResult(
403
- 'Weather in ${args.city}: ' +
404
- 'Temperature: ${response.current_condition[0].temp_F}F, ' +
405
- 'Conditions: ${response.current_condition[0].weatherDesc[0].value}, ' +
406
- 'Humidity: ${response.current_condition[0].humidity}%'
407
- ),
408
- );
409
- ```
410
-
411
- The `output()` method calls `toDict()` on the `FunctionResult`, so you can also include actions:
412
-
413
- ```typescript
414
- const tool = new DataMap('urgent_alert')
415
- .purpose('Send an urgent alert')
416
- .parameter('message', 'string', 'Alert message', { required: true })
417
- .webhook('POST', 'https://api.alerts.example.com/send')
418
- .body({ message: '${args.message}' })
419
- .output(
420
- new FunctionResult('Alert sent: ${response.alert_id}')
421
- .setMetadata({ alert_id: '${response.alert_id}' }),
422
- );
423
- ```
424
-
425
- ---
426
-
427
- ### webhookExpressions
428
-
429
- Set pattern-matching expressions on the most recently added webhook. These expressions are evaluated against the webhook's response, allowing conditional output based on the response content.
430
-
431
- ```typescript
432
- webhookExpressions(expressions: Record<string, unknown>[]): this
433
- ```
434
-
435
- | Parameter | Type | Description |
436
- |---------------|-----------------------------|----------------------------------------------------------------|
437
- | `expressions` | `Record<string, unknown>[]` | Array of expression objects with `string`, `pattern`, and `output` fields. |
438
-
439
- **Throws:** `Error` if no webhook has been added yet.
440
-
441
- **Returns:** `this` for chaining.
442
-
443
- ```typescript
444
- const tool = new DataMap('check_order_status')
445
- .purpose('Check the status of an order')
446
- .parameter('order_id', 'string', 'Order ID', { required: true })
447
- .webhook('GET', 'https://api.store.example.com/orders/${args.order_id}')
448
- .webhookExpressions([
449
- {
450
- string: '${response.status}',
451
- pattern: 'shipped',
452
- output: new FunctionResult(
453
- 'Order ${args.order_id} has shipped! Tracking: ${response.tracking_number}'
454
- ).toDict(),
455
- },
456
- {
457
- string: '${response.status}',
458
- pattern: 'processing',
459
- output: new FunctionResult(
460
- 'Order ${args.order_id} is being processed. Estimated ship date: ${response.est_ship_date}'
461
- ).toDict(),
462
- },
463
- {
464
- string: '${response.status}',
465
- pattern: 'delivered',
466
- output: new FunctionResult(
467
- 'Order ${args.order_id} was delivered on ${response.delivery_date}.'
468
- ).toDict(),
469
- },
470
- ])
471
- .output(
472
- new FunctionResult('Order ${args.order_id} status: ${response.status}'),
473
- );
474
- ```
475
-
476
- ---
477
-
478
- ## Error Handling
479
-
480
- ### fallbackOutput
481
-
482
- Set a fallback output used when no webhook succeeds or no expression matches. This ensures the AI always gets a response even when the tool encounters an error.
483
-
484
- ```typescript
485
- fallbackOutput(result: FunctionResult): this
486
- ```
487
-
488
- | Parameter | Type | Description |
489
- |-----------|-----------------------|-----------------------------------------------|
490
- | `result` | `FunctionResult` | The fallback result. |
491
-
492
- **Returns:** `this` for chaining.
493
-
494
- ```typescript
495
- const tool = new DataMap('get_price')
496
- .purpose('Get the price of a product')
497
- .parameter('product', 'string', 'Product name', { required: true })
498
- .webhook('GET', 'https://api.store.example.com/price/${args.product}')
499
- .output(new FunctionResult('${args.product} costs $${response.price}'))
500
- .fallbackOutput(
501
- new FunctionResult('Sorry, I could not look up the price for ${args.product}. Please try again later.'),
502
- );
503
- ```
504
-
505
- ---
506
-
507
- ### errorKeys
508
-
509
- Set error keys on the most recently added webhook. If the webhook response contains any of these keys, the response is treated as an error and the fallback output is used instead.
510
-
511
- If no webhook has been added, the error keys are set globally (same as `globalErrorKeys`).
512
-
513
- ```typescript
514
- errorKeys(keys: string[]): this
515
- ```
516
-
517
- | Parameter | Type | Description |
518
- |-----------|------------|----------------------------------------------------|
519
- | `keys` | `string[]` | Response keys that indicate an error occurred. |
520
-
521
- **Returns:** `this` for chaining.
522
-
523
- ```typescript
524
- const tool = new DataMap('api_lookup')
525
- .purpose('Look up data from an API')
526
- .parameter('id', 'string', 'Record ID', { required: true })
527
- .webhook('GET', 'https://api.example.com/data/${args.id}')
528
- .errorKeys(['error', 'error_message', 'fault'])
529
- .output(new FunctionResult('Found: ${response.name}'))
530
- .fallbackOutput(new FunctionResult('Lookup failed. Please try again.'));
531
- ```
532
-
533
- ---
534
-
535
- ### globalErrorKeys
536
-
537
- Set error keys at the top-level data map scope, regardless of webhook context. These apply to all webhooks in the DataMap.
538
-
539
- ```typescript
540
- globalErrorKeys(keys: string[]): this
541
- ```
542
-
543
- | Parameter | Type | Description |
544
- |-----------|------------|----------------------------------------------------|
545
- | `keys` | `string[]` | Response keys that indicate an error occurred. |
546
-
547
- **Returns:** `this` for chaining.
548
-
549
- ```typescript
550
- const tool = new DataMap('multi_api')
551
- .purpose('Call multiple APIs')
552
- .globalErrorKeys(['error', 'err'])
553
- .webhook('GET', 'https://api1.example.com/data')
554
- .output(new FunctionResult('API 1: ${response.value}'))
555
- .webhook('GET', 'https://api2.example.com/data')
556
- .output(new FunctionResult('API 2: ${response.value}'))
557
- .fallbackOutput(new FunctionResult('Both APIs failed.'));
558
- ```
559
-
560
- ---
561
-
562
- ## Iteration
563
-
564
- ### foreach
565
-
566
- Configure iteration over an array in the webhook response. This allows you to loop over a list of items and build a composite response string.
567
-
568
- ```typescript
569
- foreach(config: {
570
- input_key: string;
571
- output_key: string;
572
- append: string;
573
- max?: number;
574
- }): this
575
- ```
576
-
577
- | Parameter | Type | Description |
578
- |--------------------|----------|--------------------------------------------------------------|
579
- | `config.input_key` | `string` | Dot-path to the array in the response (e.g., `"results"`). |
580
- | `config.output_key`| `string` | Variable name that holds the concatenated output. |
581
- | `config.append` | `string` | Template string appended for each item in the array. |
582
- | `config.max` | `number` | Optional maximum number of items to iterate over. |
583
-
584
- **Throws:** `Error` if no webhook has been added yet.
585
-
586
- **Returns:** `this` for chaining.
587
-
588
- The `append` template has access to the current item's fields. After iteration, the concatenated result is available via `${output_key}` in the output template.
589
-
590
- ```typescript
591
- const tool = new DataMap('list_orders')
592
- .purpose('List recent orders for a customer')
593
- .parameter('customer_id', 'string', 'Customer ID', { required: true })
594
- .webhook('GET', 'https://api.store.example.com/customers/${args.customer_id}/orders')
595
- .foreach({
596
- input_key: 'orders',
597
- output_key: 'order_list',
598
- append: 'Order #${id}: ${status} - $${total}\n',
599
- max: 5,
600
- })
601
- .output(
602
- new FunctionResult('Recent orders for customer ${args.customer_id}:\n${order_list}'),
603
- )
604
- .fallbackOutput(
605
- new FunctionResult('Could not retrieve orders for customer ${args.customer_id}.'),
606
- );
607
- ```
608
-
609
- In this example, if the API returns:
610
-
611
- ```json
612
- {
613
- "orders": [
614
- { "id": "1001", "status": "shipped", "total": "29.99" },
615
- { "id": "1002", "status": "processing", "total": "49.50" },
616
- { "id": "1003", "status": "delivered", "total": "15.00" }
617
- ]
618
- }
619
- ```
620
-
621
- The `${order_list}` variable becomes:
622
-
623
- ```
624
- Order #1001: shipped - $29.99
625
- Order #1002: processing - $49.50
626
- Order #1003: delivered - $15.00
627
- ```
628
-
629
- ---
630
-
631
- ## Environment Variables
632
-
633
- ### enableEnvExpansion
634
-
635
- Enable `${ENV.*}` variable expansion in URLs, bodies, headers, and outputs. When enabled, all `${ENV.VARIABLE_NAME}` references are replaced with the corresponding `process.env` values at the time `toSwaigFunction()` is called.
636
-
637
- ```typescript
638
- enableEnvExpansion(enabled?: boolean): this
639
- ```
640
-
641
- | Parameter | Type | Default | Description |
642
- |-----------|-----------|---------|-----------------------------------------|
643
- | `enabled` | `boolean` | `true` | Whether to enable environment expansion.|
644
-
645
- **Returns:** `this` for chaining.
646
-
647
- This is useful for embedding API keys or configuration values without hardcoding them:
648
-
649
- ```typescript
650
- // Set environment variables (typically via .env file or deployment config)
651
- // API_KEY=sk-abc123
652
- // API_BASE_URL=https://api.example.com
653
-
654
- const tool = new DataMap('secure_lookup')
655
- .purpose('Look up data from a secure API')
656
- .parameter('query', 'string', 'Search query', { required: true })
657
- .enableEnvExpansion()
658
- .webhook('GET', '${ENV.API_BASE_URL}/search?q=${args.query}', {
659
- headers: {
660
- 'Authorization': 'Bearer ${ENV.API_KEY}',
661
- },
662
- })
663
- .output(new FunctionResult('Result: ${response.data}'));
664
- ```
665
-
666
- When `toSwaigFunction()` is called, `${ENV.API_KEY}` is replaced with the value of `process.env.API_KEY`. If the environment variable is not set, it is replaced with an empty string.
667
-
668
- **Important:** The expansion happens at serialization time (when `toSwaigFunction()` is called), not at runtime. The resolved values are baked into the SWML document.
669
-
670
- ---
671
-
672
- ## Registration
673
-
674
- ### registerWithAgent
675
-
676
- Register this DataMap tool with an `AgentBase` instance. This is a convenience method that calls `toSwaigFunction()` internally and passes the result to the agent's `registerSwaigFunction()` method.
677
-
678
- ```typescript
679
- registerWithAgent(agent: {
680
- registerSwaigFunction(fn: Record<string, unknown>): unknown
681
- }): this
682
- ```
683
-
684
- | Parameter | Type | Description |
685
- |-----------|----------|----------------------------------------------------|
686
- | `agent` | `object` | An object with a `registerSwaigFunction` method. |
687
-
688
- **Returns:** `this` for chaining.
689
-
690
- ```typescript
691
- import { AgentBase, DataMap, FunctionResult } from '@anthropic/@signalwire/sdk';
692
-
693
- const agent = new AgentBase({ name: 'my-agent', basicAuth: ['user', 'pass'] });
694
-
695
- new DataMap('get_time')
696
- .purpose('Get the current time in a timezone')
697
- .parameter('timezone', 'string', 'IANA timezone', { required: true })
698
- .webhook('GET', 'https://worldtimeapi.org/api/timezone/${args.timezone}')
699
- .output(new FunctionResult('Current time: ${response.datetime}'))
700
- .fallbackOutput(new FunctionResult('Could not get time for that timezone.'))
701
- .registerWithAgent(agent);
702
-
703
- agent.run();
704
- ```
705
-
706
- ---
707
-
708
- ### toSwaigFunction
709
-
710
- Serialize the DataMap to a SWAIG function definition object suitable for inclusion in a SWML document. This is the terminal method that produces the wire format.
711
-
712
- ```typescript
713
- toSwaigFunction(): Record<string, unknown>
714
- ```
715
-
716
- **Returns:** A plain object with `function`, `description`, `parameters`, and `data_map` fields.
717
-
718
- ```typescript
719
- const tool = new DataMap('echo')
720
- .purpose('Echo back the input')
721
- .parameter('text', 'string', 'Text to echo', { required: true })
722
- .expression(
723
- '${args.text}',
724
- '.*',
725
- new FunctionResult('You said: ${args.text}'),
726
- );
727
-
728
- const swaigDef = tool.toSwaigFunction();
729
- console.log(JSON.stringify(swaigDef, null, 2));
730
- ```
731
-
732
- Output:
733
-
734
- ```json
735
- {
736
- "function": "echo",
737
- "description": "Echo back the input",
738
- "parameters": {
739
- "type": "object",
740
- "properties": {
741
- "text": { "type": "string", "description": "Text to echo" }
742
- },
743
- "required": ["text"]
744
- },
745
- "data_map": {
746
- "expressions": [
747
- {
748
- "string": "${args.text}",
749
- "pattern": ".*",
750
- "output": { "response": "You said: ${args.text}" }
751
- }
752
- ]
753
- }
754
- }
755
- ```
756
-
757
- You can then register this definition manually:
758
-
759
- ```typescript
760
- agent.registerSwaigFunction(tool.toSwaigFunction());
761
- ```
762
-
763
- ---
764
-
765
- ## Helper Functions
766
-
767
- ### createSimpleApiTool
768
-
769
- Create a DataMap tool that calls a single API endpoint and formats the response. This is a convenience function for the most common DataMap pattern: one GET/POST request with a response template.
770
-
771
- ```typescript
772
- import { createSimpleApiTool } from '@anthropic/@signalwire/sdk';
773
-
774
- createSimpleApiTool(opts: {
775
- name: string;
776
- url: string;
777
- responseTemplate: string;
778
- parameters?: Record<string, {
779
- type?: string;
780
- description?: string;
781
- required?: boolean;
782
- }>;
783
- method?: string;
784
- headers?: Record<string, string>;
785
- body?: Record<string, unknown>;
786
- errorKeys?: string[];
787
- }): DataMap
788
- ```
789
-
790
- | Parameter | Type | Default | Description |
791
- |-------------------------|----------------------------|-----------|---------------------------------------------------|
792
- | `opts.name` | `string` | -- | Tool name. |
793
- | `opts.url` | `string` | -- | Webhook URL (supports template variables). |
794
- | `opts.responseTemplate` | `string` | -- | Response template with `${response.*}` variables. |
795
- | `opts.parameters` | `Record<string, {...}>` | -- | Parameter definitions. |
796
- | `opts.method` | `string` | `'GET'` | HTTP method. |
797
- | `opts.headers` | `Record<string, string>` | -- | Request headers. |
798
- | `opts.body` | `Record<string, unknown>` | -- | Request body (for POST/PUT). |
799
- | `opts.errorKeys` | `string[]` | -- | Response keys indicating errors. |
800
-
801
- **Returns:** A configured `DataMap` instance ready for registration.
802
-
803
- ```typescript
804
- import { createSimpleApiTool } from '@anthropic/@signalwire/sdk';
805
-
806
- // Minimal: a single GET endpoint
807
- const jokeTool = createSimpleApiTool({
808
- name: 'get_joke',
809
- url: 'https://official-joke-api.appspot.com/random_joke',
810
- responseTemplate: 'Here is a joke: ${response.setup} ... ${response.punchline}',
811
- });
812
-
813
- agent.registerSwaigFunction(jokeTool.toSwaigFunction());
814
-
815
- // With parameters and POST
816
- const searchTool = createSimpleApiTool({
817
- name: 'search_docs',
818
- url: 'https://api.docs.example.com/search',
819
- method: 'POST',
820
- responseTemplate: 'Found ${response.total} results. Top result: ${response.results[0].title}',
821
- parameters: {
822
- query: { type: 'string', description: 'Search query', required: true },
823
- limit: { type: 'integer', description: 'Max results' },
824
- },
825
- headers: {
826
- 'Authorization': 'Bearer my-token',
827
- },
828
- body: {
829
- q: '${args.query}',
830
- max: '${args.limit}',
831
- },
832
- errorKeys: ['error'],
833
- });
834
-
835
- agent.registerSwaigFunction(searchTool.toSwaigFunction());
836
- ```
837
-
838
- ---
839
-
840
- ### createExpressionTool
841
-
842
- Create a DataMap tool that evaluates expressions against patterns without making any HTTP calls. Useful for validation, classification, and simple lookups.
843
-
844
- ```typescript
845
- import { createExpressionTool } from '@anthropic/@signalwire/sdk';
846
-
847
- createExpressionTool(opts: {
848
- name: string;
849
- patterns: Record<string, [string, FunctionResult]>;
850
- parameters?: Record<string, {
851
- type?: string;
852
- description?: string;
853
- required?: boolean;
854
- }>;
855
- }): DataMap
856
- ```
857
-
858
- | Parameter | Type | Description |
859
- |------------------|-------------------------------------------------------|--------------------------------------------------------|
860
- | `opts.name` | `string` | Tool name. |
861
- | `opts.patterns` | `Record<string, [string, FunctionResult]>` | Map of test values to `[pattern, output]` tuples. |
862
- | `opts.parameters`| `Record<string, {...}>` | Parameter definitions. |
863
-
864
- The `patterns` object maps test values (template strings) to tuples of `[regexPattern, result]`:
865
-
866
- ```typescript
867
- import { createExpressionTool, FunctionResult } from '@anthropic/@signalwire/sdk';
868
-
869
- const validator = createExpressionTool({
870
- name: 'validate_phone',
871
- patterns: {
872
- '${args.phone}': [
873
- '^\\+?1?\\d{10,15}$',
874
- new FunctionResult('The phone number ${args.phone} is valid.'),
875
- ],
876
- },
877
- parameters: {
878
- phone: { type: 'string', description: 'Phone number to validate', required: true },
879
- },
880
- });
881
-
882
- agent.registerSwaigFunction(validator.toSwaigFunction());
883
- ```
884
-
885
- ---
886
-
887
- ## Template Variables Reference
888
-
889
- Template variables are strings enclosed in `${}` that are evaluated by the SignalWire platform at runtime.
890
-
891
- ### Argument Variables
892
-
893
- | Variable | Description | Example |
894
- |-------------------|----------------------------------------------------------|------------------------|
895
- | `${args.<name>}` | Value of an input argument passed by the AI. | `${args.city}` |
896
- | `${lc:args.<name>}` | Argument value converted to lowercase. | `${lc:args.city}` |
897
- | `${uc:args.<name>}` | Argument value converted to uppercase. | `${uc:args.symbol}` |
898
-
899
- ### Response Variables
900
-
901
- | Variable | Description | Example |
902
- |-----------------------------|-------------------------------------------------------|---------------------------------------------|
903
- | `${response.<key>}` | Top-level field from the webhook JSON response. | `${response.name}` |
904
- | `${response.<key>.<subkey>}` | Nested field from the response. | `${response.address.city}` |
905
- | `${response.<key>[N]}` | Array element by index. | `${response.results[0].title}` |
906
- | `${response.<key>[N].<sub>}` | Field within an array element. | `${response.current_condition[0].temp_F}` |
907
-
908
- ### Environment Variables
909
-
910
- | Variable | Description | Example |
911
- |-------------------|--------------------------------------------------------------------|------------------------|
912
- | `${ENV.<name>}` | Value of `process.env.<name>`. Requires `enableEnvExpansion()`. | `${ENV.API_KEY}` |
913
-
914
- ### Foreach Variables
915
-
916
- Inside a `foreach` `append` template, you can reference fields of the current item directly:
917
-
918
- | Variable | Description | Example |
919
- |------------|--------------------------------------------|----------------|
920
- | `${<field>}` | Field of the current item in the array. | `${id}`, `${name}` |
921
-
922
- ### Case Transformation
923
-
924
- The `${lc:...}` and `${uc:...}` prefixes can be applied to argument variables to transform them to lowercase or uppercase respectively. This is particularly useful in URL templates:
925
-
926
- ```typescript
927
- // Lowercase city name for URL-friendly paths
928
- .webhook('GET', 'https://api.example.com/cities/${lc:args.city_name}')
929
-
930
- // Uppercase stock ticker symbol
931
- .webhook('GET', 'https://api.example.com/stocks/${uc:args.symbol}')
932
- ```
933
-
934
- ---
935
-
936
- ## Complete Examples
937
-
938
- ### Example 1: Weather lookup with DataMap builder
939
-
940
- ```typescript
941
- import { AgentBase, DataMap, FunctionResult } from '@anthropic/@signalwire/sdk';
942
-
943
- const agent = new AgentBase({
944
- name: 'weather-agent',
945
- route: '/',
946
- basicAuth: ['user', 'pass'],
947
- });
948
-
949
- agent.setPromptText('You are a weather assistant. Help users check the weather.');
950
-
951
- const weatherTool = new DataMap('get_weather')
952
- .purpose('Get current weather for a city')
953
- .parameter('city', 'string', 'The city name', { required: true })
954
- .webhook('GET', 'https://wttr.in/${lc:args.city}?format=j1')
955
- .output(
956
- new FunctionResult(
957
- 'Weather in ${args.city}: ${response.current_condition[0].temp_F}F, ' +
958
- '${response.current_condition[0].weatherDesc[0].value}'
959
- ),
960
- )
961
- .fallbackOutput(
962
- new FunctionResult('Sorry, could not fetch weather for that city.'),
963
- );
964
-
965
- agent.registerSwaigFunction(weatherTool.toSwaigFunction());
966
- agent.run();
967
- ```
968
-
969
- ### Example 2: Expression-only tool (no HTTP)
970
-
971
- ```typescript
972
- import { AgentBase, DataMap, FunctionResult } from '@anthropic/@signalwire/sdk';
973
-
974
- const agent = new AgentBase({
975
- name: 'validator-agent',
976
- route: '/',
977
- basicAuth: ['user', 'pass'],
978
- });
979
-
980
- agent.setPromptText('You help validate user data like emails and phone numbers.');
981
-
982
- const emailValidator = new DataMap('validate_email')
983
- .purpose('Check if an email address is valid')
984
- .parameter('email', 'string', 'Email address to validate', { required: true })
985
- .expression(
986
- '${args.email}',
987
- /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/,
988
- new FunctionResult('The email ${args.email} is valid.'),
989
- new FunctionResult('The email ${args.email} is invalid. Please provide a correct email address.'),
990
- );
991
-
992
- emailValidator.registerWithAgent(agent);
993
- agent.run();
994
- ```
995
-
996
- ### Example 3: API tool with POST body and error handling
997
-
998
- ```typescript
999
- import { AgentBase, DataMap, FunctionResult } from '@anthropic/@signalwire/sdk';
1000
-
1001
- const agent = new AgentBase({
1002
- name: 'ticket-agent',
1003
- route: '/',
1004
- basicAuth: ['user', 'pass'],
1005
- });
1006
-
1007
- agent.setPromptText('You are a support agent. Create tickets for customer issues.');
1008
-
1009
- const ticketTool = new DataMap('create_ticket')
1010
- .purpose('Create a support ticket for the customer')
1011
- .parameter('subject', 'string', 'Brief description of the issue', { required: true })
1012
- .parameter('priority', 'string', 'Urgency level', {
1013
- required: true,
1014
- enum: ['low', 'medium', 'high', 'critical'],
1015
- })
1016
- .parameter('description', 'string', 'Detailed description of the issue')
1017
- .enableEnvExpansion()
1018
- .webhook('POST', '${ENV.HELPDESK_URL}/api/tickets', {
1019
- headers: {
1020
- 'Authorization': 'Bearer ${ENV.HELPDESK_TOKEN}',
1021
- 'Content-Type': 'application/json',
1022
- },
1023
- })
1024
- .body({
1025
- subject: '${args.subject}',
1026
- priority: '${args.priority}',
1027
- description: '${args.description}',
1028
- source: 'phone',
1029
- })
1030
- .errorKeys(['error', 'message'])
1031
- .output(
1032
- new FunctionResult(
1033
- 'Ticket #${response.ticket_id} created successfully with ${args.priority} priority.'
1034
- ),
1035
- )
1036
- .fallbackOutput(
1037
- new FunctionResult('Failed to create the ticket. Please try again or contact support via email.'),
1038
- );
1039
-
1040
- ticketTool.registerWithAgent(agent);
1041
- agent.run();
1042
- ```
1043
-
1044
- ### Example 4: Iteration over array responses
1045
-
1046
- ```typescript
1047
- import { AgentBase, DataMap, FunctionResult } from '@anthropic/@signalwire/sdk';
1048
-
1049
- const agent = new AgentBase({
1050
- name: 'store-agent',
1051
- route: '/',
1052
- basicAuth: ['user', 'pass'],
1053
- });
1054
-
1055
- agent.setPromptText('You help customers find products and check orders.');
1056
-
1057
- const ordersTool = new DataMap('list_orders')
1058
- .purpose('List recent orders for the caller')
1059
- .parameter('email', 'string', 'Customer email address', { required: true })
1060
- .webhook('GET', 'https://api.store.example.com/orders?email=${args.email}')
1061
- .foreach({
1062
- input_key: 'orders',
1063
- output_key: 'order_summary',
1064
- append: '- Order #${id}: ${status}, Total: $${total}\n',
1065
- max: 10,
1066
- })
1067
- .output(
1068
- new FunctionResult('Here are your recent orders:\n${order_summary}'),
1069
- )
1070
- .fallbackOutput(
1071
- new FunctionResult('No orders found for ${args.email}.'),
1072
- );
1073
-
1074
- ordersTool.registerWithAgent(agent);
1075
- agent.run();
1076
- ```
1077
-
1078
- ### Example 5: Quick setup with createSimpleApiTool
1079
-
1080
- ```typescript
1081
- import { AgentBase, createSimpleApiTool } from '@anthropic/@signalwire/sdk';
1082
-
1083
- const agent = new AgentBase({
1084
- name: 'fun-agent',
1085
- route: '/',
1086
- basicAuth: ['user', 'pass'],
1087
- });
1088
-
1089
- agent.setPromptText('You tell jokes and fun facts.');
1090
-
1091
- // One-liner API integration
1092
- const jokeTool = createSimpleApiTool({
1093
- name: 'get_joke',
1094
- url: 'https://official-joke-api.appspot.com/random_joke',
1095
- responseTemplate: '${response.setup} ... ${response.punchline}',
1096
- });
1097
-
1098
- const factTool = createSimpleApiTool({
1099
- name: 'get_fact',
1100
- url: 'https://uselessfacts.jsph.pl/random.json?language=en',
1101
- responseTemplate: 'Fun fact: ${response.text}',
1102
- });
1103
-
1104
- agent.registerSwaigFunction(jokeTool.toSwaigFunction());
1105
- agent.registerSwaigFunction(factTool.toSwaigFunction());
1106
- agent.run();
1107
- ```
1108
-
1109
- ### Example 6: Expression tool with createExpressionTool
1110
-
1111
- ```typescript
1112
- import {
1113
- AgentBase,
1114
- createExpressionTool,
1115
- FunctionResult,
1116
- } from '@anthropic/@signalwire/sdk';
1117
-
1118
- const agent = new AgentBase({
1119
- name: 'validator-agent',
1120
- route: '/',
1121
- basicAuth: ['user', 'pass'],
1122
- });
1123
-
1124
- agent.setPromptText('You validate user inputs like zip codes and phone numbers.');
1125
-
1126
- const zipValidator = createExpressionTool({
1127
- name: 'validate_zip',
1128
- patterns: {
1129
- '${args.zip}': [
1130
- '^\\d{5}(-\\d{4})?$',
1131
- new FunctionResult('${args.zip} is a valid US zip code.'),
1132
- ],
1133
- },
1134
- parameters: {
1135
- zip: { type: 'string', description: 'Zip code to validate', required: true },
1136
- },
1137
- });
1138
-
1139
- agent.registerSwaigFunction(zipValidator.toSwaigFunction());
1140
- agent.run();
1141
- ```