@provide-io/telemetry 0.2.2

package/dist/config.js

@@ -0,0 +1,350 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * TelemetryConfig — mirrors Python provide.telemetry TelemetryConfig.
+ *
+ * Env vars (same names as Python package):
+ *   PROVIDE_TELEMETRY_SERVICE_NAME, PROVIDE_TELEMETRY_ENV (fallback: PROVIDE_ENV),
+ *   PROVIDE_TELEMETRY_VERSION (fallback: PROVIDE_VERSION),
+ *   PROVIDE_LOG_LEVEL, PROVIDE_LOG_FORMAT, PROVIDE_TRACE_ENABLED,
+ *   PROVIDE_TELEMETRY_STRICT_SCHEMA,
+ *   OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS
+ */
+import { setSamplingPolicy } from './sampling';
+import { setQueuePolicy } from './backpressure';
+import { setExporterPolicy } from './resilience';
+import { setSetupError } from './health';
+import { ConfigurationError } from './exceptions';
+const DEFAULTS = {
+    serviceName: 'provide-service',
+    environment: 'development',
+    version: 'unknown',
+    logLevel: 'info',
+    logFormat: 'json',
+    otelEnabled: false,
+    sanitizeFields: [],
+    captureToWindow: true,
+    consoleOutput: false,
+    strictSchema: false,
+    requiredLogKeys: [],
+    logIncludeTimestamp: true,
+    logIncludeCaller: true,
+    logSanitize: true,
+    logCodeAttributes: false,
+    logModuleLevels: {},
+    traceSampleRate: 1.0,
+    metricsEnabled: true,
+    samplingLogsRate: 1.0,
+    samplingTracesRate: 1.0,
+    samplingMetricsRate: 1.0,
+    backpressureLogsMaxsize: 0,
+    backpressureTracesMaxsize: 0,
+    backpressureMetricsMaxsize: 0,
+    exporterLogsRetries: 0,
+    exporterLogsBackoffMs: 0,
+    exporterLogsTimeoutMs: 10000,
+    exporterLogsFailOpen: true,
+    exporterTracesRetries: 0,
+    exporterTracesBackoffMs: 0,
+    exporterTracesTimeoutMs: 10000,
+    exporterTracesFailOpen: true,
+    exporterMetricsRetries: 0,
+    exporterMetricsBackoffMs: 0,
+    exporterMetricsTimeoutMs: 10000,
+    exporterMetricsFailOpen: true,
+    sloEnableRedMetrics: false,
+    sloEnableUseMetrics: false,
+    piiMaxDepth: 8,
+    securityMaxAttrValueLength: 1024,
+    securityMaxAttrCount: 64,
+};
+let _config = { ...DEFAULTS };
+/** Read a string from Node process.env. Silently returns undefined in non-Node environments. */
+// Stryker disable BlockStatement
+function nodeEnv(key) {
+    try {
+        // process.env is not available in browser builds after tree-shaking,
+        // but some bundlers (esbuild, Vite) leave process.env.X inline replacements.
+        // Stryker disable next-line ConditionalExpression,StringLiteral: process is always defined in Node.js/test environments
+        return typeof process !== 'undefined' ? process.env[key] : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// Stryker enable BlockStatement
+/** Parse an env var as a number, falling back to `fallback` on missing or NaN. */
+function envNumber(key, fallback) {
+    const raw = nodeEnv(key);
+    // Stryker disable next-line ConditionalExpression: undefined check — removing returns NaN path which NaN guard catches identically
+    if (raw === undefined)
+        return fallback;
+    const n = Number(raw);
+    return Number.isNaN(n) ? fallback : n;
+}
+function envBool(key, fallback) {
+    const raw = nodeEnv(key);
+    if (raw === undefined || raw.trim() === '')
+        return fallback;
+    switch (raw.trim().toLowerCase()) {
+        case '1':
+        case 'true':
+        case 'yes':
+        case 'on':
+            return true;
+        case '0':
+        case 'false':
+        case 'no':
+        case 'off':
+            return false;
+        default:
+            throw new ConfigurationError(`invalid boolean for ${key}: ${JSON.stringify(raw)} (expected one of: 1,true,yes,on,0,false,no,off)`);
+    }
+}
+function envFloatInRange(key, fallback, min, max) {
+    const value = envNumber(key, fallback);
+    if (!Number.isFinite(value) || value < min || value > max) {
+        throw new ConfigurationError(`${key} must be in [${min}, ${max}], got ${String(value)}`);
+    }
+    return value;
+}
+function envNonNegativeInt(key, fallback) {
+    const value = envNumber(key, fallback);
+    if (!Number.isInteger(value) || value < 0) {
+        throw new ConfigurationError(`${key} must be a non-negative integer, got ${String(value)}`);
+    }
+    return value;
+}
+function envNonNegativeMsFromSeconds(key, fallbackMs) {
+    const value = envSecondsToMs(key, fallbackMs);
+    if (!Number.isFinite(value) || value < 0) {
+        throw new ConfigurationError(`${key} must be >= 0, got ${String(value)}`);
+    }
+    return value;
+}
+/** Parse an env var expressed in seconds and return milliseconds. */
+function envSecondsToMs(key, fallbackMs) {
+    const raw = nodeEnv(key);
+    // Stryker disable next-line ConditionalExpression: same as envNumber — undefined falls through to NaN guard
+    if (raw === undefined)
+        return fallbackMs;
+    const n = Number(raw);
+    return Number.isNaN(n) ? fallbackMs : n * 1000;
+}
+/** Parse a module_levels string like "mod1=DEBUG,mod2=WARN" into a Record. */
+function parseModuleLevels(raw) {
+    if (!raw)
+        return {};
+    const result = {};
+    for (const pair of raw.split(',')) {
+        /* Stryker disable MethodExpression,StringLiteral,ConditionalExpression: trim + includes('=') guard — removing produces malformed but non-crashing output */
+        const trimmed = pair.trim();
+        if (!trimmed.includes('='))
+            continue;
+        /* Stryker restore MethodExpression,StringLiteral,ConditionalExpression */
+        const [mod, level] = trimmed.split('=', 2).map((s) => s.trim());
+        if (mod && level)
+            result[mod] = level;
+    }
+    return result;
+}
+/**
+ * Build a TelemetryConfig from environment variables.
+ * Uses the same env var names as the Python package.
+ * Explicit values passed to setupTelemetry() override env vars.
+ */
+export function configFromEnv() {
+    const otelHeader = nodeEnv('OTEL_EXPORTER_OTLP_HEADERS');
+    const parsedHeaders = otelHeader ? parseOtlpHeaders(otelHeader) : undefined;
+    return {
+        serviceName: nodeEnv('PROVIDE_TELEMETRY_SERVICE_NAME') ?? DEFAULTS.serviceName,
+        environment: nodeEnv('PROVIDE_TELEMETRY_ENV') ?? nodeEnv('PROVIDE_ENV') ?? DEFAULTS.environment,
+        version: nodeEnv('PROVIDE_TELEMETRY_VERSION') ?? nodeEnv('PROVIDE_VERSION') ?? DEFAULTS.version,
+        logLevel: nodeEnv('PROVIDE_LOG_LEVEL')?.toLowerCase() ?? DEFAULTS.logLevel,
+        logFormat: (() => {
+            const fmt = nodeEnv('PROVIDE_LOG_FORMAT');
+            // Stryker disable next-line ConditionalExpression: 'json' is DEFAULTS.logFormat so removing its check returns the same default value
+            return fmt === 'json' || fmt === 'pretty' ? fmt : DEFAULTS.logFormat;
+        })(),
+        otelEnabled: envBool('PROVIDE_TRACE_ENABLED', DEFAULTS.otelEnabled),
+        otlpEndpoint: nodeEnv('OTEL_EXPORTER_OTLP_ENDPOINT'),
+        otlpHeaders: parsedHeaders,
+        sanitizeFields: DEFAULTS.sanitizeFields,
+        captureToWindow: true,
+        consoleOutput: false,
+        strictSchema: envBool('PROVIDE_TELEMETRY_STRICT_SCHEMA', DEFAULTS.strictSchema),
+        requiredLogKeys: (() => {
+            const raw = nodeEnv('PROVIDE_TELEMETRY_REQUIRED_KEYS');
+            return raw
+                ? raw
+                    .split(',')
+                    .map((s) => s.trim())
+                    .filter(Boolean)
+                : [];
+        })(),
+        // Logging extras
+        logIncludeTimestamp: envBool('PROVIDE_LOG_INCLUDE_TIMESTAMP', DEFAULTS.logIncludeTimestamp),
+        logIncludeCaller: envBool('PROVIDE_LOG_INCLUDE_CALLER', DEFAULTS.logIncludeCaller),
+        logSanitize: envBool('PROVIDE_LOG_SANITIZE', DEFAULTS.logSanitize),
+        logCodeAttributes: envBool('PROVIDE_LOG_CODE_ATTRIBUTES', DEFAULTS.logCodeAttributes),
+        logModuleLevels: parseModuleLevels(nodeEnv('PROVIDE_LOG_MODULE_LEVELS')),
+        // Tracing
+        traceSampleRate: envFloatInRange('PROVIDE_TRACE_SAMPLE_RATE', DEFAULTS.traceSampleRate, 0, 1),
+        // Metrics
+        metricsEnabled: envBool('PROVIDE_METRICS_ENABLED', DEFAULTS.metricsEnabled),
+        // Per-signal sampling
+        samplingLogsRate: envFloatInRange('PROVIDE_SAMPLING_LOGS_RATE', DEFAULTS.samplingLogsRate, 0, 1),
+        samplingTracesRate: envFloatInRange('PROVIDE_SAMPLING_TRACES_RATE', DEFAULTS.samplingTracesRate, 0, 1),
+        samplingMetricsRate: envFloatInRange('PROVIDE_SAMPLING_METRICS_RATE', DEFAULTS.samplingMetricsRate, 0, 1),
+        // Per-signal backpressure
+        backpressureLogsMaxsize: envNonNegativeInt('PROVIDE_BACKPRESSURE_LOGS_MAXSIZE', DEFAULTS.backpressureLogsMaxsize),
+        backpressureTracesMaxsize: envNonNegativeInt('PROVIDE_BACKPRESSURE_TRACES_MAXSIZE', DEFAULTS.backpressureTracesMaxsize),
+        backpressureMetricsMaxsize: envNonNegativeInt('PROVIDE_BACKPRESSURE_METRICS_MAXSIZE', DEFAULTS.backpressureMetricsMaxsize),
+        // Per-signal exporter resilience
+        exporterLogsRetries: envNonNegativeInt('PROVIDE_EXPORTER_LOGS_RETRIES', DEFAULTS.exporterLogsRetries),
+        exporterLogsBackoffMs: envNonNegativeMsFromSeconds('PROVIDE_EXPORTER_LOGS_BACKOFF_SECONDS', DEFAULTS.exporterLogsBackoffMs),
+        exporterLogsTimeoutMs: envNonNegativeMsFromSeconds('PROVIDE_EXPORTER_LOGS_TIMEOUT_SECONDS', DEFAULTS.exporterLogsTimeoutMs),
+        exporterLogsFailOpen: envBool('PROVIDE_EXPORTER_LOGS_FAIL_OPEN', DEFAULTS.exporterLogsFailOpen),
+        exporterTracesRetries: envNonNegativeInt('PROVIDE_EXPORTER_TRACES_RETRIES', DEFAULTS.exporterTracesRetries),
+        exporterTracesBackoffMs: envNonNegativeMsFromSeconds('PROVIDE_EXPORTER_TRACES_BACKOFF_SECONDS', DEFAULTS.exporterTracesBackoffMs),
+        exporterTracesTimeoutMs: envNonNegativeMsFromSeconds('PROVIDE_EXPORTER_TRACES_TIMEOUT_SECONDS', DEFAULTS.exporterTracesTimeoutMs),
+        exporterTracesFailOpen: envBool('PROVIDE_EXPORTER_TRACES_FAIL_OPEN', DEFAULTS.exporterTracesFailOpen),
+        exporterMetricsRetries: envNonNegativeInt('PROVIDE_EXPORTER_METRICS_RETRIES', DEFAULTS.exporterMetricsRetries),
+        exporterMetricsBackoffMs: envNonNegativeMsFromSeconds('PROVIDE_EXPORTER_METRICS_BACKOFF_SECONDS', DEFAULTS.exporterMetricsBackoffMs),
+        exporterMetricsTimeoutMs: envNonNegativeMsFromSeconds('PROVIDE_EXPORTER_METRICS_TIMEOUT_SECONDS', DEFAULTS.exporterMetricsTimeoutMs),
+        exporterMetricsFailOpen: envBool('PROVIDE_EXPORTER_METRICS_FAIL_OPEN', DEFAULTS.exporterMetricsFailOpen),
+        // SLO
+        sloEnableRedMetrics: envBool('PROVIDE_SLO_ENABLE_RED_METRICS', DEFAULTS.sloEnableRedMetrics),
+        sloEnableUseMetrics: envBool('PROVIDE_SLO_ENABLE_USE_METRICS', DEFAULTS.sloEnableUseMetrics),
+        // PII
+        piiMaxDepth: envNonNegativeInt('PROVIDE_LOG_PII_MAX_DEPTH', DEFAULTS.piiMaxDepth),
+        // Security
+        securityMaxAttrValueLength: envNonNegativeInt('PROVIDE_SECURITY_MAX_ATTR_VALUE_LENGTH', DEFAULTS.securityMaxAttrValueLength),
+        securityMaxAttrCount: envNonNegativeInt('PROVIDE_SECURITY_MAX_ATTR_COUNT', DEFAULTS.securityMaxAttrCount),
+    };
+}
+/** Return the active TelemetryConfig. */
+export function getConfig() {
+    return _config;
+}
+/**
+ * Apply parsed config fields to the runtime policy engines (sampling, backpressure, resilience).
+ * Mirrors Python provide.telemetry.runtime.apply_runtime_config.
+ */
+export function applyConfigPolicies(cfg) {
+    // Sampling
+    setSamplingPolicy('logs', { defaultRate: cfg.samplingLogsRate });
+    setSamplingPolicy('traces', { defaultRate: cfg.samplingTracesRate });
+    setSamplingPolicy('metrics', { defaultRate: cfg.samplingMetricsRate });
+    // Backpressure
+    setQueuePolicy({
+        maxLogs: cfg.backpressureLogsMaxsize,
+        maxTraces: cfg.backpressureTracesMaxsize,
+        maxMetrics: cfg.backpressureMetricsMaxsize,
+    });
+    // Exporter resilience (per-signal)
+    setExporterPolicy('logs', {
+        retries: cfg.exporterLogsRetries,
+        backoffMs: cfg.exporterLogsBackoffMs,
+        timeoutMs: cfg.exporterLogsTimeoutMs,
+        failOpen: cfg.exporterLogsFailOpen,
+    });
+    setExporterPolicy('traces', {
+        retries: cfg.exporterTracesRetries,
+        backoffMs: cfg.exporterTracesBackoffMs,
+        timeoutMs: cfg.exporterTracesTimeoutMs,
+        failOpen: cfg.exporterTracesFailOpen,
+    });
+    setExporterPolicy('metrics', {
+        retries: cfg.exporterMetricsRetries,
+        backoffMs: cfg.exporterMetricsBackoffMs,
+        timeoutMs: cfg.exporterMetricsTimeoutMs,
+        failOpen: cfg.exporterMetricsFailOpen,
+    });
+}
+/**
+ * Configure telemetry. Call once at app startup.
+ * Merges explicit values over the current config (which may include env-derived values).
+ */
+export function setupTelemetry(overrides) {
+    _config = { ...configFromEnv(), ...overrides };
+    try {
+        applyConfigPolicies(_config);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        setSetupError(message);
+        console.warn(`setupTelemetry: applyConfigPolicies failed: ${message}`);
+    }
+}
+/** Reset to defaults (used in tests). */
+export function _resetConfig() {
+    _config = { ...DEFAULTS };
+}
+/**
+ * Parse OTLP-style header string "key=value,key2=value2" into a Record.
+ * Keys and values are URL-decoded. Malformed pairs (no '=') and empty keys are skipped.
+ * Values may contain '=' characters (only the first '=' splits key from value).
+ */
+export function parseOtlpHeaders(raw) {
+    const result = {};
+    // Stryker disable next-line ConditionalExpression: early return is an optimization — empty string splits to [""], idx<1 skips the only pair, returns {} identically
+    if (!raw)
+        return result;
+    for (const pair of raw.split(',')) {
+        const idx = pair.indexOf('=');
+        if (idx < 1)
+            continue; // no '=' or empty key
+        const rawKey = pair.slice(0, idx).trim();
+        const rawVal = pair.slice(idx + 1).trim();
+        try {
+            const key = decodeURIComponent(rawKey);
+            // Stryker disable next-line ConditionalExpression: defensive guard — unreachable because idx<1 check and trim() already exclude empty keys
+            /* v8 ignore next: defensive — idx<1 and trim() already exclude observable empty keys */
+            if (!key)
+                continue;
+            const val = decodeURIComponent(rawVal);
+            result[key] = val;
+        }
+        catch {
+            // Skip pairs with invalid URL encoding
+            continue;
+        }
+    }
+    return result;
+}
+/** Mask a single header value: show first 4 chars + **** if >= 8 chars, else ****. */
+function maskHeaderValue(v) {
+    return v.length < 8 ? '****' : v.slice(0, 4) + '****';
+}
+/** Mask the password component of a URL's userinfo, if present. */
+function maskEndpointUrl(raw) {
+    try {
+        const u = new URL(raw);
+        if (u.password) {
+            u.password = '****';
+            return u.toString();
+        }
+    }
+    catch {
+        /* not a valid URL — return as-is */
+    }
+    return raw;
+}
+/**
+ * Return a copy of the config with OTLP secrets masked.
+ * Safe to log or serialize — never leaks header values or endpoint credentials.
+ */
+export function redactConfig(config) {
+    const result = { ...config };
+    if (config.otlpHeaders && Object.keys(config.otlpHeaders).length > 0) {
+        result.otlpHeaders = Object.fromEntries(Object.entries(config.otlpHeaders).map(([k, v]) => [k, maskHeaderValue(v)]));
+    }
+    if (config.otlpEndpoint) {
+        result.otlpEndpoint = maskEndpointUrl(config.otlpEndpoint);
+    }
+    return result;
+}
+/** Package version — mirrors Python __version__. */
+export const version = '0.2.0';
+export const __version__ = version;

package/dist/consent.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Consent-aware telemetry collection — strippable governance module.
+ * When deleted, all signals pass through unchanged.
+ */
+export type ConsentLevel = 'FULL' | 'FUNCTIONAL' | 'MINIMAL' | 'NONE';
+export declare function setConsentLevel(level: ConsentLevel): void;
+export declare function getConsentLevel(): ConsentLevel;
+export declare function shouldAllow(signal: string, logLevel?: string): boolean;
+export declare function loadConsentFromEnv(): void;
+export declare function resetConsentForTests(): void;
+//# sourceMappingURL=consent.d.ts.map

package/dist/consent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent.d.ts","sourceRoot":"","sources":["../src/consent.ts"],"names":[],"mappings":"AAGA;;;GAGG;AAEH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,YAAY,GAAG,SAAS,GAAG,MAAM,CAAC;AActE,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAEzD;AAED,wBAAgB,eAAe,IAAI,YAAY,CAE9C;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAkBtE;AAED,wBAAgB,kBAAkB,IAAI,IAAI,CAMzC;AAED,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}

package/dist/consent.js

@@ -0,0 +1,50 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+const LOG_LEVEL_ORDER = {
+    TRACE: 0,
+    DEBUG: 1,
+    INFO: 2,
+    WARNING: 3,
+    WARN: 3,
+    ERROR: 4,
+    CRITICAL: 5,
+};
+let _consentLevel = 'FULL';
+export function setConsentLevel(level) {
+    _consentLevel = level;
+}
+export function getConsentLevel() {
+    return _consentLevel;
+}
+export function shouldAllow(signal, logLevel) {
+    const level = _consentLevel;
+    if (level === 'FULL')
+        return true;
+    if (level === 'NONE')
+        return false;
+    if (level === 'FUNCTIONAL') {
+        if (signal === 'logs') {
+            const order = LOG_LEVEL_ORDER[(logLevel ?? '').toUpperCase()] ?? 0;
+            return order >= LOG_LEVEL_ORDER['WARNING'];
+        }
+        if (signal === 'context')
+            return false;
+        return true;
+    }
+    // MINIMAL
+    if (signal === 'logs') {
+        const order = LOG_LEVEL_ORDER[(logLevel ?? '').toUpperCase()] ?? 0;
+        return order >= LOG_LEVEL_ORDER['ERROR'];
+    }
+    return false;
+}
+export function loadConsentFromEnv() {
+    const raw = (process.env['PROVIDE_CONSENT_LEVEL'] ?? 'FULL').trim().toUpperCase();
+    const valid = ['FULL', 'FUNCTIONAL', 'MINIMAL', 'NONE'];
+    if (valid.includes(raw)) {
+        _consentLevel = raw;
+    }
+}
+export function resetConsentForTests() {
+    _consentLevel = 'FULL';
+}

package/dist/context.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Module-level context binding — mirrors Python provide.telemetry bind_context/unbind_context.
+ *
+ * In browser environments, context is stored in a module-level object. All log calls
+ * in the same JS execution context share the same bindings.
+ *
+ * In Node.js environments, AsyncLocalStorage provides per-async-context isolation
+ * (useful for SSR / worker processes where multiple requests run concurrently).
+ * Use runWithContext() to scope bindings to a single request/operation.
+ */
+type Context = Record<string, unknown>;
+type ALS = {
+    getStore(): Context | undefined;
+    run<T>(store: Context, fn: () => T): T;
+    enterWith(store: Context): void;
+};
+/**
+ * Bind key/value pairs into the current context.
+ * These fields are merged into every log record emitted after this call.
+ */
+export declare function bindContext(values: Context): void;
+/**
+ * Remove specific keys from the current context.
+ */
+export declare function unbindContext(...keys: string[]): void;
+/**
+ * Clear all context bindings.
+ */
+export declare function clearContext(): void;
+/**
+ * Return a snapshot of the current context (no side effects).
+ */
+export declare function getContext(): Context;
+/**
+ * Run fn with additional context values scoped to its execution.
+ * In Node.js, uses AsyncLocalStorage so the bindings are isolated per-request.
+ * In browser, temporarily binds then restores the previous state.
+ * Mirrors Python: contextvars copy_context().run(fn) pattern.
+ */
+export declare function runWithContext<T>(values: Context, fn: () => T): T;
+/**
+ * Bind a session ID that propagates across all telemetry events.
+ */
+export declare function bindSessionContext(sessionId: string): void;
+/**
+ * Return the current session ID, or null if not set.
+ */
+export declare function getSessionId(): string | null;
+/**
+ * Clear the session ID.
+ */
+export declare function clearSessionContext(): void;
+/** Reset to empty context (used in tests). */
+export declare function _resetContext(): void;
+/** Disable AsyncLocalStorage for testing the module-level fallback path. */
+export declare function _disableAsyncLocalStorageForTest(): ALS | null;
+/** Re-enable AsyncLocalStorage after testing (pass value from _disable call). */
+export declare function _restoreAsyncLocalStorageForTest(saved: ALS | null): void;
+export {};
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AAEH,KAAK,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAGvC,KAAK,GAAG,GAAG;IACT,QAAQ,IAAI,OAAO,GAAG,SAAS,CAAC;IAChC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IACvC,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CACjC,CAAC;AAoCF;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAGjD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAGrD;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,IAAI,CASnC;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAYjE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAE1D;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAG5C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED,8CAA8C;AAC9C,wBAAgB,aAAa,IAAI,IAAI,CAMpC;AAED,4EAA4E;AAC5E,wBAAgB,gCAAgC,IAAI,GAAG,GAAG,IAAI,CAI7D;AAED,iFAAiF;AACjF,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI,CAExE"}

package/dist/context.js

@@ -0,0 +1,127 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+// ── AsyncLocalStorage (Node.js / Cloudflare Workers) ──────────────────────────
+let _asyncLocalStorage = null;
+let _AlsConstructor = null;
+try {
+    // Dynamic require so the import doesn't break browser bundles.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const als = require('node:async_hooks');
+    _AlsConstructor = als.AsyncLocalStorage;
+    _asyncLocalStorage = new _AlsConstructor();
+}
+catch {
+    // Not available — fall back to module-level context below.
+}
+// ── Fallback: module-level context (browser / single-thread) ──────────────────
+let _moduleCtx = {};
+function getStore() {
+    if (_asyncLocalStorage) {
+        return _asyncLocalStorage.getStore() ?? _moduleCtx;
+    }
+    return _moduleCtx;
+}
+function ensureStore() {
+    if (_asyncLocalStorage) {
+        const store = _asyncLocalStorage.getStore();
+        if (store)
+            return store;
+        const next = { ..._moduleCtx };
+        _asyncLocalStorage.enterWith(next);
+        return next;
+    }
+    return _moduleCtx;
+}
+/**
+ * Bind key/value pairs into the current context.
+ * These fields are merged into every log record emitted after this call.
+ */
+export function bindContext(values) {
+    const store = ensureStore();
+    Object.assign(store, values);
+}
+/**
+ * Remove specific keys from the current context.
+ */
+export function unbindContext(...keys) {
+    const store = ensureStore();
+    for (const k of keys)
+        delete store[k];
+}
+/**
+ * Clear all context bindings.
+ */
+export function clearContext() {
+    if (_asyncLocalStorage) {
+        const store = _asyncLocalStorage.getStore();
+        if (store) {
+            for (const k of Object.keys(store))
+                delete store[k];
+            return;
+        }
+    }
+    _moduleCtx = {};
+}
+/**
+ * Return a snapshot of the current context (no side effects).
+ */
+export function getContext() {
+    return { ...getStore() };
+}
+/**
+ * Run fn with additional context values scoped to its execution.
+ * In Node.js, uses AsyncLocalStorage so the bindings are isolated per-request.
+ * In browser, temporarily binds then restores the previous state.
+ * Mirrors Python: contextvars copy_context().run(fn) pattern.
+ */
+export function runWithContext(values, fn) {
+    if (_asyncLocalStorage) {
+        const inherited = { ...getStore(), ...values };
+        return _asyncLocalStorage.run(inherited, fn);
+    }
+    const prev = { ...getStore() };
+    bindContext(values);
+    try {
+        return fn();
+    }
+    finally {
+        _moduleCtx = prev;
+    }
+}
+/**
+ * Bind a session ID that propagates across all telemetry events.
+ */
+export function bindSessionContext(sessionId) {
+    bindContext({ session_id: sessionId });
+}
+/**
+ * Return the current session ID, or null if not set.
+ */
+export function getSessionId() {
+    const sessionId = getStore()['session_id'];
+    return typeof sessionId === 'string' ? sessionId : null;
+}
+/**
+ * Clear the session ID.
+ */
+export function clearSessionContext() {
+    unbindContext('session_id');
+}
+/** Reset to empty context (used in tests). */
+export function _resetContext() {
+    // Recreate ALS so no enterWith-seeded store leaks between tests.
+    // The null branch is only reachable in environments without node:async_hooks (e.g. browsers).
+    /* v8 ignore next */
+    _asyncLocalStorage = _AlsConstructor ? new _AlsConstructor() : null;
+    _moduleCtx = {};
+}
+/** Disable AsyncLocalStorage for testing the module-level fallback path. */
+export function _disableAsyncLocalStorageForTest() {
+    const prev = _asyncLocalStorage;
+    _asyncLocalStorage = null;
+    return prev;
+}
+/** Re-enable AsyncLocalStorage after testing (pass value from _disable call). */
+export function _restoreAsyncLocalStorageForTest(saved) {
+    _asyncLocalStorage = saved;
+}

package/dist/exceptions.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Exception hierarchy — mirrors Python provide.telemetry.exceptions.
+ */
+export declare class TelemetryError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Raised when telemetry configuration is invalid.
+ * Also extends Error directly for maximum compatibility.
+ */
+export declare class ConfigurationError extends TelemetryError {
+    constructor(message?: string);
+}
+//# sourceMappingURL=exceptions.d.ts.map

package/dist/exceptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.d.ts","sourceRoot":"","sources":["../src/exceptions.ts"],"names":[],"mappings":"AAGA;;GAEG;AAEH,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,CAAC,EAAE,MAAM;CAI7B;AAED;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,cAAc;gBACxC,OAAO,CAAC,EAAE,MAAM;CAI7B"}

package/dist/exceptions.js

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Exception hierarchy — mirrors Python provide.telemetry.exceptions.
+ */
+export class TelemetryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TelemetryError';
+    }
+}
+/**
+ * Raised when telemetry configuration is invalid.
+ * Also extends Error directly for maximum compatibility.
+ */
+export class ConfigurationError extends TelemetryError {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigurationError';
+    }
+}

package/dist/fingerprint.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Compute a stable 12-char hex fingerprint for an error.
+ */
+export declare function computeErrorFingerprint(errorName: string, stack?: string): string;
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../src/fingerprint.ts"],"names":[],"mappings":"AA6CA;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAIjF"}