feat(browser-sdk,node-sdk): add avatar support for user and company c…

…ontexts (#297) - Updated README files to document new `avatar` attribute - Added `avatar` to user and company context types in browser and node SDKs - Expanded documentation for special attributes in context objects - Added type definitions for avatar in relevant type files
reflagcom · roncohen · Jan 29, 2025 · Jan 29, 2025 · Jan 29, 2025 · Jan 29, 2025
commit f13880ae6de016e48ad86bbcda08f11e473a4982
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -38,5 +38,8 @@
     "**/node_modules": true,
     "**/*.lock": true
   },
-  "typescript.tsdk": "node_modules/typescript/lib"
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "cSpell.words": [
+    "bucketco"
+  ]
 }
diff --git a/packages/browser-sdk/README.md b/packages/browser-sdk/README.md
@@ -109,15 +109,26 @@ If you supply `user` or `company` objects, they must include at least the `id` p
 In addition to the `id`, you must also supply anything additional that you want to be able to evaluate feature targeting rules against.
 
 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 a special attribute and is used to display name for user/company
-- for `user`, `email` is also special and will be highlighted in the Bucket UI if available
+- `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.
 
 ```ts
 const bucketClient = new BucketClient({
   publishableKey,
-  user: { id: "user_123", name: "John Doe", email: "[email protected]" },
-  company: { id: "company_123", name: "Acme, Inc" },
+  user: {
+    id: "user_123",
+    name: "John Doe",
+    email: "[email protected]"
+    avatar: "https://example.com/images/udsy6363"
+  },
+  company: {
+    id: "company_123",
+    name: "Acme, Inc",
+    avatar: "https://example.com/images/31232ds"
+  },
 });
 ```
 

diff --git a/packages/browser-sdk/src/client.ts b/packages/browser-sdk/src/client.ts
@@ -22,79 +22,149 @@ import { Logger, loggerWithPrefix, quietConsoleLogger } from "./logger";
 const isMobile = typeof window !== "undefined" && window.innerWidth < 768;
 const isNode = typeof document === "undefined"; // deno supports "window" but not "document" according to https://remix.run/docs/en/main/guides/gotchas
 
+/**
+ * (Internal) User context.
+ *
+ * @internal
+ */
 export type User = {
   /**
-   * Identifier of the user
+   * Identifier of the user.
    */
   userId: string;
 
   /**
-   * User attributes
+   * User attributes.
    */
   attributes?: {
+    /**
+     * Name of the user.
+     */
     name?: string;
+
+    /**
+     * Email of the user.
+     */
+    email?: string;
+
+    /**
+     * Avatar URL of the user.
+     */
+    avatar?: string;
+
+    /**
+     * Custom attributes of the user.
+     */
     [key: string]: any;
   };
 
+  /**
+   * Custom context of the user.
+   */
   context?: PayloadContext;
 };
 
+/**
+ * (Internal) Company context.
+ *
+ * @internal
+ */
 export type Company = {
   /**
-   * User identifier
+   * User identifier.
    */
   userId: string;
 
   /**
-   * Company identifier
+   * Company identifier.
    */
   companyId: string;
 
   /**
-   * Company attributes
+   * Company attributes.
    */
   attributes?: {
+    /**
+     * Name of the company.
+     */
     name?: string;
+
+    /**
+     * Custom attributes of the company.
+     */
     [key: string]: any;
   };
 
   context?: PayloadContext;
 };
 
+/**
+ * Tracked event.
+ */
 export type TrackedEvent = {
   /**
-   * Event name
+   * Event name.
    */
   event: string;
 
   /**
-   * User identifier
+   * User identifier.
    */
   userId: string;
 
   /**
-   * Company identifier
+   * Company identifier.
    */
   companyId?: string;
 
   /**
-   * Event attributes
+   * Event attributes.
    */
   attributes?: Record<string, any>;
 
+  /**
+   * Custom context of the event.
+   */
   context?: PayloadContext;
 };
 
+/**
+ * (Internal) Custom context of the event.
+ *
+ * @internal
+ */
 export type PayloadContext = {
+  /**
+   * Whether the company and user associated with the event are active.
+   */
   active?: boolean;
 };
 
+/**
+ * BucketClient configuration.
+ */
 interface Config {
+  /**
+   * Base URL of Bucket servers.
+   */
   apiBaseUrl: string;
+
+  /**
+   * Base URL of Bucket servers for SSE connections used by AutoFeedback.
+   */
   sseBaseUrl: string;
+
+  /**
+   * Whether to enable tracking.
+   */
   enableTracking: boolean;
 }
 
+/**
+ * Feature definitions.
+ */
+export type FeatureDefinitions = Readonly<Array<string>>;
+
 /**
  * BucketClient initialization options.
  */
@@ -105,12 +175,14 @@ export interface InitOptions {
   publishableKey: string;
 
   /**
-   * User related context. If you provide `id` Bucket will enrich the evaluation context with user attributes on Bucket servers.
+   * User related context. If you provide `id` Bucket will enrich the evaluation context with
+   * user attributes on Bucket servers.
    */
   user?: UserContext;
 
   /**
-   * Company related context. If you provide `id` Bucket will enrich the evaluation context with company attributes on Bucket servers.
+   * Company related context. If you provide `id` Bucket will enrich the evaluation context with
+   * company attributes on Bucket servers.
    */
   company?: CompanyContext;
 
@@ -165,6 +237,10 @@ export interface InitOptions {
    * Version of the SDK
    */
   sdkVersion?: string;
+
+  /**
+   * Whether to enable tracking. Defaults to `true`.
+   */
   enableTracking?: boolean;
 }
 
@@ -174,6 +250,9 @@ const defaultConfig: Config = {
   enableTracking: true,
 };
 
+/**
+ * Represents a feature.
+ */
 export interface Feature {
   /**
    * Result of feature flag evaluation
@@ -185,13 +264,16 @@ export interface 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;

diff --git a/packages/node-sdk/README.md b/packages/node-sdk/README.md
@@ -63,10 +63,12 @@ const boundClient = bucketClient.bindClient({
     id: "john_doe",
     name: "John Doe",
     email: "[email protected]",
+    avatar: "https://example.com/users/jdoe",
   },
   company: {
     id: "acme_inc",
     name: "Acme, Inc.",
+    avatar: "https://example.com/companies/acme",
   },
 });
 
@@ -242,7 +244,7 @@ See [example/app.ts](https://github.com/bucketco/bucket-javascript-sdk/tree/main
 ## Remote flag evaluation with stored context
 
 If you don't want to provide context each time when evaluating feature flags but
-rather you would like to utilise the attributes you sent to Bucket previously
+rather you would like to utilize the attributes you sent to Bucket previously
 (by calling `updateCompany` and `updateUser`) you can do so by calling `getFeaturesRemote`
 (or `getFeatureRemote` for a specific feature) with providing just `userId` and `companyId`.
 These methods will call Bucket's servers and feature flags will be evaluated remotely
@@ -368,6 +370,7 @@ to provide for easier navigation:
 
 - `name` -- display name for `user`/`company`,
 - `email` -- the email of the user.
+- `avatar` -- the URL for `user`/`company` avatar image.
 
 Attributes cannot be nested (multiple levels) and must be either strings,
 integers or booleans.

diff --git a/packages/node-sdk/src/types.ts b/packages/node-sdk/src/types.ts
@@ -397,19 +397,56 @@ export type Context = {
    * The user context. If no `id` key is set, the whole object is ignored.
    */
   user?: {
+    /**
+     * The identifier of the user.
+     */
     id: string | number | undefined;
+
+    /**
+     * The name of the user.
+     */
     name?: string | undefined;
+
+    /**
+     * The email of the user.
+     */
     email?: string | undefined;
+
+    /**
+     * The avatar URL of the user.
+     */
+    avatar?: string | undefined;
+
+    /**
+     * Custom attributes of the user.
+     */
     [k: string]: any;
   };
   /**
    * The company context. If no `id` key is set, the whole object is ignored.
    */
   company?: {
+    /**
+     * The identifier of the company.
+     */
     id: string | number | undefined;
+
+    /**
+     * The name of the company.
+     */
     name?: string | undefined;
+
+    /**
+     * The avatar URL of the company.
+     */
+    avatar?: string | undefined;
+
+    /**
+     * Custom attributes of the company.
+     */
     [k: string]: any;
   };
+
   /**
    * The other context. This is used for any additional context that is not related to user or company.
    */