@cshah18/sdk 4.0.0 → 4.2.0

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

@@ -4,9 +4,9 @@ import { ApiClient } from "./api-client";
  */
 export interface AnalyticsEvent {
     event: string;
-    productId: string;
     timestamp: string;
-    sessionId: string;
+    productId?: string;
+    sessionId?: string;
     context?: {
         pageUrl?: string;
         userAgent?: string;
@@ -31,6 +31,10 @@ export declare class AnalyticsClient {
      * Send event to backend analytics endpoint using unified ApiClient
      */
     private sendEvent;
+    /**
+     * Track page view event
+     */
+    trackPageView(): 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 } from "./types";
+import { ApiRequestOptions, ApiResponse, ApiClientConfig, ProductRewardData, ProductPrimaryGroupData, GroupJoinResponseData, GroupInviteResponseData, AuthStrategy, ShareChannel, Contact, CheckoutValidationData, CheckoutConfirmData } from "./types";
 /**
  * HTTP client for communicating with CoBuy API
  *
@@ -158,5 +158,5 @@ export declare class ApiClient {
      * @param checkoutRef - The checkout reference ID from the prepare step
      * @returns Promise with success status
      */
-    confirmCheckout(groupId: string, checkoutRef: string): Promise<ApiResponse<void>>;
+    confirmCheckout(groupId: string, checkoutRef: string, data?: CheckoutConfirmData): Promise<ApiResponse<void>>;
 }

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

@@ -1,4 +1,4 @@
-import { CoBuySDK, CoBuyInitOptions, RenderWidgetOptions, ModalOptions, Contact, CheckoutValidationData } from "./types";
+import { CoBuySDK, CoBuyInitOptions, RenderWidgetOptions, ModalOptions, Contact, CheckoutValidationData, CheckoutConfirmData } from "./types";
 import { ApiClient } from "./api-client";
 import { AnalyticsClient } from "./analytics";
 import { SocketManager } from "./socket";
@@ -119,14 +119,31 @@ export declare class CoBuy implements CoBuySDK {
      *
      * @param groupId - The group ID to confirm checkout for
      * @param checkoutRef - The checkout reference ID from the prepare step
+    /**
+     * Confirm checkout for a group
+     * Should be called after validateCheckout to complete the checkout process.
+     *
+     * @param groupId The group ID to confirm checkout for
+     * @param checkoutRef The checkout reference from the prepare step
+     * @param data Optional order details (order_id, order_total, discount_applied, currency, payment_method, metadata)
      *
      * @example
      * ```typescript
      * // Confirm checkout for a group
      * await CoBuy.confirmCheckout('fae238ae-7468-47e9-9eec-b6d52fe3b012', 'chk_9a6d8750-ed60-4795-a207-2abe955e8509');
+     *
+     * // Confirm checkout with order details
+     * await CoBuy.confirmCheckout('fae238ae-7468-47e9-9eec-b6d52fe3b012', 'chk_9a6d8750-ed60-4795-a207-2abe955e8509', {
+     *   order_id: 'ORDER-1001',
+     *   order_total: 100.00,
+     *   discount_applied: 20.00,
+     *   currency: 'USD',
+     *   payment_method: 'card',
+     *   metadata: { coupon_code: 'WELCOME20', customer_id: 'cust_123' }
+     * });
      * ```
      */
-    confirmCheckout(groupId: string, checkoutRef: string): Promise<void>;
+    confirmCheckout(groupId: string, checkoutRef: string, data?: CheckoutConfirmData): Promise<void>;
     /**
      * Get the initialized API client instance
      */

package/dist/types/core/group-channel-manager.d.ts

@@ -0,0 +1,74 @@
+import { InternalConfig, GroupFulfilledEvent, Reward } from "./types";
+export interface GroupRealtimeSnapshot {
+    groupId: string;
+    productId: string;
+    participants: number;
+    maxParticipants?: number;
+    progressPercent?: number;
+    expiresAt?: string;
+    reward?: Reward | null;
+    status?: string;
+    timeLeftSeconds?: number;
+}
+export type GroupChannelEvent = {
+    type: "update";
+    snapshot: GroupRealtimeSnapshot;
+} | {
+    type: "fulfilled";
+    snapshot: GroupRealtimeSnapshot;
+};
+export type GroupChannelListener = (event: GroupChannelEvent) => void;
+/**
+ * Centralized real-time channel manager for all group-aware UI surfaces.
+ * Ensures a single socket connection, one room subscription per group, and
+ * shared event dispatch to interested listeners.
+ */
+export declare class GroupChannelManager {
+    private readonly config;
+    private readonly sdkVersion;
+    private readonly onFulfilledCallback?;
+    private socket;
+    private readonly logger;
+    private readonly listeners;
+    private readonly groupRefCount;
+    private readonly groupToProduct;
+    private readonly latestByGroup;
+    private readonly latestByProduct;
+    private isConnecting;
+    constructor(config: InternalConfig, sdkVersion: string, onFulfilledCallback?: ((event: GroupFulfilledEvent) => void) | undefined);
+    /**
+     * Start socket connection if not already connected.
+     */
+    connect(): void;
+    /**
+     * Subscribe to realtime updates for a group. Multiple callers are reference-counted.
+     */
+    subscribeToGroup(groupId: string, productId: string): void;
+    /**
+     * Unsubscribe from a group when no listeners remain.
+     */
+    unsubscribeFromGroup(groupId: string): void;
+    /**
+     * Switch from one group room to another, ensuring only one active subscription.
+     */
+    switchGroup(oldGroupId: string | null, newGroupId: string, productId: string): void;
+    /**
+     * Register for realtime events. Returns an unsubscribe function.
+     */
+    addListener(listener: GroupChannelListener): () => void;
+    /**
+     * Retrieve the latest snapshot for a product if one exists.
+     */
+    getLatestSnapshotForProduct(productId: string): GroupRealtimeSnapshot | null;
+    /**
+     * Disconnect and clear state.
+     */
+    disconnect(): void;
+    private handleGroupUpdate;
+    private handleGroupFulfilled;
+    private cacheSnapshot;
+    private broadcast;
+    private normalizeSnapshot;
+    private pickString;
+    private pickNumber;
+}

package/dist/types/core/offline-redemption.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Offline Redemption Utilities
+ * Helpers for constructing QR URLs, copying codes, and downloading QR images
+ */
+import { OfflineRedemption } from "./types";
+/**
+ * Build full S3 URL for QR code image
+ * @param qrCodeData - S3 key from offline_redemption.qr_code_data
+ * @returns Full HTTPS URL to the QR code image
+ */
+export declare function buildQRUrl(qrCodeData: string): string;
+/**
+ * Copy redemption code to clipboard
+ * @param code - Redemption code to copy
+ * @returns Promise that resolves when copy is complete
+ */
+export declare function copyRedemptionCode(code: string): Promise<boolean>;
+/**
+ * Download QR code image
+ * @param qrUrl - Full URL to the QR code image
+ * @param filename - Name for the downloaded file
+ */
+export declare function downloadQRCode(qrUrl: string, filename?: string): Promise<boolean>;
+/**
+ * Validate offline redemption data
+ * @param redemption - Offline redemption object
+ * @returns true if data is valid and complete
+ */
+export declare function isValidOfflineRedemption(redemption: unknown): redemption is OfflineRedemption;
+/**
+ * Format expiry date for display
+ * @param isoDate - ISO 8601 date string
+ * @returns Formatted date string (e.g., "Feb 20, 2026 at 10:21 AM")
+ */
+export declare function formatExpiryDate(isoDate: string): string;
+/**
+ * Check if offline redemption is still valid
+ * @param expiryDate - ISO 8601 expiry date string
+ * @returns true if redemption has not expired
+ */
+export declare function isRedemptionValid(expiryDate: string): boolean;

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

@@ -11,9 +11,10 @@ export interface SocketHandlers {
 export declare class SocketManager {
     private readonly config;
     private readonly sdkVersion;
+    private readonly sessionId;
     private socket;
     private readonly logger;
-    constructor(config: InternalConfig, sdkVersion: string);
+    constructor(config: InternalConfig, sdkVersion: string, sessionId: string);
     private dispatchWindowEvent;
     private formatPayload;
     /**

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

@@ -161,14 +161,78 @@ export interface CheckoutValidationData {
     reward?: CheckoutValidationReward;
     message?: string;
 }
+/**
+ * Optional metadata for checkout confirmation
+ */
+export interface CheckoutConfirmMetadata {
+    coupon_code?: string;
+    customer_id?: string;
+    note?: string;
+    [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Optional order details for checkout confirmation
+ */
+export interface CheckoutConfirmData {
+    order_id?: string;
+    order_total?: number;
+    discount_applied?: number;
+    currency?: string;
+    payment_method?: "cod" | "card" | string;
+    metadata?: CheckoutConfirmMetadata;
+}
+/**
+ * Offline redemption information for fulfilled groups
+ */
+export interface OfflineRedemption {
+    member_id: string;
+    qr_code_value: string;
+    redemption_code: string;
+    qr_code_data: string;
+    offline_expires_at: string;
+}
+/**
+ * Group information in fulfillment event
+ */
+export interface FulfilledGroup {
+    id: string;
+    group_name: string;
+    description?: string;
+    campaign_creative_name?: string;
+    campaign_id: string;
+    campaign_name: string;
+    campaign_status: string;
+    participants_count: number;
+    max_participants: number;
+    status: string;
+    expiry_at: string;
+    timeLeftSeconds: number;
+}
+/**
+ * Frozen reward information in fulfillment event
+ */
+export interface FrozenReward {
+    reward: Reward;
+    group_id: string;
+    frozen_at: string;
+    product_id: string;
+    eligibility?: {
+        isEligible: boolean;
+    };
+}
 /**
  * Socket payload emitted when a group reaches fulfillment
+ * Includes all details needed for offline redemption
  */
 export interface GroupFulfilledEvent {
-    groupId: string;
-    productId: string;
-    participants: number;
-    reward: Reward;
+    group: FulfilledGroup;
+    frozen_reward: FrozenReward;
+    product_id: string;
+    offline_redemption?: OfflineRedemption;
+    groupId?: string;
+    productId?: string;
+    participants?: number;
+    reward?: Reward;
 }
 /**
  * Socket payload emitted when a new group is created
@@ -302,6 +366,10 @@ export interface ModalOptions {
         timeAgo: string;
         color: "pink" | "purple" | "blue" | "green" | "orange";
     }>;
+    /**
+     * Offline redemption data for fulfilled groups
+     */
+    offlineRedemption?: OfflineRedemption;
     /**
      * Optional callback when modal opens
      */
@@ -393,6 +461,7 @@ export interface ProductPrimaryGroupData {
     status: string;
     expiry_at: string;
     timeLeftSeconds: number;
+    offline_redemption?: OfflineRedemption;
 }
 /**
  * Group join response data
@@ -414,6 +483,7 @@ export interface GroupJoinResponseData {
     };
     isPrimary: boolean;
     product_id: string;
+    offline_redemption?: OfflineRedemption;
 }
 export type ShareChannel = "whatsapp" | "facebook" | "email" | "sms" | "copy_link" | "tiktok" | "x" | "other";
 export interface GroupInviteResponseData {
@@ -531,8 +601,9 @@ export interface CoBuySDK {
      * Finalizes the checkout and confirms the order
      * @param _groupId The group ID to confirm checkout for
      * @param _checkoutRef The checkout reference ID from the prepare step
+     * @param _data (optional) Additional order details (order_id, order_total, discount_applied, currency, payment_method, metadata)
      */
-    confirmCheckout(_groupId: string, _checkoutRef: string): Promise<void>;
+    confirmCheckout(_groupId: string, _checkoutRef: string, _data?: CheckoutConfirmData): Promise<void>;
     /**
      * Retrieve stored checkout reference for a product in this session
      * Returns both the storage key and value; key/value null if not found or storage unavailable

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

@@ -2,6 +2,7 @@ import { ApiClient } from "../../core/api-client";
 import { ProductPrimaryGroupData, GroupJoinResponseData } from "../../core/types";
 export interface GroupListItem {
     groupId: string;
+    name?: string;
     timeLabel: string;
     timeLeftSeconds?: number;
     joined: number;

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

@@ -1,4 +1,5 @@
 import { ApiClient } from "../../core/api-client";
+import { OfflineRedemption } from "../../core/types";
 import { AnalyticsClient } from "../../core/analytics";
 import { SocketManager } from "../../core/socket";
 import "./styles/styles.css";
@@ -16,6 +17,7 @@ export interface LobbyModalData {
     shareMessage?: string;
     activities?: ActivityItem[];
     isLocked?: boolean;
+    offlineRedemption?: OfflineRedemption;
 }
 export interface ActivityItem {
     emoji: string;
@@ -58,6 +60,18 @@ export declare class LobbyModal {
      * Default activity items
      */
     private getDefaultActivities;
+    /**
+     * Create entrance animation overlay
+     */
+    private createEntranceAnimation;
+    /**
+     * Show entrance animation and auto-hide after duration
+     */
+    private showEntranceAnimation;
+    /**
+     * Hide entrance animation with exit effect
+     */
+    private hideEntranceAnimation;
     /**
      * Create the modal DOM structure
      */
@@ -83,9 +97,29 @@ export declare class LobbyModal {
      */
     private createTitleSection;
     /**
-     * Create link section
+     * Create connected section (subtitle + link + share)
+     */
+    private createConnectedSection;
+    /**
+     * Create link section (just the link box and share button, no wrapper)
      */
     private createLinkSection;
+    /**
+     * Create offline redemption section
+     */
+    private createOfflineRedemptionSection;
+    /**
+     * Handle copying offline redemption code
+     */
+    private copyOfflineRedemptionCode;
+    /**
+     * Handle downloading offline QR code
+     */
+    private downloadOfflineQR;
+    /**
+     * Inject styles for offline redemption section
+     */
+    private injectOfflineRedemptionStyles;
     /**
      * Create offer section
      */
@@ -230,6 +264,10 @@ export declare class LobbyModal {
      * Show/hide link section based on lock state
      */
     private updateLinkVisibility;
+    /**
+     * Update offline redemption visibility when group is fulfilled
+     */
+    private updateOfflineRedemptionVisibility;
     /**
      * Subscribe to socket events
      */

package/dist/types/ui/offline-redemption/offline-redemption-modal.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Offline Redemption Modal
+ * Displays QR code and redemption code for fulfilled groups
+ */
+import { OfflineRedemption } from "../../core/types";
+export declare class OfflineRedemptionModal {
+    private modalElement;
+    private offlineRedemption;
+    private onClose?;
+    constructor(offlineRedemption: OfflineRedemption, onClose?: () => void);
+    /**
+     * Open the modal
+     */
+    open(): void;
+    /**
+     * Close the modal
+     */
+    close(): void;
+    /**
+     * Create the modal DOM structure
+     */
+    private createModalStructure;
+    /**
+     * Handle download QR button click
+     */
+    private handleDownloadQR;
+    /**
+     * Handle copy code button click
+     */
+    private handleCopyCode;
+    /**
+     * Inject modal styles
+     */
+    private injectStyles;
+}

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

@@ -29,6 +29,8 @@ export declare class WidgetRoot {
     private lastGroupDataRefreshTime;
     private readonly GROUP_REFRESH_DEBOUNCE;
     private groupExpiryRefreshTriggered;
+    private offlineRedemption;
+    private offlineRedemptionModal;
     constructor(config: InternalConfig, apiClient: ApiClient | null, analyticsClient?: AnalyticsClient | null);
     /** Subscribe once to backend socket events routed through the host page */
     private subscribeToSocketEvents;
@@ -104,6 +106,10 @@ export declare class WidgetRoot {
      * Handle CTA button click with analytics and modal opening
      */
     private handleCTAClick;
+    /**
+     * Open offline redemption modal when user clicks "Redeem In-store"
+     */
+    private openOfflineRedemptionModal;
     /**
      * Emit checkout intent without performing navigation
      */

package/package.json

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

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

@@ -1,126 +0,0 @@
-import { InternalConfig } from "./types";
-export interface GroupPayload {
-    id: string;
-    group_name: string;
-    participants_count: number;
-    max_participants: number;
-    status: string;
-    expiry_at: Date | string;
-    timeLeftSeconds: number;
-}
-export interface MembershipPayload {
-    id: string;
-    session_id: string;
-    created_at: Date | string;
-}
-export interface GroupMemberJoinedPayload {
-    group: GroupPayload;
-    membership: MembershipPayload;
-    product_id?: string;
-    isPrimary?: boolean;
-}
-export interface GroupCreatedPayload {
-    group: GroupPayload;
-    membership: MembershipPayload;
-    product_id?: string;
-}
-export interface GroupFulfilledPayload {
-    group: GroupPayload;
-    frozen_reward: unknown;
-    product_id?: string | null;
-}
-export interface SocketClientConfig {
-    serverUrl: string;
-    merchantKey?: string;
-    sdkVersion?: string;
-    sessionId?: string;
-    debug?: boolean;
-}
-export interface SocketEventHandlers {
-    onGroupMemberJoined?: (payload: GroupMemberJoinedPayload) => void;
-    onGroupCreated?: (payload: GroupCreatedPayload) => void;
-    onGroupFulfilled?: (payload: GroupFulfilledPayload) => void;
-    onConnect?: () => void;
-    onDisconnect?: (reason: string) => void;
-    onError?: (error: Error) => void;
-}
-/**
- * Frontend Socket.IO client for real-time group updates
- * Manages connection to the backend /sdk namespace and handles group subscriptions
- */
-export declare class SocketClient {
-    private socket;
-    private logger;
-    private config;
-    private handlers;
-    private currentGroupId;
-    private currentProductId;
-    private maxReconnectAttempts;
-    constructor(config: SocketClientConfig);
-    /**
-     * Connect to the Socket.IO server
-     * @param handlers - Event handlers for socket events
-     */
-    connect(handlers: SocketEventHandlers): Promise<void>;
-    /**
-     * Register event listeners for group updates
-     */
-    private registerEventListeners;
-    /**
-     * Subscribe to a specific group's updates
-     * @param groupId - The group ID to subscribe to
-     */
-    subscribeToGroup(groupId: string): void;
-    /**
-     * Unsubscribe from a specific group's updates
-     * @param groupId - The group ID to unsubscribe from
-     */
-    unsubscribeFromGroup(groupId: string): void;
-    /**
-     * Subscribe to product availability updates (groups being created for the product)
-     * @param productId - The product ID to watch for
-     */
-    subscribeToProductAvailable(productId: string): void;
-    /**
-     * Unsubscribe from product availability updates
-     * @param productId - The product ID to stop watching
-     */
-    unsubscribeFromProductAvailable(productId: string): void;
-    /**
-     * Check if socket is connected
-     */
-    isConnected(): boolean;
-    /**
-     * Get current socket ID
-     */
-    getSocketId(): string | null;
-    /**
-     * Get currently subscribed group ID
-     */
-    getCurrentGroupId(): string | null;
-    /**
-     * Get currently subscribed product ID
-     */
-    getCurrentProductId(): string | null;
-    /**
-     * Disconnect from the server
-     */
-    disconnect(): void;
-    /**
-     * Force reconnection to the server
-     */
-    reconnect(): void;
-    /**
-     * Update authentication credentials
-     * @param merchantKey - New merchant key
-     */
-    updateAuth(merchantKey: string): void;
-}
-/**
- * Create a socket client from SDK config
- * @param config - Internal SDK configuration
- * @param sdkVersion - SDK version
- * @param sessionId - Session ID from CoBuy instance
- * @returns Configured SocketClient instance
- */
-export declare function createSocketClient(config: InternalConfig, sdkVersion: string, sessionId: string): SocketClient;