@seaverse/data-sdk 0.1.0

package/dist/index.cjs

@@ -0,0 +1,784 @@
+'use strict';
+
+var axios = require('axios');
+
+/**
+ * Type definitions for SeaVerse Data SDK
+ *
+ * 基于 PostgreSQL/AlloyDB + PostgREST + RLS 的数据类型定义
+ */
+// ============================================================================
+// Error Types
+// ============================================================================
+/**
+ * SDK Error class
+ */
+class SDKError extends Error {
+    constructor(message, code, statusCode, details) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.details = details;
+        this.name = 'SDKError';
+    }
+}
+/**
+ * SDK Error base class (legacy alias)
+ */
+class DataSDKError extends SDKError {
+    constructor(message, code, statusCode) {
+        super(message, code || 'SDK_ERROR', statusCode);
+        this.name = 'DataSDKError';
+    }
+}
+/**
+ * Permission denied error (403)
+ */
+class PermissionError extends SDKError {
+    constructor(message = 'Permission denied') {
+        super(message, 'PERMISSION_DENIED', 403);
+        this.name = 'PermissionError';
+    }
+}
+/**
+ * Resource not found error (404)
+ */
+class NotFoundError extends SDKError {
+    constructor(message = 'Resource not found') {
+        super(message, 'NOT_FOUND', 404);
+        this.name = 'NotFoundError';
+    }
+}
+/**
+ * Rate limit exceeded error (429)
+ */
+class RateLimitError extends SDKError {
+    constructor(message = 'Rate limit exceeded') {
+        super(message, 'RATE_LIMIT_EXCEEDED', 429);
+        this.name = 'RateLimitError';
+    }
+}
+/**
+ * Validation error (400)
+ */
+class ValidationError extends SDKError {
+    constructor(message) {
+        super(message, 'VALIDATION_ERROR', 400);
+        this.name = 'ValidationError';
+    }
+}
+
+/**
+ * Environment Configuration for Data SDK
+ * 环境配置模块 - 支持多环境部署
+ */
+/**
+ * 预定义的环境配置
+ *
+ * 使用说明：
+ * - production: 正式生产环境
+ * - staging: 预发布环境
+ * - development: 开发测试环境
+ * - local: 本地开发环境
+ */
+const ENVIRONMENT_CONFIGS = {
+    production: {
+        name: 'production',
+        baseURL: 'https://data.seaverse.ai',
+        isProduction: true,
+    },
+    staging: {
+        name: 'staging',
+        baseURL: 'https://data.sg.seaverse.dev',
+        isProduction: false,
+    },
+    development: {
+        name: 'development',
+        baseURL: 'https://data-dev.seaverse.dev',
+        isProduction: false,
+    },
+    local: {
+        name: 'local',
+        baseURL: 'http://localhost:3000',
+        isProduction: false,
+    },
+};
+/**
+ * 根据当前运行环境自动检测应该使用的环境配置
+ *
+ * 检测规则：
+ * 1. localhost/127.0.0.1 → local
+ * 2. 包含 -dev 或 .dev → development
+ * 3. 包含 staging → staging
+ * 4. 其他 → production (默认)
+ *
+ * @returns 检测到的环境类型
+ */
+function detectEnvironment() {
+    // Node.js 环境或非浏览器环境，默认返回 staging（安全起见）
+    if (typeof window === 'undefined' || typeof window.location === 'undefined') {
+        return 'staging';
+    }
+    const hostname = window.location.hostname.toLowerCase();
+    // 本地开发环境
+    if (hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '0.0.0.0') {
+        return 'local';
+    }
+    // 开发环境 (包含 -dev 或 .dev)
+    if (hostname.includes('-dev.') || hostname.includes('.dev') || hostname.endsWith('.dev')) {
+        return 'development';
+    }
+    // Staging 环境
+    if (hostname.includes('-staging.') || hostname.includes('staging.')) {
+        return 'staging';
+    }
+    // 默认使用 production
+    return 'production';
+}
+/**
+ * 获取环境配置
+ *
+ * @param env 环境类型，如果不提供则自动检测
+ * @returns 环境配置对象
+ */
+function getEnvironmentConfig(env) {
+    const targetEnv = env || detectEnvironment();
+    return ENVIRONMENT_CONFIGS[targetEnv];
+}
+/**
+ * 解析用户配置，返回最终的 baseURL
+ *
+ * 优先级：
+ * 1. 显式传入的 baseURL（最高优先级）
+ * 2. environment 参数指定的环境
+ * 3. 自动检测环境（最低优先级）
+ *
+ * @param options 用户配置选项
+ * @returns 最终使用的 baseURL
+ */
+function resolveBaseURL(options) {
+    // 优先级 1: 显式传入的 baseURL
+    if (options.baseURL) {
+        return options.baseURL;
+    }
+    // 优先级 2: environment 参数
+    if (options.environment) {
+        return ENVIRONMENT_CONFIGS[options.environment].baseURL;
+    }
+    // 优先级 3: 自动检测
+    const detectedEnv = detectEnvironment();
+    return ENVIRONMENT_CONFIGS[detectedEnv].baseURL;
+}
+/**
+ * 默认超时时间（毫秒）
+ */
+const DEFAULT_TIMEOUT = 10000; // 10 seconds
+/**
+ * API 端点路径
+ */
+const ENDPOINTS = {
+    // Data operations (PostgREST)
+    APP_DATA: '/app_data',
+    // Admin roles
+    APP_ADMINS: '/app_admins',
+};
+
+/**
+ * Data SDK Client
+ *
+ * 基于 PostgreSQL/AlloyDB + PostgREST + RLS 的数据 SDK
+ */
+/**
+ * SeaVerse Data Client
+ *
+ * 高性能数据服务SDK，基于PostgREST + RLS架构
+ *
+ * @example
+ * ```typescript
+ * const client = new DataClient({
+ *   appId: 'my-app-id',
+ *   token: 'user-jwt-token',
+ * });
+ *
+ * // Query data
+ * const notes = await client.query({
+ *   table: 'notes',
+ *   filters: { category: 'work' },
+ *   order: { field: 'created_at', direction: 'desc' },
+ * });
+ *
+ * // Create data
+ * const note = await client.create({
+ *   table: 'notes',
+ *   data: { title: 'My Note', content: '...' },
+ *   visibility: 'private',
+ * });
+ *
+ * // Update data
+ * await client.update('note-id', {
+ *   data: { title: 'Updated' },
+ * });
+ *
+ * // Delete data
+ * await client.delete('note-id');
+ * ```
+ */
+class DataClient {
+    constructor(options) {
+        const { timeout = DEFAULT_TIMEOUT, headers = {}, appId, token, debug = false, } = options;
+        if (!appId) {
+            throw new ValidationError('appId is required');
+        }
+        if (!token) {
+            throw new ValidationError('token is required');
+        }
+        this.appId = appId;
+        this.token = token;
+        this.debug = debug;
+        // 解析 baseURL（支持环境自动检测）
+        const baseURL = resolveBaseURL({
+            baseURL: options.baseURL,
+            environment: options.environment,
+        });
+        this.axiosInstance = axios.create({
+            baseURL,
+            timeout,
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${token}`,
+                ...headers,
+            },
+        });
+        // Add response interceptor for error handling
+        this.axiosInstance.interceptors.response.use((response) => response, (error) => {
+            throw this._handleError(error);
+        });
+        this.log('SDK initialized', { apiUrl: baseURL, appId });
+    }
+    // ============================================
+    // Logging Methods
+    // ============================================
+    log(message, data) {
+        if (this.debug) {
+            console.log(`[DataSDK] ${message}`, data || '');
+        }
+    }
+    logError(message, error) {
+        console.error(`[DataSDK] ${message}`, error);
+    }
+    // ============================================
+    // Helper Methods
+    // ============================================
+    /**
+     * Handle axios errors and convert to SDK errors
+     * @private
+     */
+    _handleError(error) {
+        const status = error.response?.status;
+        const message = error.response?.data?.message || error.message;
+        switch (status) {
+            case 403:
+                return new PermissionError(message);
+            case 404:
+                return new NotFoundError(message);
+            case 429:
+                return new RateLimitError(message);
+            case 400:
+                return new ValidationError(message);
+            default:
+                return new SDKError(message, 'REQUEST_FAILED', status);
+        }
+    }
+    /**
+     * Get user ID from JWT token
+     * @private
+     */
+    getUserIdFromToken() {
+        try {
+            // JWT token format: header.payload.signature
+            const parts = this.token.split('.');
+            if (parts.length !== 3) {
+                throw new Error('Invalid JWT token');
+            }
+            // Decode payload (base64url)
+            const payload = parts[1];
+            // Cross-platform base64 decoding
+            let decodedString;
+            const globalObj = globalThis;
+            if (typeof globalObj.atob === 'function') {
+                // Browser environment
+                decodedString = globalObj.atob(payload);
+            }
+            else if (typeof globalObj.Buffer !== 'undefined') {
+                // Node.js environment
+                decodedString = globalObj.Buffer.from(payload, 'base64').toString('utf-8');
+            }
+            else {
+                // Fallback: manual base64 decode
+                decodedString = this.base64Decode(payload);
+            }
+            const claims = JSON.parse(decodedString);
+            return claims.sub;
+        }
+        catch (error) {
+            throw new SDKError('Unable to parse JWT token', 'INVALID_TOKEN', 401, error);
+        }
+    }
+    /**
+     * Base64 decode fallback
+     * @private
+     */
+    base64Decode(str) {
+        const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=';
+        let output = '';
+        str = String(str).replace(/=+$/, '');
+        if (str.length % 4 === 1) {
+            throw new Error('Invalid base64 string');
+        }
+        for (let bc = 0, bs = 0, buffer, i = 0; (buffer = str.charAt(i++)); ~buffer && ((bs = bc % 4 ? bs * 64 + buffer : buffer), bc++ % 4)
+            ? (output += String.fromCharCode(255 & (bs >> ((-2 * bc) & 6))))
+            : 0) {
+            buffer = chars.indexOf(buffer);
+        }
+        return output;
+    }
+    // ============================================
+    // Data Operation Methods
+    // ============================================
+    /**
+     * Query data list
+     *
+     * 查询数据列表，支持过滤、排序、分页
+     *
+     * @param options - Query options
+     * @returns Array of data records
+     *
+     * @example
+     * ```typescript
+     * const notes = await client.query({
+     *   table: 'notes',
+     *   filters: {
+     *     category: 'work',
+     *     visibility: 'private',
+     *   },
+     *   order: {
+     *     field: 'created_at',
+     *     direction: 'desc',
+     *   },
+     *   pagination: {
+     *     limit: 20,
+     *     offset: 0,
+     *   },
+     * });
+     * ```
+     */
+    async query(options) {
+        const query = {
+            app_id: `eq.${this.appId}`,
+            table_name: `eq.${options.table}`,
+        };
+        // Add filters
+        if (options.filters) {
+            const { filters } = options;
+            if (filters.id) {
+                query.id = `eq.${filters.id}`;
+            }
+            if (filters.category) {
+                query.category = `eq.${filters.category}`;
+            }
+            if (filters.visibility) {
+                query.visibility = `eq.${filters.visibility}`;
+            }
+            if (filters.tags && filters.tags.length > 0) {
+                // PostgREST array contains operator
+                query.tags = `cs.{${filters.tags.join(',')}}`;
+            }
+            if (filters.created_after) {
+                query.created_at = `gte.${filters.created_after}`;
+            }
+            if (filters.created_before) {
+                if (query.created_at) {
+                    // If created_at already exists, use 'and' to combine
+                    query.and = `(created_at.gte.${filters.created_after},created_at.lt.${filters.created_before})`;
+                    delete query.created_at;
+                }
+                else {
+                    query.created_at = `lt.${filters.created_before}`;
+                }
+            }
+            // JSONB field filters (data_value)
+            if (filters.data) {
+                Object.entries(filters.data).forEach(([key, value]) => {
+                    // PostgREST JSONB query syntax: data_value->>key (text extraction)
+                    query[`data_value->>${key}`] = `eq.${value}`;
+                });
+            }
+        }
+        // Add sorting
+        if (options.order) {
+            const direction = options.order.direction === 'asc' ? '' : '.desc';
+            query.order = `${options.order.field}${direction}`;
+        }
+        else {
+            // Default sort by created_at desc
+            query.order = 'created_at.desc';
+        }
+        // Add pagination
+        if (options.pagination) {
+            query.limit = options.pagination.limit.toString();
+            query.offset = options.pagination.offset.toString();
+        }
+        this.log('Querying data', query);
+        const response = await this.axiosInstance.get(ENDPOINTS.APP_DATA, { params: query });
+        return Array.isArray(response.data) ? response.data : [response.data];
+    }
+    /**
+     * Get single data record by ID
+     *
+     * 通过 ID 查询单条数据
+     *
+     * @param id - Data ID
+     * @returns Data record or null if not found
+     *
+     * @example
+     * ```typescript
+     * const note = await client.get('note-id-123');
+     * console.log(note?.data_value.title);
+     * ```
+     */
+    async get(id) {
+        try {
+            const response = await this.axiosInstance.get(ENDPOINTS.APP_DATA, {
+                params: {
+                    id: `eq.${id}`,
+                },
+                headers: {
+                    'Accept': 'application/vnd.pgrst.object+json', // 返回单个对象
+                },
+            });
+            const results = Array.isArray(response.data) ? response.data : [response.data];
+            return results && results.length > 0 ? results[0] : null;
+        }
+        catch (error) {
+            this._handleError(error);
+            return null;
+        }
+    }
+    /**
+     * Create data
+     *
+     * 创建新数据
+     *
+     * @param options - Create options
+     * @returns Created data record
+     *
+     * @example
+     * ```typescript
+     * const newNote = await client.create({
+     *   table: 'notes',
+     *   data: {
+     *     title: 'My Note',
+     *     content: 'Note content...',
+     *   },
+     *   visibility: 'private',
+     *   category: 'work',
+     *   tags: ['important', 'todo'],
+     * });
+     * ```
+     */
+    async create(options) {
+        const body = {
+            app_id: this.appId,
+            table_name: options.table,
+            data_value: options.data,
+            owner_user_id: this.getUserIdFromToken(),
+            visibility: options.visibility || 'private',
+            category: options.category,
+            tags: options.tags,
+        };
+        this.log('Creating data', body);
+        const response = await this.axiosInstance.post(ENDPOINTS.APP_DATA, body, {
+            headers: {
+                'Prefer': 'return=representation', // Return created record
+            },
+        });
+        const results = Array.isArray(response.data) ? response.data : [response.data];
+        return results[0];
+    }
+    /**
+     * Update data
+     *
+     * 更新数据
+     *
+     * @param id - Data ID
+     * @param options - Update options
+     * @returns Updated data record
+     *
+     * @example
+     * ```typescript
+     * const updated = await client.update('note-id-123', {
+     *   data: {
+     *     title: 'Updated Title',
+     *     content: 'Updated content',
+     *   },
+     *   category: 'personal',
+     * });
+     * ```
+     */
+    async update(id, options) {
+        const body = {
+            updated_at: new Date().toISOString(),
+        };
+        if (options.data !== undefined) {
+            body.data_value = options.data;
+        }
+        if (options.visibility !== undefined) {
+            body.visibility = options.visibility;
+        }
+        if (options.category !== undefined) {
+            body.category = options.category;
+        }
+        if (options.tags !== undefined) {
+            body.tags = options.tags;
+        }
+        this.log('Updating data', { id, body });
+        const response = await this.axiosInstance.patch(ENDPOINTS.APP_DATA, body, {
+            params: {
+                id: `eq.${id}`,
+            },
+            headers: {
+                'Prefer': 'return=representation',
+            },
+        });
+        const results = Array.isArray(response.data) ? response.data : [response.data];
+        if (!results || results.length === 0) {
+            throw new NotFoundError('Data not found or no permission to update');
+        }
+        return results[0];
+    }
+    /**
+     * Delete data
+     *
+     * 删除数据
+     *
+     * @param id - Data ID
+     *
+     * @example
+     * ```typescript
+     * await client.delete('note-id-123');
+     * ```
+     */
+    async delete(id) {
+        this.log('Deleting data', { id });
+        await this.axiosInstance.delete(ENDPOINTS.APP_DATA, {
+            params: {
+                app_id: `eq.${this.appId}`,
+                id: `eq.${id}`,
+            },
+        });
+    }
+    /**
+     * Batch delete data
+     *
+     * 批量删除数据
+     *
+     * @param ids - Array of data IDs
+     *
+     * @example
+     * ```typescript
+     * await client.batchDelete(['id-1', 'id-2', 'id-3']);
+     * ```
+     */
+    async batchDelete(ids) {
+        if (ids.length === 0)
+            return;
+        this.log('Batch deleting data', { ids });
+        await this.axiosInstance.delete(ENDPOINTS.APP_DATA, {
+            params: {
+                app_id: `eq.${this.appId}`,
+                id: `in.(${ids.join(',')})`,
+            },
+        });
+    }
+    /**
+     * Query with pagination metadata
+     *
+     * 查询数据并返回分页信息
+     *
+     * @param options - Query options
+     * @returns Paginated response with metadata
+     *
+     * @example
+     * ```typescript
+     * const result = await client.queryWithPagination({
+     *   table: 'posts',
+     *   pagination: { limit: 10, offset: 0 },
+     * });
+     *
+     * console.log(`Total: ${result.total}, Has more: ${result.hasMore}`);
+     * ```
+     */
+    async queryWithPagination(options) {
+        const limit = options.pagination?.limit || 10;
+        const offset = options.pagination?.offset || 0;
+        const query = {
+            app_id: `eq.${this.appId}`,
+            table_name: `eq.${options.table}`,
+            limit: limit.toString(),
+            offset: offset.toString(),
+        };
+        // Add filters (same as query method)
+        if (options.filters) {
+            const { filters } = options;
+            if (filters.id)
+                query.id = `eq.${filters.id}`;
+            if (filters.category)
+                query.category = `eq.${filters.category}`;
+            if (filters.visibility)
+                query.visibility = `eq.${filters.visibility}`;
+            if (filters.tags && filters.tags.length > 0) {
+                query.tags = `cs.{${filters.tags.join(',')}}`;
+            }
+            if (filters.created_after) {
+                query.created_at = `gte.${filters.created_after}`;
+            }
+            if (filters.created_before) {
+                if (query.created_at) {
+                    query.and = `(created_at.gte.${filters.created_after},created_at.lt.${filters.created_before})`;
+                    delete query.created_at;
+                }
+                else {
+                    query.created_at = `lt.${filters.created_before}`;
+                }
+            }
+            if (filters.data) {
+                Object.entries(filters.data).forEach(([key, value]) => {
+                    query[`data_value->>${key}`] = `eq.${value}`;
+                });
+            }
+        }
+        // Add sorting
+        if (options.order) {
+            const direction = options.order.direction === 'asc' ? '' : '.desc';
+            query.order = `${options.order.field}${direction}`;
+        }
+        else {
+            query.order = 'created_at.desc';
+        }
+        this.log('Querying with pagination', query);
+        // Request with count
+        const response = await this.axiosInstance.get(ENDPOINTS.APP_DATA, {
+            params: query,
+            headers: {
+                'Prefer': 'count=exact', // Request total count
+            },
+        });
+        const data = Array.isArray(response.data) ? response.data : [response.data];
+        // Extract total count from Content-Range header
+        // Format: "0-9/100" means items 0-9, total 100
+        let total;
+        let hasMore;
+        const contentRange = response.headers['content-range'];
+        if (contentRange) {
+            const match = contentRange.match(/\/(\d+|\*)/);
+            if (match && match[1] !== '*') {
+                total = parseInt(match[1], 10);
+                hasMore = offset + data.length < total;
+            }
+        }
+        return {
+            data,
+            total,
+            limit,
+            offset,
+            hasMore,
+        };
+    }
+    // ============================================
+    // Admin Operation Methods
+    // ============================================
+    /**
+     * Check if current user is admin
+     *
+     * 检查当前用户是否是管理员
+     *
+     * @returns True if user is admin
+     *
+     * @example
+     * ```typescript
+     * const isAdmin = await client.isAdmin();
+     * if (isAdmin) {
+     *   // User has admin privileges
+     * }
+     * ```
+     */
+    async isAdmin() {
+        try {
+            const response = await this.axiosInstance.get(ENDPOINTS.APP_ADMINS, {
+                params: {
+                    app_id: `eq.${this.appId}`,
+                    user_id: `eq.${this.getUserIdFromToken()}`,
+                },
+            });
+            const roles = Array.isArray(response.data) ? response.data : [response.data];
+            return roles.length > 0;
+        }
+        catch (error) {
+            this.logError('Check admin permission failed', error);
+            return false;
+        }
+    }
+    // ============================================
+    // Configuration Methods
+    // ============================================
+    /**
+     * Update token
+     *
+     * 更新 JWT token
+     *
+     * @param token - New JWT token
+     */
+    updateToken(token) {
+        this.token = token;
+        this.axiosInstance.defaults.headers['Authorization'] = `Bearer ${token}`;
+        this.log('Token updated');
+    }
+    /**
+     * Update app ID
+     *
+     * 更新应用 ID
+     *
+     * @param appId - New application ID
+     */
+    updateAppId(appId) {
+        this.appId = appId;
+        this.log('AppId updated', { appId });
+    }
+    /**
+     * Get current app ID
+     */
+    getAppId() {
+        return this.appId;
+    }
+    /**
+     * Get current user ID
+     */
+    getUserId() {
+        return this.getUserIdFromToken();
+    }
+}
+
+exports.DEFAULT_TIMEOUT = DEFAULT_TIMEOUT;
+exports.DataClient = DataClient;
+exports.DataSDKError = DataSDKError;
+exports.ENDPOINTS = ENDPOINTS;
+exports.ENVIRONMENT_CONFIGS = ENVIRONMENT_CONFIGS;
+exports.NotFoundError = NotFoundError;
+exports.PermissionError = PermissionError;
+exports.RateLimitError = RateLimitError;
+exports.SDKError = SDKError;
+exports.ValidationError = ValidationError;
+exports.detectEnvironment = detectEnvironment;
+exports.getEnvironmentConfig = getEnvironmentConfig;
+exports.resolveBaseURL = resolveBaseURL;
+//# sourceMappingURL=index.cjs.map