@signalwire/sdk 2.0.4 → 3.5.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 +785 -0
- package/LICENSE +21 -0
- package/README.md +163 -68
- package/dist/AGENTS.md +13 -0
- package/dist/AgentBase.d.ts +550 -163
- package/dist/AgentBase.js +1640 -514
- 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 +158 -45
- package/dist/DataMap.js +167 -52
- package/dist/DataMap.js.map +1 -1
- package/dist/FunctionResult.d.ts +277 -83
- package/dist/FunctionResult.js +444 -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 +163 -0
- package/dist/POM/PromptObjectModel.js +481 -0
- package/dist/POM/PromptObjectModel.js.map +1 -0
- 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 +28 -0
- package/dist/PomBuilder.js +81 -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 +29 -1
- package/dist/PromptManager.js +37 -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 +265 -66
- package/dist/SWMLService.js +652 -112
- 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 +55 -8
- package/dist/SecurityUtils.js +162 -49
- package/dist/SecurityUtils.js.map +1 -1
- 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 +110 -4
- package/dist/SwaigFunction.js +151 -19
- 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 +95 -34
- 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 -367
- 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 +916 -0
- package/dist/cli/tsdocs/topics.js.map +1 -0
- package/dist/index.d.ts +102 -39
- package/dist/index.js +107 -30
- 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 +79 -14
- package/dist/relay/RelayClient.js +268 -61
- 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 +81 -39
- 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 +63 -0
- package/dist/rest/callHandler.js +62 -0
- package/dist/rest/callHandler.js.map +1 -0
- package/dist/rest/index.d.ts +19 -76
- package/dist/rest/index.js +49 -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 -273
- package/dist/rest/namespaces/fabric.js +14 -363
- 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 +9 -57
- package/dist/rest/namespaces/phone-numbers.js +9 -63
- 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 +97 -20
- 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 +47 -7
- package/dist/skills/SkillRegistry.js +85 -13
- 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 +24 -8
- 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 +34 -25
- 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 +46 -1
- package/dist/skills/builtin/spider.js +317 -101
- 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 +57 -31
- 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 +301 -84
- 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 +32 -14
- 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 +65 -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 +3534 -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 +1160 -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 +1938 -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 +88 -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,548 @@
|
|
|
1
|
+
# Configuration
|
|
2
|
+
|
|
3
|
+
This page lists the settings the TypeScript SDK reads: constructor options, environment variables and JSON config files. It also covers authentication and logging, and which source wins when a setting comes from more than one place.
|
|
4
|
+
|
|
5
|
+
<!-- snippet-setup -->
|
|
6
|
+
```ts
|
|
7
|
+
export {}; // treat each example as a module (top-level await)
|
|
8
|
+
declare global {
|
|
9
|
+
const ConfigLoader: typeof import('@signalwire/sdk').ConfigLoader;
|
|
10
|
+
const AgentBase: typeof import('@signalwire/sdk').AgentBase; // used with `extends`
|
|
11
|
+
const getLogger: typeof import('@signalwire/sdk').getLogger;
|
|
12
|
+
const app: any; // Hono app
|
|
13
|
+
const requestHeaders: Record<string, string>;
|
|
14
|
+
}
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Table of Contents
|
|
18
|
+
|
|
19
|
+
- [Overview](#overview)
|
|
20
|
+
- [Constructor Options](#constructor-options)
|
|
21
|
+
- [Environment Variables](#environment-variables)
|
|
22
|
+
- [Config Files](#config-files)
|
|
23
|
+
- [Authentication](#authentication)
|
|
24
|
+
- [Logging](#logging)
|
|
25
|
+
- [Priority Order](#priority-order)
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Overview
|
|
30
|
+
|
|
31
|
+
The SDK has three layers of configuration:
|
|
32
|
+
|
|
33
|
+
1. **Constructor options**: passed to `new AgentBase({...})`, `new SWMLService({...})` or `new WebService({...})`.
|
|
34
|
+
2. **Environment variables**: read for server, security, logging, proxy, RELAY, REST and skill settings.
|
|
35
|
+
3. **Config files**: JSON files loaded with `ConfigLoader`, with `${VAR|default}` substitution from the environment.
|
|
36
|
+
|
|
37
|
+
A constructor option wins over the config file, and the config file wins over the environment, for the settings all three can supply. Some settings come from only one layer. [Priority Order](#priority-order) lists each case.
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## Constructor Options
|
|
42
|
+
|
|
43
|
+
Pass an `AgentOptions` object to the `AgentBase` constructor. The interface is defined in `src/types.ts`.
|
|
44
|
+
|
|
45
|
+
```typescript
|
|
46
|
+
import { AgentBase } from '@signalwire/sdk';
|
|
47
|
+
|
|
48
|
+
const agent = new AgentBase({
|
|
49
|
+
name: 'support-bot',
|
|
50
|
+
route: '/support',
|
|
51
|
+
port: 8080,
|
|
52
|
+
basicAuth: ['admin', 'a-long-random-password'],
|
|
53
|
+
autoAnswer: true,
|
|
54
|
+
recordCall: true,
|
|
55
|
+
tokenExpirySecs: 7200,
|
|
56
|
+
});
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
### AgentOptions Reference
|
|
60
|
+
|
|
61
|
+
| Property | Type | Default | Description |
|
|
62
|
+
|---|---|---|---|
|
|
63
|
+
| `name` | `string` | (required) | Name of the agent. Also the basic-auth username when the SDK generates credentials and `SWML_BASIC_AUTH_USER` is unset. |
|
|
64
|
+
| `route` | `string` | `"/"` | HTTP route the agent serves. Trailing slashes are stripped. Falls back to the config file's `service.route`. |
|
|
65
|
+
| `host` | `string` | `"0.0.0.0"` | Address the HTTP server binds to. Falls back to the config file's `service.host`. |
|
|
66
|
+
| `port` | `number` | `3000` | Port for the HTTP server. Falls back to the config file's `service.port`, then `PORT`, then `3000`. A value outside 1 to 65535 throws. |
|
|
67
|
+
| `basicAuth` | `[string, string]` | generated | Basic-auth credentials as `[username, password]`. [Authentication](#authentication) describes the fallbacks. |
|
|
68
|
+
| `usePom` | `boolean` | `true` | Build the prompt from sections (the Prompt Object Model) instead of raw text. |
|
|
69
|
+
| `tokenExpirySecs` | `number` | `3600` | Lifetime, in seconds, of the per-call tokens that secure tools and the post-prompt URL. |
|
|
70
|
+
| `swaigSecret` | `string` | `SIGNALWIRE_SWAIG_SECRET`, else random per process | Secret that signs the per-call tokens. Set the same value on every replica. |
|
|
71
|
+
| `autoAnswer` | `boolean` | `true` | Add an `answer` verb before the AI verb. |
|
|
72
|
+
| `recordCall` | `boolean` | `false` | Add a `record_call` verb after the answer. |
|
|
73
|
+
| `recordFormat` | `string` | `"mp4"` | `format` of the `record_call` verb. |
|
|
74
|
+
| `recordStereo` | `boolean` | `true` | `stereo` of the `record_call` verb. |
|
|
75
|
+
| `defaultWebhookUrl` | `string` | none | Stored on the agent, but SWML rendering doesn't read it. Use `setWebHookUrl()` to replace the SWAIG webhook URL. |
|
|
76
|
+
| `nativeFunctions` | `string[]` | `[]` | Platform function names for the SWAIG `native_functions` list. |
|
|
77
|
+
| `agentId` | `string` | 16 random hex characters | Identifier for this agent instance. |
|
|
78
|
+
| `suppressLogs` | `boolean` | `false` | When `true`, calls `suppressAllLogs(true)`, which silences the SDK's logger for the whole process, not only this agent. |
|
|
79
|
+
| `schemaPath` | `string` | bundled schema | Path to a SWML JSON Schema file that verbs are validated against, in place of the bundled schema. |
|
|
80
|
+
| `schemaValidation` | `boolean` | `true` | `false` turns off the validation of verbs, as `SWML_SKIP_SCHEMA_VALIDATION=true` does. |
|
|
81
|
+
| `enablePostPromptOverride` | `boolean` | `false` | Register `POST {route}/post_prompt_override`, which replaces the post-prompt text with the body's `post_prompt` value. |
|
|
82
|
+
| `checkForInputOverride` | `boolean` | `false` | Register `GET` and `POST {route}/check_for_input`, which log the request and echo its body. |
|
|
83
|
+
| `configFile` | `string` | none | Path to a JSON config file. [Config Files](#config-files) lists the keys the agent reads. |
|
|
84
|
+
| `signingKey` | `string` | `SIGNALWIRE_SIGNING_KEY` | Key for verifying webhook signatures on `POST` to the agent route, `/swaig`, `/post_prompt` and routing-callback paths. Requests without a valid signature get `403`. |
|
|
85
|
+
| `webhookTrustProxy` | `boolean` | `false` | Rebuild the signed URL from `X-Forwarded-Proto` and `X-Forwarded-Host`. Enable it only behind a proxy you control. `SWML_PROXY_URL_BASE` takes precedence over both. |
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## Environment Variables
|
|
90
|
+
|
|
91
|
+
The SDK reads these environment variables. All are optional.
|
|
92
|
+
|
|
93
|
+
### Server
|
|
94
|
+
|
|
95
|
+
The server port has one variable:
|
|
96
|
+
|
|
97
|
+
| Variable | Type | Default | Description |
|
|
98
|
+
|---|---|---|---|
|
|
99
|
+
| `PORT` | `number` | `3000` | HTTP port for `AgentBase`, `SWMLService` and `AgentServer` when no port option (or config-file port, for `AgentBase`) is given. `WebService` doesn't read it. |
|
|
100
|
+
|
|
101
|
+
### RELAY Connection
|
|
102
|
+
|
|
103
|
+
`RelayClient` reads these. `SIGNALWIRE_PROJECT_ID`, `SIGNALWIRE_API_TOKEN`, `SIGNALWIRE_JWT_TOKEN` and `SIGNALWIRE_SPACE` supply the credentials and space when the matching constructor option is omitted.
|
|
104
|
+
|
|
105
|
+
| Variable | Type | Default | Description |
|
|
106
|
+
|---|---|---|---|
|
|
107
|
+
| `SIGNALWIRE_RELAY_HOST` | `string` | none | RELAY WebSocket host. Precedence: `host` option, then `SIGNALWIRE_RELAY_HOST`, then `SIGNALWIRE_SPACE`, then `relay.signalwire.com`. |
|
|
108
|
+
| `SIGNALWIRE_RELAY_SCHEME` | `"ws"` or `"wss"` | `"wss"` | RELAY WebSocket scheme. The `scheme` option wins. Any other value falls back to `wss`. |
|
|
109
|
+
| `SIGNALWIRE_RELAY_CA_FILE` | `string` | none | Path to a CA bundle the RELAY WebSocket trusts. Unset, Node's default trust store applies. |
|
|
110
|
+
| `SIGNALWIRE_RELAY_PING_INTERVAL_MS` | `number` | `30000` | Milliseconds between client keepalive pings. For testing; leave unset in production. |
|
|
111
|
+
| `SIGNALWIRE_RELAY_PING_MAX_FAILURES` | `number` | `3` | Consecutive missed ping responses before the client reconnects. For testing; leave unset in production. |
|
|
112
|
+
| `SIGNALWIRE_RELAY_REQUEST_TIMEOUT_MS` | `number` | `30000` | Milliseconds a RELAY request waits for its response. For testing; leave unset in production. |
|
|
113
|
+
| `SIGNALWIRE_RELAY_RECONNECT_MIN_DELAY_S` | `number` | `1` | Seconds before the first reconnect attempt. For testing; leave unset in production. |
|
|
114
|
+
| `SIGNALWIRE_RELAY_RECONNECT_MAX_DELAY_S` | `number` | `30` | Upper limit, in seconds, of the reconnect backoff. For testing; leave unset in production. |
|
|
115
|
+
| `RELAY_MAX_CONNECTIONS` | `number` | `1` | Maximum `RelayClient` connections in one process. |
|
|
116
|
+
| `RELAY_MAX_ACTIVE_CALLS` | `number` | `1000` | Maximum concurrent calls per client, when the `maxActiveCalls` option isn't set. |
|
|
117
|
+
|
|
118
|
+
### REST Client
|
|
119
|
+
|
|
120
|
+
`RestClient` reads these when the matching constructor option is omitted:
|
|
121
|
+
|
|
122
|
+
| Variable | Type | Default | Description |
|
|
123
|
+
|---|---|---|---|
|
|
124
|
+
| `SIGNALWIRE_PROJECT_ID` | `string` | none | Project ID. |
|
|
125
|
+
| `SIGNALWIRE_API_TOKEN` | `string` | none | API token. |
|
|
126
|
+
| `SIGNALWIRE_REST_BASE_URL` | `string` | none | Full base URL, such as `http://127.0.0.1:8080`. Used when the `host` option is unset, and before `SIGNALWIRE_SPACE`. |
|
|
127
|
+
| `SIGNALWIRE_SPACE` | `string` | none | Space host, such as `example.signalwire.com`. |
|
|
128
|
+
| `SIGNALWIRE_REST_CA_FILE` | `string` | none | Path to a CA bundle the REST client trusts. |
|
|
129
|
+
|
|
130
|
+
### Authentication
|
|
131
|
+
|
|
132
|
+
These variables supply credentials and keys:
|
|
133
|
+
|
|
134
|
+
| Variable | Type | Default | Description |
|
|
135
|
+
|---|---|---|---|
|
|
136
|
+
| `SWML_BASIC_AUTH_USER` | `string` | none | Basic-auth username, used when no `basicAuth` option or config-file credentials apply. |
|
|
137
|
+
| `SWML_BASIC_AUTH_PASSWORD` | `string` | none | Basic-auth password. It's enough on its own: without `SWML_BASIC_AUTH_USER`, the username is `signalwire`. `SWML_BASIC_AUTH_USER` alone gives that username with a generated password. |
|
|
138
|
+
| `SIGNALWIRE_SIGNING_KEY` | `string` | none | Webhook signing key, used when the `signingKey` option isn't set. When neither is set, `AgentBase` logs a warning that signature validation is disabled. |
|
|
139
|
+
| `SIGNALWIRE_SWAIG_SECRET` | `string` | random per process | Secret that signs per-call SWAIG tokens, used when the `swaigSecret` option isn't set. Set the same value on every replica, so a token minted by one replica, or before a restart, validates on another. |
|
|
140
|
+
|
|
141
|
+
### Proxy Detection
|
|
142
|
+
|
|
143
|
+
These variables control the external URL the agent puts in its webhook URLs:
|
|
144
|
+
|
|
145
|
+
| Variable | Type | Default | Description |
|
|
146
|
+
|---|---|---|---|
|
|
147
|
+
| `SWML_PROXY_URL_BASE` | `string` | none | External base URL, such as `https://my-agent.example.com`. While it's set, request headers never change the base URL. |
|
|
148
|
+
| `SWML_TRUST_PROXY_HEADERS` | `"true"` | off | Read the base URL from `X-Forwarded-Host`, `Forwarded` or `X-Original-Host`, and key rate limiting by `X-Forwarded-For`. Enable it only behind a proxy you control, because clients can set these headers. |
|
|
149
|
+
| `SWML_PROXY_DEBUG` | `"true"` | off | Log proxy detection at debug level. |
|
|
150
|
+
| `SWML_ENFORCE_HTTPS` | `"true"` | off | Use `https` in the webhook URLs the agent builds from its own host and port. It doesn't reject plain-HTTP requests. |
|
|
151
|
+
|
|
152
|
+
### Logging
|
|
153
|
+
|
|
154
|
+
The logger reads these at startup:
|
|
155
|
+
|
|
156
|
+
| Variable | Type | Default | Description |
|
|
157
|
+
|---|---|---|---|
|
|
158
|
+
| `SIGNALWIRE_LOG_LEVEL` | `debug`, `info`, `warn`, `error` | `info` | Minimum level. An unknown value means `info`. |
|
|
159
|
+
| `SIGNALWIRE_LOG_MODE` | `off`, `stderr`, `auto` | `auto` | `off` silences the logger. `stderr` writes every line to stderr. `auto`, or unset, silences it in a CGI process and uses stderr on AWS Lambda. |
|
|
160
|
+
| `SIGNALWIRE_LOG_FORMAT` | `text`, `json` | `text` | Line format. |
|
|
161
|
+
| `SIGNALWIRE_LOG_COLOR` | `true`, `false` | stdout is a terminal | ANSI colors in text lines. Any value other than `true` turns them off. |
|
|
162
|
+
|
|
163
|
+
### Security
|
|
164
|
+
|
|
165
|
+
`AgentBase` reads these when it builds its HTTP app. [Priority Order](#priority-order) notes which other classes read them.
|
|
166
|
+
|
|
167
|
+
| Variable | Type | Default | Description |
|
|
168
|
+
|---|---|---|---|
|
|
169
|
+
| `SWML_CORS_ORIGINS` | `string` | `*` | Comma-separated allowed CORS origins. With a list, CORS responses allow credentials. |
|
|
170
|
+
| `SWML_ALLOWED_HOSTS` | `string` | none | Comma-separated host names. A request whose `Host` header (without the port) isn't listed gets `403`. |
|
|
171
|
+
| `SWML_MAX_REQUEST_SIZE` | `number` | `1048576` | Largest `Content-Length`, in bytes. A larger or non-numeric value gets `413`. A request without `Content-Length` isn't checked. |
|
|
172
|
+
| `SWML_RATE_LIMIT` | `number` | none | Requests per minute per client IP, answered with `429` past the limit. The IP is the connection's address, or the `X-Forwarded-For` or `X-Real-IP` address when `SWML_TRUST_PROXY_HEADERS=true`. |
|
|
173
|
+
| `SWML_CSRF_PROTECTION` | `"true"` | off | Refuse a `POST` whose `Origin` header isn't in `SWML_CORS_ORIGINS`, with `403`. Without `SWML_CORS_ORIGINS`, it checks nothing. |
|
|
174
|
+
| `SWML_USE_HSTS` | `"true"` or `"false"` | `true` | Read into `SecurityConfig.useHsts`. Only `SecurityConfig.getSecurityHeaders()` uses it; no server in the SDK calls that method. |
|
|
175
|
+
| `SWML_HSTS_MAX_AGE` | `number` | `31536000` | Read into `SecurityConfig.hstsMaxAge`, with the same limit as `SWML_USE_HSTS`. |
|
|
176
|
+
| `SWML_ALLOW_PRIVATE_URLS` | `1`, `true` or `yes` | unset | Lets the URL-fetching skills (spider, web_search) and the SDK's URL checks reach private, loopback, link-local and unspecified addresses. Leave it unset in production. |
|
|
177
|
+
| `SWML_URL_FETCH_USE_PROXY` | `1`, `true` or `yes` | unset | Lets the spider and web_search skills send a fetch through Node's environment proxy, when Node's proxy support is on (`NODE_USE_ENV_PROXY=1`), a proxy is set for the scheme (`HTTP_PROXY` or `HTTPS_PROXY`) and the host isn't in `NO_PROXY`. The private-address check can't apply through a proxy, so use a proxy that blocks private destinations. Other fetches still connect directly with the check. |
|
|
178
|
+
|
|
179
|
+
### SSL/TLS
|
|
180
|
+
|
|
181
|
+
`SslConfig` reads these. `AgentBase.serve()`, `AgentServer.run()`, `SWMLService.serve()` and `WebService.start()` use them to serve HTTPS.
|
|
182
|
+
|
|
183
|
+
| Variable | Type | Default | Description |
|
|
184
|
+
|---|---|---|---|
|
|
185
|
+
| `SWML_SSL_ENABLED` | `"true"`, `"1"` or `"yes"` | off | Serve HTTPS when the certificate and key paths are set. |
|
|
186
|
+
| `SWML_SSL_CERT_PATH` | `string` | none | Path to the PEM certificate file. |
|
|
187
|
+
| `SWML_SSL_KEY_PATH` | `string` | none | Path to the PEM private key file. |
|
|
188
|
+
| `SWML_SSL_DOMAIN` | `string` | none | Domain name stored with the SSL settings. |
|
|
189
|
+
|
|
190
|
+
### Skills
|
|
191
|
+
|
|
192
|
+
These variables control where skills come from:
|
|
193
|
+
|
|
194
|
+
| Variable | Type | Default | Description |
|
|
195
|
+
|---|---|---|---|
|
|
196
|
+
| `SIGNALWIRE_SKILL_PATHS` | `string` | none | Colon-separated directories added to the skill registry's search paths. |
|
|
197
|
+
| `SWML_SKILL_DISCOVERY_ENABLED` | `"true"` | off | Allow `SkillRegistry.discoverFromDirectory()` to import skill files from a directory. Without it, the method logs a warning and loads nothing. |
|
|
198
|
+
| `SWML_ALLOW_CUSTOM_HANDLER_CODE` | `"true"` | off | Allow the `custom_skills` skill to run handler code given as a string. Leave it unset unless you trust the skill configuration. |
|
|
199
|
+
|
|
200
|
+
### AI Chat
|
|
201
|
+
|
|
202
|
+
`AIChatClient` and `ChatGateway` read these. `AIChatClient` also reads `SIGNALWIRE_PROJECT_ID`, `SIGNALWIRE_API_TOKEN` and `SIGNALWIRE_SPACE` when the matching option is omitted. `SIGNALWIRE_SPACE` can be a space name (`example`) or a host name (`example.signalwire.com`).
|
|
203
|
+
|
|
204
|
+
| Variable | Type | Default | Description |
|
|
205
|
+
|---|---|---|---|
|
|
206
|
+
| `RAILS_DEV_MODE` | `string` | none | A full URL here is the chat service URL for `AIChatClient`, unless the `url` option is set. A boolean value (`true`, `1`, `on`, `false` and so on) is ignored. |
|
|
207
|
+
| `SIGNALWIRE_CHAT_GATEWAY_KEY` | `string` | generated | The publishable key a `ChatGateway` accepts, used when the `key` option isn't set. Without either, the gateway generates one per process. |
|
|
208
|
+
| `SIGNALWIRE_CHAT_GATEWAY_SECRET` | `string` | random per process | Secret that signs `ChatGateway` conversation handles, used when the `secret` option isn't set. Set the same value on every replica; without it, handles stop verifying across replicas and restarts. |
|
|
209
|
+
|
|
210
|
+
### Schema Validation
|
|
211
|
+
|
|
212
|
+
One variable turns off SWML verb validation:
|
|
213
|
+
|
|
214
|
+
| Variable | Type | Default | Description |
|
|
215
|
+
|---|---|---|---|
|
|
216
|
+
| `SWML_SKIP_SCHEMA_VALIDATION` | `"true"` | off | Skip the schema check `addVerb()` and `addVerbToSection()` run on each verb. |
|
|
217
|
+
|
|
218
|
+
---
|
|
219
|
+
|
|
220
|
+
## Config Files
|
|
221
|
+
|
|
222
|
+
The `ConfigLoader` class (`src/ConfigLoader.ts`) loads a JSON file, substitutes environment variables into it, and reads values by dot-separated path.
|
|
223
|
+
|
|
224
|
+
### Keys the SDK Reads
|
|
225
|
+
|
|
226
|
+
Three classes take a `configFile` option. Each reads different keys:
|
|
227
|
+
|
|
228
|
+
| Class | Keys |
|
|
229
|
+
|---|---|
|
|
230
|
+
| `AgentBase` | `service.route`, `service.host`, `service.port`, plus the `security` keys `SWMLService` reads |
|
|
231
|
+
| `SWMLService` | `security.ssl.enabled`, `security.ssl.certPath`, `security.ssl.keyPath`, `security.ssl.domain`, and basic auth from `security.auth.basic` or `security.basicAuth` (`user`, `password`) |
|
|
232
|
+
| `WebService` | `service.port`, `service.directories`, `service.enableDirectoryBrowsing`, `service.maxFileSize`, `service.allowedExtensions`, `service.blockedExtensions`, `service.enableCors` |
|
|
233
|
+
|
|
234
|
+
`AgentBase` and `SWMLService` read a config file only when you pass `configFile`. `WebService` without `configFile` searches for `web_service.json` in the locations [Search Paths](#search-paths) lists. A file passed as `configFile` that is missing or isn't valid JSON is skipped, and the service starts from its other settings.
|
|
235
|
+
|
|
236
|
+
This file sets an agent's route and port, and its basic-auth credentials:
|
|
237
|
+
|
|
238
|
+
```json
|
|
239
|
+
{
|
|
240
|
+
"service": {
|
|
241
|
+
"route": "/support",
|
|
242
|
+
"port": "${PORT|3000}"
|
|
243
|
+
},
|
|
244
|
+
"security": {
|
|
245
|
+
"auth": {
|
|
246
|
+
"basic": {
|
|
247
|
+
"user": "${SWML_BASIC_AUTH_USER|admin}",
|
|
248
|
+
"password": "${SUPPORT_AGENT_PASSWORD}"
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
}
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
A constructor option beats the file: `route` or `port` passed to the constructor wins over `service.route` or `service.port`, and `basicAuth` wins over the file's credentials. The file's password beats `SWML_BASIC_AUTH_PASSWORD`. An empty `user` or `password` in the file sets nothing.
|
|
256
|
+
|
|
257
|
+
### Loading a Config File
|
|
258
|
+
|
|
259
|
+
Pass a path to the constructor, or call `load()`:
|
|
260
|
+
|
|
261
|
+
<!-- snippet: no-run reads a config file that isn't present in the repo (illustrative ConfigLoader usage) -->
|
|
262
|
+
```typescript
|
|
263
|
+
import { ConfigLoader } from '@signalwire/sdk';
|
|
264
|
+
|
|
265
|
+
// Load by explicit path; throws if the file doesn't exist
|
|
266
|
+
const config = new ConfigLoader('./config/agent.json');
|
|
267
|
+
|
|
268
|
+
// Or load after construction
|
|
269
|
+
const config2 = new ConfigLoader();
|
|
270
|
+
config2.load('/etc/signalwire/agent.json');
|
|
271
|
+
|
|
272
|
+
// An array loads the first file that exists, and loads nothing if none does
|
|
273
|
+
const config3 = new ConfigLoader(['./agent.local.json', './agent.json']);
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
### Environment Variable Substitution
|
|
277
|
+
|
|
278
|
+
`load()` replaces every `${VAR}` and `${VAR|default}` in the file's text before it parses the JSON:
|
|
279
|
+
|
|
280
|
+
- `${VAR}` becomes the value of `VAR`, or an empty string if `VAR` is unset.
|
|
281
|
+
- `${VAR|default}` becomes the value of `VAR`, or `default` if `VAR` is unset.
|
|
282
|
+
|
|
283
|
+
The substitution happens in the raw text, so the result is still a string when the placeholder was inside quotes. In the earlier example, `service.port` is the string `"3000"`. A value containing a double quote or a backslash breaks the JSON. `getSection()` and `substituteVars()` substitute into values instead, and turn `"true"`, `"false"` and numeric strings into booleans and numbers.
|
|
284
|
+
|
|
285
|
+
### Search Paths
|
|
286
|
+
|
|
287
|
+
The static `ConfigLoader.search(filename)` method loads the first file it finds, checking these locations in order:
|
|
288
|
+
|
|
289
|
+
1. `{cwd}/{serviceName}_{filename}` and `{cwd}/.swml/{serviceName}_{filename}`, when you pass `serviceName` as the third argument
|
|
290
|
+
2. `{dir}/{filename}` for each directory in the optional second argument
|
|
291
|
+
3. `{cwd}/{filename}`
|
|
292
|
+
4. `{cwd}/config/{filename}`
|
|
293
|
+
5. `~/.signalwire/{filename}`
|
|
294
|
+
6. `{cwd}/.swml/{filename}`
|
|
295
|
+
7. `~/.swml/{filename}`
|
|
296
|
+
8. `/etc/swml/{filename}`
|
|
297
|
+
|
|
298
|
+
It returns `null` when no location has the file:
|
|
299
|
+
|
|
300
|
+
```typescript
|
|
301
|
+
// Searches the working directory, ./config/, ~/.signalwire/, ./.swml/, ~/.swml/ and /etc/swml/
|
|
302
|
+
const config = ConfigLoader.search('agent.json');
|
|
303
|
+
if (config) {
|
|
304
|
+
console.log('Loaded from:', config.getConfigFile());
|
|
305
|
+
}
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
`ConfigLoader.findConfigFile(serviceName?, additionalPaths?)` returns the path of the first existing file among `{serviceName}_config.json`, `.swml/{serviceName}_config.json`, the additional paths, `config.json`, `agent_config.json`, `.swml/config.json`, `~/.swml/config.json` and `/etc/swml/config.json`, without loading it.
|
|
309
|
+
|
|
310
|
+
### Dot-Notation Access
|
|
311
|
+
|
|
312
|
+
Use dot-separated paths to read and write nested values:
|
|
313
|
+
|
|
314
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `ConfigLoader` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
315
|
+
```typescript
|
|
316
|
+
const config = new ConfigLoader('./config/agent.json');
|
|
317
|
+
|
|
318
|
+
// Read nested values with optional defaults
|
|
319
|
+
const port = config.get<number>('server.port', 3000);
|
|
320
|
+
const agentName = config.get<string>('agent.name', 'default-agent');
|
|
321
|
+
|
|
322
|
+
// Check existence
|
|
323
|
+
if (config.has('auth.password')) {
|
|
324
|
+
// ...
|
|
325
|
+
}
|
|
326
|
+
|
|
327
|
+
// Write nested values (intermediate objects created automatically)
|
|
328
|
+
config.set('agent.temperature', 0.7);
|
|
329
|
+
|
|
330
|
+
// Get a shallow copy of the whole config
|
|
331
|
+
const all = config.getConfig();
|
|
332
|
+
|
|
333
|
+
// Get one top-level section, with values substituted and typed
|
|
334
|
+
const security = config.getSection('security');
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
A path segment of `__proto__`, `constructor` or `prototype` reads as missing, and `set()` ignores it.
|
|
338
|
+
|
|
339
|
+
### Loading from Objects
|
|
340
|
+
|
|
341
|
+
For tests, or configuration built in code, load a plain object:
|
|
342
|
+
|
|
343
|
+
```typescript
|
|
344
|
+
const config = new ConfigLoader();
|
|
345
|
+
config.loadFromObject({
|
|
346
|
+
server: { port: 8080 },
|
|
347
|
+
agent: { name: 'test-agent' },
|
|
348
|
+
});
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
`mergeWithEnv(prefix)` returns the loaded values plus every environment variable that starts with `prefix` (default `SWML_`). The prefix is stripped, the rest is lowercased and split on `_` into nested keys, and a value already in the config wins.
|
|
352
|
+
|
|
353
|
+
---
|
|
354
|
+
|
|
355
|
+
## Authentication
|
|
356
|
+
|
|
357
|
+
### Basic Auth in AgentBase
|
|
358
|
+
|
|
359
|
+
`AgentBase` requires HTTP Basic Authentication on every route except `/health` and `/ready`. It resolves the credentials in this order:
|
|
360
|
+
|
|
361
|
+
1. The `basicAuth` constructor option (source `provided`).
|
|
362
|
+
2. The config file's `security.auth.basic` or `security.basicAuth` password (source `config file`).
|
|
363
|
+
3. `SWML_BASIC_AUTH_PASSWORD`, with `SWML_BASIC_AUTH_USER` or `signalwire` as the username (source `environment`).
|
|
364
|
+
4. Generated: `SWML_BASIC_AUTH_USER` or the agent's name as the username, and 32 random hex characters as the password (source `generated`). The agent logs a warning, because a client outside the process can't know the password.
|
|
365
|
+
|
|
366
|
+
`getBasicAuthCredentials(true)` returns the credentials and their source:
|
|
367
|
+
|
|
368
|
+
```typescript
|
|
369
|
+
// 1. Explicit credentials
|
|
370
|
+
const agent = new AgentBase({
|
|
371
|
+
name: 'bot',
|
|
372
|
+
basicAuth: ['admin', 'a-long-random-password'],
|
|
373
|
+
});
|
|
374
|
+
|
|
375
|
+
// 2. From SWML_BASIC_AUTH_USER and SWML_BASIC_AUTH_PASSWORD, or generated
|
|
376
|
+
const agent2 = new AgentBase({ name: 'bot' });
|
|
377
|
+
|
|
378
|
+
// Inspect the credentials and their source
|
|
379
|
+
const [user, pass, source] = agent.getBasicAuthCredentials(true);
|
|
380
|
+
// source: 'provided' | 'config file' | 'environment' | 'generated'
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
The agent puts the credentials in the webhook URLs it renders, so SignalWire can authenticate its requests to `/swaig` and `/post_prompt`.
|
|
384
|
+
|
|
385
|
+
`SWMLService` checks the first three sources in the same order, and enforces the credentials only when one of them supplies them. Otherwise it generates credentials (the service name and a random password) but doesn't enforce them, so it serves every route without authentication. `WebService` checks its `basicAuth` option, then the config file's `security.auth.basic`, then the environment variables. Without a password from any of them it generates one that it never shows, so it refuses every request but `/health`, and `start()` throws.
|
|
386
|
+
|
|
387
|
+
### Custom Basic Auth Validation
|
|
388
|
+
|
|
389
|
+
`AgentBase` and `SWMLService` check a request's credentials through `validateBasicAuth(username, password)`, which compares them with the configured pair in constant time. Override it to add a check; an override replaces the comparison, so call `super.validateBasicAuth()` to keep it.
|
|
390
|
+
|
|
391
|
+
To add your own check, put the agent's app behind middleware that runs it, such as an `AuthHandler` [custom validator](#authhandler-multi-method-auth).
|
|
392
|
+
|
|
393
|
+
### AuthHandler (Multi-Method Auth)
|
|
394
|
+
|
|
395
|
+
The `AuthHandler` class (`src/AuthHandler.ts`) checks bearer tokens, API keys, basic auth and a custom validator, comparing secrets in constant time. It's standalone: the SDK's own servers don't use it.
|
|
396
|
+
|
|
397
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `app` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
398
|
+
```typescript
|
|
399
|
+
import { AuthHandler } from '@signalwire/sdk';
|
|
400
|
+
|
|
401
|
+
const auth = new AuthHandler({
|
|
402
|
+
bearerToken: 'a-long-random-token', // Authorization: Bearer <token>
|
|
403
|
+
apiKey: 'a-long-random-key', // X-Api-Key: <key>
|
|
404
|
+
apiKeyHeader: 'X-Api-Key', // optional; this is the default
|
|
405
|
+
basicAuth: ['admin', 'a-long-random-password'], // Authorization: Basic base64(user:pass)
|
|
406
|
+
customValidator: async (req) => { // receives { headers, method, url }
|
|
407
|
+
return req.headers['x-custom'] === 'valid';
|
|
408
|
+
},
|
|
409
|
+
});
|
|
410
|
+
|
|
411
|
+
// Use as Hono middleware; a failed check gets 401 {"error":"Unauthorized"}
|
|
412
|
+
app.use('/protected/*', auth.middleware());
|
|
413
|
+
|
|
414
|
+
// Or validate a header map yourself
|
|
415
|
+
const isValid = await auth.validate(requestHeaders);
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
`validate()` tries the bearer token, the API key, basic auth and the custom validator, in that order, and succeeds on the first match. Header names are matched in lower case, as Hono passes them. The custom validator gets `method` and `url` as empty strings.
|
|
419
|
+
|
|
420
|
+
When no method is configured, `validate()` allows every request and logs a warning. Pass `allowUnauthenticated: false` to refuse them instead. `middleware(true)` and `expressMiddleware(true)` run the check but let failed requests through.
|
|
421
|
+
|
|
422
|
+
These methods report the configuration:
|
|
423
|
+
|
|
424
|
+
| Method | Returns | Description |
|
|
425
|
+
|---|---|---|
|
|
426
|
+
| `hasBearerAuth()` | `boolean` | Whether a bearer token is configured |
|
|
427
|
+
| `hasApiKeyAuth()` | `boolean` | Whether an API key is configured |
|
|
428
|
+
| `hasBasicAuth()` | `boolean` | Whether basic-auth credentials are configured |
|
|
429
|
+
| `getAuthInfo()` | object | The enabled methods, with the basic-auth username and the API key header name |
|
|
430
|
+
|
|
431
|
+
---
|
|
432
|
+
|
|
433
|
+
## Logging
|
|
434
|
+
|
|
435
|
+
The `Logger` class (`src/Logger.ts`) writes structured log lines, configured by environment variables or in code.
|
|
436
|
+
|
|
437
|
+
### Log Levels
|
|
438
|
+
|
|
439
|
+
The logger has four levels, from lowest to highest:
|
|
440
|
+
|
|
441
|
+
| Level | Use |
|
|
442
|
+
|---|---|
|
|
443
|
+
| `debug` | Diagnostic detail |
|
|
444
|
+
| `info` | Normal operation (the default minimum) |
|
|
445
|
+
| `warn` | Something that may need attention |
|
|
446
|
+
| `error` | A failure |
|
|
447
|
+
|
|
448
|
+
### Basic Usage
|
|
449
|
+
|
|
450
|
+
`getLogger(name)` returns a logger for that name:
|
|
451
|
+
|
|
452
|
+
```typescript
|
|
453
|
+
import { getLogger } from '@signalwire/sdk';
|
|
454
|
+
|
|
455
|
+
const log = getLogger('MyModule');
|
|
456
|
+
|
|
457
|
+
log.debug('Processing request', { requestId: '123' });
|
|
458
|
+
log.info('Agent started');
|
|
459
|
+
log.warn('Token expiring soon', { expiresIn: 300 });
|
|
460
|
+
log.error('Connection failed', { host: 'example.com' });
|
|
461
|
+
```
|
|
462
|
+
|
|
463
|
+
### Text Format (Default)
|
|
464
|
+
|
|
465
|
+
With `SIGNALWIRE_LOG_FORMAT` unset or `text`, the example prints these lines. The `debug` line is under the default level, so it doesn't print:
|
|
466
|
+
|
|
467
|
+
```text
|
|
468
|
+
2026-09-28T23:18:30.530Z [INFO] [MyModule] Agent started
|
|
469
|
+
2026-09-28T23:18:30.532Z [WARN] [MyModule] Token expiring soon expiresIn=300
|
|
470
|
+
2026-09-28T23:18:30.533Z [ERROR] [MyModule] Connection failed host=example.com
|
|
471
|
+
```
|
|
472
|
+
|
|
473
|
+
Extra data follows as `key=value` pairs. With color on, the level tag is cyan for `debug`, green for `info`, yellow for `warn` and red for `error`.
|
|
474
|
+
|
|
475
|
+
### JSON Format
|
|
476
|
+
|
|
477
|
+
Set `SIGNALWIRE_LOG_FORMAT=json` for one JSON object per line, with the extra data as top-level keys:
|
|
478
|
+
|
|
479
|
+
```json
|
|
480
|
+
{"timestamp":"2026-09-28T23:18:31.550Z","level":"warn","logger":"MyModule","message":"Token expiring soon","expiresIn":300}
|
|
481
|
+
```
|
|
482
|
+
|
|
483
|
+
### Context Binding with `bind()`
|
|
484
|
+
|
|
485
|
+
`bind()` returns a logger that adds the given fields to every line:
|
|
486
|
+
|
|
487
|
+
<!-- snippet: no-run illustrative fragment: references the assumed `getLogger` from the page prelude (declared type-only in the shared snippet-setup), not a standalone program -->
|
|
488
|
+
```typescript
|
|
489
|
+
const log = getLogger('Handler');
|
|
490
|
+
|
|
491
|
+
const requestLog = log.bind({ requestId: '456', callId: 'abc-123' });
|
|
492
|
+
requestLog.info('Handling request');
|
|
493
|
+
// 2026-09-28T22:57:03.529Z [INFO] [Handler] Handling request requestId=456 callId=abc-123
|
|
494
|
+
```
|
|
495
|
+
|
|
496
|
+
### Programmatic Configuration
|
|
497
|
+
|
|
498
|
+
These functions change the logging configuration for the whole process:
|
|
499
|
+
|
|
500
|
+
```typescript
|
|
501
|
+
import {
|
|
502
|
+
setGlobalLogLevel,
|
|
503
|
+
suppressAllLogs,
|
|
504
|
+
setGlobalLogFormat,
|
|
505
|
+
setGlobalLogColor,
|
|
506
|
+
resetLoggingConfiguration,
|
|
507
|
+
} from '@signalwire/sdk';
|
|
508
|
+
|
|
509
|
+
// Change the level at runtime
|
|
510
|
+
setGlobalLogLevel('debug');
|
|
511
|
+
|
|
512
|
+
// Silence all output; suppressAllLogs(false) turns it back on
|
|
513
|
+
suppressAllLogs(true);
|
|
514
|
+
|
|
515
|
+
// Switch to JSON lines
|
|
516
|
+
setGlobalLogFormat('json');
|
|
517
|
+
|
|
518
|
+
// Force color on or off
|
|
519
|
+
setGlobalLogColor(false);
|
|
520
|
+
|
|
521
|
+
// Re-read the environment variables and drop every change made in code
|
|
522
|
+
resetLoggingConfiguration();
|
|
523
|
+
```
|
|
524
|
+
|
|
525
|
+
`new AgentServer()` calls `setGlobalLogLevel()` with its `logLevel` option, `info` by default, so it replaces the level `SIGNALWIRE_LOG_LEVEL` set. Pass `logLevel` to choose it.
|
|
526
|
+
|
|
527
|
+
---
|
|
528
|
+
|
|
529
|
+
## Priority Order
|
|
530
|
+
|
|
531
|
+
No single rule covers every setting. This table gives the order for each one, highest first:
|
|
532
|
+
|
|
533
|
+
| Setting | Resolution |
|
|
534
|
+
|---|---|
|
|
535
|
+
| Port (`AgentBase`) | `port` option, config file `service.port`, `PORT`, `3000` |
|
|
536
|
+
| Port (`SWMLService`, `AgentServer`) | `port` option, `PORT`, `3000` |
|
|
537
|
+
| Port (`WebService`) | `port` option, config file `service.port`, `8002` |
|
|
538
|
+
| Route and host (`AgentBase`) | constructor option, config file `service.route` or `service.host`, `/` or `0.0.0.0` |
|
|
539
|
+
| Basic auth (`AgentBase`, `SWMLService`) | `basicAuth` option, config file password, `SWML_BASIC_AUTH_PASSWORD`, generated |
|
|
540
|
+
| Basic auth (`WebService`) | `basicAuth` option, config file `security.auth.basic`, `SWML_BASIC_AUTH_USER` / `SWML_BASIC_AUTH_PASSWORD`; required (`start()` throws without them) |
|
|
541
|
+
| Log level | `setGlobalLogLevel()` (including through `new AgentServer()`), `SIGNALWIRE_LOG_LEVEL`, `info` |
|
|
542
|
+
| CORS origins | `SWML_CORS_ORIGINS`, `*`. `AgentBase`, `SWMLService`, `AgentServer` and `WebService` read it. |
|
|
543
|
+
| Allowed hosts, rate limit, request size, CSRF | Environment variables only, applied by `AgentBase` |
|
|
544
|
+
| Proxy URL | The most recent of `SWML_PROXY_URL_BASE` (read at construction) and `manualSetProxyUrl()`. Header detection, when `SWML_TRUST_PROXY_HEADERS=true`, replaces the base URL on each request unless `SWML_PROXY_URL_BASE` is set. Without any of them, the serverless platform's URL, or `http://{host}:{port}`. |
|
|
545
|
+
| SSL (`SWMLService.serve()`) | `serve()` options, config file `security.ssl`, `SWML_SSL_ENABLED` / `SWML_SSL_CERT_PATH` / `SWML_SSL_KEY_PATH` |
|
|
546
|
+
| SSL (`WebService.start()`) | `start()` certificate and key arguments, `ssl` option, `SWML_SSL_ENABLED` / `SWML_SSL_CERT_PATH` / `SWML_SSL_KEY_PATH` |
|
|
547
|
+
| SWAIG token secret | `swaigSecret` option, `SIGNALWIRE_SWAIG_SECRET`, random per process |
|
|
548
|
+
| Webhook signing key | `signingKey` option, `SIGNALWIRE_SIGNING_KEY`, none |
|