@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,779 @@
1
+ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
2
+ import { RelayClient } from '../../src/relay/RelayClient.js';
3
+ import { Call } from '../../src/relay/Call.js';
4
+ import { Message } from '../../src/relay/Message.js';
5
+ import { RelayError } from '../../src/relay/RelayError.js';
6
+ import { MockWebSocket } from './helpers.js';
7
+
8
+ function createClient(ws?: MockWebSocket): { client: RelayClient; ws: MockWebSocket } {
9
+ const mockWs = ws ?? new MockWebSocket();
10
+ const client = new RelayClient({
11
+ project: 'test-project',
12
+ token: 'test-token',
13
+ host: 'relay.test.com',
14
+ contexts: ['default'],
15
+ });
16
+ client._wsFactory = () => {
17
+ mockWs.autoAuthenticate();
18
+ return mockWs as any;
19
+ };
20
+ return { client, ws: mockWs };
21
+ }
22
+
23
+ describe('RelayClient', () => {
24
+ describe('constructor', () => {
25
+ it('accepts project/token directly', () => {
26
+ const client = new RelayClient({ project: 'p1', token: 't1' });
27
+ expect(client.project).toBe('p1');
28
+ expect(client.token).toBe('t1');
29
+ });
30
+
31
+ it('throws if project/token missing', () => {
32
+ const origProject = process.env.SIGNALWIRE_PROJECT_ID;
33
+ const origToken = process.env.SIGNALWIRE_API_TOKEN;
34
+ const origJwt = process.env.SIGNALWIRE_JWT_TOKEN;
35
+ delete process.env.SIGNALWIRE_PROJECT_ID;
36
+ delete process.env.SIGNALWIRE_API_TOKEN;
37
+ delete process.env.SIGNALWIRE_JWT_TOKEN;
38
+ try {
39
+ expect(() => new RelayClient({})).toThrow('project and token are required');
40
+ } finally {
41
+ if (origProject !== undefined) process.env.SIGNALWIRE_PROJECT_ID = origProject;
42
+ if (origToken !== undefined) process.env.SIGNALWIRE_API_TOKEN = origToken;
43
+ if (origJwt !== undefined) process.env.SIGNALWIRE_JWT_TOKEN = origJwt;
44
+ }
45
+ });
46
+
47
+ it('validates host', () => {
48
+ expect(() => new RelayClient({
49
+ project: 'p', token: 't',
50
+ host: 'relay.test.com/path',
51
+ })).toThrow('Invalid host');
52
+ });
53
+
54
+ it('allows JWT auth without project/token', () => {
55
+ const origEnv = process.env.SIGNALWIRE_JWT_TOKEN;
56
+ process.env.SIGNALWIRE_JWT_TOKEN = 'jwt-test';
57
+ try {
58
+ const client = new RelayClient({});
59
+ expect(client.jwtToken).toBe('jwt-test');
60
+ } finally {
61
+ if (origEnv === undefined) delete process.env.SIGNALWIRE_JWT_TOKEN;
62
+ else process.env.SIGNALWIRE_JWT_TOKEN = origEnv;
63
+ }
64
+ });
65
+ });
66
+
67
+ describe('connect', () => {
68
+ it('connects and authenticates', async () => {
69
+ const { client, ws } = createClient();
70
+
71
+ await client.connect();
72
+
73
+ expect(client.relayProtocol).toBe('test-protocol');
74
+ // Should have sent signalwire.connect
75
+ const connectMsg = ws.findSent('signalwire.connect');
76
+ expect(connectMsg).toBeDefined();
77
+ const params = connectMsg!.params as Record<string, unknown>;
78
+ expect(params.authentication).toEqual({ project: 'test-project', token: 'test-token' });
79
+ expect(params.contexts).toEqual(['default']);
80
+
81
+ await client.disconnect();
82
+ });
83
+ });
84
+
85
+ describe('execute', () => {
86
+ it('sends request and resolves on success response', async () => {
87
+ const { client, ws } = createClient();
88
+ await client.connect();
89
+
90
+ // Make a request in the background
91
+ const promise = client.execute('calling.answer', { call_id: 'c1', node_id: 'n1' });
92
+
93
+ // Find the request
94
+ await new Promise((r) => setTimeout(r, 10));
95
+ const allSent = ws.getAllSent();
96
+ const answerReq = allSent.find((m) => m.method === 'calling.answer');
97
+ expect(answerReq).toBeDefined();
98
+
99
+ // Respond
100
+ ws.receiveMessage({
101
+ jsonrpc: '2.0',
102
+ id: answerReq!.id,
103
+ result: { code: '200', message: 'OK' },
104
+ });
105
+
106
+ const result = await promise;
107
+ expect(result.code).toBe('200');
108
+
109
+ await client.disconnect();
110
+ });
111
+
112
+ it('rejects on error response', async () => {
113
+ const { client, ws } = createClient();
114
+ await client.connect();
115
+
116
+ const promise = client.execute('calling.answer', { call_id: 'c1', node_id: 'n1' });
117
+
118
+ await new Promise((r) => setTimeout(r, 10));
119
+ const answerReq = ws.getAllSent().find((m) => m.method === 'calling.answer');
120
+
121
+ ws.receiveMessage({
122
+ jsonrpc: '2.0',
123
+ id: answerReq!.id,
124
+ error: { code: 404, message: 'Not found' },
125
+ });
126
+
127
+ await expect(promise).rejects.toThrow('Not found');
128
+
129
+ await client.disconnect();
130
+ });
131
+
132
+ it('rejects on non-2xx result code', async () => {
133
+ const { client, ws } = createClient();
134
+ await client.connect();
135
+
136
+ const promise = client.execute('calling.answer', { call_id: 'c1', node_id: 'n1' });
137
+
138
+ await new Promise((r) => setTimeout(r, 10));
139
+ const answerReq = ws.getAllSent().find((m) => m.method === 'calling.answer');
140
+
141
+ ws.receiveMessage({
142
+ jsonrpc: '2.0',
143
+ id: answerReq!.id,
144
+ result: { code: '404', message: 'Not found' },
145
+ });
146
+
147
+ await expect(promise).rejects.toThrow('Not found');
148
+
149
+ await client.disconnect();
150
+ });
151
+ });
152
+
153
+ describe('event handling', () => {
154
+ it('dispatches inbound call to on_call handler', async () => {
155
+ const { client, ws } = createClient();
156
+ await client.connect();
157
+
158
+ const receivedCalls: Call[] = [];
159
+ client.onCall(async (call) => { receivedCalls.push(call); });
160
+
161
+ // Simulate inbound call event
162
+ ws.receiveMessage({
163
+ jsonrpc: '2.0',
164
+ id: 'evt-1',
165
+ method: 'signalwire.event',
166
+ params: {
167
+ event_type: 'calling.call.receive',
168
+ params: {
169
+ call_id: 'c1',
170
+ node_id: 'n1',
171
+ call_state: 'ringing',
172
+ direction: 'inbound',
173
+ device: { type: 'phone', params: { to_number: '+1234' } },
174
+ },
175
+ },
176
+ });
177
+
178
+ await new Promise((r) => setTimeout(r, 50));
179
+
180
+ expect(receivedCalls).toHaveLength(1);
181
+ expect(receivedCalls[0].callId).toBe('c1');
182
+ expect(receivedCalls[0].direction).toBe('inbound');
183
+
184
+ // Should have ACKed the event
185
+ const ackMsg = ws.getAllSent().find((m) => m.id === 'evt-1' && 'result' in m);
186
+ expect(ackMsg).toBeDefined();
187
+
188
+ await client.disconnect();
189
+ });
190
+
191
+ it('dispatches inbound message to on_message handler', async () => {
192
+ const { client, ws } = createClient();
193
+ await client.connect();
194
+
195
+ const receivedMessages: Message[] = [];
196
+ client.onMessage(async (msg) => { receivedMessages.push(msg); });
197
+
198
+ ws.receiveMessage({
199
+ jsonrpc: '2.0',
200
+ id: 'evt-2',
201
+ method: 'signalwire.event',
202
+ params: {
203
+ event_type: 'messaging.receive',
204
+ params: {
205
+ message_id: 'm1',
206
+ direction: 'inbound',
207
+ from_number: '+111',
208
+ to_number: '+222',
209
+ body: 'Hello',
210
+ message_state: 'received',
211
+ },
212
+ },
213
+ });
214
+
215
+ await new Promise((r) => setTimeout(r, 50));
216
+
217
+ expect(receivedMessages).toHaveLength(1);
218
+ expect(receivedMessages[0].messageId).toBe('m1');
219
+ expect(receivedMessages[0].body).toBe('Hello');
220
+
221
+ await client.disconnect();
222
+ });
223
+
224
+ it('routes state events to existing calls', async () => {
225
+ const { client, ws } = createClient();
226
+ await client.connect();
227
+
228
+ // Create call via inbound event
229
+ client.onCall(async () => {});
230
+ ws.receiveMessage({
231
+ jsonrpc: '2.0',
232
+ id: 'evt-1',
233
+ method: 'signalwire.event',
234
+ params: {
235
+ event_type: 'calling.call.receive',
236
+ params: { call_id: 'c1', node_id: 'n1', call_state: 'ringing' },
237
+ },
238
+ });
239
+
240
+ await new Promise((r) => setTimeout(r, 20));
241
+
242
+ // Send state update
243
+ ws.receiveMessage({
244
+ jsonrpc: '2.0',
245
+ id: 'evt-2',
246
+ method: 'signalwire.event',
247
+ params: {
248
+ event_type: 'calling.call.state',
249
+ params: { call_id: 'c1', call_state: 'answered' },
250
+ },
251
+ });
252
+
253
+ await new Promise((r) => setTimeout(r, 20));
254
+
255
+ // Verify - need access to internal calls map via inbound handler
256
+ // The call's state was updated in dispatch
257
+
258
+ await client.disconnect();
259
+ });
260
+
261
+ it('responds to server pings', async () => {
262
+ const { client, ws } = createClient();
263
+ await client.connect();
264
+
265
+ ws.receiveMessage({
266
+ jsonrpc: '2.0',
267
+ id: 'ping-1',
268
+ method: 'signalwire.ping',
269
+ params: {},
270
+ });
271
+
272
+ await new Promise((r) => setTimeout(r, 20));
273
+
274
+ // Should have sent pong
275
+ const pong = ws.getAllSent().find((m) => m.id === 'ping-1' && 'result' in m);
276
+ expect(pong).toBeDefined();
277
+
278
+ await client.disconnect();
279
+ });
280
+
281
+ it('stores authorization_state for reconnection', async () => {
282
+ const { client, ws } = createClient();
283
+ await client.connect();
284
+
285
+ ws.receiveMessage({
286
+ jsonrpc: '2.0',
287
+ id: 'evt-3',
288
+ method: 'signalwire.event',
289
+ params: {
290
+ event_type: 'signalwire.authorization.state',
291
+ params: { authorization_state: 'encrypted-state' },
292
+ },
293
+ });
294
+
295
+ await new Promise((r) => setTimeout(r, 20));
296
+
297
+ // On next connect, auth_state should be sent
298
+ // (verified indirectly — internal state updated)
299
+
300
+ await client.disconnect();
301
+ });
302
+
303
+ it('handles signalwire.disconnect with restart=true', async () => {
304
+ const { client, ws } = createClient();
305
+ await client.connect();
306
+
307
+ ws.receiveMessage({
308
+ jsonrpc: '2.0',
309
+ id: 'disc-1',
310
+ method: 'signalwire.disconnect',
311
+ params: { restart: true },
312
+ });
313
+
314
+ await new Promise((r) => setTimeout(r, 20));
315
+
316
+ // Should have ACKed
317
+ const ack = ws.getAllSent().find((m) => m.id === 'disc-1' && 'result' in m);
318
+ expect(ack).toBeDefined();
319
+
320
+ // Protocol should be cleared for fresh auth
321
+ expect(client.relayProtocol).toBe('');
322
+
323
+ await client.disconnect();
324
+ });
325
+ });
326
+
327
+ describe('sendMessage', () => {
328
+ it('sends messaging.send and returns a Message', async () => {
329
+ const { client, ws } = createClient();
330
+ await client.connect();
331
+
332
+ const msgPromise = client.sendMessage({
333
+ toNumber: '+222',
334
+ fromNumber: '+111',
335
+ body: 'Hello',
336
+ });
337
+
338
+ await new Promise((r) => setTimeout(r, 10));
339
+ const sendReq = ws.getAllSent().find((m) => m.method === 'messaging.send');
340
+ expect(sendReq).toBeDefined();
341
+
342
+ ws.receiveMessage({
343
+ jsonrpc: '2.0',
344
+ id: sendReq!.id,
345
+ result: { code: '200', message: 'OK', message_id: 'msg-1' },
346
+ });
347
+
348
+ const msg = await msgPromise;
349
+ expect(msg).toBeInstanceOf(Message);
350
+ expect(msg.messageId).toBe('msg-1');
351
+ expect(msg.state).toBe('queued');
352
+
353
+ await client.disconnect();
354
+ });
355
+
356
+ it('throws if no body or media', async () => {
357
+ const { client } = createClient();
358
+ await client.connect();
359
+
360
+ await expect(client.sendMessage({ toNumber: '+222', fromNumber: '+111' }))
361
+ .rejects.toThrow('At least one of body or media');
362
+
363
+ await client.disconnect();
364
+ });
365
+ });
366
+
367
+ describe('receive/unreceive', () => {
368
+ it('sends signalwire.receive', async () => {
369
+ const { client, ws } = createClient();
370
+ await client.connect();
371
+
372
+ const promise = client.receive(['office', 'support']);
373
+
374
+ await new Promise((r) => setTimeout(r, 10));
375
+ const recvReq = ws.getAllSent().find((m) => m.method === 'signalwire.receive');
376
+ expect(recvReq).toBeDefined();
377
+
378
+ ws.receiveMessage({
379
+ jsonrpc: '2.0',
380
+ id: recvReq!.id,
381
+ result: { code: '200' },
382
+ });
383
+
384
+ await promise;
385
+
386
+ await client.disconnect();
387
+ });
388
+
389
+ it('skips empty contexts', async () => {
390
+ const { client, ws } = createClient();
391
+ await client.connect();
392
+
393
+ await client.receive([]);
394
+ // No additional request sent
395
+ const recvReqs = ws.getAllSent().filter((m) => m.method === 'signalwire.receive');
396
+ expect(recvReqs).toHaveLength(0);
397
+
398
+ await client.disconnect();
399
+ });
400
+ });
401
+
402
+ describe('dial', () => {
403
+ it('sends calling.dial and resolves on answered event', async () => {
404
+ const { client, ws } = createClient();
405
+ await client.connect();
406
+
407
+ const dialPromise = client.dial(
408
+ [[{ type: 'phone', to: '+222', from: '+111' }]],
409
+ { tag: 'test-tag' },
410
+ );
411
+
412
+ await new Promise((r) => setTimeout(r, 10));
413
+ const dialReq = ws.getAllSent().find((m) => m.method === 'calling.dial');
414
+ expect(dialReq).toBeDefined();
415
+
416
+ // Respond to dial RPC
417
+ ws.receiveMessage({
418
+ jsonrpc: '2.0',
419
+ id: dialReq!.id,
420
+ result: { code: '200', message: 'Dialing' },
421
+ });
422
+
423
+ await new Promise((r) => setTimeout(r, 10));
424
+
425
+ // Send dial event with answered state
426
+ ws.receiveMessage({
427
+ jsonrpc: '2.0',
428
+ id: 'dial-evt',
429
+ method: 'signalwire.event',
430
+ params: {
431
+ event_type: 'calling.call.dial',
432
+ params: {
433
+ tag: 'test-tag',
434
+ dial_state: 'answered',
435
+ call: { call_id: 'c1', node_id: 'n1', device: { type: 'phone' } },
436
+ },
437
+ },
438
+ });
439
+
440
+ const call = await dialPromise;
441
+ expect(call).toBeInstanceOf(Call);
442
+ expect(call.callId).toBe('c1');
443
+ expect(call.direction).toBe('outbound');
444
+
445
+ await client.disconnect();
446
+ });
447
+
448
+ it('rejects on dial failed', async () => {
449
+ const { client, ws } = createClient();
450
+ await client.connect();
451
+
452
+ const dialPromise = client.dial(
453
+ [[{ type: 'phone', to: '+222', from: '+111' }]],
454
+ { tag: 'fail-tag' },
455
+ );
456
+
457
+ await new Promise((r) => setTimeout(r, 10));
458
+ const dialReq = ws.getAllSent().find((m) => m.method === 'calling.dial');
459
+
460
+ ws.receiveMessage({
461
+ jsonrpc: '2.0',
462
+ id: dialReq!.id,
463
+ result: { code: '200', message: 'Dialing' },
464
+ });
465
+
466
+ await new Promise((r) => setTimeout(r, 10));
467
+
468
+ ws.receiveMessage({
469
+ jsonrpc: '2.0',
470
+ id: 'dial-evt',
471
+ method: 'signalwire.event',
472
+ params: {
473
+ event_type: 'calling.call.dial',
474
+ params: {
475
+ tag: 'fail-tag',
476
+ dial_state: 'failed',
477
+ call: {},
478
+ },
479
+ },
480
+ });
481
+
482
+ await expect(dialPromise).rejects.toThrow('Dial failed');
483
+
484
+ await client.disconnect();
485
+ });
486
+
487
+ it('registers dial leg from state events before dial event', async () => {
488
+ const { client, ws } = createClient();
489
+ await client.connect();
490
+
491
+ const dialPromise = client.dial(
492
+ [[{ type: 'phone', to: '+222', from: '+111' }]],
493
+ { tag: 'leg-tag' },
494
+ );
495
+
496
+ await new Promise((r) => setTimeout(r, 10));
497
+ const dialReq = ws.getAllSent().find((m) => m.method === 'calling.dial');
498
+ ws.receiveMessage({
499
+ jsonrpc: '2.0',
500
+ id: dialReq!.id,
501
+ result: { code: '200', message: 'Dialing' },
502
+ });
503
+
504
+ await new Promise((r) => setTimeout(r, 10));
505
+
506
+ // State event arrives before dial event
507
+ ws.receiveMessage({
508
+ jsonrpc: '2.0',
509
+ id: 'state-evt',
510
+ method: 'signalwire.event',
511
+ params: {
512
+ event_type: 'calling.call.state',
513
+ params: {
514
+ call_id: 'c1',
515
+ node_id: 'n1',
516
+ tag: 'leg-tag',
517
+ call_state: 'ringing',
518
+ },
519
+ },
520
+ });
521
+
522
+ await new Promise((r) => setTimeout(r, 10));
523
+
524
+ // Now dial event resolves
525
+ ws.receiveMessage({
526
+ jsonrpc: '2.0',
527
+ id: 'dial-evt',
528
+ method: 'signalwire.event',
529
+ params: {
530
+ event_type: 'calling.call.dial',
531
+ params: {
532
+ tag: 'leg-tag',
533
+ dial_state: 'answered',
534
+ call: { call_id: 'c1', node_id: 'n1' },
535
+ },
536
+ },
537
+ });
538
+
539
+ const call = await dialPromise;
540
+ expect(call.callId).toBe('c1');
541
+
542
+ await client.disconnect();
543
+ });
544
+ });
545
+
546
+ describe('execute queue', () => {
547
+ it('queues requests when not connected', async () => {
548
+ const mockWs = new MockWebSocket();
549
+ const client = new RelayClient({
550
+ project: 'p', token: 't',
551
+ host: 'relay.test.com',
552
+ });
553
+
554
+ // Create deferred response handling
555
+ let authReqId = '';
556
+ mockWs.autoAuthenticate();
557
+
558
+ client._wsFactory = () => mockWs as any;
559
+
560
+ // Connect first
561
+ await client.connect();
562
+
563
+ // Now test: disconnect, make request, reconnect — request should flush
564
+ // We can't easily test this without the run() loop, so just verify the basic flow
565
+ await client.disconnect();
566
+ });
567
+ });
568
+
569
+ describe('disconnect', () => {
570
+ it('cleans up all state', async () => {
571
+ const { client, ws } = createClient();
572
+ await client.connect();
573
+
574
+ await client.disconnect();
575
+
576
+ expect(ws.closed).toBe(true);
577
+ });
578
+ });
579
+
580
+ describe('message state tracking', () => {
581
+ it('routes messaging.state events to tracked messages', async () => {
582
+ const { client, ws } = createClient();
583
+ await client.connect();
584
+
585
+ // Send a message first
586
+ const msgPromise = client.sendMessage({ toNumber: '+222', fromNumber: '+111', body: 'Hi' });
587
+
588
+ await new Promise((r) => setTimeout(r, 10));
589
+ const sendReq = ws.getAllSent().find((m) => m.method === 'messaging.send');
590
+ ws.receiveMessage({
591
+ jsonrpc: '2.0',
592
+ id: sendReq!.id,
593
+ result: { code: '200', message_id: 'msg-1' },
594
+ });
595
+
596
+ const msg = await msgPromise;
597
+
598
+ // Now send state events
599
+ ws.receiveMessage({
600
+ jsonrpc: '2.0',
601
+ id: 'state-1',
602
+ method: 'signalwire.event',
603
+ params: {
604
+ event_type: 'messaging.state',
605
+ params: { message_id: 'msg-1', message_state: 'delivered' },
606
+ },
607
+ });
608
+
609
+ await new Promise((r) => setTimeout(r, 50));
610
+
611
+ expect(msg.state).toBe('delivered');
612
+ expect(msg.isDone).toBe(true);
613
+
614
+ await client.disconnect();
615
+ });
616
+ });
617
+
618
+ describe('jwtToken env precedence', () => {
619
+ let origJwt: string | undefined;
620
+
621
+ beforeEach(() => {
622
+ origJwt = process.env.SIGNALWIRE_JWT_TOKEN;
623
+ });
624
+ afterEach(() => {
625
+ if (origJwt === undefined) delete process.env.SIGNALWIRE_JWT_TOKEN;
626
+ else process.env.SIGNALWIRE_JWT_TOKEN = origJwt;
627
+ });
628
+
629
+ it('reads SIGNALWIRE_JWT_TOKEN from env when option omitted', () => {
630
+ process.env.SIGNALWIRE_JWT_TOKEN = 'env-jwt';
631
+ const client = new RelayClient({});
632
+ expect(client.jwtToken).toBe('env-jwt');
633
+ });
634
+
635
+ it('explicit jwtToken option wins over env', () => {
636
+ process.env.SIGNALWIRE_JWT_TOKEN = 'env-jwt';
637
+ const client = new RelayClient({ jwtToken: 'arg-jwt' });
638
+ expect(client.jwtToken).toBe('arg-jwt');
639
+ });
640
+ });
641
+
642
+ describe('maxActiveCalls env precedence', () => {
643
+ let origMax: string | undefined;
644
+
645
+ beforeEach(() => {
646
+ origMax = process.env.RELAY_MAX_ACTIVE_CALLS;
647
+ });
648
+ afterEach(() => {
649
+ if (origMax === undefined) delete process.env.RELAY_MAX_ACTIVE_CALLS;
650
+ else process.env.RELAY_MAX_ACTIVE_CALLS = origMax;
651
+ });
652
+
653
+ it('reads RELAY_MAX_ACTIVE_CALLS from env when option omitted', () => {
654
+ process.env.RELAY_MAX_ACTIVE_CALLS = '42';
655
+ const client = new RelayClient({ project: 'p', token: 't' });
656
+ expect((client as any)._maxActiveCalls).toBe(42);
657
+ });
658
+
659
+ it('explicit maxActiveCalls option wins over env', () => {
660
+ process.env.RELAY_MAX_ACTIVE_CALLS = '42';
661
+ const client = new RelayClient({ project: 'p', token: 't', maxActiveCalls: 7 });
662
+ expect((client as any)._maxActiveCalls).toBe(7);
663
+ });
664
+
665
+ it('invalid env value falls back to default 1000', () => {
666
+ process.env.RELAY_MAX_ACTIVE_CALLS = 'not-a-number';
667
+ const client = new RelayClient({ project: 'p', token: 't' });
668
+ expect((client as any)._maxActiveCalls).toBe(1000);
669
+ });
670
+
671
+ it('non-positive env value clamps to 1', () => {
672
+ process.env.RELAY_MAX_ACTIVE_CALLS = '0';
673
+ const client = new RelayClient({ project: 'p', token: 't' });
674
+ expect((client as any)._maxActiveCalls).toBe(1);
675
+ });
676
+
677
+ it('non-positive explicit option clamps to 1', () => {
678
+ const client = new RelayClient({ project: 'p', token: 't', maxActiveCalls: -5 });
679
+ expect((client as any)._maxActiveCalls).toBe(1);
680
+ });
681
+
682
+ it('defaults to 1000 when env and option are absent', () => {
683
+ delete process.env.RELAY_MAX_ACTIVE_CALLS;
684
+ const client = new RelayClient({ project: 'p', token: 't' });
685
+ expect((client as any)._maxActiveCalls).toBe(1000);
686
+ });
687
+ });
688
+
689
+ describe('Symbol.asyncDispose', () => {
690
+ it('exposes an asyncDispose method', () => {
691
+ const client = new RelayClient({ project: 'p', token: 't' });
692
+ expect(typeof (client as any)[Symbol.asyncDispose]).toBe('function');
693
+ });
694
+
695
+ it('invoking asyncDispose calls disconnect (removes from active set)', async () => {
696
+ const { client } = createClient();
697
+ await client.connect();
698
+ // Explicitly invoke the disposer
699
+ await (client as any)[Symbol.asyncDispose]();
700
+ // After disposal, a second client should be able to connect without
701
+ // tripping the _MAX_CONNECTIONS guard.
702
+ const { client: other } = createClient();
703
+ await expect(other.connect()).resolves.toBeUndefined();
704
+ await other.disconnect();
705
+ });
706
+ });
707
+
708
+ describe('_MAX_CONNECTIONS guard', () => {
709
+ it('rejects a second concurrent client.connect() with default limit of 1', async () => {
710
+ const { client: a } = createClient();
711
+ const { client: b } = createClient();
712
+ await a.connect();
713
+ try {
714
+ await expect(b.connect()).rejects.toThrow(/connection limit reached/);
715
+ } finally {
716
+ await a.disconnect();
717
+ }
718
+ });
719
+
720
+ it('reconnecting the same instance does not trip the guard', async () => {
721
+ const { client } = createClient();
722
+ await client.connect();
723
+ // Simulate the reconnect case — same instance reconnects after a drop.
724
+ // Don't disconnect() first (that would remove it from the set).
725
+ await expect(client.connect()).resolves.toBeUndefined();
726
+ await client.disconnect();
727
+ });
728
+
729
+ it('after disconnect, a new client can connect', async () => {
730
+ const { client: a } = createClient();
731
+ await a.connect();
732
+ await a.disconnect();
733
+ const { client: b } = createClient();
734
+ await expect(b.connect()).resolves.toBeUndefined();
735
+ await b.disconnect();
736
+ });
737
+
738
+ it('RELAY_MAX_CONNECTIONS env > 1 allows additional clients', async () => {
739
+ const origMaxConn = process.env.RELAY_MAX_CONNECTIONS;
740
+ process.env.RELAY_MAX_CONNECTIONS = '3';
741
+ // Module caches _MAX_CONNECTIONS at load time, so we re-import fresh.
742
+ vi.resetModules();
743
+ try {
744
+ const mod = await import('../../src/relay/RelayClient.js');
745
+ const { MockWebSocket: FreshMockWs } = await import('./helpers.js');
746
+ const freshCreate = (): { client: InstanceType<typeof mod.RelayClient>; ws: any } => {
747
+ const mockWs = new FreshMockWs();
748
+ const client = new mod.RelayClient({
749
+ project: 'p', token: 't', host: 'relay.test.com',
750
+ });
751
+ (client as any)._wsFactory = () => {
752
+ mockWs.autoAuthenticate();
753
+ return mockWs;
754
+ };
755
+ return { client, ws: mockWs };
756
+ };
757
+ const a = freshCreate().client;
758
+ const b = freshCreate().client;
759
+ const c = freshCreate().client;
760
+ await a.connect();
761
+ await b.connect();
762
+ await c.connect();
763
+ try {
764
+ // Fourth should fail
765
+ const d = freshCreate().client;
766
+ await expect(d.connect()).rejects.toThrow(/connection limit reached \(3\)/);
767
+ } finally {
768
+ await a.disconnect();
769
+ await b.disconnect();
770
+ await c.disconnect();
771
+ }
772
+ } finally {
773
+ if (origMaxConn === undefined) delete process.env.RELAY_MAX_CONNECTIONS;
774
+ else process.env.RELAY_MAX_CONNECTIONS = origMaxConn;
775
+ vi.resetModules();
776
+ }
777
+ });
778
+ });
779
+ });