@watchupltd/browser 0.1.9 → 0.2.0

package/dist/index.mjs

@@ -0,0 +1,669 @@
+// src/transport.ts
+var Transport = class {
+  constructor(baseUrl, apiKey, debug = false) {
+    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
+    };
+    this.debug = debug;
+  }
+  /**
+   * Send via `fetch` with `keepalive: true`.
+   * `keepalive` lets the request outlive the current page — it's the
+   * browser equivalent of a "fire and forget" POST.
+   * Never rejects.
+   */
+  async send(batch) {
+    try {
+      const body = JSON.stringify(batch);
+      if (body.length > 6e4) {
+        this.beacon(batch);
+        return;
+      }
+      const res = await fetch(this.url, {
+        method: "POST",
+        headers: this.headers,
+        body,
+        keepalive: true
+      });
+      if (this.debug && !res.ok) {
+        const text = await res.text().catch(() => "");
+        console.warn(`[watchup] ingest ${res.status}: ${text}`);
+      }
+    } catch (err) {
+      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).
+   * The server must accept `application/json` from sendBeacon via a Blob.
+   */
+  beacon(batch) {
+    if (typeof navigator === "undefined" || !navigator.sendBeacon) return false;
+    try {
+      const blob = new Blob([JSON.stringify(batch)], { type: "application/json" });
+      return navigator.sendBeacon(this.url, blob);
+    } catch {
+      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
+var Batcher = class {
+  constructor(transport, flushInterval, maxBatchSize) {
+    this.traces = [];
+    this.errors = [];
+    this.events = [];
+    this.webViews = [];
+    this.timer = null;
+    this.flushing = false;
+    this.transport = transport;
+    this.flushInterval = flushInterval;
+    this.maxBatchSize = maxBatchSize;
+  }
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => this.flush(), this.flushInterval);
+    document.addEventListener("visibilitychange", () => {
+      if (document.visibilityState === "hidden") this.beaconFlush();
+    });
+    window.addEventListener("pagehide", () => this.beaconFlush(), { once: true });
+  }
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  // ── Telemetry queue ───────────────────────────────────────────────────────
+  addTrace(t) {
+    this.traces.push(t);
+    if (this.traces.length >= this.maxBatchSize) this.flush();
+  }
+  addError(e) {
+    this.errors.push(e);
+    if (this.errors.length >= Math.ceil(this.maxBatchSize / 2)) this.flush();
+  }
+  addEvent(e) {
+    this.events.push(e);
+    if (this.events.length >= this.maxBatchSize) this.flush();
+  }
+  // ── 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) {
+      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.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);
+    }
+  }
+};
+
+// src/error-capture.ts
+function captureGlobalErrors(onError, env) {
+  const handleError = (event) => {
+    var _a, _b, _c, _d;
+    onError({
+      message: event.message || "Unknown error",
+      level: "error",
+      route: window.location.pathname,
+      stack: (_a = event.error) == null ? void 0 : _a.stack,
+      context: {
+        url: window.location.href,
+        source: (_b = event.filename) != null ? _b : void 0,
+        line: (_c = event.lineno) != null ? _c : void 0,
+        col: (_d = event.colno) != null ? _d : void 0
+      },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...env && { environment: env }
+    });
+  };
+  const handleRejection = (event) => {
+    const reason = event.reason;
+    const isErr = reason instanceof Error;
+    onError({
+      message: isErr ? reason.message : String(reason != null ? reason : "Unhandled Promise rejection"),
+      level: "error",
+      route: window.location.pathname,
+      stack: isErr ? reason.stack : void 0,
+      context: {
+        url: window.location.href,
+        type: "unhandledrejection"
+      },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...env && { environment: env }
+    });
+  };
+  window.addEventListener("error", handleError);
+  window.addEventListener("unhandledrejection", handleRejection);
+  return () => {
+    window.removeEventListener("error", handleError);
+    window.removeEventListener("unhandledrejection", handleRejection);
+  };
+}
+
+// src/perf.ts
+function rating(ms, good, needsImprovement) {
+  if (ms <= good) return "ok";
+  if (ms <= needsImprovement) return "warn";
+  return "err";
+}
+function statusCode(status) {
+  return status === "err" ? 500 : status === "warn" ? 400 : 200;
+}
+function captureFCP(onTrace, env) {
+  if (typeof PerformanceObserver === "undefined") return;
+  try {
+    const po = new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        if (entry.name !== "first-contentful-paint") continue;
+        const ms = Math.round(entry.startTime);
+        const status = rating(ms, 1800, 3e3);
+        onTrace({
+          span: "web-vital fcp",
+          ms,
+          status_code: statusCode(status),
+          status,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          ...env && { environment: env }
+        });
+        po.disconnect();
+      }
+    });
+    po.observe({ type: "paint", buffered: true });
+  } catch {
+  }
+}
+function captureLCP(onTrace, env) {
+  if (typeof PerformanceObserver === "undefined") return;
+  let last = null;
+  let reported = false;
+  const report = () => {
+    if (reported || !last) return;
+    reported = true;
+    try {
+      po.disconnect();
+    } catch {
+    }
+    const ms = Math.round(last.startTime);
+    const status = rating(ms, 2500, 4e3);
+    onTrace({
+      span: "web-vital lcp",
+      ms,
+      status_code: statusCode(status),
+      status,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...env && { environment: env }
+    });
+  };
+  let po;
+  try {
+    po = new PerformanceObserver((list) => {
+      var _a;
+      const entries = list.getEntries();
+      if (entries.length) last = (_a = entries[entries.length - 1]) != null ? _a : null;
+    });
+    po.observe({ type: "largest-contentful-paint", buffered: true });
+  } catch {
+    return;
+  }
+  document.addEventListener("visibilitychange", report, { once: true });
+  document.addEventListener("keydown", report, { once: true, capture: true });
+  document.addEventListener("pointerdown", report, { once: true, capture: true });
+}
+function capturePageLoad(onTrace, env) {
+  const report = () => {
+    const nav = performance.getEntriesByType("navigation")[0];
+    if (!nav || nav.loadEventEnd <= 0) return;
+    const ms = Math.round(nav.loadEventEnd - nav.startTime);
+    const ttfb = Math.round(nav.responseStart - nav.requestStart);
+    const status = rating(ms, 2e3, 4e3);
+    onTrace({
+      span: "pageload",
+      ms,
+      status_code: statusCode(status),
+      status,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      meta: { ttfb },
+      ...env && { environment: env }
+    });
+  };
+  if (document.readyState === "complete") {
+    setTimeout(report, 0);
+  } else {
+    window.addEventListener("load", () => setTimeout(report, 100), { once: true });
+  }
+}
+
+// src/watchup.ts
+function flagBucket(flagKey, userId) {
+  const str = `${flagKey}:${userId}`;
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = hash * 33 ^ str.charCodeAt(i) | 0;
+  }
+  return (hash >>> 0) % 100;
+}
+function matchesTargeting(flag, ctx) {
+  var _a;
+  if (!((_a = flag.targeting_rules) == null ? void 0 : _a.length)) return true;
+  return flag.targeting_rules.every((rule) => {
+    var _a2;
+    const val = String((_a2 = ctx[rule.attribute]) != null ? _a2 : "");
+    switch (rule.operator) {
+      case "in":
+        return rule.values.includes(val);
+      case "not_in":
+        return !rule.values.includes(val);
+      case "contains":
+        return rule.values.some((v) => val.includes(v));
+      case "equals":
+        return rule.values[0] === val;
+      default:
+        return true;
+    }
+  });
+}
+var DEFAULTS = {
+  baseUrl: "https://api.watchup.site",
+  flushInterval: 5e3,
+  maxBatchSize: 100,
+  debug: false,
+  environment: "production",
+  release: "",
+  sampleRate: 1,
+  autoCapture: {
+    errors: true,
+    performance: true,
+    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.
+     */
+    this.sessionId = crypto.randomUUID();
+    // Feature flags
+    this._flags = /* @__PURE__ */ new Map();
+    this._flagTimer = null;
+    if (!options.apiKey) {
+      throw new Error("[watchup] apiKey is required.");
+    }
+    this.cfg = {
+      ...DEFAULTS,
+      autoCapture: { ...DEFAULTS.autoCapture, ...options.autoCapture },
+      ...options
+    };
+    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();
+    this._fetchFlags();
+    this._flagTimer = setInterval(() => this._fetchFlags(), 3e4);
+    this.cleanup.push(() => {
+      if (this._flagTimer) clearInterval(this._flagTimer);
+    });
+  }
+  async _fetchFlags() {
+    var _a;
+    try {
+      const res = await fetch(`${this.cfg.baseUrl}/api/v1/flags`, {
+        headers: { "X-Api-Key": this.cfg.apiKey }
+      });
+      if (!res.ok) return;
+      const json = await res.json();
+      if (json.ok && ((_a = json.data) == null ? void 0 : _a.flags)) {
+        this._flags.clear();
+        for (const flag of json.data.flags) {
+          this._flags.set(flag.key, flag);
+        }
+      }
+    } catch {
+    }
+  }
+  // ── 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.
+   *
+   * @example
+   * watchup.track('button.clicked', { label: 'Sign Up', variant: 'A' });
+   */
+  track(name, properties) {
+    if (!name) return;
+    const event = {
+      name,
+      ...properties && Object.keys(properties).length && { properties },
+      occurred_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    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.
+   *
+   * @example
+   * try { ... } catch (err) {
+   *   watchup.captureError(err, { component: 'CheckoutForm' });
+   * }
+   */
+  captureError(error, context) {
+    const { route, level = "error", ...rest } = context != null ? context : {};
+    const err = error instanceof Error ? error : new Error(String(error));
+    const payload = {
+      message: err.message,
+      level,
+      ...err.stack !== void 0 && { stack: err.stack },
+      route: route != null ? route : window.location.pathname,
+      ...Object.keys(rest).length && {
+        context: { ...rest, url: window.location.href }
+      },
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      environment: this.cfg.environment,
+      ...this.cfg.release && { release: this.cfg.release },
+      ...this._user && { user: this._user }
+    };
+    this.batcher.addError(payload);
+  }
+  /**
+   * Time any async operation and record it as a trace.
+   * Returns an `end()` function — call it when the operation finishes.
+   *
+   * @example
+   * const end = watchup.startTrace('fetch /api/cart');
+   * const cart = await fetch('/api/cart');
+   * end({ status: cart.ok ? 'ok' : 'err' });
+   */
+  startTrace(span) {
+    const start = Date.now();
+    return (opts = {}) => {
+      var _a;
+      const status = (_a = opts.status) != null ? _a : "ok";
+      this.batcher.addTrace({
+        span,
+        ms: Date.now() - start,
+        status_code: status === "err" ? 500 : status === "warn" ? 400 : 200,
+        status,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        environment: this.cfg.environment,
+        ...this.cfg.release && { release: this.cfg.release },
+        ...opts.meta && { meta: opts.meta },
+        ...this._user && { user: this._user }
+      });
+    };
+  }
+  // ── Feature flags ─────────────────────────────────────────────────────────
+  /**
+   * Check whether a feature flag is enabled. Evaluated locally — zero
+   * network latency. Flag rules refresh every 30 seconds in the background.
+   * Falls back to the identified user (via `setUser`) when no context is given.
+   *
+   * @example
+   * if (watchup.isEnabled('new-checkout')) {
+   *   renderNewCheckout();
+   * }
+   */
+  isEnabled(key, ctx = {}) {
+    var _a, _b, _c, _d;
+    const flag = this._flags.get(key);
+    if (!flag || !flag.enabled) return false;
+    const mergedCtx = { userId: (_a = this._user) == null ? void 0 : _a.id, email: (_b = this._user) == null ? void 0 : _b.email, ...ctx };
+    if (!matchesTargeting(flag, mergedCtx)) return false;
+    if (flag.rollout_percentage >= 100) return true;
+    if (flag.rollout_percentage <= 0) return false;
+    const userId = String((_d = (_c = mergedCtx.userId) != null ? _c : mergedCtx.email) != null ? _d : this.visitorId);
+    return flagBucket(key, userId) < flag.rollout_percentage;
+  }
+  /**
+   * Get the variant key for a multivariate (A/B) flag.
+   * Returns `"control"` if the flag is off or the visitor isn't in the rollout.
+   *
+   * @example
+   * const variant = watchup.getVariant('pricing-layout');
+   * // → "control" | "variant-a" | "variant-b"
+   */
+  getVariant(key, ctx = {}) {
+    var _a, _b, _c, _d, _e;
+    if (!this.isEnabled(key, ctx)) return "control";
+    const flag = this._flags.get(key);
+    if (!((_a = flag.variants) == null ? void 0 : _a.length)) return "on";
+    const mergedCtx = { userId: (_b = this._user) == null ? void 0 : _b.id, email: (_c = this._user) == null ? void 0 : _c.email, ...ctx };
+    const userId = String((_e = (_d = mergedCtx.userId) != null ? _d : mergedCtx.email) != null ? _e : this.visitorId);
+    const bucket = flagBucket(key, userId);
+    let cumulative = 0;
+    for (const variant of flag.variants) {
+      cumulative += variant.weight;
+      if (bucket < cumulative) return variant.key;
+    }
+    return flag.variants[flag.variants.length - 1].key;
+  }
+  /** Immediately flush all queued items (both telemetry and web analytics). */
+  flush() {
+    this.batcher.flush();
+  }
+  /** Stop the flush timer and release all listeners. */
+  shutdown() {
+    this.batcher.stop();
+    this.batcher.flush();
+    this.cleanup.forEach((fn) => fn());
+  }
+  // ── Auto-capture setup ────────────────────────────────────────────────────
+  _setupAutoCapture() {
+    const { autoCapture, environment } = this.cfg;
+    if (autoCapture.errors) {
+      this.cleanup.push(
+        captureGlobalErrors((e) => this.batcher.addError(e), environment)
+      );
+    }
+    if (autoCapture.performance) {
+      captureFCP((t) => this.batcher.addTrace(t), environment);
+      captureLCP((t) => this.batcher.addTrace(t), environment);
+      capturePageLoad((t) => this.batcher.addTrace(t), environment);
+    }
+    if (autoCapture.pageViews) {
+      this._setupPageViewTracking();
+    }
+  }
+  _setupPageViewTracking() {
+    const trackView = () => {
+      setTimeout(() => this.trackWebView(), 0);
+    };
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", trackView, { once: true });
+    } else {
+      setTimeout(() => this.trackWebView(), 0);
+    }
+    const origPush = history.pushState.bind(history);
+    const origReplace = history.replaceState.bind(history);
+    history.pushState = (...args) => {
+      origPush(...args);
+      trackView();
+    };
+    history.replaceState = (...args) => {
+      origReplace(...args);
+    };
+    const onPopState = () => trackView();
+    window.addEventListener("popstate", onPopState);
+    this.cleanup.push(() => {
+      history.pushState = origPush;
+      history.replaceState = origReplace;
+      window.removeEventListener("popstate", onPopState);
+    });
+  }
+  // ── Helpers ───────────────────────────────────────────────────────────────
+  _timezone() {
+    try {
+      return Intl.DateTimeFormat().resolvedOptions().timeZone || void 0;
+    } catch {
+      return void 0;
+    }
+  }
+};
+
+export { Watchup };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map