@seaverse/data-sdk 0.1.1 → 0.1.3

package/README.md

@@ -31,6 +31,9 @@
 - ✅ 完整的错误处理
 - ✅ 支持过滤、排序、分页
 - ✅ 支持标签和 JSONB 字段查询
+- ✅ **无缝接入** - 自动从 localStorage/PostMessage 获取配置
+- ✅ **零配置使用** - 可选的初始化，支持开箱即用
+- ✅ **函数式 API** - 提供便捷的函数调用方式
 
 ## 安装
 
@@ -40,120 +43,145 @@ npm install @seaverse/data-sdk
 
 ## 快速开始
 
-### 1. 初始化 SDK
+### 两种使用方式
 
-SDK 提供三种初始化方式，根据您的使用场景选择：
+#### 方式 A：函数式 API（推荐 - 零配置）
+
+**适合 SeaVerse 平台应用** - SDK 自动从 localStorage 获取配置，无需手动初始化
+
+```typescript
+import { query, create, update, deleteData } from '@seaverse/data-sdk';
+
+// 直接使用，无需初始化！
+// SDK 自动从 localStorage.auth_token 和 localStorage.app_id 获取配置
+
+// 查询数据
+const notes = await query({
+  table: 'notes',
+  filters: { category: 'work' },
+  order: { field: 'created_at', direction: 'desc' },
+});
+
+// 创建数据
+const newNote = await create({
+  table: 'notes',
+  data: { title: 'My Note', content: '...' },
+  visibility: 'private',
+});
+
+// 更新数据
+await update('note-id-123', {
+  data: { title: 'Updated' },
+});
+
+// 删除数据
+await deleteData('note-id-123');
+```
+
+**可选初始化（如需自定义配置）：**
+
+```typescript
+import { initData, query } from '@seaverse/data-sdk';
+
+// 可选：在应用启动时初始化
+await initData({
+  appId: 'my-app-123',      // 可选，未提供则从 localStorage 读取
+  token: 'user-jwt-token',   // 可选，未提供则从 localStorage 读取
+  debug: true,               // 可选
+});
+
+// 然后直接使用
+const notes = await query({ table: 'notes' });
+```
+
+#### 方式 B：类实例 API（传统方式）
+
+**适合需要多个实例或完全自定义配置的场景**
 
 ```typescript
 import { DataClient } from '@seaverse/data-sdk';
 
-// 方式1: SeaVerse 平台应用（自动检测环境）- 推荐
-// 适用于部署在 SeaVerse 平台的应用
+// 方式1: SeaVerse 平台应用（自动检测环境）
 const client = new DataClient({
-  appId: 'my-app-123',         // 必需：应用ID
-  token: 'user-jwt-token',      // 必需：用户JWT token
+  appId: 'my-app-123',
+  token: 'user-jwt-token',
 });
 
-// 方式2: 第三方应用（指定环境）
-// 适用于非 SeaVerse 平台或需要明确指定环境的应用
+// 方式2: 指定环境
 const client = new DataClient({
   appId: 'my-app-123',
   token: 'user-jwt-token',
-  environment: 'production',    // 可选：'production' | 'staging' | 'development' | 'local'
+  environment: 'production',    // 'production' | 'staging' | 'development' | 'local'
 });
 
-// 方式3: 完全自定义（自定义 baseURL）
-// 适用于私有部署或特殊环境
+// 方式3: 完全自定义
 const client = new DataClient({
   appId: 'my-app-123',
   token: 'user-jwt-token',
-  baseURL: 'https://custom-api.example.com', // 自定义API地址
+  baseURL: 'https://custom-api.example.com',
 });
+
+// 使用 client 实例
+const notes = await client.query({ table: 'notes' });
 ```
 
 **配置选项说明：**
 
 | 参数 | 类型 | 必需 | 说明 |
 |-----|------|------|------|
-| `appId` | string | ✅ | 应用ID，从控制台获取 |
-| `token` | string | ✅ | 用户JWT token，用于身份验证 |
+| `appId` | string | ⬜️ | 应用ID，未提供则从 localStorage/环境变量获取 |
+| `token` | string | ⬜️ | 用户JWT token，未提供则从 localStorage/环境变量获取 |
 | `baseURL` | string | ⬜️ | 自定义API地址，优先级最高 |
 | `environment` | Environment | ⬜️ | 环境类型，当未提供baseURL时使用 |
 | `timeout` | number | ⬜️ | 请求超时时间（毫秒），默认10000 |
 | `headers` | object | ⬜️ | 自定义请求头 |
 | `debug` | boolean | ⬜️ | 是否开启调试日志 |
 
-### 2. 查询数据
+### 配置自动获取规则
 
-```typescript
-// 查询列表
-const notes = await client.query({
-  table: 'notes',
-  filters: {
-    category: 'work',
-    visibility: 'private',
-  },
-  order: {
-    field: 'created_at',
-    direction: 'desc',
-  },
-  pagination: {
-    limit: 20,
-    offset: 0,
-  },
-});
+**Token 自动获取（推荐）：**
+SDK 会按照以下优先级自动获取 token：
+1. 显式传入的 `token` 参数
+2. `localStorage.getItem('token')` - **auth-sdk 标准 key**
+3. `localStorage.getItem('auth_token')` - 向后兼容
+4. PostMessage 从父窗口获取（iframe 场景）
+5. 环境变量 `process.env.DATA_SDK_TOKEN`
 
-// 查询单条
-const note = await client.get('note-id-123');
-```
+> 💡 **最佳实践**：使用 `@seaverse/auth-sdk` 进行登录，token 会自动存储到 `localStorage.token`，data-sdk 会自动读取。
 
-### 3. 创建数据
+**AppId 必须明确提供：**
+`appId` 必须由用户在初始化时明确提供，不会自动获取：
+- 通过 `initData({ appId: 'xxx' })` 提供
+- 或通过 `new DataClient({ appId: 'xxx' })` 提供
 
-```typescript
-const newNote = await client.create({
-  table: 'notes',
-  data: {
-    title: '我的笔记',
-    content: '笔记内容...',
-  },
-  visibility: 'private',
-  category: 'work',
-  tags: ['important', 'todo'],
-});
-```
-
-### 4. 更新数据
-
-```typescript
-const updated = await client.update('note-id-123', {
-  data: {
-    title: '更新的标题',
-    content: '更新的内容',
-  },
-  category: 'personal',
-});
-```
-
-### 5. 删除数据
+## API 文档
 
-```typescript
-// 删除单条
-await client.delete('note-id-123');
+### 初始化和配置 API
 
-// 批量删除
-await client.batchDelete(['id-1', 'id-2', 'id-3']);
-```
+| 方法 | 说明 | 参数 | 返回值 |
+|------|------|------|--------|
+| `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` |
 
-### 6. 管理员操作
+### 数据操作 API（函数式）
 
-```typescript
-// 检查是否是管理员
-const isAdmin = await client.isAdmin();
-```
+| 方法 | 说明 | 参数 | 返回值 |
+|------|------|------|--------|
+| `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>` |
 
-## API 文档
+### DataClient 类方法
 
-### API 概览
+使用 `new DataClient(options)` 创建实例后可用的方法：
 
 | 方法 | 说明 | 参数 | 返回值 |
 |------|------|------|--------|
@@ -165,10 +193,10 @@ const isAdmin = await client.isAdmin();
 | `batchDelete(ids)` | 批量删除 | `ids: string[]` | `Promise<void>` |
 | `queryWithPagination(options)` | 查询带分页信息 | `QueryOptions` | `Promise<PaginatedResponse<DataRecord>>` |
 | `isAdmin()` | 检查管理员权限 | - | `Promise<boolean>` |
-| `updateToken(token)` | 更新JWT token | `token: string` | `void` |
-| `updateAppId(appId)` | 更新应用ID | `appId: string` | `void` |
-| `getAppId()` | 获取当前应用ID | - | `string` |
-| `getUserId()` | 获取当前用户ID | - | `string` |
+| `updateToken(token)` | 更新实例 token | `token: string` | `void` |
+| `updateAppId(appId)` | 更新实例 appId | `appId: string` | `void` |
+| `getAppId()` | 获取实例 appId | - | `string` |
+| `getUserId()` | 获取当前用户 ID | - | `string` |
 
 ### 查询选项（QueryOptions）
 
@@ -267,20 +295,160 @@ try {
 
 ## 高级用法
 
+### 与 auth-sdk 集成（推荐）
+
+data-sdk 会自动从 auth-sdk 设置的 token 中读取认证信息：
+
+```typescript
+import { SeaVerseBackendAPIClient } from '@seaverse/auth-sdk';
+import { query, create } from '@seaverse/data-sdk';
+
+// 1. 使用 auth-sdk 登录
+const authClient = new SeaVerseBackendAPIClient({
+  appId: 'my-app-123',
+});
+
+const loginResult = await authClient.login({
+  email: 'user@example.com',
+  password: 'password',
+});
+
+// auth-sdk 会自动将 token 存储到 localStorage.token
+localStorage.setItem('token', loginResult.token);
+localStorage.setItem('app_id', 'my-app-123');
+
+// 2. data-sdk 自动读取 token，无需手动传递
+const notes = await query({
+  table: 'notes',
+  filters: { category: 'work' },
+});
+
+// 3. 创建数据
+const newNote = await create({
+  table: 'notes',
+  data: { title: 'My Note', content: '...' },
+  visibility: 'private',
+});
+```
+
+### 无缝接入场景
+
+#### React 应用中使用
+
+```typescript
+import { initData, query, create, updateToken } from '@seaverse/data-sdk';
+import { useEffect } from 'react';
+
+function App() {
+  useEffect(() => {
+    // 可选：应用启动时初始化（如果 localStorage 已有配置可省略）
+    const token = localStorage.getItem('auth_token');
+    const appId = localStorage.getItem('app_id');
+
+    if (token && appId) {
+      initData({ token, appId, debug: true });
+    }
+  }, []);
+
+  const loadNotes = async () => {
+    // 直接使用，无需传递 client 实例
+    const notes = await query({
+      table: 'notes',
+      order: { field: 'created_at', direction: 'desc' },
+    });
+    return notes;
+  };
+
+  return <div>...</div>;
+}
+```
+
+#### iframe 嵌入场景
+
+**父页面（提供配置）：**
+
+```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'),
+    }, '*');
+  }
+
+  if (event.data.type === 'DATA_SDK_APP_ID_REQUEST') {
+    event.source.postMessage({
+      type: 'DATA_SDK_APP_ID_RESPONSE',
+      appId: localStorage.getItem('app_id'),
+    }, '*');
+  }
+});
+```
+
+**iframe 页面（自动获取）：**
+
+```typescript
+import { query } from '@seaverse/data-sdk';
+
+// 直接使用，SDK 会自动通过 PostMessage 从父页面获取配置
+const notes = await query({ table: 'notes' });
+```
+
+#### 服务端渲染（SSR/SSG）
+
+```typescript
+import { query } from '@seaverse/data-sdk';
+
+// 通过环境变量提供配置
+// .env 文件：
+// DATA_SDK_TOKEN=your-jwt-token
+// DATA_SDK_APP_ID=your-app-id
+
+export async function getServerSideProps() {
+  // SDK 自动从环境变量读取配置
+  const notes = await query({
+    table: 'notes',
+    filters: { visibility: 'public' },
+  });
+
+  return { props: { notes } };
+}
+```
+
 ### 动态更新 Token
 
 ```typescript
-// JWT 过期后更新 token
+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');
 ```
 
+### 清除配置（登出场景）
+
+```typescript
+import { clearConfig } from '@seaverse/data-sdk';
+
+// 用户登出时清除所有配置
+clearConfig();
+```
+
 ### JSONB 字段查询
 
 ```typescript
@@ -343,47 +511,74 @@ console.log(`是否还有更多: ${result.hasMore}`);
 - ⚡ **短路求值**：优先检查 visibility 和 owner
 - ⚡ **哈希分区**：256 个分区，支持并行查询
 
-## 环境配置
-
-SDK 支持多环境部署，根据不同的使用场景灵活配置。
+## 架构说明
 
-### 预设环境
+### JWT Token 架构
 
-| Environment | baseURL | 适用场景 | 自动检测规则 |
-|-------------|---------|----------|-------------|
-| **production** | `https://data.seaverse.ai` | 生产环境 | 默认环境 |
-| **staging** | `https://data.sg.seaverse.dev` | 预发布环境 | hostname 包含 `staging` |
-| **development** | `https://data-dev.seaverse.dev` | 开发测试 | hostname 包含 `-dev` 或 `.dev` |
-| **local** | `http://localhost:3000` | 本地开发 | hostname 是 `localhost` 或 `127.0.0.1` |
+Data SDK 采用标准的 JWT 认证机制：
 
-### 配置优先级
+**Token 结构：**
+```json
+{
+  "sub": "user-id-123",           // 用户ID（JWT标准字段）
+  "iat": 1736832000,              // 签发时间
+  "exp": 1736918400               // 过期时间
+}
+```
 
-SDK 按以下优先级选择 API 端点：
+**重要说明：**
+- ✅ Token 中**只包含用户身份信息**（`sub` 或 `payload.user_id`）
+- ✅ Token 在用户登录时生成，具有固定的有效期
+- ❌ Token 中**不包含** `app_id`（因为 app_id 是动态的，用户可能访问多个应用）
+- ✅ `app_id` 通过 SDK 在每次请求时传递
 
-1. **显式 `baseURL`** - 最高优先级，直接使用指定的URL
-2. **`environment` 参数** - 使用预设环境配置
-3. **自动检测** - 最低优先级，根据 hostname 自动判断
+### 多租户隔离架构
 
-### 使用示例
+**隔离层级：**
+1. **应用隔离**：`app_id` - 同一用户在不同应用的数据相互隔离
+2. **用户隔离**：`user_id` - 同一应用内不同用户的私密数据相互隔离
+3. **可见性控制**：`visibility` - 支持 public/private 数据共享
 
-参见"快速开始 → 初始化 SDK"部分的三种初始化方式。
+## 数据库初始化
 
-## 错误码说明
+如果你需要自己部署数据库，请参考：
 
-SDK 提供了详细的错误码，方便问题诊断：
+```bash
+# 初始化数据库
+psql -h <host> -U postgres -d <database> -f init/init-schema.sql
+```
 
-| 错误码 | HTTP状态码 | 说明 | 解决方法 |
-|--------|-----------|------|---------|
-| `REQUEST_FAILED` | 4xx/5xx | 请求失败 | 检查请求参数和服务器状态 |
-| `TIMEOUT` | - | 请求超时 | 增加 timeout 配置或检查网络 |
-| `NETWORK_ERROR` | - | 网络错误 | 检查网络连接 |
-| `INVALID_TOKEN` | 401 | Token无效或过期 | 使用 `updateToken()` 更新token |
-| `NOT_FOUND` | 404 | 数据不存在或无权限 | 检查数据ID和权限 |
-| `PERMISSION_DENIED` | 403 | 权限不足 | 确认用户有相应权限 |
-| `VALIDATION_ERROR` | 400 | 参数验证失败 | 检查请求参数格式 |
+详细说明请查看 `init/README.md`。
 
 ## 版本历史
 
+### v0.1.3 (2026-01-14)
+
+**🔧 配置优化**
+
+- ✅ **Token 获取优化**：优先从 `localStorage.token` 读取（auth-sdk 标准 key）
+- ✅ **AppId 要求明确**：移除自动获取 appId 的功能，必须由用户明确提供
+- ✅ 简化配置逻辑：减少不必要的自动推断
+
+### v0.1.2 (2026-01-14)
+
+**🎉 无缝接入功能更新**
+
+- ✅ 新增函数式 API：`query()`, `create()`, `update()` 等便捷函数
+- ✅ 可选初始化：支持 `initData()` 或零配置直接使用
+- ✅ 自动 Token 获取：从 localStorage/PostMessage/环境变量自动获取
+- ✅ iframe 支持：通过 PostMessage 协议支持跨窗口通信
+- ✅ 全局配置管理：`updateToken()`, `updateAppId()`, `clearConfig()`
+- ✅ 完整向后兼容：保留 DataClient 类 API
+
+### v0.1.1 (2026-01-14)
+
+**🔧 配置更新**
+
+- ✅ 简化架构：JWT 只包含 user_id
+- ✅ RLS 策略优化：只检查用户权限
+- ✅ 性能提升：查询速度提升 1700 倍
+
 ### v0.1.0 (2026-01-10)
 
 **🎉 首个版本发布**
@@ -392,9 +587,7 @@ SDK 提供了详细的错误码，方便问题诊断：
 - ✅ 完整的 CRUD 操作支持
 - ✅ 多环境配置与自动检测
 - ✅ 分页查询支持
-- ✅ 管理员权限检查
 - ✅ TypeScript 类型定义
-- ✅ 完整的错误处理
 
 ## 相关资源