@cshah18/sdk 3.0.0 → 3.0.2

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

@@ -1,4 +1,4 @@
-import { ApiRequestOptions, ApiResponse, ApiClientConfig, ProductRewardData, ProductPrimaryGroupData, GroupJoinResponseData, GroupInviteResponseData, AuthStrategy, ShareChannel, Contact } from "./types";
+import { ApiRequestOptions, ApiResponse, ApiClientConfig, ProductRewardData, ProductPrimaryGroupData, GroupJoinResponseData, GroupInviteResponseData, AuthStrategy, ShareChannel, Contact, CheckoutValidationData } from "./types";
 /**
  * HTTP client for communicating with CoBuy API
  *
@@ -124,4 +124,39 @@ export declare class ApiClient {
      * @returns Promise with success status
      */
     setContact(contact: Contact): Promise<ApiResponse<void>>;
+    /**
+     * Prepare checkout for a group
+     *
+     * Signals the backend that the user is proceeding to checkout for a specific group.
+     * This allows the backend to prepare order data, lock pricing, and track conversion.
+     * Returns a checkout reference to be used in subsequent validate and confirm calls.
+     *
+     * @param groupId - The group ID to prepare checkout for
+     * @returns Promise with success status and checkout reference
+     */
+    prepareCheckout(groupId: string): Promise<ApiResponse<{
+        checkout_ref: string;
+    }>>;
+    /**
+     * Validate checkout for a group
+     *
+     * Validates the checkout reference and confirms the order can proceed.
+     * This should be called after prepareCheckout to verify the checkout state.
+     *
+     * @param groupId - The group ID to validate checkout for
+     * @param checkoutRef - The checkout reference ID from the prepare step
+     * @returns Promise with success status
+     */
+    validateCheckout(groupId: string, checkoutRef: string): Promise<ApiResponse<CheckoutValidationData>>;
+    /**
+     * Confirm checkout for a group
+     *
+     * Finalizes the checkout and confirms the order.
+     * This should be called after validateCheckout to complete the checkout process.
+     *
+     * @param groupId - The group ID to confirm checkout for
+     * @param checkoutRef - The checkout reference ID from the prepare step
+     * @returns Promise with success status
+     */
+    confirmCheckout(groupId: string, checkoutRef: string): Promise<ApiResponse<void>>;
 }

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

@@ -1,4 +1,4 @@
-import { CoBuySDK, CoBuyInitOptions, RenderWidgetOptions, ModalOptions, Contact } from "./types";
+import { CoBuySDK, CoBuyInitOptions, RenderWidgetOptions, ModalOptions, Contact, CheckoutValidationData } from "./types";
 import { ApiClient } from "./api-client";
 import { AnalyticsClient } from "./analytics";
 import { SocketManager } from "./socket";
@@ -12,6 +12,7 @@ export declare class CoBuy implements CoBuySDK {
     private analyticsClient;
     private sessionId;
     private readonly SESSION_STORAGE_KEY;
+    private readonly CHECKOUT_REF_PREFIX;
     private lobbyModal;
     private modals;
     private socketManager;
@@ -24,10 +25,30 @@ export declare class CoBuy implements CoBuySDK {
      * Generate UUID v4 compatible ID
      */
     private generateUUID;
+    /**
+     * Store checkout reference for a product/group (session-level)
+     * Storage key format: cobuy_checkout_ref_<sessionId>_<productId>_<groupId>
+     */
+    private storeCheckoutRef;
+    /**
+     * Retrieve checkout reference for a product/group (session-level)
+     * If groupId provided, try exact match first; otherwise fall back to any key for that product
+     * Returns both the matched storage key and the checkout reference value (or null if not found)
+     */
+    getCheckoutRef(productId: string, groupId?: string): {
+        key: string | null;
+        checkoutRef: string | null;
+        groupId: string | null;
+    };
     /**
      * Get the current session ID (core SDK concept)
      */
     getSessionId(): string;
+    /**
+     * Prepare checkout for a group if not already prepared
+     * Checks localStorage to prevent duplicate calls for the same product/group/session
+     */
+    private prepareCheckoutIfNotDone;
     /**
      * Initialize the SDK with configuration
      */
@@ -73,6 +94,38 @@ export declare class CoBuy implements CoBuySDK {
      * ```
      */
     setContact(contact: Contact): Promise<void>;
+    /**
+     * Validate checkout for a group
+     *
+     * Validates the checkout reference and confirms the order can proceed.
+     * Should be called after prepareCheckout to verify the checkout state.
+     *
+     * @param groupId - The group ID to validate checkout for
+     * @param checkoutRef - The checkout reference ID from the prepare step
+     *
+     * @example
+     * ```typescript
+     * // Validate checkout for a group
+     * await CoBuy.validateCheckout('fae238ae-7468-47e9-9eec-b6d52fe3b012', 'chk_9a6d8750-ed60-4795-a207-2abe955e8509');
+     * ```
+     */
+    validateCheckout(groupId: string, checkoutRef: string): Promise<CheckoutValidationData | null>;
+    /**
+     * Confirm checkout for a group
+     *
+     * Finalizes the checkout and confirms the order.
+     * Should be called after validateCheckout to complete the checkout process.
+     *
+     * @param groupId - The group ID to confirm checkout for
+     * @param checkoutRef - The checkout reference ID from the prepare step
+     *
+     * @example
+     * ```typescript
+     * // Confirm checkout for a group
+     * await CoBuy.confirmCheckout('fae238ae-7468-47e9-9eec-b6d52fe3b012', 'chk_9a6d8750-ed60-4795-a207-2abe955e8509');
+     * ```
+     */
+    confirmCheckout(groupId: string, checkoutRef: string): Promise<void>;
     /**
      * Get the initialized API client instance
      */

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

@@ -8,6 +8,9 @@ export declare const API_ENDPOINTS: {
     readonly GROUP_CREATE_AND_JOIN: "/v1/sdk/groups/new/join";
     readonly PRODUCT_ACTIVE_GROUPS: "/v1/sdk/products/:productId/groups/active";
     readonly GROUP_INVITE: "/v1/sdk/groups/:groupId/invite";
+    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";
 };
 /**
  * Build full API URL from base URL and endpoint path

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

@@ -146,6 +146,21 @@ export interface CheckoutData {
     groupId: string;
     productId: string;
 }
+export interface CheckoutValidationReward {
+    reward: Reward;
+    group_id: string;
+    product_id: string;
+    frozen_at?: string;
+    eligibility?: {
+        isEligible: boolean;
+        reason?: string;
+    };
+}
+export interface CheckoutValidationData {
+    approved: boolean;
+    reward?: CheckoutValidationReward;
+    message?: string;
+}
 /**
  * Socket payload emitted when a group reaches fulfillment
  */
@@ -168,15 +183,10 @@ export interface GroupCreatedEvent {
 }
 /**
  * Socket payload emitted when a member joins a group
+ * Matches the backend `group:member:joined` event structure.
+ * Reuses `GroupJoinResponseData` for strong typing.
  */
-export interface GroupMemberJoinedEvent {
-    groupId: string;
-    productId: string;
-    memberId: string;
-    memberCount: number;
-    maxParticipants?: number;
-    timestamp?: string;
-}
+export type GroupMemberJoinedEvent = GroupJoinResponseData;
 /**
  * Payload emitted when shopper opts to continue to checkout
  */
@@ -510,6 +520,31 @@ export interface CoBuySDK {
      * @param _contact Contact information (email or phone)
      */
     setContact(_contact: Contact): Promise<void>;
+    /**
+     * Validate checkout for a group
+     * Validates the checkout reference and confirms the order can proceed
+     * @param _groupId The group ID to validate checkout for
+     * @param _checkoutRef The checkout reference ID from the prepare step
+     */
+    validateCheckout(_groupId: string, _checkoutRef: string): Promise<CheckoutValidationData | null>;
+    /**
+     * Confirm checkout for a group
+     * 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
+     */
+    confirmCheckout(_groupId: string, _checkoutRef: string): 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
+     * @param _productId Product ID
+     * @param _groupId (optional) Group ID; exact match tried first, then product prefix fallback
+     */
+    getCheckoutRef(_productId: string, _groupId?: string): {
+        key: string | null;
+        checkoutRef: string | null;
+        groupId: string | null;
+    };
     /**
      * SDK version
      */

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

@@ -235,9 +235,8 @@ export declare class LobbyModal {
      */
     private subscribeToSocketEvents;
     /**
-     * Unsubscribe from socket events
+     * Unsubscribe from socket events - testing out flow will remove once we have conviction
      */
-    private unsubscribeFromSocketEvents;
     /**
      * Handle socket group update events
      */

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

@@ -28,6 +28,7 @@ export declare class WidgetRoot {
     private groupListModal;
     private lastGroupDataRefreshTime;
     private readonly GROUP_REFRESH_DEBOUNCE;
+    private groupExpiryRefreshTriggered;
     constructor(config: InternalConfig, apiClient: ApiClient | null, analyticsClient?: AnalyticsClient | null);
     /** Subscribe once to backend socket events routed through the host page */
     private subscribeToSocketEvents;
@@ -47,7 +48,7 @@ export declare class WidgetRoot {
     private renderGroupInfo;
     /** Render fulfilled summary card when the group is complete */
     private renderFulfilledSummary;
-    /** Update countdown text */
+    /** Update countdown text and trigger refresh when group expires */
     private updateTimer;
     /** Build and attach the shared "View all Groups" link section */
     /** Create inline View all Groups link for placement inside group container */

package/package.json

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