@njdamstra/appwrite-utils-cli 1.8.9

package/dist/adapters/AdapterFactory.d.ts

@@ -0,0 +1,94 @@
+/**
+ * AdapterFactory - Unified Client Creation with Automatic API Detection
+ *
+ * This factory creates the appropriate database adapter (TablesDB or Legacy)
+ * based on version detection and configuration. It handles dynamic SDK imports
+ * and provides a single entry point for all database operations.
+ */
+import type { AppwriteConfig } from "@njdamstra/appwrite-utils";
+import { type ApiMode, type VersionDetectionResult } from "../utils/versionDetection.js";
+import type { DatabaseAdapter } from './DatabaseAdapter.js';
+export interface AdapterFactoryConfig {
+    appwriteEndpoint: string;
+    appwriteProject: string;
+    appwriteKey?: string;
+    apiMode?: 'auto' | 'legacy' | 'tablesdb';
+    forceRefresh?: boolean;
+    sessionCookie?: string;
+    authMethod?: 'session' | 'apikey' | 'auto';
+    preConfiguredClient?: any;
+}
+export interface AdapterFactoryResult {
+    adapter: DatabaseAdapter;
+    apiMode: ApiMode;
+    detectionResult?: VersionDetectionResult;
+    client: any;
+}
+/**
+ * AdapterFactory - Main factory class for creating database adapters
+ */
+export declare class AdapterFactory {
+    private static cache;
+    private static readonly CACHE_DURATION;
+    /**
+     * Create a database adapter based on configuration and detection
+     */
+    static create(config: AdapterFactoryConfig): Promise<AdapterFactoryResult>;
+    /**
+     * Create adapter from AppwriteConfig (convenience method)
+     */
+    static createFromConfig(config: AppwriteConfig, forceRefresh?: boolean): Promise<AdapterFactoryResult>;
+    /**
+     * Create specific adapter type (internal method)
+     */
+    private static createAdapter;
+    /**
+     * Create TablesDB adapter with dynamic import
+     */
+    private static createTablesDBAdapter;
+    /**
+     * Create Legacy adapter with dynamic import
+     */
+    private static createLegacyAdapter;
+    /**
+     * Get cached adapter if available and not expired
+     */
+    private static getCachedAdapter;
+    /**
+     * Cache adapter instance
+     */
+    private static setCachedAdapter;
+    /**
+     * Clear adapter cache (useful for testing)
+     */
+    static clearCache(): void;
+    /**
+     * Validate authentication configuration
+     */
+    private static validateAuthConfig;
+    /**
+     * Test connection and API capabilities
+     */
+    static testConnection(config: AdapterFactoryConfig): Promise<{
+        success: boolean;
+        apiMode: ApiMode;
+        capabilities: string[];
+        error?: string;
+    }>;
+}
+/**
+ * Convenience function for quick adapter creation
+ */
+export declare function createDatabaseAdapter(endpoint: string, project: string, apiKey?: string, mode?: 'auto' | 'legacy' | 'tablesdb', sessionCookie?: string): Promise<DatabaseAdapter>;
+/**
+ * Helper function to get adapter metadata without creating full adapter
+ */
+export declare function getApiCapabilities(endpoint: string, project: string, apiKey?: string, sessionCookie?: string): Promise<{
+    apiMode: ApiMode;
+    terminology: {
+        container: string;
+        item: string;
+        service: string;
+    };
+    capabilities: string[];
+}>;

package/dist/adapters/AdapterFactory.js

@@ -0,0 +1,405 @@
+/**
+ * AdapterFactory - Unified Client Creation with Automatic API Detection
+ *
+ * This factory creates the appropriate database adapter (TablesDB or Legacy)
+ * based on version detection and configuration. It handles dynamic SDK imports
+ * and provides a single entry point for all database operations.
+ */
+import { detectAppwriteVersionCached, isVersionAtLeast } from "../utils/versionDetection.js";
+import { TablesDBAdapter } from './TablesDBAdapter.js';
+import { LegacyAdapter } from './LegacyAdapter.js';
+import { logger } from '../shared/logging.js';
+import { isValidSessionCookie } from '../utils/sessionAuth.js';
+import { MessageFormatter } from '../shared/messageFormatter.js';
+import { Client } from 'node-appwrite';
+/**
+ * AdapterFactory - Main factory class for creating database adapters
+ */
+export class AdapterFactory {
+    static cache = new Map();
+    static CACHE_DURATION = 5 * 60 * 1000; // 5 minutes
+    /**
+     * Create a database adapter based on configuration and detection
+     */
+    static async create(config) {
+        const startTime = Date.now();
+        // Validate authentication configuration
+        this.validateAuthConfig(config);
+        const cacheKey = `${config.appwriteEndpoint}:${config.appwriteProject}:${config.apiMode || 'auto'}`;
+        logger.info('Creating database adapter', {
+            endpoint: config.appwriteEndpoint,
+            project: config.appwriteProject,
+            requestedApiMode: config.apiMode || 'auto',
+            authMethod: config.authMethod || 'auto',
+            hasSessionCookie: !!config.sessionCookie,
+            hasPreConfiguredClient: !!config.preConfiguredClient,
+            forceRefresh: config.forceRefresh,
+            cacheKey,
+            operation: 'AdapterFactory.create'
+        });
+        // Check cache first (unless force refresh)
+        if (!config.forceRefresh) {
+            const cached = this.getCachedAdapter(cacheKey);
+            if (cached) {
+                const cacheAge = Date.now() - cached.timestamp;
+                logger.info('Using cached adapter', {
+                    cacheKey,
+                    cacheAge,
+                    apiMode: cached.adapter.getApiMode(),
+                    operation: 'AdapterFactory.create'
+                });
+                return {
+                    adapter: cached.adapter,
+                    apiMode: cached.adapter.getApiMode(),
+                    client: cached.adapter.getRawClient()
+                };
+            }
+        }
+        // Determine API mode
+        let apiMode;
+        let detectionResult;
+        if (config.apiMode && config.apiMode !== 'auto') {
+            // Use explicitly configured mode
+            apiMode = config.apiMode;
+            logger.info('Using explicitly configured API mode', {
+                apiMode,
+                endpoint: config.appwriteEndpoint,
+                operation: 'AdapterFactory.create'
+            });
+        }
+        else {
+            // Auto-detect API mode
+            logger.info('Starting API mode auto-detection', {
+                endpoint: config.appwriteEndpoint,
+                project: config.appwriteProject,
+                forceRefresh: config.forceRefresh,
+                operation: 'AdapterFactory.create'
+            });
+            const detectionStartTime = Date.now();
+            // For version detection, we need some form of authentication
+            const authKey = config.appwriteKey || '';
+            detectionResult = await detectAppwriteVersionCached(config.appwriteEndpoint, config.appwriteProject, authKey, config.forceRefresh);
+            const detectionDuration = Date.now() - detectionStartTime;
+            apiMode = detectionResult.apiMode;
+            logger.info('API mode detection completed', {
+                apiMode,
+                detectionMethod: detectionResult.detectionMethod,
+                confidence: detectionResult.confidence,
+                serverVersion: detectionResult.serverVersion,
+                detectionDuration,
+                endpoint: config.appwriteEndpoint,
+                operation: 'AdapterFactory.create'
+            });
+            // Add version-based safety check to prevent using TablesDB on old servers
+            if (detectionResult.serverVersion &&
+                !isVersionAtLeast(detectionResult.serverVersion, '1.8.0') &&
+                apiMode === 'tablesdb') {
+                logger.warn('Overriding TablesDB detection - server version too old', {
+                    serverVersion: detectionResult.serverVersion,
+                    detectedMode: apiMode,
+                    overrideMode: 'legacy',
+                    operation: 'AdapterFactory.create'
+                });
+                apiMode = 'legacy';
+            }
+        }
+        // Create appropriate adapter
+        logger.info('Creating adapter instance', {
+            apiMode,
+            endpoint: config.appwriteEndpoint,
+            operation: 'AdapterFactory.create'
+        });
+        const adapterStartTime = Date.now();
+        const result = await this.createAdapter(config, apiMode);
+        const adapterDuration = Date.now() - adapterStartTime;
+        // Cache the result
+        this.setCachedAdapter(cacheKey, result.adapter);
+        const totalDuration = Date.now() - startTime;
+        logger.info('Adapter creation completed', {
+            apiMode,
+            adapterDuration,
+            totalDuration,
+            cached: true,
+            operation: 'AdapterFactory.create'
+        });
+        return {
+            ...result,
+            apiMode,
+            detectionResult
+        };
+    }
+    /**
+     * Create adapter from AppwriteConfig (convenience method)
+     */
+    static async createFromConfig(config, forceRefresh) {
+        return this.create({
+            appwriteEndpoint: config.appwriteEndpoint,
+            appwriteProject: config.appwriteProject,
+            appwriteKey: config.appwriteKey,
+            apiMode: config.apiMode || 'auto', // Cast to access new property
+            forceRefresh
+        });
+    }
+    /**
+     * Create specific adapter type (internal method)
+     */
+    static async createAdapter(config, apiMode) {
+        if (apiMode === 'tablesdb') {
+            return this.createTablesDBAdapter(config);
+        }
+        else {
+            return this.createLegacyAdapter(config);
+        }
+    }
+    /**
+     * Create TablesDB adapter with dynamic import
+     */
+    static async createTablesDBAdapter(config) {
+        const startTime = Date.now();
+        try {
+            logger.info('Creating TablesDB adapter (static SDK imports)', {
+                endpoint: config.appwriteEndpoint,
+                operation: 'createTablesDBAdapter'
+            });
+            // Use pre-configured client or create session-aware client with TablesDB Client
+            let client;
+            if (config.preConfiguredClient) {
+                client = config.preConfiguredClient;
+            }
+            else {
+                client = new Client()
+                    .setEndpoint(config.appwriteEndpoint)
+                    .setProject(config.appwriteProject);
+                // Set authentication method with mode headers
+                // Prefer session with admin mode, fallback to API key with default mode
+                if (config.sessionCookie && isValidSessionCookie(config.sessionCookie)) {
+                    client.setSession(config.sessionCookie);
+                    client.headers['X-Appwrite-Mode'] = 'admin';
+                    logger.debug('Using session authentication for TablesDB adapter', {
+                        project: config.appwriteProject,
+                        operation: 'createTablesDBAdapter'
+                    });
+                }
+                else if (config.appwriteKey) {
+                    client.setKey(config.appwriteKey);
+                    client.headers['X-Appwrite-Mode'] = 'default';
+                    logger.debug('Using API key authentication for TablesDB adapter', {
+                        project: config.appwriteProject,
+                        operation: 'createTablesDBAdapter'
+                    });
+                }
+                else {
+                    throw new Error("No authentication available for adapter");
+                }
+            }
+            const adapter = new TablesDBAdapter(client);
+            const totalDuration = Date.now() - startTime;
+            logger.info('TablesDB adapter created successfully', {
+                totalDuration,
+                endpoint: config.appwriteEndpoint,
+                operation: 'createTablesDBAdapter'
+            });
+            return { adapter, client };
+        }
+        catch (error) {
+            const errorDuration = Date.now() - startTime;
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            MessageFormatter.warning('Failed to create TablesDB adapter - falling back to legacy', { prefix: "Adapter" });
+            logger.warn('TablesDB adapter creation failed, falling back to legacy', {
+                error: errorMessage,
+                errorDuration,
+                endpoint: config.appwriteEndpoint,
+                operation: 'createTablesDBAdapter'
+            });
+            // Fallback to legacy adapter if TablesDB creation fails
+            return this.createLegacyAdapter(config);
+        }
+    }
+    /**
+     * Create Legacy adapter with dynamic import
+     */
+    static async createLegacyAdapter(config) {
+        const startTime = Date.now();
+        try {
+            logger.info('Creating legacy adapter (static SDK imports)', {
+                endpoint: config.appwriteEndpoint,
+                operation: 'createLegacyAdapter'
+            });
+            // Use pre-configured client or create session-aware client with Legacy Client
+            let client;
+            if (config.preConfiguredClient) {
+                client = config.preConfiguredClient;
+            }
+            else {
+                client = new Client()
+                    .setEndpoint(config.appwriteEndpoint)
+                    .setProject(config.appwriteProject);
+                // Set authentication method with mode headers
+                // Prefer session with admin mode, fallback to API key with default mode
+                if (config.sessionCookie && isValidSessionCookie(config.sessionCookie)) {
+                    client.setSession(config.sessionCookie);
+                    client.headers['X-Appwrite-Mode'] = 'admin';
+                    logger.debug('Using session authentication for Legacy adapter', {
+                        project: config.appwriteProject,
+                        operation: 'createLegacyAdapter'
+                    });
+                }
+                else if (config.appwriteKey) {
+                    client.setKey(config.appwriteKey);
+                    client.headers['X-Appwrite-Mode'] = 'default';
+                    logger.debug('Using API key authentication for Legacy adapter', {
+                        project: config.appwriteProject,
+                        operation: 'createLegacyAdapter'
+                    });
+                }
+                else {
+                    throw new Error("No authentication available for adapter");
+                }
+            }
+            const adapter = new LegacyAdapter(client);
+            const totalDuration = Date.now() - startTime;
+            logger.info('Legacy adapter created successfully', {
+                totalDuration,
+                endpoint: config.appwriteEndpoint,
+                operation: 'createLegacyAdapter'
+            });
+            return { adapter, client };
+        }
+        catch (error) {
+            const errorDuration = Date.now() - startTime;
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            logger.error('Failed to load legacy Appwrite SDK', {
+                error: errorMessage,
+                errorDuration,
+                endpoint: config.appwriteEndpoint,
+                operation: 'createLegacyAdapter'
+            });
+            throw new Error(`Failed to load legacy Appwrite SDK: ${errorMessage}`);
+        }
+    }
+    /**
+     * Get cached adapter if available and not expired
+     */
+    static getCachedAdapter(cacheKey) {
+        const cached = this.cache.get(cacheKey);
+        if (!cached) {
+            return null;
+        }
+        // Check if cache is expired
+        if (Date.now() - cached.timestamp > this.CACHE_DURATION) {
+            this.cache.delete(cacheKey);
+            return null;
+        }
+        return cached;
+    }
+    /**
+     * Cache adapter instance
+     */
+    static setCachedAdapter(cacheKey, adapter) {
+        this.cache.set(cacheKey, {
+            adapter,
+            timestamp: Date.now()
+        });
+    }
+    /**
+     * Clear adapter cache (useful for testing)
+     */
+    static clearCache() {
+        this.cache.clear();
+    }
+    /**
+     * Validate authentication configuration
+     */
+    static validateAuthConfig(config) {
+        const hasApiKey = config.appwriteKey && config.appwriteKey.trim().length > 0;
+        const hasSessionCookie = config.sessionCookie && isValidSessionCookie(config.sessionCookie);
+        const hasPreConfiguredClient = !!config.preConfiguredClient;
+        // Must have at least one authentication method
+        if (!hasApiKey && !hasSessionCookie && !hasPreConfiguredClient) {
+            throw new Error(`No valid authentication method provided for project ${config.appwriteProject}. ` +
+                `Please provide an API key, session cookie, or pre-configured client.`);
+        }
+        // Validate session cookie format if provided
+        if (config.sessionCookie && !isValidSessionCookie(config.sessionCookie)) {
+            throw new Error(`Invalid session cookie format provided for project ${config.appwriteProject}. ` +
+                `Session cookie must be a valid JWT token.`);
+        }
+        logger.debug('Authentication configuration validated', {
+            hasApiKey,
+            hasSessionCookie,
+            hasPreConfiguredClient,
+            authMethod: config.authMethod || 'auto',
+            operation: 'validateAuthConfig'
+        });
+    }
+    /**
+     * Test connection and API capabilities
+     */
+    static async testConnection(config) {
+        try {
+            const result = await this.create({ ...config, forceRefresh: true });
+            const metadata = result.adapter.getMetadata();
+            // Test basic operations
+            const capabilities = [];
+            if (metadata.capabilities.bulkOperations) {
+                capabilities.push('Bulk Operations');
+            }
+            if (metadata.capabilities.advancedQueries) {
+                capabilities.push('Advanced Queries');
+            }
+            if (metadata.capabilities.realtime) {
+                capabilities.push('Realtime');
+            }
+            if (metadata.capabilities.transactions) {
+                capabilities.push('Transactions');
+            }
+            return {
+                success: true,
+                apiMode: result.apiMode,
+                capabilities
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                apiMode: 'legacy', // Default fallback
+                capabilities: [],
+                error: error instanceof Error ? error.message : 'Unknown error'
+            };
+        }
+    }
+}
+/**
+ * Convenience function for quick adapter creation
+ */
+export async function createDatabaseAdapter(endpoint, project, apiKey, mode = 'auto', sessionCookie) {
+    const result = await AdapterFactory.create({
+        appwriteEndpoint: endpoint,
+        appwriteProject: project,
+        appwriteKey: apiKey,
+        apiMode: mode,
+        sessionCookie
+    });
+    return result.adapter;
+}
+/**
+ * Helper function to get adapter metadata without creating full adapter
+ */
+export async function getApiCapabilities(endpoint, project, apiKey, sessionCookie) {
+    const adapter = await createDatabaseAdapter(endpoint, project, apiKey, 'auto', sessionCookie);
+    const metadata = adapter.getMetadata();
+    const capabilities = [];
+    if (metadata.capabilities.bulkOperations)
+        capabilities.push('Bulk Operations');
+    if (metadata.capabilities.advancedQueries)
+        capabilities.push('Advanced Queries');
+    if (metadata.capabilities.realtime)
+        capabilities.push('Realtime');
+    if (metadata.capabilities.transactions)
+        capabilities.push('Transactions');
+    return {
+        apiMode: metadata.apiMode,
+        terminology: metadata.terminology,
+        capabilities
+    };
+}