@refraction-ui/react 0.5.0 → 0.7.0

package/dist/internal/analytics/index.d.ts

@@ -0,0 +1,448 @@
+/**
+ * @refraction-ui/analytics — type contracts.
+ *
+ * The library is a neutral Segment-spec collector/router. The app instruments
+ * once via the canonical API; the router fans the canonical envelope out to
+ * N pluggable sinks. There is NO privileged engine — every vendor is a sink.
+ */
+/** Canonical Segment event types. */
+type AnalyticsEventType = 'track' | 'identify' | 'page' | 'screen' | 'group' | 'alias';
+/** Schema version stamped onto every envelope and the wire contract path. */
+declare const SCHEMA_VERSION = 1;
+/** Arbitrary, JSON-serialisable bag of values. */
+type AnalyticsProperties = Record<string, unknown>;
+/**
+ * The context block attached to every event. `library` identifies the
+ * collector; `app`/`env` identify the product instance.
+ */
+interface AnalyticsContext {
+    app: string;
+    env: string;
+    page?: {
+        path?: string;
+        url?: string;
+        referrer?: string;
+        title?: string;
+        search?: string;
+    };
+    library: {
+        name: string;
+        version: string;
+    };
+    /** Free-form additions contributed by `with(context)` children. */
+    [key: string]: unknown;
+}
+/**
+ * The canonical Segment envelope. Every sink receives events in exactly this
+ * shape; the built-in HTTP sink ships it verbatim over the wire contract.
+ */
+interface AnalyticsEvent {
+    /** Segment call type. */
+    type: AnalyticsEventType;
+    /** Event name (track/screen) or page name (page). */
+    event?: string;
+    /** Idempotency key — backends MUST dedupe on this. */
+    messageId: string;
+    /** Persistent, non-PII, resettable client id. */
+    anonymousId: string;
+    /** Opaque app-supplied id (set after identify). */
+    userId?: string;
+    /** Group id (group calls). */
+    groupId?: string;
+    /** Previous id (alias calls). */
+    previousId?: string;
+    /** Analytics session id (UUIDv4, minted at session start). */
+    sessionId: string;
+    /** track/page/screen/group payload. */
+    properties?: AnalyticsProperties;
+    /** identify/group trait payload. */
+    traits?: AnalyticsProperties;
+    /** Collector + product context. */
+    context: AnalyticsContext;
+    /** ISO-8601 client timestamp. */
+    timestamp: string;
+    /** Envelope schema version. */
+    schemaVersion: number;
+}
+/**
+ * Sink SPI — implemented by adapter packages (GA4, Azure, PostHog) and by the
+ * built-in HTTP sink. A sink declares the consent categories it requires; the
+ * router will not deliver to a sink whose categories are not all granted.
+ */
+interface AnalyticsSink {
+    /** Stable sink identifier. */
+    name: string;
+    /** Consent categories this sink requires (e.g. ['analytics']). */
+    consentCategories?: string[];
+    /** Called once before the first delivery. */
+    init?(ctx: SinkInitContext): void | Promise<void>;
+    /** Deliver a batch of canonical events. */
+    deliver(batch: AnalyticsEvent[], ctx: SinkDeliverContext): void | Promise<void>;
+    /** Flush any buffered state (best-effort). */
+    flush?(): void | Promise<void>;
+    /** Release resources on reset()/shutdown. */
+    shutdown?(): void | Promise<void>;
+}
+/** Context handed to `sink.init`. */
+interface SinkInitContext {
+    app: string;
+    env: string;
+    endpoint?: string;
+}
+/** Context handed to every `sink.deliver`. */
+interface SinkDeliverContext {
+    /** True on the unload path — sinks should prefer sendBeacon. */
+    unload: boolean;
+}
+/** Cross-tab persistence SPI. Defaults pick localStorage/cookie/memory. */
+interface AnalyticsStorage {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+/** Session engine configuration. */
+interface SessionConfig {
+    /** Inactivity timeout in ms before a new session is minted. GA4 = 30min. */
+    timeoutMs?: number;
+    /** Reset the session when a campaign/utm change is detected. */
+    resetOnCampaign?: boolean;
+    /** Persistence backend; defaults to localStorage→cookie→memory. */
+    storage?: AnalyticsStorage;
+    /** Storage key namespace. */
+    storageKey?: string;
+}
+/** Identity engine configuration. */
+interface IdentityConfig {
+    /** Persistence backend; defaults to localStorage→cookie→memory. */
+    storage?: AnalyticsStorage;
+    /** Storage key namespace. */
+    storageKey?: string;
+}
+/** Consent gate configuration. */
+interface ConsentConfig {
+    /** Categories granted at boot. */
+    granted?: string[];
+    /**
+     * If true, an event is dropped entirely when NO sink can receive it.
+     * If false (default), events are still buffered until consent is granted.
+     */
+    strict?: boolean;
+}
+/** Consent gate runtime API. */
+interface ConsentAPI {
+    grant(...categories: string[]): void;
+    revoke(...categories: string[]): void;
+    granted(): string[];
+    isGranted(category: string): boolean;
+}
+/** Session runtime API. */
+interface SessionAPI {
+    /** Current session id (mints one lazily if none active). */
+    id(): string;
+    /** Force-start a new session, returning the new id. */
+    start(): string;
+    /** End the current session. */
+    end(): void;
+    /** Attach arbitrary session-scoped properties. */
+    set(props: AnalyticsProperties): void;
+}
+/** Built-in HTTP sink options (Segment HTTP Tracking API wire contract). */
+interface HttpSinkOptions {
+    /** Base endpoint; events POST to `{endpoint}/v{schemaVersion}/batch`. */
+    endpoint: string;
+    /** Write key — sent as `Authorization: Basic base64(writeKey:)`. */
+    writeKey: string;
+    /** Max retries for 429/5xx (exponential backoff). Default 3. */
+    maxRetries?: number;
+    /** Base backoff delay in ms. Default 500. */
+    backoffBaseMs?: number;
+    /** Injected fetch (defaults to global fetch). */
+    fetchImpl?: typeof fetch;
+    /** Injected sendBeacon (defaults to navigator.sendBeacon). */
+    beaconImpl?: (url: string, body: string) => boolean;
+    /** Consent categories this sink requires. Default ['analytics']. */
+    consentCategories?: string[];
+    /** Soft per-batch byte cap (Segment ≈ 500KB). Default 500_000. */
+    maxBatchBytes?: number;
+    /** Soft per-event byte cap (Segment ≈ 32KB). Default 32_000. */
+    maxEventBytes?: number;
+}
+/** `createAnalytics` configuration. */
+interface AnalyticsConfig {
+    /** Product/app identifier (stamped into context.app). */
+    app: string;
+    /** Environment, e.g. 'development' | 'production'. Drives presets. */
+    env: string;
+    /** When set, a built-in HTTP sink is auto-registered to this endpoint. */
+    endpoint?: string;
+    /** Write key for the auto-registered HTTP sink. */
+    writeKey?: string;
+    /** Kill switch — when false, a tree-shakeable noop is returned. Default true. */
+    enabled?: boolean;
+    /** 0..1 sampling rate applied per top-level call. Default 1. */
+    sampleRate?: number;
+    /** Extra property/trait keys to redact (in addition to the PII deny-list). */
+    redactKeys?: string[];
+    /** Explicit sinks (in addition to / instead of the auto HTTP sink). */
+    sinks?: AnalyticsSink[];
+    /** Session engine config. */
+    session?: SessionConfig;
+    /** Identity engine config. */
+    identity?: IdentityConfig;
+    /** Consent gate config. */
+    consent?: ConsentConfig;
+    /**
+     * Force a preset. Defaults: env==='production' → 'prod', else 'dev'.
+     * dev = sync + console; prod = batch + sample + beacon flush on unload.
+     */
+    preset?: 'dev' | 'prod';
+    /** Batch size before an automatic flush (prod). Default 20. */
+    batchSize?: number;
+    /** Auto-flush interval in ms (prod). Default 10_000. */
+    flushIntervalMs?: number;
+}
+/** Options accepted by every top-level call. */
+interface CallOptions {
+    /** Per-call timestamp override (ISO-8601). */
+    timestamp?: string;
+    /** Per-call context overrides (shallow-merged). */
+    context?: Partial<AnalyticsContext>;
+}
+/** The public analytics surface returned by `createAnalytics`. */
+interface Analytics {
+    track(event: string, properties?: AnalyticsProperties, opts?: CallOptions): void;
+    identify(userId: string, traits?: AnalyticsProperties, opts?: CallOptions): void;
+    page(name?: string, properties?: AnalyticsProperties, opts?: CallOptions): void;
+    screen(name?: string, properties?: AnalyticsProperties, opts?: CallOptions): void;
+    group(groupId: string, traits?: AnalyticsProperties, opts?: CallOptions): void;
+    alias(userId: string, previousId?: string, opts?: CallOptions): void;
+    /** Analytics-session API (NOT replay). */
+    session: SessionAPI;
+    /** Consent gate API. */
+    consent: ConsentAPI;
+    /** Persistent, non-PII anonymous id. */
+    anonymousId(): string;
+    /** Current opaque user id (if identified). */
+    userId(): string | undefined;
+    /** Derive a child that merges extra context into every event. */
+    with(context: Partial<AnalyticsContext>): Analytics;
+    /** Register an additional sink at runtime. */
+    addSink(sink: AnalyticsSink): void;
+    /** Remove a sink by name. */
+    removeSink(name: string): void;
+    /** Registered sink names. */
+    readonly sinks: string[];
+    /** Flush all sinks (and the internal batch). */
+    flush(): Promise<void>;
+    /**
+     * Reset identity + session (privacy-safe logout). Mints a fresh
+     * anonymousId and ends the session.
+     */
+    reset(): void;
+    /** Whether this is a live collector (false for the noop). */
+    readonly enabled: boolean;
+}
+
+/**
+ * createAnalytics — the neutral Segment-spec collector/router.
+ *
+ * Mirrors `createAI`: a single factory returns the entire public surface and
+ * fans the canonical envelope out to registered sinks. There is NO privileged
+ * engine — the built-in HTTP sink and every vendor adapter are equal sinks.
+ *
+ * Presets:
+ *   dev  — synchronous delivery + a console sink (see exactly what ships).
+ *   prod — batching + sampling + beacon flush on pagehide/visibilitychange.
+ *
+ * When `enabled: false`, a tree-shakeable noop is returned and none of the
+ * live collector / sink code is reachable.
+ */
+declare function createAnalytics(config: AnalyticsConfig): Analytics;
+
+/** Create the built-in Segment-spec HTTP sink. */
+declare function createHttpSink(options: HttpSinkOptions): AnalyticsSink;
+
+interface ConsoleSinkOptions {
+    /** Injected logger (defaults to globalThis.console). */
+    logger?: Pick<Console, 'log' | 'groupCollapsed' | 'groupEnd'>;
+    /** Consent categories this sink requires. Default: none (always allowed). */
+    consentCategories?: string[];
+}
+/**
+ * Built-in `console` sink — the dev preset's default. Prints each canonical
+ * envelope so engineers can see exactly what would ship over the wire.
+ */
+declare function createConsoleSink(options?: ConsoleSinkOptions): AnalyticsSink;
+
+/** A mock sink that records every call — used for testing the router. */
+interface MockSink extends AnalyticsSink {
+    /** All events received across all deliver() calls (flattened). */
+    events: AnalyticsEvent[];
+    /** Each deliver() call's batch + context. */
+    deliveries: Array<{
+        batch: AnalyticsEvent[];
+        ctx: SinkDeliverContext;
+    }>;
+    /** init() call contexts. */
+    initCalls: SinkInitContext[];
+    /** flush() invocation count. */
+    flushCalls: number;
+    /** shutdown() invocation count. */
+    shutdownCalls: number;
+}
+interface CreateMockSinkOptions {
+    name?: string;
+    consentCategories?: string[];
+}
+/**
+ * createMockSink — an `AnalyticsSink` that captures everything for assertion.
+ * Mirrors the testing ergonomics of `@refraction-ui/ai`'s mock providers.
+ */
+declare function createMockSink(options?: CreateMockSinkOptions): MockSink;
+
+/** GA4 parity: 30 minutes of inactivity ends a session. */
+declare const DEFAULT_SESSION_TIMEOUT_MS: number;
+/**
+ * Derive a stable campaign fingerprint from a URL's query string. A change in
+ * this fingerprint (a *new* campaign, not its absence) forces a new session,
+ * matching GA4's "campaign change resets the session" behaviour.
+ */
+declare function campaignFingerprint(search?: string): string | undefined;
+/**
+ * Session engine.
+ *
+ * A session is a span of continuous activity. It ends after `timeoutMs` of
+ * inactivity (GA4 parity, default 30 min) or when a *new* campaign is
+ * detected. State is persisted cross-tab so multiple tabs share one session.
+ */
+declare function createSession(config?: SessionConfig, now?: () => number): {
+    /** Get the current session id, rotating if expired. */
+    id(campaign?: string): string;
+    /** Force a brand-new session. */
+    start(campaign?: string): string;
+    /** End the current session (next id() mints a fresh one). */
+    end(): void;
+    /** Touch activity so the inactivity window slides forward. */
+    touch(campaign?: string): string;
+    /** Attach/merge session-scoped properties. */
+    set(props: AnalyticsProperties): void;
+    /** Read session-scoped properties (undefined when none). */
+    props(): AnalyticsProperties | undefined;
+};
+
+/**
+ * Identity engine.
+ *
+ * - `anonymousId`: persistent, non-PII, resettable UUIDv4 stored cross-tab.
+ * - `userId`: opaque, app-supplied; never persisted by the library (the app
+ *   owns the user record) — kept only in memory for the active page.
+ * - `alias`: records a previous→current stitch for the wire envelope.
+ */
+declare function createIdentity(config?: IdentityConfig): {
+    anonymousId(): string;
+    userId(): string | undefined;
+    /** identify(): bind an opaque app user id (no validation, no persistence). */
+    setUserId(id: string): void;
+    /**
+     * alias(): returns the stitch pair for the envelope. `previousId`
+     * defaults to the current user or anonymous id.
+     */
+    alias(nextUserId: string, previousId?: string): {
+        userId: string;
+        previousId: string;
+    };
+    /**
+     * reset(): privacy-safe logout. Drops the user binding and mints a brand
+     * new anonymousId so the next visitor is not stitched to the old one.
+     */
+    reset(): string;
+};
+
+/**
+ * Consent gate.
+ *
+ * Holds the set of granted consent categories. The router asks the gate, per
+ * sink, whether *all* of that sink's required categories are granted before
+ * delivering. A sink with no declared categories is always allowed (it is the
+ * sink author's responsibility to declare what it needs).
+ */
+declare function createConsent(config?: ConsentConfig): ConsentAPI & {
+    /** True when every required category is granted (empty list ⇒ allowed). */
+    allows(required?: string[]): boolean;
+    /** True when at least one sink could receive (used by strict mode). */
+    strict: boolean;
+};
+
+/**
+ * PII redaction.
+ *
+ * A built-in deny-list of well-known PII key names (email/phone/name and
+ * common variants) plus any caller-supplied `redactKeys`. Matching is
+ * case-insensitive and substring-based so `userEmail`, `email_address`,
+ * `phoneNumber`, `fullName`, etc. are all caught. Redaction recurses into
+ * nested objects and arrays so PII cannot hide one level down.
+ */
+/**
+ * Built-in PII deny-list (substring, case-insensitive, separator-insensitive).
+ * These match anywhere in a key, so `userEmail`, `email_address`,
+ * `phoneNumber`, `firstName`, etc. are all caught.
+ */
+declare const PII_DENY_LIST: readonly string[];
+/**
+ * Keys that are PII only as an *exact* (normalised) match. `name` belongs
+ * here so genuine name fields redact while `username`, `eventName`,
+ * `fileName`, `firstName`-style compounds (handled by the deny-list) do not
+ * over-redact every key that merely contains "name".
+ */
+declare const PII_EXACT_KEYS: readonly string[];
+/** Replacement token written in place of a redacted value. */
+declare const REDACTED = "[REDACTED]";
+/**
+ * Build a key matcher from the deny-list + extra keys. `extra` entries match
+ * exactly (case-insensitive, normalised); deny-list entries match as
+ * substrings.
+ */
+declare function createRedactor(extraKeys?: string[]): {
+    shouldRedact: (key: string) => boolean;
+    /** Redact a properties/traits bag (returns a new object). */
+    redact(props?: AnalyticsProperties): AnalyticsProperties | undefined;
+};
+type Redactor = ReturnType<typeof createRedactor>;
+
+/**
+ * Storage adapters.
+ *
+ * Order of preference for the cross-tab default: localStorage → cookie →
+ * in-memory. The package is environment-agnostic; consumers can inject any
+ * `AnalyticsStorage` (e.g. an RN AsyncStorage shim) via config.
+ */
+/** Volatile per-process store (SSR / Node / no-DOM fallback). */
+declare function createMemoryStorage(): AnalyticsStorage;
+/** `window.localStorage` adapter (cross-tab via the storage event). */
+declare function createLocalStorageAdapter(ls: Storage): AnalyticsStorage;
+interface CookieDoc {
+    cookie: string;
+}
+/** `document.cookie` adapter (cross-tab + cross-subdomain capable). */
+declare function createCookieAdapter(doc: CookieDoc, maxAgeSeconds?: number): AnalyticsStorage;
+/**
+ * Resolve the default storage for the current environment. A caller-supplied
+ * storage always wins. Browser → localStorage (falls back to cookie if
+ * localStorage throws), otherwise in-memory.
+ */
+declare function resolveStorage(override?: AnalyticsStorage): AnalyticsStorage;
+
+/**
+ * uuidv4 — RFC 4122 version 4 UUID.
+ *
+ * Prefers `crypto.randomUUID` / `crypto.getRandomValues` when available
+ * (browser, modern Node) and degrades to `Math.random` only as a last
+ * resort. No external dependency by design (this is the neutral router).
+ */
+declare function uuidv4(): string;
+/** RFC 4122 v4 shape matcher (case-insensitive). */
+declare const UUID_V4_RE: RegExp;
+/** True when `value` is a well-formed v4 UUID. */
+declare function isUuidV4(value: unknown): value is string;
+
+export { type Analytics, type AnalyticsConfig, type AnalyticsContext, type AnalyticsEvent, type AnalyticsEventType, type AnalyticsProperties, type AnalyticsSink, type AnalyticsStorage, type CallOptions, type ConsentAPI, type ConsentConfig, type ConsoleSinkOptions, type CreateMockSinkOptions, DEFAULT_SESSION_TIMEOUT_MS, type HttpSinkOptions, type IdentityConfig, type MockSink, PII_DENY_LIST, PII_EXACT_KEYS, REDACTED, type Redactor, SCHEMA_VERSION, type SessionAPI, type SessionConfig, type SinkDeliverContext, type SinkInitContext, UUID_V4_RE, campaignFingerprint, createAnalytics, createConsent, createConsoleSink, createCookieAdapter, createHttpSink, createIdentity, createLocalStorageAdapter, createMemoryStorage, createMockSink, createRedactor, createSession, isUuidV4, resolveStorage, uuidv4 };

package/dist/internal/logger/index.d.cts

@@ -0,0 +1,229 @@
+/** Severity levels, ordered low -> high. */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/** Numeric ordering used for level threshold comparisons. */
+declare const LEVEL_ORDER: Record<LogLevel, number>;
+/** Bound key/value pairs attached to every record emitted by a logger. */
+type LogContext = Record<string, unknown>;
+/** A single structured log record handed to a sink. */
+interface LogRecord {
+    level: LogLevel;
+    message: string;
+    timestamp: number;
+    app: string;
+    env: TelemetryEnv;
+    /** Merged bound context (child loggers) + per-call context, post-redaction. */
+    context: LogContext;
+}
+/** A span record handed to a sink when a span ends. */
+interface SpanRecord {
+    name: string;
+    startTime: number;
+    endTime: number;
+    durationMs: number;
+    app: string;
+    env: TelemetryEnv;
+    /** Merged bound context + span attributes, post-redaction. */
+    context: LogContext;
+    /** 'ok' unless ended with an error. */
+    status: 'ok' | 'error';
+    error?: {
+        name: string;
+        message: string;
+    };
+}
+/**
+ * Vendor-neutral telemetry sink. Engines (console, Faro, custom) implement
+ * this — no vendor type ever leaks across this boundary.
+ */
+interface TelemetrySink {
+    /** Engine name, for diagnostics. */
+    name: string;
+    /** Receive a log record. May buffer; honor flush(). */
+    log(record: LogRecord): void;
+    /** Receive a finished span. May buffer; honor flush(). */
+    span(record: SpanRecord): void;
+    /** Force-deliver any buffered records. Resolves once delivery is attempted. */
+    flush(): Promise<void>;
+}
+/** Telemetry environment — selects a behavior preset. */
+type TelemetryEnv = 'development' | 'production';
+/** Config for {@link createTelemetry} — mirrors `createAI`'s config shape. */
+interface TelemetryConfig {
+    /** Logical app/service name attached to every record. */
+    app: string;
+    /** Environment preset selector. */
+    env: TelemetryEnv;
+    /**
+     * Remote collector endpoint. When omitted, telemetry stays console-only
+     * (no network engine is constructed).
+     */
+    endpoint?: string;
+    /**
+     * Master kill switch. When `false`, a tree-shakeable noop logger is
+     * returned and zero records are ever produced. Defaults to `true`.
+     */
+    enabled?: boolean;
+    /**
+     * Fraction of records kept, 0..1. Defaults to the preset value
+     * (1 in development, 0.25 in production). Records below the sample
+     * are dropped before reaching any sink.
+     */
+    sampleRate?: number;
+    /**
+     * Context keys to strip (deep) before a record is emitted. Use for
+     * PII / secrets, e.g. `['password', 'token', 'authorization']`.
+     */
+    redactKeys?: string[];
+}
+/** A logger bound to a context. Child loggers inherit + extend that context. */
+interface Logger {
+    debug(message: string, context?: LogContext): void;
+    info(message: string, context?: LogContext): void;
+    warn(message: string, context?: LogContext): void;
+    error(message: string, context?: LogContext): void;
+    fatal(message: string, context?: LogContext): void;
+    /**
+     * Derive a logger with additional bound context (e.g.
+     * `{ sessionId, interviewId, turnId }`). Merges over the parent's context.
+     */
+    child(context: LogContext): Logger;
+    /** Begin a span. Call {@link Span.end} to record its duration. */
+    startSpan(name: string, attributes?: LogContext): Span;
+    /** Force-deliver buffered records on every sink. */
+    flush(): Promise<void>;
+}
+/** An in-flight span returned by {@link Logger.startSpan}. */
+interface Span {
+    /** End the span and emit a {@link SpanRecord}. Optionally attach error/attrs. */
+    end(opts?: {
+        error?: unknown;
+        attributes?: LogContext;
+    }): void;
+}
+/** Return type of {@link createTelemetry}. */
+interface Telemetry extends Logger {
+    /** Registered sink names, in insertion order. */
+    readonly sinks: string[];
+    /** Register an additional sink (e.g. a custom collector). */
+    addSink(sink: TelemetrySink): void;
+    /** Remove a sink by name. */
+    removeSink(name: string): void;
+}
+
+/**
+ * Behavior derived from {@link TelemetryConfig.env}. The manager reads these
+ * fields to decide level filtering, batching, sampling, and flush triggers.
+ */
+interface TelemetryPreset {
+    /** Records strictly below this level are dropped. */
+    minLevel: LogLevel;
+    /** Buffer records and deliver in batches instead of synchronously. */
+    batch: boolean;
+    /** Batch size before an automatic flush (only when `batch`). */
+    batchSize: number;
+    /** Default sample rate when config omits `sampleRate`. */
+    sampleRate: number;
+    /** Pretty, single-line console output (vs. structured JSON). */
+    pretty: boolean;
+    /**
+     * Flush buffered records on `pagehide` + `visibilitychange` (hidden),
+     * using `navigator.sendBeacon` when available.
+     */
+    beaconFlush: boolean;
+}
+/**
+ * - development: sync, pretty, level=debug, no batching, sample everything.
+ * - production: batched + sampled, level>=warn, beacon flush on page exit.
+ */
+declare const PRESETS: Record<TelemetryEnv, TelemetryPreset>;
+/** Resolve the preset for an env (defensive copy so callers can't mutate it). */
+declare function resolvePreset(env: TelemetryEnv): TelemetryPreset;
+
+/**
+ * createTelemetry — creates a telemetry manager that fans records out to
+ * registered sinks. Manager/provider pattern, mirroring `createAI`.
+ *
+ * - `enabled: false` -> tree-shakeable noop (zero emissions, no engines).
+ * - no `endpoint` -> console-only transport.
+ * - `endpoint` set -> async Faro engine is registered when the optional
+ *   peers exist; console stays as a safe fallback until then.
+ *
+ * The returned object IS a logger (root context = `{}`); `child()` derives
+ * loggers with bound context (sessionId / interviewId / turnId / ...).
+ */
+declare function createTelemetry(config: TelemetryConfig): Telemetry;
+
+interface ConsoleSinkOptions {
+    /** Single-line pretty output (vs. structured JSON). */
+    pretty?: boolean;
+    /** Console to write to (injectable for tests). Defaults to global console. */
+    console?: Pick<Console, 'debug' | 'info' | 'warn' | 'error'>;
+}
+/**
+ * Default zero-dependency transport. Used whenever no `endpoint` is set.
+ * Synchronous; `flush()` is a resolved no-op (nothing is buffered).
+ */
+declare function createConsoleSink(opts?: ConsoleSinkOptions): TelemetrySink;
+
+/**
+ * Faro-backed engine. `@grafana/faro-web-sdk` + `@grafana/faro-web-tracing`
+ * are **optional peerDependencies** — they are loaded dynamically and never
+ * referenced in this module's public types. If the peers are absent the
+ * factory resolves to `null` so the caller can fall back to console.
+ *
+ * For tests, a `transport` may be injected: an object with a `push(payload)`
+ * method. This bypasses Faro entirely (no network, no peer required).
+ */
+/** Minimal structural shape of a Faro-ish transport. Not exported. */
+interface FaroTransport {
+    push(payload: {
+        kind: 'log' | 'span';
+        record: LogRecord | SpanRecord;
+    }): void;
+}
+interface FaroEngineOptions {
+    app: string;
+    endpoint: string;
+    /**
+     * Test/override transport. When provided, the Faro peers are NOT loaded
+     * and records are forwarded straight to `transport.push`.
+     */
+    transport?: FaroTransport;
+}
+/**
+ * Construct the Faro engine. Returns `null` when the optional peers are not
+ * installed and no override transport was supplied — callers treat `null` as
+ * "fall back to console".
+ */
+declare function createFaroSink(opts: FaroEngineOptions): Promise<TelemetrySink | null>;
+
+/**
+ * Returned by {@link createTelemetry} when `enabled: false`. Every method is
+ * an empty stub, so a bundler can dead-code-eliminate call sites and the
+ * engines (console/Faro) are never imported at runtime. Zero emissions.
+ */
+declare function createNoopTelemetry(): Telemetry;
+
+/**
+ * Deep-strip any object key whose name (case-insensitive) is in `keys`.
+ * Arrays are walked; cycles are guarded; non-matching values pass through
+ * unchanged. Returns a new structure — the input is never mutated.
+ */
+declare function redact(value: LogContext, keys: string[]): LogContext;
+
+interface MockSinkExtended extends TelemetrySink {
+    /** Every log record received, in order. */
+    logs: LogRecord[];
+    /** Every span record received, in order. */
+    spans: SpanRecord[];
+    /** Number of times {@link TelemetrySink.flush} was called. */
+    flushCalls: number;
+}
+/**
+ * createMockSink — a {@link TelemetrySink} that records everything for
+ * assertions instead of doing I/O. Used to test the manager and the Faro
+ * engine without any network. Mirrors `createMockAIProvider` in `packages/ai`.
+ */
+declare function createMockSink(name?: string): MockSinkExtended;
+
+export { type ConsoleSinkOptions, type FaroEngineOptions, LEVEL_ORDER, type LogContext, type LogLevel, type LogRecord, type Logger, type MockSinkExtended, PRESETS, type Span, type SpanRecord, type Telemetry, type TelemetryConfig, type TelemetryEnv, type TelemetryPreset, type TelemetrySink, createConsoleSink, createFaroSink, createMockSink, createNoopTelemetry, createTelemetry, redact, resolvePreset };