@scalebun/react-native 1.1.0 → 1.2.1

package/src/core/config/schema.ts

@@ -1,241 +1,359 @@
-import { z, type Infer } from '../../vendor/protocol';
+/**
+ * ScaleBun SDK — init-config validation and normalization.
+ *
+ * Hand-rolled, table-driven replacement for the vendored mini-Zod this schema used to be built
+ * on. The generic validator cost ~6.7 KB of minified bundle to serve exactly one consumer —
+ * `SDKBootstrapper.safeParse(rawConfig)` — so the machinery is replaced by a field table and a
+ * ~1.5 KB engine with BEHAVIOUR PARITY, byte-for-byte on messages:
+ *
+ *   - same accept/reject decisions (strict types, no coercion; min/max reject rather than clamp)
+ *   - same normalized output (defaults filled, nested defaults via `{}`, unknown keys stripped,
+ *     optional-and-absent keys omitted)
+ *   - same error surface (`safeParse` → `{ success, data | error }`, error with `.issues`
+ *     [{path, message}] and Zod-style `.format()`), with identical message strings
+ *
+ * The parity suite in __tests__/schemaParity.test.ts runs a generated matrix of configs against
+ * BOTH this implementation and a verbatim copy of the old vendored-z construction, and
+ * deep-compares every result. Changing behaviour here without failing that suite should be
+ * treated as impossible; if you extend the config, extend the parity suite's reference schema in
+ * the same commit.
+ *
+ * `apiBaseUrl` note: any value is accepted (`kind: 'any'`, backward compatibility) but the
+ * bootstrapper force-overwrites it with DEFAULT_API_BASE_URL immediately after parse — the
+ * endpoint is locked at build time by design.
+ */
 import { DEFAULT_TIER2_SAMPLE_RATE } from '../../features/performance/config';
 import { DEFAULT_API_BASE_URL } from '../constants/endpoints';
 
-export const ConfigSchema = z.object({
-    projectId: z.string().min(1).optional(),
-    publishableKey: z.string().min(1).optional(),
-    /**
-     * Backend API base URL. LOCKED to {@link DEFAULT_API_BASE_URL} — the ScaleBun
-     * cloud endpoint is fixed and cannot be overridden by integrators. Any value
-     * supplied here is accepted (no validation error, for backward compatibility)
-     * but ignored: the bootstrapper force-overwrites it with DEFAULT_API_BASE_URL
-     * immediately after parse. To point the SDK at a different backend, change the
-     * constant at build time.
-     */
-    // NB: `.default()` on the vendored `z` types its arg as `Partial<T> | (() => T)`, so a bare
-    // string arg fails `tsc` (.d.ts generation via bob) with TS2345. The factory form satisfies the
-    // `(() => any)` overload. Behaviour is identical — omitted apiBaseUrl resolves to the default,
-    // which the bootstrapper overwrites anyway (the endpoint is locked).
-    apiBaseUrl: z.any().default(() => DEFAULT_API_BASE_URL),
-    debug: z.boolean().default(false),
-    /**
-     * SDK internal log verbosity. Recoverable transport failures are logged at
-     * 'warn' (never console.error), so they never surface as a RedBox.
-     * Default: 'warn'. If omitted and debug=true, the bootstrapper uses 'debug'.
-     */
-    logLevel: z.enum(['silent', 'error', 'warn', 'info', 'debug']).optional(),
-    flushIntervalMs: z.number().min(1000).default(5000),
-    /**
-     * When true, end the recording session on APP_BACKGROUND and start a fresh
-     * one on next foreground (per-foreground sessions). Default false: a single
-     * session spans app-switches; the server-side reaper closes it if the app is
-     * killed in the background. Background always flushes pending data regardless.
-     */
-    finalizeOnBackground: z.boolean().default(false),
-    /**
-     * Inactivity gap (ms) at/after which timeline time is treated as "idle" and
-     * excluded from the active session duration. Sent to the backend on session
-     * start and echoed back in the session detail so the dashboard draws idle
-     * bands + computes active duration with the SAME threshold the SDK declared
-     * (no client-side guess). Default 60000 (60s).
-     */
-    idleThresholdMs: z.number().min(1000).default(60_000),
-    /**
-     * Max time (ms) the app may stay backgrounded before the analytics session is
-     * finalized on the next foreground and a fresh one is opened ("cap then
-     * reaper"). Below the cap, a background/foreground round-trip keeps ONE
-     * session (background span is flagged, not split). The server-side stale
-     * reaper is the backstop for a true process kill. Default 1800000 (30 min).
-     */
-    sessionBackgroundCapMs: z.number().min(60_000).default(30 * 60 * 1000),
-    maxQueueSize: z.number().min(1).default(1000),
-    enableNetworkMonitoring: z.boolean().default(true),
-    /**
-     * Opt-in: capture request/response headers and bodies.
-     * Default: false — must be explicitly enabled by the integrator.
-     * See ScaleBunFeatures.captureNetworkBodies for the full privacy warning.
-     */
-    captureNetworkBodies: z.boolean().default(false),
-    /**
-     * Max bytes captured per body (request or response) before truncation.
-     * Range: 1 byte – 1 MiB. Default: 65536 (64 KiB).
-     */
-    networkBodyMaxBytes: z.number().min(1).max(1_048_576).default(65_536),
-    /**
-     * Persistent queue configuration.
-     * Controls whether the event queue persists to disk and its bounds.
-     */
-    persistence: z.object({
-        /** Enable disk persistence (survives app restarts). Default: true */
-        enabled: z.boolean().default(true),
-        /** Max total bytes stored on disk. Default: 5 MB (5_242_880) */
-        maxBytes: z.number().min(1024).default(5_242_880),
-        /** Max total entries stored. Default: 5000 */
-        maxEntries: z.number().min(10).default(5_000),
-        /** Strip PII from payloads before writing to disk. Default: true */
-        redactBeforeWrite: z.boolean().default(true),
-    }).default({}),
-    clientKey: z.string().optional(),
-    /**
-     * Upload replay frame bytes to object storage via presigned PUT instead of
-     * inline base64 in the frames JSON body. Default false (legacy inline). Safe
-     * to enable before the backend is ready: the SDK auto-falls back to inline if
-     * the presign endpoint reports storage is not configured. SaaS (clientKey) only.
-     */
-    useObjectStorage: z.boolean().default(false),
-    /**
-     * Native file-based replay outbox (durable, survives app restart/process kill).
-     * When true, frames are captured natively to disk and metadata is handed to the
-     * native outbox instead of buffering base64 in the JS in-memory pendingFrames.
-     * Default false: existing in-memory JS upload path stays the only path. If the
-     * native module or a native call is unavailable, the SDK falls back to the
-     * existing JS path. SaaS (clientKey) only — uploads target /ingestion endpoints.
-     */
-    enableNativeFileOutbox: z.boolean().default(false),
-    /**
-     * Allow the NATIVE outbox to perform uploads (presign -> PUT -> commit, plus
-     * JSONL telemetry batches) on its own. Default false: even with the outbox on,
-     * native only captures+stores; JS still drives flush by calling the native
-     * flush bridge method. Set true to let native upload directly. Requires
-     * enableNativeFileOutbox.
-     */
-    nativeOutboxUploadEnabled: z.boolean().default(false),
-    /**
-     * Within the native outbox, upload frame image bytes to object storage via
-     * presigned PUT (key-only metadata commit) instead of inline base64. Default
-     * false. If the presign endpoint reports storage disabled, native falls back to
-     * the JS path for that frame (it does NOT send base64 over the bridge in the
-     * outbox path). Requires enableNativeFileOutbox.
-     */
-    useObjectStorageForFrames: z.boolean().default(false),
-    /**
-     * Native outbox tuning (all additive, all optional — native parses both the
-     * `nativeOutbox*` keys here and bare `outbox*` aliases). These only take effect
-     * when enableNativeFileOutbox is true; defaults mirror the native ReplayConfig
-     * defaults so omitting them changes nothing.
-     */
-    /** Armed-retry interval for due outbox work, ms. Default 3000. */
-    nativeOutboxRetryIntervalMs: z.number().min(250).default(3000),
-    /** Server-attempt cap before a batch is moved to dead. Default 30. */
-    nativeOutboxMaxUploadAttempts: z.number().min(1).default(30),
-    /** Poison (4xx≠429) attempt cap before dead. Default 2. */
-    nativeOutboxPoisonMaxAttempts: z.number().min(1).default(2),
-    /** Honor server Retry-After on 429/503. Default true. */
-    nativeOutboxRespectRetryAfter: z.boolean().default(true),
-    /** Force fixed 3s retry, ignoring exponential backoff. Default false. */
-    nativeOutboxStrictThreeSecondRetry: z.boolean().default(false),
-    /** Count NETWORK_UNAVAILABLE failures toward the dead threshold. Default false. */
-    nativeOutboxNetworkFailuresCountTowardDead: z.boolean().default(false),
-    /** Outbox on-disk byte cap before GC. Default 100 MiB. */
-    nativeOutboxMaxBytes: z.number().min(1024).default(100 * 1024 * 1024),
-    /** Outbox max age before GC, ms. Default 7 days. */
-    nativeOutboxMaxAgeMs: z.number().min(1000).default(7 * 24 * 60 * 60 * 1000),
-    /**
-     * Performance pipeline activation flags (SaaS).
-     * Tiered by cost. Defaults are conservative ("default-safe"): cheap
-     * event-driven Tier-1 collectors on; heavier UI-hang watchdog and Tier-2
-     * sampled collectors OFF until device-measured. All flippable via config
-     * with no SDK release.
-     */
-    performance: z.object({
-        /** Master enable; also gates native ScaleBunPerformance.initialize(). Default: true */
-        enabled: z.boolean().default(true),
-        /** Tier-1: cheap, event-driven collectors. */
-        tier1: z.object({
-            /** App launch (one-shot at start). Default: true */
-            appLaunch: z.boolean().default(true),
-            /** Screen load (per navigation). Default: true */
-            screenLoad: z.boolean().default(true),
-            /** Network perf (slow/failed requests). Default: true */
-            network: z.boolean().default(true),
-            /** UI hang / ANR watchdog. Default: true — additive, forward-only (needs native module). */
-            uiHang: z.boolean().default(true),
-        }).default({}),
-        /** Tier-2: heavy, continuous collectors (frame_metrics + js_stall), sampled. */
-        tier2: z.object({
-            /** Master enable for Tier-2. Default: true (still gated by sampleRate). */
-            enabled: z.boolean().default(true),
-            /** Per-session sampling fraction 0..1. Default: 10% — conservative, host-overridable (0 disables). */
-            sampleRate: z.number().min(0).max(1).default(DEFAULT_TIER2_SAMPLE_RATE),
-        }).default({}),
-    }).default({}),
-    /**
-     * Session-replay capture cadence for the unified SessionManager.
-     * 'navigation' (SDK default) captures only on screen change → a session with
-     * no navigation produces ~0 frames. 'frequency' captures on a timer
-     * (intervalMs, min 500ms) for a continuous replay. 'interactions' on gestures.
-     * Plumbed into SessionManager via SDKBootstrapper.
-     */
-    replay: z.object({
-        // Auto-start frame recording in SaaS mode (clientKey set) at cold launch, so replay
-        // sessions carry frames out of the box. Default: true (undefined ⇒ record). Set false for
-        // events-only sessions — the host can still record on demand via ScaleBun.startSession().
-        // Decoupled from finalizeOnBackground (which only governs per-foreground session boundaries).
-        record: z.boolean().optional(),
-        captureMode: z.enum(['navigation', 'interactions', 'frequency']).optional(),
-        intervalMs: z.number().min(500).optional(),
-        quality: z.enum(['high', 'normal', 'low', 'grayscale']).optional(),
-        // P2-5: emit deltas between keyframes (default false in DEFAULT_SESSION_REPLAY_CONFIG).
-        deltaEncoding: z.boolean().optional(),
-        deltaKeyframeInterval: z.number().int().min(1).optional(),
-    }).optional(),
-    /**
-     * Heatmap interaction capture (Feature #4).
-     *
-     * When true, tap/gesture coordinates (normalizedX/Y + gesture type + screen)
-     * are ALSO emitted to the always-on analytics lane — so heatmaps receive data
-     * even when no replay-recording session is active. This is ADDITIVE: it does
-     * NOT change replay-recording capture, and reuses the exact same USER_ACTION
-     * payload keys (normalizedX, normalizedY, gestureType, screen) the recording
-     * lane writes, so the backend aggregate reads them identically.
-     *
-     * Coordinates are NORMALIZED (0..1) and carry no PII. The analytics lane is
-     * SaaS-only (requires clientKey) and finalize-scoped per foreground; while ON
-     * a tap on every gesture is enqueued (bounded buffer, drop-oldest).
-     *
-     * Default: true (ON). Coords are normalized + PII-free, and volume is bounded
-     * by a per-foreground sampling cap in SessionManager (HEATMAP_MAX_INTERACTIONS_
-     * PER_WINDOW) so the gesture stream can't run away. Integrators who want zero
-     * extra analytics events can still set this false. SaaS (clientKey) only.
-     *
-     * CAVEAT: heatmaps populate going FORWARD only — sessions recorded before this
-     * shipped (or with the flag off) carry no analytics-lane interaction data.
-     */
-    captureInteractionHeatmap: z.boolean().default(true),
-    /**
-     * OTA (Over-the-Air) update configuration.
-     * When enabled, the SDK checks for JS bundle updates on app foreground
-     * and applies them atomically. Opt-in: existing integrators are unaffected.
-     * SaaS (clientKey) only.
-     */
-    ota: z.object({
-        /** Enable OTA update checking. Default: false (opt-in). */
-        enabled: z.boolean().default(false),
-        /** Check for updates on each app foreground. Default: true. */
-        checkOnForeground: z.boolean().default(true),
-        /** Override the auto-resolved channel (env-based). */
-        channelOverride: z.string().optional(),
-        /** Ed25519 public key for bundle signature verification (base64). */
-        publicSigningKey: z.string().optional(),
-        /**
-         * Ed25519 verifier supplied by the host — the SDK ships no crypto
-         * implementation. Required whenever `publicSigningKey` is set: pinning a
-         * key without a verifier is fail-closed, so updates stop installing.
-         * `(message, signature, publicKey) => boolean | Promise<boolean>`.
-         */
-        verifySignature: z.any().optional(),
-        /** Override how long a new bundle has to prove healthy (ms). */
-        healthyTimeoutMs: z.number().optional(),
-        /** Block UI interaction while a mandatory update is pending. Default: false. */
-        mandatoryBlocksUi: z.boolean().default(false),
-    }).optional(),
-}).refine(
-    (data) => !!data.clientKey || (!!data.projectId && !!data.publishableKey),
-    { message: 'Either clientKey (SaaS mode) or both projectId and publishableKey (legacy mode) are required' }
-);
-
-export type ScaleBunConfig = Infer<typeof ConfigSchema>;
+// ─── Result surface (drop-in for the vendored validator's) ─────────────────────
+
+export type ValidationIssue = { path: Array<string | number>; message: string };
+
+export type FormattedError = {
+    _errors: string[];
+    [key: string]: FormattedError | string[];
+};
+
+export class ConfigValidationError extends Error {
+    readonly issues: ValidationIssue[];
+
+    constructor(issues: ValidationIssue[]) {
+        super(issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; '));
+        this.name = 'ValidationError';
+        this.issues = issues;
+    }
+
+    /** Nested error object keyed by path, matching Zod's `error.format()`. */
+    format(): FormattedError {
+        const root: FormattedError = { _errors: [] };
+        for (const issue of this.issues) {
+            if (issue.path.length === 0) {
+                root._errors.push(issue.message);
+                continue;
+            }
+            let node = root;
+            for (let i = 0; i < issue.path.length; i++) {
+                const key = String(issue.path[i]);
+                const existing = node[key];
+                let child: FormattedError;
+                if (existing && !Array.isArray(existing)) {
+                    child = existing;
+                } else {
+                    child = { _errors: [] };
+                    node[key] = child;
+                }
+                if (i === issue.path.length - 1) {
+                    child._errors.push(issue.message);
+                }
+                node = child;
+            }
+        }
+        return root;
+    }
+}
+
+export type SafeParseResult<T> =
+    | { success: true; data: T }
+    | { success: false; error: ConfigValidationError };
+
+// ─── Field table ────────────────────────────────────────────────────────────────
+//
+// One row per config key. `def` present → the field always exists in the output (the default is
+// itself validated, matching DefaultSchema semantics). `opt` → absent input stays absent.
+
+type Field =
+    | { kind: 'bool'; def?: boolean; opt?: true }
+    | { kind: 'num'; min?: number; max?: number; int?: true; def?: number; opt?: true }
+    | { kind: 'str'; min?: number; opt?: true }
+    | { kind: 'enum'; values: readonly string[]; opt?: true }
+    | { kind: 'any'; def: () => unknown }
+    | { kind: 'obj'; shape: Record<string, Field>; def?: true; opt?: true };
+
+const bool = (def?: boolean): Field => (def === undefined ? { kind: 'bool' } : { kind: 'bool', def });
+const num = (o: { min?: number; max?: number; int?: true; def?: number; opt?: true }): Field => ({ kind: 'num', ...o });
+
+const SHAPE: Record<string, Field> = {
+    projectId: { kind: 'str', min: 1, opt: true },
+    publishableKey: { kind: 'str', min: 1, opt: true },
+    apiBaseUrl: { kind: 'any', def: () => DEFAULT_API_BASE_URL },
+    debug: bool(false),
+    logLevel: { kind: 'enum', values: ['silent', 'error', 'warn', 'info', 'debug'], opt: true },
+    flushIntervalMs: num({ min: 1000, def: 5000 }),
+    finalizeOnBackground: bool(false),
+    idleThresholdMs: num({ min: 1000, def: 60_000 }),
+    sessionBackgroundCapMs: num({ min: 60_000, def: 30 * 60 * 1000 }),
+    maxQueueSize: num({ min: 1, def: 1000 }),
+    enableNetworkMonitoring: bool(true),
+    captureNetworkBodies: bool(false),
+    networkBodyMaxBytes: num({ min: 1, max: 1_048_576, def: 65_536 }),
+    persistence: {
+        kind: 'obj',
+        def: true,
+        shape: {
+            enabled: bool(true),
+            maxBytes: num({ min: 1024, def: 5_242_880 }),
+            maxEntries: num({ min: 10, def: 5_000 }),
+            redactBeforeWrite: bool(true),
+        },
+    },
+    clientKey: { kind: 'str', opt: true },
+    useObjectStorage: bool(false),
+    enableNativeFileOutbox: bool(false),
+    nativeOutboxUploadEnabled: bool(false),
+    useObjectStorageForFrames: bool(false),
+    nativeOutboxRetryIntervalMs: num({ min: 250, def: 3000 }),
+    nativeOutboxMaxUploadAttempts: num({ min: 1, def: 30 }),
+    nativeOutboxPoisonMaxAttempts: num({ min: 1, def: 2 }),
+    nativeOutboxRespectRetryAfter: bool(true),
+    nativeOutboxStrictThreeSecondRetry: bool(false),
+    nativeOutboxNetworkFailuresCountTowardDead: bool(false),
+    nativeOutboxMaxBytes: num({ min: 1024, def: 100 * 1024 * 1024 }),
+    nativeOutboxMaxAgeMs: num({ min: 1000, def: 7 * 24 * 60 * 60 * 1000 }),
+    performance: {
+        kind: 'obj',
+        def: true,
+        shape: {
+            enabled: bool(true),
+            tier1: {
+                kind: 'obj',
+                def: true,
+                shape: {
+                    appLaunch: bool(true),
+                    screenLoad: bool(true),
+                    network: bool(true),
+                    uiHang: bool(true),
+                },
+            },
+            tier2: {
+                kind: 'obj',
+                def: true,
+                shape: {
+                    enabled: bool(true),
+                    sampleRate: num({ min: 0, max: 1, def: DEFAULT_TIER2_SAMPLE_RATE }),
+                },
+            },
+        },
+    },
+    replay: {
+        kind: 'obj',
+        opt: true,
+        shape: {
+            // Auto-start frame recording in SaaS mode (clientKey set) at cold launch, so replay
+            // sessions carry frames out of the box. Default: true (undefined ⇒ record). Set false
+            // for events-only sessions — the host can still record via ScaleBun.startSession().
+            record: { kind: 'bool', opt: true },
+            captureMode: { kind: 'enum', values: ['navigation', 'interactions', 'frequency'], opt: true },
+            intervalMs: num({ min: 500, opt: true }),
+            quality: { kind: 'enum', values: ['high', 'normal', 'low', 'grayscale'], opt: true },
+            deltaEncoding: { kind: 'bool', opt: true },
+            deltaKeyframeInterval: num({ min: 1, int: true, opt: true }),
+        },
+    },
+    captureInteractionHeatmap: bool(true),
+    ota: {
+        kind: 'obj',
+        opt: true,
+        shape: {
+            enabled: bool(false),
+            checkOnForeground: bool(true),
+            channelOverride: { kind: 'str', opt: true },
+            publicSigningKey: { kind: 'str', opt: true },
+            mandatoryBlocksUi: bool(false),
+        },
+    },
+};
+
+// ─── Engine ─────────────────────────────────────────────────────────────────────
+
+const typeofName = (v: unknown): string =>
+    v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v;
+
+function parseField(
+    field: Field,
+    input: unknown,
+    path: Array<string | number>,
+    issues: ValidationIssue[],
+): { ok: boolean; value?: unknown; present: boolean } {
+    const fail = (message: string) => {
+        issues.push({ path, message });
+        return { ok: false, present: true };
+    };
+
+    if (input === undefined) {
+        if ('opt' in field && field.opt) return { ok: true, present: false };
+        if (field.kind === 'any') return { ok: true, value: field.def(), present: true };
+        if (field.kind === 'obj' && field.def) return parseField({ ...field, def: undefined } as Field, {}, path, issues);
+        if ('def' in field && field.def !== undefined) return { ok: true, value: field.def, present: true };
+        // Required with no default (matches the base schemas' type errors on undefined).
+        return fail(
+            field.kind === 'bool'
+                ? 'Expected boolean, received undefined'
+                : field.kind === 'num'
+                  ? 'Expected number, received undefined'
+                  : field.kind === 'str'
+                    ? 'Expected string, received undefined'
+                    : field.kind === 'enum'
+                      ? "Invalid enum value. Expected " + field.values.map((v) => `'${v}'`).join(' | ')
+                      : 'Expected object, received undefined',
+        );
+    }
+
+    switch (field.kind) {
+        case 'any':
+            return { ok: true, value: input, present: true };
+        case 'bool':
+            if (typeof input !== 'boolean') return fail(`Expected boolean, received ${typeofName(input)}`);
+            return { ok: true, value: input, present: true };
+        case 'str':
+            if (typeof input !== 'string') return fail(`Expected string, received ${typeofName(input)}`);
+            if (field.min !== undefined && input.length < field.min) {
+                return fail(`String must contain at least ${field.min} character(s)`);
+            }
+            return { ok: true, value: input, present: true };
+        case 'num':
+            if (typeof input !== 'number' || Number.isNaN(input)) {
+                return fail(`Expected number, received ${typeofName(input)}`);
+            }
+            if (field.int && !Number.isInteger(input)) return fail('Expected integer, received float');
+            if (field.min !== undefined && input < field.min) {
+                return fail(`Number must be greater than or equal to ${field.min}`);
+            }
+            if (field.max !== undefined && input > field.max) {
+                return fail(`Number must be less than or equal to ${field.max}`);
+            }
+            return { ok: true, value: input, present: true };
+        case 'enum':
+            if (typeof input !== 'string' || !field.values.includes(input)) {
+                return fail(`Invalid enum value. Expected ${field.values.map((v) => `'${v}'`).join(' | ')}`);
+            }
+            return { ok: true, value: input, present: true };
+        case 'obj': {
+            if (typeofName(input) !== 'object') return fail(`Expected object, received ${typeofName(input)}`);
+            const src = input as Record<string, unknown>;
+            const out: Record<string, unknown> = {};
+            let ok = true;
+            for (const key of Object.keys(field.shape)) {
+                const r = parseField(field.shape[key]!, src[key], [...path, key], issues);
+                if (!r.ok) ok = false;
+                // Mirrors ObjectSchema: keep defined results, and explicit `key in input`
+                // occurrences even when the parsed value is undefined (optional present-but-
+                // undefined keys survive as own properties, exactly like the old parser).
+                else if (r.value !== undefined || key in src) {
+                    if (r.present || key in src) out[key] = r.value;
+                }
+            }
+            // Unknown keys are stripped (Zod's default `.strip()` behaviour).
+            return ok ? { ok: true, value: out, present: true } : { ok: false, present: true };
+        }
+    }
+}
+
+/** The one root-level cross-field rule (was `.refine(...)` on the old schema). */
+const ROOT_REFINE_MESSAGE =
+    'Either clientKey (SaaS mode) or both projectId and publishableKey (legacy mode) are required';
+
+export const ConfigSchema = {
+    safeParse(input: unknown): SafeParseResult<ScaleBunConfig> {
+        const issues: ValidationIssue[] = [];
+        const r = parseField({ kind: 'obj', shape: SHAPE }, input, [], issues);
+        if (r.ok && issues.length === 0) {
+            const data = r.value as ScaleBunConfig;
+            if (!(!!data.clientKey || (!!data.projectId && !!data.publishableKey))) {
+                issues.push({ path: [], message: ROOT_REFINE_MESSAGE });
+                return { success: false, error: new ConfigValidationError(issues) };
+            }
+            return { success: true, data };
+        }
+        return { success: false, error: new ConfigValidationError(issues) };
+    },
+
+    parse(input: unknown): ScaleBunConfig {
+        const r = this.safeParse(input);
+        if (!r.success) throw r.error;
+        return r.data;
+    },
+};
+
+// ─── Output type (was Infer<typeof ConfigSchema>) ──────────────────────────────
+
+export interface ScaleBunConfig {
+    projectId?: string;
+    publishableKey?: string;
+    // `any`, not `unknown`: the old schema's z.any() inferred `any`, and the bootstrapper/facade
+    // assign and pass it as a string after force-locking it to DEFAULT_API_BASE_URL.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    apiBaseUrl: any;
+    debug: boolean;
+    logLevel?: 'silent' | 'error' | 'warn' | 'info' | 'debug';
+    flushIntervalMs: number;
+    finalizeOnBackground: boolean;
+    idleThresholdMs: number;
+    sessionBackgroundCapMs: number;
+    maxQueueSize: number;
+    enableNetworkMonitoring: boolean;
+    captureNetworkBodies: boolean;
+    networkBodyMaxBytes: number;
+    persistence: {
+        enabled: boolean;
+        maxBytes: number;
+        maxEntries: number;
+        redactBeforeWrite: boolean;
+    };
+    clientKey?: string;
+    useObjectStorage: boolean;
+    enableNativeFileOutbox: boolean;
+    nativeOutboxUploadEnabled: boolean;
+    useObjectStorageForFrames: boolean;
+    nativeOutboxRetryIntervalMs: number;
+    nativeOutboxMaxUploadAttempts: number;
+    nativeOutboxPoisonMaxAttempts: number;
+    nativeOutboxRespectRetryAfter: boolean;
+    nativeOutboxStrictThreeSecondRetry: boolean;
+    nativeOutboxNetworkFailuresCountTowardDead: boolean;
+    nativeOutboxMaxBytes: number;
+    nativeOutboxMaxAgeMs: number;
+    performance: {
+        enabled: boolean;
+        tier1: { appLaunch: boolean; screenLoad: boolean; network: boolean; uiHang: boolean };
+        tier2: { enabled: boolean; sampleRate: number };
+    };
+    replay?: {
+        record?: boolean;
+        captureMode?: 'navigation' | 'interactions' | 'frequency';
+        intervalMs?: number;
+        quality?: 'high' | 'normal' | 'low' | 'grayscale';
+        deltaEncoding?: boolean;
+        deltaKeyframeInterval?: number;
+    };
+    captureInteractionHeatmap: boolean;
+    ota?: {
+        enabled: boolean;
+        checkOnForeground: boolean;
+        channelOverride?: string;
+        publicSigningKey?: string;
+        mandatoryBlocksUi: boolean;
+    };
+}
 
 // Re-export config types from contracts for consumers migrating to new import paths
 export type {