@cshah18/sdk 4.12.0 → 4.14.0

package/dist/cobuy-sdk.esm.js

@@ -452,6 +452,8 @@ class ConfigManager {
             debug,
             events: options.events,
             performance,
+            geo: options.geo,
+            device: options.device,
         };
         return this.config;
     }
@@ -819,6 +821,7 @@ class GroupListModal {
         this.currentJoinedGroupId = null;
         this.currentProductId = null;
         this.currentSessionId = null;
+        this.analyticsClient = null;
         this.onGroupJoined = null;
         this.onViewProgress = null;
         this.socketListenerRegistered = false;
@@ -833,6 +836,7 @@ class GroupListModal {
         /** Handle group member joined socket event and update groups list */
         this.onGroupMemberJoined = (event) => {
             const detail = event.detail || {};
+            console.log("eventttttt", detail);
             const productId = detail.product_id;
             const groupData = detail.group;
             // Only process if this is for the current product
@@ -865,6 +869,10 @@ class GroupListModal {
         this.apiClient = apiClient;
         this.injectStyles();
     }
+    /** Set the analytics client for event tracking */
+    setAnalyticsClient(client) {
+        this.analyticsClient = client;
+    }
     /** Set callback for when a group is joined successfully */
     setOnGroupJoined(callback) {
         this.onGroupJoined = callback;
@@ -1122,10 +1130,21 @@ class GroupListModal {
         buttonElement.disabled = true;
         const originalText = button.textContent;
         button.textContent = "Joining...";
+        const productId = this.currentProductId || "";
+        if (this.analyticsClient) {
+            this.analyticsClient
+                .trackJoinAttempt(productId, groupId)
+                .catch((e) => this.logger.warn("Analytics tracking failed", e));
+        }
         try {
             const response = await this.apiClient.joinGroup(groupId);
             if (response.success && response.data) {
                 this.logger.info(`[handleJoinGroup] Successfully joined group: ${groupId}`, response.data);
+                if (this.analyticsClient) {
+                    this.analyticsClient
+                        .trackJoinSuccess(productId, groupId)
+                        .catch((e) => this.logger.warn("Analytics tracking failed", e));
+                }
                 // Track the joined group
                 this.currentJoinedGroupId = groupId;
                 // Close the modal and trigger callback with the full join response data
@@ -1136,12 +1155,22 @@ class GroupListModal {
             }
             else {
                 this.logger.error("Failed to join group: API response unsuccessful");
+                if (this.analyticsClient) {
+                    this.analyticsClient
+                        .trackJoinFailure(productId, groupId)
+                        .catch((e) => this.logger.warn("Analytics tracking failed", e));
+                }
                 button.textContent = originalText;
                 buttonElement.disabled = false;
             }
         }
         catch (error) {
             this.logger.error("Error joining group", error);
+            if (this.analyticsClient) {
+                this.analyticsClient
+                    .trackJoinFailure(productId, groupId, "EXCEPTION", error instanceof Error ? error.message : String(error))
+                    .catch((e) => this.logger.warn("Analytics tracking failed", e));
+            }
             button.textContent = originalText;
             buttonElement.disabled = false;
         }
@@ -1162,10 +1191,21 @@ class GroupListModal {
         this.setJoinButtonsDisabled(true);
         const originalText = button.textContent;
         button.textContent = "Creating...";
+        const productId = this.currentProductId;
+        if (this.analyticsClient) {
+            this.analyticsClient
+                .trackGroupCreateAttempt(productId)
+                .catch((e) => this.logger.warn("Analytics tracking failed", e));
+        }
         try {
             const response = await this.apiClient.createAndJoinGroup(this.currentProductId);
             if (response.success && response.data) {
                 this.logger.info("Successfully created and joined new group", response.data);
+                if (this.analyticsClient) {
+                    this.analyticsClient
+                        .trackGroupCreateSuccess(productId, response.data.group.id)
+                        .catch((e) => this.logger.warn("Analytics tracking failed", e));
+                }
                 this.currentJoinedGroupId = response.data.group.id;
                 this.close();
                 if (this.onGroupJoined) {
@@ -1174,6 +1214,11 @@ class GroupListModal {
             }
             else {
                 this.logger.error("Failed to create group: API response unsuccessful");
+                if (this.analyticsClient) {
+                    this.analyticsClient
+                        .trackGroupCreateFailure(productId)
+                        .catch((e) => this.logger.warn("Analytics tracking failed", e));
+                }
                 button.textContent = originalText;
                 buttonElement.disabled = false;
                 this.setJoinButtonsDisabled(false);
@@ -1181,6 +1226,11 @@ class GroupListModal {
         }
         catch (error) {
             this.logger.error("Error creating group", error);
+            if (this.analyticsClient) {
+                this.analyticsClient
+                    .trackGroupCreateFailure(productId, "EXCEPTION", error instanceof Error ? error.message : String(error))
+                    .catch((e) => this.logger.warn("Analytics tracking failed", e));
+            }
             button.textContent = originalText;
             buttonElement.disabled = false;
             this.setJoinButtonsDisabled(false);
@@ -3578,14 +3628,13 @@ class LobbyModal {
             document.body.appendChild(this.modalElement);
             // Subscribe to realtime socket events
             this.subscribeToSocketEvents();
-            // If socket is available and connected, subscribe to this group
-            if (this.socketManager && this.socketManager.isConnected() && this.currentGroupId) {
-                this.logger.info(`[LobbyModal] Socket connected, subscribing to group ${this.currentGroupId}`);
+            // Subscribe to the group room for targeted events.
+            // Socket.IO client buffers emits until connected, so this is safe even
+            // if the handshake hasn't completed yet.
+            if (this.socketManager && this.currentGroupId) {
+                this.logger.info(`[LobbyModal] Subscribing to group room ${this.currentGroupId}`);
                 this.socketManager.subscribeToGroup(this.currentGroupId);
             }
-            else if (this.socketManager && !this.socketManager.isConnected()) {
-                this.logger.warn("[LobbyModal] Socket manager not connected yet");
-            }
             // Start timers and animations
             this.startTimer();
             this.startActivityAnimation();
@@ -4386,10 +4435,18 @@ class WidgetRoot {
         /** Handle backend fulfillment notifications */
         this.handleGroupFulfilledEvent = (event) => {
             const detail = event.detail;
-            if (!detail || !detail.productId) {
+            if (!detail || !detail.product_id) {
+                return;
+            }
+            if (this.currentProductId && detail.product_id !== this.currentProductId) {
                 return;
             }
-            if (this.currentProductId && detail.productId !== this.currentProductId) {
+            // Only enter the fulfilled/checkout flow for users who have actively joined a group this
+            // session. currentSessionId is set exclusively in the setOnGroupJoined callback (when the
+            // user completes a join API call). Observers who never joined should re-fetch the primary
+            // group API to display the updated group state instead.
+            if (!this.currentSessionId) {
+                void this.refreshGroupDataFromRealtime();
                 return;
             }
             this.processGroupFulfilled(detail);
@@ -4446,12 +4503,21 @@ class WidgetRoot {
             const groupData = await this.fetchPrimaryGroup(this.currentProductId);
             this.currentGroupData = groupData;
             this.currentGroupId = (groupData === null || groupData === void 0 ? void 0 : groupData.id) || this.currentGroupId;
-            // If backend signals completion via counts, reflect it
+            // If backend signals completion via counts, reflect it — but only for actual members.
+            // Observers may see a full group returned by fetchPrimaryGroup; they should NOT enter
+            // the checkout flow. currentSessionId is the membership signal (non-null = joined).
             if (groupData) {
                 const participants = Number(groupData.participants_count || 0);
                 const max = Number(groupData.max_participants || 0);
-                if (max > 0 && participants >= max) {
+                if (max > 0 && participants >= max && this.currentSessionId) {
                     this.groupFulfilled = true;
+                    // The primary group API returns offline_redemption for members of fulfilled groups.
+                    // Extract it here so renderFulfilledSummary shows the "Redeem In-store" link
+                    // (matching the UI users see on a full page reload).
+                    if (groupData.offline_redemption &&
+                        isValidOfflineRedemption(groupData.offline_redemption)) {
+                        this.offlineRedemption = groupData.offline_redemption;
+                    }
                 }
             }
             else {
@@ -4796,6 +4862,9 @@ class WidgetRoot {
     getGroupListModal() {
         if (!this.groupListModal) {
             this.groupListModal = new GroupListModal(undefined, 8, this.config.debug, this.apiClient);
+            if (this.analyticsClient) {
+                this.groupListModal.setAnalyticsClient(this.analyticsClient);
+            }
             // Set callback to open lobby when a group is successfully joined
             this.groupListModal.setOnGroupJoined((joinData) => {
                 var _a;
@@ -5021,6 +5090,11 @@ class WidgetRoot {
                     if (max > 0 && participants >= max) {
                         this.groupFulfilled = true;
                         this.logger.info("Group is already fulfilled on initial load", { participants, max });
+                        if (this.analyticsClient) {
+                            this.analyticsClient
+                                .trackGroupFullView(options.productId, groupData.id, max)
+                                .catch((e) => this.logger.warn("Analytics tracking failed", e));
+                        }
                     }
                 }
             }
@@ -5086,6 +5160,11 @@ class WidgetRoot {
                 // LOADED state - render widget only if we have group data
                 this.createWidget(rewardData, container, options);
                 this.logger.info(`Widget rendered for product: ${options.productId}`);
+                if (this.analyticsClient) {
+                    this.analyticsClient
+                        .trackCreativeView(options.productId)
+                        .catch((e) => this.logger.warn("Analytics tracking failed", e));
+                }
             }
             else {
                 // No group data available - hide widget
@@ -5737,7 +5816,7 @@ class WidgetRoot {
      * Handle CTA button click with analytics and modal opening
      */
     async handleCTAClick(productId) {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _e, _f, _g;
         this.logger.info(`CTA clicked for product: ${productId}`);
         // Track analytics event asynchronously (fire-and-forget)
         if (this.analyticsClient) {
@@ -5755,14 +5834,31 @@ class WidgetRoot {
         if (this.apiClient && this.currentGroupId) {
             try {
                 this.logger.info(`Joining group: ${this.currentGroupId}`);
+                if (this.analyticsClient) {
+                    this.analyticsClient
+                        .trackJoinAttempt(productId, this.currentGroupId)
+                        .catch((e) => this.logger.warn("Analytics tracking failed", e));
+                }
                 const joinResponse = await this.apiClient.joinGroup(this.currentGroupId);
                 if (!joinResponse.success) {
                     this.logger.error("Failed to join group, modal will not open", joinResponse.error);
+                    if (this.analyticsClient) {
+                        const errCode = (_c = joinResponse.error) === null || _c === void 0 ? void 0 : _c.code;
+                        const errMsg = (_d = joinResponse.error) === null || _d === void 0 ? void 0 : _d.message;
+                        this.analyticsClient
+                            .trackJoinFailure(productId, this.currentGroupId, errCode, errMsg)
+                            .catch((e) => this.logger.warn("Analytics tracking failed", e));
+                    }
                     this.setButtonLoadingState(false);
                     return; // Don't open modal on error
                 }
                 groupJoinData = joinResponse.data;
                 this.logger.info("Successfully joined group", groupJoinData);
+                if (this.analyticsClient && groupJoinData) {
+                    this.analyticsClient
+                        .trackJoinSuccess(productId, groupJoinData.group.id)
+                        .catch((e) => this.logger.warn("Analytics tracking failed", e));
+                }
                 this.offlineRedemption =
                     groupJoinData &&
                         groupJoinData.offline_redemption &&
@@ -5786,6 +5882,11 @@ class WidgetRoot {
             }
             catch (error) {
                 this.logger.error("Group join failed, modal will not open", error);
+                if (this.analyticsClient) {
+                    this.analyticsClient
+                        .trackJoinFailure(productId, (_e = this.currentGroupId) !== null && _e !== void 0 ? _e : undefined, "EXCEPTION", error instanceof Error ? error.message : String(error))
+                        .catch((e) => this.logger.warn("Analytics tracking failed", e));
+                }
                 this.setButtonLoadingState(false);
                 return; // Don't open modal on error
             }
@@ -5800,7 +5901,7 @@ class WidgetRoot {
                     const progress = Math.round((groupJoinData.group.participants_count / groupJoinData.group.max_participants) * 100);
                     // Format discount based on reward type
                     let discountText = "";
-                    if ((_d = (_c = this.currentRewardData) === null || _c === void 0 ? void 0 : _c.reward) === null || _d === void 0 ? void 0 : _d.value) {
+                    if ((_g = (_f = this.currentRewardData) === null || _f === void 0 ? void 0 : _f.reward) === null || _g === void 0 ? void 0 : _g.value) {
                         const rewardType = this.currentRewardData.reward.type;
                         const rewardValue = this.currentRewardData.reward.value;
                         if (rewardType === "percentage" || rewardType === "cashback") {
@@ -5840,6 +5941,11 @@ class WidgetRoot {
                         shareMessage: shareMessageFromInvite,
                         isLocked: !isGroupFulfilled,
                         offlineRedemption: offlineRedemptionFromJoin,
+                        onShare: this.analyticsClient
+                            ? () => {
+                                this.analyticsClient.trackShareClick(productId, groupJoinData.group.id, "other").catch((e) => this.logger.warn("Analytics tracking failed", e));
+                            }
+                            : undefined,
                         activities: [
                             {
                                 emoji: "👤",
@@ -5875,6 +5981,12 @@ class WidgetRoot {
                             },
                         ], // Will be populated from real-time data later
                     });
+                    // Track popup open after modal is launched
+                    if (this.analyticsClient) {
+                        this.analyticsClient
+                            .trackPopupOpen(productId, groupJoinData.group.id)
+                            .catch((e) => this.logger.warn("Analytics tracking failed", e));
+                    }
                     // Remove loading state after modal opens
                     this.setButtonLoadingState(false);
                 }
@@ -5981,6 +6093,14 @@ class WidgetRoot {
     getProductId() {
         return this.currentProductId;
     }
+    /**
+     * 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() {
+        return this.currentSessionId ? this.currentGroupId : null;
+    }
 }
 
 /**
@@ -5988,6 +6108,7 @@ class WidgetRoot {
  */
 const API_ENDPOINTS = {
     // Product endpoints
+    PRODUCT_CONTEXT: "/v1/sdk/products/:productId/context",
     PRODUCT_REWARD: "/v1/sdk/products/:productId/reward",
     PRODUCT_PRIMARY_GROUP: "/v1/sdk/products/:productId/group/primary",
     // Group endpoints
@@ -5998,6 +6119,8 @@ const API_ENDPOINTS = {
     GROUP_CHECKOUT_PREPARE: "/v1/sdk/groups/:groupId/checkout/prepare",
     GROUP_CHECKOUT_VALIDATE: "/v1/sdk/groups/:groupId/checkout/validate",
     GROUP_CHECKOUT_CONFIRM: "/v1/sdk/groups/:groupId/checkout/confirm",
+    // Invite endpoints
+    INVITE_RESOLVE: "/v1/sdk/invite/resolve",
 };
 /**
  * Build full API URL from base URL and endpoint path
@@ -6036,8 +6159,11 @@ class ApiClient {
         var _a;
         this.traceId = null;
         this.rewardCache = new Map();
+        this.productContextCache = new Map();
         this.REWARD_CACHE_TTL = 60000; // 1 minute
-        this.pendingRequests = new Map();
+        this.PRODUCT_CONTEXT_CACHE_TTL = 30000; // 30 seconds
+        this.pendingRewardRequests = new Map();
+        this.pendingContextRequests = new Map();
         this.baseUrl = config.baseUrl;
         this.authStrategy = config.authStrategy;
         this.sessionId = config.sessionId;
@@ -6433,6 +6559,106 @@ class ApiClient {
     getTraceId() {
         return this.traceId;
     }
+    getCachedProductContext(productId) {
+        const cached = this.productContextCache.get(productId);
+        if (cached && cached.expires > Date.now()) {
+            return cached.data;
+        }
+        if (cached) {
+            this.productContextCache.delete(productId);
+        }
+        return null;
+    }
+    normalizePrimaryGroup(groupData) {
+        if (!groupData) {
+            return null;
+        }
+        const nestedGroup = groupData.group;
+        if (nestedGroup && typeof nestedGroup === "object" && "id" in nestedGroup) {
+            return nestedGroup;
+        }
+        return groupData;
+    }
+    buildRewardDataFromContext(productId, context) {
+        var _a, _b, _c, _d, _e;
+        const primaryGroup = this.normalizePrimaryGroup(context.primary_group);
+        return {
+            productId,
+            reward: (_a = context.reward) !== null && _a !== void 0 ? _a : null,
+            campaign_mode: (_c = (_b = context.campaign) === null || _b === void 0 ? void 0 : _b.campaign_mode) !== null && _c !== void 0 ? _c : "group",
+            campaign_creative_id: (_d = primaryGroup === null || primaryGroup === void 0 ? void 0 : primaryGroup.campaign_creative_id) !== null && _d !== void 0 ? _d : null,
+            eligibility: (_e = context.eligibility) !== null && _e !== void 0 ? _e : { isEligible: false },
+        };
+    }
+    setProductContextCache(productId, context) {
+        this.productContextCache.set(productId, {
+            data: context,
+            expires: Date.now() + this.PRODUCT_CONTEXT_CACHE_TTL,
+        });
+        this.rewardCache.set(productId, {
+            data: this.buildRewardDataFromContext(productId, context),
+            expires: Date.now() + this.REWARD_CACHE_TTL,
+        });
+    }
+    /**
+     * 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.
+     */
+    async getProductContext(productId) {
+        if (!validateProductId(productId)) {
+            return {
+                success: false,
+                error: {
+                    message: "Invalid productId format. Must be a non-empty string (max 200 chars).",
+                    code: "INVALID_PRODUCT_ID",
+                },
+            };
+        }
+        // const cached = this.getCachedProductContext(productId);
+        // if (cached) {
+        //   this.logger.info(`Using cached product context for product: ${productId}`);
+        //   return {
+        //     success: true,
+        //     data: cached,
+        //   };
+        // }
+        const cacheKey = `context:${productId}`;
+        const pending = this.pendingContextRequests.get(cacheKey);
+        if (pending) {
+            this.logger.info(`Deduplicating product context request for: ${productId}`);
+            return pending;
+        }
+        const promise = this.fetchProductContext(productId).then((response) => {
+            if (response.success && response.data) {
+                this.setProductContextCache(productId, response.data);
+            }
+            return response;
+        });
+        this.pendingContextRequests.set(cacheKey, promise);
+        promise.then(() => this.pendingContextRequests.delete(cacheKey), () => this.pendingContextRequests.delete(cacheKey));
+        return promise;
+    }
+    async fetchProductContext(productId) {
+        var _a;
+        const endpoint = buildApiUrl("", API_ENDPOINTS.PRODUCT_CONTEXT, { productId });
+        this.logger.info(`Fetching product context for product: ${productId}`);
+        const response = await this.get(endpoint);
+        if (response.success && ((_a = response.data) === null || _a === void 0 ? void 0 : _a.data)) {
+            return {
+                success: true,
+                data: response.data.data,
+            };
+        }
+        return {
+            success: false,
+            error: response.error || {
+                message: "Failed to fetch product context data",
+                code: "PRODUCT_CONTEXT_FETCH_ERROR",
+            },
+        };
+    }
     /**
      * Get product reward information
      *
@@ -6477,13 +6703,31 @@ class ApiClient {
                 data: cached.data,
             };
         }
+        const cachedContext = this.getCachedProductContext(productId);
+        if (cachedContext) {
+            this.logger.info(`Using cached product context reward for product: ${productId}`);
+            return {
+                success: true,
+                data: this.buildRewardDataFromContext(productId, cachedContext),
+            };
+        }
         const cacheKey = `reward:${productId}`;
-        const pending = this.pendingRequests.get(cacheKey);
+        const pending = this.pendingRewardRequests.get(cacheKey);
         if (pending) {
             this.logger.info(`Deduplicating request for product: ${productId}`);
             return pending;
         }
-        const promise = this.fetchProductReward(productId).then((response) => {
+        const promise = (async () => {
+            const contextResponse = await this.getProductContext(productId);
+            if (contextResponse.success && contextResponse.data) {
+                return {
+                    success: true,
+                    data: this.buildRewardDataFromContext(productId, contextResponse.data),
+                };
+            }
+            this.logger.info(`Falling back to legacy reward endpoint for product: ${productId}`);
+            return this.fetchProductReward(productId);
+        })().then((response) => {
             if (response.success && response.data) {
                 this.rewardCache.set(productId, {
                     data: response.data,
@@ -6492,8 +6736,8 @@ class ApiClient {
             }
             return response;
         });
-        this.pendingRequests.set(cacheKey, promise);
-        promise.then(() => this.pendingRequests.delete(cacheKey), () => this.pendingRequests.delete(cacheKey));
+        this.pendingRewardRequests.set(cacheKey, promise);
+        promise.then(() => this.pendingRewardRequests.delete(cacheKey), () => this.pendingRewardRequests.delete(cacheKey));
         return promise;
     }
     /**
@@ -6509,6 +6753,7 @@ class ApiClient {
      */
     clearRewardCache() {
         this.rewardCache.clear();
+        this.productContextCache.clear();
     }
     async fetchProductReward(productId) {
         var _a;
@@ -6556,7 +6801,7 @@ class ApiClient {
      * ```
      */
     async getProductPrimaryGroup(productId) {
-        var _a;
+        var _a, _b;
         if (!validateProductId(productId)) {
             return {
                 success: false,
@@ -6566,15 +6811,38 @@ class ApiClient {
                 },
             };
         }
-        const endpoint = buildApiUrl("", API_ENDPOINTS.PRODUCT_PRIMARY_GROUP, { productId }, { allowAutoCreate: true });
-        this.logger.info(`Fetching primary group for product: ${productId}`);
-        const response = await this.get(endpoint);
-        if (response.success && ((_a = response.data) === null || _a === void 0 ? void 0 : _a.data)) {
+        // const cachedContext = this.getCachedProductContext(productId);
+        // const cachedGroup = this.normalizePrimaryGroup(cachedContext?.primary_group);
+        // if (cachedGroup) {
+        //   this.logger.info(`Using cached primary group from product context for product: ${productId}`);
+        //   return {
+        //     success: true,
+        //     data: {
+        //       ...cachedGroup,
+        //       group: cachedGroup,
+        //     },
+        //   };
+        // }
+        const contextResponse = await this.getProductContext(productId);
+        const contextGroup = this.normalizePrimaryGroup((_a = contextResponse.data) === null || _a === void 0 ? void 0 : _a.primary_group);
+        if (contextResponse.success && contextGroup) {
             return {
                 success: true,
-                data: response.data.data,
+                data: Object.assign(Object.assign({}, contextGroup), { group: contextGroup }),
             };
         }
+        const endpoint = buildApiUrl("", API_ENDPOINTS.PRODUCT_PRIMARY_GROUP, { productId }, { allowAutoCreate: true });
+        this.logger.info(`Fetching primary group for product: ${productId}`);
+        const response = await this.get(endpoint);
+        if (response.success && ((_b = response.data) === null || _b === void 0 ? void 0 : _b.data)) {
+            const normalizedGroup = this.normalizePrimaryGroup(response.data.data);
+            if (normalizedGroup) {
+                return {
+                    success: true,
+                    data: Object.assign(Object.assign({}, normalizedGroup), { group: normalizedGroup }),
+                };
+            }
+        }
         return {
             success: false,
             error: response.error || {
@@ -6622,6 +6890,25 @@ class ApiClient {
                 },
             };
         }
+        const cachedContext = this.getCachedProductContext(productId);
+        if (cachedContext) {
+            this.logger.info(`Using cached active groups from product context for product: ${productId}`);
+            return {
+                success: true,
+                data: {
+                    groups: (cachedContext.active_groups || []),
+                },
+            };
+        }
+        const contextResponse = await this.getProductContext(productId);
+        if (contextResponse.success && contextResponse.data) {
+            return {
+                success: true,
+                data: {
+                    groups: (contextResponse.data.active_groups || []),
+                },
+            };
+        }
         const endpoint = buildApiUrl("", API_ENDPOINTS.PRODUCT_ACTIVE_GROUPS, { productId });
         this.logger.info(`Fetching active groups for product: ${productId}`);
         const response = await this.get(endpoint);
@@ -6808,6 +7095,58 @@ class ApiClient {
             },
         };
     }
+    /**
+     * Resolve an invite token to get product and group information
+     *
+     * Resolves an invite link token (e.g., from https://brand.cobuyza.co.za/i/QMeHD7ew)
+     * to get the associated product, group, and invite metadata.
+     *
+     * @param {string} inviteToken - The invite token from the URL
+     * @returns {Promise<ApiResponse<InviteResolveResponseData>>} Product and group information
+     *
+     * @description
+     * Features:
+     * - Resolves invite tokens to product/group details
+     * - Tracks invite click counts
+     * - Returns invite metadata (shared_via, click_count)
+     * - Used for invite link handling in applications
+     *
+     * @example
+     * ```typescript
+     * // Resolve invite token from URL
+     * const response = await client.resolveInvite('QMeHD7ew');
+     *
+     * if (response.success) {
+     *   const productId = response.data.product.id;
+     *   const groupId = response.data.group.id;
+     *   // Navigate to product page
+     *   window.location.href = `/product/${productId}`;
+     * }
+     * ```
+     */
+    async resolveInvite(inviteToken) {
+        const endpoint = buildApiUrl("", API_ENDPOINTS.INVITE_RESOLVE, undefined, {
+            invite_token: inviteToken,
+        });
+        this.logger.info(`Resolving invite token: ${inviteToken}`);
+        const response = await this.get(endpoint);
+        if (response.success) {
+            const payload = response.data;
+            const inviteData = ((payload === null || payload === void 0 ? void 0 : payload.data) || response.data);
+            this.logger.info(`Invite resolved successfully for product: ${inviteData.product.id}`);
+            return {
+                success: true,
+                data: inviteData,
+            };
+        }
+        return {
+            success: false,
+            error: response.error || {
+                message: "Failed to resolve invite",
+                code: "INVITE_RESOLVE_ERROR",
+            },
+        };
+    }
     /**
      * Set or update contact information for the current session
      *
@@ -7074,6 +7413,7 @@ class AnalyticsClient {
         const event = {
             event: "CTA_CLICKED",
             productId,
+            sessionId: this.sessionId,
             timestamp: new Date().toISOString(),
             context: {
                 pageUrl: typeof window !== "undefined" ? window.location.href : undefined,
@@ -7126,12 +7466,32 @@ class AnalyticsClient {
             throw new CoBuyApiError(error instanceof Error ? error.message : "Unknown analytics error", "ANALYTICS_ERROR", { originalError: error });
         }
     }
+    /**
+     * Track session init event fired when the SDK initializes
+     */
+    async trackSessionInit(geo, device) {
+        const event = {
+            event: "SESSION_INIT",
+            sessionId: this.sessionId,
+            timestamp: new Date().toISOString(),
+            context: Object.assign(Object.assign({ pageUrl: typeof window !== "undefined" ? window.location.href : undefined, userAgent: typeof navigator !== "undefined" ? navigator.userAgent : undefined, sdkVersion: this.sdkVersion }, (geo ? { geo } : {})), (device ? { device } : {})),
+        };
+        try {
+            await this.sendEvent(event);
+            this.logger.info("[Analytics] Session init tracked");
+        }
+        catch (error) {
+            // Non-blocking
+            this.logger.error("[Analytics] Failed to track session init", error);
+        }
+    }
     /**
      * Track page view event
      */
     async trackPageView() {
         const event = {
             event: "PAGE_VIEW",
+            sessionId: this.sessionId,
             timestamp: new Date().toISOString(),
             context: {
                 pageUrl: typeof window !== "undefined" ? window.location.href : undefined,
@@ -7148,6 +7508,273 @@ class AnalyticsClient {
             this.logger.error("[Analytics] Failed to track page view", error);
         }
     }
+    /**
+     * Track creative view event (widget rendered and visible)
+     */
+    async trackCreativeView(productId) {
+        const event = {
+            event: "CREATIVE_VIEW",
+            productId,
+            sessionId: this.sessionId,
+            timestamp: new Date().toISOString(),
+            context: {
+                pageUrl: typeof window !== "undefined" ? window.location.href : undefined,
+                userAgent: typeof navigator !== "undefined" ? navigator.userAgent : undefined,
+                sdkVersion: this.sdkVersion,
+            },
+        };
+        try {
+            await this.sendEvent(event);
+            this.logger.info(`[Analytics] Creative view tracked for product: ${productId}`);
+        }
+        catch (error) {
+            this.logger.error("[Analytics] Failed to track creative view", error);
+        }
+    }
+    /**
+     * Track popup/lobby modal open event
+     */
+    async trackPopupOpen(productId, groupId) {
+        const event = {
+            event: "POPUP_OPEN",
+            productId,
+            sessionId: this.sessionId,
+            timestamp: new Date().toISOString(),
+            context: {
+                pageUrl: typeof window !== "undefined" ? window.location.href : undefined,
+                userAgent: typeof navigator !== "undefined" ? navigator.userAgent : undefined,
+                sdkVersion: this.sdkVersion,
+                groupId,
+            },
+        };
+        try {
+            await this.sendEvent(event);
+            this.logger.info(`[Analytics] Popup open tracked for product: ${productId}`);
+        }
+        catch (error) {
+            this.logger.error("[Analytics] Failed to track popup open", error);
+        }
+    }
+    /**
+     * Track join attempt event (before API call)
+     */
+    async trackJoinAttempt(productId, groupId) {
+        const event = {
+            event: "JOIN_ATTEMPT",
+            productId,
+            sessionId: this.sessionId,
+            timestamp: new Date().toISOString(),
+            context: {
+                pageUrl: typeof window !== "undefined" ? window.location.href : undefined,
+                userAgent: typeof navigator !== "undefined" ? navigator.userAgent : undefined,
+                sdkVersion: this.sdkVersion,
+                groupId,
+            },
+        };
+        try {
+            await this.sendEvent(event);
+            this.logger.info(`[Analytics] Join attempt tracked for product: ${productId}`);
+        }
+        catch (error) {
+            this.logger.error("[Analytics] Failed to track join attempt", error);
+        }
+    }
+    /**
+     * Track successful group join event
+     */
+    async trackJoinSuccess(productId, groupId) {
+        const event = {
+            event: "JOIN_SUCCESS",
+            productId,
+            sessionId: this.sessionId,
+            timestamp: new Date().toISOString(),
+            context: {
+                pageUrl: typeof window !== "undefined" ? window.location.href : undefined,
+                userAgent: typeof navigator !== "undefined" ? navigator.userAgent : undefined,
+                sdkVersion: this.sdkVersion,
+                groupId,
+            },
+        };
+        try {
+            await this.sendEvent(event);
+            this.logger.info(`[Analytics] Join success tracked for product: ${productId}`);
+        }
+        catch (error) {
+            this.logger.error("[Analytics] Failed to track join success", error);
+        }
+    }
+    /**
+     * Track join failure event
+     */
+    async trackJoinFailure(productId, groupId, errorCode, message) {
+        const event = {
+            event: "JOIN_FAILURE",
+            productId,
+            sessionId: this.sessionId,
+            timestamp: new Date().toISOString(),
+            context: {
+                pageUrl: typeof window !== "undefined" ? window.location.href : undefined,
+                userAgent: typeof navigator !== "undefined" ? navigator.userAgent : undefined,
+                sdkVersion: this.sdkVersion,
+                groupId,
+                errorCode,
+                errorMessage: message,
+            },
+        };
+        try {
+            await this.sendEvent(event);
+            this.logger.info(`[Analytics] Join failure tracked for product: ${productId}`);
+        }
+        catch (error) {
+            this.logger.error("[Analytics] Failed to track join failure", error);
+        }
+    }
+    /**
+     * Track already joined event (user attempts to join a group they're already in)
+     */
+    async trackAlreadyJoined(productId, groupId) {
+        const event = {
+            event: "ALREADY_JOINED",
+            productId,
+            sessionId: this.sessionId,
+            timestamp: new Date().toISOString(),
+            context: {
+                pageUrl: typeof window !== "undefined" ? window.location.href : undefined,
+                userAgent: typeof navigator !== "undefined" ? navigator.userAgent : undefined,
+                sdkVersion: this.sdkVersion,
+                groupId,
+            },
+        };
+        try {
+            await this.sendEvent(event);
+            this.logger.info(`[Analytics] Already joined tracked for product: ${productId}`);
+        }
+        catch (error) {
+            this.logger.error("[Analytics] Failed to track already joined", error);
+        }
+    }
+    /**
+     * Track group full view event (user sees a fulfilled/full group)
+     */
+    async trackGroupFullView(productId, groupId, totalMembers) {
+        const event = {
+            event: "GROUP_FULL_VIEW",
+            productId,
+            sessionId: this.sessionId,
+            timestamp: new Date().toISOString(),
+            context: {
+                pageUrl: typeof window !== "undefined" ? window.location.href : undefined,
+                userAgent: typeof navigator !== "undefined" ? navigator.userAgent : undefined,
+                sdkVersion: this.sdkVersion,
+                groupId,
+                totalMembers,
+            },
+        };
+        try {
+            await this.sendEvent(event);
+            this.logger.info(`[Analytics] Group full view tracked for product: ${productId}`);
+        }
+        catch (error) {
+            this.logger.error("[Analytics] Failed to track group full view", error);
+        }
+    }
+    /**
+     * Track share click event
+     */
+    async trackShareClick(productId, groupId, channel) {
+        const event = {
+            event: "SHARE_CLICK",
+            productId,
+            sessionId: this.sessionId,
+            timestamp: new Date().toISOString(),
+            context: {
+                pageUrl: typeof window !== "undefined" ? window.location.href : undefined,
+                userAgent: typeof navigator !== "undefined" ? navigator.userAgent : undefined,
+                sdkVersion: this.sdkVersion,
+                groupId,
+                channel,
+            },
+        };
+        try {
+            await this.sendEvent(event);
+            this.logger.info(`[Analytics] Share click tracked for product: ${productId}`);
+        }
+        catch (error) {
+            this.logger.error("[Analytics] Failed to track share click", error);
+        }
+    }
+    /**
+     * Track group creation attempt event
+     */
+    async trackGroupCreateAttempt(productId) {
+        const event = {
+            event: "GROUP_CREATE_ATTEMPT",
+            productId,
+            sessionId: this.sessionId,
+            timestamp: new Date().toISOString(),
+            context: {
+                pageUrl: typeof window !== "undefined" ? window.location.href : undefined,
+                userAgent: typeof navigator !== "undefined" ? navigator.userAgent : undefined,
+                sdkVersion: this.sdkVersion,
+            },
+        };
+        try {
+            await this.sendEvent(event);
+            this.logger.info(`[Analytics] Group create attempt tracked for product: ${productId}`);
+        }
+        catch (error) {
+            this.logger.error("[Analytics] Failed to track group create attempt", error);
+        }
+    }
+    /**
+     * Track successful group creation event
+     */
+    async trackGroupCreateSuccess(productId, groupId) {
+        const event = {
+            event: "GROUP_CREATE_SUCCESS",
+            productId,
+            sessionId: this.sessionId,
+            timestamp: new Date().toISOString(),
+            context: {
+                pageUrl: typeof window !== "undefined" ? window.location.href : undefined,
+                userAgent: typeof navigator !== "undefined" ? navigator.userAgent : undefined,
+                sdkVersion: this.sdkVersion,
+                groupId,
+            },
+        };
+        try {
+            await this.sendEvent(event);
+            this.logger.info(`[Analytics] Group create success tracked for product: ${productId}`);
+        }
+        catch (error) {
+            this.logger.error("[Analytics] Failed to track group create success", error);
+        }
+    }
+    /**
+     * Track group creation failure event
+     */
+    async trackGroupCreateFailure(productId, errorCode, message) {
+        const event = {
+            event: "GROUP_CREATE_FAILURE",
+            productId,
+            sessionId: this.sessionId,
+            timestamp: new Date().toISOString(),
+            context: {
+                pageUrl: typeof window !== "undefined" ? window.location.href : undefined,
+                userAgent: typeof navigator !== "undefined" ? navigator.userAgent : undefined,
+                sdkVersion: this.sdkVersion,
+                errorCode,
+                errorMessage: message,
+            },
+        };
+        try {
+            await this.sendEvent(event);
+            this.logger.info(`[Analytics] Group create failure tracked for product: ${productId}`);
+        }
+        catch (error) {
+            this.logger.error("[Analytics] Failed to track group create failure", error);
+        }
+    }
     /**
      * Track custom event (extensible for future use)
      */
@@ -12593,8 +13220,14 @@ class CoBuy {
                                     participantsCount !== undefined &&
                                     participantsCount >= maxParticipants);
                             if (isFulfilled && productId && groupId) {
-                                // Prepare checkout when group is fulfilled (if not already prepared)
-                                this.prepareCheckoutIfNotDone(productId, groupId);
+                                // Only prepare checkout if the current user is actually a member of this group.
+                                // this.widgets tracks all WidgetRoot instances; getJoinedGroupId() returns the
+                                // joined group ID only when the user has completed a join this session (not for
+                                // observers). Calling prepareCheckout for non-members would generate spurious 403s.
+                                const userIsInGroup = [...this.widgets].some((w) => w.getJoinedGroupId() === groupId);
+                                if (userIsInGroup) {
+                                    this.prepareCheckoutIfNotDone(productId, groupId);
+                                }
                             }
                             // Emit user-defined callback if provided
                             if ((_a = config.events) === null || _a === void 0 ? void 0 : _a.onGroupMemberJoined) {
@@ -12607,8 +13240,11 @@ class CoBuy {
                     this.logger.warn("[SDK] Failed to initialize sockets", e);
                 }
             }
-            // Track page view event after successful initialization
+            // Track session init + page view events after successful initialization
             if (this.analyticsClient) {
+                this.analyticsClient.trackSessionInit(config.geo, config.device).catch((error) => {
+                    this.logger.warn("[SDK] Failed to track session init", error);
+                });
                 this.analyticsClient.trackPageView().catch((error) => {
                     // Non-blocking: Analytics failure should not affect SDK initialization
                     this.logger.warn("[SDK] Failed to track page view", error);
@@ -12914,6 +13550,63 @@ class CoBuy {
             this.logger.error("Error setting contact information", error);
         }
     }
+    /**
+     * Resolve an invite token to get product and group information
+     *
+     * Resolves an invite link token (e.g., from https://brand.cobuyza.co.za/i/QMeHD7ew)
+     * to get the associated product, group, and invite metadata. Use this to handle
+     * invite links in your application routing.
+     *
+     * @param inviteToken - The invite token from the URL
+     * @returns Promise with invite resolution data or null if failed
+     *
+     * @example
+     * ```typescript
+     * // Extract token from URL path like /i/QMeHD7ew
+     * const pathParts = window.location.pathname.split('/i/');
+     * if (pathParts.length > 1) {
+     *   const inviteToken = pathParts[1];
+     *   const inviteData = await CoBuy.resolveInvite(inviteToken);
+     *
+     *   if (inviteData) {
+     *     // Navigate to product page
+     *     window.location.href = `/product/${inviteData.product.id}`;
+     *   }
+     * }
+     * ```
+     */
+    async resolveInvite(inviteToken) {
+        if (!this.configManager.isInitialized()) {
+            this.logger.warn("SDK not initialized, cannot resolve invite");
+            return null;
+        }
+        if (!this.apiClient) {
+            this.logger.error("API client not available");
+            return null;
+        }
+        if (!inviteToken || typeof inviteToken !== "string" || inviteToken.trim() === "") {
+            this.logger.error("Invalid invite token provided");
+            return null;
+        }
+        try {
+            const response = await this.apiClient.resolveInvite(inviteToken.trim());
+            if (response.success && response.data) {
+                this.logger.info(`Invite resolved successfully: product=${response.data.product.id}, group=${response.data.group.id}`);
+                return response.data;
+            }
+            else {
+                if (this.handleFraudError(response.error, "resolveInvite")) {
+                    return null;
+                }
+                this.logger.error("Failed to resolve invite", response.error);
+                return null;
+            }
+        }
+        catch (error) {
+            this.logger.error("Error resolving invite", error);
+            return null;
+        }
+    }
     /**
      * Validate checkout for a group
      *