@zerochain/sdk
Version:
The Züs JS SDK is a JavaScript client library that provides a convenient interface for interacting with the Züs Network. It allows developers to perform various operations such as creating and managing allocations, uploading and downloading files, executi
369 lines (368 loc) • 15.5 kB
TypeScript
import type { Blobber, FileRefByName, ListResult } from '@/types/blobber';
import type { ActiveWallet, NetworkDomain, Transaction } from '@/types/wallet';
/** Deletes a file from an allocation. Only the owner of the allocation can delete a file.
*
* To perform multiple deletions in a single call, use the `multiOperation` method instead.
*/
export declare const deleteFile: ({ wallet, domain, allocationId, remotePath, }: {
domain: NetworkDomain;
wallet: ActiveWallet;
allocationId: string;
/** remote path of the file to be deleted*/
remotePath: string;
}) => Promise<{
commandSuccess: boolean;
error: string;
}>;
/** Generates an `authTicket` that provides authorization to the holder to the specified file on the remotepath. */
export declare const share: ({ wallet, domain, allocationId, remotePath, clientId, encryptionPublicKey, expiration, revoke, availableAfter, }: {
domain: NetworkDomain;
wallet: ActiveWallet;
allocationId: string;
/** Remote path of the file to be shared */
remotePath: string;
/** Client ID / wallet ID of the recipient (for public sharing) */
clientId?: string;
/** Encryption public key of the recipient (for private sharing) */
encryptionPublicKey?: string;
/**
* Expiration time of the auth ticket (in Unix timestamp seconds. e.g. `1647858200`)
* @default 0 (no expiration)
*/
expiration?: number;
/** Whether to revoke the share. Only applicable for private sharing */
revoke?: boolean;
/** Time after which the share becomes available */
availableAfter?: string;
}) => Promise<string>;
/** Options for a single file download, usually as part of a multi-download request. */
type MultiDownloadOption = {
/** Remote path of the file to be downloaded */
remotePath: string;
/** Local path where the file should be stored (optional) */
localPath?: string;
/** Download operation type */
downloadType: 'file' | 'thumbnail';
/** Number of blocks to download per request @default 100 */
numBlocks?: number;
/** @optional Required only for file download with an auth ticket */
remoteFileName: string;
/** @optional Lookup hash for remote file, required for auth ticket downloads */
remoteLookupHash?: string;
/** Whether to download the file directly to disk - This uses FileSytem API. This is not supported on Safari browser. Check: https://developer.mozilla.org/en-US/docs/Web/API/Window/showSaveFilePicker */
downloadToDisk: boolean;
/** Suggested name for the file when downloading to disk (optional) */
suggestedName?: string;
};
/** Response format for each downloaded file in a multi-download operation */
type DownloadCommandResponse = {
commandSuccess: boolean;
error?: string;
/** Name of the downloaded file */
fileName?: string;
/** Blob URL of the downloaded file */
url?: string;
};
/** Downloads multiple files in parallel in a batch. This method supports downloading files directly to disk (if supported by the browser) and provides progress updates via a callback function. */
export declare const multiDownload: ({ wallet, domain, allocationId, multiDownloadOptions, authTicket, callback, }: {
domain: NetworkDomain;
wallet: ActiveWallet;
allocationId: string;
/** @optional Required only for download of a shared files (non-owner) */
authTicket?: string;
/** Array of download options for each file */
multiDownloadOptions: MultiDownloadOption[];
/** Callback function will be invoked with progress updates */
callback?: (totalBytes: number, completedBytes: number, fileName: string, blobURL: string, error?: string) => void;
}) => Promise<DownloadCommandResponse[]>;
/** Sets the upload mode for modifying the upload speed and CPU usage . Possible upload modes:
* - 0 = Slow uploads (Consumes less CPU & Memory)
* - 1 = Standard (Default)
* - 2 = High Speed uploads (Consumes more CPU & Memory)
*/
export declare const setUploadMode: ({ wallet, domain, mode, }: {
domain: NetworkDomain;
wallet: ActiveWallet;
/** Upload mode:
* - 0 = low
* - 1 = medium (default)
* - 2 = high */
mode: 0 | 1 | 2;
}) => Promise<void>;
type BulkUploadOption = {
allocationId: string;
webstreaming: boolean;
isUpdate: boolean;
isRepair: boolean;
/** Number of blocks to upload per request @default 100 */
numBlocks: number;
file: File;
remotePath: string;
/** Whether to encrypt the file */
encrypt: boolean;
/** Use `fileToByteString` to generate the thumbnail byte string, or assign an empty string if unavailable. */
thumbnailBytes: string;
/** Callback function will be invoked with progress updates */
callback?: (totalBytes: number, completedBytes: number, fileName: string, blobURL: string, error: string) => void;
/** @optional */
uploadId?: string;
/** @deprecated */
webStreaming?: boolean;
};
/** Upload multiple files in a batch. Also, used to resume a paused upload.
*
* NOTE: Keep the batch size under 50 files. */
export declare const multiUpload: ({ wallet, domain, bulkUploadOptions: options, }: {
domain: NetworkDomain;
wallet: ActiveWallet;
bulkUploadOptions: BulkUploadOption[];
}) => Promise<{
success?: boolean;
error?: string;
}>;
type MultiOperationOption = {
/** Type of operation: 'copy', 'move', 'delete', or 'createdir' */
operationType: 'copy' | 'move' | 'delete' | 'createdir';
/** Remote path of the file/directory */
remotePath: string;
/** Destination name (only for rename operation) */
destName?: string;
/** Destination path (required for copy and move operations) */
destPath?: string;
};
/** Perform multiple operations (copy, move, delete, create directory) together */
export declare const multiOperation: ({ wallet, domain, allocationId, operations, }: {
domain: NetworkDomain;
wallet: ActiveWallet;
allocationId: string;
operations: MultiOperationOption[];
}) => Promise<void>;
/** List the files for a given allocation ID and remote path */
export declare const listObjects: ({ wallet, domain, allocationId, remotePath, offset, pageLimit, }: {
domain: NetworkDomain;
wallet: ActiveWallet;
allocationId: string;
/** The remote path of the file */
remotePath: string;
/** The pagination offset for the list. @default 0 (turn off pagination)*/
offset: number;
/** The number of items per page. @default -1 (turn off pagination) */
pageLimit: number;
}) => Promise<ListResult>;
/** List objects from an auth ticket. It's useful for accessing a shared source by a non-owner */
export declare const listObjectsFromAuthTicket: ({ wallet, domain, allocationId, authTicket, lookupHash, offset, pageLimit, }: {
domain: NetworkDomain;
wallet: ActiveWallet;
allocationId: string;
/** The auth ticket, provided by a non-owner to access a shared source */
authTicket: string;
/** The lookup hash for the file */
lookupHash: string;
/** The pagination offset for the list. @default 0 (turn off pagination)*/
offset: number;
/** The number of items per page. @default -1 (turn off pagination) */
pageLimit: number;
}) => Promise<ListResult>;
/** Create a directory on blobbers */
export declare const createDir: ({ wallet, domain, allocationId, remotePath, }: {
domain: NetworkDomain;
wallet: ActiveWallet;
allocationId: string;
/** The remote path where the directory will be created */
remotePath: string;
}) => Promise<void>;
/** Downloads a specified range of blocks from a file. */
export declare const downloadBlocks: ({ wallet, domain, allocationId, remotePath, authTicket, lookupHash, writeChunkFunc, startBlock, endBlock, }: {
domain: NetworkDomain;
wallet: ActiveWallet;
allocationId: string;
remotePath: string;
/** @optional Required only for download of a shared file (non-owner) */
authTicket?: string;
/** Lookup hash of the file, which is used to locate the file if remotepath and allocation id are not provided */
lookupHash?: string;
writeChunkFunc: (lookupHash: string, chunk: Uint8Array, offset: number) => void;
startBlock: number;
endBlock: number;
}) => Promise<Uint8Array>;
type FileStats = {
CreatedAt: string;
blobber_id: string;
blobber_url: string;
blockchain_aware: boolean;
file_id: string;
last_challenge_txn: string;
name: string;
num_of_block_downloads: number;
num_of_blocks: number;
num_of_challenges: number;
num_of_failed_challenges: number;
num_of_updates: number;
path: string;
path_hash: string;
size: number;
write_marker_txn: string;
};
/** Fetches the file details */
export declare const getFileStats: ({ wallet, domain, allocationId, remotePath, }: {
domain: NetworkDomain;
wallet: ActiveWallet;
allocationId: string;
remotePath: string;
}) => Promise<FileStats[]>;
/** Updates the settings for a blobber. */
export declare const updateBlobberSettings: ({ wallet, domain, blobberSettings, }: {
domain: NetworkDomain;
wallet: ActiveWallet;
/** The new settings to apply to the blobber */
blobberSettings: Blobber;
}) => Promise<Transaction>;
type FileInfo = {
actual_size: number;
created_at: string;
encrypted_key: string;
hash: string;
lookup_hash: string;
mimetype: string;
size: number;
type: string;
updated_at: string;
name: string;
path: string;
};
/** Lists all files in an allocation from the blobbers.
* @deprecated This will consume too much memory and time if there are many nested folders with many files. Prefer using `listObjects` instead.
*/
export declare const getRemoteFileMap: ({ wallet, domain, allocationId, }: {
domain: NetworkDomain;
wallet: ActiveWallet;
allocationId: string;
}) => Promise<FileInfo[]>;
/** Get list of active blobbers */
export declare const getBlobbers: ({ wallet, domain, stakable, }: {
domain: NetworkDomain;
wallet: ActiveWallet;
/** flag to get only stakable blobbers */
stakable: boolean;
}) => Promise<Blobber[]>;
/** Retrieves blobber IDs for the given list of blobber URLs. */
export declare const getBlobberIds: ({ wallet, domain, blobberUrls, }: {
domain: NetworkDomain;
wallet: ActiveWallet;
/** List of blobber URLs for which IDs need to be retrieved */
blobberUrls: string[];
}) => Promise<string[]>;
/**
* GetContainers returns all the running containers in a given domain exposing the `{requestDomain}/endpoints/{endpointID}/docker/containers/json` endpoint
*
* The request should be authenticated with the given username and password, by first creating an auth token then issuing the request.
*
* @returns List of containers
*/
export declare const getContainers: ({ wallet, domain, username, password, requestDomain, }: {
wallet: ActiveWallet;
domain: NetworkDomain;
/** Username to authenticate with */
username: string;
/** Password to authenticate with */
password: string;
/** Domain to issue the request to */
requestDomain: string;
}) => Promise<Array<Record<string, any>>>;
/**
* UpdateContainer updates the given container ID with a new image ID in a given domain.
* The domain should expose the docker API endpoints under `{requestDomain}/endpoints/{endpointID}/docker`.
* The request should be authenticated with the given username and password, by first creating an auth token then issuing the request.
*
* @returns A map containing the response from the update operation.
*/
export declare const updateContainer: ({ wallet, domain, username, password, containerID, newImageID, requestDomain, }: {
wallet: ActiveWallet;
domain: NetworkDomain;
/** Username to authenticate with */
username: string;
/** Password to authenticate with */
password: string;
/** Domain to issue the request to */
requestDomain: string;
/** Container ID to update */
containerID: string;
/** New Image ID to update the container with */
newImageID: string;
}) => Promise<Record<string, any>>;
/**
* searchContainer searches for a container with a given name in a given domain exposing the `{requestDomain}/endpoints/{endpointID}/docker/containers/json` endpoint.
* The request should be authenticated with the given username and password, by first creating an auth token then issuing the request.
* The response is a list of containers in JSON format that match the given name.
*
* @returns List of containers matching the name
*/
export declare const searchContainer: ({ wallet, domain, username, password, name, requestDomain, }: {
wallet: ActiveWallet;
domain: NetworkDomain;
/** Username to authenticate with */
username: string;
/** Password to authenticate with */
password: string;
/** Domain to issue the request to */
requestDomain: string;
/** Name of the container to search for */
name: string;
}) => Promise<Array<Record<string, any>>>;
/** Cancel the upload operation of the file. */
export declare const cancelUpload: ({ wallet, domain, allocationId, remotePath, }: {
wallet: ActiveWallet;
domain: NetworkDomain;
allocationId: string;
/** Remote path of the file */
remotePath: string;
}) => Promise<void>;
/** Pause the upload operation of the file. */
export declare const pauseUpload: ({ wallet, domain, allocationId, remotePath, }: {
wallet: ActiveWallet;
domain: NetworkDomain;
allocationId: string;
/** Remote path of the file */
remotePath: string;
}) => Promise<void>;
/** Get file metadata by name. (File Search) */
export declare const getFileMetaByName: <T extends FileRefByName>({ wallet, domain, allocationId, fileName, modifyFileRef, }: {
wallet: ActiveWallet;
domain: NetworkDomain;
allocationId: string;
fileName: string;
modifyFileRef?: (file: FileRefByName) => T;
}) => Promise<T[] | FileRefByName[]>;
/** Download files in a directory recursively. */
export declare const downloadDirectory: ({ wallet, domain, allocationId, remotePath, authTicket, callback, }: {
domain: NetworkDomain;
wallet: ActiveWallet;
allocationId: string;
/** @optional Required only for download of a shared directory (non-owner) */
authTicket?: string;
/** Remote path of the directory to download */
remotePath: string;
/** Callback function will be invoked with progress updates */
callback?: (totalBytes: number, completedBytes: number, fileName: string, blobURL: string, error?: string) => void;
}) => Promise<void>;
/** Cancel the download of a directory. */
export declare const cancelDownloadDirectory: ({ wallet, domain, remotePath, }: {
domain: NetworkDomain;
wallet: ActiveWallet;
/** Remote path of the directory */
remotePath: string;
}) => Promise<void>;
/** Cancels the download of a specified range of blocks from a file. */
export declare const cancelDownloadBlocks: ({ wallet, domain, allocationId, remotePath, start, end, }: {
domain: NetworkDomain;
wallet: ActiveWallet;
/** The allocation ID associated with the file */
allocationId: string;
/** The remote path where the file is located */
remotePath: string;
/** The start block previously used in the downloadBlocks call */
start: number;
/** The endi block previously used in the downloadBlocks call */
end: number;
}) => Promise<void>;
export {};