@obsrviq/tracker 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Obsrviq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# @obsrviq/tracker
+
+The Obsrviq capture SDK. A tiny, privacy-first script that records DOM (rrweb),
+console, network, errors, and web vitals, then ships them in masked, gzipped
+batches. No tagging required.
+
+## Install
+
+**Script tag (no build):**
+```html
+<script
+  src="https://cdn.yourapp.com/obsrviq.global.js"
+  data-obsrviq-key="pk_live_xxx"
+  data-obsrviq-endpoint="https://in.yourapp.com"></script>
+```
+The built file is `dist/obsrviq.global.js` (host it on your CDN).
+
+**npm:**
+```bash
+npm install @obsrviq/tracker
+```
+```ts
+import { Obsrviq } from '@obsrviq/tracker';
+Obsrviq.init({ siteKey: 'pk_live_xxx', endpoint: 'https://in.yourapp.com' });
+```
+
+## API
+
+```ts
+Obsrviq.init(config);                 // see config below
+Obsrviq.identify(userId, traits?);    // raw userId (searchable) + SHA-256 hash; retro-stamps
+Obsrviq.setMetadata({ plan: 'pro' }); // merge searchable session properties anytime
+Obsrviq.reset();                      // forget identity on logout → fresh anonymous session
+Obsrviq.track('event', { conversion: true });
+Obsrviq.setConsent(true | false);     // gate recording (PRIV-2)
+Obsrviq.stop();                       // hard stop + flush
+Obsrviq.getDiagnostics();             // { recording, sessionId, flushes, bytesSent, … }
+```
+
+## Config
+
+| Option | Default | Notes |
+|---|---|---|
+| `siteKey` | — | **Required.** The `pk_` ingest key. |
+| `endpoint` | `https://in.lumera.app` | Your ingest URL. |
+| `maskAllInputs` | `true` | Never record input values. |
+| `maskTextSelector` | — | Mask text inside matching nodes. |
+| `blockSelector` | `.obsrviq-block` | Never record these nodes. |
+| `captureNetworkBodies` | `false` | Opt-in, masked, size-capped. |
+| `redactHeaders` | `authorization, cookie, set-cookie` | Redacted in captured headers. |
+| `requireConsent` | `false` | If true, nothing records until `setConsent(true)`. |
+| `sampleRate` | `1.0` | 0..1 fraction of sessions to record. |
+| `flushIntervalMs` | `5000` | Batch flush cadence. |
+| `beforeSend` | — | Last-chance redaction; return `null` to drop. |
+
+## Behavior
+
+- **Consent & privacy:** with a consent gate and consent withheld, *zero* network
+  calls leave the page (honors Global Privacy Control / DNT).
+- **Transport:** gzipped via fflate, sent with `sendBeacon` (or `fetch` keepalive)
+  on a timer, on `visibilitychange=hidden`, and on `pagehide`.
+- **Capture:** rrweb for DOM (periodic full snapshots for progressive replay);
+  custom interceptors for `fetch` / `XHR` / `PerformanceObserver` / `sendBeacon`;
+  console hooks; `window.onerror` + `onunhandledrejection`; web vitals; rage/dead
+  click detection.
+
+Full guide: [docs/EMBEDDING.md](../../docs/EMBEDDING.md).

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+import { ObsrviqInitConfig } from '@obsrviq/types';
+export { ObsrviqInitConfig } from '@obsrviq/types';
+
+interface Diagnostics {
+    recording: boolean;
+    sessionId: string | null;
+    flushes: number;
+    bytesSent: number;
+    eventsSent: number;
+    eventsQueued: number;
+}
+declare class ObsrviqClient {
+    private config;
+    private clock;
+    private transport;
+    private teardowns;
+    private meta;
+    private recording;
+    private consent;
+    private sampledIn;
+    private lastActivity;
+    /** The userId this session is attributed to (for the shared-device split). */
+    private currentUserId;
+    /** Next batch seq — mirrored from the transport so we can persist continuation. */
+    private nextSeq;
+    /** Open task spans keyed by task name → the span id + start time, so endTask()
+     *  can pair with its startTask(). Re-starting the same name supersedes the
+     *  earlier open span (the player pairs by spanId, so this only affects which
+     *  start an unqualified end() resolves to). */
+    private openTasks;
+    private consentUnmount;
+    private recDotUnmount;
+    private diag;
+    /** The current session id (null until init). */
+    get sessionId(): string | null;
+    init(config: ObsrviqInitConfig): void;
+    /** (Re)create the session id, clock, meta, and transport. Used by init() and
+     *  reset(). Does not start recording — callers decide via maybeStart().
+     *  @param seedInitUser seed identity from the init-time `cfg.userId`. True for
+     *  the initial init() session; FALSE for reset() (logout) — otherwise the fresh
+     *  post-logout session would be re-attributed to the user who just logged out. */
+    private startSession;
+    /** Persist the session-continuation record (no-op unless continueSession). Only
+     *  ever writes for a RECORDING session — a sampled-out or pre-consent session must
+     *  not leave a record that a later page would resume (and force back into
+     *  recording), and identify() can fire before recording starts. */
+    private persistSession;
+    private maybeStart;
+    /** Associate the session with an application user. Stores the RAW userId (for
+     *  search + display) AND a SHA-256 identityHash, merges any traits into metadata,
+     *  and force-flushes so the live session is retro-stamped promptly. Safe to call
+     *  before recording starts (values ride the first batch) and after login. */
+    identify(userId: string, traits?: Record<string, unknown>): void;
+    /** Merge custom properties onto the session at any time (searchable server-side). */
+    setMetadata(props: Record<string, unknown>): void;
+    /** Forget the current identity (e.g. on logout) and rotate to a fresh anonymous
+     *  session, so post-logout activity isn't attributed to the prior user. (Identity
+     *  can't be cleared on the existing row — the server merge only fills nulls — so
+     *  we start a new session instead.) */
+    reset(): void;
+    /** Set the raw userId on meta and compute its hash (async). */
+    private applyUserId;
+    private mergeMetadata;
+    /** Emit a custom event (e.g. conversions). */
+    track(name: string, props?: Record<string, unknown>): void;
+    /** Mark a conversion. Conversion is client-defined, so the NAME matters —
+     *  "checkout", "signup", "trial_started" — and each is denormalised onto the
+     *  session for per-client filtering. Sets props.conversion so the legacy
+     *  'conversion' flag still lights up. Sugar over track(name, {conversion:true}). */
+    conversion(name: string, props?: Record<string, unknown>): void;
+    /** Attach one or more free-form, searchable labels to the current session.
+     *  Tags are session-level (deduped server-side) — use them to slice sessions
+     *  however a client likes ("vip", "ab_variant_b", "mobile_app"). */
+    tag(...names: string[]): void;
+    /** Begin a named sub-event span. Pairs with end() / endTask(name) to produce a
+     *  searchable, duration-bearing span on the session timeline. Returns a handle
+     *  so callers can `const t = Obsrviq.startTask('checkout'); …; t.end()`. */
+    startTask(name: string, props?: Record<string, unknown>): {
+        end: (endProps?: Record<string, unknown>) => void;
+    };
+    /** Close a named sub-event span opened by startTask(name). Safe to call even
+     *  if the start was never seen (renders as an orphan end on the timeline). */
+    endTask(name: string, props?: Record<string, unknown>): void;
+    /** Gate recording (PRIV-2). true starts; false stops + flushes. Dismisses the
+     *  built-in consent prompt if one is showing. */
+    setConsent(granted: boolean): void;
+    /** Hard stop + flush. */
+    stop(): void;
+    /** Force a flush now (returns when send is attempted). */
+    flush(): Promise<boolean>;
+    getDiagnostics(): Diagnostics;
+    private teardown;
+}
+declare const Obsrviq: ObsrviqClient;
+
+export { type Diagnostics, Obsrviq, Obsrviq as default };