@intercartx/booster-core 0.0.1-beta.5 → 0.0.1-beta.6

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 库