@cshah18/sdk 4.7.0 → 4.9.0

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

@@ -18,10 +18,10 @@ export interface AnalyticsEvent {
  * Uses session ID provided by the SDK for all analytics events
  */
 export declare class AnalyticsClient {
-    private logger;
-    private apiClient;
-    private sdkVersion;
-    private sessionId;
+    private readonly logger;
+    private readonly apiClient;
+    private readonly sdkVersion;
+    private readonly sessionId;
     constructor(_merchantKey: string, sdkVersion: string, sessionId: string, apiClient: ApiClient | null, debug?: boolean);
     /**
      * Track a CTA click event
@@ -29,6 +29,10 @@ export declare class AnalyticsClient {
     trackCtaClick(productId: string): Promise<void>;
     /**
      * Send event to backend analytics endpoint using unified ApiClient
+     *
+     * @throws {CoBuyApiError} If API request fails
+     * @private
+     * @internal
      */
     private sendEvent;
     /**

package/dist/types/core/api-client.d.ts

@@ -11,10 +11,30 @@ export declare class ApiClient {
     private baseUrl;
     private authStrategy;
     private sessionId;
-    private logger;
-    private defaultTimeout;
+    private readonly logger;
+    private readonly defaultTimeout;
+    private readonly maxRetries;
+    private botdScore;
     private traceId;
+    private readonly rewardCache;
+    private readonly REWARD_CACHE_TTL;
+    private readonly pendingRequests;
     constructor(config: ApiClientConfig);
+    /**
+     * Update the BotD (Bot Detection) score for fraud detection
+     *
+     * @param {number | undefined} score - The BotD score (0-100) or undefined to clear
+     * @returns {void}
+     *
+     * @description
+     * Sets the fraud detection score that will be included in API request headers.
+     * Used to improve fraud detection accuracy. Cleared if undefined is passed.
+     *
+     * @example
+     * CoBuy.getApiClient()?.setBotdScore(45); // Set BotD score
+     * CoBuy.getApiClient()?.setBotdScore(undefined); // Clear score
+     */
+    setBotdScore(score: number | undefined): void;
     /**
      * Generate a unique trace ID for request correlation
      */
@@ -24,7 +44,46 @@ export declare class ApiClient {
      */
     private isRetryableError;
     /**
-     * Make an HTTP request to the API with retry logic
+     * Make an authenticated HTTP request with automatic retry logic
+     *
+     * Low-level method for making requests to the API. Handles authentication headers,
+     * timeout management, error handling, and automatic retries for transient failures.
+     *
+     * @template T - The type of data returned on success
+     * @param {string} endpoint - The API endpoint path (e.g., '/products/12345/reward')
+     * @param {ApiRequestOptions} [options={}] - Request configuration options
+     * @param {"GET" | "POST" | "PUT" | "DELETE"} [options.method="GET"] - HTTP method
+     * @param {unknown} [options.body] - Request body (automatically JSON stringified)
+     * @param {Record<string, string>} [options.headers] - Additional headers to include
+     * @param {number} [options.timeout] - Request timeout in milliseconds
+     *
+     * @returns {Promise<ApiResponse<T>>} Response with success flag and data or error
+     *
+     * @description
+     * Request Features:
+     * - Automatic authentication header injection from auth strategy
+     * - Session tracking via X-CoBuy-Session header
+     * - Request correlation via trace ID (X-CoBuy-Trace header)
+     * - Configurable timeout (default 30 seconds)
+     * - Automatic retry on transient errors (timeout, 502, 503, 504)
+     * - Exponential backoff: 100ms, 200ms, 400ms
+     * - Auth token refresh on 401/403 responses
+     * - Full response body logging in debug mode
+     *
+     * @example
+     * ```typescript
+     * const client = CoBuy.getApiClient();
+     * const response = await client.request('/products/abc123/groups', {
+     *   method: 'GET',
+     *   timeout: 15000
+     * });
+     *
+     * if (response.success) {
+     *   console.log('Groups:', response.data);
+     * } else {
+     *   console.error('Error:', response.error?.message);
+     * }
+     * ```
      */
     request<T = unknown>(endpoint: string, options?: ApiRequestOptions): Promise<ApiResponse<T>>;
     /**
@@ -52,44 +111,157 @@ export declare class ApiClient {
      */
     delete<T = unknown>(endpoint: string, options?: Omit<ApiRequestOptions, "method" | "body">): Promise<ApiResponse<T>>;
     /**
-     * Update the base URL
+     * Update the API base URL
+     *
+     * @param {string} baseUrl - The new base URL for API requests
+     * @returns {void}
+     *
+     * @example
+     * CoBuy.getApiClient()?.setBaseUrl('https://api-staging.cobuy.com');
      */
     setBaseUrl(baseUrl: string): void;
     /**
-     * Update the auth strategy
+     * Update the authentication strategy
+     *
+     * @param {AuthStrategy} authStrategy - The new auth strategy to use
+     * @returns {void}
+     *
+     * @description
+     * Allows switching between public key and token-based authentication at runtime.
+     *
+     * @example
+     * const newAuth = new TokenAuth("new_token");
+     * CoBuy.getApiClient()?.setAuthStrategy(newAuth);
      */
     setAuthStrategy(authStrategy: AuthStrategy): void;
     /**
      * Get the current session ID
+     *
+     * @returns {string} The current session ID used for API requests
+     *
+     * @example
+     * const sessionId = CoBuy.getApiClient()?.getSessionId();
+     * console.log('Current session:', sessionId);
      */
     getSessionId(): string;
     /**
      * Update the session ID
+     *
+     * @param {string} sessionId - The new session ID for API requests
+     * @returns {void}
+     *
+     * @example
+     * CoBuy.getApiClient()?.setSessionId('new-session-uuid');
      */
     setSessionId(sessionId: string): void;
     /**
-     * Get the current trace ID
+     * Get the most recent request trace ID
+     *
+     * Useful for debugging and correlating client requests with server logs.
+     *
+     * @returns {string | null} The trace ID from the last request, or null if no requests made
+     *
+     * @example
+     * const traceId = CoBuy.getApiClient()?.getTraceId();
+     * if (traceId) {
+     *   console.log('Last request trace:', traceId); // Use for support tickets
+     * }
      */
     getTraceId(): string | null;
     /**
      * Get product reward information
      *
-     * Retrieves reward data and eligibility for a specific product.
-     * This is a core method for SCRUM-247: Retrieve reward information.
+     * Retrieves discount and reward eligibility for a specific product.
+     * Results are cached for 1 minute to reduce API load.
+     *
+     * @param {string} productId - The product ID to fetch reward information for
+     * @returns {Promise<ApiResponse<ProductRewardData>>} Product reward and eligibility data
      *
-     * @param productId - The product ID to fetch reward information for
-     * @returns Promise with reward data including eligibility status
+     * @description
+     * Features:
+     * - Caches results for 60 seconds to reduce API calls
+     * - Deduplicates concurrent requests for the same product
+     * - Includes reward amount, eligibility status, and discount percentage
+     *
+     * @throws Does not throw; returns ApiResponse with error details on failure
+     *
+     * @example
+     * ```typescript
+     * const response = await client.getProductReward('prod_abc123');
+     * if (response.success) {
+     *   console.log('Discount:', response.data?.discount_percentage);
+     *   console.log('Eligible:', response.data?.eligible);
+     * }
+     * ```
      */
     getProductReward(productId: string): Promise<ApiResponse<ProductRewardData>>;
     /**
-     * Get primary group information for a product (participants, max, expiry)
+     * Clear all cached product rewards
+     *
+     * Primarily used for testing or forcing fresh data from the server.
+     *
+     * @returns {void}
+     *
+     * @example
+     * CoBuy.getApiClient()?.clearRewardCache();
+     * // Next getProductReward call will fetch fresh data
+     */
+    clearRewardCache(): void;
+    private fetchProductReward;
+    /**
+     * Get primary group information for a product
+     *
+     * Retrieves the primary group data including member count, capacity, and expiry time.
+     * Optionally creates a new group if none exists.
+     *
+     * @param {string} productId - The product ID to fetch primary group for
+     * @returns {Promise<ApiResponse<ProductPrimaryGroupData>>} Primary group data or error
+     *
+     * @description
+     * Returns group information including:
+     * - Current participant count
+     * - Maximum participants allowed
+     * - Group status (pending, active, fulfilled, expired)
+     * - Time remaining for group to close
+     * - Group ID for joining operations
+     *
+     * @example
+     * ```typescript
+     * const response = await client.getProductPrimaryGroup('prod_abc123');
+     * if (response.success) {
+     *   const group = response.data;
+     *   console.log(`${group.participants_count}/${group.max_participants} members`);
+     * }
+     * ```
      */
     getProductPrimaryGroup(productId: string): Promise<ApiResponse<ProductPrimaryGroupData>>;
     /**
-     * Get active groups for a product
+     * Get all active groups for a product
+     *
+     * Retrieves a list of currently active groups for a product, including
+     * member count, capacity, and whether the current user is a member.
      *
-     * @param productId - The product ID to fetch active groups for
-     * @returns Promise with active groups list
+     * @param {string} productId - The product ID to fetch active groups for
+     * @returns {Promise<ApiResponse<{groups: Array}>>} List of active groups with member info
+     *
+     * @description
+     * Each group includes:
+     * - Group ID and number
+     * - Current and max participant counts
+     * - Status (pending, active, fulfilled, expired)
+     * - Time remaining before group closes
+     * - Whether current user is a member
+     * - Discount and reward information
+     *
+     * @example
+     * ```typescript
+     * const response = await client.getProductActiveGroups('prod_abc123');
+     * if (response.success) {
+     *   response.data?.groups.forEach(group => {
+     *     console.log(`Group ${group.group_number}: ${group.participants_count}/${group.max_participants}`);
+     *   });
+     * }
+     * ```
      */
     getProductActiveGroups(productId: string): Promise<ApiResponse<{
         groups: Array<ProductPrimaryGroupData & {
@@ -98,41 +270,163 @@ export declare class ApiClient {
     }>>;
     /**
      * Create a new group for a product and join it
+     *
+     * Creates a brand new group for a product and immediately adds the current
+     * user as the first member. Useful when no existing groups meet the user's needs.
+     *
+     * @param {string} productId - The product ID to create a group for
+     * @returns {Promise<ApiResponse<GroupJoinResponseData>>} New group info and join status
+     *
+     * @description
+     * Returns:
+     * - New group ID and number
+     * - User's membership confirmation
+     * - Group details (capacity, status, etc.)
+     * - Discount values
+     *
+     * @example
+     * ```typescript
+     * const response = await client.createAndJoinGroup('prod_abc123');
+     * if (response.success) {
+     *   const groupId = response.data?.group?.id;
+     *   console.log('Created new group:', groupId);
+     * }
+     * ```
      */
     createAndJoinGroup(productId: string): Promise<ApiResponse<GroupJoinResponseData>>;
     /**
-     * Join a group
+     * Join an existing group
+     *
+     * Adds the current user to an existing group, optionally providing contact
+     * information (email or phone) to enrich the session.
+     *
+     * @param {string} groupId - The group ID to join
+     * @param {Contact} [contact] - Optional contact information (email or phone)
+     * @param {"email" | "phone"} [contact.type] - Type of contact
+     * @param {string} [contact.value] - Email address or phone number
+     * @returns {Promise<ApiResponse<GroupJoinResponseData>>} Updated group info and join status
      *
-     * @param groupId - The group ID to join
-     * @param contact - Optional contact information to enrich the session
-     * @returns Promise with join result
+     * @description
+     * Actions:
+     * - Adds user to group members
+     * - Records contact information if provided
+     * - Updates group status if member count reaches maximum
+     * - Returns updated group details and member count
+     *
+     * @example
+     * ```typescript
+     * // Join without contact
+     * const response = await client.joinGroup('grp_xyz789');
+     *
+     * // Join with email
+     * const response = await client.joinGroup('grp_xyz789', {
+     *   type: 'email',
+     *   value: 'user@example.com'
+     * });
+     *
+     * // Join with phone
+     * const response = await client.joinGroup('grp_xyz789', {
+     *   type: 'phone',
+     *   value: '+1234567890'
+     * });
+     * ```
      */
     joinGroup(groupId: string, contact?: Contact): Promise<ApiResponse<GroupJoinResponseData>>;
     /**
-     * Send an invite/share event for a group
+     * Record a group share/invite event
+     *
+     * Tracks when a user shares or invites others to join a group via
+     * a specific channel (email, SMS, social, etc.). Helps analyze referral effectiveness.
+     *
+     * @param {string} groupId - The group ID being shared
+     * @param {ShareChannel} sharedVia - Channel used for sharing ("email", "sms", "whatsapp", "facebook", "twitter", "linkedin", "copy_link", "qr", "other")
+     * @returns {Promise<ApiResponse<GroupInviteResponseData>>} Invite tracking result
+     *
+     * @description
+     * Supported channels:
+     * - email: Email invitation
+     * - sms: SMS/text message
+     * - whatsapp: WhatsApp share
+     * - facebook: Facebook share
+     * - twitter: Twitter/X share
+     * - linkedin: LinkedIn share
+     * - copy_link: Direct link copy
+     * - qr: QR code scan
+     * - other: Other sharing method
+     *
+     * @example
+     * ```typescript
+     * // Track email share
+     * await client.inviteToGroup('grp_xyz789', 'email');
+     *
+     * // Track WhatsApp share
+     * await client.inviteToGroup('grp_xyz789', 'whatsapp');
+     *
+     * // Track copied link
+     * await client.inviteToGroup('grp_xyz789', 'copy_link');
+     * ```
      */
     inviteToGroup(groupId: string, sharedVia: ShareChannel): Promise<ApiResponse<GroupInviteResponseData>>;
     /**
      * Set or update contact information for the current session
      *
-     * Sends contact information (email or phone) to link with the current session.
-     * This allows merchants to identify a previously anonymous user.
-     * Backend will not overwrite existing stored contact.
-     * Safe to call multiple times (idempotent).
+     * Associates email or phone with the current session, allowing merchants
+     * to identify a previously anonymous user without requiring form submission.
+     *
+     * @param {Contact} contact - Contact information
+     * @param {"email" | "phone"} contact.type - Type of contact
+     * @param {string} contact.value - Email address or phone number
+     * @returns {Promise<ApiResponse<void>>} Success confirmation
+     *
+     * @description
+     * Features:
+     * - Idempotent: safe to call multiple times
+     * - Backend won't overwrite existing contact (if any)
+     * - Enables identifying returning customers
+     * - Enriches session data for analytics
+     *
+     * @example
+     * ```typescript
+     * // Set email
+     * await client.setContact({
+     *   type: 'email',
+     *   value: 'customer@example.com'
+     * });
      *
-     * @param contact - Contact information with type and value
-     * @returns Promise with success status
+     * // Set phone
+     * await client.setContact({
+     *   type: 'phone',
+     *   value: '+1-555-123-4567'
+     * });
+     * ```
      */
     setContact(contact: Contact): Promise<ApiResponse<void>>;
     /**
      * Prepare checkout for a group
      *
      * Signals the backend that the user is proceeding to checkout for a specific group.
-     * This allows the backend to prepare order data, lock pricing, and track conversion.
-     * Returns a checkout reference to be used in subsequent validate and confirm calls.
+     * Reserves order capacity, locks pricing, prepares order data, and enables conversion tracking.
+     * Must be completed before validateCheckout and confirmCheckout.
      *
-     * @param groupId - The group ID to prepare checkout for
-     * @returns Promise with success status and checkout reference
+     * @param {string} groupId - The group ID to prepare checkout for
+     * @returns {Promise<ApiResponse<{checkout_ref: string}>>} Checkout reference for use in subsequent calls
+     *
+     * @description
+     * Actions performed:
+     * - Validates group status and user membership
+     * - Reserves a seat in the group
+     * - Locks product reward/pricing
+     * - Generates a unique checkout reference
+     * - Enables server-side conversion tracking
+     *
+     * @example
+     * ```typescript
+     * const response = await client.prepareCheckout('grp_xyz789');
+     * if (response.success) {
+     *   const checkoutRef = response.data?.checkout_ref;
+     *   // Store this reference for validateCheckout and confirmCheckout
+     * }
+     * ```
      */
     prepareCheckout(groupId: string): Promise<ApiResponse<{
         checkout_ref: string;
@@ -141,22 +435,82 @@ export declare class ApiClient {
      * Validate checkout for a group
      *
      * Validates the checkout reference and confirms the order can proceed.
-     * This should be called after prepareCheckout to verify the checkout state.
+     * Verifies group status, user membership, and pricing consistency.
+     * Should be called after prepareCheckout and before confirmCheckout.
+     *
+     * @param {string} groupId - The group ID being checked out
+     * @param {string} checkoutRef - The checkout reference from prepareCheckout
+     * @returns {Promise<ApiResponse<CheckoutValidationData>>} Validation result with order details
+     *
+     * @description
+     * Validations performed:
+     * - Checkout reference is valid and not expired
+     * - User is still a valid group member
+     * - Group hasn't changed status since prepare
+     * - Pricing/reward data is consistent
+     * - Order can safely proceed
      *
-     * @param groupId - The group ID to validate checkout for
-     * @param checkoutRef - The checkout reference ID from the prepare step
-     * @returns Promise with success status
+     * @example
+     * ```typescript
+     * const validateResp = await client.validateCheckout('grp_xyz789', 'chk_abc123');
+     * if (validateResp.success) {
+     *   const order = validateResp.data;
+     *   console.log('Order total:', order.total);
+     *   console.log('Discount:', order.discount);
+     *   // Proceed to payment if validation passed
+     * }
+     * ```
      */
     validateCheckout(groupId: string, checkoutRef: string): Promise<ApiResponse<CheckoutValidationData>>;
     /**
      * Confirm checkout for a group
      *
-     * Finalizes the checkout and confirms the order.
-     * This should be called after validateCheckout to complete the checkout process.
+     * Finalizes and confirms the order after validation.
+     * Marks the order as complete, applies discounts, records the transaction,
+     * and triggers post-purchase workflows.
+     * Should be called after validateCheckout to complete the checkout flow.
+     *
+     * @param {string} groupId - The group ID being checked out
+     * @param {string} checkoutRef - The checkout reference from prepareCheckout
+     * @param {CheckoutConfirmData} [data] - Optional order details
+     * @param {string} [data.order_id] - Merchant's order ID for this purchase
+     * @param {number} [data.order_total] - Order total amount
+     * @param {number} [data.discount_applied] - Discount amount applied
+     * @param {string} [data.currency] - Currency code (e.g., "USD")
+     * @param {string} [data.payment_method] - Payment method used (e.g., "card", "paypal")
+     * @param {boolean} [data.micrositeCheckout] - Whether this was via microsite checkout
+     * @param {Record<string, unknown>} [data.metadata] - Custom metadata to attach to order
+     * @returns {Promise<ApiResponse<void>>} Confirmation result
+     *
+     * @description
+     * Actions performed after confirmation:
+     * - Order is recorded in the system
+     * - Discount is applied to the order
+     * - Group fulfillment may be triggered if complete
+     * - Merchant order system is updated
+     * - Customer receives confirmation
+     * - Post-purchase emails/notifications sent
+     * - Analytics events recorded
+     *
+     * @example
+     * ```typescript
+     * // Confirm with basic reference
+     * await client.confirmCheckout('grp_xyz789', 'chk_abc123');
      *
-     * @param groupId - The group ID to confirm checkout for
-     * @param checkoutRef - The checkout reference ID from the prepare step
-     * @returns Promise with success status
+     * // Confirm with order details
+     * await client.confirmCheckout('grp_xyz789', 'chk_abc123', {
+     *   order_id: 'ORDER-9001',
+     *   order_total: 99.99,
+     *   discount_applied: 20.00,
+     *   currency: 'USD',
+     *   payment_method: 'card',
+     *   metadata: {
+     *     coupon_code: 'WELCOME20',
+     *     channel: 'widget',
+     *     loyalty_member: true
+     *   }
+     * });
+     * ```
      */
     confirmCheckout(groupId: string, checkoutRef: string, data?: CheckoutConfirmData): Promise<ApiResponse<void>>;
 }

package/dist/types/core/auth-strategy.d.ts

@@ -25,9 +25,9 @@ export interface AuthStrategy {
  * Used for no-backend integrations with read-only endpoints
  */
 export declare class PublicKeyAuth implements AuthStrategy {
-    private merchantKey;
-    private logger;
-    private onError?;
+    private readonly merchantKey;
+    private readonly logger;
+    private readonly onError?;
     constructor(merchantKey: string, debug?: boolean, onError?: (error: Error) => void);
     getHeaders(): Record<string, string>;
     refreshIfNeeded(): Promise<boolean>;
@@ -38,11 +38,11 @@ export declare class PublicKeyAuth implements AuthStrategy {
  * Used for backend-integrated sites with full access to protected endpoints
  */
 export declare class TokenAuth implements AuthStrategy {
-    private tokenGetter;
+    private readonly tokenGetter;
     private currentToken;
-    private logger;
-    private onError?;
-    private onTokenExpired?;
+    private readonly logger;
+    private readonly onError?;
+    private readonly onTokenExpired?;
     private tokenRefreshPromise;
     constructor(tokenGetter: string | (() => string | Promise<string>), debug?: boolean, onError?: (error: Error) => void, onTokenExpired?: () => void | Promise<void>);
     getHeaders(): Record<string, string>;