nextcloud-node-client

Access nextcloud remotely from node.js applications with a rich and simple TypeScript/JavaScript API.

The nextcloud node client supports folder and file operations including tagging and comments. User management, event subscription and event handling is on the roadmap.

Example

// typescript
import Client, { File, Folder, Tag, } from "nextcloud-node-client";

(async () => {
    try {
        // create a new client using connectivity information from environment 
        const client = new Client();
        // create a folder structure if not available
        const folder: Folder = await client.createFolder("folder/subfolder");
        // create file within the folder
        const file: File = await folder.createFile("myFile.txt", Buffer.from("My file content"));
        // add a tag to the file and create the tag if not existing
        await file.addTag("MyTag");
        // add a comment to the file
        await file.addComment("myComment");
        // get the file content
        const content: Buffer = await file.getContent();
        // share the file publicly with password and note
        const share: Share = await client.createShare({ fileSystemElement: file });
        await share.setPassword("some password");
        await share.setNote("some note\nnew line");
        // use the url to access the share 
        const shareLink:string = share.url;
        // delete the folder including the file and share
        await folder.delete();
    } catch (e) {
        // some error handling   
        console.log(e);
    }
})();

Documentation

• Installation
• Security and access management
• Concepts
• API
• Architecture

Installation

npm install nextcloud-node-client

Security and access management

The client requires the WebDAV url of the nextcloud server and the credentials.

Use an app specific password generated in the security - devices & sessions section of the nextcloud settings.

Environment

Credentials can be specified in the environment:

NEXTCLOUD_USERNAME= "<your user name>"
NEXTCLOUD_PASSWORD = "<your password>"
NEXTCLOUD_URL= "https://<your nextcloud host>/remote.php/webdav"

The cloud service configuration VCAP_SERVICES can be used alternativley (refer to the Cloud Foundry documentation for details).

The nextcloud credentials are stored in the section for user provided services user-provided. The client is able to access the service credentials by providing the instance name.

{
    "user-provided": [
        {
            "credentials": {
                "password": "<your password>",
                "url": "https://<your nextcloud host>/remote.php/webdav",
                "username": "<your user name>"
            },
            "name": "<your service instance name>"
        }
    ]
}

Creating a client

Creating a nextcloud client

  // uses the environment to initialize
  import Client from "nextcloud-node-client";
  const client = new Client();

  // uses explicite credentials
  import Client, { Server } from "nextcloud-node-client";
  const server: Server = new Server(
            { basicAuth:
                { password: "<your password>",
                  username: "<your user name>",
                },
                url: "https://<your nextcloud host>/remote.php/webdav",
            });

  const client = new Client(server);

Concepts and Philosophy

The nextcloud-node-client provids a object oriented API in TypeScript. The focus is to provide a simple access to the nextcloud resources rather than a full functional coverage.

The client comes with an object oriented API to access the APIs of nextcloud. The following object types are supported:

Client

The client is the root object and represents the connection to the nextcloud server. The client is used to get access to the root folder and the tag repository.

Folder

The folder is the representation of a nextcloud folder. It may contain many files. All files of a folder are deleted, if the folder is deleted.

File

The file is the representation of a nextcloud file. Every file is contained in a folder.

Tag

Tags are used to filter for file and folders. Tags can be created and assigned to files or folders.

Share

Files and folders can be shared with user, user groups or publicly. The share can be password protected and an exiration date can be applied.

API

This is an overview of the client API. Details can be found in the API docs

Client

• factory method for client
• create folder
• get folder
• create file
• get file
• create tag*
• get tags, by name, by id
• get quota

Folder

• get name, id, base name, urls
• delete
• create sub folders
• get sub folder
• create file
• get files
• get tags, add tag, remove tag
• add comment
• get comments
• move/rename

File

• get name, id, base name, urls, content type
• get content
• delete
• get tags, add tag, remove tag
• add comment
• get comments
• get folder
• move/rename

Tag

• get name, id
• delete*

Share

• create, update, delete

* admin permissions required

API Examples

Quota

    const q: IQuota = await client.getQuota();  
    // { used: 479244777, available: 10278950773 }

Sytem information

    const si: ISystemInfo = await client.getSystemInfo();  

Create folder

    // create folder
    const folder: Folder = await client.createFolder("/products/brooms");
    // create subfolder
    const subfolder: Folder = await folder.createSubFolder("soft brooms");
    // "/products/brooms/soft brooms"
    

Get folder(s)

    // get folder
    const folder: Folder = await client.getFolder("/products");
    // get subfolders
    const subfolders: Folder[] = await folder.getSubFolders();    

Delete folder

    // get folder
    const folder: Folder = await client.getFolder("/products");
    await folder.delete();

Create file

    const folder = await client.getFolder("/products");
    const file = folder.createFile("MyFile.txt", new Buffer("My new file"));

Get file

    const file = await client.getFile("/products/MyFile.txt");
    // or
    const folder = await client.getFolder("/products");
    const file = await folder.getFile("MyFile.txt");
    // file: name, baseName, lastmod, size, mime

Get file content

    const file = await client.getFile("/products/MyFile.txt");
    const buffer = await file.getContent();

Get file Url

    const file = await client.getFile("/products/MyFile.txt");
    const url = await file.getUrl();

Add tag to file

    const file = await client.getFile("/products/MyFile.txt");
    await file.addTag("myTag");

Delete file

    const file = await client.getFile("/products/MyFile.txt");
    await file.delete();

Get files

    const folder = await client.getFolder("/products");
    const files = await folder.getFiles();

Move and/or rename file

    const file = await client.getFile("/products/MyFile.txt");
    await file.move("/products/brooms/MyFileRenamed.txt");

Create, change and delete a share

    const file = await client.getFile("/products/MyFile.txt");
    // share the file (works also for folder)
    const createShare: ICreateShare = { fileSystemElement: file };
    const share: Share = await client.createShare(createShare);
    // change share settings
    await share.setPassword("some password");
    await share.setNote("some note\nnew line");
    await share.setExpiration(new Date(2020, 11, 5));  
    // use the url to access the share 
    const shareLink:string = share.url;
    // delete share, if not required anymore
    await share.delete();

Architecture

The nextcloud node client can be used by node applications to extend the nextcloud functionality remotely. The client uses only HTTP apis of nextcloud for access.

Quality

Tested with nextcloud 17.0.1, 18.0.0

A code coverage of 100% is aspired

Todo list

User management

User:

• get
• getIds limit, offset, search
• create
• update
• delete
• deactivate
• add/remove group
• send notification

User group:

• get
• create
• delete

Streams

Create file and get file using streams

Eventing

• create event objects
• start observer
• subscribe to events and register handler functions
• telegram support

Sharing

Share with

• user
• usergroup
• email-address

notifications

basic methods are available since 1.2.0 without strong typing

• notification object

Access using tags

Get files and folders by tag

Refactoring

• Introduction of exception classes instead of error codes (breaking change)
• Move from codecov to coveralls

Search

Search for files api

• client in github actions - upload files

License

Apache