agentlink-sdk 1.0.4 → 1.0.6

package/README.md

@@ -0,0 +1,368 @@
+# 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>
+```
+
+## 快速开始
+
+### 基本使用
+
+SDK 默认使用服务端地址 `https://mixlab.top`，可直接创建客户端；如需使用自建或其它服务端，可传入 `serverUrl` 覆盖默认值。
+
+```typescript
+import { AgentLinkClient } from 'agentlink-sdk';
+
+// 使用默认地址 https://mixlab.top
+const client = new AgentLinkClient();
+
+// 或指定自定义服务端地址
+const client = new AgentLinkClient({
+  serverUrl: 'https://your-agentlink-server.com'
+});
+
+// 发送数据
+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://mixlab.top`；可传入自定义地址如 `'https://your-server.com'`
+
+#### 方法
+
+##### 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;  // 可选，默认 'https://mixlab.top'
+}
+```
+
+### DEFAULT_SERVER_URL
+
+```typescript
+const DEFAULT_SERVER_URL = 'https://mixlab.top';
+```
+
+如需与默认地址保持一致（例如在配置中引用），可从 SDK 导入：`import { DEFAULT_SERVER_URL } from 'agentlink-sdk'`。
+
+### 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();
+
+// 发送复杂数据
+await client.sendData(
+  'https://target-app.com/receive',
+  {
+    action: 'update',
+    payload: {
+      userId: 123,
+      items: ['item1', 'item2', 'item3']
+    }
+  },
+  'user-action'
+);
+```
+
+### 接收数据示例
+
+```typescript
+// 使用默认地址，也可传入 serverUrl 使用自建服务端
+const client = new AgentLinkClient();
+
+// 监听数据
+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

@@ -1,12 +1,15 @@
 interface AgentLinkClientOptions {
     /**
-     * 服务端验证地址
-     * 例如: 'https://agentlink-server.vercel.app'
+     * 服务端验证地址，不传则使用默认地址 https://mixlab.top
+     * 例如: 'https://mixlab.top' 或自定义 'https://your-server.com'
      */
-    serverUrl: string;
+    serverUrl?: string;
 }
+/** 默认服务端地址 */
+declare const DEFAULT_SERVER_URL = "https://mixlab.top";
 interface WhitelistInfo {
     domain: string;
+    name?: string | null;
     description?: string | null;
 }
 interface WhitelistResponse {
@@ -28,7 +31,7 @@ declare class AgentLinkClient {
     private static tokenCache;
     private static whitelistCache;
     private static CACHE_TTL;
-    constructor(options: AgentLinkClientOptions);
+    constructor(options?: AgentLinkClientOptions);
     /**
      * 确保有 Token（自动获取）
      */
@@ -88,6 +91,7 @@ declare function decompress(compressedData: Uint8Array): Promise<string>;
 declare function uint8ArrayToBase64(arr: Uint8Array): string;
 /**
  * 将 URL 安全的 base64 字符串转换为 Uint8Array
+ * 如果输入无效，会抛出错误（由调用者处理）
  */
 declare function base64ToUint8Array(base64: string): Uint8Array;
 
@@ -116,4 +120,4 @@ declare function verifyWhitelist(serverUrl: string, origin?: string): Promise<bo
  */
 declare function fetchWhitelistInfo(serverUrl: string, includeAll?: boolean): Promise<any>;
 
-export { AgentLinkClient, type AgentLinkClientOptions, type SenderInfo, type URLData, type WhitelistInfo, type WhitelistResponse, base64ToUint8Array, compress, decodeDataFromUrl, decompress, encodeDataToUrl, fetchWhitelistInfo, uint8ArrayToBase64, verifyWhitelist };
+export { AgentLinkClient, type AgentLinkClientOptions, DEFAULT_SERVER_URL, type SenderInfo, type URLData, type WhitelistInfo, type WhitelistResponse, base64ToUint8Array, compress, decodeDataFromUrl, decompress, encodeDataToUrl, fetchWhitelistInfo, uint8ArrayToBase64, verifyWhitelist };

package/dist/index.d.ts

@@ -1,12 +1,15 @@
 interface AgentLinkClientOptions {
     /**
-     * 服务端验证地址
-     * 例如: 'https://agentlink-server.vercel.app'
+     * 服务端验证地址，不传则使用默认地址 https://mixlab.top
+     * 例如: 'https://mixlab.top' 或自定义 'https://your-server.com'
      */
-    serverUrl: string;
+    serverUrl?: string;
 }
+/** 默认服务端地址 */
+declare const DEFAULT_SERVER_URL = "https://mixlab.top";
 interface WhitelistInfo {
     domain: string;
+    name?: string | null;
     description?: string | null;
 }
 interface WhitelistResponse {
@@ -28,7 +31,7 @@ declare class AgentLinkClient {
     private static tokenCache;
     private static whitelistCache;
     private static CACHE_TTL;
-    constructor(options: AgentLinkClientOptions);
+    constructor(options?: AgentLinkClientOptions);
     /**
      * 确保有 Token（自动获取）
      */
@@ -88,6 +91,7 @@ declare function decompress(compressedData: Uint8Array): Promise<string>;
 declare function uint8ArrayToBase64(arr: Uint8Array): string;
 /**
  * 将 URL 安全的 base64 字符串转换为 Uint8Array
+ * 如果输入无效，会抛出错误（由调用者处理）
  */
 declare function base64ToUint8Array(base64: string): Uint8Array;
 
@@ -116,4 +120,4 @@ declare function verifyWhitelist(serverUrl: string, origin?: string): Promise<bo
  */
 declare function fetchWhitelistInfo(serverUrl: string, includeAll?: boolean): Promise<any>;
 
-export { AgentLinkClient, type AgentLinkClientOptions, type SenderInfo, type URLData, type WhitelistInfo, type WhitelistResponse, base64ToUint8Array, compress, decodeDataFromUrl, decompress, encodeDataToUrl, fetchWhitelistInfo, uint8ArrayToBase64, verifyWhitelist };
+export { AgentLinkClient, type AgentLinkClientOptions, DEFAULT_SERVER_URL, type SenderInfo, type URLData, type WhitelistInfo, type WhitelistResponse, base64ToUint8Array, compress, decodeDataFromUrl, decompress, encodeDataToUrl, fetchWhitelistInfo, uint8ArrayToBase64, verifyWhitelist };

package/dist/index.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AgentLinkClient: () => AgentLinkClient,
+  DEFAULT_SERVER_URL: () => DEFAULT_SERVER_URL,
   base64ToUint8Array: () => base64ToUint8Array,
   compress: () => compress,
   decodeDataFromUrl: () => decodeDataFromUrl,
@@ -55,14 +56,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 +106,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;
   }
 }
@@ -138,12 +174,14 @@ async function fetchWhitelistInfo(serverUrl, includeAll = false) {
 }
 
 // src/client.ts
+var DEFAULT_SERVER_URL = "https://mixlab.top";
 var _AgentLinkClient = class _AgentLinkClient {
-  constructor(options) {
+  constructor(options = {}) {
     // 发送端 Token 缓存（实例级别）
     this.token = null;
     this.tokenPromise = null;
-    this.serverUrl = options.serverUrl.replace(/\/$/, "");
+    const base = options.serverUrl ?? DEFAULT_SERVER_URL;
+    this.serverUrl = base.replace(/\/$/, "");
   }
   /**
    * 确保有 Token（自动获取）
@@ -238,13 +276,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;
   }
 }
@@ -104,12 +139,14 @@ async function fetchWhitelistInfo(serverUrl, includeAll = false) {
 }
 
 // src/client.ts
+var DEFAULT_SERVER_URL = "https://mixlab.top";
 var _AgentLinkClient = class _AgentLinkClient {
-  constructor(options) {
+  constructor(options = {}) {
     // 发送端 Token 缓存（实例级别）
     this.token = null;
     this.tokenPromise = null;
-    this.serverUrl = options.serverUrl.replace(/\/$/, "");
+    const base = options.serverUrl ?? DEFAULT_SERVER_URL;
+    this.serverUrl = base.replace(/\/$/, "");
   }
   /**
    * 确保有 Token（自动获取）
@@ -204,13 +241,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);
     };
@@ -257,6 +306,7 @@ _AgentLinkClient.CACHE_TTL = 60 * 60 * 1e3;
 var AgentLinkClient = _AgentLinkClient;
 export {
   AgentLinkClient,
+  DEFAULT_SERVER_URL,
   base64ToUint8Array,
   compress,
   decodeDataFromUrl,

package/package.json

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