nextcloud-node-client

/// <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. */ 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. * Use the server to provide server connectivity information to the client. * (The FakeServer is only used for testing and code coverage) * If the server is not provided the client tries to find the connectivity information * in the environment. * If a VCAP_SERVICES environment variable is available, the client tries to find * a service with the name "nextcloud" in the user-provides-services section. * If no VCAP_SERVICES are available, the client uses the following variables * from the envirnonment for the connectivity: * <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; }