feat: include force_all_guides param on socket connection when in debug mode (#723)

### Description
Include force_all_guides param on Guides socket channel. Resubscribes when exiting/entering debug mode.

### Checklist
- [x] Tests have been added for new features or major refactors to existing features.

Author: connorlindsey

.changeset/proud-donkeys-mate.md

@@ -0,0 +1,7 @@
+---
+"@knocklabs/react-core": minor
+"@knocklabs/client": minor
+"@knocklabs/react": minor
+---
+
+feat(beta): add support for basic guide debugging

packages/client/src/clients/guide/client.ts

@@ -341,7 +341,13 @@ export class KnockGuideClient {
     }
 
     // Join the channel topic and subscribe to supported events.
-    const params = { ...this.targetParams, user_id: this.knock.userId };
+    const debugState = this.store.state.debug;
+    const params = {
+      ...this.targetParams,
+      user_id: this.knock.userId,
+      force_all_guides: debugState.forcedGuideKey ? true : undefined,
+    };
+
     const newChannel = this.socket.channel(this.socketChannelTopic, params);
 
     for (const eventType of this.socketEventTypes) {
@@ -978,16 +984,22 @@ export class KnockGuideClient {
 
     this.knock.log(`[Guide] Handle Location change: ${href}`);
 
+    // If entering debug mode, fetch all guides.
+    const currentDebugParams = this.store.state.debug;
     const newDebugParams = detectDebugParams();
     this.setLocation(href, { debug: newDebugParams });
 
-    // If entering debug mode, fetch all guides.
-    const currentDebugParams = this.store.state.debug;
-    if (!currentDebugParams.forcedGuideKey && !!newDebugParams.forcedGuideKey) {
+    // If entering/exiting debug mode, refetch guides and resubscribe to the
+    // websocket channel.
+    if (
+      Boolean(currentDebugParams.forcedGuideKey) !==
+      Boolean(newDebugParams.forcedGuideKey)
+    ) {
       this.knock.log(
-        `[Guide] Entering debug mode for key: ${newDebugParams.forcedGuideKey}`,
+        `[Guide] ${newDebugParams.forcedGuideKey ? "Entering" : "Exiting"} debug mode`,
       );
       this.fetch();
+      this.subscribe();
     }
   };
 

packages/client/test/clients/guide/guide.test.ts

@@ -450,6 +450,52 @@ describe("KnockGuideClient", () => {
       expect(mockChannel.off).toHaveBeenCalled();
       expect(mockChannel.leave).toHaveBeenCalled();
     });
+
+    test("subscribe includes force_all_guides when debug state has forcedGuideKey", () => {
+      const mockChannel = {
+        join: vi.fn().mockReturnValue({
+          receive: vi.fn().mockReturnValue({
+            receive: vi.fn().mockReturnValue({
+              receive: vi.fn(),
+            }),
+          }),
+        }),
+        on: vi.fn(),
+        off: vi.fn(),
+        leave: vi.fn(),
+        state: "closed",
+      };
+
+      const mockSocket = {
+        channel: vi.fn().mockReturnValue(mockChannel),
+        isConnected: vi.fn().mockReturnValue(true),
+        connect: vi.fn(),
+      };
+
+      mockApiClient.socket = mockSocket as unknown as Socket;
+      vi.mocked(mockKnock.client).mockReturnValue(mockApiClient as ApiClient);
+
+      const client = new KnockGuideClient(
+        mockKnock,
+        channelId,
+        defaultTargetParams,
+      );
+
+      // Set debug state with forced guide key
+      client.store.state.debug = { forcedGuideKey: "test_guide" };
+
+      client.subscribe();
+
+      expect(mockSocket.channel).toHaveBeenCalledWith(
+        `guides:${channelId}`,
+        expect.objectContaining({
+          user_id: mockKnock.userId,
+          data: defaultTargetParams.data,
+          tenant: defaultTargetParams.tenant,
+          force_all_guides: true,
+        }),
+      );
+    });
   });
 
   describe("guide operations", () => {
@@ -1904,6 +1950,68 @@ describe("KnockGuideClient", () => {
       expect(windowWithHistory.history.pushState).toBe(originalPushState);
       expect(windowWithHistory.history.replaceState).toBe(originalReplaceState);
     });
+
+    test("handleLocationChange calls subscribe when entering debug mode", () => {
+      vi.stubGlobal("window", {
+        ...mockWindow,
+        location: {
+          href: "https://example.com/dashboard?knock_guide_key=test_guide",
+          search: "?knock_guide_key=test_guide",
+        },
+      });
+
+      const client = new KnockGuideClient(
+        mockKnock,
+        channelId,
+        {},
+        { trackLocationFromWindow: true },
+      );
+
+      client.store.state.debug = { forcedGuideKey: null };
+      client.store.state.location = "https://example.com/dashboard";
+
+      const subscribeSpy = vi
+        .spyOn(client, "subscribe")
+        .mockImplementation(() => {});
+
+      const fetchSpy = vi
+        .spyOn(client, "fetch")
+        .mockImplementation(() => Promise.resolve({ status: "ok" }));
+
+      client["handleLocationChange"]();
+
+      expect(fetchSpy).toHaveBeenCalled();
+      expect(subscribeSpy).toHaveBeenCalled();
+    });
+
+    test("handleLocationChange calls subscribe when exiting debug mode", () => {
+      vi.stubGlobal("window", {
+        ...mockWindow,
+        location: {
+          href: "https://example.com/dashboard",
+          search: "",
+        },
+      });
+
+      const client = new KnockGuideClient(
+        mockKnock,
+        channelId,
+        {},
+        { trackLocationFromWindow: true },
+      );
+
+      client.store.state.debug = { forcedGuideKey: "test_guide" };
+      client.store.state.location =
+        "https://example.com/dashboard?knock_guide_key=test_guide";
+
+      const subscribeSpy = vi
+        .spyOn(client, "subscribe")
+        .mockImplementation(() => {});
+
+      client["handleLocationChange"]();
+
+      expect(subscribeSpy).toHaveBeenCalled();
+    });
   });
 
   describe("private methods", () => {