@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,221 @@
1
+ /**
2
+ * ServerlessAdapter - Adapts AgentBase for serverless platforms.
3
+ *
4
+ * Supports AWS Lambda, Google Cloud Functions, Azure Functions, and CGI mode.
5
+ * Auto-detects platform from environment variables.
6
+ */
7
+
8
+ import { getLogger } from './Logger.js';
9
+
10
+ const log = getLogger('ServerlessAdapter');
11
+
12
+ /** Supported serverless platform identifiers, or 'auto' for environment-based detection. */
13
+ export type ServerlessPlatform = 'lambda' | 'gcf' | 'azure' | 'cgi' | 'auto';
14
+
15
+ /** Normalized incoming event from a serverless platform. */
16
+ export interface ServerlessEvent {
17
+ /** HTTP method (AWS Lambda style). */
18
+ httpMethod?: string;
19
+ /** HTTP method (GCF/Azure style). */
20
+ method?: string;
21
+ /** Request headers as key-value pairs. */
22
+ headers?: Record<string, string>;
23
+ /** Request body, either raw JSON string or parsed object. */
24
+ body?: string | Record<string, unknown>;
25
+ /** Request path. */
26
+ path?: string;
27
+ /** Raw request path (AWS API Gateway v2). */
28
+ rawPath?: string;
29
+ /** Query string parameters as key-value pairs. */
30
+ queryStringParameters?: Record<string, string>;
31
+ /** Platform-specific request context metadata. */
32
+ requestContext?: Record<string, unknown>;
33
+ }
34
+
35
+ /** Normalized outgoing response returned to a serverless platform. */
36
+ export interface ServerlessResponse {
37
+ /** HTTP status code. */
38
+ statusCode: number;
39
+ /** Response headers as key-value pairs. */
40
+ headers: Record<string, string>;
41
+ /** Response body as a string. */
42
+ body: string;
43
+ }
44
+
45
+ /** Adapts a Hono application for deployment on AWS Lambda, Google Cloud Functions, Azure Functions, or CGI. */
46
+ export class ServerlessAdapter {
47
+ private platform: ServerlessPlatform;
48
+
49
+ /**
50
+ * Create a ServerlessAdapter for the given platform.
51
+ * @param platform - Target platform; defaults to 'auto' which detects from environment variables.
52
+ */
53
+ constructor(platform: ServerlessPlatform = 'auto') {
54
+ this.platform = platform === 'auto' ? this.detectPlatform() : platform;
55
+ }
56
+
57
+ /**
58
+ * Detect the serverless platform by inspecting well-known environment variables.
59
+ * @returns The detected platform identifier; defaults to 'lambda' if no match is found.
60
+ */
61
+ detectPlatform(): ServerlessPlatform {
62
+ if (process.env['AWS_LAMBDA_FUNCTION_NAME'] || process.env['_HANDLER']) return 'lambda';
63
+ if (process.env['FUNCTION_TARGET'] || process.env['K_SERVICE']) return 'gcf';
64
+ if (process.env['FUNCTIONS_WORKER_RUNTIME'] || process.env['AZURE_FUNCTIONS_ENVIRONMENT']) return 'azure';
65
+ if (process.env['GATEWAY_INTERFACE']) return 'cgi';
66
+ return 'lambda'; // default fallback
67
+ }
68
+
69
+ /**
70
+ * Get the resolved platform identifier.
71
+ * @returns The serverless platform this adapter is configured for.
72
+ */
73
+ getPlatform(): ServerlessPlatform {
74
+ return this.platform;
75
+ }
76
+
77
+ /**
78
+ * Convert a serverless event into a standard Request, route it through the Hono app, and return a normalized response.
79
+ * @param app - A Hono-compatible application with a `fetch` method.
80
+ * @param event - The incoming serverless event to process.
81
+ * @returns The normalized serverless response.
82
+ */
83
+ async handleRequest(app: { fetch: (req: Request) => Promise<Response> }, event: ServerlessEvent): Promise<ServerlessResponse> {
84
+ const method = event.httpMethod ?? event.method ?? 'POST';
85
+ const path = event.rawPath ?? event.path ?? '/';
86
+ const headers = event.headers ?? {};
87
+
88
+ // Build URL — prefer platform env vars over client headers
89
+ const host = process.env['AWS_LAMBDA_FUNCTION_URL']
90
+ ? new URL(process.env['AWS_LAMBDA_FUNCTION_URL']).hostname
91
+ : (headers['host'] ?? 'localhost');
92
+ const proto = process.env['AWS_LAMBDA_FUNCTION_URL'] ? 'https'
93
+ : (headers['x-forwarded-proto'] ?? 'https');
94
+ let url = `${proto}://${host}${path}`;
95
+ if (event.queryStringParameters) {
96
+ const qs = new URLSearchParams(event.queryStringParameters).toString();
97
+ if (qs) url += `?${qs}`;
98
+ }
99
+
100
+ // Build body
101
+ let body: string | undefined;
102
+ if (event.body) {
103
+ body = typeof event.body === 'string' ? event.body : JSON.stringify(event.body);
104
+ }
105
+
106
+ // Create Request
107
+ const request = new Request(url, {
108
+ method,
109
+ headers: new Headers(headers),
110
+ body: method !== 'GET' && method !== 'HEAD' ? body : undefined,
111
+ });
112
+
113
+ log.debug(`Handling ${method} ${path} on ${this.platform}`);
114
+
115
+ // Route through Hono
116
+ const response = await app.fetch(request);
117
+
118
+ // Convert back to serverless response
119
+ const responseHeaders: Record<string, string> = {};
120
+ response.headers.forEach((v, k) => { responseHeaders[k] = v; });
121
+
122
+ return {
123
+ statusCode: response.status,
124
+ headers: responseHeaders,
125
+ body: await response.text(),
126
+ };
127
+ }
128
+
129
+ /**
130
+ * Generate the platform-specific invocation URL for a deployed function.
131
+ * @param opts - Optional overrides for region, project, function name, stage, or API ID.
132
+ * @returns The constructed URL string.
133
+ */
134
+ generateUrl(opts?: {
135
+ region?: string;
136
+ projectId?: string;
137
+ functionName?: string;
138
+ stage?: string;
139
+ apiId?: string;
140
+ }): string {
141
+ const functionName = opts?.functionName ?? process.env['AWS_LAMBDA_FUNCTION_NAME'] ?? 'agent';
142
+
143
+ switch (this.platform) {
144
+ case 'lambda': {
145
+ const region = opts?.region ?? process.env['AWS_REGION'] ?? 'us-east-1';
146
+ const apiId = opts?.apiId ?? 'API_ID';
147
+ const stage = opts?.stage ?? 'prod';
148
+ return `https://${apiId}.execute-api.${region}.amazonaws.com/${stage}`;
149
+ }
150
+ case 'gcf': {
151
+ const project = opts?.projectId ?? process.env['GCLOUD_PROJECT'] ?? 'PROJECT';
152
+ const region = opts?.region ?? process.env['FUNCTION_REGION'] ?? 'us-central1';
153
+ return `https://${region}-${project}.cloudfunctions.net/${functionName}`;
154
+ }
155
+ case 'azure': {
156
+ return `https://${functionName}.azurewebsites.net/api/${functionName}`;
157
+ }
158
+ case 'cgi': {
159
+ return `http://localhost/cgi-bin/${functionName}`;
160
+ }
161
+ default:
162
+ return `https://localhost/${functionName}`;
163
+ }
164
+ }
165
+
166
+ /**
167
+ * Create an AWS Lambda-compatible handler function from a Hono app.
168
+ * @param app - A Hono-compatible application with a `fetch` method.
169
+ * @returns A function that accepts a Lambda event and returns a promise of a serverless response.
170
+ */
171
+ static createLambdaHandler(app: { fetch: (req: Request) => Promise<Response> }): (event: ServerlessEvent) => Promise<ServerlessResponse> {
172
+ const adapter = new ServerlessAdapter('lambda');
173
+ return (event: ServerlessEvent) => adapter.handleRequest(app, event);
174
+ }
175
+
176
+ /**
177
+ * Create a Google Cloud Functions-compatible handler from a Hono app.
178
+ * @param app - A Hono-compatible application with a `fetch` method.
179
+ * @returns A function that accepts GCF request/response objects.
180
+ */
181
+ static createGcfHandler(app: { fetch: (req: Request) => Promise<Response> }): (req: any, res: any) => Promise<void> {
182
+ const adapter = new ServerlessAdapter('gcf');
183
+ return async (req: any, res: any) => {
184
+ const event: ServerlessEvent = {
185
+ method: req.method,
186
+ headers: req.headers,
187
+ body: req.body,
188
+ path: req.path ?? req.url,
189
+ };
190
+ const response = await adapter.handleRequest(app, event);
191
+ res.status(response.statusCode);
192
+ for (const [k, v] of Object.entries(response.headers)) {
193
+ res.set(k, v);
194
+ }
195
+ res.send(response.body);
196
+ };
197
+ }
198
+
199
+ /**
200
+ * Create an Azure Functions-compatible handler from a Hono app.
201
+ * @param app - A Hono-compatible application with a `fetch` method.
202
+ * @returns A function that accepts an Azure context and request object.
203
+ */
204
+ static createAzureHandler(app: { fetch: (req: Request) => Promise<Response> }): (context: any, req: any) => Promise<void> {
205
+ const adapter = new ServerlessAdapter('azure');
206
+ return async (context: any, req: any) => {
207
+ const event: ServerlessEvent = {
208
+ method: req.method,
209
+ headers: req.headers,
210
+ body: req.body,
211
+ path: req.url,
212
+ };
213
+ const response = await adapter.handleRequest(app, event);
214
+ context.res = {
215
+ status: response.statusCode,
216
+ headers: response.headers,
217
+ body: response.body,
218
+ };
219
+ };
220
+ }
221
+ }
@@ -0,0 +1,311 @@
1
+ /**
2
+ * SessionManager - Stateless HMAC-SHA256 token generation and validation.
3
+ *
4
+ * Tokens encode call_id, function name, expiry and a nonce, signed with a
5
+ * shared secret. No server-side state is stored.
6
+ */
7
+
8
+ import { randomBytes, createHmac } from 'node:crypto';
9
+ import { getLogger } from './Logger.js';
10
+
11
+ /** Decoded token debug info matching the Python SDK's nested return structure. */
12
+ export interface DebugTokenResult {
13
+ valid_format: boolean;
14
+ components?: {
15
+ call_id: string;
16
+ function: string;
17
+ expiry: string;
18
+ expiry_date: string | null;
19
+ nonce: string;
20
+ signature: string;
21
+ };
22
+ status?: {
23
+ current_time: number;
24
+ is_expired: boolean | null;
25
+ expires_in_seconds: number | null;
26
+ };
27
+ parts_count?: number;
28
+ token_length?: number;
29
+ error?: string;
30
+ }
31
+
32
+ /** Stateless HMAC-SHA256 token manager for SWAIG function call authentication and per-session metadata storage. */
33
+ export class SessionManager {
34
+ /** Token validity duration in seconds. */
35
+ tokenExpirySecs: number;
36
+ /** HMAC signing secret. */
37
+ secretKey: string;
38
+ /**
39
+ * When true, {@link debugToken} decodes token internals.
40
+ * When false (default), it returns `{ error: "debug mode not enabled" }`.
41
+ */
42
+ debugMode = false;
43
+ private sessionMetadata: Map<string, Record<string, unknown>> = new Map();
44
+ private sessionTimestamps: Map<string, number> = new Map();
45
+ private log = getLogger('SessionManager');
46
+
47
+ /**
48
+ * Create a new SessionManager.
49
+ * @param tokenExpirySecs - Token validity duration in seconds (default 900).
50
+ * @param secretKey - HMAC signing secret; a random key is generated if omitted.
51
+ */
52
+ constructor(tokenExpirySecs = 900, secretKey?: string) {
53
+ this.tokenExpirySecs = tokenExpirySecs;
54
+ this.secretKey = secretKey ?? randomBytes(32).toString('hex');
55
+ }
56
+
57
+ /**
58
+ * Return the given callId or generate a new random session identifier.
59
+ * @param callId - Existing call ID to reuse.
60
+ * @returns The call ID string.
61
+ */
62
+ createSession(callId?: string): string {
63
+ if (callId) return callId;
64
+ return randomBytes(16).toString('base64url');
65
+ }
66
+
67
+ /**
68
+ * Generate a signed, base64url-encoded token binding a function name to a call ID.
69
+ * @param functionName - The SWAIG function name to bind.
70
+ * @param callId - The call ID to bind.
71
+ * @returns A base64url-encoded token string.
72
+ */
73
+ generateToken(functionName: string, callId: string): string {
74
+ const expiry = Math.floor(Date.now() / 1000) + this.tokenExpirySecs;
75
+ const nonce = randomBytes(16).toString('hex');
76
+ const message = `${callId}:${functionName}:${expiry}:${nonce}`;
77
+ const signature = createHmac('sha256', this.secretKey)
78
+ .update(message)
79
+ .digest('hex');
80
+ const token = `${callId}.${functionName}.${expiry}.${nonce}.${signature}`;
81
+ const encoded = Buffer.from(token).toString('base64url');
82
+ this.log.debug('created_token', { function: functionName, call_id: callId });
83
+ return encoded;
84
+ }
85
+
86
+ /**
87
+ * Alias for {@link generateToken}.
88
+ * @param functionName - The SWAIG function name to bind.
89
+ * @param callId - The call ID to bind.
90
+ * @returns A base64url-encoded token string.
91
+ */
92
+ createToolToken(functionName: string, callId: string): string {
93
+ return this.generateToken(functionName, callId);
94
+ }
95
+
96
+ /**
97
+ * Validate a token against the expected call ID and function name.
98
+ * @param callId - The expected call ID.
99
+ * @param functionName - The expected function name.
100
+ * @param token - The base64url-encoded token to validate.
101
+ * @returns True if the token is valid and not expired.
102
+ */
103
+ validateToken(callId: string, functionName: string, token: string): boolean {
104
+ try {
105
+ const decoded = Buffer.from(token, 'base64url').toString();
106
+ const parts = decoded.split('.');
107
+ if (parts.length !== 5) {
108
+ this.log.warn('token_invalid', { function: functionName });
109
+ return false;
110
+ }
111
+ const [tokenCallId, tokenFunction, tokenExpiry, tokenNonce, tokenSignature] = parts;
112
+
113
+ if (!callId) {
114
+ this.log.warn('token_rejected_no_call_id', { function: functionName });
115
+ return false;
116
+ }
117
+ if (tokenFunction !== functionName) {
118
+ this.log.warn('token_function_mismatch', { expected: functionName, got: tokenFunction });
119
+ return false;
120
+ }
121
+
122
+ const expiry = parseInt(tokenExpiry, 10);
123
+ if (expiry <= Math.floor(Date.now() / 1000)) {
124
+ this.log.warn('token_expired', { function: functionName });
125
+ return false;
126
+ }
127
+
128
+ const message = `${tokenCallId}:${tokenFunction}:${tokenExpiry}:${tokenNonce}`;
129
+ const expectedSig = createHmac('sha256', this.secretKey)
130
+ .update(message)
131
+ .digest('hex');
132
+ if (tokenSignature !== expectedSig) {
133
+ this.log.warn('token_invalid', { function: functionName });
134
+ return false;
135
+ }
136
+ if (tokenCallId !== callId) {
137
+ this.log.warn('token_call_id_mismatch', { expected: callId, got: tokenCallId });
138
+ return false;
139
+ }
140
+
141
+ this.log.debug('token_valid', { function: functionName });
142
+ return true;
143
+ } catch {
144
+ this.log.warn('token_invalid', { function: functionName });
145
+ return false;
146
+ }
147
+ }
148
+
149
+ /**
150
+ * Alias for {@link validateToken} with reordered parameters.
151
+ * @param functionName - The expected function name.
152
+ * @param token - The base64url-encoded token to validate.
153
+ * @param callId - The expected call ID.
154
+ * @returns True if the token is valid and not expired.
155
+ */
156
+ validateToolToken(functionName: string, token: string, callId: string): boolean {
157
+ return this.validateToken(callId, functionName, token);
158
+ }
159
+
160
+ /**
161
+ * Debug a token without validating it.
162
+ *
163
+ * Requires {@link debugMode} to be `true`. When disabled, returns
164
+ * `{ error: "debug mode not enabled" }` matching the Python SDK behaviour.
165
+ *
166
+ * @param token - The base64url-encoded token to decode.
167
+ * @returns A nested debug structure matching the Python SDK, or an error object.
168
+ */
169
+ debugToken(token: string): DebugTokenResult {
170
+ if (!this.debugMode) {
171
+ return { valid_format: false, error: 'debug mode not enabled' };
172
+ }
173
+ try {
174
+ const decoded = Buffer.from(token, 'base64url').toString();
175
+ const parts = decoded.split('.');
176
+ if (parts.length !== 5) {
177
+ return {
178
+ valid_format: false,
179
+ parts_count: parts.length,
180
+ token_length: token ? token.length : 0,
181
+ };
182
+ }
183
+ const [tokenCallId, tokenFunction, tokenExpiry, tokenNonce, tokenSignature] = parts;
184
+
185
+ const currentTime = Math.floor(Date.now() / 1000);
186
+ let expiry: number | null = null;
187
+ let isExpired: boolean | null = null;
188
+ let expiresIn: number | null = null;
189
+ let expiryDate: string | null = null;
190
+ const parsed = parseInt(tokenExpiry, 10);
191
+ if (!Number.isNaN(parsed)) {
192
+ expiry = parsed;
193
+ isExpired = expiry < currentTime;
194
+ expiresIn = isExpired ? 0 : expiry - currentTime;
195
+ expiryDate = new Date(expiry * 1000).toISOString();
196
+ }
197
+
198
+ return {
199
+ valid_format: true,
200
+ components: {
201
+ call_id: tokenCallId.length > 8 ? tokenCallId.slice(0, 8) + '...' : tokenCallId,
202
+ function: tokenFunction,
203
+ expiry: tokenExpiry,
204
+ expiry_date: expiryDate,
205
+ nonce: tokenNonce,
206
+ signature: tokenSignature.length > 8 ? tokenSignature.slice(0, 8) + '...' : tokenSignature,
207
+ },
208
+ status: {
209
+ current_time: currentTime,
210
+ is_expired: isExpired,
211
+ expires_in_seconds: expiresIn,
212
+ },
213
+ };
214
+ } catch (e: unknown) {
215
+ return {
216
+ valid_format: false,
217
+ error: e instanceof Error ? e.message : String(e),
218
+ token_length: token ? token.length : 0,
219
+ };
220
+ }
221
+ }
222
+
223
+ /**
224
+ * Retrieve metadata associated with a session.
225
+ *
226
+ * Returns an empty object when no metadata has been stored for the session,
227
+ * matching Python SDK behavior (`get_session_metadata` always returns `{}`).
228
+ * Callers can safely check truthiness or iterate keys without a null guard.
229
+ *
230
+ * @param sessionId - The session identifier.
231
+ * @returns The metadata record for the session, or `{}` if no metadata exists.
232
+ */
233
+ getSessionMetadata(sessionId: string): Record<string, unknown> {
234
+ return this.sessionMetadata.get(sessionId) ?? {};
235
+ }
236
+
237
+ /**
238
+ * Merge metadata into a session, creating the entry if it does not exist.
239
+ *
240
+ * Supports two call signatures for Python SDK compatibility:
241
+ * - `setSessionMetadata(sessionId, metadata)` — bulk merge (TS-native)
242
+ * - `setSessionMetadata(sessionId, key, value)` — single key/value (Python-compatible)
243
+ *
244
+ * @param sessionId - The session identifier.
245
+ * @param metadataOrKey - A metadata record to merge, or a string key when called with three arguments.
246
+ * @param value - The value to set when called with a string key.
247
+ */
248
+ setSessionMetadata(sessionId: string, metadataOrKey: Record<string, unknown>): void;
249
+ setSessionMetadata(sessionId: string, key: string, value: unknown): boolean;
250
+ setSessionMetadata(sessionId: string, metadataOrKey: Record<string, unknown> | string, value?: unknown): void | boolean {
251
+ if (typeof metadataOrKey === 'string') {
252
+ // Python-compatible single key/value overload — returns bool for parity
253
+ this.sessionMetadata.set(sessionId, { ...this.sessionMetadata.get(sessionId), [metadataOrKey]: value });
254
+ this.sessionTimestamps.set(sessionId, Date.now());
255
+ if (this.sessionMetadata.size > 1000) {
256
+ this.cleanup();
257
+ }
258
+ return true;
259
+ }
260
+ this.sessionMetadata.set(sessionId, { ...this.sessionMetadata.get(sessionId), ...metadataOrKey });
261
+ this.sessionTimestamps.set(sessionId, Date.now());
262
+ // Auto-cleanup when map grows too large
263
+ if (this.sessionMetadata.size > 1000) {
264
+ this.cleanup();
265
+ }
266
+ }
267
+
268
+ /**
269
+ * Remove session metadata entries older than `maxAgeMs`.
270
+ * @param maxAgeMs - Maximum age in milliseconds (defaults to `tokenExpirySecs * 1000`).
271
+ */
272
+ cleanup(maxAgeMs?: number): void {
273
+ const maxAge = maxAgeMs ?? this.tokenExpirySecs * 1000;
274
+ const cutoff = Date.now() - maxAge;
275
+ for (const [id, ts] of this.sessionTimestamps) {
276
+ if (ts <= cutoff) {
277
+ this.sessionMetadata.delete(id);
278
+ this.sessionTimestamps.delete(id);
279
+ }
280
+ }
281
+ }
282
+
283
+ /**
284
+ * Legacy method retained for API compatibility with the Python SDK.
285
+ * Does nothing and returns `true`.
286
+ * @param _callId - The call/session identifier (unused).
287
+ * @returns Always `true`.
288
+ */
289
+ activateSession(_callId: string): boolean {
290
+ return true;
291
+ }
292
+
293
+ /**
294
+ * Legacy method retained for API compatibility with the Python SDK.
295
+ * Does nothing and returns `true`.
296
+ * @param _callId - The call/session identifier (unused).
297
+ * @returns Always `true`.
298
+ */
299
+ endSession(_callId: string): boolean {
300
+ return true;
301
+ }
302
+
303
+ /**
304
+ * Delete all metadata for a session.
305
+ * @param sessionId - The session identifier.
306
+ * @returns True if the session existed and was deleted.
307
+ */
308
+ deleteSessionMetadata(sessionId: string): boolean {
309
+ return this.sessionMetadata.delete(sessionId);
310
+ }
311
+ }
@@ -0,0 +1,118 @@
1
+ /**
2
+ * SslConfig - SSL/TLS configuration for HTTPS serving.
3
+ *
4
+ * Env vars:
5
+ * SWML_SSL_ENABLED: true|false
6
+ * SWML_SSL_CERT_PATH: path to PEM cert
7
+ * SWML_SSL_KEY_PATH: path to PEM key
8
+ * SWML_SSL_DOMAIN: domain for HSTS
9
+ */
10
+
11
+ import { readFileSync, existsSync } from 'node:fs';
12
+
13
+ /** Configuration options for SSL/TLS setup. */
14
+ export interface SslOptions {
15
+ /** Whether SSL is enabled. */
16
+ enabled?: boolean;
17
+ /** Filesystem path to the PEM-encoded certificate. */
18
+ certPath?: string;
19
+ /** Filesystem path to the PEM-encoded private key. */
20
+ keyPath?: string;
21
+ /** Domain name used for HSTS headers. */
22
+ domain?: string;
23
+ /** Whether to send HSTS headers; defaults to true. */
24
+ hsts?: boolean;
25
+ /** HSTS max-age in seconds; defaults to 31536000 (1 year). */
26
+ hstsMaxAge?: number;
27
+ }
28
+
29
+ /** Manages SSL/TLS configuration sourced from explicit options or environment variables. */
30
+ export class SslConfig {
31
+ /** Whether SSL is enabled. */
32
+ enabled: boolean;
33
+ /** Filesystem path to the PEM certificate, or null if unset. */
34
+ certPath: string | null;
35
+ /** Filesystem path to the PEM private key, or null if unset. */
36
+ keyPath: string | null;
37
+ /** Domain name for HSTS, or null if unset. */
38
+ domain: string | null;
39
+ /** Whether HSTS headers should be emitted. */
40
+ hsts: boolean;
41
+ /** HSTS max-age value in seconds. */
42
+ hstsMaxAge: number;
43
+
44
+ /**
45
+ * Create an SslConfig, falling back to environment variables for any unset options.
46
+ * @param opts - Optional SSL configuration overrides.
47
+ */
48
+ constructor(opts?: SslOptions) {
49
+ this.enabled = opts?.enabled ?? (process.env['SWML_SSL_ENABLED'] === 'true');
50
+ this.certPath = opts?.certPath ?? process.env['SWML_SSL_CERT_PATH'] ?? null;
51
+ this.keyPath = opts?.keyPath ?? process.env['SWML_SSL_KEY_PATH'] ?? null;
52
+ this.domain = opts?.domain ?? process.env['SWML_SSL_DOMAIN'] ?? null;
53
+ this.hsts = opts?.hsts ?? true;
54
+ this.hstsMaxAge = opts?.hstsMaxAge ?? 31536000; // 1 year
55
+ }
56
+
57
+ /**
58
+ * Check whether SSL is fully configured: enabled with both cert and key files present on disk.
59
+ * @returns True if SSL is enabled and both certificate and key files exist.
60
+ */
61
+ isConfigured(): boolean {
62
+ if (!this.enabled) return false;
63
+ if (!this.certPath || !this.keyPath) return false;
64
+ return existsSync(this.certPath) && existsSync(this.keyPath);
65
+ }
66
+
67
+ /**
68
+ * Read the PEM certificate file from disk.
69
+ * @returns The certificate contents, or null if the file is missing.
70
+ */
71
+ getCert(): string | null {
72
+ if (!this.certPath || !existsSync(this.certPath)) return null;
73
+ return readFileSync(this.certPath, 'utf-8');
74
+ }
75
+
76
+ /**
77
+ * Read the PEM private key file from disk.
78
+ * @returns The key contents, or null if the file is missing.
79
+ */
80
+ getKey(): string | null {
81
+ if (!this.keyPath || !existsSync(this.keyPath)) return null;
82
+ return readFileSync(this.keyPath, 'utf-8');
83
+ }
84
+
85
+ /**
86
+ * Build the Strict-Transport-Security header value.
87
+ * @returns The HSTS header string, or null if HSTS is disabled or SSL is off.
88
+ */
89
+ getHstsHeader(): string | null {
90
+ if (!this.hsts || !this.enabled) return null;
91
+ return `max-age=${this.hstsMaxAge}; includeSubDomains`;
92
+ }
93
+
94
+ /**
95
+ * Create the options object needed by Node.js `https.createServer()`.
96
+ * @returns An object with `cert` and `key` strings, or null if either file is missing.
97
+ */
98
+ getServerOptions(): { cert: string; key: string } | null {
99
+ const cert = this.getCert();
100
+ const key = this.getKey();
101
+ if (!cert || !key) return null;
102
+ return { cert, key };
103
+ }
104
+
105
+ /**
106
+ * Return a Hono middleware that appends the HSTS header to every response.
107
+ * @returns A Hono-compatible middleware function.
108
+ */
109
+ hstsMiddleware(): (c: any, next: () => Promise<void>) => Promise<void> {
110
+ return async (c: any, next: () => Promise<void>) => {
111
+ await next();
112
+ const hsts = this.getHstsHeader();
113
+ if (hsts) {
114
+ c.res.headers.set('Strict-Transport-Security', hsts);
115
+ }
116
+ };
117
+ }
118
+ }