{"id":15017826,"url":"https://github.com/hobigo/nextcloud-node-client","last_synced_at":"2025-06-11T14:36:31.533Z","repository":{"id":37849690,"uuid":"164631024","full_name":"hobigo/nextcloud-node-client","owner":"hobigo","description":"Nextcloud node.js client for TypeScript and JavaScript","archived":false,"fork":false,"pushed_at":"2023-01-24T15:02:34.000Z","size":7471,"stargazers_count":60,"open_issues_count":30,"forks_count":18,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-02T19:22:50.982Z","etag":null,"topics":["nextcloud","nodejs","typescript"],"latest_commit_sha":null,"homepage":"https://hobigo.github.io/nextcloud-node-client/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hobigo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null}},"created_at":"2019-01-08T11:08:08.000Z","updated_at":"2025-04-07T00:03:04.000Z","dependencies_parsed_at":"2023-02-12T03:01:09.683Z","dependency_job_id":null,"html_url":"https://github.com/hobigo/nextcloud-node-client","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hobigo%2Fnextcloud-node-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hobigo%2Fnextcloud-node-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hobigo%2Fnextcloud-node-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hobigo%2Fnextcloud-node-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hobigo","download_url":"https://codeload.github.com/hobigo/nextcloud-node-client/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hobigo%2Fnextcloud-node-client/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":258375285,"owners_count":22690961,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nextcloud","nodejs","typescript"],"created_at":"2024-09-24T19:51:02.246Z","updated_at":"2025-06-11T14:36:31.510Z","avatar_url":"https://github.com/hobigo.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# nextcloud-node-client\n\n \u003cimg src=\"https://raw.githubusercontent.com/hobigo/nextcloud-node-client/master/ncnc-logo.png\" width=\"100\"  style=\"max-width:100%;\"\u003e\n\nAccess nextcloud remotely from node.js applications with a rich and simple TypeScript / JavaScript API.\n\n[![lang: Typescript](https://img.shields.io/badge/Language-Typescript-Blue.svg?style=flat-square)](https://www.typescriptlang.org)\n![](https://github.com/hobigo/nextcloud-node-client/workflows/CI/badge.svg)\n[![NPM Downloads](https://img.shields.io/npm/dm/nextcloud-node-client.svg?style=flat)](https://npmjs.org/package/nextcloud-node-client)\n[![Dependency Status](https://david-dm.org/hobigo/nextcloud-node-client.svg?style=flat)](https://david-dm.org/hobigo/nextcloud-node-client)\n[![Coverage Status](https://coveralls.io/repos/github/hobigo/nextcloud-node-client/badge.svg?branch=master)](https://coveralls.io/github/hobigo/nextcloud-node-client?branch=master)\n[![Install Size](https://packagephobia.now.sh/badge?p=commander)](https://packagephobia.now.sh/result?p=nextcloud-node-client)\n[![documentation](https://img.shields.io/website-up-down-green-red/https/hobigo.github.io/nextcloud-node-client.svg?label=documentation-website)](https://hobigo.github.io/nextcloud-node-client)\n\n- upload and download files\n- create files and folder structures\n- all user management functions\n- create shares\n- tagging and commenting\n\nThe nextcloud node client is used to automate access to nextcloud servers from node.js apppliactions. \n\n# Example\n```typescript\n// typescript\nimport Client, { File, Folder, Tag, Share } from \"nextcloud-node-client\";\n\n(async () =\u003e {\n    try {\n        // create a new client using connectivity information from environment \n        const client = new Client();\n        // create a folder structure if not available\n        const folder: Folder = await client.createFolder(\"folder/subfolder\");\n        // create file within the folder\n        const file: File = await folder.createFile(\"myFile.txt\", Buffer.from(\"My file content\"));\n        // add a tag to the file and create the tag if not existing\n        await file.addTag(\"MyTag\");\n        // add a comment to the file\n        await file.addComment(\"myComment\");\n        // get the file content\n        const content: Buffer = await file.getContent();\n        // share the file publicly with password and note\n        const share: Share = await client.createShare({ fileSystemElement: file });\n        await share.setPassword(\"some password\");\n        await share.setNote(\"some note\\nnew line\");\n        // use the url to access the share \n        const shareLink:string = share.url;\n        // delete the folder including the file and share\n        await folder.delete();\n    } catch (e) {\n        // some error handling   \n        console.log(e);\n    }\n})();\n```\n# Documentation\n* [Installation](#installation)\n* [Upload files and folders](./docs/upload.md)\n* [Download files and folders](./docs/download.md)\n* [Get files recursively](./docs/getFiles.md)\n* [User Management](./docs/userManagement.md)\n* [Tagging](./docs/tagging.md)\n* [Security and access management](#security-and-access-management)\n* [Concepts and Philosophy](#concepts-and-philosophy)\n* [API](#api)\n* [Architecture](#architecture)\n* [Examples](#examples)\n\n## Installation\n``\nnpm install nextcloud-node-client\n``\n\n## Security and access management\nThe client requires the url of the nextcloud server and the credentials. \n\nUse an app specific password generated in the security - devices \u0026 sessions section of the nextcloud settings.\n\n### Environment\nCredentials can be specified in the environment:\n```\nNEXTCLOUD_USERNAME= \"\u003cyour user name\u003e\"\nNEXTCLOUD_PASSWORD = \"\u003cyour password\u003e\"\nNEXTCLOUD_URL= \"https://\u003cyour nextcloud host\u003e\"\n```\n\nThe cloud service configuration `VCAP_SERVICES` can be used alternativley (refer to the Cloud Foundry documentation for details).\n\nThe nextcloud credentials are stored in the section for user provided services `user-provided`.\nThe client is able to access the service credentials by providing the instance name.\n```json\n{\n    \"user-provided\": [\n        {\n            \"credentials\": {\n                \"password\": \"\u003cyour password\u003e\",\n                \"url\": \"https://\u003cyour nextcloud host\u003e\",\n                \"username\": \"\u003cyour user name\u003e\"\n            },\n            \"name\": \"\u003cyour service instance name\u003e\"\n        }\n    ]\n}\n```\n\n### Creating a client\nCreating a nextcloud client \n\n```typescript\n  // uses the environment to initialize\n  import Client from \"nextcloud-node-client\";\n  const client = new Client();\n```\n\n```typescript\n  // uses explicite credentials\n  import Client, { Server } from \"nextcloud-node-client\";\n  const server: Server = new Server(\n            { basicAuth:\n                { password: \"\u003cyour password\u003e\",\n                  username: \"\u003cyour user name\u003e\",\n                },\n                url: \"https://\u003cyour nextcloud host\u003e\",\n            });\n\n  const client = new Client(server);\n```\n\n## Concepts and Philosophy\nThe 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.\n\n![nextcloud node client object model](https://raw.githubusercontent.com/hobigo/nextcloud-node-client/master/ncnc-object-model.png)\n\nThe client comes with an object oriented API to access the APIs of nextcloud. The following object types are supported:\n### Client \nThe 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.\n\n### Folder\nThe 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.\n\n### File\nThe file is the representation of a nextcloud file. Every file is contained in a folder.\n\n### Tag\nTags are used to filter for file and folders. Tags can be created and assigned to files or folders.\n\n### Share\nFiles and folders can be shared with user, user groups or publicly. The share can be password protected and an exiration date can be applied.\n\n## API\nThis is an overview of the client API.\nDetails can be found in the [API docs](https://hobigo.github.io/nextcloud-node-client)\n\n\n### Client\n- factory method for client \n- create folder\n- get folder, get root folder\n- create file\n- get file\n- create tag*\n- get tags, by name, by id\n- get quota\n- find users, get user by id\n- create user\n- mass creations and changes of users\n- get user groups, by id\n- create user group\n### Folder\n- get name, id, base name, urls\n- delete\n- create sub folders \n- get sub folder\n- create file\n- get files\n- get tags, add tag, remove tag\n- add comment\n- get comments\n- move/rename\n### File\n- get name, id, base name, urls, content type\n- get content\n- delete\n- get tags, add tag, remove tag\n- add comment\n- get comments\n- get folder\n- move/rename\n### Tag\n- get name, id\n- delete*\n### Share\n- create, update, delete\n### User Group\n- delete\n- get members, get subadmins\n### User\n- delete\n- get properties (display name, email, quota and usage, language, last login, ...)\n- change properties (display name, email, quota, language, password, ...)\n- send welcome email\n- enable / disable\n- promote to super admin / demote from super admin\n- get member groups, get subadmin groups\n- add to user group as member / remove from member user group\n- promote as subadmin for user group / demote from subadmin user group\n\n\\* admin permissions required\n\n### API Examples\n#### Quota\n```typescript\n    const q: IQuota = await client.getQuota();  \n    // { used: 479244777, available: 10278950773 }\n```\n\n#### Sytem information\n```typescript\n    const si: ISystemInfo = await client.getSystemInfo();  \n```\n\n#### Create folder\n```typescript\n    // create folder\n    const folder: Folder = await client.createFolder(\"/products/brooms\");\n    // create subfolder\n    const subfolder: Folder = await folder.createSubFolder(\"soft brooms\");\n    // \"/products/brooms/soft brooms\"\n    \n```\n\n#### Get folder(s)\n```typescript\n    // get folder\n    const folder: Folder = await client.getFolder(\"/products\");\n    // get subfolders\n    const subfolders: Folder[] = await folder.getSubFolders();    \n```\n\n#### Delete folder\n```typescript\n    // get folder\n    const folder: Folder = await client.getFolder(\"/products\");\n    await folder.delete();\n```\n#### Create file\n```javascript\n    const folder = await client.getFolder(\"/products\");\n    const file = folder.createFile(\"MyFile.txt\", new Buffer(\"My new file\"));\n```\n#### Get file\n```javascript\n    const file = await client.getFile(\"/products/MyFile.txt\");\n    // or\n    const folder = await client.getFolder(\"/products\");\n    const file = await folder.getFile(\"MyFile.txt\");\n    // file: name, baseName, lastmod, size, mime\n```\n#### Get file content\n```javascript\n    const file = await client.getFile(\"/products/MyFile.txt\");\n    const buffer = await file.getContent();\n```\n#### Get file Url\n```javascript\n    const file = await client.getFile(\"/products/MyFile.txt\");\n    const url = await file.getUrl();\n```\n#### Add tag to file\n```javascript\n    const file = await client.getFile(\"/products/MyFile.txt\");\n    await file.addTag(\"myTag\");\n```\n#### Delete file\n```javascript\n    const file = await client.getFile(\"/products/MyFile.txt\");\n    await file.delete();\n```\n#### Get files\n```javascript\n    const folder = await client.getFolder(\"/products\");\n    const files = await folder.getFiles();\n```\n#### Move and/or rename file\n```javascript\n    const file = await client.getFile(\"/products/MyFile.txt\");\n    await file.move(\"/products/brooms/MyFileRenamed.txt\");\n```\n\n#### Create, change and delete a share\n```typescript\n    const file = await client.getFile(\"/products/MyFile.txt\");\n    // share the file (works also for folder)\n    const createShare: ICreateShare = { fileSystemElement: file };\n    const share: Share = await client.createShare(createShare);\n    // change share settings\n    await share.setPassword(\"some password\");\n    await share.setNote(\"some note\\nnew line\");\n    await share.setExpiration(new Date(2020, 11, 5));  \n    // use the url to access the share \n    const shareLink:string = share.url;\n    // delete share, if not required anymore\n    await share.delete();\n```\n\n\n## Architecture\nThe 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.\n\n![nextcloud node client component architecture](https://raw.githubusercontent.com/hobigo/nextcloud-node-client/master/ncnc-architecture.png)\n\n## Examples\n### User management\n```typescript\n// typescript\nimport Client, { User, UserGroup } from \"nextcloud-node-client\";\n\n(async () =\u003e {\n    try {\n        // create a new client using connectivity \n        // information from environment\n        const client = new Client();\n        // create a new user group\n        const group: UserGroup = await client.createUserGroup(\"MyGroup\");\n        // create a new user with a email or password\n        const user: User = await client.createUser({ id: \"MyUserId\", email: \"mail@example.com\" });\n        // set some properties \n        // ... password, phone, website, twitter, address, email, locale\n        await user.setDisplayName(\"My Display Name\");\n        await user.setQuota(\"5 GB\");\n        await user.setLanguage(\"en\");\n        // get properties \n        // ... quota, user friendly quota, phone, website, twitter, address, locale\n        const email = await user.getEmail();\n        // disable user\n        await user.disable();\n        // enable user\n        await user.enable();\n        // promote to super administrator\n        await user.promoteToSuperAdmin();\n        // demote from super administrator\n        await user.demoteFromSuperAdmin();\n        // resend welcome email to user\n        await user.resendWelcomeEmail();\n        // add to user group as member\n        await user.addToMemberUserGroup(group);\n        // get member user groups\n        const memberGroups: UserGroup[] = await user.getMemberUserGroups();\n        // get user ids of memembers\n        await group.getMemberUserIds();\n        // remove user from member group\n        await user.removeFromMemberUserGroup(group);\n        // promote user as subadmin for user group\n        await user.promoteToUserGroupSubadmin(group);\n        // get user groups where the user is subadmin\n        const subadminGroups: UserGroup[] = await user.getSubadminUserGroups();\n        // get user ids of subadmins\n        await group.getSubadminUserIds();\n        // demote user from being subadmin for user group\n        await user.demoteFromSubadminUserGroup(group);\n        // delete the user\n        await user.delete();\n        // delete the user group\n        await group.delete();\n        // mass creations / updates of users\n        // groups are created on the fly\n        await client.upsertUsers([\n            { id: \"myUser1\", email: \"myUser1@example.com\", enabled: false, memberGroups: [\"group1\", \"group2\"] },\n            { id: \"myUser2\", password: \"mySecurePassword\", displayName: \"My Name\", superAdmin: true, quota: \"2 GB\" },\n            // ...\n        ]);\n    } catch (e) {\n        // use specific exception *error classes \n        // for error handling documented in @throws\n    }\n})();\n```\n### Tagging\n```typescript\n// typescript\nimport Client, { File, Folder, Share, Tag, FileSystemElement } from \"nextcloud-node-client\";\n\n(async () =\u003e {\n    try {\n        // create a new client using connectivity information from environment\n        const client = new Client();\n        // create a folder structure if not available\n        const folder: Folder = await client.createFolder(\"folder/subfolder\");\n        // create file within the folder\n        const file: File = await folder.createFile(\"myFile.txt\", Buffer.from(\"My file content\"));\n        // create two tags\n        const tag1: Tag = await client.createTag(\"tag 1\");\n        const tag2: Tag = await client.createTag(\"tag 2\");\n        // assign tag to folder\n        folder.addTag(tag1.name);\n        // assign tag to files\n        file.addTag(tag1.name);\n        file.addTag(tag2.name);\n\n        // get list of file system elements with the tag1 assigned\n        let fse: FileSystemElement[] = await client.getFileSystemElementByTags([tag1]);\n        // print names of folder and file\n        console.log(fse[0].name);\n        console.log(fse[1].name);\n\n        // get list of file system elements with the tag1 and tag2\n        fse = await client.getFileSystemElementByTags([tag1, tag2]);\n        // print name of file\n        console.log(fse[0].name);\n\n        // delete the tags\n        await tag1.delete();\n        await tag2.delete();\n        // delete the folder including the file and share\n        await folder.delete();\n    } catch (e) {\n        // some error handling\n        console.log(e);\n    }\n})();\n```\n\n## Quality\nTested with nextcloud 17.0.1, 18.0.0\n\nA code coverage of 100% is aspired\n\n## Todo list\n\n### Version 2.0\n- remove vcap services support\n- remove server object and replace with connection object\n- connection object handles all http requets (new Connection, conn.connect() ...)\n- refactor client - use connection instead of client in sub objects move client methods to sub objects\n- Move exceptions to relevant objects, prefix all exceptions with \"Error\"\n- Remove \"I\" from interface names\n\n### Sharing\nShare with \n* user\n* usergroup\n* email-address\n\n### Search\n* Search for files api\n* client in github actions - upload files\n\n### Server API\n* \u003cstrike\u003esupport also the nextcloud server url instead of the WebDAV url only\u003c/strike\u003e\n\n### Download\n* \u003cstrike\u003edownload folder contents example\u003c/strike\u003e\n* \u003cstrike\u003edownload folder contents to disk recursively\u003c/strike\u003e\n\n### Upload\n* \u003cstrike\u003eupload local file on disk to nextcloud\u003c/strike\u003e\n* \u003cstrike\u003eupload local folder on disk to nextcloud recursively\u003c/strike\u003e\n\n### Get Files recursively\n* \u003cstrike\u003ecommand get files recurively\u003c/strike\u003e\n* \u003cstrike\u003efilter get files recurively\u003c/strike\u003e\n* \u003cstrike\u003eexample get files recurively\u003c/strike\u003e\n\n### Access using tags\n\u003cstrike\u003e* Get files and folders by tags client.getFileSystemObjectByTags\u003c/strike\u003e\n\n### User management\nUser: \n* \u003cstrike\u003eget\u003c/strike\u003e\n* \u003cstrike\u003egetIds limit, offset, search\u003c/strike\u003e\n* \u003cstrike\u003ecreate\u003c/strike\u003e\n* \u003cstrike\u003eupdate\u003c/strike\u003e\n* \u003cstrike\u003edelete\u003c/strike\u003e\n* \u003cstrike\u003edeactivate\u003c/strike\u003e\n* \u003cstrike\u003eadd/remove group member\u003c/strike\u003e\n* \u003cstrike\u003eadd/remove group subadmin\u003c/strike\u003e\n* \u003cstrike\u003eexample in readme\u003c/strike\u003e\n* send notification\n\nUser group: \n* \u003cstrike\u003eget\u003c/strike\u003e\n* \u003cstrike\u003ecreate\u003c/strike\u003e\n* \u003cstrike\u003edelete\u003c/strike\u003e\n\n### Streams\nCreate file and get file using streams\n\n### Eventing\n* create event objects\n* start observer\n* subscribe to events and register handler functions\n* telegram support\n\n### notifications\nbasic methods are available since 1.2.0 without strong typing\n* notification object\n\n### Refactoring\n* Introduction of exception classes instead of error codes (breaking change)\n* \u003cstrike\u003eMove from codecov to coveralls\u003c/strike\u003e\n* move to eslint instead of using tslint\n* remove \"I\" from all interfaces - (breaking change)\n\n### Search\n* Search for files api\n* client in github actions - upload files\n\n## License\nApache","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhobigo%2Fnextcloud-node-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhobigo%2Fnextcloud-node-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhobigo%2Fnextcloud-node-client/lists"}