@seaverse/data-sdk 0.1.6 → 0.1.8

package/README.md

@@ -47,13 +47,16 @@ npm install @seaverse/data-sdk
 
 #### 方式 A：函数式 API（推荐 - 零配置）
 
-**适合 SeaVerse 平台应用** - SDK 自动从 localStorage 获取配置，无需手动初始化
+**适合 SeaVerse 平台应用** - SDK 自动从 localStorage/环境变量/PostMessage 获取配置，无需手动初始化
 
 ```typescript
 import { query, create, update, deleteData } from '@seaverse/data-sdk';
 
 // 直接使用，无需初始化！
-// SDK 自动从 localStorage.auth_token 和 localStorage.app_id 获取配置
+// SDK 自动从以下来源获取配置（按优先级）：
+// - localStorage.app_id 和 localStorage.auth_token
+// - 环境变量 APP_ID 和 API_SERVICE_TOKEN
+// - PostMessage 从父页面获取（iframe 场景）
 
 // 查询数据
 const notes = await query({
@@ -83,11 +86,21 @@ await deleteData('note-id-123');
 ```typescript
 import { initData, query } from '@seaverse/data-sdk';
 
-// 可选：在应用启动时初始化
+// 方式1: 完全自动获取（零配置）
+await initData();
+// appId 和 token 都会自动获取
+
+// 方式2: 只提供 appId
+await initData({
+  appId: 'my-app-123',      // 显式提供
+  // token 会自动获取
+});
+
+// 方式3: 完全显式提供
 await initData({
-  appId: 'my-app-123',      // 可选，未提供则从 localStorage 读取
-  token: 'user-jwt-token',   // 可选，未提供则从 localStorage 读取
-  debug: true,               // 可选
+  appId: 'my-app-123',
+  token: 'user-jwt-token',
+  debug: true,
 });
 
 // 然后直接使用
@@ -101,20 +114,30 @@ const notes = await query({ table: 'notes' });
 ```typescript
 import { DataClient } from '@seaverse/data-sdk';
 
-// 方式1: SeaVerse 平台应用（自动检测环境）
+// 方式1: 使用静态工厂方法（支持自动获取配置）
+const client = await DataClient.create();
+// appId 和 token 都会自动获取
+
+// 方式2: 部分配置 + 自动获取
+const client = await DataClient.create({
+  appId: 'my-app-123',  // 显式提供 appId
+  // token 会自动获取
+});
+
+// 方式3: 显式提供所有配置（传统方式）
 const client = new DataClient({
   appId: 'my-app-123',
   token: 'user-jwt-token',
 });
 
-// 方式2: 指定环境
+// 方式4: 指定环境
 const client = new DataClient({
   appId: 'my-app-123',
   token: 'user-jwt-token',
   environment: 'production',    // 'production' | 'staging' | 'development' | 'local'
 });
 
-// 方式3: 完全自定义
+// 方式5: 完全自定义
 const client = new DataClient({
   appId: 'my-app-123',
   token: 'user-jwt-token',
@@ -129,8 +152,8 @@ const notes = await client.query({ table: 'notes' });
 
 | 参数 | 类型 | 必需 | 说明 |
 |-----|------|------|------|
-| `appId` | string | ⬜️ | 应用ID，未提供则从 localStorage/环境变量获取 |
-| `token` | string | ⬜️ | 用户JWT token，未提供则从 localStorage/环境变量获取 |
+| `appId` | string | ⬜️ | 应用ID，未提供则自动获取（localStorage/环境变量/PostMessage） |
+| `token` | string | ⬜️ | 用户JWT token，未提供则自动获取（localStorage/环境变量/PostMessage） |
 | `baseURL` | string | ⬜️ | 自定义API地址，优先级最高 |
 | `environment` | Environment | ⬜️ | 环境类型，当未提供baseURL时使用 |
 | `timeout` | number | ⬜️ | 请求超时时间（毫秒），默认10000 |
@@ -139,20 +162,24 @@ const notes = await client.query({ table: 'notes' });
 
 ### 配置自动获取规则
 
-**Token 自动获取（推荐）：**
+**Token 自动获取：**
 SDK 会按照以下优先级自动获取 token（与 seacloud-sdk 保持一致）：
-1. 显式传入的 `token` 参数
+1. 显式传入的 `token` 参数（最高优先级）
 2. `localStorage.getItem('auth_token')` - **标准 key，与 seacloud-sdk 一致**
-3. `localStorage.getItem('token')` - auth-sdk 备选 key
-4. 环境变量 `process.env.DATA_SDK_TOKEN`
-5. PostMessage 从父窗口获取（iframe 场景）
+3. 环境变量 `process.env.API_SERVICE_TOKEN`
+4. PostMessage 从父窗口获取（iframe 场景，使用 `seaverse:get_token` 协议）
 
-> 💡 **最佳实践**：使用 `@seaverse/auth-sdk` 进行登录，token 会自动存储到 `localStorage.auth_token`，data-sdk 会自动读取。
+**AppId 自动获取：**
+SDK 会按照以下优先级自动获取 appId：
+1. 显式传入的 `appId` 参数（最高优先级）
+2. `localStorage.getItem('app_id')` - **标准 key**
+3. 环境变量 `process.env.APP_ID`
+4. PostMessage 从父窗口获取（iframe 场景，使用 `seaverse:get_appid` 协议）
 
-**AppId 必须明确提供：**
-`appId` 必须由用户在初始化时明确提供，不会自动获取：
-- 通过 `initData({ appId: 'xxx' })` 提供
-- 或通过 `new DataClient({ appId: 'xxx' })` 提供
+> 💡 **最佳实践**：
+> - 使用 `@seaverse/auth-sdk` 进行登录，token 会自动存储到 `localStorage.auth_token`
+> - 将 appId 存储到 `localStorage.app_id`
+> - data-sdk 会自动读取这两个配置，实现零配置使用
 
 ## API 文档
 
@@ -297,9 +324,7 @@ try {
 
 ### 与 auth-sdk 集成（推荐）
 
-data-sdk 提供两种方式与 auth-sdk 集成：
-
-#### 方式 A：通过 localStorage（浏览器环境）
+data-sdk 通过 localStorage 与 auth-sdk 无缝集成（与 seacloud-sdk 保持一致）：
 
 ```typescript
 import { SeaVerseBackendAPIClient } from '@seaverse/auth-sdk';
@@ -315,7 +340,7 @@ const loginResult = await authClient.login({
   password: 'password',
 });
 
-// 2. 存储 token 到 localStorage（与 seacloud-sdk 保持一致）
+// 2. 存储 token 到 localStorage（标准 key）
 localStorage.setItem('auth_token', loginResult.token);
 
 // 3. 初始化 data-sdk（自动从 localStorage 读取 token）
@@ -328,35 +353,11 @@ await initData({
 const notes = await query({ table: 'notes' });
 ```
 
-#### 方式 B：直接调用 auth-sdk API（服务端/Node.js 环境）
-
-```typescript
-import { SeaVerseBackendAPIClient } from '@seaverse/auth-sdk';
-import { initData, query } from '@seaverse/data-sdk';
-
-// 1. 创建 auth-sdk client
-const authClient = new SeaVerseBackendAPIClient({
-  appId: 'my-app-123',
-  environment: 'production',
-});
-
-// 2. 🔥 直接传入 authClient，data-sdk 会调用 getApiServiceToken()
-await initData({
-  appId: 'my-app-123',
-  authClient,  // data-sdk 会自动调用 authClient.getApiServiceToken()
-});
-
-// 3. 使用 data-sdk
-const notes = await query({ table: 'notes' });
-```
-
 **Token 获取优先级：**
 1. 显式传入的 `token` 参数（最高优先级）
-2. 传入的 `authClient`（调用 `getApiServiceToken()`）
-3. `localStorage.getItem('auth_token')`
-4. `localStorage.getItem('token')`
-5. 环境变量 `process.env.DATA_SDK_TOKEN`
-6. PostMessage 从父窗口获取（iframe 场景）
+2. `localStorage.getItem('auth_token')`
+3. 环境变量 `process.env.API_SERVICE_TOKEN`
+4. PostMessage 从父窗口获取（iframe 场景，使用 `seaverse:get_token` 协议）
 
 ### 无缝接入场景
 
@@ -397,18 +398,43 @@ function App() {
 ```typescript
 // 监听来自 iframe 的配置请求
 window.addEventListener('message', (event) => {
-  if (event.data.type === 'DATA_SDK_TOKEN_REQUEST') {
-    event.source.postMessage({
-      type: 'DATA_SDK_TOKEN_RESPONSE',
-      token: localStorage.getItem('auth_token'),
-    }, '*');
+  // 处理 token 请求
+  if (event.data.type === 'seaverse:get_token') {
+    const token = localStorage.getItem('auth_token');
+
+    if (token) {
+      event.source.postMessage({
+        type: 'seaverse:token',
+        payload: {
+          accessToken: token,
+          expiresIn: 3600
+        }
+      }, '*');
+    } else {
+      event.source.postMessage({
+        type: 'seaverse:error',
+        error: 'Token not found'
+      }, '*');
+    }
   }
 
-  if (event.data.type === 'DATA_SDK_APP_ID_REQUEST') {
-    event.source.postMessage({
-      type: 'DATA_SDK_APP_ID_RESPONSE',
-      appId: localStorage.getItem('app_id'),
-    }, '*');
+  // 处理 appId 请求
+  if (event.data.type === 'seaverse:get_appid') {
+    const appId = localStorage.getItem('app_id');
+
+    if (appId) {
+      event.source.postMessage({
+        type: 'seaverse:appid',
+        payload: {
+          appId: appId
+        }
+      }, '*');
+    } else {
+      event.source.postMessage({
+        type: 'seaverse:error',
+        error: 'AppId not found'
+      }, '*');
+    }
   }
 });
 ```
@@ -418,10 +444,18 @@ window.addEventListener('message', (event) => {
 ```typescript
 import { query } from '@seaverse/data-sdk';
 
-// 直接使用，SDK 会自动通过 PostMessage 从父页面获取配置
+// 直接使用，SDK 会自动通过 PostMessage 从父页面获取 appId 和 token
 const notes = await query({ table: 'notes' });
 ```
 
+**PostMessage 协议说明：**
+
+| 协议 | 请求 type | 响应 type | 响应 payload |
+|------|----------|----------|-------------|
+| Token | `seaverse:get_token` | `seaverse:token` | `{ accessToken: string, expiresIn: number }` |
+| AppId | `seaverse:get_appid` | `seaverse:appid` | `{ appId: string }` |
+| 错误 | - | `seaverse:error` | `{ error: string }` |
+
 #### 服务端渲染（SSR/SSG）
 
 ```typescript
@@ -429,8 +463,8 @@ import { query } from '@seaverse/data-sdk';
 
 // 通过环境变量提供配置
 // .env 文件：
-// DATA_SDK_TOKEN=your-jwt-token
-// DATA_SDK_APP_ID=your-app-id
+// API_SERVICE_TOKEN=your-jwt-token
+// APP_ID=your-app-id
 
 export async function getServerSideProps() {
   // SDK 自动从环境变量读取配置
@@ -579,14 +613,38 @@ psql -h <host> -U postgres -d <database> -f init/init-schema.sql
 
 ## 版本历史
 
+### v0.1.8 (2026-01-15)
+
+**🎉 AppId 自动获取功能**
+
+- ✅ **AppId 自动获取**：支持从 localStorage/环境变量/PostMessage 自动获取 appId
+- ✅ **PostMessage 协议扩展**：新增 `seaverse:get_appid` / `seaverse:appid` 协议
+- ✅ **零配置使用**：`initData()` 和 `DataClient.create()` 现在可以不传任何参数
+- ✅ **优先级统一**：appId 和 token 采用相同的获取优先级
+- ✅ **环境变量支持**：新增 `APP_ID` 环境变量支持
+
+**AppId 获取优先级：**
+1. 显式传入的 `appId` 参数
+2. `localStorage.app_id`
+3. 环境变量 `APP_ID`
+4. PostMessage 从父页面获取
+
+### v0.1.7 (2026-01-15)
+
+**🔧 完全采用 seacloud-sdk 的 Token 获取逻辑**
+
+- ✅ **移除 authClient 参数**：简化 API，不再支持直接传入 auth-sdk client
+- ✅ **统一 Token 获取方式**：完全采用 seacloud-sdk 的实现
+- ✅ **PostMessage 协议统一**：使用 `seaverse:get_token` / `seaverse:token` 协议（与 seacloud-sdk 一致）
+- ✅ **环境变量更新**：使用 `API_SERVICE_TOKEN` 而非 `DATA_SDK_TOKEN`
+- ✅ **优先级调整**：token → localStorage.auth_token → env → PostMessage
+
 ### v0.1.6 (2026-01-14)
 
-**🎉 支持直接调用 auth-sdk API**
+**🎉 支持直接调用 auth-sdk API**（已在 v0.1.7 移除）
 
-- ✅ **新增 authClient 参数**：`initData({ authClient })` 直接调用 `authClient.getApiServiceToken()`
-- ✅ **适合服务端场景**：Node.js/Lambda 函数可直接通过 auth-sdk 获取 token
-- ✅ **灵活的集成方式**：支持 localStorage（浏览器）和 API 调用（服务端）两种方式
-- ✅ **完整示例**：新增 `examples/auth-sdk-integration.ts` 演示各种集成场景
+- ❌ ~~新增 authClient 参数~~（v0.1.7 已移除）
+- ✅ 完整示例：新增 `examples/auth-sdk-integration.ts` 演示各种集成场景
 
 ### v0.1.5 (2026-01-14)