@scalebun-release/react-native 2.5.0

package/lib/module/pipeline/queue/flushQueue.js

@@ -0,0 +1,102 @@
+import { logger } from '../../core/logger/internalLogger';
+import { describeErrorReason, isRecoverableFlushError } from '../../core/logger/errorClassification';
+import { getDelayWithJitter } from '../../transport/backoff/exponentialJitter';
+import { ENDPOINTS } from '../../transport/http/endpoints';
+
+/** Outcome of a flush attempt — lets callers schedule retries / report status. */
+
+/**
+ * Guards against overlapping flushes for the same queue. The scheduler interval
+ * and a manual `flush()` can fire concurrently; running both would let two
+ * attempts return batches to the queue independently and churn ordering.
+ */
+const inFlight = new WeakSet();
+
+/** Per-queue count of consecutive recoverable failures, for backoff. */
+const failureStreak = new WeakMap();
+export async function flushQueue(queue, httpClient, deviceId, headers) {
+  if (inFlight.has(queue)) {
+    __DEV__ && logger.debug('[Flush] Skipped — a flush is already in progress');
+    return {
+      status: 'skipped',
+      batchSize: 0
+    };
+  }
+  const batch = queue.popBatch(50);
+  if (batch.length === 0) {
+    return {
+      status: 'empty',
+      batchSize: 0
+    };
+  }
+  inFlight.add(queue);
+  try {
+    const res = await httpClient.post(ENDPOINTS.EVENTS, {
+      deviceId,
+      events: batch
+    }, headers);
+
+    // Treat transient backend states (5xx / 429) as recoverable.
+    if (res.status >= 500 || res.status === 429) {
+      return handleRecoverable(queue, batch, undefined, res.status);
+    }
+
+    // Client errors (bad clientKey, bad payload) won't fix on retry — do NOT
+    // requeue (avoids an infinite loop) but surface clearly and actionably.
+    if (res.status >= 400) {
+      failureStreak.delete(queue);
+      const hint = res.status === 404 ? '- 404 = route not found at this URL (routing/base-URL or wrong lane), NOT auth\n' + '- apiBaseUrl points at the correct environment + path prefix\n' : res.status === 401 || res.status === 403 ? '- clientKey is valid and active (auth rejected)\n' : '- payload shape is accepted by this endpoint\n';
+      logger.error('Events rejected by the ingestion endpoint — not retrying this batch.\n' + `HTTP ${res.status}. Check:\n` + hint + `Endpoint: ${ENDPOINTS.EVENTS}`);
+      return {
+        status: 'fatal',
+        batchSize: batch.length
+      };
+    }
+    failureStreak.delete(queue);
+    __DEV__ && logger.info(`Successfully flushed ${batch.length} events`);
+    return {
+      status: 'flushed',
+      batchSize: batch.length
+    };
+  } catch (err) {
+    if (isRecoverableFlushError(err)) {
+      return handleRecoverable(queue, batch, err);
+    }
+    return handleFatal(queue, batch, err);
+  } finally {
+    inFlight.delete(queue);
+  }
+}
+function handleRecoverable(queue, batch, err, status) {
+  // Return events to the FRONT of the queue, preserving order. No double send,
+  // no double redaction — requeueBatch re-inserts the exact popped envelopes.
+  queue.requeueBatch(batch);
+
+  // Clamp the streak: the backoff delay already saturates at its 30s cap well before
+  // this (2^5·1000 > 30000), so a higher count only risks unbounded integer growth.
+  // The batch is never dropped (no-data-loss contract) — only the retry cadence is bounded.
+  const attempt = Math.min((failureStreak.get(queue) ?? 0) + 1, 16);
+  failureStreak.set(queue, attempt);
+  const nextRetryMs = Math.round(getDelayWithJitter(attempt - 1));
+  const reason = describeErrorReason(err, status);
+
+  // Recoverable failures are routine — never use console.error (would RedBox).
+  logger.warn('Flush aborted; events returned to queue. Retrying later.\n' + `Reason: ${reason}\n` + `Endpoint: ${ENDPOINTS.EVENTS}\n` + `Queue size: ${queue.length()}\n` + `Retry attempt: ${attempt}\n` + `Next retry: ~${nextRetryMs}ms`);
+  return {
+    status: 'recoverable',
+    batchSize: batch.length,
+    nextRetryMs
+  };
+}
+function handleFatal(queue, batch, err) {
+  // Even fatal errors keep the events — never silently drop user data.
+  queue.requeueBatch(batch);
+
+  // Genuinely unexpected / actionable: surface clearly for the host developer.
+  logger.error('Events could not be flushed due to an unexpected error.\n' + 'Check:\n' + '- clientKey\n' + '- apiBaseUrl\n' + '- backend server status\n' + '- CORS / SSL / local dev proxy\n' + `Endpoint: ${ENDPOINTS.EVENTS}`, err);
+  return {
+    status: 'fatal',
+    batchSize: batch.length
+  };
+}
+//# sourceMappingURL=flushQueue.js.map

package/lib/module/pipeline/queue/memoryQueue.js

@@ -0,0 +1,24 @@
+export class MemoryQueue {
+  items = [];
+  maxItems = 1000;
+  constructor(maxItems = 1000) {
+    this.maxItems = maxItems;
+  }
+  add(envelope) {
+    if (this.items.length >= this.maxItems) {
+      this.items.shift(); // Drop oldest
+    }
+    this.items.push(envelope);
+  }
+  popBatch(limit = 50) {
+    return this.items.splice(0, limit);
+  }
+  clear() {
+    this.items = [];
+  }
+  get length() {
+    return this.items.length;
+  }
+}
+export const memoryQueue = new MemoryQueue();
+//# sourceMappingURL=memoryQueue.js.map

package/lib/module/pipeline/queue/persistentQueue.js

@@ -0,0 +1,336 @@
+/**
+ * ScaleBun SDK — Disk-Backed Persistent Queue
+ *
+ * Persists event envelopes to a StorageBackend so they survive
+ * app restarts, crashes, and force-kills.
+ *
+ * STORAGE LAYOUT (chunked keys):
+ *   scalebun_q:meta        → { head, tail, count, totalBytes }
+ *   scalebun_q:e:{seq}     → JSON-serialized envelope
+ *
+ * Each envelope gets its own key. This makes add() O(1) and
+ * popBatch() O(batch_size) instead of the old O(queue_size)
+ * approach of serializing the entire array on every write.
+ *
+ * FEATURES:
+ * - Configurable bounds: maxBytes (default 5 MB), maxEntries (default 5000)
+ * - Redaction before write: strips PII from payloads before disk persistence
+ * - Leftover drain: on init, returns envelopes from previous run before
+ *   accepting new ones — ensures crash-time events are not lost
+ * - FIFO ordering: popBatch() returns envelopes in insertion order
+ *
+ * STORAGE: persists through the SDK's first-party `StorageBackend` (durable
+ * native file store by default; in-memory only as an emergency fallback). No
+ * third-party storage dependency is required.
+ */
+
+import { logger } from '../../core/logger/internalLogger';
+import { redactBody } from '../../debug/redaction';
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+const META_KEY = 'scalebun_q:meta';
+const ENTRY_PREFIX = 'scalebun_q:e:';
+
+// ─── Config ─────────────────────────────────────────────────────────────────
+
+export const DEFAULT_PERSISTENCE_CONFIG = {
+  enabled: true,
+  maxBytes: 5_242_880,
+  // 5 MB
+  maxEntries: 5_000,
+  redactBeforeWrite: true
+};
+
+// ─── Queue Metadata ─────────────────────────────────────────────────────────
+
+const EMPTY_META = {
+  head: 0,
+  tail: 0,
+  count: 0,
+  totalBytes: 0
+};
+
+// ─── PersistentQueue ────────────────────────────────────────────────────────
+
+export class PersistentQueue {
+  /**
+   * Create a PersistentQueue backed by the given storage.
+   *
+   * @param backend - Storage backend (MemoryBackend for tests, native durable backend for prod)
+   * @param config  - Persistence configuration (bounds, redaction)
+   */
+  constructor(backend, config = {}) {
+    this.backend = backend;
+    this.config = {
+      ...DEFAULT_PERSISTENCE_CONFIG,
+      ...config
+    };
+    this.meta = this._loadMeta();
+    __DEV__ && logger.debug(`[PersistentQueue] Initialized: count=${this.meta.count}, ` + `bytes=${this.meta.totalBytes}, head=${this.meta.head}, tail=${this.meta.tail}`);
+  }
+
+  // ─── Public API ─────────────────────────────────────────────────────
+
+  /**
+   * Add an envelope to the queue.
+   *
+   * If redactBeforeWrite is enabled, the envelope payload is redacted
+   * before serialization. If bounds are exceeded, the oldest entries
+   * are evicted.
+   */
+  add(envelope) {
+    try {
+      const toStore = this.config.redactBeforeWrite ? this._redactEnvelope(envelope) : envelope;
+      const serialized = JSON.stringify(toStore);
+      const byteSize = serialized.length; // Approximate: 1 char ≈ 1 byte for ASCII/JSON
+
+      // Evict oldest entries if we'd exceed caps
+      this._evictIfNeeded(byteSize);
+      const key = ENTRY_PREFIX + this.meta.tail;
+      this.backend.set(key, serialized);
+      this.meta.tail++;
+      this.meta.count++;
+      this.meta.totalBytes += byteSize;
+      this._saveMeta();
+    } catch (e) {
+      logger.error('[PersistentQueue] Failed to add envelope:', e);
+    }
+  }
+
+  /**
+   * Pop a batch of envelopes in FIFO order.
+   *
+   * @param limit - Max number of envelopes to return (default 50)
+   * @returns Array of deserialized envelopes
+   */
+  popBatch(limit = 50) {
+    const batch = [];
+    try {
+      const count = Math.min(limit, this.meta.count);
+      for (let i = 0; i < count; i++) {
+        const seq = this.meta.head + i;
+        const key = ENTRY_PREFIX + seq;
+        const raw = this.backend.get(key);
+        if (raw) {
+          try {
+            batch.push(JSON.parse(raw));
+          } catch {
+            logger.warn(`[PersistentQueue] Corrupt entry at seq=${seq}, skipping`);
+          }
+          this.backend.delete(key);
+          this.meta.totalBytes -= raw.length;
+        } else {
+          // Gap — entry was already evicted or corrupted
+          __DEV__ && logger.debug(`[PersistentQueue] Missing entry at seq=${seq}`);
+        }
+      }
+      this.meta.head += count;
+      this.meta.count -= count;
+      if (this.meta.totalBytes < 0) this.meta.totalBytes = 0;
+
+      // Reset counters when empty to prevent unbounded seq growth
+      if (this.meta.count === 0) {
+        this.meta.head = 0;
+        this.meta.tail = 0;
+        this.meta.totalBytes = 0;
+      }
+      this._saveMeta();
+    } catch (e) {
+      logger.error('[PersistentQueue] Failed to pop batch:', e);
+    }
+    return batch;
+  }
+
+  /**
+   * Return a previously-popped batch to the FRONT of the queue, preserving
+   * the batch's original FIFO order relative to the rest of the queue.
+   *
+   * Used when a flush fails with a recoverable error: the events must go back
+   * exactly where they were (oldest-first) rather than being appended to the
+   * tail behind newer events. These envelopes were already redacted on their
+   * first `add()`, so redaction is intentionally NOT re-applied here (avoids
+   * double-masking and wasted work).
+   */
+  requeueBatch(batch) {
+    if (batch.length === 0) return;
+    try {
+      // Insert in reverse so batch[0] ends up at the smallest head index.
+      for (let i = batch.length - 1; i >= 0; i--) {
+        const serialized = JSON.stringify(batch[i]);
+        this.meta.head--;
+        const key = ENTRY_PREFIX + this.meta.head;
+        this.backend.set(key, serialized);
+        this.meta.count++;
+        this.meta.totalBytes += serialized.length;
+      }
+      this._saveMeta();
+    } catch (e) {
+      logger.warn('[PersistentQueue] Failed to requeue batch:', e);
+    }
+  }
+
+  /**
+   * Current queue length (number of envelopes).
+   */
+  length() {
+    return this.meta.count;
+  }
+
+  /**
+   * Current approximate total bytes stored.
+   */
+  totalBytes() {
+    return this.meta.totalBytes;
+  }
+
+  /**
+   * Drain all leftover envelopes from a previous app run.
+   *
+   * Call this during SDK init, BEFORE accepting new events.
+   * Returns all stored envelopes and clears the queue.
+   * If no leftovers exist, returns an empty array.
+   */
+  drainLeftovers() {
+    if (this.meta.count === 0) return [];
+    __DEV__ && logger.info(`[PersistentQueue] Draining ${this.meta.count} leftover envelopes ` + `from previous run (${this.meta.totalBytes} bytes)`);
+
+    // Pop everything
+    return this.popBatch(this.meta.count);
+  }
+
+  /**
+   * Clear all entries and reset metadata.
+   */
+  clear() {
+    try {
+      // Delete all entry keys
+      for (let seq = this.meta.head; seq < this.meta.tail; seq++) {
+        this.backend.delete(ENTRY_PREFIX + seq);
+      }
+      this.meta = {
+        ...EMPTY_META
+      };
+      this._saveMeta();
+    } catch (e) {
+      logger.error('[PersistentQueue] Failed to clear:', e);
+    }
+  }
+
+  // ─── Internal ───────────────────────────────────────────────────────
+
+  /**
+   * Load queue metadata from storage.
+   * If no metadata exists, scans for orphan entry keys (recovery mode).
+   */
+  _loadMeta() {
+    try {
+      const raw = this.backend.get(META_KEY);
+      if (raw) {
+        const parsed = JSON.parse(raw);
+        // Validate loaded meta
+        if (typeof parsed.head === 'number' && typeof parsed.tail === 'number' && typeof parsed.count === 'number' && typeof parsed.totalBytes === 'number' && parsed.head >= 0 && parsed.tail >= parsed.head && parsed.count >= 0) {
+          return parsed;
+        }
+        logger.warn('[PersistentQueue] Invalid metadata, recovering...');
+      }
+
+      // Recovery: scan for orphan keys
+      return this._recoverMeta();
+    } catch (e) {
+      logger.error('[PersistentQueue] Failed to load metadata:', e);
+      return {
+        ...EMPTY_META
+      };
+    }
+  }
+
+  /**
+   * Recovery mode: scan getAllKeys() for `scalebun_q:e:*` entries
+   * and reconstruct metadata from what's actually stored.
+   */
+  _recoverMeta() {
+    try {
+      const allKeys = this.backend.getAllKeys();
+      const entryKeys = allKeys.filter(k => k.startsWith(ENTRY_PREFIX)).map(k => parseInt(k.substring(ENTRY_PREFIX.length), 10)).filter(n => !isNaN(n)).sort((a, b) => a - b);
+      if (entryKeys.length === 0) return {
+        ...EMPTY_META
+      };
+      let totalBytes = 0;
+      for (const seq of entryKeys) {
+        const raw = this.backend.get(ENTRY_PREFIX + seq);
+        if (raw) totalBytes += raw.length;
+      }
+      const meta = {
+        head: entryKeys[0],
+        tail: entryKeys[entryKeys.length - 1] + 1,
+        count: entryKeys.length,
+        totalBytes
+      };
+      __DEV__ && logger.info(`[PersistentQueue] Recovered metadata: ${meta.count} entries, ` + `head=${meta.head}, tail=${meta.tail}, bytes=${meta.totalBytes}`);
+      this.backend.set(META_KEY, JSON.stringify(meta));
+      return meta;
+    } catch {
+      return {
+        ...EMPTY_META
+      };
+    }
+  }
+
+  /** Save queue metadata to storage. */
+  _saveMeta() {
+    try {
+      this.backend.set(META_KEY, JSON.stringify(this.meta));
+    } catch (e) {
+      logger.error('[PersistentQueue] Failed to save metadata:', e);
+    }
+  }
+
+  /**
+   * Evict oldest entries if adding `newBytes` would exceed caps.
+   */
+  _evictIfNeeded(newBytes) {
+    // Evict for entry count cap
+    while (this.meta.count >= this.config.maxEntries && this.meta.head < this.meta.tail) {
+      this._evictOldest();
+    }
+
+    // Evict for byte cap
+    while (this.meta.totalBytes + newBytes > this.config.maxBytes && this.meta.count > 0 && this.meta.head < this.meta.tail) {
+      this._evictOldest();
+    }
+  }
+
+  /** Evict the oldest entry. */
+  _evictOldest() {
+    const key = ENTRY_PREFIX + this.meta.head;
+    const raw = this.backend.get(key);
+    if (raw) {
+      this.meta.totalBytes -= raw.length;
+    }
+    this.backend.delete(key);
+    this.meta.head++;
+    this.meta.count--;
+    if (this.meta.totalBytes < 0) this.meta.totalBytes = 0;
+  }
+
+  /**
+   * Apply redaction to an envelope before disk write.
+   * Returns a new envelope — never mutates the original.
+   */
+  _redactEnvelope(envelope) {
+    try {
+      return {
+        ...envelope,
+        payload: redactBody(envelope.payload)
+      };
+    } catch {
+      // If redaction fails, store as-is rather than dropping
+      return envelope;
+    }
+  }
+}
+
+// (A createPersistentQueue factory used to live here; every construction site builds
+// PersistentQueue directly with an explicit backend, so the factory was verified dead and removed.)
+//# sourceMappingURL=persistentQueue.js.map

package/lib/module/pipeline/queue/queuePolicy.js

@@ -0,0 +1,2 @@
+
+//# sourceMappingURL=queuePolicy.js.map

package/lib/module/pipeline/scheduler/flushScheduler.js

@@ -0,0 +1,38 @@
+import { logger } from '../../core/logger/internalLogger';
+import { describeErrorReason, isRecoverableFlushError } from '../../core/logger/errorClassification';
+export class FlushScheduler {
+  running = false;
+  constructor(onFlush) {
+    this.onFlush = onFlush;
+  }
+  start(intervalMs) {
+    this.stop();
+    this.timer = setInterval(() => {
+      // Skip if the previous tick's flush hasn't settled — avoids
+      // overlapping flushes piling up when the network is slow.
+      if (this.running) {
+        __DEV__ && logger.debug('[FlushScheduler] Previous flush still running — skipping tick');
+        return;
+      }
+      this.running = true;
+      this.onFlush().catch(err => {
+        // Recoverable transport failures are routine — keep them out
+        // of console.error so they never trigger a RedBox overlay.
+        if (isRecoverableFlushError(err)) {
+          logger.warn(`[FlushScheduler] Scheduled flush deferred (reason: ${describeErrorReason(err)}).`);
+        } else {
+          logger.error('[FlushScheduler] Scheduled flush error:', err);
+        }
+      }).finally(() => {
+        this.running = false;
+      });
+    }, intervalMs);
+  }
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+  }
+}
+//# sourceMappingURL=flushScheduler.js.map

package/lib/module/pipeline/scheduler/retryPolicy.js

@@ -0,0 +1,9 @@
+/**
+ * Returns a delay in ms for the next retry attempt using exponential backoff with jitter.
+ */
+export function getExponentialBackoff(attempt, baseDelay = 1000) {
+  const delay = baseDelay * Math.pow(2, attempt);
+  const jitter = delay * 0.2 * Math.random();
+  return delay + jitter;
+}
+//# sourceMappingURL=retryPolicy.js.map

package/lib/module/public/ScaleBunErrorBoundary.js

@@ -0,0 +1,82 @@
+/**
+ * ScaleBunErrorBoundary — React render errors, forwarded to the SDK.
+ *
+ * THE GAP THIS CLOSES
+ * `ErrorUtils.setGlobalHandler` catches a render error only when NO boundary intercepts it first.
+ * The moment a host wraps its tree in its own boundary — which most production apps do — that
+ * boundary's `componentDidCatch` consumes the error, it never reaches `ErrorUtils`, and the SDK
+ * recorded nothing at all. The screen went blank or fell back, and the crash list stayed empty.
+ *
+ * The web SDK has shipped `ScaleBunErrorBoundary` from `@scalebun/web-react` for exactly this reason;
+ * React Native had no equivalent and no `componentDidCatch` hook a host could forward through. This
+ * is the counterpart, and the two are deliberately the same component with the same prop names so a
+ * team working across both platforms writes the same thing twice.
+ *
+ * Use it INSTEAD of your own boundary, or nest it inside one — `onError` runs after capture so an
+ * existing boundary's logging keeps working.
+ *
+ * ```tsx
+ * <ScaleBunErrorBoundary fallback={(e) => <Text>Something broke: {e.message}</Text>}>
+ *   <App />
+ * </ScaleBunErrorBoundary>
+ * ```
+ */
+import { Component } from 'react';
+import ScaleBun from './ScaleBunFacade';
+export class ScaleBunErrorBoundary extends Component {
+  state = {
+    error: null
+  };
+  static getDerivedStateFromError(error) {
+    return {
+      error
+    };
+  }
+  componentDidCatch(error, info) {
+    try {
+      /**
+       * NOT fatal, matching the web boundary.
+       *
+       * The app is still running — that is the entire point of a boundary — so this is reported
+       * as a handled error rather than a crash. Marking it fatal would put an event the user
+       * experienced as a fallback screen into the same bucket as an app that actually died, and
+       * the crash rate is a number people act on.
+       *
+       * `componentStack` travels in `metadata` because that is the shape RN's `captureError`
+       * takes; the web SDK accepts it as a top-level context key. Same information, and the
+       * difference is in the two facades, not here.
+       */
+      ScaleBun.captureError(error, {
+        screenName: this.props.screenName,
+        metadata: {
+          componentStack: info.componentStack ?? undefined
+        }
+      });
+    } catch {
+      /* never let capture break the boundary */
+    }
+    /**
+     * Tell the OTA boot guard. A fallback keeps the process alive, and a live process is exactly
+     * what makes the guard mark a freshly-installed bundle healthy — so without this, an update
+     * that breaks the first screen would never be reverted. The orchestrator ignores it outside
+     * the health window. Lazy + guarded: apps without OTA never load the orchestrator here.
+     */
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      require('../features/ota/OtaOrchestrator').otaOrchestrator?.noteBootFailure?.();
+    } catch {
+      /* OTA absent or unavailable — nothing to tell */
+    }
+    this.props.onError?.(error, info);
+  }
+  render() {
+    if (this.state.error) {
+      const {
+        fallback
+      } = this.props;
+      return typeof fallback === 'function' ? fallback(this.state.error) : fallback ?? null;
+    }
+    return this.props.children;
+  }
+}
+//# sourceMappingURL=ScaleBunErrorBoundary.js.map