@signalwire/sdk 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.github/workflows/publish.yml +27 -0
- package/.github/workflows/test.yml +17 -0
- package/CLAUDE.md +112 -0
- package/README.md +254 -0
- package/docs/MIGRATION-2.0.md +81 -0
- package/docs/agent-guide.md +869 -0
- package/docs/agent_guide.md +1026 -0
- package/docs/api-reference.md +2420 -0
- package/docs/api_reference.md +1301 -0
- package/docs/architecture.md +843 -0
- package/docs/cli-guide.md +579 -0
- package/docs/cli_guide.md +448 -0
- package/docs/cloud_functions_guide.md +474 -0
- package/docs/configuration.md +422 -0
- package/docs/contexts-guide.md +787 -0
- package/docs/contexts_guide.md +511 -0
- package/docs/datamap-guide.md +1141 -0
- package/docs/datamap_guide.md +595 -0
- package/docs/llm_parameters.md +239 -0
- package/docs/mcp_gateway_reference.md +648 -0
- package/docs/mcp_integration.md +108 -0
- package/docs/prefabs-guide.md +800 -0
- package/docs/sdk_features.md +477 -0
- package/docs/security.md +436 -0
- package/docs/serverless-guide.md +513 -0
- package/docs/skills-guide.md +857 -0
- package/docs/skills-system.md +301 -0
- package/docs/skills_parameter_schema.md +392 -0
- package/docs/skills_system.md +467 -0
- package/docs/swaig-reference.md +1627 -0
- package/docs/swaig_reference.md +910 -0
- package/docs/swml_service_guide.md +600 -0
- package/docs/third_party_skills.md +533 -0
- package/docs/web_service.md +677 -0
- package/examples/README.md +131 -0
- package/examples/advanced-datamap.ts +100 -0
- package/examples/advanced-dynamic-config.ts +70 -0
- package/examples/auto-vivified.ts +94 -0
- package/examples/call-flow.ts +63 -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 +55 -0
- package/examples/datasphere-multi-instance.ts +63 -0
- package/examples/datasphere-serverless-env.ts +68 -0
- package/examples/datasphere-webhook-env.ts +66 -0
- package/examples/datasphere.ts +37 -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 +71 -0
- package/examples/gather-per-question-functions-demo.ts +140 -0
- package/examples/joke-agent.ts +34 -0
- package/examples/kubernetes-agent.ts +45 -0
- package/examples/llm-params.ts +69 -0
- package/examples/mcp-agent.ts +84 -0
- package/examples/mcp-gateway.ts +35 -0
- package/examples/multi-agent.ts +73 -0
- package/examples/multi-endpoint.ts +79 -0
- package/examples/pom-prompt.ts +71 -0
- package/examples/prefab-concierge.ts +47 -0
- package/examples/prefab-faq.ts +54 -0
- package/examples/prefab-info-gatherer.ts +33 -0
- package/examples/prefab-receptionist.ts +36 -0
- package/examples/prefab-survey.ts +68 -0
- package/examples/record-call.ts +67 -0
- package/examples/relay-demo.ts +33 -0
- package/examples/room-and-sip.ts +94 -0
- package/examples/serverless-lambda.ts +35 -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 +38 -0
- package/examples/step-function-inheritance-demo.ts +124 -0
- package/examples/swaig-features.ts +187 -0
- package/examples/swml-service-routing.ts +66 -0
- package/examples/swml-service.ts +38 -0
- package/examples/tap.ts +68 -0
- package/examples/verb-methods.ts +45 -0
- package/examples/web-search-multi-instance.ts +72 -0
- package/examples/web-search.ts +38 -0
- package/examples/wikipedia.ts +36 -0
- package/livewire/README.md +140 -0
- package/livewire/docs/migration-guide.md +228 -0
- package/livewire/examples/livewire-basic-agent.ts +74 -0
- package/livewire/examples/livewire-handoff.ts +197 -0
- package/livewire/examples/livewire-multi-tool.ts +117 -0
- package/package.json +38 -0
- package/relay/README.md +70 -0
- package/relay/RELAY_IMPLEMENTATION_GUIDE.md +1257 -0
- package/relay/docs/call-methods.md +474 -0
- package/relay/docs/client-reference.md +142 -0
- package/relay/docs/events.md +134 -0
- package/relay/docs/getting-started.md +134 -0
- package/relay/docs/guide.md +306 -0
- package/relay/docs/messaging.md +182 -0
- package/relay/examples/relay-inbound.ts +66 -0
- package/relay/examples/relay-messaging.ts +71 -0
- package/relay/examples/relay-outbound.ts +76 -0
- package/rest/README.md +95 -0
- package/rest/docs/calling.md +273 -0
- package/rest/docs/client-reference.md +107 -0
- package/rest/docs/compat.md +204 -0
- package/rest/docs/fabric.md +183 -0
- package/rest/docs/getting-started.md +110 -0
- package/rest/docs/guide.md +351 -0
- package/rest/docs/namespaces.md +285 -0
- package/rest/examples/rest-10dlc-registration.ts +161 -0
- package/rest/examples/rest-calling-ivr-and-ai.ts +102 -0
- package/rest/examples/rest-calling-play-and-record.ts +91 -0
- package/rest/examples/rest-client.ts +65 -0
- package/rest/examples/rest-compat-laml.ts +210 -0
- package/rest/examples/rest-datasphere-search.ts +82 -0
- package/rest/examples/rest-fabric-conferences-and-routing.ts +144 -0
- package/rest/examples/rest-fabric-subscribers-and-sip.ts +108 -0
- package/rest/examples/rest-fabric-swml-and-callflows.ts +99 -0
- package/rest/examples/rest-manage-resources.ts +65 -0
- package/rest/examples/rest-phone-number-management.ts +197 -0
- package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
- package/rest/examples/rest-video-rooms.ts +186 -0
- package/src/AgentBase.ts +2489 -0
- package/src/AgentServer.ts +415 -0
- package/src/AuthHandler.ts +256 -0
- package/src/ConfigLoader.ts +447 -0
- package/src/ContextBuilder.ts +1150 -0
- package/src/DataMap.ts +449 -0
- package/src/FunctionResult.ts +866 -0
- package/src/Logger.ts +337 -0
- package/src/PomBuilder.ts +439 -0
- package/src/PromptManager.ts +133 -0
- package/src/SWMLHandler.ts +298 -0
- package/src/SWMLService.ts +717 -0
- package/src/SchemaUtils.ts +361 -0
- package/src/SecurityUtils.ts +153 -0
- package/src/ServerlessAdapter.ts +221 -0
- package/src/SessionManager.ts +311 -0
- package/src/SslConfig.ts +118 -0
- package/src/SwaigFunction.ts +276 -0
- package/src/SwmlBuilder.ts +258 -0
- package/src/SwmlVerbMethods.generated.ts +234 -0
- package/src/TypeInference.ts +181 -0
- package/src/WebService.ts +619 -0
- package/src/cli/agent-loader.ts +166 -0
- package/src/cli/mock-data.ts +111 -0
- package/src/cli/swaig-test.ts +452 -0
- package/src/generateVerbTypes.ts +322 -0
- package/src/index.ts +167 -0
- package/src/livewire/index.ts +950 -0
- package/src/prefabs/ConciergeAgent.ts +287 -0
- package/src/prefabs/FAQBotAgent.ts +384 -0
- package/src/prefabs/InfoGathererAgent.ts +339 -0
- package/src/prefabs/ReceptionistAgent.ts +366 -0
- package/src/prefabs/SurveyAgent.ts +646 -0
- package/src/prefabs/index.ts +27 -0
- package/src/relay/Action.ts +314 -0
- package/src/relay/Call.ts +854 -0
- package/src/relay/Deferred.ts +71 -0
- package/src/relay/Message.ts +148 -0
- package/src/relay/RelayClient.ts +1036 -0
- package/src/relay/RelayError.ts +14 -0
- package/src/relay/RelayEvent.ts +892 -0
- package/src/relay/constants.ts +132 -0
- package/src/relay/index.ts +123 -0
- package/src/relay/types.ts +149 -0
- package/src/rest/HttpClient.ts +103 -0
- package/src/rest/RestError.ts +31 -0
- package/src/rest/base/BaseResource.ts +19 -0
- package/src/rest/base/CrudResource.ts +51 -0
- package/src/rest/base/CrudWithAddresses.ts +26 -0
- package/src/rest/index.ts +200 -0
- package/src/rest/namespaces/addresses.ts +32 -0
- package/src/rest/namespaces/calling.ts +187 -0
- package/src/rest/namespaces/chat.ts +20 -0
- package/src/rest/namespaces/compat.ts +352 -0
- package/src/rest/namespaces/datasphere.ts +45 -0
- package/src/rest/namespaces/fabric.ts +222 -0
- package/src/rest/namespaces/imported-numbers.ts +20 -0
- package/src/rest/namespaces/logs.ts +84 -0
- package/src/rest/namespaces/lookup.ts +21 -0
- package/src/rest/namespaces/mfa.ts +30 -0
- package/src/rest/namespaces/number-groups.ts +38 -0
- package/src/rest/namespaces/phone-numbers.ts +44 -0
- package/src/rest/namespaces/project.ts +36 -0
- package/src/rest/namespaces/pubsub.ts +20 -0
- package/src/rest/namespaces/queues.ts +33 -0
- package/src/rest/namespaces/recordings.ts +28 -0
- package/src/rest/namespaces/registry.ts +101 -0
- package/src/rest/namespaces/short-codes.ts +28 -0
- package/src/rest/namespaces/sip-profile.ts +25 -0
- package/src/rest/namespaces/verified-callers.ts +27 -0
- package/src/rest/namespaces/video.ts +165 -0
- package/src/rest/pagination.ts +84 -0
- package/src/rest/types.ts +61 -0
- package/src/schema.json +12250 -0
- package/src/skills/SkillBase.ts +547 -0
- package/src/skills/SkillManager.ts +415 -0
- package/src/skills/SkillRegistry.ts +367 -0
- package/src/skills/builtin/api_ninjas_trivia.ts +280 -0
- package/src/skills/builtin/ask_claude.ts +241 -0
- package/src/skills/builtin/claude_skills.ts +978 -0
- package/src/skills/builtin/custom_skills.ts +312 -0
- package/src/skills/builtin/datasphere.ts +438 -0
- package/src/skills/builtin/datasphere_serverless.ts +339 -0
- package/src/skills/builtin/datetime.ts +130 -0
- package/src/skills/builtin/google_maps.ts +651 -0
- package/src/skills/builtin/index.ts +88 -0
- package/src/skills/builtin/info_gatherer.ts +405 -0
- package/src/skills/builtin/joke.ts +191 -0
- package/src/skills/builtin/math.ts +142 -0
- package/src/skills/builtin/mcp_gateway.ts +677 -0
- package/src/skills/builtin/native_vector_search.ts +901 -0
- package/src/skills/builtin/play_background_file.ts +358 -0
- package/src/skills/builtin/spider.ts +869 -0
- package/src/skills/builtin/swml_transfer.ts +635 -0
- package/src/skills/builtin/weather_api.ts +248 -0
- package/src/skills/builtin/web_search.ts +1074 -0
- package/src/skills/builtin/wikipedia_search.ts +299 -0
- package/src/skills/index.ts +12 -0
- package/src/types.ts +132 -0
- package/tests/AgentBase.test.ts +1093 -0
- package/tests/AgentServer.test.ts +126 -0
- package/tests/AuthHandler.test.ts +133 -0
- package/tests/ConfigLoader.test.ts +151 -0
- package/tests/ContextBuilder.test.ts +108 -0
- package/tests/DataMap.test.ts +367 -0
- package/tests/EphemeralSkillCopy.test.ts +107 -0
- package/tests/FunctionResult.test.ts +298 -0
- package/tests/GracefulShutdown.test.ts +46 -0
- package/tests/Logger.test.ts +420 -0
- package/tests/PomBuilder.test.ts +228 -0
- package/tests/ProxyDetection.test.ts +228 -0
- package/tests/SWMLService.test.ts +320 -0
- package/tests/SWMLVerbHandler.test.ts +523 -0
- package/tests/SchemaUtils.test.ts +106 -0
- package/tests/SchemaUtils.verb.test.ts +206 -0
- package/tests/SecurityUtils.test.ts +192 -0
- package/tests/ServerlessAdapter.test.ts +222 -0
- package/tests/SessionManager.test.ts +257 -0
- package/tests/SkillBaseFeatures.test.ts +130 -0
- package/tests/SkillMultiInstance.test.ts +102 -0
- package/tests/SkillParameterSchemas.test.ts +134 -0
- package/tests/SkillRegistrySchema.test.ts +84 -0
- package/tests/SslConfig.test.ts +97 -0
- package/tests/SwmlBuilder.test.ts +400 -0
- package/tests/TypeInference.test.ts +165 -0
- package/tests/VerbHandlerRegistry.test.ts +128 -0
- package/tests/cli/mock-data.test.ts +113 -0
- package/tests/cli/swaig-test.test.ts +108 -0
- package/tests/examples.test.ts +194 -0
- package/tests/fixtures/scrape-parity/README.md +53 -0
- package/tests/fixtures/scrape-parity/expected/01_simple_article.json +5 -0
- package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +5 -0
- package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +5 -0
- package/tests/fixtures/scrape-parity/expected/04_bare_body.json +5 -0
- package/tests/fixtures/scrape-parity/expected/05_malformed.json +5 -0
- package/tests/fixtures/scrape-parity/expected/06_multi_class.json +5 -0
- package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +5 -0
- package/tests/fixtures/scrape-parity/expected/08_inline_script.json +5 -0
- package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +5 -0
- package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +5 -0
- package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +5 -0
- package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +5 -0
- package/tests/fixtures/scrape-parity/html/01_simple_article.html +18 -0
- package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +18 -0
- package/tests/fixtures/scrape-parity/html/03_nested_containers.html +13 -0
- package/tests/fixtures/scrape-parity/html/04_bare_body.html +9 -0
- package/tests/fixtures/scrape-parity/html/05_malformed.html +11 -0
- package/tests/fixtures/scrape-parity/html/06_multi_class.html +18 -0
- package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +12 -0
- package/tests/fixtures/scrape-parity/html/08_inline_script.html +17 -0
- package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +21 -0
- package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +10 -0
- package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +13 -0
- package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +24 -0
- package/tests/fixtures/scrape-parity/python_extract.py +109 -0
- package/tests/livewire/livewire.test.ts +780 -0
- package/tests/mcp.test.ts +221 -0
- package/tests/prefabs/prefabs.test.ts +1093 -0
- package/tests/relay/Action.test.ts +392 -0
- package/tests/relay/Call.test.ts +535 -0
- package/tests/relay/Deferred.test.ts +71 -0
- package/tests/relay/Message.test.ts +164 -0
- package/tests/relay/RelayClient.test.ts +779 -0
- package/tests/relay/RelayEvent.test.ts +463 -0
- package/tests/relay/helpers.ts +79 -0
- package/tests/rest/HttpClient.test.ts +274 -0
- package/tests/rest/RestError.test.ts +53 -0
- package/tests/rest/calling.test.ts +156 -0
- package/tests/rest/client.test.ts +197 -0
- package/tests/rest/compat.test.ts +335 -0
- package/tests/rest/datasphere.test.ts +71 -0
- package/tests/rest/fabric.test.ts +186 -0
- package/tests/rest/helpers.ts +95 -0
- package/tests/rest/logs.test.ts +68 -0
- package/tests/rest/pagination.test.ts +133 -0
- package/tests/rest/registry.test.ts +94 -0
- package/tests/rest/relay-rest.test.ts +290 -0
- package/tests/rest/video.test.ts +173 -0
- package/tests/setup.ts +6 -0
- package/tests/skills/SkillBase.test.ts +108 -0
- package/tests/skills/SkillManager.test.ts +268 -0
- package/tests/skills/SkillRegistry.test.ts +176 -0
- package/tests/skills/builtin.test.ts +1472 -0
- package/tests/skills/claude-skills.test.ts +54 -0
- package/tests/skills/custom-skills.test.ts +53 -0
- package/tests/skills/datasphere-serverless.test.ts +70 -0
- package/tests/skills/datasphere.test.ts +107 -0
- package/tests/skills/datetime.test.ts +101 -0
- package/tests/skills/google-maps.test.ts +78 -0
- package/tests/skills/info-gatherer.test.ts +411 -0
- package/tests/skills/joke.test.ts +81 -0
- package/tests/skills/math.test.ts +68 -0
- package/tests/skills/mcp-gateway.test.ts +101 -0
- package/tests/skills/play-background.test.ts +54 -0
- package/tests/skills/spider.test.ts +108 -0
- package/tests/skills/swml-transfer.test.ts +178 -0
- package/tests/skills/trivia.test.ts +54 -0
- package/tests/skills/vector-search.test.ts +135 -0
- package/tests/skills/weather-api.test.ts +77 -0
- package/tests/skills/web-search-parity.test.ts +59 -0
- package/tests/skills/web-search.test.ts +103 -0
- package/tests/skills/wikipedia.test.ts +63 -0
- package/tsconfig.json +18 -0
- package/vitest.config.ts +9 -0
package/src/Logger.ts
ADDED
|
@@ -0,0 +1,337 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Logger - Structured logger with env-var-based configuration.
|
|
3
|
+
*
|
|
4
|
+
* SIGNALWIRE_LOG_LEVEL: debug | info | warn | error (default: info)
|
|
5
|
+
* SIGNALWIRE_LOG_MODE: off | stderr | auto (default: auto)
|
|
6
|
+
* SIGNALWIRE_LOG_FORMAT: text | json (default: text)
|
|
7
|
+
* SIGNALWIRE_LOG_COLOR: true | false (default: true when TTY and no CLI raw flags)
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
const LEVELS = { debug: 0, info: 1, warn: 2, error: 3 } as const;
|
|
11
|
+
/** Log severity level. */
|
|
12
|
+
type LogLevel = keyof typeof LEVELS;
|
|
13
|
+
/** Output format for log entries. */
|
|
14
|
+
type LogFormat = 'text' | 'json';
|
|
15
|
+
/** Output stream routing. */
|
|
16
|
+
type LogStream = 'stdout' | 'stderr';
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* Detect the execution environment, matching Python SDK's detection logic.
|
|
20
|
+
* @returns A tuple of [environment_name, derived_log_mode].
|
|
21
|
+
*/
|
|
22
|
+
export function getExecutionMode(): [string, 'off' | 'stderr' | 'default'] {
|
|
23
|
+
if (process.env['GATEWAY_INTERFACE']) return ['cgi', 'off'];
|
|
24
|
+
if (process.env['AWS_LAMBDA_FUNCTION_NAME'] || process.env['LAMBDA_TASK_ROOT']) return ['lambda', 'stderr'];
|
|
25
|
+
if (process.env['FUNCTION_TARGET'] || process.env['K_SERVICE'] || process.env['GOOGLE_CLOUD_PROJECT']) return ['google_cloud_function', 'default'];
|
|
26
|
+
if (process.env['AZURE_FUNCTIONS_ENVIRONMENT'] || process.env['FUNCTIONS_WORKER_RUNTIME']) return ['azure_function', 'default'];
|
|
27
|
+
return ['server', 'default'];
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** Check process.argv for CLI flags that should disable colors. */
|
|
31
|
+
function cliSuppressesColor(): boolean {
|
|
32
|
+
return process.argv.includes('--raw') || process.argv.includes('--dump-swml');
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
function deriveStream(mode: string | undefined): LogStream {
|
|
36
|
+
if (mode === 'stderr') return 'stderr';
|
|
37
|
+
return 'stdout';
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
function deriveSuppressed(mode: string | undefined): boolean {
|
|
41
|
+
if (mode === 'off') return true;
|
|
42
|
+
if (!mode || mode === 'auto') {
|
|
43
|
+
const [, derived] = getExecutionMode();
|
|
44
|
+
return derived === 'off';
|
|
45
|
+
}
|
|
46
|
+
return false;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
function deriveStreamFromMode(mode: string | undefined): LogStream {
|
|
50
|
+
if (mode === 'stderr') return 'stderr';
|
|
51
|
+
if (!mode || mode === 'auto') {
|
|
52
|
+
const [, derived] = getExecutionMode();
|
|
53
|
+
if (derived === 'stderr') return 'stderr';
|
|
54
|
+
}
|
|
55
|
+
return 'stdout';
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
function deriveColor(): boolean {
|
|
59
|
+
if (process.env['SIGNALWIRE_LOG_COLOR'] !== undefined) {
|
|
60
|
+
return process.env['SIGNALWIRE_LOG_COLOR'] === 'true';
|
|
61
|
+
}
|
|
62
|
+
if (cliSuppressesColor()) return false;
|
|
63
|
+
return process.stdout?.isTTY ?? false;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
let globalLevel: LogLevel = (process.env['SIGNALWIRE_LOG_LEVEL'] as LogLevel) ?? 'info';
|
|
67
|
+
let globalSuppressed = deriveSuppressed(process.env['SIGNALWIRE_LOG_MODE']);
|
|
68
|
+
let globalFormat: LogFormat = (process.env['SIGNALWIRE_LOG_FORMAT'] as LogFormat) ?? 'text';
|
|
69
|
+
let globalColor = deriveColor();
|
|
70
|
+
let globalStream: LogStream = deriveStreamFromMode(process.env['SIGNALWIRE_LOG_MODE']);
|
|
71
|
+
|
|
72
|
+
// ANSI color codes
|
|
73
|
+
const COLORS: Record<LogLevel, string> = {
|
|
74
|
+
debug: '\x1b[36m', // cyan
|
|
75
|
+
info: '\x1b[32m', // green
|
|
76
|
+
warn: '\x1b[33m', // yellow
|
|
77
|
+
error: '\x1b[31m', // red
|
|
78
|
+
};
|
|
79
|
+
const RESET = '\x1b[0m';
|
|
80
|
+
const DIM = '\x1b[2m';
|
|
81
|
+
|
|
82
|
+
// Logger cache
|
|
83
|
+
const loggerCache = new Map<string, Logger>();
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* Set the minimum log level for all loggers.
|
|
87
|
+
* @param level - The minimum severity level to emit.
|
|
88
|
+
*/
|
|
89
|
+
export function setGlobalLogLevel(level: LogLevel): void {
|
|
90
|
+
globalLevel = level;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* Suppress or unsuppress all log output globally.
|
|
95
|
+
* @param suppress - True to suppress, false to restore (default true).
|
|
96
|
+
*/
|
|
97
|
+
export function suppressAllLogs(suppress = true): void {
|
|
98
|
+
globalSuppressed = suppress;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* Set the output format for all loggers.
|
|
103
|
+
* @param format - Either 'text' (human-readable) or 'json' (structured).
|
|
104
|
+
*/
|
|
105
|
+
export function setGlobalLogFormat(format: LogFormat): void {
|
|
106
|
+
globalFormat = format;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* Enable or disable ANSI color codes in text-format output.
|
|
111
|
+
* @param enabled - True to enable colors, false to disable.
|
|
112
|
+
*/
|
|
113
|
+
export function setGlobalLogColor(enabled: boolean): void {
|
|
114
|
+
globalColor = enabled;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* Set the output stream for all loggers.
|
|
119
|
+
* @param stream - Either 'stdout' (default) or 'stderr'.
|
|
120
|
+
*/
|
|
121
|
+
export function setGlobalLogStream(stream: LogStream): void {
|
|
122
|
+
globalStream = stream;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/** Reset all logging settings to their environment-variable-based defaults. */
|
|
126
|
+
export function resetLoggingConfiguration(): void {
|
|
127
|
+
const mode = process.env['SIGNALWIRE_LOG_MODE'];
|
|
128
|
+
globalLevel = (process.env['SIGNALWIRE_LOG_LEVEL'] as LogLevel) ?? 'info';
|
|
129
|
+
globalSuppressed = deriveSuppressed(mode);
|
|
130
|
+
globalFormat = (process.env['SIGNALWIRE_LOG_FORMAT'] as LogFormat) ?? 'text';
|
|
131
|
+
globalColor = deriveColor();
|
|
132
|
+
globalStream = deriveStreamFromMode(mode);
|
|
133
|
+
loggerCache.clear();
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** Format a value for key=value text output. */
|
|
137
|
+
function formatKvValue(v: unknown): string {
|
|
138
|
+
if (v === null || v === undefined) return String(v);
|
|
139
|
+
if (typeof v === 'string') {
|
|
140
|
+
// Quote strings with spaces or special characters
|
|
141
|
+
if (/[\s"=,;{}[\]]/.test(v)) return `"${v.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
|
|
142
|
+
return v;
|
|
143
|
+
}
|
|
144
|
+
if (typeof v === 'object') return JSON.stringify(v);
|
|
145
|
+
return String(v);
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/** Convert a data record to key=value pairs string. */
|
|
149
|
+
function formatKvPairs(data: Record<string, unknown>): string {
|
|
150
|
+
return Object.entries(data)
|
|
151
|
+
.map(([k, v]) => `${k}=${formatKvValue(v)}`)
|
|
152
|
+
.join(' ');
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** Regex matching control characters that should be stripped from log values. */
|
|
156
|
+
const CONTROL_CHAR_RE = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g;
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Strip control characters from all string values in a data record to prevent
|
|
160
|
+
* log injection attacks. Mirrors Python SDK's `strip_control_chars` structlog
|
|
161
|
+
* processor. Processes nested objects and arrays recursively.
|
|
162
|
+
*
|
|
163
|
+
* @param data - The record whose string values should be sanitized.
|
|
164
|
+
* @returns A shallow copy of `data` with control characters removed from strings.
|
|
165
|
+
*/
|
|
166
|
+
export function stripControlChars<T extends Record<string, unknown>>(data: T): T {
|
|
167
|
+
const result = {} as T;
|
|
168
|
+
for (const key of Object.keys(data) as (keyof T)[]) {
|
|
169
|
+
const value = data[key];
|
|
170
|
+
if (typeof value === 'string') {
|
|
171
|
+
result[key] = value.replace(CONTROL_CHAR_RE, '') as T[keyof T];
|
|
172
|
+
} else if (Array.isArray(value)) {
|
|
173
|
+
result[key] = value.map((item) =>
|
|
174
|
+
typeof item === 'string'
|
|
175
|
+
? item.replace(CONTROL_CHAR_RE, '')
|
|
176
|
+
: item !== null && typeof item === 'object' && !Array.isArray(item)
|
|
177
|
+
? stripControlChars(item as Record<string, unknown>)
|
|
178
|
+
: item
|
|
179
|
+
) as T[keyof T];
|
|
180
|
+
} else if (value !== null && typeof value === 'object') {
|
|
181
|
+
result[key] = stripControlChars(value as Record<string, unknown>) as T[keyof T];
|
|
182
|
+
} else {
|
|
183
|
+
result[key] = value;
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
return result;
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
/** Serialize Error instances in data to plain objects with message, name, stack. */
|
|
190
|
+
function serializeErrors(data: Record<string, unknown>): Record<string, unknown> {
|
|
191
|
+
const result: Record<string, unknown> = {};
|
|
192
|
+
for (const [k, v] of Object.entries(data)) {
|
|
193
|
+
if (v instanceof Error) {
|
|
194
|
+
result[k] = { message: v.message, name: v.name, stack: v.stack };
|
|
195
|
+
} else {
|
|
196
|
+
result[k] = v;
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
return result;
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
/** Structured logger that respects global level, format, and color settings. */
|
|
203
|
+
export class Logger {
|
|
204
|
+
private name: string;
|
|
205
|
+
private context: Record<string, unknown>;
|
|
206
|
+
|
|
207
|
+
/**
|
|
208
|
+
* Create a new Logger instance.
|
|
209
|
+
* @param name - Logger name shown in log output.
|
|
210
|
+
* @param context - Optional key-value pairs included in every log entry.
|
|
211
|
+
*/
|
|
212
|
+
constructor(name: string, context?: Record<string, unknown>) {
|
|
213
|
+
this.name = name;
|
|
214
|
+
this.context = context ?? {};
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/**
|
|
218
|
+
* Create a child logger with additional bound context fields merged into the parent's context.
|
|
219
|
+
* @param context - Key-value pairs to merge into the child logger's context.
|
|
220
|
+
* @returns A new Logger instance with the merged context.
|
|
221
|
+
*/
|
|
222
|
+
bind(context: Record<string, unknown>): Logger {
|
|
223
|
+
return new Logger(this.name, { ...this.context, ...context });
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/**
|
|
227
|
+
* Log a message at the debug level.
|
|
228
|
+
* @param msg - The log message.
|
|
229
|
+
* @param data - Optional structured data to include.
|
|
230
|
+
*/
|
|
231
|
+
debug(msg: string, data?: Record<string, unknown>): void {
|
|
232
|
+
this.log('debug', msg, data);
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/**
|
|
236
|
+
* Log a message at the info level.
|
|
237
|
+
* @param msg - The log message.
|
|
238
|
+
* @param data - Optional structured data to include.
|
|
239
|
+
*/
|
|
240
|
+
info(msg: string, data?: Record<string, unknown>): void {
|
|
241
|
+
this.log('info', msg, data);
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
/**
|
|
245
|
+
* Log a message at the warn level.
|
|
246
|
+
* @param msg - The log message.
|
|
247
|
+
* @param data - Optional structured data to include.
|
|
248
|
+
*/
|
|
249
|
+
warn(msg: string, data?: Record<string, unknown>): void {
|
|
250
|
+
this.log('warn', msg, data);
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
/**
|
|
254
|
+
* Log a message at the error level.
|
|
255
|
+
* @param msg - The log message.
|
|
256
|
+
* @param data - Optional structured data to include.
|
|
257
|
+
*/
|
|
258
|
+
error(msg: string, data?: Record<string, unknown>): void {
|
|
259
|
+
this.log('error', msg, data);
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
private log(level: LogLevel, msg: string, data?: Record<string, unknown>): void {
|
|
263
|
+
if (globalSuppressed) return;
|
|
264
|
+
if (LEVELS[level] < LEVELS[globalLevel]) return;
|
|
265
|
+
|
|
266
|
+
// Serialize Error instances then strip control characters before merging
|
|
267
|
+
const serialized = data ? serializeErrors(data) : data;
|
|
268
|
+
const safeData = serialized ? stripControlChars(serialized) : serialized;
|
|
269
|
+
|
|
270
|
+
const merged = (safeData && Object.keys(safeData).length) || Object.keys(this.context).length
|
|
271
|
+
? { ...this.context, ...safeData }
|
|
272
|
+
: undefined;
|
|
273
|
+
|
|
274
|
+
if (globalFormat === 'json') {
|
|
275
|
+
this.logJson(level, msg, merged);
|
|
276
|
+
} else {
|
|
277
|
+
this.logText(level, msg, merged);
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
private logText(level: LogLevel, msg: string, data?: Record<string, unknown>): void {
|
|
282
|
+
const levelStr = level.toUpperCase();
|
|
283
|
+
const ts = new Date().toISOString();
|
|
284
|
+
let prefix: string;
|
|
285
|
+
if (globalColor) {
|
|
286
|
+
prefix = `${DIM}${ts}${RESET} ${COLORS[level]}[${levelStr}]${RESET} ${DIM}[${this.name}]${RESET}`;
|
|
287
|
+
} else {
|
|
288
|
+
prefix = `${ts} [${levelStr}] [${this.name}]`;
|
|
289
|
+
}
|
|
290
|
+
const suffix = data && Object.keys(data).length ? ' ' + formatKvPairs(data) : '';
|
|
291
|
+
const line = `${prefix} ${msg}${suffix}`;
|
|
292
|
+
|
|
293
|
+
this.emit(level, line);
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
private logJson(level: LogLevel, msg: string, data?: Record<string, unknown>): void {
|
|
297
|
+
const entry: Record<string, unknown> = {
|
|
298
|
+
timestamp: new Date().toISOString(),
|
|
299
|
+
level,
|
|
300
|
+
logger: this.name,
|
|
301
|
+
message: msg,
|
|
302
|
+
};
|
|
303
|
+
if (data && Object.keys(data).length) {
|
|
304
|
+
Object.assign(entry, data);
|
|
305
|
+
}
|
|
306
|
+
const line = JSON.stringify(entry);
|
|
307
|
+
|
|
308
|
+
this.emit(level, line);
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
private emit(level: LogLevel, line: string): void {
|
|
312
|
+
if (globalStream === 'stderr') {
|
|
313
|
+
console.error(line);
|
|
314
|
+
return;
|
|
315
|
+
}
|
|
316
|
+
switch (level) {
|
|
317
|
+
case 'debug': console.debug(line); break;
|
|
318
|
+
case 'info': console.info(line); break;
|
|
319
|
+
case 'warn': console.warn(line); break;
|
|
320
|
+
case 'error': console.error(line); break;
|
|
321
|
+
}
|
|
322
|
+
}
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
/**
|
|
326
|
+
* Create or retrieve a cached Logger instance with the given name.
|
|
327
|
+
* @param name - Logger name shown in log output.
|
|
328
|
+
* @returns A Logger instance (cached by name).
|
|
329
|
+
*/
|
|
330
|
+
export function getLogger(name: string): Logger {
|
|
331
|
+
let logger = loggerCache.get(name);
|
|
332
|
+
if (!logger) {
|
|
333
|
+
logger = new Logger(name);
|
|
334
|
+
loggerCache.set(name, logger);
|
|
335
|
+
}
|
|
336
|
+
return logger;
|
|
337
|
+
}
|