@signalwire/sdk 2.0.1 → 2.0.3

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 (610) 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/{src/index.ts → dist/index.d.ts} +13 -100
  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 +1026 -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/dist/rest/index.d.ts +131 -0
  149. package/{src/rest/index.ts → dist/rest/index.js} +101 -136
  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/{src/rest/pagination.ts → dist/rest/pagination.d.ts} +2 -61
  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 -2598
  416. package/src/AgentServer.ts +0 -442
  417. package/src/AuthHandler.ts +0 -256
  418. package/src/ConfigLoader.ts +0 -447
  419. package/src/ContextBuilder.ts +0 -1181
  420. package/src/DataMap.ts +0 -477
  421. package/src/FunctionResult.ts +0 -903
  422. package/src/Logger.ts +0 -337
  423. package/src/PomBuilder.ts +0 -467
  424. package/src/PromptManager.ts +0 -133
  425. package/src/SWMLHandler.ts +0 -298
  426. package/src/SWMLService.ts +0 -749
  427. package/src/SchemaUtils.ts +0 -361
  428. package/src/ServerlessAdapter.ts +0 -240
  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 -283
  433. package/src/SwmlVerbMethods.generated.ts +0 -234
  434. package/src/TypeInference.ts +0 -199
  435. package/src/WebService.ts +0 -641
  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/livewire/index.ts +0 -1252
  441. package/src/prefabs/ConciergeAgent.ts +0 -309
  442. package/src/prefabs/FAQBotAgent.ts +0 -415
  443. package/src/prefabs/InfoGathererAgent.ts +0 -379
  444. package/src/prefabs/ReceptionistAgent.ts +0 -395
  445. package/src/prefabs/SurveyAgent.ts +0 -671
  446. package/src/relay/Action.ts +0 -482
  447. package/src/relay/Call.ts +0 -1270
  448. package/src/relay/Deferred.ts +0 -94
  449. package/src/relay/Message.ts +0 -199
  450. package/src/relay/RelayClient.ts +0 -1185
  451. package/src/relay/RelayError.ts +0 -20
  452. package/src/relay/RelayEvent.ts +0 -944
  453. package/src/relay/index.ts +0 -123
  454. package/src/relay/types.ts +0 -149
  455. package/src/rest/HttpClient.ts +0 -164
  456. package/src/rest/RestError.ts +0 -45
  457. package/src/rest/base/BaseResource.ts +0 -32
  458. package/src/rest/base/CrudResource.ts +0 -98
  459. package/src/rest/base/CrudWithAddresses.ts +0 -37
  460. package/src/rest/namespaces/addresses.ts +0 -64
  461. package/src/rest/namespaces/calling.ts +0 -534
  462. package/src/rest/namespaces/chat.ts +0 -31
  463. package/src/rest/namespaces/compat.ts +0 -812
  464. package/src/rest/namespaces/datasphere.ts +0 -88
  465. package/src/rest/namespaces/fabric.ts +0 -417
  466. package/src/rest/namespaces/imported-numbers.ts +0 -31
  467. package/src/rest/namespaces/logs.ts +0 -151
  468. package/src/rest/namespaces/lookup.ts +0 -38
  469. package/src/rest/namespaces/mfa.ts +0 -61
  470. package/src/rest/namespaces/number-groups.ts +0 -68
  471. package/src/rest/namespaces/phone-numbers.ts +0 -76
  472. package/src/rest/namespaces/project.ts +0 -65
  473. package/src/rest/namespaces/pubsub.ts +0 -31
  474. package/src/rest/namespaces/queues.ts +0 -58
  475. package/src/rest/namespaces/recordings.ts +0 -53
  476. package/src/rest/namespaces/registry.ts +0 -200
  477. package/src/rest/namespaces/short-codes.ts +0 -54
  478. package/src/rest/namespaces/sip-profile.ts +0 -40
  479. package/src/rest/namespaces/verified-callers.ts +0 -46
  480. package/src/rest/namespaces/video.ts +0 -332
  481. package/src/rest/types.ts +0 -61
  482. package/src/skills/SkillBase.ts +0 -582
  483. package/src/skills/SkillManager.ts +0 -419
  484. package/src/skills/SkillRegistry.ts +0 -367
  485. package/src/skills/builtin/api_ninjas_trivia.ts +0 -285
  486. package/src/skills/builtin/ask_claude.ts +0 -246
  487. package/src/skills/builtin/claude_skills.ts +0 -983
  488. package/src/skills/builtin/custom_skills.ts +0 -327
  489. package/src/skills/builtin/datasphere.ts +0 -447
  490. package/src/skills/builtin/datasphere_serverless.ts +0 -347
  491. package/src/skills/builtin/datetime.ts +0 -137
  492. package/src/skills/builtin/google_maps.ts +0 -656
  493. package/src/skills/builtin/info_gatherer.ts +0 -415
  494. package/src/skills/builtin/joke.ts +0 -196
  495. package/src/skills/builtin/math.ts +0 -149
  496. package/src/skills/builtin/mcp_gateway.ts +0 -685
  497. package/src/skills/builtin/native_vector_search.ts +0 -910
  498. package/src/skills/builtin/play_background_file.ts +0 -367
  499. package/src/skills/builtin/spider.ts +0 -874
  500. package/src/skills/builtin/swml_transfer.ts +0 -645
  501. package/src/skills/builtin/weather_api.ts +0 -255
  502. package/src/skills/builtin/web_search.ts +0 -1083
  503. package/src/skills/builtin/wikipedia_search.ts +0 -304
  504. package/src/types.ts +0 -132
  505. package/tests/AgentBase.test.ts +0 -1093
  506. package/tests/AgentServer.test.ts +0 -126
  507. package/tests/AuthHandler.test.ts +0 -133
  508. package/tests/ConfigLoader.test.ts +0 -151
  509. package/tests/ContextBuilder.test.ts +0 -108
  510. package/tests/DataMap.test.ts +0 -367
  511. package/tests/EphemeralSkillCopy.test.ts +0 -107
  512. package/tests/FunctionResult.test.ts +0 -298
  513. package/tests/GracefulShutdown.test.ts +0 -46
  514. package/tests/Logger.test.ts +0 -420
  515. package/tests/PomBuilder.test.ts +0 -228
  516. package/tests/ProxyDetection.test.ts +0 -228
  517. package/tests/SWMLService.test.ts +0 -320
  518. package/tests/SWMLVerbHandler.test.ts +0 -523
  519. package/tests/SchemaUtils.test.ts +0 -106
  520. package/tests/SchemaUtils.verb.test.ts +0 -206
  521. package/tests/SecurityUtils.test.ts +0 -192
  522. package/tests/ServerlessAdapter.test.ts +0 -222
  523. package/tests/SessionManager.test.ts +0 -257
  524. package/tests/SkillBaseFeatures.test.ts +0 -130
  525. package/tests/SkillMultiInstance.test.ts +0 -102
  526. package/tests/SkillParameterSchemas.test.ts +0 -134
  527. package/tests/SkillRegistrySchema.test.ts +0 -84
  528. package/tests/SslConfig.test.ts +0 -97
  529. package/tests/SwmlBuilder.test.ts +0 -400
  530. package/tests/TypeInference.test.ts +0 -165
  531. package/tests/VerbHandlerRegistry.test.ts +0 -128
  532. package/tests/cli/mock-data.test.ts +0 -113
  533. package/tests/cli/swaig-test.test.ts +0 -108
  534. package/tests/examples.test.ts +0 -194
  535. package/tests/fixtures/scrape-parity/README.md +0 -53
  536. package/tests/fixtures/scrape-parity/expected/01_simple_article.json +0 -5
  537. package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +0 -5
  538. package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +0 -5
  539. package/tests/fixtures/scrape-parity/expected/04_bare_body.json +0 -5
  540. package/tests/fixtures/scrape-parity/expected/05_malformed.json +0 -5
  541. package/tests/fixtures/scrape-parity/expected/06_multi_class.json +0 -5
  542. package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +0 -5
  543. package/tests/fixtures/scrape-parity/expected/08_inline_script.json +0 -5
  544. package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +0 -5
  545. package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +0 -5
  546. package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +0 -5
  547. package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +0 -5
  548. package/tests/fixtures/scrape-parity/html/01_simple_article.html +0 -18
  549. package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +0 -18
  550. package/tests/fixtures/scrape-parity/html/03_nested_containers.html +0 -13
  551. package/tests/fixtures/scrape-parity/html/04_bare_body.html +0 -9
  552. package/tests/fixtures/scrape-parity/html/05_malformed.html +0 -11
  553. package/tests/fixtures/scrape-parity/html/06_multi_class.html +0 -18
  554. package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +0 -12
  555. package/tests/fixtures/scrape-parity/html/08_inline_script.html +0 -17
  556. package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +0 -21
  557. package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +0 -10
  558. package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +0 -13
  559. package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +0 -24
  560. package/tests/fixtures/scrape-parity/python_extract.py +0 -109
  561. package/tests/livewire/livewire.test.ts +0 -780
  562. package/tests/mcp.test.ts +0 -221
  563. package/tests/prefabs/prefabs.test.ts +0 -1093
  564. package/tests/relay/Action.test.ts +0 -392
  565. package/tests/relay/Call.test.ts +0 -535
  566. package/tests/relay/Deferred.test.ts +0 -71
  567. package/tests/relay/Message.test.ts +0 -164
  568. package/tests/relay/RelayClient.test.ts +0 -779
  569. package/tests/relay/RelayEvent.test.ts +0 -463
  570. package/tests/relay/helpers.ts +0 -79
  571. package/tests/rest/HttpClient.test.ts +0 -274
  572. package/tests/rest/RestError.test.ts +0 -53
  573. package/tests/rest/calling.test.ts +0 -156
  574. package/tests/rest/client.test.ts +0 -197
  575. package/tests/rest/compat.test.ts +0 -335
  576. package/tests/rest/datasphere.test.ts +0 -71
  577. package/tests/rest/fabric.test.ts +0 -186
  578. package/tests/rest/helpers.ts +0 -95
  579. package/tests/rest/logs.test.ts +0 -68
  580. package/tests/rest/pagination.test.ts +0 -133
  581. package/tests/rest/registry.test.ts +0 -94
  582. package/tests/rest/relay-rest.test.ts +0 -290
  583. package/tests/rest/video.test.ts +0 -173
  584. package/tests/setup.ts +0 -6
  585. package/tests/skills/SkillBase.test.ts +0 -108
  586. package/tests/skills/SkillManager.test.ts +0 -268
  587. package/tests/skills/SkillRegistry.test.ts +0 -176
  588. package/tests/skills/builtin.test.ts +0 -1472
  589. package/tests/skills/claude-skills.test.ts +0 -54
  590. package/tests/skills/custom-skills.test.ts +0 -53
  591. package/tests/skills/datasphere-serverless.test.ts +0 -70
  592. package/tests/skills/datasphere.test.ts +0 -107
  593. package/tests/skills/datetime.test.ts +0 -101
  594. package/tests/skills/google-maps.test.ts +0 -78
  595. package/tests/skills/info-gatherer.test.ts +0 -411
  596. package/tests/skills/joke.test.ts +0 -81
  597. package/tests/skills/math.test.ts +0 -68
  598. package/tests/skills/mcp-gateway.test.ts +0 -101
  599. package/tests/skills/play-background.test.ts +0 -54
  600. package/tests/skills/spider.test.ts +0 -108
  601. package/tests/skills/swml-transfer.test.ts +0 -178
  602. package/tests/skills/trivia.test.ts +0 -54
  603. package/tests/skills/vector-search.test.ts +0 -135
  604. package/tests/skills/weather-api.test.ts +0 -77
  605. package/tests/skills/web-search-parity.test.ts +0 -59
  606. package/tests/skills/web-search.test.ts +0 -103
  607. package/tests/skills/wikipedia.test.ts +0 -63
  608. package/tsconfig.json +0 -18
  609. package/vitest.config.ts +0 -9
  610. /package/{src → dist}/schema.json +0 -0
@@ -1,677 +0,0 @@
1
- # WebService Documentation
2
-
3
- The `WebService` class provides static file serving capabilities for the SignalWire AI Agents SDK. It follows the same architectural pattern as `SearchService`, allowing it to run as a standalone service or alongside your AI agents.
4
-
5
- ## Table of Contents
6
- - [Overview](#overview)
7
- - [Installation](#installation)
8
- - [Quick Start](#quick-start)
9
- - [Configuration](#configuration)
10
- - [Security Features](#security-features)
11
- - [HTTPS/SSL Support](#httpsssl-support)
12
- - [API Endpoints](#api-endpoints)
13
- - [Usage Examples](#usage-examples)
14
- - [Deployment Patterns](#deployment-patterns)
15
-
16
- ## Overview
17
-
18
- WebService is designed to serve static files with configurable security features. It's perfect for:
19
- - Serving agent documentation and API specs
20
- - Hosting static assets (images, CSS, JavaScript)
21
- - Serving generated reports and exports
22
- - Providing configuration files and templates
23
- - Hosting agent UI components
24
-
25
- ### Key Features
26
- - **Multiple directory mounting** - Serve different directories at different URL paths
27
- - **Security-first design** - Authentication, CORS, security headers, file filtering
28
- - **HTTPS support** - Full SSL/TLS support with PEM files
29
- - **Directory browsing** - Optional HTML directory listings
30
- - **MIME type handling** - Automatic content-type detection
31
- - **Path traversal protection** - Prevents access outside designated directories
32
- - **File filtering** - Allow/block specific file extensions
33
-
34
- ## Installation
35
-
36
- WebService is included in the core SignalWire AI Agents SDK:
37
-
38
- ```bash
39
- pip install @signalwire/sdk
40
- ```
41
-
42
- ## Quick Start
43
-
44
- ```python
45
- from signalwire_agents import WebService
46
-
47
- # Create a service to serve files
48
- service = WebService(
49
- port=8002,
50
- directories={
51
- "/docs": "./documentation",
52
- "/assets": "./static/assets"
53
- }
54
- )
55
-
56
- # Start the service
57
- service.start()
58
- # Service available at http://localhost:8002
59
- # Basic Auth: dev:w00t (auto-generated)
60
- ```
61
-
62
- ## Configuration
63
-
64
- WebService can be configured through multiple methods (in order of priority):
65
-
66
- ### 1. Constructor Parameters
67
-
68
- ```python
69
- service = WebService(
70
- port=8002, # Port to bind to
71
- directories={ # URL path to directory mappings
72
- "/docs": "./documentation",
73
- "/assets": "./static"
74
- },
75
- basic_auth=("admin", "secret"), # Custom authentication
76
- enable_directory_browsing=True, # Allow directory listings
77
- allowed_extensions=['.html', '.css', '.js'], # Whitelist extensions
78
- blocked_extensions=['.env', '.key'], # Blacklist extensions
79
- max_file_size=100 * 1024 * 1024, # Max file size (100MB)
80
- enable_cors=True # Enable CORS headers
81
- )
82
- ```
83
-
84
- ### 2. Environment Variables
85
-
86
- ```bash
87
- # Basic authentication
88
- export SWML_BASIC_AUTH_USER="admin"
89
- export SWML_BASIC_AUTH_PASS="secretpassword"
90
-
91
- # SSL/HTTPS configuration
92
- export SWML_SSL_ENABLED=true
93
- export SWML_SSL_CERT="/path/to/cert.pem"
94
- export SWML_SSL_KEY="/path/to/key.pem"
95
-
96
- # Security settings
97
- export SWML_ALLOWED_HOSTS="example.com,*.example.com"
98
- export SWML_CORS_ORIGINS="https://app.example.com"
99
- ```
100
-
101
- ### 3. Configuration File
102
-
103
- Create a `web.json` or `swml_web.json` file:
104
-
105
- ```json
106
- {
107
- "service": {
108
- "port": 8002,
109
- "directories": {
110
- "/docs": "./documentation",
111
- "/api": "./api-specs",
112
- "/reports": "./generated/reports"
113
- },
114
- "enable_directory_browsing": true,
115
- "max_file_size": 52428800,
116
- "allowed_extensions": [".html", ".css", ".js", ".json", ".pdf"],
117
- "blocked_extensions": [".env", ".key", ".pem"]
118
- },
119
- "security": {
120
- "basic_auth": {
121
- "username": "admin",
122
- "password": "secure123"
123
- },
124
- "ssl_enabled": true,
125
- "ssl_cert": "/etc/ssl/certs/server.crt",
126
- "ssl_key": "/etc/ssl/private/server.key",
127
- "allowed_hosts": ["*"],
128
- "cors_origins": ["*"]
129
- }
130
- }
131
- ```
132
-
133
- ## Security Features
134
-
135
- ### Basic Authentication
136
-
137
- WebService implements HTTP Basic Authentication. Credentials can be set via:
138
-
139
- 1. **Constructor**: `basic_auth=("username", "password")`
140
- 2. **Environment**: `SWML_BASIC_AUTH_USER` and `SWML_BASIC_AUTH_PASS`
141
- 3. **Config file**: `security.basic_auth` section
142
- 4. **Auto-generated**: If not specified, generates random credentials
143
-
144
- ### File Security
145
-
146
- #### Default Blocked Extensions/Files
147
- - `.env`, `.git`, `.gitignore`
148
- - `.key`, `.pem`, `.crt`
149
- - `.pyc`, `__pycache__`
150
- - `.DS_Store`, `.swp`
151
-
152
- #### Path Traversal Protection
153
- WebService prevents access outside designated directories:
154
- ```python
155
- # These attempts will be blocked:
156
- # GET /docs/../../../etc/passwd
157
- # GET /docs/./././../config.json
158
- ```
159
-
160
- #### File Size Limits
161
- Default maximum file size is 100MB. Configure with:
162
- ```python
163
- service = WebService(max_file_size=50 * 1024 * 1024) # 50MB
164
- ```
165
-
166
- ### Security Headers
167
-
168
- Automatically adds security headers to all responses:
169
- - `X-Content-Type-Options: nosniff`
170
- - `X-Frame-Options: DENY`
171
- - `X-XSS-Protection: 1; mode=block`
172
- - `Strict-Transport-Security` (when HTTPS is enabled)
173
-
174
- ## HTTPS/SSL Support
175
-
176
- WebService provides multiple ways to enable HTTPS:
177
-
178
- ### Method 1: Environment Variables
179
-
180
- ```bash
181
- # Using file paths
182
- export SWML_SSL_CERT="/path/to/cert.pem"
183
- export SWML_SSL_KEY="/path/to/key.pem"
184
-
185
- # Or using inline PEM content
186
- export SWML_SSL_CERT_INLINE="-----BEGIN CERTIFICATE-----
187
- MIIDXTCCAkWgAwIBAgIJAKLdQVPy...
188
- -----END CERTIFICATE-----"
189
- export SWML_SSL_KEY_INLINE="-----BEGIN PRIVATE KEY-----
190
- MIIEvQIBADANBgkqhkiG9w0BAQE...
191
- -----END PRIVATE KEY-----"
192
- ```
193
-
194
- ### Method 2: Direct Parameters
195
-
196
- ```python
197
- service = WebService(directories={"/docs": "./docs"})
198
- service.start(
199
- ssl_cert="/path/to/cert.pem",
200
- ssl_key="/path/to/key.pem"
201
- )
202
- # Service available at https://localhost:8002
203
- ```
204
-
205
- ### Method 3: Configuration File
206
-
207
- ```json
208
- {
209
- "security": {
210
- "ssl_enabled": true,
211
- "ssl_cert": "/etc/ssl/certs/server.crt",
212
- "ssl_key": "/etc/ssl/private/server.key"
213
- }
214
- }
215
- ```
216
-
217
- ### Generating Self-Signed Certificates
218
-
219
- For development/testing:
220
-
221
- ```bash
222
- # Generate a self-signed certificate
223
- openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \
224
- -days 365 -nodes -subj "/CN=localhost"
225
-
226
- # Use with WebService
227
- export SWML_SSL_CERT="cert.pem"
228
- export SWML_SSL_KEY="key.pem"
229
- ```
230
-
231
- ## API Endpoints
232
-
233
- ### GET /health
234
- Health check endpoint (no authentication required)
235
-
236
- **Response:**
237
- ```json
238
- {
239
- "status": "healthy",
240
- "directories": ["/docs", "/assets"],
241
- "ssl_enabled": false,
242
- "auth_required": true,
243
- "directory_browsing": true
244
- }
245
- ```
246
-
247
- ### GET /
248
- Root endpoint showing available directories
249
-
250
- **Response:** HTML page listing all mounted directories
251
-
252
- ### GET /{route}/{file_path}
253
- Serve files from mounted directories
254
-
255
- **Parameters:**
256
- - `route`: The mounted directory route (e.g., `/docs`)
257
- - `file_path`: Path to file within the directory
258
-
259
- **Response:**
260
- - File content with appropriate MIME type
261
- - 404 if file not found
262
- - 403 if file type blocked or directory browsing disabled
263
-
264
- ## Usage Examples
265
-
266
- ### Basic File Serving
267
-
268
- ```python
269
- from signalwire_agents import WebService
270
-
271
- # Serve documentation
272
- service = WebService(
273
- directories={
274
- "/docs": "./documentation",
275
- "/api": "./api-specs"
276
- }
277
- )
278
- service.start()
279
-
280
- # Files accessible at:
281
- # http://localhost:8002/docs/index.html
282
- # http://localhost:8002/api/swagger.json
283
- ```
284
-
285
- ### With Directory Browsing
286
-
287
- ```python
288
- service = WebService(
289
- directories={"/files": "./public"},
290
- enable_directory_browsing=True # Allow browsing directories
291
- )
292
- service.start()
293
-
294
- # Browse files at: http://localhost:8002/files/
295
- ```
296
-
297
- ### Restricted File Types
298
-
299
- ```python
300
- # Only serve web assets
301
- service = WebService(
302
- directories={"/web": "./www"},
303
- allowed_extensions=['.html', '.css', '.js', '.png', '.jpg', '.woff2'],
304
- enable_directory_browsing=False
305
- )
306
- ```
307
-
308
- ### Dynamic Directory Management
309
-
310
- ```python
311
- service = WebService()
312
-
313
- # Add directories after initialization
314
- service.add_directory("/docs", "./documentation")
315
- service.add_directory("/reports", "./generated/reports")
316
-
317
- # Remove a directory
318
- service.remove_directory("/reports")
319
-
320
- service.start()
321
- ```
322
-
323
- ### With Custom Authentication
324
-
325
- ```python
326
- service = WebService(
327
- directories={"/private": "./sensitive-docs"},
328
- basic_auth=("admin", "super-secret-password")
329
- )
330
- service.start()
331
- ```
332
-
333
- ### HTTPS with Let's Encrypt
334
-
335
- ```python
336
- # Assuming you have Let's Encrypt certificates
337
- service = WebService(
338
- directories={"/secure": "./secure-files"}
339
- )
340
- service.start(
341
- ssl_cert="/etc/letsencrypt/live/example.com/fullchain.pem",
342
- ssl_key="/etc/letsencrypt/live/example.com/privkey.pem"
343
- )
344
- # Service available at https://example.com:8002
345
- ```
346
-
347
- ### Multi-Environment Configuration
348
-
349
- ```python
350
- import os
351
-
352
- # Development vs Production
353
- if os.getenv("ENVIRONMENT") == "production":
354
- service = WebService(
355
- port=443,
356
- directories={"/": "./dist"},
357
- enable_directory_browsing=False
358
- )
359
- service.start(
360
- host="0.0.0.0",
361
- ssl_cert="/etc/ssl/certs/production.crt",
362
- ssl_key="/etc/ssl/private/production.key"
363
- )
364
- else:
365
- service = WebService(
366
- port=8002,
367
- directories={"/": "./src"},
368
- enable_directory_browsing=True
369
- )
370
- service.start()
371
- ```
372
-
373
- ## Deployment Patterns
374
-
375
- ### Standalone Service
376
-
377
- Run WebService as a dedicated static file server:
378
-
379
- ```python
380
- # web_server.py
381
- from signalwire_agents import WebService
382
-
383
- if __name__ == "__main__":
384
- service = WebService(
385
- port=8002,
386
- directories={
387
- "/docs": "/var/www/docs",
388
- "/assets": "/var/www/assets",
389
- "/downloads": "/var/www/downloads"
390
- }
391
- )
392
- service.start()
393
- ```
394
-
395
- ### Alongside AI Agents
396
-
397
- Run WebService alongside your AI agents on different ports:
398
-
399
- ```python
400
- # main.py
401
- from signalwire_agents import AgentBase, WebService
402
- import threading
403
-
404
- # Start WebService in background
405
- def run_web_service():
406
- web = WebService(
407
- port=8002,
408
- directories={"/docs": "./agent-docs"}
409
- )
410
- web.start()
411
-
412
- # Start web service thread
413
- web_thread = threading.Thread(target=run_web_service, daemon=True)
414
- web_thread.start()
415
-
416
- # Run your agent
417
- class MyAgent(AgentBase):
418
- def __init__(self):
419
- super().__init__(name="My Agent")
420
-
421
- agent = MyAgent()
422
- agent.serve(port=3000) # Agent on port 3000, WebService on 8002
423
- ```
424
-
425
- ### Docker Deployment
426
-
427
- ```dockerfile
428
- FROM python:3.9-slim
429
-
430
- WORKDIR /app
431
-
432
- # Install SDK
433
- RUN pip install @signalwire/sdk
434
-
435
- # Copy static files
436
- COPY ./static /app/static
437
- COPY ./web_config.json /app/web_config.json
438
-
439
- # Expose port
440
- EXPOSE 8002
441
-
442
- # Run WebService
443
- CMD ["python", "-c", "from signalwire_agents import WebService; WebService(config_file='web_config.json').start()"]
444
- ```
445
-
446
- ### Systemd Service
447
-
448
- Create `/etc/systemd/system/signalwire-web.service`:
449
-
450
- ```ini
451
- [Unit]
452
- Description=SignalWire Web Service
453
- After=network.target
454
-
455
- [Service]
456
- Type=simple
457
- User=www-data
458
- WorkingDirectory=/opt/signalwire
459
- Environment="SWML_SSL_CERT=/etc/ssl/certs/server.crt"
460
- Environment="SWML_SSL_KEY=/etc/ssl/private/server.key"
461
- ExecStart=/usr/bin/python3 -c "from signalwire_agents import WebService; WebService(directories={'/': '/var/www/html'}).start()"
462
- Restart=always
463
-
464
- [Install]
465
- WantedBy=multi-user.target
466
- ```
467
-
468
- ### Nginx Reverse Proxy
469
-
470
- For production, use Nginx as a reverse proxy:
471
-
472
- ```nginx
473
- server {
474
- listen 80;
475
- server_name static.example.com;
476
-
477
- # Redirect to HTTPS
478
- return 301 https://$server_name$request_uri;
479
- }
480
-
481
- server {
482
- listen 443 ssl http2;
483
- server_name static.example.com;
484
-
485
- ssl_certificate /etc/ssl/certs/example.com.crt;
486
- ssl_certificate_key /etc/ssl/private/example.com.key;
487
-
488
- location / {
489
- proxy_pass http://localhost:8002;
490
- proxy_set_header Host $host;
491
- proxy_set_header X-Real-IP $remote_addr;
492
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
493
- proxy_set_header X-Forwarded-Proto $scheme;
494
-
495
- # Cache static assets
496
- location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
497
- proxy_pass http://localhost:8002;
498
- expires 1h;
499
- add_header Cache-Control "public, immutable";
500
- }
501
- }
502
- }
503
- ```
504
-
505
- ## Best Practices
506
-
507
- ### Security
508
- 1. **Always use HTTPS in production** - Protect data in transit
509
- 2. **Change default credentials** - Never use auto-generated auth in production
510
- 3. **Restrict file types** - Use `allowed_extensions` to whitelist safe files
511
- 4. **Disable directory browsing** - Turn off in production environments
512
- 5. **Use reverse proxy** - Put Nginx/Apache in front for additional security
513
-
514
- ### Performance
515
- 1. **Set appropriate cache headers** - WebService adds 1-hour cache by default
516
- 2. **Limit file sizes** - Adjust `max_file_size` based on your needs
517
- 3. **Use CDN for static assets** - Offload traffic for better performance
518
- 4. **Compress large files** - Use gzip/brotli at reverse proxy level
519
-
520
- ### Organization
521
- 1. **Separate content types** - Use different routes for different file types
522
- 2. **Version your assets** - Include version in path (e.g., `/assets/v1/`)
523
- 3. **Use index.html** - Provide default files for directories
524
- 4. **Document your structure** - Maintain clear directory organization
525
-
526
- ## Troubleshooting
527
-
528
- ### Common Issues
529
-
530
- **Issue: "FastAPI not available"**
531
- ```bash
532
- # Install FastAPI and uvicorn
533
- pip install fastapi uvicorn
534
- ```
535
-
536
- **Issue: SSL certificate errors**
537
- ```python
538
- # Check certificate paths
539
- import os
540
- print(os.path.exists("/path/to/cert.pem")) # Should be True
541
- print(os.path.exists("/path/to/key.pem")) # Should be True
542
- ```
543
-
544
- **Issue: Permission denied**
545
- ```bash
546
- # Ensure read permissions on directories
547
- chmod -R 755 /path/to/static/files
548
- ```
549
-
550
- **Issue: Directory not found**
551
- ```python
552
- # Use absolute paths
553
- import os
554
- service = WebService(
555
- directories={
556
- "/docs": os.path.abspath("./documentation")
557
- }
558
- )
559
- ```
560
-
561
- ### Debug Logging
562
-
563
- Enable debug logging to troubleshoot issues:
564
-
565
- ```python
566
- import logging
567
- logging.basicConfig(level=logging.DEBUG)
568
-
569
- service = WebService(directories={"/test": "./test"})
570
- service.start()
571
- ```
572
-
573
- ## API Reference
574
-
575
- ### WebService Class
576
-
577
- ```python
578
- class WebService:
579
- def __init__(self,
580
- port: int = 8002,
581
- directories: Dict[str, str] = None,
582
- basic_auth: Optional[Tuple[str, str]] = None,
583
- config_file: Optional[str] = None,
584
- enable_directory_browsing: bool = False,
585
- allowed_extensions: Optional[list] = None,
586
- blocked_extensions: Optional[list] = None,
587
- max_file_size: int = 100 * 1024 * 1024,
588
- enable_cors: bool = True)
589
- ```
590
-
591
- #### Parameters
592
- - `port`: Port to bind to (default: 8002)
593
- - `directories`: Dictionary mapping URL paths to local directories
594
- - `basic_auth`: Tuple of (username, password) for authentication
595
- - `config_file`: Path to JSON configuration file
596
- - `enable_directory_browsing`: Allow directory listing (default: False)
597
- - `allowed_extensions`: List of allowed file extensions
598
- - `blocked_extensions`: List of blocked file extensions
599
- - `max_file_size`: Maximum file size in bytes (default: 100MB)
600
- - `enable_cors`: Enable CORS headers (default: True)
601
-
602
- #### Methods
603
-
604
- ##### start()
605
- ```python
606
- def start(self,
607
- host: str = "0.0.0.0",
608
- port: Optional[int] = None,
609
- ssl_cert: Optional[str] = None,
610
- ssl_key: Optional[str] = None)
611
- ```
612
- Start the web service.
613
-
614
- ##### add_directory()
615
- ```python
616
- def add_directory(self, route: str, directory: str) -> None
617
- ```
618
- Add a new directory to serve.
619
-
620
- ##### remove_directory()
621
- ```python
622
- def remove_directory(self, route: str) -> None
623
- ```
624
- Remove a directory from being served.
625
-
626
- ## Integration with SignalWire Agents
627
-
628
- WebService complements AI agents by providing static file serving:
629
-
630
- ```python
631
- from signalwire_agents import AgentBase, WebService
632
-
633
- class DocumentationAgent(AgentBase):
634
- def __init__(self):
635
- super().__init__(name="Documentation Assistant")
636
-
637
- # Reference documentation served by WebService
638
- self.prompt_add_section(
639
- "Documentation",
640
- "User documentation is available at https://example.com:8002/docs/"
641
- )
642
-
643
- @self.tool(
644
- "get_doc_link",
645
- description="Get link to a documentation page",
646
- parameters={
647
- "doc_name": {"type": "string", "description": "Name of the documentation page"}
648
- }
649
- )
650
- def get_doc_link(self, args, raw_data):
651
- doc_name = args.get('doc_name')
652
- return FunctionResult(
653
- f"Documentation available at: https://example.com:8002/docs/{doc_name}.html"
654
- )
655
-
656
- # Run both services
657
- if __name__ == "__main__":
658
- # Start WebService for documentation
659
- web = WebService(
660
- port=8002,
661
- directories={"/docs": "./documentation"}
662
- )
663
-
664
- # Start agent
665
- agent = DocumentationAgent()
666
-
667
- # Run in threads or separate processes
668
- import threading
669
- web_thread = threading.Thread(target=web.start, daemon=True)
670
- web_thread.start()
671
-
672
- agent.serve(port=3000)
673
- ```
674
-
675
- ## Summary
676
-
677
- WebService provides a secure, configurable static file server that integrates with the SignalWire AI Agents SDK. It follows the same architectural patterns as other SDK services, making it familiar and easy to use while providing configurable security features and flexible deployment options.