@scalebun-release/react-native 2.5.0

package/lib/typescript/integrations/network/bodyCapture.d.ts

@@ -0,0 +1,101 @@
+/**
+ * ScaleBun SDK — Network Body & Header Capture Helpers
+ *
+ * Pure, no-throw utilities shared by both the fetch and XHR interceptors.
+ *
+ * ⚠️  PRIVACY: These helpers capture raw HTTP payload content.
+ * They MUST only be called when `captureNetworkBodies` is explicitly
+ * enabled by the integrator. The integrator is responsible for ensuring
+ * compliance with applicable privacy laws (GDPR, CCPA, etc.).
+ *
+ * Redaction is applied by the caller via `redactHeaders` / `redactBody` /
+ * `redactNetworkEvent` from `src/debug/redaction.ts`.
+ *
+ * Scope: JS-host only (fetch / XHR).
+ * Native-layer capture (OkHttp, URLSession) is future work.
+ */
+export declare const DEFAULT_BODY_MAX_BYTES = 65536;
+/** Marker emitted when a body cannot be read synchronously (FormData, stream). */
+export interface UnreadableBody {
+    kind: 'unreadable';
+    reason: 'FormData' | 'ReadableStream' | 'Blob' | 'ArrayBuffer' | 'unknown';
+}
+/** Marker emitted when a body is truncated to fit the byte cap. */
+export interface TruncatedBody {
+    kind: 'truncated';
+    preview: string;
+    totalBytes: number;
+    capturedBytes: number;
+}
+/** Marker emitted when the content-type indicates binary/non-textual content. */
+export interface SkippedBody {
+    kind: 'skipped';
+    reason: 'binary-content-type';
+    contentType: string;
+}
+export type CapturedBody = string | object | null | UnreadableBody | TruncatedBody | SkippedBody;
+/**
+ * Returns true when the content-type indicates binary/non-textual content
+ * that should be skipped rather than captured.
+ * Never throws.
+ */
+export declare function isBinaryContentType(contentType: string | null | undefined): boolean;
+/** UTF-8 byte length of a string. Never throws. */
+export declare function utf8ByteLength(s: string): number;
+/**
+ * Best-effort byte size of an outgoing request body, computed synchronously
+ * without consuming streams. Returns 0 when the size can't be known cheaply
+ * (FormData / Blob / stream). Never throws.
+ */
+export declare function requestBodyBytes(body: unknown): number;
+/** Parse a `content-length` header value to a byte count. 0 when absent/invalid. */
+export declare function contentLengthBytes(value: string | null | undefined): number;
+/**
+ * Synchronously extract the request body from a fetch `init.body` value.
+ *
+ * - `string`         → returned as-is (already textual)
+ * - `URLSearchParams` → `.toString()` (safe, synchronous)
+ * - `FormData`       → `{ kind: 'unreadable', reason: 'FormData' }`
+ * - `ReadableStream` → `{ kind: 'unreadable', reason: 'ReadableStream' }`
+ * - `Blob`           → `{ kind: 'unreadable', reason: 'Blob' }`
+ * - `ArrayBuffer`    → `{ kind: 'unreadable', reason: 'ArrayBuffer' }`
+ * - null/undefined   → null
+ *
+ * Never throws.
+ */
+export declare function extractRequestBody(body: unknown): CapturedBody;
+/**
+ * Read the fetch response body asynchronously using `response.clone()` so
+ * the original response stream remains intact for the caller.
+ *
+ * Skips binary content-types. Truncates at `maxBytes`.
+ * Never throws — returns a SkippedBody or UnreadableBody on any failure.
+ */
+export declare function extractResponseBodyFromFetch(response: Response, maxBytes: number): Promise<CapturedBody>;
+/**
+ * Extract the XHR response body from `xhr.responseText`.
+ *
+ * Skips binary content-types. Truncates at `maxBytes`.
+ * Never throws.
+ */
+export declare function extractResponseBodyFromXHR(responseText: string | null | undefined, contentType: string | null | undefined, maxBytes: number): CapturedBody;
+/**
+ * Normalise a fetch `Headers` object, `HeadersInit` value, or a plain
+ * `Record<string, string>` into a flat `Record<string, string>`.
+ *
+ * Returns an empty object on any failure.
+ * Never throws.
+ */
+export declare function extractFetchRequestHeaders(headers: HeadersInit_ | undefined): Record<string, string>;
+/**
+ * Convert a fetch `Headers` object to a plain `Record<string, string>`.
+ * Never throws.
+ */
+export declare function headersToRecord(headers: Headers): Record<string, string>;
+/**
+ * Parse XHR `getAllResponseHeaders()` string into a `Record<string, string>`.
+ * The raw string format is `"key: value\r\nkey2: value2\r\n"`.
+ * Never throws.
+ */
+export declare function parseXHRResponseHeaders(raw: string | null): Record<string, string>;
+//# sourceMappingURL=bodyCapture.d.ts.map

package/lib/typescript/integrations/xhr/xhrInterceptor.d.ts

@@ -0,0 +1,46 @@
+/**
+ * ScaleBun SDK — XHR Interceptor
+ *
+ * Monkey-patches `XMLHttpRequest` to capture network events.
+ *
+ * When `captureNetworkBodies` is enabled:
+ *   - Request headers: shimmed via `setRequestHeader` to record headers
+ *     before `send()` is called.
+ *   - Response headers: parsed from `getAllResponseHeaders()` in the `load`
+ *     handler.
+ *   - Request body: captured from the `send(body)` argument (strings only;
+ *     FormData / ArrayBuffer etc. get a placeholder).
+ *   - Response body: read from `xhr.responseText` after the response
+ *     arrives, truncated to `networkBodyMaxBytes`. Binary content-types
+ *     are skipped.
+ *   - All headers and bodies pass through `redactNetworkEvent` when
+ *     `redactNetwork` is true.
+ *
+ * ⚠️  PRIVACY: Body capture is opt-in via `captureNetworkBodies: true`.
+ * The integrator is responsible for compliance with applicable privacy
+ * regulations (GDPR, CCPA, etc.) and their own privacy policy.
+ *
+ * Scope: JS-host (XHR) only.
+ * Native-layer capture (OkHttp / URLSession) is a separate future task.
+ */
+export interface XHRInterceptorOptions {
+    /** Capture request/response headers and bodies. Default: false */
+    captureNetworkBodies?: boolean;
+    /** Max bytes to capture per body before truncating. Default: 65536 */
+    networkBodyMaxBytes?: number;
+    /** Apply redaction pipeline to captured headers/bodies. Default: true (fail closed) */
+    redactNetwork?: boolean;
+    /**
+     * Lifecycle ping for consumers that need to know a request is IN FLIGHT, not just what it
+     * turned out to be. `onEvent` fires once, on completion, and carries the whole record — which
+     * is the right shape for telemetry and useless for "is this screen still waiting".
+     *
+     * `end` is raised from `loadend`, which the platform dispatches exactly once for every
+     * terminal state — load, error, abort and timeout alike. The `load` and `error` handlers
+     * below deliberately do NOT carry it: they cover only two of the four, so pairing on them
+     * would leak a start for every cancelled request.
+     */
+    onRequestPhase?: (phase: 'start' | 'end', url: string) => void;
+}
+export declare function installXHRInterceptor(onEvent: (data: any) => void, options?: XHRInterceptorOptions): void;
+//# sourceMappingURL=xhrInterceptor.d.ts.map

package/lib/typescript/metro/composeSourceMap.d.ts

@@ -0,0 +1,26 @@
+export interface ArtifactMapping {
+    /** Absolute path of the pre-bundled artifact as Metro resolved it. */
+    artifactPath: string;
+    /** Absolute path of the artifact's stage-2 source map. */
+    mapPath: string;
+}
+interface MutableSourceMap {
+    version: number;
+    sources: (string | null)[];
+    sourcesContent?: (string | null)[];
+    names: string[];
+    mappings: string;
+    [key: string]: unknown;
+}
+/**
+ * Rewrite `metroMap` so mappings pointing into any of `artifacts` resolve through that artifact's
+ * stage-2 map. Returns the number of rewritten segments (0 = nothing matched, map returned as-is).
+ *
+ * The input object is mutated and returned — serialization happens exactly once, in the caller.
+ */
+export declare function composeSourceMap(metroMap: MutableSourceMap, artifacts: readonly ArtifactMapping[]): {
+    map: MutableSourceMap;
+    rewritten: number;
+};
+export {};
+//# sourceMappingURL=composeSourceMap.d.ts.map

package/lib/typescript/metro/featureModules.d.ts

@@ -0,0 +1,49 @@
+/**
+ * ScaleBun SDK — Build-time excludable feature registry.
+ *
+ * Metro has NO tree shaking: every module reachable from the entry point is bundled regardless of
+ * whether it is ever imported by name or ever executed. Measured on this SDK, importing a single
+ * tiny function instead of the whole facade changed the bundle by 115 bytes. So the only way a
+ * consumer can stop paying for a subsystem they do not use is to make it unreachable at RESOLUTION
+ * time, which is what `withScaleBun`'s `features` option does.
+ *
+ * Each entry lists module paths RELATIVE TO THE PACKAGE ROOT, without extension and without the
+ * `lib/module` / `lib/commonjs` / `src` prefix, so one list covers every build output.
+ *
+ * IMPORTANT: a module belongs here only if it is genuinely unreachable when the feature is off.
+ * `debug/` is the cautionary case — it also contains PRODUCTION code:
+ *   - `debug/redaction`      → redactBody / redactNetworkEvent, used by SessionManager,
+ *                              persistentQueue and both network interceptors. Removing it would
+ *                              silently disable payload redaction. It is NOT listed here.
+ *   - `debug/protocol`       → PROTOCOL_VERSION, imported as a VALUE by journeyManager and
+ *                              DesktopSessionTransport. NOT listed here.
+ *   - `debug/screenTracking` → getTrackedScreen, used by NetworkFeature. NOT listed here.
+ *   - `debug/bootstrap`      → re-exported from the package entry point. NOT listed here; it is
+ *                              instead guarded at runtime (see enableDebug).
+ */
+/**
+ * Feature name → the modules that become unreachable when it is disabled.
+ *
+ * Keep this narrow and evidence-backed. Every addition must be justified by checking who actually
+ * imports the module, distinguishing `import type` (erased) from a value import (not erased).
+ */
+export declare const SCALEBUN_FEATURE_MODULES: Readonly<Record<string, readonly string[]>>;
+export type ScaleBunFeatureName = keyof typeof SCALEBUN_FEATURE_MODULES;
+/**
+ * Build the set of module suffixes to exclude for a given feature configuration.
+ *
+ * Every known feature is resolved: an explicit `true`/`false` in `features` wins, otherwise the
+ * feature's default applies. Unknown names throw — a typo here would silently ship (or silently
+ * keep) code the caller believed they had configured, so it is an error rather than a warning.
+ */
+export declare function resolveExcludedModules(features: Readonly<Record<string, boolean | undefined>> | undefined): ReadonlySet<string>;
+/**
+ * Does `filePath` correspond to one of the excluded module paths?
+ *
+ * Matches against the tail of the path so a single registry entry covers `lib/module/…​.js`,
+ * `lib/commonjs/…​.js` and `src/…​.ts`. Callers MUST have already confirmed the file lives inside
+ * the ScaleBun package — matching on the tail alone would also match a host application's own
+ * `debug/commands.js`, which must never be stubbed.
+ */
+export declare function isExcludedModule(filePath: string, excluded: ReadonlySet<string>): boolean;
+//# sourceMappingURL=featureModules.d.ts.map

package/lib/typescript/metro/index.d.ts

@@ -0,0 +1,99 @@
+/**
+ * ScaleBun SDK — Metro configuration helper.
+ *
+ * PURPOSE
+ * The SDK integrates OPTIONALLY with a few third-party packages (screenshots,
+ * Notifee, Expo Router). Each is loaded through a guarded lazy `require()` at
+ * runtime, but Metro statically resolves every literal `require('<name>')` at
+ * BUNDLE time — before the runtime `try/catch` runs — so a host that does not
+ * install one of these packages fails to bundle with:
+ *
+ *     Unable to resolve module <name>
+ *
+ * `withScaleBun` wraps a host's Metro config so that, ONLY for ScaleBun's own
+ * optional integration packages, a failed resolution falls back to an empty
+ * stub module shipped inside the SDK. Everything else resolves exactly as before
+ * and unrelated missing modules still fail normally.
+ *
+ * This entry point is deliberately Node-only: it imports no React Native, no
+ * native modules, and no SDK runtime code, so it is safe to `require()` from a
+ * CommonJS `metro.config.js`.
+ *
+ * Resolution order for every request:
+ *   host's custom resolveRequest (if any) → Metro's default resolver →
+ *   on failure, if the name is a known ScaleBun optional module → empty stub;
+ *   otherwise the original resolution error is rethrown.
+ */
+export interface MetroSourceFileResolution {
+    type: 'sourceFile';
+    filePath: string;
+}
+export type MetroResolution = MetroSourceFileResolution | {
+    type: 'empty';
+} | {
+    type: 'assetFiles';
+    filePaths: readonly string[];
+};
+export interface MetroResolutionContext {
+    /**
+     * Metro's DEFAULT resolver. Metro guarantees this is present inside a custom
+     * `resolveRequest` and that it is NOT the custom resolver itself, so calling
+     * it cannot recurse back into `withScaleBun`.
+     */
+    resolveRequest: MetroResolver;
+    [key: string]: unknown;
+}
+export type MetroResolver = (context: MetroResolutionContext, moduleName: string, platform: string | null) => MetroResolution;
+export interface MetroResolverConfig {
+    resolveRequest?: MetroResolver;
+    [key: string]: unknown;
+}
+export interface MetroConfigLike {
+    resolver?: MetroResolverConfig;
+    [key: string]: unknown;
+}
+export interface WithScaleBunOptions {
+    /**
+     * Extra optional module names to stub when absent, merged with the built-in
+     * ScaleBun list. Use only for ScaleBun integrations you knowingly opt out of
+     * installing — never to silence unrelated missing modules.
+     */
+    optionalModules?: readonly string[];
+    /**
+     * Per-subsystem bundling switches. Metro performs no tree shaking, so a subsystem you never
+     * call is still bundled in full; resolution-time exclusion is the only mechanism that removes
+     * it. See ./featureModules for the module list behind each name and, importantly, for what
+     * deliberately stays (redaction, protocol constants and screen tracking live under `debug/`
+     * but are production code).
+     *
+     * | feature    | contents                              | default | measured cost |
+     * |------------|---------------------------------------|---------|---------------|
+     * | `devTools` | desktop-debugger bridge + profiler    | OFF     | ~53 KB        |
+     *
+     * `devTools` is OFF by default because the ScaleBun desktop debugger is a future product —
+     * no counterpart exists yet, so the tooling can only dial a socket nobody is listening on.
+     * When the desktop app ships, opt in with:
+     *
+     *     withScaleBun(config, { features: { devTools: true } })
+     *
+     * In a devTools-excluded bundle, `ScaleBun.init({ debugConnection })` logs one clear warning
+     * and continues; every production feature (analytics, sessions, replay, crash, network
+     * capture, redaction, Engage, OTA, push) is unaffected — verified by differential test.
+     */
+    features?: Readonly<Record<string, boolean | undefined>>;
+}
+/**
+ * Wrap a Metro configuration so the SDK's optional integration packages resolve
+ * to an empty stub when they are not installed.
+ *
+ * @param config  A Metro config (typically the result of `mergeConfig(...)`).
+ * @param options Optional extra module names to treat as ScaleBun-optional.
+ * @returns A NEW config object; the input and its `resolver` are not mutated.
+ */
+export declare function withScaleBun<T extends MetroConfigLike>(config: T, options?: WithScaleBunOptions): T & {
+    resolver: MetroResolverConfig;
+};
+export { SCALEBUN_OPTIONAL_MODULES } from './optionalModules';
+export type { ScaleBunOptionalModule } from './optionalModules';
+export default withScaleBun;
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/metro/optionalDependencyStub.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ScaleBun SDK — Empty stand-in for an ABSENT optional integration package.
+ *
+ * When `withScaleBun` detects that one of the SDK's optional integration
+ * packages (see ./optionalModules) is not installed, it points Metro at this
+ * file so bundling succeeds. The module intentionally exports nothing: every
+ * optional loader validates the real API shape it needs (e.g. `captureRef`,
+ * `createChannel`, `usePathname`), so an empty object reads as "integration
+ * unavailable" rather than a false positive.
+ *
+ * Do NOT add exports here. It must never look like a real installed package.
+ */
+export {};
+//# sourceMappingURL=optionalDependencyStub.d.ts.map

package/lib/typescript/metro/optionalModules.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ScaleBun SDK — Optional integration module registry.
+ *
+ * Single source of truth for the third-party packages the SDK integrates with
+ * OPTIONALLY. Each is loaded through a guarded, lazy `require()` at runtime, so a
+ * host that does not use the integration never needs the package at runtime.
+ *
+ * Metro, however, statically resolves every literal `require('<name>')` string at
+ * bundle time — BEFORE the runtime `try/catch` can execute — so an uninstalled
+ * package fails the bundle with "Unable to resolve module <name>". `withScaleBun`
+ * (see ./index) stubs exactly these names when they are absent so bundling
+ * succeeds while the integration stays disabled. See FIX_PUSH_UNKNOWN_MODULE.md.
+ *
+ * IMPORTANT: keep this list narrow. Only ScaleBun's own optional integrations
+ * belong here. Never add a package the SDK does not knowingly `require()`, so an
+ * unrelated missing module still fails resolution normally.
+ */
+export declare const SCALEBUN_OPTIONAL_MODULES: readonly ["react-native-view-shot", "@notifee/react-native", "expo-router"];
+export type ScaleBunOptionalModule = (typeof SCALEBUN_OPTIONAL_MODULES)[number];
+//# sourceMappingURL=optionalModules.d.ts.map

package/lib/typescript/metro/serializerCompose.d.ts

@@ -0,0 +1,46 @@
+import { type ArtifactMapping } from './composeSourceMap';
+type MetroModule = {
+    path: string;
+};
+export interface MetroSerializerOptions {
+    createModuleId: (filePath: string) => number;
+    excludeSource?: boolean;
+    processModuleFilter?: (module: MetroModule) => boolean;
+    shouldAddToIgnoreList?: (module: MetroModule) => boolean;
+    getSourceUrl?: (module: MetroModule) => string;
+    [key: string]: unknown;
+}
+export type MetroSerializerResult = string | {
+    code: string;
+    map: string;
+};
+export type MetroSerializer = (entryPoint: string, preModules: readonly MetroModule[], graph: {
+    dependencies: Map<string, MetroModule>;
+}, options: MetroSerializerOptions) => MetroSerializerResult | Promise<MetroSerializerResult>;
+interface MetroInternals {
+    baseJSBundle: (entryPoint: string, preModules: readonly MetroModule[], graph: {
+        dependencies: Map<string, MetroModule>;
+    }, options: MetroSerializerOptions) => unknown;
+    bundleToString: (bundle: unknown) => {
+        code: string;
+    };
+    sourceMapObject: (modules: readonly MetroModule[], options: object) => object;
+}
+/**
+ * Resolve Metro's serialization helpers from the HOST's Metro install. Returns null when they
+ * cannot be found (exotic Metro version/layout) — callers must degrade gracefully.
+ *
+ * Resolution is anchored at the APP (project root / cwd), never at this package's own location:
+ * `metro` is not a dependency of the SDK, so under pnpm's strict layout a bare require from here
+ * finds nothing — and even where it would resolve, the app's Metro is the one whose serializer
+ * contract must be matched, not whichever copy happens to sit near the SDK.
+ */
+export declare function resolveMetroInternals(searchPaths: readonly string[]): MetroInternals | null;
+/** The artifacts a package root can contain, with existence checked once at config time. */
+export declare function discoverArtifacts(packageRoot: string): ArtifactMapping[];
+/**
+ * Build the composing serializer. `hostSerializer` is the app's own customSerializer, if any.
+ */
+export declare function createComposingSerializer(artifacts: readonly ArtifactMapping[], internals: MetroInternals, hostSerializer: MetroSerializer | undefined): MetroSerializer;
+export {};
+//# sourceMappingURL=serializerCompose.d.ts.map

package/lib/typescript/pipeline/dispatcher/dispatcher.d.ts

@@ -0,0 +1,7 @@
+import { Envelope } from '../envelope/envelope';
+export declare class Dispatcher {
+    private transport;
+    constructor(transport: (batch: Envelope[]) => Promise<void>);
+    flush(): Promise<void>;
+}
+//# sourceMappingURL=dispatcher.d.ts.map

package/lib/typescript/pipeline/envelope/envelope.d.ts

@@ -0,0 +1,16 @@
+import { UserContext, AppContext, DeviceContext } from '../../core/context/user';
+export interface Envelope {
+    id: string;
+    type: 'event' | 'session' | 'crash' | 'log';
+    timestamp: number;
+    payload: any;
+    common?: {
+        user?: UserContext;
+        app?: AppContext;
+        device?: DeviceContext;
+        sessionId?: string;
+    };
+}
+export declare function createEnvelope(type: Envelope['type'], payload: any): Envelope;
+export type { UserContext as ContractUserContext, AppContext as ContractAppContext, DeviceContext as ContractDeviceContext, SessionContext as ContractSessionContext, } from '../../vendor/sdk-contracts';
+//# sourceMappingURL=envelope.d.ts.map

package/lib/typescript/pipeline/envelope/serializer.d.ts

@@ -0,0 +1,7 @@
+import { Envelope } from './envelope';
+export interface SerializedEnvelope {
+    body: string;
+    size: number;
+}
+export declare function serializeEnvelope(envelope: Envelope): SerializedEnvelope;
+//# sourceMappingURL=serializer.d.ts.map

package/lib/typescript/pipeline/processors/dedupe.d.ts

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

package/lib/typescript/pipeline/processors/enrich.d.ts

@@ -0,0 +1,3 @@
+import { Envelope } from '../envelope/envelope';
+export declare function enrichProcessor(envelope: Envelope, context: any): Envelope;
+//# sourceMappingURL=enrich.d.ts.map

package/lib/typescript/pipeline/processors/sampling.d.ts

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

package/lib/typescript/pipeline/processors/sanitize.d.ts

@@ -0,0 +1,3 @@
+import { Envelope } from '../envelope/envelope';
+export declare function sanitizeProcessor(envelope: Envelope): Envelope;
+//# sourceMappingURL=sanitize.d.ts.map

package/lib/typescript/pipeline/queue/flushQueue.d.ts

@@ -0,0 +1,12 @@
+import type { HttpClient } from '../../transport/http/httpClient';
+import type { PersistentQueue } from './persistentQueue';
+/** Outcome of a flush attempt — lets callers schedule retries / report status. */
+export interface FlushResult {
+    status: 'empty' | 'flushed' | 'skipped' | 'recoverable' | 'fatal';
+    /** Events in the attempted batch (0 when empty/skipped). */
+    batchSize: number;
+    /** Suggested delay before the next retry (recoverable failures only). */
+    nextRetryMs?: number;
+}
+export declare function flushQueue(queue: PersistentQueue, httpClient: HttpClient, deviceId: string, headers?: Record<string, string>): Promise<FlushResult>;
+//# sourceMappingURL=flushQueue.d.ts.map

package/lib/typescript/pipeline/queue/memoryQueue.d.ts

@@ -0,0 +1,12 @@
+import { Envelope } from '../envelope/envelope';
+export declare class MemoryQueue {
+    private items;
+    private maxItems;
+    constructor(maxItems?: number);
+    add(envelope: Envelope): void;
+    popBatch(limit?: number): Envelope[];
+    clear(): void;
+    get length(): number;
+}
+export declare const memoryQueue: MemoryQueue;
+//# sourceMappingURL=memoryQueue.d.ts.map

package/lib/typescript/pipeline/queue/persistentQueue.d.ts

@@ -0,0 +1,120 @@
+/**
+ * ScaleBun SDK — Disk-Backed Persistent Queue
+ *
+ * Persists event envelopes to a StorageBackend so they survive
+ * app restarts, crashes, and force-kills.
+ *
+ * STORAGE LAYOUT (chunked keys):
+ *   scalebun_q:meta        → { head, tail, count, totalBytes }
+ *   scalebun_q:e:{seq}     → JSON-serialized envelope
+ *
+ * Each envelope gets its own key. This makes add() O(1) and
+ * popBatch() O(batch_size) instead of the old O(queue_size)
+ * approach of serializing the entire array on every write.
+ *
+ * FEATURES:
+ * - Configurable bounds: maxBytes (default 5 MB), maxEntries (default 5000)
+ * - Redaction before write: strips PII from payloads before disk persistence
+ * - Leftover drain: on init, returns envelopes from previous run before
+ *   accepting new ones — ensures crash-time events are not lost
+ * - FIFO ordering: popBatch() returns envelopes in insertion order
+ *
+ * STORAGE: persists through the SDK's first-party `StorageBackend` (durable
+ * native file store by default; in-memory only as an emergency fallback). No
+ * third-party storage dependency is required.
+ */
+import type { Envelope } from '../envelope/envelope';
+import type { StorageBackend } from '../../storage/StorageBackend';
+export interface PersistenceConfig {
+    /** Whether disk persistence is enabled. Default: true */
+    enabled: boolean;
+    /** Max total bytes stored. Default: 5 MB (5_242_880) */
+    maxBytes: number;
+    /** Max total entries stored. Default: 5000 */
+    maxEntries: number;
+    /** Whether to redact PII before writing to disk. Default: true */
+    redactBeforeWrite: boolean;
+}
+export declare const DEFAULT_PERSISTENCE_CONFIG: PersistenceConfig;
+export declare class PersistentQueue {
+    private backend;
+    private config;
+    private meta;
+    /**
+     * Create a PersistentQueue backed by the given storage.
+     *
+     * @param backend - Storage backend (MemoryBackend for tests, native durable backend for prod)
+     * @param config  - Persistence configuration (bounds, redaction)
+     */
+    constructor(backend: StorageBackend, config?: Partial<PersistenceConfig>);
+    /**
+     * Add an envelope to the queue.
+     *
+     * If redactBeforeWrite is enabled, the envelope payload is redacted
+     * before serialization. If bounds are exceeded, the oldest entries
+     * are evicted.
+     */
+    add(envelope: Envelope): void;
+    /**
+     * Pop a batch of envelopes in FIFO order.
+     *
+     * @param limit - Max number of envelopes to return (default 50)
+     * @returns Array of deserialized envelopes
+     */
+    popBatch(limit?: number): Envelope[];
+    /**
+     * Return a previously-popped batch to the FRONT of the queue, preserving
+     * the batch's original FIFO order relative to the rest of the queue.
+     *
+     * Used when a flush fails with a recoverable error: the events must go back
+     * exactly where they were (oldest-first) rather than being appended to the
+     * tail behind newer events. These envelopes were already redacted on their
+     * first `add()`, so redaction is intentionally NOT re-applied here (avoids
+     * double-masking and wasted work).
+     */
+    requeueBatch(batch: Envelope[]): void;
+    /**
+     * Current queue length (number of envelopes).
+     */
+    length(): number;
+    /**
+     * Current approximate total bytes stored.
+     */
+    totalBytes(): number;
+    /**
+     * Drain all leftover envelopes from a previous app run.
+     *
+     * Call this during SDK init, BEFORE accepting new events.
+     * Returns all stored envelopes and clears the queue.
+     * If no leftovers exist, returns an empty array.
+     */
+    drainLeftovers(): Envelope[];
+    /**
+     * Clear all entries and reset metadata.
+     */
+    clear(): void;
+    /**
+     * Load queue metadata from storage.
+     * If no metadata exists, scans for orphan entry keys (recovery mode).
+     */
+    private _loadMeta;
+    /**
+     * Recovery mode: scan getAllKeys() for `scalebun_q:e:*` entries
+     * and reconstruct metadata from what's actually stored.
+     */
+    private _recoverMeta;
+    /** Save queue metadata to storage. */
+    private _saveMeta;
+    /**
+     * Evict oldest entries if adding `newBytes` would exceed caps.
+     */
+    private _evictIfNeeded;
+    /** Evict the oldest entry. */
+    private _evictOldest;
+    /**
+     * Apply redaction to an envelope before disk write.
+     * Returns a new envelope — never mutates the original.
+     */
+    private _redactEnvelope;
+}
+//# sourceMappingURL=persistentQueue.d.ts.map

package/lib/typescript/pipeline/queue/queuePolicy.d.ts

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

package/lib/typescript/pipeline/scheduler/flushScheduler.d.ts

@@ -0,0 +1,9 @@
+export declare class FlushScheduler {
+    private onFlush;
+    private timer?;
+    private running;
+    constructor(onFlush: () => Promise<void>);
+    start(intervalMs: number): void;
+    stop(): void;
+}
+//# sourceMappingURL=flushScheduler.d.ts.map

package/lib/typescript/pipeline/scheduler/retryPolicy.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Returns a delay in ms for the next retry attempt using exponential backoff with jitter.
+ */
+export declare function getExponentialBackoff(attempt: number, baseDelay?: number): number;
+//# sourceMappingURL=retryPolicy.d.ts.map