@scalebun-release/react-native 2.5.0

package/lib/module/config/quotaState.js

@@ -0,0 +1,423 @@
+/**
+ * ScaleBun SDK — per-feature quota state (shared contract v1).
+ *
+ * The plan caps four features: `events`, `sessions`, `frames`, `networkRequests`. When one is
+ * exhausted the server says so in two places, and this module is the ONE place both land:
+ *
+ *   1. GET /config carries `quota: { v, serverTime, periodEnd, blocked: { <feature>: { until, since } } }`.
+ *   2. An ingestion refusal — HTTP 402 `{ code: 'quota_exceeded', feature, until }` on the
+ *      single-feature endpoints, or `quota.events.blocked` in the 200 body of POST /v1/batch.
+ *
+ * Every lane asks `isBlocked(feature)` at CAPTURE time (don't record what cannot be stored) and at
+ * SEND time (don't upload what was queued before the block arrived). Lanes that hold state
+ * (buffers, persisted queues, native outbox directories, running capture) subscribe and purge or
+ * stop when a block begins, and resume when it ends.
+ *
+ * CLOCKS. There is no server-time sync in this SDK and the device clock may be arbitrarily wrong,
+ * so a block is never lifted by the device clock alone. `untilMs` is computed RELATIVE to the moment
+ * the block was received — `receivedAt + (until − serverTime)` — which is immune to a skewed device
+ * clock, and reaching it only triggers ONE forced /config refresh. The block is lifted only when the
+ * server no longer lists it. If that refresh fails, the next attempt is at least 5 minutes later.
+ *
+ * `quota` absent from /config (an older backend) leaves the persisted state untouched; with nothing
+ * persisted, nothing is blocked. Every method is non-throwing.
+ *
+ * The refresh at untilMs is delayed by a per-device random 60–300 s so a fleet whose blocks all end at
+ * the same periodEnd does not hit /config in the same second.
+ *
+ * OUT OF CONTRACT (not gated here; the backend does not meter them against these quotas):
+ *  - the legacy `PersistentQueue` → `/sdk/events` (projectId/publishableKey) lane;
+ *  - the legacy `BackendReplayTransport` (`/v1/replay/...`, `X-API-Key`) replay transport.
+ * Both predate the clientKey ingestion contract that the four limited lanes belong to.
+ */
+import { createStorageBackend } from '../storage/StorageBackend';
+import { logger } from '../core/logger/internalLogger';
+export const QUOTA_FEATURES = ['events', 'sessions', 'frames', 'networkRequests'];
+
+/** Shape of the `quota` block on GET /config (contract §1). */
+
+const K_QUOTA = 'scalebun_quota_state';
+/** Floor between two expiry-driven refreshes (and the fallback when `until` is unparseable). */
+const MIN_RECHECK_MS = 5 * 60 * 1000;
+/** setTimeout's ceiling (~24.8 days). A longer wait is re-armed when it fires. */
+const MAX_TIMER_MS = 2_147_483_647;
+/** Anti-herd jitter added to the untilMs refresh: 60–300 s, fixed per QuotaState instance. */
+const JITTER_MIN_MS = 60_000;
+const JITTER_SPAN_MS = 240_000;
+export function isQuotaFeature(x) {
+  return typeof x === 'string' && QUOTA_FEATURES.includes(x);
+}
+function parseIso(s) {
+  if (typeof s !== 'string' || !s) return null;
+  const t = Date.parse(s);
+  return Number.isFinite(t) ? t : null;
+}
+export class QuotaState {
+  blocks = new Map();
+  listeners = new Set();
+  refresher = null;
+  timer = null;
+  lastExpiryRefreshAt = 0;
+  loaded = false;
+  syncListeners = new Set();
+  /** Monotonic in-process refusal counter (see QuotaBlockRecord.seq). */
+  refusalSeq = 0;
+  constructor(storageFactory = () => createStorageBackend(), clock = () => Date.now(), random = Math.random) {
+    this.storageFactory = storageFactory;
+    this.clock = clock;
+    this.jitterMs = JITTER_MIN_MS + Math.floor(Math.max(0, Math.min(1, random())) * JITTER_SPAN_MS);
+  }
+
+  /**
+   * Called after EVERY state sync — each /config 200 that carries `quota` and each recorded refusal —
+   * whether or not anything transitioned. Consumers that mirror the full state elsewhere (the native
+   * outbox lanes) re-assert it here, which is what un-parks a lane native parked on its own.
+   */
+  onSync(listener) {
+    this.syncListeners.add(listener);
+    return () => {
+      this.syncListeners.delete(listener);
+    };
+  }
+  emitSync() {
+    for (const l of Array.from(this.syncListeners)) {
+      try {
+        l();
+      } catch {
+        /* no-throw */
+      }
+    }
+  }
+
+  // ── reads ────────────────────────────────────────────────────────────────
+
+  isBlocked(feature) {
+    this.ensureLoaded();
+    return this.blocks.has(feature);
+  }
+  blockedFeatures() {
+    this.ensureLoaded();
+    return Array.from(this.blocks.keys());
+  }
+
+  /** Copy of the current records (diagnostics / tests). */
+  snapshot() {
+    this.ensureLoaded();
+    const out = {};
+    for (const [f, r] of this.blocks) out[f] = {
+      ...r
+    };
+    return out;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /**
+   * Register the forced /config refresh used when a block's `untilMs` is reached. Arms the expiry
+   * timer for whatever is already persisted.
+   */
+  setRefresher(fn) {
+    this.ensureLoaded();
+    this.refresher = fn;
+    this.scheduleExpiryCheck();
+  }
+
+  /**
+   * Capture at /config REQUEST START and pass to applyConfig. Refusals recorded after this mark
+   * survive that response; everything older (and everything loaded from disk) is reconciled by it.
+   */
+  requestMark() {
+    return this.refusalSeq;
+  }
+
+  // ── writes ───────────────────────────────────────────────────────────────
+
+  /**
+   * Apply the `quota` block of a FRESH (HTTP 200) /config response.
+   *
+   * @param requestMark `requestMark()` captured when the /config request was issued. A refusal
+   *        recorded AFTER it (in this process) is kept even when this response does not list it —
+   *        the server answered before it knew. Omitted → every refusal counts as older.
+   */
+  applyConfig(quota, receivedAt = this.clock(), requestMark = Number.MAX_SAFE_INTEGER) {
+    try {
+      this.ensureLoaded();
+      if (!quota || typeof quota !== 'object') return; // old backend → keep persisted state
+      const q = quota;
+      if (typeof q.v !== 'number' || q.v < 1) return; // unknown shape → keep persisted state
+      const serverNow = parseIso(q.serverTime);
+      const listed = new Map();
+      const blocked = q.blocked && typeof q.blocked === 'object' ? q.blocked : {};
+      for (const key of Object.keys(blocked)) {
+        if (!isQuotaFeature(key)) continue;
+        const b = blocked[key] ?? {};
+        const untilIso = typeof b.until === 'string' && b.until || q.periodEnd || null;
+        listed.set(key, {
+          until: untilIso,
+          since: typeof b.since === 'string' ? b.since : null,
+          receivedAt,
+          untilMs: this.untilMsFrom(untilIso, serverNow, receivedAt),
+          source: 'config'
+        });
+      }
+      const changes = [];
+      for (const [f, rec] of Array.from(this.blocks)) {
+        if (listed.has(f)) continue;
+        if (rec.source === 'refusal' && (rec.seq ?? 0) > requestMark) continue;
+        this.blocks.delete(f);
+        changes.push([f, false]);
+      }
+      for (const [f, rec] of listed) {
+        if (!this.blocks.has(f)) changes.push([f, true]);
+        this.blocks.set(f, rec);
+      }
+      this.persist();
+      this.scheduleExpiryCheck();
+      this.emit(changes);
+      this.emitSync();
+    } catch (err) {
+      logger.warn(`[ScaleBun.quota] applyConfig failed: ${err?.message}`);
+    }
+  }
+
+  /**
+   * Record a quota refusal from an ingestion response. `until` is the server's period end; the
+   * refresh time is anchored on `Retry-After` (seconds until period end) when present, else on the
+   * response `Date` header, else — last resort — on the device clock. In every case reaching it only
+   * triggers a /config refresh.
+   *
+   * @returns true when `feature` is a limited feature and is now blocked.
+   */
+  applyRefusal(feature, until, opts = {}) {
+    try {
+      this.ensureLoaded();
+      if (!isQuotaFeature(feature)) return false;
+      const receivedAt = opts.receivedAt ?? this.clock();
+      const untilIso = typeof until === 'string' && until ? until : null;
+      const ra = opts.retryAfterSec;
+      const untilMs = typeof ra === 'number' && Number.isFinite(ra) && ra >= 0 ? receivedAt + ra * 1000 : this.untilMsFrom(untilIso, parseIso(opts.serverDate), receivedAt);
+      const had = this.blocks.get(feature);
+      // A config block is anchored on serverTime and reconciled by /config itself; a refusal for
+      // an already-blocked feature adds nothing (but mirrors still re-assert the state).
+      if (had?.source === 'config') {
+        this.emitSync();
+        return true;
+      }
+      this.blocks.set(feature, {
+        until: untilIso,
+        since: had?.since ?? null,
+        receivedAt,
+        untilMs,
+        source: 'refusal',
+        seq: ++this.refusalSeq
+      });
+      this.persist();
+      this.scheduleExpiryCheck();
+      if (!had) {
+        logger.warn(`[ScaleBun.quota] ${feature} quota exceeded — capture and upload stopped until ${untilIso ?? 'the server lifts it'}`);
+        this.emit([[feature, true]]);
+      }
+      this.emitSync();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // ── internals ────────────────────────────────────────────────────────────
+
+  untilMsFrom(untilIso, serverNowMs, receivedAt) {
+    const until = parseIso(untilIso);
+    if (until === null) return receivedAt + MIN_RECHECK_MS;
+    // No server anchor: the device clock is the only reference. Still only triggers a refresh.
+    if (serverNowMs === null) return until;
+    return receivedAt + Math.max(0, until - serverNowMs);
+  }
+  emit(changes) {
+    for (const [f, blocked] of changes) {
+      for (const l of Array.from(this.listeners)) {
+        try {
+          l(f, blocked);
+        } catch {
+          /* a listener must never break the others */
+        }
+      }
+    }
+  }
+  scheduleExpiryCheck() {
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    if (!this.refresher || this.blocks.size === 0) return;
+    let earliest = Infinity;
+    for (const r of this.blocks.values()) earliest = Math.min(earliest, r.untilMs);
+    const at = Math.max(earliest + this.jitterMs, this.lastExpiryRefreshAt + MIN_RECHECK_MS);
+    const delay = Math.min(Math.max(at - this.clock(), 0), MAX_TIMER_MS);
+    const t = setTimeout(() => this.runExpiryRefresh(), delay);
+    t?.unref?.();
+    this.timer = t;
+  }
+  runExpiryRefresh() {
+    this.timer = null;
+    const now = this.clock();
+    let due = false;
+    for (const r of this.blocks.values()) if (r.untilMs + this.jitterMs <= now) due = true;
+    if (!due || !this.refresher) {
+      this.scheduleExpiryCheck(); // clamped long wait, or nothing left
+      return;
+    }
+    this.lastExpiryRefreshAt = now;
+    const refresher = this.refresher;
+    Promise.resolve().then(() => refresher()).catch(() => {/* refresh failure keeps the block; re-armed below */}).then(() => this.scheduleExpiryCheck());
+  }
+  ensureLoaded() {
+    if (this.loaded) return;
+    this.loaded = true;
+    try {
+      const raw = this.storageFactory()?.get(K_QUOTA);
+      if (!raw) return;
+      const parsed = JSON.parse(raw);
+      if (parsed?.v !== 1 || !parsed.blocks) return;
+      for (const key of Object.keys(parsed.blocks)) {
+        const r = parsed.blocks[key];
+        if (!isQuotaFeature(key) || !r || typeof r.untilMs !== 'number') continue;
+        let receivedAt = typeof r.receivedAt === 'number' ? r.receivedAt : 0;
+        let untilMs = r.untilMs;
+        // Received "in the future": the clock was ahead then and has been corrected since.
+        // Shift the record back to now so its refresh is not delayed by the skew.
+        const now = this.clock();
+        if (receivedAt > now) {
+          untilMs -= receivedAt - now;
+          receivedAt = now;
+        }
+        this.blocks.set(key, {
+          until: typeof r.until === 'string' ? r.until : null,
+          since: typeof r.since === 'string' ? r.since : null,
+          receivedAt,
+          untilMs,
+          source: r.source === 'refusal' ? 'refusal' : 'config',
+          seq: 0 // from disk: older than any request of this process
+        });
+      }
+    } catch {
+      /* corrupt state → nothing blocked; the next /config restores the truth */
+    }
+  }
+  persist() {
+    try {
+      const storage = this.storageFactory();
+      if (!storage) return;
+      if (this.blocks.size === 0) {
+        storage.delete(K_QUOTA);
+        return;
+      }
+      const blocks = {};
+      for (const [f, r] of this.blocks) {
+        const {
+          seq: _seq,
+          ...rest
+        } = r; // seq is in-process only
+        blocks[f] = rest;
+      }
+      storage.set(K_QUOTA, JSON.stringify({
+        v: 1,
+        blocks
+      }));
+    } catch {
+      /* no-throw */
+    }
+  }
+
+  /** TEST-ONLY: drop in-memory state, listeners and timers. */
+  __resetForTests(storageFactory, clock) {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    this.blocks.clear();
+    this.listeners.clear();
+    this.syncListeners.clear();
+    this.refresher = null;
+    this.lastExpiryRefreshAt = 0;
+    this.refusalSeq = 0;
+    this.loaded = false;
+    if (storageFactory) this.storageFactory = storageFactory;
+    if (clock) this.clock = clock;
+  }
+}
+
+/** The process-wide quota state every lane consults. */
+export const quotaState = new QuotaState();
+
+// ── response helpers ─────────────────────────────────────────────────────────
+
+function header(headers, name) {
+  try {
+    const v = headers?.get?.(name);
+    return typeof v === 'string' && v ? v : null;
+  } catch {
+    return null;
+  }
+}
+function retryAfterSeconds(headers) {
+  const v = header(headers, 'retry-after');
+  if (!v) return null;
+  const n = Number(v.trim());
+  return Number.isFinite(n) && n >= 0 ? n : null;
+}
+
+/**
+ * Inspect a SINGLE-FEATURE ingestion response (sessions start, frames, frames/presign, network,
+ * events) for a quota refusal and record it.
+ *
+ *   - HTTP 402 `{ code: 'quota_exceeded', feature, until }` → blocked.
+ *   - HTTP 2xx with `quota: { feature, granted, refused, until }` and `refused > 0` → a partial grant:
+ *     the allowance is now spent, so the feature is blocked from here on.
+ *
+ * @returns the refused feature, or null.
+ */
+export function noteQuotaResponse(status, body, headers, target = quotaState) {
+  try {
+    if (!body || typeof body !== 'object') return null;
+    const b = body;
+    const opts = {
+      retryAfterSec: retryAfterSeconds(headers),
+      serverDate: header(headers, 'date')
+    };
+    if (status === 402 && b.code === 'quota_exceeded' && isQuotaFeature(b.feature)) {
+      target.applyRefusal(b.feature, b.until, opts);
+      return b.feature;
+    }
+    const q = b.quota;
+    if (status >= 200 && status < 300 && q && typeof q === 'object' && isQuotaFeature(q.feature)) {
+      if (typeof q.refused === 'number' && q.refused > 0) {
+        target.applyRefusal(q.feature, q.until, opts);
+        return q.feature;
+      }
+    }
+  } catch {
+    /* no-throw */
+  }
+  return null;
+}
+
+/**
+ * Inspect a POST /v1/batch response body (`quota.events.blocked`, contract §2c) and record the block.
+ * @returns true when events are now blocked.
+ */
+export function noteBatchQuota(body, headers, target = quotaState) {
+  try {
+    const ev = body?.quota?.events;
+    if (!ev || ev.blocked !== true) return false;
+    return target.applyRefusal('events', ev.until, {
+      retryAfterSec: retryAfterSeconds(headers),
+      serverDate: header(headers, 'date')
+    });
+  } catch {
+    return false;
+  }
+}
+//# sourceMappingURL=quotaState.js.map

package/lib/module/core/architecture.js

@@ -0,0 +1,38 @@
+/**
+ * Runtime React Native architecture detection.
+ *
+ * Why this exists: our native-module resolvers prefer the codegen TurboModule
+ * spec (`require('../specs/Native*').default`, i.e. `TurboModuleRegistry.get`).
+ * On the **Old Architecture**, `TurboModuleRegistry.get()` does NOT return null —
+ * it transparently falls back to the legacy `NativeModules` lookup via React
+ * Native's built-in backward-compatibility layer. So "the turbo lookup
+ * succeeded" is NOT proof the New Architecture is active. Inferring the
+ * architecture from which lookup won therefore mislabels Old-Arch apps as
+ * "New Architecture".
+ *
+ * The only reliable runtime signal is the TurboModule proxy / bridgeless flag
+ * that the native runtime installs onto the global object when — and only when —
+ * the New Architecture is enabled.
+ */
+
+/**
+ * `true` when the app is running on the React Native New Architecture
+ * (TurboModules / Fabric / bridgeless), `false` on the Old Architecture (bridge)
+ * or when there is no native runtime (web / SSR / tests).
+ */
+export function isNewArchitecture() {
+  const g = globalThis;
+  // `__turboModuleProxy` is installed by the TurboModule runtime; `RN$Bridgeless`
+  // is set when running bridgeless (which is always New Architecture).
+  return g?.__turboModuleProxy != null || g?.RN$Bridgeless === true;
+}
+
+/**
+ * Human-readable label for the active architecture and how a native module was
+ * obtained — used in the one-time "native module via …" resolver logs so the
+ * line reflects reality on both architectures.
+ */
+export function nativeModuleVia() {
+  return isNewArchitecture() ? 'TurboModule (New Architecture)' : 'legacy NativeModules (Old Architecture)';
+}
+//# sourceMappingURL=architecture.js.map

package/lib/module/core/clock/now.js

@@ -0,0 +1,7 @@
+/**
+ * Returns the current timestamp in milliseconds.
+ */
+export function now() {
+  return Date.now();
+}
+//# sourceMappingURL=now.js.map

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

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