@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,523 @@
1
+ import { describe, it, expect } from 'vitest';
2
+ import { SWMLVerbHandler, AIVerbHandler, VerbHandlerRegistry } from '../src/SWMLHandler.js';
3
+
4
+ // ---------- Mock handler for testing the abstract interface ----------
5
+
6
+ class MockVerbHandler extends SWMLVerbHandler {
7
+ private verbName: string;
8
+
9
+ constructor(verbName = 'mock_verb') {
10
+ super();
11
+ this.verbName = verbName;
12
+ }
13
+
14
+ getVerbName(): string {
15
+ return this.verbName;
16
+ }
17
+
18
+ validateConfig(config: Record<string, unknown>): [boolean, string[]] {
19
+ if (!('required_field' in config)) {
20
+ return [false, ['Missing required_field']];
21
+ }
22
+ return [true, []];
23
+ }
24
+
25
+ buildConfig(opts: Record<string, unknown>): Record<string, unknown> {
26
+ return { mock_config: true, ...opts };
27
+ }
28
+ }
29
+
30
+ // ======================== SWMLVerbHandler (abstract) ========================
31
+
32
+ describe('SWMLVerbHandler', () => {
33
+ it('cannot be instantiated directly', () => {
34
+ // TypeScript prevents this at compile time, but verify at runtime that
35
+ // the abstract class's concrete subclass works.
36
+ const handler = new MockVerbHandler('test_verb');
37
+ expect(handler.getVerbName()).toBe('test_verb');
38
+ });
39
+
40
+ it('mock implementation validates config correctly', () => {
41
+ const handler = new MockVerbHandler();
42
+
43
+ const [valid, errors] = handler.validateConfig({ required_field: 'value' });
44
+ expect(valid).toBe(true);
45
+ expect(errors).toHaveLength(0);
46
+
47
+ const [invalid, errs] = handler.validateConfig({ other_field: 'value' });
48
+ expect(invalid).toBe(false);
49
+ expect(errs).toContain('Missing required_field');
50
+ });
51
+
52
+ it('mock implementation builds config', () => {
53
+ const handler = new MockVerbHandler();
54
+ const config = handler.buildConfig({ param1: 'value1', param2: 'value2' });
55
+ expect(config['mock_config']).toBe(true);
56
+ expect(config['param1']).toBe('value1');
57
+ expect(config['param2']).toBe('value2');
58
+ });
59
+ });
60
+
61
+ // ======================== AIVerbHandler ========================
62
+
63
+ describe('AIVerbHandler', () => {
64
+ it('returns "ai" as verb name', () => {
65
+ const handler = new AIVerbHandler();
66
+ expect(handler.getVerbName()).toBe('ai');
67
+ });
68
+
69
+ // ---------- validateConfig ----------
70
+
71
+ describe('validateConfig', () => {
72
+ it('accepts valid prompt text configuration', () => {
73
+ const handler = new AIVerbHandler();
74
+ const [valid, errors] = handler.validateConfig({
75
+ prompt: { text: 'You are a helpful assistant' },
76
+ });
77
+ expect(valid).toBe(true);
78
+ expect(errors).toHaveLength(0);
79
+ });
80
+
81
+ it('accepts valid prompt POM configuration', () => {
82
+ const handler = new AIVerbHandler();
83
+ const [valid, errors] = handler.validateConfig({
84
+ prompt: {
85
+ pom: [
86
+ { title: 'Section 1', body: 'Content 1' },
87
+ { title: 'Section 2', body: 'Content 2' },
88
+ ],
89
+ },
90
+ });
91
+ expect(valid).toBe(true);
92
+ expect(errors).toHaveLength(0);
93
+ });
94
+
95
+ it('rejects contexts-only config (needs text or pom base prompt)', () => {
96
+ const handler = new AIVerbHandler();
97
+ const [valid, errors] = handler.validateConfig({
98
+ prompt: {
99
+ contexts: {
100
+ context1: { steps: [{ step: 'greeting', content: 'Hello' }] },
101
+ },
102
+ },
103
+ });
104
+ expect(valid).toBe(false);
105
+ expect(errors).toContain("'prompt' must contain either 'text' or 'pom' as base prompt");
106
+ });
107
+
108
+ it('accepts text combined with contexts', () => {
109
+ const handler = new AIVerbHandler();
110
+ const [valid, errors] = handler.validateConfig({
111
+ prompt: {
112
+ text: 'You are a helpful assistant',
113
+ contexts: {
114
+ context1: { steps: [{ step: 'greeting', content: 'Hello' }] },
115
+ },
116
+ },
117
+ });
118
+ expect(valid).toBe(true);
119
+ expect(errors).toHaveLength(0);
120
+ });
121
+
122
+ it('rejects missing prompt', () => {
123
+ const handler = new AIVerbHandler();
124
+ const [valid, errors] = handler.validateConfig({
125
+ post_prompt: { text: 'Summary' },
126
+ });
127
+ expect(valid).toBe(false);
128
+ expect(errors).toContain("Missing required field 'prompt'");
129
+ });
130
+
131
+ it('rejects both text and pom', () => {
132
+ const handler = new AIVerbHandler();
133
+ const [valid, errors] = handler.validateConfig({
134
+ prompt: { text: 'You are helpful', pom: [{ title: 'Section' }] },
135
+ });
136
+ expect(valid).toBe(false);
137
+ expect(errors).toContain(
138
+ "'prompt' can only contain one of: 'text' or 'pom' (mutually exclusive)",
139
+ );
140
+ });
141
+
142
+ it('rejects non-object prompt', () => {
143
+ const handler = new AIVerbHandler();
144
+ const [valid, errors] = handler.validateConfig({
145
+ prompt: 'invalid_string_prompt',
146
+ });
147
+ expect(valid).toBe(false);
148
+ expect(errors).toContain("'prompt' must be an object");
149
+ });
150
+
151
+ it('rejects prompt dict with no valid content keys', () => {
152
+ const handler = new AIVerbHandler();
153
+ const [valid, errors] = handler.validateConfig({
154
+ prompt: { other_field: 'value' },
155
+ });
156
+ expect(valid).toBe(false);
157
+ expect(errors).toContain("'prompt' must contain either 'text' or 'pom' as base prompt");
158
+ });
159
+
160
+ it('rejects non-object contexts', () => {
161
+ const handler = new AIVerbHandler();
162
+ const [valid, errors] = handler.validateConfig({
163
+ prompt: { text: 'hi', contexts: 'invalid_string_contexts' },
164
+ });
165
+ expect(valid).toBe(false);
166
+ expect(errors).toContain("'prompt.contexts' must be an object");
167
+ });
168
+
169
+ it('rejects non-object SWAIG', () => {
170
+ const handler = new AIVerbHandler();
171
+ const [valid, errors] = handler.validateConfig({
172
+ prompt: { text: 'hi' },
173
+ SWAIG: 'invalid',
174
+ });
175
+ expect(valid).toBe(false);
176
+ expect(errors).toContain("'SWAIG' must be an object");
177
+ });
178
+
179
+ it('rejects array prompt', () => {
180
+ const handler = new AIVerbHandler();
181
+ const [valid, errors] = handler.validateConfig({
182
+ prompt: ['not', 'an', 'object'],
183
+ });
184
+ expect(valid).toBe(false);
185
+ expect(errors).toContain("'prompt' must be an object");
186
+ });
187
+
188
+ it('rejects array SWAIG', () => {
189
+ const handler = new AIVerbHandler();
190
+ const [valid, errors] = handler.validateConfig({
191
+ prompt: { text: 'hi' },
192
+ SWAIG: ['not', 'an', 'object'],
193
+ });
194
+ expect(valid).toBe(false);
195
+ expect(errors).toContain("'SWAIG' must be an object");
196
+ });
197
+ });
198
+
199
+ // ---------- buildConfig ----------
200
+
201
+ describe('buildConfig', () => {
202
+ it('builds config with prompt text', () => {
203
+ const handler = new AIVerbHandler();
204
+ const config = handler.buildConfig({
205
+ promptText: 'You are a helpful assistant',
206
+ postPrompt: 'Provide a summary',
207
+ postPromptUrl: 'https://example.com/summary',
208
+ });
209
+
210
+ expect((config['prompt'] as Record<string, unknown>)['text']).toBe(
211
+ 'You are a helpful assistant',
212
+ );
213
+ expect((config['post_prompt'] as Record<string, unknown>)['text']).toBe(
214
+ 'Provide a summary',
215
+ );
216
+ expect(config['post_prompt_url']).toBe('https://example.com/summary');
217
+ });
218
+
219
+ it('builds config with prompt POM', () => {
220
+ const handler = new AIVerbHandler();
221
+ const pomData = [
222
+ { title: 'Section 1', body: 'Content 1' },
223
+ { title: 'Section 2', body: 'Content 2' },
224
+ ];
225
+ const config = handler.buildConfig({
226
+ promptPom: pomData,
227
+ postPrompt: 'Summary',
228
+ });
229
+
230
+ expect((config['prompt'] as Record<string, unknown>)['pom']).toEqual(pomData);
231
+ expect((config['post_prompt'] as Record<string, unknown>)['text']).toBe('Summary');
232
+ });
233
+
234
+ it('builds config with text and contexts combined', () => {
235
+ const handler = new AIVerbHandler();
236
+ const contextsData = {
237
+ context1: { steps: [{ step: 'greeting', content: 'Hello' }] },
238
+ };
239
+ const config = handler.buildConfig({
240
+ promptText: 'You are a helpful assistant',
241
+ contexts: contextsData,
242
+ postPrompt: 'Summary',
243
+ });
244
+
245
+ const prompt = config['prompt'] as Record<string, unknown>;
246
+ expect(prompt['text']).toBe('You are a helpful assistant');
247
+ expect(prompt['contexts']).toEqual(contextsData);
248
+ expect((config['post_prompt'] as Record<string, unknown>)['text']).toBe('Summary');
249
+ });
250
+
251
+ it('builds config with SWAIG', () => {
252
+ const handler = new AIVerbHandler();
253
+ const swaigData = {
254
+ functions: [{ function: 'test_func', description: 'Test function' }],
255
+ };
256
+ const config = handler.buildConfig({
257
+ promptText: 'You are helpful',
258
+ swaig: swaigData,
259
+ });
260
+
261
+ expect((config['prompt'] as Record<string, unknown>)['text']).toBe('You are helpful');
262
+ expect(config['SWAIG']).toEqual(swaigData);
263
+ });
264
+
265
+ it('builds minimal config', () => {
266
+ const handler = new AIVerbHandler();
267
+ const config = handler.buildConfig({ promptText: 'Hello' });
268
+
269
+ expect((config['prompt'] as Record<string, unknown>)['text']).toBe('Hello');
270
+ expect(config['post_prompt']).toBeUndefined();
271
+ expect(config['post_prompt_url']).toBeUndefined();
272
+ expect(config['SWAIG']).toBeUndefined();
273
+ });
274
+
275
+ it('throws when no prompt option is provided', () => {
276
+ const handler = new AIVerbHandler();
277
+ expect(() => handler.buildConfig({})).toThrow(
278
+ 'Either promptText or promptPom must be provided as base prompt',
279
+ );
280
+ });
281
+
282
+ it('throws when both promptText and promptPom are provided', () => {
283
+ const handler = new AIVerbHandler();
284
+ expect(() =>
285
+ handler.buildConfig({
286
+ promptText: 'Text prompt',
287
+ promptPom: [{ title: 'POM section' }],
288
+ }),
289
+ ).toThrow('promptText and promptPom are mutually exclusive');
290
+ });
291
+
292
+ it('allows combining text with contexts', () => {
293
+ const handler = new AIVerbHandler();
294
+ const config = handler.buildConfig({
295
+ promptText: 'Text prompt',
296
+ contexts: { context1: { steps: [] } },
297
+ });
298
+
299
+ const prompt = config['prompt'] as Record<string, unknown>;
300
+ expect(prompt['text']).toBe('Text prompt');
301
+ expect(prompt['contexts']).toEqual({ context1: { steps: [] } });
302
+ });
303
+
304
+ it('routes top-level kwargs correctly', () => {
305
+ const handler = new AIVerbHandler();
306
+ const config = handler.buildConfig({
307
+ promptText: 'Hello',
308
+ languages: ['en', 'es'],
309
+ hints: ['hint1', 'hint2'],
310
+ pronounce: { word: 'pronunciation' },
311
+ global_data: { key: 'value' },
312
+ custom_param: 'custom_value',
313
+ });
314
+
315
+ expect((config['prompt'] as Record<string, unknown>)['text']).toBe('Hello');
316
+ expect(config['languages']).toEqual(['en', 'es']);
317
+ expect(config['hints']).toEqual(['hint1', 'hint2']);
318
+ expect(config['pronounce']).toEqual({ word: 'pronunciation' });
319
+ expect(config['global_data']).toEqual({ key: 'value' });
320
+ expect((config['params'] as Record<string, unknown>)['custom_param']).toBe('custom_value');
321
+ });
322
+
323
+ it('routes globalData (camelCase) to global_data (snake_case)', () => {
324
+ const handler = new AIVerbHandler();
325
+ const config = handler.buildConfig({
326
+ promptText: 'Hello',
327
+ globalData: { key: 'value' },
328
+ });
329
+
330
+ expect(config['global_data']).toEqual({ key: 'value' });
331
+ expect(config['globalData']).toBeUndefined();
332
+ });
333
+
334
+ it('handles None-equivalent values gracefully', () => {
335
+ const handler = new AIVerbHandler();
336
+ const config = handler.buildConfig({
337
+ promptText: 'Test',
338
+ postPrompt: undefined,
339
+ postPromptUrl: undefined,
340
+ swaig: undefined,
341
+ });
342
+
343
+ expect((config['prompt'] as Record<string, unknown>)['text']).toBe('Test');
344
+ expect(config['post_prompt']).toBeUndefined();
345
+ expect(config['post_prompt_url']).toBeUndefined();
346
+ expect(config['SWAIG']).toBeUndefined();
347
+ });
348
+
349
+ it('handles empty string values', () => {
350
+ const handler = new AIVerbHandler();
351
+ const config = handler.buildConfig({
352
+ promptText: '',
353
+ postPrompt: '',
354
+ postPromptUrl: '',
355
+ });
356
+
357
+ expect((config['prompt'] as Record<string, unknown>)['text']).toBe('');
358
+ expect((config['post_prompt'] as Record<string, unknown>)['text']).toBe('');
359
+ expect(config['post_prompt_url']).toBe('');
360
+ });
361
+
362
+ it('always initializes params dict (matching Python behavior)', () => {
363
+ const handler = new AIVerbHandler();
364
+ const config = handler.buildConfig({ promptText: 'Hello' });
365
+ expect(config['params']).toEqual({});
366
+ });
367
+ });
368
+
369
+ // ---------- Integration: build then validate ----------
370
+
371
+ describe('build + validate integration', () => {
372
+ it('validates a fully built config', () => {
373
+ const handler = new AIVerbHandler();
374
+ const config = handler.buildConfig({
375
+ promptText: 'You are a helpful assistant',
376
+ postPrompt: 'Provide a brief summary',
377
+ postPromptUrl: 'https://example.com/summary',
378
+ swaig: {
379
+ functions: [
380
+ {
381
+ function: 'get_weather',
382
+ description: 'Get weather information',
383
+ parameters: { type: 'object', properties: {} },
384
+ },
385
+ ],
386
+ },
387
+ });
388
+
389
+ const [valid, errors] = handler.validateConfig(config);
390
+ expect(valid).toBe(true);
391
+ expect(errors).toHaveLength(0);
392
+ });
393
+
394
+ it('validates a complex SWAIG config', () => {
395
+ const handler = new AIVerbHandler();
396
+ const complexSwaig = {
397
+ defaults: { web_hook_url: 'https://example.com/webhook' },
398
+ functions: [
399
+ {
400
+ function: 'search',
401
+ description: 'Search for information',
402
+ parameters: {
403
+ type: 'object',
404
+ properties: { query: { type: 'string', description: 'Search query' } },
405
+ required: ['query'],
406
+ },
407
+ fillers: { en: ['Searching...', 'Looking that up...'] },
408
+ },
409
+ {
410
+ function: 'calculate',
411
+ description: 'Perform calculations',
412
+ parameters: {
413
+ type: 'object',
414
+ properties: { expression: { type: 'string', description: 'Math expression' } },
415
+ },
416
+ },
417
+ ],
418
+ includes: [{ url: 'https://api.example.com/functions', functions: ['external_func1'] }],
419
+ };
420
+
421
+ const config = handler.buildConfig({
422
+ promptText: 'You are a calculator and search assistant',
423
+ swaig: complexSwaig,
424
+ });
425
+
426
+ const [valid, errors] = handler.validateConfig(config);
427
+ expect(valid).toBe(true);
428
+ expect(errors).toHaveLength(0);
429
+ expect(config['SWAIG']).toEqual(complexSwaig);
430
+ });
431
+
432
+ it('catches various invalid configurations', () => {
433
+ const handler = new AIVerbHandler();
434
+ const invalidConfigs: Record<string, unknown>[] = [
435
+ {},
436
+ { prompt: {} },
437
+ { prompt: { invalid: 'field' } },
438
+ { prompt: { text: 'test', pom: [] } },
439
+ ];
440
+
441
+ for (const config of invalidConfigs) {
442
+ const [valid, errors] = handler.validateConfig(config);
443
+ expect(valid).toBe(false);
444
+ expect(errors.length).toBeGreaterThan(0);
445
+ }
446
+ });
447
+ });
448
+ });
449
+
450
+ // ======================== VerbHandlerRegistry ========================
451
+
452
+ describe('VerbHandlerRegistry', () => {
453
+ it('registers AIVerbHandler by default', () => {
454
+ const registry = new VerbHandlerRegistry();
455
+ expect(registry.hasHandler('ai')).toBe(true);
456
+ const handler = registry.getHandler('ai');
457
+ expect(handler).toBeInstanceOf(AIVerbHandler);
458
+ });
459
+
460
+ it('registers a custom handler', () => {
461
+ const registry = new VerbHandlerRegistry();
462
+ const mockHandler = new MockVerbHandler('custom_verb');
463
+ registry.registerHandler(mockHandler);
464
+ expect(registry.hasHandler('custom_verb')).toBe(true);
465
+ expect(registry.getHandler('custom_verb')).toBe(mockHandler);
466
+ });
467
+
468
+ it('returns undefined for unregistered verb', () => {
469
+ const registry = new VerbHandlerRegistry();
470
+ expect(registry.getHandler('nonexistent')).toBeUndefined();
471
+ expect(registry.hasHandler('nonexistent')).toBe(false);
472
+ });
473
+
474
+ it('allows overriding the default AI handler', () => {
475
+ const registry = new VerbHandlerRegistry();
476
+ const customAI = new MockVerbHandler('ai');
477
+ registry.registerHandler(customAI);
478
+ expect(registry.getHandler('ai')).toBe(customAI);
479
+ expect(registry.getHandler('ai')).toBeInstanceOf(MockVerbHandler);
480
+ });
481
+
482
+ it('supports multiple handlers simultaneously', () => {
483
+ const registry = new VerbHandlerRegistry();
484
+ const h1 = new MockVerbHandler('verb1');
485
+ const h2 = new MockVerbHandler('verb2');
486
+ const h3 = new MockVerbHandler('verb3');
487
+
488
+ registry.registerHandler(h1);
489
+ registry.registerHandler(h2);
490
+ registry.registerHandler(h3);
491
+
492
+ expect(registry.hasHandler('verb1')).toBe(true);
493
+ expect(registry.hasHandler('verb2')).toBe(true);
494
+ expect(registry.hasHandler('verb3')).toBe(true);
495
+ expect(registry.hasHandler('ai')).toBe(true); // default still there
496
+
497
+ expect(registry.getHandler('verb1')).toBe(h1);
498
+ expect(registry.getHandler('verb2')).toBe(h2);
499
+ expect(registry.getHandler('verb3')).toBe(h3);
500
+ });
501
+
502
+ it('registry + handler complete workflow', () => {
503
+ const registry = new VerbHandlerRegistry();
504
+ const playHandler = new MockVerbHandler('play');
505
+ registry.registerHandler(playHandler);
506
+
507
+ for (const verbName of ['ai', 'play']) {
508
+ expect(registry.hasHandler(verbName)).toBe(true);
509
+ const handler = registry.getHandler(verbName)!;
510
+ expect(handler).toBeDefined();
511
+
512
+ if (verbName === 'ai') {
513
+ const config = handler.buildConfig({ promptText: 'Test' });
514
+ const [valid] = handler.validateConfig(config);
515
+ expect(valid).toBe(true);
516
+ } else {
517
+ const config = handler.buildConfig({ required_field: 'test' });
518
+ const [valid] = handler.validateConfig(config);
519
+ expect(valid).toBe(true);
520
+ }
521
+ }
522
+ });
523
+ });
@@ -0,0 +1,106 @@
1
+ import { describe, it, expect } from 'vitest';
2
+ import { SchemaUtils } from '../src/SchemaUtils.js';
3
+
4
+ describe('SchemaUtils', () => {
5
+ it('validates a minimal valid SWML document', () => {
6
+ const validator = new SchemaUtils();
7
+ const result = validator.validate({
8
+ version: '1.0.0',
9
+ sections: { main: [] },
10
+ });
11
+ expect(result.valid).toBe(true);
12
+ expect(result.errors).toHaveLength(0);
13
+ });
14
+
15
+ it('rejects missing version', () => {
16
+ const validator = new SchemaUtils();
17
+ const result = validator.validate({ sections: { main: [] } });
18
+ expect(result.valid).toBe(false);
19
+ expect(result.errors.some(e => e.includes('version'))).toBe(true);
20
+ });
21
+
22
+ it('rejects missing sections', () => {
23
+ const validator = new SchemaUtils();
24
+ const result = validator.validate({ version: '1.0.0' });
25
+ expect(result.valid).toBe(false);
26
+ expect(result.errors.some(e => e.includes('sections'))).toBe(true);
27
+ });
28
+
29
+ it('rejects invalid version', () => {
30
+ const validator = new SchemaUtils();
31
+ const result = validator.validate({
32
+ version: '2.0.0',
33
+ sections: { main: [] },
34
+ });
35
+ expect(result.valid).toBe(false);
36
+ expect(result.errors.some(e => e.includes('Invalid version'))).toBe(true);
37
+ });
38
+
39
+ it('rejects missing main section', () => {
40
+ const validator = new SchemaUtils();
41
+ const result = validator.validate({
42
+ version: '1.0.0',
43
+ sections: { other: [] },
44
+ });
45
+ expect(result.valid).toBe(false);
46
+ expect(result.errors.some(e => e.includes('main'))).toBe(true);
47
+ });
48
+
49
+ it('validates SWML from JSON string', () => {
50
+ const validator = new SchemaUtils();
51
+ const result = validator.validate(JSON.stringify({
52
+ version: '1.0.0',
53
+ sections: { main: [{ answer: {} }] },
54
+ }));
55
+ expect(result.valid).toBe(true);
56
+ });
57
+
58
+ it('rejects invalid JSON string', () => {
59
+ const validator = new SchemaUtils();
60
+ const result = validator.validate('not json');
61
+ expect(result.valid).toBe(false);
62
+ expect(result.errors).toContain('Invalid JSON');
63
+ });
64
+
65
+ it('validates AI verb with prompt', () => {
66
+ const validator = new SchemaUtils();
67
+ const result = validator.validate({
68
+ version: '1.0.0',
69
+ sections: { main: [{ ai: { prompt: { text: 'Hello' } } }] },
70
+ });
71
+ expect(result.valid).toBe(true);
72
+ });
73
+
74
+ it('rejects AI verb with empty prompt', () => {
75
+ const validator = new SchemaUtils();
76
+ const result = validator.validate({
77
+ version: '1.0.0',
78
+ sections: { main: [{ ai: { prompt: {} } }] },
79
+ });
80
+ expect(result.valid).toBe(false);
81
+ expect(result.errors.some(e => e.includes('prompt'))).toBe(true);
82
+ });
83
+
84
+ it('caches validation results', () => {
85
+ const validator = new SchemaUtils();
86
+ const doc = JSON.stringify({ version: '1.0.0', sections: { main: [] } });
87
+ validator.validate(doc);
88
+ expect(validator.getCacheSize()).toBe(1);
89
+ validator.validate(doc); // should hit cache
90
+ expect(validator.getCacheSize()).toBe(1);
91
+ });
92
+
93
+ it('clearCache empties the cache', () => {
94
+ const validator = new SchemaUtils();
95
+ validator.validate({ version: '1.0.0', sections: { main: [] } });
96
+ expect(validator.getCacheSize()).toBe(1);
97
+ validator.clearCache();
98
+ expect(validator.getCacheSize()).toBe(0);
99
+ });
100
+
101
+ it('skipValidation always returns valid', () => {
102
+ const validator = new SchemaUtils({ skipValidation: true });
103
+ const result = validator.validate({ invalid: true } as any);
104
+ expect(result.valid).toBe(true);
105
+ });
106
+ });