react-native-cloud-storage 1.4.2 → 1.5.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Kuatsu Digital Agency
+Copyright (c) 2023-2024 Kuatsu Digital Agency
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights

package/README.md

@@ -2,13 +2,13 @@
 
 ![npm bundle size](https://img.shields.io/bundlephobia/min/react-native-cloud-storage?style=flat-square) ![GitHub](https://img.shields.io/github/license/kuatsu/react-native-cloud-storage?style=flat-square) ![GitHub last commit](https://img.shields.io/github/last-commit/kuatsu/react-native-cloud-storage?style=flat-square)
 
-This library provides a unified and streamlined API for accessing cloud storage services on iOS, Android and Web. It supports iCloud on iOS and Google Drive on all other platforms.
+This library provides a unified and streamlined API for accessing cloud storage services on iOS, Android and Web. It supports iCloud (on iOS only) and Google Drive (all platforms).
 
 - 💾 Read and write files to the cloud
 - 🧪 Fully compatible with Expo
 - 📱 iOS, Android & Web support
 - 🏎️ Lightning fast iCloud performance using native iOS APIs
-- 🌐 Google Drive REST API implementation for other platforms
+- 🌐 Google Drive REST API implementation for all platforms
 - 🧬 Easy to use React Hooks API, or use the imperative `fs`-style API
 - 👌 Zero dependencies, small bundle size
 
@@ -36,14 +36,15 @@ Afterwards, [add the provided config plugin](https://react-native-cloud-storage.
 ```jsx
 import React from 'react';
 import { Platform, View, Text, Button } from 'react-native';
-import { CloudStorage, useIsCloudAvailable } from 'react-native-cloud-storage';
+import { CloudStorage, CloudStorageProvider, useIsCloudAvailable } from 'react-native-cloud-storage';
 
 const App = () => {
   const cloudAvailable = useIsCloudAvailable();
 
   React.useEffect(() => {
-    if (Platform.OS !== 'ios') {
-      CloudStorage.setGoogleDriveAccessToken('some-access-token'); // get via @react-native-google-signin/google-signin or similar
+    if (CloudStorage.getDefaultProvider() === CloudStorageProvider.GoogleDrive) {
+      // get access token via @react-native-google-signin/google-signin or similar
+      CloudStorage.setProviderOptions({ accessToken: 'some-access-token' });
     }
   }, []);
 

package/ios/CloudStorage.swift

@@ -3,311 +3,101 @@ import Foundation
 @objc(CloudStorage)
 class CloudStorage: NSObject {
   @objc(fileExists:withScope:withResolver:withRejecter:)
-  func fileExists(path: String, scope: String, resolve:RCTPromiseResolveBlock,reject:RCTPromiseRejectBlock) -> Void {
-    let fileUrl: URL?
-    do {
-      fileUrl = try getFileURL(path, scope)
-    } catch let error as NSError {
-      reject(error.domain, error.userInfo["message"] as? String, error)
-      return
+  func fileExists(path: String, scope: String, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+    withPromise(resolve: resolve, reject: reject) {
+      let fileUrl = try CloudKitUtils.getFileURL(path: path, scope: scope)
+      return try FileUtils.checkFileExists(fileUrl: fileUrl)
     }
-
-    let fileManager = FileManager.default
-    let fileExists = fileManager.fileExists(atPath: fileUrl!.path)
-    resolve(fileExists)
   }
 
   @objc(appendToFile:withData:withScope:withResolver:withRejecter:)
-  func appendToFile(path: String, data: String, scope: String, resolve:RCTPromiseResolveBlock,reject:RCTPromiseRejectBlock) -> Void {
-    // Append data to the file at path. If the file doesn't exist, create it.
-    let fileUrl: URL?
-    do {
-      fileUrl = try getFileURL(path, scope)
-    } catch let error as NSError {
-      reject(error.domain, error.userInfo["message"] as? String, error)
-      return
-    }
+  func appendToFile(path: String, data: String, scope: String, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+    withPromise(resolve: resolve, reject: reject) {
+      let fileUrl = try CloudKitUtils.getFileURL(path: path, scope: scope)
 
-    let fileManager = FileManager.default
-    if (!fileManager.fileExists(atPath: fileUrl!.path)) {
-      do {
-        try data.write(to: fileUrl!, atomically: true, encoding: .utf8)
-        resolve(true)
-      } catch {
-        reject("ERR_WRITE_ERROR", "Error writing file \(path)", error)
-      }
-    } else {
-      do {
-        let fileHandle = try FileHandle(forWritingTo: fileUrl!)
-        fileHandle.seekToEndOfFile()
-        fileHandle.write(data.data(using: .utf8)!)
-        fileHandle.closeFile()
-        resolve(true)
-      } catch {
-        reject("ERR_WRITE_ERROR", "Error writing file \(path)", error)
+      var existingData = ""
+      if try FileUtils.checkFileExists(fileUrl: fileUrl) {
+        existingData = try FileUtils.readFile(fileUrl: fileUrl)
       }
+
+      let newData = existingData + data
+      return try FileUtils.writeFile(fileUrl: fileUrl, content: newData)
     }
   }
 
   @objc(createFile:withData:withScope:withOverwrite:withResolver:withRejecter:)
-  func createFile(path: String, data: String, scope: String, overwrite: Bool, resolve:RCTPromiseResolveBlock,reject:RCTPromiseRejectBlock) -> Void {
-    let fileUrl: URL?
-    do {
-      fileUrl = try getFileURL(path, scope, overwrite ? nil : false)
-    } catch let error as NSError {
-      reject(error.domain, error.userInfo["message"] as? String, error)
-      return
-    }
+  func createFile(path: String, data: String, scope: String, overwrite: Bool, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+    withPromise(resolve: resolve, reject: reject) {
+      let fileUrl = try CloudKitUtils.getFileURL(path: path, scope: scope)
+
+      if try (FileUtils.checkFileExists(fileUrl: fileUrl) && !overwrite) {
+        throw CloudStorageError.fileAlreadyExists(path: path)
+      }
 
-    do {
-      try data.write(to: fileUrl!, atomically: true, encoding: .utf8)
-      resolve(true)
-    } catch {
-      reject("ERR_WRITE_ERROR", "Error writing file \(path)", error)
+      return try FileUtils.writeFile(fileUrl: fileUrl, content: data)
     }
   }
 
   @objc(createDirectory:withScope:withResolver:withRejecter:)
-  func createDirectory(path: String, scope: String, resolve:RCTPromiseResolveBlock,reject:RCTPromiseRejectBlock) -> Void {
-    let directoryUrl: URL?
-    do {
-      directoryUrl = try getFileURL(path, scope, false)
-    } catch let error as NSError {
-      reject(error.domain, error.userInfo["message"] as? String, error)
-      return
-    }
-
-    let fileManager = FileManager.default
-    do {
-      try fileManager.createDirectory(at: directoryUrl!, withIntermediateDirectories: true, attributes: nil)
-      resolve(true)
-    } catch {
-      reject("ERR_WRITE_ERROR", "Error creating directory \(path)", error)
+  func createDirectory(path: String, scope: String, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+    withPromise(resolve: resolve, reject: reject) {
+      let fileUrl = try CloudKitUtils.getFileURL(path: path, scope: scope)
+      return try FileUtils.createDirectory(directoryUrl: fileUrl)
     }
   }
 
   @objc(listFiles:withScope:withResolver:withRejecter:)
-  func listFiles(path: String, scope: String, resolve:RCTPromiseResolveBlock,reject:RCTPromiseRejectBlock) -> Void {
-    let directoryUrl: URL?
-    do {
-      directoryUrl = try getFileURL(path, scope, true)
-    } catch let error as NSError {
-      reject(error.domain, error.userInfo["message"] as? String, error)
-      return
-    }
-
-    let fileManager = FileManager.default
-    do {
-      let files = try fileManager.contentsOfDirectory(atPath: directoryUrl!.path)
-      resolve(files)
-    } catch {
-      reject("ERR_READ_ERROR", "Error reading directory \(path)", error)
+  func listFiles(path: String, scope: String, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+    withPromise(resolve: resolve, reject: reject) {
+      let fileUrl = try CloudKitUtils.getFileURL(path: path, scope: scope)
+      return try FileUtils.listFiles(directoryUrl: fileUrl)
     }
   }
 
   @objc(readFile:withScope:withResolver:withRejecter:)
-  func readFile(path: String, scope: String, resolve:RCTPromiseResolveBlock,reject:RCTPromiseRejectBlock) -> Void {
-    let fileUrl: URL?
-    do {
-      fileUrl = try getFileURL(path, scope, true)
-    } catch let error as NSError {
-      reject(error.domain, error.userInfo["message"] as? String, error)
-      return
-    }
-
-    do {
-      let fileContents = try String(contentsOf: fileUrl!, encoding: .utf8)
-      resolve(fileContents)
-    } catch {
-      reject("ERR_READ_ERROR", "Error reading file \(path)", error)
+  func readFile(path: String, scope: String, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+    withPromise(resolve: resolve, reject: reject) {
+      let fileUrl = try CloudKitUtils.getFileURL(path: path, scope: scope)
+      return try FileUtils.readFile(fileUrl: fileUrl)
     }
   }
 
   @objc(downloadFile:withScope:withResolver:withRejecter:)
-  func downloadFile(path: String, scope: String, resolve:RCTPromiseResolveBlock,reject:RCTPromiseRejectBlock) -> Void {
-    let fileManager = FileManager.default
-
-    guard let directory = getDirectory(scope) else {
-        let error = NSError(domain: "", code: 200, userInfo: [NSLocalizedDescriptionKey : "Error reading directory \(scope)"])
-        reject("ERR_READ_ERROR", "Error reading directory \(scope)", error)
-        return
-    }
-
-    // remove leading slashes
-    let path = path.replacingOccurrences(of: "^/+", with: "", options: .regularExpression)
-
-    // append path to scope directory and return URL
-    let filePath = directory.appendingPathComponent(path)
-
-    let isDownloadable = fileManager.isUbiquitousItem(at: filePath)
-
-    if (!isDownloadable) {
-      reject("ERR_FILE_NOT_DOWNLOADABLE", "File or directory \(path) is not an iCloud file", NSError(domain: "", code: 202, userInfo: [NSLocalizedDescriptionKey : "File or directory \(path) is not an iCloud file"]))
-      return
-    }
-    do {
-      // trigger download of file
-      try fileManager.startDownloadingUbiquitousItem(at: filePath)
-    } catch {
-      let error = NSError(domain: "", code: 202, userInfo: [NSLocalizedDescriptionKey : "File or directory \(path) not downloadable"])
-      reject("ERR_FILE_NOT_DOWNLOADABLE", "File or directory \(path) not downloadable", error)
-      return
+  func downloadFile(path: String, scope: String, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+    withPromise(resolve: resolve, reject: reject) {
+      let fileUrl = try CloudKitUtils.getFileURL(path: path, scope: scope)
+      return try CloudKitUtils.downloadFile(fileUrl: fileUrl)
     }
-    resolve(true)
   }
 
-
   @objc(deleteFile:withScope:withResolver:withRejecter:)
-  func deleteFile(path: String, scope: String, resolve:RCTPromiseResolveBlock,reject:RCTPromiseRejectBlock) -> Void {
-    let fileUrl: URL?
-    do {
-      fileUrl = try getFileURL(path, scope, true)
-    } catch let error as NSError {
-      reject(error.domain, error.userInfo["message"] as? String, error)
-      return
-    }
-
-    if (fileUrl!.hasDirectoryPath) {
-      reject("ERR_PATH_IS_DIRECTORY", "Path \(path) is a directory", nil)
-      return
-    }
-
-    let fileManager = FileManager.default
-    do {
-      try fileManager.removeItem(at: fileUrl!)
-      resolve(true)
-    } catch {
-      reject("ERR_DELETE_ERROR", "Error deleting file \(path)", error)
+  func deleteFile(path: String, scope: String, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+    withPromise(resolve: resolve, reject: reject) {
+      let fileUrl = try CloudKitUtils.getFileURL(path: path, scope: scope)
+      return try FileUtils.deleteFileOrDirectory(fileUrl: fileUrl)
     }
   }
 
   @objc(deleteDirectory:withRecursive:withScope:withResolver:withRejecter:)
-  func deleteDirectory(path: String, recursive: Bool, scope: String, resolve:RCTPromiseResolveBlock,reject:RCTPromiseRejectBlock) -> Void {
-    let fileUrl: URL?
-    do {
-      fileUrl = try getFileURL(path, scope, true)
-    } catch let error as NSError {
-      reject(error.domain, error.userInfo["message"] as? String, error)
-      return
-    }
-
-    if (!fileUrl!.hasDirectoryPath) {
-      reject("ERR_PATH_IS_FILE", "Path \(path) is a file", nil)
-      return
-    }
-
-    if (!recursive) {
-      // check if directory is empty
-      let fileManager = FileManager.default
-      do {
-        print(fileUrl!.path)
-        let files = try fileManager.contentsOfDirectory(atPath: fileUrl!.path)
-        print(files)
-        if (files.count > 0) {
-          reject("ERR_DIRECTORY_NOT_EMPTY", "Directory \(path) is not empty", nil)
-          return
-        }
-      } catch {
-        reject("ERR_UNKNOWN", "Error reading directory \(path)", error)
-        return
-      }
-    }
-
-    let fileManager = FileManager.default
-    do {
-      try fileManager.removeItem(at: fileUrl!)
-      resolve(true)
-    } catch {
-      reject("ERR_DELETE_ERROR", "Error deleting directory \(path)", error)
+  func deleteDirectory(path: String, recursive _: Bool, scope: String, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+    withPromise(resolve: resolve, reject: reject) {
+      let fileUrl = try CloudKitUtils.getFileURL(path: path, scope: scope)
+      return try FileUtils.deleteFileOrDirectory(fileUrl: fileUrl)
     }
   }
 
   @objc(statFile:withScope:withResolver:withRejecter:)
-  func statFile(path: String, scope: String, resolve:RCTPromiseResolveBlock,reject:RCTPromiseRejectBlock) -> Void {
-    let fileUrl: URL?
-    do {
-      fileUrl = try getFileURL(path, scope, true)
-    } catch let error as NSError {
-      reject(error.domain, error.userInfo["message"] as? String, error)
-      return
-    }
-
-    let fileManager = FileManager.default
-    do {
-      let attributes = try fileManager.attributesOfItem(atPath: fileUrl!.path)
-      let size = attributes[FileAttributeKey.size] as! UInt64
-      let birthtime = attributes[FileAttributeKey.creationDate] as! Date
-      let mtime = attributes[FileAttributeKey.modificationDate] as! Date
-      let isDirectory = attributes[FileAttributeKey.type] as! FileAttributeType == FileAttributeType.typeDirectory
-      let isFile = attributes[FileAttributeKey.type] as! FileAttributeType == FileAttributeType.typeRegular
-      let result = [
-        "size": size,
-        "birthtimeMs": birthtime.timeIntervalSince1970 * 1000,
-        "mtimeMs": mtime.timeIntervalSince1970 * 1000,
-        "isDirectory": isDirectory,
-        "isFile": isFile
-      ] as [String : Any]
-      resolve(result)
-    } catch {
-      reject("ERR_STAT_ERROR", "Error getting stats for file \(path)", error)
+  func statFile(path: String, scope: String, resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+    withPromise(resolve: resolve, reject: reject) {
+      let fileUrl = try CloudKitUtils.getFileURL(path: path, scope: scope)
+      return try FileUtils.statFile(fileUrl: fileUrl).toDictionary()
     }
   }
 
   @objc(isCloudAvailable:withRejecter:)
-  func isCloudAvailable(resolve:RCTPromiseResolveBlock,reject:RCTPromiseRejectBlock) -> Void {
-    let token = FileManager.default.ubiquityIdentityToken
-    resolve(token != nil)
-  }
-
-  /**
-    Returns the iCloud directory URL for the given scope.
-
-    - Parameter scope: The scope of the directory. Can be either "documents" or "app_data".
-    - Returns: The URL of the iCloud directory.
-  */
-  private func getDirectory(_ scope: String) -> URL? {
-    let fileManager = FileManager.default
-    let isDocumentDirectory = scope.caseInsensitiveCompare("documents") == .orderedSame
-    let ubiquityURL = fileManager.url(forUbiquityContainerIdentifier: nil)
-    print(ubiquityURL)
-    if (isDocumentDirectory) {
-      return fileManager.urls(for: .documentDirectory, in: .userDomainMask).first
-    } else {
-      return ubiquityURL
-    }
-  }
-
-  /**
-    Parses a given path and directory scope to a full file URL. Does not check if the file exists.
-
-    - Parameter path: The path of the file.
-    - Parameter scope: The scope of the directory. Can be either "documents" or "app_data".
-    - Parameter shouldExist: Whether the file should exist. If true, throws an error if the file does not exist. If false, throws an error if the file exists. If nil, does not check if the file exists.
-    - Returns: The full URL of the file.
-    - Throws: An NSError if the scope directory couldn't be found or the file should exist but doesn't or vice versa.
-  */
-  private func getFileURL(_ path: String, _ scope: String, _ shouldExist: Bool? = nil) throws -> URL? {
-    let fileManager = FileManager.default
-
-    guard let directory = getDirectory(scope) else {
-      throw NSError(domain: "ERR_DIRECTORY_NOT_FOUND", code: 0, userInfo: ["message": "Directory for scope \(scope) not found"])
+  func isCloudAvailable(resolve: @escaping RCTPromiseResolveBlock, reject: @escaping RCTPromiseRejectBlock) {
+    withPromise(resolve: resolve, reject: reject) {
+      CloudKitUtils.isCloudKitAvailable()
     }
-
-    // remove leading slashes
-    let path = path.replacingOccurrences(of: "^/+", with: "", options: .regularExpression)
-
-    // append path to scope directory and return URL
-    let filePath = directory.appendingPathComponent(path)
-
-    if (shouldExist != nil) {
-      let fileExists = fileManager.fileExists(atPath: filePath.path)
-      if (shouldExist! && !fileExists) {
-        throw NSError(domain: "ERR_FILE_NOT_FOUND", code: 0, userInfo: ["message": "File or directory \(path) not found"])
-      } else if (!shouldExist! && fileExists) {
-        throw NSError(domain: "ERR_FILE_EXISTS", code: 0, userInfo: ["message": "File or directory \(path) already exists"])
-      }
-    }
-
-    return filePath
   }
 }

package/ios/CloudStorage.xcodeproj/project.pbxproj

@@ -8,6 +8,11 @@
 
 /* Begin PBXBuildFile section */
 		50ADE3732B56EE1300DB5583 /* CloudStorageEventEmitter.swift in Sources */ = {isa = PBXBuildFile; fileRef = 5009AB9B2B56ECD30058E83A /* CloudStorageEventEmitter.swift */; };
+		50BC353B2CA6ED940085E8B9 /* FileUtils.swift in Sources */ = {isa = PBXBuildFile; fileRef = 50BC353A2CA6ED940085E8B9 /* FileUtils.swift */; };
+		50BC353F2CA6EF760085E8B9 /* Types.swift in Sources */ = {isa = PBXBuildFile; fileRef = 50BC353E2CA6EF760085E8B9 /* Types.swift */; };
+		50BC35412CA6F0E80085E8B9 /* CloudKitUtils.swift in Sources */ = {isa = PBXBuildFile; fileRef = 50BC35402CA6F0E80085E8B9 /* CloudKitUtils.swift */; };
+		50BC35452CA6FA6D0085E8B9 /* CloudStorageError.swift in Sources */ = {isa = PBXBuildFile; fileRef = 50BC35442CA6FA6D0085E8B9 /* CloudStorageError.swift */; };
+		50BC35472CA6FF3F0085E8B9 /* Promise.swift in Sources */ = {isa = PBXBuildFile; fileRef = 50BC35462CA6FF3F0085E8B9 /* Promise.swift */; };
 		F4FF95D7245B92E800C19C63 /* CloudStorage.swift in Sources */ = {isa = PBXBuildFile; fileRef = F4FF95D6245B92E800C19C63 /* CloudStorage.swift */; };
 /* End PBXBuildFile section */
 
@@ -27,6 +32,11 @@
 		134814201AA4EA6300B7C361 /* libCloudStorage.a */ = {isa = PBXFileReference; explicitFileType = archive.ar; includeInIndex = 0; path = libCloudStorage.a; sourceTree = BUILT_PRODUCTS_DIR; };
 		5009AB9B2B56ECD30058E83A /* CloudStorageEventEmitter.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CloudStorageEventEmitter.swift; sourceTree = "<group>"; };
 		50ADE3712B56EDFB00DB5583 /* CloudStorageEventEmitter.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = CloudStorageEventEmitter.m; sourceTree = "<group>"; };
+		50BC353A2CA6ED940085E8B9 /* FileUtils.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = FileUtils.swift; sourceTree = "<group>"; };
+		50BC353E2CA6EF760085E8B9 /* Types.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Types.swift; sourceTree = "<group>"; };
+		50BC35402CA6F0E80085E8B9 /* CloudKitUtils.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CloudKitUtils.swift; sourceTree = "<group>"; };
+		50BC35442CA6FA6D0085E8B9 /* CloudStorageError.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CloudStorageError.swift; sourceTree = "<group>"; };
+		50BC35462CA6FF3F0085E8B9 /* Promise.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = Promise.swift; sourceTree = "<group>"; };
 		B3E7B5891CC2AC0600A0062D /* CloudStorage.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = CloudStorage.m; sourceTree = "<group>"; };
 		F4FF95D5245B92E700C19C63 /* CloudStorage-Bridging-Header.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = "CloudStorage-Bridging-Header.h"; sourceTree = "<group>"; };
 		F4FF95D6245B92E800C19C63 /* CloudStorage.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = CloudStorage.swift; sourceTree = "<group>"; };
@@ -51,9 +61,22 @@
 			name = Products;
 			sourceTree = "<group>";
 		};
+		50BC35482CA704A60085E8B9 /* Utils */ = {
+			isa = PBXGroup;
+			children = (
+				50BC35402CA6F0E80085E8B9 /* CloudKitUtils.swift */,
+				50BC35442CA6FA6D0085E8B9 /* CloudStorageError.swift */,
+				50BC353A2CA6ED940085E8B9 /* FileUtils.swift */,
+				50BC35462CA6FF3F0085E8B9 /* Promise.swift */,
+				50BC353E2CA6EF760085E8B9 /* Types.swift */,
+			);
+			path = Utils;
+			sourceTree = "<group>";
+		};
 		58B511D21A9E6C8500147676 = {
 			isa = PBXGroup;
 			children = (
+				50BC35482CA704A60085E8B9 /* Utils */,
 				50ADE3712B56EDFB00DB5583 /* CloudStorageEventEmitter.m */,
 				5009AB9B2B56ECD30058E83A /* CloudStorageEventEmitter.swift */,
 				F4FF95D6245B92E800C19C63 /* CloudStorage.swift */,
@@ -120,8 +143,13 @@
 			isa = PBXSourcesBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
+				50BC353B2CA6ED940085E8B9 /* FileUtils.swift in Sources */,
+				50BC35412CA6F0E80085E8B9 /* CloudKitUtils.swift in Sources */,
+				50BC35472CA6FF3F0085E8B9 /* Promise.swift in Sources */,
+				50BC35452CA6FA6D0085E8B9 /* CloudStorageError.swift in Sources */,
 				F4FF95D7245B92E800C19C63 /* CloudStorage.swift in Sources */,
 				50ADE3732B56EE1300DB5583 /* CloudStorageEventEmitter.swift in Sources */,
+				50BC353F2CA6EF760085E8B9 /* Types.swift in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};

package/ios/CloudStorageEventEmitter.swift

@@ -10,7 +10,7 @@ class CloudStorageEventEmitter: RCTEventEmitter {
   }
 
   override func supportedEvents() -> [String]! {
-    return ["RNCloudStorage.cloud.availability-changed"]
+    ["RNCloudStorage.cloud.availability-changed"]
   }
 
   override func startObserving() {
@@ -23,8 +23,8 @@ class CloudStorageEventEmitter: RCTEventEmitter {
     NotificationCenter.default.removeObserver(self, name: NSNotification.Name.NSUbiquityIdentityDidChange, object: nil)
   }
 
-  @objc func iCloudIdentityChanged(_ notification: Notification? = nil) {
-    let token = FileManager.default.ubiquityIdentityToken
-    CloudStorageEventEmitter.shared.sendEvent(withName: "RNCloudStorage.cloud.availability-changed", body: ["available": token != nil])
+  @objc func iCloudIdentityChanged(_: Notification? = nil) {
+    let isAvailable = CloudKitUtils.isCloudKitAvailable()
+    CloudStorageEventEmitter.shared.sendEvent(withName: "RNCloudStorage.cloud.availability-changed", body: ["available": isAvailable])
   }
 }

package/ios/Utils/CloudKitUtils.swift

@@ -0,0 +1,112 @@
+//
+//  CloudKitUtils.swift
+//  CloudStorage
+//
+//  Created by Maximilian Krause on 27.09.24.
+//  Copyright © 2024 Kuatsu App Agency. All rights reserved.
+//
+
+import Foundation
+
+enum CloudKitUtils {
+  private static let fileManager = FileManager.default
+
+  /**
+     Checks if the CloudKit service is available.
+
+     - Returns: True if the CloudKit service is available, false otherwise.
+   */
+  static func isCloudKitAvailable() -> Bool {
+    fileManager.ubiquityIdentityToken != nil
+  }
+
+  /**
+     Downloads a file from iCloud.
+
+     - Parameter fileUrl: The URL of the file to download.
+     - Throws: An NSError if the file is not downloadable or the download failed.
+   */
+  static func downloadFile(fileUrl: URL) throws {
+    let isDownloadable = fileManager.isUbiquitousItem(at: fileUrl)
+
+    if !isDownloadable {
+      throw CloudStorageError.fileNotDownloadable(path: fileUrl.path)
+    }
+
+    do {
+      // trigger download of file
+      try fileManager.startDownloadingUbiquitousItem(at: fileUrl)
+    } catch {
+      throw CloudStorageError.fileNotDownloadable(path: fileUrl.path)
+    }
+  }
+
+  /**
+     Returns the iCloud directory URL for the given scope.
+
+     - Parameter scope: The scope of the directory.
+     - Returns: The URL of the iCloud directory, or nil if no directory is found.
+   */
+  private static func getScopeDirectory(scope: DirectoryScope) -> URL? {
+    switch scope {
+    case .appData:
+      appDataDirectory
+    case .documents:
+      documentsDirectory
+    }
+  }
+
+  /**
+     Parses a given path and directory scope to a full file URL.
+
+     - Parameter path: The path of the file.
+     - Parameter scope: The scope of the directory.
+     - Parameter shouldExist: Whether the file should exist. If true, throws an error if the file does not exist. If false, throws an error if the file exists. If nil, does not check if the file exists.
+     - Returns: The full URL of the file.
+     - Throws: An NSError if the scope directory couldn't be found or the file should exist but doesn't or vice versa.
+   */
+  static func getFileURL(path: String, scope: DirectoryScope, _ shouldExist: Bool? = nil) throws -> URL {
+    guard let directory = getScopeDirectory(scope: scope) else {
+      throw CloudStorageError.directoryNotFound(path: path)
+    }
+
+    // append path to scope directory
+    let fileUrl = directory.appendingPathComponent(FileUtils.sanitizePath(path: path))
+
+    if shouldExist != nil {
+      let fileExists = try FileUtils.checkFileExists(fileUrl: fileUrl)
+      if shouldExist! && !fileExists {
+        throw CloudStorageError.fileNotFound(path: path)
+      } else if !shouldExist! && fileExists {
+        throw CloudStorageError.fileAlreadyExists(path: path)
+      }
+    }
+
+    return fileUrl
+  }
+
+  /**
+     Parses a given path and unchecked directory scope to a full file URL.
+
+     - Parameter path: The path of the file.
+     - Parameter scope: The scope of the directory. Will be checked for validity.
+     - Parameter shouldExist: Whether the file should exist. If true, throws an error if the file does not exist. If false, throws an error if the file exists. If nil, does not check if the file exists.
+     - Returns: The full URL of the file.
+     - Throws: An NSError if the scope directory couldn't be found or the file should exist but doesn't or vice versa.
+   */
+  static func getFileURL(path: String, scope: String, _ shouldExist: Bool? = nil) throws -> URL {
+    guard let directoryScope = DirectoryScope(rawValue: scope) else {
+      throw CloudStorageError.invalidScope(scope: scope)
+    }
+
+    return try getFileURL(path: path, scope: directoryScope, shouldExist)
+  }
+
+  static var appDataDirectory: URL? {
+    fileManager.url(forUbiquityContainerIdentifier: nil)
+  }
+
+  static var documentsDirectory: URL? {
+    fileManager.urls(for: .documentDirectory, in: .userDomainMask).first
+  }
+}