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

import { QueryExecResult, DatabaseExecResult } from "@/interfaces/database";

/**
 * 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;
  /** Whether the platform is a native app (Capacitor, Electron, etc.) */
  isNativeApp: 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;

  // Platform detection methods
  /**
   * Checks if running on Capacitor platform.
   * @returns true if running on Capacitor, false otherwise
   */
  isCapacitor(): boolean;

  /**
   * Checks if running on Electron platform.
   * @returns true if running on Electron, false otherwise
   */
  isElectron(): boolean;

  /**
   * Checks if running on web platform.
   * @returns true if running on web, false otherwise
   */
  isWeb(): boolean;

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

  /**
   * Rotates the camera between front and back cameras.
   * @returns Promise that resolves when the camera is rotated
   */
  rotateCamera(): Promise<void>;

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

  /**
   * Executes a SQL query on the database.
   * @param sql - The SQL query to execute
   * @param params - The parameters to pass to the query
   * @returns Promise resolving to the query result
   */
  dbQuery(
    sql: string,
    params?: unknown[],
  ): Promise<QueryExecResult | undefined>;

  /**
   * Executes a create/update/delete on the database.
   * @param sql - The SQL statement to execute
   * @param params - The parameters to pass to the statement
   * @returns Promise resolving to the result of the statement
   */
  dbExec(sql: string, params?: unknown[]): Promise<DatabaseExecResult>;

  /**
   * Executes a SQL query and returns the first row as an array.
   * @param sql - The SQL query to execute
   * @param params - The parameters to pass to the query
   * @returns Promise resolving to the first row as an array, or undefined if no results
   */
  dbGetOneRow(sql: string, params?: unknown[]): Promise<unknown[] | undefined>;

  // Database utility methods
  /**
   * Generates an INSERT SQL statement for a given model and table.
   * @param model - The model object containing the data to insert
   * @param tableName - The name of the table to insert into
   * @returns Object containing the SQL statement and parameters
   */
  generateInsertStatement(
    model: Record<string, unknown>,
    tableName: string,
  ): { sql: string; params: unknown[] };

  /**
   * Updates default settings in the database.
   * @param settings - The settings object to update
   * @returns Promise that resolves when the update is complete
   */
  updateDefaultSettings(settings: Record<string, unknown>): Promise<void>;

  /**
   * Inserts DID-specific settings into the database.
   * @param did - The DID to associate with the settings
   * @returns Promise that resolves when the insertion is complete
   */
  insertDidSpecificSettings(did: string): Promise<void>;

  /**
   * Updates DID-specific settings in the database.
   * @param did - The DID to update settings for
   * @param settings - The settings object to update
   * @returns Promise that resolves when the update is complete
   */
  updateDidSpecificSettings(
    did: string,
    settings: Record<string, unknown>,
  ): Promise<void>;

  /**
   * Retrieves settings for the active account.
   * @returns Promise resolving to the settings object
   */
  retrieveSettingsForActiveAccount(): Promise<Record<string, unknown> | null>;

  // --- PWA/Web-only methods (optional, only implemented on web) ---
  /**
   * Registers the service worker for PWA support (web only)
   */
  registerServiceWorker?(): void;

  /**
   * Returns true if PWA is enabled (web only)
   */
  readonly isPWAEnabled?: boolean;
}