appwrite-utils-cli 0.0.269 → 0.0.270

package/dist/migrations/schema.js

@@ -29,6 +29,12 @@ const stringAttributeSchema = z.object({
         .boolean()
         .optional()
         .describe("Whether the attribute is encrypted or not"),
+    format: z.string().nullish().describe("The format of the attribute"),
+    description: z
+        .string()
+        .or(z.record(z.string()))
+        .nullish()
+        .describe("The description of the attribute, also used for OpenApi Generation"),
 });
 const integerAttributeSchema = z.object({
     key: z.string().describe("The key of the attribute"),
@@ -64,6 +70,11 @@ const integerAttributeSchema = z.object({
         .int()
         .nullish()
         .describe("The default value of the attribute"),
+    description: z
+        .string()
+        .or(z.record(z.string()))
+        .nullish()
+        .describe("The description of the attribute, also used for OpenApi Generation"),
 });
 const floatAttributeSchema = z.object({
     key: z.string().describe("The key of the attribute"),
@@ -87,6 +98,11 @@ const floatAttributeSchema = z.object({
     min: z.number().optional().describe("The minimum value of the attribute"),
     max: z.number().optional().describe("The maximum value of the attribute"),
     xdefault: z.number().nullish().describe("The default value of the attribute"),
+    description: z
+        .string()
+        .or(z.record(z.string()))
+        .nullish()
+        .describe("The description of the attribute, also used for OpenApi Generation"),
 });
 const booleanAttributeSchema = z.object({
     key: z.string().describe("The key of the attribute"),
@@ -111,6 +127,11 @@ const booleanAttributeSchema = z.object({
         .boolean()
         .nullish()
         .describe("The default value of the attribute"),
+    description: z
+        .string()
+        .or(z.record(z.string()))
+        .nullish()
+        .describe("The description of the attribute, also used for OpenApi Generation"),
 });
 const datetimeAttributeSchema = z.object({
     key: z.string().describe("The key of the attribute"),
@@ -132,6 +153,11 @@ const datetimeAttributeSchema = z.object({
         .default(false)
         .describe("Whether the attribute is an array or not"),
     xdefault: z.string().nullish().describe("The default value of the attribute"),
+    description: z
+        .string()
+        .or(z.record(z.string()))
+        .nullish()
+        .describe("The description of the attribute, also used for OpenApi Generation"),
 });
 const emailAttributeSchema = z.object({
     key: z.string().describe("The key of the attribute"),
@@ -153,6 +179,11 @@ const emailAttributeSchema = z.object({
         .default(false)
         .describe("Whether the attribute is an array or not"),
     xdefault: z.string().nullish().describe("The default value of the attribute"),
+    description: z
+        .string()
+        .or(z.record(z.string()))
+        .nullish()
+        .describe("The description of the attribute, also used for OpenApi Generation"),
 });
 const ipAttributeSchema = z.object({
     key: z.string().describe("The key of the attribute"),
@@ -171,6 +202,11 @@ const ipAttributeSchema = z.object({
         .default(false)
         .describe("Whether the attribute is an array or not"),
     xdefault: z.string().nullish().describe("The default value of the attribute"),
+    description: z
+        .string()
+        .or(z.record(z.string()))
+        .nullish()
+        .describe("The description of the attribute, also used for OpenApi Generation"),
 });
 const urlAttributeSchema = z.object({
     key: z.string().describe("The key of the attribute"),
@@ -189,6 +225,11 @@ const urlAttributeSchema = z.object({
         .default(false)
         .describe("Whether the attribute is an array or not"),
     xdefault: z.string().nullish().describe("The default value of the attribute"),
+    description: z
+        .string()
+        .or(z.record(z.string()))
+        .nullish()
+        .describe("The description of the attribute, also used for OpenApi Generation"),
 });
 const enumAttributeSchema = z.object({
     key: z.string().describe("The key of the attribute"),
@@ -211,6 +252,11 @@ const enumAttributeSchema = z.object({
         .describe("The elements of the enum attribute")
         .default([]),
     xdefault: z.string().nullish().describe("The default value of the attribute"),
+    description: z
+        .string()
+        .or(z.record(z.string()))
+        .nullish()
+        .describe("The description of the attribute, also used for OpenApi Generation"),
 });
 const relationshipAttributeSchema = z.object({
     key: z.string().describe("The key of the attribute"),
@@ -257,6 +303,11 @@ const relationshipAttributeSchema = z.object({
     })
         .optional()
         .describe("Configuration for mapping and resolving relationships during data import"),
+    description: z
+        .string()
+        .or(z.record(z.string()))
+        .nullish()
+        .describe("The description of the attribute, also used for OpenApi Generation"),
 });
 export const createRelationshipAttributes = (relatedCollection, relationType, twoWay, twoWayKey, onDelete, side) => {
     return relationshipAttributeSchema.parse({
@@ -268,16 +319,18 @@ export const createRelationshipAttributes = (relatedCollection, relationType, tw
         side,
     });
 };
-export const attributeSchema = stringAttributeSchema
-    .or(integerAttributeSchema)
-    .or(floatAttributeSchema)
-    .or(booleanAttributeSchema)
-    .or(datetimeAttributeSchema)
-    .or(emailAttributeSchema)
-    .or(ipAttributeSchema)
-    .or(urlAttributeSchema)
-    .or(enumAttributeSchema)
-    .or(relationshipAttributeSchema);
+export const attributeSchema = z.discriminatedUnion("type", [
+    stringAttributeSchema,
+    integerAttributeSchema,
+    floatAttributeSchema,
+    booleanAttributeSchema,
+    datetimeAttributeSchema,
+    emailAttributeSchema,
+    ipAttributeSchema,
+    urlAttributeSchema,
+    enumAttributeSchema,
+    relationshipAttributeSchema,
+]);
 export const parseAttribute = (attribute) => {
     if (attribute.type === "string") {
         return stringAttributeSchema.parse(attribute);
@@ -451,6 +504,10 @@ export const collectionSchema = z.object({
         .boolean()
         .default(false)
         .describe("Whether document security is enabled or not"),
+    description: z
+        .string()
+        .optional()
+        .describe("The description of the collection, if any, used to generate OpenAPI documentation"),
     $createdAt: z.string(),
     $updatedAt: z.string(),
     $permissions: z

package/dist/migrations/schemaStrings.js

@@ -166,14 +166,20 @@ export class SchemaGenerator {
     };
     typeToZod = (attribute) => {
         let baseSchemaCode = "";
-        switch (attribute.type) {
+        const finalAttribute = (attribute.type === "string" &&
+            attribute.format &&
+            attribute.format === "enum" &&
+            attribute.type === "string"
+            ? { ...attribute, type: attribute.format }
+            : attribute);
+        switch (finalAttribute.type) {
             case "string":
                 baseSchemaCode = "z.string()";
-                if (attribute.size) {
-                    baseSchemaCode += `.max(${attribute.size}, "Maximum length of ${attribute.size} characters exceeded")`;
+                if (finalAttribute.size) {
+                    baseSchemaCode += `.max(${finalAttribute.size}, "Maximum length of ${finalAttribute.size} characters exceeded")`;
                 }
-                if (attribute.xdefault !== undefined) {
-                    baseSchemaCode += `.default("${attribute.xdefault}")`;
+                if (finalAttribute.xdefault !== undefined) {
+                    baseSchemaCode += `.default("${finalAttribute.xdefault}")`;
                 }
                 if (!attribute.required && !attribute.array) {
                     baseSchemaCode += ".nullish()";
@@ -181,95 +187,95 @@ export class SchemaGenerator {
                 break;
             case "integer":
                 baseSchemaCode = "z.number().int()";
-                if (attribute.min !== undefined) {
-                    if (BigInt(attribute.min) === BigInt(-9223372036854776000)) {
-                        delete attribute.min;
+                if (finalAttribute.min !== undefined) {
+                    if (BigInt(finalAttribute.min) === BigInt(-9223372036854776000)) {
+                        delete finalAttribute.min;
                     }
                     else {
-                        baseSchemaCode += `.min(${attribute.min}, "Minimum value of ${attribute.min} not met")`;
+                        baseSchemaCode += `.min(${finalAttribute.min}, "Minimum value of ${finalAttribute.min} not met")`;
                     }
                 }
-                if (attribute.max !== undefined) {
-                    if (BigInt(attribute.max) === BigInt(9223372036854776000)) {
-                        delete attribute.max;
+                if (finalAttribute.max !== undefined) {
+                    if (BigInt(finalAttribute.max) === BigInt(9223372036854776000)) {
+                        delete finalAttribute.max;
                     }
                     else {
-                        baseSchemaCode += `.max(${attribute.max}, "Maximum value of ${attribute.max} exceeded")`;
+                        baseSchemaCode += `.max(${finalAttribute.max}, "Maximum value of ${finalAttribute.max} exceeded")`;
                     }
                 }
-                if (attribute.xdefault !== undefined) {
-                    baseSchemaCode += `.default(${attribute.xdefault})`;
+                if (finalAttribute.xdefault !== undefined) {
+                    baseSchemaCode += `.default(${finalAttribute.xdefault})`;
                 }
-                if (!attribute.required && !attribute.array) {
+                if (!finalAttribute.required && !finalAttribute.array) {
                     baseSchemaCode += ".nullish()";
                 }
                 break;
             case "float":
                 baseSchemaCode = "z.number()";
-                if (attribute.min !== undefined) {
-                    baseSchemaCode += `.min(${attribute.min}, "Minimum value of ${attribute.min} not met")`;
+                if (finalAttribute.min !== undefined) {
+                    baseSchemaCode += `.min(${finalAttribute.min}, "Minimum value of ${finalAttribute.min} not met")`;
                 }
-                if (attribute.max !== undefined) {
-                    baseSchemaCode += `.max(${attribute.max}, "Maximum value of ${attribute.max} exceeded")`;
+                if (finalAttribute.max !== undefined) {
+                    baseSchemaCode += `.max(${finalAttribute.max}, "Maximum value of ${finalAttribute.max} exceeded")`;
                 }
-                if (attribute.xdefault !== undefined) {
-                    baseSchemaCode += `.default(${attribute.xdefault})`;
+                if (finalAttribute.xdefault !== undefined) {
+                    baseSchemaCode += `.default(${finalAttribute.xdefault})`;
                 }
-                if (!attribute.required && !attribute.array) {
+                if (!finalAttribute.required && !finalAttribute.array) {
                     baseSchemaCode += ".nullish()";
                 }
                 break;
             case "boolean":
                 baseSchemaCode = "z.boolean()";
-                if (attribute.xdefault !== undefined) {
-                    baseSchemaCode += `.default(${attribute.xdefault})`;
+                if (finalAttribute.xdefault !== undefined) {
+                    baseSchemaCode += `.default(${finalAttribute.xdefault})`;
                 }
-                if (!attribute.required && !attribute.array) {
+                if (!finalAttribute.required && !finalAttribute.array) {
                     baseSchemaCode += ".nullish()";
                 }
                 break;
             case "datetime":
                 baseSchemaCode = "z.date()";
-                if (attribute.xdefault !== undefined) {
-                    baseSchemaCode += `.default(new Date("${attribute.xdefault}"))`;
+                if (finalAttribute.xdefault !== undefined) {
+                    baseSchemaCode += `.default(new Date("${finalAttribute.xdefault}"))`;
                 }
-                if (!attribute.required && !attribute.array) {
+                if (!finalAttribute.required && !finalAttribute.array) {
                     baseSchemaCode += ".nullish()";
                 }
                 break;
             case "email":
                 baseSchemaCode = "z.string().email()";
-                if (attribute.xdefault !== undefined) {
-                    baseSchemaCode += `.default("${attribute.xdefault}")`;
+                if (finalAttribute.xdefault !== undefined) {
+                    baseSchemaCode += `.default("${finalAttribute.xdefault}")`;
                 }
-                if (!attribute.required && !attribute.array) {
+                if (!finalAttribute.required && !finalAttribute.array) {
                     baseSchemaCode += ".nullish()";
                 }
                 break;
             case "ip":
                 baseSchemaCode = "z.string()"; // Add custom validation as needed
-                if (attribute.xdefault !== undefined) {
-                    baseSchemaCode += `.default("${attribute.xdefault}")`;
+                if (finalAttribute.xdefault !== undefined) {
+                    baseSchemaCode += `.default("${finalAttribute.xdefault}")`;
                 }
-                if (!attribute.required && !attribute.array) {
+                if (!finalAttribute.required && !finalAttribute.array) {
                     baseSchemaCode += ".nullish()";
                 }
                 break;
             case "url":
                 baseSchemaCode = "z.string().url()";
-                if (attribute.xdefault !== undefined) {
-                    baseSchemaCode += `.default("${attribute.xdefault}")`;
+                if (finalAttribute.xdefault !== undefined) {
+                    baseSchemaCode += `.default("${finalAttribute.xdefault}")`;
                 }
-                if (!attribute.required && !attribute.array) {
+                if (!finalAttribute.required && !finalAttribute.array) {
                     baseSchemaCode += ".nullish()";
                 }
                 break;
             case "enum":
-                baseSchemaCode = `z.enum([${attribute.elements
+                baseSchemaCode = `z.enum([${finalAttribute.elements
                     .map((element) => `"${element}"`)
                     .join(", ")}])`;
-                if (attribute.xdefault !== undefined) {
-                    baseSchemaCode += `.default("${attribute.xdefault}")`;
+                if (finalAttribute.xdefault !== undefined) {
+                    baseSchemaCode += `.default("${finalAttribute.xdefault}")`;
                 }
                 if (!attribute.required && !attribute.array) {
                     baseSchemaCode += ".nullish()";

package/dist/schemas/authUser.d.ts

@@ -29,8 +29,8 @@ export declare const AuthUserSchema: z.ZodObject<{
 }>;
 export type AuthUser = z.infer<typeof AuthUserSchema>;
 export declare const AuthUserCreateSchema: z.ZodObject<{
-    email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    email: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     $createdAt: z.ZodOptional<z.ZodString>;
     $updatedAt: z.ZodOptional<z.ZodString>;
     phone: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -41,16 +41,16 @@ export declare const AuthUserCreateSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     prefs: Record<string, string>;
     labels: string[];
-    email?: string | null | undefined;
     name?: string | null | undefined;
+    email?: string | null | undefined;
     $createdAt?: string | undefined;
     $updatedAt?: string | undefined;
     phone?: string | null | undefined;
     userId?: string | undefined;
     password?: string | undefined;
 }, {
-    email?: string | null | undefined;
     name?: string | null | undefined;
+    email?: string | null | undefined;
     $createdAt?: string | undefined;
     $updatedAt?: string | undefined;
     phone?: string | null | undefined;

package/dist/utilsController.d.ts

@@ -15,6 +15,9 @@ export interface SetupOptions {
     importData: boolean;
     checkDuplicates: boolean;
     shouldWriteFile: boolean;
+    endpoint?: string;
+    project?: string;
+    key?: string;
 }
 export declare class UtilsController {
     private appwriteFolderPath;
@@ -27,6 +30,6 @@ export declare class UtilsController {
     validityRuleDefinitions: ValidationRules;
     afterImportActionsDefinitions: AfterImportActions;
     constructor();
-    init(): Promise<void>;
+    init(setupOptions: SetupOptions): Promise<void>;
     run(options: SetupOptions): Promise<void>;
 }

package/dist/utilsController.js

@@ -66,14 +66,26 @@ export class UtilsController {
     //     console.error("Failed to load custom definitions:", error);
     //   }
     // }
-    async init() {
+    async init(setupOptions) {
         if (!this.config) {
             console.log("Initializing appwrite client & loading config...");
             this.config = await loadConfig(this.appwriteConfigPath);
-            this.appwriteServer = new Client()
-                .setEndpoint(this.config.appwriteEndpoint)
-                .setProject(this.config.appwriteProject)
-                .setKey(this.config.appwriteKey);
+            this.appwriteServer = new Client();
+            if (setupOptions.endpoint) {
+                if (!setupOptions.project || !setupOptions.key) {
+                    throw new Error("Project ID and API key required when setting endpoint");
+                }
+                this.appwriteServer
+                    .setEndpoint(setupOptions.endpoint)
+                    .setProject(setupOptions.project)
+                    .setKey(setupOptions.key);
+            }
+            else {
+                this.appwriteServer
+                    .setEndpoint(this.config.appwriteEndpoint)
+                    .setProject(this.config.appwriteProject)
+                    .setKey(this.config.appwriteKey);
+            }
             this.database = new Databases(this.appwriteServer);
             this.storage = new Storage(this.appwriteServer);
             this.config.appwriteClient = this.appwriteServer;
@@ -81,7 +93,7 @@ export class UtilsController {
         }
     }
     async run(options) {
-        await this.init(); // Ensure initialization is done
+        await this.init(options); // Ensure initialization is done
         if (!this.database || !this.storage || !this.config) {
             throw new Error("Database or storage not initialized");
         }

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": "0.0.269",
+  "version": "0.0.270",
   "main": "src/main.ts",
   "type": "module",
   "repository": {
@@ -30,6 +30,7 @@
     "postinstall": "echo 'This package is intended for CLI use only and should not be added as a dependency in other projects.'"
   },
   "dependencies": {
+    "@asteasolutions/zod-to-openapi": "^7.0.0",
     "js-yaml": "^4.1.0",
     "lodash": "^4.17.21",
     "luxon": "^3.4.4",

package/src/main.ts

@@ -5,7 +5,6 @@ const args = process.argv.slice(2);
 
 async function main() {
   const controller = new UtilsController();
-  await controller.init();
 
   let sync = false;
   let runProd = false;
@@ -18,6 +17,9 @@ async function main() {
   let importData = false;
   let wipeDocuments = false;
   let shouldWriteFile = false;
+  let endpoint: string | undefined;
+  let project: string | undefined;
+  let key: string | undefined;
   if (args.includes("--sync")) {
     sync = true;
   }
@@ -51,6 +53,15 @@ async function main() {
   if (args.includes("--write-data") || args.includes("--writeData")) {
     shouldWriteFile = true;
   }
+  if (args.includes("--endpoint")) {
+    endpoint = args[args.indexOf("--endpoint") + 1];
+  }
+  if (args.includes("--project")) {
+    project = args[args.indexOf("--project") + 1];
+  }
+  if (args.includes("--key")) {
+    key = args[args.indexOf("--key") + 1];
+  }
   if (args.includes("--init")) {
     await controller.run({
       sync: sync,
@@ -66,6 +77,9 @@ async function main() {
       importData: false,
       checkDuplicates: false,
       shouldWriteFile: shouldWriteFile,
+      endpoint: endpoint,
+      project: project,
+      key: key,
     });
   } else {
     await controller.run({
@@ -82,6 +96,9 @@ async function main() {
       importData: importData,
       checkDuplicates: false,
       shouldWriteFile: shouldWriteFile,
+      endpoint: endpoint,
+      project: project,
+      key: key,
     });
   }
 }

package/src/migrations/appwriteToX.ts

@@ -81,7 +81,18 @@ export class AppwriteToX {
           collection.$permissions
         );
         const collAttributes = attributesSchema
-          .parse(collection.attributes)
+          .parse(
+            collection.attributes.map((attr: any) => {
+              if (
+                attr.type === "string" &&
+                attr.format &&
+                attr.format.length > 0
+              ) {
+                return { ...attr, type: attr.format };
+              }
+              return attr;
+            })
+          )
           .filter((attribute) =>
             attribute.type === "relationship"
               ? attribute.side !== "child"

package/src/migrations/openapi.ts

@@ -0,0 +1,69 @@
+import {
+  OpenAPIRegistry,
+  OpenApiGeneratorV3,
+  OpenApiGeneratorV31,
+} from "@asteasolutions/zod-to-openapi";
+import {
+  attributeSchema,
+  collectionSchema,
+  type AppwriteConfig,
+  type Attribute,
+  type Collection,
+  type CollectionCreate,
+} from "./schema.js";
+import { z } from "zod";
+import { writeFileSync } from "fs";
+
+const registry = new OpenAPIRegistry();
+
+export const generateOpenApi = async (config: AppwriteConfig) => {
+  for (const collection of config.collections) {
+    // Transform and register each attribute schema
+    const attributeSchemas = collection.attributes.map((attribute) => {
+      return transformTypeToOpenApi(attributeSchema);
+    });
+
+    // Create and register the collection schema with descriptions
+    const updatedCollectionSchema = collectionSchema
+      .extend({
+        // @ts-ignore
+        attributes: z.array(z.union(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
+  // @ts-ignore
+  const openApiSpec = registry.toOpenAPI();
+
+  // Output the OpenAPI spec to a file
+  writeFileSync(
+    "./appwrite/openapi/openapi.json",
+    JSON.stringify(openApiSpec, null, 2)
+  );
+};
+
+export function transformTypeToOpenApi<T extends z.ZodTypeAny>(
+  schema: T
+): z.infer<T> {
+  return schema.transform((data) => {
+    let finalData = data;
+    if (data._def.attributes) {
+      finalData._def.attributes = data._def.attributes.map(
+        (attribute: typeof attributeSchema) => {
+          if (attribute.description) {
+            return attribute.openapi(attribute.description);
+          }
+          return attribute;
+        }
+      );
+    }
+    if (schema.description) {
+      finalData.openapi(schema.description);
+    }
+    return finalData;
+  });
+}