appwrite-utils-cli 0.0.268 → 0.0.270

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;
+  });
+}

package/src/migrations/schema.ts

@@ -30,6 +30,14 @@ 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"
+    ),
 });
 
 type StringAttribute = z.infer<typeof stringAttributeSchema>;
@@ -68,6 +76,13 @@ 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"
+    ),
 });
 
 type IntegerAttribute = z.infer<typeof integerAttributeSchema>;
@@ -94,6 +109,13 @@ 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"
+    ),
 });
 
 type FloatAttribute = z.infer<typeof floatAttributeSchema>;
@@ -121,6 +143,13 @@ 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"
+    ),
 });
 
 type BooleanAttribute = z.infer<typeof booleanAttributeSchema>;
@@ -145,6 +174,13 @@ 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"
+    ),
 });
 
 type DatetimeAttribute = z.infer<typeof datetimeAttributeSchema>;
@@ -169,6 +205,13 @@ 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"
+    ),
 });
 
 type EmailAttribute = z.infer<typeof emailAttributeSchema>;
@@ -190,6 +233,13 @@ 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"
+    ),
 });
 
 type IpAttribute = z.infer<typeof ipAttributeSchema>;
@@ -211,6 +261,13 @@ 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"
+    ),
 });
 
 type UrlAttribute = z.infer<typeof urlAttributeSchema>;
@@ -236,6 +293,13 @@ 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"
+    ),
 });
 
 type EnumAttribute = z.infer<typeof enumAttributeSchema>;
@@ -291,6 +355,13 @@ const relationshipAttributeSchema = z.object({
     .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 type RelationshipAttribute = z.infer<typeof relationshipAttributeSchema>;
@@ -313,16 +384,18 @@ export const createRelationshipAttributes = (
   });
 };
 
-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:
@@ -551,6 +624,12 @@ 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/src/migrations/schemaStrings.ts

@@ -218,15 +218,22 @@ export class SchemaGenerator {
 
   typeToZod = (attribute: Attribute) => {
     let baseSchemaCode = "";
-
-    switch (attribute.type) {
+    const finalAttribute: Attribute = (
+      attribute.type === "string" &&
+      attribute.format &&
+      attribute.format === "enum" &&
+      attribute.type === "string"
+        ? { ...attribute, type: attribute.format }
+        : attribute
+    ) as 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()";
@@ -234,93 +241,93 @@ 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/src/utilsController.ts

@@ -49,6 +49,9 @@ export interface SetupOptions {
   importData: boolean;
   checkDuplicates: boolean;
   shouldWriteFile: boolean;
+  endpoint?: string;
+  project?: string;
+  key?: string;
 }
 
 type CollectionConfig = AppwriteConfig["collections"];
@@ -108,14 +111,27 @@ export class UtilsController {
   //   }
   // }
 
-  async init() {
+  async init(setupOptions: 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;
@@ -124,7 +140,7 @@ export class UtilsController {
   }
 
   async run(options: SetupOptions) {
-    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");
     }