feat(KNO-9338): add branch configuration options (#696)

Author: mattmikolay

.changeset/cuddly-moments-fly.md

@@ -0,0 +1,21 @@
+---
+"@knocklabs/react-core": patch
+---
+
+Add `branch` option to `useAuthenticatedKnockClient` hook
+
+The `useAuthenticatedKnockClient` hook now accepts a `branch` option. To use
+`useAuthenticatedKnockClient` with a branch, set the `apiKey` param to your
+development environment's API key and set the `branch` option to the slug of an
+existing branch.
+
+```tsx
+import { useAuthenticatedKnockClient } from "@knocklabs/react-core";
+
+const knock = useAuthenticatedKnockClient(
+  process.env.KNOCK_PUBLIC_API_KEY,
+  { id: user.id },
+  undefined, // userToken when needed
+  { branch: "my-branch-slug" },
+);
+```

.changeset/four-dodos-enter.md

@@ -0,0 +1,5 @@
+---
+"nextjs-example": patch
+---
+
+Add NEXT_PUBLIC_KNOCK_BRANCH env var for specifying branch

.changeset/tidy-days-make.md

@@ -0,0 +1,17 @@
+---
+"@knocklabs/client": patch
+---
+
+Add `branch` option to `Knock` client
+
+The `Knock` client now accepts a `branch` option. To use `Knock` with a branch,
+set the `apiKey` param to your development environment's API key and set the
+`branch` option to the slug of an existing branch.
+
+```js
+import Knock from "@knocklabs/client";
+
+const knock = new Knock(process.env.KNOCK_PUBLIC_API_KEY, {
+  branch: "my-branch-slug",
+});
+```

.changeset/yellow-insects-knock.md

@@ -0,0 +1,26 @@
+---
+"@knocklabs/react-core": patch
+---
+
+Add `branch` prop to `<KnockProvider>`
+
+The `<KnockProvider>` context provider now accepts an optional `branch` prop.
+To use `<KnockProvider>` with a branch, set the `apiKey` prop to your
+development environment's API key and set `branch` to the slug of an existing
+branch.
+
+```tsx
+import { KnockProvider } from "@knocklabs/react";
+
+const YourAppLayout = () => {
+  return (
+    <KnockProvider
+      apiKey={process.env.KNOCK_PUBLIC_API_KEY}
+      user={{ id: user.id }}
+      branch="my-branch-slug"
+    >
+      {/** the rest of your app */}
+    </KnockProvider>
+  );
+};
+```

examples/nextjs-example/.env.sample

@@ -6,4 +6,5 @@ NEXT_PUBLIC_KNOCK_PUBLIC_API_KEY=<Knock public API key>
 NEXT_PUBLIC_KNOCK_FEED_CHANNEL_ID=<Knock in-app feed channel ID for loading the feed>
 NEXT_PUBLIC_WORKFLOW_KEY=<Knock workflow key that has the in-app channel, for sending notifications to this feed>
 
-NEXT_PUBLIC_KNOCK_HOST=<Optional>
+NEXT_PUBLIC_KNOCK_HOST=<Optional>
+NEXT_PUBLIC_KNOCK_BRANCH=<Optional>

examples/nextjs-example/pages/index.tsx

@@ -45,6 +45,7 @@ export default function Home() {
       userToken={userToken}
       apiKey={process.env.NEXT_PUBLIC_KNOCK_PUBLIC_API_KEY!}
       host={process.env.NEXT_PUBLIC_KNOCK_HOST}
+      branch={process.env.NEXT_PUBLIC_KNOCK_BRANCH}
       onUserTokenExpiring={tokenRefreshHandler}
       timeBeforeExpirationInMs={5000}
       logLevel="debug"

packages/client/src/api.ts

@@ -6,6 +6,7 @@ type ApiClientOptions = {
   host: string;
   apiKey: string;
   userToken: string | undefined;
+  branch?: string;
 };
 
 export interface ApiResponse {
@@ -21,6 +22,7 @@ class ApiClient {
   private host: string;
   private apiKey: string;
   private userToken: string | null;
+  private branch: string | null;
   private axiosClient: AxiosInstance;
 
   public socket: Socket | undefined;
@@ -29,6 +31,7 @@ class ApiClient {
     this.host = options.host;
     this.apiKey = options.apiKey;
     this.userToken = options.userToken || null;
+    this.branch = options.branch || null;
 
     // Create a retryable axios client
     this.axiosClient = axios.create({
@@ -39,6 +42,7 @@ class ApiClient {
         Authorization: `Bearer ${this.apiKey}`,
         "X-Knock-User-Token": this.userToken,
         "X-Knock-Client": this.getKnockClientHeader(),
+        "X-Knock-Branch": this.branch,
       },
     });
 
@@ -47,6 +51,7 @@ class ApiClient {
         params: {
           user_token: this.userToken,
           api_key: this.apiKey,
+          branch_slug: this.branch,
         },
       });
     }

packages/client/src/interfaces.ts

@@ -8,6 +8,7 @@ export type LogLevel = "debug";
 export interface KnockOptions {
   host?: string;
   logLevel?: LogLevel;
+  branch?: string;
 }
 
 export interface KnockObject<T = GenericData> {

packages/client/src/knock.ts

@@ -25,6 +25,7 @@ class Knock {
   public userId: string | undefined | null;
   public userToken?: string;
   public logLevel?: LogLevel;
+  public readonly branch?: string;
   private tokenExpirationTimer: ReturnType<typeof setTimeout> | null = null;
   readonly feeds = new FeedClient(this);
   readonly objects = new ObjectClient(this);
@@ -40,6 +41,7 @@ class Knock {
   ) {
     this.host = options.host || DEFAULT_HOST;
     this.logLevel = options.logLevel;
+    this.branch = options.branch || undefined;
 
     this.log("Initialized Knock instance");
 
@@ -187,6 +189,7 @@ class Knock {
       apiKey: this.apiKey,
       host: this.host,
       userToken: this.userToken,
+      branch: this.branch,
     });
   }
 

packages/client/test/api.test.ts

@@ -5,6 +5,8 @@ import ApiClient from "../src/api";
 
 import { createAxiosMock, mockAxios } from "./test-utils/mocks";
 
+const TEST_BRANCH_SLUG = "lorem-ipsum-dolor-branch";
+
 // Type for accessing global properties
 type GlobalWithWindow = Record<string, unknown>;
 
@@ -74,6 +76,7 @@ describe("API Client", () => {
         host: "https://api.knock.app",
         apiKey: "pk_test_12345",
         userToken: undefined,
+        branch: TEST_BRANCH_SLUG,
       });
 
       expect(apiClient).toBeInstanceOf(ApiClient);
@@ -515,6 +518,22 @@ describe("API Client", () => {
       );
     });
 
+    test("sets correct x-knock-branch header", () => {
+      const apiClient = new ApiClient({
+        host: "https://api.knock.app",
+        apiKey: "pk_test_12345",
+        userToken: undefined,
+        branch: TEST_BRANCH_SLUG,
+      });
+
+      const axiosClient = (apiClient as unknown as Record<string, unknown>)
+        .axiosClient as { defaults: { headers: Record<string, string> } };
+
+      expect(axiosClient.defaults.headers["X-Knock-Branch"]).toBe(
+        TEST_BRANCH_SLUG,
+      );
+    });
+
     test("supports various HTTP methods", async () => {
       const mockHttp = createAxiosMock();
       const apiClient = new ApiClient({