@knocklabs/client 0.21.0 → 0.21.2

package/src/clients/guide/client.ts

@@ -7,7 +7,6 @@ import Knock from "../../knock";
 
 import {
   DEFAULT_GROUP_KEY,
-  SelectionResult,
   byKey,
   checkStateIfThrottled,
   findDefaultGroup,
@@ -46,6 +45,8 @@ import {
   SelectFilterParams,
   SelectGuideOpts,
   SelectGuidesOpts,
+  SelectQueryLimit,
+  SelectionResult,
   StepMessageState,
   StoreState,
   TargetParams,
@@ -150,41 +151,32 @@ const safeJsonParseDebugParams = (value: string): DebugState => {
   }
 };
 
-const select = (state: StoreState, filters: SelectFilterParams = {}) => {
+type SelectQueryMetadata = {
+  limit: SelectQueryLimit;
+  opts: SelectGuideOpts;
+};
+
+const select = (
+  state: StoreState,
+  filters: SelectFilterParams,
+  metadata: SelectQueryMetadata,
+) => {
   // A map of selected guides as values, with its order index as keys.
   const result = new SelectionResult();
 
   const defaultGroup = findDefaultGroup(state.guideGroups);
   if (!defaultGroup) return result;
 
-  const displaySequence = [...defaultGroup.display_sequence];
+  const displaySequence = defaultGroup.display_sequence;
   const location = state.location;
 
-  // If in debug mode, put the forced guide at the beginning of the display sequence.
-  if (state.debug.forcedGuideKey) {
-    const forcedKeyIndex = displaySequence.indexOf(state.debug.forcedGuideKey);
-    if (forcedKeyIndex > -1) {
-      displaySequence.splice(forcedKeyIndex, 1);
-    }
-    displaySequence.unshift(state.debug.forcedGuideKey);
-  }
-
   for (const [index, guideKey] of displaySequence.entries()) {
-    let guide = state.guides[guideKey];
-
-    // Use preview guide if it exists and matches the forced guide key
-    if (
-      state.debug.forcedGuideKey === guideKey &&
-      state.previewGuides[guideKey]
-    ) {
-      guide = state.previewGuides[guideKey];
-    }
-
+    const guide = state.previewGuides[guideKey] || state.guides[guideKey];
     if (!guide) continue;
 
-    const affirmed = predicate(guide, {
+    const affirmed = predicate(guide, filters, {
       location,
-      filters,
+      ineligibleGuides: state.ineligibleGuides,
       debug: state.debug,
     });
 
@@ -193,19 +185,20 @@ const select = (state: StoreState, filters: SelectFilterParams = {}) => {
     result.set(index, guide);
   }
 
-  result.metadata = { guideGroup: defaultGroup };
+  result.metadata = { guideGroup: defaultGroup, filters, ...metadata };
+
   return result;
 };
 
-type PredicateOpts = {
-  location?: string | undefined;
-  filters?: SelectFilterParams | undefined;
-  debug: DebugState;
-};
+type PredicateOpts = Pick<
+  StoreState,
+  "location" | "ineligibleGuides" | "debug"
+>;
 
 const predicate = (
   guide: KnockGuide,
-  { location, filters = {}, debug = {} }: PredicateOpts,
+  filters: SelectFilterParams,
+  { location, ineligibleGuides = {}, debug = {} }: PredicateOpts,
 ) => {
   if (filters.type && filters.type !== guide.type) {
     return false;
@@ -215,11 +208,16 @@ const predicate = (
     return false;
   }
 
-  // Bypass filtering if the debugged guide matches the given filters.
-  // This should always run AFTER checking the filters but BEFORE
-  // checking archived status and location rules.
-  if (debug.forcedGuideKey === guide.key) {
-    return true;
+  // If in debug mode with a forced guide key, bypass other filtering and always
+  // return true for that guide only. This should always run AFTER checking the
+  // filters but BEFORE checking archived status and location rules.
+  if (debug.forcedGuideKey) {
+    return debug.forcedGuideKey === guide.key;
+  }
+
+  const ineligible = ineligibleGuides[guide.key];
+  if (ineligible) {
+    return false;
   }
 
   if (!guide.active) {
@@ -230,6 +228,13 @@ const predicate = (
     return false;
   }
 
+  return checkActivatable(guide, location);
+};
+
+export const checkActivatable = (
+  guide: KnockGuide,
+  location: string | undefined,
+) => {
   const url = location ? newUrl(location) : undefined;
 
   const urlRules = guide.activation_url_rules || [];
@@ -283,18 +288,21 @@ export class KnockGuideClient {
   ) {
     const {
       trackLocationFromWindow = true,
+      // TODO(KNO-11523): Remove once we ship guide toolbar v2, and offload as
+      // much debugging specific logic and responsibilities to toolbar.
+      trackDebugParams = false,
       throttleCheckInterval = DEFAULT_COUNTER_INCREMENT_INTERVAL,
     } = options;
     const win = checkForWindow();
 
     const location = trackLocationFromWindow ? win?.location?.href : undefined;
-
-    const debug = detectDebugParams();
+    const debug = trackDebugParams ? detectDebugParams() : undefined;
 
     this.store = new Store<StoreState>({
       guideGroups: [],
       guideGroupDisplayLogs: {},
       guides: {},
+      ineligibleGuides: {},
       previewGuides: {},
       queries: {},
       location,
@@ -376,7 +384,12 @@ export class KnockGuideClient {
       >(this.channelId, queryParams);
       queryStatus = { status: "ok" };
 
-      const { entries, guide_groups: groups, guide_group_display_logs } = data;
+      const {
+        entries,
+        guide_groups: groups,
+        guide_group_display_logs,
+        ineligible_guides,
+      } = data;
 
       this.knock.log("[Guide] Loading fetched guides");
       this.store.setState((state) => ({
@@ -384,6 +397,7 @@ export class KnockGuideClient {
         guideGroups: groups?.length > 0 ? groups : [mockDefaultGroup(entries)],
         guideGroupDisplayLogs: guide_group_display_logs || {},
         guides: byKey(entries.map((g) => this.localCopy(g))),
+        ineligibleGuides: byKey(ineligible_guides || []),
         queries: { ...state.queries, [queryKey]: queryStatus },
       }));
     } catch (e) {
@@ -418,8 +432,9 @@ export class KnockGuideClient {
     const params = {
       ...this.targetParams,
       user_id: this.knock.userId,
-      force_all_guides: debugState.forcedGuideKey ? true : undefined,
-      preview_session_id: debugState.previewSessionId || undefined,
+      force_all_guides:
+        debugState?.forcedGuideKey || debugState?.debugging ? true : undefined,
+      preview_session_id: debugState?.previewSessionId || undefined,
     };
 
     const newChannel = this.socket.channel(this.socketChannelTopic, params);
@@ -484,6 +499,8 @@ export class KnockGuideClient {
   private handleSocketEvent(payload: GuideSocketEvent) {
     const { event, data } = payload;
 
+    // TODO(KNO-11489): Include an ineligible guide in the socket payload too
+    // and process it when handling socket events in real time.
     switch (event) {
       case "guide.added":
         return this.addOrReplaceGuide(payload);
@@ -565,6 +582,39 @@ export class KnockGuideClient {
     }
   }
 
+  setDebug(debugOpts?: Omit<DebugState, "debugging">) {
+    this.knock.log("[Guide] .setDebug()");
+    const shouldRefetch = !this.store.state.debug?.debugging;
+
+    this.store.setState((state) => ({
+      ...state,
+      debug: { ...debugOpts, debugging: true },
+    }));
+
+    if (shouldRefetch) {
+      this.knock.log(
+        `[Guide] Start debugging, refetching guides and resubscribing to the websocket channel`,
+      );
+      this.fetch();
+      this.subscribe();
+    }
+  }
+
+  unsetDebug() {
+    this.knock.log("[Guide] .unsetDebug()");
+    const shouldRefetch = this.store.state.debug?.debugging;
+
+    this.store.setState((state) => ({ ...state, debug: undefined }));
+
+    if (shouldRefetch) {
+      this.knock.log(
+        `[Guide] Stop debugging, refetching guides and resubscribing to the websocket channel`,
+      );
+      this.fetch();
+      this.subscribe();
+    }
+  }
+
   //
   // Store selector
   //
@@ -578,14 +628,35 @@ export class KnockGuideClient {
       `[Guide] .selectGuides (filters: ${formatFilters(filters)}; state: ${formatState(state)})`,
     );
 
-    const selectedGuide = this.selectGuide(state, filters, opts);
-    if (!selectedGuide) {
+    // 1. First, call selectGuide() using the same filters to ensure we have a
+    // group stage open and respect throttling. This isn't the real query, but
+    // rather it's a shortcut ahead of handling the actual query result below.
+    const selectedGuide = this.selectGuide(state, filters, {
+      ...opts,
+      // Don't record this result, not the actual query result we need.
+      recordSelectQuery: false,
+    });
+
+    // 2. Now make the actual select query with the provided filters and opts,
+    // and record the result (as needed). By default, we only record the result
+    // while in debugging.
+    const { recordSelectQuery = !!state.debug?.debugging } = opts;
+    const metadata: SelectQueryMetadata = {
+      limit: "all",
+      opts: { ...opts, recordSelectQuery },
+    };
+    const result = select(state, filters, metadata);
+    this.maybeRecordSelectResult(result);
+
+    // 3. Stop if there is not at least one guide to return.
+    if (!selectedGuide && !opts.includeThrottled) {
       return [];
     }
 
     // There should be at least one guide to return here now.
-    const guides = [...select(state, filters).values()];
+    const guides = [...result.values()];
 
+    // 4. If throttled, filter out any throttled guides.
     if (!opts.includeThrottled && checkStateIfThrottled(state)) {
       const unthrottledGuides = guides.filter(
         (g) => g.bypass_global_group_limit,
@@ -618,32 +689,6 @@ export class KnockGuideClient {
       return undefined;
     }
 
-    const result = select(state, filters);
-
-    if (result.size === 0) {
-      this.knock.log("[Guide] Selection found zero result");
-      return undefined;
-    }
-
-    const [index, guide] = [...result][0]!;
-    this.knock.log(
-      `[Guide] Selection found: \`${guide.key}\` (total: ${result.size})`,
-    );
-
-    // If a guide ignores the group limit, then return immediately to render
-    // always.
-    if (guide.bypass_global_group_limit) {
-      this.knock.log(`[Guide] Returning the unthrottled guide: ${guide.key}`);
-      return guide;
-    }
-
-    // Check if inside the throttle window (i.e. throttled) and if so stop and
-    // return undefined unless explicitly given the option to include throttled.
-    if (!opts.includeThrottled && checkStateIfThrottled(state)) {
-      this.knock.log(`[Guide] Throttling the selected guide: ${guide.key}`);
-      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
@@ -677,6 +722,35 @@ export class KnockGuideClient {
       this.stage = this.openGroupStage(); // Assign here to make tsc happy
     }
 
+    // Must come AFTER we ensure a group stage exists above, so we can record
+    // select queries. By default, we only record the result while in debugging.
+    const { recordSelectQuery = !!state.debug?.debugging } = opts;
+    const metadata: SelectQueryMetadata = {
+      limit: "one",
+      opts: { ...opts, recordSelectQuery },
+    };
+    const result = select(state, filters, metadata);
+    this.maybeRecordSelectResult(result);
+
+    if (result.size === 0) {
+      this.knock.log("[Guide] Selection found zero result");
+      return undefined;
+    }
+
+    const [index, guide] = [...result][0]!;
+    this.knock.log(
+      `[Guide] Selection found: \`${guide.key}\` (total: ${result.size})`,
+    );
+
+    // If a guide ignores the group limit, then return immediately to render
+    // always.
+    if (guide.bypass_global_group_limit) {
+      this.knock.log(`[Guide] Returning the unthrottled guide: ${guide.key}`);
+      return guide;
+    }
+
+    const throttled = !opts.includeThrottled && checkStateIfThrottled(state);
+
     switch (this.stage.status) {
       case "open": {
         this.knock.log(`[Guide] Adding to the group stage: ${guide.key}`);
@@ -686,8 +760,16 @@ export class KnockGuideClient {
 
       case "patch": {
         this.knock.log(`[Guide] Patching the group stage: ${guide.key}`);
+        // Refresh the ordered queue in the group stage while continuing to
+        // render the currently resolved guide while in patch window, so that
+        // we can re-resolve when the group stage closes.
         this.stage.ordered[index] = guide.key;
 
+        if (throttled) {
+          this.knock.log(`[Guide] Throttling the selected guide: ${guide.key}`);
+          return undefined;
+        }
+
         const ret = this.stage.resolved === guide.key ? guide : undefined;
         this.knock.log(
           `[Guide] Returning \`${ret?.key}\` (stage: ${formatGroupStage(this.stage)})`,
@@ -696,6 +778,11 @@ export class KnockGuideClient {
       }
 
       case "closed": {
+        if (throttled) {
+          this.knock.log(`[Guide] Throttling the selected guide: ${guide.key}`);
+          return undefined;
+        }
+
         const ret = this.stage.resolved === guide.key ? guide : undefined;
         this.knock.log(
           `[Guide] Returning \`${ret?.key}\` (stage: ${formatGroupStage(this.stage)})`,
@@ -705,6 +792,42 @@ export class KnockGuideClient {
     }
   }
 
+  // Record select query results by accumulating them by 1) key or type first,
+  // and then 2) "one" or "all".
+  private maybeRecordSelectResult(result: SelectionResult) {
+    if (!result.metadata) return;
+
+    const { opts, filters, limit } = result.metadata;
+    if (!opts.recordSelectQuery) return;
+    if (!filters.key && !filters.type) return;
+    if (!this.stage || this.stage.status === "closed") return;
+
+    // Deep merge to accumulate the results.
+    const queriedByKey = this.stage.results.key || {};
+    if (filters.key) {
+      queriedByKey[filters.key] = {
+        ...(queriedByKey[filters.key] || {}),
+        ...{ [limit]: result },
+      };
+    }
+    const queriedByType = this.stage.results.type || {};
+    if (filters.type) {
+      queriedByType[filters.type] = {
+        ...(queriedByType[filters.type] || {}),
+        ...{ [limit]: result },
+      };
+    }
+
+    this.stage = {
+      ...this.stage,
+      results: { key: queriedByKey, type: queriedByType },
+    };
+  }
+
+  getStage() {
+    return this.stage;
+  }
+
   private openGroupStage() {
     this.knock.log("[Guide] Opening a new group stage");
 
@@ -720,6 +843,7 @@ export class KnockGuideClient {
     this.stage = {
       status: "open",
       ordered: [],
+      results: {},
       timeoutId,
     };
 
@@ -736,17 +860,8 @@ export class KnockGuideClient {
     // callback to a setTimeout, but just to be safe.
     this.ensureClearTimeout();
 
-    // If in debug mode, try to resolve the forced guide, otherwise return the first non-undefined guide.
-    let resolved = undefined;
-    if (this.store.state.debug.forcedGuideKey) {
-      resolved = this.stage.ordered.find(
-        (x) => x === this.store.state.debug.forcedGuideKey,
-      );
-    }
-
-    if (!resolved) {
-      resolved = this.stage.ordered.find((x) => x !== undefined);
-    }
+    // Resolve to the first non-undefined guide in the stage.
+    const resolved = this.stage.ordered.find((x) => x !== undefined);
 
     this.knock.log(
       `[Guide] Closing the current group stage: resolved=${resolved}`,
@@ -937,7 +1052,7 @@ export class KnockGuideClient {
       // Get the next unarchived step.
       getStep() {
         // If debugging this guide, return the first step regardless of archive status
-        if (self.store.state.debug.forcedGuideKey === this.key) {
+        if (self.store.state.debug?.forcedGuideKey === this.key) {
           return this.steps[0];
         }
 
@@ -994,7 +1109,7 @@ export class KnockGuideClient {
 
     // Append debug params
     const debugState = this.store.state.debug;
-    if (debugState.forcedGuideKey) {
+    if (debugState?.forcedGuideKey || debugState?.debugging) {
       combinedParams.force_all_guides = true;
     }
 
@@ -1163,8 +1278,15 @@ export class KnockGuideClient {
 
     this.knock.log(`[Guide] Detected a location change: ${href}`);
 
+    if (!this.options.trackDebugParams) {
+      this.setLocation(href);
+      return;
+    }
+
+    // TODO(KNO-11523): Remove below once we ship toolbar v2.
+
     // If entering debug mode, fetch all guides.
-    const currentDebugParams = this.store.state.debug;
+    const currentDebugParams = this.store.state.debug || {};
     const newDebugParams = detectDebugParams();
 
     this.setLocation(href, { debug: newDebugParams });

package/src/clients/guide/helpers.ts

@@ -3,23 +3,11 @@ import {
   GuideActivationUrlRuleData,
   GuideData,
   GuideGroupData,
-  KnockGuide,
   KnockGuideActivationUrlPattern,
   SelectFilterParams,
   StoreState,
 } from "./types";
 
-// Extends the map class to allow having metadata on it, which is used to record
-// the guide group context for the selection result (though currently only a
-// default global group is supported).
-export class SelectionResult<K = number, V = KnockGuide> extends Map<K, V> {
-  metadata: { guideGroup: GuideGroupData } | undefined;
-
-  constructor() {
-    super();
-  }
-}
-
 export const formatGroupStage = (stage: GroupStage) => {
   return `status=${stage.status}, resolved=${stage.resolved}`;
 };

package/src/clients/guide/index.ts

@@ -1,9 +1,18 @@
-export { KnockGuideClient, DEBUG_QUERY_PARAMS } from "./client";
+export {
+  KnockGuideClient,
+  DEBUG_QUERY_PARAMS,
+  checkActivatable,
+} from "./client";
+export { checkStateIfThrottled } from "./helpers";
 export type {
   KnockGuide,
   KnockGuideStep,
+  GuideIneligibilityMarker as KnockGuideIneligibilityMarker,
   TargetParams as KnockGuideTargetParams,
   SelectFilterParams as KnockGuideFilterParams,
   SelectGuideOpts as KnockSelectGuideOpts,
   SelectGuidesOpts as KnockSelectGuidesOpts,
+  StoreState as KnockGuideClientStoreState,
+  GroupStage as KnockGuideClientGroupStage,
+  SelectionResult as KnockGuideSelectionResult,
 } from "./types";

package/src/clients/guide/types.ts

@@ -1,5 +1,27 @@
 import { GenericData } from "@knocklabs/types";
 
+// i.e. useGuide vs useGuides
+export type SelectQueryLimit = "one" | "all";
+
+type SelectionResultMetadata = {
+  guideGroup: GuideGroupData;
+  // Additional info about the underlying select query behind the result.
+  filters: SelectFilterParams;
+  limit: SelectQueryLimit;
+  opts: SelectGuideOpts;
+};
+
+// Extends the map class to allow having metadata on it, which is used to record
+// the guide group context for the selection result (though currently only a
+// default global group is supported).
+export class SelectionResult<K = number, V = KnockGuide> extends Map<K, V> {
+  metadata: SelectionResultMetadata | undefined;
+
+  constructor() {
+    super();
+  }
+}
+
 //
 // Fetch guides API
 //
@@ -65,6 +87,19 @@ export interface GuideGroupData {
   updated_at: string;
 }
 
+type GuideIneligibilityReason =
+  | "guide_not_active"
+  | "marked_as_archived"
+  | "target_conditions_not_met"
+  | "not_in_target_audience";
+
+export type GuideIneligibilityMarker = {
+  __typename: "GuideIneligibilityMarker";
+  key: KnockGuide["key"];
+  reason: GuideIneligibilityReason;
+  message: string;
+};
+
 export type GetGuidesQueryParams = {
   data?: string;
   tenant?: string;
@@ -76,6 +111,7 @@ export type GetGuidesResponse = {
   entries: GuideData[];
   guide_groups: GuideGroupData[];
   guide_group_display_logs: Record<GuideGroupData["key"], string>;
+  ineligible_guides: GuideIneligibilityMarker[];
 };
 
 //
@@ -194,6 +230,7 @@ export type QueryStatus = {
 };
 
 export type DebugState = {
+  debugging?: boolean;
   forcedGuideKey?: string | null;
   previewSessionId?: string | null;
 };
@@ -202,11 +239,15 @@ export type StoreState = {
   guideGroups: GuideGroupData[];
   guideGroupDisplayLogs: Record<GuideGroupData["key"], string>;
   guides: Record<KnockGuide["key"], KnockGuide>;
+  ineligibleGuides: Record<
+    GuideIneligibilityMarker["key"],
+    GuideIneligibilityMarker
+  >;
   previewGuides: Record<KnockGuide["key"], KnockGuide>;
   queries: Record<QueryKey, QueryStatus>;
   location: string | undefined;
   counter: number;
-  debug: DebugState;
+  debug?: DebugState;
 };
 
 export type QueryFilterParams = Pick<GetGuidesQueryParams, "type">;
@@ -218,6 +259,7 @@ export type SelectFilterParams = {
 
 export type SelectGuideOpts = {
   includeThrottled?: boolean;
+  recordSelectQuery?: boolean;
 };
 
 export type SelectGuidesOpts = SelectGuideOpts;
@@ -229,13 +271,25 @@ export type TargetParams = {
 
 export type ConstructorOpts = {
   trackLocationFromWindow?: boolean;
+  trackDebugParams?: boolean;
   orderResolutionDuration?: number;
   throttleCheckInterval?: number;
 };
 
+type SelectionResultByLimit = {
+  one?: SelectionResult;
+  all?: SelectionResult;
+};
+
+type RecordedSelectionResults = {
+  key?: Record<KnockGuide["key"], SelectionResultByLimit>;
+  type?: Record<KnockGuide["type"], SelectionResultByLimit>;
+};
+
 export type GroupStage = {
   status: "open" | "closed" | "patch";
   ordered: Array<KnockGuide["key"]>;
   resolved?: KnockGuide["key"];
   timeoutId: ReturnType<typeof setTimeout> | null;
+  results: RecordedSelectionResults;
 };

package/src/helpers.ts

@@ -4,3 +4,42 @@ const uuidRegex =
 export function isValidUuid(uuid: string) {
   return uuidRegex.test(uuid);
 }
+
+/**
+ * Exponential backoff with full jitter and a minimum delay floor.
+ *
+ * - Uses exponential growth capped at maxDelayMs
+ * - Applies full jitter to spread retries uniformly across the window
+ * - Enforces a minimum delay to avoid tight retry loops
+ *
+ * Example (baseDelayMs = 1000):
+ *   Try 1:   250ms – 1,000ms
+ *   Try 2:   250ms – 2,000ms
+ *   Try 3:   250ms – 4,000ms
+ *   Try 4:   250ms – 8,000ms
+ *   Try 5+:  250ms – maxDelayMs
+ */
+export function exponentialBackoffFullJitter(
+  tries: number,
+  {
+    baseDelayMs,
+    maxDelayMs,
+    minDelayMs = 250,
+  }: {
+    baseDelayMs: number;
+    maxDelayMs: number;
+    minDelayMs?: number;
+  },
+): number {
+  const exponentialDelay = Math.min(
+    maxDelayMs,
+    baseDelayMs * Math.pow(2, Math.max(0, tries - 1)),
+  );
+
+  if (exponentialDelay <= minDelayMs) {
+    return minDelayMs;
+  }
+
+  const jitterRange = exponentialDelay - minDelayMs;
+  return minDelayMs + Math.floor(Math.random() * jitterRange);
+}

package/src/interfaces.ts

@@ -9,6 +9,8 @@ export interface KnockOptions {
   host?: string;
   logLevel?: LogLevel;
   branch?: string;
+  /** Automatically disconnect the socket when the page is hidden and reconnect when visible. Defaults to `true`. */
+  disconnectOnPageHidden?: boolean;
 }
 
 export interface KnockObject<T = GenericData> {