@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,298 @@
1
+ /**
2
+ * SWMLHandler - SWML verb handler framework.
3
+ *
4
+ * Consolidates the abstract {@link SWMLVerbHandler} base class, the
5
+ * concrete {@link AIVerbHandler} for the SWML "ai" verb (including its
6
+ * {@link AIVerbBuildOptions} build signature), and the {@link VerbHandlerRegistry}
7
+ * that maps verb names to handler instances.
8
+ *
9
+ * Verb handlers provide specialized logic for complex SWML verbs that
10
+ * cannot be handled generically by the schema-driven SwmlBuilder.
11
+ * The "ai" verb is complex and requires specialized handling, particularly
12
+ * for managing prompts, SWAIG functions, and AI configurations.
13
+ *
14
+ * Register implementations via {@link VerbHandlerRegistry.registerHandler}.
15
+ *
16
+ * Mirrors Python SDK's single-file layout in
17
+ * `signalwire/signalwire/core/swml_handler.py`.
18
+ */
19
+
20
+ /**
21
+ * Abstract base class for pluggable SWML verb handlers.
22
+ *
23
+ * Each concrete handler owns one verb name and provides validate/build
24
+ * logic for that verb's configuration. Subclass this to create handlers
25
+ * for custom or complex SWML verbs that require specialized handling
26
+ * beyond generic schema-driven validation.
27
+ *
28
+ * @example
29
+ * ```ts
30
+ * class MyVerbHandler extends SWMLVerbHandler {
31
+ * getVerbName(): string { return 'my_verb'; }
32
+ * validateConfig(config: Record<string, unknown>): [boolean, string[]] {
33
+ * const errors: string[] = [];
34
+ * if (!config['url']) errors.push("Missing required field 'url'");
35
+ * return [errors.length === 0, errors];
36
+ * }
37
+ * buildConfig(opts: Record<string, unknown>): Record<string, unknown> {
38
+ * return { url: opts['url'] };
39
+ * }
40
+ * }
41
+ * ```
42
+ */
43
+ export abstract class SWMLVerbHandler {
44
+ /**
45
+ * Get the name of the SWML verb this handler handles.
46
+ * @returns The verb name as a string (e.g. "ai", "play").
47
+ */
48
+ abstract getVerbName(): string;
49
+
50
+ /**
51
+ * Validate the configuration for this verb.
52
+ * @param config - The configuration dictionary for this verb.
53
+ * @returns A `[isValid, errorMessages]` tuple where `isValid` is `true`
54
+ * when the config is valid and `errorMessages` lists any issues found.
55
+ */
56
+ abstract validateConfig(config: Record<string, unknown>): [boolean, string[]];
57
+
58
+ /**
59
+ * Build a configuration object for this verb from the provided arguments.
60
+ * @param opts - Key-value arguments specific to this verb.
61
+ * @returns A configuration dictionary ready for inclusion in a SWML document.
62
+ */
63
+ abstract buildConfig(opts: Record<string, unknown>): Record<string, unknown>;
64
+ }
65
+
66
+ /** Options accepted by {@link AIVerbHandler.buildConfig}. */
67
+ export interface AIVerbBuildOptions {
68
+ /** Text prompt for the AI (mutually exclusive with promptPom). */
69
+ promptText?: string;
70
+ /** POM structure for the AI prompt (mutually exclusive with promptText). */
71
+ promptPom?: Record<string, unknown>[];
72
+ /** Optional contexts and steps configuration (can be combined with text or pom). */
73
+ contexts?: Record<string, unknown>;
74
+ /** Optional post-prompt text. */
75
+ postPrompt?: string;
76
+ /** Optional URL for post-prompt processing. */
77
+ postPromptUrl?: string;
78
+ /** Optional SWAIG configuration. */
79
+ swaig?: Record<string, unknown>;
80
+ /** Additional AI parameters; see {@link AIVerbHandler.buildConfig} for routing rules. */
81
+ [key: string]: unknown;
82
+ }
83
+
84
+ /** Handler for the SWML 'ai' verb. */
85
+ export class AIVerbHandler extends SWMLVerbHandler {
86
+ /**
87
+ * Get the name of the verb this handler handles.
88
+ * @returns "ai" as the verb name.
89
+ */
90
+ getVerbName(): string {
91
+ return 'ai';
92
+ }
93
+
94
+ /**
95
+ * Validate the configuration for the AI verb.
96
+ *
97
+ * Checks that:
98
+ * - `prompt` is present and is an object
99
+ * - `prompt` contains exactly one of `text` or `pom` (mutually exclusive)
100
+ * - `prompt.contexts`, if present, is an object
101
+ * - `SWAIG`, if present, is an object
102
+ *
103
+ * @param config - The configuration dictionary for the AI verb.
104
+ * @returns A [isValid, errorMessages] tuple.
105
+ */
106
+ validateConfig(config: Record<string, unknown>): [boolean, string[]] {
107
+ const errors: string[] = [];
108
+
109
+ // Check that prompt is present
110
+ if (!('prompt' in config)) {
111
+ errors.push("Missing required field 'prompt'");
112
+ return [false, errors];
113
+ }
114
+
115
+ const prompt = config['prompt'];
116
+ if (typeof prompt !== 'object' || prompt === null || Array.isArray(prompt)) {
117
+ errors.push("'prompt' must be an object");
118
+ return [false, errors];
119
+ }
120
+
121
+ const p = prompt as Record<string, unknown>;
122
+
123
+ // Check that prompt contains either text or pom (required, mutually exclusive)
124
+ const hasText = 'text' in p;
125
+ const hasPom = 'pom' in p;
126
+ const hasContexts = 'contexts' in p;
127
+
128
+ const basePromptCount = [hasText, hasPom].filter(Boolean).length;
129
+ if (basePromptCount === 0) {
130
+ errors.push("'prompt' must contain either 'text' or 'pom' as base prompt");
131
+ } else if (basePromptCount > 1) {
132
+ errors.push("'prompt' can only contain one of: 'text' or 'pom' (mutually exclusive)");
133
+ }
134
+
135
+ // Contexts are optional and can be combined with text or pom
136
+ if (hasContexts) {
137
+ const contexts = p['contexts'];
138
+ if (typeof contexts !== 'object' || contexts === null || Array.isArray(contexts)) {
139
+ errors.push("'prompt.contexts' must be an object");
140
+ }
141
+ }
142
+
143
+ // Validate SWAIG structure if present
144
+ if ('SWAIG' in config) {
145
+ const swaig = config['SWAIG'];
146
+ if (typeof swaig !== 'object' || swaig === null || Array.isArray(swaig)) {
147
+ errors.push("'SWAIG' must be an object");
148
+ }
149
+ }
150
+
151
+ return [errors.length === 0, errors];
152
+ }
153
+
154
+ /**
155
+ * Build a configuration for the AI verb.
156
+ *
157
+ * Requires exactly one of `promptText` or `promptPom` (mutually exclusive).
158
+ * Throws an `Error` if both or neither are provided.
159
+ *
160
+ * Extra keys in `opts` are routed as follows:
161
+ * - `languages`, `hints`, `pronounce`, `globalData` / `global_data` are placed at the top level of the config.
162
+ * - All other extra keys are placed into `config.params`.
163
+ *
164
+ * @param opts - Build options for the AI verb configuration.
165
+ * @returns AI verb configuration dictionary.
166
+ */
167
+ buildConfig(opts: AIVerbBuildOptions = {}): Record<string, unknown> {
168
+ const {
169
+ promptText,
170
+ promptPom,
171
+ contexts,
172
+ postPrompt,
173
+ postPromptUrl,
174
+ swaig,
175
+ ...rest
176
+ } = opts;
177
+
178
+ const config: Record<string, unknown> = {};
179
+
180
+ // Require either text or pom as base prompt (mutually exclusive)
181
+ const basePromptCount = [promptText, promptPom].filter((v) => v !== undefined).length;
182
+ if (basePromptCount === 0) {
183
+ throw new Error('Either promptText or promptPom must be provided as base prompt');
184
+ } else if (basePromptCount > 1) {
185
+ throw new Error('promptText and promptPom are mutually exclusive');
186
+ }
187
+
188
+ // Build prompt object with base prompt
189
+ const promptConfig: Record<string, unknown> = {};
190
+ if (promptText !== undefined) {
191
+ promptConfig['text'] = promptText;
192
+ } else if (promptPom !== undefined) {
193
+ promptConfig['pom'] = promptPom;
194
+ }
195
+
196
+ // Add contexts if provided (optional, activates steps feature)
197
+ if (contexts !== undefined) {
198
+ promptConfig['contexts'] = contexts;
199
+ }
200
+
201
+ config['prompt'] = promptConfig;
202
+
203
+ // Add post-prompt if provided
204
+ if (postPrompt !== undefined) {
205
+ config['post_prompt'] = { text: postPrompt };
206
+ }
207
+
208
+ // Add post-prompt URL if provided
209
+ if (postPromptUrl !== undefined) {
210
+ config['post_prompt_url'] = postPromptUrl;
211
+ }
212
+
213
+ // Add SWAIG if provided
214
+ if (swaig !== undefined) {
215
+ config['SWAIG'] = swaig;
216
+ }
217
+
218
+ // Add any additional parameters
219
+ // Match Python behavior: always initialize params dict
220
+ if (!('params' in config)) {
221
+ config['params'] = {} as Record<string, unknown>;
222
+ }
223
+
224
+ const topLevelKeys = new Set(['languages', 'hints', 'pronounce', 'global_data', 'globalData']);
225
+ for (const [key, value] of Object.entries(rest)) {
226
+ if (topLevelKeys.has(key)) {
227
+ // Route globalData to the snake_case key expected by SWML
228
+ config[key === 'globalData' ? 'global_data' : key] = value;
229
+ } else {
230
+ // Add to params object
231
+ (config['params'] as Record<string, unknown>)[key] = value;
232
+ }
233
+ }
234
+
235
+ return config;
236
+ }
237
+ }
238
+
239
+ /**
240
+ * Registry for SWML verb handlers.
241
+ *
242
+ * This class maintains a registry of handlers for special SWML verbs
243
+ * and provides methods for accessing and using them. The "ai" verb handler
244
+ * ({@link AIVerbHandler}) is registered automatically on construction.
245
+ *
246
+ * @example
247
+ * ```ts
248
+ * const registry = new VerbHandlerRegistry();
249
+ *
250
+ * // The "ai" handler is already registered
251
+ * registry.hasHandler('ai'); // true
252
+ *
253
+ * // Register a custom handler
254
+ * registry.registerHandler(new MyCustomVerbHandler());
255
+ *
256
+ * // Look up a handler
257
+ * const handler = registry.getHandler('ai');
258
+ * if (handler) {
259
+ * const [valid, errors] = handler.validateConfig(config);
260
+ * }
261
+ * ```
262
+ */
263
+ export class VerbHandlerRegistry {
264
+ private handlers: Map<string, SWMLVerbHandler> = new Map();
265
+
266
+ /** Initialize the registry with default handlers. */
267
+ constructor() {
268
+ // Register default handlers (matches Python's __init__)
269
+ this.registerHandler(new AIVerbHandler());
270
+ }
271
+
272
+ /**
273
+ * Register a new verb handler, replacing any existing handler for the same verb name.
274
+ * @param handler - The handler to register.
275
+ */
276
+ registerHandler(handler: SWMLVerbHandler): void {
277
+ const verbName = handler.getVerbName();
278
+ this.handlers.set(verbName, handler);
279
+ }
280
+
281
+ /**
282
+ * Get the handler for a specific verb.
283
+ * @param verbName - The name of the verb (e.g. "ai").
284
+ * @returns The handler if found, or `undefined` otherwise.
285
+ */
286
+ getHandler(verbName: string): SWMLVerbHandler | undefined {
287
+ return this.handlers.get(verbName);
288
+ }
289
+
290
+ /**
291
+ * Check if a handler exists for a specific verb.
292
+ * @param verbName - The name of the verb.
293
+ * @returns `true` if a handler is registered for the verb, `false` otherwise.
294
+ */
295
+ hasHandler(verbName: string): boolean {
296
+ return this.handlers.has(verbName);
297
+ }
298
+ }