@quantabit/kyc-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuantaBit Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# @quantabit/kyc-sdk
+
+> QuantaBit KYC SDK - Identity verification, document upload, and compliance level management
+
+## 📦 Installation
+
+```bash
+npm install @quantabit/kyc-sdk
+# or
+yarn add @quantabit/kyc-sdk
+```
+
+## 🚀 Quick Start
+
+### API Client
+
+```javascript
+import { kycApi, KYCLevel, KYCStatus } from "@quantabit/kyc-sdk";
+
+// Get KYC status
+const status = await kycApi.getStatus();
+
+// Phone verification
+await kycApi.verifyPhone("+1234567890");
+
+// Email verification
+await kycApi.verifyEmail("user@example.com");
+
+// Upload identity document
+await kycApi.uploadDocument(documentFile);
+
+// Submit document for verification
+await kycApi.submitDocumentVerification({
+  documentType: "passport",
+  frontImage: frontFile,
+  backImage: backFile,
+});
+```
+
+## 📖 Type Definitions
+
+```javascript
+import { KYCLevel, KYCStatus, DocumentType, VerificationType } from "@quantabit/kyc-sdk";
+
+// KYC levels
+KYCLevel.NONE;      // Not verified
+KYCLevel.BASIC;     // Email/phone verified
+KYCLevel.STANDARD;  // Document verified
+KYCLevel.ADVANCED;  // Full KYC (video call)
+
+// KYC status
+KYCStatus.PENDING;  // Under review
+KYCStatus.APPROVED; // Approved
+KYCStatus.REJECTED; // Rejected
+KYCStatus.EXPIRED;  // Expired
+
+// Document types
+DocumentType.PASSPORT;       // Passport
+DocumentType.ID_CARD;        // National ID card
+DocumentType.DRIVERS_LICENSE; // Driver's license
+```
+
+## 🌐 Internationalization
+
+```javascript
+import { setLanguage, t } from "@quantabit/kyc-sdk";
+setLanguage("en");
+```
+
+## 📄 License
+
+MIT License
+
+
+
+---
+
+## 🌐 Brand & Links
+- Official Mainnet: [QuantaBit Chain](https://qbitchain.io/)
+- Developer Platform: [Developer Platform](https://developer.quantabit.io/)
+- Open Platform: [Open Platform](https://open.quantabit.io/)
+- Payment Platform: [Pay Platform](https://pay.qbitwallet.io/)
+- Feedback: [Feedback](https://xwin.live/qbit)

package/dist/index.cjs

@@ -0,0 +1,540 @@
+'use strict';
+
+var sdkConfig = require('@quantabit/sdk-config');
+
+/**
+ * Kyc SDK - API 客户端
+ * KYC 身份认证系统后端接口封装
+ * 
+ * 使用 BaseApiClient 基类简化代码
+ */
+
+
+/**
+ * KYC API 客户端
+ */
+class KycApiClient extends sdkConfig.BaseApiClient {
+  constructor(config = {}) {
+    super('/kyc', config);
+  }
+
+  // ============ 认证状态 ============
+
+  /**
+   * 获取认证状态
+   */
+  async getStatus() {
+    return this.get('/status');
+  }
+
+  /**
+   * 获取认证等级信息
+   */
+  async getLevelInfo() {
+    return this.get('/levels');
+  }
+
+  /**
+   * 获取当前认证等级
+   */
+  async getCurrentLevel() {
+    return this.get('/my/level');
+  }
+
+  // ============ 基础认证（Level 1）============
+
+  /**
+   * 提交基础信息
+   * @param {Object} data - 基础信息
+   */
+  async submitBasicInfo(data) {
+    return this.post('/basic', data);
+  }
+
+  /**
+   * 获取基础认证状态
+   */
+  async getBasicStatus() {
+    return this.get('/basic/status');
+  }
+
+  /**
+   * 验证手机号
+   * @param {string} phone - 手机号
+   * @param {string} code - 验证码
+   */
+  async verifyPhone(phone, code) {
+    return this.post('/phone/verify', {
+      phone,
+      code
+    });
+  }
+
+  /**
+   * 验证邮箱
+   * @param {string} email - 邮箱
+   * @param {string} code - 验证码
+   */
+  async verifyEmail(email, code) {
+    return this.post('/email/verify', {
+      email,
+      code
+    });
+  }
+
+  // ============ 身份认证（Level 2）============
+
+  /**
+   * 提交身份证件
+   * @param {Object} data - 证件信息
+   */
+  async submitIdDocument(data) {
+    return this.post('/identity', data);
+  }
+
+  /**
+   * 提交证件认证（兼容快捷导出命名）
+   * @param {Object} data - 证件认证数据
+   */
+  async submitDocumentVerification(data) {
+    return this.submitIdDocument(data);
+  }
+
+  /**
+   * 上传证件照片
+   * @param {string} type - 照片类型（front, back, selfie）
+   * @param {File} file - 图片文件
+   */
+  async uploadIdPhoto(type, file) {
+    const formData = new FormData();
+    formData.append('type', type);
+    formData.append('file', file);
+    const token = this.getToken();
+    const response = await fetch(`${this.baseUrl}/identity/upload`, {
+      method: 'POST',
+      headers: {
+        'Authorization': token ? `Bearer ${token}` : ''
+      },
+      body: formData
+    });
+    return response.json();
+  }
+
+  /**
+   * 获取身份认证状态
+   */
+  async getIdentityStatus() {
+    return this.get('/identity/status');
+  }
+
+  // ============ 人脸识别 ============
+
+  /**
+   * 获取人脸识别 Token
+   */
+  async getFaceToken() {
+    return this.post('/face/token');
+  }
+
+  /**
+   * 提交人脸识别结果
+   * @param {string} token - 人脸识别 Token
+   * @param {Object} result - 识别结果
+   */
+  async submitFaceResult(token, result) {
+    return this.post('/face/verify', {
+      token,
+      result
+    });
+  }
+
+  /**
+   * 获取人脸识别状态
+   */
+  async getFaceStatus() {
+    return this.get('/face/status');
+  }
+
+  // ============ 高级认证（Level 3）============
+
+  /**
+   * 提交高级认证信息
+   * @param {Object} data - 高级认证数据
+   */
+  async submitAdvancedInfo(data) {
+    return this.post('/advanced', data);
+  }
+
+  /**
+   * 上传补充材料
+   * @param {string} type - 材料类型
+   * @param {File} file - 文件
+   */
+  async uploadDocument(type, file) {
+    const formData = new FormData();
+    formData.append('type', type);
+    formData.append('file', file);
+    const token = this.getToken();
+    const response = await fetch(`${this.baseUrl}/advanced/upload`, {
+      method: 'POST',
+      headers: {
+        'Authorization': token ? `Bearer ${token}` : ''
+      },
+      body: formData
+    });
+    return response.json();
+  }
+
+  /**
+   * 获取高级认证状态
+   */
+  async getAdvancedStatus() {
+    return this.get('/advanced/status');
+  }
+
+  // ============ 认证记录 ============
+
+  /**
+   * 获取认证历史
+   * @param {Object} params - 查询参数
+   */
+  async getHistory(params = {}) {
+    return this.get('/history', params);
+  }
+
+  /**
+   * 重新提交认证
+   * @param {string} level - 认证等级
+   */
+  async resubmit(level) {
+    return this.post('/resubmit', {
+      level
+    });
+  }
+
+  // ============ 管理员操作 ============
+
+  /**
+   * 获取待审核列表（管理员）
+   * @param {Object} params - 查询参数
+   */
+  async getPendingReviews(params = {}) {
+    return this.get('/admin/pending', params);
+  }
+
+  /**
+   * 审核认证（管理员）
+   * @param {string} userId - 用户 ID
+   * @param {string} level - 认证等级
+   * @param {Object} decision - 审核决定
+   */
+  async review(userId, level, decision) {
+    return this.post('/admin/review', {
+      user_id: userId,
+      level,
+      ...decision
+    });
+  }
+
+  // ============ 隐私合规 (GDPR 特殊类别数据) ============
+
+  /**
+   * 请求删除身份认证数据 — GDPR 第17条
+   * 向服务端提交身份数据删除请求
+   * 注意: 受 AML/KYC 法规限制，某些数据可能需要保留法定期限
+   * @param {string} reason - 删除原因
+   * @returns {Promise<object>} 删除请求结果
+   */
+  async requestDataDeletion(reason = '') {
+    return this.post('/gdpr/delete', {
+      reason
+    });
+  }
+
+  /**
+   * 导出身份认证数据 — GDPR 第20条
+   * 返回脱敏后的身份认证信息（证件号部分遮蔽）
+   * @returns {Promise<object>} 脱敏后的身份数据
+   */
+  async exportKycData() {
+    try {
+      const status = await this.getStatus();
+      const history = await this.getHistory({
+        page_size: 50
+      });
+      return {
+        exportDate: new Date().toISOString(),
+        format: 'QBit KYC Export (GDPR Art. 20)',
+        note: 'ID numbers are partially masked for security',
+        currentLevel: status?.data?.level || 'none',
+        verificationStatus: status?.data?.status || 'unknown',
+        history: history?.data?.items?.map(item => ({
+          ...item,
+          // 证件号脱敏
+          id_number: item.id_number ? `${item.id_number.slice(0, 4)}****${item.id_number.slice(-4)}` : undefined,
+          // 移除证件照片 URL（敏感生物数据）
+          photo_url: undefined,
+          selfie_url: undefined
+        })) || []
+      };
+    } catch (e) {
+      return {
+        error: e.message,
+        exportDate: new Date().toISOString()
+      };
+    }
+  }
+
+  /**
+   * 获取隐私数据声明
+   */
+  getDataDisclosure() {
+    return {
+      sdk: '@quantabit/kyc-sdk',
+      privacyLevel: 'functional',
+      consentRequired: true,
+      specialCategory: true,
+      collected: [{
+        type: 'identity_documents',
+        description: 'Government-issued ID (front/back)',
+        retention: '5 years (AML regulation)',
+        encrypted: true
+      }, {
+        type: 'biometric_data',
+        description: 'Facial recognition data',
+        retention: 'Until verification complete',
+        encrypted: true
+      }, {
+        type: 'personal_info',
+        description: 'Name, DOB, nationality',
+        retention: '5 years (AML regulation)'
+      }, {
+        type: 'address_proof',
+        description: 'Proof of address documents',
+        retention: '5 years'
+      }],
+      compliance: ['GDPR Art. 9 (Special categories)', 'AML 5th Directive', 'KYC/CDD'],
+      gdprCapabilities: ['export', 'delete-request'],
+      legalBasis: 'Legal obligation (AML) + Explicit consent (biometric)',
+      note: 'Biometric data is processed with explicit consent and deleted after verification. AML-required data has a 5-year legal retention period.'
+    };
+  }
+}
+
+// 创建默认实例
+const kycApi = new KycApiClient();
+const KYCApiClient = KycApiClient;
+
+/**
+ * KYC SDK - 国际化
+ */
+
+const SUPPORTED_LANGUAGES = ['en', 'zh', 'ja', 'ko'];
+const messages = {
+  zh: {
+    title: '实名认证',
+    level0: '未认证',
+    level1: '基础认证',
+    level2: '标准认证',
+    level3: '高级认证',
+    level4: '尊享认证',
+    statusNotStarted: '未开始',
+    statusPending: '待审核',
+    statusReviewing: '审核中',
+    statusApproved: '已通过',
+    statusRejected: '已拒绝',
+    statusExpired: '已过期',
+    idCard: '身份证',
+    passport: '护照',
+    driverLicense: '驾驶证',
+    uploadFront: '上传证件正面',
+    uploadBack: '上传证件背面',
+    uploadSelfie: '上传手持证件照',
+    startLiveness: '开始活体检测',
+    nameLabel: '姓名',
+    idNumberLabel: '证件号码',
+    countryLabel: '国家/地区',
+    addressLabel: '地址',
+    submitVerification: '提交认证',
+    processing: '处理中...',
+    verificationSuccess: '认证成功',
+    verificationFailed: '认证失败',
+    tips: '请确保照片清晰、完整，证件在有效期内',
+    privacyNotice: '您的信息将被安全加密存储，仅用于身份验证'
+  },
+  ja: {
+    title: '実名認証',
+    level0: '未認証',
+    level1: '基本認証',
+    level2: '標準認証',
+    level3: '高級認証',
+    level4: 'プレミアム認証',
+    statusNotStarted: '未開始',
+    statusPending: '審査待ち',
+    statusReviewing: '審査中',
+    statusApproved: '承認済み',
+    statusRejected: '拒否されました',
+    statusExpired: '期限切れ',
+    idCard: '身分証明書',
+    passport: 'パスポート',
+    driverLicense: '運転免許証',
+    uploadFront: '身分証の表面をアップロード',
+    uploadBack: '身分証の裏面をアップロード',
+    uploadSelfie: '身分証を持った写真をアップロード',
+    startLiveness: '生体認証を開始',
+    nameLabel: '氏名',
+    idNumberLabel: '身分証番号',
+    countryLabel: '国/地域',
+    addressLabel: '住所',
+    submitVerification: '認証を提出',
+    processing: '処理中...',
+    verificationSuccess: '認証成功',
+    verificationFailed: '認証失敗',
+    tips: '写真が鮮明で完全であること、身分証が有効期限内であることを確認してください',
+    privacyNotice: 'あなたの情報は安全に暗号化され、本人確認のみに使用されます'
+  },
+  ko: {
+    title: '실명 인증',
+    level0: '미인증',
+    level1: '기본 인증',
+    level2: '표준 인증',
+    level3: '고급 인증',
+    level4: '프리미엄 인증',
+    statusNotStarted: '시작되지 않음',
+    statusPending: '심사 대기 중',
+    statusReviewing: '심사 중',
+    statusApproved: '승인됨',
+    statusRejected: '거부됨',
+    statusExpired: '만료됨',
+    idCard: '신분증',
+    passport: '여권',
+    driverLicense: '운전면허증',
+    uploadFront: '신분증 앞면 업로드',
+    uploadBack: '신분증 뒷면 업로드',
+    uploadSelfie: '신분증을 든 사진 업로드',
+    startLiveness: '생체 인증 시작',
+    nameLabel: '성명',
+    idNumberLabel: '신분증 번호',
+    countryLabel: '국가/지역',
+    addressLabel: '주소',
+    submitVerification: '인증 제출',
+    processing: '처리 중...',
+    verificationSuccess: '인증 성공',
+    verificationFailed: '인증 실패',
+    tips: '사진이 선명하고 완전하며 신분증이 유효 기간 내에 있는지 확인하세요',
+    privacyNotice: '귀하의 정보는 안전하게 암호화되어 본인 확인 용도로만 사용됩니다'
+  },
+  en: {
+    title: 'Identity Verification',
+    level0: 'Not Verified',
+    level1: 'Basic Verified',
+    level2: 'Standard Verified',
+    level3: 'Advanced Verified',
+    level4: 'Premium Verified',
+    statusNotStarted: 'Not Started',
+    statusPending: 'Pending',
+    statusReviewing: 'Under Review',
+    statusApproved: 'Approved',
+    statusRejected: 'Rejected',
+    statusExpired: 'Expired',
+    idCard: 'ID Card',
+    passport: 'Passport',
+    driverLicense: 'Driver License',
+    uploadFront: 'Upload Front Side',
+    uploadBack: 'Upload Back Side',
+    uploadSelfie: 'Upload Selfie with ID',
+    startLiveness: 'Start Liveness Check',
+    nameLabel: 'Full Name',
+    idNumberLabel: 'ID Number',
+    countryLabel: 'Country/Region',
+    addressLabel: 'Address',
+    submitVerification: 'Submit Verification',
+    processing: 'Processing...',
+    verificationSuccess: 'Verification Successful',
+    verificationFailed: 'Verification Failed',
+    tips: 'Please ensure photos are clear and complete, and documents are valid',
+    privacyNotice: 'Your information will be securely encrypted and used only for identity verification'
+  }
+};
+let currentLanguage = 'zh';
+function setLanguage(lang) {
+  if (SUPPORTED_LANGUAGES.includes(lang)) currentLanguage = lang;
+}
+function getLanguage() {
+  return currentLanguage;
+}
+function t(key) {
+  return (messages[currentLanguage] || messages.en)[key] || key;
+}
+
+/**
+ * KYC SDK - 类型定义
+ */
+
+// 认证级别
+const KYCLevel = {
+  NONE: 0,
+  BASIC: 1,
+  // 手机/邮箱验证
+  STANDARD: 2,
+  // 身份证验证
+  ADVANCED: 3,
+  // 视频活体验证
+  PREMIUM: 4 // 高级认证
+};
+
+// 认证状态
+const KYCStatus = {
+  NOT_STARTED: 'not_started',
+  PENDING: 'pending',
+  REVIEWING: 'reviewing',
+  APPROVED: 'approved',
+  REJECTED: 'rejected',
+  EXPIRED: 'expired'
+};
+
+// 证件类型
+const DocumentType = {
+  ID_CARD: 'id_card',
+  PASSPORT: 'passport',
+  DRIVER_LICENSE: 'driver_license',
+  RESIDENCE_PERMIT: 'residence_permit'
+};
+
+// 验证类型
+const VerificationType = {
+  PHONE: 'phone',
+  EMAIL: 'email',
+  DOCUMENT: 'document',
+  LIVENESS: 'liveness',
+  ADDRESS: 'address'
+};
+
+/**
+ * @quantabit/kyc-sdk
+ * KYC SDK
+ */
+
+const getStatus = (...args) => kycApi.getStatus(...args);
+const verifyPhone = (...args) => kycApi.verifyPhone(...args);
+const verifyEmail = (...args) => kycApi.verifyEmail(...args);
+const uploadDocument = (...args) => kycApi.uploadDocument(...args);
+const submitDocumentVerification = (...args) => kycApi.submitDocumentVerification(...args);
+
+exports.DocumentType = DocumentType;
+exports.KYCApiClient = KYCApiClient;
+exports.KYCLevel = KYCLevel;
+exports.KYCStatus = KYCStatus;
+exports.SUPPORTED_LANGUAGES = SUPPORTED_LANGUAGES;
+exports.VerificationType = VerificationType;
+exports.getLanguage = getLanguage;
+exports.getStatus = getStatus;
+exports.kycApi = kycApi;
+exports.messages = messages;
+exports.setLanguage = setLanguage;
+exports.submitDocumentVerification = submitDocumentVerification;
+exports.t = t;
+exports.uploadDocument = uploadDocument;
+exports.verifyEmail = verifyEmail;
+exports.verifyPhone = verifyPhone;
+//# sourceMappingURL=index.cjs.map