@signalwire/sdk 2.0.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 (325) hide show
  1. package/.github/workflows/publish.yml +27 -0
  2. package/.github/workflows/test.yml +17 -0
  3. package/CLAUDE.md +112 -0
  4. package/README.md +254 -0
  5. package/docs/MIGRATION-2.0.md +81 -0
  6. package/docs/agent-guide.md +869 -0
  7. package/docs/agent_guide.md +1026 -0
  8. package/docs/api-reference.md +2420 -0
  9. package/docs/api_reference.md +1301 -0
  10. package/docs/architecture.md +843 -0
  11. package/docs/cli-guide.md +579 -0
  12. package/docs/cli_guide.md +448 -0
  13. package/docs/cloud_functions_guide.md +474 -0
  14. package/docs/configuration.md +422 -0
  15. package/docs/contexts-guide.md +787 -0
  16. package/docs/contexts_guide.md +511 -0
  17. package/docs/datamap-guide.md +1141 -0
  18. package/docs/datamap_guide.md +595 -0
  19. package/docs/llm_parameters.md +239 -0
  20. package/docs/mcp_gateway_reference.md +648 -0
  21. package/docs/mcp_integration.md +108 -0
  22. package/docs/prefabs-guide.md +800 -0
  23. package/docs/sdk_features.md +477 -0
  24. package/docs/security.md +436 -0
  25. package/docs/serverless-guide.md +513 -0
  26. package/docs/skills-guide.md +857 -0
  27. package/docs/skills-system.md +301 -0
  28. package/docs/skills_parameter_schema.md +392 -0
  29. package/docs/skills_system.md +467 -0
  30. package/docs/swaig-reference.md +1627 -0
  31. package/docs/swaig_reference.md +910 -0
  32. package/docs/swml_service_guide.md +600 -0
  33. package/docs/third_party_skills.md +533 -0
  34. package/docs/web_service.md +677 -0
  35. package/examples/README.md +131 -0
  36. package/examples/advanced-datamap.ts +100 -0
  37. package/examples/advanced-dynamic-config.ts +70 -0
  38. package/examples/auto-vivified.ts +94 -0
  39. package/examples/call-flow.ts +63 -0
  40. package/examples/comprehensive-dynamic.ts +125 -0
  41. package/examples/contexts-steps.ts +65 -0
  42. package/examples/custom-path.ts +45 -0
  43. package/examples/datamap-tools.ts +55 -0
  44. package/examples/datasphere-multi-instance.ts +63 -0
  45. package/examples/datasphere-serverless-env.ts +68 -0
  46. package/examples/datasphere-webhook-env.ts +66 -0
  47. package/examples/datasphere.ts +37 -0
  48. package/examples/declarative.ts +100 -0
  49. package/examples/dynamic-config.ts +54 -0
  50. package/examples/dynamic-info-gatherer.ts +69 -0
  51. package/examples/dynamic-swml-service.ts +67 -0
  52. package/examples/gather-info.ts +71 -0
  53. package/examples/gather-per-question-functions-demo.ts +140 -0
  54. package/examples/joke-agent.ts +34 -0
  55. package/examples/kubernetes-agent.ts +45 -0
  56. package/examples/llm-params.ts +69 -0
  57. package/examples/mcp-agent.ts +84 -0
  58. package/examples/mcp-gateway.ts +35 -0
  59. package/examples/multi-agent.ts +73 -0
  60. package/examples/multi-endpoint.ts +79 -0
  61. package/examples/pom-prompt.ts +71 -0
  62. package/examples/prefab-concierge.ts +47 -0
  63. package/examples/prefab-faq.ts +54 -0
  64. package/examples/prefab-info-gatherer.ts +33 -0
  65. package/examples/prefab-receptionist.ts +36 -0
  66. package/examples/prefab-survey.ts +68 -0
  67. package/examples/record-call.ts +67 -0
  68. package/examples/relay-demo.ts +33 -0
  69. package/examples/room-and-sip.ts +94 -0
  70. package/examples/serverless-lambda.ts +35 -0
  71. package/examples/session-state.ts +83 -0
  72. package/examples/simple-agent.ts +36 -0
  73. package/examples/simple-static.ts +29 -0
  74. package/examples/skills-demo.ts +38 -0
  75. package/examples/step-function-inheritance-demo.ts +124 -0
  76. package/examples/swaig-features.ts +187 -0
  77. package/examples/swml-service-routing.ts +66 -0
  78. package/examples/swml-service.ts +38 -0
  79. package/examples/tap.ts +68 -0
  80. package/examples/verb-methods.ts +45 -0
  81. package/examples/web-search-multi-instance.ts +72 -0
  82. package/examples/web-search.ts +38 -0
  83. package/examples/wikipedia.ts +36 -0
  84. package/livewire/README.md +140 -0
  85. package/livewire/docs/migration-guide.md +228 -0
  86. package/livewire/examples/livewire-basic-agent.ts +74 -0
  87. package/livewire/examples/livewire-handoff.ts +197 -0
  88. package/livewire/examples/livewire-multi-tool.ts +117 -0
  89. package/package.json +38 -0
  90. package/relay/README.md +70 -0
  91. package/relay/RELAY_IMPLEMENTATION_GUIDE.md +1257 -0
  92. package/relay/docs/call-methods.md +474 -0
  93. package/relay/docs/client-reference.md +142 -0
  94. package/relay/docs/events.md +134 -0
  95. package/relay/docs/getting-started.md +134 -0
  96. package/relay/docs/guide.md +306 -0
  97. package/relay/docs/messaging.md +182 -0
  98. package/relay/examples/relay-inbound.ts +66 -0
  99. package/relay/examples/relay-messaging.ts +71 -0
  100. package/relay/examples/relay-outbound.ts +76 -0
  101. package/rest/README.md +95 -0
  102. package/rest/docs/calling.md +273 -0
  103. package/rest/docs/client-reference.md +107 -0
  104. package/rest/docs/compat.md +204 -0
  105. package/rest/docs/fabric.md +183 -0
  106. package/rest/docs/getting-started.md +110 -0
  107. package/rest/docs/guide.md +351 -0
  108. package/rest/docs/namespaces.md +285 -0
  109. package/rest/examples/rest-10dlc-registration.ts +161 -0
  110. package/rest/examples/rest-calling-ivr-and-ai.ts +102 -0
  111. package/rest/examples/rest-calling-play-and-record.ts +91 -0
  112. package/rest/examples/rest-client.ts +65 -0
  113. package/rest/examples/rest-compat-laml.ts +210 -0
  114. package/rest/examples/rest-datasphere-search.ts +82 -0
  115. package/rest/examples/rest-fabric-conferences-and-routing.ts +144 -0
  116. package/rest/examples/rest-fabric-subscribers-and-sip.ts +108 -0
  117. package/rest/examples/rest-fabric-swml-and-callflows.ts +99 -0
  118. package/rest/examples/rest-manage-resources.ts +65 -0
  119. package/rest/examples/rest-phone-number-management.ts +197 -0
  120. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  121. package/rest/examples/rest-video-rooms.ts +186 -0
  122. package/src/AgentBase.ts +2489 -0
  123. package/src/AgentServer.ts +415 -0
  124. package/src/AuthHandler.ts +256 -0
  125. package/src/ConfigLoader.ts +447 -0
  126. package/src/ContextBuilder.ts +1150 -0
  127. package/src/DataMap.ts +449 -0
  128. package/src/FunctionResult.ts +866 -0
  129. package/src/Logger.ts +337 -0
  130. package/src/PomBuilder.ts +439 -0
  131. package/src/PromptManager.ts +133 -0
  132. package/src/SWMLHandler.ts +298 -0
  133. package/src/SWMLService.ts +717 -0
  134. package/src/SchemaUtils.ts +361 -0
  135. package/src/SecurityUtils.ts +153 -0
  136. package/src/ServerlessAdapter.ts +221 -0
  137. package/src/SessionManager.ts +311 -0
  138. package/src/SslConfig.ts +118 -0
  139. package/src/SwaigFunction.ts +276 -0
  140. package/src/SwmlBuilder.ts +258 -0
  141. package/src/SwmlVerbMethods.generated.ts +234 -0
  142. package/src/TypeInference.ts +181 -0
  143. package/src/WebService.ts +619 -0
  144. package/src/cli/agent-loader.ts +166 -0
  145. package/src/cli/mock-data.ts +111 -0
  146. package/src/cli/swaig-test.ts +452 -0
  147. package/src/generateVerbTypes.ts +322 -0
  148. package/src/index.ts +167 -0
  149. package/src/livewire/index.ts +950 -0
  150. package/src/prefabs/ConciergeAgent.ts +287 -0
  151. package/src/prefabs/FAQBotAgent.ts +384 -0
  152. package/src/prefabs/InfoGathererAgent.ts +339 -0
  153. package/src/prefabs/ReceptionistAgent.ts +366 -0
  154. package/src/prefabs/SurveyAgent.ts +646 -0
  155. package/src/prefabs/index.ts +27 -0
  156. package/src/relay/Action.ts +314 -0
  157. package/src/relay/Call.ts +854 -0
  158. package/src/relay/Deferred.ts +71 -0
  159. package/src/relay/Message.ts +148 -0
  160. package/src/relay/RelayClient.ts +1036 -0
  161. package/src/relay/RelayError.ts +14 -0
  162. package/src/relay/RelayEvent.ts +892 -0
  163. package/src/relay/constants.ts +132 -0
  164. package/src/relay/index.ts +123 -0
  165. package/src/relay/types.ts +149 -0
  166. package/src/rest/HttpClient.ts +103 -0
  167. package/src/rest/RestError.ts +31 -0
  168. package/src/rest/base/BaseResource.ts +19 -0
  169. package/src/rest/base/CrudResource.ts +51 -0
  170. package/src/rest/base/CrudWithAddresses.ts +26 -0
  171. package/src/rest/index.ts +200 -0
  172. package/src/rest/namespaces/addresses.ts +32 -0
  173. package/src/rest/namespaces/calling.ts +187 -0
  174. package/src/rest/namespaces/chat.ts +20 -0
  175. package/src/rest/namespaces/compat.ts +352 -0
  176. package/src/rest/namespaces/datasphere.ts +45 -0
  177. package/src/rest/namespaces/fabric.ts +222 -0
  178. package/src/rest/namespaces/imported-numbers.ts +20 -0
  179. package/src/rest/namespaces/logs.ts +84 -0
  180. package/src/rest/namespaces/lookup.ts +21 -0
  181. package/src/rest/namespaces/mfa.ts +30 -0
  182. package/src/rest/namespaces/number-groups.ts +38 -0
  183. package/src/rest/namespaces/phone-numbers.ts +44 -0
  184. package/src/rest/namespaces/project.ts +36 -0
  185. package/src/rest/namespaces/pubsub.ts +20 -0
  186. package/src/rest/namespaces/queues.ts +33 -0
  187. package/src/rest/namespaces/recordings.ts +28 -0
  188. package/src/rest/namespaces/registry.ts +101 -0
  189. package/src/rest/namespaces/short-codes.ts +28 -0
  190. package/src/rest/namespaces/sip-profile.ts +25 -0
  191. package/src/rest/namespaces/verified-callers.ts +27 -0
  192. package/src/rest/namespaces/video.ts +165 -0
  193. package/src/rest/pagination.ts +84 -0
  194. package/src/rest/types.ts +61 -0
  195. package/src/schema.json +12250 -0
  196. package/src/skills/SkillBase.ts +547 -0
  197. package/src/skills/SkillManager.ts +415 -0
  198. package/src/skills/SkillRegistry.ts +367 -0
  199. package/src/skills/builtin/api_ninjas_trivia.ts +280 -0
  200. package/src/skills/builtin/ask_claude.ts +241 -0
  201. package/src/skills/builtin/claude_skills.ts +978 -0
  202. package/src/skills/builtin/custom_skills.ts +312 -0
  203. package/src/skills/builtin/datasphere.ts +438 -0
  204. package/src/skills/builtin/datasphere_serverless.ts +339 -0
  205. package/src/skills/builtin/datetime.ts +130 -0
  206. package/src/skills/builtin/google_maps.ts +651 -0
  207. package/src/skills/builtin/index.ts +88 -0
  208. package/src/skills/builtin/info_gatherer.ts +405 -0
  209. package/src/skills/builtin/joke.ts +191 -0
  210. package/src/skills/builtin/math.ts +142 -0
  211. package/src/skills/builtin/mcp_gateway.ts +677 -0
  212. package/src/skills/builtin/native_vector_search.ts +901 -0
  213. package/src/skills/builtin/play_background_file.ts +358 -0
  214. package/src/skills/builtin/spider.ts +869 -0
  215. package/src/skills/builtin/swml_transfer.ts +635 -0
  216. package/src/skills/builtin/weather_api.ts +248 -0
  217. package/src/skills/builtin/web_search.ts +1074 -0
  218. package/src/skills/builtin/wikipedia_search.ts +299 -0
  219. package/src/skills/index.ts +12 -0
  220. package/src/types.ts +132 -0
  221. package/tests/AgentBase.test.ts +1093 -0
  222. package/tests/AgentServer.test.ts +126 -0
  223. package/tests/AuthHandler.test.ts +133 -0
  224. package/tests/ConfigLoader.test.ts +151 -0
  225. package/tests/ContextBuilder.test.ts +108 -0
  226. package/tests/DataMap.test.ts +367 -0
  227. package/tests/EphemeralSkillCopy.test.ts +107 -0
  228. package/tests/FunctionResult.test.ts +298 -0
  229. package/tests/GracefulShutdown.test.ts +46 -0
  230. package/tests/Logger.test.ts +420 -0
  231. package/tests/PomBuilder.test.ts +228 -0
  232. package/tests/ProxyDetection.test.ts +228 -0
  233. package/tests/SWMLService.test.ts +320 -0
  234. package/tests/SWMLVerbHandler.test.ts +523 -0
  235. package/tests/SchemaUtils.test.ts +106 -0
  236. package/tests/SchemaUtils.verb.test.ts +206 -0
  237. package/tests/SecurityUtils.test.ts +192 -0
  238. package/tests/ServerlessAdapter.test.ts +222 -0
  239. package/tests/SessionManager.test.ts +257 -0
  240. package/tests/SkillBaseFeatures.test.ts +130 -0
  241. package/tests/SkillMultiInstance.test.ts +102 -0
  242. package/tests/SkillParameterSchemas.test.ts +134 -0
  243. package/tests/SkillRegistrySchema.test.ts +84 -0
  244. package/tests/SslConfig.test.ts +97 -0
  245. package/tests/SwmlBuilder.test.ts +400 -0
  246. package/tests/TypeInference.test.ts +165 -0
  247. package/tests/VerbHandlerRegistry.test.ts +128 -0
  248. package/tests/cli/mock-data.test.ts +113 -0
  249. package/tests/cli/swaig-test.test.ts +108 -0
  250. package/tests/examples.test.ts +194 -0
  251. package/tests/fixtures/scrape-parity/README.md +53 -0
  252. package/tests/fixtures/scrape-parity/expected/01_simple_article.json +5 -0
  253. package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +5 -0
  254. package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +5 -0
  255. package/tests/fixtures/scrape-parity/expected/04_bare_body.json +5 -0
  256. package/tests/fixtures/scrape-parity/expected/05_malformed.json +5 -0
  257. package/tests/fixtures/scrape-parity/expected/06_multi_class.json +5 -0
  258. package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +5 -0
  259. package/tests/fixtures/scrape-parity/expected/08_inline_script.json +5 -0
  260. package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +5 -0
  261. package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +5 -0
  262. package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +5 -0
  263. package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +5 -0
  264. package/tests/fixtures/scrape-parity/html/01_simple_article.html +18 -0
  265. package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +18 -0
  266. package/tests/fixtures/scrape-parity/html/03_nested_containers.html +13 -0
  267. package/tests/fixtures/scrape-parity/html/04_bare_body.html +9 -0
  268. package/tests/fixtures/scrape-parity/html/05_malformed.html +11 -0
  269. package/tests/fixtures/scrape-parity/html/06_multi_class.html +18 -0
  270. package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +12 -0
  271. package/tests/fixtures/scrape-parity/html/08_inline_script.html +17 -0
  272. package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +21 -0
  273. package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +10 -0
  274. package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +13 -0
  275. package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +24 -0
  276. package/tests/fixtures/scrape-parity/python_extract.py +109 -0
  277. package/tests/livewire/livewire.test.ts +780 -0
  278. package/tests/mcp.test.ts +221 -0
  279. package/tests/prefabs/prefabs.test.ts +1093 -0
  280. package/tests/relay/Action.test.ts +392 -0
  281. package/tests/relay/Call.test.ts +535 -0
  282. package/tests/relay/Deferred.test.ts +71 -0
  283. package/tests/relay/Message.test.ts +164 -0
  284. package/tests/relay/RelayClient.test.ts +779 -0
  285. package/tests/relay/RelayEvent.test.ts +463 -0
  286. package/tests/relay/helpers.ts +79 -0
  287. package/tests/rest/HttpClient.test.ts +274 -0
  288. package/tests/rest/RestError.test.ts +53 -0
  289. package/tests/rest/calling.test.ts +156 -0
  290. package/tests/rest/client.test.ts +197 -0
  291. package/tests/rest/compat.test.ts +335 -0
  292. package/tests/rest/datasphere.test.ts +71 -0
  293. package/tests/rest/fabric.test.ts +186 -0
  294. package/tests/rest/helpers.ts +95 -0
  295. package/tests/rest/logs.test.ts +68 -0
  296. package/tests/rest/pagination.test.ts +133 -0
  297. package/tests/rest/registry.test.ts +94 -0
  298. package/tests/rest/relay-rest.test.ts +290 -0
  299. package/tests/rest/video.test.ts +173 -0
  300. package/tests/setup.ts +6 -0
  301. package/tests/skills/SkillBase.test.ts +108 -0
  302. package/tests/skills/SkillManager.test.ts +268 -0
  303. package/tests/skills/SkillRegistry.test.ts +176 -0
  304. package/tests/skills/builtin.test.ts +1472 -0
  305. package/tests/skills/claude-skills.test.ts +54 -0
  306. package/tests/skills/custom-skills.test.ts +53 -0
  307. package/tests/skills/datasphere-serverless.test.ts +70 -0
  308. package/tests/skills/datasphere.test.ts +107 -0
  309. package/tests/skills/datetime.test.ts +101 -0
  310. package/tests/skills/google-maps.test.ts +78 -0
  311. package/tests/skills/info-gatherer.test.ts +411 -0
  312. package/tests/skills/joke.test.ts +81 -0
  313. package/tests/skills/math.test.ts +68 -0
  314. package/tests/skills/mcp-gateway.test.ts +101 -0
  315. package/tests/skills/play-background.test.ts +54 -0
  316. package/tests/skills/spider.test.ts +108 -0
  317. package/tests/skills/swml-transfer.test.ts +178 -0
  318. package/tests/skills/trivia.test.ts +54 -0
  319. package/tests/skills/vector-search.test.ts +135 -0
  320. package/tests/skills/weather-api.test.ts +77 -0
  321. package/tests/skills/web-search-parity.test.ts +59 -0
  322. package/tests/skills/web-search.test.ts +103 -0
  323. package/tests/skills/wikipedia.test.ts +63 -0
  324. package/tsconfig.json +18 -0
  325. package/vitest.config.ts +9 -0
@@ -0,0 +1,27 @@
1
+ name: Publish Release
2
+ on:
3
+ push:
4
+ tags: ['v*']
5
+ workflow_dispatch:
6
+
7
+ jobs:
8
+ publish:
9
+ runs-on: ubuntu-latest
10
+ permissions:
11
+ contents: write
12
+ id-token: write
13
+ steps:
14
+ - uses: actions/checkout@v5
15
+ - uses: actions/setup-node@v4
16
+ with:
17
+ node-version: '22'
18
+ registry-url: 'https://registry.npmjs.org'
19
+ - run: npm ci
20
+ - run: npm test
21
+ - run: npm publish --access public
22
+ env:
23
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
24
+ - name: Create GitHub Release
25
+ uses: softprops/action-gh-release@v2
26
+ with:
27
+ generate_release_notes: true
@@ -0,0 +1,17 @@
1
+ name: Test
2
+ on:
3
+ pull_request:
4
+ push:
5
+ branches: [main]
6
+
7
+ jobs:
8
+ test:
9
+ runs-on: ubuntu-latest
10
+ steps:
11
+ - uses: actions/checkout@v5
12
+ - uses: actions/setup-node@v4
13
+ with:
14
+ node-version: '22'
15
+ cache: 'npm'
16
+ - run: npm ci
17
+ - run: npm test
package/CLAUDE.md ADDED
@@ -0,0 +1,112 @@
1
+ # CLAUDE.md
2
+
3
+ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+ ## Build & Test Commands
6
+
7
+ ```bash
8
+ npm run build # TypeScript compilation (tsc → dist/)
9
+ npm test # Run all tests (vitest)
10
+ npm test -- AgentBase # Run tests matching a filename
11
+ npm test -- -t "renders basic SWML" # Run tests matching a description
12
+ npm run test:watch # Continuous test mode
13
+ npm run dev # TypeScript watch + rebuild
14
+ ```
15
+
16
+ CLI tool for testing agents without a running server:
17
+ ```bash
18
+ npx tsx src/cli/swaig-test.ts examples/simple-agent.ts --dump-swml
19
+ npx tsx src/cli/swaig-test.ts examples/simple-agent.ts --list-tools
20
+ npx tsx src/cli/swaig-test.ts examples/simple-agent.ts --exec get_time
21
+ ```
22
+
23
+ ## Architecture
24
+
25
+ This SDK builds AI voice agents as HTTP microservices. Agents serve [SWML](https://developer.signalwire.com/sdks/reference/swml/methods/) documents (JSON call-flow instructions) and handle [SWAIG](https://developer.signalwire.com/sdks/reference/swml/methods/ai/swaig/) function callbacks from the SignalWire platform.
26
+
27
+ ### Core Flow
28
+
29
+ ```
30
+ SignalWire ──GET /──> AgentBase (returns SWML JSON)
31
+ SignalWire ──POST /swaig──> AgentBase (dispatches to tool handlers)
32
+ SignalWire ──POST /post_prompt──> AgentBase (receives call summary)
33
+ ```
34
+
35
+ ### Composition Architecture
36
+
37
+ `AgentBase` is the central class (~1100 lines). It uses **composition** (not inheritance) to assemble functionality from internal managers:
38
+
39
+ - **PromptManager** / **PomBuilder** — raw text or structured prompt rendering
40
+ - **SwmlBuilder** — assembles the 5-phase SWML document
41
+ - **SessionManager** — HMAC token generation/validation for secure tools
42
+ - **ContextBuilder** — multi-step conversation workflows (state machine)
43
+ - **SkillManager** — loads/unloads skill plugins that inject tools, prompts, and hints
44
+ - **Hono App** — HTTP server with basicAuth, CORS, security headers, rate limiting
45
+
46
+ This differs from the Python SDK which uses 8 mixins. The TS SDK composes everything inside AgentBase.
47
+
48
+ ### SWML 5-Phase Rendering
49
+
50
+ `renderSwml()` builds the call-flow document in phases:
51
+ 1. **Pre-answer** — verbs before picking up (e.g., play ringing)
52
+ 2. **Answer** — auto-answer verb (if enabled)
53
+ 3. **Post-answer** — verbs after answer, before AI (e.g., welcome message)
54
+ 4. **AI** — the AI block with prompt, tools, languages, params
55
+ 5. **Post-AI** — verbs after AI ends (e.g., hangup)
56
+
57
+ ### Key Classes
58
+
59
+ | Class | Purpose | Size |
60
+ |-------|---------|------|
61
+ | `AgentBase` | HTTP server, SWML rendering, tool dispatch, dynamic config | ~1100 lines |
62
+ | `FunctionResult` | Fluent response builder with 40+ call-control actions | ~900 lines |
63
+ | `ContextBuilder` | Multi-step workflows: Context → Step → GatherInfo | ~800 lines |
64
+ | `DataMap` | Server-side tools (webhooks + expressions, no server roundtrip) | ~400 lines |
65
+ | `SwaigFunction` | Wraps a tool handler with metadata for SWAIG serialization | ~100 lines |
66
+
67
+ ### Subclassing Pattern
68
+
69
+ Prefab agents and user agents extend `AgentBase` using three key hooks:
70
+
71
+ ```typescript
72
+ class MyAgent extends AgentBase {
73
+ static override PROMPT_SECTIONS = [/* declarative prompt sections */];
74
+ protected override defineTools(): void { /* register tools */ }
75
+ async onSummary(summary, rawData) { /* process call summary */ }
76
+ }
77
+ ```
78
+
79
+ `defineTools()` is called at the end of the `AgentBase` constructor. Subclasses override it to register their tools after all fields are initialized.
80
+
81
+ ### Builder Pattern
82
+
83
+ `FunctionResult`, `DataMap`, `ContextBuilder`, and `PomBuilder` all use fluent chaining (methods return `this`).
84
+
85
+ ## Code Conventions
86
+
87
+ - **ES Modules** throughout (`"type": "module"` in package.json, `.js` extensions in imports)
88
+ - **SWML output keys** use `snake_case` to match the Python SDK and platform expectations
89
+ - **TypeScript strict mode** enabled — no implicit any, strict null checks
90
+ - All public API surfaces have JSDoc comments
91
+ - Tests use vitest with globals enabled (no explicit imports of `describe`/`it`/`expect`)
92
+ - Test setup (`tests/setup.ts`) polyfills `globalThis.crypto` for Hono's basicAuth in Node
93
+
94
+ ## Key Environment Variables
95
+
96
+ | Variable | Purpose |
97
+ |----------|---------|
98
+ | `PORT` | HTTP server port (default 3000) |
99
+ | `SWML_BASIC_AUTH_USER` / `SWML_BASIC_AUTH_PASSWORD` | Auth credentials |
100
+ | `SWML_PROXY_URL_BASE` | Proxy/tunnel base URL for webhook URLs |
101
+ | `SIGNALWIRE_LOG_LEVEL` | debug, info, warn, error |
102
+ | `SIGNALWIRE_LOG_MODE` | Set to "off" to suppress all logging |
103
+
104
+ ## Project Layout
105
+
106
+ - `src/` — TypeScript source (compiled to `dist/`)
107
+ - `src/cli/` — CLI tool for offline agent testing (swaig-test)
108
+ - `src/skills/` — Skills framework + 18 built-in skills in `builtin/`
109
+ - `src/prefabs/` — 5 pre-built agent types (InfoGatherer, Survey, FAQ, Concierge, Receptionist)
110
+ - `tests/` — Vitest test files mirroring src/ structure
111
+ - `examples/` — Runnable example agents (`npx tsx examples/simple-agent.ts`)
112
+ - `docs/` — Comprehensive markdown documentation (12 guides + API reference)
package/README.md ADDED
@@ -0,0 +1,254 @@
1
+ <!-- Header -->
2
+ <div align="center">
3
+ <a href="https://signalwire.com" target="_blank">
4
+ <img src="https://github.com/user-attachments/assets/0c8ed3b9-8c50-4dc6-9cc4-cc6cd137fd50" width="500" />
5
+ </a>
6
+
7
+ # SignalWire SDK for TypeScript
8
+
9
+ _Build AI voice agents, control live calls over WebSocket, and manage every SignalWire resource over REST -- all from one package._
10
+
11
+ <p align="center">
12
+ <a href="https://developer.signalwire.com/sdks/agents-sdk" target="_blank">Documentation</a> &middot;
13
+ <a href="https://github.com/signalwire/signalwire-docs/issues/new/choose" target="_blank">Report an Issue</a> &middot;
14
+ <a href="https://www.npmjs.com/package/@signalwire/sdk" target="_blank">npm</a>
15
+ </p>
16
+
17
+ <a href="https://discord.com/invite/F2WNYTNjuF" target="_blank"><img src="https://img.shields.io/badge/Discord%20Community-5865F2" alt="Discord" /></a>
18
+ <a href="LICENSE"><img src="https://img.shields.io/badge/MIT-License-blue" alt="MIT License" /></a>
19
+ <a href="https://github.com/signalwire/signalwire-typescript" target="_blank"><img src="https://img.shields.io/github/stars/signalwire/signalwire-typescript" alt="GitHub Stars" /></a>
20
+
21
+ </div>
22
+
23
+ ---
24
+
25
+ ## What's in this SDK
26
+
27
+ | Capability | What it does | Quick link |
28
+ |-----------|-------------|------------|
29
+ | **AI Agents** | Build voice agents that handle calls autonomously -- the platform runs the AI pipeline, your code defines the persona, tools, and call flow | [Agent Guide](#ai-agents) |
30
+ | **RELAY Client** | Control live calls and SMS/MMS in real time over WebSocket -- answer, play, record, collect DTMF, conference, transfer, and more | [RELAY docs](relay/README.md) |
31
+ | **REST Client** | Manage SignalWire resources over HTTP -- phone numbers, SIP endpoints, Fabric AI agents, video rooms, messaging, and 17+ API namespaces | [REST docs](rest/README.md) |
32
+
33
+ ```bash
34
+ npm install @signalwire/sdk
35
+ ```
36
+
37
+ ---
38
+
39
+ ## AI Agents
40
+
41
+ Each agent is a self-contained microservice that generates [SWML](docs/swml_service_guide.md) (SignalWire Markup Language) and handles [SWAIG](docs/swaig-reference.md) (SignalWire AI Gateway) tool calls. The SignalWire platform runs the entire AI pipeline (STT, LLM, TTS) -- your agent just defines the behavior.
42
+
43
+ ```typescript
44
+ import { AgentBase, FunctionResult } from '@signalwire/sdk';
45
+
46
+ const agent = new AgentBase({
47
+ name: 'my-agent',
48
+ route: '/agent',
49
+ });
50
+
51
+ agent.addLanguage({ name: 'English', code: 'en-US', voice: 'inworld.Mark' });
52
+ agent.promptAddSection('Role', { body: 'You are a helpful assistant.' });
53
+
54
+ agent.defineTool({
55
+ name: 'get_time',
56
+ description: 'Get the current time',
57
+ parameters: {},
58
+ handler: () => new FunctionResult(`The time is ${new Date().toLocaleTimeString()}`),
59
+ });
60
+
61
+ agent.run(); // Starts HTTP server on port 3000
62
+ ```
63
+
64
+ Test locally without running a server:
65
+
66
+ ```bash
67
+ swaig-test examples/simple-agent.ts --list-tools
68
+ swaig-test examples/simple-agent.ts --dump-swml
69
+ swaig-test examples/simple-agent.ts --exec get_time
70
+ ```
71
+
72
+ ### Agent Features
73
+
74
+ - **Prompt Object Model (POM)** -- structured prompt composition via `promptAddSection()`
75
+ - **SWAIG tools** -- define functions with `defineTool()` that the AI calls mid-conversation, with native access to the call's media stack
76
+ - **Skills system** -- add capabilities with one-liners: `agent.addSkill('datetime')`
77
+ - **Contexts and steps** -- structured multi-step workflows with navigation control
78
+ - **DataMap tools** -- tools that execute on SignalWire's servers, calling REST APIs without your own webhook
79
+ - **Dynamic configuration** -- per-request agent customization for multi-tenant deployments
80
+ - **Call flow control** -- pre-answer, post-answer, and post-AI verb insertion
81
+ - **Prefab agents** -- ready-to-use archetypes (InfoGatherer, Survey, FAQ, Receptionist, Concierge)
82
+ - **Multi-agent hosting** -- serve multiple agents on a single server with `AgentServer`
83
+ - **SIP routing** -- route SIP calls to agents based on usernames
84
+ - **Session state** -- persistent conversation state with global data and post-prompt summaries
85
+ - **Security** -- auto-generated basic auth, function-specific HMAC tokens, SSL support
86
+ - **Serverless** -- auto-detects Lambda, CGI, Google Cloud Functions, Azure Functions
87
+
88
+ ### Agent Examples
89
+
90
+ The [`examples/`](examples/) directory contains 35+ working examples:
91
+
92
+ | Example | What it demonstrates |
93
+ |---------|---------------------|
94
+ | [simple-agent.ts](examples/simple-agent.ts) | POM prompts, SWAIG tools, multilingual support, LLM tuning |
95
+ | [contexts-steps.ts](examples/contexts-steps.ts) | Multi-step workflow with context switching and step navigation |
96
+ | [datamap-tools.ts](examples/datamap-tools.ts) | Server-side API tools without webhooks |
97
+ | [skills-demo.ts](examples/skills-demo.ts) | Loading built-in skills (datetime, math) |
98
+ | [call-flow.ts](examples/call-flow.ts) | Call flow verbs, debug events, FunctionResult actions |
99
+ | [session-state.ts](examples/session-state.ts) | onSummary, global data, post-prompt summaries |
100
+ | [multi-agent.ts](examples/multi-agent.ts) | Multiple agents on one server |
101
+ | [serverless-lambda.ts](examples/serverless-lambda.ts) | AWS Lambda deployment |
102
+ | [dynamic-config.ts](examples/dynamic-config.ts) | Per-request dynamic configuration, multi-tenant routing |
103
+
104
+ ---
105
+
106
+ ## RELAY Client
107
+
108
+ Real-time call control and messaging over WebSocket. The RELAY client connects to SignalWire via the Blade protocol and gives you imperative, async control over live phone calls and SMS/MMS.
109
+
110
+ ```typescript
111
+ import { RelayClient, Call } from '@signalwire/sdk';
112
+
113
+ const client = new RelayClient({
114
+ contexts: ['default'],
115
+ });
116
+
117
+ client.onCall(async (call: Call) => {
118
+ await call.answer();
119
+ const action = await call.play([
120
+ { type: 'tts', text: 'Welcome to SignalWire!' },
121
+ ]);
122
+ await action.wait();
123
+ await call.hangup();
124
+ });
125
+
126
+ client.run();
127
+ ```
128
+
129
+ - 40+ calling methods (play, record, collect, detect, tap, stream, AI, conferencing, and more)
130
+ - SMS/MMS messaging with delivery tracking
131
+ - Action objects with `wait()`, `stop()`, `pause()`, `resume()`
132
+ - Auto-reconnect with exponential backoff
133
+
134
+ See the **[RELAY documentation](relay/README.md)** for the full guide, API reference, and examples.
135
+
136
+ ---
137
+
138
+ ## REST Client
139
+
140
+ Typed HTTP client for managing SignalWire resources and controlling calls over HTTP. No WebSocket required -- just standard `fetch` requests.
141
+
142
+ ```typescript
143
+ import { RestClient } from '@signalwire/sdk';
144
+
145
+ const client = new RestClient({
146
+ project: '...',
147
+ token: '...',
148
+ host: 'example.signalwire.com',
149
+ });
150
+
151
+ await client.fabric.aiAgents.create({ name: 'Support Bot', prompt: { text: 'You are helpful.' } });
152
+ await client.calling.play(callId, { play: [{ type: 'tts', text: 'Hello!' }] });
153
+ await client.phoneNumbers.search({ area_code: '512' });
154
+ await client.datasphere.documents.search({ query_string: 'billing policy' });
155
+ ```
156
+
157
+ - 17 namespaced API surfaces: Fabric (17 resource types), Calling (37 commands), Video, Datasphere, Compat (Twilio-compatible), Phone Numbers, SIP, Queues, Recordings, and more
158
+ - Zero dependencies -- uses built-in `fetch` (Node 18+)
159
+ - Dict returns -- raw JSON, no wrapper objects
160
+
161
+ See the **[REST documentation](rest/README.md)** for the full guide, API reference, and examples.
162
+
163
+ ---
164
+
165
+ ## Installation
166
+
167
+ ```bash
168
+ # Core SDK (agents, RELAY, REST)
169
+ npm install @signalwire/sdk
170
+ ```
171
+
172
+ Requires Node.js >= 18.
173
+
174
+ ## Documentation
175
+
176
+ Full reference documentation is available at **[developer.signalwire.com/sdks/agents-sdk](https://developer.signalwire.com/sdks/agents-sdk)**.
177
+
178
+ Guides are also available in the [`docs/`](docs/) directory:
179
+
180
+ ### Getting Started
181
+
182
+ - [Agent Guide](docs/agent-guide.md) -- creating agents, prompt configuration, dynamic setup
183
+ - [Architecture](docs/architecture.md) -- SDK architecture and core concepts
184
+ - [SDK Features](docs/sdk_features.md) -- feature overview, SDK vs raw SWML comparison
185
+
186
+ ### Core Features
187
+
188
+ - [SWAIG Reference](docs/swaig-reference.md) -- function results, actions, post_data lifecycle
189
+ - [Contexts and Steps](docs/contexts-guide.md) -- structured workflows, navigation, gather mode
190
+ - [DataMap Guide](docs/datamap-guide.md) -- serverless API tools without webhooks
191
+ - [LLM Parameters](docs/llm_parameters.md) -- temperature, top_p, barge confidence tuning
192
+ - [SWML Service Guide](docs/swml_service_guide.md) -- low-level construction of SWML documents
193
+
194
+ ### Skills and Extensions
195
+
196
+ - [Skills System](docs/skills-guide.md) -- built-in skills and the modular framework
197
+ - [Third-Party Skills](docs/third_party_skills.md) -- creating and publishing custom skills
198
+ - [MCP Gateway](docs/mcp_gateway_reference.md) -- Model Context Protocol integration
199
+ - [MCP Integration](docs/mcp_integration.md) -- MCP agent setup and configuration
200
+
201
+ ### Deployment
202
+
203
+ - [CLI Guide](docs/cli-guide.md) -- `swaig-test` command reference
204
+ - [Cloud Functions](docs/cloud_functions_guide.md) -- Lambda, Cloud Functions, Azure deployment
205
+ - [Serverless Guide](docs/serverless-guide.md) -- deploy to AWS Lambda, Google Cloud Functions, Azure Functions, CGI
206
+ - [Configuration](docs/configuration.md) -- environment variables, SSL, proxy setup
207
+ - [Security](docs/security.md) -- authentication and security model
208
+
209
+ ### Reference
210
+
211
+ - [API Reference](docs/api-reference.md) -- complete class and method reference
212
+ - [Web Service](docs/web_service.md) -- HTTP server and endpoint details
213
+ - [Skills Parameter Schema](docs/skills_parameter_schema.md) -- skill parameter definitions
214
+ - [Prefabs Guide](docs/prefabs-guide.md) -- pre-built agents: InfoGatherer, Survey, FAQ, Concierge, Receptionist
215
+ - [Migration Guide](docs/MIGRATION-2.0.md) -- upgrading to SDK 2.0
216
+
217
+ ## Environment Variables
218
+
219
+ | Variable | Used by | Description |
220
+ |----------|---------|-------------|
221
+ | `SIGNALWIRE_PROJECT_ID` | RELAY, REST | Project identifier |
222
+ | `SIGNALWIRE_API_TOKEN` | RELAY, REST | API token |
223
+ | `SIGNALWIRE_SPACE` | RELAY, REST | Space hostname (e.g. `example.signalwire.com`) |
224
+ | `SWML_BASIC_AUTH_USER` | Agents | Basic auth username (default: auto-generated) |
225
+ | `SWML_BASIC_AUTH_PASSWORD` | Agents | Basic auth password (default: auto-generated) |
226
+ | `SWML_PROXY_URL_BASE` | Agents | Base URL when behind a reverse proxy |
227
+ | `SWML_SSL_ENABLED` | Agents | Enable HTTPS (`true`, `1`, `yes`) |
228
+ | `SWML_SSL_CERT_PATH` | Agents | Path to SSL certificate |
229
+ | `SWML_SSL_KEY_PATH` | Agents | Path to SSL private key |
230
+ | `SIGNALWIRE_LOG_LEVEL` | All | Logging level (`debug`, `info`, `warn`, `error`) |
231
+ | `SIGNALWIRE_LOG_MODE` | All | Set to `off` to suppress all logging |
232
+
233
+ ## Testing
234
+
235
+ ```bash
236
+ # Install dependencies
237
+ npm install
238
+
239
+ # Run the test suite
240
+ npm test
241
+
242
+ # Watch mode
243
+ npm run test:watch
244
+
245
+ # Build
246
+ npm run build
247
+
248
+ # Dev mode (watch + rebuild)
249
+ npm run dev
250
+ ```
251
+
252
+ ## License
253
+
254
+ MIT -- see [LICENSE](LICENSE) for details.
@@ -0,0 +1,81 @@
1
+ # Migrating to SignalWire SDK 2.0
2
+
3
+ ## Package Rename
4
+
5
+ ```bash
6
+ # Before
7
+ npm install signalwire-agents
8
+
9
+ # After
10
+ npm install @signalwire/sdk
11
+ ```
12
+
13
+ Update your `package.json`:
14
+ ```jsonc
15
+ // Before
16
+ "dependencies": {
17
+ "signalwire-agents": "^1.0.0"
18
+ }
19
+
20
+ // After
21
+ "dependencies": {
22
+ "@signalwire/sdk": "^2.0.0"
23
+ }
24
+ ```
25
+
26
+ ## Import Changes
27
+
28
+ ```typescript
29
+ // Before
30
+ import { AgentBase, SwaigFunctionResult } from 'signalwire-agents';
31
+ import { SignalWireClient } from 'signalwire-agents/rest';
32
+
33
+ const client = new SignalWireClient(projectId, token, spaceUrl);
34
+ const result = new SwaigFunctionResult('Done');
35
+
36
+ // After
37
+ import { AgentBase, FunctionResult } from '@signalwire/sdk';
38
+ import { RestClient } from '@signalwire/sdk/rest';
39
+
40
+ const client = new RestClient(projectId, token, spaceUrl);
41
+ const result = new FunctionResult('Done');
42
+ ```
43
+
44
+ ## Class Renames
45
+
46
+ | Before | After |
47
+ |--------|-------|
48
+ | `SwaigFunctionResult` | `FunctionResult` |
49
+ | `SignalWireClient` | `RestClient` |
50
+
51
+ ## Quick Migration
52
+
53
+ Find and replace in your project:
54
+ ```bash
55
+ # Update package imports
56
+ find . -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' | \
57
+ xargs sed -i "s/from 'signalwire-agents/from '@signalwire\/sdk/g"
58
+
59
+ # Also handle double-quote imports
60
+ find . -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' | \
61
+ xargs sed -i 's/from "signalwire-agents/from "@signalwire\/sdk/g'
62
+
63
+ # Rename classes
64
+ find . -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' | \
65
+ xargs sed -i 's/SwaigFunctionResult/FunctionResult/g'
66
+ find . -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' | \
67
+ xargs sed -i 's/SignalWireClient/RestClient/g'
68
+
69
+ # Update package.json
70
+ sed -i 's/"signalwire-agents"/"@signalwire\/sdk"/g' package.json
71
+ npm install
72
+ ```
73
+
74
+ ## What Didn't Change
75
+
76
+ - All method names (setPromptText, defineTool, addSkill, etc.)
77
+ - All parameter shapes and types
78
+ - SWML output format
79
+ - RELAY protocol
80
+ - REST API paths
81
+ - Skills, contexts, DataMap -- all the same