@guidelytech/sdk-core 0.9.0 → 0.10.0

package/dist/index.d.cts

@@ -4,14 +4,15 @@ export { AppSnapshot, AutocaptureSettings, ExceptionProperties, GuideConfig, Gui
 import { FlagsClient, JsonValue, FlagValue, FlagDetails } from '@guidelytech/flags';
 export { Attributes, EvaluationResult, FlagDetails, FlagsBootstrap, FlagsClient, FlagsClientOptions, FlagsPayload, JsonValue } from '@guidelytech/flags';
 import { MessengerTab } from '@guidelytech/guide-runtime/messenger';
-import { k as GuidelyOptions, c as GuidelyAccount, a as ConsentState, C as ChecklistProgressState, l as GuidelyEvents, e as GuidelyUser, G as GuideLocalState, S as SessionState } from './types-zM5e3loY.cjs';
-export { E as EventQueue, b as EventQueueOptions, m as GuideStepInfo, d as GuidelyEnvironment, n as GuidelyEventName, P as PersistedState, f as areMutuallyExclusive, i as isExclusiveGuide, h as isFrequencyEligible, j as isWithinSchedule } from './types-zM5e3loY.cjs';
-export { K as KEYS, b as KeyValueStore, S as StorageKind, d as createStorage } from './http-47tiAlOM.cjs';
-export { C as CaptureMarker, a as CaptureOutgoingMessage } from './capture-C3faAYb7.cjs';
+import { k as GuidelyOptions, c as GuidelyAccount, a as ConsentState, C as ChecklistProgressState, l as GuidelyEvents, e as GuidelyUser, G as GuideLocalState, S as SessionState } from './types-B5ecgHUV.cjs';
+export { E as EventQueue, b as EventQueueOptions, m as GuideStepInfo, d as GuidelyEnvironment, n as GuidelyEventName, P as PersistedState, f as areMutuallyExclusive, i as isExclusiveGuide, h as isFrequencyEligible, j as isWithinSchedule } from './types-B5ecgHUV.cjs';
+export { a as KEYS, K as KeyValueStore, c as StorageKind, d as createStorage } from './health-DFHUstWd.cjs';
+export { C as CaptureMarker, a as CaptureOutgoingMessage } from './capture-DVJyQ2JZ.cjs';
 export { CAPTURE_PARAM } from '@guidelytech/shared/runtime';
+import './http-D0dCcpLN.cjs';
 
 declare const SDK_NAME = "@guidelytech/sdk-core";
-declare const SDK_VERSION = "0.9.0";
+declare const SDK_VERSION = "0.10.0";
 declare const DEFAULT_API_URL = "https://api.guidely.app";
 /**
  * Framework-independent Guidely client. Create one per page with {@link createGuidely} or
@@ -24,6 +25,8 @@ declare class GuidelyClient {
     private readonly sessionStore;
     private readonly emitter;
     private readonly queue;
+    /** Survey answers and guide/checklist progress, kept until the server accepts them. */
+    private readonly outbox;
     private config;
     private etag;
     private anonymousId;
@@ -85,6 +88,8 @@ declare class GuidelyClient {
     private wireErrorListeners;
     /** Re-fetches the published config and re-evaluates triggers. */
     refresh(): Promise<void>;
+    /** Re-renders after a config change (refresh, or a config that arrived after start). */
+    private applyConfigChange;
     /** Tears everything down: guides, widgets, listeners, timers, host element. Re-init is allowed via a new client. */
     destroy(): void;
     /** Identifies the end user and loads server-held state (audiences, guide history, checklist progress). */

package/dist/index.d.ts

@@ -4,14 +4,15 @@ export { AppSnapshot, AutocaptureSettings, ExceptionProperties, GuideConfig, Gui
 import { FlagsClient, JsonValue, FlagValue, FlagDetails } from '@guidelytech/flags';
 export { Attributes, EvaluationResult, FlagDetails, FlagsBootstrap, FlagsClient, FlagsClientOptions, FlagsPayload, JsonValue } from '@guidelytech/flags';
 import { MessengerTab } from '@guidelytech/guide-runtime/messenger';
-import { k as GuidelyOptions, c as GuidelyAccount, a as ConsentState, C as ChecklistProgressState, l as GuidelyEvents, e as GuidelyUser, G as GuideLocalState, S as SessionState } from './types-DnJW_4ck.js';
-export { E as EventQueue, b as EventQueueOptions, m as GuideStepInfo, d as GuidelyEnvironment, n as GuidelyEventName, P as PersistedState, f as areMutuallyExclusive, i as isExclusiveGuide, h as isFrequencyEligible, j as isWithinSchedule } from './types-DnJW_4ck.js';
-export { K as KEYS, b as KeyValueStore, S as StorageKind, d as createStorage } from './http-47tiAlOM.js';
-export { C as CaptureMarker, a as CaptureOutgoingMessage } from './capture-Dqd7up2n.js';
+import { k as GuidelyOptions, c as GuidelyAccount, a as ConsentState, C as ChecklistProgressState, l as GuidelyEvents, e as GuidelyUser, G as GuideLocalState, S as SessionState } from './types-BtPovimB.js';
+export { E as EventQueue, b as EventQueueOptions, m as GuideStepInfo, d as GuidelyEnvironment, n as GuidelyEventName, P as PersistedState, f as areMutuallyExclusive, i as isExclusiveGuide, h as isFrequencyEligible, j as isWithinSchedule } from './types-BtPovimB.js';
+export { a as KEYS, K as KeyValueStore, c as StorageKind, d as createStorage } from './health-DFHUstWd.js';
+export { C as CaptureMarker, a as CaptureOutgoingMessage } from './capture-369s4YYT.js';
 export { CAPTURE_PARAM } from '@guidelytech/shared/runtime';
+import './http-DJd8jRhK.js';
 
 declare const SDK_NAME = "@guidelytech/sdk-core";
-declare const SDK_VERSION = "0.9.0";
+declare const SDK_VERSION = "0.10.0";
 declare const DEFAULT_API_URL = "https://api.guidely.app";
 /**
  * Framework-independent Guidely client. Create one per page with {@link createGuidely} or
@@ -24,6 +25,8 @@ declare class GuidelyClient {
     private readonly sessionStore;
     private readonly emitter;
     private readonly queue;
+    /** Survey answers and guide/checklist progress, kept until the server accepts them. */
+    private readonly outbox;
     private config;
     private etag;
     private anonymousId;
@@ -85,6 +88,8 @@ declare class GuidelyClient {
     private wireErrorListeners;
     /** Re-fetches the published config and re-evaluates triggers. */
     refresh(): Promise<void>;
+    /** Re-renders after a config change (refresh, or a config that arrived after start). */
+    private applyConfigChange;
     /** Tears everything down: guides, widgets, listeners, timers, host element. Re-init is allowed via a new client. */
     destroy(): void;
     /** Identifies the end user and loads server-held state (audiences, guide history, checklist progress). */

package/dist/index.js

@@ -1,27 +1,28 @@
 import {
   Emitter,
   EventQueue,
+  Outbox,
   areMutuallyExclusive,
   dismissedAfterMerge,
   isExclusiveGuide,
   isFrequencyEligible,
   isWithinSchedule
-} from "./chunk-544KSOC3.js";
+} from "./chunk-GDJB466J.js";
 import {
+  Api,
   KEYS,
+  __publicField,
   createStorage,
+  postWithRetry,
   readJson,
   writeJson
-} from "./chunk-CYAG6ZYX.js";
-import {
-  Api,
-  __publicField,
-  postWithRetry
-} from "./chunk-AKNE7D5M.js";
+} from "./chunk-C4WWSF67.js";
 
 // src/client.ts
 import { evaluateRules, randomId, rolloutBucket, sanitizeProperties, supportsPlatform } from "@guidelytech/shared/runtime";
 import {
+  closestComposed as closestComposed3,
+  composedTarget,
   destroyHost,
   isChecklistComplete,
   renderChecklist,
@@ -35,7 +36,7 @@ import { createScope } from "@guidelytech/guide-runtime";
 import { createFlagsClient } from "@guidelytech/flags";
 
 // src/authoring.ts
-import { highlightSelectors, previewStep, runGuide, startAuthoring } from "@guidelytech/guide-runtime";
+import { closestComposed, highlightSelectors, previewStep, runGuide, startAuthoring } from "@guidelytech/guide-runtime";
 
 // src/snapshot.ts
 var MAX_SNAPSHOT_BYTES = 6 * 1024 * 1024;
@@ -199,7 +200,7 @@ var AuthoringBridge = class {
   masked(el) {
     return this.opts.maskSelectors.some((sel) => {
       try {
-        return !!el.closest(sel);
+        return !!closestComposed(el, sel);
       } catch {
         return false;
       }
@@ -380,7 +381,7 @@ function takeCaptureToken(sessionStore) {
 var loadCapture = async () => (await import("./capture.js")).capture;
 
 // src/autocapture.ts
-import { isGuidelyElement, isStableId } from "@guidelytech/guide-runtime";
+import { closestComposed as closestComposed2, isGuidelyElement, isStableId, SHADOW_SEPARATOR, shadowHostChain } from "@guidelytech/guide-runtime";
 var INTERACTIVE_SELECTOR = "a,button,input[type=button],input[type=submit],input[type=reset],input[type=checkbox],input[type=radio],select,summary,label,[role=button],[role=link],[role=tab],[role=menuitem],[role=checkbox],[role=switch],[role=option],[onclick],[data-guidely-track]";
 var DEFAULT_MASK_SELECTORS = ["[data-guidely-mask]", ".guidely-mask"];
 var PREFERRED_ATTRS = ["data-testid", "data-test-id", "data-test", "data-cy", "data-qa", "data-guidely-track", "data-tour"];
@@ -400,11 +401,11 @@ function validSelectors(list) {
   return out;
 }
 function isIgnoredElement(el) {
-  return isGuidelyElement(el) || !!el.closest("[data-guidely-ignore]");
+  return isGuidelyElement(el) || !!closestComposed2(el, "[data-guidely-ignore]");
 }
 function interactiveElement(target) {
   try {
-    return target.closest(INTERACTIVE_SELECTOR);
+    return closestComposed2(target, INTERACTIVE_SELECTOR);
   } catch {
     return null;
   }
@@ -415,14 +416,19 @@ function esc(value) {
 }
 var attr = (tag, name, value) => value ? `${tag}[${name}="${value.replace(/["\\]/g, "\\$&")}"]` : `${tag}[${name}]`;
 function elementSelector(el) {
+  const own = ownSelector(el);
+  const chain = shadowHostChain(el);
+  return (chain ? chain + SHADOW_SEPARATOR + own : own).slice(0, 300);
+}
+function ownSelector(el) {
   const tag = el.tagName.toLowerCase();
   if (el.id && isStableId(el.id)) return `#${esc(el.id)}`;
-  for (const name of PREFERRED_ATTRS) if (el.hasAttribute(name)) return attr(tag, name, el.getAttribute(name) || "").slice(0, 300);
+  for (const name of PREFERRED_ATTRS) if (el.hasAttribute(name)) return attr(tag, name, el.getAttribute(name) || "");
   for (const a of Array.from(el.attributes)) {
-    if (a.name.startsWith("data-") && !NOISY_DATA_ATTR.test(a.name) && a.value && a.value.length <= 60) return attr(tag, a.name, a.value).slice(0, 300);
+    if (a.name.startsWith("data-") && !NOISY_DATA_ATTR.test(a.name) && a.value && a.value.length <= 60) return attr(tag, a.name, a.value);
   }
   const label = el.getAttribute("aria-label");
-  if (label && label.length <= 80) return attr(tag, "aria-label", label).slice(0, 300);
+  if (label && label.length <= 80) return attr(tag, "aria-label", label);
   const parts = [];
   let cur = el;
   while (cur && parts.length < 4) {
@@ -438,12 +444,12 @@ function elementSelector(el) {
     parts.unshift(same.length > 1 ? `${t}:nth-of-type(${same.indexOf(node) + 1})` : t);
     cur = parent;
   }
-  return (parts.join(" > ") || tag).slice(0, 300);
+  return parts.join(" > ") || tag;
 }
 function matches(el, selector, deep) {
   if (!selector) return false;
   try {
-    return !!el.closest(selector) || deep && !!el.querySelector(selector);
+    return !!closestComposed2(el, selector) || deep && !!el.querySelector(selector);
   } catch {
     return false;
   }
@@ -461,7 +467,7 @@ function elementText(el, mask, maskAll) {
   return text ? text.slice(0, 100) : void 0;
 }
 function linkHref(el) {
-  const a = el.closest("a[href]");
+  const a = closestComposed2(el, "a[href]");
   if (!a) return void 0;
   try {
     const u = new URL(a.getAttribute("href") || "", location.href);
@@ -1028,11 +1034,22 @@ var loadRecorder = async () => (await import("./recorder.js")).recorder;
 
 // src/client.ts
 var SDK_NAME = "@guidelytech/sdk-core";
-var SDK_VERSION = "0.9.0";
+var SDK_VERSION = "0.10.0";
 var DEFAULT_API_URL = "https://api.guidely.app";
 var PAGE_SCOPED = /* @__PURE__ */ new Set(["page_load", "url_match", "element_click", "element_visible", "delay"]);
 var DAY_MS = 24 * 60 * 60 * 1e3;
 var MAX_SESSION_EXCEPTIONS = 100;
+var CACHED_START_MS = 1500;
+function settlesWithin(promise, ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(false), ms);
+    const done = () => {
+      clearTimeout(timer);
+      resolve(true);
+    };
+    promise.then(done, done);
+  });
+}
 function isBrowser() {
   return typeof window !== "undefined" && typeof document !== "undefined";
 }
@@ -1053,6 +1070,8 @@ var GuidelyClient = class _GuidelyClient {
     __publicField(this, "sessionStore");
     __publicField(this, "emitter");
     __publicField(this, "queue");
+    /** Survey answers and guide/checklist progress, kept until the server accepts them. */
+    __publicField(this, "outbox");
     __publicField(this, "config", null);
     __publicField(this, "etag", null);
     __publicField(this, "anonymousId");
@@ -1152,6 +1171,7 @@ var GuidelyClient = class _GuidelyClient {
       store: this.store,
       storageKey: KEYS.queue(this.options.projectId),
       enabled: () => this.analyticsEnabled(),
+      health: this.api.health,
       send: async (events) => {
         const res = await this.api.post("/events", { events, sentAt: nowIso(), sdk: { name: SDK_NAME, version: SDK_VERSION } }, { keepalive: true });
         return { ok: res.ok, retry: !(res.status >= 400 && res.status < 500 && res.status !== 429) };
@@ -1159,6 +1179,7 @@ var GuidelyClient = class _GuidelyClient {
       beacon: (events) => this.api.beacon("/events", { events, sentAt: nowIso(), sdk: { name: SDK_NAME, version: SDK_VERSION } }),
       onError: (err) => this.reportError(err)
     });
+    this.outbox = new Outbox({ api: this.api, store: this.store, storageKey: KEYS.outbox(this.options.projectId), health: this.api.health });
     if (options.user) this.user = { ...options.user };
     this.flags = this.createFlags(options.flags);
   }
@@ -1216,12 +1237,15 @@ var GuidelyClient = class _GuidelyClient {
       const cached = readJson(this.store, KEYS.config(this.options.projectId), null);
       this.etag = this.store.get(KEYS.etag(this.options.projectId));
       if (cached && cached.guides) this.config = webOnly(cached);
-      await this.fetchConfig();
+      const before = this.config?.configVersion;
+      const fresh = this.fetchConfig();
+      if (!this.config) await fresh;
+      else if (!await settlesWithin(fresh, CACHED_START_MS)) void fresh.then(() => this.applyConfigChange(before));
       if (this.destroyed) return;
       this.wireListeners();
       if (!this.identitySettled) {
-        if (this.options.user) await this.identify(this.options.user.id, this.options.user.traits, this.options.user.account);
-        else if (this.user?.id) await this.identify(this.user.id, this.user.traits, this.user.account);
+        const known = this.options.user ?? (this.user?.id ? this.user : null);
+        if (known) await settlesWithin(this.identify(known.id, known.traits, known.account), CACHED_START_MS);
       }
       if (this.destroyed) return;
       this.isReady = true;
@@ -1326,7 +1350,12 @@ var GuidelyClient = class _GuidelyClient {
       win.removeEventListener("scroll", onScroll);
       doc.removeEventListener("keydown", onKey, true);
     });
-    const refresh = setInterval(() => void this.refresh(), this.options.configRefreshMs);
+    const refresh = setInterval(() => {
+      if (this.api.health.canSend()) void this.refresh();
+    }, this.options.configRefreshMs);
+    const onOnline = () => this.api.health.online();
+    win.addEventListener("online", onOnline);
+    this.cleanups.push(() => win.removeEventListener("online", onOnline));
     this.cleanups.push(() => clearInterval(refresh));
     const poll = setInterval(() => {
       if (!this.isReady || !this.config || this.editing() || doc.visibilityState === "hidden") return;
@@ -1359,6 +1388,11 @@ var GuidelyClient = class _GuidelyClient {
     if (this.destroyed) return;
     const before = this.config?.configVersion;
     await this.fetchConfig();
+    this.applyConfigChange(before);
+  }
+  /** Re-renders after a config change (refresh, or a config that arrived after start). */
+  applyConfigChange(before) {
+    if (this.destroyed || !this.isReady) return;
     if (this.config && this.config.configVersion !== before) {
       this.renderPersistentWidgets();
       this.evaluate("ready");
@@ -1393,6 +1427,7 @@ var GuidelyClient = class _GuidelyClient {
     this.replay = null;
     this.queue.flushSync();
     this.queue.destroy();
+    this.outbox.destroy();
     this.flags.destroy();
     this.emitter.clear();
     destroyHost();
@@ -1595,7 +1630,7 @@ var GuidelyClient = class _GuidelyClient {
     if (changed) void this.queue.flush();
   }
   handleDocumentClick(e) {
-    const target = e.target;
+    const target = composedTarget(e);
     if (!target || typeof target.closest !== "function") return;
     this.autocaptureClick(e, target);
     this.completeChecklistTasksBy("click", target);
@@ -1690,7 +1725,7 @@ var GuidelyClient = class _GuidelyClient {
   }
   /** Bins one pointer sample into the heatmap buffer. Not session activity. */
   sampleMove(e) {
-    const target = e.target;
+    const target = composedTarget(e);
     if (document.visibilityState === "hidden" || !target?.closest || !this.autocaptureOn("mouseMovement") || isIgnoredElement(target)) return;
     const url = location.href;
     if (this.heatmap.url !== url) this.flushHeatmap();
@@ -1815,7 +1850,9 @@ var GuidelyClient = class _GuidelyClient {
             this.persistSession();
             this.replay?.stop({ discard: true });
           },
-          onError: (err) => this.reportError(err)
+          onError: (err) => this.reportError(err),
+          health: this.api.health,
+          stash: this.sessionStore
         });
         this.syncReplay();
       },
@@ -1905,7 +1942,7 @@ var GuidelyClient = class _GuidelyClient {
       case "element_click":
         if (reason !== "click" || !t.value || !detail.target) return false;
         try {
-          return !!detail.target.closest(t.value);
+          return !!closestComposed3(detail.target, t.value);
         } catch {
           return false;
         }
@@ -2056,7 +2093,9 @@ var GuidelyClient = class _GuidelyClient {
     if (reason === "completed") this.completeChecklistTasksBy("guide_completed", guide);
   }
   syncGuideState(guideId, update) {
-    void postWithRetry(this.api, "/guide-state", { anonymousId: this.anonymousId, userId: this.user?.id || null, updates: [{ guideId, ...update }] });
+    const body = { anonymousId: this.anonymousId, userId: this.user?.id || null, updates: [{ guideId, ...update }] };
+    if (update.impression) void postWithRetry(this.api, "/guide-state", body);
+    else this.outbox.add(`guide:${guideId}:${update.completed ? "completed" : "dismissed"}:${this.anonymousId}`, "/guide-state", body);
   }
   show(guide, manual, stepId) {
     try {
@@ -2184,7 +2223,7 @@ var GuidelyClient = class _GuidelyClient {
         this.persistState();
         this.recordEnd(guide, "completed");
         this.enqueue("survey_submitted", { guideId: guide.id, guideVersion: guide.version, properties: { responseId } });
-        void postWithRetry(this.api, `/surveys/${encodeURIComponent(guide.id)}/responses`, { anonymousId: this.anonymousId, userId: this.user?.id || null, accountId: this.user?.account?.id || null, guideVersion: guide.version, answers, responseId });
+        this.outbox.add(`survey:${responseId}`, `/surveys/${encodeURIComponent(guide.id)}/responses`, { anonymousId: this.anonymousId, userId: this.user?.id || null, accountId: this.user?.account?.id || null, guideVersion: guide.version, answers, responseId });
         this.emitter.emit("survey:submit", { guide, answers, responseId });
         this.emitter.emit("guide:complete", guide);
         widget.showThankYou();
@@ -2373,7 +2412,7 @@ var GuidelyClient = class _GuidelyClient {
     }
     this.persistState();
     this.widgets.get(guide.id)?.checklist?.setProgress(this.getChecklistProgress(guide.id));
-    void postWithRetry(this.api, `/checklists/${encodeURIComponent(guide.id)}/progress`, { anonymousId: this.anonymousId, userId: this.user?.id || null, guideVersion: guide.version, completedTaskIds: progress.completedTaskIds, completed: !!progress.completedAt });
+    this.outbox.add(`checklist:${guide.id}:progress:${this.anonymousId}`, `/checklists/${encodeURIComponent(guide.id)}/progress`, { anonymousId: this.anonymousId, userId: this.user?.id || null, guideVersion: guide.version, completedTaskIds: progress.completedTaskIds, completed: !!progress.completedAt });
     this.emitter.emit("checklist:task", { guide, task, progress: this.getChecklistProgress(guide.id) });
     if (complete) {
       this.emitter.emit("checklist:complete", guide);
@@ -2393,7 +2432,7 @@ var GuidelyClient = class _GuidelyClient {
         else if (kind === "guide_completed") hit = value.id === task.completionValue || value.key === task.completionValue;
         else if (kind === "click") {
           try {
-            hit = !!value.closest(task.completionValue);
+            hit = !!closestComposed3(value, task.completionValue);
           } catch {
             hit = false;
           }
@@ -2413,7 +2452,7 @@ var GuidelyClient = class _GuidelyClient {
     progress.dismissedAt = nowIso();
     this.persistState();
     this.enqueue("checklist_dismissed", { guideId: guide.id, guideVersion: guide.version });
-    void postWithRetry(this.api, `/checklists/${encodeURIComponent(guide.id)}/progress`, { anonymousId: this.anonymousId, userId: this.user?.id || null, guideVersion: guide.version, completedTaskIds: progress.completedTaskIds, dismissed: true });
+    this.outbox.add(`checklist:${guide.id}:dismissed:${this.anonymousId}`, `/checklists/${encodeURIComponent(guide.id)}/progress`, { anonymousId: this.anonymousId, userId: this.user?.id || null, guideVersion: guide.version, completedTaskIds: progress.completedTaskIds, dismissed: true });
     this.widgets.get(guide.id)?.destroy();
     this.widgets.delete(guide.id);
   }