react-native-cloud-store/lib/typescript/icloud.d.ts

A react-native module for cloud operation

/**
 * A full icloud path string without schema, for example:
 * - ✅ `/path/to/icloud-container/my/file.txt`
 * - ❌ `file:///path/to/icloud-container/my/file.txt`
 * - ❌ `my/file.txt`
 * - ❌ `/my/file.txt`
 */
export type ICloudPath = string;
/**
 * A full file path string with or without schema, for example:
 * - ✅ `/path/to/app/documents/my/file.txt`
 * - ✅ `file:///path/to/app/documents/my/file.txt`
 * - ❌ `/my/file.txt`
 */
export type LocalPath = string;
/**
 *  Check whether icloud is available. This will return `false` when:
 *  - user disabled your app from accessing icloud drive in system settings
 *  - user did not log in with apple id
 *
 * @group Group Base
 */
export declare function isICloudAvailable(): Promise<boolean>;
/**
 * Get the default icloud container url which is the first container selected in (xcode) settings.
 *
 * This would be an empty string or undefined if cannot get it, for example:
 *  - the developer did not create a icloud container
 *  - the developer did not choose a icloud container
 *
 * :::caution
 * The value of this property was set on app startup and will not change even if user disabled or enabled icloud later while your app was running, you can use {@link getDefaultICloudContainerPath} to get the always-new data.
 * :::
 * @category iCloud
 */
export declare const defaultICloudContainerPath: ICloudPath | undefined;
/**
 * Get current default container url. This function will always return the newest path or `undefined` if it cannot get it.
 *
 * @category Base
 */
export declare function getDefaultICloudContainerPath(): Promise<ICloudPath | undefined>;
/**
 * Get path from specific container id
 *
 * @category Base
 */
export declare function getICloudURL(containerIdentifier?: string): Promise<ICloudPath>;
/**
 * When `onProgress` option provided, make sure you have called {@link registerGlobalUploadEvent} at the beginning of your app
 * @group Group File
 */
export declare function writeFile(path: ICloudPath, content: string, options?: {
    override?: boolean;
    onProgress?: (data: {
        progress: number;
    }) => void;
}): Promise<void>;
/**
 * Return utf8 string
 * @category File
 */
export declare function readFile(path: ICloudPath): Promise<string>;
/**
 * Read files/directories under the provided path
 * @category Directory
 */
export declare function readDir(path: ICloudPath): Promise<ICloudPath[]>;
/**
 *
 * @category Directory
 */
export declare function createDir(path: ICloudPath): Promise<void>;
/**
 *
 * @category Directory
 */
export declare function moveDir(pathFrom: ICloudPath, pathTo: ICloudPath): Promise<void>;
/**
 * Copy the file or directory

 * @category File / Directory
 */
export declare function copy(pathFrom: ICloudPath, pathTo: ICloudPath, options?: {
    override?: boolean;
}): Promise<void>;
/**
 * Delete the file or directory. deleting items from iCloud can’t be undone. Once deleted, the item is gone forever.
 * @category File / Directory
 */
export declare function unlink(path: ICloudPath): Promise<void>;
/**
 * Check whether the file or directory exists
 * @category File / Directory
 */
export declare function exist(path: ICloudPath): Promise<boolean>;
/**
 * Values that describe the iCloud storage state of a file. ([official doc](https://developer.apple.com/documentation/foundation/urlubiquitousitemdownloadingstatus))
 */
export declare enum DownloadStatus {
    /**
     * A local copy of this item exists and is the most up-to-date version known to the device.
     */
    current = "NSURLUbiquitousItemDownloadingStatusCurrent",
    /**
     * A local copy of this item exists, but it is stale. The most recent version will be downloaded as soon as possible.
     */
    downloaded = "NSURLUbiquitousItemDownloadingStatusDownloaded",
    /**
     * This item has not been downloaded yet.
     */
    notDownloaded = "NSURLUbiquitousItemDownloadingStatusNotDownloaded"
}
/**
 * File/Directory detailed info
 */
export interface ICloudStat {
    isInICloud?: boolean;
    containerDisplayName?: string;
    isDownloading?: boolean;
    hasCalledDownload?: boolean;
    downloadStatus?: DownloadStatus;
    downloadError?: string;
    isUploaded?: boolean;
    isUploading?: boolean;
    uploadError?: string;
    hasUnresolvedConflicts?: boolean;
    modifyTimestamp?: number;
    createTimestamp?: number;
    name?: string;
    localizedName?: string;
    fileSize?: number;
    isDirectory?: boolean;
}
/**
 * Get the detailed info of the file/directory
 * @param path
 * @category File / Directory
 */
export declare function stat(path: ICloudPath): Promise<ICloudStat>;
/**
 * A wrapper of [evictUbiquitousItem](https://developer.apple.com/documentation/foundation/filemanager/1409696-evictubiquitousitem)
 *
 * Removes the local copy of the file or directory that’s stored in iCloud. This doesn't delete the file or directory, you should use {@link unlink} if you want to delete it permanently
 */
export declare function evictUbiquitousItem(path: ICloudPath): Promise<undefined>;
/**
 * A wrapper of [startDownloadingUbiquitousItem](https://developer.apple.com/documentation/foundation/filemanager/1410377-startdownloadingubiquitousitem)
 *
 * Starts downloading (if necessary) the specified item to the local system.
 */
export declare function startDownloadingUbiquitousItem(path: ICloudPath): Promise<undefined>;
/**
 * A wrapper of [setUbiquitous](https://developer.apple.com/documentation/foundation/filemanager/1413989-setubiquitous)
 *
 * Indicates whether the item at the specified URL should be stored in iCloud.
 *
 * @param flag - `true` to move the item to iCloud or `false` to remove it from iCloud (if it is there currently).
 * @param path - The path of the item (file or directory) that you want to store in iCloud.
 * @param destPath - If moving a file into iCloud, it's the location in iCloud at which to store the file or directory. If moving a file out of iCloud, it's the location on the local device.
 */
export declare function setUbiquitous(flag: boolean, path: ICloudPath | LocalPath, destPath: ICloudPath | LocalPath): Promise<undefined>;
/**
 * A wrapper of [url(forPublishingUbiquitousItemAt..)](https://developer.apple.com/documentation/foundation/filemanager/1411577-url)
 *
 * Returns a URL that can be emailed to users to allow them to download a copy of a flat file item from iCloud. Your app must have access to the network for this call to succeed.
 *
 * @param path - The path in the cloud that you want to share. The file at the specified path must already be uploaded to iCloud when you call this method.
 * @param expirationTimestamp - Timestamp of the expiration date
 */
export declare function getUrlForPublishingUbiquitousItem(path: ICloudPath, expirationTimestamp?: number): Promise<string>;
/**
 * Upload the local file from the app to iCloud container,  `icloudPath` should not exist before uploading or it will throw error
 * :::info
 * This function will be resolved immediately, if your want to wait until uploaded, you can wrap it with `Promise` yourself
 * :::
 */
export declare function upload(localPath: LocalPath, path: ICloudPath, options?: {
    onProgress: (data: {
        progress: number;
    }) => void;
}): Promise<void>;
/**
 * Download file in the icloud.
 * If you want to put the file in the icloud to your application directories, you must download it and then move/copy the file.
 * :::info
 * This function will be resolved immediately, if your want to wait until uploaded, you can wrap it with Promise yourself
 * :::
 * @param path
 * @param options
 */
export declare function download(path: ICloudPath, options?: {
    onProgress: (data: {
        progress: number;
    }) => void;
}): Promise<void>;
/**
 * Call this function at the beginning once to make `onProgress` callback of `upload`/`writeFile` work
 */
export declare function registerGlobalUploadEvent(): {
    remove(): void;
} | undefined;
/**
 * Call this function at the beginning once to make `onProgress` callback of `download` work
 */
export declare function registerGlobalDownloadEvent(): {
    remove(): void;
} | undefined;
export type DocumentsGatheringData = {
    id: string;
    info: {
        added: string[];
        changed: string[];
        removed: string[];
    };
    detail: Array<{
        type: 'upload' | 'download';
        path: string;
        progress: number | null;
        isDir: boolean | null;
    }>;
};
export type DocumentsGatheringEventHandler = (data: DocumentsGatheringData) => void;
/**
 * This event only emits at the first search phase
 * @category Events
 */
export declare function onICloudDocumentsStartGathering(fn: DocumentsGatheringEventHandler): import("react-native").EmitterSubscription;
/**
 * This event only emits at the first search phase
 * @param fn
 * @category Events
 */
export declare function onICloudDocumentsGathering(fn: DocumentsGatheringEventHandler): import("react-native").EmitterSubscription;
/**
 * This event only emits at the first search phase
 * @category Events
 */
export declare function onICloudDocumentsFinishGathering(fn: DocumentsGatheringEventHandler): import("react-native").EmitterSubscription;
/**
 * This event emits when upload/download progress updated.
 * :::info
 * `download` and `upload` have supported `onProgress`, so this event is not needed if you don't have special needs
 * :::
 *
 * @category Events
 */
export declare function onICloudDocumentsUpdateGathering(fn: DocumentsGatheringEventHandler): import("react-native").EmitterSubscription;
/**
 * Call this function at the beginning once to make `onICloudIdentityDidChange` event work
 */
export declare function registerICloudIdentityDidChangeEvent(): {
    remove(): void;
} | undefined;
/**
 * Rarely used event.
 * From the [official doc](https://developer.apple.com/documentation/foundation/nsnotification/name/1407629-nsubiquityidentitydidchange): The system generates this notification when the user logs into or out of an iCloud account or enables or disables the syncing of documents and data.  when the user logs into or out of an iCloud account or enables or disables the syncing of documents and data.
 *
 * @category Events
 */
export declare function onICloudIdentityDidChange(fn: (data: {
    tokenChanged: boolean;
}) => void): import("react-native").EmitterSubscription;