@clickaroo/checkout-ui 0.1.7-beta → 1.0.0-beta

package/CHANGELOG.md

@@ -4,40 +4,40 @@
 
 ### Minor Changes
 
-- 配置 storybook、支持多产品下单、添加谷歌地址建议支持
+- Configure storybook, support multi-product checkout, add Google address suggestions support
 
 ## 1.0.4
 
 ### Patch Changes
 
-- 修改.gitlab-ci.yml
+- Update .gitlab-ci.yml
 
 ## 1.0.3
 
 ### Patch Changes
 
-- 添加 Changesets 支持，用于自动管理版本和 changelog
+- Add Changesets support for automatic version and changelog management
 
 ## 1.0.2
 
 ### Patch Changes
 
-- 添加 Terser 压缩混淆生产环境代码
+- Add Terser compression and obfuscation for production code
 
 ## 1.0.1
 
 ### Patch Changes
 
-- 关闭 source map 文件生成
+- Disable source map file generation
 
 ## 1.0.0
 
-### 首次发布
+### Initial Release
 
-- ✨ 完整的结账流程组件
-- ✨ CheckoutProvider 上下文提供者
-- ✨ CustomerInfo 客户信息组件
-- ✨ DeliveryAddress 收货地址组件
-- ✨ PaymentMethods 支付方式组件
-- ✨ ButtonGroup 订单提交按钮组
-- ✨ Stripe 支付集成
+- ✨ Complete checkout flow components
+- ✨ CheckoutProvider context provider
+- ✨ CustomerInfo customer information component
+- ✨ DeliveryAddress delivery address component
+- ✨ PaymentMethods payment methods component
+- ✨ ButtonGroup order submission button group
+- ✨ Stripe payment integration

package/README.md

@@ -17,18 +17,30 @@ yarn add @clickaroo/checkout-ui
 #### Use CheckoutPage
 
 ```tsx
-import { CheckoutPage } from '@clickaroo/checkout-ui';
+import { CheckoutPage, CheckoutProvider, ClickarooProvider } from '@clickaroo/checkout-ui';
 
 function App() {
-  const carts = [{
+  const cart = [{
     sku: "TEST001",
     offerPricePoint: "OPP-TEST001",
-  }]
+  }];
 
   return (
-    <CheckoutPage 
-      cart={carts}
-    />
+    <ClickarooProvider>
+      <CheckoutProvider
+        baseUrl="https://api.clickaroo.io"
+        cart={cart}
+      >
+        <CheckoutPage />
+      </CheckoutProvider>
+    </ClickarooProvider>
   );
 }
 ```
+
+> **Note**: 
+> - `ClickarooProvider` must wrap your application at the root level to manage Clickaroo parameters
+> - `CheckoutProvider` requires a `baseUrl` prop (the API base URL)
+> - `CheckoutPage` must be wrapped with both providers
+
+For more detailed documentation, see the [Storybook documentation](https://your-storybook-url).

package/dist/index.d.ts

@@ -1,23 +1,49 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { OnCheckoutInitCallback, OnPaymentInfoCompleteCallback, OnOrderSubmitCallback, OnOrderSuccessCallback } from '@/types/callback';
-import { CartItem as CartItem$1 } from '@/types/cartItem';
 import React, { ReactNode } from 'react';
-import z from 'zod/v4';
-import { CustomerInfo as CustomerInfo$1, DeliveryAddress as DeliveryAddress$2 } from '@/contexts/CheckoutContext';
-import { OrderDetail as OrderDetail$1 } from '@/types/order';
+import { z } from 'zod';
 
-interface CheckoutProps {
-    cart: CartItem$1[];
-    onCheckoutInit?: OnCheckoutInitCallback;
+interface CartItem {
+    sku: string;
+    offerPricePoint: string;
+    [key: string]: unknown;
+}
+
+declare enum PaymentType {
+    OneTime = "one-time",
+    Subscription = "subscription"
+}
+interface CheckoutCartItem extends CartItem {
+    priceInCents: number;
+    currency: string;
+    quantity: number;
+    paymentType: PaymentType;
+}
+interface OnCheckoutInitCallback {
+    (): void;
+}
+interface OnPaymentInfoCompleteCallback {
+    (products: CheckoutCartItem[], totalAmount: number): void;
+}
+interface OnOrderSubmitCallback {
+    (products: CheckoutCartItem[], totalAmount: number, setMetadata: (metadata: Record<string, string>) => void): void;
+}
+interface OnOrderSuccessCallback {
+    (orderCode: string, tradeCode?: string): void;
+}
+
+interface CheckoutPageProps {
+    googleApiKey?: string;
     onPaymentInfoComplete?: OnPaymentInfoCompleteCallback;
     onOrderSubmit?: OnOrderSubmitCallback;
     onOrderSuccess?: OnOrderSuccessCallback;
-    googleApiKey?: string;
-    metadata?: Record<string, string>;
 }
-declare const CheckoutPage: (props: CheckoutProps) => react_jsx_runtime.JSX.Element;
+declare const CheckoutPage: (props: CheckoutPageProps) => react_jsx_runtime.JSX.Element;
 
-declare const SubmitButton: React.FC;
+interface SubmitButtonProps {
+    onOrderSubmit?: OnOrderSubmitCallback;
+    onOrderSuccess?: OnOrderSuccessCallback;
+}
+declare const SubmitButton: React.FC<SubmitButtonProps>;
 
 interface CustomInfoProps {
     showTitle?: boolean;
@@ -26,79 +52,40 @@ declare const CustomInfo: React.FC<CustomInfoProps>;
 
 interface DeliveryAddressProps {
     showTitle?: boolean;
+    googleApiKey?: string;
 }
 declare const DeliveryAddress$1: React.FC<DeliveryAddressProps>;
 
 interface PaymentMethodsProps {
     showText?: boolean;
-}
-declare const PaymentMethods: React.FC<PaymentMethodsProps>;
-
-declare const CustomerInfoSchema: z.ZodObject<{
-    firstName: z.ZodString;
-    lastName: z.ZodString;
-    email: z.ZodString;
-    phone: z.ZodString;
-}, z.core.$strip>;
-type CustomerInfo = z.infer<typeof CustomerInfoSchema>;
-declare const AddressSchema: z.ZodObject<{
-    country: z.ZodString;
-    address: z.ZodString;
-    address2: z.ZodOptional<z.ZodString>;
-    city: z.ZodString;
-    state: z.ZodString;
-    zipCode: z.ZodString;
-}, z.core.$strip>;
-type DeliveryAddress = z.infer<typeof AddressSchema>;
-interface CheckoutProviderProps {
-    children: ReactNode;
-    cart: CartItem$1[];
-    onCheckoutInit?: OnCheckoutInitCallback;
     onPaymentInfoComplete?: OnPaymentInfoCompleteCallback;
-    onOrderSubmit?: OnOrderSubmitCallback;
-    onOrderSuccess?: OnOrderSuccessCallback;
-    googleApiKey?: string;
-    metadata?: Record<string, string>;
-}
-declare const CheckoutProvider: React.FC<CheckoutProviderProps>;
-
-declare const configureAPIUrl: (url: string) => void;
-
-interface CartItem {
-    sku: string;
-    offerPricePoint: string;
-    [key: string]: unknown;
-}
-
-interface UseCheckoutContextPublic {
-    isFormValid: () => boolean;
-    customerInfo: CustomerInfo$1;
-    deliveryAddress: DeliveryAddress$2;
-    isPaymentComplete: boolean;
-    cart: CartItem$1[];
-    updateCustomerInfo: (info: Partial<CustomerInfo$1>) => void;
-    updateDeliveryAddress: (address: Partial<DeliveryAddress$2>) => void;
 }
-declare const useCheckoutContextPublic: () => UseCheckoutContextPublic;
+declare const PaymentMethods: React.FC<PaymentMethodsProps>;
 
-interface OrderSubmissionResult {
-    success: boolean;
-    message: string;
-    orderCode?: string;
-    tradeCode?: string;
+interface ClickarooInfo {
+    offer_code: string;
+    type: "one_off" | "subscription_schedules";
+    payment: {
+        type: "stripe";
+        data: ClickarooPaymentStripe;
+    };
+    subscription_schedules?: {
+        phase: number;
+        price_in_cents: number;
+        currency: string;
+        quantity: number;
+        period: string;
+    }[];
+    one_off?: {
+        price_in_cents: number;
+        currency: string;
+        quantity: number;
+    };
 }
-declare const useOrderSubmission: () => {
-    isSubmitting: boolean;
-    submitOrder: () => Promise<OrderSubmissionResult>;
-};
-
-interface UseOrderDetailReturn {
-    orderDetail: OrderDetail$1 | null;
-    loading: boolean;
-    error: string | null;
-    refetch: () => void;
+interface ClickarooPaymentStripe {
+    publishable_key: string;
+    account_id: string;
 }
-declare const useOrderDetail: (orderCode: string | null) => UseOrderDetailReturn;
 
 declare enum OrderPaymentStatus {
     PENDING = "pending",
@@ -220,52 +207,182 @@ interface OrderDetail {
     updated_at: string;
 }
 
-declare const createOrderWithToken: (orderData: Omit<CreateOrderRequest, "clickaroo_token">) => Promise<{
+interface ApiClientConfig {
+    baseUrl: string;
+}
+interface ApiResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: {
+        message: string;
+        code?: string;
+        details?: unknown;
+    };
+}
+/**
+ * SDK-style API client for Clickaroo backend.
+ */
+declare class ApiClient {
+    private baseUrl;
+    constructor(config: ApiClientConfig);
+    getBaseUrl(): string;
+    setBaseUrl(baseUrl: string): void;
+    createOrder(orderData: CreateOrderRequest): Promise<ApiResponse<CreateOrderResponse>>;
+    createOrderWithToken(orderData: Omit<CreateOrderRequest, "clickaroo_token">): Promise<ApiResponse<CreateOrderResponse>>;
+    getOrderDetail(orderCode: string): Promise<ApiResponse<OrderDetail>>;
+    getPricePointInfo(offerPricePoints: string | string[]): Promise<ApiResponse<ClickarooInfo | Record<string, ClickarooInfo>>>;
+}
+
+declare global {
+    interface Window {
+        dataLayer: unknown[];
+        gtag: (...args: unknown[]) => void;
+    }
+}
+
+declare const CustomerInfoSchema: z.ZodObject<{
+    firstName: z.ZodString;
+    lastName: z.ZodString;
+    email: z.ZodString;
+    phone: z.ZodString;
+}, z.core.$strip>;
+type CustomerInfo = z.infer<typeof CustomerInfoSchema>;
+declare const AddressSchema: z.ZodObject<{
+    country: z.ZodString;
+    address: z.ZodString;
+    address2: z.ZodOptional<z.ZodString>;
+    city: z.ZodString;
+    state: z.ZodString;
+    zipCode: z.ZodString;
+}, z.core.$strip>;
+type DeliveryAddress = z.infer<typeof AddressSchema>;
+interface CheckoutProviderProps {
+    children: ReactNode;
+    cart: CartItem[];
+    baseUrl: string;
+    onCheckoutInit?: OnCheckoutInitCallback;
+    metadata?: Record<string, string>;
+}
+declare const CheckoutProvider: React.FC<CheckoutProviderProps>;
+
+/**
+ * Storage utility functions
+ * Provides unified interface for Cookie, LocalStorage, SessionStorage operations
+ */
+interface CookieOptions {
+    expires?: number;
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    sameSite?: 'strict' | 'lax' | 'none';
+}
+
+/**
+ * ClickarooProvider configuration options
+ */
+interface ClickarooProviderConfig {
+    /** Storage key prefix, if not provided, no prefix is added when storing */
+    keyPrefix?: string;
+    /** List of parameters to manage, if not provided, all parameters from URL are stored */
+    params?: string[];
+    /** Cookie configuration options */
+    cookieOptions?: CookieOptions;
+    /** Whether to output debug information to console */
+    debug?: boolean;
+}
+/**
+ * Clickaroo Context type
+ */
+interface ClickarooContextType {
+    /** Get parameter value */
+    getParam: (paramName: string) => string | null;
+    /** Set parameter value (saved according to storage priority) */
+    setParam: (paramName: string, value: string) => void;
+    /** Get all parameters */
+    getAllParams: () => Record<string, string>;
+    /** Clear parameter */
+    clearParam: (paramName: string) => void;
+    /** Clear all parameters */
+    clearAllParams: () => void;
+    /** Current parameter values (read-only) */
+    params: Record<string, string>;
+}
+/**
+ * ClickarooProvider Props
+ */
+interface ClickarooProviderProps {
+    children: ReactNode;
+    config?: ClickarooProviderConfig;
+}
+/**
+ * ClickarooProvider component
+ * Used to manage Clickaroo-related parameters at the outermost level of the application
+ */
+declare const ClickarooProvider: React.FC<ClickarooProviderProps>;
+
+interface UseCheckoutContextPublic {
+    isFormValid: () => boolean;
+    customerInfo: CustomerInfo;
+    deliveryAddress: DeliveryAddress;
+    isPaymentComplete: boolean;
+    cart: CartItem[];
+    updateCustomerInfo: (info: Partial<CustomerInfo>) => void;
+    updateDeliveryAddress: (address: Partial<DeliveryAddress>) => void;
+}
+declare const useCheckoutContextPublic: () => UseCheckoutContextPublic;
+
+interface OrderSubmissionResult {
+    success: boolean;
+    message: string;
+    orderCode?: string;
+    tradeCode?: string;
+}
+declare const useOrderSubmission: () => {
+    isSubmitting: boolean;
+    submitOrder: () => Promise<OrderSubmissionResult>;
+};
+
+interface UseOrderDetailReturn {
+    orderDetail: OrderDetail | null;
+    loading: boolean;
+    error: string | null;
+    refetch: () => void;
+}
+declare const useOrderDetail: (orderCode: string | null) => UseOrderDetailReturn;
+
+/**
+ * Hook for using Clickaroo parameters
+ *
+ * @example
+ * ```tsx
+ * const { getParam, params } = useClickarooParams();
+ * const token = getParam('token');
+ * const sub4 = getParam('sub4');
+ * ```
+ */
+declare const useClickarooParams: () => ClickarooContextType;
+
+declare const createOrderWithToken: (baseUrl: string, orderData: Omit<CreateOrderRequest, "clickaroo_token">) => Promise<{
     success: boolean;
     data?: CreateOrderResponse;
     error?: OrderApiError;
 }>;
-declare const getOrderDetail: (orderCode: string) => Promise<{
+declare const getOrderDetail: (baseUrl: string, orderCode: string) => Promise<{
     success: boolean;
     data?: OrderDetail;
     error?: OrderApiError;
 }>;
 
-interface ClickarooInfo {
-    offer_code: string;
-    type: "one_off" | "subscription_schedules";
-    payment: {
-        type: "stripe";
-        data: ClickarooPaymentStripe;
-    };
-    subscription_schedules?: {
-        phase: number;
-        price_in_cents: number;
-        currency: string;
-        quantity: number;
-        period: string;
-    }[];
-    one_off?: {
-        price_in_cents: number;
-        currency: string;
-        quantity: number;
-    };
-}
-interface ClickarooPaymentStripe {
-    publishable_key: string;
-    account_id: string;
-}
-
 interface PricePointApiError {
     message: string;
     code?: string;
     details?: unknown;
 }
-declare const getPricePointInfo: (offerPricePoints: string | string[]) => Promise<{
+declare const getPricePointInfo: (baseUrl: string, offerPricePoints: string | string[]) => Promise<{
     success: boolean;
     data?: ClickarooInfo | Record<string, ClickarooInfo>;
     error?: PricePointApiError;
 }>;
 
-export { SubmitButton as ButtonGroup, CheckoutPage, CheckoutProvider, CustomInfo as CustomerInfo, DeliveryAddress$1 as DeliveryAddress, PaymentMethods, configureAPIUrl, createOrderWithToken as createOrder, getOrderDetail, getPricePointInfo, useCheckoutContextPublic as useCheckoutContext, useOrderDetail, useOrderSubmission };
-export type { CartItem, CustomerInfo as CustomerInfoType, DeliveryAddress as DeliveryAddressType, UseCheckoutContextPublic as UseCheckoutContext };
+export { ApiClient, SubmitButton as ButtonGroup, CheckoutPage, CheckoutProvider, ClickarooProvider, CustomInfo as CustomerInfo, DeliveryAddress$1 as DeliveryAddress, PaymentMethods, createOrderWithToken as createOrder, getOrderDetail, getPricePointInfo, useCheckoutContextPublic as useCheckoutContext, useClickarooParams, useOrderDetail, useOrderSubmission };
+export type { ApiClientConfig, ApiResponse, CartItem, ClickarooContextType, ClickarooProviderConfig, CustomerInfo as CustomerInfoType, DeliveryAddress as DeliveryAddressType, UseCheckoutContextPublic as UseCheckoutContext };