@cshah18/sdk 4.8.0 → 4.10.0

package/dist/types/ui/widget/theme.d.ts

@@ -1,19 +1,137 @@
 import { CoBuyThemeOptions } from "../../core/types";
 /**
- * Merge global theme with optional widget-specific overrides
- * Priority: widgetTheme > globalTheme > defaults
+ * Merge global theme with widget-specific theme overrides
+ *
+ * Combines multiple theme objects with priority: widgetTheme > globalTheme > defaults.
+ * Validates all color and style values, falling back to defaults if invalid.
+ *
+ * @param {CoBuyThemeOptions} [globalTheme={}] - Global theme to apply to all widgets
+ * @param {string} [globalTheme.primaryColor] - Primary brand color (validated as CSS color)
+ * @param {string} [globalTheme.secondaryColor] - Secondary brand color
+ * @param {string} [globalTheme.textColor] - Text color for widget
+ * @param {string} [globalTheme.borderRadius] - Border radius for widget elements (CSS size value)
+ * @param {string} [globalTheme.fontFamily] - Font family for widget text
+ * @param {"none" | "fast" | "normal" | "slow"} [globalTheme.animationSpeed] - Animation speed
+ * @param {"none" | "subtle" | "smooth" | "bouncy"} [globalTheme.animationStyle] - Animation style
+ *
+ * @param {CoBuyThemeOptions} [widgetTheme={}] - Widget-specific theme overrides (takes priority over global)
+ * @param {string} [widgetTheme.primaryColor] - Override primary color
+ * @param {string} [widgetTheme.secondaryColor] - Override secondary color
+ * @param {string} [widgetTheme.textColor] - Override text color
+ * @param {string} [widgetTheme.borderRadius] - Override border radius
+ * @param {string} [widgetTheme.fontFamily] - Override font family
+ * @param {"none" | "fast" | "normal" | "slow"} [widgetTheme.animationSpeed] - Override animation speed
+ * @param {"none" | "subtle" | "smooth" | "bouncy"} [widgetTheme.animationStyle] - Override animation style
+ *
+ * @returns {Required<CoBuyThemeOptions>} Merged theme with all properties defined
+ *
+ * @description
+ * All theme values are validated:
+ * - Colors are checked against valid CSS color formats
+ * - Border radius is validated as a CSS size value
+ * - Font family is validated as a non-empty string
+ * - Animation speeds and styles are checked against allowed values
+ * - Invalid values are logged and replaced with defaults
+ *
+ * @example
+ * ```typescript
+ * // Merge global and widget themes
+ * const theme = mergeTheme(
+ *   {
+ *     primaryColor: '#4f46e5',
+ *     fontFamily: 'Inter, sans-serif'
+ *   },
+ *   {
+ *     primaryColor: '#ff0000' // Override primary color for this widget
+ *   }
+ * );
+ * // Result: theme.primaryColor === '#ff0000'
+ *
+ * // With invalid color (falls back to default)
+ * const theme2 = mergeTheme(
+ *   { primaryColor: 'notacolor' },
+ *   {}
+ * );
+ * // Result: theme2.primaryColor === '#4f46e5' (default value)
+ * ```
  */
 export declare function mergeTheme(globalTheme?: CoBuyThemeOptions, widgetTheme?: CoBuyThemeOptions): Required<CoBuyThemeOptions>;
 /**
- * Apply theme to widget container using scoped CSS custom properties
- * This approach ensures:
- * 1. Styles are isolated to this widget instance
- * 2. No conflicts with merchant's global styles
- * 3. Easy runtime theme updates
- * 4. Browser handles invalid values gracefully
+ * Apply theme to widget container using CSS custom properties
+ *
+ * Sets scoped CSS variables on the container element to apply theme colors,
+ * sizing, fonts, and animations. This approach isolates styles to the widget
+ * instance and prevents conflicts with merchant's global styles.
+ *
+ * @param {HTMLElement} container - The DOM element to apply theme to
+ * @param {Required<CoBuyThemeOptions>} theme - The theme configuration to apply
+ * @param {string} theme.primaryColor - Primary brand color (applied to --cobuy-primary-color)
+ * @param {string} theme.secondaryColor - Secondary color (applied to --cobuy-secondary-color)
+ * @param {string} theme.textColor - Text color (applied to --cobuy-text-color)
+ * @param {string} theme.borderRadius - Border radius (applied to --cobuy-border-radius)
+ * @param {string} theme.fontFamily - Font family (applied to --cobuy-font-family)
+ * @param {AnimationSpeed} theme.animationSpeed - Animation speed for transitions
+ * @param {AnimationStyle} theme.animationStyle - Animation style/easing
+ *
+ * @returns {void}
+ *
+ * @description
+ * Sets the following CSS custom properties on the container:
+ * - `--cobuy-primary-color`: Primary brand color
+ * - `--cobuy-secondary-color`: Secondary color
+ * - `--cobuy-text-color`: Text color
+ * - `--cobuy-border-radius`: Border radius value
+ * - `--cobuy-font-family`: Font family stack
+ * - `--cobuy-animation-duration`: Duration in milliseconds
+ * - `--cobuy-animation-easing`: CSS easing function
+ * - `--cobuy-animation-transform`: CSS transform for animations
+ *
+ * @example
+ * ```typescript
+ * const container = document.getElementById('cobuy-widget');
+ * const theme = {
+ *   primaryColor: '#4f46e5',
+ *   secondaryColor: '#6366f1',
+ *   textColor: '#111827',
+ *   borderRadius: '8px',
+ *   fontFamily: 'Inter, sans-serif',
+ *   animationSpeed: 'normal',
+ *   animationStyle: 'smooth'
+ * };
+ *
+ * applyTheme(container, theme);
+ * // Now all widget styles use the applied theme colors and animations
+ * ```
  */
 export declare function applyTheme(container: HTMLElement, theme: Required<CoBuyThemeOptions>): void;
 /**
- * Get the default theme (useful for testing and documentation)
+ * Get the default theme configuration
+ *
+ * Returns a copy of the default theme used when no custom theme is provided.
+ * Useful for documentation, testing, or as a baseline for customization.
+ *
+ * @returns {Required<CoBuyThemeOptions>} Default theme with all properties defined
+ *
+ * @description
+ * Default values:
+ * - Primary Color: #4f46e5 (Indigo-600)
+ * - Secondary Color: #6366f1 (Indigo-500)
+ * - Text Color: #111827 (Gray-900)
+ * - Border Radius: 8px
+ * - Font Family: Inter, system-ui, -apple-system, sans-serif
+ * - Animation Speed: normal (300ms)
+ * - Animation Style: subtle (fade only)
+ *
+ * @example
+ * ```typescript
+ * const defaults = getDefaultTheme();
+ * console.log(defaults.primaryColor); // #4f46e5
+ *
+ * // Use default as base and customize
+ * const customTheme = {
+ *   ...getDefaultTheme(),
+ *   primaryColor: '#ff0000'
+ * };
+ * ```
  */
 export declare function getDefaultTheme(): Required<CoBuyThemeOptions>;

package/dist/types/ui/widget/widget-root.d.ts

@@ -5,17 +5,16 @@ import { AnalyticsClient } from "../../core/analytics";
  * WidgetRoot handles rendering of the CoBuy widget into a DOM container
  */
 export declare class WidgetRoot {
-    private logger;
-    private apiClient;
-    private analyticsClient;
-    private config;
-    private events?;
+    private readonly logger;
+    private readonly apiClient;
+    private readonly analyticsClient;
+    private readonly config;
+    private readonly events?;
     private state;
     private retryCount;
-    private readonly MAX_RETRIES;
     private currentProductId;
     private currentContainer;
-    private debouncedCTAClick;
+    private readonly debouncedCTAClick;
     private currentGroupData;
     private groupFulfilled;
     private frozenReward;
@@ -31,13 +30,25 @@ export declare class WidgetRoot {
     private groupExpiryRefreshTriggered;
     private offlineRedemption;
     private offlineRedemptionModal;
+    private isRendering;
+    private renderPromise;
+    private liveRegionAnnouncer;
+    private lastRenderedProductId;
+    private lastRenderedContainer;
+    private renderDebounceTimer;
+    private pendingRenderOptions;
+    private readonly RENDER_DEBOUNCE_MS;
+    /**
+     * Get max retries from config (configurable via performance options)
+     */
+    private get MAX_RETRIES();
     constructor(config: InternalConfig, apiClient: ApiClient | null, analyticsClient?: AnalyticsClient | null);
     /** Subscribe once to backend socket events routed through the host page */
     private subscribeToSocketEvents;
     /** Handle backend fulfillment notifications */
-    private handleGroupFulfilledEvent;
+    private readonly handleGroupFulfilledEvent;
     /** Handle realtime group creation/join events by refreshing group UI */
-    private handleGroupUpdatedEvent;
+    private readonly handleGroupUpdatedEvent;
     /** Fetch latest group data and re-render containers */
     private refreshGroupDataFromRealtime;
     /** Update widget and any external containers after realtime refresh */
@@ -59,10 +70,45 @@ export declare class WidgetRoot {
     private getGroupListModal;
     /**
      * Render the widget into the specified container
+     *
+     * Asynchronous method that renders the collaborative buying widget.
+     * Automatically fetches product data, groups, and set up event listeners.
+     * Includes request deduplication to prevent redundant API calls from rapid re-renders
+     * (e.g., React component re-rendering).
+     *
+     * @param {RenderWidgetOptions} options - Widget rendering options
+     * @returns {Promise<void>} Rejects if rendering fails
+     *
+     * @throws {CoBuyRenderError} If container not found or rendering fails
+     * @throws {CoBuyValidationError} If productId validation fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const widget = new WidgetRoot(config, apiClient, analyticsClient);
+     *   await widget.render({
+     *     productId: 'prod_123',
+     *     container: '#widget-container'
+     *   });
+     * } catch (error) {
+     *   if (error instanceof CoBuyRenderError) {
+     *     console.error('Widget render failed:', error.message);
+     *   }
+     * }
+     * ```
      */
     render(options: RenderWidgetOptions): Promise<void>;
+    /**
+     * Queued render that handles concurrent render protection
+     */
+    private doQueuedRender;
+    private doRender;
     /**
      * Fetch reward data with automatic retry on failure
+     *
+     * @param productId The product ID to fetch reward for
+     * @returns Promise with reward data on success, null on failure
+     * @internal State updates (LOADED/ERROR) are handled by the caller
      */
     private fetchRewardWithRetry;
     /**
@@ -97,6 +143,14 @@ export declare class WidgetRoot {
      * Handle retry button click - reset retry count and re-fetch
      */
     private handleRetry;
+    /**
+     * Get or create a live region announcer for screen reader announcements
+     */
+    private getOrCreateLiveRegion;
+    /**
+     * Announce a message to screen readers via live region
+     */
+    private announceToScreenReaders;
     private createWidget;
     /**
      * Inject base layout styles for responsive widget rendering

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cshah18/sdk",
-  "version": "4.8.0",
+  "version": "4.10.0",
   "description": "CoBuy Embedded SDK for browser JavaScript integration",
   "type": "module",
   "main": "dist/cobuy-sdk.umd.js",
@@ -11,6 +11,7 @@
   ],
   "scripts": {
     "build": "rollup -c",
+    "build:analyze": "ANALYZE=true rollup -c && echo '📊 Bundle analysis: open dist/stats.html'",
     "build:watch": "rollup -c -w",
     "lint": "eslint \"src/**/*.{ts,tsx}\"",
     "lint:fix": "eslint \"src/**/*.{ts,tsx}\" --fix",
@@ -29,6 +30,7 @@
   "author": "CoBuy",
   "license": "MIT",
   "dependencies": {
+    "@fingerprintjs/botd": "^2.0.0",
     "socket.io-client": "^4.7.5"
   },
   "devDependencies": {
@@ -46,6 +48,7 @@
     "prettier": "^3.7.4",
     "rollup": "^4.9.4",
     "rollup-plugin-postcss": "^4.0.2",
+    "rollup-plugin-visualizer": "^5.12.0",
     "tslib": "^2.6.2",
     "typescript": "^5.3.3"
   }