@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,474 @@
1
+ # Call Methods Reference
2
+
3
+ A `Call` object represents a live phone call. You get one from `@client.on_call` (inbound) or `client.dial()` (outbound).
4
+
5
+ ## Properties
6
+
7
+ | Property | Type | Description |
8
+ |----------|------|-------------|
9
+ | `call_id` | `str` | Unique call identifier |
10
+ | `node_id` | `str` | Server node handling the call |
11
+ | `state` | `str` | Current state: `created`, `ringing`, `answered`, `ending`, `ended` |
12
+ | `direction` | `str` | `inbound` or `outbound` |
13
+ | `tag` | `str` | Correlation tag |
14
+ | `device` | `dict` | Device info (type, params) |
15
+ | `segment_id` | `str` | Segment identifier |
16
+
17
+ ## Actions: Blocking vs Fire-and-Forget
18
+
19
+ Methods like `play()`, `record()`, `detect()`, etc. return **Action** objects. The `await call.play(...)` itself only waits for the server to accept the command — the actual operation runs asynchronously on the server. You choose how to handle completion:
20
+
21
+ ### Wait inline (blocking)
22
+
23
+ ```python
24
+ action = await call.play([{"type": "tts", "params": {"text": "Hello"}}])
25
+ await action.wait() # blocks until playback finishes
26
+ # execution continues only after play is done
27
+ ```
28
+
29
+ ### Fire and forget (background)
30
+
31
+ ```python
32
+ action = await call.play([{"type": "tts", "params": {"text": "Hello"}}])
33
+ # don't call action.wait() — continue immediately while audio plays
34
+ await call.send_digits("1234")
35
+
36
+ # check later if needed
37
+ if action.is_done:
38
+ print(f"Play result: {action.result}")
39
+ ```
40
+
41
+ ### Fire with callback
42
+
43
+ ```python
44
+ # Sync callback
45
+ action = await call.play(
46
+ [{"type": "tts", "params": {"text": "Hello"}}],
47
+ on_completed=lambda event: print(f"Done: {event.params}"),
48
+ )
49
+ # continues immediately; callback fires when playback finishes
50
+
51
+ # Async callback
52
+ async def on_recording_done(event):
53
+ print(f"Recording URL: {event.params.get('url')}")
54
+ await call.hangup()
55
+
56
+ action = await call.record(on_completed=on_recording_done)
57
+ ```
58
+
59
+ The `on_completed` callback is available on all action-based methods: `play`, `record`, `play_and_collect`, `collect`, `detect`, `pay`, `send_fax`, `receive_fax`, `tap`, `stream`, `transcribe`, and `ai`. It accepts both sync and async functions. Errors in callbacks are caught and logged, never crash the event loop. The callback also fires when the call is gone (404/410).
60
+
61
+ ### Action methods summary
62
+
63
+ | Method | Returns |
64
+ |--------|---------|
65
+ | `action.wait(timeout=None)` | Blocks until the action completes, returns the terminal `RelayEvent` |
66
+ | `action.is_done` | `True` if the action has completed |
67
+ | `action.result` | The terminal `RelayEvent` (or `None` if not done) |
68
+ | `action.completed` | `True` if the action reached a terminal state |
69
+ | `action.stop()` | Stop the operation on the server |
70
+
71
+ Some actions also have `pause()`, `resume()`, and `volume()`.
72
+
73
+ ## Lifecycle
74
+
75
+ ### `answer(**kwargs) -> dict`
76
+
77
+ Answer an inbound call.
78
+
79
+ ```python
80
+ await call.answer()
81
+ ```
82
+
83
+ ### `hangup(reason="hangup") -> dict`
84
+
85
+ End the call.
86
+
87
+ ```python
88
+ await call.hangup()
89
+ await call.hangup(reason="busy")
90
+ ```
91
+
92
+ ### `pass_() -> dict`
93
+
94
+ Decline control, returning the call to routing.
95
+
96
+ ```python
97
+ await call.pass_()
98
+ ```
99
+
100
+ ## Audio Playback
101
+
102
+ ### `play(media, *, volume=None, direction=None, loop=None, control_id=None) -> PlayAction`
103
+
104
+ Play audio. Returns a `PlayAction` with `stop()`, `pause()`, `resume()`, `volume()`, and `wait()`.
105
+
106
+ ```python
107
+ # TTS
108
+ action = await call.play([{"type": "tts", "params": {"text": "Hello!"}}])
109
+ await action.wait()
110
+
111
+ # Audio file
112
+ action = await call.play([{"type": "audio", "params": {"url": "https://example.com/sound.mp3"}}])
113
+
114
+ # Silence
115
+ action = await call.play([{"type": "silence", "params": {"duration": 2}}])
116
+
117
+ # Ringtone
118
+ action = await call.play([{"type": "ringtone", "params": {"name": "us"}}])
119
+
120
+ # Control playback
121
+ await action.pause()
122
+ await action.resume()
123
+ await action.volume(-3.0)
124
+ await action.stop()
125
+ ```
126
+
127
+ ## Recording
128
+
129
+ ### `record(audio=None, *, control_id=None) -> RecordAction`
130
+
131
+ Record the call. Returns a `RecordAction` with `stop()`, `pause()`, `resume()`, and `wait()`.
132
+
133
+ ```python
134
+ action = await call.record(audio={"format": "wav", "stereo": True, "direction": "both"})
135
+ # ... later ...
136
+ await action.stop()
137
+ event = await action.wait()
138
+ print(f"Recording URL: {event.params.get('url')}")
139
+ ```
140
+
141
+ ## Input Collection
142
+
143
+ ### `play_and_collect(media, collect, *, volume=None, control_id=None) -> CollectAction`
144
+
145
+ Play audio and collect DTMF or speech input. Returns a `CollectAction`.
146
+
147
+ ```python
148
+ action = await call.play_and_collect(
149
+ [{"type": "tts", "params": {"text": "Press 1 for sales, 2 for support."}}],
150
+ {"digits": {"max": 1, "digit_timeout": 5.0}},
151
+ )
152
+ event = await action.wait()
153
+ digit = event.params.get("result", {}).get("params", {}).get("digits", "")
154
+ ```
155
+
156
+ ### `collect(*, digits=None, speech=None, ..., control_id=None) -> StandaloneCollectAction`
157
+
158
+ Collect input without playing audio.
159
+
160
+ ```python
161
+ action = await call.collect(
162
+ digits={"max": 4, "terminators": "#"},
163
+ speech={"language": "en-US"},
164
+ partial_results=True,
165
+ )
166
+ event = await action.wait()
167
+ ```
168
+
169
+ ## Bridging
170
+
171
+ ### `connect(devices, *, ringback=None, tag=None, max_duration=None, max_price_per_minute=None, status_url=None) -> dict`
172
+
173
+ Bridge the call to another destination.
174
+
175
+ ```python
176
+ await call.connect(
177
+ [[{"type": "phone", "params": {"to_number": "+15551234567", "from_number": "+15559876543"}}]],
178
+ ringback=[{"type": "ringtone", "params": {"name": "us"}}],
179
+ )
180
+ ```
181
+
182
+ ### `disconnect() -> dict`
183
+
184
+ Unbridge a connected call.
185
+
186
+ ```python
187
+ await call.disconnect()
188
+ ```
189
+
190
+ ## DTMF
191
+
192
+ ### `send_digits(digits, *, control_id=None) -> dict`
193
+
194
+ Send DTMF tones.
195
+
196
+ ```python
197
+ await call.send_digits("1234#")
198
+ ```
199
+
200
+ ## Detection
201
+
202
+ ### `detect(detect, *, timeout=None, control_id=None) -> DetectAction`
203
+
204
+ Detect machine, fax, or digits.
205
+
206
+ ```python
207
+ action = await call.detect({"type": "machine"}, timeout=30.0)
208
+ event = await action.wait()
209
+ ```
210
+
211
+ ## SIP Refer
212
+
213
+ ### `refer(device, *, status_url=None) -> dict`
214
+
215
+ Transfer via SIP REFER.
216
+
217
+ ```python
218
+ await call.refer({"type": "sip", "params": {"to": "sip:user@example.com"}})
219
+ ```
220
+
221
+ ## Transfer
222
+
223
+ ### `transfer(dest) -> dict`
224
+
225
+ Transfer call control to another RELAY app or SWML script.
226
+
227
+ ```python
228
+ await call.transfer("https://example.com/swml-endpoint")
229
+ ```
230
+
231
+ ## Fax
232
+
233
+ ### `send_fax(document, *, identity=None, header_info=None, control_id=None) -> FaxAction`
234
+
235
+ ```python
236
+ action = await call.send_fax("https://example.com/document.pdf", identity="+15551234567")
237
+ event = await action.wait()
238
+ ```
239
+
240
+ ### `receive_fax(*, control_id=None) -> FaxAction`
241
+
242
+ ```python
243
+ action = await call.receive_fax()
244
+ event = await action.wait()
245
+ ```
246
+
247
+ ## Tap (Media Interception)
248
+
249
+ ### `tap(tap, device, *, control_id=None) -> TapAction`
250
+
251
+ Intercept call media and stream to an RTP endpoint.
252
+
253
+ ```python
254
+ action = await call.tap(
255
+ {"type": "audio", "params": {"direction": "both"}},
256
+ {"type": "rtp", "params": {"addr": "192.168.1.100", "port": 5000}},
257
+ )
258
+ ```
259
+
260
+ ## Streaming
261
+
262
+ ### `stream(url, *, name=None, codec=None, track=None, control_id=None, ...) -> StreamAction`
263
+
264
+ Stream call audio to a WebSocket endpoint.
265
+
266
+ ```python
267
+ action = await call.stream(
268
+ "wss://example.com/audio",
269
+ name="my_stream",
270
+ codec="PCMU",
271
+ track="inbound_track",
272
+ )
273
+ # Stop streaming
274
+ await action.stop()
275
+ ```
276
+
277
+ ## Payment
278
+
279
+ ### `pay(payment_connector_url, *, control_id=None, charge_amount=None, currency=None, ...) -> PayAction`
280
+
281
+ Collect a payment via DTMF.
282
+
283
+ ```python
284
+ action = await call.pay(
285
+ "https://pay.example.com",
286
+ charge_amount="25.99",
287
+ currency="usd",
288
+ input_method="dtmf",
289
+ )
290
+ event = await action.wait()
291
+ ```
292
+
293
+ ## Conference
294
+
295
+ ### `join_conference(name, *, muted=None, beep=None, max_participants=None, record=None, ...) -> dict`
296
+
297
+ ```python
298
+ await call.join_conference("my_conference", muted=False, beep="onEnter")
299
+ ```
300
+
301
+ ### `leave_conference(conference_id) -> dict`
302
+
303
+ ```python
304
+ await call.leave_conference("conf-123")
305
+ ```
306
+
307
+ ## Hold
308
+
309
+ ### `hold() -> dict` / `unhold() -> dict`
310
+
311
+ ```python
312
+ await call.hold()
313
+ # ... later ...
314
+ await call.unhold()
315
+ ```
316
+
317
+ ## Denoise
318
+
319
+ ### `denoise() -> dict` / `denoise_stop() -> dict`
320
+
321
+ ```python
322
+ await call.denoise()
323
+ # ... later ...
324
+ await call.denoise_stop()
325
+ ```
326
+
327
+ ## Transcription
328
+
329
+ ### `transcribe(*, control_id=None, status_url=None) -> TranscribeAction`
330
+
331
+ ```python
332
+ action = await call.transcribe(status_url="https://example.com/transcription")
333
+ # ... later ...
334
+ await action.stop()
335
+ ```
336
+
337
+ ## Live Transcribe / Translate
338
+
339
+ ### `live_transcribe(action_obj) -> dict`
340
+
341
+ ```python
342
+ await call.live_transcribe({"start": {"language": "en-US"}})
343
+ ```
344
+
345
+ ### `live_translate(action_obj, *, status_url=None) -> dict`
346
+
347
+ ```python
348
+ await call.live_translate({"start": {"source": "en-US", "target": "es"}})
349
+ ```
350
+
351
+ ## Echo
352
+
353
+ ### `echo(*, timeout=None, status_url=None) -> dict`
354
+
355
+ Echo audio back to the caller (useful for testing).
356
+
357
+ ```python
358
+ await call.echo(timeout=30.0)
359
+ ```
360
+
361
+ ## AI Agent
362
+
363
+ ### `ai(*, control_id=None, prompt=None, SWAIG=None, ai_params=None, ...) -> AIAction`
364
+
365
+ Start an AI agent session on the call.
366
+
367
+ ```python
368
+ action = await call.ai(
369
+ prompt={"text": "You are a helpful support agent."},
370
+ SWAIG={"functions": [...]},
371
+ ai_params={"end_of_speech_timeout": 3000},
372
+ )
373
+ event = await action.wait()
374
+ ```
375
+
376
+ ### `amazon_bedrock(*, prompt=None, SWAIG=None, ...) -> dict`
377
+
378
+ Connect to an Amazon Bedrock AI agent.
379
+
380
+ ### `ai_message(*, message_text=None, role=None, ...) -> dict`
381
+
382
+ Send a message to an active AI session.
383
+
384
+ ### `ai_hold(*, timeout=None, prompt=None) -> dict` / `ai_unhold(*, prompt=None) -> dict`
385
+
386
+ Put an AI session on/off hold.
387
+
388
+ ## Rooms
389
+
390
+ ### `join_room(name, *, status_url=None) -> dict`
391
+
392
+ ```python
393
+ await call.join_room("my_room")
394
+ ```
395
+
396
+ ### `leave_room() -> dict`
397
+
398
+ ```python
399
+ await call.leave_room()
400
+ ```
401
+
402
+ ## Queue
403
+
404
+ ### `queue_enter(queue_name, *, control_id=None, status_url=None) -> dict`
405
+
406
+ ```python
407
+ await call.queue_enter("support")
408
+ ```
409
+
410
+ ### `queue_leave(queue_name, *, control_id=None, queue_id=None, status_url=None) -> dict`
411
+
412
+ ```python
413
+ await call.queue_leave("support", queue_id="q-123")
414
+ ```
415
+
416
+ ## Digit Bindings
417
+
418
+ ### `bind_digit(digits, bind_method, *, bind_params=None, realm=None, max_triggers=None) -> dict`
419
+
420
+ Bind a DTMF sequence to trigger a RELAY method.
421
+
422
+ ```python
423
+ await call.bind_digit(
424
+ "*1",
425
+ "calling.play",
426
+ bind_params={"play": [{"type": "tts", "params": {"text": "You pressed star-1"}}]},
427
+ )
428
+ ```
429
+
430
+ ### `clear_digit_bindings(*, realm=None) -> dict`
431
+
432
+ ```python
433
+ await call.clear_digit_bindings()
434
+ ```
435
+
436
+ ## User Events
437
+
438
+ ### `user_event(*, event=None, **kwargs) -> dict`
439
+
440
+ Send a custom event.
441
+
442
+ ```python
443
+ await call.user_event(event="order_placed", order_id="12345")
444
+ ```
445
+
446
+ ## Event Handling
447
+
448
+ ### `on(event_type, handler)`
449
+
450
+ Register an event listener on this call.
451
+
452
+ ```python
453
+ def on_play(event):
454
+ print(f"Play state: {event.params.get('state')}")
455
+
456
+ call.on("calling.call.play", on_play)
457
+ ```
458
+
459
+ ### `wait_for(event_type, predicate=None, timeout=None) -> RelayEvent`
460
+
461
+ Wait for a specific event.
462
+
463
+ ```python
464
+ event = await call.wait_for("calling.call.play", timeout=30.0)
465
+ ```
466
+
467
+ ### `wait_for_ended(timeout=None) -> RelayEvent`
468
+
469
+ Wait for the call to end.
470
+
471
+ ```python
472
+ event = await call.wait_for_ended()
473
+ print(f"End reason: {event.params.get('end_reason')}")
474
+ ```
@@ -0,0 +1,142 @@
1
+ # RelayClient Reference
2
+
3
+ ## Constructor
4
+
5
+ ```python
6
+ RelayClient(
7
+ project: str = None, # SIGNALWIRE_PROJECT_ID
8
+ token: str = None, # SIGNALWIRE_API_TOKEN
9
+ jwt_token: str = None, # SIGNALWIRE_JWT_TOKEN
10
+ host: str = None, # SIGNALWIRE_SPACE (default: relay.signalwire.com)
11
+ contexts: list[str] = None, # Topics to subscribe to
12
+ max_active_calls: int = None, # RELAY_MAX_ACTIVE_CALLS (default: 1000)
13
+ )
14
+ ```
15
+
16
+ Authentication requires either `project` + `token` (legacy) or `jwt_token` (faster, no server roundtrip). All parameters fall back to their corresponding environment variables.
17
+
18
+ ## Methods
19
+
20
+ ### `run()`
21
+
22
+ Blocking entry point. Connects, authenticates, and runs the event loop with auto-reconnect until interrupted.
23
+
24
+ ```python
25
+ client.run()
26
+ ```
27
+
28
+ ### `connect()` / `disconnect()`
29
+
30
+ Manual lifecycle control for use in async code.
31
+
32
+ ```python
33
+ await client.connect()
34
+ # ... use client ...
35
+ await client.disconnect()
36
+ ```
37
+
38
+ Also supports async context manager:
39
+
40
+ ```python
41
+ async with RelayClient(contexts=["default"]) as client:
42
+ ...
43
+ ```
44
+
45
+ ### `on_call(handler)`
46
+
47
+ Decorator to register the inbound call handler. The handler receives a `Call` object.
48
+
49
+ ```python
50
+ @client.on_call
51
+ async def handle(call):
52
+ await call.answer()
53
+ ```
54
+
55
+ ### `dial(devices, *, tag=None, max_duration=None, dial_timeout=None) -> Call`
56
+
57
+ Place an outbound call. Returns a `Call` once the remote party answers.
58
+
59
+ - `devices` -- nested list of device objects (serial/parallel dial)
60
+ - `tag` -- optional correlation tag (auto-generated if omitted)
61
+ - `max_duration` -- max call duration in minutes
62
+ - `dial_timeout` -- seconds to wait before raising `TimeoutError` (default: 120)
63
+
64
+ ```python
65
+ call = await client.dial([
66
+ [{"type": "phone", "params": {"to_number": "+15551234567", "from_number": "+15559876543"}}]
67
+ ])
68
+ ```
69
+
70
+ ### `on_message(handler)`
71
+
72
+ Decorator to register the inbound message handler. The handler receives a `Message` object.
73
+
74
+ ```python
75
+ @client.on_message
76
+ async def handle(message):
77
+ print(f"SMS from {message.from_number}: {message.body}")
78
+ ```
79
+
80
+ ### `send_message(*, to_number, from_number, body=None, media=None, ...) -> Message`
81
+
82
+ Send an outbound SMS/MMS. Returns a `Message` that tracks delivery state.
83
+
84
+ ```python
85
+ message = await client.send_message(
86
+ to_number="+15552222222",
87
+ from_number="+15551111111",
88
+ body="Hello!",
89
+ )
90
+ event = await message.wait() # block until delivered/failed
91
+ ```
92
+
93
+ See [Messaging](messaging.md) for full details.
94
+
95
+ ### `execute(method, params) -> dict`
96
+
97
+ Send a raw JSON-RPC request. Used internally by Call methods, but available for custom commands.
98
+
99
+ ### `receive(contexts) / unreceive(contexts)`
100
+
101
+ Dynamically subscribe to or unsubscribe from contexts after connecting.
102
+
103
+ ```python
104
+ await client.receive(["new-context"])
105
+ await client.unreceive(["old-context"])
106
+ ```
107
+
108
+ ## Properties
109
+
110
+ | Property | Type | Description |
111
+ |----------|------|-------------|
112
+ | `relay_protocol` | `str` | Server-assigned protocol string from connect response |
113
+ | `project` | `str` | Project ID |
114
+ | `host` | `str` | Relay host |
115
+ | `contexts` | `list[str]` | Initial contexts |
116
+
117
+ ## Connection Behavior
118
+
119
+ - **Auto-reconnect**: On connection loss, the client reconnects with exponential backoff (1s to 30s).
120
+ - **Ping/pong**: Client sends periodic pings and monitors server pings. After 3 consecutive failures, the connection is force-closed and reconnected.
121
+ - **Request queueing**: Requests made while disconnected are queued and sent after re-authentication.
122
+ - **Authorization state**: The server sends encrypted auth state via events. On reconnect, this is sent back for fast re-authentication without a full auth roundtrip.
123
+ - **Server disconnect**: The server can request a graceful disconnect (e.g. during deployment). The client auto-reconnects afterward.
124
+
125
+ ## Concurrency
126
+
127
+ Each inbound call handler runs as an independent `asyncio.Task`, so multiple calls are handled concurrently. The `max_active_calls` parameter (default: 1000) caps concurrent calls to prevent unbounded memory growth.
128
+
129
+ For multiple WebSocket connections in one process, set `RELAY_MAX_CONNECTIONS` (default: 1).
130
+
131
+ ## Error Handling
132
+
133
+ ```python
134
+ from signalwire_agents.relay import RelayError
135
+
136
+ try:
137
+ await call.play([...])
138
+ except RelayError as e:
139
+ print(f"Error {e.code}: {e.message}")
140
+ ```
141
+
142
+ `RelayError` is raised when the server returns a non-2xx response code. Errors 404 and 410 (call gone) are silently swallowed by Call methods since the call no longer exists.