@watchupltd/browser 0.1.0 → 0.1.2

package/dist/index.d.mts

@@ -1,3 +1,11 @@
+interface WatchupUser {
+    /** Your app's internal user ID — the only required field. */
+    id: string | number;
+    email?: string;
+    name?: string;
+    /** Any extra key/value pairs you want attached to events. */
+    [key: string]: unknown;
+}
 interface WatchupOptions {
     /**
      * Your project's **public** API key from the Watchup dashboard.
@@ -46,6 +54,7 @@ interface TracePayload {
     environment?: string;
     release?: string;
     meta?: Record<string, unknown>;
+    user?: WatchupUser;
 }
 interface ErrorPayload {
     message: string;
@@ -56,6 +65,7 @@ interface ErrorPayload {
     timestamp: string;
     environment?: string;
     release?: string;
+    user?: WatchupUser;
 }
 interface EventPayload {
     name: string;
@@ -67,17 +77,81 @@ interface IngestBatch {
     errors?: ErrorPayload[];
     events?: EventPayload[];
 }
+interface WebAnalyticsPayload {
+    /** URL path, e.g. "/pricing". */
+    path: string;
+    /** Hostname of the tracked site, e.g. "example.com". */
+    hostname: string;
+    /** Full referrer URL (document.referrer). */
+    referrer?: string;
+    /** document.title at tracking time. */
+    title?: string;
+    /** Screen width in CSS pixels. */
+    screen_w?: number;
+    /** Screen height in CSS pixels. */
+    screen_h?: number;
+    /** navigator.language, e.g. "en-GB". */
+    lang?: string;
+    /** Intl.DateTimeFormat().resolvedOptions().timeZone */
+    timezone?: string;
+    /** UTM parameters parsed from the current URL's query string. */
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+    /**
+     * Persistent visitor UUID (stored in localStorage).
+     * The server hashes this before storing — the raw value is never persisted.
+     */
+    visitor_id: string;
+    /**
+     * Per-session UUID (stored in sessionStorage).
+     * The server hashes this before storing — the raw value is never persisted.
+     */
+    session_id: string;
+    /** Event type — defaults to "pageview". Use for custom web events. */
+    event_name?: string;
+    /** ISO-8601 timestamp when the event occurred. */
+    occurred_at: string;
+}
 
 declare class Watchup {
     private readonly cfg;
     private readonly batcher;
     private readonly cleanup;
+    private _user;
     /**
      * A random UUID generated on init.  Stable for the lifetime of the page —
      * useful for correlating all events from one user session.
      */
     readonly sessionId: string;
+    /**
+     * Persistent visitor ID.  Stored in localStorage so it survives browser
+     * sessions.  Falls back to a per-session UUID when localStorage is blocked.
+     * The server hashes this value with SHA-256 before persisting.
+     */
+    private readonly visitorId;
+    /**
+     * Per-session ID stored in sessionStorage.  Resets on tab close.
+     * The server hashes this value before persisting.
+     */
+    private readonly webSessionId;
     constructor(options: WatchupOptions);
+    private _getOrCreateVisitorId;
+    private _getOrCreateSessionId;
+    /**
+     * Attach a user to all subsequent errors, traces, and events.
+     * Call this after login; the context persists until `clearUser()` or page reload.
+     *
+     * @example
+     * watchup.setUser({ id: '42', email: 'ada@example.com', name: 'Ada Lovelace' });
+     */
+    setUser(user: WatchupUser): void;
+    /**
+     * Remove the current user context (e.g. after logout).
+     */
+    clearUser(): void;
     /**
      * Track a custom analytics event.
      *
@@ -85,6 +159,16 @@ declare class Watchup {
      * watchup.track('button.clicked', { label: 'Sign Up', variant: 'A' });
      */
     track(name: string, properties?: Record<string, unknown>): void;
+    /**
+     * Track a web analytics page view (or custom web event).
+     * Enriches the payload with visitor context, UTM params, and device info.
+     *
+     * Normally called automatically. Call manually when you need custom event_name.
+     *
+     * @example
+     * watchup.trackWebView({ event_name: 'conversion', path: '/checkout/success' });
+     */
+    trackWebView(overrides?: Partial<WebAnalyticsPayload>): void;
     /**
      * Manually capture an error.
      *
@@ -110,12 +194,13 @@ declare class Watchup {
         status?: TracePayload['status'];
         meta?: Record<string, unknown>;
     }) => void;
-    /** Immediately flush all queued items. */
+    /** Immediately flush all queued items (both telemetry and web analytics). */
     flush(): void;
     /** Stop the flush timer and release all listeners. */
     shutdown(): void;
     private _setupAutoCapture;
     private _setupPageViewTracking;
+    private _timezone;
 }
 
-export { type ErrorPayload, type EventPayload, type IngestBatch, type TracePayload, Watchup, type WatchupOptions };
+export { type ErrorPayload, type EventPayload, type IngestBatch, type TracePayload, Watchup, type WatchupOptions, type WatchupUser };

package/dist/index.d.ts

@@ -1,3 +1,11 @@
+interface WatchupUser {
+    /** Your app's internal user ID — the only required field. */
+    id: string | number;
+    email?: string;
+    name?: string;
+    /** Any extra key/value pairs you want attached to events. */
+    [key: string]: unknown;
+}
 interface WatchupOptions {
     /**
      * Your project's **public** API key from the Watchup dashboard.
@@ -46,6 +54,7 @@ interface TracePayload {
     environment?: string;
     release?: string;
     meta?: Record<string, unknown>;
+    user?: WatchupUser;
 }
 interface ErrorPayload {
     message: string;
@@ -56,6 +65,7 @@ interface ErrorPayload {
     timestamp: string;
     environment?: string;
     release?: string;
+    user?: WatchupUser;
 }
 interface EventPayload {
     name: string;
@@ -67,17 +77,81 @@ interface IngestBatch {
     errors?: ErrorPayload[];
     events?: EventPayload[];
 }
+interface WebAnalyticsPayload {
+    /** URL path, e.g. "/pricing". */
+    path: string;
+    /** Hostname of the tracked site, e.g. "example.com". */
+    hostname: string;
+    /** Full referrer URL (document.referrer). */
+    referrer?: string;
+    /** document.title at tracking time. */
+    title?: string;
+    /** Screen width in CSS pixels. */
+    screen_w?: number;
+    /** Screen height in CSS pixels. */
+    screen_h?: number;
+    /** navigator.language, e.g. "en-GB". */
+    lang?: string;
+    /** Intl.DateTimeFormat().resolvedOptions().timeZone */
+    timezone?: string;
+    /** UTM parameters parsed from the current URL's query string. */
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+    /**
+     * Persistent visitor UUID (stored in localStorage).
+     * The server hashes this before storing — the raw value is never persisted.
+     */
+    visitor_id: string;
+    /**
+     * Per-session UUID (stored in sessionStorage).
+     * The server hashes this before storing — the raw value is never persisted.
+     */
+    session_id: string;
+    /** Event type — defaults to "pageview". Use for custom web events. */
+    event_name?: string;
+    /** ISO-8601 timestamp when the event occurred. */
+    occurred_at: string;
+}
 
 declare class Watchup {
     private readonly cfg;
     private readonly batcher;
     private readonly cleanup;
+    private _user;
     /**
      * A random UUID generated on init.  Stable for the lifetime of the page —
      * useful for correlating all events from one user session.
      */
     readonly sessionId: string;
+    /**
+     * Persistent visitor ID.  Stored in localStorage so it survives browser
+     * sessions.  Falls back to a per-session UUID when localStorage is blocked.
+     * The server hashes this value with SHA-256 before persisting.
+     */
+    private readonly visitorId;
+    /**
+     * Per-session ID stored in sessionStorage.  Resets on tab close.
+     * The server hashes this value before persisting.
+     */
+    private readonly webSessionId;
     constructor(options: WatchupOptions);
+    private _getOrCreateVisitorId;
+    private _getOrCreateSessionId;
+    /**
+     * Attach a user to all subsequent errors, traces, and events.
+     * Call this after login; the context persists until `clearUser()` or page reload.
+     *
+     * @example
+     * watchup.setUser({ id: '42', email: 'ada@example.com', name: 'Ada Lovelace' });
+     */
+    setUser(user: WatchupUser): void;
+    /**
+     * Remove the current user context (e.g. after logout).
+     */
+    clearUser(): void;
     /**
      * Track a custom analytics event.
      *
@@ -85,6 +159,16 @@ declare class Watchup {
      * watchup.track('button.clicked', { label: 'Sign Up', variant: 'A' });
      */
     track(name: string, properties?: Record<string, unknown>): void;
+    /**
+     * Track a web analytics page view (or custom web event).
+     * Enriches the payload with visitor context, UTM params, and device info.
+     *
+     * Normally called automatically. Call manually when you need custom event_name.
+     *
+     * @example
+     * watchup.trackWebView({ event_name: 'conversion', path: '/checkout/success' });
+     */
+    trackWebView(overrides?: Partial<WebAnalyticsPayload>): void;
     /**
      * Manually capture an error.
      *
@@ -110,12 +194,13 @@ declare class Watchup {
         status?: TracePayload['status'];
         meta?: Record<string, unknown>;
     }) => void;
-    /** Immediately flush all queued items. */
+    /** Immediately flush all queued items (both telemetry and web analytics). */
     flush(): void;
     /** Stop the flush timer and release all listeners. */
     shutdown(): void;
     private _setupAutoCapture;
     private _setupPageViewTracking;
+    private _timezone;
 }
 
-export { type ErrorPayload, type EventPayload, type IngestBatch, type TracePayload, Watchup, type WatchupOptions };
+export { type ErrorPayload, type EventPayload, type IngestBatch, type TracePayload, Watchup, type WatchupOptions, type WatchupUser };

package/dist/index.js

@@ -3,7 +3,9 @@
 // src/transport.ts
 var Transport = class {
   constructor(baseUrl, apiKey, debug = false) {
-    this.url = `${baseUrl.replace(/\/$/, "")}/api/v1/ingest/batch`;
+    const base = baseUrl.replace(/\/$/, "");
+    this.url = `${base}/api/v1/ingest/batch`;
+    this.webUrl = `${base}/api/v1/ingest/web-batch`;
     this.headers = {
       "Content-Type": "application/json",
       "X-Api-Key": apiKey
@@ -37,6 +39,31 @@ var Transport = class {
       if (this.debug) console.warn("[watchup] send failed:", err);
     }
   }
+  /**
+   * Send web analytics batch to the dedicated /web-batch endpoint.
+   * Never rejects.
+   */
+  async sendWeb(batch) {
+    try {
+      const body = JSON.stringify(batch);
+      if (body.length > 6e4) {
+        this.beaconWeb(batch);
+        return;
+      }
+      const res = await fetch(this.webUrl, {
+        method: "POST",
+        headers: this.headers,
+        body,
+        keepalive: true
+      });
+      if (this.debug && !res.ok) {
+        const text = await res.text().catch(() => "");
+        console.warn(`[watchup] web-batch ${res.status}: ${text}`);
+      }
+    } catch (err) {
+      if (this.debug) console.warn("[watchup] sendWeb failed:", err);
+    }
+  }
   /**
    * Send via `navigator.sendBeacon`.
    * Returns `true` if the browser accepted the request (doesn't guarantee delivery).
@@ -51,6 +78,18 @@ var Transport = class {
       return false;
     }
   }
+  /**
+   * sendBeacon variant for web analytics events.
+   */
+  beaconWeb(batch) {
+    if (typeof navigator === "undefined" || !navigator.sendBeacon) return false;
+    try {
+      const blob = new Blob([JSON.stringify(batch)], { type: "application/json" });
+      return navigator.sendBeacon(this.webUrl, blob);
+    } catch {
+      return false;
+    }
+  }
 };
 
 // src/batcher.ts
@@ -59,6 +98,7 @@ var Batcher = class {
     this.traces = [];
     this.errors = [];
     this.events = [];
+    this.webViews = [];
     this.timer = null;
     this.flushing = false;
     this.transport = transport;
@@ -79,6 +119,7 @@ var Batcher = class {
       this.timer = null;
     }
   }
+  // ── Telemetry queue ───────────────────────────────────────────────────────
   addTrace(t) {
     this.traces.push(t);
     if (this.traces.length >= this.maxBatchSize) this.flush();
@@ -91,27 +132,49 @@ var Batcher = class {
     this.events.push(e);
     if (this.events.length >= this.maxBatchSize) this.flush();
   }
-  drain() {
+  // ── Web analytics queue ───────────────────────────────────────────────────
+  addWebView(payload) {
+    this.webViews.push(payload);
+    if (this.webViews.length >= this.maxBatchSize) this.flushWeb();
+  }
+  // ── Drain helpers ─────────────────────────────────────────────────────────
+  drainTelemetry() {
     const traces = this.traces.splice(0);
     const errors = this.errors.splice(0);
     const events = this.events.splice(0);
     if (!traces.length && !errors.length && !events.length) return null;
     return { traces, errors, events };
   }
+  drainWeb() {
+    const web = this.webViews.splice(0);
+    if (!web.length) return null;
+    return { web };
+  }
+  // ── Flush ─────────────────────────────────────────────────────────────────
   flush() {
-    if (this.flushing) return;
-    const batch = this.drain();
-    if (!batch) return;
-    this.flushing = true;
-    this.transport.send(batch).finally(() => {
-      this.flushing = false;
-    });
+    if (!this.flushing) {
+      const batch = this.drainTelemetry();
+      if (batch) {
+        this.flushing = true;
+        this.transport.send(batch).finally(() => {
+          this.flushing = false;
+        });
+      }
+    }
+    this.flushWeb();
+  }
+  flushWeb() {
+    const batch = this.drainWeb();
+    if (batch) this.transport.sendWeb(batch);
   }
   beaconFlush() {
-    const batch = this.drain();
-    if (!batch) return;
-    if (!this.transport.beacon(batch)) {
-      this.transport.send(batch);
+    const batch = this.drainTelemetry();
+    if (batch) {
+      if (!this.transport.beacon(batch)) this.transport.send(batch);
+    }
+    const webBatch = this.drainWeb();
+    if (webBatch) {
+      if (!this.transport.beaconWeb(webBatch)) this.transport.sendWeb(webBatch);
     }
   }
 };
@@ -267,9 +330,12 @@ var DEFAULTS = {
     pageViews: true
   }
 };
+var VISITOR_KEY = "__wup_vid";
+var SESSION_KEY = "__wup_sid";
 var Watchup = class {
   constructor(options) {
     this.cleanup = [];
+    this._user = null;
     /**
      * A random UUID generated on init.  Stable for the lifetime of the page —
      * useful for correlating all events from one user session.
@@ -286,8 +352,52 @@ var Watchup = class {
     const transport = new Transport(this.cfg.baseUrl, this.cfg.apiKey, this.cfg.debug);
     this.batcher = new Batcher(transport, this.cfg.flushInterval, this.cfg.maxBatchSize);
     this.batcher.start();
+    this.visitorId = this._getOrCreateVisitorId();
+    this.webSessionId = this._getOrCreateSessionId();
     this._setupAutoCapture();
   }
+  // ── Visitor / session identity helpers ─────────────────────────────────────
+  _getOrCreateVisitorId() {
+    try {
+      let id = localStorage.getItem(VISITOR_KEY);
+      if (!id) {
+        id = crypto.randomUUID();
+        localStorage.setItem(VISITOR_KEY, id);
+      }
+      return id;
+    } catch {
+      return crypto.randomUUID();
+    }
+  }
+  _getOrCreateSessionId() {
+    try {
+      let id = sessionStorage.getItem(SESSION_KEY);
+      if (!id) {
+        id = crypto.randomUUID();
+        sessionStorage.setItem(SESSION_KEY, id);
+      }
+      return id;
+    } catch {
+      return this.sessionId;
+    }
+  }
+  // ── User identification ───────────────────────────────────────────────────
+  /**
+   * Attach a user to all subsequent errors, traces, and events.
+   * Call this after login; the context persists until `clearUser()` or page reload.
+   *
+   * @example
+   * watchup.setUser({ id: '42', email: 'ada@example.com', name: 'Ada Lovelace' });
+   */
+  setUser(user) {
+    this._user = { ...user };
+  }
+  /**
+   * Remove the current user context (e.g. after logout).
+   */
+  clearUser() {
+    this._user = null;
+  }
   // ── Public API ────────────────────────────────────────────────────────────
   /**
    * Track a custom analytics event.
@@ -304,6 +414,44 @@ var Watchup = class {
     };
     this.batcher.addEvent(event);
   }
+  /**
+   * Track a web analytics page view (or custom web event).
+   * Enriches the payload with visitor context, UTM params, and device info.
+   *
+   * Normally called automatically. Call manually when you need custom event_name.
+   *
+   * @example
+   * watchup.trackWebView({ event_name: 'conversion', path: '/checkout/success' });
+   */
+  trackWebView(overrides = {}) {
+    var _a, _b;
+    const url = new URL(window.location.href);
+    const params = url.searchParams;
+    const payload = {
+      path: url.pathname + (url.search || ""),
+      hostname: url.hostname,
+      referrer: document.referrer || void 0,
+      title: document.title || void 0,
+      screen_w: (_a = window.screen) == null ? void 0 : _a.width,
+      screen_h: (_b = window.screen) == null ? void 0 : _b.height,
+      lang: navigator.language || void 0,
+      timezone: this._timezone(),
+      // UTM parameters
+      utm_source: params.get("utm_source") || void 0,
+      utm_medium: params.get("utm_medium") || void 0,
+      utm_campaign: params.get("utm_campaign") || void 0,
+      utm_term: params.get("utm_term") || void 0,
+      utm_content: params.get("utm_content") || void 0,
+      // Identity (raw; the server hashes before storing)
+      visitor_id: this.visitorId,
+      session_id: this.webSessionId,
+      event_name: "pageview",
+      occurred_at: (/* @__PURE__ */ new Date()).toISOString(),
+      // Apply caller overrides last
+      ...overrides
+    };
+    this.batcher.addWebView(payload);
+  }
   /**
    * Manually capture an error.
    *
@@ -325,7 +473,8 @@ var Watchup = class {
       },
       timestamp: (/* @__PURE__ */ new Date()).toISOString(),
       environment: this.cfg.environment,
-      ...this.cfg.release && { release: this.cfg.release }
+      ...this.cfg.release && { release: this.cfg.release },
+      ...this._user && { user: this._user }
     };
     this.batcher.addError(payload);
   }
@@ -351,11 +500,12 @@ var Watchup = class {
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
         environment: this.cfg.environment,
         ...this.cfg.release && { release: this.cfg.release },
-        ...opts.meta && { meta: opts.meta }
+        ...opts.meta && { meta: opts.meta },
+        ...this._user && { user: this._user }
       });
     };
   }
-  /** Immediately flush all queued items. */
+  /** Immediately flush all queued items (both telemetry and web analytics). */
   flush() {
     this.batcher.flush();
   }
@@ -383,33 +533,24 @@ var Watchup = class {
     }
   }
   _setupPageViewTracking() {
-    const track = () => {
-      this.batcher.addEvent({
-        name: "pageview",
-        properties: {
-          path: window.location.pathname,
-          ...window.location.search && { search: window.location.search },
-          ...document.referrer && { referrer: document.referrer },
-          title: document.title
-        },
-        occurred_at: (/* @__PURE__ */ new Date()).toISOString()
-      });
+    const trackView = () => {
+      setTimeout(() => this.trackWebView(), 0);
     };
     if (document.readyState === "loading") {
-      document.addEventListener("DOMContentLoaded", track, { once: true });
+      document.addEventListener("DOMContentLoaded", trackView, { once: true });
     } else {
-      setTimeout(track, 0);
+      setTimeout(() => this.trackWebView(), 0);
     }
     const origPush = history.pushState.bind(history);
     const origReplace = history.replaceState.bind(history);
     history.pushState = (...args) => {
       origPush(...args);
-      setTimeout(track, 0);
+      trackView();
     };
     history.replaceState = (...args) => {
       origReplace(...args);
     };
-    const onPopState = () => setTimeout(track, 0);
+    const onPopState = () => trackView();
     window.addEventListener("popstate", onPopState);
     this.cleanup.push(() => {
       history.pushState = origPush;
@@ -417,6 +558,14 @@ var Watchup = class {
       window.removeEventListener("popstate", onPopState);
     });
   }
+  // ── Helpers ───────────────────────────────────────────────────────────────
+  _timezone() {
+    try {
+      return Intl.DateTimeFormat().resolvedOptions().timeZone || void 0;
+    } catch {
+      return void 0;
+    }
+  }
 };
 
 exports.Watchup = Watchup;