@onchaindb/sdk 0.4.0 → 0.4.2

package/src/database.ts

@@ -0,0 +1,695 @@
+// Database Management Client for OnChainDB SDK
+// Provides comprehensive collection and index management capabilities
+
+import { AxiosInstance, AxiosError } from 'axios';
+import { OnChainDBError } from './types';
+import { buildPaymentPayload, encodePaymentHeader } from './x402/utils';
+import type { X402PaymentRequirement } from './x402/types';
+
+// Database Management 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' | 'price';
+  fields?: string[]; // For composite indexes
+  options?: IndexOptions;
+  price_config?: PriceConfig; // For price-based payment splits
+  status?: IndexStatus;
+  statistics?: IndexStatistics;
+}
+
+export interface PriceConfig {
+  app_owner_percentage: number; // e.g., 0.80 for 80%
+  platform_percentage: number;   // e.g., 0.20 for 20%
+  app_owner_address: string;     // Wallet to receive app owner share
+}
+
+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;
+}
+
+// Materialized View Types
+export interface MaterializedView {
+  name: string;
+  source_collections: string[];
+  query: any;
+  created_at?: string;
+}
+
+export interface ViewInfo {
+  name: string;
+  source_collections: string[];
+  created_at: string;
+}
+
+export interface ListViewsResponse {
+  views: ViewInfo[];
+}
+
+/**
+ * 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 class DatabaseManager {
+  constructor(
+    private httpClient: AxiosInstance,
+    private serverUrl: string,
+    private appId: string,
+    private apiKey?: string
+  ) {}
+
+  // ==================== Index Management ====================
+
+  /**
+   * Create a new index on a collection with x402 payment support
+   *
+   * Index creation is currently FREE but this method handles 402 responses
+   * in case payment is required in the future.
+   *
+   * @param indexDefinition - Index definition without status/statistics
+   * @param paymentOptions - Optional payment configuration (for future use)
+   * @returns Created index
+   */
+  async createIndex(
+    indexDefinition: Omit<Index, 'status' | 'statistics'>,
+    paymentOptions?: {
+      userWallet?: any;
+    }
+  ): Promise<Index> {
+    const endpoint = `/api/apps/${this.appId}/indexes`;
+
+    try {
+      // First attempt - server will return 402 if payment required
+      const response = await this.httpClient.post(
+        endpoint,
+        indexDefinition,
+        { headers: this.getHeaders() }
+      );
+      return response.data;
+    } catch (error) {
+      const axiosError = error as AxiosError;
+
+      // Handle 402 Payment Required (for future use when payment is enabled)
+      if (axiosError.response?.status === 402) {
+        if (!paymentOptions?.userWallet) {
+          throw new OnChainDBError(
+            'Payment required but no wallet provided. Pass userWallet in paymentOptions.',
+            'PAYMENT_REQUIRED'
+          );
+        }
+
+        console.log('[x402] Payment required for index creation');
+
+        // Parse payment requirement from response
+        const paymentData = axiosError.response.data as any;
+        const accepts = paymentData?.accepts;
+
+        if (!accepts || accepts.length === 0) {
+          throw new OnChainDBError('Invalid 402 response: no payment options', 'PAYMENT_ERROR');
+        }
+
+        // Use first accepted payment option (native TIA)
+        const requirement: X402PaymentRequirement = accepts[0];
+        const amountUtia = parseInt(requirement.maxAmountRequired || '0', 10);
+        const brokerAddress = requirement.payTo;
+
+        console.log(`[x402] Index creation cost: ${amountUtia} utia to ${brokerAddress}`);
+
+        // Execute payment via wallet
+        const paymentResult = await paymentOptions.userWallet.signAndBroadcast(
+          brokerAddress,
+          `${amountUtia}utia`,
+          `OnChainDB index creation - ${indexDefinition.field_name}`
+        );
+
+        if (!paymentResult.success) {
+          throw new OnChainDBError(`Payment failed: ${paymentResult.error}`, 'PAYMENT_ERROR');
+        }
+
+        console.log(`[x402] Payment successful: ${paymentResult.txHash}`);
+
+        // Build X-PAYMENT header and retry
+        const x402Payload = buildPaymentPayload(requirement, {
+          txHash: paymentResult.txHash,
+          network: requirement.network,
+          sender: paymentResult.sender || '',
+          chainType: 'cosmos',
+          paymentMethod: 'native'
+        });
+        const encodedPayment = encodePaymentHeader(x402Payload);
+
+        const retryResponse = await this.httpClient.post(
+          endpoint,
+          indexDefinition,
+          {
+            headers: {
+              ...this.getHeaders(),
+              'X-PAYMENT': encodedPayment
+            }
+          }
+        );
+
+        return retryResponse.data;
+      }
+
+      // Re-throw other errors
+      throw error;
+    }
+  }
+
+  /**
+   * Create multiple indexes in a batch operation
+   */
+  async createIndexes(
+    collection: string,
+    indexes: Omit<Index, 'collection' | 'status' | 'statistics'>[]
+  ): Promise<Index[]> {
+    // Since batch endpoint doesn't exist, create indexes individually
+    const results: Index[] = [];
+    
+    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?: string, includeStats?: boolean): Promise<Index[]> {
+    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: string, indexName: string): Promise<Index> {
+    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: string, indexName: string): Promise<IndexStatus> {
+    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: string, indexName: string): Promise<IndexStatistics> {
+    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: string, 
+    indexName: string,
+    options?: { background?: boolean }
+  ): Promise<{ success: boolean; message: string }> {
+    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: string, indexName: string): Promise<{ success: boolean; message: string }> {
+    const response = await this.httpClient.delete(
+      `/api/apps/${this.appId}/collections/${collection}/indexes/${indexName}`,
+      { headers: this.getHeaders() }
+    );
+
+    return response.data;
+  }
+
+  /**
+   * Create a Price index for on-chain commerce
+   *
+   * Price indexes enable automatic payment splits when writing to collections.
+   * Perfect for order/purchase collections where you want to charge based on item price.
+   *
+   * @param collection - Collection name (e.g., 'orders')
+   * @param fieldName - Price field name (e.g., 'total_price')
+   * @param config - Optional payment split configuration
+   * @returns Created index
+   *
+   * @example
+   * ```typescript
+   * // Create price index on orders collection
+   * await db.createPriceIndex('orders', 'total_price', {
+   *   app_owner_percentage: 0.80,  // 80% to merchant
+   *   platform_percentage: 0.20,    // 20% to platform
+   *   app_owner_address: 'celestia1abc...'
+   * });
+   *
+   * // Now when writing orders, price field triggers automatic split:
+   * await client.store({
+   *   collection: 'orders',
+   *   data: {
+   *     order_id: '123',
+   *     total_price: 100  // 80 TIA to merchant, 20 TIA to platform
+   *   }
+   * });
+   * ```
+   */
+  async createPriceIndex(
+    collection: string,
+    fieldName: string,
+    config?: Partial<PriceConfig>
+  ): Promise<Index> {
+    const priceConfig: PriceConfig = {
+      app_owner_percentage: config?.app_owner_percentage ?? 0.80,
+      platform_percentage: config?.platform_percentage ?? 0.20,
+      app_owner_address: config?.app_owner_address ?? ''
+    };
+
+    return this.createIndex({
+      name: `${collection}_${fieldName}_price_index`,
+      collection,
+      field_name: fieldName,
+      index_type: 'price',
+      price_config: priceConfig
+    });
+  }
+
+  // ==================== Schema Management ====================
+
+  /**
+   * Validate data against collection schema
+   */
+  async validateSchema(collection: string, data: any): Promise<{ valid: boolean; errors?: string[] }> {
+    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: string,
+    newSchema: CollectionSchema,
+    options?: { dryRun?: boolean; batchSize?: number }
+  ): Promise<{ success: boolean; migrated: number; errors?: any[] }> {
+    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: string, query: any): Promise<QueryPlan> {
+    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: string): Promise<{
+    missing_indexes: string[];
+    unused_indexes: string[];
+    slow_queries: any[];
+    recommendations: string[];
+  }> {
+    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: BatchOperation[]): Promise<BatchResult[]> {
+    const response = await this.httpClient.post(
+      `/api/apps/${this.appId}/batch`,
+      { operations },
+      { headers: this.getHeaders() }
+    );
+
+    return response.data;
+  }
+
+  // ==================== Materialized Views Management ====================
+
+  /**
+   * Create a materialized view
+   *
+   * Materialized views are pre-computed query results that update automatically
+   * when source data changes. Great for complex aggregations and joins.
+   *
+   * @param name - Unique name for the view
+   * @param sourceCollections - Collections this view depends on
+   * @param query - Query definition for the view
+   * @returns Created view definition
+   *
+   * @example
+   * ```typescript
+   * // Create a view for top-selling products
+   * await db.createView('topSellers', ['products', 'orders'], {
+   *   select: ['id', 'name', 'price', 'salesCount'],
+   *   where: { status: 'active' },
+   *   orderBy: { salesCount: 'desc' },
+   *   limit: 100
+   * });
+   * ```
+   */
+  async createView(
+    name: string,
+    sourceCollections: string[],
+    query: any
+  ): Promise<MaterializedView> {
+    const payload = {
+      name,
+      source_collections: sourceCollections,
+      query
+    };
+
+    const response = await this.httpClient.post(
+      `/apps/${this.appId}/views`,
+      payload,
+      { headers: this.getHeaders() }
+    );
+
+    return response.data;
+  }
+
+  /**
+   * List all materialized views for the app
+   */
+  async listViews(): Promise<ViewInfo[]> {
+    const response = await this.httpClient.get(
+      `/apps/${this.appId}/views`,
+      { headers: this.getHeaders() }
+    );
+
+    return response.data.views || response.data;
+  }
+
+  /**
+   * Get a specific materialized view
+   */
+  async getView(name: string): Promise<MaterializedView> {
+    const response = await this.httpClient.get(
+      `/apps/${this.appId}/views/${name}`,
+      { headers: this.getHeaders() }
+    );
+
+    return response.data;
+  }
+
+  /**
+   * Delete a materialized view
+   */
+  async deleteView(name: string): Promise<{ success: boolean; message: string }> {
+    const response = await this.httpClient.delete(
+      `/apps/${this.appId}/views/${name}`,
+      { headers: this.getHeaders() }
+    );
+
+    return response.data;
+  }
+
+  /**
+   * Refresh/rebuild a materialized view
+   */
+  async refreshView(name: string): Promise<{ success: boolean; message: string }> {
+    const response = await this.httpClient.post(
+      `/apps/${this.appId}/views/${name}/refresh`,
+      {},
+      { headers: this.getHeaders() }
+    );
+
+    return response.data;
+  }
+
+  // ==================== Statistics and Monitoring ====================
+
+  /**
+   * Get overall database statistics
+   */
+  async getDatabaseStats(): Promise<DatabaseStats> {
+    const response = await this.httpClient.get(
+      `/api/apps/${this.appId}/stats`,
+      { headers: this.getHeaders() }
+    );
+
+    return response.data;
+  }
+
+  /**
+   * Get collection-specific statistics
+   */
+  async getCollectionStats(collection: string): Promise<CollectionMetadata> {
+    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(): Promise<{ 
+    healthy: boolean; 
+    response_time: number; 
+    version: string;
+    features: string[];
+  }> {
+    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
+   */
+  private getHeaders(): { [key: string]: string } {
+    const headers: { [key: string]: string } = {
+      'Content-Type': 'application/json'
+    };
+
+    if (this.apiKey) {
+      headers['Authorization'] = `Bearer ${this.apiKey}`;
+    }
+
+    return headers;
+  }
+
+  /**
+   * Set API key for authenticated operations
+   */
+  setApiKey(apiKey: string): void {
+    this.apiKey = apiKey;
+  }
+
+  /**
+   * Update server configuration
+   */
+  updateConfig(httpClient: AxiosInstance, serverUrl: string, appId: string): void {
+    this.httpClient = httpClient;
+    this.serverUrl = serverUrl;
+    this.appId = appId;
+  }
+}
+
+/**
+ * Factory function to create a DatabaseManager instance
+ */
+export function createDatabaseManager(
+  httpClient: AxiosInstance,
+  serverUrl: string,
+  appId: string,
+  apiKey?: string
+): DatabaseManager {
+  return new DatabaseManager(httpClient, serverUrl, appId, apiKey);
+}
+
+// Types are available as imports, no need to re-export