@scalebun/react-native 1.0.4 → 1.2.0

package/lib/module/core/config/schema.js

@@ -1,224 +1,417 @@
-import { z } 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.
-   */
-  // Thunk, not a bare string: `default()` is typed `Partial<T> | (() => T)`, and for
-  // `z.any()` T is `any`, so `Partial<any>` widens to an index signature that a string
-  // does not satisfy. The function overload does, and DefaultSchema calls it only when
-  // the input is undefined — identical at runtime, and it type-checks, which `bob build`
-  // requires to emit definitions at all.
-  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({
-    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(),
-    /** 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'
+
+// ─── Result surface (drop-in for the vendored validator's) ─────────────────────
+
+export class ConfigValidationError extends Error {
+  constructor(issues) {
+    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() {
+    const root = {
+      _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;
+        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;
+  }
+}
+
+// ─── 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.
+
+const bool = def => def === undefined ? {
+  kind: 'bool'
+} : {
+  kind: 'bool',
+  def
+};
+const num = o => ({
+  kind: 'num',
+  ...o
 });
+const SHAPE = {
+  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 => v === null ? 'null' : Array.isArray(v) ? 'array' : typeof v;
+function parseField(field, input, path, issues) {
+  const fail = message => {
+    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
+    }, {}, 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;
+        const out = {};
+        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) {
+    const issues = [];
+    const r = parseField({
+      kind: 'obj',
+      shape: SHAPE
+    }, input, [], issues);
+    if (r.ok && issues.length === 0) {
+      const data = r.value;
+      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) {
+    const r = this.safeParse(input);
+    if (!r.success) throw r.error;
+    return r.data;
+  }
+};
+
+// ─── Output type (was Infer<typeof ConfigSchema>) ──────────────────────────────
 
 // Re-export config types from contracts for consumers migrating to new import paths
 //# sourceMappingURL=schema.js.map