efici-nextcloud
v0.3.2
Published
Nextcloud client API for node.js
Downloads
5
Maintainers
Readme
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