@scalebun-release/react-native 2.5.0

package/lib/typescript/specs/NativeScaleBunStorage.d.ts

@@ -0,0 +1,55 @@
+import type { TurboModule } from 'react-native';
+/**
+ * React Native Codegen spec for the first-party durable key-value store
+ * (`ScaleBunStorage`).
+ *
+ * This is the SDK's OWN persistence backend — it requires NO third-party storage
+ * library. App developers install nothing: the native module ships inside
+ * `@scalebun/react-native` and persists data to an app-private file
+ * (Android `filesDir/scalebun_kv.json`, iOS Application Support).
+ *
+ * DESIGN — synchronous mirror + async write-through:
+ *   The JS `StorageBackend` contract is synchronous (it is read at module-load
+ *   time, e.g. the device id). RN has no synchronous durable storage in core, so
+ *   this module exposes ONE synchronous method, `getAllSync()`, used exactly
+ *   once during `createStorageBackend()` to hydrate an in-memory mirror. All
+ *   subsequent reads hit that mirror synchronously; writes are mirrored in
+ *   memory and flushed to disk asynchronously through `setItems`/`removeItems`.
+ *   Disk writes are coalesced + atomic (temp-file + rename) on the native side.
+ *
+ * Codegen note: `getAllSync` returns `string` (a JSON object of all key→value
+ * pairs) and is therefore generated as a SYNCHRONOUS JSI method on the New
+ * Architecture; on the Old Architecture it is a blocking synchronous bridge
+ * method. The write methods return `Promise<void>` so they never block the JS
+ * thread.
+ */
+export interface Spec extends TurboModule {
+    /**
+     * Synchronously return ALL persisted entries as a JSON object string
+     * (`{"<key>":"<value>", ...}`). Returns `"{}"` when the store is empty or
+     * cannot be read. Called once at init to hydrate the JS mirror.
+     */
+    getAllSync(): string;
+    /**
+     * Merge a batch of entries (JSON object string `{"<key>":"<value>"}`) into the
+     * store and schedule an atomic disk flush. Async — fire-and-forget from JS.
+     */
+    setItems(entriesJson: string): Promise<void>;
+    /**
+     * Delete a batch of keys (JSON array string `["<key>", ...]`) and schedule an
+     * atomic disk flush. Async — fire-and-forget from JS.
+     */
+    removeItems(keysJson: string): Promise<void>;
+    /** Delete every persisted entry and remove the backing file. Async. */
+    clear(): Promise<void>;
+}
+/**
+ * Resolved via `get` (not `getEnforcing`) so the SDK degrades gracefully when
+ * the native module is unavailable (web/SSR, Jest, an app that hasn't rebuilt
+ * native yet) — it returns `null` and the storage layer falls back to an
+ * in-memory backend with a single honest warning. On the Old Architecture the
+ * registry transparently bridges to the legacy `NativeModules.ScaleBunStorage`.
+ */
+declare const _default: Spec | null;
+export default _default;
+//# sourceMappingURL=NativeScaleBunStorage.d.ts.map

package/lib/typescript/storage/StorageBackend.d.ts

@@ -0,0 +1,131 @@
+/**
+ * ScaleBun SDK — Storage Backend Abstraction
+ *
+ * Pluggable, synchronous key-value storage interface used by the PersistentQueue,
+ * the Engage throttle/test-seen stores, the event tracker identifiers, and the
+ * device id. It is the SDK's single storage seam — no feature talks to a storage
+ * implementation directly.
+ *
+ * DEFAULT BACKEND — first-party, zero third-party dependency:
+ * The default React Native backend (`NativeKVBackend`) is backed by the SDK's
+ * OWN native module (`ScaleBunStorage`), which persists to an app-private file
+ * (Android `filesDir/scalebun_kv.json`, iOS Application Support). App developers
+ * install NOTHING — the native module ships inside `@scalebun/react-native`.
+ *
+ * Because this interface is synchronous (it is read at module-load time) but
+ * native file IO is asynchronous, `NativeKVBackend` keeps a synchronous in-memory
+ * mirror that is hydrated ONCE from the native store via the synchronous
+ * `getAllSync()` method, then kept in sync with the disk through asynchronous,
+ * coalesced write-through (`setItems` / `removeItems`).
+ *
+ * FALLBACK:
+ * If the native module is unavailable (e.g. the app has not rebuilt native code,
+ * web/SSR, or a unit-test environment), the factory falls back to `MemoryBackend`
+ * and logs exactly ONE honest warning per app launch. Data will not survive a
+ * restart in that mode — but the SDK keeps functioning.
+ */
+/**
+ * Minimal synchronous key-value storage interface for the persistent queue and
+ * the SDK's small identifiers/state.
+ *
+ * All operations are synchronous. The default native backend satisfies this with
+ * an in-memory mirror over an app-private file (hydrated once at init, written
+ * back asynchronously). Implementations must never throw.
+ */
+export interface StorageBackend {
+    /** Read a value by key. Returns undefined if not found. */
+    get(key: string): string | undefined;
+    /** Write a value by key. Overwrites if key exists. */
+    set(key: string, value: string): void;
+    /** Delete a key. No-op if key doesn't exist. */
+    delete(key: string): void;
+    /**
+     * Return all keys currently stored.
+     * Used during leftover drain to discover entries from previous runs.
+     */
+    getAllKeys(): string[];
+}
+/**
+ * In-memory storage backend. Data does NOT survive app restarts.
+ *
+ * Used for:
+ * - Unit tests (no native deps)
+ * - Emergency fallback when the native durable store is unavailable
+ * - Environments where persistence is explicitly disabled
+ */
+export declare class MemoryBackend implements StorageBackend {
+    private data;
+    get(key: string): string | undefined;
+    set(key: string, value: string): void;
+    delete(key: string): void;
+    getAllKeys(): string[];
+}
+/**
+ * Minimal shape of the native `ScaleBunStorage` module this backend depends on.
+ * Declared structurally (not imported as the codegen `Spec`) so tests can inject
+ * a plain fake and so the backend never hard-depends on the generated type.
+ */
+export interface NativeKVModule {
+    getAllSync(): string;
+    setItems(entriesJson: string): Promise<void> | void;
+    removeItems(keysJson: string): Promise<void> | void;
+    clear(): Promise<void> | void;
+}
+/**
+ * Durable, first-party storage backed by the SDK's own `ScaleBunStorage` native
+ * module. Data survives app restarts, crashes, and force-kills (modulo the small
+ * window of the most-recent un-flushed write — see below).
+ *
+ * Strategy:
+ *   - On construction, `getAllSync()` loads the entire persisted namespace into a
+ *     synchronous in-memory `Map` (the mirror).
+ *   - Reads (`get` / `getAllKeys`) serve the mirror synchronously.
+ *   - Writes (`set` / `delete`) update the mirror immediately, then enqueue a
+ *     pending change that is flushed to the native store on a microtask. Pending
+ *     sets/deletes for the same key are coalesced; ordering is preserved per key.
+ *
+ * Durability window: a write is in the mirror immediately but reaches disk on the
+ * next flush. A process kill in that sub-millisecond window can lose the most
+ * recent write(s). This matches any async-persistence store and is the price of
+ * not blocking the JS thread on every event. Everything already on disk is safe
+ * and atomically written by the native side.
+ */
+export declare class NativeKVBackend implements StorageBackend {
+    private readonly native;
+    private readonly mirror;
+    /** Keys whose latest value still needs to be pushed to the native store. */
+    private pendingSets;
+    /** Keys whose deletion still needs to be pushed to the native store. */
+    private pendingDeletes;
+    private flushScheduled;
+    constructor(native: NativeKVModule);
+    /** Load the full persisted namespace synchronously into the mirror. */
+    private _hydrate;
+    get(key: string): string | undefined;
+    set(key: string, value: string): void;
+    delete(key: string): void;
+    getAllKeys(): string[];
+    /** Coalesce pending writes and flush them to the native store on a microtask. */
+    private _scheduleFlush;
+    private _flush;
+}
+/**
+ * Create (once) and return the shared storage backend for the current
+ * environment.
+ *
+ * Selection order:
+ *   1. `NativeKVBackend` over the first-party `ScaleBunStorage` native module
+ *      (durable, app-private file — the default for React Native).
+ *   2. `MemoryBackend` (emergency fallback — no persistence), with exactly ONE
+ *      honest warning per launch. The warning never mentions any third-party
+ *      library.
+ *
+ * Idempotent: subsequent calls return the cached instance.
+ */
+export declare function createStorageBackend(): StorageBackend;
+/**
+ * TEST-ONLY: reset the shared backend singleton so each test can exercise the
+ * factory's selection logic from a clean slate.
+ */
+export declare function __resetStorageBackendForTests(): void;
+//# sourceMappingURL=StorageBackend.d.ts.map

package/lib/typescript/storage/db/sqlite.d.ts

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

package/lib/typescript/storage/files/fileStore.d.ts

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

package/lib/typescript/transport/auth/sdkSession.d.ts

@@ -0,0 +1,10 @@
+export declare class SdkSessionManager {
+    private token?;
+    private expiresAt?;
+    setSession(token: string, expiresIn: number): void;
+    getToken(): string | undefined;
+    isExpired(): boolean;
+    clear(): void;
+}
+export declare const sdkSession: SdkSessionManager;
+//# sourceMappingURL=sdkSession.d.ts.map

package/lib/typescript/transport/backoff/exponentialJitter.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Exponential backoff with jitter.
+ */
+export declare function getDelayWithJitter(attempt: number, base?: number): number;
+//# sourceMappingURL=exponentialJitter.d.ts.map

package/lib/typescript/transport/http/endpoints.d.ts

@@ -0,0 +1,26 @@
+export declare const ENDPOINTS: {
+    SESSIONS: string;
+    EVENTS: string;
+    INGESTION_START: string;
+    INGESTION_IDENTIFY: (id: string) => string;
+    INGESTION_FRAMES: (id: string) => string;
+    INGESTION_FRAMES_PRESIGN: (id: string) => string;
+    INGESTION_EVENTS: (id: string) => string;
+    INGESTION_NETWORK: (id: string) => string;
+    INGESTION_LOGS: (id: string) => string;
+    INGESTION_ERRORS: (id: string) => string;
+    INGESTION_PERFORMANCE: (id: string) => string;
+    INGESTION_FINALIZE: (id: string) => string;
+    INGESTION_RATING: (id: string) => string;
+    INGESTION_RATING_STANDALONE: string;
+    INGESTION_RATING_EVENTS: string;
+    ENGAGE_CONFIG: (query?: string) => string;
+    COACH_CONFIG: (preview?: string) => string;
+    ENGAGE_RESPONSES: string;
+    ENGAGE_EVENTS: string;
+    ENGAGE_SURVEY_IMPRESSIONS: string;
+    ENGAGE_DEVICE_TOKEN: string;
+    ENGAGE_ATTACHMENTS_PRESIGN: string;
+    OTA_CHECK: string;
+};
+//# sourceMappingURL=endpoints.d.ts.map

package/lib/typescript/transport/http/httpClient.d.ts

@@ -0,0 +1,23 @@
+export interface HttpResponse {
+    status: number;
+    data?: any;
+}
+/** Default request deadline (ms). After this the request is aborted. */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 10000;
+/**
+ * Error thrown when a request is aborted because it exceeded the deadline.
+ * Distinct from a bare AbortError so callers can report `reason: timeout`.
+ */
+export declare class RequestTimeoutError extends Error {
+    readonly timeoutMs: number;
+    readonly cause?: unknown | undefined;
+    readonly isTimeout = true;
+    constructor(timeoutMs: number, cause?: unknown | undefined);
+}
+export declare class HttpClient {
+    private baseUrl;
+    private timeoutMs;
+    constructor(baseUrl: string, timeoutMs?: number);
+    post(path: string, body: any, headers?: Record<string, string>): Promise<HttpResponse>;
+}
+//# sourceMappingURL=httpClient.d.ts.map

package/lib/typescript/transport/rateLimit/retryAfter.d.ts

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

package/lib/typescript/transport/signing/requestSigner.d.ts

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

package/lib/typescript/vendor/protocol/index.d.ts

@@ -0,0 +1,345 @@
+/**
+ * @scalebun/protocol — Canonical wire-protocol schemas and types
+ *
+ * Single source of truth for all message schemas shared between the
+ * ScaleBun SDK and the ScaleBun Desktop debugger.
+ *
+ * Constraints:
+ *   - Pure TypeScript only — no external runtime deps (no zod), so the package
+ *     resolves cleanly under React Native / Metro.
+ *   - No React Native, no Electron, no Node-only APIs, no DOM globals.
+ *   - Consumable by any future binding (Expo, Flutter codegen, native wrappers).
+ *
+ * Protocol version: 1  (wire format is UNCHANGED by this refactor)
+ */
+import { type Infer } from './internal/validation';
+export { z } from './internal/validation';
+export type { Infer, SafeParseResult, ValidationIssue, ValidationError } from './internal/validation';
+export declare const PROTOCOL_VERSION = 1;
+/** Heartbeat interval sent in ACK; SDK uses this for its ping timer */
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;
+export declare const HelloMessageSchema: import("./internal/validation").ObjectSchemaType<Omit<{
+    protocolVersion: import("./internal/validation").NumberSchemaType;
+    deviceId: import("./internal/validation").StringSchemaType;
+    sessionId: import("./internal/validation").StringSchemaType;
+    timestamp: import("./internal/validation").NumberSchemaType;
+    sequence: import("./internal/validation").NumberSchemaType;
+}, "type" | "payload"> & {
+    type: import("./internal/validation").Schema<"hello">;
+    payload: import("./internal/validation").ObjectSchemaType<{
+        appName: import("./internal/validation").Schema<string | undefined>;
+        appVersion: import("./internal/validation").Schema<string | undefined>;
+        bundleId: import("./internal/validation").Schema<string | undefined>;
+        platform: import("./internal/validation").Schema<"android" | "ios" | "web" | undefined>;
+        osVersion: import("./internal/validation").Schema<string | undefined>;
+        deviceModel: import("./internal/validation").Schema<string | undefined>;
+        sdkVersion: import("./internal/validation").Schema<string | undefined>;
+        buildType: import("./internal/validation").Schema<"debug" | "release" | undefined>;
+        capabilities: import("./internal/validation").Schema<string[] | undefined>;
+        token: import("./internal/validation").Schema<string | undefined>;
+        /**
+         * Shared secret for desktop authentication.
+         *
+         * If the desktop has secret enforcement enabled, the SDK must provide
+         * this field and its value must match the desktop's configured secret.
+         * If enforcement is disabled on the desktop, this field is ignored.
+         *
+         * Optional for backward compatibility: old SDKs that don't send it
+         * will still parse correctly. The desktop decides whether to reject.
+         *
+         * SECURITY NOTE: This is local-network authentication only.
+         * The WS channel is unencrypted (ws://). The secret prevents
+         * unauthorized connections from same-network devices; it does NOT
+         * protect against packet sniffing. For transport encryption, use
+         * TLS (wss://), which is a separate concern.
+         *
+         * Migration path:
+         *   1. Desktop generates a secret on first launch (visible in Connection panel).
+         *   2. Copy the secret and add `secret: '<value>'` to your SDK debug config.
+         *   3. Desktop rejects connections with wrong/missing secret (close code 4401).
+         *   4. To allow old SDKs during migration, toggle "Allow unauthenticated
+         *      connections" ON in the Connection panel.
+         */
+        secret: import("./internal/validation").Schema<string | undefined>;
+        /**
+         * Transport-layer statistics reported by the SDK on each hello.
+         * Allows the desktop to surface data-loss warnings when the SDK
+         * buffer overflowed during a disconnect.
+         *
+         * Optional for backward compatibility: old SDKs that don't send it
+         * will still parse correctly.
+         */
+        transportStats: import("./internal/validation").Schema<{
+            droppedMessages: number;
+        } | undefined>;
+    }>;
+}>;
+export declare const EventCategorySchema: import("./internal/validation").Schema<"journey" | "session" | "crash" | "log" | "navigation" | "network" | "lifecycle" | "breadcrumb" | "replay" | "performance" | "profiler" | "export" | "custom">;
+export declare const LogLevelSchema: import("./internal/validation").Schema<"error" | "warn" | "info" | "debug">;
+/**
+ * ─── recordingSessionId Contract ────────────────────────────────────────────
+ *
+ * The wire envelope's top-level `sessionId` is the TRANSPORT session ID
+ * (`debug-xxx`), generated once in `DebugTransport.setIdentity()` when
+ * `enableDebug()` is called. It does NOT change between recordings.
+ *
+ * `payload.data.recordingSessionId` is the RECORDING session ID (`ses-xxx`),
+ * generated by `SessionManager.startSession()` each time the user presses
+ * "Record". It is null/absent when no recording is active.
+ *
+ * The desktop uses `recordingSessionId` to correctly correlate network and
+ * performance events to the active recording session without relying on the
+ * transport ID. When absent (legacy SDK), the desktop falls back to its
+ * existing time-bounded ingestion logic.
+ *
+ * Layers:
+ *   SDK Core     → stamps `recordingSessionId` via `DebugEventStream`
+ *   Desktop Core → reads it in `shouldIngest()` for precise session correlation
+ *
+ * Wire envelope is UNCHANGED. Only the event `data` payload gains this field.
+ * ────────────────────────────────────────────────────────────────────────────
+ */
+export declare const EventMessageSchema: import("./internal/validation").ObjectSchemaType<Omit<{
+    protocolVersion: import("./internal/validation").NumberSchemaType;
+    deviceId: import("./internal/validation").StringSchemaType;
+    sessionId: import("./internal/validation").StringSchemaType;
+    timestamp: import("./internal/validation").NumberSchemaType;
+    sequence: import("./internal/validation").NumberSchemaType;
+}, "type" | "payload"> & {
+    type: import("./internal/validation").Schema<"event">;
+    payload: import("./internal/validation").ObjectSchemaType<{
+        id: import("./internal/validation").StringSchemaType;
+        category: import("./internal/validation").Schema<"journey" | "session" | "crash" | "log" | "navigation" | "network" | "lifecycle" | "breadcrumb" | "replay" | "performance" | "profiler" | "export" | "custom">;
+        name: import("./internal/validation").StringSchemaType;
+        data: import("./internal/validation").Schema<Record<string, unknown> | undefined>;
+        level: import("./internal/validation").Schema<"error" | "warn" | "info" | "debug" | undefined>;
+        tags: import("./internal/validation").Schema<string[] | undefined>;
+    }>;
+}>;
+export declare const MetricMessageSchema: import("./internal/validation").ObjectSchemaType<Omit<{
+    protocolVersion: import("./internal/validation").NumberSchemaType;
+    deviceId: import("./internal/validation").StringSchemaType;
+    sessionId: import("./internal/validation").StringSchemaType;
+    timestamp: import("./internal/validation").NumberSchemaType;
+    sequence: import("./internal/validation").NumberSchemaType;
+}, "type" | "payload"> & {
+    type: import("./internal/validation").Schema<"metric">;
+    payload: import("./internal/validation").ObjectSchemaType<{
+        name: import("./internal/validation").StringSchemaType;
+        value: import("./internal/validation").NumberSchemaType;
+        unit: import("./internal/validation").Schema<string | undefined>;
+        tags: import("./internal/validation").Schema<Record<string, string> | undefined>;
+    }>;
+}>;
+export declare const CommandNameSchema: import("./internal/validation").Schema<"ping" | "setLogLevel" | "clearQueue" | "triggerFlush" | "addBreadcrumb" | "startReplay" | "stopReplay" | "snapshot" | "startSession" | "stopSession" | "captureFrame" | "perfCaptureScreen" | "journeyRecordToggle" | "journeyCaptureStep" | "journeySave" | "journeyRun" | "journeyStopRun" | "reloadApp" | "exportReportResult">;
+export declare const CommandMessageSchema: import("./internal/validation").ObjectSchemaType<Omit<{
+    protocolVersion: import("./internal/validation").NumberSchemaType;
+    deviceId: import("./internal/validation").StringSchemaType;
+    sessionId: import("./internal/validation").StringSchemaType;
+    timestamp: import("./internal/validation").NumberSchemaType;
+    sequence: import("./internal/validation").NumberSchemaType;
+}, "type" | "payload"> & {
+    type: import("./internal/validation").Schema<"command">;
+    payload: import("./internal/validation").ObjectSchemaType<{
+        commandId: import("./internal/validation").StringSchemaType;
+        name: import("./internal/validation").Schema<"ping" | "setLogLevel" | "clearQueue" | "triggerFlush" | "addBreadcrumb" | "startReplay" | "stopReplay" | "snapshot" | "startSession" | "stopSession" | "captureFrame" | "perfCaptureScreen" | "journeyRecordToggle" | "journeyCaptureStep" | "journeySave" | "journeyRun" | "journeyStopRun" | "reloadApp" | "exportReportResult">;
+        args: import("./internal/validation").Schema<Record<string, unknown> | undefined>;
+    }>;
+}>;
+export declare const CommandResultMessageSchema: import("./internal/validation").ObjectSchemaType<Omit<{
+    protocolVersion: import("./internal/validation").NumberSchemaType;
+    deviceId: import("./internal/validation").StringSchemaType;
+    sessionId: import("./internal/validation").StringSchemaType;
+    timestamp: import("./internal/validation").NumberSchemaType;
+    sequence: import("./internal/validation").NumberSchemaType;
+}, "type" | "payload"> & {
+    type: import("./internal/validation").Schema<"command_result">;
+    payload: import("./internal/validation").ObjectSchemaType<{
+        commandId: import("./internal/validation").StringSchemaType;
+        success: import("./internal/validation").Schema<boolean>;
+        data: import("./internal/validation").Schema<Record<string, unknown> | undefined>;
+        error: import("./internal/validation").Schema<string | undefined>;
+    }>;
+}>;
+export declare const ErrorMessageSchema: import("./internal/validation").ObjectSchemaType<Omit<{
+    protocolVersion: import("./internal/validation").NumberSchemaType;
+    deviceId: import("./internal/validation").StringSchemaType;
+    sessionId: import("./internal/validation").StringSchemaType;
+    timestamp: import("./internal/validation").NumberSchemaType;
+    sequence: import("./internal/validation").NumberSchemaType;
+}, "type" | "payload"> & {
+    type: import("./internal/validation").Schema<"error">;
+    payload: import("./internal/validation").ObjectSchemaType<{
+        code: import("./internal/validation").StringSchemaType;
+        message: import("./internal/validation").StringSchemaType;
+        details: import("./internal/validation").Schema<Record<string, unknown> | undefined>;
+    }>;
+}>;
+export declare const PingMessageSchema: import("./internal/validation").ObjectSchemaType<{
+    type: import("./internal/validation").Schema<"scalebun:ping">;
+    deviceId: import("./internal/validation").StringSchemaType;
+    timestamp: import("./internal/validation").NumberSchemaType;
+}>;
+export declare const PongMessageSchema: import("./internal/validation").ObjectSchemaType<{
+    type: import("./internal/validation").Schema<"scalebun:pong">;
+    timestamp: import("./internal/validation").NumberSchemaType;
+    echoTimestamp: import("./internal/validation").NumberSchemaType;
+}>;
+export declare const AckMessageSchema: import("./internal/validation").ObjectSchemaType<{
+    type: import("./internal/validation").Schema<"scalebun:ack">;
+    serverVersion: import("./internal/validation").StringSchemaType;
+    heartbeatIntervalMs: import("./internal/validation").NumberSchemaType;
+    timestamp: import("./internal/validation").NumberSchemaType;
+}>;
+export declare const DebugMessageSchema: import("./internal/validation").Schema<{
+    type: "hello";
+    sessionId: string;
+    deviceId: string;
+    timestamp: number;
+    protocolVersion: number;
+    sequence: number;
+    payload: {
+        platform?: "android" | "ios" | "web" | undefined;
+        appVersion?: string | undefined;
+        secret?: string | undefined;
+        token?: string | undefined;
+        osVersion?: string | undefined;
+        deviceModel?: string | undefined;
+        appName?: string | undefined;
+        bundleId?: string | undefined;
+        sdkVersion?: string | undefined;
+        buildType?: "debug" | "release" | undefined;
+        capabilities?: string[] | undefined;
+        transportStats?: {
+            droppedMessages: number;
+        } | undefined;
+    };
+} | {
+    type: "event";
+    sessionId: string;
+    deviceId: string;
+    timestamp: number;
+    protocolVersion: number;
+    sequence: number;
+    payload: {
+        id: string;
+        name: string;
+        category: "journey" | "session" | "crash" | "log" | "navigation" | "network" | "lifecycle" | "breadcrumb" | "replay" | "performance" | "profiler" | "export" | "custom";
+        tags?: string[] | undefined;
+        data?: Record<string, unknown> | undefined;
+        level?: "error" | "warn" | "info" | "debug" | undefined;
+    };
+} | {
+    type: "metric";
+    sessionId: string;
+    deviceId: string;
+    timestamp: number;
+    protocolVersion: number;
+    sequence: number;
+    payload: {
+        name: string;
+        value: number;
+        tags?: Record<string, string> | undefined;
+        unit?: string | undefined;
+    };
+} | {
+    type: "command";
+    sessionId: string;
+    deviceId: string;
+    timestamp: number;
+    protocolVersion: number;
+    sequence: number;
+    payload: {
+        name: "ping" | "setLogLevel" | "clearQueue" | "triggerFlush" | "addBreadcrumb" | "startReplay" | "stopReplay" | "snapshot" | "startSession" | "stopSession" | "captureFrame" | "perfCaptureScreen" | "journeyRecordToggle" | "journeyCaptureStep" | "journeySave" | "journeyRun" | "journeyStopRun" | "reloadApp" | "exportReportResult";
+        commandId: string;
+        args?: Record<string, unknown> | undefined;
+    };
+} | {
+    type: "command_result";
+    sessionId: string;
+    deviceId: string;
+    timestamp: number;
+    protocolVersion: number;
+    sequence: number;
+    payload: {
+        commandId: string;
+        success: boolean;
+        error?: string | undefined;
+        data?: Record<string, unknown> | undefined;
+    };
+} | {
+    type: "error";
+    sessionId: string;
+    deviceId: string;
+    timestamp: number;
+    protocolVersion: number;
+    sequence: number;
+    payload: {
+        message: string;
+        code: string;
+        details?: Record<string, unknown> | undefined;
+    };
+}>;
+export type HelloMessage = Infer<typeof HelloMessageSchema>;
+export type EventMessage = Infer<typeof EventMessageSchema>;
+export type MetricMessage = Infer<typeof MetricMessageSchema>;
+export type CommandMessage = Infer<typeof CommandMessageSchema>;
+export type CommandResultMessage = Infer<typeof CommandResultMessageSchema>;
+export type ErrorMessage = Infer<typeof ErrorMessageSchema>;
+export type PingMessage = Infer<typeof PingMessageSchema>;
+export type PongMessage = Infer<typeof PongMessageSchema>;
+export type AckMessage = Infer<typeof AckMessageSchema>;
+export type DebugMessage = Infer<typeof DebugMessageSchema>;
+/** Any message that can be received (including control messages) */
+export type AnyScaleBunMessage = DebugMessage | PingMessage | PongMessage | AckMessage;
+export type EventCategory = Infer<typeof EventCategorySchema>;
+export type LogLevel = Infer<typeof LogLevelSchema>;
+export type CommandName = Infer<typeof CommandNameSchema>;
+export type DeviceStatus = 'connected' | 'reconnecting' | 'disconnected';
+export interface DeviceInfo {
+    deviceId: string;
+    sessionId: string;
+    appName?: string;
+    appVersion?: string;
+    bundleId?: string;
+    platform?: string;
+    osVersion?: string;
+    deviceModel?: string;
+    deviceName?: string;
+    sdkVersion?: string;
+    buildType?: string;
+    capabilities?: string[];
+    connectedAt: number;
+    lastSeen: number;
+    pingLatencyMs?: number;
+    status: DeviceStatus;
+    /** Cumulative messages dropped by the SDK transport due to buffer overflow. */
+    droppedMessages?: number;
+}
+export type ParseResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+    raw: unknown;
+};
+/**
+ * Safely parse a raw message. Returns typed result or error description.
+ * Never throws.
+ */
+export declare function parseDebugMessage(raw: unknown): ParseResult<DebugMessage>;
+/**
+ * Parse any ScaleBun message including control messages (ping/pong/ack).
+ * Tries debug message first, then control messages. Never throws.
+ */
+export declare function parseAnyMessage(raw: unknown): ParseResult<AnyScaleBunMessage>;
+/**
+ * Safely serialize a message to JSON string. Never throws.
+ */
+export declare function serializeMessage(msg: DebugMessage | PingMessage): string | null;
+/**
+ * Safely deserialize a JSON string to a raw object. Never throws.
+ */
+export declare function deserializeMessage(data: string): unknown | null;
+//# sourceMappingURL=index.d.ts.map