@cshah18/sdk 4.8.0 → 4.9.0

package/dist/types/core/validation.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Input validation helpers for SDK configuration and widget options
+ */
+/**
+ * Validate product ID format and constraints
+ *
+ * @param {string} productId - The product ID to validate
+ * @returns {boolean} True if product ID is valid, false otherwise
+ *
+ * @description
+ * Validates that a product ID meets the following criteria:
+ * - Must be a non-empty string
+ * - Maximum length of 200 characters
+ * - Cannot be only whitespace
+ *
+ * @example
+ * validateProductId("prod_123");        // ✅ true
+ * validateProductId("");                // ❌ false (empty)
+ * validateProductId("x".repeat(201));  // ❌ false (too long)
+ */
+export declare function validateProductId(productId: string): boolean;
+/**
+ * Validate CSS color format
+ *
+ * @param {string} color - The color value to validate
+ * @returns {boolean} True if color is valid CSS format, false otherwise
+ *
+ * @description
+ * Validates that a color value is valid CSS format. Supports:
+ * - **Hex Colors**: #RGB, #RRGGBB, #RRGGBBAA
+ * - **RGB/RGBA**: rgb(255, 0, 0), rgba(255, 0, 0, 0.5)
+ * - **HSL/HSLA**: hsl(0, 100%, 50%), hsla(0, 100%, 50%, 0.5)
+ * - **Named Colors**: transparent, inherit, initial, unset
+ *
+ * @example
+ * validateColor("#4f46e5");        // ✅ true (hex)
+ * validateColor("#4f46e5cc");      // ✅ true (hex with alpha)
+ * validateColor("rgb(0, 0, 0)");   // ✅ true (rgb)
+ * validateColor("notacolor");      // ❌ false (invalid)
+ */
+export declare function validateColor(color: string): boolean;
+/**
+ * Validate CSS border radius format
+ *
+ * @param {string} borderRadius - The border radius value to validate
+ * @returns {boolean} True if border radius is valid CSS format, false otherwise
+ *
+ * @description
+ * Validates that a border radius value is valid CSS format.
+ * Supports common CSS units: px, rem, em, %, ch, ex, vw, vh, vmin, vmax
+ *
+ * @example
+ * validateBorderRadius("8px");      // ✅ true
+ * validateBorderRadius("0.5rem");   // ✅ true
+ * validateBorderRadius("8");        // ✅ true (assumes pixels)
+ * validateBorderRadius("notsize");  // ❌ false
+ */
+export declare function validateBorderRadius(borderRadius: string): boolean;
+/**
+ * Validate CSS font family format
+ *
+ * @param {string} fontFamily - The font family value to validate
+ * @returns {boolean} True if font family is valid, false otherwise
+ *
+ * @description
+ * Validates that a font family value is suitable for use.
+ * - Must not be empty or whitespace-only
+ * - Maximum length of 500 characters
+ * - Can be single font or comma-separated list
+ *
+ * @example
+ * validateFontFamily("Inter, sans-serif");     // ✅ true
+ * validateFontFamily("'Courier New', monospace"); // ✅ true
+ * validateFontFamily("");                      // ❌ false (empty)
+ */
+export declare function validateFontFamily(fontFamily: string): boolean;
+/**
+ * Validate animation speed value
+ *
+ * @param {string} speed - The animation speed to validate
+ * @returns {boolean} True if speed is a valid animation speed value, false otherwise
+ *
+ * @description
+ * Validates that the animation speed is one of the predefined values.
+ * Valid values: "none", "fast", "normal", "slow"
+ *
+ * @example
+ * validateAnimationSpeed("normal");  // ✅ true
+ * validateAnimationSpeed("slow");    // ✅ true
+ * validateAnimationSpeed("fast");    // ✅ true (case-insensitive)
+ * validateAnimationSpeed("SLOW");    // ✅ true
+ * validateAnimationSpeed("instant"); // ❌ false (invalid value)
+ */
+export declare function validateAnimationSpeed(speed: string): boolean;
+/**
+ * Validate animation style value
+ *
+ * @param {string} style - The animation style to validate
+ * @returns {boolean} True if style is a valid animation style value, false otherwise
+ *
+ * @description
+ * Validates that the animation style is one of the predefined values.
+ * Valid values: "none", "subtle", "smooth", "bouncy"
+ * - *none*: No animation
+ * - *subtle*: Fade only (no movement)
+ * - *smooth*: Fade + slide animation
+ * - *bouncy*: Spring-like bounce effect
+ *
+ * @example
+ * validateAnimationStyle("subtle");  // ✅ true
+ * validateAnimationStyle("SMOOTH");  // ✅ true (case-insensitive)
+ * validateAnimationStyle("bouncy");  // ✅ true
+ * validateAnimationStyle("custom");  // ❌ false (invalid)
+ */
+export declare function validateAnimationStyle(style: string): boolean;
+/**
+ * Validate widget container (selector or element)
+ *
+ * @param {string | HTMLElement} container - CSS selector string or HTMLElement
+ * @returns {boolean} True if container is valid, false otherwise
+ *
+ * @description
+ * Validates that a container is either a valid CSS selector string or
+ * an actual HTMLElement instance for widget rendering.
+ *
+ * @example
+ * validateContainer("#my-widget");           // ✅ true (valid selector)
+ * validateContainer(document.getElementById("target")); // ✅ true (element)
+ * validateContainer("");                      // ❌ false (empty selector)
+ * validateContainer("   ");                   // ❌ false (whitespace)
+ */
+export declare function validateContainer(container: string | HTMLElement): boolean;
+/**
+ * Validate merchant authentication key
+ *
+ * @param {string} merchantKey - The merchant key to validate
+ * @returns {boolean} True if merchant key is valid, false otherwise
+ *
+ * @description
+ * Validates that a merchant key is properly formatted for authentication.
+ * - Must be a non-empty string
+ * - Maximum length of 500 characters
+ * - Cannot be whitespace-only
+ *
+ * @example
+ * validateMerchantKey("pk_live_abc123xyz");     // ✅ true
+ * validateMerchantKey("");                      // ❌ false (empty)
+ * validateMerchantKey("   ");                   // ❌ false (whitespace)
+ */
+export declare function validateMerchantKey(merchantKey: string): boolean;
+/**
+ * Validate session authentication token
+ *
+ * @param {string | Function} token - Session token string or function
+ * @returns {boolean} True if token is valid, false otherwise
+ *
+ * @description
+ * Validates that a session token is either:
+ * - A non-empty string token, OR
+ * - A function that returns a string or Promise<string> for async token retrieval
+ *
+ * This allows both static tokens and dynamic token providers.
+ *
+ * @example
+ * validateSessionToken("token_abc123");                    // ✅ true
+ * validateSessionToken(() => "dynamic_token");            // ✅ true
+ * validateSessionToken(async () => await fetchToken());   // ✅ true
+ * validateSessionToken("");                                // ❌ false (empty string)
+ * validateSessionToken({} as any);                         // ❌ false (not function)
+ */
+export declare function validateSessionToken(token: string | (() => string | Promise<string>)): boolean;

package/dist/types/index.d.ts

@@ -1,13 +1,12 @@
-import { CoBuy } from "./core/cobuy";
 import type { CoBuySDK } from "./core/types";
 export type { CoBuySDK };
 export * from "./core/types";
 export type { AuthStrategy } from "./core/auth-strategy";
 export { PublicKeyAuth, TokenAuth } from "./core/auth-strategy";
-declare const instance: CoBuy;
 declare global {
     interface Window {
         CoBuy?: CoBuySDK;
     }
 }
+declare const instance: CoBuySDK;
 export default instance;

package/dist/types/ui/group-list/group-list-modal.d.ts

@@ -17,10 +17,10 @@ export interface ApiGroupData extends ProductPrimaryGroupData {
  */
 export declare class GroupListModal {
     private overlayEl;
-    private logger;
+    private readonly logger;
     private groups;
     private liveCount;
-    private apiClient;
+    private readonly apiClient;
     private isLoading;
     private startButton;
     private countdownIntervals;
@@ -46,7 +46,7 @@ export declare class GroupListModal {
     /** Unsubscribe from socket events */
     private unsubscribeFromSocketEvents;
     /** Handle group member joined socket event and update groups list */
-    private onGroupMemberJoined;
+    private readonly onGroupMemberJoined;
     /** Update the rendered group card with new data */
     private updateGroupCard;
     open(productId?: string, sessionId?: string, joinedGroupId?: string): Promise<void>;

package/dist/types/ui/lobby/lobby-modal.d.ts

@@ -2,7 +2,6 @@ import { ApiClient } from "../../core/api-client";
 import { OfflineRedemption } from "../../core/types";
 import { AnalyticsClient } from "../../core/analytics";
 import { SocketManager } from "../../core/socket";
-import "./styles/styles.css";
 export interface LobbyModalData {
     productId: string;
     groupId?: string;
@@ -36,19 +35,20 @@ export interface LobbyModalCallbacks {
  * LobbyModal - Renders and manages the group buying lobby modal
  */
 export declare class LobbyModal {
-    private logger;
-    private analyticsClient;
-    private socketManager;
-    private apiClient;
+    private readonly logger;
+    private readonly analyticsClient;
+    private readonly socketManager;
+    private readonly apiClient;
     private modalElement;
     private data;
-    private callbacks;
+    private readonly callbacks;
     private timerInterval;
     private activityInterval;
     private activityCards;
     private socketListenerRegistered;
     private currentGroupId;
     private shareOverlay;
+    private keyboardHandler;
     constructor(data: LobbyModalData, callbacks: LobbyModalCallbacks, apiClient: ApiClient | null, analyticsClient: AnalyticsClient | null, socketManager?: SocketManager | null, debug?: boolean);
     /**
      * Derive lock state from data so UI reflects completion
@@ -120,6 +120,12 @@ export declare class LobbyModal {
      * Inject styles for offline redemption section
      */
     private injectOfflineRedemptionStyles;
+    /**
+     * Inject lobby styles into the document head
+     * This is called once when the first lobby modal is created
+     */
+    private static stylesInjected;
+    private injectLobbyStyles;
     /**
      * Trigger the same checkout flow as clicking "Continue to Checkout" on the widget
      */
@@ -240,6 +246,18 @@ export declare class LobbyModal {
      * Open/render the modal
      */
     open(groupId?: string): void;
+    /**
+     * Set up keyboard accessibility features: ESC to close and Tab focus trap
+     */
+    private setupKeyboardAccessibility;
+    /**
+     * Get all focusable elements within the modal
+     */
+    private getFocusableElements;
+    /**
+     * Clean up keyboard event listeners
+     */
+    private removeKeyboardAccessibility;
     /**
      * Close the modal
      */
@@ -286,7 +304,7 @@ export declare class LobbyModal {
     /**
      * Handle socket group update events
      */
-    private handleSocketGroupUpdate;
+    private readonly handleSocketGroupUpdate;
     /**
      * Create activity item from socket event data
      */

package/dist/types/ui/offline-redemption/offline-redemption-modal.d.ts

@@ -5,8 +5,8 @@
 import { OfflineRedemption } from "../../core/types";
 export declare class OfflineRedemptionModal {
     private modalElement;
-    private offlineRedemption;
-    private onClose?;
+    private readonly offlineRedemption;
+    private readonly onClose?;
     constructor(offlineRedemption: OfflineRedemption, onClose?: () => void);
     /**
      * Open the modal

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.9.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"
   }