appwrite-utils-cli 1.3.5 → 1.4.0

package/dist/adapters/AdapterFactory.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 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 "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;
+}
+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;
+    /**
+     * 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'): Promise<DatabaseAdapter>;
+/**
+ * Helper function to get adapter metadata without creating full adapter
+ */
+export declare function getApiCapabilities(endpoint: string, project: string, apiKey: string): Promise<{
+    apiMode: ApiMode;
+    terminology: {
+        container: string;
+        item: string;
+        service: string;
+    };
+    capabilities: string[];
+}>;

package/dist/adapters/AdapterFactory.js

@@ -0,0 +1,217 @@
+/**
+ * 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 } from "../utils/versionDetection.js";
+import { TablesDBAdapter } from './TablesDBAdapter.js';
+import { LegacyAdapter } from './LegacyAdapter.js';
+/**
+ * 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 cacheKey = `${config.appwriteEndpoint}:${config.appwriteProject}:${config.apiMode || 'auto'}`;
+        // Check cache first (unless force refresh)
+        if (!config.forceRefresh) {
+            const cached = this.getCachedAdapter(cacheKey);
+            if (cached) {
+                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;
+        }
+        else {
+            // Auto-detect API mode
+            detectionResult = await detectAppwriteVersionCached(config.appwriteEndpoint, config.appwriteProject, config.appwriteKey, config.forceRefresh);
+            apiMode = detectionResult.apiMode;
+        }
+        // Create appropriate adapter
+        const result = await this.createAdapter(config, apiMode);
+        // Cache the result
+        this.setCachedAdapter(cacheKey, result.adapter);
+        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) {
+        try {
+            // Dynamic import of TablesDB SDK
+            const { Client, TablesDB } = await import('node-appwrite-tablesdb');
+            const client = new Client()
+                .setEndpoint(config.appwriteEndpoint)
+                .setProject(config.appwriteProject)
+                .setKey(config.appwriteKey);
+            const tablesDB = new TablesDB(client);
+            const adapter = new TablesDBAdapter(tablesDB);
+            return { adapter, client };
+        }
+        catch (error) {
+            console.warn('Failed to load TablesDB SDK, falling back to legacy:', error);
+            // Fallback to legacy adapter if TablesDB SDK is not available
+            return this.createLegacyAdapter(config);
+        }
+    }
+    /**
+     * Create Legacy adapter with dynamic import
+     */
+    static async createLegacyAdapter(config) {
+        try {
+            // Dynamic import of legacy SDK
+            const { Client, Databases } = await import('node-appwrite');
+            const client = new Client()
+                .setEndpoint(config.appwriteEndpoint)
+                .setProject(config.appwriteProject)
+                .setKey(config.appwriteKey);
+            const databases = new Databases(client);
+            const adapter = new LegacyAdapter(databases);
+            return { adapter, client };
+        }
+        catch (error) {
+            throw new Error(`Failed to load legacy Appwrite SDK: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * 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();
+    }
+    /**
+     * 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') {
+    const result = await AdapterFactory.create({
+        appwriteEndpoint: endpoint,
+        appwriteProject: project,
+        appwriteKey: apiKey,
+        apiMode: mode
+    });
+    return result.adapter;
+}
+/**
+ * Helper function to get adapter metadata without creating full adapter
+ */
+export async function getApiCapabilities(endpoint, project, apiKey) {
+    const adapter = await createDatabaseAdapter(endpoint, project, apiKey, 'auto');
+    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

@@ -0,0 +1,217 @@
+/**
+ * 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 { 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;
+    enabled?: boolean;
+}
+export interface UpdateTableParams {
+    databaseId: string;
+    id: string;
+    name: string;
+    permissions?: string[];
+    documentSecurity?: 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[];
+}
+export interface CreateIndexParams {
+    databaseId: string;
+    tableId: string;
+    key: string;
+    type: string;
+    attributes: string[];
+    orders?: string[];
+}
+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;
+    [key: string]: any;
+}
+export interface UpdateAttributeParams {
+    databaseId: string;
+    tableId: string;
+    key: string;
+    required?: boolean;
+    default?: any;
+}
+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: any;
+    protected apiMode: ApiMode;
+    constructor(client: any, 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);
+}

package/dist/adapters/DatabaseAdapter.js

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+/**
+ * Base adapter class with common functionality
+ */
+export class BaseAdapter {
+    client;
+    apiMode;
+    constructor(client, apiMode) {
+        this.client = client;
+        this.apiMode = apiMode;
+    }
+    // Common implementations
+    getApiMode() {
+        return this.apiMode;
+    }
+    getRawClient() {
+        return this.client;
+    }
+    supportsBulkOperations() {
+        return this.getMetadata().capabilities.bulkOperations;
+    }
+    getTerminology() {
+        return this.getMetadata().terminology;
+    }
+}
+/**
+ * Error types for adapter operations
+ */
+export class AdapterError extends Error {
+    code;
+    originalError;
+    constructor(message, code, originalError) {
+        super(message);
+        this.code = code;
+        this.originalError = originalError;
+        this.name = 'AdapterError';
+    }
+}
+export class UnsupportedOperationError extends AdapterError {
+    constructor(operation, apiMode) {
+        super(`Operation '${operation}' is not supported in ${apiMode} mode`, 'UNSUPPORTED_OPERATION');
+        this.name = 'UnsupportedOperationError';
+    }
+}

package/dist/adapters/LegacyAdapter.d.ts

@@ -0,0 +1,49 @@
+/**
+ * LegacyAdapter - Translation Layer for Legacy Appwrite API
+ *
+ * This adapter translates TablesDB-style calls (object notation) to legacy
+ * Appwrite Databases API calls (positional parameters). It ensures all internal
+ * code can use modern TablesDB patterns while maintaining compatibility with
+ * older Appwrite instances.
+ */
+import { BaseAdapter, type CreateRowParams, type UpdateRowParams, type ListRowsParams, type DeleteRowParams, type CreateTableParams, type UpdateTableParams, type ListTablesParams, type DeleteTableParams, type GetTableParams, type BulkCreateRowsParams, type BulkUpsertRowsParams, type BulkDeleteRowsParams, type CreateIndexParams, type ListIndexesParams, type DeleteIndexParams, type CreateAttributeParams, type UpdateAttributeParams, type DeleteAttributeParams, type ApiResponse, type AdapterMetadata } from './DatabaseAdapter.js';
+/**
+ * LegacyAdapter - Translates TablesDB calls to legacy Databases API
+ */
+export declare class LegacyAdapter extends BaseAdapter {
+    private databases;
+    constructor(client: any);
+    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;
+    /**
+     * Check if endpoint supports bulk operations via HTTP (for cloud instances)
+     */
+    private supportsHttpBulkOperations;
+    /**
+     * Normalize response format to be consistent with TablesDB
+     */
+    private normalizeResponse;
+}