appwrite-utils-cli 1.9.6 → 1.11.0

package/dist/utils/typeGuards.d.ts

@@ -1,35 +0,0 @@
-import type { Databases } from "node-appwrite";
-import type { DatabaseAdapter } from "../adapters/DatabaseAdapter.js";
-/**
- * Type guard and validation utilities
- */
-/**
- * Type guard to check if object is a DatabaseAdapter
- * @param db - Object to check
- * @returns True if object is DatabaseAdapter
- */
-export declare function isDatabaseAdapter(db: Databases | DatabaseAdapter): db is DatabaseAdapter;
-/**
- * Type guard to check if object is legacy Databases instance
- * @param db - Object to check
- * @returns True if object is Databases (not DatabaseAdapter)
- */
-export declare function isLegacyDatabases(db: Databases | DatabaseAdapter): db is Databases;
-/**
- * Checks if object has metadata property
- * @param obj - Object to check
- * @returns True if object has metadata
- */
-export declare function hasMetadata(obj: any): boolean;
-/**
- * Type guard for collection create objects
- * @param obj - Object to check
- * @returns True if object looks like CollectionCreate
- */
-export declare function isCollectionCreate(obj: any): boolean;
-/**
- * Type guard for table create objects
- * @param obj - Object to check
- * @returns True if object looks like TableCreate
- */
-export declare function isTableCreate(obj: any): boolean;

package/dist/utils/typeGuards.js

@@ -1,57 +0,0 @@
-import { logger } from "../shared/logging.js";
-/**
- * Type guard and validation utilities
- */
-/**
- * Type guard to check if object is a DatabaseAdapter
- * @param db - Object to check
- * @returns True if object is DatabaseAdapter
- */
-export function isDatabaseAdapter(db) {
-    const isAdapter = 'getMetadata' in db && typeof db.getMetadata === 'function';
-    logger.debug('Adapter type detection', {
-        isAdapter,
-        hasGetMetadata: 'getMetadata' in db,
-        getMetadataType: typeof db.getMetadata,
-        operation: 'isDatabaseAdapter'
-    });
-    return isAdapter;
-}
-/**
- * Type guard to check if object is legacy Databases instance
- * @param db - Object to check
- * @returns True if object is Databases (not DatabaseAdapter)
- */
-export function isLegacyDatabases(db) {
-    return !isDatabaseAdapter(db);
-}
-/**
- * Checks if object has metadata property
- * @param obj - Object to check
- * @returns True if object has metadata
- */
-export function hasMetadata(obj) {
-    return obj && typeof obj === 'object' && 'metadata' in obj;
-}
-/**
- * Type guard for collection create objects
- * @param obj - Object to check
- * @returns True if object looks like CollectionCreate
- */
-export function isCollectionCreate(obj) {
-    return obj &&
-        typeof obj === 'object' &&
-        'name' in obj &&
-        ('$id' in obj || 'collectionId' in obj);
-}
-/**
- * Type guard for table create objects
- * @param obj - Object to check
- * @returns True if object looks like TableCreate
- */
-export function isTableCreate(obj) {
-    return obj &&
-        typeof obj === 'object' &&
-        'name' in obj &&
-        ('tableId' in obj || '$id' in obj);
-}

package/dist/utils/validationRules.d.ts

@@ -1,43 +0,0 @@
-export interface ValidationRules {
-    [key: string]: (value: any, ...args: any[]) => boolean;
-}
-export declare const validationRules: {
-    isNumber: (value: any) => boolean;
-    isString: (value: any) => boolean;
-    isBoolean: (value: any) => boolean;
-    isArray: (value: any) => boolean;
-    isObject: (value: any) => boolean;
-    isNull: (value: any) => boolean;
-    isValidEmail: (value: string) => boolean;
-    isValidPhone: (value: string) => boolean;
-    isValidPassword: (value: string) => boolean;
-    isValidUrl: (value: string) => boolean;
-    isValidHex: (value: string) => boolean;
-    isValidHexColor: (value: string) => boolean;
-    isValidHexAlpha: (value: string) => boolean;
-    isValidDate: (value: string) => boolean;
-    isValidTime: (value: string) => boolean;
-    isNullish: (value: any) => boolean;
-    isUndefined: (value: any) => boolean;
-    isDefined: (value: any) => boolean;
-    isDate: (value: any) => boolean;
-    isEmpty: (value: any) => boolean;
-    isInteger: (value: any) => boolean;
-    isFloat: (value: any) => boolean;
-    isArrayLike: (value: any) => boolean;
-    isArrayLikeObject: (value: any) => boolean;
-    isFunction: (value: any) => boolean;
-    isLength: (value: any) => boolean;
-    isMap: (value: any) => boolean;
-    isSet: (value: any) => boolean;
-    isRegExp: (value: any) => boolean;
-    isSymbol: (value: any) => boolean;
-    isObjectLike: (value: any) => boolean;
-    isPlainObject: (value: any) => boolean;
-    isSafeInteger: (value: any) => boolean;
-    isTypedArray: (value: any) => boolean;
-    isEqual: (value: any, other: any) => boolean;
-    isMatch: (object: any, source: any) => boolean;
-    has: (object: any, path: string) => boolean;
-    get: (object: any, path: string, defaultValue: any) => any;
-};

package/dist/utils/validationRules.js

@@ -1,42 +0,0 @@
-import { isNumber, isString, isBoolean, isArray, isPlainObject, isNull, isUndefined, isDate, isEmpty, isInteger, isArrayLike, isArrayLikeObject, isFunction, isLength, isMap, isSet, isRegExp, isSymbol, isObjectLike, isSafeInteger, isTypedArray, isEqual, isMatch, has, get, } from "es-toolkit/compat";
-export const validationRules = {
-    isNumber: (value) => isNumber(value),
-    isString: (value) => isString(value),
-    isBoolean: (value) => isBoolean(value),
-    isArray: (value) => isArray(value),
-    isObject: (value) => isPlainObject(value) && !isArray(value) && !isFunction(value),
-    isNull: (value) => isNull(value),
-    isValidEmail: (value) => value.match(/^[\w\-\.]+@([\w-]+\.)+[\w-]{2,}$/) !== null,
-    isValidPhone: (value) => value.match(/^[+]?[(]?[0-9]{3}[)]?[-\s.]?[0-9]{3}[-\s.]?[0-9]{4,6}$/im) !==
-        null,
-    isValidPassword: (value) => value.match(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*#?&])[A-Za-z\d@$!%*#?&]{8,}$/) !== null,
-    isValidUrl: (value) => value.match(/^(https?:\/\/)?([\da-z\.-]+)\.([a-z\.]{2,6})([\/\w \.-]*)*\/?$/) !== null,
-    isValidHex: (value) => value.match(/^#([a-f0-9]{6}|[a-f0-9]{3})$/i) !== null,
-    isValidHexColor: (value) => value.match(/^#([a-f0-9]{6}|[a-f0-9]{3})$/i) !== null,
-    isValidHexAlpha: (value) => value.match(/^#([a-f0-9]{8}|[a-f0-9]{4})$/i) !== null,
-    isValidDate: (value) => value.match(/^\d{4}-\d{2}-\d{2}$/) !== null,
-    isValidTime: (value) => value.match(/^\d{2}:\d{2}(:\d{2})?$/) !== null,
-    isNullish: (value) => isNull(value) || isUndefined(value),
-    isUndefined: (value) => isUndefined(value),
-    isDefined: (value) => !isUndefined(value) && !isNull(value) && !isEmpty(value),
-    isDate: (value) => isDate(value),
-    isEmpty: (value) => isEmpty(value),
-    isInteger: (value) => isInteger(value),
-    isFloat: (value) => isNumber(value) && !isInteger(value), // Note: Works for double precision numbers
-    isArrayLike: (value) => isArrayLike(value),
-    isArrayLikeObject: (value) => isArrayLikeObject(value),
-    isFunction: (value) => isFunction(value),
-    isLength: (value) => isLength(value),
-    isMap: (value) => isMap(value),
-    isSet: (value) => isSet(value),
-    isRegExp: (value) => isRegExp(value),
-    isSymbol: (value) => isSymbol(value),
-    isObjectLike: (value) => isObjectLike(value),
-    isPlainObject: (value) => isPlainObject(value),
-    isSafeInteger: (value) => isSafeInteger(value),
-    isTypedArray: (value) => isTypedArray(value),
-    isEqual: (value, other) => isEqual(value, other),
-    isMatch: (object, source) => isMatch(object, source),
-    has: (object, path) => has(object, path),
-    get: (object, path, defaultValue) => get(object, path, defaultValue),
-};

package/dist/utils/versionDetection.d.ts

@@ -1,58 +0,0 @@
-/**
- * Version Detection Utility for Appwrite API Compatibility
- *
- * This module provides functions to detect whether an Appwrite instance
- * supports the new TablesDB API or uses the legacy Databases API.
- *
- * Detection Strategy:
- * 1. Primary: Test TablesDB-specific endpoint availability
- * 2. Secondary: Health endpoint version check
- * 3. Fallback: Default to legacy mode for safety
- */
-export type ApiMode = 'legacy' | 'tablesdb';
-export interface VersionDetectionResult {
-    apiMode: ApiMode;
-    detectionMethod: 'endpoint_probe' | 'health_check' | 'fallback';
-    serverVersion?: string;
-    confidence: 'high' | 'medium' | 'low';
-}
-/**
- * Detects Appwrite API version and TablesDB support
- *
- * @param endpoint - Appwrite server endpoint URL
- * @param project - Project ID
- * @param apiKey - API key for authentication
- * @returns Promise resolving to version detection result
- */
-export declare function detectAppwriteVersion(endpoint: string, project: string, apiKey: string): Promise<VersionDetectionResult>;
-/**
- * Cached version detection with automatic cache management
- *
- * @param endpoint - Appwrite server endpoint URL
- * @param project - Project ID
- * @param apiKey - API key for authentication
- * @param forceRefresh - Skip cache and force fresh detection
- * @returns Promise resolving to version detection result
- */
-export declare function detectAppwriteVersionCached(endpoint: string, project: string, apiKey: string, forceRefresh?: boolean): Promise<VersionDetectionResult>;
-/**
- * Quick check for cloud.appwrite.io instances (likely have TablesDB)
- *
- * @param endpoint - Appwrite server endpoint URL
- * @returns boolean indicating if endpoint is likely cloud-hosted
- */
-export declare function isCloudAppwriteEndpoint(endpoint: string): boolean;
-/**
- * SDK feature detection as a fallback method
- * Attempts to dynamically import TablesDB to check availability
- */
-/**
- * Clear version detection cache (useful for testing)
- */
-export declare function clearVersionDetectionCache(): void;
-/**
- * Fetch server version from /health/version (no auth required)
- */
-export declare function fetchServerVersion(endpoint: string): Promise<string | null>;
-/** Compare semantic versions (basic) */
-export declare function isVersionAtLeast(current: string | undefined, target: string): boolean;

package/dist/utils/versionDetection.js

@@ -1,251 +0,0 @@
-/**
- * Version Detection Utility for Appwrite API Compatibility
- *
- * This module provides functions to detect whether an Appwrite instance
- * supports the new TablesDB API or uses the legacy Databases API.
- *
- * Detection Strategy:
- * 1. Primary: Test TablesDB-specific endpoint availability
- * 2. Secondary: Health endpoint version check
- * 3. Fallback: Default to legacy mode for safety
- */
-import { logger } from '../shared/logging.js';
-import { MessageFormatter } from '../shared/messageFormatter.js';
-import { Client, Databases, TablesDB, Query } from 'node-appwrite';
-/**
- * Detects Appwrite API version and TablesDB support
- *
- * @param endpoint - Appwrite server endpoint URL
- * @param project - Project ID
- * @param apiKey - API key for authentication
- * @returns Promise resolving to version detection result
- */
-export async function detectAppwriteVersion(endpoint, project, apiKey) {
-    const startTime = Date.now();
-    // Clean endpoint URL
-    const cleanEndpoint = endpoint.replace(/\/$/, '');
-    logger.info('Starting Appwrite version detection', {
-        endpoint: cleanEndpoint,
-        project,
-        operation: 'detectAppwriteVersion'
-    });
-    // STEP 1: Check server version FIRST
-    const serverVersion = await fetchServerVersion(cleanEndpoint);
-    if (serverVersion && !isVersionAtLeast(serverVersion, '1.8.0')) {
-        // Server < 1.8.0 doesn't support TablesDB
-        logger.info('Server version below 1.8.0 - using legacy adapter', {
-            serverVersion,
-            operation: 'detectAppwriteVersion'
-        });
-        return {
-            apiMode: 'legacy',
-            detectionMethod: 'health_check',
-            serverVersion,
-            confidence: 'high'
-        };
-    }
-    // STEP 2: If version is unknown, use SDK probe (no fake HTTP endpoints)
-    try {
-        logger.debug('Attempting SDK-based TablesDB probe', {
-            endpoint: cleanEndpoint,
-            operation: 'detectAppwriteVersion'
-        });
-        const client = new Client().setEndpoint(cleanEndpoint).setProject(project);
-        if (apiKey && apiKey.trim().length > 0)
-            client.setKey(apiKey);
-        const databases = new Databases(client);
-        // Try to get a database id to probe tables listing
-        let dbId;
-        try {
-            const dbList = await databases.list([Query.limit(1)]);
-            dbId = dbList?.databases?.[0]?.$id || dbList?.databases?.[0]?.id || dbList?.[0]?.$id;
-        }
-        catch (e) {
-            // Ignore, we'll still attempt a conservative probe
-            logger.debug('Databases.list probe failed or returned no items', { operation: 'detectAppwriteVersion' });
-        }
-        const tables = new TablesDB(client);
-        if (dbId) {
-            // Probe listTables for the first database (limit 1)
-            await tables.listTables({ databaseId: dbId, queries: [Query.limit(1)] });
-        }
-        else {
-            // No databases to probe; assume TablesDB available (cannot falsify-positively without a db)
-            logger.debug('No databases found to probe tables; assuming TablesDB if SDK available', { operation: 'detectAppwriteVersion' });
-        }
-        const result = {
-            apiMode: 'tablesdb',
-            detectionMethod: 'endpoint_probe', // repurpose label for SDK probe
-            confidence: 'medium',
-            serverVersion: serverVersion || undefined
-        };
-        logger.info('TablesDB detected via SDK probe', {
-            endpoint: cleanEndpoint,
-            result,
-            operation: 'detectAppwriteVersion'
-        });
-        return result;
-    }
-    catch (error) {
-        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-        logger.warn('SDK TablesDB probe failed; defaulting conservatively', {
-            endpoint: cleanEndpoint,
-            error: errorMessage,
-            operation: 'detectAppwriteVersion'
-        });
-    }
-    // Final fallback: default to tablesdb for modern environments when version unknown
-    const fallbackResult = {
-        apiMode: 'tablesdb',
-        detectionMethod: 'fallback',
-        confidence: 'low',
-        serverVersion: serverVersion || undefined
-    };
-    logger.info('Defaulting to TablesDB mode (fallback)', {
-        endpoint: cleanEndpoint,
-        result: fallbackResult,
-        operation: 'detectAppwriteVersion'
-    });
-    return fallbackResult;
-}
-/**
- * Cached version detection to avoid repeated API calls
- */
-class VersionDetectionCache {
-    cache = new Map();
-    CACHE_DURATION = 5 * 60 * 1000; // 5 minutes
-    getCacheKey(endpoint, project) {
-        return `${endpoint}:${project}`;
-    }
-    get(endpoint, project) {
-        const key = this.getCacheKey(endpoint, project);
-        const cached = this.cache.get(key);
-        if (!cached) {
-            return null;
-        }
-        // Check if cache is expired
-        if (Date.now() - cached.timestamp > this.CACHE_DURATION) {
-            this.cache.delete(key);
-            return null;
-        }
-        return cached.result;
-    }
-    set(endpoint, project, result) {
-        const key = this.getCacheKey(endpoint, project);
-        this.cache.set(key, {
-            result,
-            timestamp: Date.now()
-        });
-    }
-    clear() {
-        this.cache.clear();
-    }
-}
-// Global cache instance
-const detectionCache = new VersionDetectionCache();
-/**
- * Cached version detection with automatic cache management
- *
- * @param endpoint - Appwrite server endpoint URL
- * @param project - Project ID
- * @param apiKey - API key for authentication
- * @param forceRefresh - Skip cache and force fresh detection
- * @returns Promise resolving to version detection result
- */
-export async function detectAppwriteVersionCached(endpoint, project, apiKey, forceRefresh = false) {
-    const startTime = Date.now();
-    logger.debug('Version detection with cache requested', {
-        endpoint,
-        project,
-        forceRefresh,
-        operation: 'detectAppwriteVersionCached'
-    });
-    // Check cache first (unless force refresh)
-    if (!forceRefresh) {
-        const cached = detectionCache.get(endpoint, project);
-        if (cached) {
-            logger.info('Using cached version detection result', {
-                endpoint,
-                project,
-                cachedResult: cached,
-                operation: 'detectAppwriteVersionCached'
-            });
-            return cached;
-        }
-        logger.debug('No cached result found, performing fresh detection', {
-            endpoint,
-            project,
-            operation: 'detectAppwriteVersionCached'
-        });
-    }
-    else {
-        logger.debug('Force refresh requested, bypassing cache', {
-            endpoint,
-            project,
-            operation: 'detectAppwriteVersionCached'
-        });
-    }
-    // Perform fresh detection
-    const result = await detectAppwriteVersion(endpoint, project, apiKey);
-    const totalDuration = Date.now() - startTime;
-    // Cache the result
-    detectionCache.set(endpoint, project, result);
-    logger.info('Version detection completed and cached', {
-        endpoint,
-        project,
-        result,
-        totalDuration,
-        operation: 'detectAppwriteVersionCached'
-    });
-    return result;
-}
-/**
- * Quick check for cloud.appwrite.io instances (likely have TablesDB)
- *
- * @param endpoint - Appwrite server endpoint URL
- * @returns boolean indicating if endpoint is likely cloud-hosted
- */
-export function isCloudAppwriteEndpoint(endpoint) {
-    return endpoint.includes('cloud.appwrite.io');
-}
-/**
- * SDK feature detection as a fallback method
- * Attempts to dynamically import TablesDB to check availability
- */
-// Removed dynamic SDK capability checks to avoid confusion and side effects.
-/**
- * Clear version detection cache (useful for testing)
- */
-export function clearVersionDetectionCache() {
-    detectionCache.clear();
-}
-/**
- * Fetch server version from /health/version (no auth required)
- */
-export async function fetchServerVersion(endpoint) {
-    try {
-        const clean = endpoint.replace(/\/$/, '');
-        const res = await fetch(`${clean}/health/version`, { method: 'GET', signal: AbortSignal.timeout(5000) });
-        if (!res.ok)
-            return null;
-        const data = await res.json().catch(() => null);
-        const version = (data && (data.version || data.build || data.release)) ?? null;
-        return typeof version === 'string' ? version : null;
-    }
-    catch {
-        return null;
-    }
-}
-/** Compare semantic versions (basic) */
-export function isVersionAtLeast(current, target) {
-    if (!current)
-        return false;
-    const toNums = (v) => v.split('.').map(n => parseInt(n, 10));
-    const [a1 = 0, a2 = 0, a3 = 0] = toNums(current);
-    const [b1, b2, b3] = toNums(target);
-    if (a1 !== b1)
-        return a1 > b1;
-    if (a2 !== b2)
-        return a2 > b2;
-    return a3 >= b3;
-}

package/dist/utils/yamlConverter.d.ts

@@ -1,100 +0,0 @@
-import type { Collection, CollectionCreate } from "appwrite-utils";
-export interface YamlCollectionData {
-    name: string;
-    id?: string;
-    documentSecurity?: boolean;
-    rowSecurity?: boolean;
-    enabled?: boolean;
-    permissions?: Array<{
-        permission: string;
-        target: string;
-    }>;
-    attributes?: Array<{
-        key: string;
-        type: string;
-        size?: number;
-        required?: boolean;
-        array?: boolean;
-        encrypt?: boolean;
-        default?: any;
-        min?: number;
-        max?: number;
-        elements?: string[];
-        relatedCollection?: string;
-        relationType?: string;
-        twoWay?: boolean;
-        twoWayKey?: string;
-        onDelete?: string;
-        side?: string;
-    }>;
-    columns?: Array<{
-        key: string;
-        type: string;
-        size?: number;
-        required?: boolean;
-        array?: boolean;
-        encrypt?: boolean;
-        default?: any;
-        min?: number;
-        max?: number;
-        elements?: string[];
-        relatedTable?: string;
-        relationType?: string;
-        twoWay?: boolean;
-        twoWayKey?: string;
-        onDelete?: string;
-        side?: string;
-    }>;
-    indexes?: Array<{
-        key: string;
-        type: string;
-        attributes: string[];
-        columns?: string[];
-        orders?: string[];
-    }>;
-    importDefs?: any[];
-}
-/**
- * Configuration for terminology selection
- */
-export interface YamlTerminologyConfig {
-    useTableTerminology: boolean;
-    entityType: 'collection' | 'table';
-    schemaPath?: string;
-}
-/**
- * Converts a Collection object to YAML format with proper schema reference
- * Supports both collection and table terminology based on configuration
- */
-export declare function collectionToYaml(collection: Collection | CollectionCreate, config?: YamlTerminologyConfig): string;
-/**
- * Sanitizes a collection name for use as a filename
- */
-export declare function sanitizeFilename(name: string): string;
-/**
- * Generates the filename for a collection/table YAML file
- */
-export declare function getCollectionYamlFilename(collection: Collection | CollectionCreate, useTableTerminology?: boolean): string;
-/**
- * Converts column terminology back to attribute terminology for loading
- */
-export declare function normalizeYamlData(yamlData: YamlCollectionData): YamlCollectionData;
-/**
- * Determines if YAML data uses table terminology
- */
-export declare function usesTableTerminology(yamlData: YamlCollectionData): boolean;
-/**
- * Converts between attribute and column terminology
- */
-export declare function convertTerminology(yamlData: YamlCollectionData, toTableTerminology: boolean): YamlCollectionData;
-/**
- * Generates a template YAML file for collections or tables
- */
-export declare function generateYamlTemplate(entityName: string, config: YamlTerminologyConfig): string;
-/**
- * Generates example YAML files for both collection and table formats
- */
-export declare function generateExampleYamls(entityName: string): {
-    collection: string;
-    table: string;
-};