@anker-in/shopify-react 1.3.0-beta.0 → 1.3.0-beta.2

package/dist/{types-CMMWxyUF.d.mts → types-CM5QrlnE.d.mts}

@@ -1,4 +1,5 @@
-import { NormalizedProductVariant, NormalizedProduct, MoneyV2, NormalizedCart } from '@anker-in/shopify-sdk';
+import { NormalizedLineItem, MoneyV2, NormalizedProductVariant, NormalizedProduct, BuyerIdentityInput, NormalizedCart } from '@anker-in/shopify-sdk';
+import Decimal from 'decimal.js';
 
 /**
  * Tracking Types
@@ -18,19 +19,30 @@ interface GtmParams {
 
 declare global {
     interface Window {
-        dataLayer?: any[];
-        gtag?: (...args: any) => void;
+        dataLayer?: Array<Record<string, unknown>>;
+        gtag?: {
+            (command: 'config', targetId: string, config?: Record<string, unknown>): void;
+            (command: 'set', config: Record<string, unknown>): void;
+            (command: 'event', eventName: string, eventParams?: Record<string, unknown>): void;
+            (command: 'get', targetId: string, fieldName: string, callback?: (value: string) => void): void;
+            (command: 'consent', consentArg: string, consentParams?: Record<string, unknown>): void;
+        };
     }
 }
 /**
  * Push event to GA4 dataLayer
  */
-declare const gaTrack: (data: any) => void;
+declare const gaTrack: (data: Record<string, unknown>) => void;
 /**
  * Track add to cart event in GA4
  */
 declare const trackAddToCartGA: ({ lineItems, gtmParams, }: {
-    lineItems: AddToCartLineItem[];
+    lineItems: Array<NormalizedLineItem & {
+        finalPrice?: MoneyV2;
+        gtmParams?: {
+            item_category_id?: number | string;
+        };
+    }>;
     gtmParams?: GtmParams;
 }) => void;
 /**
@@ -46,26 +58,59 @@ declare const trackBeginCheckoutGA: ({ lineItems, currencyCode, gtmParams, }: {
  * This triggers begin_checkout event for buy now actions
  */
 declare const trackBuyNowGA: ({ lineItems, gtmParams, }: {
-    lineItems: AddToCartLineItem[];
+    lineItems: Array<NormalizedLineItem & {
+        gtmParams?: {
+            item_category_id?: number | string;
+        };
+    }>;
     gtmParams?: GtmParams;
 }) => void;
+/**
+ * GA4 Data
+ */
+interface GA4Data {
+    clientId: string;
+    sessionId: string;
+}
+/**
+ * Wait for gtag to be ready
+ */
+declare function waitForGtagReady(timeout?: number): Promise<void>;
+/**
+ * Get GA4 client ID
+ */
+declare const getGA4ClientId: (measurementId?: string) => Promise<string>;
+/**
+ * Get GA4 session ID
+ */
+declare const getGA4SessionId: (measurementId?: string) => Promise<string>;
+/**
+ * Get GA4 data (client ID and session ID)
+ */
+declare const getGA4Data: (measurementId?: string) => Promise<GA4Data>;
 
 /**
  * Facebook Pixel Tracking
  * FBQ event tracking utilities
  */
 
+type FbqCommand = 'track' | 'trackCustom' | 'trackSingle' | 'trackCustom';
+type FbqEventName = 'AddToCart' | 'Purchase' | 'InitiateCheckout' | 'ViewContent' | string;
+type FbqEventParams = Record<string, unknown>;
 declare global {
     interface Window {
-        fbq?: (...args: any[]) => void;
-        gtag?: (...args: any[]) => void;
+        fbq?: (command: FbqCommand, eventName: FbqEventName, params?: FbqEventParams) => void;
     }
 }
 /**
  * Track add to cart event in Facebook Pixel
  */
-declare const trackAddToCartFBQ: ({ lineItems }: {
-    lineItems: AddToCartLineItem[];
+declare const trackAddToCartFBQ: ({ lineItems, }: {
+    lineItems: Array<NormalizedLineItem & {
+        gtmParams?: {
+            item_category_id?: number | string;
+        };
+    }>;
 }) => void;
 /**
  * Configuration for Buy Now tracking events
@@ -102,6 +147,9 @@ type AddToCartLineItem = {
         code: string;
         amount: number;
     };
+    gtmParams?: {
+        item_category_id?: number | string;
+    };
 };
 interface AddToCartInput {
     /** Lines to add */
@@ -118,10 +166,7 @@ interface AddToCartInput {
     /** 全量更新 codes，默认是追加 */
     replaceExistingCodes?: boolean;
     /** Buyer identity for cart creation */
-    buyerIdentity?: {
-        email?: string;
-        countryCode?: string;
-    };
+    buyerIdentity?: BuyerIdentityInput;
     /** GTM tracking parameters */
     gtmParams?: Omit<GtmParams, 'brand'>;
     /** Force create new cart */
@@ -134,6 +179,131 @@ interface UseAddToCartOptions {
     withTrack?: boolean;
 }
 
+/**
+ * Auto Remove Free Gifts Hook
+ *
+ * Automatically removes Function and Script free gifts from cart on page load.
+ * This ensures gifts are only added at checkout time, not kept in cart permanently.
+ *
+ * Based on storefront-anker production implementation.
+ */
+
+interface UseAutoRemoveFreeGiftsOptions {
+    /**
+     * Whether to remove Function gifts (with _discounts_function_env attribute)
+     * @default true
+     */
+    removeFunctionGifts?: boolean;
+    /**
+     * Whether to remove Script gifts (with _giveaway_gradient_gifts attribute)
+     * @default true
+     */
+    removeScriptGifts?: boolean;
+    /**
+     * Custom function to identify additional gift line items
+     * @param line - Line item to check
+     * @returns true if line item is a gift that should be removed
+     */
+    isGiftLineItem?: (line: NormalizedLineItem) => boolean;
+}
+interface UseAutoRemoveFreeGiftsResult {
+    /** Whether removal is in progress */
+    isRemoving: boolean;
+}
+/**
+ * Automatically removes free gifts from cart on initialization
+ *
+ * Function满赠和Script满赠的赠品都会被添加到购物车，需要在返回购物车页面时自动删除。
+ * - Function 赠品：带 _discounts_function_env 属性
+ * - Script 赠品：带 _giveaway_gradient_gifts 属性
+ *
+ * @example
+ * ```tsx
+ * function CartPage() {
+ *   // Auto-remove all gifts on page load
+ *   useAutoRemoveFreeGifts()
+ *
+ *   return <Cart />
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Only remove Function gifts, keep Script gifts
+ * useAutoRemoveFreeGifts({
+ *   removeFunctionGifts: true,
+ *   removeScriptGifts: false
+ * })
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom gift identification
+ * useAutoRemoveFreeGifts({
+ *   isGiftLineItem: (line) => {
+ *     // Also remove other campaign gifts
+ *     return line.customAttributes?.some(
+ *       attr => attr.key === '_giveaway_summer_campaign'
+ *     )
+ *   }
+ * })
+ * ```
+ */
+declare function useAutoRemoveFreeGifts(options?: UseAutoRemoveFreeGiftsOptions): UseAutoRemoveFreeGiftsResult;
+/**
+ * Helper function to check if a line item is a Function gift
+ */
+declare function isFunctionGift(line: NormalizedLineItem): boolean;
+/**
+ * Helper function to check if a line item is a Script gift
+ */
+declare function isScriptGift(line: NormalizedLineItem): boolean;
+/**
+ * Helper function to check if a line item is a buy-get gift (买赠)
+ */
+declare function isBuyGetGift(line: NormalizedLineItem): boolean;
+/**
+ * Helper function to check if a line item is any type of gift
+ */
+declare function isAnyGift(line: NormalizedLineItem): boolean;
+
+interface GiveawayProduct {
+    handle: string;
+    sku: string;
+}
+interface Breakpoint {
+    breakpoint: string;
+    giveawayProducts: GiveawayProduct[];
+}
+interface ScriptAutoFreeGiftConfig {
+    activityAvailableQuery?: string;
+    activityQroperty?: string;
+    breakpoints?: Array<{
+        breakpoint: string;
+        giveawayProducts: GiveawayProduct[];
+    }>;
+    includeTags?: string[];
+    useTotalAmount?: boolean;
+    requireLogin?: boolean;
+}
+interface UseScriptAutoFreeGiftResult {
+    involvedLines: NormalizedLineItem[];
+    reorder: (a: NormalizedLineItem, b: NormalizedLineItem) => number;
+    disableCodeRemove: boolean;
+    nextFreeGiftLevel: Breakpoint | null;
+    freeGiftLevel: Breakpoint | null;
+    involvedSubTotal: Decimal;
+    giftProductsResult?: NormalizedProduct[];
+}
+declare const useScriptAutoFreeGift: ({ campaign, _giveaway, cart, locale: providedLocale, lines, profile, }: {
+    campaign?: ScriptAutoFreeGiftConfig;
+    _giveaway: string;
+    cart: NormalizedCart | undefined;
+    locale?: string;
+    lines?: AddToCartLineItem[];
+    profile?: any;
+}) => UseScriptAutoFreeGiftResult;
+
 /**
  * Plus Member Types
  * Type definitions for Plus Member functionality
@@ -510,4 +680,4 @@ type DeliveryCustomData = {
     plus_type?: DeliveryPlusType;
 };
 
-export { type AddToCartLineItem as A, type BuyNowTrackConfig as B, DeliveryPlusType as D, type GtmParams as G, PLUS_MEMBER_TYPE as P, ShippingMethodMode as S, type UseAddToCartOptions as U, type AddToCartInput as a, PlusMemberMode as b, type PlusMemberShippingMethodMetafields as c, type PlusMemberShippingMethodConfig as d, type PlusMemberSettingsMetafields as e, type SelectedPlusMemberVariant as f, type DeliveryCustomData as g, gaTrack as h, trackBeginCheckoutGA as i, trackBuyNowGA as j, trackAddToCartFBQ as k, trackBuyNowFBQ as l, trackAddToCartGA as t };
+export { type AddToCartLineItem as A, trackAddToCartFBQ as B, type BuyNowTrackConfig as C, DeliveryPlusType as D, trackBuyNowFBQ as E, type GtmParams as G, PLUS_MEMBER_TYPE as P, type ScriptAutoFreeGiftConfig as S, type UseAutoRemoveFreeGiftsOptions as U, type UseAutoRemoveFreeGiftsResult as a, isScriptGift as b, isBuyGetGift as c, isAnyGift as d, type UseScriptAutoFreeGiftResult as e, useScriptAutoFreeGift as f, type AddToCartInput as g, type UseAddToCartOptions as h, isFunctionGift as i, PlusMemberMode as j, ShippingMethodMode as k, type PlusMemberShippingMethodMetafields as l, type PlusMemberShippingMethodConfig as m, type PlusMemberSettingsMetafields as n, type SelectedPlusMemberVariant as o, type DeliveryCustomData as p, gaTrack as q, trackBeginCheckoutGA as r, trackBuyNowGA as s, trackAddToCartGA as t, useAutoRemoveFreeGifts as u, type GA4Data as v, waitForGtagReady as w, getGA4ClientId as x, getGA4SessionId as y, getGA4Data as z };

package/dist/{types-CMMWxyUF.d.ts → types-CM5QrlnE.d.ts}

@@ -1,4 +1,5 @@
-import { NormalizedProductVariant, NormalizedProduct, MoneyV2, NormalizedCart } from '@anker-in/shopify-sdk';
+import { NormalizedLineItem, MoneyV2, NormalizedProductVariant, NormalizedProduct, BuyerIdentityInput, NormalizedCart } from '@anker-in/shopify-sdk';
+import Decimal from 'decimal.js';
 
 /**
  * Tracking Types
@@ -18,19 +19,30 @@ interface GtmParams {
 
 declare global {
     interface Window {
-        dataLayer?: any[];
-        gtag?: (...args: any) => void;
+        dataLayer?: Array<Record<string, unknown>>;
+        gtag?: {
+            (command: 'config', targetId: string, config?: Record<string, unknown>): void;
+            (command: 'set', config: Record<string, unknown>): void;
+            (command: 'event', eventName: string, eventParams?: Record<string, unknown>): void;
+            (command: 'get', targetId: string, fieldName: string, callback?: (value: string) => void): void;
+            (command: 'consent', consentArg: string, consentParams?: Record<string, unknown>): void;
+        };
     }
 }
 /**
  * Push event to GA4 dataLayer
  */
-declare const gaTrack: (data: any) => void;
+declare const gaTrack: (data: Record<string, unknown>) => void;
 /**
  * Track add to cart event in GA4
  */
 declare const trackAddToCartGA: ({ lineItems, gtmParams, }: {
-    lineItems: AddToCartLineItem[];
+    lineItems: Array<NormalizedLineItem & {
+        finalPrice?: MoneyV2;
+        gtmParams?: {
+            item_category_id?: number | string;
+        };
+    }>;
     gtmParams?: GtmParams;
 }) => void;
 /**
@@ -46,26 +58,59 @@ declare const trackBeginCheckoutGA: ({ lineItems, currencyCode, gtmParams, }: {
  * This triggers begin_checkout event for buy now actions
  */
 declare const trackBuyNowGA: ({ lineItems, gtmParams, }: {
-    lineItems: AddToCartLineItem[];
+    lineItems: Array<NormalizedLineItem & {
+        gtmParams?: {
+            item_category_id?: number | string;
+        };
+    }>;
     gtmParams?: GtmParams;
 }) => void;
+/**
+ * GA4 Data
+ */
+interface GA4Data {
+    clientId: string;
+    sessionId: string;
+}
+/**
+ * Wait for gtag to be ready
+ */
+declare function waitForGtagReady(timeout?: number): Promise<void>;
+/**
+ * Get GA4 client ID
+ */
+declare const getGA4ClientId: (measurementId?: string) => Promise<string>;
+/**
+ * Get GA4 session ID
+ */
+declare const getGA4SessionId: (measurementId?: string) => Promise<string>;
+/**
+ * Get GA4 data (client ID and session ID)
+ */
+declare const getGA4Data: (measurementId?: string) => Promise<GA4Data>;
 
 /**
  * Facebook Pixel Tracking
  * FBQ event tracking utilities
  */
 
+type FbqCommand = 'track' | 'trackCustom' | 'trackSingle' | 'trackCustom';
+type FbqEventName = 'AddToCart' | 'Purchase' | 'InitiateCheckout' | 'ViewContent' | string;
+type FbqEventParams = Record<string, unknown>;
 declare global {
     interface Window {
-        fbq?: (...args: any[]) => void;
-        gtag?: (...args: any[]) => void;
+        fbq?: (command: FbqCommand, eventName: FbqEventName, params?: FbqEventParams) => void;
     }
 }
 /**
  * Track add to cart event in Facebook Pixel
  */
-declare const trackAddToCartFBQ: ({ lineItems }: {
-    lineItems: AddToCartLineItem[];
+declare const trackAddToCartFBQ: ({ lineItems, }: {
+    lineItems: Array<NormalizedLineItem & {
+        gtmParams?: {
+            item_category_id?: number | string;
+        };
+    }>;
 }) => void;
 /**
  * Configuration for Buy Now tracking events
@@ -102,6 +147,9 @@ type AddToCartLineItem = {
         code: string;
         amount: number;
     };
+    gtmParams?: {
+        item_category_id?: number | string;
+    };
 };
 interface AddToCartInput {
     /** Lines to add */
@@ -118,10 +166,7 @@ interface AddToCartInput {
     /** 全量更新 codes，默认是追加 */
     replaceExistingCodes?: boolean;
     /** Buyer identity for cart creation */
-    buyerIdentity?: {
-        email?: string;
-        countryCode?: string;
-    };
+    buyerIdentity?: BuyerIdentityInput;
     /** GTM tracking parameters */
     gtmParams?: Omit<GtmParams, 'brand'>;
     /** Force create new cart */
@@ -134,6 +179,131 @@ interface UseAddToCartOptions {
     withTrack?: boolean;
 }
 
+/**
+ * Auto Remove Free Gifts Hook
+ *
+ * Automatically removes Function and Script free gifts from cart on page load.
+ * This ensures gifts are only added at checkout time, not kept in cart permanently.
+ *
+ * Based on storefront-anker production implementation.
+ */
+
+interface UseAutoRemoveFreeGiftsOptions {
+    /**
+     * Whether to remove Function gifts (with _discounts_function_env attribute)
+     * @default true
+     */
+    removeFunctionGifts?: boolean;
+    /**
+     * Whether to remove Script gifts (with _giveaway_gradient_gifts attribute)
+     * @default true
+     */
+    removeScriptGifts?: boolean;
+    /**
+     * Custom function to identify additional gift line items
+     * @param line - Line item to check
+     * @returns true if line item is a gift that should be removed
+     */
+    isGiftLineItem?: (line: NormalizedLineItem) => boolean;
+}
+interface UseAutoRemoveFreeGiftsResult {
+    /** Whether removal is in progress */
+    isRemoving: boolean;
+}
+/**
+ * Automatically removes free gifts from cart on initialization
+ *
+ * Function满赠和Script满赠的赠品都会被添加到购物车，需要在返回购物车页面时自动删除。
+ * - Function 赠品：带 _discounts_function_env 属性
+ * - Script 赠品：带 _giveaway_gradient_gifts 属性
+ *
+ * @example
+ * ```tsx
+ * function CartPage() {
+ *   // Auto-remove all gifts on page load
+ *   useAutoRemoveFreeGifts()
+ *
+ *   return <Cart />
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Only remove Function gifts, keep Script gifts
+ * useAutoRemoveFreeGifts({
+ *   removeFunctionGifts: true,
+ *   removeScriptGifts: false
+ * })
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom gift identification
+ * useAutoRemoveFreeGifts({
+ *   isGiftLineItem: (line) => {
+ *     // Also remove other campaign gifts
+ *     return line.customAttributes?.some(
+ *       attr => attr.key === '_giveaway_summer_campaign'
+ *     )
+ *   }
+ * })
+ * ```
+ */
+declare function useAutoRemoveFreeGifts(options?: UseAutoRemoveFreeGiftsOptions): UseAutoRemoveFreeGiftsResult;
+/**
+ * Helper function to check if a line item is a Function gift
+ */
+declare function isFunctionGift(line: NormalizedLineItem): boolean;
+/**
+ * Helper function to check if a line item is a Script gift
+ */
+declare function isScriptGift(line: NormalizedLineItem): boolean;
+/**
+ * Helper function to check if a line item is a buy-get gift (买赠)
+ */
+declare function isBuyGetGift(line: NormalizedLineItem): boolean;
+/**
+ * Helper function to check if a line item is any type of gift
+ */
+declare function isAnyGift(line: NormalizedLineItem): boolean;
+
+interface GiveawayProduct {
+    handle: string;
+    sku: string;
+}
+interface Breakpoint {
+    breakpoint: string;
+    giveawayProducts: GiveawayProduct[];
+}
+interface ScriptAutoFreeGiftConfig {
+    activityAvailableQuery?: string;
+    activityQroperty?: string;
+    breakpoints?: Array<{
+        breakpoint: string;
+        giveawayProducts: GiveawayProduct[];
+    }>;
+    includeTags?: string[];
+    useTotalAmount?: boolean;
+    requireLogin?: boolean;
+}
+interface UseScriptAutoFreeGiftResult {
+    involvedLines: NormalizedLineItem[];
+    reorder: (a: NormalizedLineItem, b: NormalizedLineItem) => number;
+    disableCodeRemove: boolean;
+    nextFreeGiftLevel: Breakpoint | null;
+    freeGiftLevel: Breakpoint | null;
+    involvedSubTotal: Decimal;
+    giftProductsResult?: NormalizedProduct[];
+}
+declare const useScriptAutoFreeGift: ({ campaign, _giveaway, cart, locale: providedLocale, lines, profile, }: {
+    campaign?: ScriptAutoFreeGiftConfig;
+    _giveaway: string;
+    cart: NormalizedCart | undefined;
+    locale?: string;
+    lines?: AddToCartLineItem[];
+    profile?: any;
+}) => UseScriptAutoFreeGiftResult;
+
 /**
  * Plus Member Types
  * Type definitions for Plus Member functionality
@@ -510,4 +680,4 @@ type DeliveryCustomData = {
     plus_type?: DeliveryPlusType;
 };
 
-export { type AddToCartLineItem as A, type BuyNowTrackConfig as B, DeliveryPlusType as D, type GtmParams as G, PLUS_MEMBER_TYPE as P, ShippingMethodMode as S, type UseAddToCartOptions as U, type AddToCartInput as a, PlusMemberMode as b, type PlusMemberShippingMethodMetafields as c, type PlusMemberShippingMethodConfig as d, type PlusMemberSettingsMetafields as e, type SelectedPlusMemberVariant as f, type DeliveryCustomData as g, gaTrack as h, trackBeginCheckoutGA as i, trackBuyNowGA as j, trackAddToCartFBQ as k, trackBuyNowFBQ as l, trackAddToCartGA as t };
+export { type AddToCartLineItem as A, trackAddToCartFBQ as B, type BuyNowTrackConfig as C, DeliveryPlusType as D, trackBuyNowFBQ as E, type GtmParams as G, PLUS_MEMBER_TYPE as P, type ScriptAutoFreeGiftConfig as S, type UseAutoRemoveFreeGiftsOptions as U, type UseAutoRemoveFreeGiftsResult as a, isScriptGift as b, isBuyGetGift as c, isAnyGift as d, type UseScriptAutoFreeGiftResult as e, useScriptAutoFreeGift as f, type AddToCartInput as g, type UseAddToCartOptions as h, isFunctionGift as i, PlusMemberMode as j, ShippingMethodMode as k, type PlusMemberShippingMethodMetafields as l, type PlusMemberShippingMethodConfig as m, type PlusMemberSettingsMetafields as n, type SelectedPlusMemberVariant as o, type DeliveryCustomData as p, gaTrack as q, trackBeginCheckoutGA as r, trackBuyNowGA as s, trackAddToCartGA as t, useAutoRemoveFreeGifts as u, type GA4Data as v, waitForGtagReady as w, getGA4ClientId as x, getGA4SessionId as y, getGA4Data as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anker-in/shopify-react",
-  "version": "1.3.0-beta.0",
+  "version": "1.3.0-beta.2",
   "description": "React hooks and components for Shopify SDK",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -31,8 +31,8 @@
     "decimal.js": "^10.6.0",
     "js-cookie": "^3.0.5",
     "swr": "^2.2.0",
-    "@anker-in/shopify-sdk": "1.2.0-beta.0",
-    "@anker-in/shopify-core": "1.0.1"
+    "@anker-in/shopify-core": "1.0.1",
+    "@anker-in/shopify-sdk": "1.2.0-beta.2"
   },
   "peerDependencies": {
     "react": ">=18.0.0",