@blocklet/payment-broker-client 1.20.17

package/examples/README.md

@@ -0,0 +1,277 @@
+# Payment Kit Broker Client - Examples
+
+这里包含了 Payment Kit Broker Client 的完整使用示例，展示了如何在不同环境中使用 SDK 进行网站部署。
+
+## 📁 目录结构
+
+```
+examples/
+├── nodejs/                    # Node.js 环境示例
+│   ├── deploy-example.mjs     # 完整部署示例
+│   ├── package.json          # 依赖配置
+│   └── README.md             # Node.js 示例文档
+├── browser/                   # 浏览器环境示例
+│   ├── simple-example.js     # 简化 JS 示例
+│   └── README.md             # Browser 示例文档（引用 test.tsx）
+└── README.md                 # 本文件
+```
+
+## 🚀 快速开始
+
+### Node.js 示例
+
+适用于命令行工具、服务器端脚本等场景。
+
+```bash
+# 进入 Node.js 示例目录
+cd nodejs/
+
+# 安装依赖
+npm install
+
+# 设置环境变量
+export BASE_URL="https://your-blocklet-url.com"
+export AUTH_TOKEN="your-auth-token"
+
+# 运行示例
+npm start
+```
+
+**特点**：
+- ✅ 完整的 CLI 体验
+- 🔐 Auth Token 认证
+- 🎨 彩色控制台输出
+- 🌐 自动打开支付页面
+- 🔄 支持恢复部署
+
+### Browser 示例
+
+适用于 Web 应用、管理面板等浏览器环境。
+
+```bash
+# 进入 Browser 示例目录
+cd examples/browser/
+
+# 查看 README.md 了解详细使用方法
+cat README.md
+```
+
+**两种集成方式：**
+- **完整示例** - `README.md` 中包含完整的 React 组件代码
+- **简化集成** - `simple-example.js` 中包含核心逻辑
+
+**特点**：
+- ✅ 现代化 Web UI
+- 🌐 浏览器原生支持
+- 📱 响应式设计
+- 📊 实时日志显示
+- 💾 本地存储持久化
+
+## 🔧 配置对比
+
+### Node.js 配置
+
+```javascript
+import { BrokerClient, STEPS } from '@blocklet/payment-broker-client';
+
+const client = new BrokerClient({
+  baseUrl: 'https://your-blocklet-url.com',
+  authToken: 'your-auth-token',          // 必需：认证令牌
+  paymentLinkKey: 'PAYMENT_LINK_ID',     // 可选：Payment Link 键名
+  timeout: 300000,
+  polling: {
+    interval: 3000,
+    maxAttempts: 100,
+    backoffStrategy: 'linear',
+  },
+});
+```
+
+### Browser 配置
+
+```javascript
+import { BrokerClient, STEPS } from '@blocklet/payment-broker-client/browser';
+
+const client = new BrokerClient({
+  baseUrl: 'https://your-blocklet-url.com',
+  api: yourApiInstance,                  // 必需：API 实例
+  paymentLinkKey: 'PAYMENT_LINK_ID',     // 可选：Payment Link 键名
+  timeout: 300000,
+  polling: {
+    interval: 3000,
+    maxAttempts: 100,
+    backoffStrategy: 'linear',
+  },
+});
+```
+
+## 📊 功能对比
+
+| 功能 | Node.js | Browser | 说明 |
+|------|---------|---------|------|
+| **认证方式** | Auth Token | Cookie/Session | Node.js 需要显式令牌，Browser 依赖登录状态 |
+| **HTTP 请求** | 内置 | 外部 API | Node.js 内置请求，Browser 需要传入 API 实例 |
+| **配置获取** | API 调用 | window.blocklet | 不同的配置来源 |
+| **支付页面** | 自动打开浏览器 | window.open | 都支持自动打开支付页面 |
+| **错误处理** | 控制台输出 | UI 显示 | 不同的错误展示方式 |
+| **数据持久化** | 文件/数据库 | localStorage | 不同的存储方式 |
+
+## 🎯 使用场景
+
+### Node.js 示例适用于：
+
+- 📟 **命令行工具**: CLI 部署脚本
+- 🤖 **自动化脚本**: CI/CD 流程
+- 🖥️ **服务器端应用**: 后端服务集成
+- 📦 **打包工具**: 构建时部署
+- 🔧 **开发工具**: 开发者工具集成
+
+### Browser 示例适用于：
+
+- 🌐 **Web 管理面板**: 管理员界面
+- 👤 **用户控制台**: 用户自助部署
+- 📱 **移动端 Web**: 响应式部署界面
+- 🔗 **嵌入式组件**: 集成到现有应用
+- 🎨 **自定义 UI**: 基于示例定制界面
+
+## 🔄 部署流程
+
+两个示例都遵循相同的部署流程：
+
+```
+1. 初始化 BrokerClient
+   ↓
+2. 调用 client.deploy()
+   ↓
+3. STEP1: 等待支付 → 支付成功
+   ↓
+4. STEP2: 开始安装 → 安装完成
+   ↓
+5. STEP3: 启动服务 → 服务完成
+   ↓
+6. STEP4: 获取地址 → 部署完成
+```
+
+## 🛠️ 自定义和扩展
+
+### 步骤回调自定义
+
+```javascript
+const hooks = {
+  [STEPS.PAYMENT_PENDING]: async ({ sessionId, paymentUrl, isResuming }) => {
+    // 自定义支付步骤处理
+    console.log('处理支付步骤...');
+    
+    // Node.js: 保存到文件
+    // Browser: 保存到 localStorage
+    
+    if (!isResuming) {
+      // 自定义打开支付页面的逻辑
+    }
+  },
+  
+  // 其他步骤回调...
+};
+```
+
+### 错误处理自定义
+
+```javascript
+const onError = (error, step) => {
+  // 自定义错误处理
+  console.error(`部署失败于 ${step}:`, error.message);
+  
+  // Node.js: 记录到日志文件
+  // Browser: 显示用户友好的错误消息
+  
+  if (error.recovery?.suggestions) {
+    error.recovery.suggestions.forEach(suggestion => {
+      // 显示恢复建议
+    });
+  }
+};
+```
+
+## 📚 API 参考
+
+### BrokerClient 方法
+
+```javascript
+// 部署方法
+await client.deploy({
+  cachedCheckoutId?: string,        // 缓存的会话 ID
+  cachedPaymentUrl?: string,        // 缓存的支付 URL
+  page_info: {                      // 页面信息（必需）
+    success_message: {
+      en: string,                   // 英文成功消息
+      zh: string,                   // 中文成功消息
+    },
+  },
+  hooks?: DeploymentHooks,          // 部署钩子
+  onError?: ErrorHandler,           // 错误处理
+});
+```
+
+### 步骤常量
+
+```javascript
+import { STEPS } from '@blocklet/payment-broker-client';
+
+STEPS.PAYMENT_PENDING         // 等待支付
+STEPS.PAYMENT_COMPLETED       // 支付完成
+STEPS.INSTALLATION_STARTING   // 开始安装
+STEPS.INSTALLATION_COMPLETED  // 安装完成
+STEPS.SERVICE_STARTING        // 启动服务
+STEPS.SERVICE_READY           // 服务就绪
+STEPS.ACCESS_PREPARING        // 准备访问权限
+STEPS.ACCESS_READY            // 访问就绪
+```
+
+## 🔍 故障排除
+
+### 常见问题
+
+1. **认证失败**
+   - Node.js: 检查 `AUTH_TOKEN` 环境变量
+   - Browser: 确保在已登录状态下运行
+
+2. **网络错误**
+   - 检查 `BASE_URL` 是否正确
+   - 验证网络连接和防火墙设置
+
+3. **Payment Link 错误**
+   - 确认 `paymentLinkKey` 对应的环境变量存在
+   - 检查 blocklet 配置
+
+4. **构建问题**
+   - 确保正确构建了 SDK
+   - 检查文件路径和导入语句
+
+### 调试技巧
+
+```javascript
+// 开启详细日志
+const client = new BrokerClient({
+  // ... 其他配置
+  logger: {
+    level: 'debug',
+    enabled: true,
+  },
+});
+
+// 捕获所有错误
+process.on('unhandledRejection', (error) => {
+  console.error('Unhandled rejection:', error);
+});
+```
+
+## 📖 更多资源
+
+- [Payment Kit Broker Client 主文档](../README.md)
+- [API 完整参考](../docs/api.md)
+- [类型定义](../src/core/types.ts)
+- [错误处理指南](../docs/error-handling.md)
+
+## 🤝 贡献
+
+欢迎提交示例改进和新的使用场景！请查看项目的贡献指南。

package/examples/browser/README.md

@@ -0,0 +1,119 @@
+# Payment Kit Broker Client - Browser Example
+
+这是一个使用 Payment Kit Broker Client 在浏览器环境中部署网站的完整示例。
+
+## 功能特性
+
+- ✅ 完整的部署流程演示
+- 🌐 浏览器原生支持（无需 Auth Token）
+- 🔄 支持恢复中断的部署
+- 🎨 现代化 UI 设计
+- 📱 响应式布局
+- 🔗 自动打开支付页面
+- ⚙️ 自定义 Payment Link Key
+- 📊 实时日志显示
+- 💾 本地存储持久化
+- 📈 详细的步骤回调和错误处理
+
+## 快速开始
+
+
+如果你只需要核心功能，可以参考 `simple-example.js` 文件中的简化代码。
+
+## 核心配置说明
+
+### 浏览器环境特点
+
+1. **无需 Auth Token** - 浏览器环境在已登录状态下运行
+2. **需要 API 实例** - 必须传入 `api` 对象处理 HTTP 请求
+3. **自动获取配置** - 从 `window.blocklet` 自动获取配置信息
+
+### 配置参数
+
+```javascript
+const client = new BrokerClient({
+  baseUrl: 'https://your-blocklet-url.com',  // 必需：Blocklet URL
+  api: yourApiInstance,                      // 必需：API 实例
+  paymentLinkKey: 'PAYMENT_LINK_ID',        // 可选：Payment Link 键名
+  timeout: 300000,                          // 可选：超时时间
+  polling: {                                // 可选：轮询配置
+    interval: 3000,
+    maxAttempts: 100,
+    backoffStrategy: 'linear',
+  },
+});
+```
+
+## 功能特性说明
+
+上面的完整示例包含了以下功能：
+
+- ✅ 完整的 UI 界面
+- 📊 实时日志显示  
+- 💾 localStorage 持久化
+- 🔄 恢复部署功能
+- 📱 响应式设计
+- 🎨 Material-UI 组件
+- 🔧 配置管理
+- 🧹 缓存清理功能
+
+这个示例是一个完全独立的组件，可以直接在任何 React 项目中使用。
+
+## API 实例配置
+
+浏览器环境需要传入 API 实例：
+
+```javascript
+// 方法1: 使用 @blocklet/payment-react 的 api
+import { api } from '@blocklet/payment-react';
+
+// 方法2: 使用自定义 axios 实例
+import axios from 'axios';
+const api = axios.create({
+  baseURL: getCurrentBaseUrl(),
+  headers: { 'Content-Type': 'application/json' },
+});
+
+// 方法3: 使用 fetch 包装
+const api = {
+  get: async (url) => fetch(url).then(r => r.json()),
+  post: async (url, data) => fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(data)
+  }).then(r => r.json())
+};
+```
+
+## 故障排除
+
+### 常见问题
+
+1. **导入错误**
+   ```bash
+   npm install @blocklet/payment-broker-client
+   ```
+
+2. **API 实例未配置**
+   ```javascript
+   // 确保传入正确的 API 实例
+   import { api } from '@blocklet/payment-react';
+   ```
+
+3. **window.blocklet 未定义**
+   ```javascript
+   // 确保在 blocklet 环境中运行
+   console.log(window.blocklet); // 应该有值
+   ```
+
+4. **支付页面无法打开**
+   ```javascript
+   // 检查浏览器弹窗拦截设置
+   window.open(paymentUrl, '_blank');
+   ```
+
+## 相关链接
+
+- [Payment Kit Broker Client 文档](../../README.md)
+- [Node.js 示例](../nodejs/README.md)
+- [API 参考](../../docs/api.md)

package/examples/browser/simple-example.js

@@ -0,0 +1,223 @@
+/**
+ * Simple Browser Example for Payment Kit Broker Client
+ * 
+ * This is a minimal example showing how to use the BrokerClient in a browser environment.
+ * For a complete UI example, see index.html
+ */
+
+// Import the BrokerClient (make sure to build and copy the browser version first)
+// import { BrokerClient, STEPS } from './broker-client-browser.js';
+
+// Example usage function
+async function deployWebsiteSimple(options = {}) {
+  const {
+    paymentLinkKey,
+    cachedCheckoutId,
+    cachedPaymentUrl,
+    api = createDefaultApi(),
+  } = options;
+
+  console.log('🚀 Starting simple browser deployment...');
+
+  // Create BrokerClient instance
+  const client = new BrokerClient({
+    baseUrl: getCurrentBaseUrl(),
+    paymentLinkKey: paymentLinkKey || undefined,
+    api: api,
+    timeout: 300000,
+    polling: {
+      interval: 3000,
+      maxAttempts: 100,
+      backoffStrategy: 'linear',
+    },
+  });
+
+  try {
+    const result = await client.deploy({
+      cachedCheckoutId: cachedCheckoutId || undefined,
+      cachedPaymentUrl: cachedPaymentUrl || undefined,
+      page_info: {
+        success_message: {
+          en: 'Congratulations! Your website has been successfully deployed.',
+          zh: '恭喜您，网站部署成功！',
+        },
+      },
+      hooks: {
+        [STEPS.PAYMENT_PENDING]: ({ sessionId, paymentUrl, linkId, isResuming }) => {
+          console.log('⏳ Step 1: Waiting for payment...');
+          console.log(`📋 Session ID: ${sessionId}`);
+          console.log(`🔗 Payment URL: ${paymentUrl}`);
+          
+          if (!isResuming && paymentUrl) {
+            console.log('🌐 Opening payment page...');
+            window.open(paymentUrl, '_blank');
+          }
+        },
+
+        [STEPS.PAYMENT_COMPLETED]: ({ sessionId, vendors }) => {
+          console.log('✅ Payment successful!');
+          console.log(`📦 Vendors: ${vendors.length}`);
+        },
+
+        [STEPS.INSTALLATION_STARTING]: ({ vendors }) => {
+          console.log('📦 Step 2: Installing services...');
+          console.log(`📊 Installing ${vendors.length} services`);
+        },
+
+        [STEPS.INSTALLATION_COMPLETED]: ({ progress }) => {
+          console.log(`✅ Installation complete (${progress || 100}%)`);
+        },
+
+        [STEPS.SERVICE_STARTING]: ({ vendors }) => {
+          console.log('🚀 Step 3: Starting services...');
+          console.log(`🔧 Starting ${vendors.length} services`);
+        },
+
+        [STEPS.SERVICE_READY]: () => {
+          console.log('✅ Services started successfully');
+        },
+
+        [STEPS.ACCESS_PREPARING]: () => {
+          console.log('🌐 Step 4: Getting access URLs...');
+        },
+
+        [STEPS.ACCESS_READY]: ({ appUrl, homeUrl, subscriptionUrl, dashboardUrl }) => {
+          console.log('🎉 Deployment completed!');
+          console.log(`🏠 Website: ${homeUrl || appUrl}`);
+          if (subscriptionUrl) console.log(`💳 Subscription: ${subscriptionUrl}`);
+          if (dashboardUrl) console.log(`📊 Dashboard: ${dashboardUrl}`);
+        },
+      },
+
+      onError: (error, step) => {
+        console.error(`❌ Deployment failed at ${step}:`, error.message);
+        if (error.recovery?.suggestions) {
+          error.recovery.suggestions.forEach(suggestion => {
+            console.log(`💡 Suggestion: ${suggestion}`);
+          });
+        }
+      },
+    });
+
+    console.log('🎊 Deployment successful:', result);
+    return result;
+
+  } catch (error) {
+    console.error('❌ Deployment failed:', error.message);
+    throw error;
+  }
+}
+
+// Helper function to get current base URL
+function getCurrentBaseUrl() {
+  return `${window.location.protocol}//${window.location.host}${window?.blocklet?.prefix || '/'}`;
+}
+
+// Default API implementation using fetch
+function createDefaultApi() {
+  const baseURL = getCurrentBaseUrl();
+  
+  return {
+    async get(url) {
+      const response = await fetch(`${baseURL}${url}`);
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      return response.json();
+    },
+
+    async post(url, data) {
+      const response = await fetch(`${baseURL}${url}`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(data),
+      });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      return response.json();
+    },
+  };
+}
+
+// Example usage scenarios
+
+// 1. Basic deployment
+function example1_BasicDeployment() {
+  return deployWebsiteSimple();
+}
+
+// 2. Resume deployment with cached session
+function example2_ResumeDeployment() {
+  return deployWebsiteSimple({
+    cachedCheckoutId: 'cs_your_session_id_here',
+    cachedPaymentUrl: 'https://your-payment-url-here',
+  });
+}
+
+// 3. Custom payment link key
+function example3_CustomPaymentLinkKey() {
+  return deployWebsiteSimple({
+    paymentLinkKey: 'CUSTOM_PAYMENT_LINK_ID',
+  });
+}
+
+// 4. Custom API instance
+function example4_CustomAPI() {
+  const customApi = {
+    async get(url) {
+      // Your custom GET implementation
+      console.log('Custom GET:', url);
+      return fetch(url).then(r => r.json());
+    },
+    async post(url, data) {
+      // Your custom POST implementation
+      console.log('Custom POST:', url, data);
+      return fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(data),
+      }).then(r => r.json());
+    },
+  };
+
+  return deployWebsiteSimple({
+    api: customApi,
+  });
+}
+
+// Export for use in other modules
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = {
+    deployWebsiteSimple,
+    getCurrentBaseUrl,
+    createDefaultApi,
+    example1_BasicDeployment,
+    example2_ResumeDeployment,
+    example3_CustomPaymentLinkKey,
+    example4_CustomAPI,
+  };
+}
+
+// Global access for browser console
+if (typeof window !== 'undefined') {
+  window.PaymentKitExamples = {
+    deployWebsiteSimple,
+    getCurrentBaseUrl,
+    createDefaultApi,
+    examples: {
+      basicDeployment: example1_BasicDeployment,
+      resumeDeployment: example2_ResumeDeployment,
+      customPaymentLinkKey: example3_CustomPaymentLinkKey,
+      customAPI: example4_CustomAPI,
+    },
+  };
+  
+  console.log('🎯 Payment Kit Examples loaded! Try:');
+  console.log('  PaymentKitExamples.examples.basicDeployment()');
+  console.log('  PaymentKitExamples.examples.resumeDeployment()');
+  console.log('  PaymentKitExamples.examples.customPaymentLinkKey()');
+  console.log('  PaymentKitExamples.examples.customAPI()');
+}