@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
@@ -0,0 +1,642 @@
1
+ # Lesson 6: Running and Testing Fred
2
+
3
+ Fred is complete. This lesson runs it, tests its functions with `swaig-test` and `curl`, adds a script to manage it, and covers the problems you're most likely to hit.
4
+
5
+ ## Table of Contents
6
+
7
+ 1. [Running Fred](#running-fred)
8
+ 2. [Understanding the Endpoints](#understanding-the-endpoints)
9
+ 3. [Testing with swaig-test](#testing-with-swaig-test)
10
+ 4. [Testing with curl](#testing-with-curl)
11
+ 5. [Managing Fred with Scripts](#managing-fred-with-scripts)
12
+ 6. [Troubleshooting](#troubleshooting)
13
+ 7. [Production Considerations](#production-considerations)
14
+
15
+ ---
16
+
17
+ ## Running Fred
18
+
19
+ Running `fred.ts` starts a web server that SignalWire can call.
20
+
21
+ ### Step 1: Run Fred Directly
22
+
23
+ Start Fred from the project directory:
24
+
25
+ ```bash
26
+ npx tsx fred.ts
27
+ ```
28
+
29
+ The output looks like this, with the second warning shortened. Your password will differ:
30
+
31
+ ```text
32
+ 2026-09-29T17:41:55.751Z [WARN] [AgentBase] [signalwire] webhook signature validation is disabled — set signingKey or SIGNALWIRE_SIGNING_KEY to enable
33
+ 2026-09-29T17:41:55.752Z [WARN] [AgentBase] basic_auth_password_autogenerated: username="Fred". No SWML_BASIC_AUTH_PASSWORD found in environment ...
34
+ ============================================================
35
+ Fred: a Wikipedia knowledge bot
36
+ ============================================================
37
+
38
+ Fred searches Wikipedia and shares facts about Wikipedia itself.
39
+
40
+ Questions to try:
41
+ - Tell me about Albert Einstein
42
+ - What is quantum physics?
43
+ - Who was Marie Curie?
44
+ - Search for information about the solar system
45
+ - Can you share a fun fact?
46
+
47
+ Fred is available at: http://localhost:3000/fred
48
+ Basic Auth: Fred:5a37e6447524c6858a2395d234c2e910
49
+
50
+ Starting Fred. Press Ctrl+C to stop.
51
+ ============================================================
52
+ 2026-09-29T17:41:55.758Z [INFO] [AgentBase] Agent 'Fred' running at http://0.0.0.0:3000/fred
53
+ 2026-09-29T17:41:55.758Z [INFO] [AgentBase] Auth: Fred:**** (source: generated)
54
+ ```
55
+
56
+ ### Important Information
57
+
58
+ Note three details from the output:
59
+
60
+ - **URL**: `http://localhost:3000/fred`. The server listens on every network interface, `0.0.0.0`.
61
+ - **Credentials**: the username and password for basic authentication. Without `SWML_BASIC_AUTH_USER` and `SWML_BASIC_AUTH_PASSWORD` set, the SDK generates a new password each time Fred starts, and warns that it did. The SDK's own log line masks the password, so the banner is where you read it.
62
+ - **The signature warning**: webhook signature validation is off until you set `SIGNALWIRE_SIGNING_KEY`. That's fine on your own machine. [Production Considerations](#production-considerations) covers when to set it.
63
+
64
+ Press Ctrl+C to stop Fred.
65
+
66
+ ## Understanding the Endpoints
67
+
68
+ Fred answers on three HTTP endpoints, all under its route.
69
+
70
+ ### 1. SWML Endpoint (/fred)
71
+
72
+ Returns Fred's configuration as a SWML document:
73
+
74
+ - **Purpose**: tells SignalWire how Fred behaves
75
+ - **Method**: SignalWire requests it with a `POST`. You can fetch it with `GET` to inspect it.
76
+ - **Auth**: required
77
+
78
+ ### 2. SWAIG Endpoint (POST /fred/swaig)
79
+
80
+ Runs Fred's functions:
81
+
82
+ - **Purpose**: executes a function the model called
83
+ - **Method**: `POST`
84
+ - **Auth**: required
85
+ - **Token**: required. Each function's URL in the SWML carries a token that's valid for one call.
86
+ - **Content-Type**: `application/json`
87
+
88
+ ### 3. Health Endpoint (GET /fred/health)
89
+
90
+ Reports whether Fred is running. It needs no credentials, so load balancers and container health checks can use it.
91
+
92
+ ## Testing with swaig-test
93
+
94
+ The SDK includes a command-line tool, `swaig-test`, that loads an agent from its file and runs its functions without starting a server. It loads `fred.ts` with Node.js's own TypeScript support, which is why Fred needs Node.js 22.18 or later.
95
+
96
+ ### List Fred's Functions
97
+
98
+ List the functions Fred registers:
99
+
100
+ ```bash
101
+ npx swaig-test fred.ts --list-tools
102
+ ```
103
+
104
+ `swaig-test` imports `fred.ts` and finds the exported `fred`. The import doesn't run the banner or the server, so the function list is the whole output:
105
+
106
+ ```text
107
+ Available SWAIG functions:
108
+ search_wiki - Search Wikipedia for information about a topic and get article summaries (LOCAL webhook)
109
+ Parameters:
110
+ query (string): The search term or topic to look up on Wikipedia.
111
+ share_fun_fact - Share an interesting fact about Wikipedia itself (LOCAL webhook)
112
+ Parameters:
113
+ category (string [options: statistics, history, records, random]): Type of fact to share
114
+ ```
115
+
116
+ ### Test Functions Without Running the Server
117
+
118
+ Run a function with `--exec`, followed by its arguments:
119
+
120
+ ```bash
121
+ # Test Wikipedia search
122
+ npx swaig-test fred.ts --exec search_wiki --query "Python programming language"
123
+
124
+ # Test fun fact with category
125
+ npx swaig-test fred.ts --exec share_fun_fact --category history
126
+
127
+ # Test fun fact without parameters (uses default)
128
+ npx swaig-test fred.ts --exec share_fun_fact
129
+ ```
130
+
131
+ The fun fact with a category prints one fact from it:
132
+
133
+ ```text
134
+ RESULT:
135
+ Response: Here's a history fact about Wikipedia: Wikipedia was launched on January 15, 2001!
136
+ ```
137
+
138
+ Everything after `--exec` and the function name is passed to the function as an argument. Put `swaig-test`'s own options, such as `--verbose` or `--call-id`, before `--exec`.
139
+
140
+ ### Generate and Inspect SWML
141
+
142
+ `--dump-swml` prints the SWML document SignalWire would receive:
143
+
144
+ ```bash
145
+ # Generate SWML document
146
+ npx swaig-test fred.ts --dump-swml
147
+
148
+ # Get raw JSON for processing
149
+ npx swaig-test fred.ts --dump-swml --raw | jq '.sections.main[] | select(.ai) | .ai.SWAIG.functions'
150
+ ```
151
+
152
+ The `ai` verb isn't the first entry in `main`. An `answer` verb comes before it, so the `jq` filter selects the entry that has `ai`.
153
+
154
+ ### Test Different Call Scenarios
155
+
156
+ Options that describe the call change the request `swaig-test` simulates:
157
+
158
+ ```bash
159
+ # Simulate an inbound SIP call
160
+ npx swaig-test fred.ts --dump-swml --call-type sip --call-direction inbound
161
+
162
+ # Custom caller info
163
+ npx swaig-test fred.ts --dump-swml --from-number "+15551234567" --to-extension "+15559876543"
164
+ ```
165
+
166
+ ### Test Serverless Deployment
167
+
168
+ `--simulate-serverless` renders the agent as it would run on a serverless platform:
169
+
170
+ ```bash
171
+ # Test Lambda deployment
172
+ npx swaig-test fred.ts --simulate-serverless lambda --dump-swml
173
+
174
+ # Test with Lambda function execution
175
+ npx swaig-test fred.ts --simulate-serverless lambda --exec search_wiki --query "SignalWire"
176
+
177
+ # Test CGI deployment
178
+ npx swaig-test fred.ts --simulate-serverless cgi --cgi-host example.com --dump-swml
179
+ ```
180
+
181
+ ### Debug Mode
182
+
183
+ `--verbose` shows the SDK's logs while a function runs. Like every `swaig-test` option, it goes before `--exec`:
184
+
185
+ ```bash
186
+ # See the SDK's logs during the call
187
+ npx swaig-test fred.ts --verbose --exec search_wiki --query "Albert Einstein"
188
+
189
+ # Run a function as part of a specific call
190
+ npx swaig-test fred.ts --call-id custom-123 --exec share_fun_fact
191
+ ```
192
+
193
+ ### Benefits of swaig-test
194
+
195
+ `swaig-test` is the fastest way to check an agent:
196
+
197
+ 1. **No server required**: functions run without starting Fred
198
+ 2. **Quick validation**: check a function before you deploy
199
+ 3. **SWML inspection**: see exactly what SignalWire receives
200
+ 4. **Serverless testing**: check Lambda and CGI configurations
201
+ 5. **Debugging**: see the SDK's logs for one function call
202
+
203
+ For every option, see the [CLI guide](../../../docs/cli-guide.md).
204
+
205
+ ## Testing with curl
206
+
207
+ With Fred running, you can also test it over HTTP. Replace `username:password` with the credentials from Fred's output. The commands use `jq` to read the JSON.
208
+
209
+ ### Step 2: Fetch Fred's SWML Configuration
210
+
211
+ Fetch the SWML document, and format it:
212
+
213
+ ```bash
214
+ # Get Fred's SWML document
215
+ curl -u username:password http://localhost:3000/fred | jq
216
+ ```
217
+
218
+ The response is Fred's SWML document. This excerpt is shortened:
219
+
220
+ ```json
221
+ {
222
+ "version": "1.0.0",
223
+ "sections": {
224
+ "main": [
225
+ {
226
+ "answer": {}
227
+ },
228
+ {
229
+ "ai": {
230
+ "prompt": {
231
+ "pom": [
232
+ {
233
+ "body": "You are Fred, a friendly and knowledgeable assistant...",
234
+ "title": "Personality"
235
+ }
236
+ ]
237
+ },
238
+ "SWAIG": {
239
+ "functions": [
240
+ {
241
+ "function": "search_wiki",
242
+ "description": "Search Wikipedia for information about a topic and get article summaries"
243
+ },
244
+ {
245
+ "function": "share_fun_fact",
246
+ "description": "Share an interesting fact about Wikipedia itself"
247
+ }
248
+ ]
249
+ }
250
+ }
251
+ }
252
+ ]
253
+ }
254
+ }
255
+ ```
256
+
257
+ ### Step 3: Test Wikipedia Search
258
+
259
+ SignalWire calls a function at the URL Fred's SWML gives it, and that URL carries a security token that's valid for one call only. A test does the same. It fetches the SWML for a test call, takes the function's URL from it, and posts to that URL with the same call ID.
260
+
261
+ ```bash
262
+ # Fetch the SWML for a test call, and take search_wiki's URL from it
263
+ URL=$(curl -s -u username:password "http://localhost:3000/fred?call_id=test-call-123" \
264
+ | jq -r '.sections.main[] | select(.ai) | .ai.SWAIG.functions[] | select(.function == "search_wiki") | .web_hook_url')
265
+
266
+ # Call search_wiki the way SignalWire does, with the same call ID
267
+ curl -X POST -H "Content-Type: application/json" \
268
+ -d '{
269
+ "function": "search_wiki",
270
+ "argument": {
271
+ "parsed": [
272
+ {
273
+ "query": "FreeSWITCH"
274
+ }
275
+ ]
276
+ },
277
+ "call_id": "test-call-123"
278
+ }' \
279
+ "$URL"
280
+ ```
281
+
282
+ The URL already includes Fred's credentials, so the second `curl` doesn't need `-u`.
283
+
284
+ The response holds up to two article introductions, separated by a line of `=` characters. This one is shortened:
285
+
286
+ ```json
287
+ {"response":"**FreeSWITCH**\n\nFreeSWITCH is a free and open-source telephony software for real-time communication protocols using audio, video, text and other forms of media...\n\n==================================================\n\n**Siren (codec)**\n\n..."}
288
+ ```
289
+
290
+ ### Step 4: Test Fun Fact Function
291
+
292
+ Each function has its own token, so take `share_fun_fact`'s URL the same way:
293
+
294
+ ```bash
295
+ # Fetch the SWML for a test call, and take share_fun_fact's URL from it
296
+ URL=$(curl -s -u username:password "http://localhost:3000/fred?call_id=test-call-456" \
297
+ | jq -r '.sections.main[] | select(.ai) | .ai.SWAIG.functions[] | select(.function == "share_fun_fact") | .web_hook_url')
298
+
299
+ # Get a history fact
300
+ curl -X POST -H "Content-Type: application/json" \
301
+ -d '{
302
+ "function": "share_fun_fact",
303
+ "argument": {
304
+ "parsed": [
305
+ {
306
+ "category": "history"
307
+ }
308
+ ]
309
+ },
310
+ "call_id": "test-call-456"
311
+ }' \
312
+ "$URL"
313
+ ```
314
+
315
+ The response is one fact from the category:
316
+
317
+ ```json
318
+ {"response":"Here's a history fact about Wikipedia: Wikipedia's name comes from 'wiki' (Hawaiian for 'quick') and 'encyclopedia'!"}
319
+ ```
320
+
321
+ ## Managing Fred with Scripts
322
+
323
+ A small shell script can start Fred in the background, stop it, and report its status.
324
+
325
+ ### Step 5: Create Management Script
326
+
327
+ Create `fred.sh` with this minimal version. [Appendix A](appendix-complete-code.md#management-script-fredsh) has the complete script, which adds a `logs` command and waits for Fred to stop.
328
+
329
+ The script runs Fred with `node --import tsx fred.ts`. That loads the same TypeScript support `npx tsx` uses, in a single process, so the process ID the script saves is Fred's. `npx tsx` runs Fred in a child process of its own, and stopping the process the script started would leave Fred running.
330
+
331
+ ```bash
332
+ #!/bin/bash
333
+ # Start, stop and check Fred
334
+
335
+ PID_FILE="fred.pid"
336
+ LOG_FILE="fred.log"
337
+
338
+ # Colors for output
339
+ GREEN='\033[0;32m'
340
+ RED='\033[0;31m'
341
+ YELLOW='\033[1;33m'
342
+ NC='\033[0m' # No Color
343
+
344
+ # Function to check if Fred is running
345
+ is_running() {
346
+ if [ -f "$PID_FILE" ]; then
347
+ PID=$(cat "$PID_FILE")
348
+ if ps -p "$PID" > /dev/null 2>&1; then
349
+ return 0
350
+ fi
351
+ fi
352
+ return 1
353
+ }
354
+
355
+ # Start Fred
356
+ start_fred() {
357
+ if is_running; then
358
+ echo -e "${YELLOW}Fred is already running${NC}"
359
+ return 1
360
+ fi
361
+
362
+ echo -e "${GREEN}Starting Fred...${NC}"
363
+ nohup node --import tsx fred.ts > "$LOG_FILE" 2>&1 &
364
+ PID=$!
365
+ echo $PID > "$PID_FILE"
366
+
367
+ sleep 2
368
+
369
+ if is_running; then
370
+ echo -e "${GREEN}Fred started${NC}"
371
+ echo " PID: $PID"
372
+ echo " Logs: $LOG_FILE"
373
+
374
+ # Extract auth from log
375
+ AUTH=$(grep "Basic Auth:" "$LOG_FILE" | head -1)
376
+ if [ ! -z "$AUTH" ]; then
377
+ echo " $AUTH"
378
+ fi
379
+ else
380
+ echo -e "${RED}Fred failed to start${NC}"
381
+ return 1
382
+ fi
383
+ }
384
+
385
+ # Stop Fred
386
+ stop_fred() {
387
+ if ! is_running; then
388
+ echo -e "${YELLOW}Fred is not running${NC}"
389
+ return 1
390
+ fi
391
+
392
+ PID=$(cat "$PID_FILE")
393
+ echo -e "${GREEN}Stopping Fred...${NC}"
394
+ kill $PID
395
+ rm -f "$PID_FILE"
396
+ echo -e "${GREEN}Fred stopped${NC}"
397
+ }
398
+
399
+ # Main script
400
+ case "$1" in
401
+ start)
402
+ start_fred
403
+ ;;
404
+ stop)
405
+ stop_fred
406
+ ;;
407
+ restart)
408
+ stop_fred
409
+ sleep 1
410
+ start_fred
411
+ ;;
412
+ status)
413
+ if is_running; then
414
+ echo -e "${GREEN}Fred is running${NC}"
415
+ PID=$(cat "$PID_FILE")
416
+ echo " PID: $PID"
417
+ else
418
+ echo -e "${RED}Fred is not running${NC}"
419
+ fi
420
+ ;;
421
+ *)
422
+ echo "Usage: $0 {start|stop|restart|status}"
423
+ exit 1
424
+ ;;
425
+ esac
426
+ ```
427
+
428
+ Make it executable:
429
+
430
+ ```bash
431
+ chmod +x fred.sh
432
+ ```
433
+
434
+ ### Using the Management Script
435
+
436
+ The script's commands start, check and stop Fred:
437
+
438
+ ```bash
439
+ # Start Fred in background
440
+ ./fred.sh start
441
+
442
+ # Check status
443
+ ./fred.sh status
444
+
445
+ # View logs
446
+ tail -f fred.log
447
+
448
+ # Stop Fred
449
+ ./fred.sh stop
450
+ ```
451
+
452
+ ## Troubleshooting
453
+
454
+ Most problems when running Fred fall into a few groups.
455
+
456
+ ### Common Issues and Solutions
457
+
458
+ #### Port Already in Use
459
+
460
+ Another program is using port 3000. Node.js stops with `EADDRINUSE`:
461
+
462
+ ```text
463
+ Error: listen EADDRINUSE: address already in use 0.0.0.0:3000
464
+ ```
465
+
466
+ Find the program that holds the port, and stop it:
467
+
468
+ ```bash
469
+ # Find process using port 3000
470
+ lsof -i :3000
471
+ ```
472
+
473
+ Or run Fred on another port:
474
+
475
+ ```bash
476
+ PORT=3001 npx tsx fred.ts
477
+ ```
478
+
479
+ #### Authentication Failed
480
+
481
+ A request with missing or wrong credentials gets `401` and this body:
482
+
483
+ ```json
484
+ {"error":"Unauthorized"}
485
+ ```
486
+
487
+ To fix it, check three things:
488
+
489
+ - The username and password match the ones in Fred's output
490
+ - The credentials are current. A generated password changes each time Fred restarts.
491
+ - The `curl` command includes `-u username:password`
492
+
493
+ #### Cannot Find the Package
494
+
495
+ Node.js can't find the SDK when it isn't installed in the project that runs Fred:
496
+
497
+ ```text
498
+ Cannot find package '@signalwire/sdk' imported from /home/you/fred-bot/fred.ts
499
+ ```
500
+
501
+ Install the dependencies from the project directory, and run Fred from there:
502
+
503
+ ```bash
504
+ npm install
505
+ ```
506
+
507
+ #### Invalid or Expired Token
508
+
509
+ A function call through `/fred/swaig` can answer "the security token for this function is invalid or expired". The request either lacks the token from Fred's SWML, or carries a token from another call. [Step 3](#step-3-test-wikipedia-search) shows how to call a function with its token.
510
+
511
+ #### No Response from Functions
512
+
513
+ If a function call returns nothing useful, check three things:
514
+
515
+ 1. The function name matches exactly (`search_wiki`, not `search_wikipedia`)
516
+ 2. The JSON has the right structure, including the `parsed` array
517
+ 3. The `Content-Type: application/json` header is set
518
+
519
+ ### Debug Tips
520
+
521
+ These checks narrow down most problems.
522
+
523
+ #### Enable Debug Logging
524
+
525
+ `SIGNALWIRE_LOG_LEVEL` sets how much the SDK logs. Run Fred with debug logging:
526
+
527
+ ```bash
528
+ SIGNALWIRE_LOG_LEVEL=debug npx tsx fred.ts
529
+ ```
530
+
531
+ #### Test a Function Without the Server
532
+
533
+ `swaig-test` runs a function without a server, credentials or a token:
534
+
535
+ ```bash
536
+ # Simplest possible function call: no server, no credentials, no token
537
+ npx swaig-test fred.ts --exec share_fun_fact
538
+ ```
539
+
540
+ If this works but a call over HTTP doesn't, the problem is in the request, not in Fred's code.
541
+
542
+ #### Check Fred's Health
543
+
544
+ The health endpoint needs no credentials:
545
+
546
+ ```bash
547
+ curl http://localhost:3000/fred/health
548
+ ```
549
+
550
+ A running Fred answers:
551
+
552
+ ```json
553
+ {"status":"ok"}
554
+ ```
555
+
556
+ ## Production Considerations
557
+
558
+ Running Fred for real callers needs fixed secrets, HTTPS, and a process manager.
559
+
560
+ ### Security
561
+
562
+ Set these environment variables before Fred takes real calls:
563
+
564
+ 1. **Fixed credentials**, so they don't change on restart:
565
+
566
+ ```bash
567
+ export SWML_BASIC_AUTH_USER="fred"
568
+ export SWML_BASIC_AUTH_PASSWORD="a-long-random-password"
569
+ ```
570
+
571
+ 2. **Your project's signing key**, from the SignalWire dashboard. With it set, the SDK rejects requests that SignalWire didn't sign.
572
+
573
+ ```bash
574
+ export SIGNALWIRE_SIGNING_KEY="your-signing-key"
575
+ ```
576
+
577
+ 3. **A fixed secret for tool tokens.** Without one, the SDK generates a new secret each time Fred starts. Calls in progress during a restart then lose their tokens. Every copy of Fred must use the same secret.
578
+
579
+ ```bash
580
+ export SIGNALWIRE_SWAIG_SECRET="another-long-random-string"
581
+ ```
582
+
583
+ Serve Fred over HTTPS, either behind a reverse proxy such as nginx, or with the SDK's own TLS support (`SWML_SSL_ENABLED`, `SWML_SSL_CERT_PATH` and `SWML_SSL_KEY_PATH`).
584
+
585
+ Fred's banner prints the password. With fixed credentials in production, keep the log where only operators can read it, or remove the `Basic Auth` line from the banner.
586
+
587
+ ### Deployment Options
588
+
589
+ Three common ways to keep Fred running:
590
+
591
+ 1. **Direct**, choosing the port with `PORT`:
592
+
593
+ ```bash
594
+ PORT=8080 npx tsx fred.ts
595
+ ```
596
+
597
+ 2. **Docker**: [Appendix B](appendix-docker-deployment.md) has two Dockerfiles and a Compose file.
598
+
599
+ 3. **systemd**: [Appendix A](appendix-complete-code.md) has a service file.
600
+
601
+ ## Summary
602
+
603
+ In this tutorial you:
604
+
605
+ - Built Fred from scratch
606
+ - Ran Fred locally
607
+ - Tested Wikipedia search and fun facts with `swaig-test` and `curl`
608
+ - Created a management script
609
+ - Learned how to troubleshoot common problems
610
+
611
+ ## Next Steps
612
+
613
+ To take real phone calls with Fred:
614
+
615
+ 1. Sign up for a SignalWire account
616
+ 2. Make Fred reachable at a public HTTPS address, with a deployment or a tunnel such as ngrok
617
+ 3. Set `SWML_PROXY_URL_BASE` to that address
618
+ 4. Buy or configure a phone number, and point it at `https://username:password@your-address/fred`
619
+
620
+ The appendices have the complete code and deployment files. Continue with [Appendix A: Complete Code and Management Script](appendix-complete-code.md).
621
+
622
+ ---
623
+
624
+ The commands from this lesson, for quick reference:
625
+
626
+ ```bash
627
+ # Start Fred
628
+ npx tsx fred.ts
629
+
630
+ # Test SWML
631
+ curl -u user:pass http://localhost:3000/fred
632
+
633
+ # Test Wikipedia search
634
+ npx swaig-test fred.ts --exec search_wiki --query "Python"
635
+
636
+ # Test fun fact
637
+ npx swaig-test fred.ts --exec share_fun_fact
638
+ ```
639
+
640
+ ---
641
+
642
+ [Previous: Custom Functions](05-custom-functions.md) | [Overview](README.md) | [Next: Complete Code](appendix-complete-code.md)
@@ -0,0 +1,56 @@
1
+ # Fred Bot Tutorial: Building a Wikipedia AI Assistant
2
+
3
+ This tutorial builds Fred, a voice agent that answers questions from Wikipedia, using the SignalWire TypeScript SDK. Each lesson adds one part of the agent, and by the end you run Fred locally and test it from the command line.
4
+
5
+ ## What You'll Build
6
+
7
+ Fred is an AI voice agent with a friendly persona. It can:
8
+
9
+ - Search Wikipedia for information on a topic
10
+ - Share facts about Wikipedia itself
11
+ - Hold a conversation about what it finds
12
+ - Answer voice calls through the SignalWire platform
13
+
14
+ ## Lessons
15
+
16
+ Each lesson builds on the one before it, so work through them in order:
17
+
18
+ 1. [Introduction to SignalWire Agents](01-introduction.md): the SDK's core concepts and how an agent handles a call
19
+ 2. [Setting Up Your Environment](02-setup.md): create a Node.js project, install the SDK and check that it works
20
+ 3. [Creating Fred's Basic Structure](03-basic-agent.md): the agent class, its prompt, and its voice
21
+ 4. [Adding the Wikipedia Search Skill](04-wikipedia-skill.md): add Wikipedia search with the skills system
22
+ 5. [Creating Custom Functions](05-custom-functions.md): write a SWAIG function that shares facts about Wikipedia
23
+ 6. [Running and Testing Fred](06-running-testing.md): run Fred, and test it with `swaig-test` and `curl`
24
+
25
+ The appendices are for reference:
26
+
27
+ - [Appendix A: Complete Code and Management Script](appendix-complete-code.md): `fred.ts`, `fred.sh`, the project files and a quick start
28
+ - [Appendix B: Docker Deployment](appendix-docker-deployment.md): run Fred in a container
29
+
30
+ ## Prerequisites
31
+
32
+ You need:
33
+
34
+ - Node.js 22.18 or later, with npm
35
+ - Basic TypeScript knowledge
36
+ - Familiarity with the command line
37
+
38
+ Knowing how REST APIs or telephony applications work helps, but isn't required.
39
+
40
+ The tutorial takes 45 to 60 minutes in total, 5 to 10 minutes per lesson.
41
+
42
+ ## Getting Help
43
+
44
+ These resources cover the SDK and the platform:
45
+
46
+ - **SignalWire documentation:** [signalwire.com/docs](https://signalwire.com/docs)
47
+ - **SDK documentation:** the [docs](../../../docs/) folder in this repository, which also ships in the npm package and prints with `npx sw-tsdocs`
48
+ - **GitHub Issues:** [github.com/signalwire/signalwire-typescript](https://github.com/signalwire/signalwire-typescript)
49
+
50
+ When you've built Fred, the [Full-Guardrails Agent tutorial](../../full-guardrails-agent/tutorial/README.md) goes further: an agent whose actions have consequences, kept correct by code instead of by the prompt.
51
+
52
+ Start with [Lesson 1: Introduction to SignalWire Agents](01-introduction.md).
53
+
54
+ ---
55
+
56
+ *This tutorial was written for `@signalwire/sdk` 3.5.0.*