@cshah18/sdk 4.13.0 → 4.15.0

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

@@ -1,4 +1,5 @@
 import { ApiClient } from "./api-client";
+import { GeoData, DeviceData } from "./types";
 /**
  * Analytics event interface matching backend expectations
  */
@@ -11,6 +12,12 @@ export interface AnalyticsEvent {
         pageUrl?: string;
         userAgent?: string;
         sdkVersion?: string;
+        groupId?: string;
+        channel?: string;
+        totalMembers?: number;
+        errorCode?: string;
+        errorMessage?: string;
+        [key: string]: unknown;
     };
 }
 /**
@@ -35,10 +42,58 @@ export declare class AnalyticsClient {
      * @internal
      */
     private sendEvent;
+    /**
+     * Track session init event fired when the SDK initializes
+     */
+    trackSessionInit(geo?: GeoData, device?: DeviceData): Promise<void>;
     /**
      * Track page view event
      */
     trackPageView(): Promise<void>;
+    /**
+     * Track creative view event (widget rendered and visible)
+     */
+    trackCreativeView(productId: string): Promise<void>;
+    /**
+     * Track popup/lobby modal open event
+     */
+    trackPopupOpen(productId: string, groupId?: string): Promise<void>;
+    /**
+     * Track join attempt event (before API call)
+     */
+    trackJoinAttempt(productId: string, groupId: string): Promise<void>;
+    /**
+     * Track successful group join event
+     */
+    trackJoinSuccess(productId: string, groupId: string): Promise<void>;
+    /**
+     * Track join failure event
+     */
+    trackJoinFailure(productId: string, groupId?: string, errorCode?: string, message?: string): Promise<void>;
+    /**
+     * Track already joined event (user attempts to join a group they're already in)
+     */
+    trackAlreadyJoined(productId: string, groupId?: string): Promise<void>;
+    /**
+     * Track group full view event (user sees a fulfilled/full group)
+     */
+    trackGroupFullView(productId: string, groupId?: string, totalMembers?: number): Promise<void>;
+    /**
+     * Track share click event
+     */
+    trackShareClick(productId: string, groupId?: string, channel?: string): Promise<void>;
+    /**
+     * Track group creation attempt event
+     */
+    trackGroupCreateAttempt(productId: string): Promise<void>;
+    /**
+     * Track successful group creation event
+     */
+    trackGroupCreateSuccess(productId: string, groupId: string): Promise<void>;
+    /**
+     * Track group creation failure event
+     */
+    trackGroupCreateFailure(productId: string, errorCode?: string, message?: string): Promise<void>;
     /**
      * Track custom event (extensible for future use)
      */

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

@@ -1,4 +1,4 @@
-import { ApiRequestOptions, ApiResponse, ApiClientConfig, ProductRewardData, ProductPrimaryGroupData, GroupJoinResponseData, GroupInviteResponseData, InviteResolveResponseData, AuthStrategy, ShareChannel, Contact, CheckoutValidationData, CheckoutConfirmData } from "./types";
+import { ApiRequestOptions, ApiResponse, ApiClientConfig, ProductRewardData, ProductContextData, ProductPrimaryGroupData, GroupJoinResponseData, GroupInviteResponseData, InviteResolveResponseData, AuthStrategy, ShareChannel, Contact, LeaveGroupResponseData, RecoverOrJoinGroupResponseData, CheckoutValidationData, CheckoutConfirmData } from "./types";
 /**
  * HTTP client for communicating with CoBuy API
  *
@@ -17,8 +17,11 @@ export declare class ApiClient {
     private botdScore;
     private traceId;
     private readonly rewardCache;
+    private readonly productContextCache;
     private readonly REWARD_CACHE_TTL;
-    private readonly pendingRequests;
+    private readonly PRODUCT_CONTEXT_CACHE_TTL;
+    private readonly pendingRewardRequests;
+    private readonly pendingContextRequests;
     constructor(config: ApiClientConfig);
     /**
      * Update the BotD (Bot Detection) score for fraud detection
@@ -168,6 +171,18 @@ export declare class ApiClient {
      * }
      */
     getTraceId(): string | null;
+    private getCachedProductContext;
+    private normalizePrimaryGroup;
+    private buildRewardDataFromContext;
+    private setProductContextCache;
+    /**
+     * Get product context information
+     *
+     * Uses the consolidated bootstrap endpoint so the SDK can resolve campaign,
+     * reward, primary group, and active groups in a single request.
+     */
+    getProductContext(productId: string): Promise<ApiResponse<ProductContextData>>;
+    private fetchProductContext;
     /**
      * Get product reward information
      *
@@ -431,6 +446,22 @@ export declare class ApiClient {
      * ```
      */
     setContact(contact: Contact): Promise<ApiResponse<void>>;
+    /**
+     * Leave an active group for the current SDK session.
+     */
+    leaveGroup(groupId: string, params?: {
+        leave_source?: "close_icon" | "browser_close" | "unknown";
+        leave_reason?: "voluntary_with_contact" | "voluntary_no_contact" | "unknown";
+    }): Promise<ApiResponse<LeaveGroupResponseData>>;
+    recoverOrJoinGroup(productId: string, contact?: Contact): Promise<ApiResponse<RecoverOrJoinGroupResponseData>>;
+    /**
+     * Best-effort leave signal for unload/pagehide scenarios.
+     * Uses fetch keepalive so it can run while page is closing.
+     */
+    leaveGroupBestEffort(groupId: string, params?: {
+        leave_source?: "close_icon" | "browser_close" | "unknown";
+        leave_reason?: "voluntary_with_contact" | "voluntary_no_contact" | "unknown";
+    }): void;
     /**
      * Prepare checkout for a group
      *

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

@@ -2,9 +2,12 @@
  * API endpoint paths for active CoBuy backend endpoints
  */
 export declare const API_ENDPOINTS: {
+    readonly PRODUCT_CONTEXT: "/v1/sdk/products/:productId/context";
     readonly PRODUCT_REWARD: "/v1/sdk/products/:productId/reward";
     readonly PRODUCT_PRIMARY_GROUP: "/v1/sdk/products/:productId/group/primary";
+    readonly PRODUCT_RECOVER_OR_JOIN_GROUP: "/v1/sdk/products/:productId/group/recover-or-join";
     readonly GROUP_JOIN: "/v1/sdk/groups/:groupId/join";
+    readonly GROUP_LEAVE: "/v1/sdk/groups/:groupId/leave";
     readonly GROUP_CREATE_AND_JOIN: "/v1/sdk/groups/new/join";
     readonly PRODUCT_ACTIVE_GROUPS: "/v1/sdk/products/:productId/groups/active";
     readonly GROUP_INVITE: "/v1/sdk/groups/:groupId/invite";

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

@@ -1,7 +1,8 @@
-import { InternalConfig, GroupFulfilledEvent, GroupCreatedEvent, GroupMemberJoinedEvent } from "./types";
-export type SocketEventName = "group:member:joined" | "group:created" | "group:fulfilled";
+import { InternalConfig, GroupFulfilledEvent, GroupCreatedEvent, GroupMemberJoinedEvent, GroupMemberLeftEvent } from "./types";
+export type SocketEventName = "group:member:joined" | "group:member:left" | "group:created" | "group:fulfilled";
 export interface SocketHandlers {
     onGroupMemberJoined?: (payload: GroupMemberJoinedEvent) => void;
+    onGroupMemberLeft?: (payload: GroupMemberLeftEvent) => void;
     onGroupCreated?: (payload: GroupCreatedEvent) => void;
     onGroupFulfilled?: (payload: GroupFulfilledEvent) => void;
 }

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

@@ -126,6 +126,29 @@ export interface PerformanceConfig {
 /**
  * Options for initializing the CoBuy SDK
  */
+/**
+ * Geographic data provided by the merchant at SDK init time
+ */
+export interface GeoData {
+    latitude?: number;
+    longitude?: number;
+    city?: string;
+    region?: string;
+    country?: string;
+    [key: string]: unknown;
+}
+/**
+ * Device data provided by the merchant at SDK init time
+ */
+export interface DeviceData {
+    /** "mobile" | "tablet" | "desktop" */
+    type?: string;
+    os?: string;
+    browser?: string;
+    screenWidth?: number;
+    screenHeight?: number;
+    [key: string]: unknown;
+}
 export interface CoBuyInitOptions {
     /**
      * Authentication mode (default: "public")
@@ -207,6 +230,16 @@ export interface CoBuyInitOptions {
      * ```
      */
     performance?: PerformanceConfig;
+    /**
+     * Optional geographic data for analytics (merchant-provided)
+     * Use when the merchant's backend has resolved geo info from IP or user input
+     */
+    geo?: GeoData;
+    /**
+     * Optional device data for analytics (merchant-provided)
+     * Collect from browser APIs (navigator, screen) and pass here
+     */
+    device?: DeviceData;
 }
 /**
  * Callback data structure for checkout events
@@ -272,6 +305,7 @@ export interface FulfilledGroup {
     campaign_id: string;
     campaign_name: string;
     campaign_status: string;
+    campaign_redemption_method?: "online" | "offline" | "both";
     participants_count: number;
     max_participants: number;
     status: string;
@@ -453,6 +487,10 @@ export interface ModalOptions {
      * Offline redemption data for fulfilled groups
      */
     offlineRedemption?: OfflineRedemption;
+    /**
+     * Campaign redemption method - controls which checkout options are shown
+     */
+    redemptionMethod?: "online" | "offline" | "both";
     /**
      * Optional callback when modal opens
      */
@@ -503,7 +541,7 @@ export interface Reward {
     id: string;
     name: string;
     type: RewardType;
-    value: string;
+    value: string | number;
     description: string | null;
     remaining_quantity: number;
     total_quantity: number;
@@ -523,14 +561,56 @@ export interface RewardEligibility {
  */
 export interface ProductRewardData {
     productId: string;
-    reward: Reward;
+    reward: Reward | null;
+    campaign_mode?: "group" | "no_group";
+    campaign_creative_id?: string | null;
+    eligibility: RewardEligibility;
+}
+export interface ProductContextProductData {
+    id: string;
+    external_product_id: string | null;
+    name: string;
+    description: string | null;
+    sku: string | null;
+    price: number;
+    images: unknown[];
+}
+export interface ProductContextCampaignData {
+    id: string;
+    name: string;
+    description: string | null;
+    status: string | null;
+    campaign_mode?: "group" | "no_group" | null;
+    min_group_size?: number | null;
+    total_groups_count?: number | null;
+    reward_type?: string | null;
+    reward_value?: string | number | null;
+    start_date?: string | null;
+    end_date?: string | null;
+    redemption_method?: "online" | "offline" | "both" | null;
+}
+export interface ProductContextData {
+    product_id: string;
+    product: ProductContextProductData | null;
+    campaign: ProductContextCampaignData | null;
+    reward: Reward | null;
+    primary_group: ProductPrimaryGroupData | null;
+    active_groups: Array<ProductPrimaryGroupData & {
+        is_member?: boolean;
+    }>;
     eligibility: RewardEligibility;
+    sdk: {
+        ready: boolean;
+        campaign_status: string | null;
+        has_primary_group: boolean;
+        active_group_count: number;
+    };
 }
 /**
  * Primary group information for a product (SCRUM-284)
  */
 export interface ProductPrimaryGroupData {
-    group: ProductPrimaryGroupData | PromiseLike<ProductPrimaryGroupData | null> | null;
+    group?: ProductPrimaryGroupData | null;
     id: string;
     group_name: string;
     description: string | null;
@@ -539,6 +619,7 @@ export interface ProductPrimaryGroupData {
     campaign_id: string | null;
     campaign_name: string | null;
     campaign_status: string | null;
+    campaign_redemption_method?: "online" | "offline" | "both";
     participants_count: number;
     max_participants: number;
     status: string;
@@ -558,6 +639,7 @@ export interface GroupJoinResponseData {
         status: string;
         expiry_at: string;
         timeLeftSeconds: number;
+        campaign_redemption_method?: "online" | "offline" | "both";
     };
     membership: {
         id: string;
@@ -568,6 +650,37 @@ export interface GroupJoinResponseData {
     product_id: string;
     offline_redemption?: OfflineRedemption;
 }
+export interface LeaveGroupResponseData {
+    left: boolean;
+    session_id: string;
+    group: {
+        id: string;
+        group_name: string;
+        description: string | null;
+        campaign_creative_id: string | null;
+        campaign_creative_name: string | null;
+        campaign_id: string | null;
+        campaign_name: string | null;
+        campaign_status: string | null;
+        campaign_redemption_method?: "online" | "offline" | "both";
+        participants_count: number;
+        max_participants: number;
+        status: string;
+        expiry_at: string;
+        timeLeftSeconds: number;
+    };
+    product_id?: string;
+}
+export interface RecoverOrJoinGroupResponseData extends GroupJoinResponseData {
+    recovery: {
+        recovered: boolean;
+        matched_by: "session" | "contact" | "none";
+        outcome: "existing_active_membership" | "rejoined_previous_group" | "joined_next_available_group" | "created_new_group";
+        previous_group_id?: string;
+        joined_group_id: string;
+    };
+}
+export type GroupMemberLeftEvent = LeaveGroupResponseData;
 export type ShareChannel = "whatsapp" | "facebook" | "email" | "sms" | "copy_link" | "tiktok" | "x" | "other";
 export interface GroupInviteResponseData {
     invite_url?: string;
@@ -768,6 +881,8 @@ export interface InternalConfig {
         maxRetries: number;
         animationSpeed: "fast" | "normal" | "slow";
     };
+    geo?: GeoData;
+    device?: DeviceData;
 }
 /**
  * Group status enumeration

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

@@ -1,4 +1,5 @@
 import { ApiClient } from "../../core/api-client";
+import { AnalyticsClient } from "../../core/analytics";
 import { ProductPrimaryGroupData, GroupJoinResponseData } from "../../core/types";
 export interface GroupListItem {
     groupId: string;
@@ -27,12 +28,15 @@ export declare class GroupListModal {
     private currentJoinedGroupId;
     private currentProductId;
     private currentSessionId;
+    private analyticsClient;
     private onGroupJoined;
     private onViewProgress;
     private socketListenerRegistered;
     private readonly escapeHandler;
     private readonly handleGroupMemberJoinedEvent;
     constructor(groups?: GroupListItem[], liveCount?: number, debug?: boolean, apiClient?: ApiClient | null);
+    /** Set the analytics client for event tracking */
+    setAnalyticsClient(client: AnalyticsClient): void;
     /** Set callback for when a group is joined successfully */
     setOnGroupJoined(callback: (joinData: GroupJoinResponseData) => void): void;
     /** Set callback for when viewing progress on an already joined group */

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

@@ -1,4 +1,5 @@
 import { ApiClient } from "../../core/api-client";
+import { AnalyticsClient } from "../../core/analytics";
 import { OfflineRedemption } from "../../core/types";
 import { SocketManager } from "../../core/socket";
 import "./styles/styles.css";
@@ -17,6 +18,7 @@ export interface LobbyModalData {
     activities?: ActivityItem[];
     isLocked?: boolean;
     offlineRedemption?: OfflineRedemption;
+    redemptionMethod?: "online" | "offline" | "both";
 }
 export interface ActivityItem {
     emoji: string;
@@ -31,6 +33,9 @@ export interface LobbyModalCallbacks {
     onCopyLink?: (link: string) => void;
     onShare?: () => void;
 }
+interface CloseOptions {
+    skipLeaveFlow?: boolean;
+}
 /**
  * LobbyModal - Renders and manages the group buying lobby modal
  */
@@ -38,6 +43,7 @@ export declare class LobbyModal {
     private readonly logger;
     private readonly socketManager;
     private readonly apiClient;
+    private readonly analyticsClient;
     private modalElement;
     private data;
     private readonly callbacks;
@@ -48,7 +54,36 @@ export declare class LobbyModal {
     private currentGroupId;
     private shareOverlay;
     private keyboardHandler;
-    constructor(data: LobbyModalData, callbacks: LobbyModalCallbacks, apiClient: ApiClient | null, socketManager?: SocketManager | null, debug?: boolean);
+    private leaveFlowInProgress;
+    private leaveSignalSent;
+    private hasContactProtection;
+    private initialContactPromptTimer;
+    private contactPromptOverlay;
+    private leaveLoaderOverlay;
+    private beforeUnloadHandler;
+    private pageHideHandler;
+    private visibilityChangeHandler;
+    private readonly CONTACT_PROTECTION_PREFIX;
+    private readonly LAST_LEFT_GROUP_PREFIX;
+    constructor(data: LobbyModalData, callbacks: LobbyModalCallbacks, apiClient: ApiClient | null, socketManager?: SocketManager | null, analyticsClient?: AnalyticsClient | null, debug?: boolean);
+    private getSessionId;
+    private getContactProtectionStorageKey;
+    private getLastLeftGroupStorageKey;
+    private readContactProtectionState;
+    private persistContactProtectionState;
+    private persistLastLeftGroup;
+    private clearInitialContactPromptTimer;
+    private clearContactPromptOverlay;
+    private showBlockingLoader;
+    private hideBlockingLoader;
+    private updateContactProtectionUI;
+    private showToastMessage;
+    private trackAnalyticsEvent;
+    private saveContactValue;
+    private openContactProtectionPrompt;
+    private openUnprotectedLeaveWarning;
+    private scheduleInitialContactPrompt;
+    private leaveGroupExplicitly;
     /**
      * Derive lock state from data so UI reflects completion
      */
@@ -103,6 +138,10 @@ export declare class LobbyModal {
      * Create link section (just the link box and share button, no wrapper)
      */
     private createLinkSection;
+    /**
+     * Create a standalone "Checkout Online" button for the link/share section
+     */
+    private createOnlineCheckoutButton;
     /**
      * Create offline redemption section
      */
@@ -251,10 +290,16 @@ export declare class LobbyModal {
      * Clean up keyboard event listeners
      */
     private removeKeyboardAccessibility;
+    private registerLifecycleLeaveHandlers;
+    private unregisterLifecycleLeaveHandlers;
+    private triggerBestEffortLeave;
+    private shouldRunLeaveFlow;
+    private inferContactType;
+    private runLeaveFlowAndClose;
     /**
      * Close the modal
      */
-    close(): void;
+    close(options?: CloseOptions): void;
     /**
      * Check if modal is open
      */
@@ -291,6 +336,7 @@ export declare class LobbyModal {
      * Subscribe to socket events
      */
     private subscribeToSocketEvents;
+    private unsubscribeFromSocketEvents;
     /**
      * Handle socket group update events
      */
@@ -308,3 +354,4 @@ export declare class LobbyModal {
      */
     private updateTeamCard;
 }
+export {};

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

@@ -30,6 +30,7 @@ export declare class WidgetRoot {
     private groupExpiryRefreshTriggered;
     private offlineRedemption;
     private offlineRedemptionModal;
+    private campaignRedemptionMethod;
     private isRendering;
     private renderPromise;
     private liveRegionAnnouncer;
@@ -38,11 +39,16 @@ export declare class WidgetRoot {
     private renderDebounceTimer;
     private pendingRenderOptions;
     private readonly RENDER_DEBOUNCE_MS;
+    private readonly LAST_LEFT_GROUP_PREFIX;
     /**
      * Get max retries from config (configurable via performance options)
      */
     private get MAX_RETRIES();
     constructor(config: InternalConfig, apiClient: ApiClient | null, analyticsClient?: AnalyticsClient | null);
+    private getRecoveryStorageKey;
+    private getStoredRecoveryGroupId;
+    private clearStoredRecoveryGroupId;
+    private showRecoveryToast;
     /** Subscribe once to backend socket events routed through the host page */
     private subscribeToSocketEvents;
     /** Handle backend fulfillment notifications */
@@ -185,4 +191,10 @@ export declare class WidgetRoot {
      * Expose current product id for optional filtering by host
      */
     getProductId(): string | null;
+    /**
+     * Returns the group ID that the current user has joined via this widget, or null if the user
+     * is only an observer (has not actively joined a group this session).
+     * Used by the CoBuy host class to check membership before preparing checkout.
+     */
+    getJoinedGroupId(): string | null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cshah18/sdk",
-  "version": "4.13.0",
+  "version": "4.15.0",
   "description": "CoBuy Embedded SDK for browser JavaScript integration",
   "type": "module",
   "main": "dist/cobuy-sdk.umd.js",