@intercartx/booster-core 0.0.1-beta.3 → 0.0.1-beta.30

package/README.md

@@ -1,2 +1,380 @@
+# @intercartx/booster-core
 
-@intercartx/booster-core
+核心功能库，提供结账系统的业务逻辑、数据模型、验证工具、API 接口和样式文件。这是一个框架无关的核心包，为上层 UI 组件库提供基础能力。
+
+## 安装
+
+```bash
+npm install @intercartx/booster-core
+# 或
+pnpm add @intercartx/booster-core
+# 或
+yarn add @intercartx/booster-core
+```
+
+## 功能特性
+
+### 🎯 核心功能
+
+- **业务模型 (Models)**: 提供完整的结账业务逻辑模型
+  - 地址管理 (Address)
+  - 支付处理 (Payment)
+  - 订单摘要 (OrderSummary)
+  - 费用管理 (Fees Manager)
+  - 小费管理 (Tips)
+  - 运费管理 (Shipping Methods)
+  - 自定义信息 (Custom Info)
+  - 购买按钮 (Buy Now)
+  - PayPal 模态框 (PayPal Modal)
+  - 电话输入 (Phone)
+
+- **数据验证 (Validation)**: 提供完整的表单验证功能
+  - 邮箱验证
+  - 电话验证
+  - 必填字段验证
+  - 国家/地区验证
+  - 邮政编码验证（支持多个国家）
+  - 州/省验证
+
+- **工具函数 (Utils)**: 提供常用工具函数
+  - 货币格式化
+  - 电话号码处理
+  - Google Places API 集成
+  - 加密工具
+  - 防抖函数
+  - 重试机制
+  - 浏览器信息检测
+  - 追踪工具 (Tracksity)
+
+- **API 接口**: 提供与后端交互的 API
+  - 配置获取
+  - 订单处理
+  - 支付处理（信用卡、ACH、PayPal）
+  - 订单确认
+
+- **样式文件**: 提供完整的样式系统
+  - 全局样式
+  - 组件样式
+  - 主题配置
+  - 响应式设计
+
+## 使用方式
+
+### 基础导入
+
+```typescript
+import { 
+  setGlobalConfig, 
+  getGlobalConfig,
+  globalState,
+  CheckoutConfig 
+} from '@intercartx/booster-core'
+```
+
+### 配置管理
+
+```typescript
+import { setGlobalConfig, CheckoutConfig } from '@intercartx/booster-core'
+
+const config: CheckoutConfig = {
+  token: 'your-token',
+  googleApiKey: 'your-google-api-key',
+  website: {
+    name: 'Your Website',
+    setting: {
+      trackings: {}
+    }
+  },
+  currency: 'USD',
+  language: 'en',
+  region: 'US',
+  feeSetting: {
+    tip: true,
+    coupon: true,
+    shipping: true
+  },
+  processorData: {
+    productInfo: {
+      // 产品信息
+    }
+  },
+  paymentMethods: {
+    // 支付方式配置
+  },
+  publicKey: 'your-public-key'
+}
+
+setGlobalConfig(config)
+```
+
+### 使用验证函数
+
+```typescript
+import { 
+  validateEmail, 
+  validatePhone, 
+  validateRequired,
+  validateCountry 
+} from '@intercartx/booster-core'
+
+// 验证邮箱
+const isValidEmail = validateEmail('user@example.com')
+
+// 验证电话
+const isValidPhone = validatePhone('+1234567890', 'US')
+
+// 验证必填字段
+const isValid = validateRequired('value')
+
+// 验证国家
+const isValidCountry = validateCountry('US')
+```
+
+### 使用工具函数
+
+```typescript
+import { 
+  formatCurrency, 
+  formatPhoneNumber,
+  debounce 
+} from '@intercartx/booster-core'
+
+// 格式化货币
+const formatted = formatCurrency(1000, 'USD') // $10.00
+
+// 格式化电话号码
+const phone = formatPhoneNumber('1234567890', 'US')
+
+// 防抖函数
+const debouncedFn = debounce(() => {
+  console.log('Debounced!')
+}, 300)
+```
+
+### 使用 API
+
+```typescript
+import { apiGetConfig, apiProcessor } from '@intercartx/booster-core/api'
+
+// 获取配置
+const config = await apiGetConfig('your-token')
+
+// 处理订单
+const result = await apiProcessor({
+  website: 'Your Website',
+  region: 'US',
+  processorData: {
+    productInfo: {
+      // 产品信息
+    }
+  }
+})
+```
+
+### 使用样式
+
+```typescript
+// 导入全局样式
+import '@intercartx/booster-core/styles/global.css'
+
+// 导入特定组件样式
+import '@intercartx/booster-core/styles/button.css'
+import '@intercartx/booster-core/styles/input.css'
+import '@intercartx/booster-core/styles/payment.css'
+```
+
+### 使用业务模型
+
+```typescript
+import { 
+  AddressModel,
+  PaymentModel,
+  OrderSummaryModel,
+  TipsModel,
+  ShippingMethodsModel 
+} from '@intercartx/booster-core'
+
+// 创建地址模型实例
+const addressModel = new AddressModel({
+  // 地址配置
+})
+
+// 创建支付模型实例
+const paymentModel = new PaymentModel({
+  // 支付配置
+})
+```
+
+## API 参考
+
+### 主要导出
+
+#### 配置管理
+- `setGlobalConfig(config: CheckoutConfig)`: 设置全局配置
+- `getGlobalConfig(): CheckoutConfig`: 获取全局配置
+- `globalState`: 全局状态对象
+
+#### 验证函数
+- `validateEmail(email: string): boolean`
+- `validatePhone(phone: string, country?: string): boolean`
+- `validateRequired(value: any): boolean`
+- `validateCountry(country: string): boolean`
+- `validateUSZipCode(zipCode: string): boolean`
+- `validateUSStateCode(stateCode: string): boolean`
+- `validateCAPostcode(postcode: string): boolean`
+- `validateCAProvince(province: string): boolean`
+- `validateGBPostcode(postcode: string): boolean`
+- `validateAUPostcode(postcode: string): boolean`
+- `validateAUStateOrTerritory(state: string): boolean`
+- `validateNZPostalCode(postcode: string): boolean`
+- `validateNZRegion(region: string): boolean`
+
+#### 工具函数
+- `formatCurrency(amount: number, currency: string): string`
+- `formatPhoneNumber(phone: string, country: string): string`
+- `debounce<T extends (...args: any[]) => any>(fn: T, delay: number): T`
+- `retry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>`
+- `encrypt(data: string, key: string): string`
+- `getBrowserInfo(): BrowserInfo`
+
+#### API 函数
+- `apiGetConfig(token: string): Promise<CheckoutConfig>`
+- `apiProcessor(data: ProcessorData): Promise<ProcessorResult>`
+- `apiPreOrder(data: PreOrderData): Promise<PreOrderResult>`
+- `apiOrderConfirm(data: OrderConfirmData): Promise<OrderConfirmResult>`
+- `apiCCPayment(data: CCPaymentData): Promise<CCPaymentResult>`
+- `apiACHPayment(data: ACHPaymentData): Promise<ACHPaymentResult>`
+- `apiPPPayment(data: PPPaymentData): Promise<PPPaymentResult>`
+
+#### 业务模型
+- `AddressModel`: 地址管理模型
+- `AddressSuggestModel`: 地址建议模型
+- `MultiRegionsModel`: 多地区模型
+- `PaymentModel`: 支付模型
+- `CCPaymentModel`: 信用卡支付模型
+- `ACHPaymentModel`: ACH 支付模型
+- `PPPaymentModel`: PayPal 支付模型
+- `StripePaymentModel`: Stripe 支付模型
+- `FxpPaymentModel`: FXP 支付模型
+- `OrderSummaryModel`: 订单摘要模型
+- `TipsModel`: 小费模型
+- `ShippingMethodsModel`: 运费方法模型
+- `CustomInfoModel`: 自定义信息模型
+- `BuyNowModel`: 购买按钮模型
+- `PaypalModalModel`: PayPal 模态框模型
+- `PhoneModel`: 电话输入模型
+- `PayButtonModel`: 支付按钮模型
+
+## 类型定义
+
+### CheckoutConfig
+
+```typescript
+interface CheckoutConfig {
+  token: string
+  googleApiKey?: string
+  website: {
+    name: string
+    setting: {
+      trackings: any
+    }
+  }
+  currency: string
+  language: string
+  region: string
+  feeSetting: {
+    tip: boolean
+    coupon: boolean
+    shipping: boolean
+  }
+  processorData: {
+    productInfo: OrderProduct
+  }
+  paymentMethods: PaymentConfig
+  publicKey: string
+}
+```
+
+### PaymentConfig
+
+```typescript
+interface PaymentConfig {
+  CC?: ccPaymentConfig
+  PP?: ppPaymentConfig
+  ACH?: achPaymentConfig
+}
+```
+
+## 样式系统
+
+本包提供了完整的样式系统，包括：
+
+- **全局样式**: `styles/global.css`
+- **组件样式**: 
+  - `styles/button.css`
+  - `styles/input.css`
+  - `styles/select.css`
+  - `styles/payment.css`
+  - `styles/address.css`
+  - `styles/order-summary.css`
+  - `styles/custom-info.css`
+  - `styles/paypal-modal.css`
+  - `styles/phone-input.css`
+  - `styles/fee.css`
+  - `styles/loading.css`
+  - `styles/checkout-page.css`
+  - `styles/stripe-payment.css`
+  - `styles/fxp-payment.css`
+  - `styles/select-list.css`
+  - `styles/theme.css`
+
+## 依赖项
+
+### 核心依赖
+- `@stripe/stripe-js`: Stripe 支付集成
+- `currency-symbol-map`: 货币符号映射
+- `decimal.js`: 精确的十进制运算
+- `libphonenumber-js`: 电话号码处理
+- `node-forge`: 加密工具
+- `payment`: 支付处理
+- `uuid`: UUID 生成
+- `zod`: 数据验证
+
+### 开发依赖
+- `typescript`: TypeScript 支持
+- `sass`: SCSS 编译
+- `tailwindcss`: Tailwind CSS
+- `postcss`: PostCSS 处理
+- `autoprefixer`: CSS 自动前缀
+
+## 构建
+
+```bash
+# 构建 TypeScript
+pnpm run build:ts
+
+# 构建 SCSS
+pnpm run build:scss
+
+# 构建样式文件
+pnpm run build:styles
+
+# 完整构建
+pnpm run build
+
+# 开发模式（监听 SCSS 变化）
+pnpm run dev
+
+# 类型检查
+pnpm run typecheck
+```
+
+## 许可证
+
+GPL-3.0-only
+
+## 相关包
+
+- `@intercartx/booster-react`: React 组件库
+- `@intercartx/booster-solid`: SolidJS 组件库
+- `@intercartx/booster-elements`: Web Components 库

package/dist/api/config/index.d.ts

@@ -5,3 +5,5 @@ export declare function apiProcessor(data: ProcessorRequest): Promise<{
     token: string;
 }>;
 export declare function getApiURL(): string;
+export declare function setPrefixApi(prefix: string): void;
+export type { ProcessorRequest };

package/dist/api/config/index.js

@@ -6,6 +6,9 @@ export async function apiProcessor(data) {
     return post(`/processor`, data);
 }
 export function getApiURL() {
+    if (prefixApi) {
+        return `${prefixApi}/v3`;
+    }
     if (process.env.NODE_ENV === 'development') {
         return '/api/v3';
     }
@@ -15,3 +18,7 @@ export function getApiURL() {
     }
     return `${location.protocol}//${location.host}/v3`;
 }
+let prefixApi = null;
+export function setPrefixApi(prefix) {
+    prefixApi = prefix;
+}

package/dist/api/index.d.ts

@@ -1,3 +1,4 @@
 export * from './config';
 export * from './utils';
 export * from './order';
+export { HTTPError } from './helper';

package/dist/api/index.js

@@ -1,3 +1,4 @@
 export * from './config';
 export * from './utils';
 export * from './order';
+export { HTTPError } from './helper';

package/dist/api/order/index.d.ts

@@ -5,3 +5,4 @@ export * from './cc';
 export * from './pp';
 export * from './ach';
 export * from './types';
+export * from './quick';

package/dist/api/order/index.js

@@ -5,3 +5,4 @@ export * from './cc';
 export * from './pp';
 export * from './ach';
 export * from './types';
+export * from './quick';

package/dist/api/order/quick.d.ts

@@ -0,0 +1,12 @@
+import { OrderProduct } from "../types";
+export interface QuickOrderRequest {
+    products: OrderProduct;
+    confirmUrl: string;
+}
+export interface QuickOrderResponse {
+    sourceToken: string;
+    newToken: string;
+    newOrderId: string;
+    newTradeId: string;
+}
+export declare function apiCreateQuickOrder(token: string, body: QuickOrderRequest): Promise<QuickOrderResponse>;

package/dist/api/order/quick.js

@@ -0,0 +1,4 @@
+import { post } from "../helper";
+export async function apiCreateQuickOrder(token, body) {
+    return post(`/order/quick/submission/${token}`, body);
+}

package/dist/api/order/types.d.ts

@@ -64,3 +64,7 @@ export interface SubmissionRequest extends PreSubmissionRequest {
     action?: string;
     subAction?: PaymentSubAction;
 }
+export declare enum ResponseErrorCode {
+    CREDIT_CARD_FAILED = 2002,// 卡号支付失败，sdk 可以根据此错误码自动请求 paypal 支付
+    ORDER_ALREADY_HAS_TRADE = 4004
+}

package/dist/api/order/types.js

@@ -31,3 +31,8 @@ export var OrderStatusPaid;
     OrderStatusPaid[OrderStatusPaid["Unpaid"] = 0] = "Unpaid";
     OrderStatusPaid[OrderStatusPaid["Paid"] = 1] = "Paid";
 })(OrderStatusPaid || (OrderStatusPaid = {}));
+export var ResponseErrorCode;
+(function (ResponseErrorCode) {
+    ResponseErrorCode[ResponseErrorCode["CREDIT_CARD_FAILED"] = 2002] = "CREDIT_CARD_FAILED";
+    ResponseErrorCode[ResponseErrorCode["ORDER_ALREADY_HAS_TRADE"] = 4004] = "ORDER_ALREADY_HAS_TRADE"; // 订单已关联交易，返回数据可能有 {message: string, data?: {action?: {url?: string, secret?: string}}}1. 当 data?.action?.url 存在时，跳转 url 进行对应操作2. 当 data?.action?.secret 存在时，使用 secret 进行 3ds3. 没有 data 则直接访问确认订单/订阅接口
+})(ResponseErrorCode || (ResponseErrorCode = {}));

package/dist/api/types.d.ts

@@ -15,19 +15,7 @@ interface ShippingMethod {
     price: number | string;
     currency: string;
 }
-interface BaseOrderProduct {
-    display: {
-        title: string;
-        subTitle: string;
-        image: string;
-        quantity: number;
-        price: number | string;
-        originPrice: number | string;
-        discount: number;
-        sku?: string;
-    }[];
-}
-interface OneTimeOrderProduct extends BaseOrderProduct {
+interface OneTimeOrderProduct {
     purchase: {
         cart: {
             quantity: number;
@@ -40,8 +28,9 @@ interface OneTimeOrderProduct extends BaseOrderProduct {
         }[];
         coupon?: string[];
     };
+    display: Display[];
 }
-interface SubscriptionOrderProduct extends BaseOrderProduct {
+interface SubscriptionOrderProduct {
     subscription: {
         pricePlan: {
             products: {
@@ -55,6 +44,21 @@ interface SubscriptionOrderProduct extends BaseOrderProduct {
         }[];
         planId?: string;
     };
+    displays: {
+        display: Display[];
+        interval: number;
+    }[];
+}
+interface Display {
+    title: string;
+    subTitle: string;
+    image: string;
+    quantity: number;
+    price: number | string;
+    originPrice: number | string;
+    discount: number;
+    productId?: string;
+    [key: string]: any;
 }
 type OrderProduct = OneTimeOrderProduct | SubscriptionOrderProduct;
 interface BrowserInfo {

package/dist/index.d.ts

@@ -2,3 +2,5 @@ export * from './validate';
 export * from './models';
 export * from './utils';
 export * from './types';
+export * from './api';
+export * from './report-event';

package/dist/index.js

@@ -2,3 +2,5 @@ export * from './validate';
 export * from './models';
 export * from './utils';
 export * from './types';
+export * from './api';
+export * from './report-event';

package/dist/models/business/CustomInfo.js

@@ -49,7 +49,7 @@ export class CustomInfoModel extends BusinessModel {
             inputMode: 'numeric',
             maxLength: 16,
             ...props.phone,
-            validateFn: validatePhone,
+            validateFn: (e, m) => validatePhone(`${this.phone.prefix}${e}`, m),
             validateMessages: validateMessages.phone,
             region: 'US'
         });

package/dist/models/business/ErrorTip.d.ts

@@ -0,0 +1,9 @@
+import { BaseModel } from "../Base";
+export declare class ErrorTipModel extends BaseModel {
+    isShow: boolean;
+    message: string;
+    reactiveKeys: string[];
+    constructor();
+    showErrorTip(message: string): void;
+    hideErrorTip(): void;
+}

package/dist/models/business/ErrorTip.js

@@ -0,0 +1,27 @@
+import { CheckoutEvents } from "../../types";
+import { BaseModel } from "../Base";
+import { globalState } from "../GlobalState";
+export class ErrorTipModel extends BaseModel {
+    constructor() {
+        super();
+        this.isShow = false;
+        this.message = '';
+        this.reactiveKeys = ['isShow', 'message'];
+        globalState.on(CheckoutEvents.ERROR_TIP_SHOW, (message) => {
+            if (message) {
+                this.showErrorTip(message);
+            }
+            else {
+                this.hideErrorTip();
+            }
+        });
+    }
+    showErrorTip(message) {
+        this.isShow = true;
+        this.message = message;
+    }
+    hideErrorTip() {
+        this.isShow = false;
+        this.message = '';
+    }
+}

package/dist/models/business/FullScreeenLoading.js

@@ -1,4 +1,5 @@
 import { BaseModel } from "../Base";
+import { globalState } from "../GlobalState";
 class FullScreenLoadingModel extends BaseModel {
     constructor() {
         super(...arguments);
@@ -9,10 +10,12 @@ class FullScreenLoadingModel extends BaseModel {
     showLoading(msg) {
         this.isShow = true;
         this.message = msg || 'Processing...';
+        globalState.emit('purchaseing', { isShow: this.isShow, message: this.message });
     }
     hideLoading() {
         this.isShow = false;
         this.message = '';
+        globalState.emit('purchaseing', { isShow: this.isShow, message: this.message });
     }
 }
 export const globalLoading = new FullScreenLoadingModel();

package/dist/models/business/OrderSummary.d.ts

@@ -1,8 +1,9 @@
-import { OrderProduct } from "../../api/types";
+import { OneTimeOrderProduct, SubscriptionOrderProduct } from "../../api/types";
 import { FeeCalculateResponse } from "../../api/utils/types";
 import { BusinessModel } from "./Business";
 export declare class OrderSummaryModel extends BusinessModel {
-    displayProductList: OrderProduct['display'];
+    displayProductList: OneTimeOrderProduct['display'] | SubscriptionOrderProduct['displays'][0]['display'];
+    isSubscription: boolean;
     isOpen: boolean;
     fees: FeeCalculateResponse['feeDetail'];
     reactiveKeys: string[];
@@ -12,4 +13,5 @@ export declare class OrderSummaryModel extends BusinessModel {
     get total(): string;
     get isLoading(): boolean;
     toggleOpen(): void;
+    getSubscriptionPlanTexts(): string[];
 }