hm-tracking-sdk 0.1.2 → 0.1.3

package/README.md

@@ -4,48 +4,49 @@
 
 ## 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",
+- 接口: init()
 
-  // 可选：本地存储 Key 前缀，避免项目间冲突
-  storageKeyPrefix: "your_app_prefix",
-
-  // 可选：浏览器环境下使用，可显式传入自定义用户
-  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>`。
@@ -74,32 +75,37 @@ await sdk.init();
   - 自定义用户：也可传入 `customUser` 替代匿名用户。
 
 ### 2.3 环境判断
-  
-```ts
-import { isTelegramEnv } from "hm-tracking-sdk";
 
-if (isTelegramEnv()) {
-  // Telegram WebApp 环境
-} else {
-  // 浏览器/其他环境
-}
-```
+- 接口: isTelegramEnv()
+
+  ```ts
+  import { isTelegramEnv } from "hm-tracking-sdk";
+
+  if (isTelegramEnv()) {
+    // Telegram WebApp 环境
+  } else {
+    // 浏览器/其他环境
+  }
+  ```
+
+  - 函数说明：判断是否是Telegram环境。
+  - 返回值：`boolean`。
 
 ---
 
 ## 3. 获取Telegram用户信息
 
-返回 Telegram 当前用户的信息
+- 接口: getTelegramUserUnsafe()
 
-```ts
-import { getTelegramUserUnsafe, type TelegramUserInfo } from "hm-tracking-sdk";
+  ```ts
+  import { getTelegramUserUnsafe, type TelegramUserInfo } from "hm-tracking-sdk";
 
-const user: TelegramUserInfo | null = getTelegramUserUnsafe();
-```
+  const user: TelegramUserInfo | null = getTelegramUserUnsafe();
+  ```
 
-- 函数说明：在 Telegram 环境下读取 `WebApp.initDataUnsafe` 并返回 `TelegramUserInfo`；获取失败返回 `null`。
-- 返回值：`TelegramUserInfo | null`，数据结构为：
-  
+  - 函数说明：在 Telegram 环境下返回 `TelegramUserInfo`；获取失败返回 `null`。
+  - 返回值：`TelegramUserInfo | null`，数据结构为：
+    
   ```ts
   export interface TelegramUserInfo {
     id?: number;
@@ -122,9 +128,11 @@ const user: TelegramUserInfo | null = getTelegramUserUnsafe();
 
 ### 4.1 展示广告
 
-```ts
-await sdk.showHmAdByPosition(adPositionName);
-```
+- 接口: showHmAdByPosition()
+
+  ```ts
+  await sdk.showHmAdByPosition(adPositionName);
+  ```
 
 - 函数说明：根据广告位名称展示广告。
 - 参数说明
@@ -143,46 +151,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 +215,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 +284,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 +305,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.3",
     "private": false,
     "description": "Telegram tracking SDK for Web/Miniapp with TON/Stars payment integration.",
     "license": "MIT",