Datasource integrations for Buttercup vaults
This repository is deprecated since 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
dependency.
Datasources are how Buttercup integrates with 3rd party services like Dropbox, ownCloud and Nextcloud etc.
You might want to check out the API documentation.
Supported interfaces:
- Text:
TextDatasource
- Files:
FileDatasource
- WebDAV:
WebDAVDatasource
- OwnCloud:
OwnCloudDatasource
- Nextcloud:
NextcloudDatasource
- Dropbox:
DropboxDatasource
- Google Drive:
GoogleDriveDatasource
You can easily add new, custom datasources by creating a new class and using registerDatasource
to register it.
Simply run npm install @buttercup/datasources
to install.
This library has @buttercup/app-env
as a peer dependency - it is required for normal function. This is usually handled in combination with buttercup
core.
Datasources are exported by the module so you can import only what you need:
const { Archive, Credentials } = require("buttercup");
const { TextDatasource } = require("@buttercup/datasources");
const tds = new TextDatasource(encryptedContent);
tds
.load(Credentials.fromPassword("myPass"))
.then(Archive.createFromHistory)
.then(archive => {
console.log(archive.toObject());
});
Services 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:
const { AuthManager } = require("@buttercup/datasources");
AuthManager.getSharedManager().registerHandler("googledrive", googleDriveDS => {
// handle refreshing or fetching of tokens
// attach them to datasource
// return a promise
});
It should be noted that when using a datasource & workspace combination (inherent when using ArchiveManager
) you should also update the workspace in the registered handler.
You can add your own datasources by using the registerDatasource
method. Datasources must have the following properties:
Datasource#load(credentials)
: Load the stored contents (provided as a string) and return an array of Archive history items. It is often best to extendTextDatasource
for this functionality.Datasource#save(historyArray, credentials)
: Save the archive history. It is often best to extendTextDatasource
for this functionality.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 atype
property that is the string name of the datasource.Datasource.fromObject(obj)
: Create a new datasource instance from an object (format should matchDatasource#toObject()
).Datasource.fromString(str)
: Should create a new datasource instance from a string. This method is usually generic, as shown below.
The 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:
Datasource.fromString = function fromString(str, hostCredentials) {
return Datasource.fromObject(JSON.parse(str), hostCredentials);
};
Once you have your datasource, be sure to register it:
registerDatasource("custom", CustomDatasource);
Note: The first argument "custom"
should match the type
property in the object presentation of the datasource.
If your datasource uses OAuth2 and stores tokens on it, you should use the following 2 public instance properties:
Datasource#token
- The access tokenDatasource#refreshToken
- The refresh token, if available
Buttercup 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.
If 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.