@njdamstra/appwrite-utils-cli 1.8.9

package/src/utils/typeGuards.ts

@@ -0,0 +1,65 @@
+import type { Databases } from "node-appwrite";
+import type { DatabaseAdapter } from "../adapters/DatabaseAdapter.js";
+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: Databases | DatabaseAdapter): db is DatabaseAdapter {
+  const isAdapter = 'getMetadata' in db && typeof db.getMetadata === 'function';
+  logger.debug('Adapter type detection', {
+    isAdapter,
+    hasGetMetadata: 'getMetadata' in db,
+    getMetadataType: typeof (db as any).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: Databases | DatabaseAdapter): db is Databases {
+  return !isDatabaseAdapter(db);
+}
+
+/**
+ * Checks if object has metadata property
+ * @param obj - Object to check
+ * @returns True if object has metadata
+ */
+export function hasMetadata(obj: any): boolean {
+  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: any): boolean {
+  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: any): boolean {
+  return obj &&
+         typeof obj === 'object' &&
+         'name' in obj &&
+         ('tableId' in obj || '$id' in obj);
+}

package/src/utils/validationRules.ts

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

package/src/utils/versionDetection.ts

@@ -0,0 +1,292 @@
+/**
+ * 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';
+
+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 async function detectAppwriteVersion(
+  endpoint: string,
+  project: string,
+  apiKey: string
+): Promise<VersionDetectionResult> {
+  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: string | undefined;
+    try {
+      const dbList: any = 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: VersionDetectionResult = {
+      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: VersionDetectionResult = {
+    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 {
+  private cache = new Map<string, { result: VersionDetectionResult; timestamp: number }>();
+  private readonly CACHE_DURATION = 5 * 60 * 1000; // 5 minutes
+  
+  private getCacheKey(endpoint: string, project: string): string {
+    return `${endpoint}:${project}`;
+  }
+  
+  get(endpoint: string, project: string): VersionDetectionResult | null {
+    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: string, project: string, result: VersionDetectionResult): void {
+    const key = this.getCacheKey(endpoint, project);
+    this.cache.set(key, {
+      result,
+      timestamp: Date.now()
+    });
+  }
+  
+  clear(): void {
+    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: string,
+  project: string,
+  apiKey: string,
+  forceRefresh: boolean = false
+): Promise<VersionDetectionResult> {
+  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: string): boolean {
+  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(): void {
+  detectionCache.clear();
+}
+
+/**
+ * Fetch server version from /health/version (no auth required)
+ */
+export async function fetchServerVersion(endpoint: string): Promise<string | null> {
+  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) as any;
+    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: string | undefined, target: string): boolean {
+  if (!current) return false;
+  const toNums = (v: string) => 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;
+}