@njdamstra/appwrite-utils-cli 1.8.9

package/dist/utils/dataConverters.js

@@ -0,0 +1,139 @@
+import { converterFunctions } from "@njdamstra/appwrite-utils";
+import { cloneDeep, isPlainObject } from "es-toolkit";
+/**
+ * Deeply converts all properties of an object (or array) to strings.
+ * @param data The input data to convert.
+ * @returns The data with all its properties converted to strings.
+ */
+export const deepAnyToString = (data) => {
+    if (Array.isArray(data)) {
+        return data.map((item) => deepAnyToString(item));
+    }
+    else if (isPlainObject(data)) {
+        return Object.keys(data).reduce((acc, key) => {
+            acc[key] = deepAnyToString(data[key]);
+            return acc;
+        }, {});
+    }
+    else {
+        return converterFunctions.anyToString(data);
+    }
+};
+/**
+ * Performs a deep conversion of all values in a nested structure to the specified type.
+ * Uses a conversion function like anyToString, anyToNumber, etc.
+ * @param data The data to convert.
+ * @param convertFn The conversion function to apply.
+ * @returns The converted data.
+ */
+export const deepConvert = (data, convertFn) => {
+    if (Array.isArray(data)) {
+        return data.map((item) => deepConvert(item, convertFn));
+    }
+    else if (isPlainObject(data)) {
+        return Object.keys(data).reduce((acc, key) => {
+            acc[key] = deepConvert(data[key], convertFn);
+            return acc;
+        }, {});
+    }
+    else {
+        return convertFn(data);
+    }
+};
+/**
+ * Converts an entire object's properties to different types based on a provided schema.
+ * @param obj The object to convert.
+ * @param schema A mapping of object keys to conversion functions.
+ * @returns The converted object.
+ */
+export const convertObjectBySchema = (obj, schema) => {
+    return Object.keys(obj).reduce((acc, key) => {
+        const convertFn = schema[key];
+        acc[key] = convertFn ? convertFn(obj[key]) : obj[key];
+        return acc;
+    }, {});
+};
+/**
+ * Converts the keys of an object based on a provided attributeMappings.
+ * Each key in the object is checked against attributeMappings; if a matching entry is found,
+ * the key is renamed to the targetKey specified in attributeMappings.
+ *
+ * @param obj The object to convert.
+ * @param attributeMappings The attributeMappings defining how keys in the object should be converted.
+ * @returns The converted object with keys renamed according to attributeMappings.
+ */
+export const convertObjectByAttributeMappings = (obj, attributeMappings) => {
+    const result = {};
+    // Correctly handle [any] notation by mapping or aggregating over all elements or keys
+    const resolveValue = (obj, path) => {
+        const parts = path.split(".");
+        let current = obj;
+        for (let i = 0; i < parts.length; i++) {
+            if (parts[i] === "[any]") {
+                if (Array.isArray(current)) {
+                    // If current is an array, apply resolution to each item
+                    return current.map((item) => resolveValue(item, parts.slice(i + 1).join(".")));
+                }
+                else if (typeof current === "object" && current !== null) {
+                    // If current is an object, aggregate values from all keys
+                    return Object.values(current).map((value) => resolveValue(value, parts.slice(i + 1).join(".")));
+                }
+            }
+            else {
+                current = current[parts[i]];
+                if (current === undefined)
+                    return undefined;
+            }
+        }
+        return current;
+    };
+    for (const mapping of attributeMappings) {
+        if (mapping.valueToSet !== undefined) {
+            result[mapping.targetKey] = mapping.valueToSet;
+        }
+        else if (Array.isArray(mapping.oldKeys)) {
+            // Collect and flatten values from multiple oldKeys
+            const values = mapping.oldKeys
+                .map((oldKey) => resolveValue(obj, oldKey))
+                .flat(Infinity);
+            if (values.length > 0) {
+                result[mapping.targetKey] = values.filter((value) => value !== undefined);
+            }
+            else {
+                result[mapping.targetKey] = null;
+            }
+        }
+        else if (mapping.oldKey) {
+            // Resolve single oldKey
+            const value = resolveValue(obj, mapping.oldKey);
+            if (value !== undefined) {
+                result[mapping.targetKey] = Array.isArray(value)
+                    ? value.flat(Infinity)
+                    : value;
+            }
+            else {
+                result[mapping.targetKey] = value ? value : null;
+            }
+        }
+    }
+    return result;
+};
+/**
+ * Ensures data conversion without mutating the original input.
+ * @param data The data to convert.
+ * @param convertFn The conversion function to apply.
+ * @returns The converted data.
+ */
+export const immutableConvert = (data, convertFn) => {
+    const clonedData = cloneDeep(data);
+    return convertFn(clonedData);
+};
+/**
+ * Validates a string against a regular expression and returns the string if valid, or null.
+ * @param value The string to validate.
+ * @param pattern The regex pattern to validate against.
+ * @returns The original string if valid, otherwise null.
+ */
+export const validateString = (value, pattern) => {
+    return pattern.test(value) ? value : null;
+};

package/dist/utils/directoryUtils.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Directory utility functions for filtering and managing directory traversal
+ */
+/**
+ * List of directories that should be ignored during recursive searches
+ * Includes common build outputs, dependencies, caches, and system folders
+ */
+export declare const IGNORED_DIRECTORIES: string[];
+/**
+ * Determines if a directory should be ignored during recursive file operations
+ *
+ * @param dirName - The name of the directory to check
+ * @returns true if the directory should be ignored, false otherwise
+ *
+ * @remarks
+ * A directory is ignored if:
+ * - It matches one of the entries in IGNORED_DIRECTORIES
+ * - It starts with '.git' prefix
+ * - It starts with 'node_modules' prefix
+ * - It starts with '.' (hidden directory) except for '.appwrite'
+ */
+export declare const shouldIgnoreDirectory: (dirName: string) => boolean;

package/dist/utils/directoryUtils.js

@@ -0,0 +1,59 @@
+/**
+ * Directory utility functions for filtering and managing directory traversal
+ */
+/**
+ * List of directories that should be ignored during recursive searches
+ * Includes common build outputs, dependencies, caches, and system folders
+ */
+export const IGNORED_DIRECTORIES = [
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+    '.next',
+    '.nuxt',
+    '.cache',
+    '.git',
+    '.svn',
+    '.hg',
+    '__pycache__',
+    '.pytest_cache',
+    '.mypy_cache',
+    'venv',
+    '.venv',
+    'env',
+    '.env',
+    'target',
+    'out',
+    'bin',
+    'obj',
+    '.vs',
+    '.vscode',
+    '.idea',
+    'temp',
+    'tmp',
+    '.tmp',
+    'logs',
+    'log',
+    '.DS_Store',
+    'Thumbs.db'
+];
+/**
+ * Determines if a directory should be ignored during recursive file operations
+ *
+ * @param dirName - The name of the directory to check
+ * @returns true if the directory should be ignored, false otherwise
+ *
+ * @remarks
+ * A directory is ignored if:
+ * - It matches one of the entries in IGNORED_DIRECTORIES
+ * - It starts with '.git' prefix
+ * - It starts with 'node_modules' prefix
+ * - It starts with '.' (hidden directory) except for '.appwrite'
+ */
+export const shouldIgnoreDirectory = (dirName) => {
+    return IGNORED_DIRECTORIES.includes(dirName) ||
+        dirName.startsWith('.git') ||
+        dirName.startsWith('node_modules') ||
+        (dirName.startsWith('.') && dirName !== '.appwrite');
+};

package/dist/utils/getClientFromConfig.d.ts

@@ -0,0 +1,39 @@
+import { type AppwriteConfig } from "@njdamstra/appwrite-utils";
+import { Client } from "node-appwrite";
+import type { DatabaseAdapter } from "../adapters/DatabaseAdapter.js";
+/**
+ * Enhanced client creation from config with session authentication support
+ * @deprecated Use getAdapterFromConfig for dual API support with session auth
+ */
+export declare const getClientFromConfig: (config: AppwriteConfig, sessionCookie?: string) => Client | undefined;
+/**
+ * Enhanced client creation with session authentication support
+ * Priority: explicit session > session from prefs > API key
+ */
+export declare const getClientWithAuth: (endpoint: string, project: string, key?: string, sessionCookie?: string) => Client;
+/**
+ * Legacy function - returns basic Client
+ * @deprecated Use getClientWithAuth for session support or createDatabaseAdapter for dual API support
+ */
+export declare const getClient: (endpoint: string, project: string, key: string) => Client;
+/**
+ * Modern adapter-based client creation with dual API support and session authentication
+ * Returns both adapter and legacy client for compatibility
+ */
+export declare const getAdapterFromConfig: (config: AppwriteConfig, forceRefresh?: boolean, sessionCookie?: string) => Promise<{
+    adapter: DatabaseAdapter;
+    client: Client;
+    apiMode: "legacy" | "tablesdb";
+}>;
+/**
+ * Create adapter from individual parameters with session authentication support
+ */
+export declare const getAdapter: (endpoint: string, project: string, key?: string, apiMode?: "auto" | "legacy" | "tablesdb", sessionCookie?: string) => Promise<{
+    adapter: DatabaseAdapter;
+    client: Client;
+    apiMode: "legacy" | "tablesdb";
+}>;
+/**
+ * Check if session authentication is available for a project
+ */
+export declare const checkSessionAuth: (endpoint: string, project: string) => boolean;

package/dist/utils/getClientFromConfig.js

@@ -0,0 +1,199 @@
+import {} from "@njdamstra/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";
+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, sessionCookie) => {
+    let appwriteClient;
+    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, 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);
+            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 = () => {
+        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, project, key) => {
+    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, 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,
+        apiMode: result.apiMode
+    };
+};
+/**
+ * Create adapter from individual parameters with session authentication support
+ */
+export const getAdapter = async (endpoint, project, key, apiMode = 'auto', sessionCookie) => {
+    // Create config object with session support
+    const config = {
+        appwriteEndpoint: endpoint,
+        appwriteProject: project,
+        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

@@ -0,0 +1,63 @@
+import { type Models } from "node-appwrite";
+import type { CollectionImportData } from "../migrations/dataLoader.js";
+import type { ConfigCollection } from "@njdamstra/appwrite-utils";
+export declare const toPascalCase: (str: string) => string;
+export declare const toCamelCase: (str: string) => string;
+export declare const ensureDirectoryExistence: (filePath: string) => true | undefined;
+export declare const writeFileSync: (filePath: string, content: string, options: {
+    flag: string;
+}) => void;
+export declare const readFileSync: (filePath: string) => string;
+export declare const existsSync: (filePath: string) => boolean;
+export declare const mkdirSync: (filePath: string) => void;
+export declare const readdirSync: (filePath: string) => string[];
+export declare const areCollectionNamesSame: (a: string, b: string) => boolean;
+/**
+ * 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 declare const getFileViewUrl: (endpoint: string, projectId: string, bucketId: string, fileId: string, jwt?: Models.Jwt) => string;
+/**
+ * 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 declare const getFileDownloadUrl: (endpoint: string, projectId: string, bucketId: string, fileId: string, jwt?: Models.Jwt) => string;
+export declare const finalizeByAttributeMap: (appwriteFolderPath: string, collection: ConfigCollection, item: CollectionImportData["data"][number]) => Promise<any>;
+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).
+ * @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) => 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

@@ -0,0 +1,156 @@
+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
+        .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) => {
+    return str
+        .replace(/(?:^\w|[A-Z]|\b\w)/g, (word, index) => index === 0 ? word.toLowerCase() : word.toUpperCase())
+        .replace(/\s+/g, "");
+};
+export const ensureDirectoryExistence = (filePath) => {
+    const dirname = path.dirname(filePath);
+    if (fs.existsSync(dirname)) {
+        return true;
+    }
+    ensureDirectoryExistence(dirname);
+    fs.mkdirSync(dirname);
+};
+export const writeFileSync = (filePath, content, options) => {
+    ensureDirectoryExistence(filePath);
+    fs.writeFileSync(filePath, content, options);
+};
+export const readFileSync = (filePath) => {
+    return fs.readFileSync(filePath, "utf8");
+};
+export const existsSync = (filePath) => {
+    return fs.existsSync(filePath);
+};
+export const mkdirSync = (filePath) => {
+    ensureDirectoryExistence(filePath);
+    fs.mkdirSync(filePath);
+};
+export const readdirSync = (filePath) => {
+    return fs.readdirSync(filePath);
+};
+export const areCollectionNamesSame = (a, b) => {
+    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, projectId, bucketId, fileId, 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, projectId, bucketId, fileId, jwt) => {
+    return `${endpoint}/storage/buckets/${bucketId}/files/${fileId}/download?project=${projectId}${jwt ? `&jwt=${jwt.jwt}` : ""}`;
+};
+export const finalizeByAttributeMap = async (appwriteFolderPath, collection, item) => {
+    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 (createFunction, attemptNum = 0, throwError = false) => {
+    try {
+        return await createFunction();
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message.toLowerCase() : String(error).toLowerCase();
+        const errorCode = error.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, projectId, 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);
+};