@cshah18/sdk 1.0.0 → 2.0.0

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

@@ -52,14 +52,63 @@ export interface CoBuyThemeOptions {
      */
     animationStyle?: AnimationStyle;
 }
+/**
+ * Authentication mode for SDK initialization
+ * - "public": Use merchant key (no-backend sites, read-only endpoints)
+ * - "token": Use short-lived session token (backend-integrated sites, full access)
+ */
+export type AuthMode = "public" | "token";
+/**
+ * Authentication callbacks for token mode
+ */
+export interface AuthCallbacks {
+    /**
+     * Called when authentication fails (401/403)
+     * Use this to handle auth errors in your application
+     */
+    onAuthError?: (error: Error) => void;
+    /**
+     * Called when token expires or needs refresh
+     * Use this to fetch a new token from your backend
+     */
+    onTokenExpired?: () => void | Promise<void>;
+}
 /**
  * Options for initializing the CoBuy SDK
  */
 export interface CoBuyInitOptions {
+    /**
+     * Authentication mode (default: "public")
+     * - "public": For no-backend sites (uses merchantKey)
+     * - "token": For backend-integrated sites (uses sessionToken)
+     */
+    authMode?: AuthMode;
     /**
      * Unique merchant key provided by CoBuy
+     * Required for authMode="public"
+     * Not used in authMode="token"
      */
-    merchantKey: string;
+    merchantKey?: string;
+    /**
+     * Session token for authenticated requests
+     * Required for authMode="token"
+     * Can be a string or async function that returns a token
+     * Token should be short-lived (5-15 minutes) and fetched from your backend
+     *
+     * Example:
+     * ```ts
+     * sessionToken: async () => {
+     *   const response = await fetch('/api/cobuy-token');
+     *   const { token } = await response.json();
+     *   return token;
+     * }
+     * ```
+     */
+    sessionToken?: string | (() => string | Promise<string>);
+    /**
+     * Authentication callbacks for handling errors and token refresh
+     */
+    auth?: AuthCallbacks;
     /**
      * Environment to connect to (default: "production")
      */
@@ -97,6 +146,44 @@ export interface CheckoutData {
     groupId: string;
     productId: string;
 }
+/**
+ * Socket payload emitted when a group reaches fulfillment
+ */
+export interface GroupFulfilledEvent {
+    groupId: string;
+    productId: string;
+    participants: number;
+    reward: Reward;
+}
+/**
+ * Socket payload emitted when a new group is created
+ */
+export interface GroupCreatedEvent {
+    groupId: string;
+    productId: string;
+    createdAt: string;
+    participantCount?: number;
+    maxParticipants?: number;
+    groupNumber?: string;
+}
+/**
+ * Socket payload emitted when a member joins a group
+ */
+export interface GroupMemberJoinedEvent {
+    groupId: string;
+    productId: string;
+    memberId: string;
+    memberCount: number;
+    maxParticipants?: number;
+    timestamp?: string;
+}
+/**
+ * Payload emitted when shopper opts to continue to checkout
+ */
+export interface CheckoutRequestedEvent {
+    groupId: string;
+    productId: string;
+}
 /**
  * Widget event callbacks for lifecycle events
  */
@@ -125,6 +212,22 @@ export interface WidgetEvents {
      * Called when modal closes
      */
     onModalClose?: (_productId: string) => void;
+    /**
+     * Called when the backend notifies that a group has been fulfilled
+     */
+    onGroupFulfilled?: (_event: GroupFulfilledEvent) => void;
+    /**
+     * Called when the backend notifies that a group was created
+     */
+    onGroupCreated?: (_event: GroupCreatedEvent) => void;
+    /**
+     * Called when the backend notifies that a member joined a group
+     */
+    onGroupMemberJoined?: (_event: GroupMemberJoinedEvent) => void;
+    /**
+     * Called when shopper clicks continue to checkout from the fulfilled state
+     */
+    onCheckoutRequested?: (_event: CheckoutRequestedEvent) => void;
 }
 /**
  * Modal configuration options
@@ -134,10 +237,61 @@ export interface ModalOptions {
      * Product ID to show in the modal
      */
     productId: string;
+    /**
+     * Group ID for the lobby
+     */
+    groupId?: string;
     /**
      * Optional custom title for the modal
      */
     title?: string;
+    /**
+     * Group number (e.g., "1000")
+     */
+    groupNumber?: string;
+    /**
+     * Lobby status
+     */
+    status?: "active" | "complete";
+    /**
+     * Group progress percentage (0-100)
+     */
+    progress?: number;
+    /**
+     * Current number of members in the group
+     */
+    currentMembers?: number;
+    /**
+     * Total members needed for the group
+     */
+    totalMembers?: number;
+    /**
+     * Time left in seconds
+     */
+    timeLeft?: number;
+    /**
+     * Discount text (e.g., "20% OFF")
+     */
+    discount?: string;
+    /**
+     * Group link URL
+     */
+    groupLink?: string;
+    /**
+     * Whether the offer is locked
+     */
+    isLocked?: boolean;
+    /**
+     * Activity items to display
+     */
+    activities?: Array<{
+        emoji: string;
+        username: string;
+        location: string;
+        action: string;
+        timeAgo: string;
+        color: "pink" | "purple" | "blue" | "green" | "orange";
+    }>;
     /**
      * Optional callback when modal opens
      */
@@ -145,12 +299,38 @@ export interface ModalOptions {
     /**
      * Optional callback when modal closes
      */
-    onClose?: (_productId: string) => void;
+    onClose?: () => void;
+    /**
+     * Optional callback when user copies the group link
+     */
+    onCopyLink?: (_link: string) => void;
+    /**
+     * Optional callback when user shares
+     */
+    onShare?: () => void;
+}
+/**
+ * Contact information for user identification
+ * Supports email or phone number as contact types
+ * Used for enriching anonymous sessions with user contact data
+ */
+export interface Contact {
+    /**
+     * Type of contact information
+     * - "email": User's email address
+     * - "phone": User's phone number
+     */
+    type: "email" | "phone";
+    /**
+     * The contact value (email address or phone number)
+     * Must be a valid email or phone format
+     */
+    value: string;
 }
 /**
  * Reward type enumeration
  */
-export type RewardType = "percentage" | "fixed" | "points" | "cashback";
+export type RewardType = "percentage" | "fixed" | "points" | "cashback" | "flat";
 /**
  * Reward status enumeration
  */
@@ -185,6 +365,60 @@ export interface ProductRewardData {
     reward: Reward;
     eligibility: RewardEligibility;
 }
+/**
+ * Primary group information for a product (SCRUM-284)
+ */
+export interface ProductPrimaryGroupData {
+    group: ProductPrimaryGroupData | PromiseLike<ProductPrimaryGroupData | null> | null;
+    id: string;
+    group_name: string;
+    description: string | null;
+    campaign_creative_id: string | null;
+    campaign_creative_name: string | null;
+    campaign_id: string | null;
+    campaign_name: string | null;
+    campaign_status: string | null;
+    participants_count: number;
+    max_participants: number;
+    status: string;
+    expiry_at: string;
+    timeLeftSeconds: number;
+}
+/**
+ * Group join response data
+ */
+export interface GroupJoinResponseData {
+    group: {
+        id: string;
+        group_name: string;
+        participants_count: number;
+        max_participants: number;
+        status: string;
+        expiry_at: string;
+        timeLeftSeconds: number;
+    };
+    membership: {
+        id: string;
+        session_id: string;
+        created_at: string;
+    };
+    isPrimary: boolean;
+    product_id: string;
+}
+export type ShareChannel = "whatsapp" | "facebook" | "email" | "sms" | "copy_link" | "tiktok" | "x" | "other";
+export interface GroupInviteResponseData {
+    invite_url?: string;
+    invite_token?: string;
+    share_message?: string;
+    group?: {
+        id: string;
+        name?: string;
+        current_count?: number;
+        slots_remaining?: number;
+        expires_at?: string;
+    };
+    [key: string]: unknown;
+}
 /**
  * Options for rendering the CoBuy widget
  */
@@ -218,6 +452,45 @@ export interface RenderWidgetOptions {
      * Callback triggered when widget closes
      */
     onClose?: () => void;
+    /**
+     * Optional layout order for widget sections.
+     * Controls the rendering order of 'group' (participation info),
+     * 'reward' (reward text), and 'cta' (action button).
+     * Defaults to ["group", "reward", "cta"].
+     */
+    layout?: Array<"group" | "reward" | "cta">;
+    /**
+     * Optional separate container for group participation info.
+     * If provided, group info will render here instead of inside the main widget.
+     * Can be a selector string or HTMLElement.
+     */
+    groupContainer?: string | HTMLElement;
+    /**
+     * Optional separate container for reward text.
+     * If provided, reward text will render here instead of inside the main widget.
+     * Can be a selector string or HTMLElement.
+     */
+    rewardContainer?: string | HTMLElement;
+    /**
+     * Optional customization for the "View all Groups" link.
+     * - container: render the link in a separate element (like reward/group containers)
+     * - text / classes / styles: adjust copy, font, color, underline, alignment, etc.
+     */
+    viewAllLink?: {
+        container?: string | HTMLElement;
+        text?: string;
+        align?: "left" | "center" | "right";
+        className?: string;
+        linkClassName?: string;
+        underline?: boolean;
+        color?: string;
+        fontSize?: string;
+        fontWeight?: string | number;
+        fontFamily?: string;
+        textDecoration?: string;
+        style?: Partial<Record<string, string | number>>;
+        linkStyle?: Partial<Record<string, string | number>>;
+    };
 }
 /**
  * Public CoBuy SDK interface
@@ -231,17 +504,30 @@ export interface CoBuySDK {
      * Render the CoBuy widget into a DOM container
      */
     renderWidget(_options: RenderWidgetOptions): void;
+    /**
+     * Set or update contact information for the current session
+     * Allows merchants to enrich an anonymous session with user contact data
+     * @param _contact Contact information (email or phone)
+     */
+    setContact(_contact: Contact): Promise<void>;
     /**
      * SDK version
      */
     readonly version: string;
+    /**
+     * Optional cleanup for long-lived pages (closes sockets, etc.)
+     */
+    destroy?(): void;
 }
 /**
  * Internal configuration object used throughout the SDK
  * This extends the public CoBuyInitOptions with computed values
  */
 export interface InternalConfig {
-    merchantKey: string;
+    authMode: AuthMode;
+    merchantKey?: string;
+    sessionToken?: string | (() => string | Promise<string>);
+    auth?: AuthCallbacks;
     env: CoBuyEnvironment;
     apiBaseUrl: string;
     theme: CoBuyThemeOptions;
@@ -278,7 +564,17 @@ export interface ApiResponse<T = unknown> {
  */
 export interface ApiClientConfig {
     baseUrl: string;
-    merchantKey: string;
+    authStrategy: AuthStrategy;
+    sessionId: string;
     debug?: boolean;
     timeout?: number;
 }
+/**
+ * Authentication strategy interface (imported from auth-strategy.ts)
+ * Re-exported here for convenience
+ */
+export interface AuthStrategy {
+    getHeaders(): Record<string, string>;
+    refreshIfNeeded(): Promise<boolean>;
+    onAuthError(error: Error): void;
+}

package/dist/types/index.d.ts

@@ -2,6 +2,8 @@ import { CoBuy } from "./core/cobuy";
 import type { CoBuySDK } from "./core/types";
 export type { CoBuySDK };
 export * from "./core/types";
+export type { AuthStrategy } from "./core/auth-strategy";
+export { PublicKeyAuth, TokenAuth } from "./core/auth-strategy";
 declare const instance: CoBuy;
 declare global {
     interface Window {

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

@@ -0,0 +1,61 @@
+import { ApiClient } from "../../core/api-client";
+import { ProductPrimaryGroupData, GroupJoinResponseData } from "../../core/types";
+export interface GroupListItem {
+    groupId: string;
+    timeLabel: string;
+    timeLeftSeconds?: number;
+    joined: number;
+    total: number;
+    isMember: boolean;
+}
+export interface ApiGroupData extends ProductPrimaryGroupData {
+    is_member: boolean;
+}
+/**
+ * GroupListModal - Renders the "View all Groups" popup with optional API integration.
+ */
+export declare class GroupListModal {
+    private overlayEl;
+    private logger;
+    private groups;
+    private liveCount;
+    private apiClient;
+    private isLoading;
+    private startButton;
+    private countdownIntervals;
+    private currentJoinedGroupId;
+    private currentProductId;
+    private currentSessionId;
+    private onGroupJoined;
+    private onViewProgress;
+    private readonly escapeHandler;
+    constructor(groups?: GroupListItem[], liveCount?: number, debug?: boolean, apiClient?: ApiClient | null);
+    /** 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 */
+    setOnViewProgress(callback: (groupId: string, groupData: GroupListItem) => void): void;
+    /** Set the currently joined group ID to show appropriate button states */
+    setCurrentJoinedGroup(groupId: string): void;
+    /** Check if a group ID exists in the current groups list */
+    hasGroup(groupId: string): boolean;
+    open(productId?: string, sessionId?: string, joinedGroupId?: string): Promise<void>;
+    private fetchAndRenderGroups;
+    private formatTimeRemaining;
+    close(): void;
+    isOpen(): boolean;
+    /** Handle join group button click - calls API and executes callback */
+    private handleJoinGroup;
+    /** Handle create new group button click - creates and joins a group, then triggers callback */
+    private handleCreateNewGroup;
+    private buildOverlay;
+    private createLoadingSkeleton;
+    private createHeader;
+    private createLiveBox;
+    private createCardsGrid;
+    private startCountdown;
+    private setJoinButtonsDisabled;
+    private updateStartButtonState;
+    private createGroupCard;
+    private createMemberAvatar;
+    private injectStyles;
+}

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

@@ -0,0 +1,257 @@
+import { ApiClient } from "../../core/api-client";
+import { AnalyticsClient } from "../../core/analytics";
+import { SocketManager } from "../../core/socket";
+import "./styles/styles.css";
+export interface LobbyModalData {
+    productId: string;
+    groupId?: string;
+    groupNumber?: string;
+    status?: "active" | "complete";
+    progress?: number;
+    currentMembers?: number;
+    totalMembers?: number;
+    timeLeft?: number;
+    discount?: string;
+    groupLink?: string;
+    shareMessage?: string;
+    activities?: ActivityItem[];
+    isLocked?: boolean;
+}
+export interface ActivityItem {
+    emoji: string;
+    username: string;
+    location: string;
+    action: string;
+    timeAgo: string;
+    color: "pink" | "purple" | "blue" | "green" | "orange";
+}
+export interface LobbyModalCallbacks {
+    onClose?: () => void;
+    onCopyLink?: (link: string) => void;
+    onShare?: () => void;
+}
+/**
+ * LobbyModal - Renders and manages the group buying lobby modal
+ */
+export declare class LobbyModal {
+    private logger;
+    private analyticsClient;
+    private socketManager;
+    private apiClient;
+    private modalElement;
+    private data;
+    private callbacks;
+    private timerInterval;
+    private activityInterval;
+    private activityCards;
+    private socketListenerRegistered;
+    private currentGroupId;
+    private shareOverlay;
+    constructor(data: LobbyModalData, callbacks: LobbyModalCallbacks, apiClient: ApiClient | null, analyticsClient: AnalyticsClient | null, socketManager?: SocketManager | null, debug?: boolean);
+    /**
+     * Derive lock state from data so UI reflects completion
+     */
+    private computeIsLocked;
+    private getRewardText;
+    private getTitleText;
+    /**
+     * Default activity items
+     */
+    private getDefaultActivities;
+    /**
+     * Create the modal DOM structure
+     */
+    private createModalStructure;
+    /**
+     * Create close icon
+     */
+    private createCloseIcon;
+    /**
+     * Create top section
+     */
+    private createTopSection;
+    /**
+     * Create left section
+     */
+    private createLeftSection;
+    /**
+     * Create status section
+     */
+    private createStatusSection;
+    /**
+     * Create title section
+     */
+    private createTitleSection;
+    /**
+     * Create link section
+     */
+    private createLinkSection;
+    /**
+     * Create offer section
+     */
+    private createOfferSection;
+    /**
+     * Create right section
+     */
+    private createRightSection;
+    /**
+     * Create group info box
+     */
+    private createGroupInfoBox;
+    /**
+     * Create progress card
+     */
+    private createProgressCard;
+    /**
+     * Create team card
+     */
+    private createTeamCard;
+    /**
+     * Create time card
+     */
+    private createTimeCard;
+    /**
+     * Create activity section
+     */
+    private createActivitySection;
+    /**
+     * Create activity card
+     */
+    private createActivityCard;
+    /**
+     * Format time in HH:MM:SS format
+     */
+    private formatTime;
+    /**
+     * Update timer
+     */
+    private updateTimer;
+    /**
+     * Start timer
+     */
+    private startTimer;
+    /**
+     * Stop timer
+     */
+    private stopTimer;
+    /**
+     * Layout activity cards
+     */
+    private layoutActivityCards;
+    /**
+     * Shuffle activity cards
+     */
+    private shuffleActivityCards;
+    /**
+     * Start activity animation
+     */
+    private startActivityAnimation;
+    /**
+     * Stop activity animation
+     */
+    private stopActivityAnimation;
+    /**
+     * Record invite/share event and refresh share link/message
+     */
+    private recordInvite;
+    /**
+     * Copy link to clipboard
+     */
+    private copyLink;
+    /**
+     * Share functionality
+     */
+    private share;
+    /**
+     * Create share overlay modal
+     */
+    private createShareOverlay;
+    /**
+     * Create a share card
+     */
+    private createShareCard;
+    /**
+     * Open share modal
+     */
+    private openShareModal;
+    /**
+     * Close share modal
+     */
+    private closeShareModal;
+    /**
+     * Copy link from modal
+     */
+    private copyLinkFromModal;
+    /**
+     * Share to WhatsApp
+     */
+    private shareToWhatsApp;
+    /**
+     * Share to Facebook
+     */
+    private shareToFacebook;
+    /**
+     * Share to Twitter (X)
+     */
+    private shareToTwitter;
+    /**
+     * Share via SMS
+     */
+    private shareToSMS;
+    /**
+     * Open/render the modal
+     */
+    open(groupId?: string): void;
+    /**
+     * Close the modal
+     */
+    close(): void;
+    /**
+     * Check if modal is open
+     */
+    isOpen(): boolean;
+    /**
+     * Update modal data
+     */
+    updateData(data: Partial<LobbyModalData>): void;
+    /**
+     * Update title and subtitle dynamically from API/state
+     */
+    private updateTitleUI;
+    /**
+     * Update status chip text and styling
+     */
+    private updateStatusUI;
+    /**
+     * Update lock status and reward text in the UI
+     */
+    private updateLockUI;
+    /**
+     * Show/hide link section based on lock state
+     */
+    private updateLinkVisibility;
+    /**
+     * Subscribe to socket events
+     */
+    private subscribeToSocketEvents;
+    /**
+     * Unsubscribe from socket events
+     */
+    private unsubscribeFromSocketEvents;
+    /**
+     * Handle socket group update events
+     */
+    private handleSocketGroupUpdate;
+    /**
+     * Create activity item from socket event data
+     */
+    private createActivityFromEvent;
+    /**
+     * Update activity list dynamically from live data
+     */
+    private updateActivityList;
+    /**
+     * Update team card members dynamically
+     */
+    private updateTeamCard;
+}