appwrite-utils-cli 1.3.4 → 1.4.0

package/dist/users/methods.d.ts

@@ -8,8 +8,8 @@ export declare class UsersController {
     constructor(config: AppwriteConfig, db: Databases);
     wipeUsers(): Promise<void>;
     getAllUsers(): Promise<Models.User<Models.Preferences>[]>;
-    createUsersAndReturn(items: AuthUserCreate[]): Promise<(Models.User<Models.Preferences> | undefined)[]>;
-    createUserAndReturn(item: AuthUserCreate): Promise<Models.User<Models.Preferences> | undefined>;
+    createUsersAndReturn(items: AuthUserCreate[]): Promise<any[]>;
+    createUserAndReturn(item: AuthUserCreate): Promise<any>;
     createAndCheckForUserAndReturn(item: AuthUserCreate): Promise<Models.User<Models.Preferences> | undefined>;
     getUserIdByEmailOrPhone(email?: string, phone?: string): Promise<string | undefined>;
     transferUsersBetweenDbsLocalToRemote: (endpoint: string, projectId: string, apiKey: string) => Promise<void>;

package/dist/utils/configMigration.js

@@ -220,7 +220,6 @@ async function convertCollectionToYaml(tsFilePath, targetDir) {
                     required: attr.required ?? false,
                     array: attr.array,
                     default: attr.xdefault || attr.default,
-                    description: attr.description,
                     min: attr.min,
                     max: attr.max,
                     elements: attr.elements,

package/dist/utils/getClientFromConfig.d.ts

@@ -1,4 +1,30 @@
 import { type AppwriteConfig } from "appwrite-utils";
 import { Client } from "node-appwrite";
+import type { DatabaseAdapter } from "../adapters/DatabaseAdapter.js";
+/**
+ * Legacy function - returns basic Client for backwards compatibility
+ * @deprecated Use getAdapterFromConfig for dual API support
+ */
 export declare const getClientFromConfig: (config: AppwriteConfig) => Client | undefined;
+/**
+ * Legacy function - returns basic Client
+ * @deprecated Use createDatabaseAdapter for dual API support
+ */
 export declare const getClient: (endpoint: string, project: string, key: string) => Client;
+/**
+ * Modern adapter-based client creation with dual API support
+ * Returns both adapter and legacy client for compatibility
+ */
+export declare const getAdapterFromConfig: (config: AppwriteConfig, forceRefresh?: boolean) => Promise<{
+    adapter: DatabaseAdapter;
+    client: Client;
+    apiMode: "legacy" | "tablesdb";
+}>;
+/**
+ * Create adapter from individual parameters
+ */
+export declare const getAdapter: (endpoint: string, project: string, key: string, apiMode?: "auto" | "legacy" | "tablesdb") => Promise<{
+    adapter: DatabaseAdapter;
+    client: Client;
+    apiMode: "legacy" | "tablesdb";
+}>;

package/dist/utils/getClientFromConfig.js

@@ -1,5 +1,10 @@
 import {} from "appwrite-utils";
 import { Client } from "node-appwrite";
+import { AdapterFactory } from "../adapters/AdapterFactory.js";
+/**
+ * Legacy function - returns basic Client for backwards compatibility
+ * @deprecated Use getAdapterFromConfig for dual API support
+ */
 export const getClientFromConfig = (config) => {
     let appwriteClient;
     if (!config.appwriteClient) {
@@ -11,6 +16,38 @@ export const getClientFromConfig = (config) => {
     }
     return appwriteClient;
 };
+/**
+ * Legacy function - returns basic Client
+ * @deprecated Use createDatabaseAdapter for dual API support
+ */
 export const getClient = (endpoint, project, key) => {
     return new Client().setEndpoint(endpoint).setProject(project).setKey(key);
 };
+/**
+ * Modern adapter-based client creation with dual API support
+ * Returns both adapter and legacy client for compatibility
+ */
+export const getAdapterFromConfig = async (config, forceRefresh) => {
+    const result = await AdapterFactory.createFromConfig(config, forceRefresh);
+    return {
+        adapter: result.adapter,
+        client: result.client,
+        apiMode: result.apiMode
+    };
+};
+/**
+ * Create adapter from individual parameters
+ */
+export const getAdapter = async (endpoint, project, key, apiMode = 'auto') => {
+    const result = await AdapterFactory.create({
+        appwriteEndpoint: endpoint,
+        appwriteProject: project,
+        appwriteKey: key,
+        apiMode
+    });
+    return {
+        adapter: result.adapter,
+        client: result.client,
+        apiMode: result.apiMode
+    };
+};

package/dist/utils/loadConfigs.js

@@ -346,7 +346,6 @@ const YamlCollectionSchema = z.object({
         required: z.boolean().default(false),
         array: z.boolean().optional(),
         default: z.any().optional(),
-        description: z.string().optional(),
         min: z.number().optional(),
         max: z.number().optional(),
         elements: z.array(z.string()).optional(),
@@ -387,7 +386,6 @@ const loadYamlCollection = (filePath) => {
                 required: attr.required,
                 array: attr.array,
                 xdefault: attr.default,
-                description: attr.description,
                 min: attr.min,
                 max: attr.max,
                 elements: attr.elements,

package/dist/utils/schemaStrings.js

@@ -211,11 +211,6 @@ export class SchemaGenerator {
     createSchemaString = (name, attributes) => {
         const pascalName = toPascalCase(name);
         let imports = `import { z } from "zod";\n`;
-        const hasDescription = attributes.some((attr) => attr.description);
-        if (hasDescription) {
-            imports += `import { extendZodWithOpenApi } from "@asteasolutions/zod-to-openapi";\n`;
-            imports += `extendZodWithOpenApi(z);\n`;
-        }
         // Use the relationshipMap to find related collections
         const relationshipDetails = this.relationshipMap.get(name) || [];
         const relatedCollections = relationshipDetails
@@ -340,7 +335,7 @@ export class SchemaGenerator {
                 baseSchemaCode = "z.number().int()";
                 if (finalAttribute.min !== undefined) {
                     if (BigInt(finalAttribute.min) === BigInt(-9223372036854776000)) {
-                        delete finalAttribute.min;
+                        finalAttribute.min = undefined;
                     }
                     else {
                         baseSchemaCode += `.min(${finalAttribute.min}, "Minimum value of ${finalAttribute.min} not met")`;
@@ -348,7 +343,7 @@ export class SchemaGenerator {
                 }
                 if (finalAttribute.max !== undefined) {
                     if (BigInt(finalAttribute.max) === BigInt(9223372036854776000)) {
-                        delete finalAttribute.max;
+                        finalAttribute.max = undefined;
                     }
                     else {
                         baseSchemaCode += `.max(${finalAttribute.max}, "Maximum value of ${finalAttribute.max} exceeded")`;
@@ -445,16 +440,6 @@ export class SchemaGenerator {
         if (attribute.array && !attribute.required) {
             baseSchemaCode += ".nullish()";
         }
-        if (attribute.description) {
-            if (typeof attribute.description === "string") {
-                baseSchemaCode += `.openapi({ description: "${attribute.description}" })`;
-            }
-            else {
-                baseSchemaCode += `.openapi(${Object.entries(attribute.description)
-                    .map(([key, value]) => `"${key}": ${value}`)
-                    .join(", ")})`;
-            }
-        }
         return baseSchemaCode;
     };
 }

package/dist/utils/setupFiles.js

@@ -10,6 +10,8 @@ const baseConfig = {
     appwriteEndpoint: "https://cloud.appwrite.io/v1",
     appwriteProject: "YOUR_PROJECT_ID",
     appwriteKey: "YOUR_API_KEY",
+    appwriteClient: null,
+    apiMode: "auto", // Enable dual API support - auto-detect TablesDB vs legacy
     logging: {
         enabled: false,
         level: "info",

package/dist/utils/versionDetection.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 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
+ */
+export declare function detectSdkSupport(): Promise<{
+    tablesDbAvailable: boolean;
+    legacyAvailable: boolean;
+}>;
+/**
+ * Clear version detection cache (useful for testing)
+ */
+export declare function clearVersionDetectionCache(): void;

package/dist/utils/versionDetection.js

@@ -0,0 +1,217 @@
+/**
+ * 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
+ */
+/**
+ * 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) {
+    // Clean endpoint URL
+    const cleanEndpoint = endpoint.replace(/\/$/, '');
+    // Try primary detection method: TablesDB endpoint probe
+    try {
+        const tablesDbResult = await probeTablesDbEndpoint(cleanEndpoint, project, apiKey);
+        if (tablesDbResult.apiMode === 'tablesdb') {
+            return tablesDbResult;
+        }
+    }
+    catch (error) {
+        console.warn('TablesDB endpoint probe failed:', error instanceof Error ? error.message : 'Unknown error');
+    }
+    // Try secondary detection method: SDK feature detection
+    try {
+        const sdkResult = await probeSdkCapabilities();
+        if (sdkResult.apiMode === 'tablesdb') {
+            return sdkResult;
+        }
+    }
+    catch (error) {
+        console.warn('SDK capability probe failed:', error instanceof Error ? error.message : 'Unknown error');
+    }
+    // Fallback to legacy mode
+    return {
+        apiMode: 'legacy',
+        detectionMethod: 'fallback',
+        confidence: 'low'
+    };
+}
+/**
+ * Test TablesDB endpoint availability - most reliable detection method
+ */
+async function probeTablesDbEndpoint(endpoint, project, apiKey) {
+    const response = await fetch(`${endpoint}/tablesdb/`, {
+        method: 'GET',
+        headers: {
+            'Content-Type': 'application/json',
+            'X-Appwrite-Project': project,
+            'X-Appwrite-Key': apiKey
+        },
+        // Short timeout for faster detection
+        signal: AbortSignal.timeout(5000)
+    });
+    if (response.ok || response.status === 404) {
+        // 200 = TablesDB available, 404 = endpoint exists but no tables
+        // Both indicate TablesDB support
+        return {
+            apiMode: 'tablesdb',
+            detectionMethod: 'endpoint_probe',
+            confidence: 'high'
+        };
+    }
+    // 501 Not Implemented or other errors = no TablesDB support
+    throw new Error(`TablesDB endpoint returned ${response.status}: ${response.statusText}`);
+}
+/**
+ * SDK capability detection as secondary method
+ */
+async function probeSdkCapabilities() {
+    try {
+        // Try to import TablesDB SDK
+        let TablesDBModule;
+        try {
+            TablesDBModule = await import('node-appwrite-tablesdb');
+        }
+        catch (importError) {
+            // TablesDB SDK not available, will fall back to legacy
+        }
+        if (TablesDBModule?.TablesDB) {
+            return {
+                apiMode: 'tablesdb',
+                detectionMethod: 'endpoint_probe',
+                confidence: 'medium'
+            };
+        }
+    }
+    catch (error) {
+        // TablesDB SDK not available, assume legacy
+    }
+    // Check for legacy SDK availability
+    try {
+        const { Databases } = await import('node-appwrite');
+        if (Databases) {
+            return {
+                apiMode: 'legacy',
+                detectionMethod: 'endpoint_probe',
+                confidence: 'medium'
+            };
+        }
+    }
+    catch (error) {
+        throw new Error('No Appwrite SDK available');
+    }
+    throw new Error('Unable to determine SDK capabilities');
+}
+/**
+ * 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) {
+    // Check cache first (unless force refresh)
+    if (!forceRefresh) {
+        const cached = detectionCache.get(endpoint, project);
+        if (cached) {
+            return cached;
+        }
+    }
+    // Perform fresh detection
+    const result = await detectAppwriteVersion(endpoint, project, apiKey);
+    // Cache the result
+    detectionCache.set(endpoint, project, result);
+    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
+ */
+export async function detectSdkSupport() {
+    const result = {
+        tablesDbAvailable: false,
+        legacyAvailable: false
+    };
+    // Test TablesDB SDK availability
+    try {
+        const tablesModule = await import('node-appwrite-tablesdb');
+        if (tablesModule) {
+            result.tablesDbAvailable = true;
+        }
+    }
+    catch (error) {
+        // TablesDB SDK not available
+    }
+    // Test legacy SDK availability  
+    try {
+        await import('node-appwrite');
+        result.legacyAvailable = true;
+    }
+    catch (error) {
+        // Legacy SDK not available
+    }
+    return result;
+}
+/**
+ * Clear version detection cache (useful for testing)
+ */
+export function clearVersionDetectionCache() {
+    detectionCache.clear();
+}

package/dist/utils/yamlConverter.d.ts

@@ -15,7 +15,6 @@ export interface YamlCollectionData {
         required?: boolean;
         array?: boolean;
         default?: any;
-        description?: string;
         min?: number;
         max?: number;
         elements?: string[];

package/dist/utils/yamlConverter.js

@@ -33,8 +33,6 @@ export function collectionToYaml(collection, schemaPath = "../.yaml_schemas/coll
                 yamlAttr.array = attr.array;
             if ('xdefault' in attr && attr.xdefault !== undefined)
                 yamlAttr.default = attr.xdefault;
-            if (attr.description !== undefined)
-                yamlAttr.description = attr.description;
             if ('min' in attr && attr.min !== undefined)
                 yamlAttr.min = attr.min;
             if ('max' in attr && attr.max !== undefined)

package/dist/utilsController.js

@@ -55,6 +55,8 @@ export class UtilsController {
                     appwriteEndpoint: directConfig.appwriteEndpoint,
                     appwriteProject: directConfig.appwriteProject,
                     appwriteKey: directConfig.appwriteKey,
+                    appwriteClient: null,
+                    apiMode: "auto", // Default to auto-detect for dual API support
                     enableBackups: false,
                     backupInterval: 0,
                     backupRetention: 0,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "appwrite-utils-cli",
   "description": "Appwrite Utility Functions to help with database management, data conversion, data import, migrations, and much more. Meant to be used as a CLI tool, I do not recommend installing this in frontend environments.",
-  "version": "1.3.4",
+  "version": "1.4.0",
   "main": "src/main.ts",
   "type": "module",
   "repository": {
@@ -33,7 +33,7 @@
     "@types/inquirer": "^9.0.8",
     "@types/json-schema": "^7.0.15",
     "@types/yargs": "^17.0.33",
-    "appwrite-utils": "^1.3.2",
+    "appwrite-utils": "^1.4.0",
     "chalk": "^5.4.1",
     "cli-progress": "^3.12.0",
     "commander": "^12.1.0",
@@ -44,6 +44,7 @@
     "luxon": "^3.6.1",
     "nanostores": "^0.10.3",
     "node-appwrite": "^17",
+    "node-appwrite-tablesdb": "npm:node-appwrite@^18.0.0",
     "p-limit": "^6.2.0",
     "tar": "^7.4.3",
     "tsx": "^4.20.3",