@njdamstra/appwrite-utils-cli 1.8.9

package/src/storage/schemas.ts

@@ -0,0 +1,205 @@
+import { z } from "zod";
+import {
+  attributeSchema,
+  type Attribute,
+  parseAttribute,
+  CollectionCreateSchema,
+} from "@njdamstra/appwrite-utils";
+
+export const BackupSchema = z.object({
+  $id: z.string(),
+  $createdAt: z.string(),
+  $updatedAt: z.string(),
+  database: z.string(),
+  collections: z.array(z.string()),
+  documents: z
+    .array(
+      z.object({
+        collectionId: z.string(),
+        data: z.string(),
+      })
+    )
+    .default([]),
+});
+
+export type Backup = z.infer<typeof BackupSchema>;
+
+export const BackupCreateSchema = BackupSchema.omit({
+  $id: true,
+  $createdAt: true,
+  $updatedAt: true,
+});
+
+export type BackupCreate = z.infer<typeof BackupCreateSchema>;
+
+export const BatchSchema = z.object({
+  $id: z.string(),
+  $createdAt: z.string(),
+  $updatedAt: z.string(),
+  data: z.string().describe("The serialized data for this batch"),
+  processed: z
+    .boolean()
+    .default(false)
+    .describe("Whether the batch has been processed"),
+});
+
+export type Batch = z.infer<typeof BatchSchema>;
+
+export const BatchCreateSchema = BatchSchema.omit({
+  $id: true,
+  $createdAt: true,
+  $updatedAt: true,
+});
+
+export type BatchCreate = z.infer<typeof BatchCreateSchema>;
+
+export const OperationSchema = z.object({
+  $id: z.string(),
+  $createdAt: z.string(),
+  $updatedAt: z.string(),
+  operationType: z.string(),
+  collectionId: z.string(),
+  data: z.any(),
+  batches: z.array(z.string()).default([]).optional(),
+  progress: z.number(),
+  total: z.number(),
+  error: z.string(),
+  status: z
+    .enum([
+      "pending",
+      "ready",
+      "in_progress",
+      "completed",
+      "error",
+      "cancelled",
+    ])
+    .default("pending"),
+});
+
+export type Operation = z.infer<typeof OperationSchema>;
+
+export const OperationCreateSchema = OperationSchema.omit({
+  $id: true,
+  $createdAt: true,
+  $updatedAt: true,
+});
+
+export type OperationCreate = z.infer<typeof OperationCreateSchema>;
+
+export const getMigrationCollectionSchemas = () => {
+  const currentOperationsAttributes: Attribute[] = [
+    parseAttribute({
+      key: "operationType",
+      type: "string",
+      error: "Invalid Operation Type",
+      size: 50,
+      required: true,
+      array: false,
+      xdefault: null,
+    }),
+    attributeSchema.parse({
+      key: "collectionId",
+      type: "string",
+      error: "Invalid Collection Id",
+      size: 50,
+      array: false,
+      xdefault: null,
+    }),
+    attributeSchema.parse({
+      key: "batches",
+      type: "string",
+      error: "Invalid Batches",
+      size: 1073741824,
+      array: true,
+    }),
+    attributeSchema.parse({
+      key: "data",
+      type: "string",
+      error: "Invalid Data",
+      size: 1073741824,
+    }),
+    attributeSchema.parse({
+      key: "progress",
+      type: "integer",
+      error: "Invalid Progress",
+      required: true,
+      array: false,
+    }),
+    attributeSchema.parse({
+      key: "total",
+      type: "integer",
+      error: "Invalid Total",
+      required: true,
+      array: false,
+    }),
+    attributeSchema.parse({
+      key: "error",
+      type: "string",
+      error: "Operation Error",
+      required: false,
+      array: false,
+    }),
+    attributeSchema.parse({
+      key: "status",
+      type: "enum",
+      elements: [
+        "pending",
+        "ready",
+        "in_progress",
+        "completed",
+        "error",
+        "cancelled",
+      ],
+      error: "Invalid Status",
+      array: false,
+      xdefault: "pending",
+    }),
+  ];
+
+  const currentOperationsConfig = CollectionCreateSchema.parse({
+    name: "CurrentOperations",
+    enabled: true,
+    documentSecurity: false,
+    attributes: [],
+    indexes: [],
+  });
+
+  const batchesAttributes: Attribute[] = [
+    attributeSchema.parse({
+      key: "data",
+      type: "string",
+      size: 1073741824,
+      error: "Invalid Data",
+      required: true,
+      array: false,
+    }),
+    attributeSchema.parse({
+      key: "processed",
+      type: "boolean",
+      error: "Invalid Processed",
+      required: true,
+      array: false,
+      xdefault: false,
+    }),
+  ];
+
+  const batchesConfig = CollectionCreateSchema.parse({
+    name: "Batches",
+    enabled: true,
+    documentSecurity: false,
+    attributes: [],
+    indexes: [],
+  });
+
+  const toReturn = {
+    CurrentOperations: {
+      collection: currentOperationsConfig,
+      attributes: currentOperationsAttributes,
+    },
+    Batches: {
+      collection: batchesConfig,
+      attributes: batchesAttributes,
+    },
+  };
+  return toReturn;
+};

package/src/types/node-appwrite-tablesdb.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Type declarations for optional node-appwrite-tablesdb module
+ * This allows compilation when the module is not installed
+ */
+
+declare module 'node-appwrite-tablesdb' {
+  export class Client {
+    setEndpoint(endpoint: string): this;
+    setProject(project: string): this;
+    setKey(key: string): this;
+  }
+  
+  export class TablesDB {
+    constructor(client: Client);
+    
+    // Core methods based on TablesDB API
+    listTables(databaseId: string, queries?: any[]): Promise<any>;
+    createTable(databaseId: string, id: string, name: string, permissions?: string[], documentSecurity?: boolean, enabled?: boolean): Promise<any>;
+    updateTable(databaseId: string, id: string, name: string, permissions?: string[], documentSecurity?: boolean, enabled?: boolean): Promise<any>;
+    deleteTable(databaseId: string, tableId: string): Promise<void>;
+    getTable(databaseId: string, tableId: string): Promise<any>;
+    
+    listRows(databaseId: string, tableId: string, queries?: any[]): Promise<any>;
+    createRow(databaseId: string, tableId: string, id: string, data: any, permissions?: string[]): Promise<any>;
+    updateRow(databaseId: string, tableId: string, id: string, data?: any, permissions?: string[]): Promise<any>;
+    deleteRow(databaseId: string, tableId: string, id: string): Promise<void>;
+    getRow(databaseId: string, tableId: string, id: string): Promise<any>;
+    
+    // Bulk operations (if supported)
+    bulkCreateRows?(databaseId: string, tableId: string, rows: any[]): Promise<any>;
+    bulkUpsertRows?(databaseId: string, tableId: string, rows: any[]): Promise<any>;
+    bulkDeleteRows?(databaseId: string, tableId: string, rowIds: string[]): Promise<any>;
+    
+    // Index operations
+    listIndexes(databaseId: string, tableId: string, queries?: any[]): Promise<any>;
+    createIndex(databaseId: string, tableId: string, key: string, type: string, attributes: string[], orders?: string[]): Promise<any>;
+    deleteIndex(databaseId: string, tableId: string, key: string): Promise<void>;
+    
+    // Attribute operations
+    createAttribute(databaseId: string, tableId: string, key: string, type: string, ...args: any[]): Promise<any>;
+    updateAttribute(databaseId: string, tableId: string, key: string, required?: boolean, defaultValue?: any): Promise<any>;
+    deleteAttribute(databaseId: string, tableId: string, key: string): Promise<void>;
+  }
+}

package/src/types.ts

@@ -0,0 +1,9 @@
+export type { ValidationRules } from "./utils/validationRules.js";
+export {
+  type AuthUserCreate,
+  AuthUserCreateSchema,
+  type AuthUser,
+  AuthUserSchema,
+} from "./schemas/authUser.js";
+export { validationRules } from "./utils/validationRules.js";
+export { afterImportActions } from "./migrations/afterImportActions.js";

package/src/users/methods.ts

@@ -0,0 +1,359 @@
+import type { AppwriteConfig, ConfigCollection } from "@njdamstra/appwrite-utils";
+import {
+  AppwriteException,
+  Databases,
+  ID,
+  Query,
+  Users,
+  type Models,
+} from "node-appwrite";
+import {
+  AuthUserSchema,
+  type AuthUser,
+  type AuthUserCreate,
+} from "../schemas/authUser.js";
+import { logger } from "../shared/logging.js";
+import { splitIntoBatches } from "../shared/migrationHelpers.js";
+import {
+  getAppwriteClient,
+  tryAwaitWithRetry,
+} from "../utils/helperFunctions.js";
+import { isUndefined } from "es-toolkit/compat";
+import { isEmpty } from "es-toolkit/compat";
+import { MessageFormatter } from "../shared/messageFormatter.js";
+
+export class UsersController {
+  private config: AppwriteConfig;
+  private users: Users;
+  static userFields = [
+    "email",
+    "name",
+    "password",
+    "phone",
+    "labels",
+    "prefs",
+    "userId",
+    "$createdAt",
+    "$updatedAt",
+  ];
+
+  constructor(config: AppwriteConfig, db: Databases) {
+    this.config = config;
+    this.users = new Users(this.config.appwriteClient!);
+  }
+
+  async wipeUsers() {
+    const allUsers = await this.getAllUsers();
+    MessageFormatter.progress("Deleting all users...", { prefix: "Users" });
+
+    const createBatches = (finalData: any[], batchSize: number) => {
+      const finalBatches: any[][] = [];
+      for (let i = 0; i < finalData.length; i += batchSize) {
+        finalBatches.push(finalData.slice(i, i + batchSize));
+      }
+      return finalBatches;
+    };
+
+    let usersDeleted = 0;
+    if (allUsers.length > 0) {
+      const batchedUserPromises = createBatches(allUsers, 25); // Batch size of 25
+
+      for (const batch of batchedUserPromises) {
+        MessageFormatter.progress(`Deleting ${batch.length} users...`, { prefix: "Users" });
+        await Promise.all(
+          batch.map((user) =>
+            tryAwaitWithRetry(async () => await this.users.delete(user.$id))
+          )
+        );
+        usersDeleted += batch.length;
+        if (usersDeleted % 100 === 0) {
+          MessageFormatter.progress(`Deleted ${usersDeleted} users...`, { prefix: "Users" });
+        }
+      }
+    } else {
+      MessageFormatter.info("No users to delete", { prefix: "Users" });
+    }
+  }
+
+  async getAllUsers() {
+    const allUsers: Models.User<Models.Preferences>[] = [];
+    const users = await tryAwaitWithRetry(
+      async () => await this.users.list([Query.limit(200)])
+    );
+    if (users.users.length === 0) {
+      return [];
+    }
+    if (users.users.length === 200) {
+      let lastDocumentId = users.users[users.users.length - 1].$id;
+      allUsers.push(...users.users);
+      while (lastDocumentId) {
+        const moreUsers = await tryAwaitWithRetry(
+          async () =>
+            await this.users.list([
+              Query.limit(200),
+              Query.cursorAfter(lastDocumentId),
+            ])
+        );
+        allUsers.push(...moreUsers.users);
+        if (moreUsers.users.length < 200) {
+          break;
+        }
+        lastDocumentId = moreUsers.users[moreUsers.users.length - 1].$id;
+      }
+    } else {
+      allUsers.push(...users.users);
+    }
+    return allUsers;
+  }
+
+  async createUsersAndReturn(items: AuthUserCreate[]): Promise<any[]> {
+    const users = await Promise.all(
+      items.map((item) => this.createUserAndReturn(item))
+    );
+    return users;
+  }
+
+  async createUserAndReturn(item: AuthUserCreate): Promise<any> {
+    try {
+      const user = await tryAwaitWithRetry(async () => {
+        const createdUser = await this.users.create(
+          item.userId || ID.unique(),
+          item.email || undefined,
+          item.phone && item.phone.length < 15 && item.phone.startsWith("+")
+            ? item.phone
+            : undefined,
+          `changeMe${item.email?.toLowerCase()}` || `changeMePlease`,
+          item.name || undefined
+        );
+
+        if (item.labels) {
+          await this.users.updateLabels(createdUser.$id, item.labels);
+        }
+        if (item.prefs) {
+          await this.users.updatePrefs(createdUser.$id, item.prefs);
+        }
+
+        return createdUser;
+      }); // Set throwError to true since we want to handle errors
+
+      return user;
+    } catch (e) {
+      if (e instanceof Error) {
+        logger.error("FAILED CREATING USER: ", e.message, item);
+      }
+    }
+  }
+
+  async createAndCheckForUserAndReturn(item: AuthUserCreate) {
+    let userToReturn: Models.User<Models.Preferences> | undefined = undefined;
+    try {
+      // Attempt to find an existing user by email or phone.
+      let foundUsers: Models.User<Models.Preferences>[] = [];
+      if (item.email) {
+        const foundUsersByEmail = await this.users.list([
+          Query.equal("email", item.email),
+        ]);
+        foundUsers = foundUsersByEmail.users;
+      }
+      if (item.phone) {
+        const foundUsersByPhone = await this.users.list([
+          Query.equal("phone", item.phone),
+        ]);
+        foundUsers = foundUsers.length
+          ? foundUsers.concat(foundUsersByPhone.users)
+          : foundUsersByPhone.users;
+      }
+
+      userToReturn = foundUsers[0] || undefined;
+
+      if (!userToReturn) {
+        userToReturn = await this.users.create(
+          item.userId || ID.unique(),
+          item.email || undefined,
+          item.phone && item.phone.length < 15 && item.phone.startsWith("+")
+            ? item.phone
+            : undefined,
+          item.password?.toLowerCase() ||
+            `changeMe${item.email?.toLowerCase()}` ||
+            `changeMePlease`,
+          item.name || undefined
+        );
+      } else {
+        // Update user details as necessary, ensuring email uniqueness if attempting an update.
+        if (
+          item.email &&
+          item.email !== userToReturn.email &&
+          !isEmpty(item.email) &&
+          !isUndefined(item.email)
+        ) {
+          const emailExists = await this.users.list([
+            Query.equal("email", item.email),
+          ]);
+          if (emailExists.users.length === 0) {
+            userToReturn = await this.users.updateEmail(
+              userToReturn.$id,
+              item.email
+            );
+          } else {
+            MessageFormatter.warning("Email update skipped: Email already exists.", { prefix: "Users" });
+          }
+        }
+        if (item.password) {
+          userToReturn = await this.users.updatePassword(
+            userToReturn.$id,
+            item.password.toLowerCase()
+          );
+        }
+        if (item.name && item.name !== userToReturn.name) {
+          userToReturn = await this.users.updateName(
+            userToReturn.$id,
+            item.name
+          );
+        }
+        if (
+          item.phone &&
+          item.phone !== userToReturn.phone &&
+          item.phone.length < 15 &&
+          item.phone.startsWith("+") &&
+          (isUndefined(userToReturn.phone) || isEmpty(userToReturn.phone))
+        ) {
+          const userFoundWithPhone = await this.users.list([
+            Query.equal("phone", item.phone),
+          ]);
+          if (userFoundWithPhone.total === 0) {
+            userToReturn = await this.users.updatePhone(
+              userToReturn.$id,
+              item.phone
+            );
+          }
+        }
+      }
+      if (item.$createdAt && item.$updatedAt) {
+        MessageFormatter.warning(
+          "$createdAt and $updatedAt are not yet supported, sorry about that!",
+          { prefix: "Users" }
+        );
+      }
+      if (item.labels && item.labels.length) {
+        userToReturn = await this.users.updateLabels(
+          userToReturn.$id,
+          item.labels
+        );
+      }
+      if (item.prefs && Object.keys(item.prefs).length) {
+        await this.users.updatePrefs(userToReturn.$id, item.prefs);
+        userToReturn.prefs = item.prefs;
+      }
+      return userToReturn;
+    } catch (error) {
+      return userToReturn;
+    }
+  }
+
+  async getUserIdByEmailOrPhone(email?: string, phone?: string) {
+    if (!email && !phone) {
+      return undefined;
+    }
+    if (email && phone) {
+      const foundUsersByEmail = await this.users.list([
+        // @ts-ignore
+        Query.or([Query.equal("email", email), Query.equal("phone", phone)]),
+      ]);
+      if (foundUsersByEmail.users.length > 0) {
+        return foundUsersByEmail.users[0]?.$id;
+      }
+    } else if (email) {
+      const foundUsersByEmail = await this.users.list([
+        Query.equal("email", email),
+      ]);
+      if (foundUsersByEmail.users.length > 0) {
+        return foundUsersByEmail.users[0]?.$id;
+      } else {
+        if (!phone) {
+          return undefined;
+        } else {
+          const foundUsersByPhone = await this.users.list([
+            Query.equal("phone", phone),
+          ]);
+          if (foundUsersByPhone.users.length > 0) {
+            return foundUsersByPhone.users[0]?.$id;
+          } else {
+            return undefined;
+          }
+        }
+      }
+    }
+    if (phone) {
+      const foundUsersByPhone = await this.users.list([
+        Query.equal("phone", phone),
+      ]);
+      if (foundUsersByPhone.users.length > 0) {
+        return foundUsersByPhone.users[0]?.$id;
+      } else {
+        return undefined;
+      }
+    }
+  }
+
+  transferUsersBetweenDbsLocalToRemote = async (
+    endpoint: string,
+    projectId: string,
+    apiKey: string
+  ) => {
+    const localUsers = this.users;
+    const client = getAppwriteClient(endpoint, projectId, apiKey);
+    const remoteUsers = new Users(client);
+
+    let fromUsers = await localUsers.list([Query.limit(50)]);
+
+    if (fromUsers.users.length === 0) {
+      MessageFormatter.info("No users found", { prefix: "Users" });
+      return;
+    } else if (fromUsers.users.length < 50) {
+      MessageFormatter.progress(`Transferring ${fromUsers.users.length} users to remote`, { prefix: "Users" });
+      const batchedPromises = fromUsers.users.map((user) => {
+        return tryAwaitWithRetry(async () => {
+          const toCreateObject: Partial<typeof user> = {
+            ...user,
+          };
+          delete toCreateObject.$id;
+          delete toCreateObject.$createdAt;
+          delete toCreateObject.$updatedAt;
+          await remoteUsers.create(
+            user.$id,
+            user.email,
+            user.phone,
+            user.password,
+            user.name
+          );
+        });
+      });
+      await Promise.all(batchedPromises);
+    } else {
+      while (fromUsers.users.length === 50) {
+        fromUsers = await localUsers.list([
+          Query.limit(50),
+          Query.cursorAfter(fromUsers.users[fromUsers.users.length - 1].$id),
+        ]);
+        const batchedPromises = fromUsers.users.map((user) => {
+          return tryAwaitWithRetry(async () => {
+            const toCreateObject: Partial<typeof user> = {
+              ...user,
+            };
+            delete toCreateObject.$id;
+            delete toCreateObject.$createdAt;
+            delete toCreateObject.$updatedAt;
+            await remoteUsers.create(
+              user.$id,
+              user.email,
+              user.phone,
+              user.password,
+              user.name
+            );
+          });
+        });
+        await Promise.all(batchedPromises);
+      }
+    }
+  };
+}