@intercartx/booster-core

核心功能库，提供结账系统的业务逻辑、数据模型、验证工具、API 接口和样式文件。这是一个框架无关的核心包，为上层 UI 组件库提供基础能力。

安装

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）
  • 订单确认

• 样式文件: 提供完整的样式系统

  • 全局样式
  • 组件样式
  • 主题配置
  • 响应式设计

使用方式

基础导入

import { 
  setGlobalConfig, 
  getGlobalConfig,
  globalState,
  CheckoutConfig 
} from '@intercartx/booster-core'

配置管理

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)

使用验证函数

import { 
  validateEmail, 
  validatePhone, 
  validateRequired,
  validateCountry 
} from '@intercartx/booster-core'

// 验证邮箱
const isValidEmail = validateEmail('[email protected]')

// 验证电话
const isValidPhone = validatePhone('+1234567890', 'US')

// 验证必填字段
const isValid = validateRequired('value')

// 验证国家
const isValidCountry = validateCountry('US')

使用工具函数

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

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: {
      // 产品信息
    }
  }
})

使用样式

// 导入全局样式
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'

使用业务模型

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

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

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 自动前缀

构建

# 构建 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 库