@knocklabs/client 0.21.1 → 0.21.3

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
 //
@@ -210,7 +232,10 @@ export type QueryStatus = {
 export type DebugState = {
   debugging?: boolean;
   forcedGuideKey?: string | null;
+  focusedGuideKeys?: Record<KnockGuide["key"], true>;
   previewSessionId?: string | null;
+  skipEngagementTracking?: boolean;
+  ignoreDisplayInterval?: boolean;
 };
 
 export type StoreState = {
@@ -237,6 +262,7 @@ export type SelectFilterParams = {
 
 export type SelectGuideOpts = {
   includeThrottled?: boolean;
+  recordSelectQuery?: boolean;
 };
 
 export type SelectGuidesOpts = SelectGuideOpts;
@@ -253,9 +279,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);
+    }
+  }
+}