@njdamstra/appwrite-utils-cli 1.8.9

package/dist/storage/schemas.js

@@ -0,0 +1,175 @@
+import { z } from "zod";
+import { attributeSchema, 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 const BackupCreateSchema = BackupSchema.omit({
+    $id: true,
+    $createdAt: true,
+    $updatedAt: true,
+});
+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 const BatchCreateSchema = BatchSchema.omit({
+    $id: true,
+    $createdAt: true,
+    $updatedAt: true,
+});
+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 const OperationCreateSchema = OperationSchema.omit({
+    $id: true,
+    $createdAt: true,
+    $updatedAt: true,
+});
+export const getMigrationCollectionSchemas = () => {
+    const currentOperationsAttributes = [
+        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 = [
+        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/dist/types.d.ts

@@ -0,0 +1,4 @@
+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/dist/types.js

@@ -0,0 +1,3 @@
+export { AuthUserCreateSchema, AuthUserSchema, } from "./schemas/authUser.js";
+export { validationRules } from "./utils/validationRules.js";
+export { afterImportActions } from "./migrations/afterImportActions.js";

package/dist/users/methods.d.ts

@@ -0,0 +1,16 @@
+import type { AppwriteConfig } from "@njdamstra/appwrite-utils";
+import { Databases, type Models } from "node-appwrite";
+import { type AuthUserCreate } from "../schemas/authUser.js";
+export declare class UsersController {
+    private config;
+    private users;
+    static userFields: string[];
+    constructor(config: AppwriteConfig, db: Databases);
+    wipeUsers(): Promise<void>;
+    getAllUsers(): Promise<Models.User<Models.Preferences>[]>;
+    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/users/methods.js

@@ -0,0 +1,277 @@
+import { AppwriteException, Databases, ID, Query, Users, } from "node-appwrite";
+import { AuthUserSchema, } 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 {
+    config;
+    users;
+    static userFields = [
+        "email",
+        "name",
+        "password",
+        "phone",
+        "labels",
+        "prefs",
+        "userId",
+        "$createdAt",
+        "$updatedAt",
+    ];
+    constructor(config, db) {
+        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, batchSize) => {
+            const finalBatches = [];
+            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 = [];
+        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) {
+        const users = await Promise.all(items.map((item) => this.createUserAndReturn(item)));
+        return users;
+    }
+    async createUserAndReturn(item) {
+        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) {
+        let userToReturn = undefined;
+        try {
+            // Attempt to find an existing user by email or phone.
+            let foundUsers = [];
+            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, phone) {
+        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, projectId, apiKey) => {
+        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 = {
+                        ...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 = {
+                            ...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);
+            }
+        }
+    };
+}

package/dist/utils/ClientFactory.d.ts

@@ -0,0 +1,87 @@
+import { Client } from "node-appwrite";
+import type { AppwriteConfig } from "@njdamstra/appwrite-utils";
+import type { DatabaseAdapter } from "../adapters/DatabaseAdapter.js";
+/**
+ * Factory for creating authenticated Appwrite clients and database adapters.
+ *
+ * This factory provides a clean separation of concerns by taking pre-configured
+ * AppwriteConfig objects (with authentication already resolved by ConfigManager)
+ * and creating the necessary client and adapter instances.
+ *
+ * Key features:
+ * - Takes pre-authenticated config from ConfigManager
+ * - Creates client with appropriate authentication method
+ * - Creates adapter with automatic version detection
+ * - Leverages AdapterFactory's internal caching for performance
+ *
+ * @example
+ * ```typescript
+ * const configManager = ConfigManager.getInstance();
+ * const config = await configManager.loadConfig();
+ *
+ * // Config already has session or API key resolved
+ * const { client, adapter } = await ClientFactory.createFromConfig(config);
+ * ```
+ */
+export declare class ClientFactory {
+    /**
+     * Create authenticated client and database adapter from configuration.
+     *
+     * This method expects the config to have authentication already resolved:
+     * - Either `sessionCookie` is set (from ConfigManager's session loading)
+     * - Or `appwriteKey` is set (from config file or CLI overrides)
+     *
+     * The ConfigManager handles all session discovery and authentication priority,
+     * so this factory simply applies the resolved authentication to the client.
+     *
+     * @param config - AppwriteConfig with resolved authentication
+     * @returns Object containing authenticated client and database adapter
+     * @throws Error if no authentication method is available in config
+     *
+     * @example
+     * ```typescript
+     * const config = await ConfigManager.getInstance().loadConfig();
+     * const { client, adapter } = await ClientFactory.createFromConfig(config);
+     *
+     * // Client is now authenticated and ready to use
+     * const databases = new Databases(client);
+     * const collections = await adapter.listCollections(databaseId);
+     * ```
+     */
+    static createFromConfig(config: AppwriteConfig): Promise<{
+        client: Client;
+        adapter: DatabaseAdapter;
+    }>;
+    /**
+     * Create client and adapter from individual parameters.
+     *
+     * This is a lower-level method for cases where you don't have a full
+     * AppwriteConfig object. For most use cases, prefer createFromConfig().
+     *
+     * @param endpoint - Appwrite endpoint URL
+     * @param project - Appwrite project ID
+     * @param options - Authentication and API mode options
+     * @returns Object containing authenticated client and database adapter
+     * @throws Error if no authentication method is provided
+     *
+     * @example
+     * ```typescript
+     * const { client, adapter } = await ClientFactory.create(
+     *   "https://cloud.appwrite.io/v1",
+     *   "my-project-id",
+     *   {
+     *     apiKey: "my-api-key",
+     *     apiMode: "auto"
+     *   }
+     * );
+     * ```
+     */
+    static create(endpoint: string, project: string, options?: {
+        apiKey?: string;
+        sessionCookie?: string;
+        apiMode?: "auto" | "legacy" | "tablesdb";
+    }): Promise<{
+        client: Client;
+        adapter: DatabaseAdapter;
+    }>;
+}