@njdamstra/appwrite-utils-cli 1.8.9

package/dist/utils/typeGuards.d.ts

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

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

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

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

@@ -0,0 +1,58 @@
+/**
+ * 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

@@ -0,0 +1,251 @@
+/**
+ * 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

@@ -0,0 +1,100 @@
+import type { Collection, CollectionCreate } from "@njdamstra/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;
+};