@newtalaria/browser 0.1.0 → 0.1.4

package/README.md

@@ -29,8 +29,11 @@ Talaria.init({
   release: '1.0.0',
   // Continuous session upload (0–1). Default 0 = buffer only until an error.
   replaysSessionSampleRate: 0,
-  // On error, flush buffer + attach replayId (0–1). Default 1.
+  // On error, promote the ~60s ring buffer (0–1). Default 1.
   replaysOnErrorSampleRate: 1,
+  // Post-error upload window. Default 15000 (cheap clip). Use 0 to continue
+  // until the 5-minute max duration (Sentry-like, more expensive).
+  replaysErrorAfterMs: 15_000,
   maskAllInputs: true, // default
 });
 
@@ -49,6 +52,32 @@ await Talaria.close();
 
 `Talaria.init` also installs `window.onerror` / `unhandledrejection` handlers unless you pass `disableDefaultIntegrations: true`.
 
+## Recommended sampling (cost)
+
+You pay for **uploaded + retained** bytes, not for local buffering. Prefer error clips in production; keep full-session sampling low.
+
+| Traffic | `replaysSessionSampleRate` | `replaysOnErrorSampleRate` | `replaysErrorAfterMs` |
+| --- | --- | --- | --- |
+| High (100k+/day) | `0.01` | `1.0` | `15000` (default clip) |
+| Medium (10k–100k/day) | `0.1` | `1.0` | `15000` |
+| Low (under 10k/day) | `0.25` | `1.0` | `15000` |
+| Marketing / docs site | `0` | `1.0` | `15000` |
+| Rich post-error context | `0` | `1.0` | `0` (continue to 5 min cap) |
+
+**Defaults (`session=0`, `onError=1`, `errorAfterMs=15000`)** are the cheapest useful profile: quiet traffic costs nothing; each sampled error keeps ~60s before + ~15s after.
+
+## Replay sampling behavior
+
+| Mode | Behavior |
+| --- | --- |
+| Session sample hit | `replays/start` immediately; segments upload every ~5s or ~100KB until unload or **5 min** max |
+| Session sample miss | Record into a ~60s ring buffer; nothing uploaded until an error sample hits |
+| Error sample + `replaysErrorAfterMs > 0` | Upload buffer (≤480KiB gzip pack target / 512KiB server cap) + trailing window, hard caps **12 segments** or **2MiB** compressed, attach `replayId` only if segments landed, `finish`, return to buffer mode |
+| Error sample + `replaysErrorAfterMs = 0` | Upload buffer then continue like session mode until **5 min** / unload / size caps |
+| Server limit (replay segments / total size / duration) | Stop uploading that replay; no retries |
+| Oversized single rrweb event | Dropped with a console warning (cannot fit under segment cap) |
+| `pagehide` / `close` | Flush pending segments with `fetch` `keepalive`, then `replays/finish`; `close` fully resets so `init()` works again (React Strict Mode) |
+
 ## Serverpod URL pattern
 
 Talaria uses **Serverpod RPC**, not REST resource URLs:
@@ -91,15 +120,6 @@ decode('<base64>', 'base64')
 
 Segment payloads are a **gzip-compressed JSON array** of rrweb events.
 
-## Replay sampling
-
-| Mode | Behavior |
-| --- | --- |
-| Session sample hit | `replays/start` immediately; segments upload every ~5s or ~100KB |
-| Session sample miss | Record into a ~60s ring buffer; nothing uploaded until an error sample hits |
-| Error sample hit | Enable upload, flush buffer, send event with `replayId` |
-| `pagehide` / `close` | Flush pending segments with `fetch` `keepalive`, then `replays/finish` |
-
 Custom rrweb events:
 
 - `talaria-console` — console level + args (truncated)
@@ -121,3 +141,31 @@ Privacy defaults: `maskAllInputs: true`, password fields masked, `[data-talaria-
 ## Example
 
 See [`../../examples/sdk-spa`](../../examples/sdk-spa) for a minimal page wired to `localhost:8080`.
+
+## Local `file:` install (marketing / monorepo)
+
+`dist/` is gitignored. After editing SDK `src/`, rebuild before the consumer picks up changes:
+
+```bash
+cd new_talaria_js/packages/browser
+npm run build
+# or: npm install in the consumer — `prepare` runs build for file: installs
+```
+
+Then restart the Next app with a clean cache:
+
+```bash
+cd ../new_talaria_marketing   # sibling repo
+rm -rf .next
+npm run dev
+```
+
+**Serverpod must be restarted** after changing `ReplayLimits` (compressed cap is 512KiB). A live process still on 256KiB will 400 every near-max segment.
+
+### Verify error-clip ingest
+
+1. Restart Serverpod (512KiB live).
+2. Rebuild the browser package; restart marketing with clean `.next`.
+3. Browse `/docs/**` ~30s, throw one test exception.
+4. Expect: a few `ingestSegment` 200s, one `finish`, **zero** compressed-size 400 spam, dashboard replay plays.
+5. Throw again later: a new bounded clip is allowed (buffer mode reset).

package/dist/client.d.ts

@@ -1,4 +1,6 @@
 import type { CaptureContext, SeverityLevel, TalariaInitOptions } from './types.js';
+export { computeErrorClipDeadlineMs, fitCompressedPrefix, isErrorClipBudgetExhausted, planOversizedRetry, } from './replay/fit_segment.js';
+export { MAX_SEGMENTS_ERROR_CLIP, MAX_ERROR_CLIP_COMPRESSED_BYTES, TARGET_COMPRESSED_SEGMENT_BYTES, MAX_COMPRESSED_SEGMENT_BYTES, } from './replay/segment_buffer.js';
 export declare class TalariaClient {
     private options;
     private transport;
@@ -6,14 +8,28 @@ export declare class TalariaClient {
     private sessionId;
     private recorder;
     private buffer;
+    /** Continuous upload for the whole page session (session sample hit). */
+    private sessionSampled;
     private uploadEnabled;
     private startedOnServer;
     private finishedOnServer;
     private segmentIndex;
+    private uploadedCompressedBytes;
+    /** Wall clock when continuous upload began (session or error promote). */
+    private uploadStartedAtMs;
+    /** Absolute deadline for error-clip mode (not extended by later errors). */
+    private errorClipDeadlineMs;
     private flushTimer;
+    private errorClipTimer;
+    private maxDurationTimer;
     private uploadChain;
     private closed;
     private teardowns;
+    /**
+     * Replay id that just finished with segments — kept briefly so capture can
+     * attach it to the error event after budget/timer finish resets buffer mode.
+     */
+    private linkableReplayId;
     init(options: TalariaInitOptions): void;
     getReplayId(): string | null;
     captureException(error: unknown, context?: CaptureContext): Promise<void>;
@@ -23,13 +39,49 @@ export declare class TalariaClient {
         keepalive?: boolean;
         finish?: boolean;
     }): Promise<void>;
+    /**
+     * Stop recording, flush while still open, then fully reset so `init()` can
+     * run again (React Strict Mode remount).
+     */
     close(): Promise<void>;
     private onRrwebEvent;
     private capture;
+    private markUploadStarted;
+    private isPastMaxDuration;
+    private isPastErrorClipDeadline;
+    private isErrorClipMode;
+    private scheduleMaxDurationStop;
+    private clearMaxDurationTimer;
+    private runStopForMaxDuration;
+    /**
+     * Schedule end of the cheap error clip against a fixed absolute deadline.
+     * Subsequent errors re-arm the timer but never push the wall later.
+     */
+    private scheduleErrorClipEnd;
+    private clearErrorClipTimer;
+    /** Flush trailing post-error window, finish replay, return to ring buffer. */
+    private endErrorClip;
+    private runEndErrorClip;
+    /** After an error clip (or terminal limit), buffer locally until the next error. */
+    private resetToBufferMode;
+    /** Emit a checkout FullSnapshot into the ring buffer (sync via rrweb emit). */
+    private checkoutFullSnapshot;
+    /**
+     * Ensure segment 0 begins at Meta+FullSnapshot. Orphan increments alone
+     * produce a blank rrweb player.
+     */
+    private prepareBufferForNewReplay;
+    private stopUploadingAfterLimit;
     private installGlobalHandlers;
     private enqueueUpload;
     private ensureStarted;
     private uploadPendingSegments;
+    private maxSegmentsAllowed;
+    /**
+     * Pull the largest event prefix that gzips under the target compressed size.
+     * Drops a single event that can never fit.
+     */
+    private takeFittedSegment;
     private finishOnServer;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EAEd,aAAa,EACb,kBAAkB,EACnB,MAAM,YAAY,CAAC;AA6DpB,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAkB;IAEnC,IAAI,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IA0DvC,WAAW,IAAI,MAAM,GAAG,IAAI;IAItB,gBAAgB,CACpB,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC;IAcV,cAAc,CAClB,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,aAAsB,EAC7B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC;IASV,KAAK,CAAC,IAAI,CAAC,EAAE;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBX,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAyB5B,OAAO,CAAC,YAAY;YAcN,OAAO;IA4DrB,OAAO,CAAC,qBAAqB;IA6B7B,OAAO,CAAC,aAAa;YAKP,aAAa;YAiBb,qBAAqB;YAqCrB,cAAc;CAkB7B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EAEd,aAAa,EACb,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAoCpB,OAAO,EACL,0BAA0B,EAC1B,mBAAmB,EACnB,0BAA0B,EAC1B,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,uBAAuB,EACvB,+BAA+B,EAC/B,+BAA+B,EAC/B,4BAA4B,GAC7B,MAAM,4BAA4B,CAAC;AAuEpC,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,MAAM,CAAuB;IACrC,yEAAyE;IACzE,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,uBAAuB,CAAK;IACpC,0EAA0E;IAC1E,OAAO,CAAC,iBAAiB,CAAuB;IAChD,4EAA4E;IAC5E,OAAO,CAAC,mBAAmB,CAAuB;IAClD,OAAO,CAAC,UAAU,CAA+C;IACjE,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,gBAAgB,CAA8C;IACtE,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAkB;IACnC;;;OAGG;IACH,OAAO,CAAC,gBAAgB,CAAuB;IAE/C,IAAI,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAgEvC,WAAW,IAAI,MAAM,GAAG,IAAI;IAKtB,gBAAgB,CACpB,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC;IAcV,cAAc,CAClB,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,aAAsB,EAC7B,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC;IASV,KAAK,CAAC,IAAI,CAAC,EAAE;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,GAAG,OAAO,CAAC,IAAI,CAAC;IA0CjB;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmD5B,OAAO,CAAC,YAAY;YAwBN,OAAO;IA4ErB,OAAO,CAAC,iBAAiB;IAkBzB,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,uBAAuB;IAK/B,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,uBAAuB;IAiB/B,OAAO,CAAC,qBAAqB;YAOf,qBAAqB;IAsBnC;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAmB5B,OAAO,CAAC,mBAAmB;IAO3B,8EAA8E;YAChE,YAAY;YAgBZ,eAAe;IAW7B,oFAAoF;IACpF,OAAO,CAAC,iBAAiB;IAiBzB,+EAA+E;IAC/E,OAAO,CAAC,oBAAoB;IAI5B;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IAYjC,OAAO,CAAC,uBAAuB;IAc/B,OAAO,CAAC,qBAAqB;IA6B7B,OAAO,CAAC,aAAa;YAKP,aAAa;YAkBb,qBAAqB;IA8HnC,OAAO,CAAC,kBAAkB;IAQ1B;;;OAGG;YACW,iBAAiB;YA2BjB,cAAc;CAuB7B"}

package/dist/index.d.ts

@@ -10,6 +10,8 @@ import type { CaptureContext, SeverityLevel, TalariaInitOptions } from './types.
  *   apiKey: 'tal_live_…',
  *   environment: 'development',
  *   replaysOnErrorSampleRate: 1,
+ *   // Default 15s post-error clip; set 0 to continue until 5 min cap.
+ *   replaysErrorAfterMs: 15_000,
  * });
  *
  * try {
@@ -27,7 +29,9 @@ export declare const Talaria: {
     flush(): Promise<void>;
     close(): Promise<void>;
 };
-export type { CaptureContext, Environment, SeverityLevel, TalariaInitOptions, } from './types.js';
 export { TalariaClient } from './client.js';
+export { computeErrorClipDeadlineMs, fitCompressedPrefix, isErrorClipBudgetExhausted, planOversizedRetry, } from './replay/fit_segment.js';
+export { MAX_SEGMENTS_ERROR_CLIP, MAX_ERROR_CLIP_COMPRESSED_BYTES, TARGET_COMPRESSED_SEGMENT_BYTES, MAX_COMPRESSED_SEGMENT_BYTES, } from './replay/segment_buffer.js';
+export type { CaptureContext, Environment, SeverityLevel, TalariaInitOptions, } from './types.js';
 export default Talaria;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACb,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAIpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,OAAO;kBACJ,kBAAkB,GAAG,IAAI;4BAIf,OAAO,YAAY,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;4BAK9D,MAAM,UACP,aAAa,YACX,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC;mBAID,MAAM,GAAG,IAAI;aAInB,OAAO,CAAC,IAAI,CAAC;aAIb,OAAO,CAAC,IAAI,CAAC;CAGvB,CAAC;AAEF,YAAY,EACV,cAAc,EACd,WAAW,EACX,aAAa,EACb,kBAAkB,GACnB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,eAAe,OAAO,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACb,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAIpB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,OAAO;kBACJ,kBAAkB,GAAG,IAAI;4BAIf,OAAO,YAAY,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;4BAK9D,MAAM,UACP,aAAa,YACX,cAAc,GACvB,OAAO,CAAC,IAAI,CAAC;mBAID,MAAM,GAAG,IAAI;aAInB,OAAO,CAAC,IAAI,CAAC;aAIb,OAAO,CAAC,IAAI,CAAC;CAGvB,CAAC;AAEF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EACL,0BAA0B,EAC1B,mBAAmB,EACnB,0BAA0B,EAC1B,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,uBAAuB,EACvB,+BAA+B,EAC/B,+BAA+B,EAC/B,4BAA4B,GAC7B,MAAM,4BAA4B,CAAC;AAEpC,YAAY,EACV,cAAc,EACd,WAAW,EACX,aAAa,EACb,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,eAAe,OAAO,CAAC"}