@replayio/self-healing-capture 0.1.0

package/README.md

@@ -0,0 +1,92 @@
+# @replayio/self-healing-capture
+
+Browser capture for FullStory sessions. This package owns the producers for network exchanges,
+clicks, input/change values, paste text, keyboard events, user identity, activity counts and page/session
+context. Install the package rather than copying a recorder into your app.
+
+```sh
+npm install @replayio/self-healing-capture @fullstory/browser
+```
+
+Call once in your production browser entry point, before rendering the application:
+
+```ts
+import { initCapture } from '@replayio/self-healing-capture'
+
+export const capture = initCapture({
+  orgId: '<your FullStory organization ID>',
+  endpoint: '/api/self-healing/session', // same-origin server route
+  onError: error => console.error('Session capture failed', error),
+})
+
+// When the application authenticates a user:
+capture.identify({ id: user.id, name: user.name, email: user.email })
+```
+
+The package initializes FullStory itself. Remove the previous recorder/FullStory initialization
+when migrating; do not install a second fetch wrapper. Do not call `initCapture` during SSR.
+Repeated calls with the same org/endpoint return the existing controller. It captures fetch traffic
+(browser-visible headers and bodies), not XMLHttpRequest or WebSockets. It preserves the existing
+QA capture fields without introducing a redaction policy.
+
+## Server route
+
+The browser has no provider or account credentials. Its same-origin POST endpoint uses the app's
+existing access controls and forwards the JSON body to Self Healing's
+`POST /api/v1/connection/sessions`, adding `Authorization: Bearer <SELF_HEALING_API_KEY>` server-side.
+Preserve the upstream response status so the recorder can detect failures.
+
+For a standalone QA integration, configure the endpoint to the app's QA registration proxy instead.
+The wire format is QA's existing `{session_url, auxiliary_data}` envelope. No Self Healing server or
+package import is required in QA's ingestion/review implementation.
+
+## Uploads and lifecycle
+
+- Network, interaction and page-context artifacts use QA's version-1 namespace/key contracts.
+  `session/capture-producer` additionally identifies this package and version. That is provenance,
+  not authentication. QA recognizes network/interaction data by their artifact keys.
+- The package batches whole events into UTF-8 JSON requests of at most 256 KiB. Uploads use the
+  original fetch, so they do not capture themselves. Network errors, 429, server errors and
+  Self Healing's `upload_busy` retry up to three attempts with identical bodies and event IDs.
+- A single event larger than the request limit fails explicitly through `onError` and `flush()`;
+  it is not truncated to fit. Bodies above 1 MB are null and the per-page/session network budget
+  is 8 MB, matching the existing producer. Dropped counts are included in capture context.
+  Network and interaction counts each stop at 5,000 entries per page/session.
+- `await capture.flush()` waits for current in-flight captures and pending uploads. It rejects
+  if FullStory has no session yet or any capture/upload has failed. There is no durable offline queue.
+- `await capture.stop()` stops new capture, removes interaction listeners and flushes outstanding
+  data. It does not stop FullStory recording or seal the server's session, and it cannot be restarted
+  on the same page. `identify()` is a no-op after stopping.
+- Session rollover preserves ownership of requests already in flight and resets producer counters.
+  `captured_at` is absolute milliseconds; `source_timestamp` is page-relative milliseconds.
+
+Finalization is a server operation. Once a whole session has ended and all pages' uploads succeeded,
+send `{session_url, auxiliary_data: [], complete: true}` to Self Healing. A page flush or unload alone
+cannot establish that a multi-page FullStory session has ended.
+
+## Development and release
+
+The source of truth is `packages/capture/src` in `replayio/self-healing`. Changes to producers belong
+here. QA owns its independent ingestion schemas and compatibility tests, not another installer copy.
+
+Publish locally with interactive npm authentication and 2FA:
+
+```sh
+npm ci
+npm run capture:publish
+```
+
+Run from a terminal using Node 22.14+ and an npm account with publishing access to `@replayio`.
+The script checks whether the manifest version exists, runs tests and the production build, packs
+the tested output into a temporary directory, logs into npm if necessary, and publishes that exact
+artifact. npm owns the browser login/security-key/2FA prompts. Credentials and OTPs are not script
+arguments or repository secrets. Follow npm's authentication prompt when it appears.
+
+Use `npm run capture:publish -- --dry-run` to test building and packaging without login or publication.
+Registry errors fail the version check; already-published versions are skipped. After publishing,
+the script checks that the version is visible on npm. If visibility verification fails, rerun: an
+existing version is skipped, never overwritten. Temporary tarballs are removed when the script exits.
+
+For later releases, update the package version and emitted producer metadata together, update the
+root lockfile, and run the script from the reviewed revision. The producer test checks that metadata
+matches the manifest. Installers receive updates through dependency upgrades and their lockfiles.

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+export interface CaptureOptions {
+    orgId: string;
+    /** Same-origin POST route holding the server-side credential. */
+    endpoint?: string;
+    onError?: (error: Error) => void;
+}
+export interface CaptureController {
+    identify(user: FullStoryUser | null): void;
+    /** Wait for in-flight captures and upload all known sessions. Rejects on capture/upload failure. */
+    flush(): Promise<void>;
+    /** Stop new capture and flush existing data; does not seal a FullStory session. */
+    stop(): Promise<void>;
+}
+export interface FullStoryUser {
+    id: string;
+    name: string;
+    email: string | null;
+}
+export declare function initCapture(options: CaptureOptions): CaptureController;

package/dist/index.js

@@ -0,0 +1,544 @@
+import { FullStory, init } from "@fullstory/browser";
+import { splitBatches } from "./transport.js";
+let active;
+let activeOptions;
+const CAPTURED_SESSION_INTERACTION_EVENTS = [
+    "click",
+    "change",
+    "input",
+    "paste",
+    "keydown",
+    "keyup",
+];
+function countsAsSessionInteraction(event) {
+    return (event.type === "click" ||
+        event.type === "change" ||
+        (event instanceof KeyboardEvent &&
+            event.type === "keydown" &&
+            ["Enter", "Escape"].includes(event.key)));
+}
+const MAX_BODY_BYTES = 1_000_000;
+const MAX_CAPTURE_BYTES = 8_000_000;
+const MAX_CAPTURED_INTERACTIONS = 5_000;
+const ACTIONABLE_SELECTOR = 'button, a[href], input, select, textarea, summary, [role="button"], [role="link"], [role="checkbox"], [role="menuitem"], [role="option"], [role="radio"], [role="switch"], [role="tab"], [contenteditable="true"]';
+let setCapturedUserEmail = null;
+let fullStoryInitialized = false;
+/** Identify the authenticated user in FullStory and attach their email to Replay QA's session record. */
+function identifyFullStoryUser(user) {
+    if (!fullStoryInitialized || !user)
+        return;
+    FullStory("setIdentity", {
+        uid: user.id,
+        properties: {
+            displayName: user.name,
+            ...(user.email ? { email: user.email } : {}),
+        },
+    });
+    if (user.email)
+        setCapturedUserEmail?.(user.email);
+}
+function shouldStopSessionUploads(status) {
+    return status < 200 || status >= 300;
+}
+export function initCapture(options) {
+    if (typeof window === "undefined")
+        throw new Error("initCapture must run in the browser");
+    if (active) {
+        if (options.orgId !== activeOptions?.orgId ||
+            options.endpoint !== activeOptions?.endpoint) {
+            throw new Error("Capture is already initialized with different options");
+        }
+        return active;
+    }
+    if (!options.orgId)
+        throw new Error("A FullStory organization ID is required");
+    const endpoint = new URL(options.endpoint ?? "/api/self-healing/session", window.location.href);
+    if (endpoint.origin !== window.location.origin ||
+        endpoint.username ||
+        endpoint.password) {
+        throw new Error("Capture endpoint must be same-origin");
+    }
+    const orgId = options.orgId;
+    let stopped = false;
+    let lastError;
+    const reportError = (error) => {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        try {
+            (options.onError ?? console.error)(lastError);
+        }
+        catch {
+            /* observers cannot break the app */
+        }
+    };
+    const inFlight = new Set();
+    const nativeFetch = window.fetch.bind(window);
+    const pageId = crypto.randomUUID();
+    let userEmail = null;
+    let fullStoryReady = false;
+    let syntheticExchange = null;
+    // All auxiliary producers use this same session object, including work finishing after rollover.
+    function createCaptureSession(sessionUrl, previousSessionUrl) {
+        return {
+            sessionUrl,
+            previousSessionUrl,
+            capturedExchanges: [],
+            capturedInteractions: [],
+            capturedBytes: 0,
+            interactionCount: 0,
+            queuedExchangeCount: 0,
+            queuedInteractionCount: -1,
+            queuedCapturedInteractionCount: 0,
+            uploadsStopped: false,
+            userEmail,
+            queuedUserEmail: null,
+            uploadTimer: null,
+            uploadChain: Promise.resolve(),
+            droppedNetworkCount: 0,
+            droppedInteractionCount: 0,
+            queuedContext: "",
+        };
+    }
+    let currentSession = createCaptureSession(null, null);
+    const sessions = new Set([currentSession]);
+    function synchronizeSession(sessionUrl) {
+        if (currentSession.sessionUrl !== sessionUrl) {
+            if (currentSession.sessionUrl === null) {
+                // Requests made before SDK readiness belong to the first session, even if still in flight.
+                currentSession.sessionUrl = sessionUrl;
+            }
+            else {
+                const previous = currentSession;
+                if (previous.uploadTimer)
+                    clearTimeout(previous.uploadTimer);
+                previous.uploadTimer = null;
+                void queueCaptureUpload(previous);
+                currentSession = createCaptureSession(sessionUrl, previous.sessionUrl);
+                sessions.add(currentSession);
+            }
+            uploadCapture(currentSession);
+        }
+        return currentSession;
+    }
+    function captureSession() {
+        if (!fullStoryReady)
+            return currentSession;
+        // Read at the event boundary: an idle tab can resume into a new FullStory session without reload.
+        try {
+            const sessionUrl = FullStory("getSession", { format: "url" });
+            return sessionUrl ? synchronizeSession(sessionUrl) : null;
+        }
+        catch {
+            // Stopped/unavailable recording must not assign new events to a stale session.
+            return null;
+        }
+    }
+    setCapturedUserEmail = (email) => {
+        userEmail = email;
+        const session = captureSession();
+        if (!session)
+            return;
+        session.userEmail = email;
+        uploadCapture(session);
+    };
+    async function boundedBody(value) {
+        const bytes = await value.clone().arrayBuffer();
+        if (bytes.byteLength > MAX_BODY_BYTES)
+            return null;
+        return new TextDecoder().decode(bytes);
+    }
+    async function sendCaptureBatch(body) {
+        for (let attempt = 0;; attempt++) {
+            try {
+                const response = await nativeFetch(endpoint.href, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body,
+                });
+                if (attempt === 2)
+                    return response;
+                const busy = response.status === 409 &&
+                    (await response
+                        .clone()
+                        .json()
+                        .catch(() => null))?.error?.code === "upload_busy";
+                if (response.status < 500 && response.status !== 429 && !busy)
+                    return response;
+            }
+            catch (error) {
+                if (attempt === 2)
+                    throw error;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 500 * 2 ** attempt));
+        }
+    }
+    function queueCaptureUpload(session) {
+        if (!session.sessionUrl || session.uploadsStopped)
+            return Promise.resolve();
+        const exchanges = session.capturedExchanges
+            .slice(session.queuedExchangeCount)
+            .map(({ startup_body: _body, status_text: _status, ...exchange }) => exchange)
+            .sort((a, b) => a.source_timestamp - b.source_timestamp);
+        const context = JSON.stringify({
+            id: pageId,
+            page_started_at: performance.timeOrigin,
+            previous_session_url: session.previousSessionUrl,
+            dropped_network_count: session.droppedNetworkCount,
+            dropped_interaction_count: session.droppedInteractionCount,
+        });
+        const auxiliaryData = [
+            {
+                namespace: "session",
+                key: "capture-producer",
+                schema_version: 1,
+                payload: { name: "@replayio/self-healing-capture", version: "0.1.0" },
+            },
+            ...(context !== session.queuedContext
+                ? [
+                    {
+                        namespace: "session",
+                        key: "capture-context",
+                        schema_version: 1,
+                        payload: {
+                            version: 1,
+                            pages: [
+                                {
+                                    id: pageId,
+                                    page_started_at: performance.timeOrigin,
+                                    previous_session_url: session.previousSessionUrl,
+                                    dropped_network_count: session.droppedNetworkCount,
+                                    dropped_interaction_count: session.droppedInteractionCount,
+                                },
+                            ],
+                        },
+                    },
+                ]
+                : []),
+            ...(exchanges.length > 0
+                ? [
+                    {
+                        namespace: "network",
+                        key: "captured-exchanges",
+                        schema_version: 1,
+                        payload: { version: 1, exchanges },
+                    },
+                ]
+                : []),
+            ...(session.capturedInteractions.length !==
+                session.queuedCapturedInteractionCount
+                ? [
+                    {
+                        namespace: "interaction",
+                        key: "captured-interactions",
+                        schema_version: 1,
+                        payload: {
+                            version: 1,
+                            interactions: session.capturedInteractions.slice(session.queuedCapturedInteractionCount),
+                        },
+                    },
+                ]
+                : []),
+            ...(session.interactionCount !== session.queuedInteractionCount
+                ? [
+                    {
+                        namespace: "session",
+                        key: "metrics",
+                        schema_version: 1,
+                        payload: {
+                            version: 1,
+                            interaction_count: session.interactionCount,
+                        },
+                    },
+                ]
+                : []),
+            ...(session.userEmail && session.userEmail !== session.queuedUserEmail
+                ? [
+                    {
+                        namespace: "session",
+                        key: "identity",
+                        schema_version: 1,
+                        payload: { version: 1, email: session.userEmail },
+                    },
+                ]
+                : []),
+        ];
+        if (auxiliaryData.length === 1)
+            return session.uploadChain;
+        session.queuedContext = context;
+        session.queuedExchangeCount = session.capturedExchanges.length;
+        session.queuedInteractionCount = session.interactionCount;
+        session.queuedCapturedInteractionCount =
+            session.capturedInteractions.length;
+        session.queuedUserEmail = session.userEmail;
+        const body = {
+            session_url: session.sessionUrl,
+            auxiliary_data: auxiliaryData,
+        };
+        // Each immutable batch is retried with the same event IDs; the server deduplicates it.
+        session.uploadChain = session.uploadChain
+            .then(async () => {
+            if (session.uploadsStopped)
+                return;
+            for (const batch of splitBatches(body)) {
+                const response = await sendCaptureBatch(batch);
+                if (shouldStopSessionUploads(response.status)) {
+                    session.uploadsStopped = true;
+                    throw new Error(`Capture upload failed: ${response.status}`);
+                }
+            }
+        })
+            .catch((error) => {
+            session.uploadsStopped = true;
+            reportError(error);
+        });
+        return session.uploadChain;
+    }
+    function uploadCapture(session) {
+        if (!session.sessionUrl || session.uploadsStopped)
+            return;
+        if (session.uploadTimer)
+            return;
+        session.uploadTimer = setTimeout(() => {
+            session.uploadTimer = null;
+            void queueCaptureUpload(session);
+        }, 250);
+    }
+    function selectorFor(element) {
+        const tag = element.tagName.toLowerCase();
+        const testId = element.getAttribute("data-testid");
+        const candidate = (selector) => selector.length <= 2_000 ? selector : null;
+        if (testId)
+            return candidate(`[data-testid=${JSON.stringify(testId)}]`);
+        if (element.id)
+            return candidate(`#${CSS.escape(element.id)}`);
+        const ariaLabel = element.getAttribute("aria-label");
+        if (ariaLabel)
+            return candidate(`${tag}[aria-label=${JSON.stringify(ariaLabel)}]`);
+        const name = element.getAttribute("name");
+        if (name)
+            return candidate(`${tag}[name=${JSON.stringify(name)}]`);
+        const label = (element.textContent ?? "")
+            .replace(/\s+/g, " ")
+            .trim()
+            .slice(0, 500);
+        return label
+            ? candidate(`${tag}:has-text(${JSON.stringify(label)})`)
+            : null;
+    }
+    function recordInteraction(event) {
+        if (stopped || !event.isTrusted)
+            return;
+        const session = captureSession();
+        if (!session)
+            return;
+        if (countsAsSessionInteraction(event))
+            session.interactionCount++;
+        if (session.capturedInteractions.length >= MAX_CAPTURED_INTERACTIONS) {
+            session.droppedInteractionCount++;
+            return uploadCapture(session);
+        }
+        const path = event
+            .composedPath()
+            .filter((item) => item instanceof Element);
+        const target = path.find((element) => element.matches(ACTIONABLE_SELECTOR)) ?? path[0];
+        const selector = target ? selectorFor(target) : null;
+        const label = target
+            ? (target.getAttribute("aria-label") ||
+                target.textContent ||
+                target.tagName)
+                .replace(/\s+/g, " ")
+                .trim()
+                .slice(0, 500)
+            : null;
+        const textTarget = target instanceof HTMLInputElement ||
+            target instanceof HTMLTextAreaElement ||
+            target instanceof HTMLSelectElement;
+        const editable = target instanceof HTMLElement && target.isContentEditable;
+        const keyboard = event instanceof KeyboardEvent
+            ? {
+                key: event.key,
+                code: event.code,
+                altKey: event.altKey,
+                ctrlKey: event.ctrlKey,
+                metaKey: event.metaKey,
+                shiftKey: event.shiftKey,
+                repeat: event.repeat,
+                isComposing: event.isComposing,
+            }
+            : {};
+        session.capturedInteractions.push({
+            id: crypto.randomUUID(),
+            captured_at: performance.timeOrigin + performance.now(),
+            source_timestamp: Math.round(performance.now()),
+            kind: event.type,
+            selector,
+            label: label || null,
+            tag_name: target?.tagName.toLowerCase(),
+            ...keyboard,
+            ...(["input", "change"].includes(event.type) && (textTarget || editable)
+                ? { value: textTarget ? target.value : (target.textContent ?? "") }
+                : {}),
+            ...(event instanceof ClipboardEvent && event.type === "paste"
+                ? { text: event.clipboardData?.getData("text/plain") ?? "" }
+                : {}),
+            ...(event instanceof InputEvent
+                ? { inputType: event.inputType, isComposing: event.isComposing }
+                : {}),
+        });
+        uploadCapture(session);
+    }
+    for (const eventName of CAPTURED_SESSION_INTERACTION_EVENTS) {
+        window.addEventListener(eventName, recordInteraction, { capture: true });
+    }
+    async function replayForFullStory(exchange) {
+        syntheticExchange = exchange;
+        try {
+            // FullStory observes this synthetic response without issuing a second backend request.
+            await window.fetch(exchange.url, {
+                method: exchange.method,
+                headers: { "x-fs-recapture": "1" },
+            });
+        }
+        finally {
+            syntheticExchange = null;
+        }
+    }
+    window.fetch = async (input, init) => {
+        if (stopped)
+            return nativeFetch(input, init);
+        const request = new Request(input instanceof Request
+            ? input
+            : new URL(String(input), window.location.href), init);
+        if (request.url === endpoint.href)
+            return nativeFetch(request);
+        const synthetic = syntheticExchange;
+        if (synthetic &&
+            request.headers.get("x-fs-recapture") === "1" &&
+            request.method === synthetic.method &&
+            request.url === synthetic.url) {
+            return new Response(synthetic.startup_body?.byteLength
+                ? synthetic.startup_body.slice(0)
+                : null, {
+                status: synthetic.status,
+                statusText: synthetic.status_text,
+                headers: synthetic.response_headers,
+            });
+        }
+        const session = captureSession();
+        if (!session)
+            return nativeFetch(request);
+        const startedBeforeReady = !fullStoryReady;
+        const sourceTimestamp = Math.round(performance.now());
+        const capturedAt = performance.timeOrigin + sourceTimestamp;
+        const exchangeId = crypto.randomUUID();
+        const requestBody = request.method !== "GET" && request.method !== "HEAD"
+            ? boundedBody(request).catch(() => null)
+            : Promise.resolve(null);
+        const responsePromise = nativeFetch(request);
+        inFlight.add(responsePromise);
+        let response;
+        try {
+            response = await responsePromise;
+        }
+        finally {
+            inFlight.delete(responsePromise);
+        }
+        const capture = (async () => {
+            const clone = response.clone();
+            const responseBytes = await clone.arrayBuffer().catch(() => null);
+            const capturedRequestBody = await requestBody;
+            const exchangeBytes = (responseBytes?.byteLength ?? 0) +
+                new TextEncoder().encode(capturedRequestBody ?? "").byteLength;
+            if (session.capturedBytes + exchangeBytes > MAX_CAPTURE_BYTES ||
+                session.capturedExchanges.length >= 5_000) {
+                session.droppedNetworkCount++;
+                uploadCapture(session);
+                return;
+            }
+            const exchange = {
+                id: exchangeId,
+                captured_at: capturedAt,
+                source_timestamp: sourceTimestamp,
+                method: request.method,
+                url: request.url,
+                status: clone.status,
+                request_headers: Object.fromEntries(request.headers.entries()),
+                request_body: capturedRequestBody,
+                response_headers: Object.fromEntries(clone.headers.entries()),
+                response_body: responseBytes && responseBytes.byteLength <= MAX_BODY_BYTES
+                    ? new TextDecoder().decode(responseBytes)
+                    : null,
+                ...(startedBeforeReady &&
+                    (request.method === "GET" || request.method === "HEAD") &&
+                    responseBytes &&
+                    responseBytes.byteLength <= MAX_BODY_BYTES
+                    ? { startup_body: responseBytes, status_text: clone.statusText }
+                    : {}),
+            };
+            session.capturedBytes += exchangeBytes;
+            session.capturedExchanges.push(exchange);
+            uploadCapture(session);
+            if (!stopped && fullStoryReady && exchange.startup_body) {
+                await replayForFullStory(exchange);
+                delete exchange.startup_body;
+                delete exchange.status_text;
+            }
+        })().catch(reportError);
+        inFlight.add(capture);
+        void capture.finally(() => inFlight.delete(capture));
+        return response;
+    };
+    const controller = {
+        identify: (user) => {
+            if (!stopped)
+                identifyFullStoryUser(user);
+        },
+        async flush() {
+            while (inFlight.size)
+                await Promise.allSettled([...inFlight]);
+            for (const session of sessions) {
+                if (session.uploadTimer)
+                    clearTimeout(session.uploadTimer);
+                session.uploadTimer = null;
+                await queueCaptureUpload(session);
+            }
+            if (lastError)
+                throw lastError;
+            if (!currentSession.sessionUrl)
+                throw new Error("FullStory session is not ready");
+        },
+        async stop() {
+            stopped = true;
+            for (const eventName of CAPTURED_SESSION_INTERACTION_EVENTS) {
+                window.removeEventListener(eventName, recordInteraction, {
+                    capture: true,
+                });
+            }
+            await controller.flush();
+        },
+    };
+    active = controller;
+    activeOptions = { ...options };
+    init({ orgId }, async ({ sessionUrl }) => {
+        if (stopped && currentSession.sessionUrl !== null)
+            return;
+        const session = synchronizeSession(sessionUrl);
+        const firstStart = !fullStoryReady;
+        fullStoryReady = true;
+        if (firstStart) {
+            for (const exchange of session.capturedExchanges.filter((item) => !stopped && item.startup_body)) {
+                await replayForFullStory(exchange);
+                delete exchange.startup_body;
+                delete exchange.status_text;
+            }
+        }
+        if (session.uploadTimer)
+            clearTimeout(session.uploadTimer);
+        session.uploadTimer = null;
+        await queueCaptureUpload(session);
+    });
+    // init() above registers the SDK synchronously and queues any API calls made before the session is
+    // ready, so identify is safe from here on. Setting the flag outside the ready callback keeps an
+    // identify that lands between init() and session-ready working rather than crashing.
+    fullStoryInitialized = true;
+    return controller;
+}

package/dist/transport.d.ts

@@ -0,0 +1,14 @@
+/** QA's versioned auxiliary artifact envelope. Consumers need no package dependency. */
+export interface Artifact {
+    namespace: string;
+    key: string;
+    schema_version: number;
+    payload: Record<string, unknown>;
+}
+export interface CaptureBatch {
+    session_url: string;
+    auxiliary_data: Artifact[];
+}
+export declare const MAX_BATCH_BYTES: number;
+/** Split between whole events, preserving IDs and payloads for identical retries. */
+export declare function splitBatches(input: CaptureBatch, maxBytes?: number): string[];

package/dist/transport.js

@@ -0,0 +1,65 @@
+export const MAX_BATCH_BYTES = 256 * 1024;
+/** Split between whole events, preserving IDs and payloads for identical retries. */
+export function splitBatches(input, maxBytes = MAX_BATCH_BYTES) {
+    const encode = (artifacts) => JSON.stringify({
+        session_url: input.session_url,
+        auxiliary_data: artifacts,
+    });
+    const fits = (artifacts) => new TextEncoder().encode(encode(artifacts)).byteLength <= maxBytes;
+    const result = [];
+    let pending = [];
+    for (const artifact of input.auxiliary_data) {
+        const field = artifact.namespace === "network" && artifact.key === "captured-exchanges"
+            ? "exchanges"
+            : artifact.namespace === "interaction" &&
+                artifact.key === "captured-interactions"
+                ? "interactions"
+                : artifact.namespace === "session" &&
+                    artifact.key === "capture-context"
+                    ? "pages"
+                    : undefined;
+        const entries = field ? artifact.payload[field] : undefined;
+        if (field && Array.isArray(entries) && entries.length > 0) {
+            let chunk = [];
+            const withEntries = (values) => ({
+                ...artifact,
+                payload: { ...artifact.payload, [field]: values },
+            });
+            for (const entry of entries) {
+                const candidate = [...chunk, entry];
+                if (fits([...pending, withEntries(candidate)])) {
+                    chunk = candidate;
+                    continue;
+                }
+                if (chunk.length)
+                    pending.push(withEntries(chunk));
+                if (pending.length) {
+                    result.push(encode(pending));
+                    pending = [];
+                }
+                if (!fits([withEntries([entry])]))
+                    throw new Error(`A ${artifact.namespace}/${artifact.key} event exceeds the ${maxBytes}-byte upload limit`);
+                chunk = [entry];
+            }
+            if (chunk.length)
+                pending.push(withEntries(chunk));
+        }
+        else {
+            if (!fits([artifact]))
+                throw new Error(`Artifact ${artifact.namespace}/${artifact.key} exceeds the upload limit`);
+            if (!fits([...pending, artifact])) {
+                result.push(encode(pending));
+                pending = [];
+            }
+            pending.push(artifact);
+        }
+        // QA accepts at most ten artifacts per registration.
+        if (pending.length >= 10) {
+            result.push(encode(pending));
+            pending = [];
+        }
+    }
+    if (pending.length)
+        result.push(encode(pending));
+    return result;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@replayio/self-healing-capture",
+  "version": "0.1.0",
+  "description": "FullStory auxiliary capture for Self Healing and compatible session ingesters",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/replayio/self-healing.git",
+    "directory": "packages/capture"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@fullstory/browser": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build"
+  }
+}