@signalwire/sdk 2.0.5 → 3.6.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.
- package/CHANGELOG.md +821 -0
- package/LICENSE +21 -0
- package/README.md +163 -68
- package/dist/AGENTS.md +13 -0
- package/dist/AgentBase.d.ts +510 -126
- package/dist/AgentBase.js +1581 -455
- package/dist/AgentBase.js.map +1 -1
- package/dist/AgentServer.d.ts +21 -0
- package/dist/AgentServer.js +154 -47
- package/dist/AgentServer.js.map +1 -1
- package/dist/AuthHandler.d.ts +14 -2
- package/dist/AuthHandler.js +7 -2
- package/dist/AuthHandler.js.map +1 -1
- package/dist/ConfigLoader.d.ts +5 -13
- package/dist/ConfigLoader.js +15 -29
- package/dist/ConfigLoader.js.map +1 -1
- package/dist/ContextBuilder.d.ts +202 -9
- package/dist/ContextBuilder.js +219 -36
- package/dist/ContextBuilder.js.map +1 -1
- package/dist/DataMap.d.ts +186 -45
- package/dist/DataMap.js +210 -52
- package/dist/DataMap.js.map +1 -1
- package/dist/FunctionResult.d.ts +309 -83
- package/dist/FunctionResult.js +483 -116
- package/dist/FunctionResult.js.map +1 -1
- package/dist/Logger.d.ts +30 -5
- package/dist/Logger.js +77 -19
- package/dist/Logger.js.map +1 -1
- package/dist/POM/PromptObjectModel.d.ts +12 -1
- package/dist/POM/PromptObjectModel.js +25 -9
- package/dist/POM/PromptObjectModel.js.map +1 -1
- package/dist/ParameterSchema.d.ts +306 -0
- package/dist/ParameterSchema.js +251 -0
- package/dist/ParameterSchema.js.map +1 -0
- package/dist/PlatformContracts.d.ts +21 -0
- package/dist/PlatformContracts.generated.d.ts +109 -0
- package/dist/PlatformContracts.generated.js +8 -0
- package/dist/PlatformContracts.generated.js.map +1 -0
- package/dist/PlatformContracts.js +2 -0
- package/dist/PlatformContracts.js.map +1 -0
- package/dist/PomBuilder.d.ts +18 -0
- package/dist/PomBuilder.js +53 -3
- package/dist/PomBuilder.js.map +1 -1
- package/dist/PostPrompt.d.ts +110 -0
- package/dist/PostPrompt.js +204 -0
- package/dist/PostPrompt.js.map +1 -0
- package/dist/PromptManager.d.ts +22 -1
- package/dist/PromptManager.js +28 -1
- package/dist/PromptManager.js.map +1 -1
- package/dist/PublicFetch.d.ts +132 -0
- package/dist/PublicFetch.js +311 -0
- package/dist/PublicFetch.js.map +1 -0
- package/dist/RobotsTxt.d.ts +41 -0
- package/dist/RobotsTxt.js +152 -0
- package/dist/RobotsTxt.js.map +1 -0
- package/dist/SWMLHandler.js.map +1 -1
- package/dist/SWMLService.d.ts +169 -59
- package/dist/SWMLService.js +456 -129
- package/dist/SWMLService.js.map +1 -1
- package/dist/SchemaUtils.d.ts +115 -2
- package/dist/SchemaUtils.js +444 -12
- package/dist/SchemaUtils.js.map +1 -1
- package/dist/SecurityUtils.d.ts +49 -9
- package/dist/SecurityUtils.js +153 -51
- package/dist/SecurityUtils.js.map +1 -1
- package/dist/SemanticGate.d.ts +183 -0
- package/dist/SemanticGate.js +533 -0
- package/dist/SemanticGate.js.map +1 -0
- package/dist/ServerlessAdapter.d.ts +156 -7
- package/dist/ServerlessAdapter.js +399 -42
- package/dist/ServerlessAdapter.js.map +1 -1
- package/dist/SessionManager.d.ts +11 -2
- package/dist/SessionManager.js +50 -18
- package/dist/SessionManager.js.map +1 -1
- package/dist/SslConfig.d.ts +2 -1
- package/dist/SslConfig.js +4 -1
- package/dist/SslConfig.js.map +1 -1
- package/dist/SwaigActions.generated.d.ts +23 -0
- package/dist/SwaigActions.generated.js +8 -0
- package/dist/SwaigActions.generated.js.map +1 -0
- package/dist/SwaigContracts.d.ts +15 -0
- package/dist/SwaigContracts.generated.d.ts +264 -0
- package/dist/SwaigContracts.generated.js +12 -0
- package/dist/SwaigContracts.generated.js.map +1 -0
- package/dist/SwaigContracts.js +2 -0
- package/dist/SwaigContracts.js.map +1 -0
- package/dist/SwaigFunction.d.ts +139 -7
- package/dist/SwaigFunction.js +170 -22
- package/dist/SwaigFunction.js.map +1 -1
- package/dist/SwmlBuilder.d.ts +68 -19
- package/dist/SwmlBuilder.js +74 -38
- package/dist/SwmlBuilder.js.map +1 -1
- package/dist/SwmlVerbMethods.generated.d.ts +41 -4
- package/dist/SwmlVerbMethods.generated.js +1 -1
- package/dist/TypeInference.d.ts +39 -3
- package/dist/TypeInference.js +256 -16
- package/dist/TypeInference.js.map +1 -1
- package/dist/WebService.d.ts +79 -11
- package/dist/WebService.js +320 -109
- package/dist/WebService.js.map +1 -1
- package/dist/WebhookMiddleware.d.ts +119 -0
- package/dist/WebhookMiddleware.js +271 -0
- package/dist/WebhookMiddleware.js.map +1 -0
- package/dist/WebhookValidator.d.ts +92 -0
- package/dist/WebhookValidator.js +409 -0
- package/dist/WebhookValidator.js.map +1 -0
- package/dist/agents/BedrockAgent.d.ts +162 -0
- package/dist/agents/BedrockAgent.js +323 -0
- package/dist/agents/BedrockAgent.js.map +1 -0
- package/dist/ai-chat/AIChatClient.d.ts +316 -0
- package/dist/ai-chat/AIChatClient.js +535 -0
- package/dist/ai-chat/AIChatClient.js.map +1 -0
- package/dist/ai-chat/ChatGateway.d.ts +408 -0
- package/dist/ai-chat/ChatGateway.js +747 -0
- package/dist/ai-chat/ChatGateway.js.map +1 -0
- package/dist/ai-chat/HandoffRouter.d.ts +282 -0
- package/dist/ai-chat/HandoffRouter.js +518 -0
- package/dist/ai-chat/HandoffRouter.js.map +1 -0
- package/dist/ai-chat/index.d.ts +12 -0
- package/dist/ai-chat/index.js +10 -0
- package/dist/ai-chat/index.js.map +1 -0
- package/dist/capabilities.d.ts +64 -0
- package/dist/capabilities.js +95 -0
- package/dist/capabilities.js.map +1 -0
- package/dist/cli/agent-loader.d.ts +32 -6
- package/dist/cli/agent-loader.js +92 -33
- package/dist/cli/agent-loader.js.map +1 -1
- package/dist/cli/datamap-exec.d.ts +175 -0
- package/dist/cli/datamap-exec.js +1284 -0
- package/dist/cli/datamap-exec.js.map +1 -0
- package/dist/cli/function-args.d.ts +40 -0
- package/dist/cli/function-args.js +146 -0
- package/dist/cli/function-args.js.map +1 -0
- package/dist/cli/simulation.d.ts +99 -0
- package/dist/cli/simulation.js +490 -0
- package/dist/cli/simulation.js.map +1 -0
- package/dist/cli/swaig-test.d.ts +12 -25
- package/dist/cli/swaig-test.js +935 -371
- package/dist/cli/swaig-test.js.map +1 -1
- package/dist/cli/tsdocs/agentsNote.d.ts +30 -0
- package/dist/cli/tsdocs/agentsNote.js +92 -0
- package/dist/cli/tsdocs/agentsNote.js.map +1 -0
- package/dist/cli/tsdocs/api-index.json +1 -0
- package/dist/cli/tsdocs/api.d.ts +91 -0
- package/dist/cli/tsdocs/api.js +372 -0
- package/dist/cli/tsdocs/api.js.map +1 -0
- package/dist/cli/tsdocs/apiTypes.d.ts +64 -0
- package/dist/cli/tsdocs/apiTypes.js +7 -0
- package/dist/cli/tsdocs/apiTypes.js.map +1 -0
- package/dist/cli/tsdocs/bin.d.ts +6 -0
- package/dist/cli/tsdocs/bin.js +23 -0
- package/dist/cli/tsdocs/bin.js.map +1 -0
- package/dist/cli/tsdocs/files.d.ts +108 -0
- package/dist/cli/tsdocs/files.js +287 -0
- package/dist/cli/tsdocs/files.js.map +1 -0
- package/dist/cli/tsdocs/index.d.ts +28 -0
- package/dist/cli/tsdocs/index.js +307 -0
- package/dist/cli/tsdocs/index.js.map +1 -0
- package/dist/cli/tsdocs/live.d.ts +41 -0
- package/dist/cli/tsdocs/live.js +202 -0
- package/dist/cli/tsdocs/live.js.map +1 -0
- package/dist/cli/tsdocs/locate.d.ts +51 -0
- package/dist/cli/tsdocs/locate.js +75 -0
- package/dist/cli/tsdocs/locate.js.map +1 -0
- package/dist/cli/tsdocs/render.d.ts +75 -0
- package/dist/cli/tsdocs/render.js +323 -0
- package/dist/cli/tsdocs/render.js.map +1 -0
- package/dist/cli/tsdocs/topics.d.ts +43 -0
- package/dist/cli/tsdocs/topics.js +920 -0
- package/dist/cli/tsdocs/topics.js.map +1 -0
- package/dist/index.d.ts +49 -68
- package/dist/index.js +45 -73
- package/dist/index.js.map +1 -1
- package/dist/livewire/index.d.ts +229 -155
- package/dist/livewire/index.js +298 -195
- package/dist/livewire/index.js.map +1 -1
- package/dist/llms.txt +65 -0
- package/dist/prefabs/CallSessionStore.d.ts +52 -0
- package/dist/prefabs/CallSessionStore.js +72 -0
- package/dist/prefabs/CallSessionStore.js.map +1 -0
- package/dist/prefabs/ConciergeAgent.d.ts +13 -1
- package/dist/prefabs/ConciergeAgent.js +36 -31
- package/dist/prefabs/ConciergeAgent.js.map +1 -1
- package/dist/prefabs/FAQBotAgent.d.ts +9 -1
- package/dist/prefabs/FAQBotAgent.js +113 -47
- package/dist/prefabs/FAQBotAgent.js.map +1 -1
- package/dist/prefabs/InfoGathererAgent.d.ts +22 -3
- package/dist/prefabs/InfoGathererAgent.js +67 -58
- package/dist/prefabs/InfoGathererAgent.js.map +1 -1
- package/dist/prefabs/ReceptionistAgent.d.ts +16 -5
- package/dist/prefabs/ReceptionistAgent.js +39 -31
- package/dist/prefabs/ReceptionistAgent.js.map +1 -1
- package/dist/prefabs/SurveyAgent.d.ts +22 -4
- package/dist/prefabs/SurveyAgent.js +84 -68
- package/dist/prefabs/SurveyAgent.js.map +1 -1
- package/dist/relay/Action.d.ts +44 -21
- package/dist/relay/Action.js +75 -17
- package/dist/relay/Action.js.map +1 -1
- package/dist/relay/Call.d.ts +312 -47
- package/dist/relay/Call.js +369 -18
- package/dist/relay/Call.js.map +1 -1
- package/dist/relay/Deferred.js.map +1 -1
- package/dist/relay/Message.d.ts +26 -5
- package/dist/relay/Message.js +36 -6
- package/dist/relay/Message.js.map +1 -1
- package/dist/relay/RelayClient.d.ts +44 -17
- package/dist/relay/RelayClient.js +175 -65
- package/dist/relay/RelayClient.js.map +1 -1
- package/dist/relay/RelayError.d.ts +14 -0
- package/dist/relay/RelayError.js +15 -0
- package/dist/relay/RelayError.js.map +1 -1
- package/dist/relay/RelayEvent.d.ts +96 -65
- package/dist/relay/RelayEvent.js +85 -56
- package/dist/relay/RelayEvent.js.map +1 -1
- package/dist/relay/closedSets.d.ts +111 -0
- package/dist/relay/closedSets.js +83 -0
- package/dist/relay/closedSets.js.map +1 -0
- package/dist/relay/index.d.ts +3 -1
- package/dist/relay/index.js +1 -0
- package/dist/relay/index.js.map +1 -1
- package/dist/relay/normalize.js.map +1 -1
- package/dist/relay/protocol.types.generated.d.ts +1195 -0
- package/dist/relay/protocol.types.generated.js +8 -0
- package/dist/relay/protocol.types.generated.js.map +1 -0
- package/dist/relay/types.d.ts +73 -42
- package/dist/rest/HttpClient.d.ts +36 -8
- package/dist/rest/HttpClient.js +233 -40
- package/dist/rest/HttpClient.js.map +1 -1
- package/dist/rest/RequestOptions.d.ts +110 -0
- package/dist/rest/RequestOptions.js +113 -0
- package/dist/rest/RequestOptions.js.map +1 -0
- package/dist/rest/RestError.d.ts +52 -6
- package/dist/rest/RestError.js +89 -5
- package/dist/rest/RestError.js.map +1 -1
- package/dist/rest/base/CrudResource.d.ts +16 -26
- package/dist/rest/base/CrudResource.js +19 -33
- package/dist/rest/base/CrudResource.js.map +1 -1
- package/dist/rest/base/CrudWithAddresses.d.ts +3 -2
- package/dist/rest/base/CrudWithAddresses.js +2 -2
- package/dist/rest/base/CrudWithAddresses.js.map +1 -1
- package/dist/rest/base/FabricResource.d.ts +15 -0
- package/dist/rest/base/FabricResource.js +16 -0
- package/dist/rest/base/FabricResource.js.map +1 -0
- package/dist/rest/base/ReadResource.d.ts +62 -0
- package/dist/rest/base/ReadResource.js +69 -0
- package/dist/rest/base/ReadResource.js.map +1 -0
- package/dist/rest/callHandler.d.ts +5 -2
- package/dist/rest/callHandler.js +4 -1
- package/dist/rest/callHandler.js.map +1 -1
- package/dist/rest/index.d.ts +18 -77
- package/dist/rest/index.js +47 -120
- package/dist/rest/index.js.map +1 -1
- package/dist/rest/namespaces/_client_tree_generated.d.ts +103 -0
- package/dist/rest/namespaces/_client_tree_generated.js +171 -0
- package/dist/rest/namespaces/_client_tree_generated.js.map +1 -0
- package/dist/rest/namespaces/addresses.d.ts +3 -42
- package/dist/rest/namespaces/addresses.js +3 -50
- package/dist/rest/namespaces/addresses.js.map +1 -1
- package/dist/rest/namespaces/calling.d.ts +6 -378
- package/dist/rest/namespaces/calling.js +6 -473
- package/dist/rest/namespaces/calling.js.map +1 -1
- package/dist/rest/namespaces/calling.resources.generated.d.ts +165 -0
- package/dist/rest/namespaces/calling.resources.generated.js +477 -0
- package/dist/rest/namespaces/calling.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/calling.types.generated.d.ts +2917 -0
- package/dist/rest/namespaces/calling.types.generated.js +8 -0
- package/dist/rest/namespaces/calling.types.generated.js.map +1 -0
- package/dist/rest/namespaces/chat.d.ts +4 -18
- package/dist/rest/namespaces/chat.js +4 -21
- package/dist/rest/namespaces/chat.js.map +1 -1
- package/dist/rest/namespaces/chat.resources.generated.d.ts +12 -0
- package/dist/rest/namespaces/chat.resources.generated.js +29 -0
- package/dist/rest/namespaces/chat.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/chat.types.generated.d.ts +56 -0
- package/dist/rest/namespaces/chat.types.generated.js +8 -0
- package/dist/rest/namespaces/chat.types.generated.js.map +1 -0
- package/dist/rest/namespaces/datasphere.d.ts +6 -62
- package/dist/rest/namespaces/datasphere.js +6 -72
- package/dist/rest/namespaces/datasphere.js.map +1 -1
- package/dist/rest/namespaces/datasphere.resources.generated.d.ts +25 -0
- package/dist/rest/namespaces/datasphere.resources.generated.js +50 -0
- package/dist/rest/namespaces/datasphere.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/datasphere.types.generated.d.ts +180 -0
- package/dist/rest/namespaces/datasphere.types.generated.js +8 -0
- package/dist/rest/namespaces/datasphere.types.generated.js.map +1 -0
- package/dist/rest/namespaces/fabric.d.ts +11 -327
- package/dist/rest/namespaces/fabric.js +14 -439
- package/dist/rest/namespaces/fabric.js.map +1 -1
- package/dist/rest/namespaces/fabric.resources.generated.d.ts +195 -0
- package/dist/rest/namespaces/fabric.resources.generated.js +399 -0
- package/dist/rest/namespaces/fabric.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/fabric.types.generated.d.ts +4557 -0
- package/dist/rest/namespaces/fabric.types.generated.js +8 -0
- package/dist/rest/namespaces/fabric.types.generated.js.map +1 -0
- package/dist/rest/namespaces/fax.resources.generated.d.ts +6 -0
- package/dist/rest/namespaces/fax.resources.generated.js +14 -0
- package/dist/rest/namespaces/fax.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/fax.types.generated.d.ts +131 -0
- package/dist/rest/namespaces/fax.types.generated.js +8 -0
- package/dist/rest/namespaces/fax.types.generated.js.map +1 -0
- package/dist/rest/namespaces/imported-numbers.d.ts +3 -18
- package/dist/rest/namespaces/imported-numbers.js +3 -21
- package/dist/rest/namespaces/imported-numbers.js.map +1 -1
- package/dist/rest/namespaces/logs.d.ts +10 -101
- package/dist/rest/namespaces/logs.js +10 -128
- package/dist/rest/namespaces/logs.js.map +1 -1
- package/dist/rest/namespaces/logs.resources.generated.d.ts +9 -0
- package/dist/rest/namespaces/logs.resources.generated.js +17 -0
- package/dist/rest/namespaces/logs.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/logs.types.generated.d.ts +131 -0
- package/dist/rest/namespaces/logs.types.generated.js +8 -0
- package/dist/rest/namespaces/logs.types.generated.js.map +1 -0
- package/dist/rest/namespaces/lookup.d.ts +3 -25
- package/dist/rest/namespaces/lookup.js +3 -27
- package/dist/rest/namespaces/lookup.js.map +1 -1
- package/dist/rest/namespaces/message.resources.generated.d.ts +6 -0
- package/dist/rest/namespaces/message.resources.generated.js +14 -0
- package/dist/rest/namespaces/message.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/message.types.generated.d.ts +122 -0
- package/dist/rest/namespaces/message.types.generated.js +8 -0
- package/dist/rest/namespaces/message.types.generated.js.map +1 -0
- package/dist/rest/namespaces/messages.resources.generated.d.ts +18 -0
- package/dist/rest/namespaces/messages.resources.generated.js +44 -0
- package/dist/rest/namespaces/messages.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/messages.types.generated.d.ts +99 -0
- package/dist/rest/namespaces/messages.types.generated.js +8 -0
- package/dist/rest/namespaces/messages.types.generated.js.map +1 -0
- package/dist/rest/namespaces/mfa.d.ts +3 -42
- package/dist/rest/namespaces/mfa.js +3 -49
- package/dist/rest/namespaces/mfa.js.map +1 -1
- package/dist/rest/namespaces/number-groups.d.ts +3 -45
- package/dist/rest/namespaces/number-groups.js +3 -53
- package/dist/rest/namespaces/number-groups.js.map +1 -1
- package/dist/rest/namespaces/phone-numbers.d.ts +8 -196
- package/dist/rest/namespaces/phone-numbers.js +8 -230
- package/dist/rest/namespaces/phone-numbers.js.map +1 -1
- package/dist/rest/namespaces/project.d.ts +6 -42
- package/dist/rest/namespaces/project.js +6 -51
- package/dist/rest/namespaces/project.js.map +1 -1
- package/dist/rest/namespaces/project.resources.generated.d.ts +17 -0
- package/dist/rest/namespaces/project.resources.generated.js +44 -0
- package/dist/rest/namespaces/project.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/project.types.generated.d.ts +58 -0
- package/dist/rest/namespaces/project.types.generated.js +8 -0
- package/dist/rest/namespaces/project.types.generated.js.map +1 -0
- package/dist/rest/namespaces/projects.resources.generated.d.ts +12 -0
- package/dist/rest/namespaces/projects.resources.generated.js +25 -0
- package/dist/rest/namespaces/projects.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/projects.types.generated.d.ts +77 -0
- package/dist/rest/namespaces/projects.types.generated.js +8 -0
- package/dist/rest/namespaces/projects.types.generated.js.map +1 -0
- package/dist/rest/namespaces/pubsub.d.ts +4 -18
- package/dist/rest/namespaces/pubsub.js +4 -21
- package/dist/rest/namespaces/pubsub.js.map +1 -1
- package/dist/rest/namespaces/pubsub.resources.generated.d.ts +12 -0
- package/dist/rest/namespaces/pubsub.resources.generated.js +29 -0
- package/dist/rest/namespaces/pubsub.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/pubsub.types.generated.d.ts +60 -0
- package/dist/rest/namespaces/pubsub.types.generated.js +8 -0
- package/dist/rest/namespaces/pubsub.types.generated.js.map +1 -0
- package/dist/rest/namespaces/queues.d.ts +3 -38
- package/dist/rest/namespaces/queues.js +3 -44
- package/dist/rest/namespaces/queues.js.map +1 -1
- package/dist/rest/namespaces/recordings.d.ts +3 -34
- package/dist/rest/namespaces/recordings.js +3 -40
- package/dist/rest/namespaces/recordings.js.map +1 -1
- package/dist/rest/namespaces/registry.d.ts +6 -137
- package/dist/rest/namespaces/registry.js +6 -173
- package/dist/rest/namespaces/registry.js.map +1 -1
- package/dist/rest/namespaces/relay-rest.resources.generated.d.ts +168 -0
- package/dist/rest/namespaces/relay-rest.resources.generated.js +430 -0
- package/dist/rest/namespaces/relay-rest.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/relay-rest.types.generated.d.ts +1906 -0
- package/dist/rest/namespaces/relay-rest.types.generated.js +8 -0
- package/dist/rest/namespaces/relay-rest.types.generated.js.map +1 -0
- package/dist/rest/namespaces/short-codes.d.ts +3 -35
- package/dist/rest/namespaces/short-codes.js +3 -41
- package/dist/rest/namespaces/short-codes.js.map +1 -1
- package/dist/rest/namespaces/sip-profile.d.ts +3 -24
- package/dist/rest/namespaces/sip-profile.js +3 -29
- package/dist/rest/namespaces/sip-profile.js.map +1 -1
- package/dist/rest/namespaces/verified-callers.d.ts +3 -29
- package/dist/rest/namespaces/verified-callers.js +3 -34
- package/dist/rest/namespaces/verified-callers.js.map +1 -1
- package/dist/rest/namespaces/video.d.ts +10 -227
- package/dist/rest/namespaces/video.js +10 -288
- package/dist/rest/namespaces/video.js.map +1 -1
- package/dist/rest/namespaces/video.resources.generated.d.ts +81 -0
- package/dist/rest/namespaces/video.resources.generated.js +171 -0
- package/dist/rest/namespaces/video.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/video.types.generated.d.ts +771 -0
- package/dist/rest/namespaces/video.types.generated.js +8 -0
- package/dist/rest/namespaces/video.types.generated.js.map +1 -0
- package/dist/rest/namespaces/voice.resources.generated.d.ts +9 -0
- package/dist/rest/namespaces/voice.resources.generated.js +17 -0
- package/dist/rest/namespaces/voice.resources.generated.js.map +1 -0
- package/dist/rest/namespaces/voice.types.generated.d.ts +214 -0
- package/dist/rest/namespaces/voice.types.generated.js +8 -0
- package/dist/rest/namespaces/voice.types.generated.js.map +1 -0
- package/dist/rest/pagination.d.ts +5 -1
- package/dist/rest/pagination.js +40 -20
- package/dist/rest/pagination.js.map +1 -1
- package/dist/rest/types.d.ts +21 -3
- package/dist/schema.json +299 -98
- package/dist/skills/SkillBase.d.ts +111 -21
- package/dist/skills/SkillBase.js +100 -17
- package/dist/skills/SkillBase.js.map +1 -1
- package/dist/skills/SkillManager.d.ts +66 -13
- package/dist/skills/SkillManager.js +101 -20
- package/dist/skills/SkillManager.js.map +1 -1
- package/dist/skills/SkillName.d.ts +44 -0
- package/dist/skills/SkillName.js +2 -0
- package/dist/skills/SkillName.js.map +1 -0
- package/dist/skills/SkillRegistry.d.ts +22 -11
- package/dist/skills/SkillRegistry.js +47 -17
- package/dist/skills/SkillRegistry.js.map +1 -1
- package/dist/skills/builtin/api_ninjas_trivia.d.ts +3 -1
- package/dist/skills/builtin/api_ninjas_trivia.js +18 -6
- package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
- package/dist/skills/builtin/ask_claude.d.ts +14 -4
- package/dist/skills/builtin/ask_claude.js +36 -14
- package/dist/skills/builtin/ask_claude.js.map +1 -1
- package/dist/skills/builtin/claude_skills.d.ts +3 -1
- package/dist/skills/builtin/claude_skills.js +19 -15
- package/dist/skills/builtin/claude_skills.js.map +1 -1
- package/dist/skills/builtin/custom_skills.d.ts +10 -3
- package/dist/skills/builtin/custom_skills.js +26 -9
- package/dist/skills/builtin/custom_skills.js.map +1 -1
- package/dist/skills/builtin/datasphere.d.ts +5 -3
- package/dist/skills/builtin/datasphere.js +21 -22
- package/dist/skills/builtin/datasphere.js.map +1 -1
- package/dist/skills/builtin/datasphere_serverless.d.ts +12 -1
- package/dist/skills/builtin/datasphere_serverless.js +17 -6
- package/dist/skills/builtin/datasphere_serverless.js.map +1 -1
- package/dist/skills/builtin/datetime.d.ts +3 -1
- package/dist/skills/builtin/datetime.js +11 -7
- package/dist/skills/builtin/datetime.js.map +1 -1
- package/dist/skills/builtin/google_maps.d.ts +29 -14
- package/dist/skills/builtin/google_maps.js +89 -269
- package/dist/skills/builtin/google_maps.js.map +1 -1
- package/dist/skills/builtin/index.d.ts +8 -6
- package/dist/skills/builtin/index.js +8 -6
- package/dist/skills/builtin/index.js.map +1 -1
- package/dist/skills/builtin/info_gatherer.d.ts +4 -2
- package/dist/skills/builtin/info_gatherer.js +20 -12
- package/dist/skills/builtin/info_gatherer.js.map +1 -1
- package/dist/skills/builtin/joke.d.ts +16 -6
- package/dist/skills/builtin/joke.js +54 -37
- package/dist/skills/builtin/joke.js.map +1 -1
- package/dist/skills/builtin/math.d.ts +3 -1
- package/dist/skills/builtin/math.js +14 -9
- package/dist/skills/builtin/math.js.map +1 -1
- package/dist/skills/builtin/mcp_gateway.d.ts +34 -5
- package/dist/skills/builtin/mcp_gateway.js +77 -46
- package/dist/skills/builtin/mcp_gateway.js.map +1 -1
- package/dist/skills/builtin/native_vector_search.d.ts +19 -5
- package/dist/skills/builtin/native_vector_search.js +179 -61
- package/dist/skills/builtin/native_vector_search.js.map +1 -1
- package/dist/skills/builtin/play_background_file.d.ts +21 -15
- package/dist/skills/builtin/play_background_file.js +43 -122
- package/dist/skills/builtin/play_background_file.js.map +1 -1
- package/dist/skills/builtin/spider.d.ts +42 -4
- package/dist/skills/builtin/spider.js +277 -104
- package/dist/skills/builtin/spider.js.map +1 -1
- package/dist/skills/builtin/swml_transfer.d.ts +14 -3
- package/dist/skills/builtin/swml_transfer.js +45 -24
- package/dist/skills/builtin/swml_transfer.js.map +1 -1
- package/dist/skills/builtin/weather_api.d.ts +24 -13
- package/dist/skills/builtin/weather_api.js +38 -30
- package/dist/skills/builtin/weather_api.js.map +1 -1
- package/dist/skills/builtin/web_search.d.ts +48 -10
- package/dist/skills/builtin/web_search.js +294 -100
- package/dist/skills/builtin/web_search.js.map +1 -1
- package/dist/skills/builtin/wikipedia_search.d.ts +4 -2
- package/dist/skills/builtin/wikipedia_search.js +14 -13
- package/dist/skills/builtin/wikipedia_search.js.map +1 -1
- package/dist/skills/index.d.ts +3 -2
- package/dist/skills/index.js +1 -1
- package/dist/skills/index.js.map +1 -1
- package/dist/swml_verbs_generated.d.ts +2824 -0
- package/dist/swml_verbs_generated.js +12 -0
- package/dist/swml_verbs_generated.js.map +1 -0
- package/dist/types.d.ts +59 -6
- package/dist/web.d.ts +27 -0
- package/dist/web.js +20 -0
- package/dist/web.js.map +1 -0
- package/docs/agent-guide.md +1034 -0
- package/docs/ai_chat.md +560 -0
- package/docs/api-reference.md +3641 -0
- package/docs/architecture.md +846 -0
- package/docs/bedrock_agent.md +411 -0
- package/docs/cli-guide.md +403 -0
- package/docs/cloud_functions_guide.md +399 -0
- package/docs/configuration.md +548 -0
- package/docs/contexts-guide.md +884 -0
- package/docs/datamap-guide.md +1207 -0
- package/docs/developer_pain_points.md +548 -0
- package/docs/llm_parameters.md +298 -0
- package/docs/mcp_gateway_reference.md +354 -0
- package/docs/mcp_integration.md +162 -0
- package/docs/pgi_agent_guide.md +1820 -0
- package/docs/prefabs-guide.md +815 -0
- package/docs/programmatically_governed_inference.md +301 -0
- package/docs/sdk_features.md +501 -0
- package/docs/security.md +559 -0
- package/docs/serverless-guide.md +520 -0
- package/docs/skills-guide.md +1223 -0
- package/docs/skills-system.md +405 -0
- package/docs/skills_parameter_schema.md +417 -0
- package/docs/swaig-reference.md +1986 -0
- package/docs/swml_service_guide.md +573 -0
- package/docs/third_party_skills.md +410 -0
- package/docs/web_service.md +666 -0
- package/examples/README.md +202 -0
- package/examples/advanced-datamap.ts +108 -0
- package/examples/advanced-dynamic-config.ts +70 -0
- package/examples/auto-vivified.ts +95 -0
- package/examples/call-flow.ts +65 -0
- package/examples/comprehensive-dynamic.ts +125 -0
- package/examples/contexts-steps.ts +65 -0
- package/examples/custom-path.ts +45 -0
- package/examples/datamap-tools.ts +51 -0
- package/examples/datasphere-multi-instance.ts +66 -0
- package/examples/datasphere-serverless-env.ts +87 -0
- package/examples/datasphere-webhook-env.ts +65 -0
- package/examples/datasphere.ts +56 -0
- package/examples/declarative.ts +100 -0
- package/examples/dynamic-config.ts +54 -0
- package/examples/dynamic-info-gatherer.ts +69 -0
- package/examples/dynamic-swml-service.ts +67 -0
- package/examples/gather-info.ts +95 -0
- package/examples/gather-per-question-functions-demo.ts +139 -0
- package/examples/joke-agent.ts +34 -0
- package/examples/kubernetes-agent.ts +45 -0
- package/examples/llm-params.ts +75 -0
- package/examples/mcp-agent.ts +89 -0
- package/examples/mcp-gateway.ts +81 -0
- package/examples/multi-agent.ts +80 -0
- package/examples/multi-endpoint.ts +79 -0
- package/examples/pgi/case-domain.ts +114 -0
- package/examples/pgi/serve.ts +16 -0
- package/examples/pgi/support-agent.ts +265 -0
- package/examples/pom-prompt.ts +70 -0
- package/examples/prefab-concierge.ts +42 -0
- package/examples/prefab-faq.ts +58 -0
- package/examples/prefab-info-gatherer.ts +33 -0
- package/examples/prefab-receptionist.ts +36 -0
- package/examples/prefab-survey.ts +69 -0
- package/examples/quickstart-agent.ts +29 -0
- package/examples/quickstart-relay.ts +25 -0
- package/examples/quickstart-rest.ts +25 -0
- package/examples/record-call.ts +65 -0
- package/examples/relay-demo.ts +33 -0
- package/examples/room-and-sip.ts +93 -0
- package/examples/serverless-lambda.ts +43 -0
- package/examples/session-state.ts +83 -0
- package/examples/simple-agent.ts +36 -0
- package/examples/simple-static.ts +29 -0
- package/examples/skills-demo.ts +41 -0
- package/examples/step-function-inheritance-demo.ts +124 -0
- package/examples/swaig-features.ts +193 -0
- package/examples/swml-service-routing.ts +66 -0
- package/examples/swml-service.ts +38 -0
- package/examples/swmlservice_ai_sidecar.ts +104 -0
- package/examples/swmlservice_swaig_standalone.ts +79 -0
- package/examples/tap.ts +67 -0
- package/examples/typed-tools.ts +68 -0
- package/examples/verb-methods.ts +45 -0
- package/examples/web-search-multi-instance.ts +75 -0
- package/examples/web-search.ts +38 -0
- package/examples/wikipedia.ts +36 -0
- package/livewire/README.md +164 -0
- package/livewire/docs/migration-guide.md +251 -0
- package/livewire/examples/livewire-basic-agent.ts +74 -0
- package/livewire/examples/livewire-handoff.ts +196 -0
- package/livewire/examples/livewire-multi-tool.ts +121 -0
- package/package.json +85 -13
- package/relay/README.md +101 -0
- package/relay/docs/call-methods.md +622 -0
- package/relay/docs/client-reference.md +281 -0
- package/relay/docs/events.md +193 -0
- package/relay/docs/getting-started.md +221 -0
- package/relay/docs/guide.md +386 -0
- package/relay/docs/messaging.md +246 -0
- package/relay/examples/relay-inbound.ts +66 -0
- package/relay/examples/relay-messaging.ts +74 -0
- package/relay/examples/relay-outbound.ts +76 -0
- package/rest/README.md +141 -0
- package/rest/docs/calling.md +313 -0
- package/rest/docs/client-reference.md +149 -0
- package/rest/docs/fabric.md +192 -0
- package/rest/docs/getting-started.md +138 -0
- package/rest/docs/guide.md +421 -0
- package/rest/docs/namespaces.md +367 -0
- package/rest/docs/phone-binding.md +116 -0
- package/rest/examples/rest-10dlc-registration.ts +177 -0
- package/rest/examples/rest-bind-phone-to-swml-webhook.ts +66 -0
- package/rest/examples/rest-calling-ivr-and-ai.ts +136 -0
- package/rest/examples/rest-calling-play-and-record.ts +98 -0
- package/rest/examples/rest-client.ts +59 -0
- package/rest/examples/rest-datasphere-search.ts +81 -0
- package/rest/examples/rest-fabric-conferences-and-routing.ts +147 -0
- package/rest/examples/rest-fabric-subscribers-and-sip.ts +106 -0
- package/rest/examples/rest-fabric-swml-and-callflows.ts +101 -0
- package/rest/examples/rest-manage-resources.ts +64 -0
- package/rest/examples/rest-phone-number-management.ts +200 -0
- package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
- package/rest/examples/rest-video-rooms.ts +186 -0
- package/tutorial/fred/fred.ts +218 -0
- package/tutorial/fred/tutorial/01-introduction.md +141 -0
- package/tutorial/fred/tutorial/02-setup.md +304 -0
- package/tutorial/fred/tutorial/03-basic-agent.md +284 -0
- package/tutorial/fred/tutorial/04-wikipedia-skill.md +298 -0
- package/tutorial/fred/tutorial/05-custom-functions.md +347 -0
- package/tutorial/fred/tutorial/06-running-testing.md +642 -0
- package/tutorial/fred/tutorial/README.md +56 -0
- package/tutorial/fred/tutorial/appendix-complete-code.md +632 -0
- package/tutorial/fred/tutorial/appendix-docker-deployment.md +504 -0
- package/tutorial/full-guardrails-agent/handlers.ts +436 -0
- package/tutorial/full-guardrails-agent/penny.ts +305 -0
- package/tutorial/full-guardrails-agent/reservations.ts +1109 -0
- package/tutorial/full-guardrails-agent/tutorial/01-why-guardrails.md +149 -0
- package/tutorial/full-guardrails-agent/tutorial/02-design-first.md +139 -0
- package/tutorial/full-guardrails-agent/tutorial/03-rules-first.md +422 -0
- package/tutorial/full-guardrails-agent/tutorial/04-the-shell.md +238 -0
- package/tutorial/full-guardrails-agent/tutorial/05-steps-and-scoping.md +247 -0
- package/tutorial/full-guardrails-agent/tutorial/06-tools-that-decide.md +467 -0
- package/tutorial/full-guardrails-agent/tutorial/07-gather-and-projection.md +160 -0
- package/tutorial/full-guardrails-agent/tutorial/08-the-verification-gate.md +333 -0
- package/tutorial/full-guardrails-agent/tutorial/09-people-and-endings.md +313 -0
- package/tutorial/full-guardrails-agent/tutorial/10-testing-and-running.md +387 -0
- package/tutorial/full-guardrails-agent/tutorial/README.md +106 -0
- package/tutorial/full-guardrails-agent/tutorial/appendix-complete-code.md +2207 -0
- package/tutorial/full-guardrails-agent/tutorial/appendix-deployment.md +191 -0
- package/tutorial/full-guardrails-agent/tutorial/appendix-technique-map.md +117 -0
- package/tutorial/full-guardrails-agent/workflow.ts +219 -0
- package/tutorial/multi_agents/README.md +175 -0
- package/tutorial/multi_agents/advanced_agent.ts +395 -0
- package/tutorial/multi_agents/extending_agents.ts +641 -0
- package/tutorial/multi_agents/knowledge.ts +59 -0
- package/tutorial/multi_agents/lesson1_first_agent.md +368 -0
- package/tutorial/multi_agents/lesson2_knowledge_bases.md +404 -0
- package/tutorial/multi_agents/lesson3_multi_agent_systems.md +621 -0
- package/tutorial/multi_agents/lesson4_advanced_features.md +805 -0
- package/tutorial/multi_agents/lesson5_extending_agents.md +856 -0
- package/tutorial/multi_agents/pc_builder.ts +529 -0
- package/tutorial/multi_agents/sales_agent.ts +88 -0
- package/tutorial/multi_agents/sales_agent_with_search.ts +116 -0
- package/tutorial/multi_agents/sales_knowledge.md +139 -0
- package/tutorial/multi_agents/support_knowledge.md +256 -0
- package/dist/cli/mock-data.d.ts +0 -37
- package/dist/cli/mock-data.js +0 -80
- package/dist/cli/mock-data.js.map +0 -1
- package/dist/generateVerbTypes.d.ts +0 -11
- package/dist/generateVerbTypes.js +0 -265
- package/dist/generateVerbTypes.js.map +0 -1
- package/dist/rest/namespaces/compat.d.ts +0 -585
- package/dist/rest/namespaces/compat.js +0 -735
- package/dist/rest/namespaces/compat.js.map +0 -1
|
@@ -0,0 +1,666 @@
|
|
|
1
|
+
# WebService Documentation
|
|
2
|
+
|
|
3
|
+
The `WebService` class serves static files from local directories over HTTP or HTTPS. It's built on [Hono](https://hono.dev/) and runs on its own port, standalone or next to your agents.
|
|
4
|
+
|
|
5
|
+
<!-- snippet-setup -->
|
|
6
|
+
```ts
|
|
7
|
+
export {}; // treat each example as a module (top-level await)
|
|
8
|
+
declare global {
|
|
9
|
+
const WebService: typeof import('@signalwire/sdk').WebService;
|
|
10
|
+
}
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Table of Contents
|
|
14
|
+
- [Overview](#overview)
|
|
15
|
+
- [Installation](#installation)
|
|
16
|
+
- [Quick Start](#quick-start)
|
|
17
|
+
- [Configuration](#configuration)
|
|
18
|
+
- [Security Features](#security-features)
|
|
19
|
+
- [HTTPS/SSL Support](#httpsssl-support)
|
|
20
|
+
- [API Endpoints](#api-endpoints)
|
|
21
|
+
- [Usage Examples](#usage-examples)
|
|
22
|
+
- [Deployment Patterns](#deployment-patterns)
|
|
23
|
+
- [Best Practices](#best-practices)
|
|
24
|
+
- [API Reference](#api-reference)
|
|
25
|
+
- [Integration with SignalWire Agents](#integration-with-signalwire-agents)
|
|
26
|
+
|
|
27
|
+
## Overview
|
|
28
|
+
|
|
29
|
+
`WebService` serves files from local directories, each at its own URL prefix. You can use it to serve:
|
|
30
|
+
- Audio files that an agent's SWML plays
|
|
31
|
+
- Documentation, API specs and reports
|
|
32
|
+
- Static assets such as images, CSS and JavaScript
|
|
33
|
+
|
|
34
|
+
It has these features:
|
|
35
|
+
- Several directories, each mounted at its own URL prefix
|
|
36
|
+
- HTTP Basic Authentication on every route but `/health`, CORS and security headers
|
|
37
|
+
- An allowlist and a blocklist of file extensions, and a maximum file size
|
|
38
|
+
- Optional HTML directory listings
|
|
39
|
+
- A content type chosen from the file extension
|
|
40
|
+
- HTTPS from PEM certificate and key files
|
|
41
|
+
|
|
42
|
+
## Installation
|
|
43
|
+
|
|
44
|
+
`WebService` is part of the SignalWire SDK package:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
npm install @signalwire/sdk
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The package requires Node.js 22 or later.
|
|
51
|
+
|
|
52
|
+
## Quick Start
|
|
53
|
+
|
|
54
|
+
This service serves two directories on port 8002, to clients that send its credentials:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
export SWML_BASIC_AUTH_USER="admin"
|
|
58
|
+
export SWML_BASIC_AUTH_PASSWORD="a-long-random-password"
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
<!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
|
|
62
|
+
```typescript
|
|
63
|
+
import { WebService } from '@signalwire/sdk';
|
|
64
|
+
|
|
65
|
+
// Create a service to serve files
|
|
66
|
+
const service = new WebService({
|
|
67
|
+
port: 8002,
|
|
68
|
+
directories: {
|
|
69
|
+
'/docs': './documentation',
|
|
70
|
+
'/assets': './static/assets',
|
|
71
|
+
},
|
|
72
|
+
});
|
|
73
|
+
|
|
74
|
+
// Start the service
|
|
75
|
+
await service.start();
|
|
76
|
+
// Service available at http://localhost:8002, with the credentials above
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`start()` throws if no credentials are configured. See [Basic Authentication](#basic-authentication).
|
|
80
|
+
|
|
81
|
+
## Configuration
|
|
82
|
+
|
|
83
|
+
Constructor options override values from a config file. For each setting, the constructor option wins, then the config file, then the default.
|
|
84
|
+
|
|
85
|
+
### 1. Constructor Options
|
|
86
|
+
|
|
87
|
+
The constructor takes a `WebServiceOptions` object:
|
|
88
|
+
|
|
89
|
+
```typescript
|
|
90
|
+
const service = new WebService({
|
|
91
|
+
port: 8002, // Port to bind to (default 8002)
|
|
92
|
+
directories: { // URL prefix to directory mappings
|
|
93
|
+
'/docs': './documentation',
|
|
94
|
+
'/assets': './static',
|
|
95
|
+
},
|
|
96
|
+
basicAuth: ['admin', 'a-long-random-password'], // [username, password]
|
|
97
|
+
enableDirectoryBrowsing: true, // Allow directory listings
|
|
98
|
+
allowedExtensions: ['.html', '.css', '.js'], // Allowlist extensions
|
|
99
|
+
blockedExtensions: ['.env', '.key'], // Replaces the default blocklist
|
|
100
|
+
maxFileSize: 100 * 1024 * 1024, // Max file size (100 MB)
|
|
101
|
+
enableCors: true, // Enable CORS headers (default true)
|
|
102
|
+
});
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### 2. Environment Variables
|
|
106
|
+
|
|
107
|
+
`WebService` reads these environment variables:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
# Basic auth credentials, used when neither the basicAuth option nor the config file sets them
|
|
111
|
+
export SWML_BASIC_AUTH_USER="admin" # defaults to signalwire
|
|
112
|
+
export SWML_BASIC_AUTH_PASSWORD="a-long-random-password"
|
|
113
|
+
|
|
114
|
+
# SSL/HTTPS configuration (via SslConfig), used when the ssl option doesn't set them
|
|
115
|
+
export SWML_SSL_ENABLED=true
|
|
116
|
+
export SWML_SSL_CERT_PATH="/path/to/cert.pem"
|
|
117
|
+
export SWML_SSL_KEY_PATH="/path/to/key.pem"
|
|
118
|
+
|
|
119
|
+
# CORS origins (comma-separated; defaults to *)
|
|
120
|
+
export SWML_CORS_ORIGINS="https://app.example.com"
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
It doesn't read `PORT`; set the `port` option or the config file's `service.port`.
|
|
124
|
+
|
|
125
|
+
### 3. Configuration File
|
|
126
|
+
|
|
127
|
+
Pass `configFile` to load a JSON file. The values under the `service` key map to the constructor options:
|
|
128
|
+
|
|
129
|
+
```json
|
|
130
|
+
{
|
|
131
|
+
"service": {
|
|
132
|
+
"port": 8002,
|
|
133
|
+
"directories": {
|
|
134
|
+
"/docs": "./documentation",
|
|
135
|
+
"/api": "./api-specs",
|
|
136
|
+
"/reports": "./generated/reports"
|
|
137
|
+
},
|
|
138
|
+
"enableDirectoryBrowsing": true,
|
|
139
|
+
"maxFileSize": 52428800,
|
|
140
|
+
"allowedExtensions": [".html", ".css", ".js", ".json", ".pdf"],
|
|
141
|
+
"blockedExtensions": [".env", ".key", ".pem"],
|
|
142
|
+
"enableCors": true
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
This constructor loads that file:
|
|
148
|
+
|
|
149
|
+
```typescript
|
|
150
|
+
const service = new WebService({ configFile: './web_service.json' });
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
The file can set credentials under `security.auth.basic` (`{"user": ..., "password": ...}`), but not `ssl`. Directories from the file and from the `directories` option are merged, and the option wins for the same prefix. Relative directory paths resolve against the process's working directory. A `configFile` that is missing or isn't valid JSON is skipped with a warning.
|
|
154
|
+
|
|
155
|
+
Without `configFile`, the constructor looks for `web_service.json` in the working directory, `./config/`, `~/.signalwire/`, `./.swml/`, `~/.swml/` and `/etc/swml/`, and loads the first one it finds. If that file isn't valid JSON, the constructor logs a warning and starts from its other settings. See [Search Paths](configuration.md#search-paths) in the configuration guide.
|
|
156
|
+
|
|
157
|
+
## Security Features
|
|
158
|
+
|
|
159
|
+
### Basic Authentication
|
|
160
|
+
|
|
161
|
+
The service takes its credentials from the first of these that sets a password:
|
|
162
|
+
|
|
163
|
+
1. The `basicAuth: ['username', 'password']` option
|
|
164
|
+
2. The config file's `security.auth.basic` `user` and `password`
|
|
165
|
+
3. The `SWML_BASIC_AUTH_USER` and `SWML_BASIC_AUTH_PASSWORD` environment variables
|
|
166
|
+
|
|
167
|
+
The user defaults to `signalwire` when only a password is set, and an empty password doesn't count. Every route except `/health` requires HTTP Basic Authentication, `/` included.
|
|
168
|
+
|
|
169
|
+
Without credentials from any of these, the service generates a password it never shows, so `getApp()` refuses every request but `/health` with `401`, and `start()` throws:
|
|
170
|
+
|
|
171
|
+
```text
|
|
172
|
+
WebService needs basic-auth credentials: set SWML_BASIC_AUTH_USER and SWML_BASIC_AUTH_PASSWORD, pass basicAuth: [user, password], or set security.auth.basic in the config file. A generated password is never shown, so every file request would be refused.
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
`start()` logs the user and where the credentials came from (`provided`, `config file` or `environment`), not the password.
|
|
176
|
+
|
|
177
|
+
### File Security
|
|
178
|
+
|
|
179
|
+
#### Default Blocked Extensions and Files
|
|
180
|
+
|
|
181
|
+
The default blocklist refuses these files:
|
|
182
|
+
- `.env`, `.git`, `.gitignore`
|
|
183
|
+
- `.key`, `.pem`, `.crt`
|
|
184
|
+
- `.pyc`, `__pycache__`
|
|
185
|
+
- `.DS_Store`, `.swp`
|
|
186
|
+
|
|
187
|
+
An entry that starts with a dot matches a file extension or a whole file name. Any other entry matches a file name, or any part of the file's path below the mount. Every entry also matches a directory on the path below the mount, so `__pycache__` blocks `/__pycache__/data.txt`. Passing `blockedExtensions` replaces the default list, so include the defaults you still want.
|
|
188
|
+
|
|
189
|
+
#### Hidden Files and Directories
|
|
190
|
+
|
|
191
|
+
Whatever `blockedExtensions` holds, the service refuses with `403` any path whose components below the mount include one that starts with a dot, whether the file exists or not. That covers `/.env.production`, anything under `/.git/`, `/.ssh/` or `/.aws/`, and the encoded form `/%2eenv`. The one exception is `.well-known`, so ACME challenges and `security.txt` are served from `/.well-known/`, though a dot-named file inside it isn't. A directory mounted from a path that itself contains a dot directory, such as `~/.site/public`, is served normally: only the components below the mount count. Directory listings hide dot entries and blocked names.
|
|
192
|
+
|
|
193
|
+
The blocklist, the hidden-path rule and `allowedExtensions` apply both to the path in the request and to the file actually read. A symbolic link inside the mount, such as `alias.txt` pointing to `.env`, `keys` pointing to `.ssh`, or a link into a `__pycache__` directory, gets `403` like the file it points to. The same goes for a directory's `index.html`.
|
|
194
|
+
|
|
195
|
+
#### Path Traversal Protection
|
|
196
|
+
|
|
197
|
+
`WebService` refuses a path containing `..` with `403`, and checks that the resolved path is inside the mounted directory. A `..` segment in a request URL is resolved when the URL is parsed, before routing, so `GET /docs/../../etc/passwd` becomes `GET /etc/passwd`. That path matches no mount and gets `404`.
|
|
198
|
+
|
|
199
|
+
The check follows symbolic links. A link inside a mounted directory serves its target only when the target is also inside the directory; a link to a file or directory outside it gets `403`. A directory listing doesn't show symbolic links.
|
|
200
|
+
|
|
201
|
+
#### File Size Limits
|
|
202
|
+
|
|
203
|
+
A file larger than `maxFileSize` gets `403`, like a blocked file type. The default maximum is 100 MB. This service sets 50 MB:
|
|
204
|
+
|
|
205
|
+
```typescript
|
|
206
|
+
const service = new WebService({ maxFileSize: 50 * 1024 * 1024 }); // 50 MB
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
### Security Headers
|
|
210
|
+
|
|
211
|
+
Every response carries these headers:
|
|
212
|
+
- `X-Content-Type-Options: nosniff`
|
|
213
|
+
- `X-Frame-Options: DENY`
|
|
214
|
+
- `X-XSS-Protection: 1; mode=block`
|
|
215
|
+
- `Referrer-Policy: strict-origin-when-cross-origin`
|
|
216
|
+
- `Content-Security-Policy: default-src 'none'; frame-ancestors 'none'`
|
|
217
|
+
- `Permissions-Policy: camera=(), microphone=(), geolocation=()`
|
|
218
|
+
- `Strict-Transport-Security: max-age=31536000; includeSubDomains`, when SSL is configured through the `ssl` option or the `SWML_SSL_ENABLED`, `SWML_SSL_CERT_PATH` and `SWML_SSL_KEY_PATH` variables
|
|
219
|
+
|
|
220
|
+
With `enableCors` (the default), CORS allows the origins in `SWML_CORS_ORIGINS`, or any origin when it's unset or lists `*`.
|
|
221
|
+
|
|
222
|
+
## HTTPS/SSL Support
|
|
223
|
+
|
|
224
|
+
`WebService` serves HTTPS when SSL is enabled and both the certificate and the key files exist. If either file is missing, it serves plain HTTP. `start()` logs the scheme it uses.
|
|
225
|
+
|
|
226
|
+
### Method 1: Environment Variables
|
|
227
|
+
|
|
228
|
+
`SslConfig` reads the SSL settings from the environment:
|
|
229
|
+
|
|
230
|
+
```bash
|
|
231
|
+
export SWML_SSL_ENABLED=true
|
|
232
|
+
export SWML_SSL_CERT_PATH="/path/to/cert.pem"
|
|
233
|
+
export SWML_SSL_KEY_PATH="/path/to/key.pem"
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
### Method 2: Constructor `ssl` Option
|
|
237
|
+
|
|
238
|
+
The `ssl` option sets the same values. A field it leaves out falls back to its environment variable:
|
|
239
|
+
|
|
240
|
+
<!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
|
|
241
|
+
```typescript
|
|
242
|
+
const service = new WebService({
|
|
243
|
+
directories: { '/docs': './docs' },
|
|
244
|
+
ssl: { enabled: true, certPath: '/path/to/cert.pem', keyPath: '/path/to/key.pem' },
|
|
245
|
+
});
|
|
246
|
+
await service.start();
|
|
247
|
+
// Service available at https://localhost:8002
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
### Method 3: `start()` Parameters
|
|
251
|
+
|
|
252
|
+
`start(host, port, sslCert, sslKey)` takes the certificate and key paths directly. They replace the other SSL settings for that server:
|
|
253
|
+
|
|
254
|
+
<!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
|
|
255
|
+
```typescript
|
|
256
|
+
const service = new WebService({ directories: { '/docs': './docs' } });
|
|
257
|
+
await service.start('0.0.0.0', 8002, '/path/to/cert.pem', '/path/to/key.pem');
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
With this method alone, responses don't carry the `Strict-Transport-Security` header, because that header depends on the `ssl` option or the environment variables.
|
|
261
|
+
|
|
262
|
+
### Generating Self-Signed Certificates
|
|
263
|
+
|
|
264
|
+
For development and testing, `openssl` can create a self-signed certificate:
|
|
265
|
+
|
|
266
|
+
```bash
|
|
267
|
+
# Generate a self-signed certificate
|
|
268
|
+
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \
|
|
269
|
+
-days 365 -nodes -subj "/CN=localhost"
|
|
270
|
+
|
|
271
|
+
# Use with WebService
|
|
272
|
+
export SWML_SSL_ENABLED=true
|
|
273
|
+
export SWML_SSL_CERT_PATH="cert.pem"
|
|
274
|
+
export SWML_SSL_KEY_PATH="key.pem"
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
## API Endpoints
|
|
278
|
+
|
|
279
|
+
### GET /health
|
|
280
|
+
|
|
281
|
+
`GET /health` reports the service's configuration. It needs no credentials, so a load balancer can probe it. `authRequired` is always `true`.
|
|
282
|
+
|
|
283
|
+
**Response:**
|
|
284
|
+
```json
|
|
285
|
+
{
|
|
286
|
+
"status": "healthy",
|
|
287
|
+
"directories": ["/docs", "/assets"],
|
|
288
|
+
"sslEnabled": false,
|
|
289
|
+
"authRequired": true,
|
|
290
|
+
"directoryBrowsing": true
|
|
291
|
+
}
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
### GET /
|
|
295
|
+
|
|
296
|
+
`GET /` returns an HTML page that links to each mounted directory. With no directories, it returns `{"service":"SignalWire Web Service","directories":[]}`.
|
|
297
|
+
|
|
298
|
+
### GET /{route}/{filePath}
|
|
299
|
+
|
|
300
|
+
`GET` on a mounted prefix serves a file from that directory. `route` is the mounted prefix (for example, `/docs`), and `filePath` is the path of a file inside the directory.
|
|
301
|
+
|
|
302
|
+
**Response:**
|
|
303
|
+
- The file, with a content type from its extension (`application/octet-stream` for an unknown one) and `Cache-Control: public, max-age=3600`
|
|
304
|
+
- `404` if the file doesn't exist
|
|
305
|
+
- `403` if the path contains `..` or a component below the mount that starts with a dot (other than `.well-known`), resolves (through a symbolic link) to a file outside the mounted directory or under a hidden or blocked directory, or the file is blocked, isn't allowed, or is larger than `maxFileSize`
|
|
306
|
+
- `307` to the same path with a trailing slash, for a directory requested without one (`/docs/guide` redirects to `/docs/guide/`), so relative links in its `index.html` or listing resolve inside it. The `Location` is a path on this host, built from the path as the client sent it, still percent-encoded (`/docs/my%20dir` redirects to `/docs/my%20dir/`), without the query string and with leading slashes collapsed to one, so `//example.org` can't send the browser to another host.
|
|
307
|
+
- `401` without valid credentials
|
|
308
|
+
- For a directory requested with its trailing slash: with `enableDirectoryBrowsing`, an HTML listing of its subdirectories and allowed files, without dot files. Without it, the directory's `index.html` if that exists and is allowed, otherwise `403`.
|
|
309
|
+
|
|
310
|
+
## Usage Examples
|
|
311
|
+
|
|
312
|
+
The examples that don't pass `basicAuth` take their credentials from `SWML_BASIC_AUTH_USER` and `SWML_BASIC_AUTH_PASSWORD`, as in the [Quick Start](#quick-start).
|
|
313
|
+
|
|
314
|
+
### Basic File Serving
|
|
315
|
+
|
|
316
|
+
This service serves two directories on the default port:
|
|
317
|
+
|
|
318
|
+
<!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
|
|
319
|
+
```typescript
|
|
320
|
+
import { WebService } from '@signalwire/sdk';
|
|
321
|
+
|
|
322
|
+
// Serve documentation
|
|
323
|
+
const service = new WebService({
|
|
324
|
+
directories: {
|
|
325
|
+
'/docs': './documentation',
|
|
326
|
+
'/api': './api-specs',
|
|
327
|
+
},
|
|
328
|
+
});
|
|
329
|
+
await service.start();
|
|
330
|
+
|
|
331
|
+
// Files accessible at:
|
|
332
|
+
// http://localhost:8002/docs/index.html
|
|
333
|
+
// http://localhost:8002/api/swagger.json
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
### With Directory Browsing
|
|
337
|
+
|
|
338
|
+
This service lists the contents of `./public`:
|
|
339
|
+
|
|
340
|
+
<!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
|
|
341
|
+
```typescript
|
|
342
|
+
const service = new WebService({
|
|
343
|
+
directories: { '/files': './public' },
|
|
344
|
+
enableDirectoryBrowsing: true, // Allow browsing directories
|
|
345
|
+
});
|
|
346
|
+
await service.start();
|
|
347
|
+
|
|
348
|
+
// Browse files at: http://localhost:8002/files/
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
### Restricted File Types
|
|
352
|
+
|
|
353
|
+
This service serves only web assets:
|
|
354
|
+
|
|
355
|
+
```typescript
|
|
356
|
+
// Only serve web assets
|
|
357
|
+
const service = new WebService({
|
|
358
|
+
directories: { '/web': './www' },
|
|
359
|
+
allowedExtensions: ['.html', '.css', '.js', '.png', '.jpg', '.woff2'],
|
|
360
|
+
enableDirectoryBrowsing: false,
|
|
361
|
+
});
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
### Dynamic Directory Management
|
|
365
|
+
|
|
366
|
+
`addDirectory()` mounts a directory after construction, and `removeDirectory()` unmounts one. Both work on a running service and take effect from the next request.
|
|
367
|
+
|
|
368
|
+
<!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
|
|
369
|
+
```typescript
|
|
370
|
+
const service = new WebService();
|
|
371
|
+
service.addDirectory('/docs', './documentation');
|
|
372
|
+
await service.start();
|
|
373
|
+
|
|
374
|
+
// Later, while the service runs
|
|
375
|
+
service.addDirectory('/reports', './generated/reports');
|
|
376
|
+
service.removeDirectory('/docs'); // GET /docs/... now returns 404
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
When prefixes overlap, the longest one that matches the request path serves it. A directory mounted at `/` serves every path except `/` and `/health`.
|
|
380
|
+
|
|
381
|
+
`addDirectory()` throws if the directory doesn't exist or isn't a directory.
|
|
382
|
+
|
|
383
|
+
### With Credentials in Code
|
|
384
|
+
|
|
385
|
+
This service takes its credentials from the `basicAuth` option instead of the environment:
|
|
386
|
+
|
|
387
|
+
<!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
|
|
388
|
+
```typescript
|
|
389
|
+
const service = new WebService({
|
|
390
|
+
directories: { '/private': './sensitive-docs' },
|
|
391
|
+
basicAuth: ['admin', 'a-long-random-password'],
|
|
392
|
+
});
|
|
393
|
+
await service.start();
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
### HTTPS with an Existing Certificate
|
|
397
|
+
|
|
398
|
+
This service uses certificate files from a certificate authority, passed to `start()`:
|
|
399
|
+
|
|
400
|
+
<!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
|
|
401
|
+
```typescript
|
|
402
|
+
const service = new WebService({
|
|
403
|
+
directories: { '/secure': './secure-files' },
|
|
404
|
+
});
|
|
405
|
+
await service.start(
|
|
406
|
+
'0.0.0.0',
|
|
407
|
+
8002,
|
|
408
|
+
'/etc/letsencrypt/live/example.com/fullchain.pem',
|
|
409
|
+
'/etc/letsencrypt/live/example.com/privkey.pem',
|
|
410
|
+
);
|
|
411
|
+
// Service available at https://example.com:8002
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
### Multi-Environment Configuration
|
|
415
|
+
|
|
416
|
+
This setup serves HTTPS in production and a browsable directory in development:
|
|
417
|
+
|
|
418
|
+
<!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
|
|
419
|
+
```typescript
|
|
420
|
+
import { WebService } from '@signalwire/sdk';
|
|
421
|
+
|
|
422
|
+
let service: WebService;
|
|
423
|
+
|
|
424
|
+
if (process.env.NODE_ENV === 'production') {
|
|
425
|
+
service = new WebService({
|
|
426
|
+
port: 443,
|
|
427
|
+
directories: { '/': './dist' },
|
|
428
|
+
enableDirectoryBrowsing: false,
|
|
429
|
+
ssl: {
|
|
430
|
+
enabled: true,
|
|
431
|
+
certPath: '/etc/ssl/certs/production.crt',
|
|
432
|
+
keyPath: '/etc/ssl/private/production.key',
|
|
433
|
+
},
|
|
434
|
+
});
|
|
435
|
+
} else {
|
|
436
|
+
service = new WebService({
|
|
437
|
+
port: 8002,
|
|
438
|
+
directories: { '/': './src' },
|
|
439
|
+
enableDirectoryBrowsing: true,
|
|
440
|
+
});
|
|
441
|
+
}
|
|
442
|
+
|
|
443
|
+
await service.start();
|
|
444
|
+
```
|
|
445
|
+
|
|
446
|
+
## Deployment Patterns
|
|
447
|
+
|
|
448
|
+
### Standalone Service
|
|
449
|
+
|
|
450
|
+
This script (`web-server.ts`) runs `WebService` as a dedicated static file server:
|
|
451
|
+
|
|
452
|
+
<!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
|
|
453
|
+
```typescript
|
|
454
|
+
import { WebService } from '@signalwire/sdk';
|
|
455
|
+
|
|
456
|
+
const service = new WebService({
|
|
457
|
+
port: 8002,
|
|
458
|
+
directories: {
|
|
459
|
+
'/docs': '/var/www/docs',
|
|
460
|
+
'/assets': '/var/www/assets',
|
|
461
|
+
'/downloads': '/var/www/downloads',
|
|
462
|
+
},
|
|
463
|
+
});
|
|
464
|
+
|
|
465
|
+
await service.start();
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
### Alongside AI Agents
|
|
469
|
+
|
|
470
|
+
This script (`main.ts`) runs `WebService` on one port and an agent on another:
|
|
471
|
+
|
|
472
|
+
<!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
|
|
473
|
+
```typescript
|
|
474
|
+
import { AgentBase, WebService } from '@signalwire/sdk';
|
|
475
|
+
|
|
476
|
+
// Start WebService for documentation on port 8002
|
|
477
|
+
const web = new WebService({
|
|
478
|
+
port: 8002,
|
|
479
|
+
directories: { '/docs': './agent-docs' },
|
|
480
|
+
});
|
|
481
|
+
await web.start();
|
|
482
|
+
|
|
483
|
+
// Run the agent on port 3000
|
|
484
|
+
const agent = new AgentBase({ name: 'My Agent' });
|
|
485
|
+
agent.setPromptText('You are a helpful assistant.');
|
|
486
|
+
await agent.serve({ port: 3000 });
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
### Inside Another Hono App
|
|
490
|
+
|
|
491
|
+
`getApp()` returns a Hono app that a parent app can mount under a prefix with `route()`:
|
|
492
|
+
|
|
493
|
+
```typescript
|
|
494
|
+
import { Hono } from 'hono';
|
|
495
|
+
import { WebService } from '@signalwire/sdk';
|
|
496
|
+
|
|
497
|
+
const web = new WebService({ directories: { '/docs': './documentation' } });
|
|
498
|
+
const app = new Hono();
|
|
499
|
+
app.route('/static', web.getApp());
|
|
500
|
+
// GET /static/docs/index.html serves ./documentation/index.html
|
|
501
|
+
// GET /static/health is the health check, without credentials
|
|
502
|
+
```
|
|
503
|
+
|
|
504
|
+
The service resolves its mounts against the path below the prefix the request matched, at a path-segment boundary, so `/staticx/docs/...` isn't served. A parameterized prefix such as `/:tenant`, or one with a regular expression such as `/:tenant{[a-z]+}`, works too. The directory redirect keeps the prefix (`/static/docs/guide` redirects to `/static/docs/guide/`), and so do the links on the `/static` overview page.
|
|
505
|
+
|
|
506
|
+
Use `route()`, not `mount()`. `mount()` hands the service a request with the prefix removed from its URL, so files are served, but a directory redirect points at the path without the prefix.
|
|
507
|
+
|
|
508
|
+
### Docker Deployment
|
|
509
|
+
|
|
510
|
+
This Dockerfile runs the compiled `web-server.ts` from the standalone example. It assumes you compile it to `dist/web-server.js` before the build:
|
|
511
|
+
|
|
512
|
+
```dockerfile
|
|
513
|
+
FROM node:22-slim
|
|
514
|
+
|
|
515
|
+
WORKDIR /app
|
|
516
|
+
|
|
517
|
+
# Install dependencies (including @signalwire/sdk)
|
|
518
|
+
COPY package*.json ./
|
|
519
|
+
RUN npm ci --omit=dev
|
|
520
|
+
|
|
521
|
+
# Copy app + static files
|
|
522
|
+
COPY ./dist ./dist
|
|
523
|
+
COPY ./static /app/static
|
|
524
|
+
COPY ./web_service.json /app/web_service.json
|
|
525
|
+
|
|
526
|
+
# Expose port
|
|
527
|
+
EXPOSE 8002
|
|
528
|
+
|
|
529
|
+
# Run WebService
|
|
530
|
+
CMD ["node", "dist/web-server.js"]
|
|
531
|
+
```
|
|
532
|
+
|
|
533
|
+
The service finds `/app/web_service.json` because the working directory is `/app`.
|
|
534
|
+
|
|
535
|
+
### Nginx Reverse Proxy
|
|
536
|
+
|
|
537
|
+
For production, Nginx in front of the service can terminate TLS:
|
|
538
|
+
|
|
539
|
+
```nginx
|
|
540
|
+
server {
|
|
541
|
+
listen 80;
|
|
542
|
+
server_name static.example.com;
|
|
543
|
+
|
|
544
|
+
# Redirect to HTTPS
|
|
545
|
+
return 301 https://$server_name$request_uri;
|
|
546
|
+
}
|
|
547
|
+
|
|
548
|
+
server {
|
|
549
|
+
listen 443 ssl http2;
|
|
550
|
+
server_name static.example.com;
|
|
551
|
+
|
|
552
|
+
ssl_certificate /etc/ssl/certs/example.com.crt;
|
|
553
|
+
ssl_certificate_key /etc/ssl/private/example.com.key;
|
|
554
|
+
|
|
555
|
+
location / {
|
|
556
|
+
proxy_pass http://localhost:8002;
|
|
557
|
+
proxy_set_header Host $host;
|
|
558
|
+
proxy_set_header X-Real-IP $remote_addr;
|
|
559
|
+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
560
|
+
proxy_set_header X-Forwarded-Proto $scheme;
|
|
561
|
+
}
|
|
562
|
+
}
|
|
563
|
+
```
|
|
564
|
+
|
|
565
|
+
## Best Practices
|
|
566
|
+
|
|
567
|
+
These practices apply to a production deployment:
|
|
568
|
+
|
|
569
|
+
1. Serve HTTPS, from the service or from a proxy in front of it.
|
|
570
|
+
2. Use a long random password (the `basicAuth` option or `SWML_BASIC_AUTH_PASSWORD`), and send it only over HTTPS, since basic auth sends it with every request.
|
|
571
|
+
3. Use `allowedExtensions` to serve only the file types you intend.
|
|
572
|
+
4. Turn off directory browsing.
|
|
573
|
+
5. Mount only directories whose contents you control.
|
|
574
|
+
6. Tune `maxFileSize`, and use a CDN for large or busy static assets.
|
|
575
|
+
|
|
576
|
+
## API Reference
|
|
577
|
+
|
|
578
|
+
### WebService Class
|
|
579
|
+
|
|
580
|
+
The class has these public members:
|
|
581
|
+
|
|
582
|
+
<!-- snippet: no-compile class API-signature reference (declaration-only, no bodies), not runnable -->
|
|
583
|
+
```typescript
|
|
584
|
+
class WebService {
|
|
585
|
+
constructor(options?: WebServiceOptions);
|
|
586
|
+
|
|
587
|
+
readonly port: number;
|
|
588
|
+
readonly directories: Record<string, string>;
|
|
589
|
+
readonly enableDirectoryBrowsing: boolean;
|
|
590
|
+
readonly allowedExtensions: string[] | null;
|
|
591
|
+
readonly blockedExtensions: string[];
|
|
592
|
+
readonly maxFileSize: number;
|
|
593
|
+
readonly enableCors: boolean;
|
|
594
|
+
|
|
595
|
+
addDirectory(route: string, directory: string): void;
|
|
596
|
+
removeDirectory(route: string): void;
|
|
597
|
+
getApp(): Hono;
|
|
598
|
+
get sslConfig(): SslConfig;
|
|
599
|
+
start(host?: string, port?: number, sslCert?: string, sslKey?: string): Promise<void>;
|
|
600
|
+
stop(): void;
|
|
601
|
+
}
|
|
602
|
+
```
|
|
603
|
+
|
|
604
|
+
#### WebServiceOptions
|
|
605
|
+
|
|
606
|
+
| Option | Type | Default | Description |
|
|
607
|
+
|--------|------|---------|-------------|
|
|
608
|
+
| `port` | `number` | `8002` | Port to bind to. |
|
|
609
|
+
| `directories` | `Record<string, string>` | `{}` | URL prefix to local directory mappings. |
|
|
610
|
+
| `basicAuth` | `[string, string]` | config file, then environment | `[username, password]` for basic auth. Required from one of the three sources. |
|
|
611
|
+
| `configFile` | `string` | none | Path to a JSON config file. Without it, the constructor searches for `web_service.json`. |
|
|
612
|
+
| `enableDirectoryBrowsing` | `boolean` | `false` | Serve HTML listings for directories. |
|
|
613
|
+
| `allowedExtensions` | `string[]` | all | Allowlist of file extensions, such as `.html`. |
|
|
614
|
+
| `blockedExtensions` | `string[]` | (defaults) | Blocklist of extensions and names. Replaces the default list. |
|
|
615
|
+
| `maxFileSize` | `number` | `104857600` | Maximum file size in bytes (100 MB). |
|
|
616
|
+
| `enableCors` | `boolean` | `true` | Add CORS headers. |
|
|
617
|
+
| `ssl` | `SslOptions` | none | SSL settings: `enabled`, `certPath`, `keyPath`, `domain`, `hsts`, `hstsMaxAge`. |
|
|
618
|
+
|
|
619
|
+
#### Methods
|
|
620
|
+
|
|
621
|
+
These methods manage the service:
|
|
622
|
+
|
|
623
|
+
- `addDirectory(route, directory)`: Mount a directory at a URL prefix, before or after the service starts. Throws if the directory doesn't exist or isn't a directory.
|
|
624
|
+
- `removeDirectory(route)`: Unmount the prefix. Its route returns `404` from the next request.
|
|
625
|
+
- `getApp()`: Return the underlying Hono app, to mount or test.
|
|
626
|
+
- `start(host?, port?, sslCert?, sslKey?)`: Start the HTTP or HTTPS server. `host` defaults to `0.0.0.0`. Throws if no credentials are configured. With `SWAIG_CLI_MODE=true`, it does nothing.
|
|
627
|
+
- `stop()`: Stop the server.
|
|
628
|
+
|
|
629
|
+
## Integration with SignalWire Agents
|
|
630
|
+
|
|
631
|
+
An agent can point callers or the model at files the service serves. This agent's tool returns a documentation link, and the agent and the service run in the same process on different ports:
|
|
632
|
+
|
|
633
|
+
<!-- snippet: no-run starts a blocking HTTP file server via service.start() -->
|
|
634
|
+
```typescript
|
|
635
|
+
import { AgentBase, FunctionResult, WebService } from '@signalwire/sdk';
|
|
636
|
+
|
|
637
|
+
class DocumentationAgent extends AgentBase {
|
|
638
|
+
protected override defineTools(): void {
|
|
639
|
+
this.defineTool({
|
|
640
|
+
name: 'get_doc_link',
|
|
641
|
+
description: 'Get a link to a documentation page.',
|
|
642
|
+
parameters: {
|
|
643
|
+
doc_name: { type: 'string', description: 'Name of the documentation page' },
|
|
644
|
+
},
|
|
645
|
+
required: ['doc_name'],
|
|
646
|
+
handler: (args) =>
|
|
647
|
+
new FunctionResult(
|
|
648
|
+
`Documentation available at: https://example.com:8002/docs/${args.doc_name}.html`,
|
|
649
|
+
),
|
|
650
|
+
});
|
|
651
|
+
}
|
|
652
|
+
}
|
|
653
|
+
|
|
654
|
+
// Start WebService for documentation
|
|
655
|
+
const web = new WebService({ port: 8002, directories: { '/docs': './documentation' } });
|
|
656
|
+
await web.start();
|
|
657
|
+
|
|
658
|
+
// Start the agent
|
|
659
|
+
const agent = new DocumentationAgent({ name: 'Documentation Assistant' });
|
|
660
|
+
agent.promptAddSection('Documentation', {
|
|
661
|
+
body: 'User documentation is available at https://example.com:8002/docs/',
|
|
662
|
+
});
|
|
663
|
+
await agent.serve({ port: 3000 });
|
|
664
|
+
```
|
|
665
|
+
|
|
666
|
+
The tool's response is context for the model, not speech: the model decides how to pass the link on. For audio, a SWML `play` verb, or a `FunctionResult` action such as `playBackgroundFile()`, can use a URL the service serves. Every file the service serves needs its credentials, so a URL that someone or something else fetches has to carry them, for example `https://user:password@example.com:8002/audio/greeting.mp3`.
|