@newtalaria/browser 0.1.0

package/README.md

@@ -0,0 +1,123 @@
+# `@newtalaria/browser`
+
+Browser SDK for [Talaria](https://github.com/) — error capture and **session replay** (rrweb event streams, not video).
+
+## Install
+
+```bash
+npm install @newtalaria/browser
+```
+
+From this monorepo:
+
+```bash
+cd new_talaria_js/packages/browser
+npm install
+npm run build
+```
+
+## Quick start
+
+```ts
+import { Talaria } from '@newtalaria/browser';
+
+Talaria.init({
+  // Serverpod base URL (no trailing path)
+  dsn: 'http://localhost:8080',
+  apiKey: 'tal_live_…', // full raw key from createApiKey
+  environment: 'development',
+  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.
+  replaysOnErrorSampleRate: 1,
+  maskAllInputs: true, // default
+});
+
+try {
+  throw new Error('Something broke');
+} catch (error) {
+  await Talaria.captureException(error);
+}
+
+await Talaria.captureMessage('Checkout opened', 'info');
+console.log('replay', Talaria.getReplayId());
+
+await Talaria.flush();
+await Talaria.close();
+```
+
+`Talaria.init` also installs `window.onerror` / `unhandledrejection` handlers unless you pass `disableDefaultIntegrations: true`.
+
+## Serverpod URL pattern
+
+Talaria uses **Serverpod RPC**, not REST resource URLs:
+
+| Call | Method | URL |
+| --- | --- | --- |
+| Start replay | `POST` | `{baseUrl}/replays/start` |
+| Upload segment | `POST` | `{baseUrl}/replays/ingestSegment` |
+| Finish replay | `POST` | `{baseUrl}/replays/finish` |
+| Ingest event | `POST` | `{baseUrl}/events/ingest` |
+
+Local default: `http://localhost:8080`.
+
+Bodies are JSON with named parameters and `__className__` on typed inputs:
+
+```json
+{
+  "input": {
+    "__className__": "StartReplayInput",
+    "replayId": "…",
+    "environment": "development",
+    "sessionId": "…",
+    "url": "http://localhost:5173/"
+  }
+}
+```
+
+Auth (ingest):
+
+- `X-API-Key: tal_live_…` (preferred)
+- or `Authorization: Bearer tal_live_…`
+
+### ByteData (`gzipBytes`)
+
+Serverpod serializes `ByteData` as a wrapped base64 string:
+
+```text
+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)
+- `talaria-network` — method, redacted URL, status, duration (no bodies / no auth headers)
+
+Privacy defaults: `maskAllInputs: true`, password fields masked, `[data-talaria-mask]` blocked.
+
+## Public API
+
+| API | Description |
+| --- | --- |
+| `Talaria.init(options)` | Configure + start recording |
+| `Talaria.captureException(error)` | Ingest error (+ replay link when sampled) |
+| `Talaria.captureMessage(message, level?)` | Ingest message |
+| `Talaria.getReplayId()` | Active upload replay id, or `null` |
+| `Talaria.flush()` | Upload buffered segments |
+| `Talaria.close()` | Stop recording, flush, finish |
+
+## Example
+
+See [`../../examples/sdk-spa`](../../examples/sdk-spa) for a minimal page wired to `localhost:8080`.

package/dist/client.d.ts

@@ -0,0 +1,35 @@
+import type { CaptureContext, SeverityLevel, TalariaInitOptions } from './types.js';
+export declare class TalariaClient {
+    private options;
+    private transport;
+    private replayId;
+    private sessionId;
+    private recorder;
+    private buffer;
+    private uploadEnabled;
+    private startedOnServer;
+    private finishedOnServer;
+    private segmentIndex;
+    private flushTimer;
+    private uploadChain;
+    private closed;
+    private teardowns;
+    init(options: TalariaInitOptions): void;
+    getReplayId(): string | null;
+    captureException(error: unknown, context?: CaptureContext): Promise<void>;
+    captureMessage(message: string, level?: SeverityLevel, context?: CaptureContext): Promise<void>;
+    flush(opts?: {
+        reason?: string;
+        keepalive?: boolean;
+        finish?: boolean;
+    }): Promise<void>;
+    close(): Promise<void>;
+    private onRrwebEvent;
+    private capture;
+    private installGlobalHandlers;
+    private enqueueUpload;
+    private ensureStarted;
+    private uploadPendingSegments;
+    private finishOnServer;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +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"}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import type { CaptureContext, SeverityLevel, TalariaInitOptions } from './types.js';
+/**
+ * Talaria browser SDK — error capture + session replay.
+ *
+ * ```ts
+ * import { Talaria } from '@newtalaria/browser';
+ *
+ * Talaria.init({
+ *   dsn: 'http://localhost:8080',
+ *   apiKey: 'tal_live_…',
+ *   environment: 'development',
+ *   replaysOnErrorSampleRate: 1,
+ * });
+ *
+ * try {
+ *   throw new Error('boom');
+ * } catch (e) {
+ *   await Talaria.captureException(e);
+ * }
+ * ```
+ */
+export declare const Talaria: {
+    init(options: TalariaInitOptions): void;
+    captureException(error: unknown, context?: CaptureContext): Promise<void>;
+    captureMessage(message: string, level?: SeverityLevel, context?: CaptureContext): Promise<void>;
+    getReplayId(): string | null;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+};
+export type { CaptureContext, Environment, SeverityLevel, TalariaInitOptions, } from './types.js';
+export { TalariaClient } from './client.js';
+export default Talaria;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}