@cshah18/sdk 4.12.0 → 4.14.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, AuthStrategy, ShareChannel, Contact, CheckoutValidationData, CheckoutConfirmData } from "./types";
+import { ApiRequestOptions, ApiResponse, ApiClientConfig, ProductRewardData, ProductContextData, ProductPrimaryGroupData, GroupJoinResponseData, GroupInviteResponseData, InviteResolveResponseData, AuthStrategy, ShareChannel, Contact, 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
      *
@@ -367,6 +382,36 @@ export declare class ApiClient {
      * ```
      */
     inviteToGroup(groupId: string, sharedVia: ShareChannel): Promise<ApiResponse<GroupInviteResponseData>>;
+    /**
+     * 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}`;
+     * }
+     * ```
+     */
+    resolveInvite(inviteToken: string): Promise<ApiResponse<InviteResolveResponseData>>;
     /**
      * Set or update contact information for the current session
      *

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

@@ -1,4 +1,4 @@
-import { CoBuySDK, CoBuyInitOptions, RenderWidgetOptions, ModalOptions, Contact, CheckoutValidationData, CheckoutConfirmData } from "./types";
+import { CoBuySDK, CoBuyInitOptions, RenderWidgetOptions, ModalOptions, Contact, CheckoutValidationData, CheckoutConfirmData, InviteResolveResponseData } from "./types";
 import { ApiClient } from "./api-client";
 import { AnalyticsClient } from "./analytics";
 import { SocketManager } from "./socket";
@@ -246,6 +246,32 @@ export declare class CoBuy implements CoBuySDK {
      * ```
      */
     setContact(contact: Contact): Promise<void>;
+    /**
+     * 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}`;
+     *   }
+     * }
+     * ```
+     */
+    resolveInvite(inviteToken: string): Promise<InviteResolveResponseData | null>;
     /**
      * Validate checkout for a group
      *

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

@@ -2,6 +2,7 @@
  * 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 GROUP_JOIN: "/v1/sdk/groups/:groupId/join";
@@ -11,6 +12,7 @@ export declare const API_ENDPOINTS: {
     readonly GROUP_CHECKOUT_PREPARE: "/v1/sdk/groups/:groupId/checkout/prepare";
     readonly GROUP_CHECKOUT_VALIDATE: "/v1/sdk/groups/:groupId/checkout/validate";
     readonly GROUP_CHECKOUT_CONFIRM: "/v1/sdk/groups/:groupId/checkout/confirm";
+    readonly INVITE_RESOLVE: "/v1/sdk/invite/resolve";
 };
 /**
  * Build full API URL from base URL and endpoint path

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
@@ -503,7 +536,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 +556,55 @@ 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;
+}
+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;
@@ -582,6 +656,41 @@ export interface GroupInviteResponseData {
     };
     [key: string]: unknown;
 }
+/**
+ * Invite resolution response data
+ */
+export interface InviteResolveResponseData {
+    product: {
+        id: string;
+        name: string;
+        images: string[];
+        price: number;
+        description: string;
+    };
+    creative: {
+        id: string;
+        name: string;
+        contact_required: boolean;
+    };
+    brand: {
+        id: string;
+        name: string;
+    };
+    group: {
+        id: string;
+        group_name: string;
+        description: string;
+        current_count: number;
+        required_count: number;
+        status: string;
+        auto_created: boolean;
+        expiry_at: string;
+    };
+    invite_metadata: {
+        shared_via: string;
+        click_count: number;
+    };
+}
 /**
  * Options for rendering the CoBuy widget
  */
@@ -672,6 +781,13 @@ export interface CoBuySDK {
      * @param _contact Contact information (email or phone)
      */
     setContact(_contact: Contact): Promise<void>;
+    /**
+     * Resolve an invite token to get product and group information
+     * Used to handle invite links like https://brand.cobuyza.co.za/i/{token}
+     * @param _inviteToken The invite token from the URL
+     * @returns Promise with invite resolution data including product, group, and metadata
+     */
+    resolveInvite(_inviteToken: string): Promise<InviteResolveResponseData | null>;
     /**
      * Validate checkout for a group
      * Validates the checkout reference and confirms the order can proceed
@@ -726,6 +842,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/widget/widget-root.d.ts

@@ -185,4 +185,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.12.0",
+  "version": "4.14.0",
   "description": "CoBuy Embedded SDK for browser JavaScript integration",
   "type": "module",
   "main": "dist/cobuy-sdk.umd.js",