feat(browser-sdk,react-sdk): check events (#316)

Author: pavkam

packages/browser-sdk/FEEDBACK.md

@@ -13,7 +13,7 @@ the viewport, displayed in English, and with a [light-mode theme](#custom-stylin
 
 These settings can be overwritten when initializing the Bucket Browser SDK:
 
-```javascript
+```typescript
 const bucket = new BucketClient({
   publishableKey: "bucket-publishable-key",
   user: { id: "42" },
@@ -39,11 +39,9 @@ const bucket = new BucketClient({
 
 See also:
 
-- [Positioning and behavior](#positioning-and-behavior) for the position option.
-- [Static language configuration](#static-language-configuration) if you want to
-  translate the feedback UI.
-- [Automated feedback surveys](#automated-feedback-surveys) to
-  override default configuration.
+- [Positioning and behavior](#positioning-and-behavior) for the position option,
+- [Static language configuration](#static-language-configuration) if you want to translate the feedback UI,
+- [Automated feedback surveys](#automated-feedback-surveys) to override default configuration.
 
 ## Automated feedback surveys
 
@@ -63,7 +61,7 @@ The live connection for automated feedback is established when the
 
 You can disable automated collection in the `BucketClient` constructor:
 
-```javascript
+```typescript
 const bucket = new BucketClient({
   publishableKey: "bucket-publishable-key",
   user: { id: "42" },

packages/browser-sdk/README.md

@@ -8,9 +8,9 @@ First find your `publishableKey` under [environment settings](https://app.bucket
 
 The package can be imported or used directly in a HTML script tag:
 
-A. Import module
+A. Import module:
 
-```ts
+```typescript
 import { BucketClient } from "@bucketco/browser-sdk";
 
 const user = {
@@ -93,19 +93,21 @@ See [example/browser.html](https://github.com/bucketco/bucket-javascript-sdk/tre
 
 Supply these to the constructor call:
 
-```ts
+```typescript
 type Configuration = {
   logger: console; // by default only logs warn/error, by passing `console` you'll log everything
   apiBaseUrl?: "https://front.bucket.co";
   sseBaseUrl?: "https://livemessaging.bucket.co";
   feedback?: undefined; // See FEEDBACK.md
-  enableTracking?: true; // set to `false` to stop sending track events and user/company updates to Bucket servers. Useful when you're impersonating a user.
+  enableTracking?: true; // set to `false` to stop sending track events and user/company updates to Bucket servers. Useful when you're impersonating a user
   featureOptions?: {
-    fallbackFeatures?: string[]; // Enable these features if unable to contact bucket.co
-    timeoutMs?: number; // Timeout for fetching features
-    staleWhileRevalidate?: boolean; // Revalidate in the background when cached features turn stale to avoid latency in the UI
-    staleTimeMs?: number; // at initialization time features are loaded from the cache unless they have gone stale. Defaults to 0 which means the cache is disabled. Increase in the case of a non-SPA.
-    expireTimeMs?: number; // In case we're unable to fetch features from Bucket, cached/stale features will be used instead until they expire after  `expireTimeMs`.
+    fallbackFeatures?:
+      | string[]
+      | Record<string, { key: string; payload: any } | true>; // Enable these features if unable to contact bucket.co. Can be a list of feature keys or a record with configuration values
+    timeoutMs?: number; // Timeout for fetching features (default: 5000ms)
+    staleWhileRevalidate?: boolean; // Revalidate in the background when cached features turn stale to avoid latency in the UI (default: false)
+    staleTimeMs?: number; // at initialization time features are loaded from the cache unless they have gone stale. Defaults to 0 which means the cache is disabled. Increase in the case of a non-SPA
+    expireTimeMs?: number; // In case we're unable to fetch features from Bucket, cached/stale features will be used instead until they expire after `expireTimeMs`. Default is 30 days
   };
 };
 ```
@@ -120,9 +122,9 @@ In addition to the `id`, you must also supply anything additional that you want
 Attributes cannot be nested (multiple levels) and must be either strings, integers or booleans.
 Some attributes are special and used in Bucket UI:
 
-- `name` is used to display name for `user`/`company`,
-- `email` is accepted for `user`s and will be highlighted in the Bucket UI if available,
-- `avatar` can be provided for both `user` and `company` and should be an URL to an image.
+- `name` -- display name for `user`/`company`,
+- `email` -- is accepted for `user`s and will be highlighted in the Bucket UI if available,
+- `avatar` -- can be provided for both `user` and `company` and should be an URL to an image.
 
 ```ts
 const bucketClient = new BucketClient({
@@ -172,6 +174,43 @@ by down-stream clients, like the React SDK.
 Note that accessing `isEnabled` on the object returned by `getFeatures` does not automatically
 generate a `check` event, contrary to the `isEnabled` property on the object returned by `getFeature`.
 
+### Feature Overrides
+
+You can override feature flags locally for testing purposes using `setFeatureOverride`:
+
+```ts
+// Override a feature to be enabled
+bucketClient.setFeatureOverride("huddle", true);
+
+// Override a feature to be disabled
+bucketClient.setFeatureOverride("huddle", false);
+
+// Remove the override
+bucketClient.setFeatureOverride("huddle", null);
+
+// Get current override value
+const override = bucketClient.getFeatureOverride("huddle"); // returns boolean | null
+```
+
+Feature overrides are persisted in `localStorage` and will be restored when the page is reloaded.
+
+### Feature Updates
+
+You can listen for feature updates using `onFeaturesUpdated`:
+
+```ts
+// Register a callback for feature updates
+const unsubscribe = bucketClient.onFeaturesUpdated(() => {
+  console.log("Features were updated");
+});
+
+// Later, stop listening for updates
+unsubscribe();
+```
+
+> [!NOTE]
+> Note that the callback may be called even if features haven't actually changed.
+
 ### Remote config
 
 Similar to `isEnabled`, each feature has a `config` property. This configuration is managed from within Bucket.
@@ -225,7 +264,7 @@ const { isEnabled } = bucketClient.getFeature("voiceHuddle");
 await bucketClient.updateUser({ voiceHuddleOptIn: (!isEnabled).toString() });
 ```
 
-Note that user/company attributes are also stored remotely on the Bucket servers and will automatically be used to evaluate feature targeting if the page is refreshed.
+> [!NOTE] > `user`/`company` attributes are also stored remotely on the Bucket servers and will automatically be used to evaluate feature targeting if the page is refreshed.
 
 ### Qualitative feedback
 
@@ -235,7 +274,8 @@ Bucket can collect qualitative feedback from your users in the form of a [Custom
 
 The Bucket Browser SDK comes with automated feedback collection mode enabled by default, which lets the Bucket service ask your users for feedback for relevant features just after they've used them.
 
-Note: To get started with automatic feedback collection, make sure you've set `user` in the `BucketClient` constructor.
+> [!NOTE]
+> To get started with automatic feedback collection, make sure you've set `user` in the `BucketClient` constructor.
 
 Automated feedback surveys work even if you're not using the SDK to send events to Bucket.
 It works because the Bucket Browser SDK maintains a live connection to Bucket's servers and can automatically show a feedback prompt whenever the Bucket servers determines that an event should trigger a prompt - regardless of how this event is sent to Bucket.
@@ -262,7 +302,7 @@ bucketClient.feedback({
 });
 ```
 
-#### Bucket feedback API
+### Bucket feedback API
 
 If you are not using the Bucket Browser SDK, you can still submit feedback using the HTTP API.
 
@@ -274,9 +314,9 @@ The Bucket Browser SDK doesn't collect any metadata and HTTP IP addresses are _n
 
 For tracking individual users, we recommend using something like database ID as userId, as it's unique and doesn't include any PII (personal identifiable information). If, however, you're using e.g. email address as userId, but prefer not to send any PII to Bucket, you can hash the sensitive data before sending it to Bucket:
 
-```
+```ts
 import bucket from "@bucketco/browser-sdk";
-import { sha256 } from 'crypto-hash';
+import { sha256 } from "crypto-hash";
 
 bucket.user(await sha256("john_doe"));
 ```
@@ -290,28 +330,27 @@ The two cookies are:
 - `bucket-prompt-${userId}`: store the last automated feedback prompt message ID received to avoid repeating surveys
 - `bucket-token-${userId}`: caching a token used to connect to Bucket's live messaging infrastructure that is used to deliver automated feedback surveys in real time.
 
-### Typescript
+### TypeScript
 
 Types are bundled together with the library and exposed automatically when importing through a package manager.
 
 ## Content Security Policy (CSP)
 
 If you are running with strict Content Security Policies active on your website, you will need to enable these directives in order to use the SDK:
 
-| Directive   | Values                          | Reason                                                                                                                                   |
-| ----------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| connect-src | https://front.bucket.co         | Basic functionality`                                                                                                                     |
-| connect-src | https://livemessaging.bucket.co | Server sent events for use in automated feedback surveys, which allows for automatically collecting feedback when a user used a feature. |
-| style-src   | 'unsafe-inline'                 | The feedback UI is styled with inline styles. Not having this directive results unstyled HTML elements.                                  |
+| Directive   | Values                                                             | Reason                                                                                                                                   |
+| ----------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| connect-src | [https://front.bucket.co](https://front.bucket.co)                 | Basic functionality`                                                                                                                     |
+| connect-src | [https://livemessaging.bucket.co](https://livemessaging.bucket.co) | Server sent events for use in automated feedback surveys, which allows for automatically collecting feedback when a user used a feature. |
+| style-src   | 'unsafe-inline'                                                    | The feedback UI is styled with inline styles. Not having this directive results unstyled HTML elements.                                  |
 
 If you are including the Bucket tracking SDK with a `<script>`-tag from `jsdelivr.net` you will also need:
 
-| Directive       | Values                   | Reason                          |
-| --------------- | ------------------------ | ------------------------------- |
-| script-src-elem | https://cdn.jsdelivr.net | Loads the Bucket SDK from a CDN |
-
-# License
+| Directive       | Values                                               | Reason                          |
+| --------------- | ---------------------------------------------------- | ------------------------------- |
+| script-src-elem | [https://cdn.jsdelivr.net](https://cdn.jsdelivr.net) | Loads the Bucket SDK from a CDN |
 
-MIT License
+## License
 
-Copyright (c) 2025 Bucket ApS
+> MIT License
+> Copyright (c) 2025 Bucket ApS

packages/browser-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bucketco/browser-sdk",
-  "version": "3.0.0-alpha.2",
+  "version": "3.0.0-alpha.3",
   "packageManager": "yarn@4.1.1",
   "license": "MIT",
   "repository": {

packages/browser-sdk/src/client.ts

@@ -707,25 +707,39 @@ export class BucketClient {
         }
       : { key: undefined, payload: undefined };
 
-    function sendCheckEvent() {
-      fClient
-        .sendCheckEvent({
-          key,
-          version: f?.targetingVersion,
-          value,
-        })
-        .catch(() => {
-          // ignore
-        });
-    }
-
     return {
       get isEnabled() {
-        sendCheckEvent();
+        fClient
+          .sendCheckEvent({
+            action: "check",
+            key,
+            version: f?.targetingVersion,
+            ruleEvaluationResults: f?.ruleEvaluationResults,
+            missingContextFields: f?.missingContextFields,
+            value,
+          })
+          .catch(() => {
+            // ignore
+          });
         return value;
       },
       get config() {
-        sendCheckEvent();
+        fClient
+          .sendCheckEvent({
+            action: "check-config",
+            key,
+            version: f?.config?.version,
+            ruleEvaluationResults: f?.config?.ruleEvaluationResults,
+            missingContextFields: f?.config?.missingContextFields,
+            value: f?.config && {
+              key: f.config.key,
+              payload: f.config.payload,
+            },
+          })
+          .catch(() => {
+            // ignore
+          });
+
         return config;
       },
       track: () => this.track(key),

packages/browser-sdk/src/feature/featureCache.ts

@@ -27,7 +27,11 @@ export function parseAPIFeaturesResponse(
       typeof feature.isEnabled !== "boolean" ||
       feature.key !== key ||
       typeof feature.targetingVersion !== "number" ||
-      (feature.config && typeof feature.config !== "object")
+      (feature.config && typeof feature.config !== "object") ||
+      (feature.missingContextFields &&
+        !Array.isArray(feature.missingContextFields)) ||
+      (feature.ruleEvaluationResults &&
+        !Array.isArray(feature.ruleEvaluationResults))
     ) {
       return;
     }
@@ -37,6 +41,8 @@ export function parseAPIFeaturesResponse(
       targetingVersion: feature.targetingVersion,
       key,
       config: feature.config,
+      missingContextFields: feature.missingContextFields,
+      ruleEvaluationResults: feature.ruleEvaluationResults,
     };
   }