@scalebun/react-native 1.0.2 → 1.0.4

package/lib/typescript/features/ota/OtaOrchestrator.d.ts

@@ -1,4 +1,5 @@
 import type { OtaCheckResponse, OtaBundlePayload } from './OtaTypes';
+import { type SignatureConfig } from './signature';
 export interface SyncResult {
     status: 'UP_TO_DATE' | 'UPDATE_INSTALLED' | 'ROLLED_BACK' | 'ERROR';
     bundle?: OtaBundlePayload;
@@ -25,10 +26,48 @@ export declare class OtaOrchestrator {
     private isRestartRequiredState;
     private healthyTimer;
     private bootGuardConfig;
+    private signatureConfig;
+    private environment;
+    /** One-time boot checks have run in this process (init is idempotent). */
+    private initialized;
+    private storageBackend;
     /**
      * Initialize the orchestrator. Checks for boot-guard recovery state.
+     *
+     * `signature` is optional: an app that has not adopted signing keeps working
+     * on SHA-256 integrity alone. Once a public key IS configured, a bundle that
+     * cannot be verified is refused rather than installed (OTA-03).
+     */
+    init(config?: BootGuardConfig & {
+        signature?: SignatureConfig;
+    }): void;
+    /**
+     * Read the active slot back into `currentBundle` so the next check reports
+     * what this device is genuinely running.
+     */
+    private hydrateCurrentBundleFromSlots;
+    /**
+     * Compare the bundle the slot manager believes is active against the identity
+     * marker compiled into the bundle that actually loaded.
+     *
+     * A mismatch means the install path reported success while the runtime kept
+     * executing different code — the silent no-op this whole guard exists for.
+     * It is reported as APPLY_FAILED, because that is what happened, regardless
+     * of what the previous session's telemetry claimed.
+     *
+     * The expectation recorded at install time is what makes this conclusive.
+     * Without it, a missing marker is ambiguous — it could be a bundle published
+     * before markers existed, or an install that never took effect. Having
+     * written down "this bundle definitely carries marker X" before restarting,
+     * a missing marker afterwards can only mean the second.
      */
-    init(config?: BootGuardConfig): void;
+    private verifyRunningBundleIdentity;
+    private static readonly INSTALL_EXPECTATION_KEY;
+    private recordInstallExpectation;
+    private readInstallRecord;
+    private readInstallExpectation;
+    private clearInstallExpectation;
+    private storage;
     /**
      * Sprint 5 (S5-NAT-1): Check if the native boot guard reverted us on this cold start.
      * If getSlotState() shows bootMarkerPresent=false but we have a 'previous' slot
@@ -46,16 +85,26 @@ export declare class OtaOrchestrator {
         appVersion: string;
         installationId: string;
         channelName?: string;
+        country?: string;
+        attributes?: Record<string, string | number>;
+        segmentIds?: string[];
+        lifecycleStage?: string;
     }): Promise<OtaCheckResponse>;
     /**
      * Downloads, stage, and apply an update in one step.
      * Sprint 5: emits lifecycle events + starts boot-guard heartbeat.
      */
-    sync(params: {
+    sync(rawParams: {
         apiUrl: string;
         clientKey: string;
         appVersion: string;
-        installationId: string;
+        /** Omit to use the SDK's canonical per-install id (recommended — P8). */
+        installationId?: string;
+        channelName?: string;
+        country?: string;
+        attributes?: Record<string, string | number>;
+        segmentIds?: string[];
+        lifecycleStage?: string;
         autoRestart?: boolean;
     }): Promise<SyncResult>;
     /**
@@ -67,8 +116,31 @@ export declare class OtaOrchestrator {
      * marker stays set and native code reverts on next cold start.
      */
     private startBootGuardHeartbeat;
+    /** One-shot guard so repeated syncs cannot stack resume listeners. */
+    private resumeRestartArmed;
+    /**
+     * ON_NEXT_RESUME: restart the JS runtime the next time the app returns to
+     * the foreground after genuinely being in the background.
+     *
+     * The staged bundle is already applied at this point — the restart is purely
+     * about WHEN the user experiences the reload. Two deliberate choices:
+     *
+     *  - Armed only after a real background→active transition, never on the
+     *    initial 'active' state, so installing while the user is mid-session
+     *    does not instantly yank the screen out from under them.
+     *  - One-shot. The listener removes itself after firing (or after the
+     *    restart makes the whole question moot).
+     */
+    private armResumeRestart;
     /**
      * Reload the JS app bundle to apply the new update immediately.
+     *
+     * Order matters: the native `restartApp()` is the only path that works in
+     * RELEASE builds. `DevSettings.reload()` looks callable there too — it
+     * logged, returned, and reloaded nothing when tested live on a release APK,
+     * which made every "restart" this SDK ever promised a silent no-op in
+     * production. DevSettings remains as the dev-build fallback for hosts that
+     * have not rebuilt native yet.
      */
     restart(): void;
 }

package/lib/typescript/features/ota/OtaOrchestrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OtaOrchestrator.d.ts","sourceRoot":"","sources":["../../../../src/features/ota/OtaOrchestrator.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAmB,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGtF,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,YAAY,GAAG,kBAAkB,GAAG,aAAa,GAAG,OAAO,CAAC;IACpE,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,+BAA+B;AAC/B,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAKD,qBAAa,eAAe;IAC1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,aAAa,CAAiC;IACtD,OAAO,CAAC,sBAAsB,CAAS;IACvC,OAAO,CAAC,YAAY,CAA8C;IAClE,OAAO,CAAC,eAAe,CAAuB;IAE9C;;OAEG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,IAAI;IAepC;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAkB9B,SAAS,IAAI,OAAO;IAIpB,iBAAiB,IAAI,OAAO;IAI5B;;OAEG;IACG,cAAc,CAAC,aAAa,EAAE;QAClC,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAgC7B;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAE;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB,GAAG,OAAO,CAAC,UAAU,CAAC;IA8HvB;;;;;;;OAOG;IACH,OAAO,CAAC,uBAAuB;IAkC/B;;OAEG;IACH,OAAO,IAAI,IAAI;CAUhB;AAED,eAAO,MAAM,eAAe,iBAAwB,CAAC"}
+{"version":3,"file":"OtaOrchestrator.d.ts","sourceRoot":"","sources":["../../../../src/features/ota/OtaOrchestrator.ts"],"names":[],"mappings":"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"}

package/lib/typescript/features/ota/OtaTypes.d.ts

@@ -12,6 +12,29 @@ export interface OtaCheckRequest {
     installationId: string;
     currentBundleId?: string;
     currentBundleHash?: string;
+    /** Channel to pull from. Omitted means `default`. */
+    channelName?: string;
+    /** ISO 3166-1 alpha-2. The server fills this from the edge when absent. */
+    country?: string;
+    /** Free-form device attributes evaluated by ATTRIBUTE rules. */
+    attributes?: Record<string, string | number>;
+    /** CDP segment ids this installation belongs to. */
+    segmentIds?: string[];
+    /** Lifecycle stage (e.g. 'onboarding', 'activated', 'churned'). */
+    lifecycleStage?: string;
+    /** React Native version of the host binary, e.g. `"0.81.5"`. */
+    rnVersion?: string;
+    /** True when the JS engine is Hermes. */
+    hermes?: boolean;
+    /**
+     * Hermes bytecode (HBC) format version of the running engine. Independent of
+     * the RN release number. A mismatch either fails to load outright ("Wrong
+     * bytecode version. Expected 96 but got 98") or — worse — loads and crashes
+     * later on a path the older runtime does not expose.
+     */
+    hermesBytecodeVersion?: number;
+    /** True when running the New Architecture's bridgeless runtime. */
+    bridgeless?: boolean;
 }
 export interface OtaCheckResponse {
     action: 'NONE' | 'DOWNLOAD' | 'ROLLBACK';
@@ -25,8 +48,27 @@ export interface OtaBundlePayload {
     sha256: string;
     signature?: string;
     isMandatory: boolean;
+    /**
+     * How to activate the bundle after install:
+     *   ON_NEXT_RESTART — nothing to do now; next cold start loads it (default)
+     *   ON_NEXT_RESUME  — restart the JS runtime when the app next returns to
+     *                     the foreground after a background stay
+     *   IMMEDIATE       — restart the JS runtime right after install
+     * Absent means ON_NEXT_RESTART, which is what every pre-installMode release
+     * actually did.
+     */
+    installMode?: 'ON_NEXT_RESTART' | 'ON_NEXT_RESUME' | 'IMMEDIATE';
     releaseNote?: string;
     patch?: OtaPatchPayload;
+    /**
+     * Identity marker compiled into this bundle at publish time.
+     *
+     * Recorded at install; compared after restart against the marker the RUNNING
+     * bundle carries. Its PRESENCE is the important part — knowing a bundle
+     * definitely has a marker is what turns "no marker after restart" from
+     * ambiguous into proof that the install never took effect.
+     */
+    identityToken?: string;
 }
 export interface OtaPatchPayload {
     url: string;

package/lib/typescript/features/ota/OtaTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OtaTypes.d.ts","sourceRoot":"","sources":["../../../../src/features/ota/OtaTypes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,SAAS,GAAG,KAAK,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAGD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;IACzC,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB;AAGD,MAAM,MAAM,YAAY,GACpB,OAAO,GACP,kBAAkB,GAClB,mBAAmB,GACnB,WAAW,GACX,cAAc,GACd,eAAe,GACf,iBAAiB,CAAC;AAEtB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,YAAY,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB"}
+{"version":3,"file":"OtaTypes.d.ts","sourceRoot":"","sources":["../../../../src/features/ota/OtaTypes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,SAAS,GAAG,KAAK,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAS3B,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IAC7C,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;IAOxB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,mEAAmE;IACnE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAGD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;IACzC,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,iBAAiB,GAAG,gBAAgB,GAAG,WAAW,CAAC;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB;AAGD,MAAM,MAAM,YAAY,GACpB,OAAO,GACP,kBAAkB,GAClB,mBAAmB,GACnB,WAAW,GACX,cAAc,GACd,eAAe,GACf,iBAAiB,CAAC;AAEtB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,YAAY,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB"}

package/lib/typescript/features/ota/deviceAttributes.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Hardware/OS context auto-attached to OTA check payloads so ATTRIBUTE targeting
+ * rules can address device classes without any host-app wiring:
+ *
+ *   deviceModel  — 'SM-A155F', '23129RAA4G'… (Android; iOS does not expose it in JS)
+ *   manufacturer — 'samsung', 'xiaomi'… (lowercased: rules shouldn't fail on casing)
+ *   brand        — 'redmi' vs manufacturer 'xiaomi' — sub-brands are real segments
+ *   osVersion    — Android Release ('14') / iOS version ('17.5')
+ *   formFactor   — 'phone' | 'tablet' | 'tv' (Android tablets via the 600dp
+ *                  smallest-width convention — the same line AndroidX draws)
+ *
+ * Host-supplied attributes always win on key collision: an app that knows better
+ * (e.g. its own device tiering) must not be overridden by generic detection.
+ * Everything here is best-effort — a missing constant yields a missing key,
+ * never a guessed value.
+ */
+export declare function deviceTargetingAttributes(): Record<string, string>;
+//# sourceMappingURL=deviceAttributes.d.ts.map

package/lib/typescript/features/ota/deviceAttributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deviceAttributes.d.ts","sourceRoot":"","sources":["../../../../src/features/ota/deviceAttributes.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA2BlE"}

package/lib/typescript/features/ota/environment.d.ts

@@ -0,0 +1,99 @@
+/**
+ * OTA runtime environment detection.
+ *
+ * ── Why this file exists ────────────────────────────────────────────────────
+ *
+ * Our Android OTA resolves the active bundle through
+ * `MainApplication.getJSBundleFile()`. That is a *bridge-mode* API.
+ *
+ * Under the New Architecture (bridgeless), the app is built by
+ * `DefaultReactHost` instead — and until React Native 0.76.1,
+ * `DefaultReactNativeHost.toReactHost()` never forwarded `jsBundleFile`:
+ *
+ *     // RN 0.74.1 — DefaultReactNativeHost.kt
+ *     public fun toReactHost(context: Context): ReactHost =
+ *         DefaultReactHost.getDefaultReactHost(
+ *             context, packages, jsMainModuleName,
+ *             bundleAssetName ?: "index",   // <- jsBundleFile is NEVER passed
+ *             isHermesEnabled ?: true)
+ *
+ *     // RN 0.74.1 — DefaultReactHost.kt
+ *     val jsBundleLoader =
+ *         JSBundleLoader.createAssetLoader(context, "assets://$jsBundleAssetPath", true)
+ *
+ * The loader is hardcoded to the APK asset. `getJSBundleFile()` is never
+ * consulted, so an update stages, applies, reports INSTALLED, restarts — and
+ * the app loads the bundle baked into the APK. Every signal says success and
+ * nothing happened. This is the same failure that killed CodePush on modern RN.
+ *
+ * Fixed upstream in 0.76.1 (`jsBundleFile` is threaded through). Verified
+ * present in 0.81.5.
+ *
+ * We refuse to run rather than pretend to work. A loud failure at startup is
+ * recoverable; a silent no-op that reports success is not — it corrupts the
+ * adoption metrics, the guard thresholds, and every rollout decision made
+ * from them.
+ */
+/** First React Native version where bridgeless honours `getJSBundleFile()`. */
+export declare const MIN_BRIDGELESS_RN: {
+    readonly major: 0;
+    readonly minor: 76;
+    readonly patch: 1;
+};
+/**
+ * React Native 0.82 REMOVED `ReactNativeHost`. The New Architecture became
+ * mandatory and `newArchEnabled=false` was withdrawn, so the legacy
+ * `override fun getJSBundleFile()` integration does not merely stop working —
+ * it does not compile. From 0.82 the only correct integration is passing
+ * `jsBundleFilePath` straight to `getDefaultReactHost(...)`.
+ *
+ * We cannot see which integration a host app used, so this is not a block. It
+ * drives a startup hint, and the post-restart identity check is what actually
+ * catches a host that got it wrong.
+ */
+export declare const REACT_HOST_ONLY_RN: {
+    readonly major: 0;
+    readonly minor: 82;
+    readonly patch: 0;
+};
+export interface RnVersion {
+    major: number;
+    minor: number;
+    patch: number;
+}
+export interface OtaEnvironment {
+    /** Parsed React Native version, or null when it could not be determined. */
+    rnVersion: RnVersion | null;
+    /** `"0.76.1"`, or null. Sent to the backend for compatibility gating. */
+    rnVersionString: string | null;
+    /** True when running on the New Architecture's bridgeless runtime. */
+    bridgeless: boolean;
+    /** True when the JS engine is Hermes. */
+    hermes: boolean;
+    /**
+     * Hermes bytecode (HBC) format version of the *running* engine. This is the
+     * file-format compatibility number, NOT a React Native release number — the
+     * two move independently. A bundle compiled by a different hermesc can be
+     * rejected outright ("Wrong bytecode version. Expected 96 but got 98") or,
+     * worse, load fine and crash later on a path the older runtime lacks.
+     */
+    hermesBytecodeVersion: number | null;
+    /** False when OTA cannot work on this runtime and must not be enabled. */
+    supported: boolean;
+    /** Human-readable explanation when `supported` is false. */
+    blockReason: string | null;
+    /**
+     * True on RN >= 0.82, where `ReactNativeHost` no longer exists and the only
+     * valid integration is `getDefaultReactHost(..., jsBundleFilePath = …)`.
+     * Used to make the startup diagnostic name the right fix.
+     */
+    requiresReactHostIntegration: boolean;
+}
+/**
+ * Detect the runtime environment and decide whether OTA can function at all.
+ * Result is cached — none of these values change during a process lifetime.
+ */
+export declare function detectOtaEnvironment(): OtaEnvironment;
+/** Test seam — the detection result is process-lifetime cached. */
+export declare function _resetOtaEnvironmentCache(): void;
+//# sourceMappingURL=environment.d.ts.map

package/lib/typescript/features/ota/environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../../../src/features/ota/environment.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,iBAAiB;;;;CAA6C,CAAC;AAE5E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB;;;;CAA6C,CAAC;AAE7E,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5B,yEAAyE;IACzE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,sEAAsE;IACtE,UAAU,EAAE,OAAO,CAAC;IACpB,yCAAyC;IACzC,MAAM,EAAE,OAAO,CAAC;IAChB;;;;;;OAMG;IACH,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,0EAA0E;IAC1E,SAAS,EAAE,OAAO,CAAC;IACnB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B;;;;OAIG;IACH,4BAA4B,EAAE,OAAO,CAAC;CACvC;AA4DD;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,cAAc,CAyCrD;AAED,mEAAmE;AACnE,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/lib/typescript/features/ota/geoCountry.d.ts

@@ -0,0 +1,14 @@
+/** Override the lookup endpoint (e.g. a self-hosted Worker). */
+export declare function setGeoEndpoint(url: string): void;
+/**
+ * Synchronous read of the cached country (uppercase ISO 3166-1 alpha-2), or
+ * null when no fresh lookup has ever succeeded. Never triggers network.
+ */
+export declare function getDeviceCountry(): string | null;
+/**
+ * Refresh the cache from the Worker if stale. Fire-and-forget: call it at
+ * orchestrator init; the first check of a cold install may go out without a
+ * country (the server stores the country per device on later checks anyway).
+ */
+export declare function prefetchDeviceCountry(): Promise<void>;
+//# sourceMappingURL=geoCountry.d.ts.map

package/lib/typescript/features/ota/geoCountry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geoCountry.d.ts","sourceRoot":"","sources":["../../../../src/features/ota/geoCountry.ts"],"names":[],"mappings":"AAmCA,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAEhD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAShD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAwBrD"}

package/lib/typescript/features/ota/retry.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Retry with exponential backoff and full jitter.
+ *
+ * ── Why ─────────────────────────────────────────────────────────────────────
+ *
+ * The OTA path had no retry at all. A download that failed on a flaky mobile
+ * connection returned an error and the device then waited for the next cold
+ * start to try again — which on a phone is often hours, and on a device that
+ * is never fully restarted, effectively never. On mobile networks a single
+ * transient failure is the common case, not the exception.
+ *
+ * Full jitter (`random(0, backoff)` rather than `backoff`) matters more here
+ * than in most clients: every device on a release checks in against the same
+ * schedule, so a fixed backoff would retry the whole fleet in lockstep and
+ * turn one origin blip into a synchronised thundering herd.
+ */
+export interface RetryOptions {
+    /** Total attempts including the first. Default 3. */
+    attempts?: number;
+    /** Base delay in ms for the first backoff. Default 1000. */
+    baseDelayMs?: number;
+    /** Upper bound on any single delay. Default 30_000. */
+    maxDelayMs?: number;
+    /** Label used in log lines. */
+    label?: string;
+    /**
+     * Decides whether a given failure is worth retrying. Default: retry
+     * everything. Callers should pass a predicate that returns false for
+     * failures that will never succeed on a retry (4xx, hash mismatch), so a
+     * device does not burn battery re-requesting something already rejected.
+     */
+    isRetryable?: (err: unknown) => boolean;
+}
+/** Exposed for tests; `Math.random` is the only nondeterminism in the schedule. */
+export declare function backoffDelay(attemptIndex: number, baseDelayMs: number, maxDelayMs: number, random?: () => number): number;
+/**
+ * Run `fn`, retrying on failure with exponential backoff.
+ * Rethrows the last error once attempts are exhausted.
+ */
+export declare function retryWithBackoff<T>(fn: (attempt: number) => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * True for failures that a later attempt could plausibly survive.
+ *
+ * Network errors and 5xx/429 are retryable. A 4xx other than 429 is the server
+ * telling us the request itself is wrong — retrying it just wastes battery.
+ */
+export declare function isRetryableNetworkError(err: unknown): boolean;
+/** Error carrying an HTTP status so `isRetryableNetworkError` can classify it. */
+export declare class HttpStatusError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+//# sourceMappingURL=retry.d.ts.map

package/lib/typescript/features/ota/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../../src/features/ota/retry.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;CACzC;AAQD,mFAAmF;AACnF,wBAAgB,YAAY,CAC1B,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,MAAM,MAAoB,GACjC,MAAM,CAGR;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACnC,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,CAAC,CAAC,CAgCZ;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAU7D;AAED,kFAAkF;AAClF,qBAAa,eAAgB,SAAQ,KAAK;aAGtB,MAAM,EAAE,MAAM;gBAD9B,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM;CAKjC"}

package/lib/typescript/features/ota/signature.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Bundle signature verification (OTA-03).
+ *
+ * WHAT WAS WRONG. `ota-signing-key.service.ts` documents the intended model
+ * exactly: the CLI generates an ed25519 keypair locally, uploads only the public
+ * half, and "the device verifies every bundle's signature before install and
+ * rejects forgeries." Two of those three steps did not exist. The CLI had no
+ * signing code, and this SDK received `bundle.signature` in the check response
+ * and never read it. The only client-side check was SHA-256 against a hash
+ * delivered in the same response as the URL — which defends against a corrupted
+ * download and nothing else. On a platform whose entire purpose is remote code
+ * delivery, that is the control that matters most.
+ *
+ * WHY IT IS SHAPED LIKE THIS. The SDK ships zero third-party runtime
+ * dependencies, and React Native has no built-in ed25519. So verification is
+ * delegated to a host-provided verifier when one is installed, and the SDK's job
+ * is to decide — unambiguously — what happens when there is not one.
+ *
+ * THE POLICY, which is the important part:
+ *
+ *   - A bundle carrying a signature, with a configured public key and a
+ *     verifier: verified. Failure REJECTS the install. This is the goal state.
+ *   - A bundle carrying a signature, with a public key configured, but no
+ *     verifier available: REJECT. The app asked for signature enforcement by
+ *     configuring a key; silently installing unverified code because a helper is
+ *     missing would turn a security feature into a placebo.
+ *   - No public key configured: skip, and say so once. Signing is opt-in per app,
+ *     and an app that has not adopted it must keep working.
+ *
+ * The failure mode is the whole design: an app that opts in cannot be
+ * accidentally downgraded to unverified installs.
+ */
+/** Verifies a detached ed25519 signature. Supplied by the host app. */
+export type SignatureVerifier = (input: {
+    /** Hex-encoded SHA-256 of the bundle — what the signature is over. */
+    messageHex: string;
+    /** Hex or base64 detached signature from the check response. */
+    signature: string;
+    /** The app's configured ed25519 public key. */
+    publicKey: string;
+}) => boolean | Promise<boolean>;
+export interface SignatureConfig {
+    /** ed25519 public key shipped in the app binary. Absent = signing not adopted. */
+    publicKey?: string;
+    /** Host-provided ed25519 verification function. */
+    verifier?: SignatureVerifier;
+}
+export type SignatureOutcome = {
+    ok: true;
+    reason: 'verified' | 'not_configured';
+} | {
+    ok: false;
+    reason: 'no_verifier' | 'invalid_signature' | 'missing_signature' | 'verifier_threw';
+};
+/**
+ * Decide whether a bundle may be staged.
+ *
+ * Returns a structured outcome rather than a boolean so the caller can emit a
+ * precise telemetry reason — "we shipped unverified code because no key was
+ * configured" and "we refused because the signature was forged" are very
+ * different operational events and must not collapse into one.
+ */
+export declare function verifyBundleSignature(bundleSha256: string, signature: string | undefined, config: SignatureConfig | undefined): Promise<SignatureOutcome>;
+/** Test seam — resets the once-per-process "not configured" warning. */
+export declare function _resetSignatureWarnings(): void;
+//# sourceMappingURL=signature.d.ts.map

package/lib/typescript/features/ota/signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.d.ts","sourceRoot":"","sources":["../../../../src/features/ota/signature.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,uEAAuE;AACvE,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE;IACtC,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;CACnB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEjC,MAAM,WAAW,eAAe;IAC9B,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,UAAU,GAAG,gBAAgB,CAAA;CAAE,GACnD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,aAAa,GAAG,mBAAmB,GAAG,mBAAmB,GAAG,gBAAgB,CAAA;CAAE,CAAC;AAIxG;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,MAAM,EAAE,eAAe,GAAG,SAAS,GAClC,OAAO,CAAC,gBAAgB,CAAC,CA+C3B;AAED,wEAAwE;AACxE,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C"}

package/lib/typescript/features/ota/useOtaUpdate.d.ts

@@ -5,7 +5,22 @@ export interface UseOtaUpdateOptions {
     apiUrl: string;
     clientKey: string;
     appVersion: string;
-    installationId: string;
+    /**
+     * Omit to use the SDK's canonical per-install id (recommended). Supplying a
+     * different id here — the old docs suggested `deviceId` — put OTA telemetry
+     * in its own identity namespace, disconnected from every other SDK lane.
+     */
+    installationId?: string;
+    /** OTA channel to pull from. Omitted means `default`. */
+    channelName?: string;
+    /** ISO 3166-1 alpha-2. The server resolves this from the edge when absent. */
+    country?: string;
+    /** Free-form device attributes evaluated by ATTRIBUTE targeting rules. */
+    attributes?: Record<string, string | number>;
+    /** CDP segment ids this installation belongs to. */
+    segmentIds?: string[];
+    /** Lifecycle stage evaluated by LIFECYCLE_STAGE targeting rules. */
+    lifecycleStage?: string;
     autoRestart?: boolean;
     /**
      * When true and the server says `isMandatory`, the hook sets
@@ -45,7 +60,10 @@ export interface UseOtaUpdateReturn {
  *   apiUrl: 'https://api.scalebun.com/api/v1',
  *   clientKey: 'scalebun_ck_…',
  *   appVersion: '1.0.0',
- *   installationId: deviceId,
+ *   // installationId is resolved from the SDK's own persisted install id —
+ *   // do NOT pass deviceId here (the old example did; it split OTA telemetry
+ *   // into a separate identity namespace from every other lane).
+ *   channelName: 'production',
  *   mandatoryBlocksUi: true,
  * });
  * ```

package/lib/typescript/features/ota/useOtaUpdate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useOtaUpdate.d.ts","sourceRoot":"","sources":["../../../../src/features/ota/useOtaUpdate.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAmB,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE9D,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,SAAS,EAAE,OAAO,CAAC;IACnB,qEAAqE;IACrE,iBAAiB,EAAE,OAAO,CAAC;IAC3B,sDAAsD;IACtD,YAAY,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACtC,wCAAwC;IACxC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,uDAAuD;IACvD,gBAAgB,EAAE,MAAM,CAAC;IACzB,4CAA4C;IAC5C,SAAS,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3B,+EAA+E;IAC/E,sBAAsB,EAAE,OAAO,CAAC;IAChC,0BAA0B;IAC1B,IAAI,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC;IAChC,0CAA0C;IAC1C,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CA6E7E"}
+{"version":3,"file":"useOtaUpdate.d.ts","sourceRoot":"","sources":["../../../../src/features/ota/useOtaUpdate.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAmB,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE9D,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IAC7C,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,SAAS,EAAE,OAAO,CAAC;IACnB,qEAAqE;IACrE,iBAAiB,EAAE,OAAO,CAAC;IAC3B,sDAAsD;IACtD,YAAY,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACtC,wCAAwC;IACxC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,uDAAuD;IACvD,gBAAgB,EAAE,MAAM,CAAC;IACzB,4CAA4C;IAC5C,SAAS,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3B,+EAA+E;IAC/E,sBAAsB,EAAE,OAAO,CAAC;IAChC,0BAA0B;IAC1B,IAAI,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC;IAChC,0CAA0C;IAC1C,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CA6E7E"}

package/lib/typescript/features/performance/PerformanceFeature.d.ts

@@ -42,7 +42,6 @@ export declare class PerformanceFeature implements IFeature {
     private static readonly CAPTURE_MAX_RETRIES;
     /** Delay schedule for each attempt (ms) — escalating to let views settle */
     private static readonly CAPTURE_DELAYS;
-    private trackFn;
     constructor(config?: Partial<PerformanceConfig>);
     initialize(context: FeatureContext): Promise<void>;
     /** Activate native performance module once (no-throw if unavailable). */

package/lib/typescript/features/performance/PerformanceFeature.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PerformanceFeature.d.ts","sourceRoot":"","sources":["../../../../src/features/performance/PerformanceFeature.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"PerformanceFeature.d.ts","sourceRoot":"","sources":["../../../../src/features/performance/PerformanceFeature.ts"],"names":[],"mappings":"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"}

package/lib/typescript/features/performance/collectors/FrameMetricsCollector.d.ts

@@ -19,8 +19,41 @@ export declare class FrameMetricsCollector {
     private contextProvider;
     private eventSubscription;
     private running;
+    /** AppState subscription — see `_installAppStateGate`. */
+    private appStateSubscription;
+    /** True while the native sampler is actually running (i.e. armed AND foregrounded). */
+    private sampling;
     constructor(config: PerformanceConfig, onFrameMetrics: FrameMetricsCallback, contextProvider: () => PerfContext);
     start(): void;
+    /**
+     * Pause sampling while the app is backgrounded.
+     *
+     * THE BUG THIS FIXES. `startFrameMetrics` hands off to a native loop that runs until something
+     * calls `stopFrameMetrics`. Nothing did. The collector had no AppState awareness at all — unlike
+     * `AutoScreenLoadCollector`, which has subscribed to it since it was written — so once a session
+     * was sampled in, it kept sampling for as long as the PROCESS lived, not as long as the app was
+     * being used.
+     *
+     * Measured in production: sessions with `durationMs` of 86,400,000 (exactly 24h) and 70,797,000
+     * (~19.7h) carrying 39,766 and 3,709 frame samples against 0 and 6 real gestures respectively.
+     * `frame_metrics` was 75% of ALL mobile events for this reason.
+     *
+     * The `tier2SampleRate` knob does not help here: it gates WHICH sessions collect, not how long
+     * they collect for. A sampled-in session that gets backgrounded still samples for hours, which is
+     * why lowering it would have hidden the symptom while leaving the cause.
+     *
+     * It is also a DATA-QUALITY fix, not only a volume one. Frame timings from a backgrounded app
+     * describe a screen nobody is looking at, and they were feeding the low-FPS KPI and jank
+     * detection — so the noise was not merely stored, it was being reported as UI performance.
+     *
+     * NOTE: on iOS the OS already stops delivering CADisplayLink callbacks on background, so the
+     * practical effect is largest on Android. Gating in JS keeps the two platforms behaving the same
+     * either way, rather than relying on an OS side effect that is not part of any contract.
+     */
+    private _installAppStateGate;
+    /** Idempotent — AppState can fire 'active' more than once without an intervening background. */
+    private _startNativeSampler;
+    private _stopNativeSampler;
     stop(): void;
     private _handleNativeFrameMetrics;
 }

package/lib/typescript/features/performance/collectors/FrameMetricsCollector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FrameMetricsCollector.d.ts","sourceRoot":"","sources":["../../../../../src/features/performance/collectors/FrameMetricsCollector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAEhE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAEtE,qBAAa,qBAAqB;IAC9B,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,eAAe,CAAoB;IAC3C,OAAO,CAAC,iBAAiB,CAAa;IACtC,OAAO,CAAC,OAAO,CAAS;gBAGpB,MAAM,EAAE,iBAAiB,EACzB,cAAc,EAAE,oBAAoB,EACpC,eAAe,EAAE,MAAM,WAAW;IAOtC,KAAK,IAAI,IAAI;IA6Bb,IAAI,IAAI,IAAI;IAiBZ,OAAO,CAAC,yBAAyB;CAkCpC"}
+{"version":3,"file":"FrameMetricsCollector.d.ts","sourceRoot":"","sources":["../../../../../src/features/performance/collectors/FrameMetricsCollector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAEhE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAEtE,qBAAa,qBAAqB;IAC9B,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,eAAe,CAAoB;IAC3C,OAAO,CAAC,iBAAiB,CAAa;IACtC,OAAO,CAAC,OAAO,CAAS;IACxB,0DAA0D;IAC1D,OAAO,CAAC,oBAAoB,CAAwC;IACpE,uFAAuF;IACvF,OAAO,CAAC,QAAQ,CAAS;gBAGrB,MAAM,EAAE,iBAAiB,EACzB,cAAc,EAAE,oBAAoB,EACpC,eAAe,EAAE,MAAM,WAAW;IAOtC,KAAK,IAAI,IAAI;IA2Bb;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CAAC,oBAAoB;IAS5B,gGAAgG;IAChG,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,kBAAkB;IAa1B,IAAI,IAAI,IAAI;IAgBZ,OAAO,CAAC,yBAAyB;CAkCpC"}

package/lib/typescript/features/performance/transport/PerformanceTransport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PerformanceTransport.d.ts","sourceRoot":"","sources":["../../../../../src/features/performance/transport/PerformanceTransport.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAClF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAGnD,iFAAiF;AACjF,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,YAAY,IAAI,MAAM,CAAC;IACvB,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;CAC5B;AAID,qBAAa,oBAAoB;IAC7B,OAAO,CAAC,IAAI,CAAkC;IAC9C,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,MAAM,CAAiB;gBAEnB,MAAM,EAAE,iBAAiB;IAIrC,+CAA+C;IAC/C,OAAO,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,GAAG,IAAI;IAW7C,wDAAwD;IACxD,OAAO,IAAI,iBAAiB,GAAG,IAAI;IAInC,2DAA2D;IAC3D,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAmBpC,6EAA6E;IAC7E,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAmB3F,0DAA0D;IAC1D,gBAAgB,CAAC,OAAO,EAAE,cAAc,GAAG;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAkBvE,+BAA+B;IAC/B,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAY9C,OAAO,CAAC,KAAK;IAkBb,mBAAmB;IACnB,KAAK,IAAI,IAAI;CAGhB"}
+{"version":3,"file":"PerformanceTransport.d.ts","sourceRoot":"","sources":["../../../../../src/features/performance/transport/PerformanceTransport.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAClF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAGnD,iFAAiF;AACjF,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,YAAY,IAAI,MAAM,CAAC;IACvB,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;CAC5B;AAID,qBAAa,oBAAoB;IAC7B,OAAO,CAAC,IAAI,CAAkC;IAC9C,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,MAAM,CAAiB;gBAEnB,MAAM,EAAE,iBAAiB;IAIrC,+CAA+C;IAC/C,OAAO,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,GAAG,IAAI;IAW7C,wDAAwD;IACxD,OAAO,IAAI,iBAAiB,GAAG,IAAI;IAInC,2DAA2D;IAC3D,SAAS,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI;IAmBpC,6EAA6E;IAC7E,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAqC3F,0DAA0D;IAC1D,gBAAgB,CAAC,OAAO,EAAE,cAAc,GAAG;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAkBvE,+BAA+B;IAC/B,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAY9C,OAAO,CAAC,KAAK;IAkBb,mBAAmB;IACnB,KAAK,IAAI,IAAI;CAGhB"}