@njdamstra/appwrite-utils-cli 1.8.9

package/src/utils/getClientFromConfig.ts

@@ -0,0 +1,257 @@
+import { type AppwriteConfig } from "@njdamstra/appwrite-utils";
+import { Client } from "node-appwrite";
+import { AdapterFactory, type AdapterFactoryResult } from "../adapters/AdapterFactory.js";
+import type { DatabaseAdapter } from "../adapters/DatabaseAdapter.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
+ */
+export const getClientFromConfig = (config: AppwriteConfig, sessionCookie?: string) => {
+  let appwriteClient: Client | undefined;
+  if (!config.appwriteClient) {
+    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: string,
+  project: string,
+  key?: string,
+  sessionCookie?: string
+): Client => {
+  const client = new Client()
+    .setEndpoint(endpoint)
+    .setProject(project);
+
+  const authAttempts: string[] = [];
+
+  // Priority 1: Explicit session cookie provided
+  if (sessionCookie) {
+    if (isValidSessionCookie(sessionCookie)) {
+      client.setSession(sessionCookie);
+      logger.debug("Using explicit session authentication", { prefix: "Auth", project });
+      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);
+      logger.debug("Using session authentication", { prefix: "Auth", project, email: sessionAuth.email || 'unknown user' });
+      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);
+      logger.debug("Using API key authentication", { prefix: "Auth", project });
+      return client;
+    }
+  }
+
+  // Build detailed error message based on attempted methods
+  const buildAuthError = (): Error => {
+    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 getClientWithAuth for session support or createDatabaseAdapter for dual API support
+ */
+export const getClient = (endpoint: string, project: string, key: string) => {
+  return getClientWithAuth(endpoint, project, key);
+};
+
+/**
+ * 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: AppwriteConfig,
+  forceRefresh?: boolean,
+  sessionCookie?: string
+): Promise<{
+  adapter: DatabaseAdapter;
+  client: Client;
+  apiMode: 'legacy' | 'tablesdb';
+}> => {
+  // 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,
+    apiMode: result.apiMode
+  };
+};
+
+/**
+ * Create adapter from individual parameters with session authentication support
+ */
+export const getAdapter = async (
+  endpoint: string,
+  project: string,
+  key?: string,
+  apiMode: 'auto' | 'legacy' | 'tablesdb' = 'auto',
+  sessionCookie?: string
+): Promise<{
+  adapter: DatabaseAdapter;
+  client: Client;
+  apiMode: 'legacy' | 'tablesdb';
+}> => {
+  // Create config object with session support
+  const config: any = {
+    appwriteEndpoint: endpoint,
+    appwriteProject: project,
+    appwriteKey: key || "",
+    apiMode
+  };
+
+  const authAttempts: string[] = [];
+
+  // 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 = (): Error => {
+        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: string, project: string): boolean => {
+  return hasSessionAuth(endpoint, project);
+};

package/src/utils/helperFunctions.ts

@@ -0,0 +1,228 @@
+import {
+  AppwriteException,
+  type Models,
+  type Storage,
+} from "node-appwrite";
+import fs from "node:fs";
+import path from "node:path";
+import type { CollectionImportData } from "../migrations/dataLoader.js";
+import type { ConfigCollection } from "@njdamstra/appwrite-utils";
+import { getClientWithAuth } from "./getClientFromConfig.js";
+
+export const toPascalCase = (str: string): string => {
+  return (
+    str
+      // Split the string into words on spaces or camelCase transitions
+      .split(/(?:\s+)|(?:([A-Z][a-z]+))/g)
+      // Filter out empty strings that can appear due to the split regex
+      .filter(Boolean)
+      // Capitalize the first letter of each word and join them together
+      .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+      .join("")
+  );
+};
+
+export const toCamelCase = (str: string): string => {
+  return str
+    .replace(/(?:^\w|[A-Z]|\b\w)/g, (word, index) =>
+      index === 0 ? word.toLowerCase() : word.toUpperCase()
+    )
+    .replace(/\s+/g, "");
+};
+
+export const ensureDirectoryExistence = (filePath: string) => {
+  const dirname = path.dirname(filePath);
+  if (fs.existsSync(dirname)) {
+    return true;
+  }
+  ensureDirectoryExistence(dirname);
+  fs.mkdirSync(dirname);
+};
+
+export const writeFileSync = (
+  filePath: string,
+  content: string,
+  options: { flag: string }
+) => {
+  ensureDirectoryExistence(filePath);
+  fs.writeFileSync(filePath, content, options);
+};
+
+export const readFileSync = (filePath: string) => {
+  return fs.readFileSync(filePath, "utf8");
+};
+
+export const existsSync = (filePath: string) => {
+  return fs.existsSync(filePath);
+};
+
+export const mkdirSync = (filePath: string) => {
+  ensureDirectoryExistence(filePath);
+  fs.mkdirSync(filePath);
+};
+
+export const readdirSync = (filePath: string) => {
+  return fs.readdirSync(filePath);
+};
+
+export const areCollectionNamesSame = (a: string, b: string) => {
+  return (
+    a.toLowerCase().trim().replace(" ", "") ===
+    b.toLowerCase().trim().replace(" ", "")
+  );
+};
+
+/**
+ * Generates the view URL for a specific file based on the provided endpoint, project ID, bucket ID, file ID, and optional JWT token.
+ *
+ * @param {string} endpoint - the base URL endpoint
+ * @param {string} projectId - the ID of the project
+ * @param {string} bucketId - the ID of the bucket
+ * @param {string} fileId - the ID of the file
+ * @param {Models.Jwt} [jwt] - optional JWT token generated via the Appwrite SDK
+ * @return {string} the generated view URL for the file
+ */
+export const getFileViewUrl = (
+  endpoint: string,
+  projectId: string,
+  bucketId: string,
+  fileId: string,
+  jwt?: Models.Jwt
+) => {
+  return `${endpoint}/storage/buckets/${bucketId}/files/${fileId}/view?project=${projectId}${
+    jwt ? `&jwt=${jwt.jwt}` : ""
+  }`;
+};
+
+/**
+ * Generates a download URL for a file based on the provided endpoint, project ID, bucket ID, file ID, and optionally a JWT.
+ *
+ * @param {string} endpoint - The base URL endpoint.
+ * @param {string} projectId - The ID of the project.
+ * @param {string} bucketId - The ID of the bucket.
+ * @param {string} fileId - The ID of the file.
+ * @param {Models.Jwt} [jwt] - Optional JWT object for authentication with Appwrite.
+ * @return {string} The complete download URL for the file.
+ */
+export const getFileDownloadUrl = (
+  endpoint: string,
+  projectId: string,
+  bucketId: string,
+  fileId: string,
+  jwt?: Models.Jwt
+) => {
+  return `${endpoint}/storage/buckets/${bucketId}/files/${fileId}/download?project=${projectId}${
+    jwt ? `&jwt=${jwt.jwt}` : ""
+  }`;
+};
+
+export const finalizeByAttributeMap = async (
+  appwriteFolderPath: string,
+  collection: ConfigCollection,
+  item: CollectionImportData["data"][number]
+) => {
+  const schemaFolderPath = path.join(appwriteFolderPath, "schemas");
+  const zodSchema = await import(
+    `${schemaFolderPath}/${toCamelCase(collection.name)}.ts`
+  );
+  return zodSchema.parse({
+    ...item.context,
+    ...item.finalData,
+  });
+};
+
+export let numTimesFailedTotal = 0;
+
+/**
+ * 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).
+ * @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 const tryAwaitWithRetry = async <T>(
+  createFunction: () => Promise<T>,
+  attemptNum: number = 0,
+  throwError: boolean = false
+): Promise<T> => {
+  try {
+    return await createFunction();
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+    const errorCode = (error as any).code;
+
+    // Check if this is a validation error that should NOT be retried
+    const isValidationError =
+      errorCode === 400 || errorCode === 409 || errorCode === 422 ||
+      errorMessage.includes("already exists") ||
+      errorMessage.includes("attribute with the same key") ||
+      errorMessage.includes("invalid") && !errorMessage.includes("fetch failed") ||
+      errorMessage.includes("conflict") ||
+      errorMessage.includes("bad request");
+
+    // Check if this is a transient error that SHOULD be retried
+    const isTransientError =
+      errorCode === 522 || errorCode === "522" ||  // Cloudflare error
+      errorCode >= 500 && errorCode < 600 ||        // 5xx server errors
+      errorMessage.includes("fetch failed") ||      // Network failures
+      errorMessage.includes("timeout") ||
+      errorMessage.includes("econnrefused") ||
+      errorMessage.includes("network error");
+
+    // Only retry if it's a transient error AND not a validation error
+    if (isTransientError && !isValidationError) {
+      if (errorCode === 522 || errorCode === "522") {
+        console.log("Cloudflare error. Retrying...");
+      } else {
+        console.log(`Fetch failed on attempt ${attemptNum}. Retrying...`);
+      }
+      numTimesFailedTotal++;
+      if (attemptNum > 5) {
+        throw error;
+      }
+      await delay(2500);
+      return tryAwaitWithRetry(createFunction, attemptNum + 1);
+    }
+
+    // For validation errors or non-transient errors, throw immediately
+    if (throwError) {
+      throw error;
+    }
+    console.error("Error during retryAwait function: ", error);
+    // @ts-ignore
+    return Promise.resolve();
+  }
+};
+
+export const getAppwriteClient = (
+  endpoint: string,
+  projectId: string,
+  apiKey: string
+) => {
+  return getClientWithAuth(endpoint, projectId, apiKey);
+};
+
+export const delay = (ms: number) =>
+  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: number,
+  baseDelay: number = 2000,
+  maxDelay: number = 30000
+): number => {
+  return Math.min(baseDelay * Math.pow(2, retryCount), maxDelay);
+};

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from "./helperFunctions.js";
+export * from "./setupFiles.js";