@knocklabs/client 0.15.1 → 0.16.0

package/dist/esm/clients/guide/client.mjs

@@ -1,64 +1,119 @@
-var l = Object.defineProperty;
-var k = (o, e, t) => e in o ? l(o, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : o[e] = t;
-var c = (o, e, t) => k(o, typeof e != "symbol" ? e + "" : e, t);
-import { Store as m } from "@tanstack/store";
-import { URLPattern as p } from "urlpattern-polyfill";
-const u = (o) => [...o].sort(
-  (e, t) => t.priority - e.priority || new Date(t.inserted_at).getTime() - new Date(e.inserted_at).getTime()
-), g = (o) => `/v1/users/${o}/guides`;
-class v {
-  constructor(e, t, s = {}, n = {}) {
-    c(this, "store");
+var f = Object.defineProperty;
+var S = (u, e, t) => e in u ? f(u, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : u[e] = t;
+var d = (u, e, t) => S(u, typeof e != "symbol" ? e + "" : e, t);
+import { Store as y } from "@tanstack/store";
+import { URLPattern as v } from "urlpattern-polyfill";
+import { byKey as G, mockDefaultGroup as _, formatFilters as l, findDefaultGroup as k, DEFAULT_GROUP_KEY as g, checkIfThrottled as w, SelectionResult as C } from "./helpers.mjs";
+const b = 50, I = 30 * 1e3, A = (u) => `/v1/users/${u}/guides`, p = (u, e = {}) => {
+  const t = new C(), s = k(u.guideGroups);
+  if (!s) return t;
+  const r = s.display_sequence, i = u.location;
+  for (const [n, o] of r.entries()) {
+    const a = u.guides[o];
+    !a || !L(a, { location: i, filters: e }) || t.set(n, a);
+  }
+  return t.metadata = { guideGroup: s }, t;
+}, L = (u, { location: e, filters: t = {} }) => {
+  if (t.type && t.type !== u.type || t.key && t.key !== u.key || u.steps.every((r) => !!r.message.archived_at))
+    return !1;
+  const s = u.activation_location_rules || [];
+  return !(s.length > 0 && e && !s.reduce((i, n) => {
+    if (i === !1) return !1;
+    switch (n.directive) {
+      case "allow":
+        return i === !0 || n.pattern.test(e) ? !0 : void 0;
+      case "block":
+        return n.pattern.test(e) ? !1 : i;
+    }
+  }, void 0));
+};
+class F {
+  constructor(e, t, s = {}, r = {}) {
+    d(this, "store");
     // Phoenix channels for real time guide updates over websocket
-    c(this, "socket");
-    c(this, "socketChannel");
-    c(this, "socketChannelTopic");
-    c(this, "socketEventTypes", ["guide.added", "guide.updated", "guide.removed"]);
+    d(this, "socket");
+    d(this, "socketChannel");
+    d(this, "socketChannelTopic");
+    d(this, "socketEventTypes", [
+      "guide.added",
+      "guide.updated",
+      "guide.removed",
+      "guide_group.added",
+      "guide_group.updated"
+    ]);
     // Original history methods to monkey patch, or restore in cleanups.
-    c(this, "pushStateFn");
-    c(this, "replaceStateFn");
+    d(this, "pushStateFn");
+    d(this, "replaceStateFn");
+    // Guides that are competing to render are "staged" first without rendering
+    // and ranked based on its relative order in the group over a duration of time
+    // to resolve and render the prevailing one.
+    d(this, "stage");
+    d(this, "counterIntervalId");
     // Define as an arrow func property to always bind this to the class instance.
-    c(this, "handleLocationChange", () => {
+    d(this, "handleLocationChange", () => {
       const e = window.location.href;
-      this.store.state.location !== e && (this.knock.log(`[Guide] Handle Location change: ${e}`), this.store.setState((t) => ({ ...t, location: e })));
+      this.store.state.location !== e && (this.knock.log(`[Guide] Handle Location change: ${e}`), this.setLocation(e));
     });
-    this.knock = e, this.channelId = t, this.targetParams = s, this.options = n;
-    const { trackLocationFromWindow: i = !0 } = n, r = i ? window == null ? void 0 : window.location.href : void 0;
-    this.store = new m({
-      guides: [],
+    this.knock = e, this.channelId = t, this.targetParams = s, this.options = r;
+    const { trackLocationFromWindow: i = !0 } = r, n = i ? window == null ? void 0 : window.location.href : void 0;
+    this.store = new y({
+      guideGroups: [],
+      guideGroupDisplayLogs: {},
+      guides: {},
       queries: {},
-      location: r
+      location: n,
+      // Increment to update the state store and trigger re-selection.
+      counter: 0
     });
-    const { socket: a } = this.knock.client();
-    this.socket = a, this.socketChannelTopic = `guides:${t}`, i && this.listenForLocationChangesFromWindow(), this.knock.log("[Guide] Initialized a guide client");
+    const { socket: o } = this.knock.client();
+    this.socket = o, this.socketChannelTopic = `guides:${t}`, i && this.listenForLocationChangesFromWindow(), this.startCounterInterval(), this.knock.log("[Guide] Initialized a guide client");
+  }
+  incrementCounter() {
+    this.knock.log("[Guide] Incrementing the counter"), this.store.setState((e) => ({ ...e, counter: e.counter + 1 }));
+  }
+  startCounterInterval() {
+    const {
+      throttleCheckInterval: e = I
+    } = this.options;
+    this.counterIntervalId = setInterval(() => {
+      this.knock.log("[Guide] Counter interval tick"), !(this.stage && this.stage.status !== "closed") && this.incrementCounter();
+    }, e);
+  }
+  clearCounterInterval() {
+    this.counterIntervalId && (clearInterval(this.counterIntervalId), this.counterIntervalId = void 0);
   }
   cleanup() {
-    this.unsubscribe(), this.removeEventListeners();
+    this.unsubscribe(), this.removeEventListeners(), this.clearGroupStage(), this.clearCounterInterval();
   }
   async fetch(e) {
     this.knock.failIfNotAuthenticated(), this.knock.log("[Guide] Loading all eligible guides");
-    const t = this.buildQueryParams(e == null ? void 0 : e.filters), s = this.formatQueryKey(t), n = this.store.state.queries[s];
-    if (n)
-      return n;
-    this.store.setState((r) => ({
-      ...r,
-      queries: { ...r.queries, [s]: { status: "loading" } }
+    const t = this.buildQueryParams(e == null ? void 0 : e.filters), s = this.formatQueryKey(t), r = this.store.state.queries[s];
+    if (r)
+      return r;
+    this.store.setState((n) => ({
+      ...n,
+      queries: { ...n.queries, [s]: { status: "loading" } }
     }));
     let i;
     try {
-      const r = await this.knock.user.getGuides(this.channelId, t);
-      i = { status: "ok" }, this.store.setState((a) => ({
-        ...a,
-        // For now assume a single fetch to get all eligible guides. When/if
-        // we implement incremental loads, then this will need to be a merge
-        // and sort operation.
-        guides: r.entries.map((d) => this.localCopy(d)),
-        queries: { ...a.queries, [s]: i }
+      const n = await this.knock.user.getGuides(this.channelId, t);
+      i = { status: "ok" };
+      const {
+        entries: o,
+        guide_groups: a,
+        guide_group_display_logs: h
+      } = n;
+      this.store.setState((c) => ({
+        ...c,
+        guideGroups: (a == null ? void 0 : a.length) > 0 ? a : [_(o)],
+        guideGroupDisplayLogs: h,
+        guides: G(o.map((m) => this.localCopy(m))),
+        queries: { ...c.queries, [s]: i }
       }));
-    } catch (r) {
-      i = { status: "error", error: r }, this.store.setState((a) => ({
-        ...a,
-        queries: { ...a.queries, [s]: i }
+    } catch (n) {
+      i = { status: "error", error: n }, this.store.setState((o) => ({
+        ...o,
+        queries: { ...o.queries, [s]: i }
       }));
     }
     return i;
@@ -68,7 +123,7 @@ class v {
     this.knock.failIfNotAuthenticated(), this.knock.log("[Guide] Subscribing to real time updates"), this.socket.isConnected() || this.socket.connect(), this.socketChannel && this.unsubscribe();
     const e = { ...this.targetParams, user_id: this.knock.userId }, t = this.socket.channel(this.socketChannelTopic, e);
     for (const s of this.socketEventTypes)
-      t.on(s, (n) => this.handleSocketEvent(n));
+      t.on(s, (r) => this.handleSocketEvent(r));
     ["closed", "errored"].includes(t.state) && t.join(), this.socketChannel = t;
   }
   unsubscribe() {
@@ -83,36 +138,113 @@ class v {
     const { event: t, data: s } = e;
     switch (t) {
       case "guide.added":
-        return this.addGuide(e);
+        return this.addOrReplaceGuide(e);
       case "guide.updated":
-        return s.eligible ? this.replaceOrAddGuide(e) : this.removeGuide(e);
+        return s.eligible ? this.addOrReplaceGuide(e) : this.removeGuide(e);
       case "guide.removed":
         return this.removeGuide(e);
+      case "guide_group.added":
+      case "guide_group.updated":
+        return this.addOrReplaceGuideGroup(e);
       default:
         return;
     }
   }
+  setLocation(e) {
+    this.clearGroupStage(), this.store.setState((t) => ({ ...t, location: e }));
+  }
   //
   // Store selector
   //
-  select(e, t = {}) {
-    return e.guides.filter((s) => {
-      if (t.type && t.type !== s.type || t.key && t.key !== s.key)
-        return !1;
-      const n = s.activation_location_rules || [];
-      return !(n.length > 0 && e.location && !n.reduce(
-        (r, a) => {
-          if (r === !1) return !1;
-          switch (a.directive) {
-            case "allow":
-              return r === !0 || a.pattern.test(e.location) ? !0 : void 0;
-            case "block":
-              return a.pattern.test(e.location) ? !1 : r;
-          }
-        },
-        void 0
-      ));
-    });
+  selectGuides(e, t = {}) {
+    if (Object.keys(e.guides).length === 0)
+      return [];
+    this.knock.log(`[Guide] Selecting guides for: ${l(t)}`);
+    const s = p(e, t);
+    return s.size === 0 ? (this.knock.log("[Guide] Selection returned zero result"), []) : [...s.values()];
+  }
+  selectGuide(e, t = {}) {
+    if (Object.keys(e.guides).length === 0)
+      return;
+    this.knock.log(`[Guide] Selecting a guide for: ${l(t)}`);
+    const s = p(e, t);
+    if (s.size === 0) {
+      this.knock.log("[Guide] Selection returned zero result");
+      return;
+    }
+    const [r, i] = [...s][0];
+    if (i.bypass_global_group_limit)
+      return i;
+    const n = k(e.guideGroups), o = e.guideGroupDisplayLogs[g];
+    if (!(n && n.display_interval && o && w(
+      o,
+      n.display_interval
+    )))
+      switch (this.stage || (this.stage = this.openGroupStage()), this.stage.status) {
+        case "open": {
+          this.knock.log(`[Guide] Addng to the group stage: ${i.key}`), this.stage.ordered[r] = i.key;
+          return;
+        }
+        case "patch":
+          return this.knock.log(`[Guide] Patching the group stage: ${i.key}`), this.stage.ordered[r] = i.key, this.stage.resolved === i.key ? i : void 0;
+        case "closed":
+          return this.stage.resolved === i.key ? i : void 0;
+      }
+  }
+  openGroupStage() {
+    this.knock.log("[Guide] Opening a new group stage");
+    const {
+      orderResolutionDuration: e = b
+    } = this.options, t = setTimeout(() => {
+      this.closePendingGroupStage(), this.incrementCounter();
+    }, e);
+    return this.stage = {
+      status: "open",
+      ordered: [],
+      timeoutId: t
+    }, this.stage;
+  }
+  // Close the current non-closed stage to resolve the prevailing guide up next
+  // for display amongst the ones that have been staged.
+  closePendingGroupStage() {
+    if (!(!this.stage || this.stage.status === "closed"))
+      return this.knock.log("[Guide] Closing the current group stage"), this.ensureClearTimeout(), this.stage = {
+        ...this.stage,
+        status: "closed",
+        resolved: this.stage.ordered.find((e) => e !== void 0),
+        timeoutId: null
+      }, this.stage;
+  }
+  // Set the current closed stage status to "patch" to allow re-running
+  // selections and re-building a group stage with the latest/updated state,
+  // while keeping the currently resolved guide in place so that it stays
+  // rendered until we are ready to resolve the updated stage and re-render.
+  // Note, must be called ahead of updating the state store.
+  patchClosedGroupStage() {
+    var s;
+    if (((s = this.stage) == null ? void 0 : s.status) !== "closed") return;
+    this.knock.log("[Guide] Patching the current group stage");
+    const { orderResolutionDuration: e = 0 } = this.options, t = setTimeout(() => {
+      this.closePendingGroupStage(), this.incrementCounter();
+    }, e);
+    return this.ensureClearTimeout(), this.stage = {
+      ...this.stage,
+      status: "patch",
+      ordered: [],
+      timeoutId: t
+    }, this.stage;
+  }
+  clearGroupStage() {
+    this.stage && (this.knock.log("[Guide] Clearing the current group stage"), this.ensureClearTimeout(), this.stage = void 0);
+  }
+  ensureClearTimeout() {
+    var e;
+    (e = this.stage) != null && e.timeoutId && clearTimeout(this.stage.timeoutId);
+  }
+  // Test helper that opens and closes the group stage to return the select
+  // result immediately.
+  _selectGuide(e, t = {}) {
+    return this.openGroupStage(), this.selectGuide(e, t), this.closePendingGroupStage(), this.selectGuide(e, t);
   }
   //
   // Engagement event handlers
@@ -121,6 +253,7 @@ class v {
   // event to the backend.
   //
   async markAsSeen(e, t) {
+    if (t.message.seen_at) return;
     this.knock.log(
       `[Guide] Marking as seen (Guide key: ${e.key}, Step ref:${t.ref})`
     );
@@ -128,7 +261,7 @@ class v {
       seen_at: (/* @__PURE__ */ new Date()).toISOString()
     });
     if (!s) return;
-    const n = {
+    const r = {
       ...this.buildEngagementEventBaseParams(e, s),
       content: s.content,
       data: this.targetParams.data,
@@ -136,25 +269,26 @@ class v {
     };
     return this.knock.user.markGuideStepAs(
       "seen",
-      n
+      r
     ), s;
   }
   async markAsInteracted(e, t, s) {
     this.knock.log(
       `[Guide] Marking as interacted (Guide key: ${e.key}, Step ref:${t.ref})`
     );
-    const n = (/* @__PURE__ */ new Date()).toISOString(), i = this.setStepMessageAttrs(e.key, t.ref, {
-      read_at: n,
-      interacted_at: n
+    const r = (/* @__PURE__ */ new Date()).toISOString(), i = this.setStepMessageAttrs(e.key, t.ref, {
+      read_at: r,
+      interacted_at: r
     });
     if (!i) return;
-    const r = {
+    const n = {
       ...this.buildEngagementEventBaseParams(e, i),
       metadata: s
     };
-    return this.knock.user.markGuideStepAs("interacted", r), i;
+    return this.knock.user.markGuideStepAs("interacted", n), i;
   }
   async markAsArchived(e, t) {
+    if (t.message.archived_at) return;
     this.knock.log(
       `[Guide] Marking as archived (Guide key: ${e.key}, Step ref:${t.ref})`
     );
@@ -162,44 +296,53 @@ class v {
       archived_at: (/* @__PURE__ */ new Date()).toISOString()
     });
     if (!s) return;
-    const n = this.buildEngagementEventBaseParams(e, s);
+    const r = this.buildEngagementEventBaseParams(e, s);
     return this.knock.user.markGuideStepAs(
       "archived",
-      n
+      {
+        ...r,
+        unthrottled: e.bypass_global_group_limit
+      }
     ), s;
   }
   //
   // Helpers
   //
   localCopy(e) {
-    const t = this, s = { ...e };
-    return s.steps = e.steps.map(({ message: n, ...i }) => {
-      const r = {
+    const t = this, s = {
+      ...e,
+      // Get the next unarchived step.
+      getStep() {
+        return this.steps.find((r) => !r.message.archived_at);
+      }
+    };
+    return s.getStep = s.getStep.bind(s), s.steps = e.steps.map(({ message: r, ...i }) => {
+      const n = {
         ...i,
-        message: { ...n },
+        message: { ...r },
         markAsSeen() {
           if (!this.message.seen_at)
             return t.markAsSeen(s, this);
         },
-        markAsInteracted({ metadata: a } = {}) {
-          return t.markAsInteracted(s, this, a);
+        markAsInteracted({ metadata: o } = {}) {
+          return t.markAsInteracted(s, this, o);
         },
         markAsArchived() {
           if (!this.message.archived_at)
             return t.markAsArchived(s, this);
         }
       };
-      return r.markAsSeen = r.markAsSeen.bind(r), r.markAsInteracted = r.markAsInteracted.bind(r), r.markAsArchived = r.markAsArchived.bind(r), r;
-    }), s.activation_location_rules = e.activation_location_rules.map((n) => ({
-      ...n,
-      pattern: new p({ pathname: n.pathname })
+      return n.markAsSeen = n.markAsSeen.bind(n), n.markAsInteracted = n.markAsInteracted.bind(n), n.markAsArchived = n.markAsArchived.bind(n), n;
+    }), s.activation_location_rules = e.activation_location_rules.map((r) => ({
+      ...r,
+      pattern: new v({ pathname: r.pathname })
     })), s;
   }
   buildQueryParams(e = {}) {
     const t = { ...this.targetParams, ...e };
     let s = Object.fromEntries(
       Object.entries(t).filter(
-        ([n, i]) => i != null
+        ([r, i]) => i != null
       )
     );
     return s = s.data ? { ...s, data: JSON.stringify(s.data) } : s, s;
@@ -207,19 +350,22 @@ class v {
   formatQueryKey(e) {
     const s = Object.keys(e).sort().map(
       (i) => `${encodeURIComponent(i)}=${encodeURIComponent(e[i])}`
-    ).join("&"), n = g(this.knock.userId);
-    return s ? `${n}?${s}` : n;
+    ).join("&"), r = A(this.knock.userId);
+    return s ? `${r}?${s}` : r;
   }
   setStepMessageAttrs(e, t, s) {
-    let n;
-    return this.store.setState((i) => {
-      const r = i.guides.map((a) => {
-        if (a.key !== e) return a;
-        const d = a.steps.map((h) => (h.ref !== t || (h.message = { ...h.message, ...s }, n = h), h));
-        return { ...a, steps: d };
-      });
-      return { ...i, guides: r };
-    }), n;
+    let r;
+    return s.archived_at && this.clearGroupStage(), this.store.setState((i) => {
+      const n = i.guides[e];
+      if (!n) return i;
+      const o = n.steps.map((c) => (c.ref !== t || (c.message = { ...c.message, ...s }, r = c), c));
+      n.steps = o;
+      const a = { ...i.guides, [n.key]: n }, h = s.archived_at && !n.bypass_global_group_limit ? {
+        ...i.guideGroupDisplayLogs,
+        [g]: s.archived_at
+      } : i.guideGroupDisplayLogs;
+      return { ...i, guides: a, guideGroupDisplayLogs: h };
+    }), r;
   }
   buildEngagementEventBaseParams(e, t) {
     return {
@@ -230,25 +376,35 @@ class v {
       guide_step_ref: t.ref
     };
   }
-  addGuide({ data: e }) {
-    const t = this.localCopy(e.guide);
-    this.store.setState((s) => ({ ...s, guides: u([...s.guides, t]) }));
-  }
-  replaceOrAddGuide({ data: e }) {
+  addOrReplaceGuide({ data: e }) {
+    this.patchClosedGroupStage();
     const t = this.localCopy(e.guide);
     this.store.setState((s) => {
-      let n = !1;
-      const i = s.guides.map((r) => r.key !== t.key ? r : (n = !0, t));
-      return {
-        ...s,
-        guides: u(n ? i : [...i, t])
-      };
+      const r = { ...s.guides, [t.key]: t };
+      return { ...s, guides: r };
     });
   }
   removeGuide({ data: e }) {
-    this.store.setState((t) => {
-      const s = t.guides.filter((n) => n.key !== e.guide.key);
-      return { ...t, guides: s };
+    this.patchClosedGroupStage(), this.store.setState((t) => {
+      const { [e.guide.key]: s, ...r } = t.guides;
+      return { ...t, guides: r };
+    });
+  }
+  addOrReplaceGuideGroup({
+    data: e
+  }) {
+    this.patchClosedGroupStage(), this.store.setState((t) => {
+      const s = [e.guide_group], r = e.guide_group.display_sequence_unthrottled || [], i = e.guide_group.display_sequence_throttled || [];
+      let n = t.guides;
+      return n = r.reduce((o, a) => {
+        if (!o[a]) return o;
+        const h = { ...o[a], bypass_global_group_limit: !0 };
+        return { ...o, [a]: h };
+      }, n), n = i.reduce((o, a) => {
+        if (!o[a]) return o;
+        const h = { ...o[a], bypass_global_group_limit: !1 };
+        return { ...o, [a]: h };
+      }, n), { ...t, guides: n, guideGroups: s };
     });
   }
   listenForLocationChangesFromWindow() {
@@ -256,14 +412,14 @@ class v {
       window.addEventListener("popstate", this.handleLocationChange), window.addEventListener("hashchange", this.handleLocationChange);
       const e = window.history.pushState, t = window.history.replaceState;
       window.history.pushState = new Proxy(e, {
-        apply: (s, n, i) => {
-          Reflect.apply(s, n, i), setTimeout(() => {
+        apply: (s, r, i) => {
+          Reflect.apply(s, r, i), setTimeout(() => {
             this.handleLocationChange();
           }, 0);
         }
       }), window.history.replaceState = new Proxy(t, {
-        apply: (s, n, i) => {
-          Reflect.apply(s, n, i), setTimeout(() => {
+        apply: (s, r, i) => {
+          Reflect.apply(s, r, i), setTimeout(() => {
             this.handleLocationChange();
           }, 0);
         }
@@ -278,7 +434,7 @@ class v {
   }
 }
 export {
-  v as KnockGuideClient,
-  g as guidesApiRootPath
+  F as KnockGuideClient,
+  A as guidesApiRootPath
 };
 //# sourceMappingURL=client.mjs.map