@scalebun/react-native 1.0.2 → 1.0.3

package/src/integrations/network/bodyCapture.ts

@@ -1,328 +1,328 @@
-/**
- * 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.
- */
-
-// ─── Constants ───────────────────────────────────────────────────────────────
-
-export const DEFAULT_BODY_MAX_BYTES = 65_536; // 64 KiB
-
-/**
- * Content-type prefixes for non-textual responses that should be skipped.
- * Capturing binary bodies would produce unreadable noise in the desktop panel.
- */
-const BINARY_CONTENT_TYPES = [
-    'image/',
-    'audio/',
-    'video/',
-    'application/octet-stream',
-    'application/zip',
-    'application/gzip',
-    'application/pdf',
-    'font/',
-];
-
-// ─── Types ────────────────────────────────────────────────────────────────────
-
-/** 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;
-
-// ─── Content-Type Guard ───────────────────────────────────────────────────────
-
-/**
- * Returns true when the content-type indicates binary/non-textual content
- * that should be skipped rather than captured.
- * Never throws.
- */
-export function isBinaryContentType(contentType: string | null | undefined): boolean {
-    if (!contentType) return false;
-    const lower = contentType.toLowerCase();
-    return BINARY_CONTENT_TYPES.some(prefix => lower.startsWith(prefix));
-}
-
-// ─── Size Helpers (non-PII byte counts) ───────────────────────────────────────
-//
-// Byte *counts* carry no payload content, so — unlike body/header capture — they
-// are safe to compute unconditionally (independent of `captureNetworkBodies`).
-// They feed the request/response size columns the dashboard network drawer shows.
-
-/** UTF-8 byte length of a string. Never throws. */
-export function utf8ByteLength(s: string): number {
-    try {
-        if (typeof Buffer !== 'undefined') return Buffer.byteLength(s, 'utf8');
-        // Fallback without TextEncoder: count UTF-8 bytes via URI encoding.
-        return unescape(encodeURIComponent(s)).length;
-    } catch {
-        return s.length;
-    }
-}
-
-/**
- * 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 function requestBodyBytes(body: unknown): number {
-    try {
-        if (body === null || body === undefined) return 0;
-        if (typeof body === 'string') return utf8ByteLength(body);
-        if (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams) {
-            return utf8ByteLength(body.toString());
-        }
-        if (typeof Blob !== 'undefined' && body instanceof Blob) return body.size;
-        if (body instanceof ArrayBuffer) return body.byteLength;
-        if (ArrayBuffer.isView(body as any)) return (body as ArrayBufferView).byteLength;
-        return 0;
-    } catch {
-        return 0;
-    }
-}
-
-/** Parse a `content-length` header value to a byte count. 0 when absent/invalid. */
-export function contentLengthBytes(value: string | null | undefined): number {
-    if (!value) return 0;
-    const n = parseInt(value, 10);
-    return Number.isFinite(n) && n >= 0 ? n : 0;
-}
-
-// ─── Request Body Extraction ─────────────────────────────────────────────────
-
-/**
- * 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 function extractRequestBody(body: unknown): CapturedBody {
-    try {
-        if (body === null || body === undefined) return null;
-        if (typeof body === 'string') return body;
-
-        // URLSearchParams — safe to stringify synchronously
-        if (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams) {
-            return body.toString();
-        }
-
-        // FormData — reading is async and would consume the stream
-        if (typeof FormData !== 'undefined' && body instanceof FormData) {
-            return { kind: 'unreadable', reason: 'FormData' };
-        }
-
-        // ReadableStream — cannot read without consuming. Referenced via globalThis
-        // because it isn't in the RN/Hermes lib types and is undefined on some
-        // Hermes builds.
-        const ReadableStreamCtor = (globalThis as any).ReadableStream;
-        if (ReadableStreamCtor && body instanceof ReadableStreamCtor) {
-            return { kind: 'unreadable', reason: 'ReadableStream' };
-        }
-
-        // Blob — async read, skip here
-        if (typeof Blob !== 'undefined' && body instanceof Blob) {
-            return { kind: 'unreadable', reason: 'Blob' };
-        }
-
-        // ArrayBuffer / TypedArray — binary, no meaningful text representation
-        if (body instanceof ArrayBuffer) {
-            return { kind: 'unreadable', reason: 'ArrayBuffer' };
-        }
-
-        // Unknown type — record but don't crash
-        return { kind: 'unreadable', reason: 'unknown' };
-    } catch {
-        return { kind: 'unreadable', reason: 'unknown' };
-    }
-}
-
-// ─── Fetch Response Body Extraction ─────────────────────────────────────────
-
-/**
- * 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 async function extractResponseBodyFromFetch(
-    response: Response,
-    maxBytes: number,
-): Promise<CapturedBody> {
-    try {
-        const contentType = response.headers.get('content-type');
-
-        // Skip non-textual content
-        if (isBinaryContentType(contentType)) {
-            return { kind: 'skipped', reason: 'binary-content-type', contentType: contentType ?? '' };
-        }
-
-        // Clone before reading — preserves the original stream for the caller
-        const clone = response.clone();
-        const text = await clone.text();
-
-        return truncateBody(text, maxBytes);
-    } catch {
-        return { kind: 'unreadable', reason: 'unknown' };
-    }
-}
-
-// ─── XHR Response Body Extraction ────────────────────────────────────────────
-
-/**
- * Extract the XHR response body from `xhr.responseText`.
- *
- * Skips binary content-types. Truncates at `maxBytes`.
- * Never throws.
- */
-export function extractResponseBodyFromXHR(
-    responseText: string | null | undefined,
-    contentType: string | null | undefined,
-    maxBytes: number,
-): CapturedBody {
-    try {
-        if (isBinaryContentType(contentType)) {
-            return { kind: 'skipped', reason: 'binary-content-type', contentType: contentType ?? '' };
-        }
-        if (responseText === null || responseText === undefined) return null;
-        return truncateBody(responseText, maxBytes);
-    } catch {
-        return { kind: 'unreadable', reason: 'unknown' };
-    }
-}
-
-// ─── Body Truncation ─────────────────────────────────────────────────────────
-
-/**
- * Truncate a text body to `maxBytes` (counted in UTF-16 code units, which
- * is the natural unit for JS strings and keeps the implementation simple and
- * fast without a TextEncoder round-trip).
- *
- * If the body fits, it is returned as-is (possibly JSON-parsed for object inspection).
- * If it exceeds the cap, returns a TruncatedBody marker.
- */
-function truncateBody(text: string, maxBytes: number): CapturedBody {
-    if (text.length <= maxBytes) {
-        // Attempt JSON parse for structured display in the desktop panel
-        try {
-            return JSON.parse(text);
-        } catch {
-            return text;
-        }
-    }
-
-    const preview = text.slice(0, maxBytes);
-    return {
-        kind: 'truncated',
-        preview,
-        totalBytes: text.length,
-        capturedBytes: maxBytes,
-    };
-}
-
-// ─── Header Extraction ────────────────────────────────────────────────────────
-
-/**
- * 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 function extractFetchRequestHeaders(
-    headers: HeadersInit_ | undefined,
-): Record<string, string> {
-    if (!headers) return {};
-    try {
-        if (headers instanceof Headers) {
-            return headersToRecord(headers);
-        }
-        if (Array.isArray(headers)) {
-            return Object.fromEntries(headers);
-        }
-        // Plain object
-        return { ...(headers as Record<string, string>) };
-    } catch {
-        return {};
-    }
-}
-
-/**
- * Convert a fetch `Headers` object to a plain `Record<string, string>`.
- * Never throws.
- */
-export function headersToRecord(headers: Headers): Record<string, string> {
-    const result: Record<string, string> = {};
-    try {
-        headers.forEach((value: string, key: string) => {
-            result[key] = value;
-        });
-    } catch {
-        // Partial result is acceptable
-    }
-    return result;
-}
-
-/**
- * Parse XHR `getAllResponseHeaders()` string into a `Record<string, string>`.
- * The raw string format is `"key: value\r\nkey2: value2\r\n"`.
- * Never throws.
- */
-export function parseXHRResponseHeaders(raw: string | null): Record<string, string> {
-    if (!raw) return {};
-    const result: Record<string, string> = {};
-    try {
-        for (const line of raw.split('\r\n')) {
-            const colonIndex = line.indexOf(': ');
-            if (colonIndex === -1) continue;
-            const key = line.slice(0, colonIndex).trim().toLowerCase();
-            const value = line.slice(colonIndex + 2).trim();
-            if (key) result[key] = value;
-        }
-    } catch {
-        // Partial result is acceptable
-    }
-    return result;
-}
+/**
+ * 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.
+ */
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+export const DEFAULT_BODY_MAX_BYTES = 65_536; // 64 KiB
+
+/**
+ * Content-type prefixes for non-textual responses that should be skipped.
+ * Capturing binary bodies would produce unreadable noise in the desktop panel.
+ */
+const BINARY_CONTENT_TYPES = [
+    'image/',
+    'audio/',
+    'video/',
+    'application/octet-stream',
+    'application/zip',
+    'application/gzip',
+    'application/pdf',
+    'font/',
+];
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/** 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;
+
+// ─── Content-Type Guard ───────────────────────────────────────────────────────
+
+/**
+ * Returns true when the content-type indicates binary/non-textual content
+ * that should be skipped rather than captured.
+ * Never throws.
+ */
+export function isBinaryContentType(contentType: string | null | undefined): boolean {
+    if (!contentType) return false;
+    const lower = contentType.toLowerCase();
+    return BINARY_CONTENT_TYPES.some(prefix => lower.startsWith(prefix));
+}
+
+// ─── Size Helpers (non-PII byte counts) ───────────────────────────────────────
+//
+// Byte *counts* carry no payload content, so — unlike body/header capture — they
+// are safe to compute unconditionally (independent of `captureNetworkBodies`).
+// They feed the request/response size columns the dashboard network drawer shows.
+
+/** UTF-8 byte length of a string. Never throws. */
+export function utf8ByteLength(s: string): number {
+    try {
+        if (typeof Buffer !== 'undefined') return Buffer.byteLength(s, 'utf8');
+        // Fallback without TextEncoder: count UTF-8 bytes via URI encoding.
+        return unescape(encodeURIComponent(s)).length;
+    } catch {
+        return s.length;
+    }
+}
+
+/**
+ * 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 function requestBodyBytes(body: unknown): number {
+    try {
+        if (body === null || body === undefined) return 0;
+        if (typeof body === 'string') return utf8ByteLength(body);
+        if (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams) {
+            return utf8ByteLength(body.toString());
+        }
+        if (typeof Blob !== 'undefined' && body instanceof Blob) return body.size;
+        if (body instanceof ArrayBuffer) return body.byteLength;
+        if (ArrayBuffer.isView(body as any)) return (body as ArrayBufferView).byteLength;
+        return 0;
+    } catch {
+        return 0;
+    }
+}
+
+/** Parse a `content-length` header value to a byte count. 0 when absent/invalid. */
+export function contentLengthBytes(value: string | null | undefined): number {
+    if (!value) return 0;
+    const n = parseInt(value, 10);
+    return Number.isFinite(n) && n >= 0 ? n : 0;
+}
+
+// ─── Request Body Extraction ─────────────────────────────────────────────────
+
+/**
+ * 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 function extractRequestBody(body: unknown): CapturedBody {
+    try {
+        if (body === null || body === undefined) return null;
+        if (typeof body === 'string') return body;
+
+        // URLSearchParams — safe to stringify synchronously
+        if (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams) {
+            return body.toString();
+        }
+
+        // FormData — reading is async and would consume the stream
+        if (typeof FormData !== 'undefined' && body instanceof FormData) {
+            return { kind: 'unreadable', reason: 'FormData' };
+        }
+
+        // ReadableStream — cannot read without consuming. Referenced via globalThis
+        // because it isn't in the RN/Hermes lib types and is undefined on some
+        // Hermes builds.
+        const ReadableStreamCtor = (globalThis as any).ReadableStream;
+        if (ReadableStreamCtor && body instanceof ReadableStreamCtor) {
+            return { kind: 'unreadable', reason: 'ReadableStream' };
+        }
+
+        // Blob — async read, skip here
+        if (typeof Blob !== 'undefined' && body instanceof Blob) {
+            return { kind: 'unreadable', reason: 'Blob' };
+        }
+
+        // ArrayBuffer / TypedArray — binary, no meaningful text representation
+        if (body instanceof ArrayBuffer) {
+            return { kind: 'unreadable', reason: 'ArrayBuffer' };
+        }
+
+        // Unknown type — record but don't crash
+        return { kind: 'unreadable', reason: 'unknown' };
+    } catch {
+        return { kind: 'unreadable', reason: 'unknown' };
+    }
+}
+
+// ─── Fetch Response Body Extraction ─────────────────────────────────────────
+
+/**
+ * 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 async function extractResponseBodyFromFetch(
+    response: Response,
+    maxBytes: number,
+): Promise<CapturedBody> {
+    try {
+        const contentType = response.headers.get('content-type');
+
+        // Skip non-textual content
+        if (isBinaryContentType(contentType)) {
+            return { kind: 'skipped', reason: 'binary-content-type', contentType: contentType ?? '' };
+        }
+
+        // Clone before reading — preserves the original stream for the caller
+        const clone = response.clone();
+        const text = await clone.text();
+
+        return truncateBody(text, maxBytes);
+    } catch {
+        return { kind: 'unreadable', reason: 'unknown' };
+    }
+}
+
+// ─── XHR Response Body Extraction ────────────────────────────────────────────
+
+/**
+ * Extract the XHR response body from `xhr.responseText`.
+ *
+ * Skips binary content-types. Truncates at `maxBytes`.
+ * Never throws.
+ */
+export function extractResponseBodyFromXHR(
+    responseText: string | null | undefined,
+    contentType: string | null | undefined,
+    maxBytes: number,
+): CapturedBody {
+    try {
+        if (isBinaryContentType(contentType)) {
+            return { kind: 'skipped', reason: 'binary-content-type', contentType: contentType ?? '' };
+        }
+        if (responseText === null || responseText === undefined) return null;
+        return truncateBody(responseText, maxBytes);
+    } catch {
+        return { kind: 'unreadable', reason: 'unknown' };
+    }
+}
+
+// ─── Body Truncation ─────────────────────────────────────────────────────────
+
+/**
+ * Truncate a text body to `maxBytes` (counted in UTF-16 code units, which
+ * is the natural unit for JS strings and keeps the implementation simple and
+ * fast without a TextEncoder round-trip).
+ *
+ * If the body fits, it is returned as-is (possibly JSON-parsed for object inspection).
+ * If it exceeds the cap, returns a TruncatedBody marker.
+ */
+function truncateBody(text: string, maxBytes: number): CapturedBody {
+    if (text.length <= maxBytes) {
+        // Attempt JSON parse for structured display in the desktop panel
+        try {
+            return JSON.parse(text);
+        } catch {
+            return text;
+        }
+    }
+
+    const preview = text.slice(0, maxBytes);
+    return {
+        kind: 'truncated',
+        preview,
+        totalBytes: text.length,
+        capturedBytes: maxBytes,
+    };
+}
+
+// ─── Header Extraction ────────────────────────────────────────────────────────
+
+/**
+ * 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 function extractFetchRequestHeaders(
+    headers: HeadersInit_ | undefined,
+): Record<string, string> {
+    if (!headers) return {};
+    try {
+        if (headers instanceof Headers) {
+            return headersToRecord(headers);
+        }
+        if (Array.isArray(headers)) {
+            return Object.fromEntries(headers);
+        }
+        // Plain object
+        return { ...(headers as Record<string, string>) };
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * Convert a fetch `Headers` object to a plain `Record<string, string>`.
+ * Never throws.
+ */
+export function headersToRecord(headers: Headers): Record<string, string> {
+    const result: Record<string, string> = {};
+    try {
+        headers.forEach((value: string, key: string) => {
+            result[key] = value;
+        });
+    } catch {
+        // Partial result is acceptable
+    }
+    return result;
+}
+
+/**
+ * Parse XHR `getAllResponseHeaders()` string into a `Record<string, string>`.
+ * The raw string format is `"key: value\r\nkey2: value2\r\n"`.
+ * Never throws.
+ */
+export function parseXHRResponseHeaders(raw: string | null): Record<string, string> {
+    if (!raw) return {};
+    const result: Record<string, string> = {};
+    try {
+        for (const line of raw.split('\r\n')) {
+            const colonIndex = line.indexOf(': ');
+            if (colonIndex === -1) continue;
+            const key = line.slice(0, colonIndex).trim().toLowerCase();
+            const value = line.slice(colonIndex + 2).trim();
+            if (key) result[key] = value;
+        }
+    } catch {
+        // Partial result is acceptable
+    }
+    return result;
+}