agentlink-sdk 1.0.3 → 1.0.5

package/README.md

@@ -0,0 +1,357 @@
+# AgentLink SDK
+
+AgentLink 客户端 SDK，用于跨域数据同步，通过 URL hash 传递数据，支持 Token 验证和白名单机制。
+
+## 安装
+
+### npm
+
+```bash
+npm install agentlink-sdk
+```
+
+### yarn
+
+```bash
+yarn add agentlink-sdk
+```
+
+### pnpm
+
+```bash
+pnpm add agentlink-sdk
+```
+
+### CDN
+
+```html
+<script type="module">
+  import { AgentLinkClient } from 'https://cdn.jsdelivr.net/npm/agentlink-sdk@latest/dist/index.mjs';
+</script>
+```
+
+## 快速开始
+
+### 基本使用
+
+```typescript
+import { AgentLinkClient } from 'agentlink-sdk';
+
+// 创建客户端实例
+const client = new AgentLinkClient({
+  serverUrl: 'https://agent-link-server.vercel.app'
+});
+
+// 发送数据
+await client.sendData(
+  'https://target-domain.com/page',
+  { message: 'Hello from AgentLink' },
+  'greeting'
+);
+
+// 接收数据
+client.receiveData((data, type, senderInfo) => {
+  console.log('收到数据:', data);
+  console.log('数据类型:', type);
+  console.log('发送方信息:', senderInfo);
+});
+```
+
+## API 文档
+
+### AgentLinkClient
+
+#### 构造函数
+
+```typescript
+new AgentLinkClient(options: AgentLinkClientOptions)
+```
+
+**参数：**
+
+- `options.serverUrl` (string, 必需): 服务端验证地址，例如 `'https://agentlink-server.vercel.app'`
+
+#### 方法
+
+##### sendData
+
+发送数据到目标应用。
+
+```typescript
+async sendData(
+  targetUrl: string,
+  data: any,
+  type: string,
+  windowName?: string
+): Promise<void>
+```
+
+**参数：**
+
+- `targetUrl` (string, 必需): 目标应用的完整 URL
+- `data` (any, 必需): 要发送的数据对象
+- `type` (string, 必需): 数据类型标识
+- `windowName` (string, 可选): 窗口名称，用于复用窗口，默认为 `'agentlink-window'`
+
+**示例：**
+
+```typescript
+await client.sendData(
+  'https://example.com/receive',
+  { 
+    message: 'Hello',
+    timestamp: Date.now(),
+    user: { id: 123, name: '张三' }
+  },
+  'user-message'
+);
+```
+
+##### receiveData
+
+监听来自 URL hash 的数据。
+
+```typescript
+receiveData(
+  callback: (
+    data: any,
+    type: string,
+    senderInfo?: SenderInfo,
+    verification?: string
+  ) => void
+): () => void
+```
+
+**参数：**
+
+- `callback` (function, 必需): 接收到数据时的回调函数
+  - `data`: 接收到的数据
+  - `type`: 数据类型
+  - `senderInfo`: 发送方信息（包含 domain 和 description）
+  - `verification`: 验证状态信息
+
+**返回值：**
+
+返回一个取消监听的函数。
+
+**示例：**
+
+```typescript
+const unsubscribe = client.receiveData((data, type, senderInfo, verification) => {
+  console.log('收到数据:', data);
+  console.log('数据类型:', type);
+  if (senderInfo) {
+    console.log('发送方域名:', senderInfo.domain);
+    console.log('发送方描述:', senderInfo.description);
+  }
+  console.log('验证状态:', verification);
+});
+
+// 取消监听
+unsubscribe();
+```
+
+##### getDataFromUrl
+
+从当前 URL 或指定 URL 获取数据并验证发送方。
+
+```typescript
+async getDataFromUrl(url?: string): Promise<{
+  data: any;
+  type: string;
+  senderInfo?: SenderInfo;
+  verification?: string;
+} | null>
+```
+
+**参数：**
+
+- `url` (string, 可选): 要解析的 URL，默认为当前页面的 URL
+
+**返回值：**
+
+如果 URL 中包含数据，返回包含 `data`、`type`、`senderInfo` 和 `verification` 的对象；否则返回 `null`。
+
+**示例：**
+
+```typescript
+const result = await client.getDataFromUrl();
+if (result) {
+  console.log('数据:', result.data);
+  console.log('类型:', result.type);
+  console.log('发送方:', result.senderInfo);
+  console.log('验证状态:', result.verification);
+}
+```
+
+##### getWhitelistInfo
+
+获取白名单信息。
+
+```typescript
+async getWhitelistInfo(includeAll?: boolean): Promise<WhitelistResponse>
+```
+
+**参数：**
+
+- `includeAll` (boolean, 可选): 是否获取所有白名单信息，默认为 `false`（仅获取当前域名）
+
+**返回值：**
+
+```typescript
+{
+  whitelist: WhitelistInfo | WhitelistInfo[] | null;
+  origin: string | null;
+}
+```
+
+**示例：**
+
+```typescript
+// 获取当前域名的白名单信息
+const info = await client.getWhitelistInfo(false);
+console.log('当前域名白名单:', info.whitelist);
+
+// 获取所有白名单信息
+const allInfo = await client.getWhitelistInfo(true);
+console.log('所有白名单:', allInfo.whitelist);
+```
+
+## 类型定义
+
+### AgentLinkClientOptions
+
+```typescript
+interface AgentLinkClientOptions {
+  serverUrl: string;
+}
+```
+
+### SenderInfo
+
+```typescript
+interface SenderInfo {
+  domain: string;
+  description: string | null;
+}
+```
+
+### WhitelistInfo
+
+```typescript
+interface WhitelistInfo {
+  domain: string;
+  description?: string | null;
+}
+```
+
+### WhitelistResponse
+
+```typescript
+interface WhitelistResponse {
+  whitelist: WhitelistInfo | WhitelistInfo[] | null;
+  origin: string | null;
+}
+```
+
+## 特性
+
+- ✅ **跨域数据同步**: 通过 URL hash 实现跨域数据传输
+- ✅ **Token 验证**: 自动获取和验证 Token，确保数据来源可信
+- ✅ **白名单机制**: 支持域名白名单验证
+- ✅ **数据压缩**: 自动压缩大型数据，优化 URL 长度
+- ✅ **缓存优化**: Token 和白名单验证结果缓存，减少服务器请求
+- ✅ **TypeScript 支持**: 完整的 TypeScript 类型定义
+- ✅ **窗口复用**: 支持复用窗口，避免频繁打开新窗口
+
+## 工作原理
+
+1. **发送数据**：
+   - SDK 自动从服务器获取当前域名的 Token
+   - 将数据编码到 URL hash 中（包含 Token 和验证信息）
+   - 通过 `window.open` 打开目标页面并传递数据
+
+2. **接收数据**：
+   - 监听 `hashchange` 事件
+   - 从 URL hash 中解码数据
+   - 验证发送方的 Token 和 Origin
+   - 返回数据及发送方信息
+
+3. **安全机制**：
+   - Token 验证：确保数据来自已注册的域名
+   - 白名单验证：检查域名是否在白名单中
+   - 缓存机制：减少重复验证请求
+
+## 示例
+
+完整示例请参考 [example.html](./example.html)
+
+### 发送数据示例
+
+```typescript
+const client = new AgentLinkClient({
+  serverUrl: 'https://agent-link-server.vercel.app'
+});
+
+// 发送复杂数据
+await client.sendData(
+  'https://target-app.com/receive',
+  {
+    action: 'update',
+    payload: {
+      userId: 123,
+      items: ['item1', 'item2', 'item3']
+    }
+  },
+  'user-action'
+);
+```
+
+### 接收数据示例
+
+```typescript
+const client = new AgentLinkClient({
+  serverUrl: 'https://agent-link-server.vercel.app'
+});
+
+// 监听数据
+client.receiveData((data, type, senderInfo, verification) => {
+  if (senderInfo) {
+    console.log(`来自 ${senderInfo.domain} 的数据`);
+  }
+  
+  switch (type) {
+    case 'user-action':
+      handleUserAction(data);
+      break;
+    case 'greeting':
+      handleGreeting(data);
+      break;
+    default:
+      console.log('未知数据类型:', type);
+  }
+});
+```
+
+## 注意事项
+
+1. **弹窗拦截**: 某些浏览器可能会拦截 `window.open`，确保在用户交互事件（如点击）中调用 `sendData`
+2. **URL 长度限制**: 虽然 SDK 会自动压缩数据，但过大的数据仍可能超出浏览器 URL 长度限制
+3. **HTTPS 要求**: 生产环境建议使用 HTTPS，确保数据传输安全
+4. **Token 缓存**: Token 在实例级别缓存，同一实例的多次调用会复用 Token
+
+## 浏览器支持
+
+- Chrome/Edge (最新版本)
+- Firefox (最新版本)
+- Safari (最新版本)
+
+## 许可证
+
+MIT
+
+## 相关链接
+
+- [示例文件](./example.html)
+- [GitHub 仓库](https://github.com/your-org/AgentLink)
+

package/dist/index.d.mts

@@ -26,6 +26,7 @@ declare class AgentLinkClient {
     private token;
     private tokenPromise;
     private static tokenCache;
+    private static whitelistCache;
     private static CACHE_TTL;
     constructor(options: AgentLinkClientOptions);
     /**
@@ -36,6 +37,10 @@ declare class AgentLinkClient {
      * 从服务器获取 Token
      */
     private fetchToken;
+    /**
+     * 检查域名是否在白名单中
+     */
+    private checkWhitelist;
     /**
      * 验证发送端的 Token 和 Origin
      */
@@ -50,16 +55,18 @@ declare class AgentLinkClient {
     sendData(targetUrl: string, data: any, type: string, windowName?: string): Promise<void>;
     /**
      * 监听来自 URL 的数据
-     * @param callback 接收到数据时的回调函数
+     * @param callback 接收到数据时的回调函数，现在包含验证信息
      */
-    receiveData(callback: (data: any, type: string, senderInfo?: SenderInfo) => void): () => void;
+    receiveData(callback: (data: any, type: string, senderInfo?: SenderInfo, verification?: string) => void): () => void;
     /**
      * 从当前 URL 获取数据并验证发送方
+     * 即使验证失败也返回数据，但会标记验证状态
      */
     getDataFromUrl(url?: string): Promise<{
         data: any;
         type: string;
         senderInfo?: SenderInfo;
+        verification?: string;
     } | null>;
     /**
      * 获取白名单信息
@@ -81,6 +88,7 @@ declare function decompress(compressedData: Uint8Array): Promise<string>;
 declare function uint8ArrayToBase64(arr: Uint8Array): string;
 /**
  * 将 URL 安全的 base64 字符串转换为 Uint8Array
+ * 如果输入无效，会抛出错误（由调用者处理）
  */
 declare function base64ToUint8Array(base64: string): Uint8Array;
 
@@ -89,11 +97,12 @@ interface URLData {
     type: string;
     token: string;
     origin: string;
+    verification?: string;
 }
 /**
  * 将数据编码为 URL hash
  */
-declare function encodeDataToUrl(data: any, type: string, token: string, origin: string, baseUrl: string): Promise<string>;
+declare function encodeDataToUrl(data: any, type: string, token: string, origin: string, baseUrl: string, verification?: string): Promise<string>;
 /**
  * 从 URL 中解码数据
  */

package/dist/index.d.ts

@@ -26,6 +26,7 @@ declare class AgentLinkClient {
     private token;
     private tokenPromise;
     private static tokenCache;
+    private static whitelistCache;
     private static CACHE_TTL;
     constructor(options: AgentLinkClientOptions);
     /**
@@ -36,6 +37,10 @@ declare class AgentLinkClient {
      * 从服务器获取 Token
      */
     private fetchToken;
+    /**
+     * 检查域名是否在白名单中
+     */
+    private checkWhitelist;
     /**
      * 验证发送端的 Token 和 Origin
      */
@@ -50,16 +55,18 @@ declare class AgentLinkClient {
     sendData(targetUrl: string, data: any, type: string, windowName?: string): Promise<void>;
     /**
      * 监听来自 URL 的数据
-     * @param callback 接收到数据时的回调函数
+     * @param callback 接收到数据时的回调函数，现在包含验证信息
      */
-    receiveData(callback: (data: any, type: string, senderInfo?: SenderInfo) => void): () => void;
+    receiveData(callback: (data: any, type: string, senderInfo?: SenderInfo, verification?: string) => void): () => void;
     /**
      * 从当前 URL 获取数据并验证发送方
+     * 即使验证失败也返回数据，但会标记验证状态
      */
     getDataFromUrl(url?: string): Promise<{
         data: any;
         type: string;
         senderInfo?: SenderInfo;
+        verification?: string;
     } | null>;
     /**
      * 获取白名单信息
@@ -81,6 +88,7 @@ declare function decompress(compressedData: Uint8Array): Promise<string>;
 declare function uint8ArrayToBase64(arr: Uint8Array): string;
 /**
  * 将 URL 安全的 base64 字符串转换为 Uint8Array
+ * 如果输入无效，会抛出错误（由调用者处理）
  */
 declare function base64ToUint8Array(base64: string): Uint8Array;
 
@@ -89,11 +97,12 @@ interface URLData {
     type: string;
     token: string;
     origin: string;
+    verification?: string;
 }
 /**
  * 将数据编码为 URL hash
  */
-declare function encodeDataToUrl(data: any, type: string, token: string, origin: string, baseUrl: string): Promise<string>;
+declare function encodeDataToUrl(data: any, type: string, token: string, origin: string, baseUrl: string, verification?: string): Promise<string>;
 /**
  * 从 URL 中解码数据
  */

package/dist/index.js

@@ -55,19 +55,45 @@ function uint8ArrayToBase64(arr) {
   return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 function base64ToUint8Array(base64) {
-  const padding = "=".repeat((4 - base64.length % 4) % 4);
-  const standardBase64 = base64.replace(/-/g, "+").replace(/_/g, "/") + padding;
-  const binary = atob(standardBase64);
-  const arr = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) {
-    arr[i] = binary.charCodeAt(i);
+  if (!base64 || typeof base64 !== "string") {
+    const error = new Error("Invalid base64 string: input must be a non-empty string");
+    error.isInvalidBase64 = true;
+    throw error;
+  }
+  const cleaned = base64.trim().replace(/[\s\n\r]/g, "");
+  if (!cleaned) {
+    const error = new Error("Invalid base64 string: empty after cleaning");
+    error.isInvalidBase64 = true;
+    throw error;
+  }
+  const base64Regex = /^[A-Za-z0-9\-_]+$/;
+  if (!base64Regex.test(cleaned)) {
+    const error = new Error(`Invalid base64 string: contains invalid characters`);
+    error.isInvalidBase64 = true;
+    throw error;
+  }
+  try {
+    const padding = "=".repeat((4 - cleaned.length % 4) % 4);
+    const standardBase64 = cleaned.replace(/-/g, "+").replace(/_/g, "/") + padding;
+    const binary = atob(standardBase64);
+    const arr = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      arr[i] = binary.charCodeAt(i);
+    }
+    return arr;
+  } catch (error) {
+    const base64Error = error instanceof Error ? error : new Error("Failed to decode base64");
+    base64Error.isInvalidBase64 = true;
+    throw base64Error;
   }
-  return arr;
 }
 
 // src/utils/url.ts
-async function encodeDataToUrl(data, type, token, origin, baseUrl) {
+async function encodeDataToUrl(data, type, token, origin, baseUrl, verification) {
   const payload = { data, type, token, origin };
+  if (verification !== void 0) {
+    payload.verification = verification;
+  }
   const jsonString = JSON.stringify(payload);
   const compressed = await compress(jsonString);
   const base64 = uint8ArrayToBase64(compressed);
@@ -79,12 +105,24 @@ async function decodeDataFromUrl(urlStr) {
   try {
     const url = new URL(urlStr);
     const hash = url.hash.startsWith("#") ? url.hash.slice(1) : url.hash;
-    if (!hash) return null;
+    if (!hash || hash.trim().length === 0) {
+      return null;
+    }
+    if (hash.length < 10) {
+      return null;
+    }
     const compressed = base64ToUint8Array(hash);
     const jsonString = await decompress(compressed);
     return JSON.parse(jsonString);
   } catch (error) {
-    console.error("[AgentLink] Failed to decode data from URL:", error);
+    if (error && typeof error === "object" && error.isInvalidBase64) {
+      return null;
+    }
+    if (error instanceof Error) {
+      if (false) {
+        console.debug("[AgentLink] Failed to decode data from URL:", error.message);
+      }
+    }
     return null;
   }
 }
@@ -170,6 +208,21 @@ var _AgentLinkClient = class _AgentLinkClient {
     this.token = token;
     return token;
   }
+  /**
+   * 检查域名是否在白名单中
+   */
+  async checkWhitelist(origin) {
+    const cached = _AgentLinkClient.whitelistCache.get(origin);
+    if (cached && Date.now() - cached.timestamp < _AgentLinkClient.CACHE_TTL) {
+      return cached.verified;
+    }
+    const verified = await verifyWhitelist(this.serverUrl, origin);
+    _AgentLinkClient.whitelistCache.set(origin, {
+      verified,
+      timestamp: Date.now()
+    });
+    return verified;
+  }
   /**
    * 验证发送端的 Token 和 Origin
    */
@@ -205,7 +258,9 @@ var _AgentLinkClient = class _AgentLinkClient {
   async sendData(targetUrl, data, type, windowName = _AgentLinkClient.DEFAULT_WINDOW_NAME) {
     const token = await this.ensureToken();
     const origin = window.location.origin;
-    const encodedUrl = await encodeDataToUrl(data, type, token, origin, targetUrl);
+    const isWhitelisted = await this.checkWhitelist(origin);
+    const verification = isWhitelisted ? "mixlab launchpad\u52A0\u901F\u8BA1\u5212" : "\u672A\u9A8C\u8BC1";
+    const encodedUrl = await encodeDataToUrl(data, type, token, origin, targetUrl, verification);
     const targetWindow = window.open(encodedUrl, windowName);
     if (!targetWindow) {
       throw new Error("[AgentLink] Failed to open target window. It might be blocked by a popup blocker.");
@@ -214,23 +269,36 @@ var _AgentLinkClient = class _AgentLinkClient {
   }
   /**
    * 监听来自 URL 的数据
-   * @param callback 接收到数据时的回调函数
+   * @param callback 接收到数据时的回调函数，现在包含验证信息
    */
   receiveData(callback) {
     const handleHashChange = async () => {
-      const result = await this.getDataFromUrl();
-      if (result) {
-        callback(result.data, result.type, result.senderInfo);
+      try {
+        const result = await this.getDataFromUrl();
+        if (result) {
+          callback(result.data, result.type, result.senderInfo, result.verification);
+        }
+      } catch (error) {
+        if (false) {
+          console.debug("[AgentLink] Error in handleHashChange (silently handled):", error);
+        }
       }
     };
     window.addEventListener("hashchange", handleHashChange);
-    handleHashChange();
+    try {
+      handleHashChange();
+    } catch (error) {
+      if (false) {
+        console.debug("[AgentLink] Error in initial hash check (silently handled):", error);
+      }
+    }
     return () => {
       window.removeEventListener("hashchange", handleHashChange);
     };
   }
   /**
    * 从当前 URL 获取数据并验证发送方
+   * 即使验证失败也返回数据，但会标记验证状态
    */
   async getDataFromUrl(url) {
     const targetUrl = url || window.location.href;
@@ -239,14 +307,18 @@ var _AgentLinkClient = class _AgentLinkClient {
       return null;
     }
     const senderInfo = await this.verifySender(urlData.token, urlData.origin);
+    let verification = urlData.verification;
+    if (!verification) {
+      verification = senderInfo ? "mixlab launchpad\u52A0\u901F\u8BA1\u5212" : "\u672A\u9A8C\u8BC1";
+    }
     if (!senderInfo) {
-      console.warn(`[AgentLink] Data received but sender verification failed`);
-      return null;
+      console.warn(`[AgentLink] Data received but sender verification failed. Verification: ${verification}`);
     }
     return {
       data: urlData.data,
       type: urlData.type,
-      senderInfo
+      senderInfo: senderInfo || void 0,
+      verification
     };
   }
   /**
@@ -259,6 +331,8 @@ var _AgentLinkClient = class _AgentLinkClient {
 _AgentLinkClient.DEFAULT_WINDOW_NAME = "agentlink-window";
 // 接收端验证结果缓存（静态，跨实例共享）
 _AgentLinkClient.tokenCache = /* @__PURE__ */ new Map();
+// 白名单验证缓存（避免重复请求）
+_AgentLinkClient.whitelistCache = /* @__PURE__ */ new Map();
 // 缓存过期时间：1 小时
 _AgentLinkClient.CACHE_TTL = 60 * 60 * 1e3;
 var AgentLinkClient = _AgentLinkClient;

package/dist/index.mjs

@@ -21,19 +21,45 @@ function uint8ArrayToBase64(arr) {
   return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 function base64ToUint8Array(base64) {
-  const padding = "=".repeat((4 - base64.length % 4) % 4);
-  const standardBase64 = base64.replace(/-/g, "+").replace(/_/g, "/") + padding;
-  const binary = atob(standardBase64);
-  const arr = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) {
-    arr[i] = binary.charCodeAt(i);
-  }
-  return arr;
+  if (!base64 || typeof base64 !== "string") {
+    const error = new Error("Invalid base64 string: input must be a non-empty string");
+    error.isInvalidBase64 = true;
+    throw error;
+  }
+  const cleaned = base64.trim().replace(/[\s\n\r]/g, "");
+  if (!cleaned) {
+    const error = new Error("Invalid base64 string: empty after cleaning");
+    error.isInvalidBase64 = true;
+    throw error;
+  }
+  const base64Regex = /^[A-Za-z0-9\-_]+$/;
+  if (!base64Regex.test(cleaned)) {
+    const error = new Error(`Invalid base64 string: contains invalid characters`);
+    error.isInvalidBase64 = true;
+    throw error;
+  }
+  try {
+    const padding = "=".repeat((4 - cleaned.length % 4) % 4);
+    const standardBase64 = cleaned.replace(/-/g, "+").replace(/_/g, "/") + padding;
+    const binary = atob(standardBase64);
+    const arr = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      arr[i] = binary.charCodeAt(i);
+    }
+    return arr;
+  } catch (error) {
+    const base64Error = error instanceof Error ? error : new Error("Failed to decode base64");
+    base64Error.isInvalidBase64 = true;
+    throw base64Error;
+  }
 }
 
 // src/utils/url.ts
-async function encodeDataToUrl(data, type, token, origin, baseUrl) {
+async function encodeDataToUrl(data, type, token, origin, baseUrl, verification) {
   const payload = { data, type, token, origin };
+  if (verification !== void 0) {
+    payload.verification = verification;
+  }
   const jsonString = JSON.stringify(payload);
   const compressed = await compress(jsonString);
   const base64 = uint8ArrayToBase64(compressed);
@@ -45,12 +71,24 @@ async function decodeDataFromUrl(urlStr) {
   try {
     const url = new URL(urlStr);
     const hash = url.hash.startsWith("#") ? url.hash.slice(1) : url.hash;
-    if (!hash) return null;
+    if (!hash || hash.trim().length === 0) {
+      return null;
+    }
+    if (hash.length < 10) {
+      return null;
+    }
     const compressed = base64ToUint8Array(hash);
     const jsonString = await decompress(compressed);
     return JSON.parse(jsonString);
   } catch (error) {
-    console.error("[AgentLink] Failed to decode data from URL:", error);
+    if (error && typeof error === "object" && error.isInvalidBase64) {
+      return null;
+    }
+    if (error instanceof Error) {
+      if (false) {
+        console.debug("[AgentLink] Failed to decode data from URL:", error.message);
+      }
+    }
     return null;
   }
 }
@@ -136,6 +174,21 @@ var _AgentLinkClient = class _AgentLinkClient {
     this.token = token;
     return token;
   }
+  /**
+   * 检查域名是否在白名单中
+   */
+  async checkWhitelist(origin) {
+    const cached = _AgentLinkClient.whitelistCache.get(origin);
+    if (cached && Date.now() - cached.timestamp < _AgentLinkClient.CACHE_TTL) {
+      return cached.verified;
+    }
+    const verified = await verifyWhitelist(this.serverUrl, origin);
+    _AgentLinkClient.whitelistCache.set(origin, {
+      verified,
+      timestamp: Date.now()
+    });
+    return verified;
+  }
   /**
    * 验证发送端的 Token 和 Origin
    */
@@ -171,7 +224,9 @@ var _AgentLinkClient = class _AgentLinkClient {
   async sendData(targetUrl, data, type, windowName = _AgentLinkClient.DEFAULT_WINDOW_NAME) {
     const token = await this.ensureToken();
     const origin = window.location.origin;
-    const encodedUrl = await encodeDataToUrl(data, type, token, origin, targetUrl);
+    const isWhitelisted = await this.checkWhitelist(origin);
+    const verification = isWhitelisted ? "mixlab launchpad\u52A0\u901F\u8BA1\u5212" : "\u672A\u9A8C\u8BC1";
+    const encodedUrl = await encodeDataToUrl(data, type, token, origin, targetUrl, verification);
     const targetWindow = window.open(encodedUrl, windowName);
     if (!targetWindow) {
       throw new Error("[AgentLink] Failed to open target window. It might be blocked by a popup blocker.");
@@ -180,23 +235,36 @@ var _AgentLinkClient = class _AgentLinkClient {
   }
   /**
    * 监听来自 URL 的数据
-   * @param callback 接收到数据时的回调函数
+   * @param callback 接收到数据时的回调函数，现在包含验证信息
    */
   receiveData(callback) {
     const handleHashChange = async () => {
-      const result = await this.getDataFromUrl();
-      if (result) {
-        callback(result.data, result.type, result.senderInfo);
+      try {
+        const result = await this.getDataFromUrl();
+        if (result) {
+          callback(result.data, result.type, result.senderInfo, result.verification);
+        }
+      } catch (error) {
+        if (false) {
+          console.debug("[AgentLink] Error in handleHashChange (silently handled):", error);
+        }
       }
     };
     window.addEventListener("hashchange", handleHashChange);
-    handleHashChange();
+    try {
+      handleHashChange();
+    } catch (error) {
+      if (false) {
+        console.debug("[AgentLink] Error in initial hash check (silently handled):", error);
+      }
+    }
     return () => {
       window.removeEventListener("hashchange", handleHashChange);
     };
   }
   /**
    * 从当前 URL 获取数据并验证发送方
+   * 即使验证失败也返回数据，但会标记验证状态
    */
   async getDataFromUrl(url) {
     const targetUrl = url || window.location.href;
@@ -205,14 +273,18 @@ var _AgentLinkClient = class _AgentLinkClient {
       return null;
     }
     const senderInfo = await this.verifySender(urlData.token, urlData.origin);
+    let verification = urlData.verification;
+    if (!verification) {
+      verification = senderInfo ? "mixlab launchpad\u52A0\u901F\u8BA1\u5212" : "\u672A\u9A8C\u8BC1";
+    }
     if (!senderInfo) {
-      console.warn(`[AgentLink] Data received but sender verification failed`);
-      return null;
+      console.warn(`[AgentLink] Data received but sender verification failed. Verification: ${verification}`);
     }
     return {
       data: urlData.data,
       type: urlData.type,
-      senderInfo
+      senderInfo: senderInfo || void 0,
+      verification
     };
   }
   /**
@@ -225,6 +297,8 @@ var _AgentLinkClient = class _AgentLinkClient {
 _AgentLinkClient.DEFAULT_WINDOW_NAME = "agentlink-window";
 // 接收端验证结果缓存（静态，跨实例共享）
 _AgentLinkClient.tokenCache = /* @__PURE__ */ new Map();
+// 白名单验证缓存（避免重复请求）
+_AgentLinkClient.whitelistCache = /* @__PURE__ */ new Map();
 // 缓存过期时间：1 小时
 _AgentLinkClient.CACHE_TTL = 60 * 60 * 1e3;
 var AgentLinkClient = _AgentLinkClient;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "agentlink-sdk",
-    "version": "1.0.3",
+    "version": "1.0.5",
     "description": "AgentLink client SDK for cross-domain data synchronization via URL hash",
     "main": "dist/index.js",
     "module": "dist/index.esm.js",