@scalebun/react-native 1.0.4 → 1.1.0

package/src/compat/codepush.ts

@@ -1,4 +1,5 @@
 import { otaOrchestrator } from '../features/ota/OtaOrchestrator';
+import { logger } from '../core/logger/internalLogger';
 
 export enum CodePushInstallMode {
   IMMEDIATE = 0,
@@ -38,12 +39,57 @@ export interface CodePushPackage {
 }
 
 /**
- * Microsoft CodePush Drop-in Compatibility Shim — Sprint 10 (S10-CLI-1).
+ * Microsoft CodePush compatibility shim.
  *
- * Allows developers to migrate from CodePush to Scalebun OTA by simply changing:
- *   - import codePush from 'react-native-code-push'
- *   + import codePush from '@scalebun/react-native/compat/codepush'
+ * 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 });
+ */
+
+export interface CodePushShimConfig {
+    /** Backend base URL, e.g. https://api.yourbackend.com/api/v1 */
+    apiUrl: string;
+    /** SDK client key for this app/environment. */
+    clientKey: string;
+    /** Native app version this binary reports (e.g. '1.4.0'). */
+    appVersion: string;
+    /** Stable per-install id. Defaults to the SDK's canonical installation id. */
+    installationId?: string;
+}
+
+let shimConfig: CodePushShimConfig | null = null;
+
+/** Point the shim at a real backend. Required before sync/checkForUpdate. */
+export function configureCodePushShim(config: CodePushShimConfig): void {
+    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(): CodePushShimConfig | null {
+    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 <P>(rootComponent: React.ComponentType<P>) {
   return rootComponent;
 };
@@ -53,14 +99,21 @@ codePushShim.sync = async (
   syncStatusCallback?: (status: CodePushSyncStatus) => void,
   downloadProgressCallback?: (progress: { receivedBytes: number; totalBytes: number }) => void,
 ): Promise<CodePushSyncStatus> => {
+  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({
-      apiUrl: 'http://localhost:3001/api/v1',
-      clientKey: 'scalebun_ck_dev_default_0000000000000000000000',
-      appVersion: '1.0.0',
-      installationId: 'codepush_shim',
-    });
+      ...params,
+      // Omitted → the orchestrator falls back to the SDK's canonical
+      // installation id, which is the right identity anyway.
+      ...(params.installationId ? { installationId: params.installationId } : {}),
+    } as any);
 
     if (result.status === 'UP_TO_DATE') {
       syncStatusCallback?.(CodePushSyncStatus.UP_TO_DATE);
@@ -81,16 +134,16 @@ codePushShim.sync = async (
 };
 
 codePushShim.checkForUpdate = async (): Promise<CodePushPackage | null> => {
+  const params = shimParams();
+  if (!params) return null;
   const check = await otaOrchestrator.checkForUpdate({
-    apiUrl: 'http://localhost:3001/api/v1',
-    clientKey: 'scalebun_ck_dev_default_0000000000000000000000',
-    appVersion: '1.0.0',
-    installationId: 'codepush_shim',
-  });
+    ...params,
+    ...(params.installationId ? { installationId: params.installationId } : {}),
+  } as any);
   if (check.action === 'NONE' || !check.bundle) return null;
 
   return {
-    appVersion: '1.0.0',
+    appVersion: params.appVersion,
     deploymentKey: 'scalebun_ota',
     description: check.bundle.releaseNote ?? '',
     failedInstall: false,
@@ -111,8 +164,26 @@ 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 (): Promise<CodePushPackage | null> => {
-  return null;
+  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;

package/src/core/config/schema.ts

@@ -13,11 +13,10 @@ export const ConfigSchema = z.object({
      * 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.
+    // NB: `.default()` on the vendored `z` types its arg as `Partial<T> | (() => T)`, so a bare
+    // string arg fails `tsc` (.d.ts generation via bob) with TS2345. The factory form satisfies the
+    // `(() => any)` overload. Behaviour is identical — omitted apiBaseUrl resolves to the default,
+    // which the bootstrapper overwrites anyway (the endpoint is locked).
     apiBaseUrl: z.any().default(() => DEFAULT_API_BASE_URL),
     debug: z.boolean().default(false),
     /**
@@ -169,6 +168,11 @@ export const ConfigSchema = z.object({
      * Plumbed into SessionManager via SDKBootstrapper.
      */
     replay: z.object({
+        // 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 on demand via ScaleBun.startSession().
+        // Decoupled from finalizeOnBackground (which only governs per-foreground session boundaries).
+        record: z.boolean().optional(),
         captureMode: z.enum(['navigation', 'interactions', 'frequency']).optional(),
         intervalMs: z.number().min(500).optional(),
         quality: z.enum(['high', 'normal', 'low', 'grayscale']).optional(),
@@ -214,6 +218,15 @@ export const ConfigSchema = z.object({
         channelOverride: z.string().optional(),
         /** Ed25519 public key for bundle signature verification (base64). */
         publicSigningKey: z.string().optional(),
+        /**
+         * Ed25519 verifier supplied by the host — the SDK ships no crypto
+         * implementation. Required whenever `publicSigningKey` is set: pinning a
+         * key without a verifier is fail-closed, so updates stop installing.
+         * `(message, signature, publicKey) => boolean | Promise<boolean>`.
+         */
+        verifySignature: z.any().optional(),
+        /** Override how long a new bundle has to prove healthy (ms). */
+        healthyTimeoutMs: z.number().optional(),
         /** Block UI interaction while a mandatory update is pending. Default: false. */
         mandatoryBlocksUi: z.boolean().default(false),
     }).optional(),

package/src/core/constants/endpoints.ts

@@ -1,9 +1,12 @@
 /**
- * ScaleBun cloud API base URL.
+ * ScaleBun cloud API base URL — the single, LOCKED endpoint for the SDK.
  *
- * Used as the default for `apiBaseUrl` when an integrator does not supply one,
- * so the common "just give me a project key" integration works without knowing
- * the server address. Override `apiBaseUrl` in init config to point at a
- * staging environment or a self-hosted backend.
+ * `SDKBootstrapper` ignores any `apiBaseUrl` passed in init config and always
+ * uses this value, so an integrator cannot repoint the SDK at another backend.
+ * Includes the `/api/v1` path segment because every SDK route is built relative
+ * to this base (e.g. `${apiBaseUrl}/batch`, `${apiBaseUrl}/ingestion/sessions`,
+ * `${apiBaseUrl}/config`). Without `/api/v1` the ingestion routes return 404 and
+ * events are silently lost. To target a staging or self-hosted backend, change
+ * this value at build time.
  */
-export const DEFAULT_API_BASE_URL = 'https://api.scalebun.com';
+export const DEFAULT_API_BASE_URL = 'https://api.scalebun.com/api/v1';

package/src/features/engage/EngageTransport.ts

@@ -56,7 +56,7 @@ function uuidV4(): string {
 }
 
 export interface EngageTransportConfig {
-    /** Backend API base URL (e.g. https://api.scalebun.com). */
+    /** Backend API base URL (e.g. https://api.scalebun.com/api/v1). */
     endpoint: string;
     /** SaaS multi-tenant client key — gates upload lanes + x-scalebun-client-key header. */
     clientKey?: string;

package/src/features/ota/OtaOrchestrator.ts

@@ -199,6 +199,15 @@ const DEFAULT_MAX_REVERT_ATTEMPTS = 2;
 export class OtaOrchestrator {
   private enabled = false;
   private currentBundle: OtaBundlePayload | null = null;
+
+  /**
+   * The bundle this process is running, once hydrated from the native slots.
+   * Read-only view for integrations (e.g. the CodePush shim's
+   * getUpdateMetadata) that need to report the running version.
+   */
+  public getCurrentBundle(): OtaBundlePayload | null {
+    return this.currentBundle;
+  }
   private isRestartRequiredState = false;
   private healthyTimer: ReturnType<typeof setTimeout> | null = null;
   private bootGuardConfig: BootGuardConfig = {};

package/src/index.ts

@@ -12,7 +12,7 @@
 
 // ─── Default Export: SDK Facade Singleton ───────────────────────────────────
 // Usage: import ScaleBun from '@scalebun/react-native';
-//        await ScaleBun.init({ projectId: '...', publishableKey: '...', apiBaseUrl: '...' });
+//        await ScaleBun.init({ projectId: '...', publishableKey: '...' });
 
 export { default } from './public/ScaleBunFacade';
 export { ScaleBunProvider } from './public/ScaleBunProvider';

package/src/public/ScaleBunFacade.ts

@@ -251,6 +251,13 @@ class ScaleBunFacade {
                 // Continue — debug connection is independent of backend API
             }
 
+            // OTA from init config. Without this the whole `ota` config block was
+            // inert: `otaOrchestrator.init()` was reachable only by importing the
+            // orchestrator directly, so an app that followed the documented
+            // `ota: { enabled: true }` path silently got no updates AND no
+            // signature enforcement (sync() gates on the flag init() sets).
+            this._maybeStartOta(rawConfig);
+
             // Auto debug connection from init config — runs regardless of backend status
             const debugConfig = (rawConfig?.desktopDebug ?? rawConfig?.debug) as DebugConnectionConfig | undefined;
             if (debugConfig) {
@@ -264,6 +271,44 @@ class ScaleBunFacade {
         }
     }
 
+    /**
+     * Boot the OTA orchestrator when the init config asks for it.
+     *
+     * `publicSigningKey` is honoured here so signature enforcement is reachable
+     * from configuration alone. The SDK ships no ed25519 implementation, so a
+     * host that pins a key must also supply `ota.verifySignature`; pinning a key
+     * without a verifier is fail-CLOSED by design (signature.ts) — an update
+     * that cannot be verified is not installed. We say that out loud rather than
+     * letting the app discover it as a silent no-update condition.
+     */
+    private _maybeStartOta(rawConfig: any): void {
+        const ota = rawConfig?.ota;
+        if (!ota?.enabled) return;
+        try {
+            // Required lazily: hosts that never enable OTA should not pay for the
+            // module (or touch the native spec) at import time.
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { otaOrchestrator } = require('../features/ota/OtaOrchestrator');
+            const publicKey = ota.publicSigningKey;
+            const verifier = ota.verifySignature;
+            if (publicKey && typeof verifier !== 'function') {
+                logger.warn(
+                    '[ScaleBun] ota.publicSigningKey is set but ota.verifySignature is not a function. ' +
+                        'Signature checking is fail-closed: updates will be REJECTED until a verifier is supplied.',
+                );
+            }
+            otaOrchestrator.init({
+                ...(publicKey ? { signature: { publicKey, verifier } } : {}),
+                ...(typeof ota.healthyTimeoutMs === 'number'
+                    ? { healthyTimeoutMs: ota.healthyTimeoutMs }
+                    : {}),
+            });
+            logger.info('[ScaleBun] OTA enabled from init config.');
+        } catch (err: any) {
+            logger.warn(`[ScaleBun] OTA init failed: ${err?.message ?? err}`);
+        }
+    }
+
     private _autoEnableDebug(debugConfig: DebugConnectionConfig): void {
         try {
             const dbgConfig = buildDebugConfigFromInitConfig(debugConfig);

package/src/public/types.ts

@@ -78,14 +78,28 @@ export interface ScaleBunInitConfig {
     /** Publishable API key from dashboard */
     publishableKey: string;
     /**
-     * Backend API base URL. Optional — defaults to the ScaleBun cloud.
-     * Override only for staging or a self-hosted backend.
+     * @deprecated The endpoint is LOCKED to the ScaleBun cloud. Any value passed here is accepted
+     * (for backward compatibility) but ignored — the bootstrapper always uses the fixed
+     * `DEFAULT_API_BASE_URL`. To target a different backend, change that constant at build time.
      */
     apiBaseUrl?: string;
     /** @deprecated Use desktopDebug instead */
     debug?: boolean;
-    /** Enable session replay capture. Default: true */
+    /** Enable session replay capture (feature on/off). Default: true */
     sessionReplay?: boolean;
+    /**
+     * Session-replay capture options (SaaS mode).
+     * - `record` (default **true**): auto-start frame recording at cold launch so replays appear out
+     *   of the box. Set `false` for events-only sessions — you can still record on demand with
+     *   `ScaleBun.startSession()`.
+     * - `captureMode` / `intervalMs` / `quality`: tune capture cadence.
+     */
+    replay?: {
+        record?: boolean;
+        captureMode?: 'navigation' | 'interactions' | 'frequency';
+        intervalMs?: number;
+        quality?: 'high' | 'normal' | 'low' | 'grayscale';
+    };
     /** Event flush interval in ms. Default: 5000 */
     flushIntervalMs?: number;
     /** Max events per flush batch. Default: 1000 */
@@ -234,7 +248,6 @@ export interface ExportResult {
  * await ScaleBun.init({
  *   projectId: 'proj_xxx',
  *   publishableKey: 'pk_xxx',
- *   apiBaseUrl: 'https://api.scalebun.com',
  * });
  * ```
  *
@@ -243,7 +256,6 @@ export interface ExportResult {
  * await ScaleBun.init({
  *   projectId: 'proj_xxx',
  *   publishableKey: 'pk_xxx',
- *   apiBaseUrl: 'https://api.scalebun.com',
  *   debug: true,
  * });
  * ```
@@ -254,8 +266,9 @@ export interface SimplifiedInitConfig {
     /** Publishable API key from dashboard */
     publishableKey: string;
     /**
-     * Backend API base URL. Optional — defaults to the ScaleBun cloud.
-     * Override only for staging or a self-hosted backend.
+     * @deprecated The endpoint is LOCKED to the ScaleBun cloud. Any value passed here is accepted
+     * (for backward compatibility) but ignored — the bootstrapper always uses the fixed
+     * `DEFAULT_API_BASE_URL`. To target a different backend, change that constant at build time.
      */
     apiBaseUrl?: string;
 
@@ -271,9 +284,23 @@ export interface SimplifiedInitConfig {
     /** @deprecated Use desktopDebug instead. */
     debug?: DebugConnectionConfig;
 
-    /** Enable session replay capture. Default: true */
+    /** Enable session replay capture (feature on/off). Default: true */
     sessionReplay?: boolean;
 
+    /**
+     * Session-replay capture options (SaaS mode).
+     * - `record` (default **true**): auto-start frame recording at cold launch so replays appear out
+     *   of the box. Set `false` for events-only sessions — you can still record on demand with
+     *   `ScaleBun.startSession()`.
+     * - `captureMode` / `intervalMs` / `quality`: tune capture cadence.
+     */
+    replay?: {
+        record?: boolean;
+        captureMode?: 'navigation' | 'interactions' | 'frequency';
+        intervalMs?: number;
+        quality?: 'high' | 'normal' | 'low' | 'grayscale';
+    };
+
     /** SDK-wide privacy settings */
     privacy?: PrivacyConfig;