@njdamstra/appwrite-utils-cli 1.8.9

package/src/shared/attributeMapper.ts

@@ -0,0 +1,229 @@
+import type { CreateAttributeParams, UpdateAttributeParams } from "../adapters/DatabaseAdapter.js";
+import type { Attribute } from "@njdamstra/appwrite-utils";
+
+function ensureNumber(n: any): number | undefined {
+  if (n === null || n === undefined) return undefined;
+  const num = Number(n);
+  return Number.isFinite(num) ? num : undefined;
+}
+
+/**
+ * Map a schema Attribute into DatabaseAdapter CreateAttributeParams
+ * Only includes fields valid for the specific type to satisfy TS unions.
+ * Also normalizes min/max ordering for numeric types to avoid server errors.
+ */
+export function mapToCreateAttributeParams(
+  attr: Attribute,
+  base: { databaseId: string; tableId: string }
+): CreateAttributeParams {
+  const type = String((attr as any).type || "").toLowerCase();
+  const required = !!(attr as any).required;
+  const array = !!(attr as any).array;
+  const xdefault = (attr as any).xdefault;
+  const encrypt = (attr as any).encrypt;
+
+  // Numeric helpers
+  const rawMin = ensureNumber((attr as any).min);
+  const rawMax = ensureNumber((attr as any).max);
+  let min = rawMin;
+  let max = rawMax;
+  if (min !== undefined && max !== undefined && min >= max) {
+    // Swap to satisfy server-side validation
+    const tmp = min;
+    min = Math.min(min, max);
+    max = Math.max(tmp, max);
+    if (min === max) {
+      // If still equal, unset max to avoid error
+      max = undefined;
+    }
+  }
+
+  switch (type) {
+    case "string":
+      return {
+        databaseId: base.databaseId,
+        tableId: base.tableId,
+        key: attr.key,
+        type,
+        size: (attr as any).size ?? 255,
+        required,
+        default: xdefault,
+        array,
+        encrypt: !!encrypt,
+      };
+
+    case "integer":
+      return {
+        databaseId: base.databaseId,
+        tableId: base.tableId,
+        key: attr.key,
+        type,
+        required,
+        default: xdefault,
+        array,
+        min,
+        max,
+      };
+
+    case "double":
+    case "float":
+      return {
+        databaseId: base.databaseId,
+        tableId: base.tableId,
+        key: attr.key,
+        type,
+        required,
+        default: xdefault,
+        array,
+        min,
+        max,
+      };
+
+    case "boolean":
+      return {
+        databaseId: base.databaseId,
+        tableId: base.tableId,
+        key: attr.key,
+        type,
+        required,
+        default: xdefault,
+        array,
+      };
+
+    case "datetime":
+    case "email":
+    case "ip":
+    case "url":
+      return {
+        databaseId: base.databaseId,
+        tableId: base.tableId,
+        key: attr.key,
+        type,
+        required,
+        default: xdefault,
+        array,
+      };
+
+    case "enum":
+      {
+        const elements = (attr as any).elements;
+        if (!Array.isArray(elements) || elements.length === 0) {
+          // Creating an enum without elements is invalid – fail fast with clear messaging
+          throw new Error(
+            `Enum attribute '${(attr as any).key}' requires a non-empty 'elements' array for creation`
+          );
+        }
+      }
+      return {
+        databaseId: base.databaseId,
+        tableId: base.tableId,
+        key: attr.key,
+        type,
+        required,
+        default: xdefault,
+        array,
+        elements: (attr as any).elements,
+      };
+
+    case "relationship": {
+      // Relationship attributes require related collection and metadata
+      return {
+        databaseId: base.databaseId,
+        tableId: base.tableId,
+        key: attr.key,
+        type,
+        relatedCollection: (attr as any).relatedCollection,
+        relationType: (attr as any).relationType,
+        twoWay: (attr as any).twoWay,
+        twoWayKey: (attr as any).twoWayKey,
+        onDelete: (attr as any).onDelete,
+        side: (attr as any).side,
+      } as unknown as CreateAttributeParams;
+    }
+
+    default:
+      return {
+        databaseId: base.databaseId,
+        tableId: base.tableId,
+        key: attr.key,
+        type,
+        required,
+      } as CreateAttributeParams;
+  }
+}
+
+/**
+ * Map a schema Attribute into DatabaseAdapter UpdateAttributeParams
+ * Omits fields that are not explicitly provided, and guards enum updates
+ * so we never send an empty elements array (preserve existing on server).
+ */
+export function mapToUpdateAttributeParams(
+  attr: Attribute,
+  base: { databaseId: string; tableId: string }
+): UpdateAttributeParams {
+  const type = String((attr as any).type || "").toLowerCase();
+  const params: UpdateAttributeParams = {
+    databaseId: base.databaseId,
+    tableId: base.tableId,
+    key: (attr as any).key,
+  };
+
+  const setIfDefined = <K extends keyof UpdateAttributeParams>(
+    key: K,
+    value: UpdateAttributeParams[K]
+  ) => {
+    if (value !== undefined) (params as any)[key] = value;
+  };
+
+  // Common fields
+  setIfDefined("type", type);
+  setIfDefined("required", (attr as any).required);
+  // Only send default if explicitly provided and not on required
+  if (!(attr as any).required && (attr as any).xdefault !== undefined) {
+    setIfDefined("default", (attr as any).xdefault as any);
+  }
+  setIfDefined("array", (attr as any).array);
+  // encrypt only applies to string types
+  if (type === "string") setIfDefined("encrypt", (attr as any).encrypt);
+
+  // Numeric normalization
+  const toNum = (n: any) => (n === null || n === undefined ? undefined : (Number(n)));
+  let min = toNum((attr as any).min);
+  let max = toNum((attr as any).max);
+  if (min !== undefined && max !== undefined && min >= max) {
+    const tmp = min;
+    min = Math.min(min, max);
+    max = Math.max(tmp, max);
+    if (min === max) max = undefined;
+  }
+
+  switch (type) {
+    case "string":
+      setIfDefined("size", (attr as any).size);
+      break;
+    case "integer":
+    case "float":
+    case "double":
+      setIfDefined("min", min);
+      setIfDefined("max", max);
+      break;
+    case "enum": {
+      const elements = (attr as any).elements;
+      if (Array.isArray(elements) && elements.length > 0) {
+        // Only include when non-empty; otherwise preserve existing on server
+        setIfDefined("elements", elements as string[]);
+      }
+      break;
+    }
+    case "relationship": {
+      setIfDefined("relatedCollection", (attr as any).relatedCollection);
+      setIfDefined("relationType", (attr as any).relationType);
+      setIfDefined("twoWay", (attr as any).twoWay);
+      setIfDefined("twoWayKey", (attr as any).twoWayKey);
+      setIfDefined("onDelete", (attr as any).onDelete);
+      break;
+    }
+  }
+
+  return params;
+}

package/src/shared/backupMetadataSchema.ts

@@ -0,0 +1,93 @@
+import { z } from "zod";
+
+/**
+ * Schema for centralized backup tracking table (_appwrite_backups)
+ *
+ * Tracks all backups created for databases, buckets, and comprehensive backups
+ */
+
+export type BackupType = 'database' | 'bucket' | 'comprehensive';
+export type BackupFormat = 'json' | 'zip';
+export type BackupStatus = 'completed' | 'partial' | 'failed';
+export type RestorationStatus = 'completed' | 'partial' | 'failed' | 'not_restored';
+
+export const BACKUP_TYPES = ['database', 'bucket', 'comprehensive'] as const;
+export const BACKUP_FORMATS = ['json', 'zip'] as const;
+export const BACKUP_STATUSES = ['completed', 'partial', 'failed'] as const;
+export const RESTORATION_STATUSES = ['completed', 'partial', 'failed', 'not_restored'] as const;
+
+export const BackupTypeSchema = z.enum(['database', 'bucket', 'comprehensive']);
+export const BackupFormatSchema = z.enum(['json', 'zip']);
+export const BackupStatusSchema = z.enum(['completed', 'partial', 'failed']);
+export const RestorationStatusSchema = z.enum(['completed', 'partial', 'failed', 'not_restored']);
+
+export interface BackupMetadata {
+  $id: string;
+  $createdAt: string;
+  $updatedAt: string;
+
+  // Core backup info
+  backupType: BackupType;         // Type of backup: database, bucket, or comprehensive
+  backupId: string;               // File ID in storage bucket for the backup file
+  manifestFileId?: string;        // File ID for the manifest JSON file
+  format: BackupFormat;           // 'json' or 'zip'
+  sizeBytes: number;              // Total backup file size
+
+  // Resource identification (at least one must be present)
+  databaseId?: string;            // Database ID (for database backups)
+  bucketId?: string;              // Bucket ID (for bucket backups)
+  comprehensiveBackupId?: string; // Parent comprehensive backup ID
+
+  // Database-specific metrics
+  collections?: number;           // Number of collections backed up
+  documents?: number;             // Number of documents backed up
+
+  // Bucket-specific metrics
+  fileCount?: number;             // Number of files backed up (for bucket backups)
+
+  // Status tracking
+  status: BackupStatus;           // 'completed', 'partial', or 'failed'
+  error?: string;                 // Error message if failed or partial
+
+  // Restoration tracking
+  restoredAt?: string;            // ISO timestamp of restoration
+  restorationStatus: RestorationStatus; // Restoration status
+  restorationError?: string;      // Error message if restoration failed
+}
+
+export const BackupMetadataSchema = z.object({
+  $id: z.string(),
+  $createdAt: z.string(),
+  $updatedAt: z.string(),
+
+  // Core backup info
+  backupType: BackupTypeSchema,
+  backupId: z.string(),
+  manifestFileId: z.string().optional(),
+  format: BackupFormatSchema,
+  sizeBytes: z.number(),
+
+  // Resource identification
+  databaseId: z.string().optional(),
+  bucketId: z.string().optional(),
+  comprehensiveBackupId: z.string().optional(),
+
+  // Database-specific metrics
+  collections: z.number().optional(),
+  documents: z.number().optional(),
+
+  // Bucket-specific metrics
+  fileCount: z.number().optional(),
+
+  // Status tracking
+  status: BackupStatusSchema,
+  error: z.string().optional(),
+
+  // Restoration tracking
+  restoredAt: z.string().optional(),
+  restorationStatus: RestorationStatusSchema.default('not_restored'),
+  restorationError: z.string().optional()
+});
+
+export const BACKUP_TABLE_ID = "appwrite_backups";
+export const BACKUP_TABLE_NAME = "Backup Tracking";

package/src/shared/backupTracking.ts

@@ -0,0 +1,211 @@
+import type { DatabaseAdapter } from "../adapters/DatabaseAdapter.js";
+import { logger } from "./logging.js";
+import { tryAwaitWithRetry } from "../utils/helperFunctions.js";
+import { Query, ID } from "node-appwrite";
+import {
+  BACKUP_TABLE_ID,
+  BACKUP_TABLE_NAME,
+  type BackupMetadata,
+  BackupMetadataSchema
+} from "./backupMetadataSchema.js";
+
+/**
+ * Checks if backup tracking table exists in database
+ */
+async function tableExists(
+  db: DatabaseAdapter,
+  databaseId: string
+): Promise<boolean> {
+  try {
+    await db.getTable({ databaseId, tableId: BACKUP_TABLE_ID });
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Creates the backup tracking table in the specified database
+ */
+export async function createBackupTrackingTable(
+  db: DatabaseAdapter,
+  databaseId: string
+): Promise<void> {
+  // Check if table already exists
+  const exists = await tableExists(db, databaseId);
+  if (exists) {
+    logger.debug("Backup tracking table already exists", {
+      databaseId,
+      tableId: BACKUP_TABLE_ID
+    });
+    return;
+  }
+
+  logger.info("Creating backup tracking table", {
+    databaseId,
+    tableId: BACKUP_TABLE_ID
+  });
+
+  // Create table
+  await tryAwaitWithRetry(async () => {
+    await db.createTable({
+      databaseId,
+      id: BACKUP_TABLE_ID,
+      name: BACKUP_TABLE_NAME
+    });
+  });
+
+  // Create attributes
+  const attributes = [
+    {
+      key: "backupId",
+      type: "string" as const,
+      size: 50,
+      required: true
+    },
+    {
+      key: "databaseId",
+      type: "string" as const,
+      size: 50,
+      required: true
+    },
+    {
+      key: "sizeBytes",
+      type: "integer" as const,
+      required: true
+    },
+    {
+      key: "collections",
+      type: "integer" as const,
+      required: true
+    },
+    {
+      key: "documents",
+      type: "integer" as const,
+      required: true
+    },
+    {
+      key: "format",
+      type: "enum" as const,
+      elements: ["json", "zip"],
+      required: true
+    },
+    {
+      key: "status",
+      type: "enum" as const,
+      elements: ["completed", "failed"],
+      required: true
+    },
+    {
+      key: "error",
+      type: "string" as const,
+      size: 10000,
+      required: false
+    }
+  ];
+
+  for (const attr of attributes) {
+    await tryAwaitWithRetry(async () => {
+      await db.createAttribute({
+        databaseId,
+        tableId: BACKUP_TABLE_ID,
+        ...attr
+      });
+    });
+  }
+
+  logger.info("Backup tracking table created successfully", {
+    databaseId,
+    tableId: BACKUP_TABLE_ID
+  });
+}
+
+/**
+ * Records backup metadata in the tracking table
+ */
+export async function recordBackup(
+  db: DatabaseAdapter,
+  databaseId: string,
+  metadata: Omit<BackupMetadata, '$id' | '$createdAt' | '$updatedAt'>
+): Promise<BackupMetadata> {
+  // Ensure tracking table exists
+  await createBackupTrackingTable(db, databaseId);
+
+  // Create backup record
+  const result = await db.createRow({
+    databaseId,
+    tableId: BACKUP_TABLE_ID,
+    id: ID.unique(),
+    data: {
+      backupId: metadata.backupId,
+      databaseId: metadata.databaseId,
+      sizeBytes: metadata.sizeBytes,
+      collections: metadata.collections,
+      documents: metadata.documents,
+      format: metadata.format,
+      status: metadata.status,
+      error: metadata.error
+    }
+  });
+
+  logger.info("Recorded backup metadata", {
+    backupId: metadata.backupId,
+    databaseId: metadata.databaseId,
+    format: metadata.format
+  });
+
+  return result.data as BackupMetadata;
+}
+
+/**
+ * Lists all backups for a database, sorted by creation date (newest first)
+ */
+export async function listBackups(
+  db: DatabaseAdapter,
+  databaseId: string
+): Promise<BackupMetadata[]> {
+  try {
+    const result = await db.listRows({
+      databaseId,
+      tableId: BACKUP_TABLE_ID,
+      queries: [
+        Query.orderDesc("$createdAt"),
+        Query.limit(100) // Limit to last 100 backups
+      ]
+    });
+
+    return (result.rows || []) as BackupMetadata[];
+  } catch (error) {
+    // Table might not exist yet
+    logger.debug("No backup tracking table found", { databaseId });
+    return [];
+  }
+}
+
+/**
+ * Gets the most recent backup for a database
+ */
+export async function getLastBackup(
+  db: DatabaseAdapter,
+  databaseId: string
+): Promise<BackupMetadata | null> {
+  try {
+    const result = await db.listRows({
+      databaseId,
+      tableId: BACKUP_TABLE_ID,
+      queries: [
+        Query.orderDesc("$createdAt"),
+        Query.limit(1)
+      ]
+    });
+
+    if (result.rows && result.rows.length > 0) {
+      return result.rows[0] as BackupMetadata;
+    }
+
+    return null;
+  } catch (error) {
+    logger.debug("No backup found or table doesn't exist", { databaseId });
+    return null;
+  }
+}