@scalebun-release/react-native 2.5.0

package/lib/module/bucketing/fnv1a32.js

@@ -0,0 +1,37 @@
+/**
+ * Deterministic experiment/rollout bucketing — MUST stay byte-for-byte identical to
+ * the backend (scalebun-dashboard-backend/src/common/bucketing/fnv1a32.ts). A shared test
+ * vector is asserted in BOTH repos; if you change the hash, update both.
+ *
+ * Inputs are ASCII (installationId = UUID, salt = hex) so charCodeAt === UTF-8 byte.
+ */
+export function fnv1a32(str) {
+  let h = 0x811c9dc5; // FNV offset basis (2166136261)
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193); // FNV prime (16777619)
+  }
+  return h >>> 0; // unsigned 32-bit
+}
+
+/** Stable 0..99 bucket for an install within an experiment/rollout (salt is immutable). */
+export function bucketOf(installationId, salt) {
+  return fnv1a32(`${installationId}:${salt}`) % 100;
+}
+
+/**
+ * Pick a variant by cumulative allocation. `variants` order is significant and
+ * `allocationPct` should sum to 100; the last variant is the fallback so an install
+ * always resolves to a variant.
+ */
+export function pickVariant(installationId, salt, variants) {
+  if (!variants.length) return null;
+  const b = bucketOf(installationId, salt);
+  let cum = 0;
+  for (const v of variants) {
+    cum += v.allocationPct;
+    if (b < cum) return v.key;
+  }
+  return variants[variants.length - 1].key;
+}
+//# sourceMappingURL=fnv1a32.js.map

package/lib/module/compat/codepush.js

@@ -0,0 +1,147 @@
+import { otaOrchestrator } from '../features/ota/OtaOrchestrator';
+import { logger } from '../core/logger/internalLogger';
+export let CodePushInstallMode = /*#__PURE__*/function (CodePushInstallMode) {
+  CodePushInstallMode[CodePushInstallMode["IMMEDIATE"] = 0] = "IMMEDIATE";
+  CodePushInstallMode[CodePushInstallMode["ON_NEXT_RESTART"] = 1] = "ON_NEXT_RESTART";
+  CodePushInstallMode[CodePushInstallMode["ON_NEXT_RESUME"] = 2] = "ON_NEXT_RESUME";
+  CodePushInstallMode[CodePushInstallMode["ON_NEXT_SUSPEND"] = 3] = "ON_NEXT_SUSPEND";
+  return CodePushInstallMode;
+}({});
+export let CodePushSyncStatus = /*#__PURE__*/function (CodePushSyncStatus) {
+  CodePushSyncStatus[CodePushSyncStatus["UP_TO_DATE"] = 0] = "UP_TO_DATE";
+  CodePushSyncStatus[CodePushSyncStatus["UPDATE_INSTALLED"] = 1] = "UPDATE_INSTALLED";
+  CodePushSyncStatus[CodePushSyncStatus["UPDATE_IGNORED"] = 2] = "UPDATE_IGNORED";
+  CodePushSyncStatus[CodePushSyncStatus["UNKNOWN_ERROR"] = 3] = "UNKNOWN_ERROR";
+  CodePushSyncStatus[CodePushSyncStatus["CHECKING_FOR_UPDATE"] = 4] = "CHECKING_FOR_UPDATE";
+  CodePushSyncStatus[CodePushSyncStatus["DOWNLOADING_PACKAGE"] = 5] = "DOWNLOADING_PACKAGE";
+  CodePushSyncStatus[CodePushSyncStatus["INSTALLING_UPDATE"] = 6] = "INSTALLING_UPDATE";
+  return CodePushSyncStatus;
+}({});
+
+/**
+ * Microsoft CodePush compatibility shim.
+ *
+ * Maps the CodePush surface (`sync`, `checkForUpdate`, the HOC) onto the
+ * ScaleBun orchestrator so a migrating app keeps compiling while its call sites
+ * are ported.
+ *
+ * CONFIGURE IT FIRST. This shim used to carry hardcoded defaults —
+ * `http://localhost:3001/api/v1` with a dev client key — so a migrated
+ * production app silently checked localhost forever and reported UP_TO_DATE on
+ * every sync. There is no correct default for someone else's backend, so there
+ * is now none: call `configureCodePushShim()` (or `ScaleBun.init({ ota })`,
+ * which the facade wires for you) before the first sync, and an unconfigured
+ * shim says so loudly instead of pretending to be up to date.
+ *
+ *   import codePush, { configureCodePushShim } from '@scalebun/react-native/compat/codepush';
+ *   configureCodePushShim({ apiUrl, clientKey, appVersion, installationId });
+ */
+
+let shimConfig = null;
+
+/** Point the shim at a real backend. Required before sync/checkForUpdate. */
+export function configureCodePushShim(config) {
+  shimConfig = config;
+}
+
+/**
+ * Resolve the sync params, or null when unconfigured. Returning null (rather
+ * than substituting a localhost default) is what turns a silent no-update into
+ * a visible, fixable error.
+ */
+function shimParams() {
+  if (!shimConfig) {
+    logger.warn('[ScaleBun] CodePush shim is not configured — no update check was performed. ' + 'Call configureCodePushShim({ apiUrl, clientKey, appVersion }) during startup.');
+    return null;
+  }
+  return shimConfig;
+}
+const codePushShim = function (rootComponent) {
+  return rootComponent;
+};
+codePushShim.sync = async (options, syncStatusCallback, downloadProgressCallback) => {
+  const params = shimParams();
+  if (!params) {
+    // Unconfigured is an ERROR, not "up to date": reporting UP_TO_DATE here is
+    // exactly how a broken migration stays invisible for months.
+    syncStatusCallback?.(CodePushSyncStatus.UNKNOWN_ERROR);
+    return CodePushSyncStatus.UNKNOWN_ERROR;
+  }
+  try {
+    syncStatusCallback?.(CodePushSyncStatus.CHECKING_FOR_UPDATE);
+    const result = await otaOrchestrator.sync({
+      ...params,
+      // Omitted → the orchestrator falls back to the SDK's canonical
+      // installation id, which is the right identity anyway.
+      ...(params.installationId ? {
+        installationId: params.installationId
+      } : {})
+    });
+    if (result.status === 'UP_TO_DATE') {
+      syncStatusCallback?.(CodePushSyncStatus.UP_TO_DATE);
+      return CodePushSyncStatus.UP_TO_DATE;
+    }
+    if (result.status === 'UPDATE_INSTALLED') {
+      syncStatusCallback?.(CodePushSyncStatus.UPDATE_INSTALLED);
+      return CodePushSyncStatus.UPDATE_INSTALLED;
+    }
+    syncStatusCallback?.(CodePushSyncStatus.UP_TO_DATE);
+    return CodePushSyncStatus.UP_TO_DATE;
+  } catch (err) {
+    syncStatusCallback?.(CodePushSyncStatus.UNKNOWN_ERROR);
+    return CodePushSyncStatus.UNKNOWN_ERROR;
+  }
+};
+codePushShim.checkForUpdate = async () => {
+  const params = shimParams();
+  if (!params) return null;
+  const check = await otaOrchestrator.checkForUpdate({
+    ...params,
+    ...(params.installationId ? {
+      installationId: params.installationId
+    } : {})
+  });
+  if (check.action === 'NONE' || !check.bundle) return null;
+  return {
+    appVersion: params.appVersion,
+    deploymentKey: 'scalebun_ota',
+    description: check.bundle.releaseNote ?? '',
+    failedInstall: false,
+    isFirstRun: false,
+    isMandatory: check.bundle.isMandatory,
+    isPending: false,
+    label: `v${check.bundle.version}`,
+    packageHash: check.bundle.sha256,
+    packageSize: check.bundle.size
+  };
+};
+codePushShim.disallowRestart = () => {
+  // Scalebun handles restart safety automatically via boot guard
+};
+codePushShim.allowRestart = () => {
+  // Scalebun handles restart safety automatically via boot guard
+};
+
+/**
+ * Metadata for the bundle currently RUNNING. CodePush apps use this to show a
+ * version or decide whether a pending update landed; returning a flat null
+ * (as this did) makes every such check read as "no OTA bundle installed".
+ */
+codePushShim.getUpdateMetadata = async () => {
+  const current = otaOrchestrator.getCurrentBundle();
+  if (!current) return null;
+  return {
+    appVersion: shimConfig?.appVersion ?? '',
+    deploymentKey: 'scalebun_ota',
+    description: current.releaseNote ?? '',
+    failedInstall: false,
+    isFirstRun: false,
+    isMandatory: current.isMandatory ?? false,
+    isPending: false,
+    label: `v${current.version}`,
+    packageHash: current.sha256,
+    packageSize: current.size
+  };
+};
+export default codePushShim;
+//# sourceMappingURL=codepush.js.map

package/lib/module/config/ConfigManager.js

@@ -0,0 +1,230 @@
+/**
+ * ScaleBun SDK — runtime config (Phase 4).
+ *
+ * Polls GET {apiBaseUrl}/config (client-key authed), caches it to disk, and resolves
+ * flags / remote config / rollouts / experiments LOCALLY (deterministic fnv1a32 — the
+ * backend never assigns). Experiment exposure flows through the normal event lane:
+ * variant() emits one `experiment_exposure` event per (install, experiment) and stamps
+ * `experiment_<key>=<variant>` onto subsequent events.
+ *
+ * Every method is non-throwing with a safe default — an app that can't reach /config
+ * behaves exactly as it would with no experiments configured.
+ */
+import { createStorageBackend } from '../storage/StorageBackend';
+import { logger } from '../core/logger/internalLogger';
+import { bucketOf, pickVariant } from '../bucketing/fnv1a32';
+import { EMPTY_CONFIG } from './configTypes';
+import { quotaState } from './quotaState';
+import { applyOtaConfig } from './otaPolicyState';
+const K_CONFIG = 'scalebun_config_payload';
+const K_CONFIG_VERSION = 'scalebun_config_version';
+const K_EXPOSED = 'scalebun_exp_exposed';
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // foreground refreshes throttled to 5 min
+
+function coerce(value, type, fallback) {
+  try {
+    if (type === 'number') {
+      const n = Number(value);
+      return Number.isNaN(n) ? fallback : n;
+    }
+    if (type === 'boolean') return value === 'true';
+    if (type === 'json') return JSON.parse(value);
+    return value;
+  } catch {
+    return fallback;
+  }
+}
+export class ConfigManager {
+  payload = EMPTY_CONFIG;
+  exposed = new Set();
+  lastFetch = 0;
+  inflight = null;
+  inflightForced = false;
+  constructor(deps) {
+    this.deps = deps;
+    this.storage = createStorageBackend();
+    this.loadCached();
+    this.loadExposed();
+  }
+
+  /**
+   * Fetch /config (ETag-aware). Keeps the cached payload on 304 / failure.
+   *
+   * `force` drops If-None-Match so the response carries a FRESH `quota.serverTime` — used when a
+   * quota block's refresh time is reached, where a 304 would say nothing about whether the server
+   * has lifted it.
+   *
+   * If-None-Match is ALSO dropped whenever any quota block is held locally. A block learned from an
+   * ingestion refusal may never have appeared in a /config 200 — the server's config version can be
+   * identical before and after the limit is raised, and an ETag request would then 304 forever while
+   * the SDK stays blocked.
+   *
+   * Concurrent unforced calls share one request. A forced call never piggybacks on an in-flight
+   * unforced one (that one may 304): it runs after it.
+   */
+  refresh(opts = {}) {
+    const force = opts.force === true;
+    if (this.inflight) {
+      if (!force || this.inflightForced) return this.inflight;
+      const prior = this.inflight;
+      return prior.then(() => this.refresh({
+        force: true
+      }));
+    }
+    this.inflightForced = force;
+    this.inflight = this.doRefresh(force).finally(() => {
+      this.inflight = null;
+      this.inflightForced = false;
+    });
+    return this.inflight;
+  }
+  async doRefresh(force) {
+    try {
+      const skipEtag = force || quotaState.blockedFeatures().length > 0;
+      const version = skipEtag ? undefined : this.storage.get(K_CONFIG_VERSION);
+      // Ordering mark for refusals (monotonic, in-process) — never the wall clock.
+      const quotaMark = quotaState.requestMark();
+      const res = await fetch(`${this.deps.apiBaseUrl}/config`, {
+        headers: {
+          'x-scalebun-client-key': this.deps.clientKey,
+          ...(version ? {
+            'If-None-Match': `"${version}"`
+          } : {})
+        }
+      });
+      this.lastFetch = Date.now();
+      if (res.status === 304) return; // unchanged — keep cache (and the quota state it produced)
+      if (!res.ok) return; // keep cache / defaults
+      const payload = await res.json();
+      if (payload && Array.isArray(payload.flags) && Array.isArray(payload.experiments)) {
+        this.payload = payload;
+        try {
+          this.storage.set(K_CONFIG, JSON.stringify(payload));
+          if (payload.version) this.storage.set(K_CONFIG_VERSION, payload.version);
+        } catch {/* no-throw */}
+        // Quota (contract v1 §1): applied LIVE — lanes subscribed to quotaState stop/resume now.
+        // `quota` absent (older backend) is a no-op inside applyConfig: persisted state stands.
+        try {
+          quotaState.applyConfig(payload.quota, this.lastFetch, quotaMark);
+        } catch {/* no-throw */}
+        // Absent leaves the previous policy standing — see applyOtaConfig.
+        applyOtaConfig(payload.ota);
+        // Push the admin replay-capture override (or its absence) to the facade.
+        try {
+          this.deps.onReplayCapture?.(this.getReplayCapture());
+        } catch {/* no-throw */}
+      }
+    } catch (err) {
+      logger.warn(`[ScaleBun.config] refresh failed: ${err?.message}`);
+    }
+  }
+
+  /**
+   * Refresh if the TTL has elapsed (call on app-foreground). Fire-and-forget. This is how a raised
+   * quota limit (or a new block) reaches a long-lived app: launch + foreground, 5-min TTL, ETag.
+   */
+  maybeRefresh() {
+    if (Date.now() - this.lastFetch > DEFAULT_TTL_MS) this.refresh().catch(() => {});
+  }
+
+  // ── resolution (all local + non-throwing) ──────────────────────────────────
+  isEnabled(key) {
+    return this.payload.flags.find(f => f.key === key)?.enabled ?? false;
+  }
+  get(key, fallback) {
+    const e = this.payload.remoteConfig.find(r => r.key === key);
+    return e ? coerce(e.value, e.type, fallback) : fallback;
+  }
+  rolloutIsOn(key) {
+    const r = this.payload.rollouts.find(x => x.key === key);
+    return r ? bucketOf(this.deps.installationId, r.salt) < r.percentage : false;
+  }
+
+  /**
+   * Whether the org is entitled to a SDK-suppressible feature. Fail-OPEN: an
+   * absent/unknown entitlement (e.g. before the first /config) returns true so we
+   * never wrongly disable a paying customer. The server is the real gate.
+   */
+  isFeatureEntitled(feature) {
+    const e = this.payload.entitlements;
+    return e?.[feature] ?? true;
+  }
+
+  /**
+   * The current admin-controlled replay capture override, or null when none is set. When non-null
+   * the SDK must use timer-based `frequency` capture at `intervalMs` (overriding the developer's
+   * local captureMode). Reads the cached/last-fetched payload — non-throwing.
+   */
+  getReplayCapture() {
+    const rc = this.payload.replayCapture;
+    return rc && rc.mode === 'frequency' && typeof rc.intervalMs === 'number' ? {
+      mode: 'frequency',
+      intervalMs: rc.intervalMs
+    } : null;
+  }
+
+  /**
+   * Read the cached config's entitlements synchronously WITHOUT a full
+   * ConfigManager (which needs the EventTracker, created during bootstrap). Lets
+   * the facade suppress closed-feature collectors at bootstrap time on any run
+   * after the first. Returns {} when no cache exists (→ fail-open).
+   */
+  static readCachedEntitlements() {
+    try {
+      const storage = createStorageBackend();
+      const raw = storage.get(K_CONFIG);
+      if (!raw) return {};
+      const parsed = JSON.parse(raw);
+      return parsed?.entitlements ?? {};
+    } catch {
+      return {};
+    }
+  }
+  variant(key) {
+    const exp = this.payload.experiments.find(e => e.key === key);
+    if (!exp) return null;
+    const v = pickVariant(this.deps.installationId, exp.salt, exp.variants);
+    if (!v) return null;
+    // Log exposure exactly once per (install, experiment).
+    if (!this.exposed.has(key)) {
+      this.exposed.add(key);
+      this.persistExposed();
+      try {
+        this.deps.emitExposure(key, v);
+      } catch {/* no-throw */}
+    }
+    // Stamp the assignment onto subsequent events for downstream slicing.
+    try {
+      this.deps.stamp(`experiment_${key}`, v);
+    } catch {/* no-throw */}
+    return v;
+  }
+
+  // ── persistence ─────────────────────────────────────────────────────────────
+  loadCached() {
+    try {
+      const raw = this.storage.get(K_CONFIG);
+      if (raw) {
+        const parsed = JSON.parse(raw);
+        if (parsed && Array.isArray(parsed.flags)) this.payload = parsed;
+      }
+    } catch {
+      this.payload = EMPTY_CONFIG;
+    }
+  }
+  loadExposed() {
+    try {
+      const raw = this.storage.get(K_EXPOSED);
+      if (raw) {
+        const a = JSON.parse(raw);
+        if (Array.isArray(a)) this.exposed = new Set(a);
+      }
+    } catch {/* no-throw */}
+  }
+  persistExposed() {
+    try {
+      this.storage.set(K_EXPOSED, JSON.stringify([...this.exposed]));
+    } catch {/* no-throw */}
+  }
+}
+//# sourceMappingURL=ConfigManager.js.map

package/lib/module/config/configTypes.js

@@ -0,0 +1,10 @@
+// Shape of GET {apiBaseUrl}/config (scalebun-dashboard-backend SdkConfigService).
+
+export const EMPTY_CONFIG = {
+  version: '',
+  flags: [],
+  remoteConfig: [],
+  experiments: [],
+  rollouts: []
+};
+//# sourceMappingURL=configTypes.js.map

package/lib/module/config/otaPolicyState.js

@@ -0,0 +1,76 @@
+/**
+ * The server-set OTA policy, held where the OTA lane can read it.
+ *
+ * ── Why a module singleton ───────────────────────────────────────────────────
+ *
+ * `OtaOrchestrator` has no reference to `ConfigManager` and should not gain one:
+ * the OTA lane runs in integration shapes where the full SDK is not present at
+ * all (the standalone orchestrator, the CodePush shim). This follows the pattern
+ * `quotaState` already established — ConfigManager applies what it fetched, and
+ * lanes read from here without knowing where it came from.
+ *
+ * ── Why the policy is read at DECISION time, not at init ─────────────────────
+ *
+ * `/config` is fetched asynchronously and cached to disk. A device that has ever
+ * fetched it keeps the policy across launches, but the first fetch of a session
+ * may land after the OTA lane has already initialised. Reading at the moment the
+ * withhold decision is made means a policy that arrives mid-session takes effect
+ * on the next check rather than on the next launch.
+ *
+ * Nothing here throws, and nothing here is persisted by this module: the payload
+ * that carries the policy is already cached by ConfigManager, so persisting it
+ * again would create a second copy that could disagree with the first.
+ */
+
+/** `null` = the server has said nothing, and the app's own config decides. */
+let serverPolicy = null;
+
+/**
+ * Apply the `ota` block from a `/config` payload.
+ *
+ * An ABSENT block leaves the previous value untouched rather than clearing it —
+ * the same rule `quotaState` uses. An older backend omits the field entirely,
+ * and treating that as "the policy was withdrawn" would silently loosen a
+ * security setting whenever a request happened to reach an older server.
+ */
+export function applyOtaConfig(block) {
+  try {
+    if (!block || typeof block !== 'object') return;
+    const raw = block.onCompromisedDevice;
+    if (raw === 'allow' || raw === 'withhold') serverPolicy = raw;
+  } catch {
+    /* never throw from config application */
+  }
+}
+
+/** What the server says, or null when it has said nothing. */
+export function serverCompromisedDevicePolicy() {
+  return serverPolicy;
+}
+
+/**
+ * Resolve the effective policy from the app's own setting and the server's.
+ *
+ * STRICTEST WINS, and the server can only ever TIGHTEN.
+ *
+ * A host that deliberately configured `withhold` must not have it switched off
+ * by a server value — loosening a security setting from outside the binary is
+ * the wrong direction, and it would mean a compromised control plane could
+ * re-enable updates to rooted devices. The server can turn withholding ON for a
+ * customer who has not shipped a release, which is the entire point of this
+ * feature, and it can never turn it off.
+ *
+ * A customer who genuinely wants to stop withholding changes it where they
+ * originally set it, or ships a release — the same cost as turning it on used to
+ * be, and now only in the direction that is safe to get wrong.
+ */
+export function resolveCompromisedDevicePolicy(hostPolicy) {
+  if (hostPolicy === 'withhold' || serverPolicy === 'withhold') return 'withhold';
+  return 'allow';
+}
+
+/** Test seam. Not exported from the package. */
+export function __resetOtaPolicyForTests() {
+  serverPolicy = null;
+}
+//# sourceMappingURL=otaPolicyState.js.map