appwrite-utils-cli 1.5.2 → 1.6.1

package/dist/adapters/AdapterFactory.js

@@ -5,9 +5,13 @@
  * based on version detection and configuration. It handles dynamic SDK imports
  * and provides a single entry point for all database operations.
  */
-import { detectAppwriteVersionCached } from "../utils/versionDetection.js";
+import { detectAppwriteVersionCached, isVersionAtLeast } from "../utils/versionDetection.js";
 import { TablesDBAdapter } from './TablesDBAdapter.js';
 import { LegacyAdapter } from './LegacyAdapter.js';
+import { logger } from '../shared/logging.js';
+import { getClientWithAuth } from '../utils/getClientFromConfig.js';
+import { isValidSessionCookie } from '../utils/sessionAuth.js';
+import { MessageFormatter } from '../shared/messageFormatter.js';
 /**
  * AdapterFactory - Main factory class for creating database adapters
  */
@@ -18,11 +22,32 @@ export class AdapterFactory {
      * Create a database adapter based on configuration and detection
      */
     static async create(config) {
+        const startTime = Date.now();
+        // Validate authentication configuration
+        this.validateAuthConfig(config);
         const cacheKey = `${config.appwriteEndpoint}:${config.appwriteProject}:${config.apiMode || 'auto'}`;
+        logger.info('Creating database adapter', {
+            endpoint: config.appwriteEndpoint,
+            project: config.appwriteProject,
+            requestedApiMode: config.apiMode || 'auto',
+            authMethod: config.authMethod || 'auto',
+            hasSessionCookie: !!config.sessionCookie,
+            hasPreConfiguredClient: !!config.preConfiguredClient,
+            forceRefresh: config.forceRefresh,
+            cacheKey,
+            operation: 'AdapterFactory.create'
+        });
         // Check cache first (unless force refresh)
         if (!config.forceRefresh) {
             const cached = this.getCachedAdapter(cacheKey);
             if (cached) {
+                const cacheAge = Date.now() - cached.timestamp;
+                logger.info('Using cached adapter', {
+                    cacheKey,
+                    cacheAge,
+                    apiMode: cached.adapter.getApiMode(),
+                    operation: 'AdapterFactory.create'
+                });
                 return {
                     adapter: cached.adapter,
                     apiMode: cached.adapter.getApiMode(),
@@ -36,16 +61,67 @@ export class AdapterFactory {
         if (config.apiMode && config.apiMode !== 'auto') {
             // Use explicitly configured mode
             apiMode = config.apiMode;
+            logger.info('Using explicitly configured API mode', {
+                apiMode,
+                endpoint: config.appwriteEndpoint,
+                operation: 'AdapterFactory.create'
+            });
         }
         else {
             // Auto-detect API mode
-            detectionResult = await detectAppwriteVersionCached(config.appwriteEndpoint, config.appwriteProject, config.appwriteKey, config.forceRefresh);
+            logger.info('Starting API mode auto-detection', {
+                endpoint: config.appwriteEndpoint,
+                project: config.appwriteProject,
+                forceRefresh: config.forceRefresh,
+                operation: 'AdapterFactory.create'
+            });
+            const detectionStartTime = Date.now();
+            // For version detection, we need some form of authentication
+            const authKey = config.appwriteKey || '';
+            detectionResult = await detectAppwriteVersionCached(config.appwriteEndpoint, config.appwriteProject, authKey, config.forceRefresh);
+            const detectionDuration = Date.now() - detectionStartTime;
             apiMode = detectionResult.apiMode;
+            logger.info('API mode detection completed', {
+                apiMode,
+                detectionMethod: detectionResult.detectionMethod,
+                confidence: detectionResult.confidence,
+                serverVersion: detectionResult.serverVersion,
+                detectionDuration,
+                endpoint: config.appwriteEndpoint,
+                operation: 'AdapterFactory.create'
+            });
+            // Add version-based safety check to prevent using TablesDB on old servers
+            if (detectionResult.serverVersion &&
+                !isVersionAtLeast(detectionResult.serverVersion, '1.8.0') &&
+                apiMode === 'tablesdb') {
+                logger.warn('Overriding TablesDB detection - server version too old', {
+                    serverVersion: detectionResult.serverVersion,
+                    detectedMode: apiMode,
+                    overrideMode: 'legacy',
+                    operation: 'AdapterFactory.create'
+                });
+                apiMode = 'legacy';
+            }
         }
         // Create appropriate adapter
+        logger.info('Creating adapter instance', {
+            apiMode,
+            endpoint: config.appwriteEndpoint,
+            operation: 'AdapterFactory.create'
+        });
+        const adapterStartTime = Date.now();
         const result = await this.createAdapter(config, apiMode);
+        const adapterDuration = Date.now() - adapterStartTime;
         // Cache the result
         this.setCachedAdapter(cacheKey, result.adapter);
+        const totalDuration = Date.now() - startTime;
+        logger.info('Adapter creation completed', {
+            apiMode,
+            adapterDuration,
+            totalDuration,
+            cached: true,
+            operation: 'AdapterFactory.create'
+        });
         return {
             ...result,
             apiMode,
@@ -79,20 +155,67 @@ export class AdapterFactory {
      * Create TablesDB adapter with dynamic import
      */
     static async createTablesDBAdapter(config) {
+        const startTime = Date.now();
         try {
+            logger.info('Loading TablesDB SDK', {
+                endpoint: config.appwriteEndpoint,
+                operation: 'createTablesDBAdapter'
+            });
             // Dynamic import of TablesDB SDK
+            const importStartTime = Date.now();
             const { Client, TablesDB } = await import('node-appwrite-tablesdb');
-            const client = new Client()
-                .setEndpoint(config.appwriteEndpoint)
-                .setProject(config.appwriteProject)
-                .setKey(config.appwriteKey);
+            const importDuration = Date.now() - importStartTime;
+            logger.debug('TablesDB SDK import successful', {
+                importDuration,
+                operation: 'createTablesDBAdapter'
+            });
+            // Use pre-configured client or create session-aware client with TablesDB Client
+            let client;
+            if (config.preConfiguredClient) {
+                client = config.preConfiguredClient;
+            }
+            else {
+                client = new Client()
+                    .setEndpoint(config.appwriteEndpoint)
+                    .setProject(config.appwriteProject);
+                // Set authentication method based on priority
+                if (config.sessionCookie && isValidSessionCookie(config.sessionCookie)) {
+                    client.setSession(config.sessionCookie);
+                    logger.debug('Using session authentication for TablesDB adapter', {
+                        project: config.appwriteProject,
+                        operation: 'createTablesDBAdapter'
+                    });
+                }
+                else if (config.appwriteKey) {
+                    client.setKey(config.appwriteKey);
+                    logger.debug('Using API key authentication for TablesDB adapter', {
+                        project: config.appwriteProject,
+                        operation: 'createTablesDBAdapter'
+                    });
+                }
+            }
             const tablesDB = new TablesDB(client);
             const adapter = new TablesDBAdapter(tablesDB);
+            const totalDuration = Date.now() - startTime;
+            logger.info('TablesDB adapter created successfully', {
+                totalDuration,
+                importDuration,
+                endpoint: config.appwriteEndpoint,
+                operation: 'createTablesDBAdapter'
+            });
             return { adapter, client };
         }
         catch (error) {
-            console.warn('Failed to load TablesDB SDK, falling back to legacy:', error);
-            // Fallback to legacy adapter if TablesDB SDK is not available
+            const errorDuration = Date.now() - startTime;
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            MessageFormatter.warning('Failed to create TablesDB adapter - falling back to legacy', { prefix: "Adapter" });
+            logger.warn('TablesDB adapter creation failed, falling back to legacy', {
+                error: errorMessage,
+                errorDuration,
+                endpoint: config.appwriteEndpoint,
+                operation: 'createTablesDBAdapter'
+            });
+            // Fallback to legacy adapter if TablesDB creation fails
             return this.createLegacyAdapter(config);
         }
     }
@@ -100,19 +223,66 @@ export class AdapterFactory {
      * Create Legacy adapter with dynamic import
      */
     static async createLegacyAdapter(config) {
+        const startTime = Date.now();
         try {
+            logger.info('Loading legacy Appwrite SDK', {
+                endpoint: config.appwriteEndpoint,
+                operation: 'createLegacyAdapter'
+            });
             // Dynamic import of legacy SDK
+            const importStartTime = Date.now();
             const { Client, Databases } = await import('node-appwrite');
-            const client = new Client()
-                .setEndpoint(config.appwriteEndpoint)
-                .setProject(config.appwriteProject)
-                .setKey(config.appwriteKey);
+            const importDuration = Date.now() - importStartTime;
+            logger.debug('Legacy SDK import successful', {
+                importDuration,
+                operation: 'createLegacyAdapter'
+            });
+            // Use pre-configured client or create session-aware client with Legacy Client
+            let client;
+            if (config.preConfiguredClient) {
+                client = config.preConfiguredClient;
+            }
+            else {
+                client = new Client()
+                    .setEndpoint(config.appwriteEndpoint)
+                    .setProject(config.appwriteProject);
+                // Set authentication method based on priority
+                if (config.sessionCookie && isValidSessionCookie(config.sessionCookie)) {
+                    client.setSession(config.sessionCookie);
+                    logger.debug('Using session authentication for Legacy adapter', {
+                        project: config.appwriteProject,
+                        operation: 'createLegacyAdapter'
+                    });
+                }
+                else if (config.appwriteKey) {
+                    client.setKey(config.appwriteKey);
+                    logger.debug('Using API key authentication for Legacy adapter', {
+                        project: config.appwriteProject,
+                        operation: 'createLegacyAdapter'
+                    });
+                }
+            }
             const databases = new Databases(client);
             const adapter = new LegacyAdapter(databases);
+            const totalDuration = Date.now() - startTime;
+            logger.info('Legacy adapter created successfully', {
+                totalDuration,
+                importDuration,
+                endpoint: config.appwriteEndpoint,
+                operation: 'createLegacyAdapter'
+            });
             return { adapter, client };
         }
         catch (error) {
-            throw new Error(`Failed to load legacy Appwrite SDK: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            const errorDuration = Date.now() - startTime;
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            logger.error('Failed to load legacy Appwrite SDK', {
+                error: errorMessage,
+                errorDuration,
+                endpoint: config.appwriteEndpoint,
+                operation: 'createLegacyAdapter'
+            });
+            throw new Error(`Failed to load legacy Appwrite SDK: ${errorMessage}`);
         }
     }
     /**
@@ -145,6 +315,31 @@ export class AdapterFactory {
     static clearCache() {
         this.cache.clear();
     }
+    /**
+     * Validate authentication configuration
+     */
+    static validateAuthConfig(config) {
+        const hasApiKey = config.appwriteKey && config.appwriteKey.trim().length > 0;
+        const hasSessionCookie = config.sessionCookie && isValidSessionCookie(config.sessionCookie);
+        const hasPreConfiguredClient = !!config.preConfiguredClient;
+        // Must have at least one authentication method
+        if (!hasApiKey && !hasSessionCookie && !hasPreConfiguredClient) {
+            throw new Error(`No valid authentication method provided for project ${config.appwriteProject}. ` +
+                `Please provide an API key, session cookie, or pre-configured client.`);
+        }
+        // Validate session cookie format if provided
+        if (config.sessionCookie && !isValidSessionCookie(config.sessionCookie)) {
+            throw new Error(`Invalid session cookie format provided for project ${config.appwriteProject}. ` +
+                `Session cookie must be a valid JWT token.`);
+        }
+        logger.debug('Authentication configuration validated', {
+            hasApiKey,
+            hasSessionCookie,
+            hasPreConfiguredClient,
+            authMethod: config.authMethod || 'auto',
+            operation: 'validateAuthConfig'
+        });
+    }
     /**
      * Test connection and API capabilities
      */
@@ -185,20 +380,21 @@ export class AdapterFactory {
 /**
  * Convenience function for quick adapter creation
  */
-export async function createDatabaseAdapter(endpoint, project, apiKey, mode = 'auto') {
+export async function createDatabaseAdapter(endpoint, project, apiKey, mode = 'auto', sessionCookie) {
     const result = await AdapterFactory.create({
         appwriteEndpoint: endpoint,
         appwriteProject: project,
         appwriteKey: apiKey,
-        apiMode: mode
+        apiMode: mode,
+        sessionCookie
     });
     return result.adapter;
 }
 /**
  * Helper function to get adapter metadata without creating full adapter
  */
-export async function getApiCapabilities(endpoint, project, apiKey) {
-    const adapter = await createDatabaseAdapter(endpoint, project, apiKey, 'auto');
+export async function getApiCapabilities(endpoint, project, apiKey, sessionCookie) {
+    const adapter = await createDatabaseAdapter(endpoint, project, apiKey, 'auto', sessionCookie);
     const metadata = adapter.getMetadata();
     const capabilities = [];
     if (metadata.capabilities.bulkOperations)

package/dist/adapters/TablesDBAdapter.js

@@ -32,7 +32,14 @@ export class TablesDBAdapter extends BaseAdapter {
     }
     async createRow(params) {
         try {
-            const result = await this.tablesDB.createRow(params);
+            // Remap 'id' to 'rowId' for TablesDB SDK compatibility
+            const result = await this.tablesDB.createRow({
+                databaseId: params.databaseId,
+                tableId: params.tableId,
+                rowId: params.id,
+                data: params.data,
+                permissions: params.permissions
+            });
             return {
                 data: result,
                 rows: [result]
@@ -44,7 +51,7 @@ export class TablesDBAdapter extends BaseAdapter {
     }
     async updateRow(params) {
         try {
-            const result = await this.tablesDB.updateRow(params);
+            const result = await this.tablesDB.updateRow(params.databaseId, params.tableId, params.id, params.data, params.permissions || []);
             return {
                 data: result,
                 rows: [result]
@@ -56,7 +63,7 @@ export class TablesDBAdapter extends BaseAdapter {
     }
     async deleteRow(params) {
         try {
-            const result = await this.tablesDB.deleteRow(params);
+            const result = await this.tablesDB.deleteRow(params.databaseId, params.tableId, params.id);
             return { data: result };
         }
         catch (error) {
@@ -65,7 +72,7 @@ export class TablesDBAdapter extends BaseAdapter {
     }
     async getRow(params) {
         try {
-            const result = await this.tablesDB.getRow(params);
+            const result = await this.tablesDB.getRow(params.databaseId, params.tableId, params.id);
             return {
                 data: result,
                 rows: [result]
@@ -91,7 +98,8 @@ export class TablesDBAdapter extends BaseAdapter {
     }
     async createTable(params) {
         try {
-            const result = await this.tablesDB.createTable(params);
+            const result = await this.tablesDB.createTable(params.databaseId, params.id, // tableId
+            params.name, params.permissions || [], params.documentSecurity ?? false, params.enabled ?? true);
             return {
                 data: result,
                 tables: [result]
@@ -103,7 +111,8 @@ export class TablesDBAdapter extends BaseAdapter {
     }
     async updateTable(params) {
         try {
-            const result = await this.tablesDB.updateTable(params);
+            const result = await this.tablesDB.updateTable(params.databaseId, params.id, // tableId
+            params.name, params.permissions, params.documentSecurity, params.enabled);
             return {
                 data: result,
                 tables: [result]
@@ -115,7 +124,7 @@ export class TablesDBAdapter extends BaseAdapter {
     }
     async deleteTable(params) {
         try {
-            const result = await this.tablesDB.deleteTable(params);
+            const result = await this.tablesDB.deleteTable(params.databaseId, params.tableId);
             return { data: result };
         }
         catch (error) {
@@ -124,7 +133,7 @@ export class TablesDBAdapter extends BaseAdapter {
     }
     async getTable(params) {
         try {
-            const result = await this.tablesDB.getTable(params);
+            const result = await this.tablesDB.getTable(params.databaseId, params.tableId);
             return {
                 data: result,
                 tables: [result]
@@ -149,7 +158,7 @@ export class TablesDBAdapter extends BaseAdapter {
     }
     async createIndex(params) {
         try {
-            const result = await this.tablesDB.createIndex(params);
+            const result = await this.tablesDB.createIndex(params.databaseId, params.tableId, params.key, params.type, params.attributes, params.orders || []);
             return { data: result };
         }
         catch (error) {
@@ -158,7 +167,7 @@ export class TablesDBAdapter extends BaseAdapter {
     }
     async deleteIndex(params) {
         try {
-            const result = await this.tablesDB.deleteIndex(params);
+            const result = await this.tablesDB.deleteIndex(params.databaseId, params.tableId, params.key);
             return { data: result };
         }
         catch (error) {
@@ -168,9 +177,43 @@ export class TablesDBAdapter extends BaseAdapter {
     // Attribute Operations
     async createAttribute(params) {
         try {
-            // Prefer createColumn if available, fallback to createAttribute
-            const fn = this.tablesDB.createColumn || this.tablesDB.createAttribute;
-            const result = await fn.call(this.tablesDB, params);
+            // TablesDB uses type-specific attribute methods like the legacy SDK
+            let result;
+            switch (params.type.toLowerCase()) {
+                case 'string':
+                    result = await this.tablesDB.createStringAttribute(params.databaseId, params.tableId, params.key, params.size || 255, params.required ?? false, params.default, params.array ?? false, params.encrypt ?? false);
+                    break;
+                case 'integer':
+                    result = await this.tablesDB.createIntegerAttribute(params.databaseId, params.tableId, params.key, params.required ?? false, params.min, params.max, params.default, params.array ?? false);
+                    break;
+                case 'float':
+                case 'double':
+                    result = await this.tablesDB.createFloatAttribute(params.databaseId, params.tableId, params.key, params.required ?? false, params.min, params.max, params.default, params.array ?? false);
+                    break;
+                case 'boolean':
+                    result = await this.tablesDB.createBooleanAttribute(params.databaseId, params.tableId, params.key, params.required ?? false, params.default, params.array ?? false);
+                    break;
+                case 'datetime':
+                    result = await this.tablesDB.createDatetimeAttribute(params.databaseId, params.tableId, params.key, params.required ?? false, params.default, params.array ?? false);
+                    break;
+                case 'email':
+                    result = await this.tablesDB.createEmailAttribute(params.databaseId, params.tableId, params.key, params.required ?? false, params.default, params.array ?? false);
+                    break;
+                case 'enum':
+                    result = await this.tablesDB.createEnumAttribute(params.databaseId, params.tableId, params.key, params.elements || [], params.required ?? false, params.default, params.array ?? false);
+                    break;
+                case 'ip':
+                    result = await this.tablesDB.createIpAttribute(params.databaseId, params.tableId, params.key, params.required ?? false, params.default, params.array ?? false);
+                    break;
+                case 'url':
+                    result = await this.tablesDB.createUrlAttribute(params.databaseId, params.tableId, params.key, params.required ?? false, params.default, params.array ?? false);
+                    break;
+                case 'relationship':
+                    result = await this.tablesDB.createRelationshipAttribute(params.databaseId, params.tableId, params.key, params.relatedCollection || '', params.type || 'oneToOne', params.twoWay ?? false, params.onDelete || 'restrict');
+                    break;
+                default:
+                    throw new AdapterError(`Unsupported attribute type: ${params.type}`, 'UNSUPPORTED_ATTRIBUTE_TYPE');
+            }
             return { data: result };
         }
         catch (error) {
@@ -179,8 +222,9 @@ export class TablesDBAdapter extends BaseAdapter {
     }
     async updateAttribute(params) {
         try {
-            const fn = this.tablesDB.updateColumn || this.tablesDB.updateAttribute;
-            const result = await fn.call(this.tablesDB, params);
+            // TablesDB uses type-specific update methods or generic updateAttribute with positional params
+            // Try type-specific first, fallback to generic
+            const result = await this.tablesDB.updateStringAttribute(params.databaseId, params.tableId, params.key, params.required ?? false, params.default);
             return { data: result };
         }
         catch (error) {
@@ -189,8 +233,7 @@ export class TablesDBAdapter extends BaseAdapter {
     }
     async deleteAttribute(params) {
         try {
-            const fn = this.tablesDB.deleteColumn || this.tablesDB.deleteAttribute;
-            const result = await fn.call(this.tablesDB, params);
+            const result = await this.tablesDB.deleteAttribute(params.databaseId, params.tableId, params.key);
             return { data: result };
         }
         catch (error) {

package/dist/backups/operations/bucketBackup.d.ts

@@ -0,0 +1,19 @@
+import type { Storage } from "node-appwrite";
+export interface BucketBackupOptions {
+    compressionLevel?: number;
+    parallelDownloads?: number;
+    onProgress?: (current: number, total: number, fileName: string) => void;
+}
+export interface BucketBackupResult {
+    backupFileId: string;
+    manifestFileId: string;
+    fileCount: number;
+    totalSizeBytes: number;
+    zipSizeBytes: number;
+    status: 'completed' | 'partial' | 'failed';
+    errors?: string[];
+}
+/**
+ * Downloads all files from a bucket in parallel and creates a ZIP backup
+ */
+export declare function backupBucket(storage: Storage, bucketId: string, backupBucketId: string, options?: BucketBackupOptions): Promise<BucketBackupResult>;