@seaverse/data-sdk 0.2.5 → 0.3.0

package/README.md

@@ -5,22 +5,6 @@
 
 高性能数据服务 SDK，基于 PostgreSQL/AlloyDB + PostgREST + RLS 架构。
 
-## 🚀 核心概念
-
-### App ID 是什么？
-
-**App ID** 是您在 SeaVerse 平台上创建的应用的唯一标识符。它用于：
-- ✅ 多租户数据隔离（每个应用的数据互不干扰）
-- ✅ 权限控制（RLS 策略基于 app_id）
-- ✅ 资源配额管理
-
-**如何获取 App ID？**
-1. 登录 [SeaVerse 控制台](https://console.seaverse.ai)
-2. 进入"应用管理"
-3. 复制您的 App ID
-
-> ⚠️ **重要**：所有 SDK 操作都需要提供有效的 `appId`，否则无法访问数据。
-
 ## 特性
 
 - ✅ TypeScript 类型支持
@@ -41,48 +25,75 @@ npm install @seaverse/data-sdk
 
 ## 快速开始
 
-### 使用 DataClient
+### 方式 1: 函数式 API（推荐 ⭐）
 
-```typescript
-import { DataClient } from '@seaverse/data-sdk';
+最简单的使用方式，零配置，自动初始化：
 
-// 方式1: 零配置（推荐）- 自动从 PostMessage 获取 appId 和 token
-const client = await DataClient.create();
+```typescript
+import { query, create, update, deleteData } from '@seaverse/data-sdk';
 
-// 方式2: 只提供 appId，token 自动获取
-const client = await DataClient.create({
-  appId: 'my-app-123',
-});
+// 首次调用会自动初始化 SDK（从 PostMessage 获取 appId 和 token）
+// 无需任何配置代码！
 
-// 方式3: 显式提供所有配置
-const client = new DataClient({
-  appId: 'my-app-123',
-  token: 'user-jwt-token',
-});
-
-// 使用 client 实例
-const notes = await client.query({
+// 查询数据
+const notes = await query({
   table_name: 'notes',
   filters: { category: 'work' },
   order: { field: 'created_at', direction: 'desc' },
 });
 
 // 创建数据
-const newNote = await client.create({
+const newNote = await create({
   table_name: 'notes',
   data_value: { title: 'My Note', content: '...' },
   visibility: 'private',
 });
 
 // 更新数据
-await client.update('note-id-123', {
+await update('note-id-123', {
   data_value: { title: 'Updated' },
 });
 
 // 删除数据
-await client.delete('note-id-123');
+await deleteData('note-id-123');
+```
+
+**✨ 为什么推荐函数式 API？**
+
+- ✅ **零配置** - 无需创建客户端实例，直接调用函数
+- ✅ **自动初始化** - 首次调用自动获取配置（通过 PostMessage）
+- ✅ **简洁易用** - 代码更简洁，AI 更容易理解
+- ✅ **单例管理** - SDK 自动管理全局实例，避免重复初始化
+
+### 方式 2: DataClient 类 API（高级场景）
+
+适合需要多实例或自定义配置的场景：
+
+```typescript
+import { DataClient } from '@seaverse/data-sdk';
+
+// 零配置（推荐）
+const client = await DataClient.connect();
+
+// 或者指定配置
+const client = await DataClient.connect({
+  appId: 'my-app-123',
+  token: 'user-jwt-token',
+});
+
+// 使用 client 实例
+const notes = await client.query({
+  table_name: 'notes',
+  filters: { category: 'work' },
+});
 ```
 
+**🎯 何时使用 DataClient 类？**
+
+- 需要管理多个应用的实例
+- 需要动态切换 token 或 appId
+- 需要自定义配置（如 baseURL、timeout）
+
 **配置选项说明：**
 
 | 参数 | 类型 | 必需 | 说明 |
@@ -101,28 +112,78 @@ await client.delete('note-id-123');
 > ```
 > 如果启用 `debug: true`，还会打印完整的 token 和详细的配置信息（⚠️ 注意：生产环境建议关闭 debug 模式）。
 
-### 配置自动获取规则
+### 配置自动获取
 
-**Token 自动获取：**
-SDK 会按照以下优先级自动获取 token：
-1. 显式传入的 `token` 参数（最高优先级）
-2. PostMessage 从父窗口获取（使用 `seaverse:get_token` 协议）
+SDK 支持零配置使用，会自动从以下来源获取配置：
 
-**AppId 自动获取：**
-SDK 会按照以下优先级自动获取 appId：
-1. 显式传入的 `appId` 参数（最高优先级）
-2. PostMessage 从父窗口获取（使用 `seaverse:get_appId` 协议）
+- **Token & AppId**: 通过 PostMessage 从父窗口获取，或显式传入
+- **BaseURL**: 自动检测运行环境，或通过 `environment` 参数指定
+- **环境变量**: Node.js 环境支持 `DATA_SDK_BASE_URL` 覆盖默认配置
+
+**支持的环境类型：**
+```typescript
+environment?: 'production' | 'staging' | 'development' | 'local'
+```
 
-> 💡 **最佳实践**：
-> - data-sdk 通过 PostMessage 协议与父页面通信获取配置
-> - 父页面需要监听并响应 `seaverse:get_token` 和 `seaverse:get_appId` 消息
-> - 适用于 iframe 嵌入场景，实现安全的跨域配置传递
+> 💡 **iframe 集成提示**：在 iframe 中使用时，SDK 会通过 PostMessage 与父页面通信获取配置（token、appId、环境标识），无需手动传递。
 
 ## API 文档
 
-### DataClient 方法
+### 函数式 API（推荐 ⭐）
 
-使用 `DataClient.create()` 或 `new DataClient(options)` 创建实例后可用的方法：
+零配置，直接导入使用：
+
+```typescript
+import {
+  query,              // 查询数据
+  get,                // 获取单条数据
+  create,             // 创建数据
+  update,             // 更新数据
+  deleteData,         // 删除单条数据
+  batchDelete,        // 批量删除
+  queryWithPagination,// 分页查询
+  isAdmin,            // 检查管理员权限
+  reinit,             // 重新初始化（切换用户/应用）
+  getClientStatus,    // 获取客户端状态
+} from '@seaverse/data-sdk';
+```
+
+| 函数 | 说明 | 参数 | 返回值 |
+|------|------|------|--------|
+| `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>` |
+| `deleteData(id)` | 删除数据 | `id: string` | `Promise<void>` |
+| `batchDelete(ids)` | 批量删除 | `ids: string[]` | `Promise<void>` |
+| `queryWithPagination(options)` | 查询带分页信息 | `QueryOptions` | `Promise<PaginatedResponse<DataRecord>>` |
+| `isAdmin()` | 检查管理员权限 | - | `Promise<boolean>` |
+| `reinit(options?)` | 重新初始化 | `DataClientOptions?` | `Promise<void>` |
+| `getClientStatus()` | 获取客户端状态 | - | `ClientStatus` |
+
+**使用示例：**
+
+```typescript
+// 查询数据
+const notes = await query({ table_name: 'notes' });
+
+// 创建数据
+const note = await create({
+  table_name: 'notes',
+  data_value: { title: 'Hello' },
+});
+
+// 重新初始化（用户登录后切换 token）
+await reinit({ token: newToken });
+
+// 检查初始化状态
+const status = getClientStatus();
+console.log('已初始化:', status.initialized);
+```
+
+### DataClient 类 API（高级场景）
+
+使用 `DataClient.connect()` 创建实例后可用的方法：
 
 | 方法 | 说明 | 参数 | 返回值 |
 |------|------|------|--------|
@@ -400,7 +461,43 @@ const notes = await client.query({ table_name: 'notes' });
 
 ### 无缝接入场景
 
-#### React 应用中使用
+#### React 应用中使用（推荐：函数式 API）
+
+```typescript
+import { query, create, update } from '@seaverse/data-sdk';
+import { useEffect, useState } from 'react';
+
+function NotesApp() {
+  const [notes, setNotes] = useState([]);
+
+  useEffect(() => {
+    // 直接调用函数，首次调用会自动初始化 SDK
+    loadNotes();
+  }, []);
+
+  const loadNotes = async () => {
+    // 无需初始化，直接使用
+    const data = await query({
+      table_name: 'notes',
+      order: { field: 'created_at', direction: 'desc' },
+    });
+    setNotes(data);
+  };
+
+  const addNote = async (title: string) => {
+    const newNote = await create({
+      table_name: 'notes',
+      data_value: { title },
+      visibility: 'private',
+    });
+    setNotes([newNote, ...notes]);
+  };
+
+  return <div>...</div>;
+}
+```
+
+**React 应用中使用（DataClient 类 - 多实例场景）：**
 
 ```typescript
 import { DataClient } from '@seaverse/data-sdk';
@@ -411,18 +508,15 @@ function App() {
 
   useEffect(() => {
     // 应用启动时初始化客户端
-    // SDK 会自动通过 PostMessage 从父页面获取配置
-    DataClient.create({ debug: true }).then(setClient);
+    DataClient.connect({ debug: true }).then(setClient);
   }, []);
 
   const loadNotes = async () => {
     if (!client) return [];
-
-    const notes = await client.query({
+    return await client.query({
       table_name: 'notes',
       order: { field: 'created_at', direction: 'desc' },
     });
-    return notes;
   };
 
   return <div>...</div>;
@@ -479,13 +573,27 @@ window.addEventListener('message', (event) => {
 });
 ```
 
-**iframe 页面（自动获取）：**
+**iframe 页面（自动获取） - 推荐：函数式 API：**
+
+```typescript
+import { query, create } from '@seaverse/data-sdk';
+
+// 直接使用，SDK 会自动通过 PostMessage 从父页面获取 appId 和 token
+const notes = await query({ table_name: 'notes' });
+
+const newNote = await create({
+  table_name: 'notes',
+  data_value: { title: 'Hello' },
+});
+```
+
+**iframe 页面 - DataClient 类：**
 
 ```typescript
 import { DataClient } from '@seaverse/data-sdk';
 
-// 零配置创建客户端，SDK 会自动通过 PostMessage 从父页面获取 appId 和 token
-const client = await DataClient.create();
+// 零配置创建客户端
+const client = await DataClient.connect();
 const notes = await client.query({ table_name: 'notes' });
 ```
 
@@ -520,6 +628,20 @@ export async function getServerSideProps() {
 
 ### 动态更新 Token
 
+**函数式 API（推荐）：**
+
+```typescript
+import { reinit } from '@seaverse/data-sdk';
+
+// 用户登录后，使用新 token
+await reinit({ token: newToken });
+
+// 完全重置（重新从 PostMessage 获取）
+await reinit();
+```
+
+**DataClient 类：**
+
 ```typescript
 // JWT 过期后更新 token
 client.updateToken('new-jwt-token');
@@ -527,6 +649,17 @@ client.updateToken('new-jwt-token');
 
 ### 切换应用
 
+**函数式 API（推荐）：**
+
+```typescript
+import { reinit } from '@seaverse/data-sdk';
+
+// 切换到其他应用
+await reinit({ appId: 'another-app', token: anotherToken });
+```
+
+**DataClient 类：**
+
 ```typescript
 // 切换到其他应用
 client.updateAppId('another-app-id');
@@ -534,9 +667,13 @@ client.updateAppId('another-app-id');
 
 ### JSONB 字段查询
 
+**函数式 API（推荐）：**
+
 ```typescript
+import { query } from '@seaverse/data-sdk';
+
 // 查询 data_value 中的字段
-const results = await client.query({
+const results = await query({
   table_name: 'posts',
   filters: {
     data_value: {
@@ -547,11 +684,26 @@ const results = await client.query({
 });
 ```
 
+**DataClient 类：**
+
+```typescript
+const results = await client.query({
+  table_name: 'posts',
+  filters: {
+    data_value: { title: 'Hello World', author: 'Alice' },
+  },
+});
+```
+
 ### 标签查询
 
+**函数式 API（推荐）：**
+
 ```typescript
+import { query } from '@seaverse/data-sdk';
+
 // 查询包含指定标签的数据
-const results = await client.query({
+const results = await query({
   table_name: 'posts',
   filters: {
     tags: ['javascript', 'typescript'], // 包含任一标签
@@ -561,9 +713,13 @@ const results = await client.query({
 
 ### 时间范围查询
 
+**函数式 API（推荐）：**
+
 ```typescript
+import { query } from '@seaverse/data-sdk';
+
 // 查询指定时间范围的数据
-const results = await client.query({
+const results = await query({
   table_name: 'logs',
   filters: {
     created_after: '2026-01-01T00:00:00Z',
@@ -574,9 +730,13 @@ const results = await client.query({
 
 ### 分页查询
 
+**函数式 API（推荐）：**
+
 ```typescript
+import { queryWithPagination } from '@seaverse/data-sdk';
+
 // 查询带总数的分页数据
-const result = await client.queryWithPagination({
+const result = await queryWithPagination({
   table_name: 'posts',
   pagination: { limit: 10, offset: 0 },
 });
@@ -585,6 +745,15 @@ console.log(`总共 ${result.total} 条，当前返回 ${result.data.length} 条
 console.log(`是否还有更多: ${result.hasMore}`);
 ```
 
+**DataClient 类：**
+
+```typescript
+const result = await client.queryWithPagination({
+  table_name: 'posts',
+  pagination: { limit: 10, offset: 0 },
+});
+```
+
 ## 性能说明
 
 基于新的 RLS 架构，SDK 具有以下性能特性：
@@ -594,6 +763,22 @@ console.log(`是否还有更多: ${result.hasMore}`);
 - ⚡ **短路求值**：优先检查 visibility 和 owner
 - ⚡ **哈希分区**：256 个分区，支持并行查询
 
+## 核心概念
+
+### App ID 是什么？
+
+**App ID** 是您在 SeaVerse 平台上创建的应用的唯一标识符。它用于：
+- ✅ 多租户数据隔离（每个应用的数据互不干扰）
+- ✅ 权限控制（RLS 策略基于 app_id）
+- ✅ 资源配额管理
+
+**如何获取 App ID？**
+1. 登录 [SeaVerse 控制台](https://console.seaverse.ai)
+2. 进入"应用管理"
+3. 复制您的 App ID
+
+> ⚠️ **重要**：所有 SDK 操作都需要提供有效的 `appId`，否则无法访问数据。
+
 ## 架构说明
 
 ### JWT Token 架构
@@ -635,6 +820,43 @@ psql -h <host> -U postgres -d <database> -f init/init-schema.sql
 
 ## 版本历史
 
+### v0.3.0 (2026-01-19)
+
+**🎉 重大功能更新**
+
+- ✅ **新增函数式 API**（推荐使用 ⭐）：提供 `query()`, `create()`, `update()`, `deleteData()` 等零配置便捷函数
+- ✅ **零配置优先**：首次调用函数时自动初始化 SDK（通过 PostMessage 获取配置）
+- ✅ **全局单例管理**：自动懒加载初始化，防止并发初始化问题
+- ✅ **新增 `DataClient.connect()`**：语义更清晰的连接方法（推荐使用，`create()` 保留作为别名）
+- ✅ **新增 `reinit()` 函数**：支持重新初始化（用于切换用户 token 或应用 appId）
+- ✅ **新增 `getClientStatus()` 函数**：查询客户端初始化状态
+
+**使用方式对比：**
+
+```typescript
+// ⭐ 方式 1: 函数式 API（推荐 - 最简单）
+import { query, create } from '@seaverse/data-sdk';
+const notes = await query({ table_name: 'notes' });
+
+// 方式 2: DataClient 类（高级场景 - 多实例）
+import { DataClient } from '@seaverse/data-sdk';
+const client = await DataClient.connect();
+const notes = await client.query({ table_name: 'notes' });
+```
+
+**架构改进：**
+
+- 新增 `src/singleton.ts` - 全局单例管理
+- 新增 `src/api.ts` - 函数式 API 封装
+- 优化 `src/client.ts` - 添加 `connect()` 方法
+- 更新 `src/index.ts` - 统一导出函数式 API 和类 API
+
+**向后兼容：**
+
+- ✅ `DataClient.create()` 方法保留（现为 `connect()` 的别名）
+- ✅ 所有原有的类方法继续支持
+- ✅ 无需修改现有代码，完全向后兼容
+
 ### v0.2.0 (2026-01-15)
 
 **🔄 重大变更（Breaking Changes）**