@cstar.help/js 0.9.0 → 0.10.1

package/dist/proactive/index.cjs

@@ -0,0 +1,481 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/proactive/index.ts
+var proactive_exports = {};
+__export(proactive_exports, {
+  ProactiveClient: () => ProactiveClient
+});
+module.exports = __toCommonJS(proactive_exports);
+var DEFAULT_BASE_URL = "https://www.cstar.help";
+function createRageClickDetector(onSignal) {
+  let clicks = [];
+  let lastFired = 0;
+  let handler = null;
+  return {
+    start() {
+      handler = (e) => {
+        const now = Date.now();
+        clicks = clicks.filter((c) => now - c.t < 500);
+        clicks.push({ x: e.clientX, y: e.clientY, t: now });
+        if (clicks.length >= 3 && now - lastFired > 2e3) {
+          const first = clicks[0];
+          const allClose = clicks.every((c) => {
+            const dx = first.x - c.x;
+            const dy = first.y - c.y;
+            return Math.sqrt(dx * dx + dy * dy) <= 50;
+          });
+          if (allClose) {
+            lastFired = now;
+            const el = e.target;
+            let context = el?.tagName ? "on " + el.tagName.toLowerCase() : "";
+            if (el?.className && typeof el.className === "string") {
+              const cls = el.className.split(" ")[0];
+              if (cls) context += "." + cls;
+            }
+            onSignal({
+              type: "rage_click",
+              confidence: Math.min(1, clicks.length / 5),
+              context: `Clicked ${clicks.length} times rapidly ${context}`,
+              timestamp: now
+            });
+            clicks = [];
+          }
+        }
+      };
+      document.addEventListener("click", handler, true);
+    },
+    stop() {
+      if (handler) document.removeEventListener("click", handler, true);
+      handler = null;
+      clicks = [];
+    }
+  };
+}
+function createExitIntentDetector(onSignal) {
+  let fired = false;
+  let handler = null;
+  return {
+    start() {
+      if (navigator.maxTouchPoints > 0) return;
+      handler = (e) => {
+        if (fired || e.clientY > 0 || e.relatedTarget) return;
+        fired = true;
+        onSignal({
+          type: "exit_intent",
+          confidence: 0.7,
+          context: "Mouse left viewport at top",
+          timestamp: Date.now()
+        });
+      };
+      document.addEventListener("mouseout", handler);
+    },
+    stop() {
+      if (handler) document.removeEventListener("mouseout", handler);
+      handler = null;
+    }
+  };
+}
+function createIdleDetector(onSignal, timeoutSeconds) {
+  let timer = null;
+  let fired = false;
+  let activityHandler = null;
+  const events = ["mousemove", "keydown", "scroll", "touchstart"];
+  function resetTimer() {
+    fired = false;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      if (!fired) {
+        fired = true;
+        onSignal({
+          type: "idle",
+          confidence: 0.6,
+          context: `Idle for ${timeoutSeconds} seconds`,
+          timestamp: Date.now()
+        });
+      }
+    }, timeoutSeconds * 1e3);
+  }
+  return {
+    start() {
+      if (!timeoutSeconds || timeoutSeconds <= 0) return;
+      activityHandler = resetTimer;
+      events.forEach((evt) => document.addEventListener(evt, activityHandler, { passive: true }));
+      resetTimer();
+    },
+    stop() {
+      if (timer) clearTimeout(timer);
+      timer = null;
+      if (activityHandler) {
+        events.forEach((evt) => document.removeEventListener(evt, activityHandler));
+        activityHandler = null;
+      }
+    }
+  };
+}
+function createErrorLoopDetector(onSignal) {
+  let errors = [];
+  let lastFired = 0;
+  let errorHandler = null;
+  let rejectionHandler = null;
+  function recordError(message) {
+    const now = Date.now();
+    errors = errors.filter((e) => now - e.t < 1e4);
+    errors.push({ msg: message, t: now });
+    if (errors.length >= 3 && now - lastFired > 15e3) {
+      lastFired = now;
+      const unique = new Set(errors.map((e) => e.msg));
+      onSignal({
+        type: "error_loop",
+        confidence: Math.min(1, errors.length / 5),
+        context: `${errors.length} errors in 10s (${unique.size} unique)`,
+        timestamp: now
+      });
+      errors = [];
+    }
+  }
+  return {
+    start() {
+      errorHandler = (e) => recordError(e.message || "Unknown error");
+      rejectionHandler = (e) => recordError(e.reason?.message || String(e.reason) || "Unhandled rejection");
+      window.addEventListener("error", errorHandler);
+      window.addEventListener("unhandledrejection", rejectionHandler);
+    },
+    stop() {
+      if (errorHandler) window.removeEventListener("error", errorHandler);
+      if (rejectionHandler) window.removeEventListener("unhandledrejection", rejectionHandler);
+      errorHandler = null;
+      rejectionHandler = null;
+      errors = [];
+    }
+  };
+}
+function createFormAbandonmentDetector(onSignal) {
+  const fields = /* @__PURE__ */ new Set();
+  let idleTimer = null;
+  let fired = false;
+  let focusHandler = null;
+  let inputHandler = null;
+  function isFormField(el) {
+    const tag = el.tagName.toLowerCase();
+    if (tag !== "input" && tag !== "textarea" && tag !== "select") return false;
+    const input = el;
+    if (input.type === "search" || el.getAttribute("role") === "searchbox") return false;
+    const name = (input.name || "").toLowerCase();
+    return name !== "search" && name !== "q" && name !== "query";
+  }
+  function resetIdleTimer() {
+    if (idleTimer) clearTimeout(idleTimer);
+    if (fields.size >= 2 && !fired) {
+      idleTimer = setTimeout(() => {
+        fired = true;
+        onSignal({
+          type: "form_abandonment",
+          confidence: 0.65,
+          context: `Interacted with ${fields.size} form fields then went idle`,
+          timestamp: Date.now()
+        });
+      }, 3e4);
+    }
+  }
+  return {
+    start() {
+      focusHandler = (e) => {
+        if (e.target && isFormField(e.target)) {
+          fields.add(e.target);
+          resetIdleTimer();
+        }
+      };
+      inputHandler = () => {
+        if (fields.size >= 1) resetIdleTimer();
+      };
+      document.addEventListener("focusin", focusHandler);
+      document.addEventListener("input", inputHandler);
+    },
+    stop() {
+      if (idleTimer) clearTimeout(idleTimer);
+      if (focusHandler) document.removeEventListener("focusin", focusHandler);
+      if (inputHandler) document.removeEventListener("input", inputHandler);
+      focusHandler = null;
+      inputHandler = null;
+      fields.clear();
+      fired = false;
+    }
+  };
+}
+function createScrollThrashDetector(onSignal) {
+  let reversals = [];
+  let lastScrollY = -1;
+  let lastDirection = 0;
+  let lastFired = 0;
+  let handler = null;
+  return {
+    start() {
+      handler = () => {
+        const now = Date.now();
+        const currentY = window.scrollY;
+        if (lastScrollY < 0) {
+          lastScrollY = currentY;
+          return;
+        }
+        const diff = currentY - lastScrollY;
+        if (Math.abs(diff) < 5) return;
+        const direction = diff > 0 ? 1 : -1;
+        if (lastDirection !== 0 && direction !== lastDirection) {
+          reversals = reversals.filter((t) => now - t < 3e3);
+          reversals.push(now);
+          if (reversals.length >= 5 && now - lastFired > 5e3) {
+            lastFired = now;
+            onSignal({
+              type: "scroll_thrash",
+              confidence: Math.min(1, reversals.length / 8),
+              context: `${reversals.length} scroll direction changes in 3s`,
+              timestamp: now
+            });
+            reversals = [];
+          }
+        }
+        lastDirection = direction;
+        lastScrollY = currentY;
+      };
+      window.addEventListener("scroll", handler, { passive: true });
+    },
+    stop() {
+      if (handler) window.removeEventListener("scroll", handler);
+      handler = null;
+      reversals = [];
+      lastScrollY = -1;
+      lastDirection = 0;
+    }
+  };
+}
+var TriggerEngine = class {
+  constructor(config, onTrigger, isOpen, baseUrl, teamId) {
+    this.sessionCount = 0;
+    this.lastTriggerTime = 0;
+    this.dismissCount = 0;
+    this.shownAt = 0;
+    this.cooldownSeconds = config.cooldownSeconds;
+    this.maxPerSession = config.maxPerSession;
+    this.dismissBehavior = config.dismissBehavior;
+    this.message = config.message;
+    this.onTrigger = onTrigger;
+    this.isOpen = isOpen;
+    this.baseUrl = baseUrl;
+    this.teamId = teamId;
+  }
+  getEffectiveCooldown() {
+    if (this.dismissBehavior === "backoff" && this.dismissCount > 0) {
+      return this.cooldownSeconds * Math.pow(2, this.dismissCount);
+    }
+    return this.cooldownSeconds;
+  }
+  /**
+   * Send analytics beacon (fire-and-forget).
+   * Uses text/plain Content-Type to avoid CORS preflight for cross-origin beacons.
+   * Falls back to fetch() if sendBeacon is unavailable or fails.
+   */
+  sendEvent(eventType, signalType, metadata) {
+    const url = this.baseUrl + "/api/widget/proactive-events";
+    const payload = JSON.stringify({
+      teamId: this.teamId,
+      eventType,
+      signalType,
+      metadata: metadata || {}
+    });
+    try {
+      const queued = navigator.sendBeacon?.(url, new Blob([payload], { type: "text/plain" }));
+      if (!queued) throw void 0;
+    } catch {
+      try {
+        fetch(url, {
+          method: "POST",
+          body: payload,
+          headers: { "Content-Type": "text/plain" },
+          keepalive: true,
+          mode: "cors"
+        }).catch(() => {
+        });
+      } catch {
+      }
+    }
+  }
+  handleSignal(signal) {
+    if (this.isOpen()) return;
+    if (this.sessionCount >= this.maxPerSession) return;
+    if (this.lastTriggerTime > 0) {
+      const elapsed = (Date.now() - this.lastTriggerTime) / 1e3;
+      if (elapsed < this.getEffectiveCooldown()) return;
+    }
+    if (this.dismissBehavior === "stop" && this.dismissCount > 0) return;
+    this.sessionCount++;
+    this.lastTriggerTime = Date.now();
+    this.shownAt = Date.now();
+    this.sendEvent("trigger_fired", signal.type);
+    this.onTrigger({
+      message: this.message,
+      signalType: signal.type,
+      confidence: signal.confidence,
+      context: signal.context
+    });
+  }
+  onEngage(signalType) {
+    const timeToEngage = Date.now() - (this.shownAt || Date.now());
+    this.sendEvent("engaged", signalType || "unknown", { timeToEngage });
+    this.shownAt = 0;
+  }
+  onDismiss(signalType) {
+    this.dismissCount++;
+    if (this.dismissBehavior === "stop") {
+      this.sessionCount = this.maxPerSession;
+    }
+    this.sendEvent("dismissed", signalType || "unknown");
+    this.shownAt = 0;
+  }
+  onAutoDismiss(signalType) {
+    this.sendEvent("auto_dismissed", signalType || "unknown");
+    this.shownAt = 0;
+  }
+};
+var ProactiveClient = class {
+  constructor(config) {
+    this.listeners = /* @__PURE__ */ new Map();
+    this.detectors = [];
+    this.triggerEngine = null;
+    this.serverConfig = null;
+    this._isOpen = false;
+    this._destroyed = false;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.teamSlug = config.teamSlug;
+    this.init();
+  }
+  // ============ EVENTS ============
+  /**
+   * Listen for proactive events.
+   *
+   * ```typescript
+   * proactive.on('trigger', (e) => showNudge(e.message));
+   * proactive.on('signal', (e) => console.log('Raw signal:', e.type));
+   * ```
+   */
+  on(event, callback) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(callback);
+    return () => {
+      this.listeners.get(event)?.delete(callback);
+    };
+  }
+  /** Remove an event listener */
+  off(event, callback) {
+    this.listeners.get(event)?.delete(callback);
+  }
+  emit(event, data) {
+    this.listeners.get(event)?.forEach((cb) => {
+      try {
+        cb(data);
+      } catch {
+      }
+    });
+  }
+  // ============ USER ACTIONS ============
+  /**
+   * Call when the user engages with your proactive nudge (clicks CTA, opens chat).
+   * Reports analytics and clears internal state.
+   */
+  engage(signalType) {
+    this.triggerEngine?.onEngage(signalType);
+  }
+  /**
+   * Call when the user explicitly dismisses your nudge (clicks X).
+   * Applies backoff or stop behavior based on config.
+   */
+  dismiss(signalType) {
+    this.triggerEngine?.onDismiss(signalType);
+  }
+  /**
+   * Call when your nudge auto-hides (timeout, not user action).
+   * Does NOT count against the session cap.
+   */
+  autoDismiss(signalType) {
+    this.triggerEngine?.onAutoDismiss(signalType);
+  }
+  /**
+   * Tell the client whether the chat is currently open.
+   * Triggers won't fire while the chat is open.
+   */
+  setOpen(isOpen) {
+    this._isOpen = isOpen;
+  }
+  /** Stop all detection and clean up */
+  destroy() {
+    this._destroyed = true;
+    this.detectors.forEach((d) => d.stop());
+    this.detectors = [];
+    this.listeners.clear();
+    this.triggerEngine = null;
+  }
+  // ============ INTERNAL ============
+  async init() {
+    try {
+      const res = await fetch(
+        `${this.baseUrl}/widget/api/config?team=${encodeURIComponent(this.teamSlug)}`
+      );
+      if (!res.ok) throw new Error(`Config fetch failed: ${res.status}`);
+      const config = await res.json();
+      if (!config.proactive?.enabled) {
+        this.emit("error", { message: "Proactive triggers are not enabled for this team" });
+        return;
+      }
+      if (this._destroyed) return;
+      this.serverConfig = config.proactive;
+      const teamId = config.teamId;
+      this.triggerEngine = new TriggerEngine(
+        this.serverConfig,
+        (event) => this.emit("trigger", event),
+        () => this._isOpen,
+        this.baseUrl,
+        teamId
+      );
+      const signals = this.serverConfig.signals;
+      const onSignal = (signal) => {
+        this.emit("signal", signal);
+        this.triggerEngine?.handleSignal(signal);
+      };
+      if (signals.rageClick) this.detectors.push(createRageClickDetector(onSignal));
+      if (signals.exitIntent) this.detectors.push(createExitIntentDetector(onSignal));
+      if (signals.idleTimeout > 0)
+        this.detectors.push(createIdleDetector(onSignal, signals.idleTimeout));
+      if (signals.errorLoop) this.detectors.push(createErrorLoopDetector(onSignal));
+      if (signals.formAbandonment) this.detectors.push(createFormAbandonmentDetector(onSignal));
+      if (signals.scrollThrash) this.detectors.push(createScrollThrashDetector(onSignal));
+      this.detectors.forEach((d) => d.start());
+      this.emit("ready", void 0);
+    } catch (err) {
+      this.emit("error", {
+        message: err instanceof Error ? err.message : "Failed to initialize proactive detection"
+      });
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ProactiveClient
+});

package/dist/proactive/index.d.cts

@@ -0,0 +1,134 @@
+/**
+ * Proactive Widget Types
+ *
+ * Types for the ProactiveClient — signal detection and trigger events
+ * for SDK users who build their own nudge UI.
+ */
+interface ProactiveConfig {
+    /** Team slug (e.g., 'acme') */
+    teamSlug: string;
+    /** Base URL for the cStar API (default: https://www.cstar.help) */
+    baseUrl?: string;
+}
+interface ProactiveSignals {
+    rageClick: boolean;
+    exitIntent: boolean;
+    idleTimeout: number;
+    errorLoop: boolean;
+    formAbandonment: boolean;
+    scrollThrash: boolean;
+}
+interface ProactiveServerConfig {
+    enabled: boolean;
+    signals: ProactiveSignals;
+    message: string;
+    cooldownSeconds: number;
+    maxPerSession: number;
+    displayMode: 'bubble' | 'auto_open';
+    dismissBehavior: 'backoff' | 'stop';
+}
+interface ProactiveSignalEvent {
+    /** Signal type identifier */
+    type: 'rage_click' | 'exit_intent' | 'idle' | 'error_loop' | 'form_abandonment' | 'scroll_thrash';
+    /** Confidence score from 0-1 */
+    confidence: number;
+    /** Human-readable context (e.g., "Clicked 5 times rapidly on .pricing-table") */
+    context: string;
+    /** When the signal was detected */
+    timestamp: number;
+}
+interface ProactiveTriggerEvent {
+    /** The configured nudge message (e.g., "Having trouble? We can help!") */
+    message: string;
+    /** Which signal caused the trigger */
+    signalType: string;
+    /** Confidence score from the signal */
+    confidence: number;
+    /** Human-readable signal context */
+    context: string;
+}
+type ProactiveEventMap = {
+    /** Fires when a trigger passes cooldown/cap checks — show your nudge UI */
+    trigger: ProactiveTriggerEvent;
+    /** Fires for every raw signal before filtering — for custom trigger logic */
+    signal: ProactiveSignalEvent;
+    /** Fires when the client connects and starts detecting */
+    ready: void;
+    /** Fires if config fetch fails or proactive is disabled for this team */
+    error: {
+        message: string;
+    };
+};
+type ProactiveEventType = keyof ProactiveEventMap;
+type ProactiveEventCallback<T extends ProactiveEventType> = (event: ProactiveEventMap[T]) => void;
+
+/**
+ * ProactiveClient — Signal Detection for Custom UIs
+ *
+ * Detects frustration signals (rage clicks, exit intent, idle timeout, etc.)
+ * on the customer's page and fires events so SDK users can build their own
+ * nudge UI. Config is fetched from the team's dashboard settings.
+ *
+ * ```typescript
+ * import { ProactiveClient } from '@cstar.help/js/proactive';
+ *
+ * const proactive = new ProactiveClient({ teamSlug: 'acme' });
+ *
+ * proactive.on('trigger', (e) => {
+ *   showNudge(e.message); // "Having trouble? We can help!"
+ * });
+ *
+ * // After showing your nudge, report what happened:
+ * proactive.engage();  // user opened chat
+ * proactive.dismiss(); // user closed nudge
+ * ```
+ */
+
+declare class ProactiveClient {
+    private readonly baseUrl;
+    private readonly teamSlug;
+    private listeners;
+    private detectors;
+    private triggerEngine;
+    private serverConfig;
+    private _isOpen;
+    private _destroyed;
+    constructor(config: ProactiveConfig);
+    /**
+     * Listen for proactive events.
+     *
+     * ```typescript
+     * proactive.on('trigger', (e) => showNudge(e.message));
+     * proactive.on('signal', (e) => console.log('Raw signal:', e.type));
+     * ```
+     */
+    on<T extends ProactiveEventType>(event: T, callback: ProactiveEventCallback<T>): () => void;
+    /** Remove an event listener */
+    off<T extends ProactiveEventType>(event: T, callback: ProactiveEventCallback<T>): void;
+    private emit;
+    /**
+     * Call when the user engages with your proactive nudge (clicks CTA, opens chat).
+     * Reports analytics and clears internal state.
+     */
+    engage(signalType?: string): void;
+    /**
+     * Call when the user explicitly dismisses your nudge (clicks X).
+     * Applies backoff or stop behavior based on config.
+     */
+    dismiss(signalType?: string): void;
+    /**
+     * Call when your nudge auto-hides (timeout, not user action).
+     * Does NOT count against the session cap.
+     */
+    autoDismiss(signalType?: string): void;
+    /**
+     * Tell the client whether the chat is currently open.
+     * Triggers won't fire while the chat is open.
+     */
+    setOpen(isOpen: boolean): void;
+    /** Stop all detection and clean up */
+    destroy(): void;
+    private init;
+}
+
+export { ProactiveClient, type ProactiveConfig, type ProactiveEventCallback, type ProactiveEventMap, type ProactiveEventType, type ProactiveServerConfig, type ProactiveSignalEvent, type ProactiveTriggerEvent };