@onchaindb/sdk 0.4.0 → 0.4.2

package/src/database.d.ts

@@ -0,0 +1,268 @@
+import { AxiosInstance } from 'axios';
+import { IndexPaymentProof } from './types';
+export interface Collection {
+    name: string;
+    schema?: CollectionSchema;
+    indexes?: Index[];
+    metadata?: CollectionMetadata;
+}
+export interface CollectionSchema {
+    fields: {
+        [fieldName: string]: FieldDefinition;
+    };
+    required?: string[];
+    relationships?: Relationship[];
+}
+export interface FieldDefinition {
+    type: 'string' | 'number' | 'boolean' | 'date' | 'object' | 'array';
+    index?: boolean;
+    unique?: boolean;
+    required?: boolean;
+    default?: any;
+    validation?: FieldValidation;
+}
+export interface FieldValidation {
+    min?: number;
+    max?: number;
+    pattern?: string;
+    enum?: any[];
+    custom?: (value: any) => boolean | string;
+}
+export interface Relationship {
+    type: 'one-to-one' | 'one-to-many' | 'many-to-many';
+    collection: string;
+    localField: string;
+    foreignField: string;
+    cascade?: boolean;
+}
+export interface Index {
+    name: string;
+    collection: string;
+    field_name: string;
+    index_type: 'btree' | 'hash' | 'fulltext' | 'composite';
+    fields?: string[];
+    options?: IndexOptions;
+    status?: IndexStatus;
+    statistics?: IndexStatistics;
+    payment_proof?: IndexPaymentProof;
+}
+export interface IndexOptions {
+    unique?: boolean;
+    sparse?: boolean;
+    background?: boolean;
+    partialFilter?: any;
+    textIndexVersion?: number;
+    weights?: {
+        [field: string]: number;
+    };
+    defaultLanguage?: string;
+}
+export interface IndexStatus {
+    building: boolean;
+    progress?: number;
+    error?: string;
+    created_at?: string;
+    completed_at?: string;
+}
+export interface IndexStatistics {
+    size: number;
+    usage_count: number;
+    last_used?: string;
+    efficiency_score?: number;
+    memory_usage?: number;
+}
+export interface CollectionMetadata {
+    created_at: string;
+    updated_at: string;
+    document_count: number;
+    storage_size: number;
+    avg_document_size: number;
+}
+export interface DatabaseStats {
+    total_collections: number;
+    total_indexes: number;
+    total_documents: number;
+    storage_size: number;
+    index_size: number;
+    active_connections: number;
+}
+export interface QueryPlan {
+    query: any;
+    indexes_used: string[];
+    estimated_cost: number;
+    execution_time_estimate: number;
+    optimization_hints: string[];
+}
+export interface BatchOperation {
+    operation: 'create' | 'update' | 'delete';
+    collection: string;
+    data: any;
+    conditions?: any;
+}
+export interface BatchResult {
+    success: boolean;
+    operation: string;
+    collection: string;
+    result?: any;
+    error?: string;
+}
+/**
+ * Comprehensive database management client for OnChainDB
+ *
+ * Provides full CRUD operations for collections, indexes, and schemas
+ * with advanced features like query planning, batch operations, and statistics
+ */
+export declare class DatabaseManager {
+    private httpClient;
+    private serverUrl;
+    private appId;
+    private apiKey?;
+    constructor(httpClient: AxiosInstance, serverUrl: string, appId: string, apiKey?: string | undefined);
+    /**
+     * Create a new collection with optional schema definition
+     */
+    createCollection(name: string, schema?: CollectionSchema, options?: {
+        validate?: boolean;
+        createIndexes?: boolean;
+    }): Promise<Collection>;
+    /**
+     * List all collections in the application
+     */
+    listCollections(includeStats?: boolean): Promise<Collection[]>;
+    /**
+     * Get detailed information about a specific collection
+     */
+    getCollection(name: string, includeStats?: boolean): Promise<Collection>;
+    /**
+     * Update collection schema or metadata
+     */
+    updateCollection(name: string, updates: Partial<Collection>, options?: {
+        validate?: boolean;
+        migrate?: boolean;
+    }): Promise<Collection>;
+    /**
+     * Delete a collection and all its data
+     */
+    deleteCollection(name: string, options?: {
+        force?: boolean;
+        cascade?: boolean;
+    }): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Create a new index on a collection with payment support
+     *
+     * @param indexDefinition - Index definition without status/statistics
+     * @param paymentOptions - Optional payment configuration for paid indexes
+     * @returns Created index with payment proof if applicable
+     */
+    createIndex(indexDefinition: Omit<Index, 'status' | 'statistics'>, paymentOptions?: {
+        userWallet?: any;
+        brokerAddress?: string;
+    }): Promise<Index>;
+    /**
+     * Create multiple indexes in a batch operation
+     */
+    createIndexes(collection: string, indexes: Omit<Index, 'collection' | 'status' | 'statistics'>[]): Promise<Index[]>;
+    /**
+     * List all indexes for a collection or entire application
+     */
+    listIndexes(collection?: string, includeStats?: boolean): Promise<Index[]>;
+    /**
+     * Get detailed information about a specific index
+     */
+    getIndex(collection: string, indexName: string): Promise<Index>;
+    /**
+     * Check the status of index building operations
+     */
+    getIndexStatus(collection: string, indexName: string): Promise<IndexStatus>;
+    /**
+     * Get index performance statistics
+     */
+    getIndexStatistics(collection: string, indexName: string): Promise<IndexStatistics>;
+    /**
+     * Rebuild an existing index
+     */
+    rebuildIndex(collection: string, indexName: string, options?: {
+        background?: boolean;
+    }): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Drop/delete an index
+     */
+    dropIndex(collection: string, indexName: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Validate data against collection schema
+     */
+    validateSchema(collection: string, data: any): Promise<{
+        valid: boolean;
+        errors?: string[];
+    }>;
+    /**
+     * Migrate collection data to new schema
+     */
+    migrateSchema(collection: string, newSchema: CollectionSchema, options?: {
+        dryRun?: boolean;
+        batchSize?: number;
+    }): Promise<{
+        success: boolean;
+        migrated: number;
+        errors?: any[];
+    }>;
+    /**
+     * Explain query execution plan
+     */
+    explainQuery(collection: string, query: any): Promise<QueryPlan>;
+    /**
+     * Get optimization suggestions for query performance
+     */
+    getOptimizationSuggestions(collection: string): Promise<{
+        missing_indexes: string[];
+        unused_indexes: string[];
+        slow_queries: any[];
+        recommendations: string[];
+    }>;
+    /**
+     * Execute multiple database operations in a single transaction
+     */
+    executeBatch(operations: BatchOperation[]): Promise<BatchResult[]>;
+    /**
+     * Get overall database statistics
+     */
+    getDatabaseStats(): Promise<DatabaseStats>;
+    /**
+     * Get collection-specific statistics
+     */
+    getCollectionStats(collection: string): Promise<CollectionMetadata>;
+    /**
+     * Test database connection and basic functionality
+     */
+    healthCheck(): Promise<{
+        healthy: boolean;
+        response_time: number;
+        version: string;
+        features: string[];
+    }>;
+    /**
+     * Get API headers including authentication
+     */
+    private getHeaders;
+    /**
+     * Set API key for authenticated operations
+     */
+    setApiKey(apiKey: string): void;
+    /**
+     * Update server configuration
+     */
+    updateConfig(httpClient: AxiosInstance, serverUrl: string, appId: string): void;
+}
+/**
+ * Factory function to create a DatabaseManager instance
+ */
+export declare function createDatabaseManager(httpClient: AxiosInstance, serverUrl: string, appId: string, apiKey?: string): DatabaseManager;

package/src/database.js

@@ -0,0 +1,294 @@
+"use strict";
+// Database Management Client for OnChainDB SDK
+// Provides comprehensive collection and index management capabilities
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatabaseManager = void 0;
+exports.createDatabaseManager = createDatabaseManager;
+const types_1 = require("./types");
+/**
+ * Comprehensive database management client for OnChainDB
+ *
+ * Provides full CRUD operations for collections, indexes, and schemas
+ * with advanced features like query planning, batch operations, and statistics
+ */
+class DatabaseManager {
+    constructor(httpClient, serverUrl, appId, apiKey) {
+        this.httpClient = httpClient;
+        this.serverUrl = serverUrl;
+        this.appId = appId;
+        this.apiKey = apiKey;
+    }
+    // ==================== Collection Management ====================
+    /**
+     * Create a new collection with optional schema definition
+     */
+    async createCollection(name, schema, options) {
+        const payload = {
+            name,
+            schema,
+            options
+        };
+        const response = await this.httpClient.post(`/api/apps/${this.appId}/collections`, payload, { headers: this.getHeaders() });
+        return response.data;
+    }
+    /**
+     * List all collections in the application
+     */
+    async listCollections(includeStats) {
+        const params = includeStats ? { include_stats: true } : {};
+        const response = await this.httpClient.get(`/api/apps/${this.appId}/collections`, {
+            params,
+            headers: this.getHeaders()
+        });
+        return response.data;
+    }
+    /**
+     * Get detailed information about a specific collection
+     */
+    async getCollection(name, includeStats) {
+        const params = includeStats ? { include_stats: true } : {};
+        const response = await this.httpClient.get(`/api/apps/${this.appId}/collections/${name}`, {
+            params,
+            headers: this.getHeaders()
+        });
+        return response.data;
+    }
+    /**
+     * Update collection schema or metadata
+     */
+    async updateCollection(name, updates, options) {
+        const payload = { ...updates, options };
+        const response = await this.httpClient.put(`/api/apps/${this.appId}/collections/${name}`, payload, { headers: this.getHeaders() });
+        return response.data;
+    }
+    /**
+     * Delete a collection and all its data
+     */
+    async deleteCollection(name, options) {
+        const response = await this.httpClient.delete(`/api/apps/${this.appId}/collections/${name}`, {
+            data: options,
+            headers: this.getHeaders()
+        });
+        return response.data;
+    }
+    // ==================== Index Management ====================
+    /**
+     * Create a new index on a collection with payment support
+     *
+     * @param indexDefinition - Index definition without status/statistics
+     * @param paymentOptions - Optional payment configuration for paid indexes
+     * @returns Created index with payment proof if applicable
+     */
+    async createIndex(indexDefinition, paymentOptions) {
+        let finalRequest = indexDefinition;
+        // Handle payment if options provided
+        if (paymentOptions?.userWallet && paymentOptions?.brokerAddress) {
+            console.log('💰 Getting index cost estimate...');
+            // Get cost estimate
+            const costEstimate = await this.httpClient.post('/api/indexes/cost-estimate', {
+                app_id: this.appId,
+                collection: indexDefinition.collection,
+                field_name: indexDefinition.field_name,
+                index_type: indexDefinition.index_type
+            });
+            const cost = costEstimate.data;
+            const costInUtia = cost.total_estimated_cost_utia;
+            console.log(`📊 Index cost: ${costInUtia} utia`);
+            // Request payment
+            console.log('💳 Requesting user payment via Keplr...');
+            const paymentResult = await paymentOptions.userWallet.signAndBroadcast(paymentOptions.brokerAddress, `${costInUtia}utia`, `OnChainDB index creation - ${indexDefinition.field_name}`);
+            if (!paymentResult.success) {
+                throw new types_1.OnChainDBError(`Payment failed: ${paymentResult.error}`, 'PAYMENT_ERROR');
+            }
+            console.log(`✅ Payment successful: ${paymentResult.txHash}`);
+            // Add payment proof
+            finalRequest = {
+                ...indexDefinition,
+                payment_proof: {
+                    tx_hash: paymentResult.txHash,
+                    user_address: paymentOptions.userWallet.getState().address,
+                    broker_address: paymentOptions.brokerAddress,
+                    amount_utia: costInUtia,
+                    estimated_cost: cost
+                }
+            };
+        }
+        // Use alternative index creation endpoint (collection-specific endpoint temporarily disabled)
+        const response = await this.httpClient.post(`/api/apps/${this.appId}/indexes`, finalRequest, { headers: this.getHeaders() });
+        return response.data;
+    }
+    /**
+     * Create multiple indexes in a batch operation
+     */
+    async createIndexes(collection, indexes) {
+        // Since batch endpoint doesn't exist, create indexes individually
+        const results = [];
+        for (const indexDef of indexes) {
+            const result = await this.createIndex({ ...indexDef, collection });
+            results.push(result);
+        }
+        return results;
+    }
+    /**
+     * List all indexes for a collection or entire application
+     */
+    async listIndexes(collection, includeStats) {
+        const endpoint = collection
+            ? `/api/apps/${this.appId}/collections/${collection}/indexes`
+            : `/api/apps/${this.appId}/indexes`;
+        const params = includeStats ? { include_stats: true } : {};
+        const response = await this.httpClient.get(endpoint, {
+            params,
+            headers: this.getHeaders()
+        });
+        return response.data;
+    }
+    /**
+     * Get detailed information about a specific index
+     */
+    async getIndex(collection, indexName) {
+        const response = await this.httpClient.get(`/api/apps/${this.appId}/collections/${collection}/indexes/${indexName}`, { headers: this.getHeaders() });
+        return response.data;
+    }
+    /**
+     * Check the status of index building operations
+     */
+    async getIndexStatus(collection, indexName) {
+        const response = await this.httpClient.get(`/api/apps/${this.appId}/collections/${collection}/indexes/${indexName}/status`, { headers: this.getHeaders() });
+        return response.data;
+    }
+    /**
+     * Get index performance statistics
+     */
+    async getIndexStatistics(collection, indexName) {
+        const response = await this.httpClient.get(`/api/apps/${this.appId}/collections/${collection}/indexes/${indexName}/statistics`, { headers: this.getHeaders() });
+        return response.data;
+    }
+    /**
+     * Rebuild an existing index
+     */
+    async rebuildIndex(collection, indexName, options) {
+        const response = await this.httpClient.post(`/api/apps/${this.appId}/collections/${collection}/indexes/${indexName}/rebuild`, options || {}, { headers: this.getHeaders() });
+        return response.data;
+    }
+    /**
+     * Drop/delete an index
+     */
+    async dropIndex(collection, indexName) {
+        const response = await this.httpClient.delete(`/api/apps/${this.appId}/collections/${collection}/indexes/${indexName}`, { headers: this.getHeaders() });
+        return response.data;
+    }
+    // ==================== Schema Management ====================
+    /**
+     * Validate data against collection schema
+     */
+    async validateSchema(collection, data) {
+        const response = await this.httpClient.post(`/api/apps/${this.appId}/collections/${collection}/validate`, { data }, { headers: this.getHeaders() });
+        return response.data;
+    }
+    /**
+     * Migrate collection data to new schema
+     */
+    async migrateSchema(collection, newSchema, options) {
+        const payload = { schema: newSchema, ...options };
+        const response = await this.httpClient.post(`/api/apps/${this.appId}/collections/${collection}/migrate`, payload, { headers: this.getHeaders() });
+        return response.data;
+    }
+    // ==================== Query Planning and Optimization ====================
+    /**
+     * Explain query execution plan
+     */
+    async explainQuery(collection, query) {
+        const response = await this.httpClient.post(`/api/apps/${this.appId}/collections/${collection}/explain`, { query }, { headers: this.getHeaders() });
+        return response.data;
+    }
+    /**
+     * Get optimization suggestions for query performance
+     */
+    async getOptimizationSuggestions(collection) {
+        const response = await this.httpClient.get(`/api/apps/${this.appId}/collections/${collection}/optimize`, { headers: this.getHeaders() });
+        return response.data;
+    }
+    // ==================== Batch Operations ====================
+    /**
+     * Execute multiple database operations in a single transaction
+     */
+    async executeBatch(operations) {
+        const response = await this.httpClient.post(`/api/apps/${this.appId}/batch`, { operations }, { headers: this.getHeaders() });
+        return response.data;
+    }
+    // ==================== Statistics and Monitoring ====================
+    /**
+     * Get overall database statistics
+     */
+    async getDatabaseStats() {
+        const response = await this.httpClient.get(`/api/apps/${this.appId}/stats`, { headers: this.getHeaders() });
+        return response.data;
+    }
+    /**
+     * Get collection-specific statistics
+     */
+    async getCollectionStats(collection) {
+        const response = await this.httpClient.get(`/api/apps/${this.appId}/collections/${collection}/stats`, { headers: this.getHeaders() });
+        return response.data;
+    }
+    // ==================== Utility Methods ====================
+    /**
+     * Test database connection and basic functionality
+     */
+    async healthCheck() {
+        const startTime = Date.now();
+        try {
+            const response = await this.httpClient.get(`/api/apps/${this.appId}/health`, { headers: this.getHeaders() });
+            const responseTime = Date.now() - startTime;
+            return {
+                healthy: true,
+                response_time: responseTime,
+                version: response.data.version || '1.0.0',
+                features: response.data.features || []
+            };
+        }
+        catch (error) {
+            return {
+                healthy: false,
+                response_time: Date.now() - startTime,
+                version: 'unknown',
+                features: []
+            };
+        }
+    }
+    /**
+     * Get API headers including authentication
+     */
+    getHeaders() {
+        const headers = {
+            'Content-Type': 'application/json'
+        };
+        if (this.apiKey) {
+            headers['Authorization'] = `Bearer ${this.apiKey}`;
+        }
+        return headers;
+    }
+    /**
+     * Set API key for authenticated operations
+     */
+    setApiKey(apiKey) {
+        this.apiKey = apiKey;
+    }
+    /**
+     * Update server configuration
+     */
+    updateConfig(httpClient, serverUrl, appId) {
+        this.httpClient = httpClient;
+        this.serverUrl = serverUrl;
+        this.appId = appId;
+    }
+}
+exports.DatabaseManager = DatabaseManager;
+/**
+ * Factory function to create a DatabaseManager instance
+ */
+function createDatabaseManager(httpClient, serverUrl, appId, apiKey) {
+    return new DatabaseManager(httpClient, serverUrl, appId, apiKey);
+}
+// Types are available as imports, no need to re-export