/**
 * 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 capabilities interface defining what features are available
 * on the current platform implementation
 */
export interface PlatformCapabilities {
  /** Whether the platform supports native file system access */
  hasFileSystem: boolean;
  /** Whether the platform supports native camera access */
  hasCamera: boolean;
  /** Whether the platform is a mobile device */
  isMobile: boolean;
  /** Whether the platform is iOS specifically */
  isIOS: boolean;
  /** Whether the platform supports native file download */
  hasFileDownload: boolean;
  /** Whether the platform requires special file handling instructions */
  needsFileHandlingInstructions: boolean;
}

/**
 * Platform-agnostic interface for handling platform-specific operations.
 * Provides a common API for file system operations, camera interactions,
 * and platform detection across different platforms (web, mobile, desktop).
 */
export interface PlatformService {
  // Platform capabilities
  /**
   * Gets the current platform's capabilities
   * @returns Object describing what features are available on this platform
   */
  getCapabilities(): PlatformCapabilities;

  // 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>;

  /**
   * Writes content to a file at the specified path and shares it.
   * @param fileName - The filename of the file to write
   * @param content - The content to write to the file
   * @returns Promise that resolves when the write is complete
   */
  writeAndShareFile(fileName: 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[]>;

  // 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>;

  /**
   * 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>;
}