react-native-cloud-storage 2.2.1 → 2.3.0

package/src/{google-drive → storages/google-drive}/index.ts

@@ -1,18 +1,18 @@
-import type NativeproviderService from '../types/native';
 import {
-  CloudStorageErrorCode,
-  type NativeRNCloudCloudStorageFileStat,
-  type NativeRNCloudCloudStorageScope,
-} from '../types/native';
-import CloudStorageError from '../utils/CloudStorageError';
+  NativeCloudStorageErrorCode,
+  NativeStorage,
+  type NativeStorageFileStat,
+  type NativeStorageScope,
+} from '../../types/native';
+import CloudStorageError from '../../utils/cloud-storage-error';
 import { MimeTypes, type GoogleDriveFile, type GoogleDriveFileSpace } from './types';
 import GoogleDriveApiClient, { GoogleDriveHttpError } from './client';
-import { type CloudStorageProviderOptions, type DeepRequired } from '../types/main';
+import { type CloudStorageProviderOptions, type DeepRequired } from '../../types/main';
 
 /**
- * A proxy class that wraps the Google Drive API client implementation to match the native iOS interface.
+ * A JavaScript-based implementation of the Google Drive API that implements the cloud storage interface.
  */
-export default class GoogleDrive implements NativeproviderService {
+export default class GoogleDrive implements NativeStorage {
   private drive: GoogleDriveApiClient;
   private options: DeepRequired<CloudStorageProviderOptions['googledrive']>;
 
@@ -22,19 +22,19 @@ export default class GoogleDrive implements NativeproviderService {
 
     return new Proxy(this, {
       // before calling any function, check if the access token is set
-      get(target: GoogleDrive, prop: keyof GoogleDrive) {
+      get(target: GoogleDrive, property: keyof GoogleDrive) {
         const allowedFunctions = ['isCloudAvailable'];
-        if (typeof target[prop] === 'function' && !allowedFunctions.includes(prop.toString())) {
+        if (typeof target[property] === 'function' && !allowedFunctions.includes(property.toString())) {
           const { accessToken } = options;
           if (!accessToken?.length) {
             throw new CloudStorageError(
-              `Google Drive access token is not set, cannot call function ${prop.toString()}`,
-              CloudStorageErrorCode.ACCESS_TOKEN_MISSING
+              `Google Drive access token is not set, cannot call function ${property.toString()}`,
+              NativeCloudStorageErrorCode.ACCESS_TOKEN_MISSING
             );
           }
         }
 
-        return target[prop];
+        return target[property];
       },
     });
   }
@@ -44,12 +44,14 @@ export default class GoogleDrive implements NativeproviderService {
     return !!accessToken?.length;
   };
 
-  private getRootDirectory(scope: NativeRNCloudCloudStorageScope): GoogleDriveFileSpace {
+  private getRootDirectory(scope: NativeStorageScope): GoogleDriveFileSpace {
     switch (scope) {
-      case 'documents':
+      case 'documents': {
         return 'drive';
-      case 'app_data':
+      }
+      case 'app_data': {
         return 'appDataFolder';
+      }
     }
   }
 
@@ -75,7 +77,7 @@ export default class GoogleDrive implements NativeproviderService {
       the files array - if it does not, it means that the directory is a child of the root directory and the one we're
       looking for */
       for (const possibleTopDirectory of possibleTopDirectories) {
-        if (!files.find((f) => f.id === possibleTopDirectory!.parents![0] && f.mimeType === MimeTypes.FOLDER)) {
+        if (!files.some((f) => f.id === possibleTopDirectory!.parents![0] && f.mimeType === MimeTypes.FOLDER)) {
           topDirectoryId = possibleTopDirectory!.id;
           break;
         }
@@ -85,24 +87,24 @@ export default class GoogleDrive implements NativeproviderService {
     if (!topDirectoryId) {
       throw new CloudStorageError(
         `Could not find top directory with name ${directoryTree[0]}`,
-        CloudStorageErrorCode.DIRECTORY_NOT_FOUND
+        NativeCloudStorageErrorCode.DIRECTORY_NOT_FOUND
       );
     }
 
     // now, we traverse the directories array and get the id of the last directory from the files array
     let currentDirectoryId = topDirectoryId;
-    for (let i = 1; i < directoryTree.length; i++) {
+    for (let index = 1; index < directoryTree.length; index++) {
       const currentDirectory = files.find((f) => f.id === currentDirectoryId);
       if (!currentDirectory)
         throw new CloudStorageError(
           `Could not find directory with id ${currentDirectoryId}`,
-          CloudStorageErrorCode.DIRECTORY_NOT_FOUND
+          NativeCloudStorageErrorCode.DIRECTORY_NOT_FOUND
         );
-      const nextDirectory = files.find((f) => f.name === directoryTree[i] && f.parents![0] === currentDirectoryId);
+      const nextDirectory = files.find((f) => f.name === directoryTree[index] && f.parents![0] === currentDirectoryId);
       if (!nextDirectory)
         throw new CloudStorageError(
-          `Could not find directory with name ${directoryTree[i]}`,
-          CloudStorageErrorCode.DIRECTORY_NOT_FOUND
+          `Could not find directory with name ${directoryTree[index]}`,
+          NativeCloudStorageErrorCode.DIRECTORY_NOT_FOUND
         );
       currentDirectoryId = nextDirectory.id;
     }
@@ -115,10 +117,10 @@ export default class GoogleDrive implements NativeproviderService {
    * @param scope The scope to get the root directory for.
    * @returns A promise that resolves to the ID of the root directory or null if it could not be found.
    */
-  private async getRootDirectoryId(scope: NativeRNCloudCloudStorageScope): Promise<string | null> {
+  private async getRootDirectoryId(scope: NativeStorageScope): Promise<string | null> {
     const files = await this.drive.listFiles(this.getRootDirectory(scope));
     for (const file of files) {
-      if (!files.find((f) => f.id === file.parents![0])) return file.parents![0] ?? null;
+      if (!files.some((f) => f.id === file.parents![0])) return file.parents![0] ?? null;
     }
 
     return null;
@@ -132,26 +134,23 @@ export default class GoogleDrive implements NativeproviderService {
   ) {
     const { strictFilenames } = this.options;
 
-    let possibleFiles: GoogleDriveFile[];
-    if (parentDirectoryId) {
-      possibleFiles = files.filter((f) => f.name === filename && f.parents![0] === parentDirectoryId);
-    } else {
-      possibleFiles = files.filter((f) => f.name === filename && !files.find((f2) => f2.id === f.parents![0]));
-    }
+    const possibleFiles: GoogleDriveFile[] = parentDirectoryId
+      ? files.filter((f) => f.name === filename && f.parents![0] === parentDirectoryId)
+      : files.filter((f) => f.name === filename && !files.some((f2) => f2.id === f.parents![0]));
 
     if (possibleFiles.length <= 1) return;
 
     if (strictFilenames) {
       throw new CloudStorageError(
         `Multiple files with the same name found at path ${path}: ${possibleFiles.map((f) => f.id).join(', ')}`,
-        CloudStorageErrorCode.MULTIPLE_FILES_SAME_NAME
+        NativeCloudStorageErrorCode.MULTIPLE_FILES_SAME_NAME
       );
     }
   }
 
   private async getFileId(
     path: string,
-    scope: NativeRNCloudCloudStorageScope,
+    scope: NativeStorageScope,
     throwIf: 'directory' | 'file' | false = false
   ): Promise<string> {
     try {
@@ -162,7 +161,7 @@ export default class GoogleDrive implements NativeproviderService {
         if (!rootDirectoryId)
           throw new CloudStorageError(
             `Root directory in scope ${scope} not found`,
-            CloudStorageErrorCode.DIRECTORY_NOT_FOUND
+            NativeCloudStorageErrorCode.DIRECTORY_NOT_FOUND
           );
         return rootDirectoryId;
       }
@@ -174,59 +173,63 @@ export default class GoogleDrive implements NativeproviderService {
         this.checkIfMultipleFilesWithSameName(path, files, filename, null);
         /* when the file is supposed to be in the root directory, we need to get the file where the name is the filename
         and the first parent has an id which does not exist in the files array */
-        file = files.find((f) => f.name === filename && !files.find((f2) => f2.id === f.parents![0]));
+        file = files.find((f) => f.name === filename && !files.some((f2) => f2.id === f.parents![0]));
       } else {
         this.checkIfMultipleFilesWithSameName(path, files, filename, parentDirectoryId);
         file = files.find((f) => f.name === filename && f.parents![0] === parentDirectoryId);
       }
-      if (!file) throw new CloudStorageError(`File not found`, CloudStorageErrorCode.FILE_NOT_FOUND);
+      if (!file) throw new CloudStorageError(`File not found`, NativeCloudStorageErrorCode.FILE_NOT_FOUND);
       if (file.mimeType === MimeTypes.FOLDER && throwIf === 'directory') {
-        throw new CloudStorageError(`Path ${path} is a directory`, CloudStorageErrorCode.PATH_IS_DIRECTORY);
+        throw new CloudStorageError(`Path ${path} is a directory`, NativeCloudStorageErrorCode.PATH_IS_DIRECTORY);
       } else if (file.mimeType !== MimeTypes.FOLDER && throwIf === 'file') {
-        throw new CloudStorageError(`Path ${path} is a file`, CloudStorageErrorCode.FILE_NOT_FOUND);
+        throw new CloudStorageError(`Path ${path} is a file`, NativeCloudStorageErrorCode.FILE_NOT_FOUND);
       }
       return file.id;
-    } catch (e: unknown) {
-      if (e instanceof GoogleDriveHttpError && e.json?.error?.status === 'UNAUTHENTICATED') {
+    } catch (error: unknown) {
+      if (error instanceof GoogleDriveHttpError && error.json?.error?.status === 'UNAUTHENTICATED') {
         throw new CloudStorageError(
           `Could not authenticate with Google Drive`,
-          CloudStorageErrorCode.AUTHENTICATION_FAILED,
-          e.json
+          NativeCloudStorageErrorCode.AUTHENTICATION_FAILED,
+          error.json
         );
       } else {
-        if (e instanceof CloudStorageError) throw e;
-        throw new CloudStorageError(`Could not get file id for path ${path}`, CloudStorageErrorCode.UNKNOWN, e);
+        if (error instanceof CloudStorageError) throw error;
+        throw new CloudStorageError(
+          `Could not get file id for path ${path}`,
+          NativeCloudStorageErrorCode.UNKNOWN,
+          error
+        );
       }
     }
   }
 
-  async fileExists(path: string, scope: NativeRNCloudCloudStorageScope): Promise<boolean> {
+  async fileExists(path: string, scope: NativeStorageScope): Promise<boolean> {
     try {
       await this.getFileId(path, scope);
       return true;
-    } catch (e: any) {
-      if (e instanceof CloudStorageError && e.code === CloudStorageErrorCode.FILE_NOT_FOUND) return false;
-      else throw e;
+    } catch (error: unknown) {
+      if (error instanceof CloudStorageError && error.code === NativeCloudStorageErrorCode.FILE_NOT_FOUND) return false;
+      else throw error;
     }
   }
 
-  async appendToFile(path: string, data: string, scope: NativeRNCloudCloudStorageScope): Promise<void> {
+  async appendToFile(path: string, data: string, scope: NativeStorageScope): Promise<void> {
     let fileId: string | undefined;
-    let prevContent = '';
+    let previousContent = '';
     try {
       fileId = await this.getFileId(path, scope);
-      prevContent = await this.drive.getFileText(fileId);
-    } catch (e: any) {
-      if (e instanceof CloudStorageError && e.code === CloudStorageErrorCode.FILE_NOT_FOUND) {
+      previousContent = await this.drive.getFileText(fileId);
+    } catch (error: unknown) {
+      if (error instanceof CloudStorageError && error.code === NativeCloudStorageErrorCode.FILE_NOT_FOUND) {
         /* do nothing, simply create the file */
       } else {
-        throw e;
+        throw error;
       }
     }
 
     if (fileId) {
       await this.drive.updateFile(fileId, {
-        body: prevContent + data,
+        body: previousContent + data,
         mimeType: MimeTypes.TEXT,
       });
     } else {
@@ -250,32 +253,27 @@ export default class GoogleDrive implements NativeproviderService {
     }
   }
 
-  async createFile(
-    path: string,
-    data: string,
-    scope: NativeRNCloudCloudStorageScope,
-    overwrite: boolean
-  ): Promise<void> {
+  async createFile(path: string, data: string, scope: NativeStorageScope, overwrite: boolean): Promise<void> {
     let fileId: string | undefined;
     if (overwrite) {
       try {
         fileId = await this.getFileId(path, scope);
-      } catch (e: any) {
-        if (e instanceof CloudStorageError && e.code === CloudStorageErrorCode.FILE_NOT_FOUND) {
+      } catch (error: unknown) {
+        if (error instanceof CloudStorageError && error.code === NativeCloudStorageErrorCode.FILE_NOT_FOUND) {
           /* do nothing, simply create the file */
         } else {
-          throw e;
+          throw error;
         }
       }
     } else {
       try {
         await this.getFileId(path, scope);
-        throw new CloudStorageError(`File ${path} already exists`, CloudStorageErrorCode.FILE_ALREADY_EXISTS);
-      } catch (e: any) {
-        if (e instanceof CloudStorageError && e.code === CloudStorageErrorCode.FILE_NOT_FOUND) {
+        throw new CloudStorageError(`File ${path} already exists`, NativeCloudStorageErrorCode.FILE_ALREADY_EXISTS);
+      } catch (error: unknown) {
+        if (error instanceof CloudStorageError && error.code === NativeCloudStorageErrorCode.FILE_NOT_FOUND) {
           /* do nothing, simply create the file */
         } else {
-          throw e;
+          throw error;
         }
       }
     }
@@ -306,30 +304,33 @@ export default class GoogleDrive implements NativeproviderService {
     }
   }
 
-  async listFiles(path: string, scope: NativeRNCloudCloudStorageScope): Promise<string[]> {
+  async listFiles(path: string, scope: NativeStorageScope): Promise<string[]> {
     const allFiles = await this.drive.listFiles(this.getRootDirectory(scope));
-    if (path !== '') {
+    if (path === '') {
+      const rootDirectoryId = await this.getRootDirectoryId(scope);
+      return [...new Set(allFiles.filter((f) => (f.parents ?? [])[0] === rootDirectoryId).map((f) => f.name))];
+    } else {
       const fileId = await this.getFileId(path, scope);
       const files = allFiles.filter((f) => (f.parents ?? [])[0] === fileId);
 
-      return Array.from(new Set(files.map((f) => f.name)));
-    } else {
-      const rootDirectoryId = await this.getRootDirectoryId(scope);
-      return Array.from(new Set(allFiles.filter((f) => (f.parents ?? [])[0] === rootDirectoryId).map((f) => f.name)));
+      return [...new Set(files.map((f) => f.name))];
     }
   }
 
-  async createDirectory(path: string, scope: NativeRNCloudCloudStorageScope): Promise<void> {
+  async createDirectory(path: string, scope: NativeStorageScope): Promise<void> {
     try {
       await this.getFileId(path, scope);
-      throw new CloudStorageError(`File ${path} already exists`, CloudStorageErrorCode.FILE_ALREADY_EXISTS);
-    } catch (e: any) {
-      if (e instanceof CloudStorageError && e.code === CloudStorageErrorCode.FILE_NOT_FOUND) {
+      throw new CloudStorageError(`File ${path} already exists`, NativeCloudStorageErrorCode.FILE_ALREADY_EXISTS);
+    } catch (error: unknown) {
+      if (error instanceof CloudStorageError && error.code === NativeCloudStorageErrorCode.FILE_NOT_FOUND) {
         /* do nothing, simply create the file */
-      } else if (e instanceof CloudStorageError && e.code === CloudStorageErrorCode.PATH_IS_DIRECTORY) {
-        throw new CloudStorageError(`Directory ${path} already exists`, CloudStorageErrorCode.FILE_ALREADY_EXISTS);
+      } else if (error instanceof CloudStorageError && error.code === NativeCloudStorageErrorCode.PATH_IS_DIRECTORY) {
+        throw new CloudStorageError(
+          `Directory ${path} already exists`,
+          NativeCloudStorageErrorCode.FILE_ALREADY_EXISTS
+        );
       } else {
-        throw e;
+        throw error;
       }
     }
 
@@ -347,24 +348,24 @@ export default class GoogleDrive implements NativeproviderService {
     });
   }
 
-  async readFile(path: string, scope: NativeRNCloudCloudStorageScope): Promise<string> {
+  async readFile(path: string, scope: NativeStorageScope): Promise<string> {
     const fileId = await this.getFileId(path, scope);
     const content = await this.drive.getFileText(fileId);
     return content;
   }
 
-  async downloadFile(_path: string, _scope: NativeRNCloudCloudStorageScope): Promise<void> {
-    // Downloading files from Google Drive is not necessary / possible, as they need to be downloaded on every read operation via the API anyway
+  async triggerSync(_path: string, _scope: NativeStorageScope): Promise<void> {
+    // Triggering file synchronization in Google Drive is not necessary / possible, as they need to be downloaded on every read operation via the API anyway
     return;
   }
 
-  async deleteFile(path: string, scope: NativeRNCloudCloudStorageScope): Promise<void> {
+  async deleteFile(path: string, scope: NativeStorageScope): Promise<void> {
     // if trying to pass a directory, throw an error
     const fileId = await this.getFileId(path, scope, 'directory');
     await this.drive.deleteFile(fileId);
   }
 
-  async deleteDirectory(path: string, recursive: boolean, scope: NativeRNCloudCloudStorageScope): Promise<void> {
+  async deleteDirectory(path: string, recursive: boolean, scope: NativeStorageScope): Promise<void> {
     // if trying to pass a file, throw an error
     const fileId = await this.getFileId(path, scope, 'file');
 
@@ -375,7 +376,7 @@ export default class GoogleDrive implements NativeproviderService {
       if (filesInDirectory.length > 0) {
         throw new CloudStorageError(
           `Directory ${path} is not empty`,
-          CloudStorageErrorCode.DELETE_ERROR,
+          NativeCloudStorageErrorCode.DELETE_ERROR,
           filesInDirectory
         );
       }
@@ -384,7 +385,7 @@ export default class GoogleDrive implements NativeproviderService {
     await this.drive.deleteFile(fileId);
   }
 
-  async statFile(path: string, scope: NativeRNCloudCloudStorageScope): Promise<NativeRNCloudCloudStorageFileStat> {
+  async statFile(path: string, scope: NativeStorageScope): Promise<NativeStorageFileStat> {
     const fileId = await this.getFileId(path, scope, false);
     const file = await this.drive.getFile(fileId!);
 
@@ -396,4 +397,86 @@ export default class GoogleDrive implements NativeproviderService {
       isFile: file.mimeType !== MimeTypes.FOLDER,
     };
   }
+
+  async downloadFile(remotePath: string, localPath: string, scope: NativeStorageScope): Promise<void> {
+    const fileId = await this.getFileId(remotePath, scope, 'directory');
+
+    try {
+      await this.drive.downloadFile(fileId, localPath);
+    } catch (error: unknown) {
+      if (error instanceof CloudStorageError) throw error;
+
+      throw new CloudStorageError(
+        `Could not download file ${remotePath} to ${localPath}`,
+        NativeCloudStorageErrorCode.UNKNOWN,
+        error
+      );
+    }
+  }
+
+  async uploadFile(
+    remotePath: string,
+    localPath: string,
+    mimeType: string,
+    scope: NativeStorageScope,
+    overwrite: boolean
+  ): Promise<void> {
+    let fileId: string | undefined;
+
+    if (overwrite) {
+      try {
+        fileId = await this.getFileId(remotePath, scope);
+      } catch (error: unknown) {
+        if (error instanceof CloudStorageError && error.code === NativeCloudStorageErrorCode.FILE_NOT_FOUND) {
+          /* File doesn't exist -> we'll create it below */
+        } else {
+          throw error;
+        }
+      }
+    } else {
+      try {
+        await this.getFileId(remotePath, scope);
+        throw new CloudStorageError(
+          `File ${remotePath} already exists`,
+          NativeCloudStorageErrorCode.FILE_ALREADY_EXISTS
+        );
+      } catch (error: unknown) {
+        if (error instanceof CloudStorageError && error.code === NativeCloudStorageErrorCode.FILE_NOT_FOUND) {
+          /* not found -> ok, we'll create */
+        } else if (error instanceof CloudStorageError) {
+          throw error;
+        } else {
+          throw error;
+        }
+      }
+    }
+
+    if (fileId) {
+      // Overwrite existing file
+      await this.drive.updateFile(fileId, {
+        mimeType,
+        localPath,
+      });
+    } else {
+      // Need to create a new file first
+      const files = await this.drive.listFiles(this.getRootDirectory(scope));
+      const { directories, filename } = this.resolvePathToDirectories(remotePath);
+      const parentDirectoryId = this.findParentDirectoryId(files, directories);
+
+      await this.drive.createFile(
+        {
+          name: filename,
+          parents: parentDirectoryId
+            ? [parentDirectoryId]
+            : scope === 'app_data'
+            ? [this.getRootDirectory(scope)]
+            : undefined,
+        },
+        {
+          mimeType,
+          localPath,
+        }
+      );
+    }
+  }
 }

package/src/types/native.ts

@@ -1,6 +1,6 @@
-export type NativeRNCloudCloudStorageScope = 'documents' | 'app_data';
+export type NativeStorageScope = 'documents' | 'app_data';
 
-export interface NativeRNCloudCloudStorageFileStat {
+export interface NativeStorageFileStat {
   size: number;
   birthtimeMs: number;
   mtimeMs: number;
@@ -8,7 +8,7 @@ export interface NativeRNCloudCloudStorageFileStat {
   isFile: boolean;
 }
 
-export enum CloudStorageErrorCode {
+export enum NativeCloudStorageErrorCode {
   INVALID_SCOPE = 'ERR_INVALID_SCOPE',
   FILE_NOT_FOUND = 'ERR_FILE_NOT_FOUND',
   PATH_IS_FILE = 'ERR_PATH_IS_FILE',
@@ -25,18 +25,54 @@ export enum CloudStorageErrorCode {
   UNKNOWN = 'ERR_UNKNOWN',
   FILE_NOT_DOWNLOADABLE = 'ERR_FILE_NOT_DOWNLOADABLE',
   ACCESS_TOKEN_MISSING = 'ERR_ACCESS_TOKEN_MISSING',
+  INVALID_URL = 'ERR_INVALID_URL',
+  NETWORK_ERROR = 'ERR_NETWORK_ERROR',
 }
 
-export default interface NativeRNCloudStorage {
-  fileExists: (path: string, scope: NativeRNCloudCloudStorageScope) => Promise<boolean>;
-  appendToFile: (path: string, data: string, scope: NativeRNCloudCloudStorageScope) => Promise<void>;
-  createFile: (path: string, data: string, scope: NativeRNCloudCloudStorageScope, overwrite: boolean) => Promise<void>;
-  createDirectory: (path: string, scope: NativeRNCloudCloudStorageScope) => Promise<void>;
-  listFiles: (path: string, scope: NativeRNCloudCloudStorageScope) => Promise<string[]>;
-  readFile: (path: string, scope: NativeRNCloudCloudStorageScope) => Promise<string>;
-  downloadFile: (path: string, scope: NativeRNCloudCloudStorageScope) => Promise<void>;
-  deleteFile: (path: string, scope: NativeRNCloudCloudStorageScope) => Promise<void>;
-  deleteDirectory: (path: string, recursively: boolean, scope: NativeRNCloudCloudStorageScope) => Promise<void>;
-  statFile: (path: string, scope: NativeRNCloudCloudStorageScope) => Promise<NativeRNCloudCloudStorageFileStat>;
+export interface NativeLocalFileSystem {
+  getConstants: () => {
+    temporaryDirectory: string;
+  };
+  createFile: (path: string, data: string) => Promise<string>;
+  readFile: (path: string) => Promise<string>;
+  downloadFile: (remoteUri: string, localPath: string, options?: { headers?: Record<string, string> }) => Promise<void>;
+  uploadFile: (
+    localPath: string,
+    remoteUri: string,
+    options?: {
+      headers?: Record<string, string>;
+      method?: 'PUT' | 'POST' | 'PATCH';
+    } & (
+      | {
+          uploadType?: 'binary';
+        }
+      | {
+          uploadType?: 'multipart';
+          fieldName?: string;
+          parameters?: Record<string, string>;
+        }
+    )
+  ) => Promise<void>;
+}
+
+export interface NativeStorage {
+  fileExists: (path: string, scope: NativeStorageScope) => Promise<boolean>;
+  appendToFile: (path: string, data: string, scope: NativeStorageScope) => Promise<void>;
+  createFile: (path: string, data: string, scope: NativeStorageScope, overwrite: boolean) => Promise<void>;
+  createDirectory: (path: string, scope: NativeStorageScope) => Promise<void>;
+  listFiles: (path: string, scope: NativeStorageScope) => Promise<string[]>;
+  readFile: (path: string, scope: NativeStorageScope) => Promise<string>;
+  deleteFile: (path: string, scope: NativeStorageScope) => Promise<void>;
+  deleteDirectory: (path: string, recursively: boolean, scope: NativeStorageScope) => Promise<void>;
+  statFile: (path: string, scope: NativeStorageScope) => Promise<NativeStorageFileStat>;
+  downloadFile: (remotePath: string, localPath: string, scope: NativeStorageScope) => Promise<void>;
+  uploadFile: (
+    remotePath: string,
+    localPath: string,
+    mimeType: string,
+    scope: NativeStorageScope,
+    overwrite: boolean
+  ) => Promise<void>;
   isCloudAvailable: () => Promise<boolean>;
+  triggerSync: (path: string, scope: NativeStorageScope) => Promise<void>;
 }

package/src/utils/cloud-storage-error.ts

@@ -0,0 +1,15 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { NativeCloudStorageErrorCode } from '../types/native';
+
+class CloudStorageError extends Error {
+  code: NativeCloudStorageErrorCode;
+  details?: any;
+
+  constructor(message: string, code: NativeCloudStorageErrorCode, details?: any) {
+    super(message);
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export default CloudStorageError;

package/src/utils/constants.ts

@@ -0,0 +1,20 @@
+import { Platform } from 'react-native';
+import { CloudStorageProvider, CloudStorageProviderOptions, CloudStorageScope, DeepRequired } from '../types/main';
+
+export const LINKING_ERROR =
+  `The package 'react-native-cloud-storage' doesn't seem to be linked. Make sure: \n\n` +
+  Platform.select({ ios: "- You have run 'pod install'\n", default: '' }) +
+  '- You rebuilt the app after installing the package\n' +
+  '- You are not using Expo Go\n';
+
+export const DEFAULT_PROVIDER_OPTIONS: DeepRequired<CloudStorageProviderOptions> = {
+  [CloudStorageProvider.ICloud]: {
+    scope: CloudStorageScope.AppData,
+  },
+  [CloudStorageProvider.GoogleDrive]: {
+    scope: CloudStorageScope.AppData,
+    accessToken: null,
+    strictFilenames: false,
+    timeout: 3000,
+  },
+};

package/src/utils/local-fs.ts

@@ -0,0 +1,19 @@
+import { NativeModules } from 'react-native';
+import { NativeLocalFileSystem as TNativeLocalFileSystem } from '../types/native';
+import { createProxiedNativeModule } from '../utils/native';
+import { LINKING_ERROR } from './constants';
+
+const NativeLocalFileSystem = createProxiedNativeModule<TNativeLocalFileSystem>(
+  NativeModules.CloudStorageLocalFileSystem
+);
+
+export const localFileSystem =
+  NativeLocalFileSystem ??
+  (new Proxy(
+    {},
+    {
+      get() {
+        throw new Error(LINKING_ERROR);
+      },
+    }
+  ) as TNativeLocalFileSystem);

package/src/utils/native.ts

@@ -0,0 +1,40 @@
+import { NativeCloudStorageErrorCode } from '../types/native';
+import CloudStorageError from './cloud-storage-error';
+
+/**
+ * Creates a proxied native module that wraps thrown errors in a CloudStorageError.
+ * @param nativeModule The native module to proxy.
+ * @returns The proxied native module.
+ */
+export const createProxiedNativeModule = <T extends object>(nativeModule: T | undefined): T | null => {
+  if (!nativeModule) return null;
+
+  return new Proxy(nativeModule, {
+    get(target: T, property: string | symbol, receiver: unknown) {
+      const originalValue = Reflect.get(target, property, receiver);
+
+      if (typeof originalValue === 'function') {
+        return async (...arguments_: unknown[]) => {
+          try {
+            return await Reflect.apply(originalValue, target, arguments_);
+          } catch (error: unknown) {
+            const error_ =
+              typeof error === 'object' &&
+              error !== null &&
+              'code' in error &&
+              typeof error.code === 'string' &&
+              Object.values(NativeCloudStorageErrorCode).includes(error.code as NativeCloudStorageErrorCode)
+                ? new CloudStorageError(
+                    'message' in error && typeof error.message === 'string' ? error.message : 'Unknown error',
+                    error.code as NativeCloudStorageErrorCode
+                  )
+                : new CloudStorageError('Unknown error', NativeCloudStorageErrorCode.UNKNOWN, error);
+            throw error_;
+          }
+        };
+      }
+
+      return originalValue;
+    },
+  });
+};