@scalebun/react-native 1.11.0 → 1.13.0

package/src/features/ota/OtaTypes.ts

@@ -8,42 +8,38 @@
 
 /**
  * ═══════════════════════════════════════════════════════════════════════════
- * OTA-TELEMETRY-SPEC — remaining telemetry fixes (from the 2026-08 audit)
+ * OTA-TELEMETRY-SPEC — status (spec §84-86)
  * ═══════════════════════════════════════════════════════════════════════════
- * These close the SDK half of spec §84-86. All are ADDITIVE + backward-compatible
- * (new optional fields, new enum members, new no-throw emit calls); old installed
- * clients omit them and the backend ingests nullable/unknown fields. Each ALTERS
- * DEVICE RUNTIME BEHAVIOR, so land them behind a real RN build + device/kill-test
- * (Metro cannot exercise the boot-guard) — this file only carries the contract
- * types + this spec, not the runtime wiring.
+ * Items 1-3 are DONE. All were additive and backward-compatible: old installed
+ * clients simply omit the new fields and never emit the new types, and the
+ * backend ingests nullable columns. Because they alter device runtime behaviour,
+ * verify against a real RN build + device kill-test before release — Metro
+ * cannot exercise the boot guard.
  *
- * 1. releaseId end-to-end  (CRITICAL — root of the dashboard funnel mismatch)
- *    Backend already serves it: OtaBundlePayload.releaseId (done, this file +
- *    ota-check.service.ts). SDK TODO:
- *      - store payload.releaseId on the downloaded/installed bundle state, and
- *      - set `releaseId: bundle.releaseId` in the delivery mapper
- *        OtaOrchestrator.ts deliverOtaEvents (~:105) — currently only bundleId.
- *      Then ota_events carry releaseId and the funnel keys by release.
+ * 1. releaseId end-to-end — DONE. `recordInstallExpectation` persists the
+ *    release id (so a rollback reported launches later can still name it),
+ *    `hydrateCurrentBundleFromSlots` restores it, every emit site passes it, and
+ *    `deliverOtaEvents` maps it onto the wire item.
  *
- * 2. Emit CHECK + OFFERED  (funnel top is currently unmeasurable)
- *    - CHECK: emit at the start of checkForUpdate (OtaOrchestrator.ts ~:480),
- *      before the fetch. ('CHECK' type already exists — no emit site today.)
- *    - OFFERED: add 'OFFERED' to OtaEventType, emit when checkRes.action ===
- *      'DOWNLOAD' (~:619) before download begins.
+ * 2. CHECK + OFFERED — DONE. CHECK is emitted at the top of `sync()` for devices
+ *    already on an OTA bundle (a device on the factory bundle has no owned
+ *    bundle id to name, and the server drops rows it cannot resolve — those are
+ *    counted server-side instead). OFFERED is emitted on `action === 'DOWNLOAD'`
+ *    before any bytes move.
  *
- * 3. Emit BOOT_SUCCESS  (honest activation signal)
- *    Add 'BOOT_SUCCESS' to OtaEventType and emit it from the boot-guard
- *    markHealthy path (OtaOrchestrator.ts ~:863). INSTALLED (~:794) is emitted
- *    optimistically BEFORE the bundle boots; keep it (it means "staged+swapped")
- *    but let the dashboard measure real activation on BOOT_SUCCESS. Optionally
- *    add 'VERIFIED' after signature check (~:635).
+ * 3. BOOT_SUCCESS — DONE. Emitted from the boot-guard heartbeat once the bundle
+ *    has actually booted and survived to `healthyAfterMs`. INSTALLED is kept and
+ *    still means "staged + swapped", but activation should be measured on
+ *    BOOT_SUCCESS: INSTALLED fires before the bundle has run, so it credits
+ *    bundles that installed and then crash-reverted.
  *
- * 4. Stamp the running OTA bundle onto session/crash telemetry
- *    SessionMetadata.bundleId is the NATIVE app package id, not the OTA bundle.
- *    Add optional otaBundleId?/otaBundleVersion? (distinct fields — do NOT
- *    overload bundleId) sourced from otaOrchestrator.getCurrentBundle() at
- *    session start (SessionManager.ts ~:451), so crashes attribute to the
- *    running bundle/version (release-health crash impact).
+ * 4. Stamp the running OTA bundle onto session/crash telemetry — NOT DONE.
+ *    `SessionMetadata.bundleId` is the NATIVE app package id, not the OTA bundle,
+ *    so crashes cannot currently be attributed to the bundle that produced them
+ *    (release-health crash impact). Needs optional otaBundleId?/otaBundleVersion?
+ *    (distinct fields — do NOT overload bundleId) sourced from
+ *    `otaOrchestrator.getCurrentBundle()` at session start, plus the matching
+ *    backend columns and a Prisma migration.
  *
  * Do NOT repurpose errorCode (it already collapses failure-error vs rollback-
  * reason); add a new optional field if the two must be distinguished.
@@ -149,14 +145,16 @@ export interface OtaPatchPayload {
 }
 
 // ── Adoption telemetry (rides the unified batch envelope as kind:'ota_event') ──
-export type OtaEventType =
-  | 'CHECK'
-  | 'DOWNLOAD_STARTED'
-  | 'DOWNLOAD_COMPLETE'
-  | 'INSTALLED'
-  | 'APPLY_FAILED'
-  | 'AUTO_ROLLBACK'
-  | 'MANUAL_ROLLBACK';
+//
+// The event vocabulary is declared ONCE, in OtaEventEmitter — the module that
+// emits it. This file used to carry a second, shorter copy under the same name,
+// so `OtaEventItem.type` and the emitter's events could disagree while both
+// type-checked, and adding a funnel step meant remembering to edit two unions.
+// `DOWNLOAD_PROGRESS` is emitted for UI only and never queued for upload, so it
+// is excluded here rather than re-listing the rest.
+import type { OtaEventType as EmittedOtaEventType } from './OtaEventEmitter';
+
+export type OtaEventType = Exclude<EmittedOtaEventType, 'DOWNLOAD_PROGRESS'>;
 
 export interface OtaEventItem {
   kind: 'ota_event';

package/src/features/ota/useOtaUpdate.ts

@@ -115,7 +115,13 @@ export function useOtaUpdate(options: UseOtaUpdateOptions): UseOtaUpdateReturn {
     setIsSyncing(true);
     setDownloadProgress(0);
     try {
-      const result = await otaOrchestrator.sync(options);
+      // Read through the ref, not the closed-over `options`. The dependency list
+      // below cannot name the targeting fields (`attributes` and `segmentIds` are
+      // fresh object/array identities on every render, so listing them would
+      // rebuild this callback each time), which left a host that changed
+      // `channelName` or `lifecycleStage` syncing against the values captured on
+      // first render. The ref is assigned on every render, so it is always current.
+      const result = await otaOrchestrator.sync(optionsRef.current);
       setSyncResult(result);
 
       // Handle mandatory update blocking
@@ -131,7 +137,10 @@ export function useOtaUpdate(options: UseOtaUpdateOptions): UseOtaUpdateReturn {
     } finally {
       setIsSyncing(false);
     }
-  }, [options.apiUrl, options.clientKey, options.appVersion, options.installationId, options.autoRestart]);
+    // Empty: everything this reads comes from `optionsRef`, so the callback has a
+    // stable identity and never needs rebuilding. A host can safely pass it to a
+    // memoised child or an effect dependency list.
+  }, []);
 
   const restart = useCallback(() => {
     setMandatoryUpdatePending(false);

package/src/public/ScaleBunFacade.ts

@@ -327,6 +327,17 @@ class ScaleBunFacade {
                     );
                 }
             }
+            // `healthyAfterMs` is the field BootGuardConfig actually declares.
+            // This passed `healthyTimeoutMs`, which nothing reads, so a host that
+            // tuned the boot-guard window silently got the 10s default instead.
+            // Both spellings are accepted so the older one keeps working.
+            const healthyAfterMs =
+                typeof ota.healthyAfterMs === 'number'
+                    ? ota.healthyAfterMs
+                    : typeof ota.healthyTimeoutMs === 'number'
+                      ? ota.healthyTimeoutMs
+                      : undefined;
+
             otaOrchestrator.init({
                 ...(signingRequested
                     ? {
@@ -338,16 +349,129 @@ class ScaleBunFacade {
                           },
                       }
                     : {}),
-                ...(typeof ota.healthyTimeoutMs === 'number'
-                    ? { healthyTimeoutMs: ota.healthyTimeoutMs }
-                    : {}),
+                ...(healthyAfterMs !== undefined ? { healthyAfterMs } : {}),
             });
             logger.info('[ScaleBun] OTA enabled from init config.');
+
+            // Run the checks the config asked for. Until this existed, `ota.enabled`
+            // initialised the orchestrator and then never checked anything: the
+            // documented `checkOnForeground` and `channelOverride` options were read
+            // by no code at all, and an app following the documented config received
+            // updates only if it ALSO drove `useOtaUpdate` or the CodePush shim by
+            // hand. Nothing logged, because "no update available" and "never asked"
+            // look identical from the outside.
+            this._startOtaChecks(ota);
         } catch (err: any) {
             logger.warn(`[ScaleBun] OTA init failed: ${err?.message ?? err}`);
         }
     }
 
+    /** Guards against overlapping config-driven OTA checks. */
+    private _otaCheckInFlight = false;
+    /** Wall clock of the last config-driven check, for the foreground floor. */
+    private _otaLastCheckAt = 0;
+    private _otaForegroundListener: ((state: string) => void) | null = null;
+
+    /**
+     * Minimum gap between config-driven checks.
+     *
+     * A foreground transition is cheap to trigger — app switchers, permission
+     * dialogs and share sheets all produce one — so an unthrottled check would
+     * put a request on the hot path every time the user glanced away. Ten
+     * minutes is well below any realistic release cadence and well above that
+     * noise. A host that wants a check on demand calls `useOtaUpdate().sync()`,
+     * which is never throttled.
+     */
+    private static readonly OTA_MIN_CHECK_INTERVAL_MS = 10 * 60 * 1000;
+
+    /**
+     * Drive OTA checks from init config: once at startup, then on each
+     * foreground when `checkOnForeground` is on (the schema default).
+     *
+     * `appVersion` is resolved from the native bridge rather than asked of the
+     * integrator, because it gates the server's `targetAppVersion` semver check
+     * — sending a wrong or invented value is worse than sending none, and there
+     * is no honest default. If it cannot be resolved, the check is skipped with
+     * a warning instead of guessing.
+     */
+    private _startOtaChecks(ota: any): void {
+        // Never in a debug build. `ScaleBunOtaModule.getJSBundleFile()` returns null
+        // there on purpose so Metro keeps ownership of the bundle — so a bundle
+        // downloaded in dev is installed into a slot that will never be loaded, and
+        // the identity check on the next launch then correctly observes that the
+        // running code is not what was installed and reports APPLY_FAILED. Checking
+        // at all in dev buys nothing and manufactures that false alarm. A developer
+        // testing the OTA path drives `useOtaUpdate().sync()` explicitly.
+        if (__DEV__) {
+            logger.info('[ScaleBun] OTA checks are skipped in debug builds (Metro owns the bundle).');
+            return;
+        }
+
+        const runCheck = async (trigger: 'startup' | 'foreground'): Promise<void> => {
+            if (this._otaCheckInFlight) return;
+            if (
+                trigger === 'foreground' &&
+                Date.now() - this._otaLastCheckAt < ScaleBunFacade.OTA_MIN_CHECK_INTERVAL_MS
+            ) {
+                return;
+            }
+            const clientKey = this._clientKey;
+            const apiUrl = this._apiBaseUrl;
+            if (!clientKey || !apiUrl) return;
+
+            this._otaCheckInFlight = true;
+            try {
+                const info = await bridgeAdapter.getDeviceInfo();
+                const appVersion = (info as { appVersion?: string } | null)?.appVersion;
+                if (!appVersion) {
+                    logger.warn(
+                        '[ScaleBun] OTA check skipped — the app version could not be read from the ' +
+                            'native bridge. Rebuild the native app, or drive checks yourself with ' +
+                            'useOtaUpdate({ appVersion }).',
+                    );
+                    return;
+                }
+                this._otaLastCheckAt = Date.now();
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const { otaOrchestrator } = require('../features/ota/OtaOrchestrator');
+                await otaOrchestrator.sync({
+                    apiUrl,
+                    clientKey,
+                    appVersion,
+                    // The documented option, finally connected. Omitted means the
+                    // server's `default` channel, exactly as before.
+                    channelName: typeof ota.channelOverride === 'string' ? ota.channelOverride : undefined,
+                    // Never forced from config: the release's own installMode
+                    // decides when the app restarts, and yanking the screen out
+                    // from under a user is not a decision this switch should make.
+                });
+            } catch (err: any) {
+                logger.warn(`[ScaleBun] OTA check failed: ${err?.message ?? err}`);
+            } finally {
+                this._otaCheckInFlight = false;
+            }
+        };
+
+        void runCheck('startup');
+
+        if (ota.checkOnForeground === false) return;
+        if (this._otaForegroundListener) return; // idempotent across repeated init()
+        try {
+            // Through `appLifecycle`, not a second AppState subscription: the SDK
+            // already owns one and fanning out from it keeps every consumer on the
+            // same transition sequence.
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { appLifecycle } = require('../core/lifecycle/appLifecycle');
+            this._otaForegroundListener = (state: string) => {
+                if (state === 'active') void runCheck('foreground');
+            };
+            appLifecycle.addListener(this._otaForegroundListener);
+        } catch {
+            // Lifecycle unavailable (tests, exotic hosts) — the startup check stands.
+            this._otaForegroundListener = null;
+        }
+    }
+
     private _autoEnableDebug(debugConfig: DebugConnectionConfig): void {
         try {
             const dbgConfig = buildDebugConfigFromInitConfig(debugConfig);