@seaverse/data-sdk 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -260,6 +260,38 @@ declare const ENDPOINTS: {
     APP_DATA: string;
     APP_ADMINS: string;
 };
+/**
+ * 自动获取 API Token
+ *
+ * 按照以下优先级获取 token：
+ * 1. 传入的 token 参数
+ * 2. localStorage 中的 token（auth-sdk 标准 key）
+ * 3. localStorage 中的 auth_token（向后兼容）
+ * 4. PostMessage 从父窗口获取（iframe 场景）
+ * 5. 环境变量 DATA_SDK_TOKEN
+ *
+ * @param providedToken - 可选的直接提供的 token
+ * @returns token 字符串
+ *
+ * @example
+ * ```typescript
+ * // 通常由 auth-sdk 的 login() 方法设置
+ * // localStorage.setItem('token', loginResult.token);
+ *
+ * // data-sdk 自动获取
+ * const token = await getApiToken();
+ * ```
+ */
+declare function getApiToken(providedToken?: string): Promise<string>;
+/**
+ * 获取 App ID
+ *
+ * appId 必须由用户明确提供，不会自动从其他地方获取
+ *
+ * @param providedAppId - 必需的 appId 参数
+ * @returns appId 字符串
+ */
+declare function getAppId(providedAppId?: string): Promise<string>;
 
 /**
  * Data SDK Client
@@ -538,5 +570,219 @@ declare class DataClient {
     getUserId(): string;
 }
 
-export { DEFAULT_TIMEOUT, DataClient, DataSDKError, ENDPOINTS, ENVIRONMENT_CONFIGS, NotFoundError, PermissionError, RateLimitError, SDKError, ValidationError, detectEnvironment, getEnvironmentConfig, resolveBaseURL };
+/**
+ * Global Configuration for Data SDK
+ * 全局配置模块 - 支持无缝接入
+ */
+
+/**
+ * 初始化 Data SDK（可选）
+ *
+ * 可以在应用启动时调用，也可以完全不调用（SDK会自动从localStorage获取配置）
+ *
+ * @param options - 初始化选项（所有参数都是可选的）
+ *
+ * @example
+ * ```typescript
+ * // 方式1: 显式初始化（推荐用于需要自定义配置的场景）
+ * await initData({
+ *   appId: 'my-app-123',
+ *   token: 'user-jwt-token',
+ *   debug: true,
+ * });
+ *
+ * // 方式2: 不初始化，直接使用（推荐用于SeaVerse平台应用）
+ * // SDK 会自动从 localStorage 读取 auth_token 和 app_id
+ * const notes = await query({ table: 'notes' });
+ * ```
+ */
+declare function initData(options?: Partial<DataClientOptions>): Promise<void>;
+/**
+ * 获取或创建 DataClient 实例
+ *
+ * 如果已经初始化，返回已有实例；否则自动创建新实例
+ *
+ * @returns DataClient 实例
+ * @throws 如果无法获取必需的配置
+ */
+declare function getClient(): Promise<DataClient>;
+/**
+ * 更新全局 token（用于 token 刷新场景）
+ *
+ * @param token - 新的 JWT token
+ *
+ * @example
+ * ```typescript
+ * // Token 刷新后更新
+ * updateToken('new-jwt-token');
+ * ```
+ */
+declare function updateToken(token: string): void;
+/**
+ * 更新全局 appId（用于切换应用场景）
+ *
+ * @param appId - 新的应用 ID
+ *
+ * @example
+ * ```typescript
+ * // 切换到其他应用
+ * updateAppId('another-app-id');
+ * ```
+ */
+declare function updateAppId(appId: string): void;
+/**
+ * 获取当前配置的 appId
+ *
+ * @returns 当前的 appId 或 undefined
+ */
+declare function getCurrentAppId(): string | undefined;
+/**
+ * 清除全局配置（用于登出场景）
+ *
+ * @example
+ * ```typescript
+ * // 用户登出时清除配置
+ * clearConfig();
+ * ```
+ */
+declare function clearConfig(): void;
+
+/**
+ * Convenient Function-based APIs
+ * 便捷的函数式 API 封装 - 无需创建 client 实例
+ */
+
+/**
+ * 查询数据列表
+ *
+ * 便捷函数 - 无需创建 client 实例
+ *
+ * @param options - 查询选项
+ * @returns 数据记录数组
+ *
+ * @example
+ * ```typescript
+ * import { query } from '@seaverse/data-sdk';
+ *
+ * const notes = await query({
+ *   table: 'notes',
+ *   filters: { category: 'work' },
+ *   order: { field: 'created_at', direction: 'desc' },
+ * });
+ * ```
+ */
+declare function query(options: QueryOptions): Promise<DataRecord[]>;
+/**
+ * 获取单条数据
+ *
+ * @param id - 数据 ID
+ * @returns 数据记录或 null
+ *
+ * @example
+ * ```typescript
+ * import { get } from '@seaverse/data-sdk';
+ *
+ * const note = await get('note-id-123');
+ * ```
+ */
+declare function get(id: string): Promise<DataRecord | null>;
+/**
+ * 创建数据
+ *
+ * @param options - 创建选项
+ * @returns 创建的数据记录
+ *
+ * @example
+ * ```typescript
+ * import { create } from '@seaverse/data-sdk';
+ *
+ * const newNote = await create({
+ *   table: 'notes',
+ *   data: { title: 'My Note', content: '...' },
+ *   visibility: 'private',
+ * });
+ * ```
+ */
+declare function create(options: CreateDataOptions): Promise<DataRecord>;
+/**
+ * 更新数据
+ *
+ * @param id - 数据 ID
+ * @param options - 更新选项
+ * @returns 更新后的数据记录
+ *
+ * @example
+ * ```typescript
+ * import { update } from '@seaverse/data-sdk';
+ *
+ * const updated = await update('note-id-123', {
+ *   data: { title: 'Updated Title' },
+ * });
+ * ```
+ */
+declare function update(id: string, options: UpdateDataOptions): Promise<DataRecord>;
+/**
+ * 删除数据
+ *
+ * @param id - 数据 ID
+ *
+ * @example
+ * ```typescript
+ * import { deleteData } from '@seaverse/data-sdk';
+ *
+ * await deleteData('note-id-123');
+ * ```
+ */
+declare function deleteData(id: string): Promise<void>;
+/**
+ * 批量删除数据
+ *
+ * @param ids - 数据 ID 数组
+ *
+ * @example
+ * ```typescript
+ * import { batchDelete } from '@seaverse/data-sdk';
+ *
+ * await batchDelete(['id-1', 'id-2', 'id-3']);
+ * ```
+ */
+declare function batchDelete(ids: string[]): Promise<void>;
+/**
+ * 查询数据并返回分页信息
+ *
+ * @param options - 查询选项
+ * @returns 分页响应（包含 total, hasMore 等元数据）
+ *
+ * @example
+ * ```typescript
+ * import { queryWithPagination } from '@seaverse/data-sdk';
+ *
+ * const result = await queryWithPagination({
+ *   table: 'posts',
+ *   pagination: { limit: 10, offset: 0 },
+ * });
+ *
+ * console.log(`总共 ${result.total} 条数据`);
+ * console.log(`是否还有更多: ${result.hasMore}`);
+ * ```
+ */
+declare function queryWithPagination(options: QueryOptions): Promise<PaginatedResponse<DataRecord>>;
+/**
+ * 检查当前用户是否是管理员
+ *
+ * @returns 是否是管理员
+ *
+ * @example
+ * ```typescript
+ * import { isAdmin } from '@seaverse/data-sdk';
+ *
+ * const admin = await isAdmin();
+ * if (admin) {
+ *   console.log('当前用户是管理员');
+ * }
+ * ```
+ */
+declare function isAdmin(): Promise<boolean>;
+
+export { DEFAULT_TIMEOUT, DataClient, DataSDKError, ENDPOINTS, ENVIRONMENT_CONFIGS, NotFoundError, PermissionError, RateLimitError, SDKError, ValidationError, batchDelete, clearConfig, create, deleteData, detectEnvironment, get, getApiToken, getAppId, getClient, getCurrentAppId, getEnvironmentConfig, initData, isAdmin, query, queryWithPagination, resolveBaseURL, update, updateAppId, updateToken };
 export type { AdminRole, CreateDataOptions, DataClientOptions, DataRecord, Environment, EnvironmentConfig, FilterOperator, JWTClaims, PaginatedResponse, QueryOptions, UpdateDataOptions, Visibility };

package/dist/index.js

@@ -180,6 +180,100 @@ const ENDPOINTS = {
     // Admin roles
     APP_ADMINS: '/app_admins',
 };
+/**
+ * 自动获取 API Token
+ *
+ * 按照以下优先级获取 token：
+ * 1. 传入的 token 参数
+ * 2. localStorage 中的 token（auth-sdk 标准 key）
+ * 3. localStorage 中的 auth_token（向后兼容）
+ * 4. PostMessage 从父窗口获取（iframe 场景）
+ * 5. 环境变量 DATA_SDK_TOKEN
+ *
+ * @param providedToken - 可选的直接提供的 token
+ * @returns token 字符串
+ *
+ * @example
+ * ```typescript
+ * // 通常由 auth-sdk 的 login() 方法设置
+ * // localStorage.setItem('token', loginResult.token);
+ *
+ * // data-sdk 自动获取
+ * const token = await getApiToken();
+ * ```
+ */
+async function getApiToken(providedToken) {
+    // Priority 1: Provided token
+    if (providedToken) {
+        return providedToken;
+    }
+    // Priority 2: localStorage 'token' (auth-sdk standard key)
+    if (typeof window !== 'undefined' && window.localStorage) {
+        const storedToken = localStorage.getItem('token');
+        if (storedToken) {
+            return storedToken;
+        }
+        // Priority 3: localStorage 'auth_token' (backward compatibility)
+        const authToken = localStorage.getItem('auth_token');
+        if (authToken) {
+            return authToken;
+        }
+    }
+    // Priority 4: PostMessage from parent (iframe scenario)
+    if (typeof window !== 'undefined' && window.parent && window.parent !== window) {
+        try {
+            const token = await getTokenFromParent();
+            if (token) {
+                return token;
+            }
+        }
+        catch (error) {
+            console.warn('[DataSDK] Failed to get token from parent window:', error);
+        }
+    }
+    // Priority 5: Environment variable
+    if (typeof process !== 'undefined' && process.env && process.env.DATA_SDK_TOKEN) {
+        return process.env.DATA_SDK_TOKEN;
+    }
+    return '';
+}
+/**
+ * 获取 App ID
+ *
+ * appId 必须由用户明确提供，不会自动从其他地方获取
+ *
+ * @param providedAppId - 必需的 appId 参数
+ * @returns appId 字符串
+ */
+async function getAppId(providedAppId) {
+    if (providedAppId) {
+        return providedAppId;
+    }
+    // appId 必须由用户明确提供
+    return '';
+}
+/**
+ * 通过 PostMessage 从父窗口获取 token (iframe 场景)
+ *
+ * @returns Promise<string> token
+ * @private
+ */
+function getTokenFromParent() {
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            reject(new Error('Timeout waiting for token from parent'));
+        }, 3000);
+        const handleMessage = (event) => {
+            if (event.data.type === 'DATA_SDK_TOKEN_RESPONSE') {
+                clearTimeout(timeout);
+                window.removeEventListener('message', handleMessage);
+                resolve(event.data.token || '');
+            }
+        };
+        window.addEventListener('message', handleMessage);
+        window.parent.postMessage({ type: 'DATA_SDK_TOKEN_REQUEST' }, '*');
+    });
+}
 
 /**
  * Data SDK Client
@@ -247,6 +341,16 @@ class DataClient {
                 ...headers,
             },
         });
+        // Add request interceptor to inject app_id query parameter
+        this.axiosInstance.interceptors.request.use((config) => {
+            // Add app_id query parameter to all requests
+            // This is required for PostgREST's data_set_role() pre-request hook
+            if (!config.params) {
+                config.params = {};
+            }
+            config.params.app_id = `eq.${this.appId}`;
+            return config;
+        }, (error) => Promise.reject(error));
         // Add response interceptor for error handling
         this.axiosInstance.interceptors.response.use((response) => response, (error) => {
             throw this._handleError(error);
@@ -372,7 +476,7 @@ class DataClient {
      */
     async query(options) {
         const query = {
-            app_id: `eq.${this.appId}`,
+            // app_id is automatically added by request interceptor
             table_name: `eq.${options.table}`,
         };
         // Add filters
@@ -766,5 +870,313 @@ class DataClient {
     }
 }
 
-export { DEFAULT_TIMEOUT, DataClient, DataSDKError, ENDPOINTS, ENVIRONMENT_CONFIGS, NotFoundError, PermissionError, RateLimitError, SDKError, ValidationError, detectEnvironment, getEnvironmentConfig, resolveBaseURL };
+/**
+ * Global Configuration for Data SDK
+ * 全局配置模块 - 支持无缝接入
+ */
+/**
+ * 全局配置实例
+ */
+const globalConfig = {};
+/**
+ * 初始化 Data SDK（可选）
+ *
+ * 可以在应用启动时调用，也可以完全不调用（SDK会自动从localStorage获取配置）
+ *
+ * @param options - 初始化选项（所有参数都是可选的）
+ *
+ * @example
+ * ```typescript
+ * // 方式1: 显式初始化（推荐用于需要自定义配置的场景）
+ * await initData({
+ *   appId: 'my-app-123',
+ *   token: 'user-jwt-token',
+ *   debug: true,
+ * });
+ *
+ * // 方式2: 不初始化，直接使用（推荐用于SeaVerse平台应用）
+ * // SDK 会自动从 localStorage 读取 auth_token 和 app_id
+ * const notes = await query({ table: 'notes' });
+ * ```
+ */
+async function initData(options = {}) {
+    const appId = options.appId || (await getAppId());
+    const token = options.token || (await getApiToken());
+    if (!appId || !token) {
+        throw new Error('[DataSDK] appId and token are required. Please call initData() with credentials or ensure they are available in localStorage/environment.');
+    }
+    globalConfig.appId = appId;
+    globalConfig.token = token;
+    globalConfig.debug = options.debug;
+    // Create client instance
+    globalConfig.client = new DataClient({
+        appId,
+        token,
+        baseURL: options.baseURL,
+        environment: options.environment,
+        timeout: options.timeout,
+        headers: options.headers,
+        debug: options.debug,
+    });
+    if (globalConfig.debug) {
+        console.log('[DataSDK] Initialized', { appId, hasToken: !!token });
+    }
+}
+/**
+ * 获取或创建 DataClient 实例
+ *
+ * 如果已经初始化，返回已有实例；否则自动创建新实例
+ *
+ * @returns DataClient 实例
+ * @throws 如果无法获取必需的配置
+ */
+async function getClient() {
+    if (globalConfig.client) {
+        return globalConfig.client;
+    }
+    // Auto-initialize with defaults
+    const appId = await getAppId();
+    const token = await getApiToken();
+    if (!appId || !token) {
+        throw new Error('[DataSDK] Unable to initialize: appId or token not found. Please call initData() first or ensure credentials are available in localStorage.');
+    }
+    globalConfig.client = new DataClient({
+        appId,
+        token,
+        debug: globalConfig.debug,
+    });
+    return globalConfig.client;
+}
+/**
+ * 更新全局 token（用于 token 刷新场景）
+ *
+ * @param token - 新的 JWT token
+ *
+ * @example
+ * ```typescript
+ * // Token 刷新后更新
+ * updateToken('new-jwt-token');
+ * ```
+ */
+function updateToken(token) {
+    globalConfig.token = token;
+    if (globalConfig.client) {
+        globalConfig.client.updateToken(token);
+    }
+    // Update localStorage
+    if (typeof window !== 'undefined' && window.localStorage) {
+        localStorage.setItem('auth_token', token);
+    }
+}
+/**
+ * 更新全局 appId（用于切换应用场景）
+ *
+ * @param appId - 新的应用 ID
+ *
+ * @example
+ * ```typescript
+ * // 切换到其他应用
+ * updateAppId('another-app-id');
+ * ```
+ */
+function updateAppId(appId) {
+    globalConfig.appId = appId;
+    if (globalConfig.client) {
+        globalConfig.client.updateAppId(appId);
+    }
+    // Update localStorage
+    if (typeof window !== 'undefined' && window.localStorage) {
+        localStorage.setItem('app_id', appId);
+    }
+}
+/**
+ * 获取当前配置的 appId
+ *
+ * @returns 当前的 appId 或 undefined
+ */
+function getCurrentAppId() {
+    return globalConfig.appId || globalConfig.client?.getAppId();
+}
+/**
+ * 清除全局配置（用于登出场景）
+ *
+ * @example
+ * ```typescript
+ * // 用户登出时清除配置
+ * clearConfig();
+ * ```
+ */
+function clearConfig() {
+    globalConfig.client = undefined;
+    globalConfig.appId = undefined;
+    globalConfig.token = undefined;
+    globalConfig.debug = undefined;
+    // Clear localStorage
+    if (typeof window !== 'undefined' && window.localStorage) {
+        localStorage.removeItem('auth_token');
+        localStorage.removeItem('app_id');
+    }
+}
+
+/**
+ * Convenient Function-based APIs
+ * 便捷的函数式 API 封装 - 无需创建 client 实例
+ */
+/**
+ * 查询数据列表
+ *
+ * 便捷函数 - 无需创建 client 实例
+ *
+ * @param options - 查询选项
+ * @returns 数据记录数组
+ *
+ * @example
+ * ```typescript
+ * import { query } from '@seaverse/data-sdk';
+ *
+ * const notes = await query({
+ *   table: 'notes',
+ *   filters: { category: 'work' },
+ *   order: { field: 'created_at', direction: 'desc' },
+ * });
+ * ```
+ */
+async function query(options) {
+    const client = await getClient();
+    return client.query(options);
+}
+/**
+ * 获取单条数据
+ *
+ * @param id - 数据 ID
+ * @returns 数据记录或 null
+ *
+ * @example
+ * ```typescript
+ * import { get } from '@seaverse/data-sdk';
+ *
+ * const note = await get('note-id-123');
+ * ```
+ */
+async function get(id) {
+    const client = await getClient();
+    return client.get(id);
+}
+/**
+ * 创建数据
+ *
+ * @param options - 创建选项
+ * @returns 创建的数据记录
+ *
+ * @example
+ * ```typescript
+ * import { create } from '@seaverse/data-sdk';
+ *
+ * const newNote = await create({
+ *   table: 'notes',
+ *   data: { title: 'My Note', content: '...' },
+ *   visibility: 'private',
+ * });
+ * ```
+ */
+async function create(options) {
+    const client = await getClient();
+    return client.create(options);
+}
+/**
+ * 更新数据
+ *
+ * @param id - 数据 ID
+ * @param options - 更新选项
+ * @returns 更新后的数据记录
+ *
+ * @example
+ * ```typescript
+ * import { update } from '@seaverse/data-sdk';
+ *
+ * const updated = await update('note-id-123', {
+ *   data: { title: 'Updated Title' },
+ * });
+ * ```
+ */
+async function update(id, options) {
+    const client = await getClient();
+    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 getClient();
+    return client.delete(id);
+}
+/**
+ * 批量删除数据
+ *
+ * @param ids - 数据 ID 数组
+ *
+ * @example
+ * ```typescript
+ * import { batchDelete } from '@seaverse/data-sdk';
+ *
+ * await batchDelete(['id-1', 'id-2', 'id-3']);
+ * ```
+ */
+async function batchDelete(ids) {
+    const client = await getClient();
+    return client.batchDelete(ids);
+}
+/**
+ * 查询数据并返回分页信息
+ *
+ * @param options - 查询选项
+ * @returns 分页响应（包含 total, hasMore 等元数据）
+ *
+ * @example
+ * ```typescript
+ * import { queryWithPagination } from '@seaverse/data-sdk';
+ *
+ * const result = await queryWithPagination({
+ *   table: 'posts',
+ *   pagination: { limit: 10, offset: 0 },
+ * });
+ *
+ * console.log(`总共 ${result.total} 条数据`);
+ * console.log(`是否还有更多: ${result.hasMore}`);
+ * ```
+ */
+async function queryWithPagination(options) {
+    const client = await getClient();
+    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 getClient();
+    return client.isAdmin();
+}
+
+export { DEFAULT_TIMEOUT, DataClient, DataSDKError, ENDPOINTS, ENVIRONMENT_CONFIGS, NotFoundError, PermissionError, RateLimitError, SDKError, ValidationError, batchDelete, clearConfig, create, deleteData, detectEnvironment, get, getApiToken, getAppId, getClient, getCurrentAppId, getEnvironmentConfig, initData, isAdmin, query, queryWithPagination, resolveBaseURL, update, updateAppId, updateToken };
 //# sourceMappingURL=index.js.map