efici-nextcloud

nextcloud-node-client

The nextcloud node client provides a TypeScript/JavaScript API for node applications to access nextcloud remotely.

Basic file and folder operations, tagging and comments are supported. File events will follow (nextcloud activities). The usage within browsers is not supported. The module is under development and API may change until version 1.0.0 is delivered.

Tested with nextcloud 14.0.4 and 15.0.1

Concepts

Client

The client is the root object and represents the connection to the nextcloud server.

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.

API overview

The API usage is currently not yet documented. Please refer to test file and the /docs folder with the generated documentation.

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, URL
• 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, URL
• get content
• delete
• get tags, add tag, remove tag
• add comment
• get comments
• move/rename

Tag

• get name, id
• delete*

* admin permissions required

Installation

npm install nextcloud-node-client

Creating a client

Creating a nextcloud client with reference to a service name

  // typescript
  import { ICredentials, NCClient } from "nextcloud-node-client";
 
  (async() => {
    // service instance name from VCAP_SERVICES environment - "user-provided" section      
    const credentials: ICredentials = NCClient.getCredentialsFromEnv("myServiceInstanceName");
    try {
        const client = new NCClient(credentials.url, credentials.basicAuth);
        //  do cool stuff with the client
    } catch (e) {
          // some error handling
    }
 })();

  // javascript
  const NCClient = require("nextcloud-node-client").NCClient;
 
  (async() => {
    // service instance name from VCAP_SERVICES environment - "user-provided" section      
    const credentials = NCClient.getCredentialsFromEnv("myServiceInstanceName");
    try {
        // service instance name from VCAP_SERVICES environment - "user-provided" section        
        const client = new NCClient(credentials.url, credentials.basicAuth);
        //  do cool stuff with the client
    } catch (e) {
          // some error handling
    }
 })();

Creating a nextcloud client with explicite credentials

  // typescript
  import { NCClient } from "nextcloud-node-client";
 
  (async() => {
    try {
        const client = new NCClient("https://myNextcloudServer.com/remote.php/webdav", { username: "<my user>", password: "<my password>" } );
        //  do cool stuff with the client
    } catch (e) {
          // some error handling
    }
 })();

Defining a nextcloud service instance

A nextcloud service instance is required to access the credentials of the nextcloud server. Storing security configuration in the environment separate from code is based on The Twelve-Factor App methodology. The service configuration is stored in the environment variable VCAP_SERVICES (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.

template for VCAP_SERVICES

VCAP_SERVICES={
    "user-provided": [
        {
            "binding_name": null,
            "credentials": {
                "password": "<your password>",
                "url": "<your WebDAV url to nextcloud>",
                "username": "<your user name>"
            },
            "instance_name": "<your service instance name>",
            "label": "user-provided",
            "name": "<your service instance name>",
            "syslog_drain_url": "",
            "tags": [],
            "volume_mounts": []
        }
    ]
}

In one line

VCAP_SERVICES={ "user-provided": [ { "binding_name": null, "credentials": { "password": "<your password>", "url": "<your WebDAV url to nextcloud>", "username": "<your user name>" }, "instance_name": "<your service instance name>", "label": "user-provided", "name": "<your service instance name>", "syslog_drain_url": "", "tags": [], "volume_mounts": [] } ] }

Find a template for a .env file in the root folder.

CloudFoundry Integration

Cloud foundry apps use the credentials provided in the environment. Create a user provided service from a json file to store the credentials securely in the environment.

cloud foundry command line:

cf create-user-provided-service myServiceInstanceName -p ./userProvidedService.json

Structure of the userProvidedService.json file

{
    "url": "<url - WebDAV endpoint of the nextcloud server>",
    "username": "<user name>",
    "password": "<password>"
}

API

Quota

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

Create folder

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

Get folder(s)

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

Delete folder

    // get folder
    const 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");

Development

set the NODE_ENV to "development" and locate the userProvidedService.json file in the root directory for local development.

Use npm run build-watch to build js files.

Test

Use npm run test to execute automated tests Use npm run test-d to execute automated tests with debug information

License

Apache