@knocklabs/client 0.15.2 → 0.16.1

package/src/clients/guide/client.ts

@@ -5,164 +5,132 @@ import { URLPattern } from "urlpattern-polyfill";
 
 import Knock from "../../knock";
 
-const sortGuides = (guides: KnockGuide[]) => {
-  return [...guides].sort(
-    (a, b) =>
-      b.priority - a.priority ||
-      new Date(b.inserted_at).getTime() - new Date(a.inserted_at).getTime(),
-  );
-};
-
-//
-// Guides API (via User client)
-//
+import {
+  DEFAULT_GROUP_KEY,
+  SelectionResult,
+  byKey,
+  checkIfThrottled,
+  findDefaultGroup,
+  formatFilters,
+  mockDefaultGroup,
+} from "./helpers";
+import {
+  ConstructorOpts,
+  GetGuidesQueryParams,
+  GetGuidesResponse,
+  GroupStage,
+  GuideAddedEvent,
+  GuideData,
+  GuideGroupAddedEvent,
+  GuideGroupUpdatedEvent,
+  GuideRemovedEvent,
+  GuideSocketEvent,
+  GuideStepData,
+  GuideUpdatedEvent,
+  KnockGuide,
+  KnockGuideStep,
+  MarkAsArchivedParams,
+  MarkAsInteractedParams,
+  MarkAsSeenParams,
+  MarkGuideAsResponse,
+  QueryFilterParams,
+  QueryStatus,
+  SelectFilterParams,
+  StepMessageState,
+  StoreState,
+  TargetParams,
+} from "./types";
+
+// How long to wait until we resolve the guides order and determine the
+// prevailing guide.
+const DEFAULT_ORDER_RESOLUTION_DURATION = 50; // in milliseconds
+
+// How often we should increment the counter to refresh the store state and
+// trigger subscribed callbacks.
+const DEFAULT_COUNTER_INCREMENT_INTERVAL = 30 * 1000; // in milliseconds
 
 export const guidesApiRootPath = (userId: string | undefined | null) =>
   `/v1/users/${userId}/guides`;
 
-interface StepMessageState {
-  id: string;
-  seen_at: string | null;
-  read_at: string | null;
-  interacted_at: string | null;
-  archived_at: string | null;
-  link_clicked_at: string | null;
-}
+const select = (state: StoreState, filters: SelectFilterParams = {}) => {
+  // A map of selected guides as values, with its order index as keys.
+  const result = new SelectionResult();
 
-interface GuideStepData {
-  ref: string;
-  schema_key: string;
-  schema_semver: string;
-  schema_variant_key: string;
-  message: StepMessageState;
-  // eslint-disable-next-line
-  content: any;
-}
+  const defaultGroup = findDefaultGroup(state.guideGroups);
+  if (!defaultGroup) return result;
 
-interface GuideActivationLocationRuleData {
-  directive: "allow" | "block";
-  pathname: string;
-}
+  const displaySequence = defaultGroup.display_sequence;
+  const location = state.location;
 
-interface GuideData {
-  __typename: "Guide";
-  channel_id: string;
-  id: string;
-  key: string;
-  priority: number;
-  type: string;
-  semver: string;
-  steps: GuideStepData[];
-  activation_location_rules: GuideActivationLocationRuleData[];
-  inserted_at: string;
-  updated_at: string;
-}
-
-export interface KnockGuideStep extends GuideStepData {
-  markAsSeen: () => void;
-  markAsInteracted: (params?: { metadata?: GenericData }) => void;
-  markAsArchived: () => void;
-}
+  for (const [index, guideKey] of displaySequence.entries()) {
+    const guide = state.guides[guideKey];
+    if (!guide) continue;
 
-interface KnockGuideActivationLocationRule
-  extends GuideActivationLocationRuleData {
-  pattern: URLPattern;
-}
-
-export interface KnockGuide extends GuideData {
-  steps: KnockGuideStep[];
-  activation_location_rules: KnockGuideActivationLocationRule[];
-}
-
-type GetGuidesQueryParams = {
-  data?: string;
-  tenant?: string;
-  type?: string;
-};
-
-type GetGuidesResponse = {
-  entries: GuideData[];
-};
-
-export type GuideEngagementEventBaseParams = {
-  // Base params required for all engagement update events
-  message_id: string;
-  channel_id: string;
-  guide_key: string;
-  guide_id: string;
-  guide_step_ref: string;
-};
+    const affirmed = predicate(guide, { location, filters });
+    if (!affirmed) continue;
 
-type MarkAsSeenParams = GuideEngagementEventBaseParams & {
-  // Rendered step content seen by the recipient
-  content: GenericData;
-  // Target params
-  data?: GenericData;
-  tenant?: string;
-};
-type MarkAsInteractedParams = GuideEngagementEventBaseParams;
-type MarkAsArchivedParams = GuideEngagementEventBaseParams;
+    result.set(index, guide);
+  }
 
-type MarkGuideAsResponse = {
-  status: "ok";
+  result.metadata = { guideGroup: defaultGroup };
+  return result;
 };
 
-type SocketEventType = "guide.added" | "guide.updated" | "guide.removed";
-
-type SocketEventPayload<E extends SocketEventType, D> = {
-  topic: string;
-  event: E;
-  data: D;
+type PredicateOpts = {
+  location?: string | undefined;
+  filters?: SelectFilterParams | undefined;
 };
 
-type GuideAddedEvent = SocketEventPayload<
-  "guide.added",
-  { guide: GuideData; eligible: true }
->;
-
-type GuideUpdatedEvent = SocketEventPayload<
-  "guide.updated",
-  { guide: GuideData; eligible: boolean }
->;
-
-type GuideRemovedEvent = SocketEventPayload<
-  "guide.removed",
-  { guide: Pick<GuideData, "key"> }
->;
-
-type GuideSocketEvent = GuideAddedEvent | GuideUpdatedEvent | GuideRemovedEvent;
-
-//
-// Guides client
-//
-
-type QueryKey = string;
-
-type QueryStatus = {
-  status: "loading" | "ok" | "error";
-  error?: Error;
-};
+const predicate = (
+  guide: KnockGuide,
+  { location, filters = {} }: PredicateOpts,
+) => {
+  if (filters.type && filters.type !== guide.type) {
+    return false;
+  }
 
-type StoreState = {
-  guides: KnockGuide[];
-  queries: Record<QueryKey, QueryStatus>;
-  location: string | undefined;
-};
+  if (filters.key && filters.key !== guide.key) {
+    return false;
+  }
 
-type QueryFilterParams = Pick<GetGuidesQueryParams, "type">;
+  if (guide.steps.every((s) => !!s.message.archived_at)) {
+    return false;
+  }
 
-export type SelectFilterParams = {
-  key?: string;
-  type?: string;
-};
+  const locationRules = guide.activation_location_rules || [];
+
+  if (locationRules.length > 0 && location) {
+    const allowed = locationRules.reduce<boolean | undefined>((acc, rule) => {
+      // Any matched block rule prevails so no need to evaluate further
+      // as soon as there is one.
+      if (acc === false) return false;
+
+      // At this point we either have a matched allow rule (acc is true),
+      // or no matched rule found yet (acc is undefined).
+
+      switch (rule.directive) {
+        case "allow": {
+          // No need to evaluate more allow rules once we matched one
+          // since any matched allowed rule means allow.
+          if (acc === true) return true;
+
+          const matched = rule.pattern.test(location);
+          return matched ? true : undefined;
+        }
+
+        case "block": {
+          // Always test block rules (unless already matched to block)
+          // because they'd prevail over matched allow rules.
+          const matched = rule.pattern.test(location);
+          return matched ? false : acc;
+        }
+      }
+    }, undefined);
 
-export type TargetParams = {
-  data?: GenericData | undefined;
-  tenant?: string | undefined;
-};
+    if (!allowed) return false;
+  }
 
-type ConstructorOpts = {
-  trackLocationFromWindow?: boolean;
+  return true;
 };
 
 export class KnockGuideClient {
@@ -172,12 +140,25 @@ export class KnockGuideClient {
   private socket: Socket | undefined;
   private socketChannel: Channel | undefined;
   private socketChannelTopic: string;
-  private socketEventTypes = ["guide.added", "guide.updated", "guide.removed"];
+  private socketEventTypes = [
+    "guide.added",
+    "guide.updated",
+    "guide.removed",
+    "guide_group.added",
+    "guide_group.updated",
+  ];
 
   // Original history methods to monkey patch, or restore in cleanups.
   private pushStateFn: History["pushState"] | undefined;
   private replaceStateFn: History["replaceState"] | undefined;
 
+  // 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.
+  private stage: GroupStage | undefined;
+
+  private counterIntervalId: ReturnType<typeof setInterval> | undefined;
+
   constructor(
     readonly knock: Knock,
     readonly channelId: string,
@@ -191,9 +172,13 @@ export class KnockGuideClient {
       : undefined;
 
     this.store = new Store<StoreState>({
-      guides: [],
+      guideGroups: [],
+      guideGroupDisplayLogs: {},
+      guides: {},
       queries: {},
       location,
+      // Increment to update the state store and trigger re-selection.
+      counter: 0,
     });
 
     // In server environments we might not have a socket connection.
@@ -205,12 +190,42 @@ export class KnockGuideClient {
       this.listenForLocationChangesFromWindow();
     }
 
+    // Start the counter loop to increment at an interval.
+    this.startCounterInterval();
+
     this.knock.log("[Guide] Initialized a guide client");
   }
 
+  private incrementCounter() {
+    this.knock.log("[Guide] Incrementing the counter");
+    this.store.setState((state) => ({ ...state, counter: state.counter + 1 }));
+  }
+
+  private startCounterInterval() {
+    const {
+      throttleCheckInterval: delay = DEFAULT_COUNTER_INCREMENT_INTERVAL,
+    } = this.options;
+
+    this.counterIntervalId = setInterval(() => {
+      this.knock.log("[Guide] Counter interval tick");
+      if (this.stage && this.stage.status !== "closed") return;
+
+      this.incrementCounter();
+    }, delay);
+  }
+
+  private clearCounterInterval() {
+    if (this.counterIntervalId) {
+      clearInterval(this.counterIntervalId);
+      this.counterIntervalId = undefined;
+    }
+  }
+
   cleanup() {
     this.unsubscribe();
     this.removeEventListeners();
+    this.clearGroupStage();
+    this.clearCounterInterval();
   }
 
   async fetch(opts?: { filters?: QueryFilterParams }) {
@@ -240,12 +255,17 @@ export class KnockGuideClient {
       >(this.channelId, queryParams);
       queryStatus = { status: "ok" };
 
+      const {
+        entries,
+        guide_groups: groups,
+        guide_group_display_logs: guideGroupDisplayLogs,
+      } = data;
+
       this.store.setState((state) => ({
         ...state,
-        // 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: data.entries.map((g) => this.localCopy(g)),
+        guideGroups: groups?.length > 0 ? groups : [mockDefaultGroup(entries)],
+        guideGroupDisplayLogs,
+        guides: byKey(entries.map((g) => this.localCopy(g))),
         queries: { ...state.queries, [queryKey]: queryStatus },
       }));
     } catch (e) {
@@ -310,73 +330,242 @@ export class KnockGuideClient {
 
     switch (event) {
       case "guide.added":
-        return this.addGuide(payload);
+        return this.addOrReplaceGuide(payload);
 
       case "guide.updated":
         return data.eligible
-          ? this.replaceOrAddGuide(payload)
+          ? this.addOrReplaceGuide(payload)
           : this.removeGuide(payload);
 
       case "guide.removed":
         return this.removeGuide(payload);
 
+      case "guide_group.added":
+      case "guide_group.updated":
+        return this.addOrReplaceGuideGroup(payload);
+
       default:
         return;
     }
   }
 
+  setLocation(href: string) {
+    // Make sure to clear out the stage.
+    this.clearGroupStage();
+
+    this.store.setState((state) => ({ ...state, location: href }));
+  }
+
   //
   // Store selector
   //
 
-  select(state: StoreState, filters: SelectFilterParams = {}) {
-    return state.guides.filter((guide) => {
-      if (filters.type && filters.type !== guide.type) {
-        return false;
-      }
+  selectGuides(state: StoreState, filters: SelectFilterParams = {}) {
+    if (Object.keys(state.guides).length === 0) {
+      return [];
+    }
+    this.knock.log(`[Guide] Selecting guides for: ${formatFilters(filters)}`);
+
+    const result = select(state, filters);
+
+    if (result.size === 0) {
+      this.knock.log("[Guide] Selection returned zero result");
+      return [];
+    }
+
+    // Return all selected guides, since we cannot apply the one-at-a-time limit
+    // or throttle settings, but rather defer to the caller to decide which ones
+    // to render. Note
+    return [...result.values()];
+  }
+
+  selectGuide(state: StoreState, filters: SelectFilterParams = {}) {
+    if (Object.keys(state.guides).length === 0) {
+      return undefined;
+    }
+    this.knock.log(`[Guide] Selecting a guide for: ${formatFilters(filters)}`);
+
+    const result = select(state, filters);
+
+    if (result.size === 0) {
+      this.knock.log("[Guide] Selection returned zero result");
+      return undefined;
+    }
+
+    const [index, guide] = [...result][0]!;
+
+    // If a guide ignores the group limit, then return immediately to render
+    // always.
+    if (guide.bypass_global_group_limit) {
+      return guide;
+    }
 
-      if (filters.key && filters.key !== guide.key) {
-        return false;
+    // Check if inside the throttle window (i.e. throttled) and if so stop and
+    // return undefined.
+    const defaultGroup = findDefaultGroup(state.guideGroups);
+    const throttleWindowStartedAt =
+      state.guideGroupDisplayLogs[DEFAULT_GROUP_KEY];
+
+    if (
+      defaultGroup &&
+      defaultGroup.display_interval &&
+      throttleWindowStartedAt
+    ) {
+      const throttled = checkIfThrottled(
+        throttleWindowStartedAt,
+        defaultGroup.display_interval,
+      );
+      if (throttled) return undefined;
+    }
+
+    // Starting here to the end of this method represents the core logic of how
+    // "group stage" works. It provides a mechanism for 1) figuring out which
+    // guide components are about to render on a page, 2) determining which
+    // among them ranks highest in the configured display sequence, and 3)
+    // returning only the prevailing guide to render at a time.
+    //
+    // Imagine N number of components that use the `useGuide()` hook which
+    // calls this `selectGuide()` method, and the logic works like this:
+    // * The first time this method is called, we don't have an "open" group
+    //   stage, so we open one (this occurs when a new page/route is rendering).
+    //   * While it is open, we record which guide was selected and its order
+    //     index from each call, but we do NOT return any guide to render yet.
+    //   * When a group stage opens, it schedules a timer to close itself. How
+    //     long this timer waits is configurable. Note, `setTimeout` with 0
+    //     delay seems to work well for React apps, where we "yield" to React
+    //     for one render cycle and close the group right after.
+    // * When a group stage closes, we evaluate which guides were selected and
+    //   recorded, then determine the winning guide (i.e. the one with the
+    //   lowest order index value).
+    //   * Then increment the internal counter to trigger a store state update,
+    //     which allows `useGuide()` and `selectGuide()` to re-run. This second
+    //     round of `selectGuide()` calls, occurring when the group stage is
+    //     closed, results in returning the prevailing guide.
+    // * Whenever a user navigates to a new page, we repeat the same process
+    //   above.
+    // * There's a third status called "patch," which is for handling real-time
+    //   updates received from the API. It's similar to the "open" to "closed"
+    //   flow, except we keep the resolved guide in place while we recalculate.
+    //   This is done so that we don't cause flickers or CLS.
+    if (!this.stage) {
+      this.stage = this.openGroupStage(); // Assign here to make tsc happy
+    }
+
+    switch (this.stage.status) {
+      case "open": {
+        this.knock.log(`[Guide] Addng to the group stage: ${guide.key}`);
+        this.stage.ordered[index] = guide.key;
+        return undefined;
       }
 
-      const locationRules = guide.activation_location_rules || [];
-
-      if (locationRules.length > 0 && state.location) {
-        const allowed = locationRules.reduce<boolean | undefined>(
-          (acc, rule) => {
-            // Any matched block rule prevails so no need to evaluate further
-            // as soon as there is one.
-            if (acc === false) return false;
-
-            // At this point we either have a matched allow rule (acc is true),
-            // or no matched rule found yet (acc is undefined).
-
-            switch (rule.directive) {
-              case "allow": {
-                // No need to evaluate more allow rules once we matched one
-                // since any matched allowed rule means allow.
-                if (acc === true) return true;
-
-                const matched = rule.pattern.test(state.location);
-                return matched ? true : undefined;
-              }
-
-              case "block": {
-                // Always test block rules (unless already matched to block)
-                // because they'd prevail over matched allow rules.
-                const matched = rule.pattern.test(state.location);
-                return matched ? false : acc;
-              }
-            }
-          },
-          undefined,
-        );
+      case "patch": {
+        this.knock.log(`[Guide] Patching the group stage: ${guide.key}`);
+        this.stage.ordered[index] = guide.key;
+        return this.stage.resolved === guide.key ? guide : undefined;
+      }
 
-        if (!allowed) return false;
+      case "closed": {
+        return this.stage.resolved === guide.key ? guide : undefined;
       }
+    }
+  }
 
-      return true;
-    });
+  private openGroupStage() {
+    this.knock.log("[Guide] Opening a new group stage");
+
+    const {
+      orderResolutionDuration: delay = DEFAULT_ORDER_RESOLUTION_DURATION,
+    } = this.options;
+
+    const timeoutId = setTimeout(() => {
+      this.closePendingGroupStage();
+      this.incrementCounter();
+    }, delay);
+
+    this.stage = {
+      status: "open",
+      ordered: [],
+      timeoutId,
+    };
+
+    return this.stage;
+  }
+
+  // Close the current non-closed stage to resolve the prevailing guide up next
+  // for display amongst the ones that have been staged.
+  private closePendingGroupStage() {
+    if (!this.stage || this.stage.status === "closed") return;
+
+    this.knock.log("[Guide] Closing the current group stage");
+
+    // Should have been cleared already since this method should be called as a
+    // callback to a setTimeout, but just to be safe.
+    this.ensureClearTimeout();
+
+    this.stage = {
+      ...this.stage,
+      status: "closed",
+      resolved: this.stage.ordered.find((x) => x !== undefined),
+      timeoutId: null,
+    };
+
+    return 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.
+  private patchClosedGroupStage() {
+    if (this.stage?.status !== "closed") return;
+
+    this.knock.log("[Guide] Patching the current group stage");
+
+    const { orderResolutionDuration: delay = 0 } = this.options;
+
+    const timeoutId = setTimeout(() => {
+      this.closePendingGroupStage();
+      this.incrementCounter();
+    }, delay);
+
+    // Just to be safe.
+    this.ensureClearTimeout();
+
+    this.stage = {
+      ...this.stage,
+      status: "patch",
+      ordered: [],
+      timeoutId,
+    };
+
+    return this.stage;
+  }
+
+  private clearGroupStage() {
+    if (!this.stage) return;
+
+    this.knock.log("[Guide] Clearing the current group stage");
+
+    this.ensureClearTimeout();
+    this.stage = undefined;
+  }
+
+  private ensureClearTimeout() {
+    if (this.stage?.timeoutId) {
+      clearTimeout(this.stage.timeoutId);
+    }
+  }
+
+  // Test helper that opens and closes the group stage to return the select
+  // result immediately.
+  private _selectGuide(state: StoreState, filters: SelectFilterParams = {}) {
+    this.openGroupStage();
+
+    this.selectGuide(state, filters);
+    this.closePendingGroupStage();
+
+    return this.selectGuide(state, filters);
   }
 
   //
@@ -387,6 +576,8 @@ export class KnockGuideClient {
   //
 
   async markAsSeen(guide: GuideData, step: GuideStepData) {
+    if (step.message.seen_at) return;
+
     this.knock.log(
       `[Guide] Marking as seen (Guide key: ${guide.key}, Step ref:${step.ref})`,
     );
@@ -441,6 +632,8 @@ export class KnockGuideClient {
   }
 
   async markAsArchived(guide: GuideData, step: GuideStepData) {
+    if (step.message.archived_at) return;
+
     this.knock.log(
       `[Guide] Marking as archived (Guide key: ${guide.key}, Step ref:${step.ref})`,
     );
@@ -454,7 +647,10 @@ export class KnockGuideClient {
 
     this.knock.user.markGuideStepAs<MarkAsArchivedParams, MarkGuideAsResponse>(
       "archived",
-      params,
+      {
+        ...params,
+        unthrottled: guide.bypass_global_group_limit,
+      },
     );
 
     return updatedStep;
@@ -469,7 +665,15 @@ export class KnockGuideClient {
     const self = this;
 
     // Build a local copy with helper methods added.
-    const localGuide = { ...remoteGuide };
+    const localGuide = {
+      ...remoteGuide,
+      // Get the next unarchived step.
+      getStep() {
+        return this.steps.find((s) => !s.message.archived_at);
+      },
+    } as KnockGuide;
+
+    localGuide.getStep = localGuide.getStep.bind(localGuide);
 
     localGuide.steps = remoteGuide.steps.map(({ message, ...rest }) => {
       const localStep = {
@@ -508,7 +712,7 @@ export class KnockGuideClient {
         };
       });
 
-    return localGuide as KnockGuide;
+    return localGuide;
   }
 
   private buildQueryParams(filterParams: QueryFilterParams = {}) {
@@ -551,23 +755,41 @@ export class KnockGuideClient {
   ) {
     let updatedStep: KnockGuideStep | undefined;
 
+    // If we are marking as archived, clear the group stage so we can render
+    // the next guide in the group.
+    if (attrs.archived_at) {
+      this.clearGroupStage();
+    }
+
     this.store.setState((state) => {
-      const guides = state.guides.map((guide) => {
-        if (guide.key !== guideKey) return guide;
+      const guide = state.guides[guideKey];
+      if (!guide) return state;
 
-        const steps = guide.steps.map((step) => {
-          if (step.ref !== stepRef) return step;
+      const steps = guide.steps.map((step) => {
+        if (step.ref !== stepRef) return step;
 
-          // Mutate in place and maintain the same obj ref so to make it easier
-          // to use in hook deps.
-          step.message = { ...step.message, ...attrs };
-          updatedStep = step;
+        // Mutate in place and maintain the same obj ref so to make it easier
+        // to use in hook deps.
+        step.message = { ...step.message, ...attrs };
+        updatedStep = step;
 
-          return step;
-        });
-        return { ...guide, steps };
+        return step;
       });
-      return { ...state, guides };
+      // Mutate in place and maintain the same obj ref.
+      guide.steps = steps;
+      const guides = { ...state.guides, [guide.key]: guide };
+
+      // If the guide is subject to throttled settings and we are marking as
+      // archived, then update the display logs to start a new throttle window.
+      const guideGroupDisplayLogs =
+        attrs.archived_at && !guide.bypass_global_group_limit
+          ? {
+              ...state.guideGroupDisplayLogs,
+              [DEFAULT_GROUP_KEY]: attrs.archived_at,
+            }
+          : state.guideGroupDisplayLogs;
+
+      return { ...state, guides, guideGroupDisplayLogs };
     });
 
     return updatedStep;
@@ -586,37 +808,57 @@ export class KnockGuideClient {
     };
   }
 
-  private addGuide({ data }: GuideAddedEvent) {
+  private addOrReplaceGuide({ data }: GuideAddedEvent | GuideUpdatedEvent) {
+    this.patchClosedGroupStage();
+
     const guide = this.localCopy(data.guide);
 
     this.store.setState((state) => {
-      return { ...state, guides: sortGuides([...state.guides, guide]) };
+      const guides = { ...state.guides, [guide.key]: guide };
+
+      return { ...state, guides };
     });
   }
 
-  private replaceOrAddGuide({ data }: GuideUpdatedEvent) {
-    const guide = this.localCopy(data.guide);
+  private removeGuide({ data }: GuideUpdatedEvent | GuideRemovedEvent) {
+    this.patchClosedGroupStage();
 
     this.store.setState((state) => {
-      let replaced = false;
-
-      const guides = state.guides.map((g) => {
-        if (g.key !== guide.key) return g;
-        replaced = true;
-        return guide;
-      });
-
-      return {
-        ...state,
-        guides: replaced ? sortGuides(guides) : sortGuides([...guides, guide]),
-      };
+      const { [data.guide.key]: _, ...rest } = state.guides;
+      return { ...state, guides: rest };
     });
   }
 
-  private removeGuide({ data }: GuideUpdatedEvent | GuideRemovedEvent) {
+  private addOrReplaceGuideGroup({
+    data,
+  }: GuideGroupAddedEvent | GuideGroupUpdatedEvent) {
+    this.patchClosedGroupStage();
+
     this.store.setState((state) => {
-      const guides = state.guides.filter((g) => g.key !== data.guide.key);
-      return { ...state, guides };
+      // Currently we only support a single default global group, so we can just
+      // update the list with the added/updated group.
+      const guideGroups = [data.guide_group];
+
+      // A guide group event can include lists of unthrottled vs throttled guide
+      // keys which we can use to bulk update the guides in the store already.
+      const unthrottled = data.guide_group.display_sequence_unthrottled || [];
+      const throttled = data.guide_group.display_sequence_throttled || [];
+
+      let guides = state.guides;
+
+      guides = unthrottled.reduce((acc, key) => {
+        if (!acc[key]) return acc;
+        const guide = { ...acc[key], bypass_global_group_limit: true };
+        return { ...acc, [key]: guide };
+      }, guides);
+
+      guides = throttled.reduce((acc, key) => {
+        if (!acc[key]) return acc;
+        const guide = { ...acc[key], bypass_global_group_limit: false };
+        return { ...acc, [key]: guide };
+      }, guides);
+
+      return { ...state, guides, guideGroups };
     });
   }
 
@@ -626,8 +868,7 @@ export class KnockGuideClient {
     if (this.store.state.location === href) return;
 
     this.knock.log(`[Guide] Handle Location change: ${href}`);
-
-    this.store.setState((state) => ({ ...state, location: href }));
+    this.setLocation(href);
   };
 
   private listenForLocationChangesFromWindow() {