@smartsamurai/krapi-sdk/src/services/backup/backup-backend.interface.ts

KRAPI TypeScript SDK - Easy-to-use client SDK for connecting to self-hosted KRAPI servers (like Appwrite SDK)

/**
 * Backup Backend Interface
 * 
 * Defines the interface for backup backend implementations.
 * This allows the SDK to work with different backup backends (file-based, Restic, etc.)
 * 
 * @module services/backup/backup-backend.interface
 */

/**
 * Backup snapshot information
 */
export interface BackupSnapshot {
  /** Short snapshot ID */
  id: string;
  /** Full snapshot ID (e.g., Restic snapshot ID) */
  snapshot_id: string;
  /** Backup type */
  type: "project" | "system";
  /** Project ID (for project backups) */
  project_id?: string;
  /** ISO timestamp */
  created_at: string;
  /** Total size in bytes */
  size: number;
  /** Unique data size after deduplication */
  unique_size?: number;
  /** Whether backup is encrypted */
  encrypted: boolean;
  /** Backup version */
  version: string;
  /** Backup description */
  description?: string;
  /** Backup tags */
  tags?: string[];
  /** Number of files in backup */
  file_count?: number;
}

/**
 * Backup statistics
 */
export interface BackupStats {
  /** Total size in bytes */
  total_size: number;
  /** Unique data size after deduplication */
  unique_size: number;
  /** Number of files */
  file_count: number;
  /** Compression ratio (if applicable) */
  compression_ratio?: number;
}

/**
 * Backup Backend Interface
 * 
 * Implementations of this interface handle the actual backup storage and retrieval.
 * The SDK's BackupService uses this interface to perform backup operations.
 */
export interface BackupBackend {
  /**
   * Initialize backup repository
   * 
   * @param password - Repository password
   * @returns Promise that resolves when repository is initialized
   */
  initializeRepository(password: string): Promise<void>;

  /**
   * Create system backup (all databases + files)
   * 
   * @param options - Backup options
   * @param options.description - Backup description
   * @param options.password - Backup password
   * @param options.tags - Backup tags
   * @returns Promise resolving to backup snapshot
   */
  createSystemBackup(options: {
    description?: string;
    password: string;
    tags?: string[];
  }): Promise<BackupSnapshot>;

  /**
   * Create project backup
   * 
   * @param projectId - Project ID
   * @param options - Backup options
   * @param options.description - Backup description
   * @param options.password - Backup password
   * @param options.includeFiles - Whether to include files
   * @param options.tags - Backup tags
   * @returns Promise resolving to backup snapshot
   */
  createProjectBackup(
    projectId: string,
    options: {
      description?: string;
      password: string;
      includeFiles?: boolean;
      tags?: string[];
    }
  ): Promise<BackupSnapshot>;

  /**
   * List backups
   * 
   * @param password - Repository password
   * @param options - List options
   * @param options.projectId - Filter by project ID
   * @param options.type - Filter by backup type
   * @param options.limit - Maximum number of backups to return
   * @returns Promise resolving to array of backup snapshots
   */
  listBackups(
    password: string,
    options?: {
      projectId?: string;
      type?: "project" | "system";
      limit?: number;
    }
  ): Promise<BackupSnapshot[]>;

  /**
   * Restore backup
   * 
   * @param snapshotId - Snapshot ID to restore
   * @param password - Repository password
   * @param targetPath - Target path for restoration
   * @param options - Restore options
   * @param options.include - Paths to include (if applicable)
   * @param options.exclude - Paths to exclude (if applicable)
   * @returns Promise that resolves when restoration is complete
   */
  restoreBackup(
    snapshotId: string,
    password: string,
    targetPath: string,
    options?: {
      include?: string[];
      exclude?: string[];
    }
  ): Promise<void>;

  /**
   * Delete backup
   * 
   * @param snapshotId - Snapshot ID to delete
   * @param password - Repository password
   * @returns Promise that resolves when backup is deleted
   */
  deleteBackup(snapshotId: string, password: string): Promise<void>;

  /**
   * Get backup statistics
   * 
   * @param snapshotId - Snapshot ID
   * @param password - Repository password
   * @returns Promise resolving to backup statistics
   */
  getBackupStats(
    snapshotId: string,
    password: string
  ): Promise<BackupStats>;
}