feat(browser-sdk,react-sdk): extend the web SDKs to support the new config option.

package.json

@@ -13,6 +13,7 @@
     "build": "lerna run build --stream",
     "test:ci": "lerna run test:ci --stream",
     "test": "lerna run test --stream",
+    "format": "lerna run format --stream",
     "prettier": "lerna run prettier --stream",
     "lint": "lerna run lint --stream",
     "lint:ci": "lerna run lint:ci --stream",

packages/browser-sdk/README.md

@@ -27,19 +27,29 @@ const bucketClient = new BucketClient({ publishableKey, user, company });
 
 await bucketClient.initialize();
 
-const { isEnabled, track, requestFeedback } = bucketClient.getFeature("huddle");
+const {
+  isEnabled,
+  config: { value: question },
+  track,
+  requestFeedback,
+} = bucketClient.getFeature("huddle");
 
 if (isEnabled) {
-  // show feature. When retrieving `isEnabled` the client automatically
+  // Show feature. When retrieving `isEnabled` the client automatically
   // sends a "check" event for the "huddle" feature which is shown in the
   // Bucket UI.
 
   // On usage, call `track` to let Bucket know that a user interacted with the feature
   track();
 
+  // The `value` is a user-supplied value in Bucket that can be dynamically evaluated
+  // with respect to the current context. Here, it is assumed that one could either get
+  // a config value that matches the context or use a default.
+  const question = value?.question ?? "Tell us what you think of Huddles";
+
   // Use `requestFeedback` to create "Send feedback" buttons easily for specific
   // features. This is not related to `track` and you can call them individually.
-  requestFeedback({ title: "Tell us what you think of Huddles" });
+  requestFeedback({ title: question });
 }
 
 // `track` just calls `bucketClient.track(<featureKey>)` to send an event using the same feature key
@@ -127,6 +137,7 @@ To retrieve features along with their targeting information, use `getFeature(key
 const huddle = bucketClient.getFeature("huddle");
 // {
 //   isEnabled: true,
+//   config: { key: "zoom", targetingVersion: 2, value: { ... } },
 //   track: () => Promise<Response>
 //   requestFeedback: (options: RequestFeedbackData) => void
 // }
@@ -140,6 +151,7 @@ const features = bucketClient.getFeatures();
 //   huddle: {
 //     isEnabled: true,
 //     targetingVersion: 42,
+//     config: ...
 //   }
 // }
 ```
@@ -148,7 +160,39 @@ const features = bucketClient.getFeatures();
 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 return from `getFeature`.
+generate a `check` event, contrary to the `isEnabled` property on the object returned by `getFeature`.
+
+### Remote config
+
+Similar to `isEnabled`, each feature has a `config` property. This configuration is set by the user within Bucket. It is
+similar to the way access is managed -- using rules. Each config-bound rule is given a configuration value
+(a JSON value) that is returned to the SDK if the requested context matches. It is possible to have
+multiple rules with different configuration values. Whichever rule matches the context, provides the configuration
+value.
+
+The config is accessible through the same methods as the `isEnabled` property:
+
+```ts
+const features = bucketClient.getFeatures();
+// {
+//   huddle: {
+//     isEnabled: true,
+//     targetingVersion: 42,
+//     config?: {
+//       key: "gpt-3.5",
+//       targetingVersion: 2,
+//       value: { maxTokens: 10000, model: "gpt-3.5-beta1" }
+//     }
+//   }
+// }
+```
+
+The `key` is given by the user in Bucket for each configuration value, and `targetingVersion` is maintained by Bucket similar
+to access `targetingVersion`. The `value` is the actual JSON value supplied by the user and serves as context-based
+configuration.
+
+Just as `isEnabled`, accessing `config` on the object returned by `getFeatures` does not automatically
+generate a `check` event, contrary to the `config` property on the object returned by `getFeature`.
 
 ### Tracking feature usage
 

packages/browser-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bucketco/browser-sdk",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "packageManager": "yarn@4.1.1",
   "license": "MIT",
   "repository": {

packages/browser-sdk/src/client.ts

@@ -174,37 +174,71 @@ const defaultConfig: Config = {
   enableTracking: true,
 };
 
+/**
+ * A dynamic configuration value for a feature.
+ */
+export type FeatureDynamicConfig =
+  | {
+      /**
+       * The key of the matched configuration value.
+       */
+      key: string;
+      /**
+       * The version of the matched configuration value.
+       */
+      targetingVersion?: number;
+
+      /**
+       * The user-supplied data.
+       */
+      value: any;
+    }
+  | { key: undefined; targetingVersion: undefined; value: undefined };
+
+/**
+ * A feature.
+ */
 export interface Feature {
   /**
-   * Result of feature flag evaluation
+   * Result of feature flag evaluation.
    */
   isEnabled: boolean;
 
+  /*
+   * Optional user-defined configuration.
+   */
+  config: FeatureDynamicConfig;
+
   /**
-   * Function to send analytics events for this feature
-   *
+   * Function to send analytics events for this feature.
    */
   track: () => Promise<Response | undefined>;
+
+  /**
+   * Function to request feedback for this feature.
+   */
   requestFeedback: (
     options: Omit<RequestFeedbackData, "featureKey" | "featureId">,
   ) => void;
 }
+
 /**
  * BucketClient lets you interact with the Bucket API.
  *
  */
 export class BucketClient {
-  private publishableKey: string;
-  private context: BucketContext;
+  private readonly publishableKey: string;
+  private readonly context: BucketContext;
   private config: Config;
   private requestFeedbackOptions: Partial<RequestFeedbackOptions>;
-  private httpClient: HttpClient;
+  private readonly httpClient: HttpClient;
 
-  private autoFeedback: AutoFeedback | undefined;
+  private readonly autoFeedback: AutoFeedback | undefined;
   private autoFeedbackInit: Promise<void> | undefined;
-  private featuresClient: FeaturesClient;
+  private readonly featuresClient: FeaturesClient;
 
   public readonly logger: Logger;
+
   /**
    * Create a new BucketClient instance.
    */
@@ -328,7 +362,7 @@ export class BucketClient {
    * Performs a shallow merge with the existing company context.
    * Attempting to update the company ID will log a warning and be ignored.
    *
-   * @param company
+   * @param company The company details.
    */
   async updateCompany(company: { [key: string]: string | number | undefined }) {
     if (company.id && company.id !== this.context.company?.id) {
@@ -350,6 +384,8 @@ export class BucketClient {
    * Update the company context.
    * Performs a shallow merge with the existing company context.
    * Updates to the company ID will be ignored.
+   *
+   * @param otherContext Additional context.
    */
   async updateOtherContext(otherContext: {
     [key: string]: string | number | undefined;
@@ -367,7 +403,7 @@ export class BucketClient {
    *
    * Calling `client.stop()` will remove all listeners added here.
    *
-   * @param cb this will be called when the features are updated.
+   * @param cb The callback to call when the update completes.
    */
   onFeaturesUpdated(cb: () => void) {
     return this.featuresClient.onUpdated(cb);
@@ -376,8 +412,8 @@ export class BucketClient {
   /**
    * Track an event in Bucket.
    *
-   * @param eventName The name of the event
-   * @param attributes Any attributes you want to attach to the event
+   * @param eventName The name of the event.
+   * @param attributes Any attributes you want to attach to the event.
    */
   async track(eventName: string, attributes?: Record<string, any> | null) {
     if (!this.context.user) {
@@ -405,7 +441,8 @@ export class BucketClient {
   /**
    * Submit user feedback to Bucket. Must include either `score` or `comment`, or both.
    *
-   * @returns
+   * @param payload The feedback details to submit.
+   * @returns The server response.
    */
   async feedback(payload: Feedback) {
     const userId =
@@ -501,35 +538,49 @@ export class BucketClient {
    * and `isEnabled` does not take any feature overrides
    * into account.
    *
-   * @returns Map of features
+   * @returns Map of features.
    */
   getFeatures(): RawFeatures {
     return this.featuresClient.getFeatures();
   }
 
+  private missingConfig: FeatureDynamicConfig = {
+    key: undefined,
+    targetingVersion: undefined,
+    value: undefined,
+  };
   /**
-   * Return a feature. Accessing `isEnabled` will automatically send a `check` event.
-   * @returns A feature
+   * Return a feature. Accessing `isEnabled` or `config` will automatically send a `check` event.
+   * @returns A feature.
    */
   getFeature(key: string): Feature {
     const f = this.getFeatures()[key];
 
     const fClient = this.featuresClient;
     const value = f?.isEnabledOverride ?? f?.isEnabled ?? false;
+    const config = f?.config ?? this.missingConfig;
+
+    function sendCheckEvent() {
+      fClient
+        .sendCheckEvent({
+          key: key,
+          version: f?.targetingVersion,
+          value,
+        })
+        .catch(() => {
+          // ignore
+        });
+    }
 
     return {
       get isEnabled() {
-        fClient
-          .sendCheckEvent({
-            key,
-            version: f?.targetingVersion,
-            value,
-          })
-          .catch(() => {
-            // ignore
-          });
+        sendCheckEvent();
         return value;
       },
+      get config() {
+        sendCheckEvent();
+        return config;
+      },
       track: () => this.track(key),
       requestFeedback: (
         options: Omit<RequestFeedbackData, "featureKey" | "featureId">,

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

@@ -22,19 +22,28 @@ export function parseAPIFeaturesResponse(
   const features: FetchedFeatures = {};
   for (const key in featuresInput) {
     const feature = featuresInput[key];
+
     if (
       typeof feature.isEnabled !== "boolean" ||
       feature.key !== key ||
-      typeof feature.targetingVersion !== "number"
+      typeof feature.targetingVersion !== "number" ||
+      (feature.config && typeof feature.config !== "object")
     ) {
       return;
     }
+
     features[key] = {
       isEnabled: feature.isEnabled,
       targetingVersion: feature.targetingVersion,
       key,
+      config: feature.config && {
+        key: feature.config.key,
+        targetingVersion: feature.config.version,
+        value: feature.config.payload,
+      },
     };
   }
+
   return features;
 }
 
@@ -45,8 +54,8 @@ export interface CacheResult {
 
 export class FeatureCache {
   private storage: StorageItem;
-  private staleTimeMs: number;
-  private expireTimeMs: number;
+  private readonly staleTimeMs: number;
+  private readonly expireTimeMs: number;
 
   constructor({
     storage,