@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,206 @@
1
+ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
2
+ import { SchemaUtils } from '../src/SchemaUtils.js';
3
+
4
+ describe('SchemaUtils — verb extraction and validation', () => {
5
+ let schema: SchemaUtils;
6
+
7
+ beforeEach(() => {
8
+ schema = new SchemaUtils();
9
+ });
10
+
11
+ describe('schema loading', () => {
12
+ it('loads the schema and extracts verbs', () => {
13
+ const names = schema.getVerbNames();
14
+ expect(names.length).toBeGreaterThanOrEqual(30);
15
+ });
16
+
17
+ it('extracts the expected verb count (~38)', () => {
18
+ const names = schema.getVerbNames();
19
+ expect(names.length).toBe(38);
20
+ });
21
+ });
22
+
23
+ describe('getVerbNames()', () => {
24
+ it('includes well-known verbs', () => {
25
+ const names = schema.getVerbNames();
26
+ expect(names).toContain('answer');
27
+ expect(names).toContain('hangup');
28
+ expect(names).toContain('play');
29
+ expect(names).toContain('ai');
30
+ expect(names).toContain('sleep');
31
+ expect(names).toContain('connect');
32
+ expect(names).toContain('tap');
33
+ expect(names).toContain('record');
34
+ expect(names).toContain('transfer');
35
+ expect(names).toContain('label');
36
+ expect(names).toContain('goto');
37
+ expect(names).toContain('execute');
38
+ expect(names).toContain('switch');
39
+ expect(names).toContain('cond');
40
+ });
41
+
42
+ it('includes snake_case verb names', () => {
43
+ const names = schema.getVerbNames();
44
+ expect(names).toContain('send_digits');
45
+ expect(names).toContain('send_fax');
46
+ expect(names).toContain('send_sms');
47
+ expect(names).toContain('record_call');
48
+ expect(names).toContain('stop_record_call');
49
+ expect(names).toContain('stop_tap');
50
+ expect(names).toContain('stop_denoise');
51
+ expect(names).toContain('sip_refer');
52
+ expect(names).toContain('enter_queue');
53
+ expect(names).toContain('join_room');
54
+ expect(names).toContain('join_conference');
55
+ });
56
+ });
57
+
58
+ describe('getVerbProperties()', () => {
59
+ it('returns inner schema for a known verb', () => {
60
+ const props = schema.getVerbProperties('hangup');
61
+ expect(props).toHaveProperty('type', 'object');
62
+ expect(props).toHaveProperty('properties');
63
+ });
64
+
65
+ it('returns empty object for unknown verb', () => {
66
+ const props = schema.getVerbProperties('nonexistent');
67
+ expect(props).toEqual({});
68
+ });
69
+
70
+ it('returns correct structure for tap', () => {
71
+ const props = schema.getVerbProperties('tap');
72
+ expect(props).toHaveProperty('type', 'object');
73
+ const innerProps = (props as Record<string, unknown>)['properties'] as Record<string, unknown>;
74
+ expect(innerProps).toHaveProperty('uri');
75
+ expect(innerProps).toHaveProperty('direction');
76
+ expect(innerProps).toHaveProperty('codec');
77
+ });
78
+ });
79
+
80
+ describe('getVerbRequiredProperties()', () => {
81
+ it('returns required fields for tap', () => {
82
+ const required = schema.getVerbRequiredProperties('tap');
83
+ expect(required).toContain('uri');
84
+ });
85
+
86
+ it('returns required fields for goto', () => {
87
+ const required = schema.getVerbRequiredProperties('goto');
88
+ expect(required).toContain('label');
89
+ });
90
+
91
+ it('returns empty array for verb with no required inner props', () => {
92
+ const required = schema.getVerbRequiredProperties('hangup');
93
+ expect(required).toEqual([]);
94
+ });
95
+
96
+ it('returns empty array for unknown verb', () => {
97
+ const required = schema.getVerbRequiredProperties('nonexistent');
98
+ expect(required).toEqual([]);
99
+ });
100
+ });
101
+
102
+ describe('getVerbDescription()', () => {
103
+ it('returns description for hangup', () => {
104
+ const desc = schema.getVerbDescription('hangup');
105
+ expect(desc).toContain('End the call');
106
+ });
107
+
108
+ it('returns description for tap', () => {
109
+ const desc = schema.getVerbDescription('tap');
110
+ expect(desc.length).toBeGreaterThan(0);
111
+ });
112
+
113
+ it('returns empty string for unknown verb', () => {
114
+ const desc = schema.getVerbDescription('nonexistent');
115
+ expect(desc).toBe('');
116
+ });
117
+ });
118
+
119
+ describe('hasVerb()', () => {
120
+ it('returns true for known verbs', () => {
121
+ expect(schema.hasVerb('answer')).toBe(true);
122
+ expect(schema.hasVerb('hangup')).toBe(true);
123
+ expect(schema.hasVerb('sleep')).toBe(true);
124
+ });
125
+
126
+ it('returns false for unknown verbs', () => {
127
+ expect(schema.hasVerb('nonexistent')).toBe(false);
128
+ expect(schema.hasVerb('Answer')).toBe(false); // PascalCase shouldn't match
129
+ });
130
+ });
131
+
132
+ describe('validateVerb()', () => {
133
+ it('passes for valid hangup config', () => {
134
+ const result = schema.validateVerb('hangup', { reason: 'busy' });
135
+ expect(result.valid).toBe(true);
136
+ expect(result.errors).toHaveLength(0);
137
+ });
138
+
139
+ it('passes for empty hangup config (no required props)', () => {
140
+ const result = schema.validateVerb('hangup', {});
141
+ expect(result.valid).toBe(true);
142
+ });
143
+
144
+ it('passes for valid tap config with required uri', () => {
145
+ const result = schema.validateVerb('tap', { uri: 'wss://example.com' });
146
+ expect(result.valid).toBe(true);
147
+ });
148
+
149
+ it('fails for tap missing required uri', () => {
150
+ const result = schema.validateVerb('tap', { direction: 'both' });
151
+ expect(result.valid).toBe(false);
152
+ expect(result.errors[0]).toContain("'uri'");
153
+ });
154
+
155
+ it('fails for unknown verb', () => {
156
+ const result = schema.validateVerb('nonexistent', {});
157
+ expect(result.valid).toBe(false);
158
+ expect(result.errors[0]).toContain('Unknown verb');
159
+ });
160
+
161
+ it('passes for goto with required label', () => {
162
+ const result = schema.validateVerb('goto', { label: 'start' });
163
+ expect(result.valid).toBe(true);
164
+ });
165
+
166
+ it('fails for goto missing required label', () => {
167
+ const result = schema.validateVerb('goto', { when: 'true' });
168
+ expect(result.valid).toBe(false);
169
+ expect(result.errors[0]).toContain("'label'");
170
+ });
171
+
172
+ it('passes for label (string-typed verb)', () => {
173
+ const result = schema.validateVerb('label', 'start');
174
+ expect(result.valid).toBe(true);
175
+ });
176
+
177
+ it('passes for sleep (anyOf typed verb)', () => {
178
+ const result = schema.validateVerb('sleep', 5000);
179
+ expect(result.valid).toBe(true);
180
+ });
181
+ });
182
+
183
+ describe('SWML_SKIP_SCHEMA_VALIDATION', () => {
184
+ it('skips validation when skipValidation is true', () => {
185
+ const skipped = new SchemaUtils({ skipValidation: true });
186
+ const result = skipped.validateVerb('nonexistent', {});
187
+ expect(result.valid).toBe(true);
188
+ });
189
+
190
+ it('skips validation via env var', () => {
191
+ const origEnv = process.env['SWML_SKIP_SCHEMA_VALIDATION'];
192
+ try {
193
+ process.env['SWML_SKIP_SCHEMA_VALIDATION'] = 'true';
194
+ const envSchema = new SchemaUtils();
195
+ const result = envSchema.validateVerb('nonexistent', {});
196
+ expect(result.valid).toBe(true);
197
+ } finally {
198
+ if (origEnv === undefined) {
199
+ delete process.env['SWML_SKIP_SCHEMA_VALIDATION'];
200
+ } else {
201
+ process.env['SWML_SKIP_SCHEMA_VALIDATION'] = origEnv;
202
+ }
203
+ }
204
+ });
205
+ });
206
+ });
@@ -0,0 +1,192 @@
1
+ import { describe, it, expect } from 'vitest';
2
+ import {
3
+ safeAssign,
4
+ isPrivateIp,
5
+ resolveAndValidateUrl,
6
+ filterSensitiveHeaders,
7
+ redactUrl,
8
+ isValidHostname,
9
+ MAX_SKILL_INPUT_LENGTH,
10
+ } from '../src/SecurityUtils.js';
11
+
12
+ describe('SecurityUtils', () => {
13
+ // ── safeAssign ──────────────────────────────────────────────────────
14
+ describe('safeAssign', () => {
15
+ it('copies normal keys', () => {
16
+ const target: Record<string, unknown> = { a: 1 };
17
+ safeAssign(target, { b: 2, c: 3 });
18
+ expect(target).toEqual({ a: 1, b: 2, c: 3 });
19
+ });
20
+
21
+ it('blocks __proto__ key', () => {
22
+ const target: Record<string, unknown> = {};
23
+ // Use Object.create to construct a source with a literal __proto__ own property
24
+ const source = Object.create(null) as Record<string, unknown>;
25
+ source['__proto__'] = { polluted: true };
26
+ source['safe'] = 'ok';
27
+ safeAssign(target, source);
28
+ expect(target['safe']).toBe('ok');
29
+ expect(({} as any).polluted).toBeUndefined();
30
+ // __proto__ should not have been copied as an own property
31
+ expect(Object.prototype.hasOwnProperty.call(target, '__proto__')).toBe(false);
32
+ });
33
+
34
+ it('blocks constructor key', () => {
35
+ const target: Record<string, unknown> = {};
36
+ const source = Object.create(null) as Record<string, unknown>;
37
+ source['constructor'] = 'bad';
38
+ source['normal'] = 'ok';
39
+ safeAssign(target, source);
40
+ // constructor should not have been set as an own property
41
+ expect(Object.prototype.hasOwnProperty.call(target, 'constructor')).toBe(false);
42
+ expect(target['normal']).toBe('ok');
43
+ });
44
+
45
+ it('blocks prototype key', () => {
46
+ const target: Record<string, unknown> = {};
47
+ const source = Object.create(null) as Record<string, unknown>;
48
+ source['prototype'] = 'bad';
49
+ source['key'] = 'val';
50
+ safeAssign(target, source);
51
+ expect(Object.prototype.hasOwnProperty.call(target, 'prototype')).toBe(false);
52
+ expect(target['key']).toBe('val');
53
+ });
54
+ });
55
+
56
+ // ── isPrivateIp ─────────────────────────────────────────────────────
57
+ describe('isPrivateIp', () => {
58
+ it('identifies 127.x as private', () => {
59
+ expect(isPrivateIp('127.0.0.1')).toBe(true);
60
+ expect(isPrivateIp('127.255.255.255')).toBe(true);
61
+ });
62
+
63
+ it('identifies 10.x as private', () => {
64
+ expect(isPrivateIp('10.0.0.1')).toBe(true);
65
+ expect(isPrivateIp('10.255.255.255')).toBe(true);
66
+ });
67
+
68
+ it('identifies 172.16-31.x as private', () => {
69
+ expect(isPrivateIp('172.16.0.1')).toBe(true);
70
+ expect(isPrivateIp('172.31.255.255')).toBe(true);
71
+ expect(isPrivateIp('172.15.0.1')).toBe(false);
72
+ expect(isPrivateIp('172.32.0.1')).toBe(false);
73
+ });
74
+
75
+ it('identifies 192.168.x as private', () => {
76
+ expect(isPrivateIp('192.168.1.1')).toBe(true);
77
+ });
78
+
79
+ it('identifies 169.254.x as private', () => {
80
+ expect(isPrivateIp('169.254.0.1')).toBe(true);
81
+ });
82
+
83
+ it('identifies IPv6 loopback ::1 as private', () => {
84
+ expect(isPrivateIp('::1')).toBe(true);
85
+ });
86
+
87
+ it('identifies fc/fd prefixes as private', () => {
88
+ expect(isPrivateIp('fc00::1')).toBe(true);
89
+ expect(isPrivateIp('fd12::1')).toBe(true);
90
+ });
91
+
92
+ it('identifies fe80 link-local as private', () => {
93
+ expect(isPrivateIp('fe80::1')).toBe(true);
94
+ });
95
+
96
+ it('returns false for public IPs', () => {
97
+ expect(isPrivateIp('8.8.8.8')).toBe(false);
98
+ expect(isPrivateIp('1.1.1.1')).toBe(false);
99
+ expect(isPrivateIp('203.0.113.1')).toBe(false);
100
+ });
101
+ });
102
+
103
+ // ── resolveAndValidateUrl ───────────────────────────────────────────
104
+ describe('resolveAndValidateUrl', () => {
105
+ it('rejects http://127.0.0.1/', async () => {
106
+ await expect(resolveAndValidateUrl('http://127.0.0.1/')).rejects.toThrow('private IP');
107
+ });
108
+
109
+ it('rejects http://10.0.0.1/', async () => {
110
+ await expect(resolveAndValidateUrl('http://10.0.0.1/')).rejects.toThrow('private IP');
111
+ });
112
+
113
+ it('passes with allowPrivate=true', async () => {
114
+ await expect(resolveAndValidateUrl('http://127.0.0.1/', true)).resolves.toBeUndefined();
115
+ });
116
+
117
+ it('rejects invalid URLs', async () => {
118
+ await expect(resolveAndValidateUrl('not-a-url')).rejects.toThrow('Invalid URL');
119
+ });
120
+ });
121
+
122
+ // ── filterSensitiveHeaders ──────────────────────────────────────────
123
+ describe('filterSensitiveHeaders', () => {
124
+ it('removes authorization and cookie, keeps content-type and host', () => {
125
+ const headers = {
126
+ 'authorization': 'Bearer secret',
127
+ 'cookie': 'session=abc',
128
+ 'content-type': 'application/json',
129
+ 'host': 'example.com',
130
+ 'x-api-key': 'key123',
131
+ 'proxy-authorization': 'Basic xxx',
132
+ };
133
+ const filtered = filterSensitiveHeaders(headers);
134
+ expect(filtered).toEqual({
135
+ 'content-type': 'application/json',
136
+ 'host': 'example.com',
137
+ });
138
+ });
139
+
140
+ it('handles case-insensitive header names', () => {
141
+ const headers = {
142
+ 'Authorization': 'Bearer secret',
143
+ 'Content-Type': 'application/json',
144
+ };
145
+ const filtered = filterSensitiveHeaders(headers);
146
+ expect(filtered).toEqual({ 'Content-Type': 'application/json' });
147
+ });
148
+ });
149
+
150
+ // ── redactUrl ───────────────────────────────────────────────────────
151
+ describe('redactUrl', () => {
152
+ it('redacts password in https://user:secret@host.com', () => {
153
+ expect(redactUrl('https://user:secret@host.com/path')).toBe('https://user:****@host.com/path');
154
+ });
155
+
156
+ it('is no-op without credentials', () => {
157
+ expect(redactUrl('https://host.com/path')).toBe('https://host.com/path');
158
+ });
159
+
160
+ it('redacts in http URLs', () => {
161
+ expect(redactUrl('http://admin:p4ss@localhost:3000')).toBe('http://admin:****@localhost:3000');
162
+ });
163
+ });
164
+
165
+ // ── isValidHostname ─────────────────────────────────────────────────
166
+ describe('isValidHostname', () => {
167
+ it('rejects empty strings', () => {
168
+ expect(isValidHostname('')).toBe(false);
169
+ });
170
+
171
+ it('rejects strings with whitespace', () => {
172
+ expect(isValidHostname('host name.com')).toBe(false);
173
+ expect(isValidHostname('host\tname')).toBe(false);
174
+ });
175
+
176
+ it('rejects strings with slashes', () => {
177
+ expect(isValidHostname('host/path')).toBe(false);
178
+ expect(isValidHostname('host\\path')).toBe(false);
179
+ });
180
+
181
+ it('accepts valid hostnames', () => {
182
+ expect(isValidHostname('example.com')).toBe(true);
183
+ expect(isValidHostname('sub.example.com')).toBe(true);
184
+ expect(isValidHostname('localhost')).toBe(true);
185
+ });
186
+ });
187
+
188
+ // ── MAX_SKILL_INPUT_LENGTH ──────────────────────────────────────────
189
+ it('MAX_SKILL_INPUT_LENGTH is 1000', () => {
190
+ expect(MAX_SKILL_INPUT_LENGTH).toBe(1000);
191
+ });
192
+ });
@@ -0,0 +1,222 @@
1
+ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
2
+ import { ServerlessAdapter } from '../src/ServerlessAdapter.js';
3
+ import { AgentBase } from '../src/AgentBase.js';
4
+ import { FunctionResult } from '../src/FunctionResult.js';
5
+ import { suppressAllLogs } from '../src/Logger.js';
6
+
7
+ describe('ServerlessAdapter', () => {
8
+ beforeEach(() => suppressAllLogs(true));
9
+ afterEach(() => suppressAllLogs(false));
10
+
11
+ it('detectPlatform returns lambda for AWS env', () => {
12
+ const saved = process.env['AWS_LAMBDA_FUNCTION_NAME'];
13
+ process.env['AWS_LAMBDA_FUNCTION_NAME'] = 'my-func';
14
+ try {
15
+ const adapter = new ServerlessAdapter('auto');
16
+ expect(adapter.getPlatform()).toBe('lambda');
17
+ } finally {
18
+ if (saved) process.env['AWS_LAMBDA_FUNCTION_NAME'] = saved;
19
+ else delete process.env['AWS_LAMBDA_FUNCTION_NAME'];
20
+ }
21
+ });
22
+
23
+ it('detectPlatform returns gcf for Google env', () => {
24
+ const saved = process.env['FUNCTION_TARGET'];
25
+ process.env['FUNCTION_TARGET'] = 'handler';
26
+ try {
27
+ const adapter = new ServerlessAdapter('auto');
28
+ expect(adapter.getPlatform()).toBe('gcf');
29
+ } finally {
30
+ if (saved) process.env['FUNCTION_TARGET'] = saved;
31
+ else delete process.env['FUNCTION_TARGET'];
32
+ }
33
+ });
34
+
35
+ it('explicit platform overrides detection', () => {
36
+ const adapter = new ServerlessAdapter('azure');
37
+ expect(adapter.getPlatform()).toBe('azure');
38
+ });
39
+
40
+ it('handleRequest routes through Hono app', async () => {
41
+ const agent = new AgentBase({ name: 'test', route: '/', basicAuth: ['u', 'p'] });
42
+ agent.setPromptText('hello');
43
+ const app = agent.getApp();
44
+ const adapter = new ServerlessAdapter('lambda');
45
+
46
+ const response = await adapter.handleRequest(app, {
47
+ httpMethod: 'GET',
48
+ path: '/health',
49
+ headers: { host: 'localhost' },
50
+ });
51
+
52
+ expect(response.statusCode).toBe(200);
53
+ const body = JSON.parse(response.body);
54
+ expect(body.status).toBe('ok');
55
+ });
56
+
57
+ it('handleRequest passes POST body', async () => {
58
+ const agent = new AgentBase({ name: 'test', route: '/', basicAuth: ['u', 'p'] });
59
+ agent.setPromptText('hello');
60
+ agent.defineTool({
61
+ name: 'echo',
62
+ description: 'Echo back',
63
+ parameters: { msg: { type: 'string' } },
64
+ handler: (args) => new FunctionResult(`Echo: ${args['msg']}`),
65
+ });
66
+ const app = agent.getApp();
67
+ const adapter = new ServerlessAdapter('lambda');
68
+
69
+ const response = await adapter.handleRequest(app, {
70
+ httpMethod: 'POST',
71
+ path: '/swaig',
72
+ headers: {
73
+ host: 'localhost',
74
+ 'content-type': 'application/json',
75
+ authorization: 'Basic ' + Buffer.from('u:p').toString('base64'),
76
+ },
77
+ body: JSON.stringify({ function: 'echo', argument: { msg: 'hi' } }),
78
+ });
79
+
80
+ expect(response.statusCode).toBe(200);
81
+ const body = JSON.parse(response.body);
82
+ expect(body.response).toContain('Echo: hi');
83
+ });
84
+
85
+ it('handleRequest handles query parameters', async () => {
86
+ const agent = new AgentBase({ name: 'test', route: '/', basicAuth: ['u', 'p'] });
87
+ agent.setPromptText('hello');
88
+ const app = agent.getApp();
89
+ const adapter = new ServerlessAdapter('lambda');
90
+
91
+ const response = await adapter.handleRequest(app, {
92
+ httpMethod: 'GET',
93
+ path: '/health',
94
+ headers: { host: 'localhost' },
95
+ queryStringParameters: { foo: 'bar' },
96
+ });
97
+
98
+ expect(response.statusCode).toBe(200);
99
+ });
100
+
101
+ it('generateUrl produces Lambda URL', () => {
102
+ const adapter = new ServerlessAdapter('lambda');
103
+ const url = adapter.generateUrl({ region: 'us-west-2', apiId: 'abc123', stage: 'dev' });
104
+ expect(url).toContain('us-west-2');
105
+ expect(url).toContain('abc123');
106
+ expect(url).toContain('dev');
107
+ });
108
+
109
+ it('generateUrl produces GCF URL', () => {
110
+ const adapter = new ServerlessAdapter('gcf');
111
+ const url = adapter.generateUrl({ projectId: 'my-proj', region: 'us-central1', functionName: 'agent' });
112
+ expect(url).toContain('my-proj');
113
+ expect(url).toContain('us-central1');
114
+ expect(url).toContain('agent');
115
+ });
116
+
117
+ it('generateUrl produces Azure URL', () => {
118
+ const adapter = new ServerlessAdapter('azure');
119
+ const url = adapter.generateUrl({ functionName: 'my-agent' });
120
+ expect(url).toContain('my-agent');
121
+ expect(url).toContain('azurewebsites.net');
122
+ });
123
+
124
+ it('generateUrl produces CGI URL', () => {
125
+ const adapter = new ServerlessAdapter('cgi');
126
+ const url = adapter.generateUrl({ functionName: 'agent' });
127
+ expect(url).toContain('cgi-bin');
128
+ });
129
+
130
+ it('createLambdaHandler returns a function', () => {
131
+ const agent = new AgentBase({ name: 'test', route: '/', basicAuth: ['u', 'p'] });
132
+ const handler = ServerlessAdapter.createLambdaHandler(agent.getApp());
133
+ expect(typeof handler).toBe('function');
134
+ });
135
+
136
+ it('Lambda handler processes requests', async () => {
137
+ const agent = new AgentBase({ name: 'test', route: '/', basicAuth: ['u', 'p'] });
138
+ agent.setPromptText('hello');
139
+ const handler = ServerlessAdapter.createLambdaHandler(agent.getApp());
140
+
141
+ const response = await handler({
142
+ httpMethod: 'GET',
143
+ path: '/health',
144
+ headers: { host: 'localhost' },
145
+ });
146
+
147
+ expect(response.statusCode).toBe(200);
148
+ });
149
+
150
+ it('handleRequest uses rawPath if available', async () => {
151
+ const agent = new AgentBase({ name: 'test', route: '/', basicAuth: ['u', 'p'] });
152
+ agent.setPromptText('hello');
153
+ const app = agent.getApp();
154
+ const adapter = new ServerlessAdapter('lambda');
155
+
156
+ const response = await adapter.handleRequest(app, {
157
+ httpMethod: 'GET',
158
+ rawPath: '/health',
159
+ headers: { host: 'localhost' },
160
+ });
161
+
162
+ expect(response.statusCode).toBe(200);
163
+ });
164
+
165
+ it('handleRequest defaults to POST method', async () => {
166
+ const agent = new AgentBase({ name: 'test', route: '/', basicAuth: ['u', 'p'] });
167
+ agent.setPromptText('hello');
168
+ const app = agent.getApp();
169
+ const adapter = new ServerlessAdapter('lambda');
170
+
171
+ // No httpMethod specified
172
+ const response = await adapter.handleRequest(app, {
173
+ path: '/',
174
+ headers: {
175
+ host: 'localhost',
176
+ authorization: 'Basic ' + Buffer.from('u:p').toString('base64'),
177
+ 'content-type': 'application/json',
178
+ },
179
+ body: '{}',
180
+ });
181
+
182
+ expect(response.statusCode).toBe(200);
183
+ });
184
+
185
+ it('response includes headers', async () => {
186
+ const agent = new AgentBase({ name: 'test', route: '/', basicAuth: ['u', 'p'] });
187
+ agent.setPromptText('hello');
188
+ const app = agent.getApp();
189
+ const adapter = new ServerlessAdapter('lambda');
190
+
191
+ const response = await adapter.handleRequest(app, {
192
+ httpMethod: 'GET',
193
+ path: '/health',
194
+ headers: { host: 'localhost' },
195
+ });
196
+
197
+ expect(response.headers).toBeDefined();
198
+ expect(response.headers['content-type']).toContain('application/json');
199
+ });
200
+
201
+ it('env var AWS_LAMBDA_FUNCTION_URL takes precedence over host header', async () => {
202
+ const saved = process.env['AWS_LAMBDA_FUNCTION_URL'];
203
+ process.env['AWS_LAMBDA_FUNCTION_URL'] = 'https://lambda-func.on.aws/';
204
+ try {
205
+ const agent = new AgentBase({ name: 'test', route: '/', basicAuth: ['u', 'p'] });
206
+ agent.setPromptText('hello');
207
+ const app = agent.getApp();
208
+ const adapter = new ServerlessAdapter('lambda');
209
+
210
+ const response = await adapter.handleRequest(app, {
211
+ httpMethod: 'GET',
212
+ path: '/health',
213
+ headers: { host: 'attacker-controlled.com' },
214
+ });
215
+ // Should still work (health endpoint)
216
+ expect(response.statusCode).toBe(200);
217
+ } finally {
218
+ if (saved) process.env['AWS_LAMBDA_FUNCTION_URL'] = saved;
219
+ else delete process.env['AWS_LAMBDA_FUNCTION_URL'];
220
+ }
221
+ });
222
+ });