@njdamstra/appwrite-utils-cli 1.8.9 → 1.10.1

package/src/utils/getClientFromConfig.ts

@@ -1,257 +0,0 @@
-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

@@ -1,228 +0,0 @@
-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/pathResolvers.ts

@@ -1,81 +0,0 @@
-import path from "path";
-
-/**
- * Path resolution utilities for Appwrite configuration and schema directories
- */
-
-/**
- * Resolves the schema output directory path
- * @param configPath - Base configuration directory path
- * @returns Full path to schemas directory
- */
-export function resolveSchemaDir(configPath: string): string {
-  return path.join(configPath, "schemas");
-}
-
-/**
- * Resolves the collections directory path
- * @param configPath - Base configuration directory path
- * @returns Full path to collections directory
- */
-export function resolveCollectionsDir(configPath: string): string {
-  return path.join(configPath, "collections");
-}
-
-/**
- * Resolves the tables directory path
- * @param configPath - Base configuration directory path
- * @returns Full path to tables directory
- */
-export function resolveTablesDir(configPath: string): string {
-  return path.join(configPath, "tables");
-}
-
-/**
- * Resolves the YAML schema directory path
- * @param configPath - Base configuration directory path
- * @returns Full path to .yaml_schemas directory
- */
-export function resolveYamlSchemaDir(configPath: string): string {
-  return path.join(configPath, ".yaml_schemas");
-}
-
-/**
- * Resolves the import data directory path
- * @param configPath - Base configuration directory path
- * @returns Full path to importData directory
- */
-export function resolveImportDataDir(configPath: string): string {
-  return path.join(configPath, "importData");
-}
-
-/**
- * Resolves the .appwrite configuration directory
- * @param startDir - Directory to start searching from
- * @returns Path to .appwrite directory or null if not found
- */
-export function resolveAppwriteDir(startDir: string): string | null {
-  const appwriteDir = path.join(startDir, ".appwrite");
-  // Note: Actual existence check should be done by caller
-  return appwriteDir;
-}
-
-/**
- * Resolves a collection file path within the collections directory
- * @param configPath - Base configuration directory path
- * @param fileName - Name of the collection file (e.g., "User.ts" or "User.yaml")
- * @returns Full path to the collection file
- */
-export function resolveCollectionFile(configPath: string, fileName: string): string {
-  return path.join(resolveCollectionsDir(configPath), fileName);
-}
-
-/**
- * Resolves a table file path within the tables directory
- * @param configPath - Base configuration directory path
- * @param fileName - Name of the table file (e.g., "User.ts" or "User.yaml")
- * @returns Full path to the table file
- */
-export function resolveTableFile(configPath: string, fileName: string): string {
-  return path.join(resolveTablesDir(configPath), fileName);
-}