nextcloud-node-client/dist/client.d.ts

/// <reference types="node" />
import ClientError from "./error";
import FakeServer from "./fakeServer";
import File from "./file";
import FileSystemElement from "./fileSystemElement";
import Folder from "./folder";
import RequestResponseLogEntry from "./requestResponseLogEntry";
import Server from "./server";
import Share, { ICreateShare, SharePermission } from "./share";
import Tag from "./tag";
export { Client, ClientError, Folder, File, FileSystemElement, ICreateShare, Tag, FakeServer, Server, SharePermission, RequestResponseLogEntry, };
export interface ISysInfoNextcloudSystem {
    "version": string;
}
export interface ISysInfoNextcloudClient {
    "version": string;
}
export interface ISysInfoNextcloud {
    "system": ISysInfoNextcloudSystem;
}
export interface ISystemInfo {
    "nextcloud": ISysInfoNextcloud;
    "nextcloudClient": ISysInfoNextcloudClient;
}
export interface IQuota {
    used: number;
    available: number | string;
}
/**
 * The nextcloud client is the root object to access the remote api of the nextcloud server.<br>
 */
export default class Client {
    static webDavUrlPath: string;
    private nextcloudOrigin;
    private nextcloudAuthHeader;
    private nextcloudRequestToken;
    private webDAVUrl;
    private proxy?;
    private fakeServer?;
    private logRequestResponse;
    private httpClient?;
    /**
     * Creates a new instance of a nextcloud client.<br/>
     * Use the server to provide server connectivity information to the client.<br/>
     * (The FakeServer is only used for testing and code coverage)<br/><br/>
     * If the server is not provided the client tries to find the connectivity information
     * in the environment.<br/>
     * If a <b>VCAP_SERVICES</b> environment variable is available, the client tries to find
     * a service with the name <b>"nextcloud"</b> in the user-provides-services section.<br/>
     * If no VCAP_SERVICES are available, the client uses the following variables
     * from the envirnonment for the connectivity:<br/>
     * <ul>
     * <li>NEXTCLOUD_URL - the WebDAV url of the nextcloud server</li>
     * <li>NEXTCLOUD_USERNAME - the user name</li>
     * <li>NEXTCLOUD_PASSWORD - the application password</li>
     * </ul>
     * @param server optional server information to connection to a nextcloud server
     * @constructor
     */
    constructor(server?: Server | FakeServer);
    /**
     * returns the used and free quota of the nextcloud account
     */
    getQuota(): Promise<IQuota>;
    /**
     * creates a new tag, if not already existing
     * this function will fail with http 403 if the user does not have admin privileges
     * @param tagName the name of the tag
     * @returns tagId
     */
    createTag(tagName: string): Promise<Tag>;
    /**
     * returns a tag identified by the name or null if not found
     * @param tagName the name of the tag
     * @returns tag or null
     */
    getTagByName(tagName: string): Promise<Tag | null>;
    /**
     * returns a tag identified by the id or null if not found
     * @param tagId the id of the tag
     * @returns tag or null
     */
    getTagById(tagId: number): Promise<Tag | null>;
    /**
     * deletes the tag by id
     * this function will fail with http 403 if the user does not have admin privileges
     * @param tagId the id of the tag like "/remote.php/dav/systemtags/234"
     */
    deleteTag(tagId: number): Promise<void>;
    /**
     * deletes all visible assignable tags
     * @throws Error
     */
    deleteAllTags(): Promise<void>;
    /**
     * returns a list of tags
     * @returns array of tags
     */
    getTags(): Promise<Tag[]>;
    /**
     * returns the list of tag names and the tag ids
     * @param fileId the id of the file
     */
    getTagsOfFile(fileId: number): Promise<Map<string, number>>;
    /**
     * removes the tag from the file
     * @param fileId the file id
     * @param tagId the tag id
     */
    removeTagOfFile(fileId: number, tagId: number): Promise<void>;
    /**
     * returns the id of the file or -1 of not found
     * @returns id of the file or -1 if not found
     */
    getFileId(fileUrl: string): Promise<number>;
    getFolderContents(folderName: string): Promise<any[]>;
    /**
     * creates a folder and all parent folders in the path if they do not exist
     * @param folderName name of the folder /folder/subfolder/subfolder
     * @returns a folder object
     */
    createFolder(folderName: string): Promise<Folder>;
    /**
     * deletes a file
     * @param fileName name of folder "/f1/f2/f3/x.txt"
     */
    deleteFile(fileName: string): Promise<void>;
    /**
     * deletes a folder
     * @param folderName name of folder "/f1/f2/f3"
     */
    deleteFolder(folderName: string): Promise<void>;
    /**
     * get a folder object from a path string
     * @param folderName Name of the folder like "/company/branches/germany"
     * @returns null if the folder does not exist or an folder object
     */
    getFolder(folderName: string): Promise<Folder | null>;
    /**
     * get a array of folders from a folder path string
     * @param folderName Name of the folder like "/company/branches/germany"
     * @returns array of folder objects
     */
    getSubFolders(folderName: string): Promise<Folder[]>;
    /**
     * get files of a folder
     * @param folderName Name of the folder like "/company/branches/germany"
     * @returns array of file objects
     */
    getFiles(folderName: string): Promise<File[]>;
    /**
     * create a new file of overwrites an existing file
     * @param fileName the file name /folder1/folder2/filename.txt
     * @param data the buffer object
     */
    createFile(fileName: string, data: Buffer): Promise<File>;
    /**
     * returns a nextcloud file object
     * @param fileName the full file name /folder1/folder2/file.pdf
     */
    getFile(fileName: string): Promise<File | null>;
    /**
     * renames the file or moves it to an other location
     * @param sourceFileName source file name
     * @param targetFileName target file name
     */
    moveFile(sourceFileName: string, targetFileName: string): Promise<File>;
    /**
     * renames the folder or moves it to an other location
     * @param sourceFolderName source folder name
     * @param tarName target folder name
     */
    moveFolder(sourceFolderName: string, tarName: string): Promise<Folder>;
    /**
     * returns the content of a file
     * @param fileName name of the file /d1/file1.txt
     * @returns Buffer with file content
     */
    getContent(fileName: string): Promise<Buffer>;
    /**
     * returns the link to a file for downloading
     * @param fileName name of the file /folder1/folder1.txt
     * @returns url
     */
    getLink(fileName: string): string;
    /**
     * returns the url to the file in the nextcloud UI
     * @param fileId the id of the file
     */
    getUILink(fileId: number): string;
    /**
     * adds a tag to a file or folder
     * if the tag does not exist, it is automatically created
     * if the tag is created, the user must have damin privileges
     * @param fileId the id of the file
     * @param tagName the name of the tag
     * @returns nothing
     * @throws Error
     */
    addTagToFile(fileId: number, tagName: string): Promise<void>;
    /**
     * adds a comment to a file
     * @param fileId the id of the file
     * @param comment the comment to be added to the file
     */
    addCommentToFile(fileId: number, comment: string): Promise<void>;
    /**
     * returns comments of a file / folder
     * @param fileId the id of the file / folder
     * @param top number of comments to return
     * @param skip the offset
     * @returns array of comment strings
     * @throws Exception
     */
    getFileComments(fileId: number, top?: number, skip?: number): Promise<string[]>;
    /**
     * returns system information about the nextcloud server and the nextcloud client
     */
    getSystemInfo(): Promise<ISystemInfo>;
    /**
     * returns users
     */
    getUserIDs(): Promise<string[]>;
    createUser(options: {
        userId: string;
        displayName: string;
        password: string;
    }): Promise<void>;
    /**
     * create a new share
     */
    createShare(options: ICreateShare): Promise<Share>;
    /**
     * update a new share
     */
    updateShare(shareId: string, body: {
        password: string;
    } | {
        expireDate: string;
    } | {
        note: string;
    }): Promise<void>;
    /**
     * get share information
     * @param shareId
     */
    getShare(shareId: string): Promise<any>;
    /**
     * get share information
     * @param shareId
     */
    deleteShare(shareId: string): Promise<any>;
    /**
     * asserts valid xml
     * asserts multistatus response
     * asserts that a href is available in the multistatus response
     * asserts propstats and prop
     * @param response the http response
     * @param href get only properties that match the href
     * @returns array of properties
     * @throws GeneralError
     */
    private getPropertiesFromWebDAVMultistatusResponse;
    /**
     * nextcloud creates a csrf token and stores it in the html header attribute
     * data-requesttoken
     * this function is currently not used
     * @returns the csrf token / requesttoken
     */
    private getHttpResponse;
    /**
     * get contents array of a folder
     * @param folderName Name of the folder like "/company/branches/germany"
     * @param folderIndicator true if folders are requested otherwise files
     * @returns array of folder contents meta data
     */
    private Contents;
    private sanitizeFolderName;
    private getTagIdFromHref;
    private createFolderInternal;
    private stat;
    private putFileContents;
}