@seaverse/data-sdk 0.2.6 → 0.3.1

package/README.md

@@ -32,6 +32,7 @@
 - ✅ 支持过滤、排序、分页
 - ✅ 支持标签和 JSONB 字段查询
 - ✅ **零配置使用** - 自动从 PostMessage 获取配置
+- ✅ **自动配额限制** - 数据库层强制执行配额，防止资源滥用
 
 ## 安装
 
@@ -41,20 +42,63 @@ npm install @seaverse/data-sdk
 
 ## 快速开始
 
-### 使用 DataClient
+### 方式1: 函数式 API（推荐 ⭐）
+
+最简单的使用方式 - 零配置，直接调用函数：
+
+```typescript
+import { query, create, update, deleteData } from '@seaverse/data-sdk';
+
+// 第一次调用自动初始化 SDK（从 PostMessage 获取 appId 和 token）
+// 无需任何配置代码！
+
+// 查询数据
+const notes = await query({
+  table_name: 'notes',
+  filters: { category: 'work' },
+  order: { field: 'created_at', direction: 'desc' }
+});
+
+// 创建数据
+const newNote = await create({
+  table_name: 'notes',
+  data_value: { title: 'My Note', content: '...' },
+  visibility: 'private'
+});
+
+// 更新数据
+await update(newNote.id, {
+  data_value: { title: 'Updated Title' }
+});
+
+// 删除数据
+await deleteData(newNote.id);
+```
+
+**为什么推荐函数式 API：**
+- ✅ **零配置** - 无需创建客户端实例，直接调用函数
+- ✅ **自动初始化** - 第一次调用自动获取配置（PostMessage）
+- ✅ **代码简洁** - 代码更简洁，更易理解
+- ✅ **单例管理** - SDK 自动管理全局实例，避免重复初始化
+
+---
+
+### 方式2: DataClient 类 API（高级场景）
+
+适用于需要多个实例或自定义配置的场景：
 
 ```typescript
 import { DataClient } from '@seaverse/data-sdk';
 
-// 方式1: 零配置（推荐）- 自动从 PostMessage 获取 appId 和 token
+// 方式2a: 零配置（推荐）- 自动从 PostMessage 获取 appId 和 token
 const client = await DataClient.create();
 
-// 方式2: 只提供 appId，token 自动获取
+// 方式2b: 只提供 appId，token 自动获取
 const client = await DataClient.create({
   appId: 'my-app-123',
 });
 
-// 方式3: 显式提供所有配置
+// 方式2c: 显式提供所有配置
 const client = new DataClient({
   appId: 'my-app-123',
   token: 'user-jwt-token',
@@ -64,23 +108,7 @@ const client = new DataClient({
 const notes = await client.query({
   table_name: 'notes',
   filters: { category: 'work' },
-  order: { field: 'created_at', direction: 'desc' },
-});
-
-// 创建数据
-const newNote = await client.create({
-  table_name: 'notes',
-  data_value: { title: 'My Note', content: '...' },
-  visibility: 'private',
 });
-
-// 更新数据
-await client.update('note-id-123', {
-  data_value: { title: 'Updated' },
-});
-
-// 删除数据
-await client.delete('note-id-123');
 ```
 
 **配置选项说明：**
@@ -530,6 +558,86 @@ client.updateToken('new-jwt-token');
 client.updateAppId('another-app-id');
 ```
 
+### 配额限制
+
+Data SDK 在数据库层实现了自动配额限制，防止单个应用占用过多资源。
+
+#### 配额说明
+
+SDK 支持以下配额限制（在数据库层通过触发器强制执行，无法绕过）：
+
+| 配额类型 | 默认值 | 说明 |
+|---------|-------|------|
+| 总数据条数 | 100,000 条 | 单个应用的最大数据总量 |
+| 单表数据条数 | 50,000 条 | 单个 table_name 的最大数据量 |
+| 存储空间 | 1 GB | 单个应用的最大存储空间 |
+| 每分钟操作 | 1,000 次 | 防止短时间内大量操作 |
+| 每小时操作 | 10,000 次 | 防止持续高频操作 |
+| 每天操作 | 100,000 次 | 防止每日滥用 |
+
+**配额检查机制：**
+- 创建操作（CREATE）：检查数据总量、单表数据量、存储空间、操作频率
+- 更新操作（UPDATE）：检查存储空间变化、操作频率
+- 删除操作（DELETE）：检查操作频率
+
+超限时会自动抛出错误，操作被拒绝并回滚。
+
+#### 错误处理
+
+```typescript
+try {
+  await client.create({
+    table_name: 'notes',
+    data_value: { title: 'New Note' },
+  });
+} catch (error) {
+  // 检查是否是配额超限错误
+  if (error.message && error.message.includes('Quota exceeded')) {
+    console.error('配额超限:', error.message);
+    // 示例错误信息：
+    // "Quota exceeded: Total records quota exceeded: 100000/100000 records"
+    // "Quota exceeded: Storage quota exceeded: 1024.5 MB/1024 MB"
+    // "Quota exceeded: Rate limit exceeded: 1234/1000 operations in last minute"
+  } else {
+    console.error('操作失败:', error);
+  }
+}
+```
+
+#### 平台管理员监控
+
+配额的监控和调整由平台管理员通过数据库查询完成：
+
+```sql
+-- 查看所有应用的使用情况
+SELECT
+  u.app_id,
+  u.total_records,
+  ROUND(u.total_storage_bytes::numeric / 1024 / 1024, 2) as storage_mb,
+  q.max_total_records,
+  ROUND((u.total_records::numeric / q.max_total_records * 100), 2) as usage_percent
+FROM app_usage_stats u
+LEFT JOIN app_quotas q ON u.app_id = q.app_id
+ORDER BY usage_percent DESC;
+
+-- 查找接近配额的应用（预警）
+SELECT app_id, usage_percent
+FROM (
+  SELECT
+    u.app_id,
+    ROUND((u.total_records::numeric / q.max_total_records * 100), 2) as usage_percent
+  FROM app_usage_stats u
+  INNER JOIN app_quotas q ON u.app_id = q.app_id
+) t
+WHERE usage_percent > 80;
+
+-- 为应用调整配额
+UPDATE app_quotas
+SET max_total_records = 500000,
+    max_storage_bytes = 5368709120  -- 5GB
+WHERE app_id = 'your-app-id';
+```
+
 ### JSONB 字段查询
 
 ```typescript

package/dist/index.cjs

@@ -160,52 +160,6 @@ function resolveBaseURL(options) {
     const detectedEnv = detectEnvironment();
     return ENVIRONMENT_CONFIGS[detectedEnv].baseURL;
 }
-/**
- * 解析用户配置，返回最终的 baseURL（异步版本）
- *
- * 优先级：
- * 1. 显式传入的 baseURL（最高优先级）
- * 2. 环境变量 DATA_SDK_BASE_URL
- * 3. environment 参数指定的环境
- * 4. iframe 环境 - 从父页面获取环境标识
- *    - 父页面返回 'develop' → development 环境
- *    - 父页面返回 'production' → production 环境
- *    - 父页面返回其他值 → 自动检测环境
- * 5. 非 iframe 环境 - 自动检测环境
- *
- * @param options 用户配置选项
- * @returns 最终使用的 baseURL
- */
-async function resolveBaseURLAsync(options) {
-    // 优先级 1: 显式传入的 baseURL
-    if (options.baseURL) {
-        return options.baseURL;
-    }
-    // 优先级 2: 环境变量 DATA_SDK_BASE_URL
-    if (typeof process !== 'undefined' && process.env?.DATA_SDK_BASE_URL) {
-        return process.env.DATA_SDK_BASE_URL;
-    }
-    // 优先级 3: environment 参数
-    if (options.environment) {
-        return ENVIRONMENT_CONFIGS[options.environment].baseURL;
-    }
-    // 优先级 4: iframe 环境 - 从父页面获取环境标识
-    if (isInIframe()) {
-        const parentEnv = await getEnvFromParent(3000);
-        if (parentEnv === 'develop') {
-            console.log('[DataSDK] iframe 环境：父页面返回开发环境，使用 development baseURL');
-            return ENVIRONMENT_CONFIGS.development.baseURL;
-        }
-        else if (parentEnv === 'production') {
-            console.log('[DataSDK] iframe 环境：父页面返回生产环境，使用 production baseURL');
-            return ENVIRONMENT_CONFIGS.production.baseURL;
-        }
-        // 如果获取到其他值或没有获取到，继续自动检测
-    }
-    // 优先级 5: 自动检测环境
-    const detectedEnv = detectEnvironment();
-    return ENVIRONMENT_CONFIGS[detectedEnv].baseURL;
-}
 /**
  * 默认超时时间（毫秒）
  */
@@ -338,59 +292,6 @@ async function getAppIdFromParent(timeout = 5000) {
         }
     });
 }
-/**
- * 通过 PostMessage 从父页面获取环境标识
- *
- * 此函数允许接收来自任何源的 PostMessage 消息，便于跨域 iframe 集成。
- * 使用 seaverse 协议与父页面通信：
- * - 发送: { type: 'seaverse:get_env' }
- * - 接收: { type: 'seaverse:env', payload: { env: string } }
- * - 错误: { type: 'seaverse:error', error: string }
- *
- * @param timeout 超时时间（毫秒），默认 5000ms
- * @returns 环境标识字符串 (如 "develop", "production") 或 null
- */
-async function getEnvFromParent(timeout = 5000) {
-    if (!isInIframe()) {
-        return null;
-    }
-    return new Promise((resolve) => {
-        const messageHandler = (event) => {
-            // 验证消息格式
-            if (event.data && event.data.type === 'seaverse:env') {
-                cleanup();
-                // 从 payload.env 中获取环境标识
-                const env = event.data.payload?.env;
-                resolve(env || null);
-            }
-            else if (event.data && event.data.type === 'seaverse:error') {
-                // 处理错误响应
-                cleanup();
-                console.warn('[DataSDK] Error getting env from parent:', event.data.error);
-                resolve(null);
-            }
-        };
-        const timeoutId = setTimeout(() => {
-            cleanup();
-            resolve(null);
-        }, timeout);
-        const cleanup = () => {
-            clearTimeout(timeoutId);
-            globalThis.window.removeEventListener('message', messageHandler);
-        };
-        // 监听父页面的响应（不限制来源）
-        globalThis.window.addEventListener('message', messageHandler);
-        // 向父页面发送请求（允许任何源接收）
-        try {
-            globalThis.window.parent.postMessage({ type: 'seaverse:get_env' }, '*' // 允许任何源，支持跨域场景
-            );
-        }
-        catch (e) {
-            cleanup();
-            resolve(null);
-        }
-    });
-}
 /**
  * 动态获取 API Token
  * 优先级：
@@ -476,40 +377,42 @@ async function getAppId(providedAppId) {
  */
 class DataClient {
     /**
-     * 创建 DataClient 实例（异步工厂方法）
+     * 连接到 Data SDK 服务（推荐 - 零配置优先）
      *
-     * 支持自动从 localStorage/环境变量/PostMessage 获取 appId、token 和 baseURL
+     * 支持自动从 PostMessage 获取 appId 和 token，自动检测环境
      *
-     * @param options - 配置选项（appId 和 token 可选）
+     * @param options - 连接选项（所有参数都是可选的）
      * @returns DataClient 实例
      *
      * @example
      * ```typescript
-     * // 自动获取 appId 和 token，并通过 PostMessage 获取环境配置
-     * const client = await DataClient.create();
+     * // 🎯 零配置（推荐 - 最简单）
+     * const client = await DataClient.connect();
      *
-     * // 提供 appId，自动获取 token
-     * const client = await DataClient.create({ appId: 'my-app-123' });
+     * // 部分配置
+     * const client = await DataClient.connect({
+     *   appId: 'my-app-123'  // 只提供 appId，其他自动获取
+     * });
      *
-     * // 显式提供所有配置
-     * const client = await DataClient.create({
+     * // 完整配置
+     * const client = await DataClient.connect({
      *   appId: 'my-app-123',
      *   token: 'user-jwt-token',
      *   environment: 'production'
      * });
      * ```
      */
-    static async create(options = {}) {
+    static async connect(options = {}) {
         const appId = options.appId || (await getAppId());
         const token = options.token || (await getApiToken());
         if (!appId) {
-            throw new ValidationError('appId is required. Please ensure it is available in localStorage.app_id, provide appId explicitly, or configure parent page to provide it via PostMessage.');
+            throw new ValidationError('appId is required. Please provide it explicitly or configure parent page to send it via PostMessage.');
         }
         if (!token) {
-            throw new ValidationError('token is required. Please ensure it is available in localStorage.auth_token, provide token explicitly, or configure parent page to provide it via PostMessage.');
+            throw new ValidationError('token is required. Please provide it explicitly or configure parent page to send it via PostMessage.');
         }
-        // 使用异步版本解析 baseURL，支持环境变量和 PostMessage
-        const baseURL = await resolveBaseURLAsync({
+        // 解析 baseURL
+        const baseURL = resolveBaseURL({
             baseURL: options.baseURL,
             environment: options.environment,
         });
@@ -517,9 +420,36 @@ class DataClient {
             ...options,
             appId,
             token,
-            baseURL, // 传递已解析的 baseURL
+            baseURL,
         });
     }
+    /**
+     * 创建 DataClient 实例（异步工厂方法）
+     *
+     * @deprecated 推荐使用 connect() 方法
+     * @param options - 配置选项（appId 和 token 可选）
+     * @returns DataClient 实例
+     *
+     * @example
+     * ```typescript
+     * // 自动获取 appId 和 token，并通过 PostMessage 获取环境配置
+     * const client = await DataClient.create();
+     *
+     * // 提供 appId，自动获取 token
+     * const client = await DataClient.create({ appId: 'my-app-123' });
+     *
+     * // 显式提供所有配置
+     * const client = await DataClient.create({
+     *   appId: 'my-app-123',
+     *   token: 'user-jwt-token',
+     *   environment: 'production'
+     * });
+     * ```
+     */
+    static async create(options = {}) {
+        // 直接调用 connect 方法
+        return DataClient.connect(options);
+    }
     constructor(options) {
         const { timeout = DEFAULT_TIMEOUT, headers = {}, appId, token, debug = false, } = options;
         if (!appId) {
@@ -1106,6 +1036,305 @@ class DataClient {
     }
 }
 
+/**
+ * 全局单例管理
+ *
+ * 为函数式 API 提供自动初始化和实例复用能力
+ */
+/**
+ * 全局单例客户端实例
+ */
+let globalClient = null;
+/**
+ * 初始化 Promise（防止并发初始化）
+ */
+let initPromise = null;
+/**
+ * 初始化状态标志
+ */
+let isInitializing = false;
+/**
+ * 获取全局客户端实例（自动初始化）
+ *
+ * 工作流程：
+ * 1. 如果已初始化 → 直接返回实例
+ * 2. 如果正在初始化 → 等待初始化完成
+ * 3. 如果未初始化 → 触发初始化
+ *
+ * @returns DataClient 实例
+ * @throws 如果初始化失败（缺少 appId 或 token）
+ */
+async function getGlobalClient() {
+    // 快速路径：已经初始化完成
+    if (globalClient) {
+        return globalClient;
+    }
+    // 中速路径：正在初始化，等待完成
+    if (initPromise) {
+        return initPromise;
+    }
+    // 慢速路径：首次调用，需要初始化
+    if (!isInitializing) {
+        isInitializing = true;
+        initPromise = (async () => {
+            try {
+                if (process.env.NODE_ENV !== 'production') {
+                    console.log('[DataSDK] 🚀 自动初始化...');
+                }
+                // 调用 DataClient.connect() 进行零配置初始化
+                const client = await DataClient.connect();
+                // 缓存实例
+                globalClient = client;
+                if (process.env.NODE_ENV !== 'production') {
+                    console.log('[DataSDK] ✅ 自动初始化成功');
+                }
+                return client;
+            }
+            catch (error) {
+                if (process.env.NODE_ENV !== 'production') {
+                    console.error('[DataSDK] ❌ 自动初始化失败:', error);
+                }
+                // 重置状态，允许下次重试
+                isInitializing = false;
+                initPromise = null;
+                throw error;
+            }
+        })();
+    }
+    return initPromise;
+}
+/**
+ * 重新初始化全局客户端
+ *
+ * 用于以下场景：
+ * - 用户登录后切换 token
+ * - 切换到其他应用
+ * - 需要更新配置
+ *
+ * @param options 连接选项（可选）
+ *
+ * @example
+ * ```typescript
+ * import { reinit } from '@seaverse/data-sdk';
+ *
+ * // 用户登录后，使用新 token
+ * await reinit({ token: newToken });
+ *
+ * // 切换到其他应用
+ * await reinit({ appId: 'another-app', token: anotherToken });
+ *
+ * // 完全重置（重新从 PostMessage 获取）
+ * await reinit();
+ * ```
+ */
+async function reinit(options = {}) {
+    if (process.env.NODE_ENV !== 'production') {
+        console.log('[DataSDK] 🔄 重新初始化...');
+    }
+    // 清除旧实例和状态
+    globalClient = null;
+    initPromise = null;
+    isInitializing = false;
+    // 创建新实例
+    const client = await DataClient.connect(options);
+    globalClient = client;
+    if (process.env.NODE_ENV !== 'production') {
+        console.log('[DataSDK] ✅ 重新初始化成功');
+    }
+}
+/**
+ * 获取当前客户端状态
+ *
+ * @returns 客户端状态信息
+ *
+ * @example
+ * ```typescript
+ * import { getClientStatus } from '@seaverse/data-sdk';
+ *
+ * const status = getClientStatus();
+ * console.log('是否已初始化:', status.initialized);
+ * console.log('是否正在初始化:', status.initializing);
+ * ```
+ */
+function getClientStatus() {
+    return {
+        initialized: globalClient !== null,
+        initializing: isInitializing,
+        hasInstance: globalClient !== null
+    };
+}
+
+/**
+ * 函数式 API
+ *
+ * 提供零配置的便捷函数，自动管理全局客户端实例
+ */
+/**
+ * 查询数据
+ *
+ * 首次调用会自动初始化 SDK（从 PostMessage 获取配置）
+ *
+ * @param options 查询选项
+ * @returns 数据记录数组
+ *
+ * @example
+ * ```typescript
+ * import { query } from '@seaverse/data-sdk';
+ *
+ * const notes = await query({ table_name: 'notes' });
+ *
+ * const filtered = await query({
+ *   table_name: 'notes',
+ *   filters: { category: 'work' },
+ *   order: { field: 'created_at', direction: 'desc' }
+ * });
+ * ```
+ */
+async function query(options) {
+    const client = await getGlobalClient();
+    return client.query(options);
+}
+/**
+ * 获取单条数据
+ *
+ * @param id 数据 ID
+ * @returns 数据记录，如果不存在返回 null
+ *
+ * @example
+ * ```typescript
+ * import { get } from '@seaverse/data-sdk';
+ *
+ * const note = await get('note-id-123');
+ * if (note) {
+ *   console.log('标题:', note.data_value.title);
+ * }
+ * ```
+ */
+async function get(id) {
+    const client = await getGlobalClient();
+    return client.get(id);
+}
+/**
+ * 创建数据
+ *
+ * @param options 创建选项
+ * @returns 创建的数据记录
+ *
+ * @example
+ * ```typescript
+ * import { create } from '@seaverse/data-sdk';
+ *
+ * const note = await create({
+ *   table_name: 'notes',
+ *   data_value: {
+ *     title: 'Hello',
+ *     content: 'World'
+ *   },
+ *   visibility: 'private',
+ *   tags: ['important']
+ * });
+ * ```
+ */
+async function create(options) {
+    const client = await getGlobalClient();
+    return client.create(options);
+}
+/**
+ * 更新数据
+ *
+ * @param id 数据 ID
+ * @param options 更新选项
+ * @returns 更新后的数据记录
+ *
+ * @example
+ * ```typescript
+ * import { update } from '@seaverse/data-sdk';
+ *
+ * await update('note-id-123', {
+ *   data_value: { title: 'Updated Title' }
+ * });
+ * ```
+ */
+async function update(id, options) {
+    const client = await getGlobalClient();
+    return client.update(id, options);
+}
+/**
+ * 删除数据
+ *
+ * @param id 数据 ID
+ *
+ * @example
+ * ```typescript
+ * import { deleteData } from '@seaverse/data-sdk';
+ *
+ * await deleteData('note-id-123');
+ * ```
+ */
+async function deleteData(id) {
+    const client = await getGlobalClient();
+    return client.delete(id);
+}
+/**
+ * 批量删除数据
+ *
+ * @param ids 数据 ID 数组
+ *
+ * @example
+ * ```typescript
+ * import { batchDelete } from '@seaverse/data-sdk';
+ *
+ * await batchDelete(['id1', 'id2', 'id3']);
+ * ```
+ */
+async function batchDelete(ids) {
+    const client = await getGlobalClient();
+    return client.batchDelete(ids);
+}
+/**
+ * 分页查询
+ *
+ * @param options 查询选项（包含分页参数）
+ * @returns 分页响应（包含数据、总数等）
+ *
+ * @example
+ * ```typescript
+ * import { queryWithPagination } from '@seaverse/data-sdk';
+ *
+ * const result = await queryWithPagination({
+ *   table_name: 'notes',
+ *   pagination: { limit: 20, offset: 0 }
+ * });
+ *
+ * console.log('数据:', result.data);
+ * console.log('总数:', result.total);
+ * console.log('是否有更多:', result.hasMore);
+ * ```
+ */
+async function queryWithPagination(options) {
+    const client = await getGlobalClient();
+    return client.queryWithPagination(options);
+}
+/**
+ * 检查当前用户是否为管理员
+ *
+ * @returns 是否为管理员
+ *
+ * @example
+ * ```typescript
+ * import { isAdmin } from '@seaverse/data-sdk';
+ *
+ * const admin = await isAdmin();
+ * if (admin) {
+ *   console.log('当前用户是管理员');
+ * }
+ * ```
+ */
+async function isAdmin() {
+    const client = await getGlobalClient();
+    return client.isAdmin();
+}
+
 exports.DataClient = DataClient;
 exports.DataSDKError = DataSDKError;
 exports.NotFoundError = NotFoundError;
@@ -1113,4 +1342,14 @@ exports.PermissionError = PermissionError;
 exports.RateLimitError = RateLimitError;
 exports.SDKError = SDKError;
 exports.ValidationError = ValidationError;
+exports.batchDelete = batchDelete;
+exports.create = create;
+exports.deleteData = deleteData;
+exports.get = get;
+exports.getClientStatus = getClientStatus;
+exports.isAdmin = isAdmin;
+exports.query = query;
+exports.queryWithPagination = queryWithPagination;
+exports.reinit = reinit;
+exports.update = update;
 //# sourceMappingURL=index.cjs.map