appwrite-utils-cli 1.3.4 → 1.4.0

package/src/utils/getClientFromConfig.ts

@@ -1,5 +1,12 @@
 import { type AppwriteConfig } from "appwrite-utils";
 import { Client } from "node-appwrite";
+import { AdapterFactory, type AdapterFactoryResult } from "../adapters/AdapterFactory.js";
+import type { DatabaseAdapter } from "../adapters/DatabaseAdapter.js";
+
+/**
+ * Legacy function - returns basic Client for backwards compatibility
+ * @deprecated Use getAdapterFromConfig for dual API support
+ */
 export const getClientFromConfig = (config: AppwriteConfig) => {
   let appwriteClient: Client | undefined;
   if (!config.appwriteClient) {
@@ -12,6 +19,55 @@ export const getClientFromConfig = (config: AppwriteConfig) => {
   return appwriteClient;
 };
 
+/**
+ * Legacy function - returns basic Client
+ * @deprecated Use createDatabaseAdapter for dual API support
+ */
 export const getClient = (endpoint: string, project: string, key: string) => {
   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: AppwriteConfig, forceRefresh?: boolean): Promise<{
+  adapter: DatabaseAdapter;
+  client: Client;
+  apiMode: 'legacy' | 'tablesdb';
+}> => {
+  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: string, 
+  project: string, 
+  key: string,
+  apiMode: 'auto' | 'legacy' | 'tablesdb' = 'auto'
+): Promise<{
+  adapter: DatabaseAdapter;
+  client: Client;
+  apiMode: 'legacy' | 'tablesdb';
+}> => {
+  const result = await AdapterFactory.create({
+    appwriteEndpoint: endpoint,
+    appwriteProject: project,
+    appwriteKey: key,
+    apiMode
+  });
+  
+  return {
+    adapter: result.adapter,
+    client: result.client,
+    apiMode: result.apiMode
+  };
+};

package/src/utils/loadConfigs.ts

@@ -388,7 +388,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(),
@@ -436,7 +435,6 @@ const loadYamlCollection = (filePath: string): CollectionCreate | null => {
         required: attr.required,
         array: attr.array,
         xdefault: attr.default,
-        description: attr.description,
         min: attr.min,
         max: attr.max,
         elements: attr.elements,

package/src/utils/schemaStrings.ts

@@ -277,11 +277,6 @@ export class SchemaGenerator {
   createSchemaString = (name: string, attributes: Attribute[]): string => {
     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) || [];
@@ -418,14 +413,14 @@ 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")`;
           }
         }
         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")`;
           }
@@ -522,15 +517,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/src/utils/setupFiles.ts

@@ -12,6 +12,8 @@ const baseConfig: AppwriteConfig = {
   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/src/utils/versionDetection.ts

@@ -0,0 +1,265 @@
+/**
+ * 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 async function detectAppwriteVersion(
+  endpoint: string,
+  project: string,
+  apiKey: string
+): Promise<VersionDetectionResult> {
+  // 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: string,
+  project: string,
+  apiKey: string
+): Promise<VersionDetectionResult> {
+  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(): Promise<VersionDetectionResult> {
+  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 {
+  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> {
+  // 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: string): boolean {
+  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(): Promise<{
+  tablesDbAvailable: boolean;
+  legacyAvailable: boolean;
+}> {
+  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(): void {
+  detectionCache.clear();
+}

package/src/utils/yamlConverter.ts

@@ -17,7 +17,6 @@ export interface YamlCollectionData {
     required?: boolean;
     array?: boolean;
     default?: any;
-    description?: string;
     min?: number;
     max?: number;
     elements?: string[];
@@ -70,7 +69,6 @@ export function collectionToYaml(collection: Collection | CollectionCreate, sche
       if (attr.required !== undefined) yamlAttr.required = attr.required;
       if (attr.array !== undefined) 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) yamlAttr.max = attr.max;
       if ('elements' in attr && attr.elements !== undefined) yamlAttr.elements = attr.elements;

package/src/utilsController.ts

@@ -128,6 +128,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/dist/functions/openapi.d.ts

@@ -1,4 +0,0 @@
-import { type AppwriteConfig } from "appwrite-utils";
-import { z } from "zod";
-export declare const generateOpenApi: (config: AppwriteConfig) => Promise<void>;
-export declare function transformTypeToOpenApi<T extends z.ZodTypeAny>(schema: T, description?: string | Record<string, any> | null | undefined): T;

package/dist/functions/openapi.js

@@ -1,60 +0,0 @@
-import { OpenAPIRegistry, OpenApiGeneratorV3, OpenApiGeneratorV31, } from "@asteasolutions/zod-to-openapi";
-import { attributeSchema, CollectionSchema, } from "appwrite-utils";
-import { z } from "zod";
-import { writeFileSync } from "fs";
-const registry = new OpenAPIRegistry();
-export const generateOpenApi = async (config) => {
-    if (!config.collections) {
-        return;
-    }
-    for (const collection of config.collections) {
-        // Transform and register each attribute schema
-        const attributeSchemas = collection.attributes.map((attribute) => {
-            return transformTypeToOpenApi(attributeSchema, attribute.description);
-        });
-        // Create and register the collection schema with descriptions
-        const updatedCollectionSchema = CollectionSchema.extend({
-            // @ts-ignore
-            attributes: attributeSchemas,
-        }).openapi(collection.description ?? "No description");
-        // Register the updated collection schema under the collection name
-        registry.register(collection.name, updatedCollectionSchema);
-    }
-    // Convert the registry to OpenAPI JSON
-    const generator = new OpenApiGeneratorV31(registry.definitions);
-    const openApiSpec = generator.generateComponents();
-    // Output the OpenAPI spec to a file
-    writeFileSync("./appwrite/openapi/openapi.json", JSON.stringify(openApiSpec, null, 2));
-};
-export function transformTypeToOpenApi(schema, description) {
-    // Check if description is an object (OpenAPI properties) or a string
-    let updatedSchema;
-    if (!description) {
-        return schema;
-    }
-    if (typeof description === "string") {
-        updatedSchema = schema.openapi(description);
-    }
-    else if (typeof description === "object") {
-        updatedSchema = schema.openapi(description);
-    }
-    else {
-        updatedSchema = schema;
-    }
-    // Check and transform attributes if they exist
-    if (schema._def && schema._def.shape) {
-        const shape = schema._def.shape();
-        for (const key in shape) {
-            const attributeDesc = shape[key].description;
-            if (attributeDesc) {
-                if (typeof attributeDesc === "string") {
-                    shape[key] = shape[key].openapi(attributeDesc);
-                }
-                else if (typeof attributeDesc === "object") {
-                    shape[key] = shape[key].openapi(attributeDesc);
-                }
-            }
-        }
-    }
-    return updatedSchema;
-}

package/dist/migrations/attributes.d.ts

@@ -1,4 +0,0 @@
-import { type Databases, type Models } from "node-appwrite";
-import { type Attribute } from "appwrite-utils";
-export declare const createOrUpdateAttribute: (db: Databases, dbId: string, collection: Models.Collection, attribute: Attribute) => Promise<void>;
-export declare const createUpdateCollectionAttributes: (db: Databases, dbId: string, collection: Models.Collection, attributes: Attribute[]) => Promise<void>;