appwrite-utils-cli 1.7.8 → 1.8.1

package/dist/utilsController.js

@@ -1,12 +1,13 @@
 import { Client, Databases, Query, Storage, Users, } from "node-appwrite";
 import {} from "appwrite-utils";
-import { loadConfig, loadConfigWithPath, findAppwriteConfig, findFunctionsDir, } from "./utils/loadConfigs.js";
+import { findAppwriteConfig, findFunctionsDir, } from "./utils/loadConfigs.js";
+import { normalizeFunctionName, validateFunctionDirectory } from './functions/pathResolution.js';
 import { UsersController } from "./users/methods.js";
 import { AppwriteToX } from "./migrations/appwriteToX.js";
 import { ImportController } from "./migrations/importController.js";
 import { ImportDataActions } from "./migrations/importDataActions.js";
 import { ensureDatabasesExist, wipeOtherDatabases, ensureCollectionsExist, } from "./databases/setup.js";
-import { createOrUpdateCollections, wipeDatabase, generateSchemas, fetchAllCollections, wipeCollection, } from "./collections/methods.js";
+import { createOrUpdateCollections, createOrUpdateCollectionsViaAdapter, wipeDatabase, generateSchemas, fetchAllCollections, wipeCollection, } from "./collections/methods.js";
 import { wipeAllTables, wipeTableRows } from "./collections/methods.js";
 import { backupDatabase, ensureDatabaseConfigBucketsExist, wipeDocumentStorage, } from "./storage/methods.js";
 import path from "path";
@@ -39,6 +40,26 @@ export class UtilsController {
      * Get the UtilsController singleton instance
      */
     static getInstance(currentUserDir, directConfig) {
+        // Clear instance if currentUserDir has changed
+        if (UtilsController.instance &&
+            UtilsController.instance.currentUserDir !== currentUserDir) {
+            logger.debug(`Clearing singleton: currentUserDir changed from ${UtilsController.instance.currentUserDir} to ${currentUserDir}`, { prefix: "UtilsController" });
+            UtilsController.clearInstance();
+        }
+        // Clear instance if directConfig endpoint or project has changed
+        if (UtilsController.instance && directConfig) {
+            const existingConfig = UtilsController.instance.config;
+            if (existingConfig) {
+                const endpointChanged = directConfig.appwriteEndpoint &&
+                    existingConfig.appwriteEndpoint !== directConfig.appwriteEndpoint;
+                const projectChanged = directConfig.appwriteProject &&
+                    existingConfig.appwriteProject !== directConfig.appwriteProject;
+                if (endpointChanged || projectChanged) {
+                    logger.debug("Clearing singleton: endpoint or project changed", { prefix: "UtilsController" });
+                    UtilsController.clearInstance();
+                }
+            }
+        }
         if (!UtilsController.instance) {
             UtilsController.instance = new UtilsController(currentUserDir, directConfig);
         }
@@ -151,13 +172,19 @@ export class UtilsController {
         this.appwriteServer = client;
         this.adapter = adapter;
         this.config = config;
+        // Update config.apiMode from adapter if it's auto or not set
+        if (adapter && (!config.apiMode || config.apiMode === 'auto')) {
+            this.config.apiMode = adapter.getApiMode();
+            logger.debug(`Updated config.apiMode from adapter during init: ${this.config.apiMode}`, { prefix: "UtilsController" });
+        }
         this.database = new Databases(this.appwriteServer);
         this.storage = new Storage(this.appwriteServer);
         this.config.appwriteClient = this.appwriteServer;
         // Log only on FIRST initialization to avoid spam
         if (!this.isInitialized) {
             const apiMode = adapter.getApiMode();
-            MessageFormatter.info(`Database adapter initialized (apiMode: ${apiMode})`, { prefix: "Adapter" });
+            const configApiMode = this.config.apiMode;
+            MessageFormatter.info(`Database adapter initialized (apiMode: ${apiMode}, config.apiMode: ${configApiMode})`, { prefix: "Adapter" });
             this.isInitialized = true;
         }
         else {
@@ -295,9 +322,14 @@ export class UtilsController {
         for (const entry of entries) {
             if (entry.isDirectory()) {
                 const functionPath = path.join(functionsDir, entry.name);
-                // Match with config functions by name
+                // Validate it's a function directory
+                if (!validateFunctionDirectory(functionPath)) {
+                    continue; // Skip invalid directories
+                }
+                // Match with config functions using normalized names
                 if (this.config?.functions) {
-                    const matchingFunc = this.config.functions.find((f) => f.name.toLowerCase() === entry.name.toLowerCase());
+                    const normalizedEntryName = normalizeFunctionName(entry.name);
+                    const matchingFunc = this.config.functions.find((f) => normalizeFunctionName(f.name) === normalizedEntryName);
                     if (matchingFunc) {
                         functionDirMap.set(matchingFunc.name, functionPath);
                     }
@@ -417,25 +449,44 @@ export class UtilsController {
         await this.init();
         if (!this.database || !this.config)
             throw new Error("Database or config not initialized");
-        await createOrUpdateCollections(this.database, database.$id, this.config, deletedCollections, collections);
+        // Ensure apiMode is properly set from adapter
+        if (this.adapter && (!this.config.apiMode || this.config.apiMode === 'auto')) {
+            this.config.apiMode = this.adapter.getApiMode();
+            logger.debug(`Updated config.apiMode from adapter: ${this.config.apiMode}`, { prefix: "UtilsController" });
+        }
+        // Always prefer adapter path for unified behavior. LegacyAdapter internally translates when needed.
+        if (this.adapter) {
+            logger.debug("Using adapter for createOrUpdateCollections (unified path)", {
+                prefix: "UtilsController",
+                apiMode: this.adapter.getApiMode()
+            });
+            await createOrUpdateCollectionsViaAdapter(this.adapter, database.$id, this.config, deletedCollections, collections);
+        }
+        else {
+            // Fallback if adapter is unavailable for some reason
+            logger.debug("Adapter unavailable, falling back to legacy Databases path", { prefix: "UtilsController" });
+            await createOrUpdateCollections(this.database, database.$id, this.config, deletedCollections, collections);
+        }
     }
     async generateSchemas() {
         // Schema generation doesn't need Appwrite connection, just config
         if (!this.config) {
-            if (this.appwriteFolderPath && this.appwriteConfigPath) {
-                MessageFormatter.progress("Loading config from file...", { prefix: "Config" });
-                try {
-                    const { config, actualConfigPath } = await loadConfigWithPath(this.appwriteFolderPath, { validate: false, strictMode: false, reportValidation: false });
-                    this.config = config;
-                    MessageFormatter.info(`Loaded config from: ${actualConfigPath}`, { prefix: "Config" });
-                }
-                catch (error) {
-                    MessageFormatter.error("Failed to load config from file", error instanceof Error ? error : undefined, { prefix: "Config" });
-                    return;
+            MessageFormatter.progress("Loading config from ConfigManager...", { prefix: "Config" });
+            try {
+                const configManager = ConfigManager.getInstance();
+                // Load config if not already loaded
+                if (!configManager.hasConfig()) {
+                    await configManager.loadConfig({
+                        configDir: this.currentUserDir,
+                        validate: false,
+                        strictMode: false,
+                    });
                 }
+                this.config = configManager.getConfig();
+                MessageFormatter.info("Config loaded successfully from ConfigManager", { prefix: "Config" });
             }
-            else {
-                MessageFormatter.error("No configuration available", undefined, { prefix: "Controller" });
+            catch (error) {
+                MessageFormatter.error("Failed to load config", error instanceof Error ? error : undefined, { prefix: "Config" });
                 return;
             }
         }
@@ -521,13 +572,13 @@ export class UtilsController {
             logger.warn("Schema regeneration failed during sync:", error);
         }
     }
-    async selectiveSync(databaseSelections, bucketSelections) {
+    async selectivePull(databaseSelections, bucketSelections) {
         await this.init();
         if (!this.database) {
             MessageFormatter.error("Database not initialized", undefined, { prefix: "Controller" });
             return;
         }
-        MessageFormatter.progress("Starting selective sync...", { prefix: "Controller" });
+        MessageFormatter.progress("Starting selective pull (Appwrite → local config)...", { prefix: "Controller" });
         // Convert database selections to Models.Database format
         const selectedDatabases = [];
         for (const dbSelection of databaseSelections) {
@@ -547,7 +598,7 @@ export class UtilsController {
             }
         }
         if (selectedDatabases.length === 0) {
-            MessageFormatter.warning("No valid databases selected for sync", { prefix: "Controller" });
+            MessageFormatter.warning("No valid databases selected for pull", { prefix: "Controller" });
             return;
         }
         // Log bucket selections if provided
@@ -560,7 +611,85 @@ export class UtilsController {
         }
         // Perform selective sync using the enhanced synchronizeConfigurations method
         await this.synchronizeConfigurations(selectedDatabases, this.config, databaseSelections, bucketSelections);
-        MessageFormatter.success("Selective sync completed successfully!", { prefix: "Controller" });
+        MessageFormatter.success("Selective pull completed successfully! Remote config pulled to local.", { prefix: "Controller" });
+    }
+    async selectivePush(databaseSelections, bucketSelections) {
+        await this.init();
+        if (!this.database) {
+            MessageFormatter.error("Database not initialized", undefined, { prefix: "Controller" });
+            return;
+        }
+        MessageFormatter.progress("Starting selective push (local config → Appwrite)...", { prefix: "Controller" });
+        // Convert database selections to Models.Database format
+        const selectedDatabases = [];
+        for (const dbSelection of databaseSelections) {
+            // Get the full database object from the controller
+            const databases = await fetchAllDatabases(this.database);
+            const database = databases.find(db => db.$id === dbSelection.databaseId);
+            if (database) {
+                selectedDatabases.push(database);
+                MessageFormatter.info(`Selected database: ${database.name} (${database.$id})`, { prefix: "Controller" });
+                // Log selected tables for this database
+                if (dbSelection.tableIds && dbSelection.tableIds.length > 0) {
+                    MessageFormatter.info(`  Tables: ${dbSelection.tableIds.join(', ')}`, { prefix: "Controller" });
+                }
+            }
+            else {
+                MessageFormatter.warning(`Database with ID ${dbSelection.databaseId} not found`, { prefix: "Controller" });
+            }
+        }
+        if (selectedDatabases.length === 0) {
+            MessageFormatter.warning("No valid databases selected for push", { prefix: "Controller" });
+            return;
+        }
+        // Log bucket selections if provided
+        if (bucketSelections && bucketSelections.length > 0) {
+            MessageFormatter.info(`Selected ${bucketSelections.length} buckets:`, { prefix: "Controller" });
+            for (const bucketSelection of bucketSelections) {
+                const dbInfo = bucketSelection.databaseId ? ` (DB: ${bucketSelection.databaseId})` : '';
+                MessageFormatter.info(`  - ${bucketSelection.bucketName} (${bucketSelection.bucketId})${dbInfo}`, { prefix: "Controller" });
+            }
+        }
+        // PUSH OPERATION: Push local configuration to Appwrite
+        // Build database-specific collection mappings from databaseSelections
+        const databaseCollectionsMap = new Map();
+        // Get all collections/tables from config (they're at the root level, not nested in databases)
+        const allCollections = this.config?.collections || this.config?.tables || [];
+        // Create database-specific collection mapping to preserve relationships
+        for (const dbSelection of databaseSelections) {
+            const collectionsForDatabase = [];
+            MessageFormatter.info(`Processing collections for database: ${dbSelection.databaseId}`, { prefix: "Controller" });
+            // Filter collections that were selected for THIS specific database
+            for (const collection of allCollections) {
+                const collectionId = collection.$id || collection.id;
+                // Check if this collection was selected for THIS database
+                if (dbSelection.tableIds.includes(collectionId)) {
+                    collectionsForDatabase.push(collection);
+                    MessageFormatter.info(`  - Selected collection: ${collection.name || collectionId} for database ${dbSelection.databaseId}`, { prefix: "Controller" });
+                }
+            }
+            databaseCollectionsMap.set(dbSelection.databaseId, collectionsForDatabase);
+            MessageFormatter.info(`Database ${dbSelection.databaseId}: ${collectionsForDatabase.length} collections selected`, { prefix: "Controller" });
+        }
+        // Calculate total collections for logging
+        const totalSelectedCollections = Array.from(databaseCollectionsMap.values())
+            .reduce((total, collections) => total + collections.length, 0);
+        MessageFormatter.info(`Pushing ${totalSelectedCollections} selected tables/collections to ${databaseCollectionsMap.size} databases`, { prefix: "Controller" });
+        // Ensure databases exist
+        await this.ensureDatabasesExist(selectedDatabases);
+        await this.ensureDatabaseConfigBucketsExist(selectedDatabases);
+        // Create/update collections with database-specific context
+        for (const database of selectedDatabases) {
+            const collectionsForThisDatabase = databaseCollectionsMap.get(database.$id) || [];
+            if (collectionsForThisDatabase.length > 0) {
+                MessageFormatter.info(`Pushing ${collectionsForThisDatabase.length} collections to database ${database.$id} (${database.name})`, { prefix: "Controller" });
+                await this.createOrUpdateCollections(database, undefined, collectionsForThisDatabase);
+            }
+            else {
+                MessageFormatter.info(`No collections selected for database ${database.$id} (${database.name})`, { prefix: "Controller" });
+            }
+        }
+        MessageFormatter.success("Selective push completed successfully! Local config pushed to Appwrite.", { prefix: "Controller" });
     }
     async syncDb(databases = [], collections = []) {
         await this.init();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appwrite-utils-cli",
   "description": "Appwrite Utility Functions to help with database management, data conversion, data import, migrations, and much more. Meant to be used as a CLI tool, I do not recommend installing this in frontend environments.",
-  "version": "1.7.8",
+  "version": "1.8.1",
   "main": "src/main.ts",
   "type": "module",
   "repository": {
@@ -24,7 +24,9 @@
     "appwrite-migrate": "./dist/main.js"
   },
   "scripts": {
-    "build": "bun run tsc",
+    "build": "bun run tsc && bun run copy-templates",
+    "prebuild": "rm -rf dist",
+    "copy-templates": "tsx scripts/copy-templates.ts",
     "start": "tsx --no-cache src/main.ts",
     "deploy": "bun run build && npm publish --access public",
     "test": "jest",
@@ -37,10 +39,11 @@
     "@types/inquirer": "^9.0.8",
     "@types/json-schema": "^7.0.15",
     "@types/yargs": "^17.0.33",
-    "appwrite-utils": "^1.6.1",
+    "appwrite-utils": "file:../appwrite-utils",
     "chalk": "^5.4.1",
     "cli-progress": "^3.12.0",
     "commander": "^12.1.0",
+    "decimal.js": "^10.6.0",
     "es-toolkit": "^1.39.4",
     "ignore": "^6.0.2",
     "inquirer": "^9.3.7",
@@ -48,8 +51,7 @@
     "jszip": "^3.10.1",
     "luxon": "^3.6.1",
     "nanostores": "^0.10.3",
-    "node-appwrite": "^17",
-    "node-appwrite-tablesdb": "npm:node-appwrite@^18.0.0",
+    "node-appwrite": "^20.2.1",
     "p-limit": "^6.2.0",
     "tar": "^7.4.3",
     "tsx": "^4.20.3",

package/scripts/copy-templates.ts

@@ -0,0 +1,23 @@
+import { cpSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const src = join(process.cwd(), 'src', 'functions', 'templates');
+const dest = join(process.cwd(), 'dist', 'functions', 'templates');
+
+// Verify source exists
+if (!existsSync(src)) {
+  console.error('❌ Error: Template source directory not found:', src);
+  process.exit(1);
+}
+
+// Create destination directory
+mkdirSync(dest, { recursive: true });
+
+// Copy templates recursively
+try {
+  cpSync(src, dest, { recursive: true });
+  console.log('✓ Templates copied to dist/functions/templates/');
+} catch (error) {
+  console.error('❌ Failed to copy templates:', error);
+  process.exit(1);
+}

package/src/adapters/AdapterFactory.ts

@@ -7,14 +7,14 @@
  */
 
 import type { AppwriteConfig } from "appwrite-utils";
-import { detectAppwriteVersionCached, isVersionAtLeast, type ApiMode, type VersionDetectionResult } from "../utils/versionDetection.js";
-import type { DatabaseAdapter } from './DatabaseAdapter.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';
+import { detectAppwriteVersionCached, isVersionAtLeast, type ApiMode, type VersionDetectionResult } from "../utils/versionDetection.js";
+import type { DatabaseAdapter } from './DatabaseAdapter.js';
+import { TablesDBAdapter } from './TablesDBAdapter.js';
+import { LegacyAdapter } from './LegacyAdapter.js';
+import { logger } from '../shared/logging.js';
+import { isValidSessionCookie } from '../utils/sessionAuth.js';
+import { MessageFormatter } from '../shared/messageFormatter.js';
+import { Client } from 'node-appwrite';
 
 export interface AdapterFactoryConfig {
   appwriteEndpoint: string;
@@ -201,73 +201,61 @@ export class AdapterFactory {
   /**
    * Create TablesDB adapter with dynamic import
    */
-  private static async createTablesDBAdapter(
-    config: AdapterFactoryConfig
-  ): Promise<{ adapter: DatabaseAdapter; client: any }> {
-    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 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: any;
-      if (config.preConfiguredClient) {
-        client = config.preConfiguredClient;
-      } else {
-        client = new Client()
-          .setEndpoint(config.appwriteEndpoint)
-          .setProject(config.appwriteProject);
-
-        // Set authentication method with mode headers
-        // Prefer session with admin mode, fallback to API key with default mode
-        if (config.sessionCookie && isValidSessionCookie(config.sessionCookie)) {
-          client.setSession(config.sessionCookie);
-          client.headers['X-Appwrite-Mode'] = 'admin';
-          logger.debug('Using session authentication for TablesDB adapter', {
-            project: config.appwriteProject,
-            operation: 'createTablesDBAdapter'
-          });
-        } else if (config.appwriteKey) {
-          client.setKey(config.appwriteKey);
-          client.headers['X-Appwrite-Mode'] = 'default';
-          logger.debug('Using API key authentication for TablesDB adapter', {
-            project: config.appwriteProject,
-            operation: 'createTablesDBAdapter'
-          });
-        } else {
-          throw new Error("No authentication available for adapter");
-        }
-      }
-
-      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) {
-      const errorDuration = Date.now() - startTime;
-      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+  private static async createTablesDBAdapter(
+    config: AdapterFactoryConfig
+  ): Promise<{ adapter: DatabaseAdapter; client: any }> {
+    const startTime = Date.now();
+
+    try {
+      logger.info('Creating TablesDB adapter (static SDK imports)', {
+        endpoint: config.appwriteEndpoint,
+        operation: 'createTablesDBAdapter'
+      });
+
+      // Use pre-configured client or create session-aware client with TablesDB Client
+      let client: any;
+      if (config.preConfiguredClient) {
+        client = config.preConfiguredClient;
+      } else {
+        client = new Client()
+          .setEndpoint(config.appwriteEndpoint)
+          .setProject(config.appwriteProject);
+
+        // Set authentication method with mode headers
+        // Prefer session with admin mode, fallback to API key with default mode
+        if (config.sessionCookie && isValidSessionCookie(config.sessionCookie)) {
+          client.setSession(config.sessionCookie);
+          client.headers['X-Appwrite-Mode'] = 'admin';
+          logger.debug('Using session authentication for TablesDB adapter', {
+            project: config.appwriteProject,
+            operation: 'createTablesDBAdapter'
+          });
+        } else if (config.appwriteKey) {
+          client.setKey(config.appwriteKey);
+          client.headers['X-Appwrite-Mode'] = 'default';
+          logger.debug('Using API key authentication for TablesDB adapter', {
+            project: config.appwriteProject,
+            operation: 'createTablesDBAdapter'
+          });
+        } else {
+          throw new Error("No authentication available for adapter");
+        }
+      }
+
+      const adapter = new TablesDBAdapter(client);
+
+      const totalDuration = Date.now() - startTime;
+      logger.info('TablesDB adapter created successfully', {
+        totalDuration,
+        endpoint: config.appwriteEndpoint,
+        operation: 'createTablesDBAdapter'
+      });
+
+      return { adapter, client };
+
+    } catch (error) {
+      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" });
 
@@ -286,73 +274,61 @@ export class AdapterFactory {
   /**
    * Create Legacy adapter with dynamic import
    */
-  private static async createLegacyAdapter(
-    config: AdapterFactoryConfig
-  ): Promise<{ adapter: DatabaseAdapter; client: any }> {
-    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 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: any;
-      if (config.preConfiguredClient) {
-        client = config.preConfiguredClient;
-      } else {
-        client = new Client()
-          .setEndpoint(config.appwriteEndpoint)
-          .setProject(config.appwriteProject);
-
-        // Set authentication method with mode headers
-        // Prefer session with admin mode, fallback to API key with default mode
-        if (config.sessionCookie && isValidSessionCookie(config.sessionCookie)) {
-          (client as any).setSession(config.sessionCookie);
-          client.headers['X-Appwrite-Mode'] = 'admin';
-          logger.debug('Using session authentication for Legacy adapter', {
-            project: config.appwriteProject,
-            operation: 'createLegacyAdapter'
-          });
-        } else if (config.appwriteKey) {
-          client.setKey(config.appwriteKey);
-          client.headers['X-Appwrite-Mode'] = 'default';
-          logger.debug('Using API key authentication for Legacy adapter', {
-            project: config.appwriteProject,
-            operation: 'createLegacyAdapter'
-          });
-        } else {
-          throw new Error("No authentication available for adapter");
-        }
-      }
-
-      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) {
-      const errorDuration = Date.now() - startTime;
-      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+  private static async createLegacyAdapter(
+    config: AdapterFactoryConfig
+  ): Promise<{ adapter: DatabaseAdapter; client: any }> {
+    const startTime = Date.now();
+
+    try {
+      logger.info('Creating legacy adapter (static SDK imports)', {
+        endpoint: config.appwriteEndpoint,
+        operation: 'createLegacyAdapter'
+      });
+
+      // Use pre-configured client or create session-aware client with Legacy Client
+      let client: any;
+      if (config.preConfiguredClient) {
+        client = config.preConfiguredClient;
+      } else {
+        client = new Client()
+          .setEndpoint(config.appwriteEndpoint)
+          .setProject(config.appwriteProject);
+
+        // Set authentication method with mode headers
+        // Prefer session with admin mode, fallback to API key with default mode
+        if (config.sessionCookie && isValidSessionCookie(config.sessionCookie)) {
+          (client as any).setSession(config.sessionCookie);
+          client.headers['X-Appwrite-Mode'] = 'admin';
+          logger.debug('Using session authentication for Legacy adapter', {
+            project: config.appwriteProject,
+            operation: 'createLegacyAdapter'
+          });
+        } else if (config.appwriteKey) {
+          client.setKey(config.appwriteKey);
+          client.headers['X-Appwrite-Mode'] = 'default';
+          logger.debug('Using API key authentication for Legacy adapter', {
+            project: config.appwriteProject,
+            operation: 'createLegacyAdapter'
+          });
+        } else {
+          throw new Error("No authentication available for adapter");
+        }
+      }
+
+      const adapter = new LegacyAdapter(client);
+
+      const totalDuration = Date.now() - startTime;
+      logger.info('Legacy adapter created successfully', {
+        totalDuration,
+        endpoint: config.appwriteEndpoint,
+        operation: 'createLegacyAdapter'
+      });
+
+      return { adapter, client };
+
+    } catch (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,
@@ -531,4 +507,4 @@ export async function getApiCapabilities(
     terminology: metadata.terminology,
     capabilities
   };
-}
+}