@scalebun-release/react-native 2.5.0

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

@@ -0,0 +1,155 @@
+/**
+ * ScaleBun SDK — per-feature quota state (shared contract v1).
+ *
+ * The plan caps four features: `events`, `sessions`, `frames`, `networkRequests`. When one is
+ * exhausted the server says so in two places, and this module is the ONE place both land:
+ *
+ *   1. GET /config carries `quota: { v, serverTime, periodEnd, blocked: { <feature>: { until, since } } }`.
+ *   2. An ingestion refusal — HTTP 402 `{ code: 'quota_exceeded', feature, until }` on the
+ *      single-feature endpoints, or `quota.events.blocked` in the 200 body of POST /v1/batch.
+ *
+ * Every lane asks `isBlocked(feature)` at CAPTURE time (don't record what cannot be stored) and at
+ * SEND time (don't upload what was queued before the block arrived). Lanes that hold state
+ * (buffers, persisted queues, native outbox directories, running capture) subscribe and purge or
+ * stop when a block begins, and resume when it ends.
+ *
+ * CLOCKS. There is no server-time sync in this SDK and the device clock may be arbitrarily wrong,
+ * so a block is never lifted by the device clock alone. `untilMs` is computed RELATIVE to the moment
+ * the block was received — `receivedAt + (until − serverTime)` — which is immune to a skewed device
+ * clock, and reaching it only triggers ONE forced /config refresh. The block is lifted only when the
+ * server no longer lists it. If that refresh fails, the next attempt is at least 5 minutes later.
+ *
+ * `quota` absent from /config (an older backend) leaves the persisted state untouched; with nothing
+ * persisted, nothing is blocked. Every method is non-throwing.
+ *
+ * The refresh at untilMs is delayed by a per-device random 60–300 s so a fleet whose blocks all end at
+ * the same periodEnd does not hit /config in the same second.
+ *
+ * OUT OF CONTRACT (not gated here; the backend does not meter them against these quotas):
+ *  - the legacy `PersistentQueue` → `/sdk/events` (projectId/publishableKey) lane;
+ *  - the legacy `BackendReplayTransport` (`/v1/replay/...`, `X-API-Key`) replay transport.
+ * Both predate the clientKey ingestion contract that the four limited lanes belong to.
+ */
+import { type StorageBackend } from '../storage/StorageBackend';
+export type QuotaFeature = 'events' | 'sessions' | 'frames' | 'networkRequests';
+export declare const QUOTA_FEATURES: readonly QuotaFeature[];
+/** Shape of the `quota` block on GET /config (contract §1). */
+export interface QuotaConfigBlock {
+    v: number;
+    serverTime?: string;
+    periodEnd?: string;
+    blocked?: Record<string, {
+        until?: string;
+        since?: string;
+    } | undefined>;
+}
+export interface QuotaBlockRecord {
+    /** Server period end (ISO) as the server stated it — informational only. */
+    until: string | null;
+    since: string | null;
+    /** Device ms when the block was received. */
+    receivedAt: number;
+    /** Device ms at which ONE /config refresh is due (server-relative, not device-clock). */
+    untilMs: number;
+    /** Where the block came from. A refusal is reconciled by the next /config that post-dates it. */
+    source: 'config' | 'refusal';
+    /**
+     * IN-PROCESS ordering of a refusal (never persisted). "Did this refusal arrive after that /config
+     * request started?" is answered with this monotonic sequence, NOT with wall-clock receivedAt: a
+     * device clock that is ahead when the 402 lands (common before NTP sync) would otherwise persist a
+     * future receivedAt and make every later /config look older than the refusal — stuck blocked.
+     * 0 for anything loaded from disk (always older than any request of this process).
+     */
+    seq?: number;
+}
+export type QuotaListener = (feature: QuotaFeature, blocked: boolean) => void;
+interface HeaderLike {
+    get(name: string): string | null | undefined;
+}
+export declare function isQuotaFeature(x: unknown): x is QuotaFeature;
+export declare class QuotaState {
+    private storageFactory;
+    private clock;
+    private blocks;
+    private listeners;
+    private refresher;
+    private timer;
+    private lastExpiryRefreshAt;
+    private loaded;
+    private syncListeners;
+    private jitterMs;
+    /** Monotonic in-process refusal counter (see QuotaBlockRecord.seq). */
+    private refusalSeq;
+    constructor(storageFactory?: () => StorageBackend | null, clock?: () => number, random?: () => number);
+    /**
+     * Called after EVERY state sync — each /config 200 that carries `quota` and each recorded refusal —
+     * whether or not anything transitioned. Consumers that mirror the full state elsewhere (the native
+     * outbox lanes) re-assert it here, which is what un-parks a lane native parked on its own.
+     */
+    onSync(listener: () => void): () => void;
+    private emitSync;
+    isBlocked(feature: QuotaFeature): boolean;
+    blockedFeatures(): QuotaFeature[];
+    /** Copy of the current records (diagnostics / tests). */
+    snapshot(): Partial<Record<QuotaFeature, QuotaBlockRecord>>;
+    subscribe(listener: QuotaListener): () => void;
+    /**
+     * Register the forced /config refresh used when a block's `untilMs` is reached. Arms the expiry
+     * timer for whatever is already persisted.
+     */
+    setRefresher(fn: (() => Promise<void> | void) | null): void;
+    /**
+     * Capture at /config REQUEST START and pass to applyConfig. Refusals recorded after this mark
+     * survive that response; everything older (and everything loaded from disk) is reconciled by it.
+     */
+    requestMark(): number;
+    /**
+     * Apply the `quota` block of a FRESH (HTTP 200) /config response.
+     *
+     * @param requestMark `requestMark()` captured when the /config request was issued. A refusal
+     *        recorded AFTER it (in this process) is kept even when this response does not list it —
+     *        the server answered before it knew. Omitted → every refusal counts as older.
+     */
+    applyConfig(quota: unknown, receivedAt?: number, requestMark?: number): void;
+    /**
+     * Record a quota refusal from an ingestion response. `until` is the server's period end; the
+     * refresh time is anchored on `Retry-After` (seconds until period end) when present, else on the
+     * response `Date` header, else — last resort — on the device clock. In every case reaching it only
+     * triggers a /config refresh.
+     *
+     * @returns true when `feature` is a limited feature and is now blocked.
+     */
+    applyRefusal(feature: unknown, until: unknown, opts?: {
+        receivedAt?: number;
+        retryAfterSec?: number | null;
+        serverDate?: string | null;
+    }): boolean;
+    private untilMsFrom;
+    private emit;
+    private scheduleExpiryCheck;
+    private runExpiryRefresh;
+    private ensureLoaded;
+    private persist;
+    /** TEST-ONLY: drop in-memory state, listeners and timers. */
+    __resetForTests(storageFactory?: () => StorageBackend | null, clock?: () => number): void;
+}
+/** The process-wide quota state every lane consults. */
+export declare const quotaState: QuotaState;
+/**
+ * Inspect a SINGLE-FEATURE ingestion response (sessions start, frames, frames/presign, network,
+ * events) for a quota refusal and record it.
+ *
+ *   - HTTP 402 `{ code: 'quota_exceeded', feature, until }` → blocked.
+ *   - HTTP 2xx with `quota: { feature, granted, refused, until }` and `refused > 0` → a partial grant:
+ *     the allowance is now spent, so the feature is blocked from here on.
+ *
+ * @returns the refused feature, or null.
+ */
+export declare function noteQuotaResponse(status: number, body: unknown, headers?: HeaderLike | null, target?: QuotaState): QuotaFeature | null;
+/**
+ * Inspect a POST /v1/batch response body (`quota.events.blocked`, contract §2c) and record the block.
+ * @returns true when events are now blocked.
+ */
+export declare function noteBatchQuota(body: unknown, headers?: HeaderLike | null, target?: QuotaState): boolean;
+export {};
+//# sourceMappingURL=quotaState.d.ts.map

package/lib/typescript/core/architecture.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Runtime React Native architecture detection.
+ *
+ * Why this exists: our native-module resolvers prefer the codegen TurboModule
+ * spec (`require('../specs/Native*').default`, i.e. `TurboModuleRegistry.get`).
+ * On the **Old Architecture**, `TurboModuleRegistry.get()` does NOT return null —
+ * it transparently falls back to the legacy `NativeModules` lookup via React
+ * Native's built-in backward-compatibility layer. So "the turbo lookup
+ * succeeded" is NOT proof the New Architecture is active. Inferring the
+ * architecture from which lookup won therefore mislabels Old-Arch apps as
+ * "New Architecture".
+ *
+ * The only reliable runtime signal is the TurboModule proxy / bridgeless flag
+ * that the native runtime installs onto the global object when — and only when —
+ * the New Architecture is enabled.
+ */
+/**
+ * `true` when the app is running on the React Native New Architecture
+ * (TurboModules / Fabric / bridgeless), `false` on the Old Architecture (bridge)
+ * or when there is no native runtime (web / SSR / tests).
+ */
+export declare function isNewArchitecture(): boolean;
+/**
+ * Human-readable label for the active architecture and how a native module was
+ * obtained — used in the one-time "native module via …" resolver logs so the
+ * line reflects reality on both architectures.
+ */
+export declare function nativeModuleVia(): string;
+//# sourceMappingURL=architecture.d.ts.map

package/lib/typescript/core/clock/now.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Returns the current timestamp in milliseconds.
+ */
+export declare function now(): number;
+//# sourceMappingURL=now.d.ts.map

package/lib/typescript/core/config/defaults.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=defaults.d.ts.map

package/lib/typescript/core/config/schema.d.ts

@@ -0,0 +1,107 @@
+export type ValidationIssue = {
+    path: Array<string | number>;
+    message: string;
+};
+export type FormattedError = {
+    _errors: string[];
+    [key: string]: FormattedError | string[];
+};
+export declare class ConfigValidationError extends Error {
+    readonly issues: ValidationIssue[];
+    constructor(issues: ValidationIssue[]);
+    /** Nested error object keyed by path, matching Zod's `error.format()`. */
+    format(): FormattedError;
+}
+export type SafeParseResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: ConfigValidationError;
+};
+export declare const ConfigSchema: {
+    safeParse(input: unknown): SafeParseResult<ScaleBunConfig>;
+    parse(input: unknown): ScaleBunConfig;
+};
+export interface ScaleBunConfig {
+    projectId?: string;
+    publishableKey?: string;
+    apiBaseUrl: any;
+    debug: boolean;
+    logLevel?: 'silent' | 'error' | 'warn' | 'info' | 'debug';
+    flushIntervalMs: number;
+    finalizeOnBackground: boolean;
+    idleThresholdMs: number;
+    sessionBackgroundCapMs: number;
+    maxQueueSize: number;
+    enableNetworkMonitoring: boolean;
+    captureNetworkBodies: boolean;
+    networkBodyMaxBytes: number;
+    persistence: {
+        enabled: boolean;
+        maxBytes: number;
+        maxEntries: number;
+        redactBeforeWrite: boolean;
+    };
+    clientKey?: string;
+    useObjectStorage: boolean;
+    enableNativeFileOutbox: boolean;
+    nativeOutboxUploadEnabled: boolean;
+    useObjectStorageForFrames: boolean;
+    nativeOutboxRetryIntervalMs: number;
+    nativeOutboxMaxUploadAttempts: number;
+    nativeOutboxPoisonMaxAttempts: number;
+    nativeOutboxRespectRetryAfter: boolean;
+    nativeOutboxStrictThreeSecondRetry: boolean;
+    nativeOutboxNetworkFailuresCountTowardDead: boolean;
+    nativeOutboxMaxBytes: number;
+    nativeOutboxMaxAgeMs: number;
+    performance: {
+        enabled: boolean;
+        tier1: {
+            appLaunch: boolean;
+            screenLoad: boolean;
+            network: boolean;
+            uiHang: boolean;
+        };
+        tier2: {
+            enabled: boolean;
+            sampleRate: number;
+        };
+    };
+    replay?: {
+        record?: boolean;
+        captureMode?: 'navigation' | 'interactions';
+        intervalMs?: number;
+        quality?: 'high' | 'normal' | 'low' | 'grayscale';
+        deltaEncoding?: boolean;
+        deltaKeyframeInterval?: number;
+    };
+    /** SB-10: public top-level privacy config, mapped onto the replay privacy policy. */
+    privacy?: {
+        maskTextInputs?: boolean;
+        maskImages?: boolean;
+        redactAuth?: boolean;
+        redactCookies?: boolean;
+        redactBodies?: boolean;
+    };
+    captureInteractionHeatmap: boolean;
+    /** RN-3 zero-config scroll instrumentation. OFF by default — it changes what the HOST renders. */
+    autoInstrumentScrollViews: boolean;
+    /** Opt-in: capture console.* into the Logs lane in SaaS mode. Default false. */
+    captureConsoleLogs: boolean;
+    ota?: {
+        enabled: boolean;
+        checkOnForeground: boolean;
+        channelOverride?: string;
+        mandatoryBlocksUi: boolean;
+        /**
+         * Withhold OTA updates from devices reporting root/jailbreak indicators.
+         * Omitted means 'allow' — the behaviour every existing app already has.
+         * Mobile only; the web SDK has no OTA lane.
+         */
+        onCompromisedDevice?: 'allow' | 'withhold';
+    };
+}
+export type { ScaleBunFeatures, ScaleBunInitConfig, SimplifiedInitConfig, DebugConnectionConfig, PrivacyConfig, BrandingConfig, ScaleBunUser, ExportPresetName, SimplifiedExportOptions, ExportResult, } from '../../vendor/sdk-contracts';
+//# sourceMappingURL=schema.d.ts.map

package/lib/typescript/core/constants/endpoints.d.ts

@@ -0,0 +1,13 @@
+/**
+ * ScaleBun cloud API base URL — the single, LOCKED endpoint for the SDK.
+ *
+ * `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 declare const DEFAULT_API_BASE_URL = "https://api.scalebun.com/api/v1";
+//# sourceMappingURL=endpoints.d.ts.map

package/lib/typescript/core/constants/protocol.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ScaleBun SDK — Debug-protocol constants needed OUTSIDE the debug lane.
+ *
+ * `PROTOCOL_VERSION` is stamped onto journey/session envelopes by production code
+ * (journeyManager, DesktopSessionTransport). Importing it from `vendor/protocol` — its canonical
+ * home — drags the whole vendored schema module into every production bundle, because that module
+ * builds all desktop wire-message schemas at module scope and Metro performs no tree shaking.
+ * Measured: 4,240 bytes of minified schema code shipped for the sake of two numeric constants.
+ *
+ * So the two constants are declared here, dependency-free, and production code imports THIS file.
+ * The vendored module keeps re-exporting its own copies for the debug lane, which is the only
+ * place the schemas themselves are used.
+ *
+ * The vendored file itself is deliberately untouched — `vendor/protocol` is a byte-identical copy
+ * of `@scalebun/protocol` enforced by parity gates, so the values are duplicated here rather than
+ * re-exported. `core/constants/__tests__/protocolConstants.test.ts` asserts both copies stay
+ * equal; if the canonical protocol bumps a value, that test fails until this file follows.
+ */
+/** Wire-protocol version stamped on every desktop-debug and journey envelope. */
+export declare const PROTOCOL_VERSION = 1;
+/** Heartbeat interval sent in ACK; the SDK uses this for its ping timer. */
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;
+//# sourceMappingURL=protocol.d.ts.map

package/lib/typescript/core/constants/timings.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ScaleBun SDK — Timing & Transport Constants
+ *
+ * Named exports for every magic number in the SDK debug transport layer.
+ * Import from here instead of using inline literals.
+ */
+export { DEFAULT_HEARTBEAT_INTERVAL_MS } from './protocol';
+/** Default WebSocket port when no port is specified in DebugConfig */
+export declare const DEFAULT_WS_PORT = 9333;
+/** Maximum messages to buffer in transport while disconnected */
+export declare const TRANSPORT_MAX_BUFFER_SIZE = 500;
+/** Give up reconnecting after this many failed attempts */
+export declare const TRANSPORT_MAX_RECONNECT_ATTEMPTS = 20;
+/** Base delay (ms) for exponential reconnect backoff */
+export declare const TRANSPORT_RECONNECT_BASE_MS = 250;
+/** Maximum delay (ms) cap for exponential reconnect backoff */
+export declare const TRANSPORT_RECONNECT_MAX_MS = 5000;
+/** Pong round-trip threshold (ms) above which a high-latency warning is logged */
+export declare const TRANSPORT_HIGH_LATENCY_WARN_MS = 1000;
+/** Delay (ms) before emitting debug_ready after connection is established */
+export declare const DEBUG_READY_EMIT_DELAY_MS = 500;
+//# sourceMappingURL=timings.d.ts.map

package/lib/typescript/core/constants/version.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ScaleBun SDK version. Sent with the session-start envelope so the dashboard
+ * can attribute telemetry to the SDK build that produced it.
+ * Keep in sync with package.json "version" — `version.test.ts` fails when they drift.
+ *
+ * Why the test matters: the 1.11.0 bump missed this line, so the build would have reported itself as
+ * 1.10.6. Every "is the release live, and on what share of traffic" question is answered from this
+ * value, so a stale one makes a rollout unobservable — which is the exact problem sending an SDK
+ * version was introduced to solve.
+ */
+export declare const SDK_VERSION = "2.5.0";
+//# sourceMappingURL=version.d.ts.map

package/lib/typescript/core/context/app.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=app.d.ts.map

package/lib/typescript/core/context/device.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The real `Platform.OS`, never narrowed.
+ *
+ * React Native's own union is `'ios' | 'android' | 'windows' | 'macos' | 'web'`, and the protocol's
+ * platform field is an open enum precisely so new ones travel without a release. Collapsing that to
+ * a two-way ternary is what made every macOS and Windows session read as Android.
+ */
+export type PlatformOS = 'ios' | 'android' | 'windows' | 'macos' | 'web' | 'unknown';
+/**
+ * `Platform.OS`, verbatim.
+ *
+ * `'unknown'` when React Native itself cannot be loaded — the previous `catch { return 'android' }`
+ * turned "we could not tell" into a confident, wrong answer.
+ */
+export declare function resolvePlatformOS(): PlatformOS;
+/**
+ * `'ios' | 'android'` for the few call sites whose payload genuinely only has those two, keeping the
+ * narrowing HONEST: `null` where it used to silently say Android.
+ */
+export declare function resolveMobileOS(): 'ios' | 'android' | null;
+/** The keys this module owns. An integrator-supplied value for any of them is overridden. */
+export declare const DETECTED_CONTEXT_KEYS: readonly ["sdk_version", "platform_os", "os_version", "device_model", "manufacturer"];
+/**
+ * Everything derivable WITHOUT the native bridge, so the very first event already carries it.
+ *
+ * The bridge is async and may not be installed at all (Expo Go, an older native binary); waiting on
+ * it would leave the opening events of every session unattributed. `Platform.constants` is populated
+ * synchronously at startup and covers Android fully — iOS exposes no model there, which is why
+ * `device_model` stays absent on iOS until {@link nativeDeviceContext} fills it in.
+ */
+export declare function staticDeviceContext(): Record<string, string>;
+/** Bridge values, once the native module answers. Absent keys stay absent. */
+export declare function nativeDeviceContext(info: {
+    platform?: string;
+    osVersion?: string;
+    deviceModel?: string;
+    manufacturer?: string;
+} | null): Record<string, string>;
+/**
+ * Merge the integrator's context with what we detected — DETECTED WINS on the keys above.
+ *
+ * The inversion is deliberate. Config normally wins over defaults, but these are not defaults: they
+ * are measurements, and a measurement must not be overridable by a guess. Everything outside
+ * {@link DETECTED_CONTEXT_KEYS} — `language`, `timezone`, `network_type`, anything app-specific —
+ * is still the integrator's to set, untouched.
+ */
+export declare function mergeDeviceContext(configured: Record<string, unknown> | undefined, detected?: Record<string, string>): Record<string, unknown>;
+/**
+ * The analytics envelope lane's platform value, AUTO-DETECTED.
+ *
+ * The init config's `platform` field was documented as "Default: react_native" — so every
+ * integration that did not hand-write `platform: 'ios' | 'android'` stamped the literal
+ * `react_native` on all its analytics events, and the dashboard's platform filters (which split
+ * ios/android) silently excluded them. Asking the developer for a value the runtime knows is an
+ * integration tax with a failure mode; `Platform.OS` answers it exactly.
+ *
+ * `react_native` remains only for the genuinely-unknown case (RN unloadable, or an OS the wire
+ * enum does not carry) — an honest "RN, platform untold" rather than a confident wrong answer.
+ */
+export declare function resolveEventPlatform(): 'ios' | 'android' | 'web' | 'react_native';
+//# sourceMappingURL=device.d.ts.map

package/lib/typescript/core/context/session.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=session.d.ts.map

package/lib/typescript/core/context/user.d.ts

@@ -0,0 +1,24 @@
+export interface UserContext {
+    id?: string;
+    email?: string;
+    name?: string;
+    [key: string]: any;
+}
+export interface AppContext {
+    name?: string;
+    version?: string;
+    build?: string;
+    bundleId?: string;
+}
+export interface DeviceContext {
+    id: string;
+    model?: string;
+    os?: string;
+    osVersion?: string;
+    locale?: string;
+}
+export interface SessionContext {
+    id: string;
+    startTime: number;
+}
+//# sourceMappingURL=user.d.ts.map

package/lib/typescript/core/contracts/IFeature.d.ts

@@ -0,0 +1,44 @@
+/**
+ * ScaleBun SDK — Feature Contract
+ *
+ * Interface for pluggable SDK features (replay, network, crash, etc.).
+ * Each feature follows the same lifecycle: register → initialize → teardown.
+ *
+ * SOLID: Interface Segregation — features only implement what they need.
+ * SOLID: Open/Closed — new features are added by implementing this interface.
+ *
+ * Canonical source: @scalebun/sdk-contracts/features
+ */
+/** Context provided to features during initialization */
+export interface FeatureContext {
+    /** Track an event through the SDK pipeline */
+    trackEvent: (name: string, payload?: Record<string, unknown>) => void;
+    /** Get the debug stream (if debug is enabled) */
+    getDebugStream: () => unknown | null;
+    /** App lifecycle state */
+    getAppState: () => 'active' | 'background' | 'inactive';
+}
+/**
+ * Contract for SDK features.
+ *
+ * Each feature module (network monitoring, crash reporting, replay, etc.)
+ * implements this interface and registers itself with the FeatureRegistry.
+ */
+export interface IFeature {
+    /** Unique feature name (e.g. 'network', 'crash', 'replay') */
+    readonly name: string;
+    /**
+     * Initialize the feature with the provided context.
+     * May be async for features that need native module setup.
+     */
+    initialize(context: FeatureContext): void | Promise<void>;
+    /**
+     * Tear down the feature and release all resources.
+     * Must be synchronous and safe to call multiple times.
+     */
+    teardown(): void;
+    /** Whether the feature is currently active */
+    readonly isActive: boolean;
+}
+export type { IFeature as ContractIFeature, FeatureContext as ContractFeatureContext, } from '../../vendor/sdk-contracts';
+//# sourceMappingURL=IFeature.d.ts.map

package/lib/typescript/core/di/container.d.ts

@@ -0,0 +1,9 @@
+export declare class Container {
+    private services;
+    register<T>(key: string, instance: T): T;
+    get<T>(key: string): T;
+    has(key: string): boolean;
+    clear(): void;
+}
+export declare const coreContainer: Container;
+//# sourceMappingURL=container.d.ts.map

package/lib/typescript/core/encoding/base64.d.ts

@@ -0,0 +1,13 @@
+/**
+ * ScaleBun SDK — base64 → binary decode (RN-safe).
+ *
+ * Used by the object-storage upload paths (replay frames + engage attachments) to
+ * turn a base64 payload into real binary bytes for a presigned PUT. We deliberately
+ * do NOT use the `fetch('data:…').blob()` round-trip: under the new architecture
+ * that rejects with "Network request failed". RN's XHR accepts a `Uint8Array` body
+ * and transfers `.buffer` to native as binary, so a decoded byte array uploads
+ * faithfully.
+ */
+/** Decode a base64 string (no data-URI prefix) into a Uint8Array of raw bytes. */
+export declare function base64ToBytes(base64: string): Uint8Array;
+//# sourceMappingURL=base64.d.ts.map

package/lib/typescript/core/id/deviceId.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Generates or retrieves a unique device ID.
+ */
+export declare function getDeviceId(): string;
+/**
+ * Generates a unique session ID.
+ */
+export declare function generateSessionId(): string;
+//# sourceMappingURL=deviceId.d.ts.map

package/lib/typescript/core/id/installationId.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The SDK's canonical per-install id.
+ *
+ * ONE install, ONE id, every lane. This is deliberately NOT `getDeviceId()` —
+ * that is a separate value under a separate storage key, and the backend schema
+ * annotates the two as different ("stable per-install id from the SDK (≠
+ * deviceId)").
+ *
+ * It matters because the backend joins a bundle's OTA installs to that device's
+ * sessions through this value. OTA events have always been keyed by it; the
+ * session lane did not send it at all, so on the server the two could only be
+ * connected for devices that happened to have registered for push. Release
+ * health then reported "no data" for bundles that were running perfectly well —
+ * or crashing badly.
+ *
+ * Lives here rather than inside one feature so the OTA orchestrator and the
+ * session adapter cannot drift to two different ids.
+ */
+export declare function resolveInstallationId(): string;
+//# sourceMappingURL=installationId.d.ts.map

package/lib/typescript/core/id/sessionId.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=sessionId.d.ts.map

package/lib/typescript/core/lifecycle/appLifecycle.d.ts

@@ -0,0 +1,14 @@
+import { AppStateStatus } from 'react-native';
+export type LifecycleListener = (state: AppStateStatus) => void;
+declare class AppLifecycle {
+    private listeners;
+    private currentState;
+    constructor();
+    private handleStateChange;
+    addListener(listener: LifecycleListener): void;
+    removeListener(listener: LifecycleListener): void;
+    getCurrentState(): AppStateStatus;
+}
+export declare const appLifecycle: AppLifecycle;
+export {};
+//# sourceMappingURL=appLifecycle.d.ts.map

package/lib/typescript/core/lifecycle/crashSafe.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Crash safety utilities for the SDK.
+ * Ensures that internal SDK failures do not crash the host application.
+ */
+export declare function noThrow<T>(fn: () => T, fallback?: T): T | undefined;
+export declare function safeAsync<T>(fn: () => Promise<T>, fallback?: T): Promise<T | undefined>;
+//# sourceMappingURL=crashSafe.d.ts.map

package/lib/typescript/core/logger/errorClassification.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ScaleBun SDK — Error Classification
+ *
+ * Pure helpers that classify transport/flush failures so the SDK can decide
+ * whether an error is a normal, recoverable condition (request aborted,
+ * timeout, offline, backend temporarily down) or a genuine fatal integration
+ * bug that the host developer must act on.
+ *
+ * Recoverable errors MUST NOT be logged through `console.error` — in React
+ * Native that triggers a LogBox / RedBox overlay for what is really a routine
+ * retry. See `internalLogger` for how levels map to console methods.
+ */
+/** Reason codes describing why a flush/transport attempt failed. */
+export type FailureReason = 'request_aborted' | 'timeout' | 'offline' | 'server_error' | 'unknown';
+/**
+ * AbortError — the request was cancelled via an AbortController. This happens
+ * on intentional cancel, app backgrounding, navigation interruption, or a
+ * timeout that aborts the underlying fetch.
+ */
+export declare function isAbortError(error: unknown): boolean;
+/** Timeout — the SDK aborted the request because it exceeded the deadline. */
+export declare function isTimeoutError(error: unknown): boolean;
+/**
+ * Network error — device offline or the backend host is unreachable. RN's
+ * fetch rejects with a generic `TypeError: Network request failed`.
+ */
+export declare function isNetworkError(error: unknown): boolean;
+/**
+ * Recoverable flush error — the events were not delivered but can safely be
+ * returned to the queue and retried later. Covers abort, timeout, offline,
+ * and transient backend unavailability (HTTP 5xx / 429).
+ *
+ * `status` is the HTTP status when the transport returned a response (used to
+ * treat 5xx and 429 as recoverable).
+ */
+export declare function isRecoverableFlushError(error: unknown, status?: number): boolean;
+/**
+ * Fatal SDK error — not recoverable by retrying. Today this means anything we
+ * could not classify as recoverable. Used to decide whether to surface via
+ * `console.error`. Callers may pass a known HTTP `status` to keep client
+ * errors (4xx, except 429) classified as fatal/actionable.
+ */
+export declare function isFatalSdkError(error: unknown, status?: number): boolean;
+/** Human-readable reason code for logs and internal status. */
+export declare function describeErrorReason(error: unknown, status?: number): FailureReason;
+//# sourceMappingURL=errorClassification.d.ts.map