Merge branch 'main' into buc-3198-extend-the-web-sdks-to-expose-the-config

pavkam · pavkam · commit 352a462b254b · 2025-01-28T12:57:13.000Z
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -39,8 +39,5 @@
     "**/*.lock": true
   },
   "typescript.tsdk": "node_modules/typescript/lib",
-  "cSpell.words": [
-    "bucketco",
-    "openfeature"
-  ]
+  "cSpell.words": ["bucketco", "openfeature"]
 }
diff --git a/packages/browser-sdk/README.md b/packages/browser-sdk/README.md
@@ -118,15 +118,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: "john@acme.com" },
-  company: { id: "company_123", name: "Acme, Inc" },
+  user: {
+    id: "user_123",
+    name: "John Doe",
+    email: "john@acme.com"
+    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
@@ -24,87 +24,162 @@ import { showToolbarToggle } from "./toolbar";
 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 the Bucket web app.
+   */
   appBaseUrl: string;
+
+  /**
+   * Base URL of Bucket servers for SSE connections used by AutoFeedback.
+   */
   sseBaseUrl: string;
+
+  /**
+   * Whether to enable tracking.
+   */
   enableTracking: boolean;
 }
 
+/**
+ * Toolbar options.
+ */
 export type ToolbarOptions =
   | boolean
   | {
       show?: boolean;
       position?: ToolbarPosition;
     };
 
+/**
+ * Feature definitions.
+ */
 export type FeatureDefinitions = Readonly<Array<string>>;
 
 /**
@@ -117,12 +192,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;
 
@@ -182,13 +259,18 @@ export interface InitOptions {
    * Version of the SDK
    */
   sdkVersion?: string;
+
+  /**
+   * Whether to enable tracking. Defaults to `true`.
+   */
   enableTracking?: boolean;
 
   /**
    * Toolbar configuration (alpha)
    * @ignore
    */
   toolbar?: ToolbarOptions;
+
   /**
    * Local-first definition of features (alpha)
    * @ignore
@@ -259,7 +341,6 @@ function shouldShowToolbar(opts: InitOptions) {
 
 /**
  * BucketClient lets you interact with the Bucket API.
- *
  */
 export class BucketClient {
   private readonly 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: "john@acme.com",
+    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
@@ -402,19 +402,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.
    */
