hm-tracking-sdk 0.1.0

package/README.md

@@ -0,0 +1,291 @@
+# HM TG Tracking SDK 使用文档
+
+本文档详细介绍如何使用 HM TG 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 初始化
+
+```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 方法完成初始化。
+- 返回值：`Promise<void>`。
+
+### 2.1 参数说明
+
+- baseURL（可选）
+  - 说明：后端服务地址；不传则使用 SDK 内置默认地址。
+  - 类型：`string`
+- storageKeyPrefix（可选）
+  - 说明：本地缓存命名空间前缀；用于隔离不同项目的存储键。
+  - 类型：`string`
+- customUser（可选）
+  - 说明：自定义用户数据，仅在非 Telegram 环境可用；若不传，SDK 会自动使用“匿名浏览器用户”（基于 Cookie 生成并持久化随机 userId），从而可以直接完成鉴权与后续请求。
+  - 类型：`TelegramUserInfo`
+
+### 2.2 环境差异
+
+- Telegram 环境
+  - SDK 自动读取当前Telegram用户的信息。
+  - 无需传入 `customUser`；若 Telegram 用户读取失败，SDK 会抛错提示。
+- 浏览器环境（非 Telegram）
+  - 默认行为：若未传 `customUser`，SDK 会使用“匿名浏览器用户”：
+    - 首次访问生成随机 `userId`，存入 Cookie（如 `tg_tracking_uid`），后续复用。
+    - 便于无登录状态下完成鉴权，拿到 token 后再进行广告或调试。
+  - 自定义用户：也可传入 `customUser` 替代匿名用户。
+
+### 2.3 环境判断
+  
+```ts
+import { isTelegramEnv } from "hm-tracking-sdk";
+
+if (isTelegramEnv()) {
+  // Telegram WebApp 环境
+} else {
+  // 浏览器/其他环境
+}
+```
+
+---
+
+## 3. 获取Telegram用户信息
+
+返回 Telegram 当前用户的信息
+
+```ts
+import { getTelegramUserUnsafe, type TelegramUserInfo } from "hm-tracking-sdk";
+
+const user: TelegramUserInfo | null = getTelegramUserUnsafe();
+```
+
+- 函数说明：在 Telegram 环境下读取 `WebApp.initDataUnsafe` 并返回 `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 展示广告
+
+```ts
+await sdk.showHmAdByPosition(adPositionName);
+```
+
+- 函数说明：根据广告位名称展示广告。
+- 参数说明
+  - adPositionName（必填）
+    - 说明：广告位名称，需要根据业务进行申请，具体请联系SDK开发者，使用示例值进行测试。
+    - 类型：`string`
+    - 示例值：
+      - `game_rewarded_ad_position`
+- 返回值：`Promise<void>`。
+
+说明：SDK 会根据根据广告位名称获取相关广告配置并完成展示。
+
+---
+
+## 5. 支付业务
+
+支付仅支持在 Telegram WebApp 内使用。
+
+### 5.1 API
+
+#### 5.1.1 钱包相关接口
+
+```ts
+sdk.isWalletConnected(): boolean
+```
+
+- 函数说明：同步检查是否已连接 TON 钱包；
+- 返回值：`boolean`。
+
+```ts
+sdk.connectWallet(): Promise<boolean>
+```
+
+- 函数说明：发起连接 TON 钱包；
+- 返回值：`Promise<boolean>` 表示是否连接成功。
+
+```ts
+sdk.disconnectWallet(): Promise<void>
+```
+
+- 函数说明：断开已连接的钱包；
+- 返回值：`Promise<void>`。
+
+```ts
+sdk.ensureWalletConnected(): Promise<boolean>
+```
+
+- 函数说明：确保钱包已连接；若未连接则尝试连接；
+- 返回值：`Promise<boolean>` 表示最终是否已连接。
+
+#### 5.2.1 获取支持的支付方式
+
+```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 创建并支付订单
+
+```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 查询支付结果
+
+```ts
+sdk.merchantPayQueryResult(data: MerchantPayQueryResultRequest): Promise<MerchantPayQueryResultResponseData>
+```
+
+- 函数说明：通过系统订单号 `orderSn` 或商户订单号 `outTradeNo` 查询订单最新结果；
+- 参数说明：`MerchantPayQueryResultRequest`，见下方类型:
+  
+   ```ts
+  interface MerchantPayQueryResultRequest {
+    orderSn?: string;
+    outTradeNo?: string;
+  }
+  ```
+
+- 返回值说明：`Promise<MerchantPayQueryResultResponseData>`，同 `MerchantPayOrderBase`。
+
+  ```ts
+  type MerchantPayQueryResultResponseData = MerchantPayOrderBase;
+  ```
+
+