@replayio/self-healing-capture 0.1.0 → 0.1.1

package/README.md

@@ -1,73 +1,22 @@
 # @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.
+Temporary browser capture support for Self Healing while Subtext gains the accessors needed for
+network exchanges, interactions, identity, metrics, and session context.
 
-```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.
+**Installation and integration instructions live in the
+[Self Healing setup skill](https://self-healing.replay.io/api/v1/skills/setup-self-healing/SKILL.md).**
+Follow that skill for account provisioning, browser initialization, server forwarding, automatic reviews,
+and verification. This package is an implementation detail of that setup, not a separate installer.
 
-## 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.
+QA consumes compatible versioned artifacts and recognizes the package/version provenance. Its
+ingestion and review code does not import this package. When Subtext supplies the required accessors,
+the Self Healing skills will describe the replacement and migration.
 
 ## 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.
+The capture implementation lives in `packages/capture/src`. Change producers here and keep QA’s
+independent ingestion schemas and compatibility tests compatible. Installation instructions belong
+only in the Self Healing skills.
 
 Publish locally with interactive npm authentication and 2FA:
 
@@ -90,3 +39,14 @@ existing version is skipped, never overwritten. Temporary tarballs are removed w
 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.
+
+## Capture failure behavior
+
+Version 0.1.1 preserves valid UTF-8 body text exactly. Binary, invalid UTF-8, or NUL-containing
+bodies are recorded as unavailable (`null`), retaining the exchange metadata. Both request and response
+bodies follow this rule, including compressed requests advertised as `text/plain`.
+
+An upload failure is reported through `onError` and retained for retry on the next capture upload or
+explicit `flush()`. Later batches are still attempted. Retries preserve event IDs for server deduplication;
+current session context and metrics are sent after retries so an older batch cannot leave stale counters.
+`flush()` rejects while any batch remains undelivered, and succeeds once they have all been accepted.

package/dist/index.js

@@ -1,5 +1,5 @@
 import { FullStory, init } from "@fullstory/browser";
-import { splitBatches } from "./transport.js";
+import { decodeCaptureBody, splitBatches } from "./transport.js";
 let active;
 let activeOptions;
 const CAPTURED_SESSION_INTERACTION_EVENTS = [
@@ -37,9 +37,6 @@ function identifyFullStoryUser(user) {
     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");
@@ -88,7 +85,8 @@ export function initCapture(options) {
             queuedExchangeCount: 0,
             queuedInteractionCount: -1,
             queuedCapturedInteractionCount: 0,
-            uploadsStopped: false,
+            pendingBatches: [],
+            uploadError: undefined,
             userEmail,
             queuedUserEmail: null,
             uploadTimer: null,
@@ -144,7 +142,7 @@ export function initCapture(options) {
         const bytes = await value.clone().arrayBuffer();
         if (bytes.byteLength > MAX_BODY_BYTES)
             return null;
-        return new TextDecoder().decode(bytes);
+        return decodeCaptureBody(bytes);
     }
     async function sendCaptureBatch(body) {
         for (let attempt = 0;; attempt++) {
@@ -172,8 +170,12 @@ export function initCapture(options) {
         }
     }
     function queueCaptureUpload(session) {
-        if (!session.sessionUrl || session.uploadsStopped)
+        if (!session.sessionUrl)
             return Promise.resolve();
+        session.uploadChain = session.uploadChain.then(() => drainCaptureUpload(session));
+        return session.uploadChain;
+    }
+    async function drainCaptureUpload(session) {
         const exchanges = session.capturedExchanges
             .slice(session.queuedExchangeCount)
             .map(({ startup_body: _body, status_text: _status, ...exchange }) => exchange)
@@ -190,9 +192,9 @@ export function initCapture(options) {
                 namespace: "session",
                 key: "capture-producer",
                 schema_version: 1,
-                payload: { name: "@replayio/self-healing-capture", version: "0.1.0" },
+                payload: { name: "@replayio/self-healing-capture", version: "0.1.1" },
             },
-            ...(context !== session.queuedContext
+            ...(context !== session.queuedContext || session.pendingBatches.length > 0
                 ? [
                     {
                         namespace: "session",
@@ -237,7 +239,8 @@ export function initCapture(options) {
                     },
                 ]
                 : []),
-            ...(session.interactionCount !== session.queuedInteractionCount
+            ...(session.interactionCount !== session.queuedInteractionCount ||
+                session.pendingBatches.length > 0
                 ? [
                     {
                         namespace: "session",
@@ -250,7 +253,9 @@ export function initCapture(options) {
                     },
                 ]
                 : []),
-            ...(session.userEmail && session.userEmail !== session.queuedUserEmail
+            ...(session.userEmail &&
+                (session.userEmail !== session.queuedUserEmail ||
+                    session.pendingBatches.length > 0)
                 ? [
                     {
                         namespace: "session",
@@ -261,39 +266,51 @@ export function initCapture(options) {
                 ]
                 : []),
         ];
-        if (auxiliaryData.length === 1)
-            return session.uploadChain;
+        if (auxiliaryData.length === 1 && !session.pendingBatches.length)
+            return;
+        let batches;
+        try {
+            batches = splitBatches({
+                session_url: session.sessionUrl,
+                auxiliary_data: auxiliaryData,
+            });
+        }
+        catch (error) {
+            reportError(error);
+            return;
+        }
         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)) {
+        session.pendingBatches.push(...batches);
+        const failed = [];
+        session.uploadError = undefined;
+        // Retry identical event IDs, but a rejected batch must not block later interactions.
+        for (const batch of session.pendingBatches) {
+            try {
                 const response = await sendCaptureBatch(batch);
-                if (shouldStopSessionUploads(response.status)) {
-                    session.uploadsStopped = true;
+                if (!response.ok)
                     throw new Error(`Capture upload failed: ${response.status}`);
+            }
+            catch (error) {
+                failed.push(batch);
+                session.uploadError =
+                    error instanceof Error ? error : new Error(String(error));
+                try {
+                    (options.onError ?? console.error)(session.uploadError);
+                }
+                catch {
+                    /* observers cannot break the app */
                 }
             }
-        })
-            .catch((error) => {
-            session.uploadsStopped = true;
-            reportError(error);
-        });
-        return session.uploadChain;
+        }
+        session.pendingBatches = failed;
     }
     function uploadCapture(session) {
-        if (!session.sessionUrl || session.uploadsStopped)
+        if (!session.sessionUrl)
             return;
         if (session.uploadTimer)
             return;
@@ -465,7 +482,7 @@ export function initCapture(options) {
                 request_body: capturedRequestBody,
                 response_headers: Object.fromEntries(clone.headers.entries()),
                 response_body: responseBytes && responseBytes.byteLength <= MAX_BODY_BYTES
-                    ? new TextDecoder().decode(responseBytes)
+                    ? decodeCaptureBody(responseBytes)
                     : null,
                 ...(startedBeforeReady &&
                     (request.method === "GET" || request.method === "HEAD") &&
@@ -503,6 +520,10 @@ export function initCapture(options) {
             }
             if (lastError)
                 throw lastError;
+            for (const session of sessions) {
+                if (session.uploadError)
+                    throw session.uploadError;
+            }
             if (!currentSession.sessionUrl)
                 throw new Error("FullStory session is not ready");
         },

package/dist/transport.d.ts

@@ -12,3 +12,5 @@ export interface CaptureBatch {
 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[];
+/** Binary or NUL-containing bodies cannot be represented in the text-only capture schema. */
+export declare function decodeCaptureBody(bytes: ArrayBuffer): string | null;

package/dist/transport.js

@@ -63,3 +63,13 @@ export function splitBatches(input, maxBytes = MAX_BATCH_BYTES) {
         result.push(encode(pending));
     return result;
 }
+/** Binary or NUL-containing bodies cannot be represented in the text-only capture schema. */
+export function decodeCaptureBody(bytes) {
+    try {
+        const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        return text.includes("\0") ? null : text;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@replayio/self-healing-capture",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "FullStory auxiliary capture for Self Healing and compatible session ingesters",
   "type": "module",
   "main": "./dist/index.js",