@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,322 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * generateVerbTypes.ts
4
+ *
5
+ * Build-time script that reads schema.json and generates SwmlVerbMethods.generated.ts.
6
+ * This provides TypeScript interface augmentation so IDE autocomplete works for all
7
+ * auto-vivified verb methods on SwmlBuilder.
8
+ *
9
+ * Usage: npx tsx src/generateVerbTypes.ts
10
+ */
11
+
12
+ import { readFileSync, writeFileSync } from 'fs';
13
+ import { join, dirname } from 'path';
14
+ import { fileURLToPath } from 'url';
15
+
16
+ const __filename = fileURLToPath(import.meta.url);
17
+ const __dirname = dirname(__filename);
18
+
19
+ interface SchemaProperty {
20
+ type?: string;
21
+ anyOf?: SchemaProperty[];
22
+ oneOf?: SchemaProperty[];
23
+ $ref?: string;
24
+ properties?: Record<string, SchemaProperty>;
25
+ required?: string[];
26
+ description?: string;
27
+ items?: SchemaProperty;
28
+ const?: unknown;
29
+ default?: unknown;
30
+ minimum?: number;
31
+ maximum?: number;
32
+ format?: string;
33
+ enum?: unknown[];
34
+ }
35
+
36
+ interface Schema {
37
+ $defs: Record<string, SchemaProperty>;
38
+ }
39
+
40
+ /**
41
+ * Map JSON Schema type to TypeScript type string.
42
+ * @param prop - The schema property to map.
43
+ * @param opts - Optional per-property overrides.
44
+ */
45
+ function mapType(prop: SchemaProperty, opts?: { widenStringEnum?: boolean }): string {
46
+ // Handle const values
47
+ if (prop.const !== undefined) {
48
+ // If the caller wants a widened string type, emit 'string' instead of the literal.
49
+ // Used for fields like hangup.reason where Python accepts any string.
50
+ if (opts?.widenStringEnum && typeof prop.const === 'string') return 'string';
51
+ return typeof prop.const === 'string' ? `'${prop.const}'` : String(prop.const);
52
+ }
53
+
54
+ // Handle $ref
55
+ if (prop.$ref) {
56
+ return 'unknown';
57
+ }
58
+
59
+ // Handle anyOf
60
+ if (prop.anyOf) {
61
+ // If wideningStringEnum, and every branch is a string const, collapse to 'string'
62
+ if (opts?.widenStringEnum && prop.anyOf.every(p => p.const !== undefined && typeof p.const === 'string')) {
63
+ return 'string';
64
+ }
65
+ const types = prop.anyOf
66
+ .map(p => mapType(p, opts))
67
+ .filter((t, i, arr) => arr.indexOf(t) === i); // deduplicate
68
+ // Filter out 'unknown' from SWMLVar refs if there are concrete types
69
+ const concreteTypes = types.filter(t => t !== 'unknown');
70
+ if (concreteTypes.length > 0) {
71
+ return concreteTypes.join(' | ');
72
+ }
73
+ return types.join(' | ');
74
+ }
75
+
76
+ // Handle oneOf
77
+ if (prop.oneOf) {
78
+ return 'Record<string, unknown>';
79
+ }
80
+
81
+ // Handle basic types
82
+ switch (prop.type) {
83
+ case 'string':
84
+ return 'string';
85
+ case 'integer':
86
+ case 'number':
87
+ return 'number';
88
+ case 'boolean':
89
+ return 'boolean';
90
+ case 'array':
91
+ if (prop.items) {
92
+ const itemType = mapType(prop.items);
93
+ return `${itemType}[]`;
94
+ }
95
+ return 'unknown[]';
96
+ case 'object':
97
+ if (prop.properties) {
98
+ return 'Record<string, unknown>';
99
+ }
100
+ return 'Record<string, unknown>';
101
+ default:
102
+ return 'unknown';
103
+ }
104
+ }
105
+
106
+ /**
107
+ * Properties that should be widened from a string-const enum to `string` in TypeScript.
108
+ * Python accepts any string for these; the schema's enum values are documentation-only hints.
109
+ * Keyed by verbName, value is the set of property names to widen.
110
+ */
111
+ const WIDEN_TO_STRING: Record<string, Set<string>> = {
112
+ // Python's SWMLService accepts any string for hangup.reason; the three schema values
113
+ // ('hangup', 'busy', 'decline') are the common platform values, not an exhaustive set.
114
+ hangup: new Set(['reason']),
115
+ };
116
+
117
+ /**
118
+ * Custom typed interface definitions for verbs whose schema shape (e.g., $ref or oneOf)
119
+ * cannot be fully expressed by the generic generateVerbConfig() logic.
120
+ *
121
+ * These interfaces match the Python SDK's named parameters for each verb:
122
+ * - AiVerbConfig mirrors: prompt_text, prompt_pom, post_prompt, post_prompt_url, swaig, **kwargs
123
+ * - PlayVerbConfig mirrors: url, urls, volume, say_voice, say_language, say_gender, auto_answer
124
+ *
125
+ * Keyed by verbName. interfaceName is emitted as a top-level export in the generated file;
126
+ * configType references that name; isOptional=true because all Python params are optional.
127
+ */
128
+ const CUSTOM_VERB_TYPES: Record<string, { interfaceName: string; interfaceBody: string; isOptional: boolean }> = {
129
+ ai: {
130
+ interfaceName: 'AiVerbConfig',
131
+ interfaceBody: [
132
+ ' /** Text prompt for the AI agent (mutually exclusive with prompt when using POM). */',
133
+ ' prompt?: string | Array<Record<string, unknown>>;',
134
+ ' /** Optional post-prompt text sent to the LLM after the conversation ends. */',
135
+ ' post_prompt?: string;',
136
+ ' /** URL to receive post-prompt status callbacks. */',
137
+ ' post_prompt_url?: string;',
138
+ ' /** SignalWire AI Gateway (SWAIG) configuration for custom function/tool definitions. */',
139
+ ' SWAIG?: Record<string, unknown>;',
140
+ ' /** Additional AI parameters passed through to the platform. */',
141
+ ' [key: string]: unknown;',
142
+ ].join('\n'),
143
+ isOptional: true,
144
+ },
145
+ play: {
146
+ interfaceName: 'PlayVerbConfig',
147
+ interfaceBody: [
148
+ ' /** Single URL to play (mutually exclusive with urls). */',
149
+ ' url?: string;',
150
+ ' /** Array of URLs to play (mutually exclusive with url). */',
151
+ ' urls?: string[];',
152
+ ' /** Volume level for audio playback. Valid range -40 to 40. Default 0. */',
153
+ ' volume?: number;',
154
+ ' /** Voice name to use for text-to-speech (e.g. "Polly.Joanna"). */',
155
+ ' say_voice?: string;',
156
+ ' /** Language code for text-to-speech (e.g. "en-US"). */',
157
+ ' say_language?: string;',
158
+ ' /** Gender for text-to-speech ("male" or "female"). */',
159
+ ' say_gender?: string;',
160
+ ' /** If true, auto-answer the call before playing audio. Default true. */',
161
+ ' auto_answer?: boolean;',
162
+ ].join('\n'),
163
+ isOptional: true,
164
+ },
165
+ };
166
+
167
+ /** Generate the interface for a verb's config parameter. */
168
+ function generateVerbConfig(
169
+ verbName: string,
170
+ innerSchema: SchemaProperty,
171
+ ): { configType: string; isOptional: boolean } {
172
+ // Some verbs have non-object inner types (e.g. "label" is a string, "sleep" is anyOf)
173
+ if (!innerSchema.type && !innerSchema.anyOf && !innerSchema.oneOf && !innerSchema.properties) {
174
+ // No type info at all (like "return") — accept any
175
+ return { configType: 'unknown', isOptional: true };
176
+ }
177
+
178
+ // String type (e.g. "label")
179
+ if (innerSchema.type === 'string') {
180
+ return { configType: 'string', isOptional: false };
181
+ }
182
+
183
+ // anyOf (e.g. "sleep" which accepts int or object)
184
+ if (innerSchema.anyOf && innerSchema.type !== 'object') {
185
+ return { configType: 'Record<string, unknown> | number', isOptional: false };
186
+ }
187
+
188
+ // oneOf with $ref (e.g. "play")
189
+ if (innerSchema.oneOf) {
190
+ return { configType: 'Record<string, unknown>', isOptional: false };
191
+ }
192
+
193
+ // Standard object with properties
194
+ if (innerSchema.type === 'object' && innerSchema.properties) {
195
+ const props = innerSchema.properties;
196
+ const required = new Set(innerSchema.required ?? []);
197
+ const widenProps = WIDEN_TO_STRING[verbName] ?? new Set<string>();
198
+ const lines: string[] = [];
199
+
200
+ for (const [propName, propDef] of Object.entries(props)) {
201
+ const tsType = mapType(propDef, { widenStringEnum: widenProps.has(propName) });
202
+ const opt = required.has(propName) ? '' : '?';
203
+ const desc = propDef.description
204
+ ? ` /** ${propDef.description.replace(/\n/g, ' ').replace(/\*\//g, '* /')} */\n `
205
+ : '';
206
+ lines.push(`${desc}${propName}${opt}: ${tsType}`);
207
+ }
208
+
209
+ if (lines.length === 0) {
210
+ // Object type but no props — accept empty config
211
+ return { configType: 'Record<string, unknown>', isOptional: true };
212
+ }
213
+
214
+ const hasRequired = required.size > 0;
215
+ const configType = `{ ${lines.join('; ')} }`;
216
+ return { configType, isOptional: !hasRequired };
217
+ }
218
+
219
+ // Object type with no properties defined
220
+ if (innerSchema.type === 'object') {
221
+ return { configType: 'Record<string, unknown>', isOptional: true };
222
+ }
223
+
224
+ // Fallback
225
+ return { configType: 'Record<string, unknown>', isOptional: true };
226
+ }
227
+
228
+ function generate(): void {
229
+ const schemaPath = join(__dirname, 'schema.json');
230
+ const outputPath = join(__dirname, 'SwmlVerbMethods.generated.ts');
231
+
232
+ const schema: Schema = JSON.parse(readFileSync(schemaPath, 'utf-8'));
233
+ const defs = schema.$defs;
234
+ const swmlMethod = defs['SWMLMethod'];
235
+
236
+ if (!swmlMethod?.anyOf) {
237
+ throw new Error('Schema missing $defs/SWMLMethod.anyOf');
238
+ }
239
+
240
+ const methods: string[] = [];
241
+
242
+ for (const ref of swmlMethod.anyOf) {
243
+ const refPath = ref.$ref;
244
+ if (!refPath) continue;
245
+
246
+ const schemaName = refPath.split('/').pop()!;
247
+ const verbDef = defs[schemaName];
248
+ if (!verbDef?.properties) continue;
249
+
250
+ const propNames = Object.keys(verbDef.properties);
251
+ if (propNames.length === 0) continue;
252
+
253
+ const verbName = propNames[0];
254
+ const innerSchema = verbDef.properties[verbName] as SchemaProperty;
255
+
256
+ // Get description
257
+ const desc = innerSchema.description ?? `Add the ${verbName} verb to the document.`;
258
+ const cleanDesc = desc.replace(/\n/g, ' ').replace(/\*\//g, '* /');
259
+
260
+ // Special handling for sleep
261
+ if (verbName === 'sleep') {
262
+ methods.push(` /** ${cleanDesc} */`);
263
+ methods.push(` sleep(durationOrConfig: number | { duration: number }): this;`);
264
+ continue;
265
+ }
266
+
267
+ // Special handling for label (takes a string directly)
268
+ if (innerSchema.type === 'string') {
269
+ methods.push(` /** ${cleanDesc} */`);
270
+ methods.push(` ${verbName}(value: string): this;`);
271
+ continue;
272
+ }
273
+
274
+ // Use custom typed interface if defined for this verb (e.g. ai, play)
275
+ if (CUSTOM_VERB_TYPES[verbName]) {
276
+ const { interfaceName, isOptional } = CUSTOM_VERB_TYPES[verbName];
277
+ const paramSig = isOptional ? `config?: ${interfaceName}` : `config: ${interfaceName}`;
278
+ methods.push(` /** ${cleanDesc} */`);
279
+ methods.push(` ${verbName}(${paramSig}): this;`);
280
+ continue;
281
+ }
282
+
283
+ const { configType, isOptional } = generateVerbConfig(verbName, innerSchema);
284
+ const paramSig = isOptional ? `config?: ${configType}` : `config: ${configType}`;
285
+
286
+ methods.push(` /** ${cleanDesc} */`);
287
+ methods.push(` ${verbName}(${paramSig}): this;`);
288
+ }
289
+
290
+ // Collect custom interface definitions to emit before the module augmentation
291
+ const customInterfaces = Object.values(CUSTOM_VERB_TYPES)
292
+ .map(({ interfaceName, interfaceBody }) =>
293
+ `export interface ${interfaceName} {\n${interfaceBody}\n}`)
294
+ .join('\n\n');
295
+
296
+ const output = `/**
297
+ * AUTO-GENERATED FILE — do not edit manually.
298
+ * Generated by: npx tsx src/generateVerbTypes.ts
299
+ *
300
+ * Provides TypeScript interface augmentation for all SWML verb methods
301
+ * auto-installed on SwmlBuilder from schema.json.
302
+ */
303
+
304
+ /* eslint-disable @typescript-eslint/no-empty-interface */
305
+
306
+ ${customInterfaces}
307
+
308
+ declare module './SwmlBuilder.js' {
309
+ interface SwmlBuilder {
310
+ ${methods.join('\n')}
311
+ }
312
+ }
313
+
314
+ export {};
315
+ `;
316
+
317
+ writeFileSync(outputPath, output, 'utf-8');
318
+ const verbCount = methods.filter(l => l.includes('): this;')).length;
319
+ console.log(`Generated ${outputPath} with ${verbCount} verb methods.`);
320
+ }
321
+
322
+ generate();
package/src/index.ts ADDED
@@ -0,0 +1,167 @@
1
+ /**
2
+ * SignalWire AI Agents SDK for TypeScript
3
+ *
4
+ * Build AI voice agents as HTTP microservices that serve SWML documents
5
+ * and handle SWAIG function callbacks.
6
+ */
7
+
8
+ // Core agent
9
+ export { AgentBase } from './AgentBase.js';
10
+ export type { RoutingCallback } from './AgentBase.js';
11
+ export { AgentServer } from './AgentServer.js';
12
+
13
+ // SWML Service (non-AI call flows)
14
+ export { SWMLService, SecurityConfig } from './SWMLService.js';
15
+ export type { OnRequestCallback, SWMLServiceOptions } from './SWMLService.js';
16
+
17
+ // Web Service (static file serving)
18
+ export { WebService } from './WebService.js';
19
+ export type { WebServiceOptions } from './WebService.js';
20
+
21
+ // Tool results & functions
22
+ export { FunctionResult } from './FunctionResult.js';
23
+ /** @deprecated Use {@link FunctionResult} instead. */
24
+ export { FunctionResult as SwaigFunctionResult } from './FunctionResult.js';
25
+ export type { PaymentPrompt, PaymentAction, PaymentParameter } from './FunctionResult.js';
26
+ export { SwaigFunction } from './SwaigFunction.js';
27
+ export type { SwaigHandler, SwaigFunctionOptions } from './SwaigFunction.js';
28
+
29
+ // DataMap (server-side tools)
30
+ export { DataMap, createSimpleApiTool, createExpressionTool, setAllowedEnvPrefixes, getAllowedEnvPrefixes } from './DataMap.js';
31
+
32
+ // Prompt Object Model
33
+ export { PomBuilder, PomSection } from './PomBuilder.js';
34
+ export type { PomSectionData } from './PomBuilder.js';
35
+
36
+ // SWML builder
37
+ export { SwmlBuilder } from './SwmlBuilder.js';
38
+ export type { SwmlBuilderOptions } from './SwmlBuilder.js';
39
+ import './SwmlVerbMethods.generated.js';
40
+
41
+ // SWML Verb Handlers
42
+ export { SWMLVerbHandler, AIVerbHandler, VerbHandlerRegistry } from './SWMLHandler.js';
43
+ export type { AIVerbBuildOptions } from './SWMLHandler.js';
44
+
45
+ // Prompt management
46
+ export { PromptManager } from './PromptManager.js';
47
+
48
+ // Contexts & Steps
49
+ export {
50
+ ContextBuilder,
51
+ Context,
52
+ Step,
53
+ GatherInfo,
54
+ GatherQuestion,
55
+ createSimpleContext,
56
+ } from './ContextBuilder.js';
57
+
58
+ // Security
59
+ export { SessionManager } from './SessionManager.js';
60
+ export type { DebugTokenResult } from './SessionManager.js';
61
+
62
+ // SSL
63
+ export { SslConfig } from './SslConfig.js';
64
+ export type { SslOptions } from './SslConfig.js';
65
+
66
+ // Schema Validation
67
+ export { SchemaUtils } from './SchemaUtils.js';
68
+ export type { ValidationResult } from './SchemaUtils.js';
69
+
70
+ // Auth
71
+ export { AuthHandler } from './AuthHandler.js';
72
+ export type { AuthConfig } from './AuthHandler.js';
73
+
74
+ // Type inference for typed tool handlers
75
+ export { inferSchema, createTypedHandlerWrapper, parseFunctionParams } from './TypeInference.js';
76
+ export type { InferredSchema, ParsedParam } from './TypeInference.js';
77
+
78
+ // Security utilities
79
+ export { safeAssign, filterSensitiveHeaders, redactUrl, MAX_SKILL_INPUT_LENGTH, validateUrl } from './SecurityUtils.js';
80
+
81
+ // Config
82
+ export { ConfigLoader } from './ConfigLoader.js';
83
+
84
+ // Logging
85
+ export { Logger, getLogger, setGlobalLogLevel, suppressAllLogs, setGlobalLogFormat, setGlobalLogColor, setGlobalLogStream, resetLoggingConfiguration, getExecutionMode, stripControlChars } from './Logger.js';
86
+
87
+ // Serverless
88
+ export { ServerlessAdapter } from './ServerlessAdapter.js';
89
+ export type { ServerlessPlatform, ServerlessEvent, ServerlessResponse } from './ServerlessAdapter.js';
90
+
91
+ // Skills
92
+ export { SkillBase, SkillManager, SkillRegistry } from './skills/index.js';
93
+ export type { SkillConfig, SkillToolDefinition, SkillPromptSection, ParameterSchemaEntry, SkillSchemaInfo } from './skills/index.js';
94
+
95
+ // Built-in Skills
96
+ export { registerBuiltinSkills } from './skills/builtin/index.js';
97
+ export {
98
+ DateTimeSkill, MathSkill, JokeSkill,
99
+ WeatherApiSkill, PlayBackgroundFileSkill, SwmlTransferSkill,
100
+ ApiNinjasTriviaSkill, InfoGathererSkill, CustomSkillsSkill,
101
+ WebSearchSkill, WikipediaSearchSkill, GoogleMapsSkill,
102
+ DataSphereSkill, DataSphereServerlessSkill, NativeVectorSearchSkill,
103
+ SpiderSkill, ClaudeSkillsSkill, AskClaudeSkill, McpGatewaySkill,
104
+ } from './skills/builtin/index.js';
105
+
106
+ // Prefab Agents
107
+ export {
108
+ InfoGathererAgent, SurveyAgent, FAQBotAgent,
109
+ ConciergeAgent, ReceptionistAgent,
110
+ } from './prefabs/index.js';
111
+ export type {
112
+ InfoGathererConfig, SurveyConfig, FAQBotConfig,
113
+ ConciergeConfig, ReceptionistConfig,
114
+ } from './prefabs/index.js';
115
+
116
+ // Types
117
+ export type {
118
+ AgentOptions,
119
+ LanguageConfig,
120
+ PronunciationRule,
121
+ FunctionInclude,
122
+ DynamicConfigCallback,
123
+ SummaryCallback,
124
+ } from './types.js';
125
+
126
+ // RELAY Client (real-time call/message control over WebSocket)
127
+ export * from './relay/index.js';
128
+
129
+ // REST Client (typed HTTP access to all SignalWire platform APIs)
130
+ export * from './rest/index.js';
131
+
132
+ // LiveWire (LiveKit-compatible agents powered by SignalWire)
133
+ export * as livewire from './livewire/index.js';
134
+
135
+ // CLI helpers — convenience wrappers matching Python's start_agent / run_agent API
136
+ import type { AgentBase as _AgentBase } from './AgentBase.js';
137
+
138
+ /**
139
+ * Start an agent's HTTP server.
140
+ *
141
+ * Equivalent to Python's `start_agent(agent)`. Delegates to `agent.serve(options)`.
142
+ *
143
+ * @param agent The AgentBase instance to start.
144
+ * @param options Optional host/port overrides.
145
+ */
146
+ export async function startAgent(
147
+ agent: _AgentBase,
148
+ options?: { port?: number; host?: string },
149
+ ): Promise<void> {
150
+ return agent.serve(options);
151
+ }
152
+
153
+ /**
154
+ * Run an agent's HTTP server.
155
+ *
156
+ * Alias for {@link startAgent} — equivalent to Python's `run_agent(agent)`.
157
+ * Delegates to `agent.serve(options)`.
158
+ *
159
+ * @param agent The AgentBase instance to run.
160
+ * @param options Optional host/port overrides.
161
+ */
162
+ export async function runAgent(
163
+ agent: _AgentBase,
164
+ options?: { port?: number; host?: string },
165
+ ): Promise<void> {
166
+ return agent.serve(options);
167
+ }