@seaverse/payment-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1058 @@
+/**
+ * Type definitions for SeaVerse Payment API
+ * Generated from payment.yaml OpenAPI specification
+ */
+/**
+ * Credit pool type in the 4-pool system
+ * - daily: Daily credits (expires at next day 00:00 UTC)
+ * - event: Event credits (expires at event deadline)
+ * - monthly: Monthly credits (expires 30 days after last grant)
+ * - permanent: Permanent credits (never expires)
+ */
+type CreditPoolType = 'daily' | 'event' | 'monthly' | 'permanent';
+/**
+ * Single credit pool detail
+ */
+interface CreditPoolDetail {
+    /**
+     * Pool type
+     */
+    type: CreditPoolType;
+    /**
+     * Balance in this pool (decimal string for precision)
+     */
+    balance: string;
+    /**
+     * Expiration timestamp in milliseconds
+     * - 0 means never expires (permanent pool only)
+     * - > 0 means specific expiration time (Unix timestamp in ms)
+     */
+    expires_at: number;
+}
+/**
+ * Credit detail response data
+ */
+interface CreditDetailResponse {
+    /**
+     * Total balance across all pools
+     */
+    total_balance: string;
+    /**
+     * Array of pool details (only includes pools with balance > 0)
+     */
+    pools: CreditPoolDetail[];
+}
+/**
+ * Credit detail success response
+ */
+interface CreditDetailSuccessResponse {
+    code: 0;
+    message: string;
+    data: CreditDetailResponse;
+}
+/**
+ * Credit account model
+ */
+interface CreditAccount {
+    id: string;
+    user_id: string;
+    app_id: string | null;
+    balance: number;
+    total_earned: number;
+    total_spent: number;
+    frozen_balance: number;
+    last_transaction_id?: string;
+    status: CreditAccountStatus;
+    status_reason?: string;
+    created_at: string;
+    updated_at: string;
+    last_activity_at?: string;
+}
+/**
+ * Credit account status
+ */
+type CreditAccountStatus = 'active' | 'suspended' | 'frozen';
+/**
+ * Credit transaction model
+ */
+interface CreditTransaction {
+    id: string;
+    user_id: string;
+    app_id: string | null;
+    type: TransactionType;
+    amount: number;
+    balance_before: number;
+    balance_after: number;
+    source: string;
+    source_id?: string;
+    description: string;
+    status: TransactionStatus;
+    status_reason?: string;
+    metadata?: Record<string, unknown>;
+    created_at: string;
+    completed_at?: string;
+}
+/**
+ * Transaction type
+ */
+type TransactionType = 'spend' | 'earn' | 'refund' | 'adjust' | 'freeze' | 'unfreeze';
+/**
+ * Transaction status
+ */
+type TransactionStatus = 'pending' | 'completed' | 'failed' | 'cancelled';
+/**
+ * List transactions request parameters
+ */
+interface ListTransactionsRequest {
+    type?: TransactionType;
+    source?: string;
+    status?: TransactionStatus;
+    start_date?: string;
+    end_date?: string;
+    page?: number;
+    page_size?: number;
+}
+/**
+ * Transaction list response
+ */
+interface TransactionListResponse {
+    transactions: CreditTransaction[];
+    page: number;
+    page_size: number;
+    has_more: boolean;
+}
+/**
+ * Standard success response wrapper
+ */
+interface ApiSuccessResponse<T> {
+    code: 0;
+    message: string;
+    data: T;
+}
+/**
+ * Standard error response
+ */
+interface ApiErrorResponse {
+    code: number;
+    message: string;
+}
+/**
+ * API response type (success or error)
+ */
+type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse;
+
+/**
+ * Payment client configuration options
+ */
+interface PaymentClientOptions {
+    /**
+     * Base URL for the Payment API
+     * @default 'https://payment.sg.seaverse.dev'
+     * @example 'https://payment.sg.seaverse.dev'
+     */
+    baseURL?: string;
+    /**
+     * Application ID for multi-tenant isolation
+     * @example 'seaverse' for SeaVerse platform
+     * @example 'game-abc123' for third-party apps
+     */
+    appId: string;
+    /**
+     * Bearer token for authentication
+     */
+    token: string;
+    /**
+     * Request timeout in milliseconds
+     * @default 30000
+     */
+    timeout?: number;
+}
+/**
+ * Payment API error
+ */
+declare class PaymentAPIError extends Error {
+    code: number;
+    response?: ApiErrorResponse | undefined;
+    constructor(message: string, code: number, response?: ApiErrorResponse | undefined);
+}
+/**
+ * SeaVerse Payment API Client
+ *
+ * Provides query capabilities for user credit accounts and transactions with multi-tenant support.
+ * All methods are read-only - credit spending/granting is handled by platform backend.
+ *
+ * ## Multi-tenant Architecture
+ * - Each app has isolated credit accounts using `app_id`
+ * - Same user can have different credit accounts in different apps
+ * - Use `appId` to specify which app's credit pool to access
+ *
+ * @example
+ * ```typescript
+ * // SeaVerse platform usage
+ * const client = new PaymentClient({
+ *   appId: 'seaverse',
+ *   token: 'your-bearer-token'
+ * });
+ *
+ * // Third-party app usage
+ * const gameClient = new PaymentClient({
+ *   appId: 'game-abc123',
+ *   token: 'your-bearer-token'
+ * });
+ *
+ * // Get credit account
+ * const account = await client.getCreditAccount();
+ * console.log(`Balance: ${account.balance} credits`);
+ *
+ * // List recent transactions
+ * const transactions = await client.listTransactions({ page_size: 10 });
+ * ```
+ */
+declare class PaymentClient {
+    private axios;
+    constructor(options: PaymentClientOptions);
+    /**
+     * Get credit detail with 4-pool system information
+     *
+     * Returns detailed credit information across 4 pools (daily/event/monthly/permanent)
+     * with expiration timestamps. This is the recommended method for displaying user credits.
+     *
+     * **Credit Pool Types:**
+     * - `daily`: Daily credits (expires at next day 00:00 UTC)
+     * - `event`: Event credits (expires at event deadline)
+     * - `monthly`: Monthly credits (expires 30 days after last grant)
+     * - `permanent`: Permanent credits (never expires)
+     *
+     * **Consumption Priority:**
+     * Daily → Event → Monthly → Permanent
+     *
+     * **Response Features:**
+     * - Only returns pools with balance > 0
+     * - `expires_at` is millisecond timestamp (0 means permanent)
+     * - Frontend can calculate remaining time from timestamp
+     *
+     * **Recommended Refresh Rate:** 30 seconds
+     *
+     * @returns Credit detail with pool breakdown
+     * @throws {PaymentAPIError} If request fails
+     *
+     * @example
+     * ```typescript
+     * const detail = await client.getCreditDetail();
+     * console.log(`Total Balance: ${detail.total_balance}`);
+     *
+     * detail.pools.forEach(pool => {
+     *   const label = pool.expires_at === 0
+     *     ? 'Permanent'
+     *     : `Expires in ${Math.floor((pool.expires_at - Date.now()) / 86400000)} days`;
+     *   console.log(`${pool.type}: ${pool.balance} (${label})`);
+     * });
+     * ```
+     */
+    getCreditDetail(): Promise<CreditDetailResponse>;
+    /**
+     * Get authenticated user's credit account information
+     *
+     * Returns current balance, total earned/spent, frozen balance, and account status.
+     *
+     * @deprecated Use getCreditDetail() instead for the new 4-pool credit system
+     * @returns Credit account information
+     * @throws {PaymentAPIError} If request fails
+     *
+     * @example
+     * ```typescript
+     * const account = await client.getCreditAccount();
+     * console.log(`Balance: ${account.balance}`);
+     * console.log(`Status: ${account.status}`);
+     * ```
+     */
+    getCreditAccount(): Promise<CreditAccount>;
+    /**
+     * List credit transactions with filters and pagination
+     *
+     * Query user's transaction history with optional filters for type, source, status, and date range.
+     * Supports pagination with max 50 items per page.
+     *
+     * @param request - List transactions request parameters
+     * @returns Paginated transaction list with has_more flag
+     * @throws {PaymentAPIError} If request fails
+     *
+     * @example
+     * ```typescript
+     * // Get recent transactions
+     * const result = await client.listTransactions({ page_size: 20 });
+     *
+     * // Filter by type
+     * const spending = await client.listTransactions({
+     *   type: 'spend',
+     *   page: 1,
+     *   page_size: 10
+     * });
+     *
+     * // Filter by date range
+     * const recentTransactions = await client.listTransactions({
+     *   start_date: '2024-01-01T00:00:00Z',
+     *   end_date: '2024-12-31T23:59:59Z',
+     *   status: 'completed'
+     * });
+     * ```
+     */
+    listTransactions(request?: ListTransactionsRequest): Promise<TransactionListResponse>;
+    /**
+     * Update the bearer token for authentication
+     *
+     * Use this method to update the token when it expires or needs to be refreshed.
+     *
+     * @param token - New bearer token
+     *
+     * @example
+     * ```typescript
+     * client.setToken('new-bearer-token');
+     * ```
+     */
+    setToken(token: string): void;
+    /**
+     * Update the base URL for the API
+     *
+     * Use this method to switch between different environments (dev/staging/prod).
+     *
+     * @param baseURL - New base URL
+     *
+     * @example
+     * ```typescript
+     * client.setBaseURL('https://payment.sg.seaverse.dev');
+     * ```
+     */
+    setBaseURL(baseURL: string): void;
+    /**
+     * Update the app ID for multi-tenant isolation
+     *
+     * Use this method to switch between different apps at runtime.
+     *
+     * @param appId - New app ID
+     *
+     * @example
+     * ```typescript
+     * // Switch to SeaVerse platform
+     * client.setAppId('seaverse');
+     *
+     * // Switch to third-party app
+     * client.setAppId('game-abc123');
+     * ```
+     */
+    setAppId(appId: string): void;
+}
+
+/**
+ * SeaVerse Payment SDK - 支付弹窗类型定义
+ * 基于 OpenAPI 规范和 SeaArt Payment SDK 定义
+ */
+/**
+ * 支付环境
+ */
+type PaymentEnvironment = 'develop' | 'release';
+/**
+ * 支付弹窗客户端配置
+ */
+interface CheckoutClientConfig {
+    /** 支付网关 API 地址 */
+    apiHost: string;
+    /** 运行环境 */
+    environment?: PaymentEnvironment;
+    /** 调试模式 */
+    debug?: boolean;
+    /**
+     * JWT Token（静态传入）
+     * 与 getAuthToken 二选一，authToken 优先级更高
+     */
+    authToken?: string;
+    /**
+     * 获取 JWT Token 的函数（动态获取）
+     * 与 authToken 二选一
+     */
+    getAuthToken?: () => string | null | Promise<string | null>;
+    /** SDK CDN 地址（可选，使用默认值） */
+    sdkCdnUrl?: string;
+    /** SDK 加载超时时间（毫秒） */
+    sdkTimeout?: number;
+}
+/**
+ * SDK 初始化配置（从 API 返回）
+ */
+interface SDKConfig {
+    /** SeaArt App ID */
+    appId: string;
+    /** SeaArt API Host */
+    apiHost: string;
+    /** 运行环境 */
+    environment: PaymentEnvironment;
+}
+/**
+ * 购买类型
+ * - 1: 一次性购买
+ * - 2: 订阅
+ */
+type PurchaseType = 1 | 2;
+/**
+ * 订阅周期
+ */
+type SubscriptionPeriod = 'week' | 'month' | 'year';
+/**
+ * 订阅参数
+ */
+interface SubscriptionParams {
+    /** 订阅周期 */
+    period: SubscriptionPeriod;
+    /** 首次计费延迟天数（0 = 立即扣费） */
+    firstDays?: number;
+    /** 每周期金额（USD） */
+    periodAmount: number;
+}
+/**
+ * 基础结账选项
+ */
+interface BaseCheckoutOptions {
+    /** 商品 ID（推荐，自动查询价格） */
+    productId?: string;
+    /** 商品名称（仅当未提供 productId 时使用） */
+    productName?: string;
+    /** 价格 USD（仅当未提供 productId 时使用） */
+    price?: number;
+    /** 额外自定义数据 */
+    extra?: Record<string, unknown>;
+    /** 语言设置 */
+    language?: string;
+    /** 用户名（显示用） */
+    userName?: string;
+}
+/**
+ * 一次性购买选项
+ */
+interface CheckoutOptions extends BaseCheckoutOptions {
+    /** 支付成功回调 */
+    onSuccess?: (result: PaymentResult) => void;
+    /** 支付失败/取消回调 */
+    onError?: (error: CheckoutPaymentError) => void;
+    /** 关闭支付弹窗回调 */
+    onClose?: () => void;
+}
+/**
+ * 订阅购买选项
+ */
+interface SubscribeOptions extends CheckoutOptions {
+    /** 订阅周期 */
+    period: SubscriptionPeriod;
+    /** 每期金额 */
+    periodAmount: number;
+    /** 首次扣款延迟天数（0 = 立即扣款） */
+    firstDays?: number;
+}
+/**
+ * 显示支付弹窗选项
+ */
+interface ShowPaymentOptions {
+    /** 交易 ID */
+    transactionId: string;
+    /** 语言 */
+    language?: string;
+    /** 用户名 */
+    userName?: string;
+    /** 商品名 */
+    productName?: string;
+    /** 来源标识 */
+    from?: string;
+    /** 成功回调 */
+    onSuccess?: (result: PaymentResult) => void;
+    /** 失败/取消回调 */
+    onUnsuccess?: (result: PaymentUnsuccessResult) => void;
+}
+/**
+ * SDK 结账请求
+ */
+interface SDKCheckoutRequest {
+    /** 商品 ID（推荐） */
+    product_id?: string;
+    /** 商品名称 */
+    product_name?: string;
+    /** 价格（USD） */
+    price?: number;
+    /** 购买类型：1-一次性，2-订阅 */
+    purchase_type: PurchaseType;
+    /** 订阅参数（purchase_type=2 时必填） */
+    subscription?: SubscriptionParams;
+    /** 额外数据 */
+    extra?: Record<string, unknown>;
+}
+/**
+ * SDK 结账响应
+ */
+interface SDKCheckoutResponse {
+    /** 订单 ID */
+    order_id: string;
+    /** 交易 ID（用于调起 SDK） */
+    transaction_id: string;
+    /** 实际支付金额 */
+    price: number;
+    /** 货币代码 */
+    currency: string;
+    /** SDK 初始化配置 */
+    sdk_config: {
+        app_id: string;
+        api_host: string;
+        environment: PaymentEnvironment;
+    };
+}
+/**
+ * 统一 API 响应格式
+ */
+interface CheckoutAPIResponse<T> {
+    /** 业务状态码：0-成功，其他-错误 */
+    code: number;
+    /** 响应消息 */
+    msg: string;
+    /** 响应数据 */
+    data: T | null;
+}
+/**
+ * 结账结果
+ */
+interface CheckoutResult {
+    /** 订单 ID */
+    orderId: string;
+    /** 交易 ID */
+    transactionId: string;
+    /** 支付金额 */
+    price: number;
+    /** 货币代码 */
+    currency: string;
+    /** SDK 配置 */
+    sdkConfig: SDKConfig;
+}
+/**
+ * 支付成功结果
+ */
+interface PaymentResult {
+    /** 交易 ID */
+    transactionId: string;
+    /** 状态 */
+    status: 'success';
+    /** 额外数据 */
+    data?: Record<string, unknown>;
+}
+/**
+ * 支付未成功结果
+ */
+interface PaymentUnsuccessResult {
+    /** 原因 */
+    reason: 'cancel' | 'error' | 'timeout';
+    /** 消息 */
+    message: string;
+    /** 交易 ID */
+    transactionId: string;
+}
+/**
+ * 支付错误代码
+ */
+type CheckoutPaymentErrorCode = 'SDK_LOAD_FAILED' | 'SDK_NOT_READY' | 'API_ERROR' | 'CHECKOUT_FAILED' | 'PAYMENT_CANCELLED' | 'PAYMENT_FAILED' | 'INVALID_PARAMS' | 'UNAUTHORIZED' | 'NETWORK_ERROR' | 'UNKNOWN_ERROR';
+/**
+ * 支付错误
+ */
+interface CheckoutPaymentError {
+    /** 错误代码 */
+    code: CheckoutPaymentErrorCode;
+    /** 错误消息 */
+    message: string;
+    /** 原始错误 */
+    cause?: unknown;
+}
+/**
+ * SeaArtPay SDK 实例接口
+ */
+interface SeaArtPaySDK {
+    /** 初始化 */
+    init(config: {
+        debug?: boolean;
+        iframeUrl?: string;
+    }): void;
+    /** 显示支付弹窗 */
+    show(options: {
+        transactionId: string;
+        language?: string;
+        userName?: string;
+        productName?: string;
+        from?: string;
+        onSuccess?: (result: unknown) => void;
+        onUnsuccess?: (result: unknown) => void;
+    }): void;
+    /** 关闭支付弹窗 */
+    close(): void;
+    /** 版本号 */
+    version?: string;
+}
+/**
+ * 全局 Window 扩展
+ */
+declare global {
+    interface Window {
+        SeaArtPay?: SeaArtPaySDK | {
+            SeaArtPay: SeaArtPaySDK;
+        };
+    }
+}
+
+/**
+ * PaymentCheckoutClient - 支付弹窗客户端
+ * 提供支付弹窗的初始化、结账和订阅功能
+ */
+
+/**
+ * 支付客户端状态
+ */
+type CheckoutClientStatus = 'idle' | 'initializing' | 'ready' | 'error';
+/**
+ * 支付弹窗客户端类
+ *
+ * 提供一次性购买和订阅购买功能，自动处理：
+ * - SeaArtPay SDK 的动态加载
+ * - 创建结账订单
+ * - 显示支付弹窗
+ * - 支付结果回调
+ *
+ * @example
+ * ```typescript
+ * // 创建客户端
+ * const checkoutClient = new PaymentCheckoutClient({
+ *   apiHost: 'https://payment.sg.seaverse.dev',
+ *   authToken: 'your-jwt-token',
+ *   environment: 'develop',
+ *   debug: true,
+ * });
+ *
+ * // 初始化
+ * await checkoutClient.init();
+ *
+ * // 发起购买
+ * const result = await checkoutClient.checkout({
+ *   productId: 'pkg_starter',
+ *   onSuccess: (res) => console.log('支付成功:', res),
+ *   onError: (err) => console.error('支付失败:', err),
+ * });
+ * ```
+ */
+declare class PaymentCheckoutClient {
+    private config;
+    private loader;
+    private checkoutAPI;
+    private status;
+    private initPromise;
+    constructor(config: CheckoutClientConfig);
+    /**
+     * 获取客户端状态
+     */
+    getStatus(): CheckoutClientStatus;
+    /**
+     * 检查是否已初始化
+     */
+    isReady(): boolean;
+    /**
+     * 初始化客户端
+     * 加载 SeaArtPay SDK
+     */
+    init(): Promise<void>;
+    private doInit;
+    /**
+     * 一次性购买
+     * @param options 购买选项
+     * @returns 结账结果（包含 transactionId）
+     */
+    checkout(options: CheckoutOptions): Promise<CheckoutResult>;
+    /**
+     * 订阅购买
+     * @param options 订阅选项
+     * @returns 结账结果（包含 transactionId）
+     */
+    subscribe(options: SubscribeOptions): Promise<CheckoutResult>;
+    /**
+     * 直接打开支付弹窗
+     * 使用已有的 transactionId
+     */
+    showPayment(options: ShowPaymentOptions): void;
+    /**
+     * 关闭支付弹窗
+     */
+    close(): void;
+    /**
+     * 获取环境配置
+     */
+    getEnvironmentConfig(): {
+        apiHost: string;
+        iframeUrl: string;
+    };
+    /**
+     * 确保客户端已就绪
+     */
+    private ensureReady;
+    /**
+     * 获取 SDK 实例
+     */
+    private getSDK;
+    /**
+     * 显示支付弹窗
+     */
+    private showPaymentModal;
+    /**
+     * 创建支付错误
+     */
+    private createError;
+    /**
+     * 日志输出
+     */
+    private log;
+}
+
+/**
+ * 结账 API 模块
+ * 实现 /api/v1/payment/sdk/checkout 接口调用
+ */
+
+/**
+ * 结账 API 配置
+ */
+interface CheckoutAPIConfig {
+    /** API 基础地址 */
+    apiHost: string;
+    /** 获取 JWT Token */
+    getAuthToken: () => string | null | Promise<string | null>;
+    /** 调试模式 */
+    debug?: boolean;
+}
+/**
+ * 结账 API 客户端
+ */
+declare class CheckoutAPI {
+    private config;
+    constructor(config: CheckoutAPIConfig);
+    /**
+     * 创建一次性购买订单
+     */
+    createOneTimeCheckout(params: {
+        productId?: string;
+        productName?: string;
+        price?: number;
+        extra?: Record<string, unknown>;
+    }): Promise<CheckoutResult>;
+    /**
+     * 创建订阅订单
+     */
+    createSubscriptionCheckout(params: {
+        productId?: string;
+        productName?: string;
+        price?: number;
+        subscription: SubscriptionParams;
+        extra?: Record<string, unknown>;
+    }): Promise<CheckoutResult>;
+    /**
+     * 创建结账订单
+     */
+    private createCheckout;
+    /**
+     * 验证请求参数
+     */
+    private validateRequest;
+    /**
+     * 转换响应数据
+     */
+    private transformResponse;
+    /**
+     * 映射错误代码
+     */
+    private mapErrorCode;
+    /**
+     * 创建支付错误
+     */
+    private createError;
+    /**
+     * 检查是否是支付错误
+     */
+    private isPaymentError;
+    /**
+     * 日志输出
+     */
+    private log;
+}
+
+/**
+ * SeaArtPay SDK 加载器
+ * 负责从 CDN 动态加载 SeaArt 支付 SDK
+ */
+
+/**
+ * SDK 加载状态
+ */
+type SDKLoadStatus = 'idle' | 'loading' | 'loaded' | 'error';
+/**
+ * 加载器配置
+ */
+interface LoaderConfig {
+    /** CDN 地址 */
+    cdnUrl?: string;
+    /** 加载超时时间（毫秒） */
+    timeout?: number;
+    /** 调试模式 */
+    debug?: boolean;
+    /** 运行环境 */
+    environment?: PaymentEnvironment;
+}
+/**
+ * SDK 加载器类
+ */
+declare class SeaArtPayLoader {
+    private status;
+    private sdk;
+    private loadPromise;
+    private config;
+    constructor(config?: LoaderConfig);
+    /**
+     * 获取当前加载状态
+     */
+    getStatus(): SDKLoadStatus;
+    /**
+     * 检查 SDK 是否已加载
+     */
+    isLoaded(): boolean;
+    /**
+     * 获取 SDK 实例
+     */
+    getSDK(): SeaArtPaySDK | null;
+    /**
+     * 加载 SDK
+     */
+    load(): Promise<SeaArtPaySDK>;
+    /**
+     * 从多个源尝试加载 SDK
+     */
+    private loadSDKFromSources;
+    /**
+     * 动态加载脚本
+     */
+    private loadScript;
+    /**
+     * 提取 SDK 实例
+     * 处理 UMD 包装对象的情况
+     */
+    private extractSDKInstance;
+    /**
+     * 验证 SDK 实例是否有效
+     */
+    private isValidSDK;
+    /**
+     * 初始化 SDK
+     */
+    private initializeSDK;
+    /**
+     * 日志输出
+     */
+    private log;
+    /**
+     * 重置加载器
+     */
+    reset(): void;
+}
+/**
+ * 获取或创建全局加载器
+ */
+declare function getGlobalLoader(config?: LoaderConfig): SeaArtPayLoader;
+/**
+ * 重置全局加载器
+ */
+declare function resetGlobalLoader(): void;
+
+/**
+ * 工具函数模块
+ */
+
+/**
+ * 生成唯一的订单引用号
+ * @param prefix 前缀
+ * @returns 唯一引用号
+ */
+declare function generateOrderReference(prefix?: string): string;
+/**
+ * 将美元金额转换为分
+ * @param dollars 美元金额
+ * @returns 分
+ */
+declare function dollarsToCents(dollars: number): number;
+/**
+ * 将分转换为美元
+ * @param cents 分
+ * @returns 美元金额
+ */
+declare function centsToDollars(cents: number): number;
+/**
+ * 格式化价格显示
+ * @param amount 金额（美元）
+ * @param currency 货币代码
+ * @returns 格式化的价格字符串
+ */
+declare function formatPrice(amount: number, currency?: string): string;
+/**
+ * 创建支付错误对象
+ * @param code 错误代码
+ * @param message 错误消息
+ * @param cause 原始错误
+ * @returns 支付错误对象
+ */
+declare function createCheckoutPaymentError(code: CheckoutPaymentErrorCode, message: string, cause?: unknown): CheckoutPaymentError;
+/**
+ * 检查是否是支付错误
+ * @param error 错误对象
+ * @returns 是否是支付错误
+ */
+declare function isCheckoutPaymentError(error: unknown): error is CheckoutPaymentError;
+/**
+ * 延迟函数
+ * @param ms 毫秒
+ * @returns Promise
+ */
+declare function delay(ms: number): Promise<void>;
+/**
+ * 带超时的 Promise
+ * @param promise 原始 Promise
+ * @param ms 超时毫秒数
+ * @param errorMessage 超时错误消息
+ * @returns 带超时的 Promise
+ */
+declare function withTimeout<T>(promise: Promise<T>, ms: number, errorMessage?: string): Promise<T>;
+/**
+ * 安全的 JSON 解析
+ * @param json JSON 字符串
+ * @param defaultValue 默认值
+ * @returns 解析结果或默认值
+ */
+declare function safeJsonParse<T>(json: string, defaultValue: T): T;
+/**
+ * 检查是否在浏览器环境
+ */
+declare function isBrowser(): boolean;
+/**
+ * 获取当前页面 URL
+ */
+declare function getCurrentUrl(): string;
+/**
+ * 获取 SDK 支持的 locale
+ * @param locale 项目 locale
+ * @returns SDK locale
+ */
+declare function getSDKLocale(locale: string): string;
+
+/**
+ * SeaVerse Payment SDK - 常量配置
+ */
+
+/**
+ * 环境配置
+ */
+declare const ENV_CONFIG: Record<PaymentEnvironment, {
+    apiHost: string;
+    iframeUrl: string;
+}>;
+/**
+ * SDK CDN 地址
+ */
+declare const SDK_CDN_URL = "https://image.cdn2.seaart.me/seaart-payment-sdk/1.0.2/seaart-pay-sdk-umd.min.js";
+/**
+ * SDK 加载超时时间（毫秒）
+ */
+declare const SDK_LOAD_TIMEOUT = 15000;
+/**
+ * SDK 全局对象名称
+ */
+declare const SDK_GLOBAL_NAME = "SeaArtPay";
+/**
+ * API 端点
+ */
+declare const API_ENDPOINTS: {
+    /** SDK 结账接口 */
+    readonly SDK_CHECKOUT: "/api/v1/payment/sdk/checkout";
+};
+/**
+ * 默认配置
+ */
+declare const DEFAULT_CHECKOUT_CONFIG: {
+    readonly environment: PaymentEnvironment;
+    readonly debug: false;
+    readonly language: "en";
+    readonly sdkTimeout: 15000;
+};
+/**
+ * HTTP 状态码
+ */
+declare const HTTP_STATUS: {
+    readonly OK: 200;
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly FORBIDDEN: 403;
+    readonly NOT_FOUND: 404;
+    readonly INTERNAL_ERROR: 500;
+};
+/**
+ * 业务状态码
+ */
+declare const BIZ_CODE: {
+    readonly SUCCESS: 0;
+    readonly BAD_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly SERVER_ERROR: 500;
+};
+
+/**
+ * @seaverse/payment-sdk
+ *
+ * SeaVerse Payment SDK - Credit management and payment checkout
+ *
+ * This SDK provides two main features:
+ *
+ * ## 1. Credit Query (PaymentClient)
+ * Query user credit accounts and transaction history.
+ *
+ * ```typescript
+ * import { PaymentClient } from '@seaverse/payment-sdk';
+ *
+ * const client = new PaymentClient({
+ *   appId: 'seaverse',
+ *   token: 'your-bearer-token',
+ * });
+ *
+ * const detail = await client.getCreditDetail();
+ * console.log(`Total Balance: ${detail.total_balance}`);
+ * ```
+ *
+ * ## 2. Payment Checkout (PaymentCheckoutClient)
+ * Show payment modal for one-time purchases and subscriptions.
+ *
+ * ```typescript
+ * import { PaymentCheckoutClient } from '@seaverse/payment-sdk';
+ *
+ * const checkoutClient = new PaymentCheckoutClient({
+ *   apiHost: 'https://payment.sg.seaverse.dev',
+ *   authToken: 'your-jwt-token',
+ *   environment: 'develop',
+ * });
+ *
+ * await checkoutClient.init();
+ *
+ * await checkoutClient.checkout({
+ *   productId: 'pkg_starter',
+ *   onSuccess: (res) => console.log('Payment success:', res),
+ * });
+ * ```
+ */
+
+/**
+ * SDK version
+ */
+declare const VERSION = "0.1.0";
+
+export { API_ENDPOINTS, BIZ_CODE, CheckoutAPI, DEFAULT_CHECKOUT_CONFIG, ENV_CONFIG, HTTP_STATUS, PaymentAPIError, PaymentCheckoutClient, PaymentClient, SDK_CDN_URL, SDK_GLOBAL_NAME, SDK_LOAD_TIMEOUT, SeaArtPayLoader, VERSION, centsToDollars, createCheckoutPaymentError, delay, dollarsToCents, formatPrice, generateOrderReference, getCurrentUrl, getGlobalLoader, getSDKLocale, isBrowser, isCheckoutPaymentError, resetGlobalLoader, safeJsonParse, withTimeout };
+export type { ApiErrorResponse, ApiResponse, ApiSuccessResponse, BaseCheckoutOptions, CheckoutAPIConfig, CheckoutAPIResponse, CheckoutClientConfig, CheckoutClientStatus, CheckoutOptions, CheckoutPaymentError, CheckoutPaymentErrorCode, CheckoutResult, CreditAccount, CreditAccountStatus, CreditDetailResponse, CreditDetailSuccessResponse, CreditPoolDetail, CreditPoolType, CreditTransaction, ListTransactionsRequest, LoaderConfig, PaymentClientOptions, PaymentEnvironment, PaymentResult, PaymentUnsuccessResult, PurchaseType, SDKCheckoutRequest, SDKCheckoutResponse, SDKConfig, SDKLoadStatus, SeaArtPaySDK, ShowPaymentOptions, SubscribeOptions, SubscriptionParams, SubscriptionPeriod, TransactionListResponse, TransactionStatus, TransactionType };