@cshah18/sdk 4.13.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, InviteResolveResponseData, 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
      *

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";

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