@customerhero/js 1.0.0 → 1.1.0

package/dist/index.cjs

@@ -29,8 +29,11 @@ __export(index_exports, {
   captureScreenshot: () => captureScreenshot,
   createTranslator: () => createTranslator,
   detectLocale: () => detectLocale,
+  evaluate: () => evaluate,
   isRtlLocale: () => isRtlLocale,
-  resolveLocale: () => resolveLocale
+  pickFire: () => pickFire,
+  resolveLocale: () => resolveLocale,
+  startTriggersRuntime: () => startTriggersRuntime
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -549,6 +552,377 @@ ${line.slice(5).trim()}` : line.slice(5).trim();
   return { event, data };
 }
 
+// src/triggers.ts
+function evaluate(node, ctx) {
+  if (isGroup(node, "all")) {
+    if (node.all.length === 0) return false;
+    return node.all.every((child) => evaluate(child, ctx));
+  }
+  if (isGroup(node, "any")) {
+    if (node.any.length === 0) return false;
+    return node.any.some((child) => evaluate(child, ctx));
+  }
+  return evaluateLeaf(node, ctx);
+}
+function isGroup(node, key) {
+  return !!node && typeof node === "object" && Array.isArray(node[key]);
+}
+function evaluateLeaf(leaf, ctx) {
+  switch (leaf.kind) {
+    case "url_path": {
+      const path = parseUrlPath(ctx.url);
+      switch (leaf.op) {
+        case "equals":
+          return path === leaf.value;
+        case "contains":
+          return path.includes(leaf.value);
+        case "starts_with":
+          return path.startsWith(leaf.value);
+        case "regex":
+          return safeRegex(leaf.value).test(path);
+        default:
+          return false;
+      }
+    }
+    case "url_query": {
+      const has = Object.prototype.hasOwnProperty.call(
+        ctx.queryParams,
+        leaf.key
+      );
+      if (leaf.op === "exists") return has;
+      if (!has) return false;
+      const v = ctx.queryParams[leaf.key] ?? "";
+      if (leaf.op === "equals") return v === (leaf.value ?? "");
+      if (leaf.op === "contains") return v.includes(leaf.value ?? "");
+      return false;
+    }
+    case "referrer": {
+      const r = ctx.referrer;
+      if (leaf.op === "equals") return r === leaf.value;
+      if (leaf.op === "contains") return r.includes(leaf.value);
+      if (leaf.op === "regex") return safeRegex(leaf.value).test(r);
+      return false;
+    }
+    case "time_on_page":
+      return ctx.timeOnPageMs >= leaf.seconds * 1e3;
+    case "scroll_depth":
+      return ctx.scrollPercent >= leaf.percent;
+    case "exit_intent":
+      return ctx.exitIntentSeen;
+    case "device":
+      return ctx.device === leaf.value;
+    case "browser_language": {
+      const lang = (ctx.language || "").toLowerCase();
+      return leaf.values.some((v) => {
+        const target = v.toLowerCase();
+        return lang === target || lang.startsWith(`${target}-`);
+      });
+    }
+    case "visitor_trait": {
+      const has = Object.prototype.hasOwnProperty.call(ctx.traits, leaf.key);
+      if (leaf.op === "exists") return has;
+      if (!has) return false;
+      const v = ctx.traits[leaf.key];
+      if (leaf.op === "equals") return v === leaf.value;
+      if (leaf.op === "gt")
+        return typeof v === "number" && typeof leaf.value === "number" && v > leaf.value;
+      if (leaf.op === "lt")
+        return typeof v === "number" && typeof leaf.value === "number" && v < leaf.value;
+      return false;
+    }
+    case "return_visit": {
+      if (leaf.op === "gte") return ctx.returnVisitCount >= leaf.count;
+      if (leaf.op === "eq") return ctx.returnVisitCount === leaf.count;
+      return false;
+    }
+    default:
+      return false;
+  }
+}
+function parseUrlPath(url) {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return url.split("?")[0] ?? url;
+  }
+}
+function safeRegex(pattern) {
+  try {
+    return new RegExp(pattern);
+  } catch {
+    return /^\b$/;
+  }
+}
+function pickFire(triggers, ctx, firedSet) {
+  const sorted = triggers.slice().sort((a, b) => a.priority - b.priority);
+  for (const t of sorted) {
+    if (t.frequency !== "every_time" && firedSet.has(t.id)) continue;
+    if (evaluate(t.conditions, ctx)) return t;
+  }
+  return null;
+}
+
+// src/triggers-runtime.ts
+var STORAGE_NS = "ch_trigger";
+var RETURN_VISIT_KEY = "ch_visits";
+var SCROLL_THROTTLE_MS = 250;
+var EXIT_INTENT_GRACE_MS = 5e3;
+function getLocalStorage() {
+  try {
+    return typeof window !== "undefined" ? window.localStorage : null;
+  } catch {
+    return null;
+  }
+}
+function getSessionStorage() {
+  try {
+    return typeof window !== "undefined" ? window.sessionStorage : null;
+  } catch {
+    return null;
+  }
+}
+function detectDevice() {
+  if (typeof window === "undefined") return "desktop";
+  const ua = navigator.userAgent || "";
+  if (/iPad|Tablet|PlayBook/i.test(ua)) return "tablet";
+  if (/Mobi|Android|iPhone|iPod/i.test(ua)) return "mobile";
+  if (window.matchMedia?.("(pointer: coarse)").matches && window.innerWidth < 1024) {
+    return window.innerWidth < 600 ? "mobile" : "tablet";
+  }
+  return "desktop";
+}
+function parseQueryParams(url) {
+  const out = {};
+  try {
+    const u = new URL(url);
+    u.searchParams.forEach((v, k) => {
+      out[k] = v;
+    });
+  } catch {
+  }
+  return out;
+}
+function readReturnVisitCount() {
+  const ls = getLocalStorage();
+  if (!ls) return 1;
+  try {
+    const raw = ls.getItem(RETURN_VISIT_KEY);
+    return raw ? Math.max(1, parseInt(raw, 10) || 1) : 1;
+  } catch {
+    return 1;
+  }
+}
+function bumpReturnVisitCount() {
+  const ls = getLocalStorage();
+  const ss = getSessionStorage();
+  if (!ls || !ss) return readReturnVisitCount();
+  try {
+    if (ss.getItem("ch_visit_seen") === "1") return readReturnVisitCount();
+    const current = parseInt(ls.getItem(RETURN_VISIT_KEY) ?? "0", 10) || 0;
+    const next = current + 1;
+    ls.setItem(RETURN_VISIT_KEY, String(next));
+    ss.setItem("ch_visit_seen", "1");
+    return next;
+  } catch {
+    return readReturnVisitCount();
+  }
+}
+function firedKey(chatbotId, triggerId) {
+  return `${STORAGE_NS}_${chatbotId}_${triggerId}_fired`;
+}
+function readFired(chatbotId, triggers) {
+  const ls = getLocalStorage();
+  const ss = getSessionStorage();
+  const out = /* @__PURE__ */ new Set();
+  for (const t of triggers) {
+    if (t.frequency === "every_time") continue;
+    try {
+      const key = firedKey(chatbotId, t.id);
+      if (t.frequency === "once_ever" && ls?.getItem(key) === "1") {
+        out.add(t.id);
+      } else if (t.frequency === "once_per_session" && ss?.getItem(key) === "1") {
+        out.add(t.id);
+      }
+    } catch {
+    }
+  }
+  return out;
+}
+function writeFired(chatbotId, triggerId, frequency) {
+  if (frequency === "every_time") return;
+  const key = firedKey(chatbotId, triggerId);
+  try {
+    if (frequency === "once_ever") {
+      getLocalStorage()?.setItem(key, "1");
+    } else if (frequency === "once_per_session") {
+      getSessionStorage()?.setItem(key, "1");
+    }
+  } catch {
+  }
+}
+function startTriggersRuntime(options) {
+  if (typeof window === "undefined") {
+    return {
+      stop() {
+      },
+      reevaluate() {
+      },
+      setTraits() {
+      },
+      markFired() {
+      }
+    };
+  }
+  const { chatbotId, triggers, onFire, isAllowedToFire } = options;
+  let stopped = false;
+  let exitIntentSeen = false;
+  let scrollPercent = 0;
+  let pageStartedAt = Date.now();
+  let timeOnPageMs = 0;
+  let lastVisibleAt = Date.now();
+  let traits = {
+    ...options.initialTraits ?? {}
+  };
+  const firedThisSession = /* @__PURE__ */ new Set();
+  for (const id of readFired(chatbotId, triggers)) firedThisSession.add(id);
+  const returnVisitCount = bumpReturnVisitCount();
+  function snapshot() {
+    const url = window.location.href;
+    return {
+      url,
+      queryParams: parseQueryParams(url),
+      referrer: document.referrer || "",
+      language: (navigator.language || "en").toLowerCase(),
+      device: detectDevice(),
+      timeOnPageMs,
+      scrollPercent,
+      exitIntentSeen,
+      returnVisitCount,
+      traits
+    };
+  }
+  function evaluate2() {
+    if (stopped) return;
+    if (!isAllowedToFire()) return;
+    if (triggers.length === 0) return;
+    const ctx = snapshot();
+    const trigger = pickFire(triggers, ctx, firedThisSession);
+    if (!trigger) return;
+    firedThisSession.add(trigger.id);
+    writeFired(chatbotId, trigger.id, trigger.frequency);
+    try {
+      onFire(trigger);
+    } catch (err) {
+      console.error("CustomerHero: trigger onFire handler threw", err);
+    }
+  }
+  const timerId = window.setInterval(() => {
+    if (document.hidden) return;
+    const now = Date.now();
+    timeOnPageMs += now - lastVisibleAt;
+    lastVisibleAt = now;
+    evaluate2();
+  }, 1e3);
+  function handleVisibility() {
+    const now = Date.now();
+    if (document.hidden) {
+      timeOnPageMs += now - lastVisibleAt;
+      if (now - pageStartedAt > EXIT_INTENT_GRACE_MS && !exitIntentSeen) {
+        exitIntentSeen = true;
+        evaluate2();
+      }
+    } else {
+      lastVisibleAt = now;
+      evaluate2();
+    }
+  }
+  document.addEventListener("visibilitychange", handleVisibility);
+  let scrollScheduled = false;
+  function handleScroll() {
+    if (scrollScheduled) return;
+    scrollScheduled = true;
+    window.setTimeout(() => {
+      scrollScheduled = false;
+      const doc = document.documentElement;
+      const scrollable = doc.scrollHeight - window.innerHeight;
+      if (scrollable <= 0) {
+        scrollPercent = Math.max(scrollPercent, 100);
+      } else {
+        const next = window.scrollY / scrollable * 100;
+        if (next > scrollPercent) {
+          scrollPercent = next;
+          evaluate2();
+        }
+      }
+    }, SCROLL_THROTTLE_MS);
+  }
+  window.addEventListener("scroll", handleScroll, { passive: true });
+  function handleMouseOut(e) {
+    if (exitIntentSeen) return;
+    if (e.relatedTarget !== null) return;
+    if (e.clientY > 0) return;
+    if (Date.now() - pageStartedAt < EXIT_INTENT_GRACE_MS) return;
+    exitIntentSeen = true;
+    evaluate2();
+  }
+  document.addEventListener("mouseout", handleMouseOut);
+  const origPush = history.pushState;
+  const origReplace = history.replaceState;
+  function onUrlChange() {
+    pageStartedAt = Date.now();
+    timeOnPageMs = 0;
+    lastVisibleAt = Date.now();
+    scrollPercent = 0;
+    exitIntentSeen = false;
+    evaluate2();
+  }
+  history.pushState = function patched(...args) {
+    const ret = origPush.apply(this, args);
+    try {
+      onUrlChange();
+    } catch {
+    }
+    return ret;
+  };
+  history.replaceState = function patched(...args) {
+    const ret = origReplace.apply(
+      this,
+      args
+    );
+    try {
+      onUrlChange();
+    } catch {
+    }
+    return ret;
+  };
+  window.addEventListener("popstate", onUrlChange);
+  const initialEval = window.setTimeout(evaluate2, 0);
+  return {
+    stop() {
+      stopped = true;
+      window.clearInterval(timerId);
+      window.clearTimeout(initialEval);
+      document.removeEventListener("visibilitychange", handleVisibility);
+      window.removeEventListener("scroll", handleScroll);
+      document.removeEventListener("mouseout", handleMouseOut);
+      window.removeEventListener("popstate", onUrlChange);
+      history.pushState = origPush;
+      history.replaceState = origReplace;
+    },
+    reevaluate() {
+      evaluate2();
+    },
+    setTraits(next) {
+      traits = { ...traits, ...next };
+      evaluate2();
+    },
+    markFired(triggerId, frequency) {
+      firedThisSession.add(triggerId);
+      writeFired(chatbotId, triggerId, frequency);
+    }
+  };
+}
+
 // src/client.ts
 function resolveConfig(userConfig, fetched) {
   return {
@@ -603,9 +977,35 @@ var CustomerHeroChat = class {
       error: null,
       identity: null,
       locale,
-      isRtl: isRtlLocale(locale)
+      isRtl: isRtlLocale(locale),
+      triggers: [],
+      preChatForm: null,
+      preChatFormVisible: false,
+      preChatSubmission: null,
+      consent: this.readStoredConsent(),
+      pendingTriggerId: null,
+      pendingPrefill: null
     };
   }
+  // ── Proactive engagement state ─────────────────────────────────────
+  triggersRuntime = null;
+  preChatFormSubmitted = false;
+  readStoredConsent() {
+    try {
+      const raw = this.storage?.getItem("ch_consent");
+      if (!raw) return { analytics: false };
+      const parsed = JSON.parse(raw);
+      return { analytics: parsed.analytics === true };
+    } catch {
+      return { analytics: false };
+    }
+  }
+  writeStoredConsent(consent) {
+    try {
+      this.storage?.setItem("ch_consent", JSON.stringify(consent));
+    } catch {
+    }
+  }
   // Switch the active locale at runtime. No-op when the resolved tag matches
   // the current locale and `stringOverrides` is unchanged. Subscribers get a
   // single state notification with the new `locale` / `isRtl`.
@@ -661,8 +1061,16 @@ var CustomerHeroChat = class {
       }
       const fetched = await response.json();
       const resolved = resolveConfig(this.userConfig, fetched);
-      this.setState({ config: resolved, configLoaded: true });
+      const triggers = Array.isArray(fetched.triggers) ? fetched.triggers : [];
+      const preChatForm = fetched.preChatForm ?? null;
+      this.setState({
+        config: resolved,
+        configLoaded: true,
+        triggers,
+        preChatForm
+      });
       if (resolved.stringOverrides) this.rebuildTranslator();
+      this.startTriggersRuntimeIfPossible();
     } catch (error) {
       const errorMsg = error instanceof Error ? error.message : "Failed to load widget config";
       console.error("CustomerHero: Failed to fetch widget config", error);
@@ -720,6 +1128,14 @@ var CustomerHeroChat = class {
     const trimmed = message.trim();
     const attachmentTokens = options?.attachmentTokens ?? [];
     if (!trimmed || this.state.isLoading) return;
+    if (this.shouldShowPreChatForm()) {
+      this.pendingMessageAfterPreChat = {
+        message: trimmed,
+        attachmentTokens
+      };
+      this.setState({ preChatFormVisible: true });
+      return;
+    }
     const userMsg = {
       role: "user",
       content: trimmed,
@@ -752,7 +1168,13 @@ var CustomerHeroChat = class {
           message: trimmed,
           ...this.state.conversationId ? { conversationId: this.state.conversationId } : {},
           ...this.identityData ? { identity: this.identityData } : {},
-          ...attachmentTokens.length > 0 ? { attachmentTokens } : {}
+          ...attachmentTokens.length > 0 ? { attachmentTokens } : {},
+          // Trigger attribution + pre-chat submission only land on the very
+          // first turn. We only consume them when there's no conversationId
+          // yet — the server ignores them on subsequent turns anyway, but
+          // sending them again would be misleading.
+          ...!this.state.conversationId && this.state.pendingTriggerId ? { triggeredByTriggerId: this.state.pendingTriggerId } : {},
+          ...!this.state.conversationId && this.state.preChatSubmission ? { prechatSubmission: this.state.preChatSubmission } : {}
         })
       });
       if (!response.ok) {
@@ -774,7 +1196,11 @@ var CustomerHeroChat = class {
                 `ch_conv_${chatbotId}`,
                 meta.conversationId
               );
-              this.setState({ conversationId: meta.conversationId });
+              this.setState({
+                conversationId: meta.conversationId,
+                pendingTriggerId: null,
+                preChatSubmission: null
+              });
             }
             this.patchMessageAt(userMsgIndex, { status: "sent" });
             if (meta?.messageId) {
@@ -1047,6 +1473,119 @@ var CustomerHeroChat = class {
       error: null
     });
   }
+  // ── Proactive engagement public API ────────────────────────────────
+  /** Update visitor consent. Until `analytics: true` is set, only direct
+   *  launcher clicks fire — URL/time/scroll/exit-intent/trait conditions
+   *  stay dormant. The setting is persisted in localStorage so revisits
+   *  don't re-prompt. */
+  setConsent(consent) {
+    const next = {
+      analytics: typeof consent.analytics === "boolean" ? consent.analytics : this.state.consent.analytics
+    };
+    this.writeStoredConsent(next);
+    this.setState({ consent: next });
+    this.triggersRuntime?.reevaluate();
+  }
+  /** Set or update visitor traits used by trait-based conditions. The trait
+   *  values are kept in memory (not persisted) so the integrator decides
+   *  the source of truth. */
+  setTraits(traits) {
+    this.triggersRuntime?.setTraits(traits);
+  }
+  /** Submit pre-chat form answers. Synthesizes a customer record server-side
+   *  on the next sendMessage. Resumes any pending message that was deferred
+   *  while the form was open. */
+  async submitPreChatForm(submission) {
+    this.preChatFormSubmitted = true;
+    this.setState({
+      preChatSubmission: submission,
+      preChatFormVisible: false
+    });
+    const pending = this.pendingMessageAfterPreChat;
+    this.pendingMessageAfterPreChat = null;
+    if (pending) {
+      await this.sendMessage(pending.message, {
+        attachmentTokens: pending.attachmentTokens
+      });
+    }
+  }
+  /** Dismiss the pre-chat form without submitting. The form will reappear
+   *  on the next sendMessage attempt — call `setConsent` to acknowledge a
+   *  refusal, or `reset()` to clear pending state. */
+  cancelPreChatForm() {
+    this.pendingMessageAfterPreChat = null;
+    this.setState({ preChatFormVisible: false });
+  }
+  /** Programmatically dispatch the action attached to a trigger. Used by
+   *  integrators who want to act on a custom button, e.g. an exit-intent
+   *  modal in their own UI. */
+  fireTrigger(triggerId) {
+    const trigger = this.state.triggers.find((t) => t.id === triggerId);
+    if (!trigger) return;
+    this.triggersRuntime?.markFired(trigger.id, trigger.frequency);
+    this.handleTriggerAction(trigger);
+  }
+  // ── Internals ──────────────────────────────────────────────────────
+  pendingMessageAfterPreChat = null;
+  shouldShowPreChatForm() {
+    const form = this.state.preChatForm;
+    if (!form) return false;
+    if (this.preChatFormSubmitted) return false;
+    if (this.state.conversationId) return false;
+    if (form.skipForIdentified && this.identityData?.userId) return false;
+    return true;
+  }
+  startTriggersRuntimeIfPossible() {
+    if (this.triggersRuntime) return;
+    if (this.state.triggers.length === 0) return;
+    this.triggersRuntime = startTriggersRuntime({
+      chatbotId: this.state.config.chatbotId,
+      triggers: this.state.triggers,
+      isAllowedToFire: () => this.state.consent.analytics,
+      onFire: (trigger) => this.handleTriggerAction(trigger)
+    });
+  }
+  handleTriggerAction(trigger) {
+    this.setState({ pendingTriggerId: trigger.id });
+    const action = trigger.action;
+    switch (action.kind) {
+      case "open_widget":
+        this.open();
+        break;
+      case "open_with_prefill":
+        this.open();
+        this.setState({ pendingPrefill: action.prefill });
+        break;
+      case "show_form":
+        this.open();
+        if (this.state.preChatForm) {
+          this.setState({ preChatFormVisible: true });
+        }
+        break;
+      case "send_message":
+        this.open();
+        if (this.state.messages.length === 0) {
+          this.setState({
+            messages: [{ role: "bot", content: action.message }]
+          });
+        }
+        break;
+    }
+  }
+  /** Read and clear the pending prefill (set by an `open_with_prefill`
+   *  trigger). The host calls this once when mounting the input and seeds
+   *  its controlled value with the result. */
+  consumePendingPrefill() {
+    const prefill = this.state.pendingPrefill;
+    if (prefill !== null) this.setState({ pendingPrefill: null });
+    return prefill;
+  }
+  /** Stop the triggers runtime and detach listeners. Safe to call multiple
+   *  times; safe to call before the runtime started. */
+  destroy() {
+    this.triggersRuntime?.stop();
+    this.triggersRuntime = null;
+  }
   identify(payload) {
     const { userId, email, name, phone, company, userHash, ...rest } = payload;
     const customProperties = {};
@@ -1089,9 +1628,7 @@ function stripSuggestions(message) {
 }
 function stripActionConfirmationBlocks(message) {
   if (!message.blocks?.length) return message;
-  const blocks = message.blocks.filter(
-    (b) => b.type !== "action_confirmation"
-  );
+  const blocks = message.blocks.filter((b) => b.type !== "action_confirmation");
   if (blocks.length === message.blocks.length) return message;
   if (blocks.length === 0) {
     const { blocks: _b, ...rest } = message;
@@ -1255,6 +1792,9 @@ async function canvasToBlob(canvas, quality) {
   captureScreenshot,
   createTranslator,
   detectLocale,
+  evaluate,
   isRtlLocale,
-  resolveLocale
+  pickFire,
+  resolveLocale,
+  startTriggersRuntime
 });