appwrite-utils-cli 1.7.2 → 1.7.4

package/dist/adapters/AdapterFactory.js

@@ -178,9 +178,11 @@ export class AdapterFactory {
                 client = new Client()
                     .setEndpoint(config.appwriteEndpoint)
                     .setProject(config.appwriteProject);
-                // Set authentication method based on priority
+                // 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.setHeader('X-Appwrite-Mode', 'admin');
                     logger.debug('Using session authentication for TablesDB adapter', {
                         project: config.appwriteProject,
                         operation: 'createTablesDBAdapter'
@@ -188,11 +190,15 @@ export class AdapterFactory {
                 }
                 else if (config.appwriteKey) {
                     client.setKey(config.appwriteKey);
+                    client.setHeader('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);
@@ -246,9 +252,11 @@ export class AdapterFactory {
                 client = new Client()
                     .setEndpoint(config.appwriteEndpoint)
                     .setProject(config.appwriteProject);
-                // Set authentication method based on priority
+                // 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.setHeader('X-Appwrite-Mode', 'admin');
                     logger.debug('Using session authentication for Legacy adapter', {
                         project: config.appwriteProject,
                         operation: 'createLegacyAdapter'
@@ -256,11 +264,15 @@ export class AdapterFactory {
                 }
                 else if (config.appwriteKey) {
                     client.setKey(config.appwriteKey);
+                    client.setHeader('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);

package/dist/config/ConfigManager.js

@@ -149,26 +149,9 @@ export class ConfigManager {
         logger.debug(`Config discovered at: ${configPath}`, { prefix: "ConfigManager" });
         // 3. Load config from file
         let config = await this.loaderService.loadFromPath(configPath);
-        // 4. Load session authentication (only if appropriate based on config)
-        // Determine if we should load session:
-        // - Load if authMethod is explicitly "session"
-        // - Load if authMethod is "auto" or undefined AND no API key exists
-        // - Skip if authMethod is "apikey" or if API key is present with "auto" mode
-        const hasApiKey = !!(config.appwriteKey && config.appwriteKey.trim().length > 0);
-        const authMethod = config.authMethod || "auto";
-        const shouldLoadSession = options.sessionOverride !== undefined ||
-            authMethod === "session" ||
-            (authMethod === "auto" && !hasApiKey);
-        logger.debug("Session loading decision", {
-            prefix: "ConfigManager",
-            hasApiKey,
-            authMethod,
-            shouldLoadSession,
-        });
-        const session = shouldLoadSession
-            ? options.sessionOverride ||
-                (await this.sessionService.findSession(config.appwriteEndpoint, config.appwriteProject))
-            : null;
+        // 4. Load session authentication
+        const session = options.sessionOverride ||
+            (await this.sessionService.findSession(config.appwriteEndpoint, config.appwriteProject));
         // 5. Merge session into config
         if (session) {
             logger.debug("Merging session authentication into config", { prefix: "ConfigManager" });

package/dist/config/services/ConfigMergeService.js

@@ -57,11 +57,8 @@ export class ConfigMergeService {
         const merged = cloneDeep(config);
         // Add session authentication (map 'cookie' to 'sessionCookie')
         merged.sessionCookie = session.cookie;
-        // Only set authMethod to "session" if not explicitly set to "apikey"
-        // This allows API key authentication to take priority when both are available
-        if (merged.authMethod !== "apikey") {
-            merged.authMethod = "session";
-        }
+        // Set authMethod to session (priority handled by ClientFactory)
+        merged.authMethod = "session";
         // Add session metadata if available
         if (session.email || session.expiresAt) {
             merged.sessionMetadata = {

package/dist/utils/ClientFactory.js

@@ -60,32 +60,80 @@ export class ClientFactory {
         const client = new Client()
             .setEndpoint(config.appwriteEndpoint)
             .setProject(config.appwriteProject);
-        // Apply authentication (priority already resolved by ConfigManager)
-        if (config.sessionCookie) {
-            // Session authentication (from ConfigManager's session loading)
+        // Apply authentication based on authMethod preference with mode headers
+        // Mode headers: "admin" for sessions (elevated permissions), "default" for API keys
+        const authMethod = config.authMethod || "auto";
+        logger.debug("Applying authentication with mode headers", {
+            prefix: "ClientFactory",
+            authMethod,
+            hasApiKey: !!config.appwriteKey,
+            hasSession: !!config.sessionCookie,
+        });
+        if (authMethod === "session") {
+            // Explicit session preference - use only session with admin mode
+            if (!config.sessionCookie) {
+                const error = new Error("authMethod set to 'session' but no session cookie available.\n\n" +
+                    "Either:\n" +
+                    "  - Run 'appwrite login' to create a session\n" +
+                    "  - Change authMethod to 'apikey' or 'auto'\n" +
+                    "  - Provide --sessionCookie flag");
+                logger.error("Failed to create client - session required", { prefix: "ClientFactory" });
+                throw error;
+            }
             client.setSession(config.sessionCookie);
-            logger.debug("Applied session authentication to client", {
+            client.headers['X-Appwrite-Mode'] = 'admin';
+            logger.debug("Applied session authentication with admin mode (explicit preference)", {
                 prefix: "ClientFactory",
                 email: config.sessionMetadata?.email,
             });
         }
-        else if (config.appwriteKey) {
-            // API key authentication (from config file or overrides)
+        else if (authMethod === "apikey") {
+            // Explicit API key preference - use only API key with default mode
+            if (!config.appwriteKey || config.appwriteKey.trim().length === 0) {
+                const error = new Error("authMethod set to 'apikey' but no API key provided.\n\n" +
+                    "Either:\n" +
+                    "  - Set appwriteKey in your config file\n" +
+                    "  - Provide --apiKey flag\n" +
+                    "  - Set APPWRITE_API_KEY environment variable");
+                logger.error("Failed to create client - API key required", { prefix: "ClientFactory" });
+                throw error;
+            }
             client.setKey(config.appwriteKey);
-            logger.debug("Applied API key authentication to client", {
+            client.headers['X-Appwrite-Mode'] = 'default';
+            logger.debug("Applied API key authentication with default mode (explicit preference)", {
                 prefix: "ClientFactory",
             });
         }
         else {
-            // No authentication available - this should have been caught by ConfigManager
-            const error = new Error("No authentication method available in configuration.\n\n" +
-                "This should have been resolved by ConfigManager during config loading.\n" +
-                "Expected either:\n" +
-                "  - config.sessionCookie (from session authentication)\n" +
-                "  - config.appwriteKey (from config file or CLI overrides)\n\n" +
-                "Suggestion: Ensure ConfigManager.loadConfig() was called before ClientFactory.createFromConfig().");
-            logger.error("Failed to create client - no authentication", { prefix: "ClientFactory" });
-            throw error;
+            // Auto mode: Prefer session with admin mode (like official CLI), fallback to API key
+            if (config.sessionCookie) {
+                client.setSession(config.sessionCookie);
+                client.headers['X-Appwrite-Mode'] = 'admin';
+                logger.debug("Applied session authentication with admin mode (auto - preferred)", {
+                    prefix: "ClientFactory",
+                    email: config.sessionMetadata?.email,
+                });
+            }
+            else if (config.appwriteKey && config.appwriteKey.trim().length > 0) {
+                client.setKey(config.appwriteKey);
+                client.headers['X-Appwrite-Mode'] = 'default';
+                logger.debug("Applied API key authentication with default mode (auto - fallback)", {
+                    prefix: "ClientFactory",
+                });
+            }
+            else {
+                // No authentication available
+                const error = new Error("No authentication method available in configuration.\n\n" +
+                    "Expected either:\n" +
+                    "  - config.sessionCookie (from session authentication via 'appwrite login')\n" +
+                    "  - config.appwriteKey (from config file, CLI flags, or environment)\n\n" +
+                    "Suggestion:\n" +
+                    "  - Run 'appwrite login' to create a session, OR\n" +
+                    "  - Add appwriteKey to your config file, OR\n" +
+                    "  - Provide --apiKey flag");
+                logger.error("Failed to create client - no authentication", { prefix: "ClientFactory" });
+                throw error;
+            }
         }
         // Create adapter with version detection
         // AdapterFactory uses internal caching, so repeated calls are fast

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.2",
+  "version": "1.7.4",
   "main": "src/main.ts",
   "type": "module",
   "repository": {

package/src/adapters/AdapterFactory.ts

@@ -231,19 +231,24 @@ export class AdapterFactory {
           .setEndpoint(config.appwriteEndpoint)
           .setProject(config.appwriteProject);
 
-        // Set authentication method based on priority
+        // 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.setHeader('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.setHeader('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");
         }
       }
 
@@ -311,19 +316,24 @@ export class AdapterFactory {
           .setEndpoint(config.appwriteEndpoint)
           .setProject(config.appwriteProject);
 
-        // Set authentication method based on priority
+        // 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.setHeader('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.setHeader('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");
         }
       }
 

package/src/config/ConfigManager.ts

@@ -249,30 +249,10 @@ export class ConfigManager {
     // 3. Load config from file
     let config = await this.loaderService.loadFromPath(configPath);
 
-    // 4. Load session authentication (only if appropriate based on config)
-    // Determine if we should load session:
-    // - Load if authMethod is explicitly "session"
-    // - Load if authMethod is "auto" or undefined AND no API key exists
-    // - Skip if authMethod is "apikey" or if API key is present with "auto" mode
-    const hasApiKey = !!(config.appwriteKey && config.appwriteKey.trim().length > 0);
-    const authMethod = config.authMethod || "auto";
-
-    const shouldLoadSession =
-      options.sessionOverride !== undefined ||
-      authMethod === "session" ||
-      (authMethod === "auto" && !hasApiKey);
-
-    logger.debug("Session loading decision", {
-      prefix: "ConfigManager",
-      hasApiKey,
-      authMethod,
-      shouldLoadSession,
-    });
-
-    const session = shouldLoadSession
-      ? options.sessionOverride ||
-        (await this.sessionService.findSession(config.appwriteEndpoint, config.appwriteProject))
-      : null;
+    // 4. Load session authentication
+    const session =
+      options.sessionOverride ||
+      (await this.sessionService.findSession(config.appwriteEndpoint, config.appwriteProject));
 
     // 5. Merge session into config
     if (session) {

package/src/config/services/ConfigMergeService.ts

@@ -81,11 +81,8 @@ export class ConfigMergeService {
     // Add session authentication (map 'cookie' to 'sessionCookie')
     merged.sessionCookie = session.cookie;
 
-    // Only set authMethod to "session" if not explicitly set to "apikey"
-    // This allows API key authentication to take priority when both are available
-    if (merged.authMethod !== "apikey") {
-      merged.authMethod = "session";
-    }
+    // Set authMethod to session (priority handled by ClientFactory)
+    merged.authMethod = "session";
 
     // Add session metadata if available
     if (session.email || session.expiresAt) {

package/src/utils/ClientFactory.ts

@@ -67,32 +67,86 @@ export class ClientFactory {
       .setEndpoint(config.appwriteEndpoint)
       .setProject(config.appwriteProject);
 
-    // Apply authentication (priority already resolved by ConfigManager)
-    if (config.sessionCookie) {
-      // Session authentication (from ConfigManager's session loading)
+    // Apply authentication based on authMethod preference with mode headers
+    // Mode headers: "admin" for sessions (elevated permissions), "default" for API keys
+    const authMethod = config.authMethod || "auto";
+
+    logger.debug("Applying authentication with mode headers", {
+      prefix: "ClientFactory",
+      authMethod,
+      hasApiKey: !!config.appwriteKey,
+      hasSession: !!config.sessionCookie,
+    });
+
+    if (authMethod === "session") {
+      // Explicit session preference - use only session with admin mode
+      if (!config.sessionCookie) {
+        const error = new Error(
+          "authMethod set to 'session' but no session cookie available.\n\n" +
+          "Either:\n" +
+          "  - Run 'appwrite login' to create a session\n" +
+          "  - Change authMethod to 'apikey' or 'auto'\n" +
+          "  - Provide --sessionCookie flag"
+        );
+        logger.error("Failed to create client - session required", { prefix: "ClientFactory" });
+        throw error;
+      }
       client.setSession(config.sessionCookie);
-      logger.debug("Applied session authentication to client", {
+      client.headers['X-Appwrite-Mode'] =  'admin';
+      logger.debug("Applied session authentication with admin mode (explicit preference)", {
         prefix: "ClientFactory",
         email: config.sessionMetadata?.email,
       });
-    } else if (config.appwriteKey) {
-      // API key authentication (from config file or overrides)
+
+    } else if (authMethod === "apikey") {
+      // Explicit API key preference - use only API key with default mode
+      if (!config.appwriteKey || config.appwriteKey.trim().length === 0) {
+        const error = new Error(
+          "authMethod set to 'apikey' but no API key provided.\n\n" +
+          "Either:\n" +
+          "  - Set appwriteKey in your config file\n" +
+          "  - Provide --apiKey flag\n" +
+          "  - Set APPWRITE_API_KEY environment variable"
+        );
+        logger.error("Failed to create client - API key required", { prefix: "ClientFactory" });
+        throw error;
+      }
       client.setKey(config.appwriteKey);
-      logger.debug("Applied API key authentication to client", {
+      client.headers['X-Appwrite-Mode'] = 'default';
+      logger.debug("Applied API key authentication with default mode (explicit preference)", {
         prefix: "ClientFactory",
       });
+
     } else {
-      // No authentication available - this should have been caught by ConfigManager
-      const error = new Error(
-        "No authentication method available in configuration.\n\n" +
-        "This should have been resolved by ConfigManager during config loading.\n" +
-        "Expected either:\n" +
-        "  - config.sessionCookie (from session authentication)\n" +
-        "  - config.appwriteKey (from config file or CLI overrides)\n\n" +
-        "Suggestion: Ensure ConfigManager.loadConfig() was called before ClientFactory.createFromConfig()."
-      );
-      logger.error("Failed to create client - no authentication", { prefix: "ClientFactory" });
-      throw error;
+      // Auto mode: Prefer session with admin mode (like official CLI), fallback to API key
+      if (config.sessionCookie) {
+        client.setSession(config.sessionCookie);
+        client.headers['X-Appwrite-Mode'] = 'admin';
+        logger.debug("Applied session authentication with admin mode (auto - preferred)", {
+          prefix: "ClientFactory",
+          email: config.sessionMetadata?.email,
+        });
+      } else if (config.appwriteKey && config.appwriteKey.trim().length > 0) {
+        client.setKey(config.appwriteKey);
+        client.headers['X-Appwrite-Mode'] = 'default';
+        logger.debug("Applied API key authentication with default mode (auto - fallback)", {
+          prefix: "ClientFactory",
+        });
+      } else {
+        // No authentication available
+        const error = new Error(
+          "No authentication method available in configuration.\n\n" +
+          "Expected either:\n" +
+          "  - config.sessionCookie (from session authentication via 'appwrite login')\n" +
+          "  - config.appwriteKey (from config file, CLI flags, or environment)\n\n" +
+          "Suggestion:\n" +
+          "  - Run 'appwrite login' to create a session, OR\n" +
+          "  - Add appwriteKey to your config file, OR\n" +
+          "  - Provide --apiKey flag"
+        );
+        logger.error("Failed to create client - no authentication", { prefix: "ClientFactory" });
+        throw error;
+      }
     }
 
     // Create adapter with version detection