appwrite-utils-cli 1.9.7 → 1.11.0

package/dist/adapters/AdapterFactory.js

@@ -1,420 +0,0 @@
-/**
- * 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 { AdapterError } from './DatabaseAdapter.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'
-            });
-            let 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';
-            // Analyze the error to determine if fallback is appropriate
-            const isAuthError = errorMessage.toLowerCase().includes('unauthorized') ||
-                errorMessage.toLowerCase().includes('forbidden') ||
-                errorMessage.toLowerCase().includes('invalid') ||
-                errorMessage.toLowerCase().includes('authentication');
-            const isVersionError = errorMessage.toLowerCase().includes('not found') ||
-                errorMessage.toLowerCase().includes('unsupported') ||
-                errorMessage.toLowerCase().includes('tablesdb');
-            // Only fallback to legacy if this is genuinely a TablesDB support issue
-            if (isVersionError) {
-                MessageFormatter.warning('TablesDB not supported on this server - using legacy adapter', { prefix: "Adapter" });
-                logger.warn('TablesDB not supported, falling back to legacy', {
-                    error: errorMessage,
-                    errorDuration,
-                    endpoint: config.appwriteEndpoint,
-                    operation: 'createTablesDBAdapter'
-                });
-                return this.createLegacyAdapter(config);
-            }
-            else {
-                // For auth or other errors, re-throw to surface the real problem
-                logger.error('TablesDB adapter creation failed with non-version error', {
-                    error: errorMessage,
-                    errorDuration,
-                    endpoint: config.appwriteEndpoint,
-                    operation: 'createTablesDBAdapter',
-                    isAuthError
-                });
-                throw new AdapterError(`TablesDB adapter creation failed: ${errorMessage}`, 'TABLESDB_ADAPTER_CREATION_FAILED', error instanceof Error ? error : undefined);
-            }
-        }
-    }
-    /**
-     * 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
-    };
-}

package/dist/adapters/DatabaseAdapter.d.ts

@@ -1,243 +0,0 @@
-/**
- * DatabaseAdapter Interface - Unified API for Appwrite Database Operations
- *
- * This interface provides a unified way to interact with both legacy Appwrite
- * (collections/documents) and new TablesDB (tables/rows) APIs. All internal
- * code uses TablesDB-style method signatures for consistency.
- */
-import type { Client } from "node-appwrite";
-import type { ApiMode } from "../utils/versionDetection.js";
-export interface CreateRowParams {
-    databaseId: string;
-    tableId: string;
-    id: string;
-    data: any;
-    permissions?: string[];
-}
-export interface UpdateRowParams {
-    databaseId: string;
-    tableId: string;
-    id: string;
-    data?: any;
-    permissions?: string[];
-}
-export interface ListRowsParams {
-    databaseId: string;
-    tableId: string;
-    queries?: any[];
-}
-export interface DeleteRowParams {
-    databaseId: string;
-    tableId: string;
-    id: string;
-}
-export interface CreateTableParams {
-    databaseId: string;
-    id: string;
-    name: string;
-    permissions?: string[];
-    documentSecurity?: boolean;
-    rowSecurity?: boolean;
-    enabled?: boolean;
-}
-export interface UpdateTableParams {
-    databaseId: string;
-    id: string;
-    name: string;
-    permissions?: string[];
-    documentSecurity?: boolean;
-    rowSecurity?: boolean;
-    enabled?: boolean;
-}
-export interface ListTablesParams {
-    databaseId: string;
-    queries?: any[];
-}
-export interface DeleteTableParams {
-    databaseId: string;
-    tableId: string;
-}
-export interface GetTableParams {
-    databaseId: string;
-    tableId: string;
-}
-export interface BulkCreateRowsParams {
-    databaseId: string;
-    tableId: string;
-    rows: any[];
-}
-export interface BulkUpsertRowsParams {
-    databaseId: string;
-    tableId: string;
-    rows: any[];
-}
-export interface BulkDeleteRowsParams {
-    databaseId: string;
-    tableId: string;
-    rowIds: string[];
-    batchSize?: number;
-}
-export interface CreateIndexParams {
-    databaseId: string;
-    tableId: string;
-    key: string;
-    type: string;
-    attributes: string[];
-    orders?: string[];
-    lengths?: number[];
-}
-export interface ListIndexesParams {
-    databaseId: string;
-    tableId: string;
-    queries?: any[];
-}
-export interface DeleteIndexParams {
-    databaseId: string;
-    tableId: string;
-    key: string;
-}
-export interface CreateAttributeParams {
-    databaseId: string;
-    tableId: string;
-    key: string;
-    type: string;
-    size?: number;
-    required?: boolean;
-    default?: any;
-    array?: boolean;
-    encrypt?: boolean;
-    min?: number;
-    max?: number;
-    elements?: string[];
-    relatedCollection?: string;
-    relationType?: 'oneToOne' | 'manyToOne' | 'oneToMany' | 'manyToMany';
-    twoWay?: boolean;
-    twoWayKey?: string;
-    onDelete?: 'setNull' | 'cascade' | 'restrict';
-    side?: 'parent' | 'child';
-    [key: string]: any;
-}
-export interface UpdateAttributeParams {
-    databaseId: string;
-    tableId: string;
-    key: string;
-    type?: string;
-    required?: boolean;
-    default?: any;
-    size?: number;
-    min?: number;
-    max?: number;
-    array?: boolean;
-    encrypt?: boolean;
-    elements?: string[];
-    relatedCollection?: string;
-    relationType?: string;
-    twoWay?: boolean;
-    twoWayKey?: string;
-    onDelete?: string;
-}
-export interface DeleteAttributeParams {
-    databaseId: string;
-    tableId: string;
-    key: string;
-}
-export interface ApiResponse<T = any> {
-    data?: T;
-    total?: number;
-    documents?: T[];
-    rows?: T[];
-    collections?: T[];
-    tables?: T[];
-    errors?: any[];
-}
-export interface AdapterMetadata {
-    apiMode: ApiMode;
-    terminology: {
-        container: 'collection' | 'table';
-        item: 'document' | 'row';
-        service: 'Databases' | 'TablesDB';
-    };
-    capabilities: {
-        bulkOperations: boolean;
-        advancedQueries: boolean;
-        realtime: boolean;
-        transactions?: boolean;
-    };
-}
-/**
- * Main DatabaseAdapter interface - all implementations must support these methods
- */
-export interface DatabaseAdapter {
-    listRows(params: ListRowsParams): Promise<ApiResponse>;
-    createRow(params: CreateRowParams): Promise<ApiResponse>;
-    updateRow(params: UpdateRowParams): Promise<ApiResponse>;
-    deleteRow(params: DeleteRowParams): Promise<ApiResponse>;
-    getRow(params: {
-        databaseId: string;
-        tableId: string;
-        id: string;
-    }): Promise<ApiResponse>;
-    listTables(params: ListTablesParams): Promise<ApiResponse>;
-    createTable(params: CreateTableParams): Promise<ApiResponse>;
-    updateTable(params: UpdateTableParams): Promise<ApiResponse>;
-    deleteTable(params: DeleteTableParams): Promise<ApiResponse>;
-    getTable(params: GetTableParams): Promise<ApiResponse>;
-    listIndexes(params: ListIndexesParams): Promise<ApiResponse>;
-    createIndex(params: CreateIndexParams): Promise<ApiResponse>;
-    deleteIndex(params: DeleteIndexParams): Promise<ApiResponse>;
-    createAttribute(params: CreateAttributeParams): Promise<ApiResponse>;
-    updateAttribute(params: UpdateAttributeParams): Promise<ApiResponse>;
-    deleteAttribute(params: DeleteAttributeParams): Promise<ApiResponse>;
-    bulkCreateRows?(params: BulkCreateRowsParams): Promise<ApiResponse>;
-    bulkUpsertRows?(params: BulkUpsertRowsParams): Promise<ApiResponse>;
-    bulkDeleteRows?(params: BulkDeleteRowsParams): Promise<ApiResponse>;
-    getMetadata(): AdapterMetadata;
-    supportsBulkOperations(): boolean;
-    getApiMode(): ApiMode;
-    getTerminology(): AdapterMetadata['terminology'];
-    getRawClient(): any;
-}
-/**
- * Base adapter class with common functionality
- */
-export declare abstract class BaseAdapter implements DatabaseAdapter {
-    protected client: Client;
-    protected apiMode: ApiMode;
-    constructor(client: Client, apiMode: ApiMode);
-    abstract listRows(params: ListRowsParams): Promise<ApiResponse>;
-    abstract createRow(params: CreateRowParams): Promise<ApiResponse>;
-    abstract updateRow(params: UpdateRowParams): Promise<ApiResponse>;
-    abstract deleteRow(params: DeleteRowParams): Promise<ApiResponse>;
-    abstract getRow(params: {
-        databaseId: string;
-        tableId: string;
-        id: string;
-    }): Promise<ApiResponse>;
-    abstract listTables(params: ListTablesParams): Promise<ApiResponse>;
-    abstract createTable(params: CreateTableParams): Promise<ApiResponse>;
-    abstract updateTable(params: UpdateTableParams): Promise<ApiResponse>;
-    abstract deleteTable(params: DeleteTableParams): Promise<ApiResponse>;
-    abstract getTable(params: GetTableParams): Promise<ApiResponse>;
-    abstract listIndexes(params: ListIndexesParams): Promise<ApiResponse>;
-    abstract createIndex(params: CreateIndexParams): Promise<ApiResponse>;
-    abstract deleteIndex(params: DeleteIndexParams): Promise<ApiResponse>;
-    abstract createAttribute(params: CreateAttributeParams): Promise<ApiResponse>;
-    abstract updateAttribute(params: UpdateAttributeParams): Promise<ApiResponse>;
-    abstract deleteAttribute(params: DeleteAttributeParams): Promise<ApiResponse>;
-    abstract getMetadata(): AdapterMetadata;
-    getApiMode(): ApiMode;
-    getRawClient(): any;
-    supportsBulkOperations(): boolean;
-    getTerminology(): AdapterMetadata['terminology'];
-}
-/**
- * Error types for adapter operations
- */
-export declare class AdapterError extends Error {
-    readonly code: string;
-    readonly originalError?: Error | undefined;
-    constructor(message: string, code: string, originalError?: Error | undefined);
-}
-export declare class UnsupportedOperationError extends AdapterError {
-    constructor(operation: string, apiMode: ApiMode);
-}