@knocklabs/client 0.21.1 → 0.21.2

package/src/api.ts

@@ -2,11 +2,16 @@ import axios, { AxiosError, AxiosInstance, AxiosRequestConfig } from "axios";
 import axiosRetry from "axios-retry";
 import { Socket } from "phoenix";
 
+import { exponentialBackoffFullJitter } from "./helpers";
+import { PageVisibilityManager } from "./pageVisibility";
+
 type ApiClientOptions = {
   host: string;
   apiKey: string;
   userToken: string | undefined;
   branch?: string;
+  /** Automatically disconnect the socket when the page is hidden and reconnect when visible. Defaults to `true`. */
+  disconnectOnPageHidden?: boolean;
 };
 
 export interface ApiResponse {
@@ -26,6 +31,7 @@ class ApiClient {
   private axiosClient: AxiosInstance;
 
   public socket: Socket | undefined;
+  private pageVisibility: PageVisibilityManager | undefined;
 
   constructor(options: ApiClientOptions) {
     this.host = options.host;
@@ -53,7 +59,23 @@ class ApiClient {
           api_key: this.apiKey,
           branch_slug: this.branch,
         },
+        reconnectAfterMs: (tries: number) => {
+          return exponentialBackoffFullJitter(tries, {
+            baseDelayMs: 1000,
+            maxDelayMs: 30_000,
+          });
+        },
+        rejoinAfterMs: (tries: number) => {
+          return exponentialBackoffFullJitter(tries, {
+            baseDelayMs: 1000,
+            maxDelayMs: 60_000,
+          });
+        },
       });
+
+      if (options.disconnectOnPageHidden !== false) {
+        this.pageVisibility = new PageVisibilityManager(this.socket);
+      }
     }
 
     axiosRetry(this.axiosClient, {
@@ -87,6 +109,14 @@ class ApiClient {
     }
   }
 
+  teardown() {
+    this.pageVisibility?.teardown();
+
+    if (this.socket?.isConnected()) {
+      this.socket.disconnect();
+    }
+  }
+
   private canRetryRequest(error: AxiosError) {
     // Retry Network Errors.
     if (axiosRetry.isNetworkError(error)) {

package/src/clients/feed/feed.ts

@@ -41,8 +41,6 @@ const feedClientDefaults: Pick<FeedClientOptions, "archived" | "mode"> = {
   mode: "compact",
 };
 
-const DEFAULT_DISCONNECT_DELAY = 2000;
-
 const CLIENT_REF_ID_PREFIX = "client_";
 
 class Feed {
@@ -53,10 +51,7 @@ class Feed {
   private userFeedId: string;
   private broadcaster: EventEmitter;
   private broadcastChannel!: BroadcastChannel | null;
-  private disconnectTimer: ReturnType<typeof setTimeout> | null = null;
   private hasSubscribedToRealTimeUpdates: boolean = false;
-  private visibilityChangeHandler: () => void = () => {};
-  private visibilityChangeListenerConnected: boolean = false;
 
   // The raw store instance, used for binding in React and other environments
   public store: FeedStore;
@@ -117,13 +112,6 @@ class Feed {
 
     this.socketManager?.leave(this);
 
-    this.tearDownVisibilityListeners();
-
-    if (this.disconnectTimer) {
-      clearTimeout(this.disconnectTimer);
-      this.disconnectTimer = null;
-    }
-
     if (this.broadcastChannel) {
       this.broadcastChannel.close();
     }
@@ -553,8 +541,6 @@ class Feed {
       __loadingType: undefined,
       __fetchSource: undefined,
       __experimentalCrossBrowserUpdates: undefined,
-      auto_manage_socket_connection: undefined,
-      auto_manage_socket_connection_delay: undefined,
     };
 
     const result = await this.knock.client().makeRequest({
@@ -815,10 +801,6 @@ class Feed {
     // In server environments we might not have a socket connection
     if (!this.socketManager) return;
 
-    if (this.defaultOptions.auto_manage_socket_connection) {
-      this.setUpVisibilityListeners();
-    }
-
     // If we're initializing but they have previously opted to listen to real-time updates
     // then we will automatically reconnect on their behalf
     if (this.hasSubscribedToRealTimeUpdates && this.knock.isAuthenticated()) {
@@ -838,33 +820,6 @@ class Feed {
     }
   }
 
-  /**
-   * Listen for changes to document visibility and automatically disconnect
-   * or reconnect the socket after a delay
-   */
-  private setUpVisibilityListeners() {
-    if (
-      typeof document === "undefined" ||
-      this.visibilityChangeListenerConnected
-    ) {
-      return;
-    }
-
-    this.visibilityChangeHandler = this.handleVisibilityChange.bind(this);
-    this.visibilityChangeListenerConnected = true;
-    document.addEventListener("visibilitychange", this.visibilityChangeHandler);
-  }
-
-  private tearDownVisibilityListeners() {
-    if (typeof document === "undefined") return;
-
-    document.removeEventListener(
-      "visibilitychange",
-      this.visibilityChangeHandler,
-    );
-    this.visibilityChangeListenerConnected = false;
-  }
-
   private emitEvent(
     type:
       | MessageEngagementStatus
@@ -882,34 +837,6 @@ class Feed {
     // Internal events only need `items:`
     this.broadcastOverChannel(`items:${type}`, { items });
   }
-
-  private handleVisibilityChange() {
-    const disconnectDelay =
-      this.defaultOptions.auto_manage_socket_connection_delay ??
-      DEFAULT_DISCONNECT_DELAY;
-
-    const client = this.knock.client();
-
-    if (document.visibilityState === "hidden") {
-      // When the tab is hidden, clean up the socket connection after a delay
-      this.disconnectTimer = setTimeout(() => {
-        client.socket?.disconnect();
-        this.disconnectTimer = null;
-      }, disconnectDelay);
-    } else if (document.visibilityState === "visible") {
-      // When the tab is visible, clear the disconnect timer if active to cancel disconnecting
-      // This handles cases where the tab is only briefly hidden to avoid unnecessary disconnects
-      if (this.disconnectTimer) {
-        clearTimeout(this.disconnectTimer);
-        this.disconnectTimer = null;
-      }
-
-      // If the socket is not connected, try to reconnect
-      if (!client.socket?.isConnected()) {
-        client.socket?.connect();
-      }
-    }
-  }
 }
 
 export default Feed;

package/src/clients/feed/interfaces.ts

@@ -34,11 +34,6 @@ export interface FeedClientOptions {
   trigger_data?: TriggerData;
   // Optionally enable cross browser feed updates for this feed
   __experimentalCrossBrowserUpdates?: boolean;
-  // Optionally automatically manage socket connections on changes to tab visibility (defaults to `false`)
-  auto_manage_socket_connection?: boolean;
-  // Optionally set the delay amount in milliseconds when automatically disconnecting sockets from inactive tabs (defaults to `2000`)
-  // Requires `auto_manage_socket_connection` to be `true`
-  auto_manage_socket_connection_delay?: number;
   // Optionally scope notifications to a given date range
   inserted_at_date_range?: {
     // Optionally set the start date with a string in ISO 8601 format
@@ -88,8 +83,6 @@ export type FetchFeedOptionsForRequest = Omit<
   __loadingType: undefined;
   __fetchSource: undefined;
   __experimentalCrossBrowserUpdates: undefined;
-  auto_manage_socket_connection: undefined;
-  auto_manage_socket_connection_delay: undefined;
 };
 
 export interface ContentBlockBase {

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,7 +151,16 @@ 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();
 
@@ -175,7 +185,8 @@ const select = (state: StoreState, filters: SelectFilterParams = {}) => {
     result.set(index, guide);
   }
 
-  result.metadata = { guideGroup: defaultGroup };
+  result.metadata = { guideGroup: defaultGroup, filters, ...metadata };
+
   return result;
 };
 
@@ -617,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,
@@ -657,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
@@ -716,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}`);
@@ -725,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)})`,
@@ -735,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)})`,
@@ -744,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");
 
@@ -759,6 +843,7 @@ export class KnockGuideClient {
     this.stage = {
       status: "open",
       ordered: [],
+      results: {},
       timeoutId,
     };
 

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

@@ -3,6 +3,7 @@ export {
   DEBUG_QUERY_PARAMS,
   checkActivatable,
 } from "./client";
+export { checkStateIfThrottled } from "./helpers";
 export type {
   KnockGuide,
   KnockGuideStep,
@@ -12,4 +13,6 @@ export type {
   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
 //
@@ -237,6 +259,7 @@ export type SelectFilterParams = {
 
 export type SelectGuideOpts = {
   includeThrottled?: boolean;
+  recordSelectQuery?: boolean;
 };
 
 export type SelectGuidesOpts = SelectGuideOpts;
@@ -253,9 +276,20 @@ export type ConstructorOpts = {
   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> {

package/src/knock.ts

@@ -26,6 +26,7 @@ class Knock {
   public userToken?: string;
   public logLevel?: LogLevel;
   public readonly branch?: string;
+  private readonly disconnectOnPageHidden?: boolean;
   private tokenExpirationTimer: ReturnType<typeof setTimeout> | null = null;
   readonly feeds = new FeedClient(this);
   readonly objects = new ObjectClient(this);
@@ -42,6 +43,7 @@ class Knock {
     this.host = options.host || DEFAULT_HOST;
     this.logLevel = options.logLevel;
     this.branch = options.branch || undefined;
+    this.disconnectOnPageHidden = options.disconnectOnPageHidden;
 
     this.log("Initialized Knock instance");
 
@@ -170,9 +172,7 @@ class Knock {
     if (this.tokenExpirationTimer) {
       clearTimeout(this.tokenExpirationTimer);
     }
-    if (this.apiClient?.socket && this.apiClient.socket.isConnected()) {
-      this.apiClient.socket.disconnect();
-    }
+    this.apiClient?.teardown();
   }
 
   log(message: string, force = false) {
@@ -190,6 +190,7 @@ class Knock {
       host: this.host,
       userToken: this.userToken,
       branch: this.branch,
+      disconnectOnPageHidden: this.disconnectOnPageHidden,
     });
   }
 

package/src/pageVisibility.ts

@@ -0,0 +1,70 @@
+import type { Socket } from "phoenix";
+
+const DEFAULT_DISCONNECT_DELAY_MS = 30_000;
+
+/**
+ * Disconnects the socket after a delay when the page becomes hidden,
+ * and reconnects when it becomes visible again. This avoids holding
+ * open connections for background tabs that aren't being viewed.
+ *
+ * The delay prevents unnecessary disconnects during brief tab switches.
+ * Phoenix channels automatically rejoin after reconnecting.
+ */
+export class PageVisibilityManager {
+  private disconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private wasConnected = false;
+
+  constructor(
+    private socket: Socket,
+    private disconnectDelayMs: number = DEFAULT_DISCONNECT_DELAY_MS,
+  ) {
+    if (typeof document !== "undefined") {
+      document.addEventListener("visibilitychange", this.onVisibilityChange);
+    }
+  }
+
+  private onVisibilityChange = () => {
+    if (document.hidden) {
+      this.scheduleDisconnect();
+    } else {
+      this.reconnect();
+    }
+  };
+
+  private scheduleDisconnect() {
+    this.clearTimer();
+
+    this.disconnectTimer = setTimeout(() => {
+      this.disconnectTimer = null;
+
+      if (this.socket.isConnected()) {
+        this.wasConnected = true;
+        this.socket.disconnect();
+      }
+    }, this.disconnectDelayMs);
+  }
+
+  private reconnect() {
+    this.clearTimer();
+
+    if (this.wasConnected) {
+      this.wasConnected = false;
+      this.socket.connect();
+    }
+  }
+
+  private clearTimer() {
+    if (this.disconnectTimer) {
+      clearTimeout(this.disconnectTimer);
+      this.disconnectTimer = null;
+    }
+  }
+
+  teardown() {
+    this.clearTimer();
+
+    if (typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", this.onVisibilityChange);
+    }
+  }
+}