@scalebun-release/react-native 2.5.0

package/lib/typescript/analytics/automaticEvents.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Canonical automatic-event bus.
+ *
+ * Every zero-instrumentation collector publishes here. EventTracker subscribes
+ * once and turns the observations into the same signed `/batch` envelopes used
+ * by public `track()` calls. Keeping collectors transport-agnostic prevents
+ * lifecycle/navigation/push/Engage from growing parallel ingestion lanes.
+ */
+export type AutomaticEventName = 'app_foregrounded' | 'app_backgrounded' | 'screen_viewed'
+/** Device rotated. Absent entirely before — a layout-driven drop-off was invisible on mobile. */
+ | 'orientation_changed'
+/** The OS warned the app it is under memory pressure — the leading indicator before an OOM kill. */
+ | 'memory_warning' | 'deep_link_opened' | 'element_interacted'
+/** An opt-in element was on screen long enough to count as seen (<ScaleBunImpression>). */
+ | 'element_viewed'
+/** An OS permission was granted or denied — the missing step in every mobile growth funnel. */
+ | 'permission_result' | 'push_received' | 'push_opened' | 'in_app_displayed' | 'in_app_clicked' | 'in_app_dismissed' | 'in_app_completed' | 'in_app_interaction' | 'in_app_render_failed' | 'in_app_cta_open_failed' | 'rating_prompt_eligible' | 'rating_prompt_shown' | 'rating_selected' | 'rating_prompt_dismissed' | 'store_redirect_clicked';
+export interface AutomaticEvent {
+    name: AutomaticEventName;
+    properties: Record<string, unknown>;
+    /** Original observation time. Delivery can be delayed while native coordinates resolve. */
+    timestamp?: number;
+}
+type AutomaticEventListener = (event: AutomaticEvent) => void;
+export declare function emitAutomaticEvent(name: AutomaticEventName, properties?: Record<string, unknown>, timestamp?: number): void;
+export declare function subscribeAutomaticEvents(listener: AutomaticEventListener): () => void;
+/** Test-only reset; intentionally not exported from the package entry point. */
+export declare function resetAutomaticEventsForTests(): void;
+export {};
+//# sourceMappingURL=automaticEvents.d.ts.map

package/lib/typescript/analytics/batching.d.ts

@@ -0,0 +1,33 @@
+/**
+ * ScaleBun SDK — batch chunking contract (Phase 3 / Wave 1).
+ *
+ * The backend rejects any `/batch` request whose `events.length` exceeds
+ * MAX_BATCH_EVENTS with HTTP 413 BATCH_TOO_LARGE (accepted:0, rejected:all).
+ * The old backend behaviour silently sliced to the first 500 and 202'd — a
+ * silent data-loss defect. Now that the server rejects, the SDK must NEVER
+ * emit an oversized batch; it splits its queue into chunks of at most this
+ * value, preserving eventIds, ordering, identifiers, and timestamps.
+ *
+ * This constant MUST equal `MAX_BATCH_EVENTS` in the backend
+ * (scalebun-dashboard-backend/src/features/ingestion-v1/constants.ts).
+ * The shared contract test (`__tests__/batchChunking.test.ts`) pins the
+ * value so the two sides cannot drift.
+ */
+export declare const MAX_BATCH_EVENTS = 500;
+/**
+ * Split a list into contiguous chunks of at most `size`, preserving order.
+ * A queue of N items yields ceil(N/size) chunks; every chunk is <= size and
+ * only the last may be shorter. No item is dropped, duplicated, or reordered.
+ */
+export declare function chunkEvents<T>(events: readonly T[], size?: number): T[][];
+/** Clamp a caller-configured batch size into the server-safe range [1, MAX_BATCH_EVENTS]. */
+export declare function clampBatchSize(configured: number | undefined, fallback: number): number;
+/**
+ * Wave 2 (§2F.2): a STABLE batch idempotency key derived from the batch's event
+ * ids. The same leading events produce the same key across transient retries, so
+ * the server replays the first response instead of re-counting accepts; a changed
+ * batch produces a different key. Non-cryptographic (FNV-1a) — this is a dedup
+ * label, not a security token. The per-event id remains the true dedup anchor.
+ */
+export declare function batchIdempotencyKey(eventIds: readonly string[]): string;
+//# sourceMappingURL=batching.d.ts.map

package/lib/typescript/analytics/eventLane.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ScaleBun SDK — event lane routing.
+ *
+ * A tracked event goes to exactly one of two lanes:
+ *  - `analytics`: product events (public, non-`$`) → EventTracker → `/batch`
+ *    → raw_events → events. These are the rows a customer queries/visualizes.
+ *  - `session`: SDK-internal signals (`$`-prefixed: `$log`, `$network_request`,
+ *    `$perf_event`, `$internal_event`, …) → session/replay/debug lane only.
+ *    They must NOT enter the analytics `events` table.
+ *
+ * The `$` prefix is the single source of truth for this split. Keeping the
+ * decision in one pure function keeps the facade and any tooling in agreement
+ * and makes the split unit-testable without the native runtime.
+ */
+export type EventLane = 'analytics' | 'session';
+/** True for SDK-internal (`$`-prefixed) signals that ride the session lane only. */
+export declare function isSessionLaneEvent(name: string): boolean;
+/** Resolve the destination lane for a tracked event name. */
+export declare function resolveEventLane(name: string): EventLane;
+/** Should this tracked event be uploaded to the session-events lane at all? */
+export declare function isUploadedSessionEvent(name: string): boolean;
+//# sourceMappingURL=eventLane.d.ts.map

package/lib/typescript/analytics/revenue.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Revenue modelling for the mobile SDK — the twin of `revenue.ts` in the web SDK.
+ *
+ * WHY THIS EXISTS AT ALL. `trackPurchase` used to be three fields and a spread:
+ * `revenue`, `currency`, `transactionId`, everything else passed through
+ * untouched. That was fine while revenue was one number on a dashboard card, and
+ * it is not fine now that the Business section bridges gross to net, splits by
+ * plan, and separates refunds from charges. Three concrete consequences of the
+ * old shape, all silent:
+ *
+ *   1. A REFUND COUNTED AS A SALE. The web SDK stores a refund as a NEGATIVE
+ *      amount; mobile stored whatever sign the caller used. An app sending
+ *      `{ revenue: 30, type: 'refund' }` from iOS added $30 to GROSS revenue and
+ *      to the customer's lifetime value. Same call from the browser subtracted
+ *      it. Nothing reported the disagreement.
+ *   2. NO PLAN ATTRIBUTION. `productId` was not mapped to the `product_id`
+ *      property the rollup groups by, so every mobile sale landed in the
+ *      "Unattributed" bucket of "Top plans by revenue".
+ *   3. ADJUSTMENTS WERE UNVALIDATED. A store commission sent as the string
+ *      "0.30" reached the aggregate, failed its numeric check there, and was
+ *      dropped with no error — so mobile net revenue was quietly overstated by
+ *      the size of the app store's cut.
+ *
+ * The shapes and the property names here are the web SDK's, deliberately: both
+ * write into one `events` table that one rollup reads. A field named differently
+ * on one platform is a field that platform does not have.
+ *
+ * No third-party dependency, browser API or React import — this is pure data
+ * transformation, callable from the tracker and directly testable.
+ */
+/**
+ * What KIND of money movement this is.
+ *
+ * `dispute` and `adjustment` exist for the transaction ledger, which has to
+ * separate them: a chargeback is money taken back by the bank and an adjustment
+ * is a correction someone made, and lumping either into `refund` makes a refund
+ * rate that cannot be acted on.
+ *
+ * SIGN CONVENTION, matching the web SDK exactly:
+ *   refund, dispute  ALWAYS stored negative — money left, whatever sign the
+ *                    caller used.
+ *   adjustment       keeps the CALLER's sign; it is the one kind that
+ *                    legitimately goes either way (a credit or a debit).
+ */
+export type RevenueType = 'one_time' | 'subscription' | 'refund' | 'dispute' | 'adjustment';
+export interface RevenueInput {
+    /** Amount in `currency`. For refunds and disputes pass the positive amount; it is stored negative. */
+    revenue: number;
+    /** ISO-4217 currency; normalized to upper-case. */
+    currency: string;
+    /** Idempotency key — the backend dedups by (appId, transactionId). */
+    transactionId: string;
+    /** Revenue kind. Default 'one_time'. */
+    type?: RevenueType;
+    /** SKU / plan id. This is what "Top plans by revenue" groups by. */
+    productId?: string;
+    /** Human-readable SKU / plan name. Sent as `product_name` for Business plan attribution. */
+    productName?: string;
+    quantity?: number;
+    /** Billing cadence for subscriptions (e.g. 'monthly' | 'yearly'). */
+    recurrence?: string;
+    /**
+     * What came OUT of the charge before it was yours — the gross-to-net bridge.
+     *
+     * Each is a POSITIVE amount in `currency`, deducted from gross to produce net.
+     * On mobile `fee` is usually the store's 15/30% commission, which is the
+     * single largest reason a mobile net figure differs from its gross one.
+     *
+     * A missing adjustment is treated as ABSENT, not as zero: net then does not
+     * claim a precision the payload did not carry. Sending `tax: 0` for a
+     * zero-rated sale is a different, and stronger, statement than sending nothing.
+     */
+    tax?: number;
+    fee?: number;
+    discount?: number;
+    [k: string]: unknown;
+}
+export interface NormalizedRevenue {
+    revenue: number;
+    currency: string;
+    props: Record<string, unknown>;
+}
+/** Upper-case a 3-letter ISO-like code; return an empty string when invalid. */
+export declare function normalizeCurrency(c: string): string;
+export declare function validBusinessAmount(value: unknown): value is number;
+/**
+ * Validate and normalize a revenue event into a top-level amount/currency plus
+ * folded properties. Returns null — a DROP — when a required field is missing or
+ * unusable, because a purchase without an idempotency key cannot be deduplicated,
+ * one without a currency cannot be added to anything, and silently dropping an
+ * invalid explicit fee/tax/discount would overstate net revenue.
+ */
+export declare function normalizeRevenue(input: RevenueInput): NormalizedRevenue | null;
+//# sourceMappingURL=revenue.d.ts.map

package/lib/typescript/analytics/subscription.d.ts

@@ -0,0 +1,35 @@
+/** Backend subscription-ledger wire contract. Additive fields require a new version. */
+export declare const SUBSCRIPTION_SCHEMA_VERSION = 3;
+export type SubscriptionStatus = 'trial_started' | 'trial_converted' | 'started' | 'renewed' | 'plan_changed' | 'cancel_scheduled' | 'resumed' | 'canceled' | 'expired' | 'payment_failed' | 'refunded';
+/** Stable cancellation taxonomy shared by React Native, Web and the dashboard. */
+export type CancellationReason = 'too_expensive' | 'no_longer_needed' | 'competitive_offer' | 'missing_features' | 'poor_experience' | 'payment_issue' | 'other';
+export interface SubscriptionPlan {
+    id?: string;
+    name?: string;
+    amount: number;
+    currency: string;
+    interval: 'day' | 'week' | 'month' | 'year';
+    intervalCount?: number;
+}
+export interface SubscriptionInput {
+    /** Stable subscription identity, scoped to the current app/environment. */
+    subscriptionId: string;
+    /**
+     * Optional stable identity for this lifecycle change. Reuse it when the host repeats the same
+     * logical call; the backend keeps the first accepted payload. A missing key falls back to the
+     * SDK envelope event id, so transport retries remain idempotent either way.
+     */
+    subscriptionEventId?: string;
+    status: SubscriptionStatus;
+    /** Optional structured reason for cancel_scheduled/canceled/expired events. */
+    cancellationReason?: CancellationReason;
+    /** Optional free-text detail; bounded before it enters the event ledger. */
+    cancellationComment?: string;
+    plan?: SubscriptionPlan;
+    trialEndAt?: string | Date;
+    effectiveAt?: string | Date;
+    properties?: Record<string, unknown>;
+}
+/** Validate and build the canonical `$subscription` event properties. */
+export declare function normalizeSubscription(input: SubscriptionInput): Record<string, unknown> | null;
+//# sourceMappingURL=subscription.d.ts.map

package/lib/typescript/bootstrap/FeatureRegistry.d.ts

@@ -0,0 +1,36 @@
+/**
+ * ScaleBun SDK — Feature Registry
+ *
+ * Central registry for SDK feature modules.
+ * Manages feature registration, initialization order, and lifecycle teardown.
+ *
+ * SOLID: Single Responsibility — only manages feature lifecycle.
+ * SOLID: Dependency Inversion — depends on IFeature abstraction.
+ */
+import type { IFeature, FeatureContext } from '../core/contracts/IFeature';
+export declare class FeatureRegistry {
+    private features;
+    private initialized;
+    /**
+     * Register a feature. Must be called before `initializeAll()`.
+     * Duplicate registrations are silently ignored (idempotent).
+     */
+    register(feature: IFeature): void;
+    /**
+     * Initialize all registered features with the provided context.
+     * Features that fail to initialize are logged but don't break others.
+     */
+    initializeAll(context: FeatureContext): Promise<void>;
+    /**
+     * Tear down all features in reverse registration order.
+     * Safe to call even if not initialized.
+     */
+    teardownAll(): void;
+    /** Get a feature by name */
+    get(name: string): IFeature | undefined;
+    /** Check if a feature is registered and active */
+    isFeatureActive(name: string): boolean;
+    /** Get all registered feature names */
+    getRegisteredFeatures(): string[];
+}
+//# sourceMappingURL=FeatureRegistry.d.ts.map

package/lib/typescript/bootstrap/SDKBootstrapper.d.ts

@@ -0,0 +1,82 @@
+/**
+ * ScaleBun SDK — SDK Bootstrapper
+ *
+ * Encapsulates the core SDK initialization sequence.
+ * Called by ScaleBunFacade.init() — this is the single real init path.
+ *
+ * Responsibilities:
+ * - Config validation and merge with defaults
+ * - Core service setup (HttpClient, Dispatcher, FlushScheduler)
+ * - Backend handshake
+ * - Feature registration and initialization via FeatureRegistry
+ * - App lifecycle wiring
+ *
+ * Returns null on failure (handshake fail, invalid config) to allow
+ * the Facade to handle gracefully without crashing.
+ */
+import { type ScaleBunConfig } from '../core/config/schema';
+import { FeatureRegistry } from './FeatureRegistry';
+import type { ScaleBunFeatures } from '../public/types';
+export interface BootstrapResult {
+    config: ScaleBunConfig;
+    featureRegistry: FeatureRegistry;
+}
+export declare class SDKBootstrapper {
+    private featureRegistry;
+    private config;
+    private _backgroundedAt;
+    private _orientationSub;
+    /** quotaState subscription that re-opens a session when a `sessions` block lifts. */
+    private _sessionsQuotaUnsub;
+    /**
+     * Set when a `sessions` block lifted while the app was NOT in the foreground (or before the
+     * adapter could open a session). Honored on the next foreground: the analytics session opens there
+     * anyway, but recording would otherwise only restart with finalizeOnBackground.
+     */
+    private _recordAfterSessionsUnblock;
+    /** Whether cold-launch auto-record applies (replay.record !== false); set when the adapter is built. */
+    private _autoRecord;
+    private _lastOrientation;
+    private _memorySub;
+    private _deepLinkUnsubscribe;
+    /**
+     * Run the full SDK initialization sequence.
+     *
+     * Returns BootstrapResult on success, null on failure.
+     * Never throws — all errors are caught and logged.
+     *
+     * @param rawConfig - Raw user-provided config (validated via the internal protocol validator)
+     * @param trackFn  - Function to track events (from Facade)
+     * @param flushFn  - Function to flush events (from Facade)
+     * @param features - Feature flags (all default true — opt-out model)
+     */
+    bootstrap(rawConfig: unknown, trackFn: (name: string, payload?: Record<string, unknown>) => void, flushFn: () => Promise<void>, features?: ScaleBunFeatures): Promise<BootstrapResult | null>;
+    /**
+     * Build the minimal Session the analytics lane needs. sendSessionStart only
+     * reads sessionId/deviceId/startedAt/metadata; device detail is enriched from
+     * the native bridge at upload time, so this stays minimal.
+     */
+    /**
+     * Emit `orientation_changed` when the device actually rotates.
+     *
+     * There was no orientation signal at all, so a drop-off caused by a broken landscape layout was
+     * invisible — the funnel showed users leaving and nothing explained why. Dimensions fires on any
+     * metric change (keyboard, split-view, font scale), so the event is emitted only when the
+     * portrait/landscape VERDICT flips; otherwise a keyboard open would look like a rotation.
+     */
+    private installOrientationTracking;
+    /**
+     * Emit `memory_warning` when the OS signals memory pressure.
+     *
+     * This is the leading indicator before an OOM kill, and the crash side was already built — so the
+     * warning that precedes the crash was the missing half. Android-only via RN's `appState`-adjacent
+     * `memoryWarning` event; iOS surfaces it through the same emitter when the native module forwards it.
+     */
+    private installMemoryWarningTracking;
+    private _buildAnalyticsSession;
+    /** Get the validated config */
+    getConfig(): ScaleBunConfig | null;
+    /** Tear down all features */
+    teardown(): void;
+}
+//# sourceMappingURL=SDKBootstrapper.d.ts.map

package/lib/typescript/bucketing/fnv1a32.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 declare function fnv1a32(str: string): number;
+/** Stable 0..99 bucket for an install within an experiment/rollout (salt is immutable). */
+export declare function bucketOf(installationId: string, salt: string): number;
+/**
+ * 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 declare function pickVariant(installationId: string, salt: string, variants: Array<{
+    key: string;
+    allocationPct: number;
+}>): string | null;
+//# sourceMappingURL=fnv1a32.d.ts.map

package/lib/typescript/compat/codepush.d.ts

@@ -0,0 +1,76 @@
+export declare enum CodePushInstallMode {
+    IMMEDIATE = 0,
+    ON_NEXT_RESTART = 1,
+    ON_NEXT_RESUME = 2,
+    ON_NEXT_SUSPEND = 3
+}
+export declare enum CodePushSyncStatus {
+    UP_TO_DATE = 0,
+    UPDATE_INSTALLED = 1,
+    UPDATE_IGNORED = 2,
+    UNKNOWN_ERROR = 3,
+    CHECKING_FOR_UPDATE = 4,
+    DOWNLOADING_PACKAGE = 5,
+    INSTALLING_UPDATE = 6
+}
+export interface CodePushOptions {
+    checkFrequency?: number;
+    installMode?: CodePushInstallMode;
+    mandatoryInstallMode?: CodePushInstallMode;
+    minimumBackgroundDuration?: number;
+}
+export interface CodePushPackage {
+    appVersion: string;
+    deploymentKey: string;
+    description: string;
+    failedInstall: boolean;
+    isFirstRun: boolean;
+    isMandatory: boolean;
+    isPending: boolean;
+    label: string;
+    packageHash: string;
+    packageSize: number;
+}
+/**
+ * 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 });
+ */
+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;
+}
+/** Point the shim at a real backend. Required before sync/checkForUpdate. */
+export declare function configureCodePushShim(config: CodePushShimConfig): void;
+declare const codePushShim: {
+    <P>(rootComponent: React.ComponentType<P>): import("react").ComponentType<P>;
+    sync(options?: CodePushOptions, syncStatusCallback?: (status: CodePushSyncStatus) => void, downloadProgressCallback?: (progress: {
+        receivedBytes: number;
+        totalBytes: number;
+    }) => void): Promise<CodePushSyncStatus>;
+    checkForUpdate(): Promise<CodePushPackage | null>;
+    disallowRestart(): void;
+    allowRestart(): void;
+    getUpdateMetadata(): Promise<CodePushPackage | null>;
+};
+export default codePushShim;
+//# sourceMappingURL=codepush.d.ts.map

package/lib/typescript/config/ConfigManager.d.ts

@@ -0,0 +1,82 @@
+export interface ConfigManagerDeps {
+    apiBaseUrl: string;
+    clientKey: string;
+    installationId: string;
+    /** Emit an exposure event (→ EventTracker.track('experiment_exposure', …)). */
+    emitExposure: (experiment: string, variant: string) => void;
+    /** Stamp a persistent property onto all subsequent events (→ EventTracker.stamp). */
+    stamp: (key: string, value: string) => void;
+    /**
+     * Called after each refresh with the current admin replay-capture override (or null when
+     * absent/withdrawn). The facade uses it to apply/revert timer capture on the native side.
+     * Optional so non-replay consumers (and tests) can omit it.
+     */
+    onReplayCapture?: (override: {
+        mode: 'frequency';
+        intervalMs: number;
+    } | null) => void;
+}
+export declare class ConfigManager {
+    private readonly deps;
+    private storage;
+    private payload;
+    private exposed;
+    private lastFetch;
+    private inflight;
+    private inflightForced;
+    constructor(deps: ConfigManagerDeps);
+    /**
+     * 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?: {
+        force?: boolean;
+    }): Promise<void>;
+    private doRefresh;
+    /**
+     * 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(): void;
+    isEnabled(key: string): boolean;
+    get<T = any>(key: string, fallback: T): T;
+    rolloutIsOn(key: string): boolean;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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(): {
+        mode: 'frequency';
+        intervalMs: number;
+    } | 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(): Record<string, boolean>;
+    variant(key: string): string | null;
+    private loadCached;
+    private loadExposed;
+    private persistExposed;
+}
+//# sourceMappingURL=ConfigManager.d.ts.map

package/lib/typescript/config/configTypes.d.ts

@@ -0,0 +1,73 @@
+import type { QuotaConfigBlock } from './quotaState';
+export interface SdkConfigPayload {
+    version: string;
+    flags: Array<{
+        key: string;
+        enabled: boolean;
+    }>;
+    remoteConfig: Array<{
+        key: string;
+        value: string;
+        type: string;
+    }>;
+    experiments: Array<{
+        key: string;
+        salt: string;
+        goalEventName: string | null;
+        variants: Array<{
+            key: string;
+            allocationPct: number;
+        }>;
+    }>;
+    rollouts: Array<{
+        key: string;
+        salt: string;
+        percentage: number;
+    }>;
+    /**
+     * Super-Admin Phase 3: the org's effective entitlements for the SDK-suppressible
+     * features. When a feature is false the SDK doesn't register its collector (no
+     * traffic → no server cost). Optional + fail-open: absent ⇒ treat as entitled.
+     */
+    entitlements?: {
+        replay?: boolean;
+        networkMonitoring?: boolean;
+        crashReporting?: boolean;
+        performanceMonitoring?: boolean;
+    };
+    /**
+     * Admin-controlled replay capture override (super-admin, per app). Present only when a
+     * super-admin has forced timer-based capture; ABSENT otherwise. When present the SDK switches
+     * replay to `frequency` at `intervalMs`, overriding the developer's local captureMode; when it
+     * disappears the SDK reverts to the developer's configured mode. Frequency is intentionally not
+     * developer-settable — this is the only path that can turn it on.
+     */
+    replayCapture?: {
+        mode: 'frequency';
+        intervalMs: number;
+    };
+    /**
+     * Per-feature quota state (shared contract v1, §1). Only BLOCKED features appear under `blocked`.
+     * Absent on an older backend — the SDK then keeps its last persisted quota state. Applied through
+     * `quotaState.applyConfig`; lanes never read it from here.
+     */
+    quota?: QuotaConfigBlock;
+    /**
+     * OTA policy the server sets, so a customer can change it without an app release.
+     *
+     * ABSENT means unset, and the SDK falls back to its own build-time config — which
+     * is how every app behaved before this field existed. A server value can only ever
+     * TIGHTEN: it cannot switch off a withhold the app itself asked for. Loosening a
+     * security setting from outside the binary is the wrong direction.
+     *
+     * Delivered here rather than on the OTA check response because a withholding
+     * device never makes that request — it short-circuits before the network call, so
+     * a policy carried there could only be learned by a device that had already
+     * disobeyed it. This payload is cached to disk, so the policy survives launches.
+     */
+    ota?: {
+        onCompromisedDevice?: 'allow' | 'withhold';
+    };
+}
+export declare const EMPTY_CONFIG: SdkConfigPayload;
+//# sourceMappingURL=configTypes.d.ts.map

package/lib/typescript/config/otaPolicyState.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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.
+ */
+export type CompromisedDevicePolicy = 'allow' | 'withhold';
+/**
+ * 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 declare function applyOtaConfig(block: unknown): void;
+/** What the server says, or null when it has said nothing. */
+export declare function serverCompromisedDevicePolicy(): CompromisedDevicePolicy | null;
+/**
+ * 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 declare function resolveCompromisedDevicePolicy(hostPolicy: CompromisedDevicePolicy | undefined): CompromisedDevicePolicy;
+/** Test seam. Not exported from the package. */
+export declare function __resetOtaPolicyForTests(): void;
+//# sourceMappingURL=otaPolicyState.d.ts.map