@seaverse/data-sdk 0.2.0 → 0.2.2

package/README.md

@@ -5,9 +5,32 @@
 
 高性能数据服务 SDK，基于 PostgreSQL/AlloyDB + PostgREST + RLS 架构。
 
-## 🚀 核心概念
+## ✨ 核心特性：零配置使用
 
-### App ID 是什么？
+**使用 `DataClient.create()` 无需传参！** SDK 会自动通过 PostMessage 协议从父页面获取 `appId` 和 `token`。
+
+```typescript
+import { DataClient } from '@seaverse/data-sdk';
+
+// 无需任何配置，自动获取！
+const client = await DataClient.create();
+
+// 直接使用
+const notes = await client.query({ table: 'notes' });
+const newNote = await client.create({
+  table: 'notes',
+  data: { title: 'My Note', content: '...' },
+});
+```
+
+**工作原理：**
+- 📡 **自动初始化**：`DataClient.create()` 自动向父页面发送 `seaverse:get_token` 和 `seaverse:get_appId` 消息
+- 🔄 **PostMessage 协议**：父页面响应消息，返回配置信息
+- ⚡ **即时可用**：适用于 iframe 嵌入场景和 SeaVerse 平台应用
+
+> 💡 **父页面需要监听并响应 PostMessage 请求**（详见 [PostMessage 协议集成](#postmessage-协议集成)）
+
+## 🚀 App ID 是什么？
 
 **App ID** 是您在 SeaVerse 平台上创建的应用的唯一标识符。它用于：
 - ✅ 多租户数据隔离（每个应用的数据互不干扰）
@@ -31,9 +54,8 @@
 - ✅ 完整的错误处理
 - ✅ 支持过滤、排序、分页
 - ✅ 支持标签和 JSONB 字段查询
-- ✅ **无缝接入** - 自动从 PostMessage 获取配置
-- ✅ **零配置使用** - 可选的初始化，支持开箱即用
-- ✅ **函数式 API** - 提供便捷的函数调用方式
+- ✅ **零配置使用** - 自动从 PostMessage 获取配置
+- ✅ **类实例 API** - 清晰的面向对象设计
 
 ## 安装
 
@@ -43,99 +65,65 @@ npm install @seaverse/data-sdk
 
 ## 快速开始
 
-### 两种使用方式
+### 方式 1：零配置使用（推荐）
 
-#### 方式 A：函数式 API（推荐 - 零配置）
-
-**适合 SeaVerse 平台应用** - SDK 自动从 PostMessage 获取配置，无需手动初始化
+**最简单的方式 - 无需传参！** SDK 会自动通过 PostMessage 从父页面获取 `appId` 和 `token`。
 
 ```typescript
-import { query, create, update, deleteData } from '@seaverse/data-sdk';
+import { DataClient } from '@seaverse/data-sdk';
 
-// 直接使用，无需初始化！
-// SDK 自动从 PostMessage 获取配置（需要父页面响应相应的消息）
+// 无需传参，自动获取配置
+const client = await DataClient.create();
 
 // 查询数据
-const notes = await query({
+const notes = await client.query({
   table: 'notes',
   filters: { category: 'work' },
   order: { field: 'created_at', direction: 'desc' },
 });
 
 // 创建数据
-const newNote = await create({
+const newNote = await client.create({
   table: 'notes',
   data: { title: 'My Note', content: '...' },
   visibility: 'private',
 });
 
 // 更新数据
-await update('note-id-123', {
+const updated = await client.update('note-id-123', {
   data: { title: 'Updated' },
 });
 
 // 删除数据
-await deleteData('note-id-123');
+await client.delete('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 会自动获取
-});
+> 📡 **自动配置获取**：`DataClient.create()` 会自动向父页面发送 PostMessage 请求获取配置
+> 🎯 **适用场景**：iframe 嵌入应用、SeaVerse 平台应用
+> ⚠️ **前置条件**：父页面需要监听并响应 PostMessage 请求（详见 [PostMessage 协议集成](#postmessage-协议集成)）
 
-// 方式3: 完全显式提供
-await initData({
-  appId: 'my-app-123',
-  token: 'user-jwt-token',
-  debug: true,
-});
-
-// 然后直接使用
-const notes = await query({ table: 'notes' });
-```
+### 方式 2：显式传参
 
-#### 方式 B：类实例 API（传统方式）
-
-**适合需要多个实例或完全自定义配置的场景**
+**适合非 iframe 环境或需要自定义配置的场景**
 
 ```typescript
 import { DataClient } from '@seaverse/data-sdk';
 
-// 方式1: 使用静态工厂方法（支持自动获取配置）
-const client = await DataClient.create();
-// appId 和 token 都会自动获取
-
-// 方式2: 部分配置 + 自动获取
+// 方式 2.1: 显式提供所有配置
 const client = await DataClient.create({
-  appId: 'my-app-123',  // 显式提供 appId
-  // token 会自动获取
-});
-
-// 方式3: 显式提供所有配置（传统方式）
-const client = new DataClient({
   appId: 'my-app-123',
   token: 'user-jwt-token',
 });
 
-// 方式4: 指定环境
-const client = new DataClient({
+// 方式 2.2: 指定环境
+const client = await DataClient.create({
   appId: 'my-app-123',
   token: 'user-jwt-token',
   environment: 'production',    // 'production' | 'staging' | 'development' | 'local'
 });
 
-// 方式5: 完全自定义
-const client = new DataClient({
+// 方式 2.3: 自定义 API 地址
+const client = await DataClient.create({
   appId: 'my-app-123',
   token: 'user-jwt-token',
   baseURL: 'https://custom-api.example.com',
@@ -163,36 +151,50 @@ const notes = await client.query({ table: 'notes' });
 > ```
 > 如果启用 `debug: true`，还会打印完整的 token 和详细的配置信息（⚠️ 注意：生产环境建议关闭 debug 模式）。
 
-### 配置自动获取规则
+## 📡 配置自动获取规则
+
+### 核心机制
+
+**SDK 采用 PostMessage 协议自动获取配置**，首次调用任何 API 时会自动触发：
+
+1. **发送请求**：SDK 向父页面发送 `seaverse:get_token` 和 `seaverse:get_appId` 消息
+2. **父页面响应**：父页面监听消息并返回配置信息
+3. **完成初始化**：SDK 接收配置后立即可用
 
-**Token 自动获取：**
-SDK 会按照以下优先级自动获取 token：
+### 获取优先级
+
+**Token 获取优先级：**
 1. 显式传入的 `token` 参数（最高优先级）
 2. PostMessage 从父窗口获取（使用 `seaverse:get_token` 协议）
 
-**AppId 自动获取：**
-SDK 会按照以下优先级自动获取 appId：
+**AppId 获取优先级：**
 1. 显式传入的 `appId` 参数（最高优先级）
 2. PostMessage 从父窗口获取（使用 `seaverse:get_appId` 协议）
 
-> 💡 **最佳实践**：
-> - data-sdk 通过 PostMessage 协议与父页面通信获取配置
-> - 父页面需要监听并响应 `seaverse:get_token` 和 `seaverse:get_appId` 消息
-> - 适用于 iframe 嵌入场景，实现安全的跨域配置传递
+### 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 }` |
+
+> ⚠️ **重要提示**：
+> - 父页面**必须**监听并响应上述 PostMessage 消息，否则 SDK 无法自动获取配置
+> - 如果父页面未响应，需要显式传入 `appId` 和 `token` 参数
+> - 详细的父页面集成代码请参见 [PostMessage 协议集成](#postmessage-协议集成)
 
 ## API 文档
 
-### 初始化和配置 API
+### 初始化
 
 | 方法 | 说明 | 参数 | 返回值 |
 |------|------|------|--------|
-| `initData(options?)` | 初始化 SDK（可选） | `Partial<DataClientOptions>` | `Promise<void>` |
-| `updateToken(token)` | 更新全局 token | `token: string` | `void` |
-| `updateAppId(appId)` | 更新全局 appId | `appId: string` | `void` |
-| `getCurrentAppId()` | 获取当前 appId | - | `string \| undefined` |
-| `clearConfig()` | 清除全局配置 | - | `void` |
+| `DataClient.create(options?)` | 创建客户端实例（支持零配置） | `DataClientOptions?` | `Promise<DataClient>` |
+
+### 数据操作方法
 
-### 数据操作 API（函数式）
+使用 `await DataClient.create()` 创建实例后可用的方法：
 
 | 方法 | 说明 | 参数 | 返回值 |
 |------|------|------|--------|
@@ -200,29 +202,16 @@ SDK 会按照以下优先级自动获取 appId：
 | `get(id)` | 获取单条数据 | `id: string` | `Promise<DataRecord \| null>` |
 | `create(options)` | 创建数据 | `CreateDataOptions` | `Promise<DataRecord>` |
 | `update(id, options)` | 更新数据 | `id: string`, `UpdateDataOptions` | `Promise<DataRecord>` |
-| `deleteData(id)` | 删除数据 | `id: string` | `Promise<void>` |
+| `delete(id)` | 删除数据 | `id: string` | `Promise<void>` |
 | `batchDelete(ids)` | 批量删除 | `ids: string[]` | `Promise<void>` |
 | `queryWithPagination(options)` | 查询带分页信息 | `QueryOptions` | `Promise<PaginatedResponse<DataRecord>>` |
 | `isAdmin()` | 检查管理员权限 | - | `Promise<boolean>` |
 
-### DataClient 类方法
-
-使用 `new DataClient(options)` 创建实例后可用的方法：
+### 配置查询方法
 
 | 方法 | 说明 | 参数 | 返回值 |
 |------|------|------|--------|
-| `query(options)` | 查询数据列表 | `QueryOptions` | `Promise<DataRecord[]>` |
-| `get(id)` | 获取单条数据 | `id: string` | `Promise<DataRecord \| null>` |
-| `create(options)` | 创建数据 | `CreateDataOptions` | `Promise<DataRecord>` |
-| `update(id, options)` | 更新数据 | `id: string`, `UpdateDataOptions` | `Promise<DataRecord>` |
-| `delete(id)` | 删除数据 | `id: string` | `Promise<void>` |
-| `batchDelete(ids)` | 批量删除 | `ids: string[]` | `Promise<void>` |
-| `queryWithPagination(options)` | 查询带分页信息 | `QueryOptions` | `Promise<PaginatedResponse<DataRecord>>` |
-| `isAdmin()` | 检查管理员权限 | - | `Promise<boolean>` |
-| `updateToken(token)` | 更新实例 token | `token: string` | `void` |
-| `updateAppId(appId)` | 更新实例 appId | `appId: string` | `void` |
-| `getAppId()` | 获取实例 appId | - | `string` |
-| `getUserId()` | 获取当前用户 ID | - | `string` |
+| `getConfig()` | 获取当前 SDK 配置 | - | `{ appId: string; token: string; url: string }` |
 
 ### 查询选项（QueryOptions）
 
@@ -483,24 +472,26 @@ const notes = await query({ table: 'notes' });
 1. 显式传入的 `token` 参数（最高优先级）
 2. PostMessage 从父窗口获取（使用 `seaverse:get_token` 协议）
 
-### 无缝接入场景
+### 使用场景示例
 
 #### React 应用中使用
 
 ```typescript
-import { initData, query, create, updateToken } from '@seaverse/data-sdk';
-import { useEffect } from 'react';
+import { DataClient } from '@seaverse/data-sdk';
+import { useEffect, useState } from 'react';
 
 function App() {
+  const [client, setClient] = useState<DataClient | null>(null);
+
   useEffect(() => {
-    // 可选：应用启动时初始化
-    // SDK 会自动通过 PostMessage 从父页面获取配置
-    initData({ debug: true });
+    // 应用启动时初始化 SDK
+    DataClient.create({ debug: true }).then(setClient);
   }, []);
 
   const loadNotes = async () => {
-    // 直接使用，无需传递 client 实例
-    const notes = await query({
+    if (!client) return [];
+
+    const notes = await client.query({
       table: 'notes',
       order: { field: 'created_at', direction: 'desc' },
     });
@@ -564,10 +555,11 @@ window.addEventListener('message', (event) => {
 **iframe 页面（自动获取）：**
 
 ```typescript
-import { query } from '@seaverse/data-sdk';
+import { DataClient } from '@seaverse/data-sdk';
 
-// 直接使用，SDK 会自动通过 PostMessage 从父页面获取 appId 和 token
-const notes = await query({ table: 'notes' });
+// 无需传参，SDK 会自动通过 PostMessage 从父页面获取配置
+const client = await DataClient.create();
+const notes = await client.query({ table: 'notes' });
 ```
 
 **PostMessage 协议说明：**
@@ -581,16 +573,16 @@ const notes = await query({ table: 'notes' });
 #### 服务端渲染（SSR/SSG）
 
 ```typescript
-import { query, initData } from '@seaverse/data-sdk';
+import { DataClient } from '@seaverse/data-sdk';
 
 export async function getServerSideProps() {
   // 服务端需要显式提供配置
-  await initData({
+  const client = await DataClient.create({
     appId: process.env.APP_ID,
     token: process.env.API_SERVICE_TOKEN,
   });
 
-  const notes = await query({
+  const notes = await client.query({
     table: 'notes',
     filters: { visibility: 'public' },
   });
@@ -599,37 +591,18 @@ export async function getServerSideProps() {
 }
 ```
 
-### 动态更新 Token
+### 获取当前配置
 
 ```typescript
-import { updateToken } from '@seaverse/data-sdk';
-
-// JWT 过期后更新 token（函数式 API）
-updateToken('new-jwt-token');
-
-// 或使用类实例
-client.updateToken('new-jwt-token');
-```
-
-### 切换应用
-
-```typescript
-import { updateAppId } from '@seaverse/data-sdk';
-
-// 切换到其他应用（函数式 API）
-updateAppId('another-app-id');
-
-// 或使用类实例
-client.updateAppId('another-app-id');
-```
-
-### 清除配置（登出场景）
+import { DataClient } from '@seaverse/data-sdk';
 
-```typescript
-import { clearConfig } from '@seaverse/data-sdk';
+const client = await DataClient.create();
 
-// 用户登出时清除所有配置
-clearConfig();
+// 获取当前 SDK 配置
+const config = client.getConfig();
+console.log('App ID:', config.appId);
+console.log('Token:', config.token);
+console.log('API URL:', config.url);
 ```
 
 ### JSONB 字段查询