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

Nextcloud client API for node.js TypeScript applications

/// <reference types="node" />
import UploadFilesCommand, { UploadFilesCommandOptions, SourceTargetFileNames } from "./uploadFilesCommand";
import UploadFolderCommand, { UploadFolderCommandOptions } from "./uploadFolderCommand";
import GetFilesRecursivelyCommand, { GetFilesRecursivelyCommandOptions } from "./getFilesRecursivelyCommand";
import { CommandStatus, CommandResultMetaData } from "./command";
import Environment from "./environment";
import ClientError, { CommandAlreadyExecutedError, QueryLimitError, QueryOffsetError, InsufficientPrivilegesError, InvalidServiceResponseFormatError, OperationFailedError, UserGroupAlreadyExistsError, UserGroupDeletionFailedError, UserResendWelcomeEmailError, UserGroupDoesNotExistError, UserNotFoundError, UserAlreadyExistsError, UserCreateError, UserUpdateError } from "./error";
import FakeServer from "./fakeServer";
import File from "./file";
import FileSystemElement from "./fileSystemElement";
import FileSystemFolder, { IFileNameFormats } from "./fileSystemFolder";
import Folder, { FolderGetFilesOptions } from "./folder";
import RequestResponseLog from "./requestResponseLog";
import RequestResponseLogEntry from "./requestResponseLogEntry";
import Server, { IServerOptions } from "./server";
import Share, { ICreateShare, SharePermission } from "./share";
import Tag from "./tag";
import UserGroup from "./userGroup";
import User, { IUserOptions, IUserOptionsQuota, IUserQuotaUserFriendly, UserProperty } from "./user";
export { FolderGetFilesOptions, CommandAlreadyExecutedError, InvalidServiceResponseFormatError, InsufficientPrivilegesError, OperationFailedError, QueryLimitError, QueryOffsetError, UserNotFoundError, UserAlreadyExistsError, UserCreateError, UserResendWelcomeEmailError, UserUpdateError, UserGroupAlreadyExistsError, UserGroupDeletionFailedError, UserGroupDoesNotExistError, };
export { Client, ClientError, Environment, Folder, File, FileSystemElement, ICreateShare, IServerOptions, Tag, FakeServer, Server, Share, SharePermission, RequestResponseLog, RequestResponseLogEntry, User, UserGroup, UserProperty, IUserOptionsQuota, IUserQuotaUserFriendly, };
export { CommandResultMetaData, GetFilesRecursivelyCommand, GetFilesRecursivelyCommandOptions, UploadFilesCommand, UploadFilesCommandOptions, UploadFolderCommand, UploadFolderCommandOptions, SourceTargetFileNames, FileSystemFolder, IFileNameFormats, CommandStatus, };
export interface IUpsertUserOptions {
    "id": string;
    "enabled"?: boolean;
    "subadminGroups"?: string[];
    "memberGroups"?: string[];
    "quota"?: string;
    "email"?: string;
    "displayName"?: string;
    "password"?: string;
    "phone"?: string;
    "address"?: string;
    "website"?: string;
    "twitter"?: string;
    "language"?: string;
    "locale"?: string;
    "superAdmin"?: boolean;
    "resendWelcomeEmail"?: boolean;
}
export interface IUserPropertyChange {
    "property": string;
    "previousValue": string;
    "newValue": string;
    "error"?: string;
}
export interface IUpsertUserReport {
    "id": string;
    "message": string;
    "changes": IUserPropertyChange[];
}
export interface ISysInfoNextcloudClient {
    "version": string;
}
export interface ISysInfoNextcloud {
    "system": object;
    "storage": object;
    "shares": object;
}
export interface ISysBasicData {
    "serverTimeString": string;
    "uptimeString": string;
    "timeServersString": string;
}
export interface ISystemInfo {
    "nextcloud": ISysInfoNextcloud;
    "server": object;
    "activeUsers": object;
    "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?;
    private userId;
    /**
     * 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 the root folder object
     * @returns {Promise<Folder>} the root folder
     */
    getRootFolder(): Folder;
    /**
     * returns an array of file system objects that have all given tags assigned (AND)
     * @param {Tag[]} tags array of tags
     * @async
     * @returns {Promise<FileSystemElement[]>} returns an array of file system objects
     */
    getFileSystemElementByTags(tags: Tag[]): Promise<FileSystemElement[]>;
    /**
     * get a folder object from a path string
     * @param {string} folderName Name of the folder like "/company/branches/germany"
     * @returns {Promise<Folder | null>} 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 {string} folderName Name of the folder like "/company/branches/germany"
     * @param {FolderGetFilesOptions} options options for filtering and paging
     * @returns array of file objects
     */
    getFiles(folderName: string, options?: FolderGetFilesOptions): 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 | NodeJS.ReadableStream): 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 content of a file
     * @param fileName name of the file /d1/file1.txt
     * @returns Buffer with file content
     */
    pipeContentStream(fileName: string, destination: NodeJS.WritableStream): Promise<void>;
    /**
     * 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>;
    getSystemBasicData(): Promise<ISysBasicData>;
    /**
     * returns a list of user groups
     * @param search string
     * @param limit number
     * @param offset number
     * @returns list of user groups
     * @throws QueryLimitError
     * @throws QueryOffsetError
     */
    getUserGroups(search?: string, limit?: number, offset?: number): Promise<UserGroup[]>;
    /**
     * returns a list of user groups
     * @param search string
     * @param limit number
     * @param offset number
     * @returns list of user groups
     * @throws QueryLimitError
     * @throws QueryOffsetError
     */
    getUserGroupIds(search?: string, limit?: number, offset?: number): Promise<string[]>;
    /**
     * get user group
     * @param id string
     * @returns Promise<UserGroup|null>
     */
    getUserGroup(id: string): Promise<UserGroup | null>;
    /**
     * returns a list of user ids that are members of the user group
     * @param id string
     * @returns list of member user ids
     * @throws [UserGroupDoesNotExistError}
     */
    getUserGroupMembers(id: string): Promise<string[]>;
    /**
     * returns a list of user ids that are subadmins of the user group
     * @param id string
     * @returns list of subadmin user ids
     * @throws [UserGroupDoesNotExistError}
     */
    getUserGroupSubadmins(id: string): Promise<string[]>;
    /**
     * create a new user group
     * @async
     * @param {string} id user group id
     * @returns {Promise<UserGroup>}
     * @throws {UserGroupAlreadyExistsError}
     */
    createUserGroup(id: string): Promise<UserGroup>;
    /**
     * deletes an existing user group
     * @param id string
     * @returns {Promise<void>}
     * @throws {UserGroupDowsNotExistError}
     * @throws {UserGroupDeletionFailedError}
     */
    deleteUserGroup(id: string): Promise<void>;
    /**
     * returns a list of users
     * https://docs.nextcloud.com/server/latest/admin_manual/configuration_user/instruction_set_for_users.html#search-get-users
     * @param search string
     * @param limit number
     * @param offset number
     */
    getUsers(search?: string, limit?: number, offset?: number): Promise<User[]>;
    /**
     * returns user data
     * @param id string the user id
     * @returns Promise<IUserOptions> user data
     * @throws {UserNotFoundError}
     */
    getUserData(id: string): Promise<IUserOptions>;
    /**
     * enables the user
     * @param id string the user id
     * @returns {Promise<void>}
     * @throws {UserNotFoundError}
     */
    enableUser(id: string): Promise<void>;
    /**
     * disables the user
     * @param id string the user id
     * @returns {Promise<void>}
     * @throws {UserNotFoundError}
     */
    disableUser(id: string): Promise<void>;
    /**
     * deletes the user
     * @param id string the user id
     * @returns {Promise<void>}
     * @throws {UserNotFoundError}
     */
    deleteUser(id: string): Promise<void>;
    /**
     * returns a user or null if not found
     * @param id string
     * @returns User | null
     */
    getUser(id: string): Promise<User | null>;
    /**
     * creates a new user with email or password
     * @param options
     * @returns User
     * @throws UserAlreadyExistsError
     * @throws {UserNotFoundError}
     * @throws UserUpdateError
     */
    createUser(options: {
        id: string;
        email?: string;
        password?: string;
    }): Promise<User>;
    /**
     * updates a user property
     * @async
     * @param {string} id user id
     * @param {UserProperty} property property name
     * @param {string} value property value
     * @returns {Promise<void>}
     * @throws  {UserNotFoundError}
     * @throws  {UserUpdateError}
     */
    updateUserProperty(id: string, property: UserProperty, value: string): Promise<void>;
    /**
     * resend the welcome email
     * @param id user id
     * @throws  {UserResendWelcomeEmailError}
     */
    resendWelcomeEmail(id: string): Promise<void>;
    /**
     * adds a user to a group as member
     * @param id string the user id
     * @param userGroupId string the user group id
     * @returns {Promise<void>}
     * @throws {UserNotFoundError}
     * @throws {UserGroupDoesNotExistError}
     * @throws {InsufficientPrivilegesError}
     * @throws {OperationFailedError}
     */
    addUserToMemberUserGroup(id: string, userGroupId: string): Promise<void>;
    /**
     * removes a user from a group as member
     * @param id string the user id
     * @param userGroupId string the user group id
     * @returns {Promise<void>}
     * @throws {UserNotFoundError}
     * @throws {UserGroupDoesNotExistError}
     * @throws {InsufficientPrivilegesError}
     * @throws {OperationFailedError}
     */
    removeUserFromMemberUserGroup(id: string, userGroupId: string): Promise<void>;
    /**
     * promotes a user to a user group subadmin
     * @param id string the user id
     * @param userGroupId string the user group id
     * @returns {Promise<void>}
     * @throws {UserNotFoundError}
     * @throws {UserGroupDoesNotExistError}
     * @throws {InsufficientPrivilegesError}
     * @throws {OperationFailedError}
     */
    promoteUserToUserGroupSubadmin(id: string, userGroupId: string): Promise<void>;
    /**
     * Removes the subadmin rights for the user specified from the group specified
     * @param id string the user id
     * @param userGroupId string the user group id
     * @returns {Promise<void>}
     * @throws {InsufficientPrivilegesError}
     * @throws {OperationFailedError}
     */
    demoteUserFromSubadminUserGroup(id: string, userGroupId: string): Promise<void>;
    /**
     * insert or update complete user data
     * @param options IUpsertUserOptions[]
     * @returns Promise<IUpsertUserReport[]
     */
    upsertUsers(options: IUpsertUserOptions[]): Promise<IUpsertUserReport[]>;
    /**
     * 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>;
    /**
     * @returns array of notification objects
     */
    getNotifications(): Promise<object[]>;
    getUpdateNotifications(version: string): Promise<object>;
    sendNotificationToUser(userId: string, shortMessage: string, longMessage?: string): Promise<void>;
    /**
     * returns apps
     */
    getApps(): Promise<string[]>;
    getAppInfos(appName: string): Promise<object>;
    /**
     * 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 getOcsMetaStatus;
    private getOcsHeaders;
    private getOcsUrl;
    private putFileContents;
}