feat: adds option for user identification control (#744)

Author: kylemcd

.changeset/cool-shrimps-cough.md

@@ -0,0 +1,6 @@
+---
+"@knocklabs/react-core": minor
+"@knocklabs/client": minor
+---
+
+feat: adds `identificationStrategy` option for user identification control

packages/client/src/interfaces.ts

@@ -54,6 +54,7 @@ export type UserTokenExpiringCallback = (
 export interface AuthenticateOptions {
   onUserTokenExpiring?: UserTokenExpiringCallback;
   timeBeforeExpirationInMs?: number;
+  identificationStrategy?: "inline" | "skip";
 }
 
 export interface BulkOperation {

packages/client/src/knock.ts

@@ -86,6 +86,7 @@ class Knock {
     let reinitializeApi = false;
     const currentApiClient = this.apiClient;
     const userId = this.getUserId(userIdOrUserWithProperties);
+    const identificationStrategy = options?.identificationStrategy || "inline";
 
     // If we've previously been initialized and the values have now changed, then we
     // need to reinitialize any stateful connections we have
@@ -120,11 +121,20 @@ class Knock {
       this.log("Reinitialized real-time connections");
     }
 
-    // Inline identify the user if we've been given an object with an id.
+    // We explicitly skip the inline identification if the strategy is set to "skip"
+    if (identificationStrategy === "skip") {
+      this.log("Skipping inline user identification");
+      return;
+    }
+
+    // Inline identify the user if we've been given an object with an id
+    // and the strategy is set to "inline".
     if (
+      identificationStrategy === "inline" &&
       typeof userIdOrUserWithProperties === "object" &&
       userIdOrUserWithProperties?.id
     ) {
+      this.log(`Identifying user ${userIdOrUserWithProperties.id} inline`);
       const { id, ...properties } = userIdOrUserWithProperties;
       this.user.identify(properties);
     }

packages/client/test/knock.test.ts

@@ -195,6 +195,118 @@ describe("Knock Client", () => {
     });
   });
 
+  describe("Inline identification strategy", () => {
+    test("defaults to inline identification when no strategy is specified", () => {
+      const knock = new Knock("pk_test_12345");
+      const identify = vi.spyOn(knock.user, "identify");
+
+      knock.authenticate(
+        { id: "user_123", name: "John Doe", email: "john@example.com" },
+        "token_456",
+      );
+
+      expect(identify).toHaveBeenCalledWith({
+        name: "John Doe",
+        email: "john@example.com",
+      });
+    });
+
+    test("performs inline identification when strategy is explicitly set to 'inline'", () => {
+      const knock = new Knock("pk_test_12345");
+      const identify = vi.spyOn(knock.user, "identify");
+
+      knock.authenticate(
+        { id: "user_123", name: "John Doe", email: "john@example.com" },
+        "token_456",
+        {
+          identificationStrategy: "inline",
+        },
+      );
+
+      expect(identify).toHaveBeenCalledWith({
+        name: "John Doe",
+        email: "john@example.com",
+      });
+    });
+
+    test("skips inline identification when strategy is set to 'skip'", () => {
+      const knock = new Knock("pk_test_12345");
+      const identify = vi.spyOn(knock.user, "identify");
+
+      knock.authenticate(
+        { id: "user_123", name: "John Doe", email: "john@example.com" },
+        "token_456",
+        {
+          identificationStrategy: "skip",
+        },
+      );
+
+      expect(identify).not.toHaveBeenCalled();
+    });
+
+    test("does not identify when authenticating with string userId regardless of strategy", () => {
+      const knock = new Knock("pk_test_12345");
+      const identify = vi.spyOn(knock.user, "identify");
+
+      knock.authenticate("user_123", "token_456", {
+        identificationStrategy: "inline",
+      });
+
+      expect(identify).not.toHaveBeenCalled();
+    });
+
+    test("does not identify with string userId when strategy is 'skip'", () => {
+      const knock = new Knock("pk_test_12345");
+      const identify = vi.spyOn(knock.user, "identify");
+
+      knock.authenticate("user_123", "token_456", {
+        identificationStrategy: "skip",
+      });
+
+      expect(identify).not.toHaveBeenCalled();
+    });
+
+    test("logs appropriate message when skipping identification", () => {
+      const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+      try {
+        const knock = new Knock("pk_test_12345", { logLevel: "debug" });
+        const identify = vi.spyOn(knock.user, "identify");
+
+        knock.authenticate({ id: "user_123", name: "John Doe" }, "token_456", {
+          identificationStrategy: "skip",
+        });
+
+        expect(consoleSpy).toHaveBeenCalledWith(
+          "[Knock] Skipping inline user identification",
+        );
+        expect(identify).not.toHaveBeenCalled();
+      } finally {
+        consoleSpy.mockRestore();
+      }
+    });
+
+    test("logs appropriate message when performing inline identification", () => {
+      const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+      try {
+        const knock = new Knock("pk_test_12345", { logLevel: "debug" });
+        const identify = vi.spyOn(knock.user, "identify");
+
+        knock.authenticate({ id: "user_123", name: "John Doe" }, "token_456", {
+          identificationStrategy: "inline",
+        });
+
+        expect(consoleSpy).toHaveBeenCalledWith(
+          "[Knock] Identifying user user_123 inline",
+        );
+        expect(identify).toHaveBeenCalled();
+      } finally {
+        consoleSpy.mockRestore();
+      }
+    });
+  });
+
   describe("Client Management", () => {
     test("provides API client after setup", () => {
       const { knock, mockApiClient } = createMockKnock();

packages/react-core/src/modules/core/context/KnockProvider.tsx

@@ -37,9 +37,11 @@ export type KnockProviderProps = {
        */
       userId: Knock["userId"];
       user?: never;
+      identificationStrategy?: never;
     }
   | {
       user: UserWithProperties;
+      identificationStrategy?: AuthenticateOptions["identificationStrategy"];
       /**
        * @deprecated The `userId` prop is deprecated and will be removed in a future version.
        * Please pass the `user` prop instead containing an `id` value.
@@ -61,6 +63,7 @@ export const KnockProvider: React.FC<PropsWithChildren<KnockProviderProps>> = ({
   timeBeforeExpirationInMs,
   children,
   i18n,
+  identificationStrategy,
   ...props
 }) => {
   const userIdOrUserWithProperties = props?.user || props?.userId;
@@ -72,8 +75,15 @@ export const KnockProvider: React.FC<PropsWithChildren<KnockProviderProps>> = ({
       onUserTokenExpiring,
       timeBeforeExpirationInMs,
       logLevel,
+      identificationStrategy,
     }),
-    [host, onUserTokenExpiring, timeBeforeExpirationInMs, logLevel],
+    [
+      host,
+      onUserTokenExpiring,
+      timeBeforeExpirationInMs,
+      logLevel,
+      identificationStrategy,
+    ],
   );
 
   const knock = useAuthenticatedKnockClient(

packages/react-core/src/modules/core/hooks/useAuthenticatedKnockClient.ts

@@ -17,6 +17,7 @@ function authenticateWithOptions(
   knock.authenticate(userIdOrUserWithProperties, userToken, {
     onUserTokenExpiring: options?.onUserTokenExpiring,
     timeBeforeExpirationInMs: options?.timeBeforeExpirationInMs,
+    identificationStrategy: options?.identificationStrategy,
   });
 }