appwrite-utils-cli 1.5.2 → 1.6.0

package/dist/utils/getClientFromConfig.js

@@ -1,34 +1,116 @@
 import {} from "appwrite-utils";
 import { Client } from "node-appwrite";
 import { AdapterFactory } from "../adapters/AdapterFactory.js";
+import { findSessionByEndpointAndProject, hasSessionAuth, isValidSessionCookie } from "./sessionAuth.js";
+import { MessageFormatter } from "../shared/messageFormatter.js";
 /**
- * Legacy function - returns basic Client for backwards compatibility
- * @deprecated Use getAdapterFromConfig for dual API support
+ * Enhanced client creation from config with session authentication support
+ * @deprecated Use getAdapterFromConfig for dual API support with session auth
  */
-export const getClientFromConfig = (config) => {
+export const getClientFromConfig = (config, sessionCookie) => {
     let appwriteClient;
     if (!config.appwriteClient) {
-        appwriteClient = new Client()
-            .setEndpoint(config.appwriteEndpoint)
-            .setProject(config.appwriteProject)
-            .setKey(config.appwriteKey);
+        appwriteClient = getClientWithAuth(config.appwriteEndpoint, config.appwriteProject, config.appwriteKey, sessionCookie);
         config.appwriteClient = appwriteClient;
     }
     return appwriteClient;
 };
+/**
+ * Enhanced client creation with session authentication support
+ * Priority: explicit session > session from prefs > API key
+ */
+export const getClientWithAuth = (endpoint, project, key, sessionCookie) => {
+    const client = new Client()
+        .setEndpoint(endpoint)
+        .setProject(project);
+    const authAttempts = [];
+    // Priority 1: Explicit session cookie provided
+    if (sessionCookie) {
+        if (isValidSessionCookie(sessionCookie)) {
+            client.setSession(sessionCookie);
+            MessageFormatter.info(`Using explicit session authentication for project ${project}`, { prefix: "Auth" });
+            return client;
+        }
+        else {
+            authAttempts.push("explicit session cookie (invalid format)");
+            MessageFormatter.warning(`Provided session cookie has invalid format`, { prefix: "Auth" });
+        }
+    }
+    // Priority 2: Session from Appwrite CLI prefs
+    const sessionAuth = findSessionByEndpointAndProject(endpoint, project);
+    if (sessionAuth) {
+        if (isValidSessionCookie(sessionAuth.sessionCookie)) {
+            client.setSession(sessionAuth.sessionCookie);
+            MessageFormatter.info(`Using session authentication for project ${project} (${sessionAuth.email || 'unknown user'})`, { prefix: "Auth" });
+            return client;
+        }
+        else {
+            authAttempts.push("session from CLI prefs (invalid/expired)");
+            MessageFormatter.warning(`Session cookie from CLI prefs is invalid or expired`, { prefix: "Auth" });
+        }
+    }
+    // Priority 3: API key fallback
+    if (key) {
+        if (key.trim() === "") {
+            authAttempts.push("API key (empty)");
+        }
+        else {
+            client.setKey(key);
+            MessageFormatter.info(`Using API key authentication for project ${project}`, { prefix: "Auth" });
+            return client;
+        }
+    }
+    // Build detailed error message based on attempted methods
+    const buildAuthError = () => {
+        let errorMessage = `No valid authentication method available for project '${project}'.\n\n`;
+        if (authAttempts.length > 0) {
+            errorMessage += `Authentication methods attempted:\n`;
+            authAttempts.forEach(attempt => {
+                errorMessage += `  ✗ ${attempt}\n`;
+            });
+            errorMessage += `\n`;
+        }
+        errorMessage += `Available authentication options:\n`;
+        errorMessage += `  1. Session Authentication (Recommended):\n`;
+        errorMessage += `     Run: appwrite login\n`;
+        errorMessage += `     Then select your project and login with your account\n\n`;
+        errorMessage += `  2. API Key Authentication:\n`;
+        errorMessage += `     - Set appwriteKey in your configuration\n`;
+        errorMessage += `     - Or provide via --key command line option\n`;
+        errorMessage += `     - Get your API key from: ${endpoint}/console/project-${project}/settings/keys\n\n`;
+        errorMessage += `  3. Environment Variables:\n`;
+        errorMessage += `     Set APPWRITE_API_KEY environment variable\n\n`;
+        errorMessage += `For more help, visit: https://appwrite.io/docs/tooling/command-line/installation`;
+        return new Error(errorMessage);
+    };
+    throw buildAuthError();
+};
 /**
  * Legacy function - returns basic Client
- * @deprecated Use createDatabaseAdapter for dual API support
+ * @deprecated Use getClientWithAuth for session support or createDatabaseAdapter for dual API support
  */
 export const getClient = (endpoint, project, key) => {
-    return new Client().setEndpoint(endpoint).setProject(project).setKey(key);
+    return getClientWithAuth(endpoint, project, key);
 };
 /**
- * Modern adapter-based client creation with dual API support
+ * Modern adapter-based client creation with dual API support and session authentication
  * Returns both adapter and legacy client for compatibility
  */
-export const getAdapterFromConfig = async (config, forceRefresh) => {
-    const result = await AdapterFactory.createFromConfig(config, forceRefresh);
+export const getAdapterFromConfig = async (config, forceRefresh, sessionCookie) => {
+    // Create enhanced config with session support
+    const enhancedConfig = { ...config };
+    // Check for session authentication if no explicit session provided
+    if (!sessionCookie && !config.appwriteKey) {
+        const sessionAuth = findSessionByEndpointAndProject(config.appwriteEndpoint, config.appwriteProject);
+        if (sessionAuth && isValidSessionCookie(sessionAuth.sessionCookie)) {
+            sessionCookie = sessionAuth.sessionCookie;
+        }
+    }
+    // Override client creation in factory if session auth is available
+    if (sessionCookie && isValidSessionCookie(sessionCookie)) {
+        enhancedConfig.appwriteClient = getClientWithAuth(config.appwriteEndpoint, config.appwriteProject, config.appwriteKey, sessionCookie);
+    }
+    const result = await AdapterFactory.createFromConfig(enhancedConfig, forceRefresh);
     return {
         adapter: result.adapter,
         client: result.client,
@@ -36,18 +118,81 @@ export const getAdapterFromConfig = async (config, forceRefresh) => {
     };
 };
 /**
- * Create adapter from individual parameters
+ * Create adapter from individual parameters with session authentication support
  */
-export const getAdapter = async (endpoint, project, key, apiMode = 'auto') => {
-    const result = await AdapterFactory.create({
+export const getAdapter = async (endpoint, project, key, apiMode = 'auto', sessionCookie) => {
+    // Create config object with session support
+    const config = {
         appwriteEndpoint: endpoint,
         appwriteProject: project,
-        appwriteKey: key,
+        appwriteKey: key || "",
         apiMode
-    });
+    };
+    const authAttempts = [];
+    // Use session auth if available, otherwise fall back to API key
+    if (sessionCookie) {
+        if (isValidSessionCookie(sessionCookie)) {
+            config.appwriteClient = getClientWithAuth(endpoint, project, key, sessionCookie);
+        }
+        else {
+            authAttempts.push("explicit session cookie (invalid format)");
+        }
+    }
+    else if (!key) {
+        // Try to find session auth if no API key provided
+        const sessionAuth = findSessionByEndpointAndProject(endpoint, project);
+        if (sessionAuth) {
+            if (isValidSessionCookie(sessionAuth.sessionCookie)) {
+                config.appwriteClient = getClientWithAuth(endpoint, project, key, sessionAuth.sessionCookie);
+            }
+            else {
+                authAttempts.push("session from CLI prefs (invalid/expired)");
+            }
+        }
+        else {
+            authAttempts.push("session from CLI prefs (not found)");
+        }
+        // If no valid authentication found, build detailed error
+        if (!config.appwriteClient) {
+            const buildDetailedAuthError = () => {
+                let errorMessage = `No valid authentication method available for project '${project}'.\n\n`;
+                if (authAttempts.length > 0) {
+                    errorMessage += `Authentication methods attempted:\n`;
+                    authAttempts.forEach(attempt => {
+                        errorMessage += `  ✗ ${attempt}\n`;
+                    });
+                    errorMessage += `\n`;
+                }
+                errorMessage += `Available authentication options:\n`;
+                errorMessage += `  1. Session Authentication (Recommended):\n`;
+                errorMessage += `     Run: appwrite login\n`;
+                errorMessage += `     Then select your project and login with your account\n`;
+                errorMessage += `     This will save session credentials to ~/.appwrite/prefs.json\n\n`;
+                errorMessage += `  2. API Key Authentication:\n`;
+                errorMessage += `     - Provide API key via --key command line option\n`;
+                errorMessage += `     - Or set appwriteKey in your configuration file\n`;
+                errorMessage += `     - Get your API key from: ${endpoint}/console/project-${project}/settings/keys\n\n`;
+                errorMessage += `  3. Environment Variables:\n`;
+                errorMessage += `     Set APPWRITE_API_KEY environment variable\n\n`;
+                // Check if CLI is installed
+                errorMessage += `Note: Ensure Appwrite CLI is installed:\n`;
+                errorMessage += `  npm install -g appwrite-cli\n\n`;
+                errorMessage += `For more help, visit: https://appwrite.io/docs/tooling/command-line/installation`;
+                return new Error(errorMessage);
+            };
+            throw buildDetailedAuthError();
+        }
+    }
+    const result = await AdapterFactory.create(config);
     return {
         adapter: result.adapter,
         client: result.client,
         apiMode: result.apiMode
     };
 };
+/**
+ * Check if session authentication is available for a project
+ */
+export const checkSessionAuth = (endpoint, project) => {
+    return hasSessionAuth(endpoint, project);
+};

package/dist/utils/helperFunctions.d.ts

@@ -1,4 +1,4 @@
-import { Client, type Models } from "node-appwrite";
+import { type Models } from "node-appwrite";
 import type { CollectionImportData } from "../migrations/dataLoader.js";
 import type { ConfigCollection } from "appwrite-utils";
 export declare const toPascalCase: (str: string) => string;
@@ -44,5 +44,19 @@ export declare let numTimesFailedTotal: number;
  * @return {Promise<any>} - A promise that resolves to the result of the createFunction or rejects with an error if it fails after 5 attempts.
  */
 export declare const tryAwaitWithRetry: <T>(createFunction: () => Promise<T>, attemptNum?: number, throwError?: boolean) => Promise<T>;
-export declare const getAppwriteClient: (endpoint: string, projectId: string, apiKey: string) => Client;
+export declare const getAppwriteClient: (endpoint: string, projectId: string, apiKey: string) => import("node-appwrite").Client;
 export declare const delay: (ms: number) => Promise<unknown>;
+/**
+ * Calculates exponential backoff delay with configurable base and maximum
+ *
+ * @param retryCount - Current retry attempt number (0-indexed)
+ * @param baseDelay - Base delay in milliseconds (default: 2000)
+ * @param maxDelay - Maximum delay cap in milliseconds (default: 30000)
+ * @returns Calculated delay in milliseconds
+ *
+ * @example
+ * calculateExponentialBackoff(0) // Returns 2000
+ * calculateExponentialBackoff(1) // Returns 4000
+ * calculateExponentialBackoff(5) // Returns 30000 (capped)
+ */
+export declare const calculateExponentialBackoff: (retryCount: number, baseDelay?: number, maxDelay?: number) => number;

package/dist/utils/helperFunctions.js

@@ -1,6 +1,7 @@
-import { AppwriteException, Client, } from "node-appwrite";
+import { AppwriteException, } from "node-appwrite";
 import fs from "node:fs";
 import path from "node:path";
+import { getClientWithAuth } from "./getClientFromConfig.js";
 export const toPascalCase = (str) => {
     return (str
         // Split the string into words on spaces or camelCase transitions
@@ -118,9 +119,22 @@ export const tryAwaitWithRetry = async (createFunction, attemptNum = 0, throwErr
     }
 };
 export const getAppwriteClient = (endpoint, projectId, apiKey) => {
-    return new Client()
-        .setEndpoint(endpoint)
-        .setProject(projectId)
-        .setKey(apiKey);
+    return getClientWithAuth(endpoint, projectId, apiKey);
 };
 export const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Calculates exponential backoff delay with configurable base and maximum
+ *
+ * @param retryCount - Current retry attempt number (0-indexed)
+ * @param baseDelay - Base delay in milliseconds (default: 2000)
+ * @param maxDelay - Maximum delay cap in milliseconds (default: 30000)
+ * @returns Calculated delay in milliseconds
+ *
+ * @example
+ * calculateExponentialBackoff(0) // Returns 2000
+ * calculateExponentialBackoff(1) // Returns 4000
+ * calculateExponentialBackoff(5) // Returns 30000 (capped)
+ */
+export const calculateExponentialBackoff = (retryCount, baseDelay = 2000, maxDelay = 30000) => {
+    return Math.min(baseDelay * Math.pow(2, retryCount), maxDelay);
+};

package/dist/utils/loadConfigs.d.ts

@@ -1,25 +1,50 @@
 import { type AppwriteConfig } from "appwrite-utils";
+import { type ValidationResult } from "../config/configValidation.js";
 /**
- * Recursively searches for configuration files starting from the given directory.
- * Priority: 1) YAML configs in .appwrite directories, 2) appwriteConfig.ts files in subdirectories
- * @param dir The directory to start the search from.
- * @returns The directory path where the config was found, suitable for passing to loadConfig().
+ * Session authentication preservation options for config loading
  */
-export declare const findAppwriteConfig: (dir: string) => string | null;
+export interface SessionPreservationOptions {
+    sessionCookie?: string;
+    authMethod?: "session" | "apikey" | "auto";
+    sessionMetadata?: {
+        email?: string;
+        expiresAt?: string;
+    };
+}
+/**
+ * Configuration loading options
+ */
+export interface ConfigLoadingOptions {
+    validate?: boolean;
+    strictMode?: boolean;
+    reportValidation?: boolean;
+    preserveAuth?: SessionPreservationOptions;
+}
+/**
+ * Helper function to create session preservation options from session data
+ * @param sessionCookie The session cookie string
+ * @param email Optional email associated with the session
+ * @param expiresAt Optional expiration timestamp
+ * @returns SessionPreservationOptions object
+ */
+export declare function createSessionPreservation(sessionCookie: string, email?: string, expiresAt?: string): SessionPreservationOptions;
+export { findAppwriteConfig, findFunctionsDir } from "./configDiscovery.js";
 /**
  * Loads the Appwrite configuration and returns both config and the path where it was found.
  * @param configDir The directory to search for config files.
- * @returns Object containing the config and the actual path where it was found.
+ * @param options Loading options including validation settings and session preservation.
+ * @returns Object containing the config, path, and validation results.
  */
-export declare const loadConfigWithPath: (configDir: string) => Promise<{
+export declare const loadConfigWithPath: (configDir: string, options?: ConfigLoadingOptions) => Promise<{
     config: AppwriteConfig;
     actualConfigPath: string;
+    validation?: ValidationResult;
 }>;
 /**
  * Loads the Appwrite configuration and all collection configurations from a specified directory.
  * Supports both YAML and TypeScript config formats with backward compatibility.
  * @param configDir The directory containing the config file and collections folder.
+ * @param options Loading options including validation settings and session preservation.
  * @returns The loaded Appwrite configuration including collections.
  */
-export declare const loadConfig: (configDir: string) => Promise<AppwriteConfig>;
-export declare const findFunctionsDir: (dir: string, depth?: number) => string | null;
+export declare const loadConfig: (configDir: string, options?: ConfigLoadingOptions) => Promise<AppwriteConfig>;