feat(browser-sdk): Event listeners (#325)

Event listeners allow capturing different events that happen in the Browser SDK. They are useful for a number of things like building client side integrations to analytics or error-logging systems.
reflagcom · roncohen · Jan 29, 2025 · Jan 29, 2025 · Jan 29, 2025 · Jan 29, 2025
commit 1e21da8ca2fb45cea9d33a1f04cfddd1812cc7d2
diff --git a/packages/browser-sdk/README.md b/packages/browser-sdk/README.md
@@ -294,7 +294,7 @@ Bucket can assist you with collecting your user's feedback by offering a pre-bui
 
 Feedback can be submitted to Bucket using the SDK:
 
-```js
+```ts
 bucketClient.feedback({
   featureId: "my_feature_id", // String (required), copy from Feature feedback tab
   score: 5, // Number: 1-5 (optional)
@@ -308,6 +308,33 @@ If you are not using the Bucket Browser SDK, you can still submit feedback using
 
 See details in [Feedback HTTP API](https://docs.bucket.co/reference/http-tracking-api#feedback)
 
+### Event listeners
+
+Event listeners allow for capturing various events occurring in the `BucketClient`. This is useful to build integrations with other system or for various debugging purposes. There are 5 kinds of events:
+
+- FeaturesUpdated
+- User
+- Company
+- Check
+- Track
+
+Use the `on()` method to add an event listener to respond to certain events. See the API reference for details on each hook.
+
+```ts
+import { BucketClient, CheckEvent, RawFeatures } from "@bucketco/browser-sdk";
+
+const client = new BucketClient({
+  // options
+});
+
+// or add the hooks after construction:
+const unsub = client.on("enabledCheck", (check: CheckEvent) =>
+  console.log(`Check event ${check}`),
+);
+// use the returned function to unsubscribe, or call `off()` with the same arguments again
+unsub();
+```
+
 ### Zero PII
 
 The Bucket Browser SDK doesn't collect any metadata and HTTP IP addresses are _not_ being stored.

diff --git a/packages/browser-sdk/example/typescript/app.ts b/packages/browser-sdk/example/typescript/app.ts
@@ -1,11 +1,9 @@
-import { BucketClient } from "../../src";
+import { BucketClient, CheckEvent, RawFeatures } from "../../src";
 
 const urlParams = new URLSearchParams(window.location.search);
 const publishableKey = urlParams.get("publishableKey");
 const featureKey = urlParams.get("featureKey") ?? "huddles";
 
-const featureList = ["huddles"];
-
 if (!publishableKey) {
   throw Error("publishableKey is missing");
 }
@@ -18,7 +16,6 @@ const bucket = new BucketClient({
     show: true,
     position: { placement: "bottom-right" },
   },
-  featureList,
 });
 
 document
@@ -37,8 +34,8 @@ bucket.initialize().then(() => {
   if (loadingElem) loadingElem.style.display = "none";
 });
 
-bucket.onFeaturesUpdated(() => {
-  const { isEnabled } = bucket.getFeature("huddles");
+bucket.on("featuresUpdated", (features: RawFeatures) => {
+  const { isEnabled } = features[featureKey];
 
   const startHuddleElem = document.getElementById("start-huddle");
   if (isEnabled) {

diff --git a/packages/browser-sdk/index.html b/packages/browser-sdk/index.html
@@ -36,7 +36,6 @@
 
     <script type="module">
       import { BucketClient } from "./src/index.ts";
-      const featureList = ["huddles"];
 
       window.bucket = new BucketClient({
         publishableKey,
@@ -48,22 +47,28 @@
             placement: "bottom-right",
           },
         },
-        featureList,
       });
 
       bucket.initialize().then(() => {
         console.log("Bucket initialized");
         document.getElementById("loading").style.display = "none";
       });
 
-      bucket.onFeaturesUpdated(() => {
-        const { isEnabled } = bucket.getFeature("huddles");
-        if (isEnabled) {
+      bucket.on("enabledCheck", (check) =>
+        console.log(`Check event for ${check.key}`),
+      );
+
+      bucket.on("featuresUpdated", (features) => {
+        console.log("Features updated");
+        const feature = bucket.getFeature(featureKey);
+
+        const startHuddleElem = document.getElementById("start-huddle");
+        if (feature.isEnabled) {
           // show the start-huddle button
-          document.getElementById("start-huddle").style.display = "block";
+          if (startHuddleElem) startHuddleElem.style.display = "block";
         } else {
           // hide the start-huddle button
-          document.getElementById("start-huddle").style.display = "none";
+          if (startHuddleElem) startHuddleElem.style.display = "none";
         }
       });
     </script>

diff --git a/packages/browser-sdk/src/client.ts b/packages/browser-sdk/src/client.ts
@@ -16,6 +16,7 @@ import * as feedbackLib from "./feedback/ui";
 import { ToolbarPosition } from "./toolbar/Toolbar";
 import { API_BASE_URL, APP_BASE_URL, SSE_REALTIME_BASE_URL } from "./config";
 import { BucketContext, CompanyContext, UserContext } from "./context";
+import { HookArgs, HooksManager } from "./hooksManager";
 import { HttpClient } from "./httpClient";
 import { Logger, loggerWithPrefix, quietConsoleLogger } from "./logger";
 import { showToolbarToggle } from "./toolbar";
@@ -356,6 +357,8 @@ export class BucketClient {
 
   public readonly logger: Logger;
 
+  private readonly hooks: HooksManager;
+
   /**
    * Create a new BucketClient instance.
    */
@@ -433,6 +436,12 @@ export class BucketClient {
           typeof opts.toolbar === "object" ? opts.toolbar.position : undefined,
       });
     }
+
+    // Register hooks
+    this.hooks = new HooksManager();
+    this.featuresClient.onUpdated(() => {
+      this.hooks.trigger("featuresUpdated", this.featuresClient.getFeatures());
+    });
   }
 
   /**
@@ -463,6 +472,31 @@ export class BucketClient {
     }
   }
 
+  /**
+   * Add a hook to the client.
+   *
+   * @param hook Hook to add.
+   */
+  on<THookType extends keyof HookArgs>(
+    type: THookType,
+    handler: (args0: HookArgs[THookType]) => void,
+  ) {
+    this.hooks.addHook(type, handler);
+  }
+
+  /**
+   * Remove a hook from the client.
+   *
+   * @param hook Hook to add.
+   * @returns A function to remove the hook.
+   */
+  off<THookType extends keyof HookArgs>(
+    type: THookType,
+    handler: (args0: HookArgs[THookType]) => void,
+  ) {
+    return this.hooks.removeHook(type, handler);
+  }
+
   /**
    * Get the current configuration.
    */
@@ -534,18 +568,6 @@ export class BucketClient {
     await this.featuresClient.setContext(this.context);
   }
 
-  /**
-   * Register a callback to be called when the features are updated.
-   * Features are not guaranteed to have actually changed when the callback is called.
-   *
-   * Calling `client.stop()` will remove all listeners added here.
-   *
-   * @param cb The callback to call when the update completes.
-   */
-  onFeaturesUpdated(cb: () => void) {
-    return this.featuresClient.onUpdated(cb);
-  }
-
   /**
    * Track an event in Bucket.
    *
@@ -572,6 +594,13 @@ export class BucketClient {
 
     const res = await this.httpClient.post({ path: `/event`, body: payload });
     this.logger.debug(`sent event`, res);
+
+    this.hooks.trigger("track", {
+      eventName,
+      attributes,
+      user: this.context.user,
+      company: this.context.company,
+    });
     return res;
   }
 
@@ -684,7 +713,8 @@ export class BucketClient {
   getFeature(key: string): Feature {
     const f = this.getFeatures()[key];
 
-    const fClient = this.featuresClient;
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const self = this;
     const value = f?.isEnabledOverride ?? f?.isEnabled ?? false;
     const config = f?.config
       ? {
@@ -695,9 +725,9 @@ export class BucketClient {
 
     return {
       get isEnabled() {
-        fClient
+        self
           .sendCheckEvent({
-            action: "check",
+            action: "check-is-enabled",
             key,
             version: f?.targetingVersion,
             ruleEvaluationResults: f?.ruleEvaluationResults,
@@ -710,7 +740,7 @@ export class BucketClient {
         return value;
       },
       get config() {
-        fClient
+        self
           .sendCheckEvent({
             action: "check-config",
             key,
@@ -749,7 +779,12 @@ export class BucketClient {
   }
 
   sendCheckEvent(checkEvent: CheckEvent) {
-    return this.featuresClient.sendCheckEvent(checkEvent);
+    return this.featuresClient.sendCheckEvent(checkEvent, () => {
+      this.hooks.trigger(
+        checkEvent.action == "check-config" ? "configCheck" : "enabledCheck",
+        checkEvent,
+      );
+    });
   }
 
   /**
@@ -787,6 +822,8 @@ export class BucketClient {
     };
     const res = await this.httpClient.post({ path: `/user`, body: payload });
     this.logger.debug(`sent user`, res);
+
+    this.hooks.trigger("user", this.context.user);
     return res;
   }
 
@@ -817,6 +854,7 @@ export class BucketClient {
 
     const res = await this.httpClient.post({ path: `/company`, body: payload });
     this.logger.debug(`sent company`, res);
+    this.hooks.trigger("company", this.context.company);
     return res;
   }
 }
diff --git a/packages/browser-sdk/src/feature/features.ts b/packages/browser-sdk/src/feature/features.ts
@@ -69,7 +69,7 @@ export type FetchedFeature = {
   };
 };
 
-const FEATURES_UPDATED_EVENT = "features-updated";
+const FEATURES_UPDATED_EVENT = "featuresUpdated";
 
 export type FetchedFeatures = Record<string, FetchedFeature | undefined>;
 
@@ -145,7 +145,7 @@ export interface CheckEvent {
   /**
    * Action to perform.
    */
-  action: "check" | "check-config";
+  action: "check-is-enabled" | "check-config";
 
   /**
    * Feature key.
@@ -299,20 +299,12 @@ export class FeaturesClient {
    * Features are not guaranteed to have actually changed when the callback is called.
    *
    * @param callback this will be called when the features are updated.
-   * @param options passed as-is to addEventListener, except the abort signal is not supported.
    * @returns a function that can be called to remove the listener
    */
-  onUpdated(callback: () => void, options?: AddEventListenerOptions | boolean) {
+  onUpdated(callback: () => void) {
     this.eventTarget.addEventListener(FEATURES_UPDATED_EVENT, callback, {
       signal: this.abortController.signal,
     });
-    return () => {
-      this.eventTarget.removeEventListener(
-        FEATURES_UPDATED_EVENT,
-        callback,
-        options,
-      );
-    };
   }
 
   getFeatures(): RawFeatures {
@@ -365,10 +357,10 @@ export class FeaturesClient {
    *
    *
    * @param checkEvent - The feature to send the event for.
+   * @param cb - Callback to call after the event is sent. Might be skipped if the event was rate limited.
    */
-  async sendCheckEvent(checkEvent: CheckEvent) {
+  async sendCheckEvent(checkEvent: CheckEvent, cb: () => void) {
     const rateLimitKey = `check-event:${this.fetchParams().toString()}:${checkEvent.key}:${checkEvent.version}:${checkEvent.value}`;
-
     await this.rateLimiter.rateLimited(rateLimitKey, async () => {
       const payload = {
         action: checkEvent.action,
@@ -390,6 +382,7 @@ export class FeaturesClient {
         });
 
       this.logger.debug(`sent feature event`, payload);
+      cb();
     });
 
     return checkEvent.value;