crowd-funder-for-time-pwa/src/services/PlatformService.ts

/**
 * Represents the result of an image capture or selection operation.
 * Contains both the image data as a Blob and the associated filename.
 */
export interface ImageResult {
  /** The image data as a Blob object */
  blob: Blob;
  /** The filename associated with the image */
  fileName: string;
}

/**
 * Platform-agnostic interface for handling platform-specific operations.
 * Provides a common API for file system operations, camera interactions,
 * platform detection, and deep linking across different platforms
 * (web, mobile, desktop).
 */
export interface PlatformService {
  // File system operations
  /**
   * Reads the contents of a file at the specified path.
   * @param path - The path to the file to read
   * @returns Promise resolving to the file contents as a string
   */
  readFile(path: string): Promise<string>;

  /**
   * Writes content to a file at the specified path.
   * @param path - The path where the file should be written
   * @param content - The content to write to the file
   * @returns Promise that resolves when the write is complete
   */
  writeFile(path: string, content: string): Promise<void>;

  /**
   * Deletes a file at the specified path.
   * @param path - The path to the file to delete
   * @returns Promise that resolves when the deletion is complete
   */
  deleteFile(path: string): Promise<void>;

  /**
   * Lists all files in the specified directory.
   * @param directory - The directory path to list
   * @returns Promise resolving to an array of filenames
   */
  listFiles(directory: string): Promise<string[]>;

  /**
   * Exports a database blob to a file, handling platform-specific save operations.
   * @param blob - The database blob to export
   * @param fileName - The name of the file to save
   * @returns Promise that resolves when the export is complete
   * @throws Error if export fails
   */
  exportDatabase(blob: Blob, fileName: string): Promise<void>;

  // Camera operations
  /**
   * Activates the device camera to take a picture.
   * @returns Promise resolving to the captured image result
   */
  takePicture(): Promise<ImageResult>;

  /**
   * Opens a file picker to select an existing image.
   * @returns Promise resolving to the selected image result
   */
  pickImage(): Promise<ImageResult>;

  // Platform specific features
  /**
   * Checks if the current platform is Capacitor (mobile).
   * @returns true if running on Capacitor
   */
  isCapacitor(): boolean;

  /**
   * Checks if the current platform is Electron (desktop).
   * @returns true if running on Electron
   */
  isElectron(): boolean;

  /**
   * Checks if the current platform is PyWebView.
   * @returns true if running on PyWebView
   */
  isPyWebView(): boolean;

  /**
   * Checks if the current platform is web browser.
   * @returns true if running in a web browser
   */
  isWeb(): boolean;

  // Deep linking
  /**
   * Handles deep link URLs for the application.
   * @param url - The deep link URL to handle
   * @returns Promise that resolves when the deep link has been handled
   */
  handleDeepLink(url: string): Promise<void>;

  /**
   * Gets platform-specific instructions for saving exported files
   * @returns Array of instruction strings for the current platform
   */
  getExportInstructions(): string[];

  /**
   * Gets the success message for database export
   * @returns Success message appropriate for the current platform
   */
  getExportSuccessMessage(): string;

  /**
   * Checks if the platform requires a secondary download link
   * @returns true if platform needs a secondary download link
   */
  needsSecondaryDownloadLink(): boolean;

  /**
   * Checks if the platform needs cleanup after download
   * @returns true if platform needs cleanup after download
   */
  needsDownloadCleanup(): boolean;
}