forked from trent_larson/crowd-funder-for-time-pwa
7b681db3e8
Add detailed TypeScript JSDoc documentation to core service modules: - api.ts: Document error handling utilities and platform-specific logging - plan.ts: Document plan/claim loading with retry mechanism - deepLinks.ts: Document URL parsing and routing functionality - Platform services: - CapacitorPlatformService: Document mobile platform capabilities - ElectronPlatformService: Document desktop placeholder implementation - PyWebViewPlatformService: Document Python bridge placeholder - WebPlatformService: Document web platform limitations and features Key improvements: - Add detailed @remarks sections explaining implementation details - Include usage examples with TypeScript code snippets - Document error handling and platform-specific behaviors - Add @todo tags for unimplemented features - Fix PlanResponse interface to include headers property This documentation enhances code maintainability and developer experience by providing clear guidance on service layer functionality and usage.
95 lines
2.7 KiB
TypeScript
95 lines
2.7 KiB
TypeScript
/**
|
|
* 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[]>;
|
|
|
|
// 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>;
|
|
}
|