@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,132 @@
1
+ /**
2
+ * Protocol constants for the SignalWire RELAY calling API.
3
+ */
4
+
5
+ // Protocol version
6
+ export const PROTOCOL_VERSION = { major: 2, minor: 0, revision: 0 };
7
+ export const AGENT_STRING = '@signalwire/sdk-typescript/2.0';
8
+
9
+ // JSON-RPC methods
10
+ export const METHOD_SIGNALWIRE_CONNECT = 'signalwire.connect';
11
+ export const METHOD_SIGNALWIRE_EVENT = 'signalwire.event';
12
+ export const METHOD_SIGNALWIRE_PING = 'signalwire.ping';
13
+ export const METHOD_SIGNALWIRE_DISCONNECT = 'signalwire.disconnect';
14
+ export const METHOD_SIGNALWIRE_RECEIVE = 'signalwire.receive';
15
+ export const METHOD_SIGNALWIRE_UNRECEIVE = 'signalwire.unreceive';
16
+
17
+ // Authorization state event
18
+ export const EVENT_AUTHORIZATION_STATE = 'signalwire.authorization.state';
19
+
20
+ // Call states
21
+ export const CALL_STATE_CREATED = 'created';
22
+ export const CALL_STATE_RINGING = 'ringing';
23
+ export const CALL_STATE_ANSWERED = 'answered';
24
+ export const CALL_STATE_ENDING = 'ending';
25
+ export const CALL_STATE_ENDED = 'ended';
26
+
27
+ export const CALL_STATES = [
28
+ CALL_STATE_CREATED,
29
+ CALL_STATE_RINGING,
30
+ CALL_STATE_ANSWERED,
31
+ CALL_STATE_ENDING,
32
+ CALL_STATE_ENDED,
33
+ ] as const;
34
+
35
+ // End reasons
36
+ export const END_REASON_HANGUP = 'hangup';
37
+ export const END_REASON_CANCEL = 'cancel';
38
+ export const END_REASON_BUSY = 'busy';
39
+ export const END_REASON_NO_ANSWER = 'noAnswer';
40
+ export const END_REASON_DECLINE = 'decline';
41
+ export const END_REASON_ERROR = 'error';
42
+ export const END_REASON_ABANDONED = 'abandoned';
43
+ export const END_REASON_MAX_DURATION = 'max_duration';
44
+ export const END_REASON_NOT_FOUND = 'not_found';
45
+
46
+ // Connect states
47
+ export const CONNECT_STATE_CONNECTING = 'connecting';
48
+ export const CONNECT_STATE_CONNECTED = 'connected';
49
+ export const CONNECT_STATE_DISCONNECTED = 'disconnected';
50
+ export const CONNECT_STATE_FAILED = 'failed';
51
+
52
+ // Event types
53
+ export const EVENT_CALL_STATE = 'calling.call.state';
54
+ export const EVENT_CALL_RECEIVE = 'calling.call.receive';
55
+ export const EVENT_CALL_CONNECT = 'calling.call.connect';
56
+ export const EVENT_CALL_PLAY = 'calling.call.play';
57
+ export const EVENT_CALL_COLLECT = 'calling.call.collect';
58
+ export const EVENT_CALL_RECORD = 'calling.call.record';
59
+ export const EVENT_CALL_DETECT = 'calling.call.detect';
60
+ export const EVENT_CALL_FAX = 'calling.call.fax';
61
+ export const EVENT_CALL_TAP = 'calling.call.tap';
62
+ export const EVENT_CALL_SEND_DIGITS = 'calling.call.send_digits';
63
+ export const EVENT_CALL_DIAL = 'calling.call.dial';
64
+ export const EVENT_CALL_REFER = 'calling.call.refer';
65
+ export const EVENT_CALL_DENOISE = 'calling.call.denoise';
66
+ export const EVENT_CALL_PAY = 'calling.call.pay';
67
+ export const EVENT_CALL_QUEUE = 'calling.call.queue';
68
+ export const EVENT_CALL_STREAM = 'calling.call.stream';
69
+ export const EVENT_CALL_ECHO = 'calling.call.echo';
70
+ export const EVENT_CALL_TRANSCRIBE = 'calling.call.transcribe';
71
+ export const EVENT_CALL_HOLD = 'calling.call.hold';
72
+ export const EVENT_CONFERENCE = 'calling.conference';
73
+ export const EVENT_CALLING_ERROR = 'calling.error';
74
+
75
+ // Messaging event types
76
+ export const EVENT_MESSAGING_RECEIVE = 'messaging.receive';
77
+ export const EVENT_MESSAGING_STATE = 'messaging.state';
78
+
79
+ // Message states
80
+ export const MESSAGE_STATE_QUEUED = 'queued';
81
+ export const MESSAGE_STATE_INITIATED = 'initiated';
82
+ export const MESSAGE_STATE_SENT = 'sent';
83
+ export const MESSAGE_STATE_DELIVERED = 'delivered';
84
+ export const MESSAGE_STATE_UNDELIVERED = 'undelivered';
85
+ export const MESSAGE_STATE_FAILED = 'failed';
86
+ export const MESSAGE_STATE_RECEIVED = 'received';
87
+
88
+ export const MESSAGE_TERMINAL_STATES = [
89
+ MESSAGE_STATE_DELIVERED,
90
+ MESSAGE_STATE_UNDELIVERED,
91
+ MESSAGE_STATE_FAILED,
92
+ ] as const;
93
+
94
+ // Play states
95
+ export const PLAY_STATE_PLAYING = 'playing';
96
+ export const PLAY_STATE_PAUSED = 'paused';
97
+ export const PLAY_STATE_FINISHED = 'finished';
98
+ export const PLAY_STATE_ERROR = 'error';
99
+
100
+ // Record states
101
+ export const RECORD_STATE_RECORDING = 'recording';
102
+ export const RECORD_STATE_PAUSED = 'paused';
103
+ export const RECORD_STATE_FINISHED = 'finished';
104
+ export const RECORD_STATE_NO_INPUT = 'no_input';
105
+
106
+ // Detect types
107
+ export const DETECT_TYPE_MACHINE = 'machine';
108
+ export const DETECT_TYPE_FAX = 'fax';
109
+ export const DETECT_TYPE_DIGIT = 'digit';
110
+
111
+ // Join room states
112
+ export const ROOM_STATE_JOINING = 'joining';
113
+ export const ROOM_STATE_JOIN = 'join';
114
+ export const ROOM_STATE_LEAVING = 'leaving';
115
+ export const ROOM_STATE_LEAVE = 'leave';
116
+
117
+ // Reconnect settings
118
+ export const RECONNECT_MIN_DELAY = 1.0;
119
+ export const RECONNECT_MAX_DELAY = 30.0;
120
+ export const RECONNECT_BACKOFF_FACTOR = 2.0;
121
+
122
+ // Ping settings
123
+ export const CLIENT_PING_INTERVAL = 30_000; // 30s
124
+ export const CLIENT_PING_MAX_FAILURES = 3;
125
+ export const SERVER_PING_TIMEOUT = 15_000; // 15s
126
+
127
+ // Request settings
128
+ export const REQUEST_TIMEOUT = 30_000; // 30s
129
+ export const EXECUTE_QUEUE_MAX = 500;
130
+
131
+ // Default host
132
+ export const DEFAULT_RELAY_HOST = 'relay.signalwire.com';
@@ -0,0 +1,123 @@
1
+ /**
2
+ * SignalWire RELAY client — real-time call control over WebSocket.
3
+ */
4
+
5
+ // Client
6
+ export { RelayClient } from './RelayClient.js';
7
+ export { RelayError } from './RelayError.js';
8
+
9
+ // Call + Actions
10
+ export { Call } from './Call.js';
11
+ export type { RelayClientLike } from './Call.js';
12
+ export {
13
+ Action,
14
+ PlayAction,
15
+ RecordAction,
16
+ DetectAction,
17
+ CollectAction,
18
+ StandaloneCollectAction,
19
+ FaxAction,
20
+ TapAction,
21
+ StreamAction,
22
+ PayAction,
23
+ TranscribeAction,
24
+ AIAction,
25
+ } from './Action.js';
26
+ export type { CallLike } from './Action.js';
27
+
28
+ // Message
29
+ export { Message } from './Message.js';
30
+
31
+ // Events
32
+ export {
33
+ RelayEvent,
34
+ CallStateEvent,
35
+ CallReceiveEvent,
36
+ PlayEvent,
37
+ RecordEvent,
38
+ CollectEvent,
39
+ ConnectEvent,
40
+ DetectEvent,
41
+ FaxEvent,
42
+ TapEvent,
43
+ StreamEvent,
44
+ SendDigitsEvent,
45
+ DialEvent,
46
+ ReferEvent,
47
+ DenoiseEvent,
48
+ PayEvent,
49
+ QueueEvent,
50
+ EchoEvent,
51
+ TranscribeEvent,
52
+ HoldEvent,
53
+ ConferenceEvent,
54
+ CallingErrorEvent,
55
+ MessageReceiveEvent,
56
+ MessageStateEvent,
57
+ parseEvent,
58
+ EVENT_CLASS_MAP,
59
+ } from './RelayEvent.js';
60
+ export type { EventClass } from './RelayEvent.js';
61
+
62
+ // Deferred utility
63
+ export { createDeferred, withTimeout } from './Deferred.js';
64
+ export type { Deferred } from './Deferred.js';
65
+
66
+ // Constants
67
+ export {
68
+ CALL_STATE_CREATED,
69
+ CALL_STATE_RINGING,
70
+ CALL_STATE_ANSWERED,
71
+ CALL_STATE_ENDING,
72
+ CALL_STATE_ENDED,
73
+ CONNECT_STATE_CONNECTING,
74
+ CONNECT_STATE_CONNECTED,
75
+ CONNECT_STATE_DISCONNECTED,
76
+ CONNECT_STATE_FAILED,
77
+ EVENT_CALL_STATE,
78
+ EVENT_CALL_RECEIVE,
79
+ EVENT_CALL_PLAY,
80
+ EVENT_CALL_RECORD,
81
+ EVENT_CALL_COLLECT,
82
+ EVENT_CALL_CONNECT,
83
+ EVENT_CALL_DETECT,
84
+ EVENT_CALL_FAX,
85
+ EVENT_CALL_TAP,
86
+ EVENT_CALL_STREAM,
87
+ EVENT_CALL_SEND_DIGITS,
88
+ EVENT_CALL_DIAL,
89
+ EVENT_CALL_REFER,
90
+ EVENT_CALL_DENOISE,
91
+ EVENT_CALL_PAY,
92
+ EVENT_CALL_QUEUE,
93
+ EVENT_CALL_ECHO,
94
+ EVENT_CALL_TRANSCRIBE,
95
+ EVENT_CALL_HOLD,
96
+ EVENT_CONFERENCE,
97
+ EVENT_CALLING_ERROR,
98
+ EVENT_MESSAGING_RECEIVE,
99
+ EVENT_MESSAGING_STATE,
100
+ MESSAGE_STATE_QUEUED,
101
+ MESSAGE_STATE_INITIATED,
102
+ MESSAGE_STATE_SENT,
103
+ MESSAGE_STATE_DELIVERED,
104
+ MESSAGE_STATE_UNDELIVERED,
105
+ MESSAGE_STATE_FAILED,
106
+ MESSAGE_STATE_RECEIVED,
107
+ } from './constants.js';
108
+
109
+ // Types
110
+ export type {
111
+ RelayClientOptions,
112
+ CallHandler,
113
+ MessageHandler,
114
+ EventHandler,
115
+ CompletedCallback,
116
+ Device,
117
+ PhoneDevice,
118
+ SipDevice,
119
+ DialOptions,
120
+ SendMessageOptions,
121
+ PlayItem,
122
+ CollectConfig,
123
+ } from './types.js';
@@ -0,0 +1,149 @@
1
+ /**
2
+ * Shared interfaces and type aliases for the RELAY client.
3
+ */
4
+
5
+ import type { Call } from './Call.js';
6
+ import type { Message } from './Message.js';
7
+ import type { RelayEvent } from './RelayEvent.js';
8
+
9
+ /** Options for constructing a RelayClient. */
10
+ export interface RelayClientOptions {
11
+ /** SignalWire project ID. Defaults to env SIGNALWIRE_PROJECT_ID. */
12
+ project?: string;
13
+ /** SignalWire API token. Defaults to env SIGNALWIRE_API_TOKEN. */
14
+ token?: string;
15
+ /** JWT token for authentication. Defaults to env SIGNALWIRE_JWT_TOKEN. */
16
+ jwtToken?: string;
17
+ /** RELAY host. Defaults to relay.signalwire.com. */
18
+ host?: string;
19
+ /** Contexts (topics) to receive inbound calls/messages on. */
20
+ contexts?: string[];
21
+ /** Maximum number of concurrent active calls. Defaults to env RELAY_MAX_ACTIVE_CALLS or 1000. */
22
+ maxActiveCalls?: number;
23
+ }
24
+
25
+ /** JSON-RPC 2.0 request. */
26
+ export interface JsonRpcRequest {
27
+ jsonrpc: '2.0';
28
+ id: string;
29
+ method: string;
30
+ params: Record<string, unknown>;
31
+ }
32
+
33
+ /** JSON-RPC 2.0 response (success). */
34
+ export interface JsonRpcResponse {
35
+ jsonrpc: '2.0';
36
+ id: string;
37
+ result?: Record<string, unknown>;
38
+ error?: JsonRpcError;
39
+ }
40
+
41
+ /** JSON-RPC 2.0 error object. */
42
+ export interface JsonRpcError {
43
+ code: number;
44
+ message: string;
45
+ data?: unknown;
46
+ }
47
+
48
+ /** Handler for inbound calls. */
49
+ export type CallHandler = (call: Call) => void | Promise<void>;
50
+
51
+ /** Handler for inbound messages. */
52
+ export type MessageHandler = (message: Message) => void | Promise<void>;
53
+
54
+ /** Handler for relay events. */
55
+ export type EventHandler = (event: RelayEvent) => void | Promise<void>;
56
+
57
+ /** Callback when an action or message completes. */
58
+ export type CompletedCallback = (event: RelayEvent) => void | Promise<void>;
59
+
60
+ /** Phone device specification for dial/connect. */
61
+ export interface PhoneDevice {
62
+ type: 'phone';
63
+ to: string;
64
+ from: string;
65
+ timeout?: number;
66
+ max_duration?: number;
67
+ codecs?: string[];
68
+ headers?: Record<string, string>[];
69
+ }
70
+
71
+ /** SIP device specification for dial/connect. */
72
+ export interface SipDevice {
73
+ type: 'sip';
74
+ to: string;
75
+ from: string;
76
+ timeout?: number;
77
+ max_duration?: number;
78
+ codecs?: string[];
79
+ headers?: Record<string, string>[];
80
+ }
81
+
82
+ /** Any device specification. */
83
+ export type Device = PhoneDevice | SipDevice | Record<string, unknown>;
84
+
85
+ /** Options for the dial() method. */
86
+ export interface DialOptions {
87
+ /** Caller ID / from number. */
88
+ from?: string;
89
+ /** Timeout in seconds for the dial. */
90
+ timeout?: number;
91
+ /** Maximum call duration in seconds. */
92
+ maxDuration?: number;
93
+ }
94
+
95
+ /** Options for the sendMessage() method. */
96
+ export interface SendMessageOptions {
97
+ /** Destination phone number in E.164 format. */
98
+ toNumber: string;
99
+ /** Sender phone number in E.164 format. */
100
+ fromNumber: string;
101
+ /** Message body text. */
102
+ body?: string;
103
+ /** Media URLs for MMS. */
104
+ media?: string[];
105
+ /** Context for the message. */
106
+ context?: string;
107
+ /** Tags for the message. */
108
+ tags?: string[];
109
+ }
110
+
111
+ /** Play item: TTS, audio URL, ringtone, or silence. */
112
+ export type PlayItem =
113
+ | { type: 'tts'; text: string; language?: string; gender?: string }
114
+ | { type: 'audio'; url: string }
115
+ | { type: 'ringtone'; name: string; duration?: number }
116
+ | { type: 'silence'; duration: number }
117
+ | Record<string, unknown>;
118
+
119
+ /** Collect input configuration. */
120
+ export interface CollectConfig {
121
+ /** Collect digits. */
122
+ digits?: {
123
+ max: number;
124
+ digit_timeout?: number;
125
+ terminators?: string;
126
+ };
127
+ /** Collect speech. */
128
+ speech?: {
129
+ end_silence_timeout?: number;
130
+ speech_timeout?: number;
131
+ language?: string;
132
+ hints?: string[];
133
+ model?: string;
134
+ };
135
+ /** Initial timeout in seconds. */
136
+ initial_timeout?: number;
137
+ /** Partial results? */
138
+ partial_results?: boolean;
139
+ /** Continuous mode? */
140
+ continuous?: boolean;
141
+ }
142
+
143
+ /** Queued request waiting for reconnection. */
144
+ export interface QueuedRequest {
145
+ method: string;
146
+ params: Record<string, unknown>;
147
+ resolve: (value: Record<string, unknown>) => void;
148
+ reject: (reason?: unknown) => void;
149
+ }
@@ -0,0 +1,103 @@
1
+ /**
2
+ * HttpClient — fetch-based HTTP with Basic Auth.
3
+ *
4
+ * All methods return parsed JSON. Throws RestError on non-2xx responses.
5
+ * Returns {} on 204 No Content.
6
+ */
7
+
8
+ /* eslint-disable @typescript-eslint/no-explicit-any */
9
+
10
+ import { getLogger } from '../Logger.js';
11
+ import { RestError } from './RestError.js';
12
+ import type { HttpClientOptions, QueryParams } from './types.js';
13
+
14
+ const logger = getLogger('rest_client');
15
+
16
+ export class HttpClient {
17
+ readonly baseUrl: string;
18
+ private readonly _authHeader: string;
19
+ private readonly _fetch: typeof globalThis.fetch;
20
+
21
+ constructor(options: HttpClientOptions) {
22
+ if (!options.host && !options.baseUrl) {
23
+ throw new Error('HttpClientOptions requires either "host" or "baseUrl".');
24
+ }
25
+
26
+ // host takes precedence (matches Python's HttpClient(project, token, host) convention
27
+ // where a bare hostname is expected and https:// is prepended automatically).
28
+ const rawUrl = options.host ? `https://${options.host}` : options.baseUrl!;
29
+ this.baseUrl = rawUrl.replace(/\/+$/, '');
30
+
31
+ this._authHeader = 'Basic ' + Buffer.from(`${options.project}:${options.token}`).toString('base64');
32
+ this._fetch = options.fetchImpl ?? globalThis.fetch;
33
+ }
34
+
35
+ private async _request<T = any>(method: string, path: string, body?: any, params?: QueryParams): Promise<T> {
36
+ let url = path.startsWith('http') ? path : `${this.baseUrl}${path}`;
37
+
38
+ if (params) {
39
+ const qs = new URLSearchParams();
40
+ for (const [k, v] of Object.entries(params)) {
41
+ if (v !== undefined) qs.set(k, String(v));
42
+ }
43
+ const qsStr = qs.toString();
44
+ if (qsStr) url += (url.includes('?') ? '&' : '?') + qsStr;
45
+ }
46
+
47
+ logger.debug(`${method} ${url}`);
48
+
49
+ const headers: Record<string, string> = {
50
+ 'Authorization': this._authHeader,
51
+ 'Accept': 'application/json',
52
+ 'User-Agent': '@signalwire/sdk-ts/2.0.0',
53
+ };
54
+ if (body !== undefined) {
55
+ headers['Content-Type'] = 'application/json';
56
+ }
57
+
58
+ const resp = await this._fetch(url, {
59
+ method,
60
+ headers,
61
+ body: body !== undefined ? JSON.stringify(body) : undefined,
62
+ });
63
+
64
+ if (!resp.ok) {
65
+ const text = await resp.text();
66
+ let errBody: string | Record<string, unknown> = text;
67
+ try {
68
+ errBody = JSON.parse(text) as Record<string, unknown>;
69
+ } catch {
70
+ // Response was not valid JSON — keep as plain string.
71
+ }
72
+ throw new RestError(resp.status, errBody, url, method);
73
+ }
74
+
75
+ if (resp.status === 204) {
76
+ return {} as T;
77
+ }
78
+
79
+ const text = await resp.text();
80
+ if (!text) return {} as T;
81
+ return JSON.parse(text) as T;
82
+ }
83
+
84
+ async get<T = any>(path: string, params?: QueryParams): Promise<T> {
85
+ return this._request<T>('GET', path, undefined, params);
86
+ }
87
+
88
+ async post<T = any>(path: string, body?: any, params?: QueryParams): Promise<T> {
89
+ return this._request<T>('POST', path, body, params);
90
+ }
91
+
92
+ async put<T = any>(path: string, body?: any): Promise<T> {
93
+ return this._request<T>('PUT', path, body);
94
+ }
95
+
96
+ async patch<T = any>(path: string, body?: any): Promise<T> {
97
+ return this._request<T>('PATCH', path, body);
98
+ }
99
+
100
+ async delete<T = any>(path: string): Promise<T> {
101
+ return this._request<T>('DELETE', path);
102
+ }
103
+ }
@@ -0,0 +1,31 @@
1
+ /**
2
+ * Custom error class for REST API errors.
3
+ *
4
+ * `body` may be a parsed JSON object (when the server returned valid JSON)
5
+ * or a plain string (when JSON parsing failed), matching the Python SDK's
6
+ * `SignalWireRestError` behavior.
7
+ */
8
+ export class RestError extends Error {
9
+ readonly statusCode: number;
10
+ readonly body: string | Record<string, unknown>;
11
+ readonly url: string;
12
+ readonly method: string;
13
+
14
+ constructor(
15
+ statusCode: number,
16
+ body: string | Record<string, unknown>,
17
+ url: string,
18
+ method: string = 'GET',
19
+ ) {
20
+ const bodyStr = typeof body === 'string' ? body : JSON.stringify(body);
21
+ super(`${method} ${url} returned ${statusCode}: ${bodyStr}`);
22
+ this.name = 'RestError';
23
+ this.statusCode = statusCode;
24
+ this.body = body;
25
+ this.url = url;
26
+ this.method = method;
27
+ }
28
+ }
29
+
30
+ /** Alias matching the Python SDK class name. */
31
+ export { RestError as SignalWireRestError };
@@ -0,0 +1,19 @@
1
+ /**
2
+ * Abstract base class for all REST resources.
3
+ */
4
+ import type { HttpClient } from '../HttpClient.js';
5
+
6
+ export abstract class BaseResource {
7
+ protected readonly _http: HttpClient;
8
+ protected readonly _basePath: string;
9
+
10
+ constructor(http: HttpClient, basePath: string) {
11
+ this._http = http;
12
+ this._basePath = basePath;
13
+ }
14
+
15
+ /** Build a sub-resource path by joining parts onto the base path. */
16
+ protected _path(...parts: (string | number)[]): string {
17
+ return [this._basePath, ...parts.map(String)].join('/');
18
+ }
19
+ }
@@ -0,0 +1,51 @@
1
+ /**
2
+ * Generic CRUD resource with configurable update method.
3
+ */
4
+
5
+ /* eslint-disable @typescript-eslint/no-explicit-any */
6
+
7
+ import type { HttpClient } from '../HttpClient.js';
8
+ import type { QueryParams } from '../types.js';
9
+ import { BaseResource } from './BaseResource.js';
10
+
11
+ export class CrudResource<
12
+ TList = any,
13
+ TItem = any,
14
+ TCreate = any,
15
+ TUpdate = any,
16
+ > extends BaseResource {
17
+ /** Override to 'PUT' for resources that use PUT instead of PATCH. */
18
+ protected _updateMethod: 'PATCH' | 'PUT' = 'PATCH';
19
+
20
+ constructor(http: HttpClient, basePath: string) {
21
+ super(http, basePath);
22
+ }
23
+
24
+ /** List resources with optional query parameters. */
25
+ async list(params?: QueryParams): Promise<TList> {
26
+ return this._http.get<TList>(this._basePath, params);
27
+ }
28
+
29
+ /** Create a new resource. */
30
+ async create(body: TCreate): Promise<TItem> {
31
+ return this._http.post<TItem>(this._basePath, body);
32
+ }
33
+
34
+ /** Get a single resource by ID. */
35
+ async get(resourceId: string): Promise<TItem> {
36
+ return this._http.get<TItem>(this._path(resourceId));
37
+ }
38
+
39
+ /** Update a resource by ID. */
40
+ async update(resourceId: string, body: TUpdate): Promise<TItem> {
41
+ if (this._updateMethod === 'PUT') {
42
+ return this._http.put<TItem>(this._path(resourceId), body);
43
+ }
44
+ return this._http.patch<TItem>(this._path(resourceId), body);
45
+ }
46
+
47
+ /** Delete a resource by ID. */
48
+ async delete(resourceId: string): Promise<any> {
49
+ return this._http.delete(this._path(resourceId));
50
+ }
51
+ }
@@ -0,0 +1,26 @@
1
+ /**
2
+ * CrudResource extended with address listing.
3
+ */
4
+
5
+ /* eslint-disable @typescript-eslint/no-explicit-any */
6
+
7
+ import type { HttpClient } from '../HttpClient.js';
8
+ import type { QueryParams } from '../types.js';
9
+ import { CrudResource } from './CrudResource.js';
10
+
11
+ export class CrudWithAddresses<
12
+ TList = any,
13
+ TItem = any,
14
+ TCreate = any,
15
+ TUpdate = any,
16
+ > extends CrudResource<TList, TItem, TCreate, TUpdate> {
17
+
18
+ constructor(http: HttpClient, basePath: string) {
19
+ super(http, basePath);
20
+ }
21
+
22
+ /** List addresses associated with a resource. */
23
+ async listAddresses(resourceId: string, params?: QueryParams): Promise<any> {
24
+ return this._http.get(this._path(resourceId, 'addresses'), params);
25
+ }
26
+ }