appwrite-utils-cli 1.7.3 → 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,17 @@ export class ClientFactory {
         const client = new Client()
             .setEndpoint(config.appwriteEndpoint)
             .setProject(config.appwriteProject);
-        // Apply authentication based on authMethod preference
+        // 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", {
+        logger.debug("Applying authentication with mode headers", {
             prefix: "ClientFactory",
             authMethod,
             hasApiKey: !!config.appwriteKey,
             hasSession: !!config.sessionCookie,
         });
-        if (authMethod === "apikey") {
-            // Explicit API key preference - use only API key
-            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 (explicit preference)", {
-                prefix: "ClientFactory",
-            });
-        }
-        else if (authMethod === "session") {
-            // Explicit session preference - use only session
+        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" +
@@ -96,35 +81,55 @@ export class ClientFactory {
                 throw error;
             }
             client.setSession(config.sessionCookie);
-            logger.debug("Applied session authentication (explicit preference)", {
+            client.headers['X-Appwrite-Mode'] = 'admin';
+            logger.debug("Applied session authentication with admin mode (explicit preference)", {
                 prefix: "ClientFactory",
                 email: config.sessionMetadata?.email,
             });
         }
+        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);
+            client.headers['X-Appwrite-Mode'] = 'default';
+            logger.debug("Applied API key authentication with default mode (explicit preference)", {
+                prefix: "ClientFactory",
+            });
+        }
         else {
-            // Auto mode: Prefer API key if present, fallback to session
-            if (config.appwriteKey && config.appwriteKey.trim().length > 0) {
-                client.setKey(config.appwriteKey);
-                logger.debug("Applied API key authentication (auto mode - preferred)", {
+            // 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.sessionCookie) {
-                client.setSession(config.sessionCookie);
-                logger.debug("Applied session authentication (auto mode - fallback)", {
+            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",
-                    email: config.sessionMetadata?.email,
                 });
             }
             else {
                 // No authentication available
                 const error = new Error("No authentication method available in configuration.\n\n" +
                     "Expected either:\n" +
-                    "  - config.appwriteKey (from config file, CLI flags, or environment)\n" +
-                    "  - config.sessionCookie (from session authentication)\n\n" +
+                    "  - config.sessionCookie (from session authentication via 'appwrite login')\n" +
+                    "  - config.appwriteKey (from config file, CLI flags, or environment)\n\n" +
                     "Suggestion:\n" +
-                    "  - Add appwriteKey to your config file, OR\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;

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.3",
+  "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,36 +67,19 @@ export class ClientFactory {
       .setEndpoint(config.appwriteEndpoint)
       .setProject(config.appwriteProject);
 
-    // Apply authentication based on authMethod preference
+    // 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", {
+    logger.debug("Applying authentication with mode headers", {
       prefix: "ClientFactory",
       authMethod,
       hasApiKey: !!config.appwriteKey,
       hasSession: !!config.sessionCookie,
     });
 
-    if (authMethod === "apikey") {
-      // Explicit API key preference - use only API key
-      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 (explicit preference)", {
-        prefix: "ClientFactory",
-      });
-
-    } else if (authMethod === "session") {
-      // Explicit session preference - use only session
+    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" +
@@ -109,34 +92,56 @@ export class ClientFactory {
         throw error;
       }
       client.setSession(config.sessionCookie);
-      logger.debug("Applied session authentication (explicit preference)", {
+      client.headers['X-Appwrite-Mode'] =  'admin';
+      logger.debug("Applied session authentication with admin mode (explicit preference)", {
         prefix: "ClientFactory",
         email: config.sessionMetadata?.email,
       });
 
+    } 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);
+      client.headers['X-Appwrite-Mode'] = 'default';
+      logger.debug("Applied API key authentication with default mode (explicit preference)", {
+        prefix: "ClientFactory",
+      });
+
     } else {
-      // Auto mode: Prefer API key if present, fallback to session
-      if (config.appwriteKey && config.appwriteKey.trim().length > 0) {
-        client.setKey(config.appwriteKey);
-        logger.debug("Applied API key authentication (auto mode - preferred)", {
-          prefix: "ClientFactory",
-        });
-      } else if (config.sessionCookie) {
+      // Auto mode: Prefer session with admin mode (like official CLI), fallback to API key
+      if (config.sessionCookie) {
         client.setSession(config.sessionCookie);
-        logger.debug("Applied session authentication (auto mode - fallback)", {
+        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.appwriteKey (from config file, CLI flags, or environment)\n" +
-          "  - config.sessionCookie (from session authentication)\n\n" +
+          "  - config.sessionCookie (from session authentication via 'appwrite login')\n" +
+          "  - config.appwriteKey (from config file, CLI flags, or environment)\n\n" +
           "Suggestion:\n" +
-          "  - Add appwriteKey to your config file, OR\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" });