hm-tracking-sdk 0.1.4 → 0.1.5

package/README.md

@@ -1,317 +1,354 @@
-# HM Tracking SDK 使用文档
-
-本文档详细介绍如何使用 HM Tracking SDK，包括初始化、广告业务和支付业务的完整流程。
-
-## 1. 安装
-
-### 建议通过 npm/yarn 安装正式发布的包：
-
-  ```bash
-  # 使用 yarn
-  yarn add hm-tracking-sdk axios crypto-js
-
-  # 或使用 npm
-  npm i hm-tracking-sdk axios crypto-js
-  ```
-
----
-
-## 2. SDK 初始化
-
-- 接口: init()
-
-  ```ts
-  import { HmTrackingSDK, type SDKInitOptions } from "hm-tracking-sdk";
-
-  const options: SDKInitOptions = {
-    // 可选：不传则使用内置默认地址
-    baseURL: "https://your-api.example.com",
-
-    // 可选：本地存储 Key 前缀，避免项目间冲突
-    storageKeyPrefix: "your_app_prefix",
-
-    // 可选：浏览器环境下使用，可显式传入自定义用户
-    customUser: {
-      user: {
-        id: 123456789,
-        firstName: "Test",
-        lastName: "User",
-        username: "test_user",
-        languageCode: "zh-hans",
-      },
-      authDate: new Date().toISOString(),
-      hash: "your_hash_value",
-    },
-  };
-
-  const sdk = new HmTrackingSDK(options);
-  await sdk.init();
-  ```
-
-- 函数说明：初始化 SDK，先创建 HmTrackingSDK 对象，然后调用 init 方法完成初始化。
-- 参数说明: `SDKInitOptions` 初始化SDK时的可选参数，数据结构及内部结构说明为：
-  
-  ```ts
-    export interface SDKInitOptions {
-      /** 自定义接口地址（可选）。不传则使用默认正式环境 */
-      baseURL?: string;
-       /** 本地存储 Key 前缀，避免冲突 */
-      storageKeyPrefix?: string;
-      /** 自定义用户信息（可选） */
-      customUser?: TelegramUserInfo;
-    }
-  ```
-
-  - baseURL（可选）
-    - 说明：后端服务地址；不传则使用 SDK 内置默认地址。
-    - 类型：`string`
-  - storageKeyPrefix（可选）
-    - 说明：本地缓存命名空间前缀；用于隔离不同项目的存储键。
-    - 类型：`string`
-  - customUser（可选）
-    - 说明：自定义用户数据，仅在非 Telegram 环境可用；若不传，SDK 会自动使用“匿名浏览器用户”（基于 Cookie 生成并持久化随机 userId），从而可以直接完成鉴权与后续请求。
-    - 类型：`TelegramUserInfo`
-- 返回值：`Promise<void>`。
-
-### 2.1 环境
-
-- Telegram 环境
-  - SDK 自动读取当前Telegram用户的信息。
-  - 无需传入 `customUser`；若 Telegram 用户读取失败，SDK 会抛错提示。
-- 浏览器环境（非 Telegram）
-  - 默认行为：若未传 `customUser`，SDK 会使用“匿名浏览器用户”：
-    - 首次访问生成随机 `userId`，存入 Cookie（如 `tg_tracking_uid`），后续复用。
-    - 便于无登录状态下完成鉴权，拿到 token 后再进行广告或调试。
-  - 自定义用户：也可传入 `customUser` 替代匿名用户。
-
-### 2.2 环境判断
-
-- 接口: isTelegramEnv()
-
-  ```ts
-  import { isTelegramEnv } from "hm-tracking-sdk";
-
-  if (isTelegramEnv()) {
-    // Telegram WebApp 环境
-  } else {
-    // 浏览器/其他环境
-  }
-  ```
-
-  - 函数说明：判断是否是Telegram环境。
-  - 返回值：`boolean`。
-
----
-
-## 3. 获取Telegram用户信息
-
-- 接口: getTelegramUserUnsafe()
-
-  ```ts
-  import { getTelegramUserUnsafe, type TelegramUserInfo } from "hm-tracking-sdk";
-
-  const user: TelegramUserInfo | null = getTelegramUserUnsafe();
-  ```
-
-  - 函数说明：在 Telegram 环境下返回 `TelegramUserInfo`；获取失败返回 `null`。
-  - 返回值：`TelegramUserInfo | null`，数据结构为：
-    
-    ```ts
-    export interface TelegramUserInfo {
-      id?: number;
-      first_name?: string;
-      last_name?: string;
-      username?: string;
-      language_code?: string;
-      allows_write_to_pm?: boolean;
-      auth_date?: number;
-      hash?: string;
-      [key: string]: unknown;
-    }
-    ```
-
-- 环境要求：仅 Telegram WebApp 可用；在浏览器环境（非 Telegram）将返回 `null`。
-
----
-
-## 4. 广告业务
-
-### 4.1 展示广告
-
-- 接口: showHmAdByPosition()
-
-  ```ts
-  await sdk.showHmAdByPosition(adPositionName);
-  ```
-
-- 函数说明：根据广告位名称展示广告。
-- 参数说明
-  - adPositionName（必填）
-    - 说明：广告位名称，需要根据业务进行申请，具体请联系SDK开发者，使用示例值进行测试。
-    - 类型：`string`
-    - 示例值：
-      - `game_rewarded_ad_position`
-- 返回值：`Promise<void>`。
-
-说明：SDK 会根据根据广告位名称获取相关广告配置并完成展示。
-
----
-
-## 5. 支付业务
-
-支付仅支持在 Telegram WebApp 内使用。
-
-### 5.1 TON钱包相关API
-
-#### 5.1.1 钱包是否链接
-
-- 接口: isWalletConnected()
-
-  ```ts
-  sdk.isWalletConnected(): boolean
-  ```
-
-- 函数说明：同步检查是否已连接 TON 钱包；
-- 返回值：`boolean`。
-
-#### 5.1.2 链接钱包
-
-- 接口: connectWallet()
-
-  ```ts
-  sdk.connectWallet(): Promise<boolean>
-  ```
-
-- 函数说明：发起连接 TON 钱包；
-- 返回值：`Promise<boolean>` 表示是否连接成功。
-
-#### 5.1.3 断开钱包链接
-
-- 接口: disconnectWallet()
-
-  ```ts
-  sdk.disconnectWallet(): Promise<void>
-  ```
-
-- 函数说明：断开已连接的钱包；
-- 返回值：`Promise<void>`。
-
-### 5.2 支付
-
-#### 5.2.1 获取支持的支付方式
-
-- 接口: getSupportedPayModes()
-
-  ```ts
-  sdk.getSupportedPayModes(): Promise<MerchantPayModeListData>
-  ```
-
-- 函数说明：获取当前支持的币种及汇率配置；
-- 返回值说明：`Promise<MerchantPayModeListData>`，见下方类型定义。
-
-  ```ts
-  interface MerchantPayModeListData {
-    payModeList: MerchantPayModeItem[];
-  }
-
-  interface MerchantPayModeItem {
-    id: number;
-    title: string;
-    name: string;   // 币种: 'USDT' | 'TON' | 'STARS'
-    rate: number;   // 汇率
-    nameDesc: string;
-  }
-  ```
-
-#### 5.2.2 创建并支付订单
-
-- 接口: payByMerchant()
-
-  ```ts
-  // 仅 TON/USDT 需要先连接钱包（STARS 无需）
-  await sdk.ensureWalletConnected();
-
-  // 创建并支付订单
-  const params: MerchantPayCreateRequest = {
-    currencyName: "TON",          // "TON" | "USDT" | "STARS"
-    amount: 10.5,                  // 支付金额
-    outTradeNo: `order_${Date.now()}`, // 自定义订单号
-    notifyUrl: "https://your-server.com/payment-callback",
-    attach: JSON.stringify({ userId: "123", itemId: "456" })
-  };
-  const result: MerchantPayFinishResponseData = await sdk.payByMerchant(params);
-  ```
-
-- 函数说明：创建支付订单并根据币种发起支付流程（STARS、TON/USDT 链上交易）；
-
-- 参数说明：
-  
-  ```ts
-  interface MerchantPayCreateRequest {
-    currencyName: string; // "USDT" | "TON" | "STARS"
-    amount: number;      // 支付金额
-    outTradeNo: string;  // 商户订单号
-    notifyUrl: string;   // 服务端支付回调地址
-    attach: string;      // 附加信息，通常使用 JSON.stringify
-  }
-  ```
-
-- 返回值数据结构：
-  
-  ```ts
-  export interface MerchantPayOrderBase {
-    orderSn: string;
-    transactionSn: string;
-    outTradeNo: string;
-    price: number | string;
-    count: number;
-    totalPrice: number | string;
-    currencyId: number;
-    currencyName: string;
-    currencyRate: number;
-    currencyAmount: number | string;
-    payUrl: string | null;
-    payExpireDatetime: string;
-    payDatetime: string | null;
-    finishDatetime: string | null;
-    description: string;
-    status: number;
-    statusDesc: string;
-    closeCode: string | null;
-    closeCodeDesc: string | null;
-    createDatetime: string;
-    updateDatetime: string;
-    transferHash: string | null;
-    transactionHash: string | null;
-    transactionLt: string | null;
-  }
-  ```
-
-  ```ts
-  // 支付完成回调返回的订单结果
-  type MerchantPayFinishResponseData = MerchantPayOrderBase;
-  ```
-
-#### 5.2.3 查询支付结果
-
-- 接口: merchantPayQueryResult()
-
-  ```ts
-  sdk.merchantPayQueryResult(data: MerchantPayQueryResultRequest): Promise<MerchantPayQueryResultResponseData>
-  ```
-
-- 函数说明：通过系统订单号 `orderSn` 或商户订单号 `outTradeNo` 查询订单最新结果；
-- 参数说明：`MerchantPayQueryResultRequest`，见下方类型:
-  
-   ```ts
-  interface MerchantPayQueryResultRequest {
-    orderSn?: string;
-    outTradeNo?: string;
-  }
-  ```
-
-- 返回值说明：`Promise<MerchantPayQueryResultResponseData>`，同 `MerchantPayOrderBase`。
-
-  ```ts
-  type MerchantPayQueryResultResponseData = MerchantPayOrderBase;
-  ```
+# HM Tracking SDK 使用文档
+
+本文档详细介绍如何使用 HM Tracking SDK，包括初始化、广告业务和支付业务的完整流程。
+
+## 1. 安装
+
+### 建议通过 npm/yarn 安装正式发布的包：
+
+  ```bash
+  # 使用 yarn
+  yarn add hm-tracking-sdk axios crypto-js
+
+  # 或使用 npm
+  npm i hm-tracking-sdk axios crypto-js
+  ```
+
+---
+
+## 2. SDK 初始化
+
+- 接口: init()
+
+  ```ts
+  import { HmTrackingSDK, type SDKInitOptions } from "hm-tracking-sdk";
+
+  const options: SDKInitOptions = {
+    // 可选：不传则使用内置默认地址
+    baseURL: "https://your-api.example.com",
+
+    // 可选：本地存储 Key 前缀，避免项目间冲突
+    storageKeyPrefix: "your_app_prefix",
+
+    // 可选：浏览器环境下使用，可显式传入自定义用户
+    customUser: {
+      user: {
+        id: 123456789,
+        firstName: "Test",
+        lastName: "User",
+        username: "test_user",
+        languageCode: "zh-hans",
+      },
+      authDate: new Date().toISOString(),
+      hash: "your_hash_value",
+    },
+  };
+
+  const sdk = new HmTrackingSDK(options);
+  await sdk.init();
+  ```
+
+- 函数说明：初始化 SDK，先创建 HmTrackingSDK 对象，然后调用 init 方法完成初始化。
+- 参数说明: `SDKInitOptions` 初始化SDK时的可选参数，数据结构及内部结构说明为：
+  
+  ```ts
+    export interface SDKInitOptions {
+      /** 自定义接口地址（可选）。不传则使用默认正式环境 */
+      baseURL?: string;
+       /** 本地存储 Key 前缀，避免冲突 */
+      storageKeyPrefix?: string;
+      /** 自定义用户信息（可选） */
+      customUser?: TelegramUserInfo;
+    }
+  ```
+
+  - baseURL（可选）
+    - 说明：后端服务地址；不传则使用 SDK 内置默认地址。
+    - 类型：`string`
+  - storageKeyPrefix（可选）
+    - 说明：本地缓存命名空间前缀；用于隔离不同项目的存储键。
+    - 类型：`string`
+  - customUser（可选）
+    - 说明：自定义用户数据，仅在非 Telegram 环境可用；若不传，SDK 会自动使用“匿名浏览器用户”（基于 Cookie 生成并持久化随机 userId），从而可以直接完成鉴权与后续请求。
+    - 类型：`TelegramUserInfo`
+- 返回值：`Promise<void>`。
+
+### 2.1 环境
+
+- Telegram 环境
+  - SDK 自动读取当前Telegram用户的信息。
+  - 无需传入 `customUser`；若 Telegram 用户读取失败，SDK 会抛错提示。
+- 浏览器环境（非 Telegram）
+  - 默认行为：若未传 `customUser`，SDK 会使用“匿名浏览器用户”：
+    - 首次访问生成随机 `userId`，存入 Cookie（如 `tg_tracking_uid`），后续复用。
+    - 便于无登录状态下完成鉴权，拿到 token 后再进行广告或调试。
+  - 自定义用户：也可传入 `customUser` 替代匿名用户。
+
+### 2.2 环境判断
+
+- 接口: isTelegramEnv()
+
+  ```ts
+  import { isTelegramEnv } from "hm-tracking-sdk";
+
+  if (isTelegramEnv()) {
+    // Telegram WebApp 环境
+  } else {
+    // 浏览器/其他环境
+  }
+  ```
+
+  - 函数说明：判断是否是Telegram环境。
+  - 返回值：`boolean`。
+
+---
+
+## 3. 获取Telegram用户信息
+
+- 接口: getTelegramUserUnsafe()
+
+  ```ts
+  import { getTelegramUserUnsafe, type TelegramUserInfo } from "hm-tracking-sdk";
+
+  const user: TelegramUserInfo | null = getTelegramUserUnsafe();
+  ```
+
+  - 函数说明：在 Telegram 环境下返回 `TelegramUserInfo`；获取失败返回 `null`。
+  - 返回值：`TelegramUserInfo | null`，数据结构为：
+    
+    ```ts
+    export interface TelegramUserInfo {
+      id?: number;
+      first_name?: string;
+      last_name?: string;
+      username?: string;
+      language_code?: string;
+      allows_write_to_pm?: boolean;
+      auth_date?: number;
+      hash?: string;
+      [key: string]: unknown;
+    }
+    ```
+
+- 环境要求：仅 Telegram WebApp 可用；在浏览器环境（非 Telegram）将返回 `null`。
+
+---
+
+## 4. 广告业务
+
+### 4.1 展示广告
+
+- 接口: showHmAdByPosition()
+
+  ```ts
+  await sdk.showHmAdByPosition(adPositionName, {
+    onSuccess: (result) => {
+      console.log("广告观看完成", result);
+    },
+    onError: (error) => {
+      console.error("广告展示失败:", error);
+    },
+  });
+  ```
+
+- 函数说明：根据广告位名称展示广告。
+- 参数说明
+  - adPositionName（必填）
+    - 说明：广告位名称，需要根据业务进行申请，具体请联系SDK开发者，使用示例值进行测试。
+    - 类型：`string`
+    - 示例值：
+      - `game_rewarded_ad_position`
+  - callbacks
+    - 说明：广告展示成功/失败的回调。
+    - 类型：
+  
+      ```ts
+      interface AdCallbacks {
+        onSuccess?: (result?: unknown) => void | Promise<void>;
+        onError?: (error: unknown) => void | Promise<void>;
+      }
+      ```
+      
+- 返回值：`Promise<void>`。失败时抛出异常；如提供 `callbacks`，会触发 `onError`。
+  
+  说明：SDK 会根据根据广告位名称获取相关广告配置并完成展示。
+
+---
+
+## 5. 支付业务
+
+支付仅支持在 Telegram WebApp 内使用。
+
+### 5.1 TON钱包相关API
+
+#### 5.1.1 钱包是否链接
+
+- 接口: isWalletConnected()
+
+  ```ts
+  sdk.isWalletConnected(): boolean
+  ```
+
+- 函数说明：同步检查是否已连接 TON 钱包；
+- 返回值：`boolean`。
+
+#### 5.1.2 链接钱包
+
+- 接口: connectWallet()
+
+  ```ts
+  sdk.connectWallet(): Promise<boolean>
+  ```
+
+- 函数说明：发起连接 TON 钱包；
+- 返回值：`Promise<boolean>` 表示是否连接成功。
+
+#### 5.1.3 断开钱包链接
+
+- 接口: disconnectWallet()
+
+  ```ts
+  sdk.disconnectWallet(): Promise<boolean>
+  ```
+
+- 函数说明：断开已连接的钱包；
+- 返回值：`Promise<boolean>`，true 表示已断开或原本未连接；false 表示断开失败。
+
+### 5.2 支付
+
+#### 5.2.1 获取支持的支付方式
+
+- 接口: getSupportedPayModes()
+
+  ```ts
+  sdk.getSupportedPayModes(): Promise<MerchantPayModeListData>
+  ```
+
+- 函数说明：获取当前支持的币种及汇率配置；
+- 返回值说明：`Promise<MerchantPayModeListData>`，见下方类型定义。
+
+  ```ts
+  interface MerchantPayModeListData {
+    payModeList: MerchantPayModeItem[];
+  }
+
+  interface MerchantPayModeItem {
+    id: number;
+    title: string;
+    name: string;   // 币种: 'USDT' | 'TON' | 'STARS'
+    rate: number;   // 汇率
+    nameDesc: string;
+  }
+  ```
+
+#### 5.2.2 创建并支付订单
+
+- 接口: payByMerchant()
+
+  ```ts
+
+  // 创建并支付订单
+  const params: MerchantPayCreateRequest = {
+    currencyName: "TON",          // "TON" | "USDT" | "STARS"
+    amount: 10.5,                  // 支付金额
+    outTradeNo: `order_${Date.now()}`, // 自定义订单号
+    notifyUrl: "https://your-server.com/payment-callback",
+    attach: JSON.stringify({ userId: "123", itemId: "456" })
+  };
+  const result: MerchantPayFinishResponseData = await sdk.payByMerchant(params);
+  ```
+
+- 函数说明：创建支付订单并根据币种发起支付流程（STARS、TON/USDT 链上交易）；
+
+- 参数说明：
+  
+  ```ts
+  interface MerchantPayCreateRequest {
+    currencyName: string; // "USDT" | "TON" | "STARS"
+    amount: number;      // 支付金额
+    outTradeNo: string;  // 商户订单号
+    notifyUrl: string;   // 服务端支付回调地址
+    attach: string;      // 附加信息，通常使用 JSON.stringify
+  }
+  ```
+
+- 返回值数据结构：
+  
+  ```ts
+  export interface MerchantPayOrderBase {
+    orderSn: string;
+    transactionSn: string;
+    outTradeNo: string;
+    price: number | string;
+    count: number;
+    totalPrice: number | string;
+    currencyId: number;
+    currencyName: string;
+    currencyRate: number;
+    currencyAmount: number | string;
+    payUrl: string | null;
+    payExpireDatetime: string;
+    payDatetime: string | null;
+    finishDatetime: string | null;
+    description: string;
+    status: number;
+    statusDesc: string;
+    closeCode: string | null;
+    closeCodeDesc: string | null;
+    createDatetime: string;
+    updateDatetime: string;
+    transferHash: string | null;
+    transactionHash: string | null;
+    transactionLt: string | null;
+  }
+  ```
+
+  ```ts
+  // 支付完成回调返回的订单结果
+  type MerchantPayFinishResponseData = MerchantPayOrderBase;
+  ```
+
+#### 5.2.3 查询支付结果
+
+- 接口: merchantPayQueryResult()
+
+  ```ts
+  sdk.merchantPayQueryResult(data: MerchantPayQueryResultRequest): Promise<MerchantPayQueryResultResponseData>
+  ```
+
+- 函数说明：通过系统订单号 `orderSn` 或商户订单号 `outTradeNo` 查询订单最新结果；
+- 参数说明：`MerchantPayQueryResultRequest`，见下方类型:
+  
+   ```ts
+  interface MerchantPayQueryResultRequest {
+    orderSn?: string;
+    outTradeNo?: string;
+  }
+  ```
+
+- 返回值说明：`Promise<MerchantPayQueryResultResponseData>`，同 `MerchantPayOrderBase`。
+
+  ```ts
+  type MerchantPayQueryResultResponseData = MerchantPayOrderBase;
+  ```
+
+#### 5.2.4 支付结果通知（服务端回调）
+
+- 说明：当你的服务接收 `notifyUrl` 的支付结果通知时，应返回统一响应结构，以便平台确认处理状态。
+- 返回值示例：
+
+```json
+{
+  "code": 1,
+  "msg": "通知支付结果成功",
+  "timestamp": 1756442387,
+  "datetime": "2025-08-29T04:39:47.518Z",
+  "data": {}
+}
+```
+
+- 约定说明：
+  - **code**: 1 表示成功；非 1 表示失败
+  - **msg**: 描述信息
+  - **timestamp/datetime**: 服务端时间
+  - **data**: 业务扩展字段（本例为空对象）