https://github.com/buttercup/datasources
Buttercup archive datasources
https://github.com/buttercup/datasources
adapter buttercup datasource integration
Last synced: 7 months ago
JSON representation
Buttercup archive datasources
- Host: GitHub
- URL: https://github.com/buttercup/datasources
- Owner: buttercup
- License: mit
- Archived: true
- Created: 2018-03-17T14:48:08.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2020-09-04T08:42:56.000Z (over 5 years ago)
- Last Synced: 2024-10-30T00:55:00.843Z (over 1 year ago)
- Topics: adapter, buttercup, datasource, integration
- Language: JavaScript
- Size: 1.11 MB
- Stars: 4
- Watchers: 3
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Buttercup Vault Datasources
> Datasource integrations for Buttercup vaults
[](https://buttercup.pw) [](https://travis-ci.org/buttercup/datasources) [](https://www.npmjs.com/package/@buttercup/datasources)
## :warning: Deprecated
This 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.
## About
Datasources are how Buttercup integrates with 3rd party services like Dropbox, ownCloud and Nextcloud etc.
You might want to check out the [API documentation](API.md).
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.
## Installation
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.
## Usage
Datasources are exported by the module so you can import only what you need:
```javascript
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());
});
```
### Handling expiried authorisation tokens
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:
```javascript
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.
### Registering a custom datasource
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 extend `TextDatasource` for this functionality.
* `Datasource#save(historyArray, credentials)`: Save the archive history. It is often best to extend `TextDatasource` 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 a `type` property that is the string name of the datasource.
* `Datasource.fromObject(obj)`: Create a new datasource instance from an object (format should match `Datasource#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:
```javascript
Datasource.fromString = function fromString(str, hostCredentials) {
return Datasource.fromObject(JSON.parse(str), hostCredentials);
};
```
Once you have your datasource, be sure to register it:
```javascript
registerDatasource("custom", CustomDatasource);
```
**Note**: The first argument `"custom"` should match the `type` property in the object presentation of the datasource.
#### Implementing OAuth2
If your datasource uses OAuth2 and stores tokens on it, you should use the following 2 public instance properties:
* `Datasource#token` - The access token
* `Datasource#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.