@replayio/self-healing-capture 0.1.1 → 0.1.3

package/README.md

@@ -3,6 +3,15 @@
 Temporary browser capture support for Self Healing while Subtext gains the accessors needed for
 network exchanges, interactions, identity, metrics, and session context.
 
+## Updating an existing installation
+
+**Agents: read [UPGRADING.md](./UPGRADING.md) before updating this dependency.**
+It ships in the npm package at
+`node_modules/@replayio/self-healing-capture/UPGRADING.md` and covers changes to
+application-owned initialization and forwarding code, not just the lockfile.
+No original installer conversation is needed. In particular, old installations
+may contain a 256 KiB forwarding check that a dependency update cannot remove.
+
 **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,
@@ -15,8 +24,9 @@ the Self Healing skills will describe the replacement and migration.
 ## Development and release
 
 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.
+independent ingestion schemas and compatibility tests compatible. Initial installation instructions live in the Self Healing skills. Every release
+that changes application integration requirements must add a versioned migration
+to UPGRADING.md and include verification steps.
 
 Publish locally with interactive npm authentication and 2FA:
 
@@ -32,9 +42,10 @@ artifact. npm owns the browser login/security-key/2FA prompts. Credentials and O
 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.
+Registry errors fail the version check; already-published versions are skipped. After npm accepts publication,
+the script briefly checks registry visibility. Delayed processing or registry read failures report
+visibility as pending without treating the accepted publication as a failure. Use the printed
+`npm view` command to check later; do not republish. Existing versions are 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
@@ -50,3 +61,5 @@ An upload failure is reported through `onError` and retained for retry on the ne
 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.
+
+Release tests and builds print concise progress; their full output is shown only if they fail.

package/UPGRADING.md

@@ -0,0 +1,72 @@
+# Upgrading an existing Self Healing integration
+
+This guide ships with `@replayio/self-healing-capture`. Coding agents should read it
+when asked to update the package and reconcile the application integration as well
+as its dependency. The original installation conversation is not required.
+
+## Upgrade procedure
+
+1. Read the installed package version and the version being installed. Use the
+   application's package manager to update the dependency and lockfile together.
+   Apply every migration below between those versions. If the old version is
+   unknown, inspect the integration against all migrations.
+2. Locate the existing `initCapture` call, identity hook, configured same-origin
+   capture endpoint, and server forwarding handler. Search for
+   `@replayio/self-healing-capture`, `initCapture`, `SELF_HEALING_URL`, and
+   `/api/v1/connection/sessions`. Follow the actual configured endpoint rather than
+   assuming the example route name.
+3. Update application-owned installation code as described below. Keep the existing
+   account, project connection, credentials, identity integration, and application
+   access controls. Do not repeat provisioning or rotate credentials for an upgrade.
+4. Run the application's relevant checks. Verify through its actual forwarding
+   route that captured network and interaction artifacts reach Self Healing.
+   Once deployed, exercise a real browser session and confirm HTTP 200 with
+   `status: "stored"` and a nonempty `session_id`. An initial metadata-only upload
+   or a FullStory recording alone does not verify auxiliary capture.
+5. Report the dependency version, application-code changes, checks, and session
+   delivery evidence. Distinguish local verification from deployed verification.
+   Follow the application's normal review/deployment process; do not claim the
+   deployed integration is updated until it has been verified.
+
+For the current complete setup contract, see
+https://self-healing.replay.io/api/v1/skills/setup-self-healing/SKILL.md.
+Use it to reconcile the existing integration; do not treat an upgrade as a new setup.
+
+## 0.1.3 — Packaged upgrade instructions
+
+No runtime integration changes beyond the migrations below. This release includes
+this guide so upgrades can be performed without access to the installer conversation.
+
+## 0.1.2 — One configurable limit per network exchange
+
+- The embedder option is `maxNetworkCaptureBytes`, defaulting to 1,000,000 bytes.
+  It measures the UTF-8 JSON encoding of each exchange, including both bodies,
+  headers, and event metadata. Omit the option to use the default; preserve an
+  intentional application-specific setting. If installation code uses the
+  pre-release `maxBatchBytes` option, replace it with this per-exchange policy.
+- Oversized exchanges are skipped and counted in `dropped_network_count`; later
+  captures continue. Batching is internal and includes space for envelope overhead.
+  A full-size exchange therefore produces an upload slightly larger than its limit.
+- Earlier setup examples installed a **256 KiB request-size check in the app's
+  forwarding handler**. Inspect for `256 * 1024`, `262144`, `413`, or the message
+  `Capture exceeds Self Healing request limit` along the capture route. Remove that
+  capture-specific check if present. Do not replace it with a 1 MB upload check.
+  Inspect capture-route body-parser configuration for the same obsolete restriction;
+  do not change unrelated application routes.
+- Forward the original JSON body to `/api/v1/connection/sessions` using server-held
+  Self Healing credentials and return the upstream status/body. Do not truncate
+  capture fields, reimplement batching, or expose credentials in the browser.
+- Verify an exchange with a body larger than 256 KiB but below the configured
+  exchange limit (for example, 500 KB under the default) is actually delivered
+  through the forwarding route with its body intact. Also verify a later small
+  exchange after an oversized exchange, and check the dropped counter increases.
+
+Updating the npm dependency cannot modify an application's existing forwarding
+handler. These application-code migrations are part of the package upgrade.
+
+## 0.1.1 — Capture decoding and retry fixes
+
+No application-code migration is required. Keep capture initialization and the
+existing identity hook. Failed uploads remain retryable; later batches continue.
+Binary, invalid UTF-8, and NUL-containing bodies are represented as unavailable
+while their exchange metadata remains captured.

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export interface CaptureOptions {
     orgId: string;
     /** Same-origin POST route holding the server-side credential. */
     endpoint?: string;
+    /** Maximum UTF-8 JSON bytes per network exchange (bodies, headers and metadata). Defaults to 1,000,000. */
+    maxNetworkCaptureBytes?: number;
     onError?: (error: Error) => void;
 }
 export interface CaptureController {

package/dist/index.js

@@ -1,5 +1,5 @@
 import { FullStory, init } from "@fullstory/browser";
-import { decodeCaptureBody, splitBatches } from "./transport.js";
+import { decodeCaptureBody, splitBatches, DEFAULT_MAX_NETWORK_CAPTURE_BYTES, } from "./transport.js";
 let active;
 let activeOptions;
 const CAPTURED_SESSION_INTERACTION_EVENTS = [
@@ -17,7 +17,6 @@ function countsAsSessionInteraction(event) {
             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"]';
@@ -40,9 +39,16 @@ function identifyFullStoryUser(user) {
 export function initCapture(options) {
     if (typeof window === "undefined")
         throw new Error("initCapture must run in the browser");
+    const maxNetworkCaptureBytes = options.maxNetworkCaptureBytes ?? DEFAULT_MAX_NETWORK_CAPTURE_BYTES;
+    if (!Number.isSafeInteger(maxNetworkCaptureBytes) ||
+        maxNetworkCaptureBytes <= 0)
+        throw new Error("maxNetworkCaptureBytes must be a positive safe integer");
     if (active) {
         if (options.orgId !== activeOptions?.orgId ||
-            options.endpoint !== activeOptions?.endpoint) {
+            options.endpoint !== activeOptions?.endpoint ||
+            maxNetworkCaptureBytes !==
+                (activeOptions?.maxNetworkCaptureBytes ??
+                    DEFAULT_MAX_NETWORK_CAPTURE_BYTES)) {
             throw new Error("Capture is already initialized with different options");
         }
         return active;
@@ -138,10 +144,8 @@ export function initCapture(options) {
         session.userEmail = email;
         uploadCapture(session);
     };
-    async function boundedBody(value) {
+    async function captureBody(value) {
         const bytes = await value.clone().arrayBuffer();
-        if (bytes.byteLength > MAX_BODY_BYTES)
-            return null;
         return decodeCaptureBody(bytes);
     }
     async function sendCaptureBatch(body) {
@@ -192,7 +196,7 @@ export function initCapture(options) {
                 namespace: "session",
                 key: "capture-producer",
                 schema_version: 1,
-                payload: { name: "@replayio/self-healing-capture", version: "0.1.1" },
+                payload: { name: "@replayio/self-healing-capture", version: "0.1.3" },
             },
             ...(context !== session.queuedContext || session.pendingBatches.length > 0
                 ? [
@@ -273,7 +277,7 @@ export function initCapture(options) {
             batches = splitBatches({
                 session_url: session.sessionUrl,
                 auxiliary_data: auxiliaryData,
-            });
+            }, maxNetworkCaptureBytes);
         }
         catch (error) {
             reportError(error);
@@ -448,7 +452,7 @@ export function initCapture(options) {
         const capturedAt = performance.timeOrigin + sourceTimestamp;
         const exchangeId = crypto.randomUUID();
         const requestBody = request.method !== "GET" && request.method !== "HEAD"
-            ? boundedBody(request).catch(() => null)
+            ? captureBody(request).catch(() => null)
             : Promise.resolve(null);
         const responsePromise = nativeFetch(request);
         inFlight.add(responsePromise);
@@ -481,16 +485,20 @@ export function initCapture(options) {
                 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
-                    ? decodeCaptureBody(responseBytes)
-                    : null,
+                response_body: responseBytes ? decodeCaptureBody(responseBytes) : null,
                 ...(startedBeforeReady &&
                     (request.method === "GET" || request.method === "HEAD") &&
-                    responseBytes &&
-                    responseBytes.byteLength <= MAX_BODY_BYTES
+                    responseBytes
                     ? { startup_body: responseBytes, status_text: clone.statusText }
                     : {}),
             };
+            const { startup_body: _startup, status_text: _status, ...uploadedExchange } = exchange;
+            if (new TextEncoder().encode(JSON.stringify(uploadedExchange)).byteLength >
+                maxNetworkCaptureBytes) {
+                session.droppedNetworkCount++;
+                uploadCapture(session);
+                return;
+            }
             session.capturedBytes += exchangeBytes;
             session.capturedExchanges.push(exchange);
             uploadCapture(session);

package/dist/transport.d.ts

@@ -9,8 +9,10 @@ export interface CaptureBatch {
     session_url: string;
     auxiliary_data: Artifact[];
 }
-export declare const MAX_BATCH_BYTES: number;
+export declare const DEFAULT_MAX_NETWORK_CAPTURE_BYTES = 1000000;
+/** Derive the upload budget from the capture limit, allowing one full exchange plus its envelope. */
+export declare function uploadBatchBytes(sessionUrl: string, maxNetworkCaptureBytes?: number): number;
 /** Split between whole events, preserving IDs and payloads for identical retries. */
-export declare function splitBatches(input: CaptureBatch, maxBytes?: number): string[];
+export declare function splitBatches(input: CaptureBatch, maxNetworkCaptureBytes?: 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

@@ -1,6 +1,22 @@
-export const MAX_BATCH_BYTES = 256 * 1024;
+export const DEFAULT_MAX_NETWORK_CAPTURE_BYTES = 1_000_000;
+/** Derive the upload budget from the capture limit, allowing one full exchange plus its envelope. */
+export function uploadBatchBytes(sessionUrl, maxNetworkCaptureBytes = DEFAULT_MAX_NETWORK_CAPTURE_BYTES) {
+    return (maxNetworkCaptureBytes +
+        new TextEncoder().encode(JSON.stringify({
+            session_url: sessionUrl,
+            auxiliary_data: [
+                {
+                    namespace: "network",
+                    key: "captured-exchanges",
+                    schema_version: 1,
+                    payload: { version: 1, exchanges: [] },
+                },
+            ],
+        })).byteLength);
+}
 /** Split between whole events, preserving IDs and payloads for identical retries. */
-export function splitBatches(input, maxBytes = MAX_BATCH_BYTES) {
+export function splitBatches(input, maxNetworkCaptureBytes = DEFAULT_MAX_NETWORK_CAPTURE_BYTES) {
+    const maxBytes = uploadBatchBytes(input.session_url, maxNetworkCaptureBytes);
     const encode = (artifacts) => JSON.stringify({
         session_url: input.session_url,
         auxiliary_data: artifacts,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@replayio/self-healing-capture",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "FullStory auxiliary capture for Self Healing and compatible session ingesters",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,7 +13,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "UPGRADING.md"
   ],
   "sideEffects": false,
   "license": "UNLICENSED",