agentlink-sdk 1.0.5 → 1.0.7

package/Prompt.md

@@ -0,0 +1,52 @@
+添加一个 **AgentLink** 功能，用于将xxx数据发送到https://www.mixlab.top 
+
+### 安装方式
+
+- **npm 安装**  
+  ```bash
+  npm install agentlink-sdk
+  ```
+
+- **CDN 引入（浏览器端）**  
+  ```html
+  <script type="module">
+    import { AgentLinkClient } from 'https://cdn.jsdelivr.net/npm/agentlink-sdk@latest/dist/index.mjs';
+  </script>
+  ```
+
+### 使用说明
+
+SDK 默认连接的服务端地址为 `https://www.mixlab.top`。你可以直接创建客户端实例；如需使用自建或其他服务端，可通过 `serverUrl` 参数覆盖默认地址。
+
+#### Node.js / 模块化环境示例：
+```javascript
+import { AgentLinkClient } from 'agentlink-sdk';
+
+// 使用默认服务端（https://www.mixlab.top）
+const client = new AgentLinkClient();
+
+// 或指定自定义服务端地址
+const client = new AgentLinkClient({
+  serverUrl: 'https://your-agentlink-server.com'
+});
+```
+
+#### 发送数据
+```javascript
+await client.sendData(
+  'https://target-domain.com/page',   // 目标页面 URL
+  { message: 'Hello from AgentLink' }, // 要发送的数据（任意 JSON 兼容对象）
+  'greeting'  // 数据类型标识（自定义字符串）
+);
+```
+
+#### 接收数据
+```javascript
+client.receiveData((data, type, senderInfo) => {
+  console.log('收到数据:', data);
+  console.log('数据类型:', type);
+  console.log('发送方信息:', senderInfo); // 包含来源 URL 等上下文
+});
+```
+
+> 请确保在支持模块化（ESM）的环境中使用该 SDK，并注意跨域策略限制。

package/README.md

@@ -34,12 +34,17 @@ pnpm add agentlink-sdk
 
 ### 基本使用
 
+SDK 默认使用服务端地址 `https://www.mixlab.top`，可直接创建客户端；如需使用自建或其它服务端，可传入 `serverUrl` 覆盖默认值。
+
 ```typescript
 import { AgentLinkClient } from 'agentlink-sdk';
 
-// 创建客户端实例
+// 使用默认地址 https://www.mixlab.top
+const client = new AgentLinkClient();
+
+// 或指定自定义服务端地址
 const client = new AgentLinkClient({
-  serverUrl: 'https://agent-link-server.vercel.app'
+  serverUrl: 'https://your-agentlink-server.com'
 });
 
 // 发送数据
@@ -57,6 +62,17 @@ client.receiveData((data, type, senderInfo) => {
 });
 ```
 
+## 跨域与白名单说明
+
+在**任意域名**的网页（例如 `https://your-site.com`）中接入 SDK 并发送数据时：
+
+- **跨域（CORS）**：AgentLink 服务端已对相关 API 配置 CORS，会正确返回 `Access-Control-Allow-Origin` 等响应头。因此从你的站点向服务端发起的 `fetch` 请求**不会被浏览器以跨域为由拦截**，无需额外配置。
+- **白名单**：发送数据前，你的**当前页面所在域名**必须在 AgentLink 服务端的**域名白名单**中。若未加入白名单，服务端将拒绝签发 Token，`sendData` 会报错。  
+  - 使用默认服务端（如 `https://www.mixlab.top`）时，需在对应后台将你的域名加入白名单。  
+  - 使用自建服务端时，请在自己的 AgentLink 管理后台添加域名。
+
+总结：只要你的域名已在所用 AgentLink 服务端的白名单中，即可正常跨域调用、发送数据，无需担心浏览器跨域限制。
+
 ## API 文档
 
 ### AgentLinkClient
@@ -69,7 +85,7 @@ new AgentLinkClient(options: AgentLinkClientOptions)
 
 **参数：**
 
-- `options.serverUrl` (string, 必需): 服务端验证地址，例如 `'https://agentlink-server.vercel.app'`
+- `options.serverUrl` (string, 可选): 服务端验证地址。不传时使用默认地址 `https://www.mixlab.top`；可传入自定义地址如 `'https://your-server.com'`
 
 #### 方法
 
@@ -223,10 +239,18 @@ console.log('所有白名单:', allInfo.whitelist);
 
 ```typescript
 interface AgentLinkClientOptions {
-  serverUrl: string;
+  serverUrl?: string;  // 可选，默认 'https://www.mixlab.top'
 }
 ```
 
+### DEFAULT_SERVER_URL
+
+```typescript
+const DEFAULT_SERVER_URL = 'https://www.mixlab.top';
+```
+
+如需与默认地址保持一致（例如在配置中引用），可从 SDK 导入：`import { DEFAULT_SERVER_URL } from 'agentlink-sdk'`。
+
 ### SenderInfo
 
 ```typescript
@@ -289,9 +313,8 @@ interface WhitelistResponse {
 ### 发送数据示例
 
 ```typescript
-const client = new AgentLinkClient({
-  serverUrl: 'https://agent-link-server.vercel.app'
-});
+// 使用默认地址
+const client = new AgentLinkClient();
 
 // 发送复杂数据
 await client.sendData(
@@ -310,9 +333,8 @@ await client.sendData(
 ### 接收数据示例
 
 ```typescript
-const client = new AgentLinkClient({
-  serverUrl: 'https://agent-link-server.vercel.app'
-});
+// 使用默认地址，也可传入 serverUrl 使用自建服务端
+const client = new AgentLinkClient();
 
 // 监听数据
 client.receiveData((data, type, senderInfo, verification) => {
@@ -335,10 +357,11 @@ client.receiveData((data, type, senderInfo, verification) => {
 
 ## 注意事项
 
-1. **弹窗拦截**: 某些浏览器可能会拦截 `window.open`，确保在用户交互事件（如点击）中调用 `sendData`
-2. **URL 长度限制**: 虽然 SDK 会自动压缩数据，但过大的数据仍可能超出浏览器 URL 长度限制
-3. **HTTPS 要求**: 生产环境建议使用 HTTPS，确保数据传输安全
-4. **Token 缓存**: Token 在实例级别缓存，同一实例的多次调用会复用 Token
+1. **域名白名单**: 发送数据前，请确认当前站点域名已在 AgentLink 服务端的白名单中，否则无法获取 Token。详见上文「跨域与白名单说明」。
+2. **弹窗拦截**: 某些浏览器可能会拦截 `window.open`，确保在用户交互事件（如点击）中调用 `sendData`
+3. **URL 长度限制**: 虽然 SDK 会自动压缩数据，但过大的数据仍可能超出浏览器 URL 长度限制
+4. **HTTPS 要求**: 生产环境建议使用 HTTPS，确保数据传输安全
+5. **Token 缓存**: Token 在实例级别缓存，同一实例的多次调用会复用 Token
 
 ## 浏览器支持
 

package/dist/index.d.mts

@@ -1,12 +1,15 @@
 interface AgentLinkClientOptions {
     /**
-     * 服务端验证地址
-     * 例如: 'https://agentlink-server.vercel.app'
+     * 服务端验证地址，不传则使用默认地址 https://www.mixlab.top
+     * 例如: 'https://www.mixlab.top' 或自定义 'https://your-server.com'
      */
-    serverUrl: string;
+    serverUrl?: string;
 }
+/** 默认服务端地址 */
+declare const DEFAULT_SERVER_URL = "https://www.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（自动获取）
      */
@@ -117,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://www.mixlab.top
+     * 例如: 'https://www.mixlab.top' 或自定义 'https://your-server.com'
      */
-    serverUrl: string;
+    serverUrl?: string;
 }
+/** 默认服务端地址 */
+declare const DEFAULT_SERVER_URL = "https://www.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（自动获取）
      */
@@ -117,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,
@@ -173,12 +174,14 @@ async function fetchWhitelistInfo(serverUrl, includeAll = false) {
 }
 
 // src/client.ts
+var DEFAULT_SERVER_URL = "https://www.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（自动获取）

package/dist/index.mjs

@@ -139,12 +139,14 @@ async function fetchWhitelistInfo(serverUrl, includeAll = false) {
 }
 
 // src/client.ts
+var DEFAULT_SERVER_URL = "https://www.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（自动获取）
@@ -304,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.5",
+    "version": "1.0.7",
     "description": "AgentLink client SDK for cross-domain data synchronization via URL hash",
     "main": "dist/index.js",
     "module": "dist/index.esm.js",