@provide-io/telemetry 0.2.2

package/dist/pretty.js

@@ -0,0 +1,85 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Pretty ANSI log renderer for CLI / terminal output.
+ *
+ * Mirrors Python provide.telemetry.logger.pretty.PrettyRenderer.
+ * Same color scheme, same layout: timestamp [level] event key=value pairs.
+ */
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const LEVEL_COLORS = {
+    fatal: '\x1b[31;1m', // bold red
+    error: '\x1b[31m', // red
+    warn: '\x1b[33m', // yellow
+    info: '\x1b[32m', // green
+    debug: '\x1b[34m', // blue
+    trace: '\x1b[36m', // cyan
+};
+// pino level number → name
+const LEVEL_NAMES = {
+    10: 'trace',
+    20: 'debug',
+    30: 'info',
+    40: 'warn',
+    50: 'error',
+    60: 'fatal',
+};
+const LEVEL_PAD = 6; // "fatal" = 5, pad to 6
+// Keys to exclude from the key=value tail (already rendered or internal)
+const SKIP_KEYS = new Set(['level', 'time', 'msg', 'event', 'v', 'pid', 'hostname']);
+/**
+ * Detect whether stdout supports color.
+ * Returns false in browsers, CI without FORCE_COLOR, or piped output.
+ */
+export function supportsColor() {
+    // Stryker disable next-line ConditionalExpression,StringLiteral,BooleanLiteral -- browser-only guard
+    /* v8 ignore next -- browser-only path, untestable in Node */
+    if (typeof process === 'undefined')
+        return false;
+    if (process.env['FORCE_COLOR'] === '1' || process.env['FORCE_COLOR'] === 'true')
+        return true;
+    if (process.env['NO_COLOR'] !== undefined)
+        return false;
+    // Stryker disable next-line OptionalChaining -- process.stdout is always defined in Node/test env
+    if (typeof process.stdout?.isTTY === 'boolean')
+        return process.stdout.isTTY;
+    return false;
+}
+/**
+ * Format a pino log object as a pretty ANSI string.
+ *
+ * Layout: `timestamp [level   ] event  key=value key=value`
+ */
+export function formatPretty(obj, colors) {
+    const parts = [];
+    // 1. Timestamp
+    const time = obj['time'];
+    if (time !== undefined) {
+        const ts = typeof time === 'number' ? new Date(time).toISOString() : String(time);
+        parts.push(colors ? DIM + ts + RESET : ts);
+    }
+    // 2. Level
+    const levelNum = obj['level'];
+    const levelName = LEVEL_NAMES[levelNum] ?? 'log';
+    const padded = levelName.padEnd(LEVEL_PAD);
+    if (colors) {
+        const c = LEVEL_COLORS[levelName] ?? '';
+        parts.push('[' + c + padded + RESET + ']');
+    }
+    else {
+        parts.push('[' + padded + ']');
+    }
+    // 3. Event / message
+    const event = obj['event'] ?? obj['msg'] ?? '';
+    parts.push(String(event));
+    // 4. Remaining key=value pairs (sorted, skip internal keys)
+    const keys = Object.keys(obj)
+        .filter((k) => !SKIP_KEYS.has(k))
+        .sort();
+    for (const k of keys) {
+        const v = JSON.stringify(obj[k]);
+        parts.push(colors ? DIM + k + RESET + '=' + v : k + '=' + v);
+    }
+    return parts.join(' ');
+}

package/dist/propagation.d.ts

@@ -0,0 +1,52 @@
+/**
+ * W3C trace context propagation helpers.
+ * Mirrors Python provide.telemetry.propagation.
+ */
+export interface PropagationContext {
+    traceparent?: string;
+    tracestate?: string;
+    baggage?: string;
+    traceId?: string;
+    spanId?: string;
+}
+/** Maximum length (in characters) for traceparent or tracestate header values. */
+export declare const MAX_HEADER_LENGTH = 512;
+/** Maximum number of comma-separated key=value pairs in tracestate. */
+export declare const MAX_TRACESTATE_PAIRS = 32;
+/** Maximum length (in characters) for the baggage header value. */
+export declare const MAX_BAGGAGE_LENGTH = 8192;
+type PropagationStore = {
+    active: PropagationContext;
+    stack: PropagationContext[];
+    otelCtxStack: unknown[];
+};
+export type PropagationALS = {
+    getStore(): PropagationStore | undefined;
+    run<T>(store: PropagationStore, fn: () => T): T;
+    enterWith(store: PropagationStore): void;
+};
+/**
+ * Extract W3C trace context from an HTTP headers object.
+ */
+export declare function extractW3cContext(headers: Record<string, string>): PropagationContext;
+/**
+ * Push ctx onto the propagation stack, making it the active context.
+ * When traceparent is present and OTel API is available, extracts an OTel
+ * context so that child spans created via withTrace() inherit the parent.
+ */
+export declare function bindPropagationContext(ctx: PropagationContext): void;
+/**
+ * Pop the last saved context, restoring the previous state.
+ */
+export declare function clearPropagationContext(): void;
+/** Return the currently active propagation context. */
+export declare function getActivePropagationContext(): PropagationContext;
+/** Return the top of the OTel context stack, or undefined if empty/no OTel wiring. */
+export declare function getActiveOtelContext(): unknown | undefined;
+export declare function _resetPropagationForTests(): void;
+/** Disable AsyncLocalStorage for testing the module-level fallback path. */
+export declare function _disablePropagationALSForTest(): PropagationALS | null;
+/** Re-enable AsyncLocalStorage after testing (pass value from _disable call). */
+export declare function _restorePropagationALSForTest(saved: PropagationALS | null): void;
+export {};
+//# sourceMappingURL=propagation.d.ts.map

package/dist/propagation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"propagation.d.ts","sourceRoot":"","sources":["../src/propagation.ts"],"names":[],"mappings":"AAGA;;;GAGG;AAEH,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,MAAM,CAAC;AACrC,uEAAuE;AACvE,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,mEAAmE;AACnE,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAGvC,KAAK,gBAAgB,GAAG;IACtB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,YAAY,EAAE,OAAO,EAAE,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,IAAI,gBAAgB,GAAG,SAAS,CAAC;IACzC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,gBAAgB,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAChD,SAAS,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC1C,CAAC;AAiEF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,kBAAkB,CAkCrF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,kBAAkB,GAAG,IAAI,CAyBpE;AAED;;GAEG;AAEH,wBAAgB,uBAAuB,IAAI,IAAI,CAa9C;AAGD,uDAAuD;AACvD,wBAAgB,2BAA2B,IAAI,kBAAkB,CAEhE;AAED,sFAAsF;AACtF,wBAAgB,oBAAoB,IAAI,OAAO,GAAG,SAAS,CAK1D;AAED,wBAAgB,yBAAyB,IAAI,IAAI,CAMhD;AAED,4EAA4E;AAC5E,wBAAgB,6BAA6B,IAAI,cAAc,GAAG,IAAI,CAIrE;AAED,iFAAiF;AACjF,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CAEhF"}

package/dist/propagation.js

@@ -0,0 +1,183 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+/** Maximum length (in characters) for traceparent or tracestate header values. */
+export const MAX_HEADER_LENGTH = 512;
+/** Maximum number of comma-separated key=value pairs in tracestate. */
+export const MAX_TRACESTATE_PAIRS = 32;
+/** Maximum length (in characters) for the baggage header value. */
+export const MAX_BAGGAGE_LENGTH = 8192;
+// ── AsyncLocalStorage (Node.js / Cloudflare Workers) ──────────────────────────
+let _als = null;
+let _AlsConstructor = null;
+// Stryker disable BlockStatement: module-level try/catch runs once at import time — cannot be tested by unit tests
+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;
+    _als = new _AlsConstructor();
+}
+catch {
+    // Not available — fall back to module-level store below.
+}
+// Stryker restore BlockStatement
+// ── Fallback: module-level store (browser / single-thread) ────────────────────
+// Stryker disable next-line ArrayDeclaration: initial empty arrays are overwritten by _resetPropagationForTests in every test beforeEach
+let _fallbackStore = { active: {}, stack: [], otelCtxStack: [] };
+function _getStore() {
+    if (_als) {
+        return _als.getStore() ?? _fallbackStore;
+    }
+    return _fallbackStore;
+}
+// Stryker disable ConditionalExpression,BlockStatement,ArrayDeclaration: _ensureStore ALS-to-fallback clone path — tested by "clones fallback stack" test; remaining mutants are equivalent because _resetPropagationForTests empties both stores
+function _ensureStore() {
+    if (_als) {
+        const store = _als.getStore();
+        if (store)
+            return store;
+        const next = {
+            active: { ..._fallbackStore.active },
+            stack: _fallbackStore.stack.map((entry) => ({ ...entry })),
+            otelCtxStack: [..._fallbackStore.otelCtxStack],
+        };
+        _als.enterWith(next);
+        return next;
+    }
+    return _fallbackStore;
+}
+// Stryker restore ConditionalExpression,BlockStatement,ArrayDeclaration
+function _parseTraceparent(value) {
+    const parts = value.split('-');
+    if (parts.length !== 4)
+        return {};
+    const [version, traceId, spanId] = parts;
+    if (version.length !== 2 || traceId.length !== 32 || spanId.length !== 16)
+        return {};
+    if (version.toLowerCase() === 'ff')
+        return {};
+    if (traceId === '0'.repeat(32) || spanId === '0'.repeat(16))
+        return {};
+    // Validate that all fields are valid hex strings.
+    if (!/^[0-9a-fA-F]+$/.test(version) ||
+        !/^[0-9a-fA-F]+$/.test(traceId) ||
+        !/^[0-9a-fA-F]+$/.test(spanId)) {
+        return {};
+    }
+    return { traceId: traceId.toLowerCase(), spanId: spanId.toLowerCase() };
+}
+/**
+ * Extract W3C trace context from an HTTP headers object.
+ */
+export function extractW3cContext(headers) {
+    const lower = {};
+    for (const [k, v] of Object.entries(headers))
+        lower[k.toLowerCase()] = v;
+    let rawTraceparent = lower['traceparent'];
+    let tracestate = lower['tracestate'];
+    let baggage = lower['baggage'];
+    // Stryker disable next-line ConditionalExpression,EqualityOperator,BlockStatement: size guard — >= vs > on boundary is equivalent (512-char valid traceparent doesn't exist)
+    if (rawTraceparent !== undefined && rawTraceparent.length > MAX_HEADER_LENGTH) {
+        rawTraceparent = undefined;
+    }
+    if (tracestate !== undefined) {
+        if (tracestate.length > MAX_HEADER_LENGTH) {
+            tracestate = undefined;
+        }
+        else if (tracestate.split(',').length > MAX_TRACESTATE_PAIRS) {
+            tracestate = undefined;
+        }
+    }
+    if (baggage !== undefined && baggage.length > MAX_BAGGAGE_LENGTH) {
+        baggage = undefined;
+    }
+    const { traceId, spanId } = rawTraceparent ? _parseTraceparent(rawTraceparent) : {};
+    // Stryker disable next-line LogicalOperator: traceId and spanId are always both defined or both undefined (from _parseTraceparent) — && and || give identical results
+    const traceparent = traceId && spanId ? rawTraceparent : undefined;
+    return {
+        ...(traceparent !== undefined && { traceparent }),
+        ...(tracestate !== undefined && { tracestate }),
+        ...(baggage !== undefined && { baggage }),
+        ...(traceId !== undefined && { traceId }),
+        ...(spanId !== undefined && { spanId }),
+    };
+}
+/**
+ * Push ctx onto the propagation stack, making it the active context.
+ * When traceparent is present and OTel API is available, extracts an OTel
+ * context so that child spans created via withTrace() inherit the parent.
+ */
+export function bindPropagationContext(ctx) {
+    const store = _ensureStore();
+    store.stack.push({ ...store.active });
+    store.active = { ...store.active, ...ctx };
+    // Wire into OTel context chain when traceparent is present.
+    if (ctx.traceparent) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const otelApi = require('@opentelemetry/api');
+            /* Stryker disable all: OTel context wiring — carrier key, extract call, catch/else sentinels are equivalent when OTel SDK behavior varies */
+            const carrier = { traceparent: ctx.traceparent };
+            if (ctx.tracestate)
+                carrier['tracestate'] = ctx.tracestate;
+            const extracted = otelApi.propagation.extract(otelApi.context.active(), carrier);
+            store.otelCtxStack.push(extracted);
+        }
+        catch {
+            store.otelCtxStack.push(undefined);
+        }
+    }
+    else {
+        store.otelCtxStack.push(undefined);
+    }
+    /* Stryker restore all */
+}
+/**
+ * Pop the last saved context, restoring the previous state.
+ */
+// Stryker disable BlockStatement
+export function clearPropagationContext() {
+    const store = _ensureStore();
+    // Stryker disable next-line ConditionalExpression,EqualityOperator
+    if (store.stack.length > 0) {
+        // Stryker enable BlockStatement
+        const restored = store.stack.pop();
+        /* v8 ignore next */
+        store.active = restored ?? {};
+    }
+    else {
+        // Stryker disable BlockStatement: empty else body is equivalent — active is always {} here because pop() restores prior state
+        store.active = {};
+    }
+    store.otelCtxStack.pop();
+}
+// Stryker enable BlockStatement
+/** Return the currently active propagation context. */
+export function getActivePropagationContext() {
+    return { ..._getStore().active };
+}
+/** Return the top of the OTel context stack, or undefined if empty/no OTel wiring. */
+export function getActiveOtelContext() {
+    const stack = _getStore().otelCtxStack;
+    // Stryker disable next-line ConditionalExpression: empty stack returns undefined; removing returns undefined from array[-1] which is also undefined
+    if (stack.length === 0)
+        return undefined;
+    return stack[stack.length - 1];
+}
+export function _resetPropagationForTests() {
+    // Recreate the ALS instance 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 */
+    _als = _AlsConstructor ? new _AlsConstructor() : null;
+    _fallbackStore = { active: {}, stack: [], otelCtxStack: [] };
+}
+/** Disable AsyncLocalStorage for testing the module-level fallback path. */
+export function _disablePropagationALSForTest() {
+    const prev = _als;
+    _als = null;
+    return prev;
+}
+/** Re-enable AsyncLocalStorage after testing (pass value from _disable call). */
+export function _restorePropagationALSForTest(saved) {
+    _als = saved;
+}

package/dist/react.d.ts

@@ -0,0 +1,38 @@
+/**
+ * React 18+ helpers for @provide-io/telemetry.
+ *
+ * Import from '@provide-io/telemetry/react'.
+ * React must be installed as a peer dependency (>=18).
+ */
+import { Component } from 'react';
+import type { ErrorInfo, ReactNode } from 'react';
+/**
+ * Bind key/value pairs into telemetry context for the lifetime of the component.
+ * Cleans up on unmount. Re-runs when values change (content-compared, not by reference).
+ */
+export declare function useTelemetryContext(values: Record<string, unknown>): void;
+interface TelemetryErrorBoundaryProps {
+    children: ReactNode;
+    fallback: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+    onError?: (error: Error, info: ErrorInfo) => void;
+}
+interface TelemetryErrorBoundaryState {
+    error: Error | null;
+}
+/**
+ * React error boundary that logs caught render errors via getLogger and renders
+ * a fallback UI. Accepts a static ReactNode or a render-prop that receives the
+ * caught error and a reset callback.
+ *
+ * Auto-logs to getLogger('react.error_boundary') on every catch. Call onError
+ * for any additional handling (alerting, Sentry, etc.).
+ */
+export declare class TelemetryErrorBoundary extends Component<TelemetryErrorBoundaryProps, TelemetryErrorBoundaryState> {
+    constructor(props: TelemetryErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): TelemetryErrorBoundaryState;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    reset(): void;
+    render(): ReactNode;
+}
+export {};
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAa,MAAM,OAAO,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAMlD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAezE;AAID,UAAU,2BAA2B;IACnC,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,SAAS,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,IAAI,KAAK,SAAS,CAAC,CAAC;IACvE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;CACnD;AAED,UAAU,2BAA2B;IACnC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,qBAAa,sBAAuB,SAAQ,SAAS,CACnD,2BAA2B,EAC3B,2BAA2B,CAC5B;gBACa,KAAK,EAAE,2BAA2B;IAM9C,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,2BAA2B;IAI1E,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI;IAUtD,KAAK,IAAI,IAAI;IAIb,MAAM,IAAI,SAAS;CAWpB"}

package/dist/react.js

@@ -0,0 +1,72 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * React 18+ helpers for @provide-io/telemetry.
+ *
+ * Import from '@provide-io/telemetry/react'.
+ * React must be installed as a peer dependency (>=18).
+ */
+import { Component, useEffect } from 'react';
+import { bindContext, unbindContext } from './context';
+import { getLogger } from './logger';
+// ── useTelemetryContext ──────────────────────────────────────────────────────
+/**
+ * Bind key/value pairs into telemetry context for the lifetime of the component.
+ * Cleans up on unmount. Re-runs when values change (content-compared, not by reference).
+ */
+export function useTelemetryContext(values) {
+    // Content-stable dep: avoids re-running when the object reference changes but values are equal.
+    // Note: key insertion order affects JSON.stringify — { b:1, a:2 } !== { a:2, b:1 }.
+    // Callers that build `values` via dynamic spread should keep key order consistent.
+    const serialized = JSON.stringify(values);
+    useEffect(() => {
+        const keys = Object.keys(values);
+        bindContext(values);
+        return () => {
+            unbindContext(...keys);
+        };
+        // `serialized` is the intentional dep — avoids re-running for referentially-new-but-equal
+        // objects. `values` is deliberately omitted; the serialized string is the stable proxy.
+    }, [serialized]);
+}
+/**
+ * React error boundary that logs caught render errors via getLogger and renders
+ * a fallback UI. Accepts a static ReactNode or a render-prop that receives the
+ * caught error and a reset callback.
+ *
+ * Auto-logs to getLogger('react.error_boundary') on every catch. Call onError
+ * for any additional handling (alerting, Sentry, etc.).
+ */
+export class TelemetryErrorBoundary extends Component {
+    constructor(props) {
+        super(props);
+        this.state = { error: null };
+        this.reset = this.reset.bind(this);
+    }
+    static getDerivedStateFromError(error) {
+        return { error };
+    }
+    componentDidCatch(error, info) {
+        getLogger('react.error_boundary').error({
+            event: 'react_error_caught',
+            error_message: error.message,
+            error_stack: error.stack ?? '',
+            component_stack: info.componentStack ?? '',
+        });
+        this.props.onError?.(error, info);
+    }
+    reset() {
+        this.setState({ error: null });
+    }
+    render() {
+        const { error } = this.state;
+        if (error !== null) {
+            const { fallback } = this.props;
+            if (typeof fallback === 'function') {
+                return fallback(error, this.reset);
+            }
+            return fallback;
+        }
+        return this.props.children;
+    }
+}

package/dist/receipts.d.ts

@@ -0,0 +1,26 @@
+/** An immutable audit record for a single PII redaction event. */
+export interface RedactionReceipt {
+    receiptId: string;
+    timestamp: string;
+    serviceName: string;
+    fieldPath: string;
+    action: string;
+    originalHash: string;
+    hmac: string;
+}
+/** Options for enabling receipt generation. */
+export interface EnableReceiptsOptions {
+    enabled: boolean;
+    signingKey?: string;
+    serviceName?: string;
+}
+/**
+ * Enable or disable receipt generation.
+ * When enabled, a hook is registered on the PII engine to capture redaction events.
+ */
+export declare function enableReceipts(options: EnableReceiptsOptions): void;
+/** Returns receipts collected during test mode. */
+export declare function getEmittedReceiptsForTests(): RedactionReceipt[];
+/** Resets all receipt state and enables test-mode collection. */
+export declare function resetReceiptsForTests(): void;
+//# sourceMappingURL=receipts.d.ts.map

package/dist/receipts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipts.d.ts","sourceRoot":"","sources":["../src/receipts.ts"],"names":[],"mappings":"AAaA,kEAAkE;AAClE,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd;AASD,+CAA+C;AAC/C,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI,CAUnE;AA+BD,mDAAmD;AACnD,wBAAgB,0BAA0B,IAAI,gBAAgB,EAAE,CAE/D;AAED,iEAAiE;AACjE,wBAAgB,qBAAqB,IAAI,IAAI,CAO5C"}

package/dist/receipts.js

@@ -0,0 +1,69 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Cryptographic redaction receipts — strippable governance module.
+ *
+ * Registers a receipt hook on the PII engine when enabled.
+ * If this file is deleted, the PII engine runs unchanged (hook stays null).
+ */
+import { createHash, createHmac, randomUUID } from 'crypto';
+import { setReceiptHook } from './pii';
+let _enabled = false;
+let _signingKey;
+let _serviceName = 'unknown';
+let _testMode = false;
+// Stryker disable next-line ArrayDeclaration
+const _testReceipts = [];
+/**
+ * Enable or disable receipt generation.
+ * When enabled, a hook is registered on the PII engine to capture redaction events.
+ */
+export function enableReceipts(options) {
+    _enabled = options.enabled;
+    _signingKey = options.signingKey;
+    _serviceName = options.serviceName ?? 'unknown';
+    if (_enabled) {
+        setReceiptHook(_onRedaction);
+    }
+    else {
+        setReceiptHook(null);
+    }
+}
+function _onRedaction(fieldPath, action, originalValue) {
+    const receiptId = randomUUID();
+    const timestamp = new Date().toISOString();
+    const originalHash = createHash('sha256').update(String(originalValue)).digest('hex');
+    let hmacValue = '';
+    if (_signingKey) {
+        const payload = `${receiptId}|${timestamp}|${fieldPath}|${action}|${originalHash}`;
+        hmacValue = createHmac('sha256', _signingKey).update(payload).digest('hex');
+    }
+    const receipt = {
+        receiptId,
+        timestamp,
+        serviceName: _serviceName,
+        fieldPath,
+        action,
+        originalHash,
+        hmac: hmacValue,
+    };
+    /* v8 ignore next 3: production-mode receipt emission — not exercised in test mode */
+    if (_testMode) {
+        _testReceipts.push(receipt);
+    }
+    // In production mode, receipts would be emitted via the logger.
+    // (No-op here when not in test mode — callers integrate with their logging pipeline.)
+}
+/** Returns receipts collected during test mode. */
+export function getEmittedReceiptsForTests() {
+    return [..._testReceipts];
+}
+/** Resets all receipt state and enables test-mode collection. */
+export function resetReceiptsForTests() {
+    _enabled = false;
+    _signingKey = undefined;
+    _serviceName = 'unknown';
+    _testMode = true;
+    _testReceipts.length = 0;
+    setReceiptHook(null);
+}

package/dist/resilience.d.ts

@@ -0,0 +1,26 @@
+export declare class TelemetryTimeoutError extends Error {
+    constructor(message: string);
+}
+export interface ExporterPolicy {
+    retries: number;
+    backoffMs: number;
+    timeoutMs: number;
+    failOpen: boolean;
+}
+export declare const CIRCUIT_BREAKER_THRESHOLD = 3;
+export declare const CIRCUIT_BASE_COOLDOWN_MS = 30000;
+export declare const _consecutiveTimeouts: Record<string, number>;
+export declare const _circuitTrippedAt: Record<string, number>;
+export declare const _openCount: Record<string, number>;
+export declare const _halfOpenProbing: Record<string, boolean>;
+export declare function setExporterPolicy(signal: string, policy: Partial<ExporterPolicy>): void;
+export declare function getExporterPolicy(signal: string): ExporterPolicy;
+export declare function runWithResilience<T>(signal: string, fn: () => Promise<T>): Promise<T | null>;
+export interface CircuitState {
+    state: string;
+    openCount: number;
+    cooldownRemainingMs: number;
+}
+export declare function getCircuitState(signal: string): CircuitState;
+export declare function _resetResilienceForTests(): void;
+//# sourceMappingURL=resilience.d.ts.map

package/dist/resilience.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resilience.d.ts","sourceRoot":"","sources":["../src/resilience.ts"],"names":[],"mappings":"AAgBA,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,OAAO,CAAC;CACnB;AASD,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAC3C,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAM/C,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAsC,CAAC;AAE/F,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAsC,CAAC;AAE5F,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAsC,CAAC;AAGrF,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAIpD,CAAC;AAGF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI,CAEvF;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAEhE;AA4BD,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACnB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAwFnB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAe5D;AAKD,wBAAgB,wBAAwB,IAAI,IAAI,CAQ/C"}