hm-tracking-sdk 0.1.2 → 0.1.4

package/README.md

@@ -4,65 +4,76 @@
 
 ## 1. 安装
 
-建议通过 npm/yarn 安装正式发布的包：
+### 建议通过 npm/yarn 安装正式发布的包：
 
-```bash
-# 使用 yarn
-yarn add hm-tracking-sdk axios crypto-js
-
-# 或使用 npm
-npm i hm-tracking-sdk axios crypto-js
-```
+  ```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",
+- 接口: init()
 
-  // 可选：浏览器环境下使用，可显式传入自定义用户
-  customUser: {
-    user: {
-      id: 123456789,
-      firstName: "Test",
-      lastName: "User",
-      username: "test_user",
-      languageCode: "zh-hans",
+  ```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",
     },
-    authDate: new Date().toISOString(),
-    hash: "your_hash_value",
-  },
-};
+  };
 
-const sdk = new HmTrackingSDK(options);
-await sdk.init();
-```
+  const sdk = new HmTrackingSDK(options);
+  await sdk.init();
+  ```
 
 - 函数说明：初始化 SDK，先创建 HmTrackingSDK 对象，然后调用 init 方法完成初始化。
-- 返回值：`Promise<void>`。
-
-### 2.1 参数说明
+- 参数说明: `SDKInitOptions` 初始化SDK时的可选参数，数据结构及内部结构说明为：
+  
+  ```ts
+    export interface SDKInitOptions {
+      /** 自定义接口地址（可选）。不传则使用默认正式环境 */
+      baseURL?: string;
+       /** 本地存储 Key 前缀，避免冲突 */
+      storageKeyPrefix?: string;
+      /** 自定义用户信息（可选） */
+      customUser?: TelegramUserInfo;
+    }
+  ```
 
-- baseURL（可选）
-  - 说明：后端服务地址；不传则使用 SDK 内置默认地址。
-  - 类型：`string`
-- storageKeyPrefix（可选）
-  - 说明：本地缓存命名空间前缀；用于隔离不同项目的存储键。
-  - 类型：`string`
-- customUser（可选）
-  - 说明：自定义用户数据，仅在非 Telegram 环境可用；若不传，SDK 会自动使用“匿名浏览器用户”（基于 Cookie 生成并持久化随机 userId），从而可以直接完成鉴权与后续请求。
-  - 类型：`TelegramUserInfo`
+  - baseURL（可选）
+    - 说明：后端服务地址；不传则使用 SDK 内置默认地址。
+    - 类型：`string`
+  - storageKeyPrefix（可选）
+    - 说明：本地缓存命名空间前缀；用于隔离不同项目的存储键。
+    - 类型：`string`
+  - customUser（可选）
+    - 说明：自定义用户数据，仅在非 Telegram 环境可用；若不传，SDK 会自动使用“匿名浏览器用户”（基于 Cookie 生成并持久化随机 userId），从而可以直接完成鉴权与后续请求。
+    - 类型：`TelegramUserInfo`
+- 返回值：`Promise<void>`。
 
-### 2.2 环境差异
+### 2.1 环境
 
 - Telegram 环境
   - SDK 自动读取当前Telegram用户的信息。
@@ -73,47 +84,52 @@ await sdk.init();
     - 便于无登录状态下完成鉴权，拿到 token 后再进行广告或调试。
   - 自定义用户：也可传入 `customUser` 替代匿名用户。
 
-### 2.3 环境判断
-  
-```ts
-import { isTelegramEnv } from "hm-tracking-sdk";
+### 2.2 环境判断
 
-if (isTelegramEnv()) {
-  // Telegram WebApp 环境
-} else {
-  // 浏览器/其他环境
-}
-```
+- 接口: isTelegramEnv()
 
----
+  ```ts
+  import { isTelegramEnv } from "hm-tracking-sdk";
 
-## 3. 获取Telegram用户信息
+  if (isTelegramEnv()) {
+    // Telegram WebApp 环境
+  } else {
+    // 浏览器/其他环境
+  }
+  ```
 
-返回 Telegram 当前用户的信息
+  - 函数说明：判断是否是Telegram环境。
+  - 返回值：`boolean`。
 
-```ts
-import { getTelegramUserUnsafe, type TelegramUserInfo } from "hm-tracking-sdk";
+---
 
-const user: TelegramUserInfo | null = getTelegramUserUnsafe();
-```
+## 3. 获取Telegram用户信息
+
+- 接口: 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;
-  }
+  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`。
 
 ---
@@ -122,9 +138,11 @@ const user: TelegramUserInfo | null = getTelegramUserUnsafe();
 
 ### 4.1 展示广告
 
-```ts
-await sdk.showHmAdByPosition(adPositionName);
-```
+- 接口: showHmAdByPosition()
+
+  ```ts
+  await sdk.showHmAdByPosition(adPositionName);
+  ```
 
 - 函数说明：根据广告位名称展示广告。
 - 参数说明
@@ -143,46 +161,52 @@ await sdk.showHmAdByPosition(adPositionName);
 
 支付仅支持在 Telegram WebApp 内使用。
 
-### 5.1 API
+### 5.1 TON钱包相关API
 
-#### 5.1.1 钱包相关接口
+#### 5.1.1 钱包是否链接
 
-```ts
-sdk.isWalletConnected(): boolean
-```
+- 接口: isWalletConnected()
+
+  ```ts
+  sdk.isWalletConnected(): boolean
+  ```
 
 - 函数说明：同步检查是否已连接 TON 钱包；
 - 返回值：`boolean`。
 
-```ts
-sdk.connectWallet(): Promise<boolean>
-```
+#### 5.1.2 链接钱包
+
+- 接口: connectWallet()
+
+  ```ts
+  sdk.connectWallet(): Promise<boolean>
+  ```
 
 - 函数说明：发起连接 TON 钱包；
 - 返回值：`Promise<boolean>` 表示是否连接成功。
 
-```ts
-sdk.disconnectWallet(): Promise<void>
-```
+#### 5.1.3 断开钱包链接
+
+- 接口: disconnectWallet()
+
+  ```ts
+  sdk.disconnectWallet(): Promise<void>
+  ```
 
 - 函数说明：断开已连接的钱包；
 - 返回值：`Promise<void>`。
 
-```ts
-sdk.ensureWalletConnected(): Promise<boolean>
-```
-
-- 函数说明：确保钱包已连接；若未连接则尝试连接；
-- 返回值：`Promise<boolean>` 表示最终是否已连接。
+### 5.2 支付
 
 #### 5.2.1 获取支持的支付方式
 
-```ts
-sdk.getSupportedPayModes(): Promise<MerchantPayModeListData>
-```
+- 接口: getSupportedPayModes()
+
+  ```ts
+  sdk.getSupportedPayModes(): Promise<MerchantPayModeListData>
+  ```
 
 - 函数说明：获取当前支持的币种及汇率配置；
-- 参数说明：无；
 - 返回值说明：`Promise<MerchantPayModeListData>`，见下方类型定义。
 
   ```ts
@@ -201,20 +225,22 @@ sdk.getSupportedPayModes(): Promise<MerchantPayModeListData>
 
 #### 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);
-```
+- 接口: 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 链上交易）；
 
@@ -268,9 +294,11 @@ const result: MerchantPayFinishResponseData = await sdk.payByMerchant(params);
 
 #### 5.2.3 查询支付结果
 
-```ts
-sdk.merchantPayQueryResult(data: MerchantPayQueryResultRequest): Promise<MerchantPayQueryResultResponseData>
-```
+- 接口: merchantPayQueryResult()
+
+  ```ts
+  sdk.merchantPayQueryResult(data: MerchantPayQueryResultRequest): Promise<MerchantPayQueryResultResponseData>
+  ```
 
 - 函数说明：通过系统订单号 `orderSn` 或商户订单号 `outTradeNo` 查询订单最新结果；
 - 参数说明：`MerchantPayQueryResultRequest`，见下方类型:
@@ -287,5 +315,3 @@ sdk.merchantPayQueryResult(data: MerchantPayQueryResultRequest): Promise<Merchan
   ```ts
   type MerchantPayQueryResultResponseData = MerchantPayOrderBase;
   ```
-
-

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "hm-tracking-sdk",
-    "version": "0.1.2",
+    "version": "0.1.4",
     "private": false,
     "description": "Telegram tracking SDK for Web/Miniapp with TON/Stars payment integration.",
     "license": "MIT",