appwrite-utils-cli 1.6.3 → 1.6.4

package/dist/config/services/__tests__/ConfigMergeService.test.js

@@ -0,0 +1,271 @@
+import { describe, it, expect, beforeEach, afterEach } from "@jest/globals";
+import { ConfigMergeService } from "../ConfigMergeService.js";
+describe("ConfigMergeService", () => {
+    let service;
+    let baseConfig;
+    let sessionInfo;
+    // Store original env vars
+    const originalEnv = { ...process.env };
+    beforeEach(() => {
+        service = new ConfigMergeService();
+        baseConfig = {
+            appwriteEndpoint: "https://cloud.appwrite.io/v1",
+            appwriteProject: "test-project",
+            appwriteKey: "test-api-key",
+            databases: [],
+            buckets: [],
+            functions: [],
+        };
+        sessionInfo = {
+            projectId: "test-project",
+            endpoint: "https://cloud.appwrite.io/v1",
+            cookie: "eyJhbGc.test.cookie",
+            email: "test@example.com",
+        };
+    });
+    afterEach(() => {
+        // Restore original env vars
+        process.env = { ...originalEnv };
+    });
+    describe("mergeSession", () => {
+        it("should merge session cookie into config", () => {
+            const result = service.mergeSession(baseConfig, sessionInfo);
+            expect(result.sessionCookie).toBe("eyJhbGc.test.cookie");
+            expect(result.authMethod).toBe("session");
+        });
+        it("should not mutate original config", () => {
+            const original = { ...baseConfig };
+            service.mergeSession(baseConfig, sessionInfo);
+            expect(baseConfig).toEqual(original);
+        });
+        it("should preserve all existing config properties", () => {
+            const result = service.mergeSession(baseConfig, sessionInfo);
+            expect(result.appwriteEndpoint).toBe(baseConfig.appwriteEndpoint);
+            expect(result.appwriteProject).toBe(baseConfig.appwriteProject);
+            expect(result.appwriteKey).toBe(baseConfig.appwriteKey);
+        });
+    });
+    describe("applyOverrides", () => {
+        it("should apply all provided overrides", () => {
+            const overrides = {
+                appwriteEndpoint: "https://custom.appwrite.io/v1",
+                appwriteProject: "override-project",
+                appwriteKey: "override-key",
+                sessionCookie: "override-cookie",
+                authMethod: "apikey",
+            };
+            const result = service.applyOverrides(baseConfig, overrides);
+            expect(result.appwriteEndpoint).toBe("https://custom.appwrite.io/v1");
+            expect(result.appwriteProject).toBe("override-project");
+            expect(result.appwriteKey).toBe("override-key");
+            expect(result.sessionCookie).toBe("override-cookie");
+            expect(result.authMethod).toBe("apikey");
+        });
+        it("should skip undefined and null values", () => {
+            const overrides = {
+                appwriteEndpoint: undefined,
+                appwriteProject: null,
+                appwriteKey: "new-key",
+            };
+            const result = service.applyOverrides(baseConfig, overrides);
+            expect(result.appwriteEndpoint).toBe(baseConfig.appwriteEndpoint);
+            expect(result.appwriteProject).toBe(baseConfig.appwriteProject);
+            expect(result.appwriteKey).toBe("new-key");
+        });
+        it("should not mutate original config", () => {
+            const original = { ...baseConfig };
+            const overrides = {
+                appwriteEndpoint: "https://custom.appwrite.io/v1",
+            };
+            service.applyOverrides(baseConfig, overrides);
+            expect(baseConfig).toEqual(original);
+        });
+    });
+    describe("mergeEnvironmentVariables", () => {
+        it("should merge environment variables when config values are not set", () => {
+            process.env.APPWRITE_ENDPOINT = "https://env.appwrite.io/v1";
+            process.env.APPWRITE_PROJECT = "env-project";
+            process.env.APPWRITE_API_KEY = "env-api-key";
+            process.env.APPWRITE_SESSION_COOKIE = "env-cookie";
+            const emptyConfig = {
+                databases: [],
+                buckets: [],
+                functions: [],
+            };
+            const result = service.mergeEnvironmentVariables(emptyConfig);
+            expect(result.appwriteEndpoint).toBe("https://env.appwrite.io/v1");
+            expect(result.appwriteProject).toBe("env-project");
+            expect(result.appwriteKey).toBe("env-api-key");
+            expect(result.sessionCookie).toBe("env-cookie");
+        });
+        it("should not override existing config values", () => {
+            process.env.APPWRITE_ENDPOINT = "https://env.appwrite.io/v1";
+            process.env.APPWRITE_PROJECT = "env-project";
+            const result = service.mergeEnvironmentVariables(baseConfig);
+            expect(result.appwriteEndpoint).toBe(baseConfig.appwriteEndpoint);
+            expect(result.appwriteProject).toBe(baseConfig.appwriteProject);
+        });
+        it("should ignore empty environment variables", () => {
+            process.env.APPWRITE_ENDPOINT = "";
+            process.env.APPWRITE_PROJECT = "";
+            const emptyConfig = {
+                databases: [],
+                buckets: [],
+                functions: [],
+            };
+            const result = service.mergeEnvironmentVariables(emptyConfig);
+            expect(result.appwriteEndpoint).toBeUndefined();
+            expect(result.appwriteProject).toBeUndefined();
+        });
+    });
+    describe("mergeSources", () => {
+        it("should merge multiple sources in priority order", () => {
+            const source1 = {
+                appwriteEndpoint: "https://source1.appwrite.io/v1",
+                appwriteProject: "source1-project",
+            };
+            const source2 = {
+                appwriteProject: "source2-project",
+                appwriteKey: "source2-key",
+            };
+            const source3 = {
+                appwriteKey: "source3-key",
+                sessionCookie: "source3-cookie",
+            };
+            const result = service.mergeSources([source1, source2, source3]);
+            expect(result.appwriteEndpoint).toBe("https://source1.appwrite.io/v1");
+            expect(result.appwriteProject).toBe("source2-project");
+            expect(result.appwriteKey).toBe("source3-key");
+            expect(result.sessionCookie).toBe("source3-cookie");
+        });
+        it("should handle arrays by replacing, not merging", () => {
+            const source1 = {
+                appwriteEndpoint: "https://cloud.appwrite.io/v1",
+                appwriteProject: "test",
+                databases: [{ $id: "db1", name: "db1" }],
+            };
+            const source2 = {
+                databases: [{ $id: "db2", name: "db2" }, { $id: "db3", name: "db3" }],
+            };
+            const result = service.mergeSources([source1, source2]);
+            expect(result.databases).toHaveLength(2);
+            expect(result.databases).toEqual([{ $id: "db2", name: "db2" }, { $id: "db3", name: "db3" }]);
+        });
+        it("should skip undefined and null sources", () => {
+            const source1 = {
+                appwriteEndpoint: "https://cloud.appwrite.io/v1",
+                appwriteProject: "test",
+            };
+            const result = service.mergeSources([
+                source1,
+                undefined,
+                null,
+                { appwriteKey: "key" },
+            ]);
+            expect(result.appwriteEndpoint).toBe("https://cloud.appwrite.io/v1");
+            expect(result.appwriteProject).toBe("test");
+            expect(result.appwriteKey).toBe("key");
+        });
+        it("should throw error when no valid sources provided", () => {
+            expect(() => service.mergeSources([])).toThrow("No valid configuration sources provided for merging");
+            expect(() => service.mergeSources([undefined, null])).toThrow("No valid configuration sources provided for merging");
+        });
+        it("should throw error when merged config lacks required fields", () => {
+            const invalidSource = {
+                appwriteKey: "key",
+            };
+            expect(() => service.mergeSources([invalidSource])).toThrow("Merged configuration is missing required fields");
+        });
+    });
+    describe("mergeAllSources", () => {
+        it("should merge all sources in correct priority order", () => {
+            process.env.APPWRITE_ENDPOINT = "https://env.appwrite.io/v1";
+            process.env.APPWRITE_API_KEY = "env-key";
+            const overrides = {
+                appwriteKey: "override-key",
+            };
+            const result = service.mergeAllSources(baseConfig, {
+                session: sessionInfo,
+                overrides,
+                includeEnv: true,
+            });
+            // Base config endpoint
+            expect(result.appwriteEndpoint).toBe(baseConfig.appwriteEndpoint);
+            // Session should set session cookie
+            expect(result.sessionCookie).toBe(sessionInfo.cookie);
+            // Override should win for API key
+            expect(result.appwriteKey).toBe("override-key");
+        });
+        it("should exclude environment variables when includeEnv is false", () => {
+            process.env.APPWRITE_SESSION_COOKIE = "env-cookie";
+            const configWithoutKey = {
+                ...baseConfig,
+                appwriteKey: undefined,
+            };
+            const result = service.mergeAllSources(configWithoutKey, {
+                includeEnv: false,
+            });
+            expect(result.sessionCookie).toBeUndefined();
+        });
+        it("should work with only base config", () => {
+            const result = service.mergeAllSources(baseConfig, {});
+            expect(result.appwriteEndpoint).toBe(baseConfig.appwriteEndpoint);
+            expect(result.appwriteProject).toBe(baseConfig.appwriteProject);
+        });
+        it("should apply priority: overrides > session > env > base", () => {
+            process.env.APPWRITE_KEY = "env-key";
+            const configWithoutKey = {
+                ...baseConfig,
+                appwriteKey: undefined,
+                sessionCookie: undefined,
+            };
+            // Test with session (should override env)
+            const withSession = service.mergeAllSources(configWithoutKey, {
+                session: sessionInfo,
+                includeEnv: true,
+            });
+            expect(withSession.sessionCookie).toBe(sessionInfo.cookie);
+            expect(withSession.authMethod).toBe("session");
+            // Test with override (should override session)
+            const withOverride = service.mergeAllSources(configWithoutKey, {
+                session: sessionInfo,
+                overrides: { authMethod: "apikey" },
+                includeEnv: true,
+            });
+            expect(withOverride.authMethod).toBe("apikey");
+        });
+    });
+    describe("deep merge behavior", () => {
+        it("should deeply merge nested objects", () => {
+            const source1 = {
+                appwriteEndpoint: "https://cloud.appwrite.io/v1",
+                appwriteProject: "test",
+                databases: [
+                    {
+                        $id: "db1",
+                        name: "Database 1",
+                    },
+                ],
+            };
+            const source2 = {
+                databases: [
+                    {
+                        $id: "db1",
+                        name: "Updated Database",
+                    },
+                ],
+            };
+            const result = service.mergeSources([source1, source2]);
+            // Arrays are replaced, not merged
+            expect(result.databases).toHaveLength(1);
+            expect(result.databases[0].name).toBe("Updated Database");
+        });
+        it("should preserve immutability throughout merge chain", () => {
+            const original1 = { ...baseConfig };
+            const original2 = { appwriteKey: "new-key" };
+            service.mergeSources([baseConfig, original2]);
+            expect(baseConfig).toEqual(original1);
+            expect(original2).toEqual({ appwriteKey: "new-key" });
+        });
+    });
+});

package/dist/config/services/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Configuration Services
+ *
+ * Modular services for configuration management, discovery, loading, validation, and merging.
+ */
+export { ConfigDiscoveryService } from "./ConfigDiscoveryService.js";
+export type { DiscoveryResult } from "./ConfigDiscoveryService.js";
+export { ConfigLoaderService } from "./ConfigLoaderService.js";
+export type { CollectionLoadOptions } from "./ConfigLoaderService.js";
+export { ConfigMergeService } from "./ConfigMergeService.js";
+export type { ConfigOverrides } from "./ConfigMergeService.js";
+export { SessionAuthService, type SessionAuthInfo, type AppwriteSessionPrefs, type AuthenticationStatus } from "./SessionAuthService.js";
+export { ConfigValidationService, type ValidationResult, type ValidationError, type ValidationWarning, type ValidationReportOptions } from "./ConfigValidationService.js";

package/dist/config/services/index.js

@@ -0,0 +1,10 @@
+/**
+ * Configuration Services
+ *
+ * Modular services for configuration management, discovery, loading, validation, and merging.
+ */
+export { ConfigDiscoveryService } from "./ConfigDiscoveryService.js";
+export { ConfigLoaderService } from "./ConfigLoaderService.js";
+export { ConfigMergeService } from "./ConfigMergeService.js";
+export { SessionAuthService } from "./SessionAuthService.js";
+export { ConfigValidationService } from "./ConfigValidationService.js";

package/dist/interactiveCLI.js

@@ -160,12 +160,12 @@ export class InteractiveCLI {
     }
     async initControllerIfNeeded(directConfig) {
         if (!this.controller) {
-            this.controller = new UtilsController(this.currentDir, directConfig);
+            this.controller = UtilsController.getInstance(this.currentDir, directConfig);
             await this.controller.init();
         }
         else {
             // Extract session info from existing controller before reinitializing
-            const sessionInfo = this.controller.getSessionInfo();
+            const sessionInfo = await this.controller.getSessionInfo();
             if (sessionInfo.hasSession && directConfig) {
                 // Create enhanced directConfig with session preservation
                 const enhancedDirectConfig = {
@@ -174,12 +174,14 @@ export class InteractiveCLI {
                     sessionMetadata: this.controller.sessionMetadata
                 };
                 // Reinitialize with session preservation
-                this.controller = new UtilsController(this.currentDir, enhancedDirectConfig);
+                UtilsController.clearInstance();
+                this.controller = UtilsController.getInstance(this.currentDir, enhancedDirectConfig);
                 await this.controller.init();
             }
             else if (directConfig) {
                 // Standard reinitialize without session
-                this.controller = new UtilsController(this.currentDir, directConfig);
+                UtilsController.clearInstance();
+                this.controller = UtilsController.getInstance(this.currentDir, directConfig);
                 await this.controller.init();
             }
             // If no directConfig provided, keep existing controller
@@ -776,11 +778,11 @@ export class InteractiveCLI {
     /**
      * Extract session information from current controller for preservation
      */
-    extractSessionFromController() {
+    async extractSessionFromController() {
         if (!this.controller?.config) {
             return undefined;
         }
-        const sessionInfo = this.controller.getSessionInfo();
+        const sessionInfo = await this.controller.getSessionInfo();
         const config = this.controller.config;
         if (!config.appwriteEndpoint || !config.appwriteProject) {
             return undefined;

package/dist/main.js

@@ -353,8 +353,8 @@ async function main() {
                 argv.useSession = true;
             }
         }
-        // Create controller with session authentication support
-        const controller = new UtilsController(process.cwd(), finalDirectConfig);
+        // Create controller with session authentication support using singleton
+        const controller = UtilsController.getInstance(process.cwd(), finalDirectConfig);
         // Pass session authentication options to the controller
         const initOptions = {};
         if (argv.useSession || argv.sessionCookie) {

package/dist/migrations/yaml/YamlImportConfigLoader.d.ts

@@ -6,8 +6,8 @@ export declare const YamlImportConfigSchema: z.ZodObject<{
         basePath: z.ZodOptional<z.ZodString>;
         type: z.ZodDefault<z.ZodEnum<{
             json: "json";
-            csv: "csv";
             yaml: "yaml";
+            csv: "csv";
         }>>;
     }, z.core.$strip>;
     target: z.ZodObject<{

package/dist/shared/operationQueue.js

@@ -55,7 +55,7 @@ export const clearProcessingState = () => {
     processedCollections.clear();
     processedAttributes.clear();
     nameToIdMapping.clear();
-    MessageFormatter.success("Cleared processing state caches");
+    logger.debug("Cleared processing state caches", { operation: "clearProcessingState", sizeBefore });
     logger.info('Processing state cleared', {
         sizeBefore,
         operation: 'clearProcessingState'

package/dist/utils/ClientFactory.d.ts

@@ -0,0 +1,87 @@
+import { Client } from "node-appwrite";
+import type { AppwriteConfig } from "appwrite-utils";
+import type { DatabaseAdapter } from "../adapters/DatabaseAdapter.js";
+/**
+ * Factory for creating authenticated Appwrite clients and database adapters.
+ *
+ * This factory provides a clean separation of concerns by taking pre-configured
+ * AppwriteConfig objects (with authentication already resolved by ConfigManager)
+ * and creating the necessary client and adapter instances.
+ *
+ * Key features:
+ * - Takes pre-authenticated config from ConfigManager
+ * - Creates client with appropriate authentication method
+ * - Creates adapter with automatic version detection
+ * - Leverages AdapterFactory's internal caching for performance
+ *
+ * @example
+ * ```typescript
+ * const configManager = ConfigManager.getInstance();
+ * const config = await configManager.loadConfig();
+ *
+ * // Config already has session or API key resolved
+ * const { client, adapter } = await ClientFactory.createFromConfig(config);
+ * ```
+ */
+export declare class ClientFactory {
+    /**
+     * Create authenticated client and database adapter from configuration.
+     *
+     * This method expects the config to have authentication already resolved:
+     * - Either `sessionCookie` is set (from ConfigManager's session loading)
+     * - Or `appwriteKey` is set (from config file or CLI overrides)
+     *
+     * The ConfigManager handles all session discovery and authentication priority,
+     * so this factory simply applies the resolved authentication to the client.
+     *
+     * @param config - AppwriteConfig with resolved authentication
+     * @returns Object containing authenticated client and database adapter
+     * @throws Error if no authentication method is available in config
+     *
+     * @example
+     * ```typescript
+     * const config = await ConfigManager.getInstance().loadConfig();
+     * const { client, adapter } = await ClientFactory.createFromConfig(config);
+     *
+     * // Client is now authenticated and ready to use
+     * const databases = new Databases(client);
+     * const collections = await adapter.listCollections(databaseId);
+     * ```
+     */
+    static createFromConfig(config: AppwriteConfig): Promise<{
+        client: Client;
+        adapter: DatabaseAdapter;
+    }>;
+    /**
+     * Create client and adapter from individual parameters.
+     *
+     * This is a lower-level method for cases where you don't have a full
+     * AppwriteConfig object. For most use cases, prefer createFromConfig().
+     *
+     * @param endpoint - Appwrite endpoint URL
+     * @param project - Appwrite project ID
+     * @param options - Authentication and API mode options
+     * @returns Object containing authenticated client and database adapter
+     * @throws Error if no authentication method is provided
+     *
+     * @example
+     * ```typescript
+     * const { client, adapter } = await ClientFactory.create(
+     *   "https://cloud.appwrite.io/v1",
+     *   "my-project-id",
+     *   {
+     *     apiKey: "my-api-key",
+     *     apiMode: "auto"
+     *   }
+     * );
+     * ```
+     */
+    static create(endpoint: string, project: string, options?: {
+        apiKey?: string;
+        sessionCookie?: string;
+        apiMode?: "auto" | "legacy" | "tablesdb";
+    }): Promise<{
+        client: Client;
+        adapter: DatabaseAdapter;
+    }>;
+}

package/dist/utils/ClientFactory.js

@@ -0,0 +1,164 @@
+import { Client } from "node-appwrite";
+import { AdapterFactory } from "../adapters/AdapterFactory.js";
+import { logger } from "../shared/logging.js";
+/**
+ * Factory for creating authenticated Appwrite clients and database adapters.
+ *
+ * This factory provides a clean separation of concerns by taking pre-configured
+ * AppwriteConfig objects (with authentication already resolved by ConfigManager)
+ * and creating the necessary client and adapter instances.
+ *
+ * Key features:
+ * - Takes pre-authenticated config from ConfigManager
+ * - Creates client with appropriate authentication method
+ * - Creates adapter with automatic version detection
+ * - Leverages AdapterFactory's internal caching for performance
+ *
+ * @example
+ * ```typescript
+ * const configManager = ConfigManager.getInstance();
+ * const config = await configManager.loadConfig();
+ *
+ * // Config already has session or API key resolved
+ * const { client, adapter } = await ClientFactory.createFromConfig(config);
+ * ```
+ */
+export class ClientFactory {
+    /**
+     * Create authenticated client and database adapter from configuration.
+     *
+     * This method expects the config to have authentication already resolved:
+     * - Either `sessionCookie` is set (from ConfigManager's session loading)
+     * - Or `appwriteKey` is set (from config file or CLI overrides)
+     *
+     * The ConfigManager handles all session discovery and authentication priority,
+     * so this factory simply applies the resolved authentication to the client.
+     *
+     * @param config - AppwriteConfig with resolved authentication
+     * @returns Object containing authenticated client and database adapter
+     * @throws Error if no authentication method is available in config
+     *
+     * @example
+     * ```typescript
+     * const config = await ConfigManager.getInstance().loadConfig();
+     * const { client, adapter } = await ClientFactory.createFromConfig(config);
+     *
+     * // Client is now authenticated and ready to use
+     * const databases = new Databases(client);
+     * const collections = await adapter.listCollections(databaseId);
+     * ```
+     */
+    static async createFromConfig(config) {
+        logger.debug("Creating client from config", {
+            prefix: "ClientFactory",
+            hasSession: !!config.sessionCookie,
+            hasApiKey: !!config.appwriteKey,
+            endpoint: config.appwriteEndpoint,
+            project: config.appwriteProject,
+        });
+        // Create base client with endpoint and project
+        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)
+            client.setSession(config.sessionCookie);
+            logger.debug("Applied session authentication to client", {
+                prefix: "ClientFactory",
+                email: config.sessionMetadata?.email,
+            });
+        }
+        else if (config.appwriteKey) {
+            // API key authentication (from config file or overrides)
+            client.setKey(config.appwriteKey);
+            logger.debug("Applied API key authentication to client", {
+                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;
+        }
+        // Create adapter with version detection
+        // AdapterFactory uses internal caching, so repeated calls are fast
+        logger.debug("Creating database adapter", {
+            prefix: "ClientFactory",
+            apiMode: config.apiMode || "auto",
+        });
+        const { adapter } = await AdapterFactory.createFromConfig(config);
+        logger.debug("Client and adapter created successfully", {
+            prefix: "ClientFactory",
+            adapterType: adapter.getApiMode(),
+        });
+        return { client, adapter };
+    }
+    /**
+     * Create client and adapter from individual parameters.
+     *
+     * This is a lower-level method for cases where you don't have a full
+     * AppwriteConfig object. For most use cases, prefer createFromConfig().
+     *
+     * @param endpoint - Appwrite endpoint URL
+     * @param project - Appwrite project ID
+     * @param options - Authentication and API mode options
+     * @returns Object containing authenticated client and database adapter
+     * @throws Error if no authentication method is provided
+     *
+     * @example
+     * ```typescript
+     * const { client, adapter } = await ClientFactory.create(
+     *   "https://cloud.appwrite.io/v1",
+     *   "my-project-id",
+     *   {
+     *     apiKey: "my-api-key",
+     *     apiMode: "auto"
+     *   }
+     * );
+     * ```
+     */
+    static async create(endpoint, project, options = {}) {
+        logger.debug("Creating client from parameters", {
+            prefix: "ClientFactory",
+            hasSession: !!options.sessionCookie,
+            hasApiKey: !!options.apiKey,
+            endpoint,
+            project,
+        });
+        // Create minimal config object
+        const config = {
+            appwriteEndpoint: endpoint,
+            appwriteProject: project,
+            appwriteKey: options.apiKey || "",
+            sessionCookie: options.sessionCookie,
+            apiMode: options.apiMode || "auto",
+            // Minimal required fields
+            appwriteClient: null,
+            authMethod: options.sessionCookie ? "session" : "apikey",
+            enableBackups: false,
+            backupInterval: 0,
+            backupRetention: 0,
+            enableBackupCleanup: false,
+            enableMockData: false,
+            documentBucketId: "",
+            usersCollectionName: "",
+            databases: [],
+            buckets: [],
+            functions: [],
+            logging: {
+                enabled: false,
+                level: "info",
+                console: false,
+            },
+        };
+        // Use main createFromConfig method
+        return this.createFromConfig(config);
+    }
+}

package/dist/utils/getClientFromConfig.js

@@ -3,6 +3,7 @@ import { Client } from "node-appwrite";
 import { AdapterFactory } from "../adapters/AdapterFactory.js";
 import { findSessionByEndpointAndProject, hasSessionAuth, isValidSessionCookie } from "./sessionAuth.js";
 import { MessageFormatter } from "../shared/messageFormatter.js";
+import { logger } from "../shared/logging.js";
 /**
  * Enhanced client creation from config with session authentication support
  * @deprecated Use getAdapterFromConfig for dual API support with session auth
@@ -28,7 +29,7 @@ export const getClientWithAuth = (endpoint, project, key, sessionCookie) => {
     if (sessionCookie) {
         if (isValidSessionCookie(sessionCookie)) {
             client.setSession(sessionCookie);
-            MessageFormatter.info(`Using explicit session authentication for project ${project}`, { prefix: "Auth" });
+            logger.debug("Using explicit session authentication", { prefix: "Auth", project });
             return client;
         }
         else {
@@ -41,7 +42,7 @@ export const getClientWithAuth = (endpoint, project, key, sessionCookie) => {
     if (sessionAuth) {
         if (isValidSessionCookie(sessionAuth.sessionCookie)) {
             client.setSession(sessionAuth.sessionCookie);
-            MessageFormatter.info(`Using session authentication for project ${project} (${sessionAuth.email || 'unknown user'})`, { prefix: "Auth" });
+            logger.debug("Using session authentication", { prefix: "Auth", project, email: sessionAuth.email || 'unknown user' });
             return client;
         }
         else {
@@ -56,7 +57,7 @@ export const getClientWithAuth = (endpoint, project, key, sessionCookie) => {
         }
         else {
             client.setKey(key);
-            MessageFormatter.info(`Using API key authentication for project ${project}`, { prefix: "Auth" });
+            logger.debug("Using API key authentication", { prefix: "Auth", project });
             return client;
         }
     }

package/dist/utils/helperFunctions.d.ts

@@ -38,6 +38,7 @@ export declare const finalizeByAttributeMap: (appwriteFolderPath: string, collec
 export declare let numTimesFailedTotal: number;
 /**
  * Tries to execute the given createFunction and retries up to 5 times if it fails.
+ * Only retries on transient errors (network failures, 5xx errors). Does NOT retry validation errors (4xx).
  *
  * @param {() => Promise<any>} createFunction - The function to be executed.
  * @param {number} [attemptNum=0] - The number of attempts made so far (default: 0).