agentlink-sdk 1.0.4 → 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

@@ -88,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;
 

package/dist/index.d.ts

@@ -88,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;
 

package/dist/index.js

@@ -55,14 +55,37 @@ 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
@@ -82,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;
   }
 }
@@ -238,13 +273,25 @@ var _AgentLinkClient = class _AgentLinkClient {
    */
   receiveData(callback) {
     const handleHashChange = async () => {
-      const result = await this.getDataFromUrl();
-      if (result) {
-        callback(result.data, result.type, result.senderInfo, result.verification);
+      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);
     };

package/dist/index.mjs

@@ -21,14 +21,37 @@ 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
@@ -48,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;
   }
 }
@@ -204,13 +239,25 @@ var _AgentLinkClient = class _AgentLinkClient {
    */
   receiveData(callback) {
     const handleHashChange = async () => {
-      const result = await this.getDataFromUrl();
-      if (result) {
-        callback(result.data, result.type, result.senderInfo, result.verification);
+      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);
     };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "agentlink-sdk",
-    "version": "1.0.4",
+    "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",