{"id":15136321,"url":"https://github.com/buttercup/datasources","last_synced_at":"2025-09-29T05:30:28.521Z","repository":{"id":57100724,"uuid":"125639098","full_name":"buttercup/datasources","owner":"buttercup","description":"Buttercup archive datasources","archived":true,"fork":false,"pushed_at":"2020-09-04T08:42:56.000Z","size":1169,"stargazers_count":4,"open_issues_count":3,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-30T00:55:00.843Z","etag":null,"topics":["adapter","buttercup","datasource","integration"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/buttercup.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-03-17T14:48:08.000Z","updated_at":"2023-01-28T12:58:13.000Z","dependencies_parsed_at":"2022-08-20T21:40:52.417Z","dependency_job_id":null,"html_url":"https://github.com/buttercup/datasources","commit_stats":null,"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buttercup%2Fdatasources","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buttercup%2Fdatasources/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buttercup%2Fdatasources/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/buttercup%2Fdatasources/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/buttercup","download_url":"https://codeload.github.com/buttercup/datasources/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234594021,"owners_count":18857416,"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":["adapter","buttercup","datasource","integration"],"created_at":"2024-09-26T06:20:43.764Z","updated_at":"2025-09-29T05:30:28.063Z","avatar_url":"https://github.com/buttercup.png","language":"JavaScript","readme":"# Buttercup Vault Datasources\n\u003e Datasource integrations for Buttercup vaults\n\n[![Buttercup](https://cdn.rawgit.com/buttercup-pw/buttercup-assets/6582a033/badge/buttercup-slim.svg)](https://buttercup.pw) [![Build Status](https://travis-ci.org/buttercup/datasources.svg?branch=master)](https://travis-ci.org/buttercup/datasources) [![npm version](https://badge.fury.io/js/%40buttercup%2Fdatasources.svg)](https://www.npmjs.com/package/@buttercup/datasources)\n\n## :warning: Deprecated\n\nThis repository is deprecated since [Buttercup core](https://github.com/buttercup/buttercup-core) version 4, as it is now included in the core library. It is no longer required to include this library as its functionality can be found in the [`buttercup`](https://www.npmjs.com/package/buttercup) dependency.\n\n## About\nDatasources are how Buttercup integrates with 3rd party services like Dropbox, ownCloud and Nextcloud etc.\n\nYou might want to check out the [API documentation](API.md).\n\nSupported interfaces:\n * Text: `TextDatasource`\n * Files: `FileDatasource`\n * WebDAV: `WebDAVDatasource`\n * OwnCloud: `OwnCloudDatasource`\n * Nextcloud: `NextcloudDatasource`\n * Dropbox: `DropboxDatasource`\n * Google Drive: `GoogleDriveDatasource`\n\nYou can easily add new, custom datasources by creating a new class and using `registerDatasource` to register it.\n\n## Installation\nSimply run `npm install @buttercup/datasources` to install.\n\nThis library has `@buttercup/app-env` as a peer dependency - it is required for normal function. This is usually handled in combination with `buttercup` core.\n\n## Usage\nDatasources are exported by the module so you can import only what you need:\n\n```javascript\nconst { Archive, Credentials } = require(\"buttercup\");\nconst { TextDatasource } = require(\"@buttercup/datasources\");\n\nconst tds = new TextDatasource(encryptedContent);\ntds\n    .load(Credentials.fromPassword(\"myPass\"))\n    .then(Archive.createFromHistory)\n    .then(archive =\u003e {\n        console.log(archive.toObject());\n    });\n```\n\n### Handling expiried authorisation tokens\nServices like Google Drive use OAuth tokens which may eventually expire. You can listen for these expirations and handle their renewal by registering a listener on the `AuthManager` shared instance:\n\n```javascript\nconst { AuthManager } = require(\"@buttercup/datasources\");\n\nAuthManager.getSharedManager().registerHandler(\"googledrive\", googleDriveDS =\u003e {\n    // handle refreshing or fetching of tokens\n    // attach them to datasource\n    // return a promise\n});\n```\n\nIt should be noted that when using a datasource \u0026 workspace combination (inherent when using `ArchiveManager`) you should also update the workspace in the registered handler.\n\n### Registering a custom datasource\nYou can add your own datasources by using the `registerDatasource` method. Datasources must have the following properties:\n\n * `Datasource#load(credentials)`: Load the stored contents (provided as a string) and return an array of Archive history items. It is often best to extend `TextDatasource` for this functionality.\n * `Datasource#save(historyArray, credentials)`: Save the archive history. It is often best to extend `TextDatasource` for this functionality.\n * `Datasource#toObject()`: Output an object representation of the data source. The object should contain the content and properties necessary to **serialise** and **deserialise** it. Do not store the archive content in the object. Each object should contain a `type` property that is the string name of the datasource.\n * `Datasource.fromObject(obj)`: Create a new datasource instance from an object (format should match `Datasource#toObject()`).\n * `Datasource.fromString(str)`: Should create a new datasource instance from a string. This method is usually **generic**, as shown below.\n\nThe `Datasource.fromString` method will usually just use JSON to deserialise the datasource object, and this should stay the same if `Datasource#toString` is not overridden:\n\n```javascript\nDatasource.fromString = function fromString(str, hostCredentials) {\n    return Datasource.fromObject(JSON.parse(str), hostCredentials);\n};\n```\n\nOnce you have your datasource, be sure to register it:\n\n```javascript\nregisterDatasource(\"custom\", CustomDatasource);\n```\n\n**Note**: The first argument `\"custom\"` should match the `type` property in the object presentation of the datasource.\n\n#### Implementing OAuth2\nIf your datasource uses OAuth2 and stores tokens on it, you should use the following 2 public instance properties:\n\n * `Datasource#token` - The access token\n * `Datasource#refreshToken` - The refresh token, if available\n\nButtercup looks for these internally when doing updates to vault sources (saved on the device). If tokens are updated at some point, Buttercup will read from these to ensure the local (encrypted) copy is kept up to date.\n\nIf you update tokens at any point, make sure to emit an event: `this.emit(\"updated\")`. Emit the event after the properties are updated so that Buttercup correctly performs the save process with the right values.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuttercup%2Fdatasources","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbuttercup%2Fdatasources","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuttercup%2Fdatasources/lists"}