@cshah18/sdk 4.7.0 → 4.9.0

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

@@ -6,17 +6,18 @@ import { SocketManager } from "./socket";
  * Main CoBuy SDK implementation
  */
 export declare class CoBuy implements CoBuySDK {
-    private configManager;
-    private logger;
+    private readonly configManager;
+    private readonly logger;
     private apiClient;
     private analyticsClient;
     private sessionId;
+    private botdScore;
     private readonly SESSION_STORAGE_KEY;
     private readonly CHECKOUT_REF_PREFIX;
     private lobbyModal;
-    private modals;
+    private readonly modals;
     private socketManager;
-    private widgets;
+    private readonly widgets;
     constructor();
     /**
      * Initialize or retrieve existing session ID from storage
@@ -45,25 +46,175 @@ export declare class CoBuy implements CoBuySDK {
      * Get the current session ID (core SDK concept)
      */
     getSessionId(): string;
+    /**
+     * Initialize BotD detection and store score for API requests
+     */
+    private initializeBotd;
+    private handleFraudError;
     /**
      * Prepare checkout for a group if not already prepared
      * Checks localStorage to prevent duplicate calls for the same product/group/session
      */
     private prepareCheckoutIfNotDone;
     /**
-     * Initialize the SDK with configuration
+     * Initialize the CoBuy SDK with configuration
+     *
+     * Must be called before rendering widgets or opening modals.
+     *
+     * @param {CoBuyInitOptions} options - SDK configuration options
+     * @param {"public" | "token"} options.authMode - Authentication mode (public key or session token)
+     * @param {string} [options.merchantKey] - Merchant public key (required for public mode)
+     * @param {string | (() => string | Promise<string>)} [options.sessionToken] - Session token (required for token mode)
+     * @param {"dev" | "prod"} [options.env] - Environment (dev or prod, defaults to prod)
+     * @param {boolean} [options.debug] - Enable debug logging
+     * @param {Object} [options.auth] - Optional auth callbacks (onAuthError, onTokenExpired)
+     * @param {Object} [options.events] - Optional event handlers (onGroupFulfilled, onGroupCreated, onGroupMemberJoined, onModalOpen, onModalClose)
+     * @param {Object} [options.customHeaders] - Optional custom headers to include in API requests
+     *
+     * @throws {Error} If required configuration is missing or invalid
+     *
+     * @example
+     * ```typescript
+     * // Initialize with public key authentication
+     * CoBuy.init({
+     *   authMode: 'public',
+     *   merchantKey: 'pk_live_abc123xyz',
+     *   env: 'prod',
+     *   debug: false
+     * });
+     *
+     * // Initialize with session token
+     * CoBuy.init({
+     *   authMode: 'token',
+     *   sessionToken: 'token_abc123xyz',
+     *   env: 'prod'
+     * });
+     *
+     * // Initialize with async token provider
+     * CoBuy.init({
+     *   authMode: 'token',
+     *   sessionToken: async () => {
+     *     const response = await fetch('/api/token');
+     *     return response.json().token;
+     *   },
+     *   env: 'prod'
+     * });
+     * ```
      */
     init(options: CoBuyInitOptions): void;
     /**
      * Render the CoBuy widget into a DOM container
+     *
+     * Creates and renders a collaborative buying widget for a specific product.
+     * The widget displays group status, members, and allows users to join groups.
+     *
+     * @param {RenderWidgetOptions} options - Widget rendering options
+     * @param {string} options.productId - Product ID to render widget for (required)
+     * @param {string | HTMLElement} options.container - DOM selector or element to render into (required)
+     * @param {Object} [options.theme] - Optional theme configuration (colors, fonts, animations)
+     * @param {Function} [options.onGroupSelect] - Callback when user selects a group
+     * @param {Function} [options.onError] - Callback for rendering errors (optional, errors also throw)
+     *
+     * @returns {Promise<void>} Resolves when widget is rendered, rejects if rendering fails
+     *
+     * @throws {CoBuyNotInitializedError} If SDK not initialized before calling
+     * @throws {CoBuyRenderError} If container not found or rendering fails
+     * @throws {CoBuyValidationError} If productId validation fails
+     *
+     * @description
+     * Error Handling:
+     * - Synchronous errors (not initialized, missing productId) are thrown immediately
+     * - Asynchronous errors (network, container not found) cause Promise rejection
+     * - onError callback is called with error details (for backwards compatibility)
+     * - Always handle Promise rejection OR use try/catch for synchronous errors
+     *
+     * @example
+     * ```typescript
+     * // Option 1: Using try/catch (recommended)
+     * try {
+     *   await CoBuy.renderWidget({
+     *     productId: 'prod_abc123',
+     *     container: '#cobuy-widget-container'
+     *   });
+     * } catch (error) {
+     *   if (error instanceof CoBuyNotInitializedError) {
+     *     console.error('SDK not initialized');
+     *   } else if (error instanceof CoBuyRenderError) {
+     *     console.error('Widget render failed:', error.message);
+     *   }
+     * }
+     *
+     * // Option 2: Using .catch() (backwards compatible)
+     * CoBuy.renderWidget({
+     *   productId: 'prod_abc123',
+     *   container: '#widget'
+     * }).catch(error => {
+     *   console.error('Widget error:', error);
+     * });
+     *
+     * // Option 3: Using onError callback + error throwing
+     * CoBuy.renderWidget({
+     *   productId: 'prod_abc123',
+     *   container: '#widget',
+     *   onError: (error) => console.error('Async error:', error)
+     * }).catch(error => console.error('Promise rejected:', error));
+     * ```
      */
-    renderWidget(options: RenderWidgetOptions): void;
+    renderWidget(options: RenderWidgetOptions): Promise<void>;
     /**
-     * Open modal for product details
+     * Open a lobby modal for a group
+     *
+     * Displays a modal with group details, members, progress, and actions.
+     * Only one modal is open at a time (others are automatically closed).
+     *
+     * @param {ModalOptions} options - Modal configuration
+     * @param {string} options.productId - Product ID for the modal
+     * @param {string} [options.groupId] - Group ID to display
+     * @param {number} [options.groupNumber] - Group number for display
+     * @param {string} [options.status] - Group status (e.g., 'pending', 'complete')
+     * @param {number} [options.progress] - Group progress percentage (0-100)
+     * @param {number} [options.currentMembers] - Current number of members
+     * @param {number} [options.totalMembers] - Total members needed
+     * @param {number} [options.timeLeft] - Seconds remaining before group closes
+     * @param {number} [options.discount] - Discount percentage
+     * @param {string} [options.groupLink] - Share link for the group
+     * @param {Array} [options.activities] - Group activity feed
+     * @param {boolean} [options.isLocked] - Whether group is locked
+     * @param {Function} [options.onOpen] - Callback when modal opens
+     * @param {Function} [options.onClose] - Callback when modal closes
+     * @param {Function} [options.onCopyLink] - Callback when share link is copied
+     * @param {Function} [options.onShare] - Callback when share action triggered
+     *
+     * @returns {void}
+     *
+     * @example
+     * ```typescript
+     * CoBuy.openModal({
+     *   productId: 'prod_abc123',
+     *   groupId: 'grp_xyz789',
+     *   status: 'pending',
+     *   progress: 75,
+     *   currentMembers: 3,
+     *   totalMembers: 4,
+     *   discount: 20,
+     *   onOpen: () => console.log('Modal opened'),
+     *   onClose: () => console.log('Modal closed')
+     * });
+     * ```
      */
     openModal(options: ModalOptions): void;
     /**
-     * Close the modal
+     * Close the currently open modal
+     *
+     * Closes and cleans up the active lobby modal if one is open.
+     * Safe to call even if no modal is currently open.
+     *
+     * @returns {void}
+     *
+     * @example
+     * ```typescript
+     * CoBuy.closeModal();
+     * ```
      */
     closeModal(): void;
     /**
@@ -146,22 +297,83 @@ export declare class CoBuy implements CoBuySDK {
     confirmCheckout(groupId: string, checkoutRef: string, data?: CheckoutConfirmData): Promise<void>;
     /**
      * Get the initialized API client instance
+     *
+     * Returns the API client used for making requests to the CoBuy backend.
+     * Useful for advanced integrations or direct API calls.
+     *
+     * @returns {ApiClient | null} The API client instance, or null if SDK not initialized
+     *
+     * @example
+     * ```typescript
+     * const apiClient = CoBuy.getApiClient();
+     * if (apiClient) {
+     *   const product = await apiClient.getProductReward('prod_abc123');
+     * }
+     * ```
      */
     getApiClient(): ApiClient | null;
     /**
      * Get the initialized Analytics client instance
+     *
+     * Returns the analytics client used for tracking user interactions.
+     * Useful for advanced event tracking or integration with analytics systems.
+     *
+     * @returns {AnalyticsClient | null} The analytics client instance, or null if SDK not initialized
+     *
+     * @example
+     * ```typescript
+     * const analytics = CoBuy.getAnalyticsClient();
+     * if (analytics) {
+     *   await analytics.trackCustomEvent('user_action', { details: 'data' });
+     * }
+     * ```
      */
     getAnalyticsClient(): AnalyticsClient | null;
     /**
      * Get the initialized Socket manager instance
+     *
+     * Returns the socket manager used for real-time group updates.
+     * Only available in public authentication mode.
+     *
+     * @returns {SocketManager | null} The socket manager instance, or null if not initialized (token mode doesn't use sockets)
+     *
+     * @example
+     * ```typescript
+     * const socketManager = CoBuy.getSocketManager();
+     * if (socketManager) {
+     *   socketManager.bindHandlers({
+     *     onGroupCreated: (event) => console.log('New group:', event)
+     *   });
+     * }
+     * ```
      */
     getSocketManager(): SocketManager | null;
     /**
-     * Get SDK version
+     * Get the SDK version
+     *
+     * Returns the current version of the CoBuy SDK.
+     *
+     * @returns {string} SDK version in semver format (e.g., "1.0.0")
+     *
+     * @example
+     * ```typescript
+     * console.log(`CoBuy SDK v${CoBuy.version}`);
+     * ```
      */
     get version(): string;
     /**
-     * Clean up resources (sockets etc.) if needed by host app
+     * Destroy the SDK and clean up resources
+     *
+     * Closes websocket connections, unbinds event handlers, and releases resources.
+     * Call this when unloading the page or removing the SDK from use.
+     *
+     * @returns {void}
+     *
+     * @example
+     * ```typescript
+     * // When unmounting the SDK (e.g., React cleanup)
+     * CoBuy.destroy();
+     * ```
      */
     destroy(): void;
 }

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

@@ -8,13 +8,20 @@ export declare class ConfigManager {
      * Default API base URLs for each environment
      */
     private static readonly DEFAULT_API_URLS;
+    /**
+     * Get API base URL override from environment (if provided)
+     * Supports both browser global and build-time env injection
+     */
+    private static getApiBaseUrlOverride;
     /**
      * Set and validate SDK configuration
+     *
+     * @throws {CoBuyInvalidConfigError} If authMode, merchantKey, or sessionToken validation fails
      */
     setConfig(options: CoBuyInitOptions): InternalConfig;
     /**
      * Get current configuration
-     * @throws CoBuyNotInitializedError if SDK has not been initialized
+     * @throws {CoBuyNotInitializedError} if SDK has not been initialized
      */
     getConfig(): InternalConfig;
     /**

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

@@ -1,12 +1,116 @@
+/**
+ * Base class for all CoBuy SDK errors
+ * Provides consistent error structure across the SDK
+ */
+export declare class CoBuyError extends Error {
+    /**
+     * Error code for programmatic handling
+     * @example 'INVALID_CONFIG', 'NOT_INITIALIZED', 'RENDER_FAILED'
+     */
+    readonly code: string;
+    /**
+     * Additional error details (API response, validation info, etc.)
+     */
+    readonly details?: unknown;
+    constructor(message: string, code: string, details?: unknown);
+}
 /**
  * Thrown when the SDK is used before initialization
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   CoBuy.renderWidget({...});
+ * } catch (error) {
+ *   if (error instanceof CoBuyNotInitializedError) {
+ *     console.log('SDK not initialized, call CoBuy.init() first');
+ *   }
+ * }
+ * ```
  */
-export declare class CoBuyNotInitializedError extends Error {
+export declare class CoBuyNotInitializedError extends CoBuyError {
     constructor();
 }
 /**
- * Thrown when invalid configuration is provided
+ * Thrown when invalid configuration is provided during initialization
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   CoBuy.init({
+ *     authMode: 'public'
+ *     // Missing merchantKey
+ *   });
+ * } catch (error) {
+ *   if (error instanceof CoBuyInvalidConfigError) {
+ *     console.log('Config validation failed:', error.message);
+ *   }
+ * }
+ * ```
+ */
+export declare class CoBuyInvalidConfigError extends CoBuyError {
+    constructor(message: string, details?: unknown);
+}
+/**
+ * Thrown when widget rendering fails
+ * This includes container resolution, DOM manipulation, or state errors
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await CoBuy.renderWidget({
+ *     productId: 'prod_123',
+ *     container: '#nonexistent'
+ *   });
+ * } catch (error) {
+ *   if (error instanceof CoBuyRenderError) {
+ *     console.log('Widget render failed:', error.message);
+ *   }
+ * }
+ * ```
+ */
+export declare class CoBuyRenderError extends CoBuyError {
+    constructor(message: string, details?: unknown);
+}
+/**
+ * Thrown when API communication fails
+ * This includes network errors, CORS issues, timeouts, and server errors
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await CoBuy.joinGroup('grp_123', {type: 'email', value: 'user@example.com'});
+ * } catch (error) {
+ *   if (error instanceof CoBuyApiError) {
+ *     console.log('API request failed:', error.code, error.message);
+ *     if (error.details?.statusCode === 429) {
+ *       console.log('Rate limited - retry later');
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export declare class CoBuyApiError extends CoBuyError {
+    constructor(message: string, code?: string, details?: unknown);
+}
+/**
+ * Thrown when input validation fails
+ * This includes invalid product IDs, container selectors, or option values
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await CoBuy.renderWidget({
+ *     productId: '', // Invalid: empty string
+ *     container: '#widget'
+ *   });
+ * } catch (error) {
+ *   if (error instanceof CoBuyValidationError) {
+ *     console.log('Invalid input:', error.message);
+ *   }
+ * }
+ * ```
  */
-export declare class CoBuyInvalidConfigError extends Error {
-    constructor(message: string);
+export declare class CoBuyValidationError extends CoBuyError {
+    constructor(message: string, details?: unknown);
 }

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

@@ -73,6 +73,56 @@ export interface AuthCallbacks {
      */
     onTokenExpired?: () => void | Promise<void>;
 }
+/**
+ * Performance tuning options for SDK
+ *
+ * Use to optimize for your specific environment:
+ * - Slow networks: increase requestTimeout, maxRetries
+ * - Fast networks: decrease requestTimeout
+ * - Snappy UI: use 'fast' animationSpeed
+ * - Smooth UX: use 'normal' or 'smooth' animationSpeed
+ */
+export interface PerformanceConfig {
+    /**
+     * HTTP request timeout in milliseconds (default: 30000)
+     *
+     * Adjust based on your network conditions:
+     * - 10000 (10s): Fast networks, aggressively fail slow requests
+     * - 30000 (30s): Standard, most reliable networks
+     * - 60000 (60s): Slow/intermittent networks, flaky connectivity
+     *
+     * @example
+     * requestTimeout: 15000  // 15 second timeout
+     */
+    requestTimeout?: number;
+    /**
+     * Maximum number of retry attempts for transient errors (default: 2)
+     *
+     * Applies to timeout, 502, 503, 504 errors only
+     * Does not retry on permanent errors (400, 401, 403, 404, etc)
+     *
+     * Adjust based on reliability needs:
+     * - 1: Fast-fail, minimize latency (single attempt + 1 retry)
+     * - 2: Balanced approach (recommended)
+     * - 3+: Flaky networks, maximize reliability at cost of latency
+     *
+     * @example
+     * maxRetries: 3  // Up to 3 retry attempts (4 total attempts)
+     */
+    maxRetries?: number;
+    /**
+     * Animation speed for widget transitions (default: "normal")
+     *
+     * Affects all animations in the collaborative buying widget:
+     * - 'fast': 0.75x speed, snappy feel, 375ms-750ms transitions
+     * - 'normal': 1x speed, balanced, 500ms-1000ms transitions (default)
+     * - 'slow': 1.5x speed, smooth, 750ms-1500ms transitions
+     *
+     * @example
+     * animationSpeed: 'fast'  // For high-energy brand feel
+     */
+    animationSpeed?: "fast" | "normal" | "slow";
+}
 /**
  * Options for initializing the CoBuy SDK
  */
@@ -138,6 +188,25 @@ export interface CoBuyInitOptions {
          */
         theme?: CoBuyThemeOptions;
     };
+    /**
+     * Optional performance tuning for SDK
+     *
+     * Fine-tune SDK behavior for your specific network conditions and UX preferences.
+     * All values have safe defaults optimized for most use cases.
+     *
+     * @example
+     * ```typescript
+     * CoBuy.init({
+     *   merchantKey: 'pk_live_123',
+     *   performance: {
+     *     requestTimeout: 15000,      // 15s timeout for fast networks
+     *     maxRetries: 3,              // 3 retries for flaky networks
+     *     animationSpeed: 'fast'      // Snappy animations
+     *   }
+     * });
+     * ```
+     */
+    performance?: PerformanceConfig;
 }
 /**
  * Callback data structure for checkout events
@@ -259,6 +328,15 @@ export interface CheckoutRequestedEvent {
     groupId: string;
     productId: string;
 }
+/**
+ * Fraud detection error details
+ */
+export interface FraudDetectionError {
+    code: string;
+    message: string;
+    statusCode?: number;
+    context?: string;
+}
 /**
  * Widget event callbacks for lifecycle events
  */
@@ -275,6 +353,10 @@ export interface WidgetEvents {
      * Called when widget encounters an error loading reward data
      */
     onError?: (_productId: string, _error: Error) => void;
+    /**
+     * Called when a request is blocked by fraud detection
+     */
+    onFraudDetected?: (_error: FraudDetectionError) => void;
     /**
      * Called when user clicks "Buy with CoBuy" button
      */
@@ -639,6 +721,148 @@ export interface InternalConfig {
     theme: CoBuyThemeOptions;
     debug: boolean;
     events?: WidgetEvents;
+    performance: {
+        requestTimeout: number;
+        maxRetries: number;
+        animationSpeed: "fast" | "normal" | "slow";
+    };
+}
+/**
+ * Group status enumeration
+ * Represents the current state of a collaborative buying group
+ */
+export type GroupStatus = "active" | "pending" | "fulfilled" | "expired" | "cancelled";
+/**
+ * Group member information
+ * Represents a participant in a collaborative buying group
+ */
+export interface GroupMember {
+    /**
+     * Unique identifier for the member
+     */
+    id: string;
+    /**
+     * Session ID of the member
+     */
+    session_id: string;
+    /**
+     * Member's display name (if available)
+     */
+    name?: string;
+    /**
+     * Member's email (if available)
+     */
+    email?: string;
+    /**
+     * Member's phone (if available)
+     */
+    phone?: string;
+    /**
+     * Timestamp when member joined (ISO 8601)
+     */
+    joined_at: string;
+    /**
+     * Whether this member is the group creator
+     */
+    is_creator?: boolean;
+    /**
+     * Member's share/referral link (if applicable)
+     */
+    share_link?: string;
+}
+/**
+ * Group timeline/countdown information
+ * Tracks time-based milestones for a group
+ */
+export interface GroupTimeline {
+    /**
+     * Current Unix timestamp in milliseconds
+     */
+    now: number;
+    /**
+     * Group expiry timestamp (ISO 8601)
+     */
+    expiry_at: string;
+    /**
+     * Seconds remaining until group expires
+     */
+    timeLeftSeconds: number;
+    /**
+     * Percentage of time remaining (0-100)
+     */
+    timeLeftPercent: number;
+    /**
+     * Whether the group has expired
+     */
+    isExpired: boolean;
+    /**
+     * Whether the group is about to expire (< 5 minutes)
+     */
+    isExpiring: boolean;
+}
+/**
+ * Group activity entry
+ * Represents an action taken within a group
+ */
+export interface GroupActivity {
+    /**
+     * Activity type (join, share, fulfill, expire, etc)
+     */
+    type: "joined" | "shared" | "fulfilled" | "expired" | "cancelled" | "invited";
+    /**
+     * Human-readable description
+     */
+    description: string;
+    /**
+     * Timestamp of activity (ISO 8601)
+     */
+    timestamp: string;
+    /**
+     * Member ID who triggered the activity
+     */
+    actor_id?: string;
+    /**
+     * Additional metadata for the activity
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Complete group information
+ * Represents all data about a collaborative buying group
+ */
+export interface GroupInfo {
+    /**
+     * Group basic information
+     */
+    id: string;
+    name: string;
+    description?: string;
+    status: GroupStatus;
+    /**
+     * Participation tracking
+     */
+    participants_count: number;
+    max_participants: number;
+    members?: GroupMember[];
+    /**
+     * Campaign information
+     */
+    campaign_id: string;
+    campaign_name: string;
+    campaign_status?: string;
+    campaign_creative_name?: string;
+    /**
+     * Timeline and expiry
+     */
+    timeline: GroupTimeline;
+    /**
+     * Activity history
+     */
+    activities?: GroupActivity[];
+    /**
+     * Offline redemption details (if group is fulfilled)
+     */
+    offline_redemption?: OfflineRedemption;
 }
 /**
  * HTTP methods supported by the API client
@@ -665,6 +889,9 @@ export interface ApiResponse<T = unknown> {
     };
     success: boolean;
 }
+/**
+ * API client configuration
+ */
 /**
  * API client configuration
  */
@@ -672,8 +899,10 @@ export interface ApiClientConfig {
     baseUrl: string;
     authStrategy: AuthStrategy;
     sessionId: string;
+    botdScore?: number;
     debug?: boolean;
     timeout?: number;
+    maxRetries?: number;
 }
 /**
  * Authentication strategy interface (imported from auth-strategy.ts)