Skip to content
This repository has been archived by the owner on Sep 6, 2020. It is now read-only.

Latest commit

 

History

History
1133 lines (814 loc) · 46.4 KB

API.md

File metadata and controls

1133 lines (814 loc) · 46.4 KB

Modules

ButtercupDatasources

The primary module

Classes

BoxDatasourceWebDAVDatasource

Datasource for Box archives

DropboxDatasourceTextDatasource

Datasource for Dropbox archives

FileDatasourceTextDatasource

File datasource for loading and saving files

NextcloudDatasourceOwnCloudDatasource

Datasource for Nextcloud archives

OwnCloudDatasourceWebDAVDatasource

Datasource for OwnCloud archives

TextDatasource

Datasource for text input and output

WebDAVDatasourceTextDatasource

WebDAV datasource for reading and writing remote archives

Functions

fireInstantiationHandlers(datasource)

Execute all datasource postprocessors

objectToDatasource(obj, [hostCredentials])null | TextDatasource

Create a datasource from an object The object must have the required properties (as output by the corresponding toObject call of the datasource).

registerDatasource(datasourceType, DSClass)

Register a new datasource This is called internally by the built-in datasources, but should be called if a custom datasource is used.

registerDatasourcePostProcessor(callback)RegisterDatasourcePostProcessorResult

Register a post-processor for a datasource being instantiated

stringToDatasource(str, [hostCredentials])null | TextDatasource

Create a datasource from a string

Typedefs

RegisterDatasourcePostProcessorResult : Object

ButtercupDatasources

The primary module

BoxDatasource ⇐ WebDAVDatasource

Datasource for Box archives

Kind: global class
Extends: WebDAVDatasource

new BoxDatasource(resourcePath, credentials)

Datasource for Box connections

Param Type Description
resourcePath String The file path
credentials Credentials The credentials (username/password) for Box

boxDatasource.client : Object

The WebDAV client instance

Kind: instance property of BoxDatasource

boxDatasource.endpoint : String

The remote WebDAV endpoint

Kind: instance property of BoxDatasource

boxDatasource.path : String

The remote archive path

Kind: instance property of BoxDatasource

boxDatasource.hasContent : Boolean

Whether the datasource currently has content Used to check if the datasource has encrypted content that can be loaded. May be used when attempting to open a vault in offline mode.

Kind: instance property of BoxDatasource

boxDatasource.toObject() ⇒ Object

Output the datasource as an object

Kind: instance method of BoxDatasource
Overrides: toObject
Returns: Object - An object describing the datasource

boxDatasource.load(credentials) ⇒ Promise.<Array.<String>>

Load archive history from the datasource

Kind: instance method of BoxDatasource
Returns: Promise.<Array.<String>> - A promise resolving archive history

Param Type Description
credentials Credentials The credentials for archive decryption

boxDatasource.save(history, credentials) ⇒ Promise

Save archive contents to the WebDAV service

Kind: instance method of BoxDatasource
Returns: Promise - A promise resolving when the save is complete

Param Type Description
history Array.<String> Archive history
credentials Credentials The credentials for encryption

boxDatasource.supportsRemoteBypass() ⇒ Boolean

Whether or not the datasource supports bypassing remote fetch operations

Kind: instance method of BoxDatasource
Returns: Boolean - True if content can be set to bypass fetch operations, false otherwise

boxDatasource.setContent(content) ⇒ TextDatasource

Set the text content

Kind: instance method of BoxDatasource
Returns: TextDatasource - Self

Param Type Description
content String The encrypted text content

boxDatasource.toString() ⇒ String

Output the datasource configuration as a string

Kind: instance method of BoxDatasource
Returns: String - The string representation of the datasource

BoxDatasource.fromObject(obj, hostCredentials) ⇒ BoxDatasource

Create an instance from an object

Kind: static method of BoxDatasource
Returns: BoxDatasource - A new instance
Throws:

  • Error Throws if credentials are not provided
  • Error Throws if the type specified is invalid
Param Type Description
obj Object The object representation
hostCredentials Credentials The box account credentials

BoxDatasource.fromString(str, hostCredentials) ⇒ BoxDatasource

Create an instance from a string

Kind: static method of BoxDatasource
Returns: BoxDatasource - A new instance
See: BoxDatasource.fromObject

Param Type Description
str String The string representation
hostCredentials Credentials Credentials for the box account

DropboxDatasource ⇐ TextDatasource

Datasource for Dropbox archives

Kind: global class
Extends: TextDatasource

new DropboxDatasource(accessToken, resourcePath)

Datasource for Dropbox accounts

Param Type Description
accessToken String The dropbox access token
resourcePath String The file path

dropboxDatasource.hasContent : Boolean

Whether the datasource currently has content Used to check if the datasource has encrypted content that can be loaded. May be used when attempting to open a vault in offline mode.

Kind: instance property of DropboxDatasource

dropboxDatasource.load(credentials) ⇒ Promise.<Array.<String>>

Load an archive from the datasource

Kind: instance method of DropboxDatasource
Overrides: load
Returns: Promise.<Array.<String>> - A promise that resolves archive history

Param Type Description
credentials Credentials The credentials for decryption

dropboxDatasource.save(history, credentials) ⇒ Promise

Save an archive using the datasource

Kind: instance method of DropboxDatasource
Overrides: save
Returns: Promise - A promise that resolves when saving has completed

Param Type Description
history Array.<String> The archive history to save
credentials Credentials The credentials to save with

dropboxDatasource.supportsRemoteBypass() ⇒ Boolean

Whether or not the datasource supports bypassing remote fetch operations

Kind: instance method of DropboxDatasource
Overrides: supportsRemoteBypass
Returns: Boolean - True if content can be set to bypass fetch operations, false otherwise

dropboxDatasource.toObject() ⇒ Object

Output the datasource as an object

Kind: instance method of DropboxDatasource
Overrides: toObject
Returns: Object - An object describing the datasource

dropboxDatasource.setContent(content) ⇒ TextDatasource

Set the text content

Kind: instance method of DropboxDatasource
Returns: TextDatasource - Self

Param Type Description
content String The encrypted text content

dropboxDatasource.toString() ⇒ String

Output the datasource configuration as a string

Kind: instance method of DropboxDatasource
Returns: String - The string representation of the datasource

DropboxDatasource.fromObject(obj) ⇒ DropboxDatasource

Create a new instance from an object

Kind: static method of DropboxDatasource
Returns: DropboxDatasource - A new instance
Throws:

  • Error Throws if the type is invalid
Param Type Description
obj Object The object representation

DropboxDatasource.fromString(str) ⇒ DropboxDatasource

Create a new instance from a string

Kind: static method of DropboxDatasource
Returns: DropboxDatasource - A new instance
Throws:

  • Error Throws if the type is invalid
Param Type Description
str String The string representation

FileDatasource ⇐ TextDatasource

File datasource for loading and saving files

Kind: global class
Extends: TextDatasource

new FileDatasource(filename)

Constructor for the file datasource

Param Type Description
filename string The filename to load and save

fileDatasource.path : String

The file path

Kind: instance property of FileDatasource

fileDatasource.hasContent : Boolean

Whether the datasource currently has content Used to check if the datasource has encrypted content that can be loaded. May be used when attempting to open a vault in offline mode.

Kind: instance property of FileDatasource

fileDatasource.load(credentials) ⇒ Promise.<Array.<String>>

Load from the filename specified in the constructor using a password

Kind: instance method of FileDatasource
Overrides: load
Returns: Promise.<Array.<String>> - A promise resolving with archive history

Param Type Description
credentials Credentials The credentials for decryption

fileDatasource.save(history, credentials) ⇒ Promise

Save archive history to a file

Kind: instance method of FileDatasource
Overrides: save
Returns: Promise - A promise that resolves when saving is complete

Param Type Description
history Array.<String> The archive history to save
credentials Credentials The credentials to save with

fileDatasource.supportsRemoteBypass() ⇒ Boolean

Whether or not the datasource supports bypassing remote fetch operations

Kind: instance method of FileDatasource
Overrides: supportsRemoteBypass
Returns: Boolean - True if content can be set to bypass fetch operations, false otherwise

fileDatasource.toObject() ⇒ Object

Output the datasource as an object

Kind: instance method of FileDatasource
Overrides: toObject
Returns: Object - An object describing the datasource

fileDatasource.setContent(content) ⇒ TextDatasource

Set the text content

Kind: instance method of FileDatasource
Returns: TextDatasource - Self

Param Type Description
content String The encrypted text content

fileDatasource.toString() ⇒ String

Output the datasource configuration as a string

Kind: instance method of FileDatasource
Returns: String - The string representation of the datasource

FileDatasource.fromObject(obj) ⇒ FileDatasource

Create an instance from an object

Kind: static method of FileDatasource
Returns: FileDatasource - A new instance
Throws:

  • Error Throws for an invalid type specification
Param Type Description
obj Object The object representation of a datasource

FileDatasource.fromString(str) ⇒ FileDatasource

Create an instance from a string

Kind: static method of FileDatasource
Returns: FileDatasource - A new instance
See: FileDatasource.fromObject

Param Type Description
str String The string representation

NextcloudDatasource ⇐ OwnCloudDatasource

Datasource for Nextcloud archives

Kind: global class
Extends: OwnCloudDatasource

new NextcloudDatasource()

Constructor for the datasource

nextcloudDatasource.client : Object

The WebDAV client instance

Kind: instance property of NextcloudDatasource

nextcloudDatasource.endpoint : String

The remote WebDAV endpoint

Kind: instance property of NextcloudDatasource

nextcloudDatasource.path : String

The remote archive path

Kind: instance property of NextcloudDatasource

nextcloudDatasource.hasContent : Boolean

Whether the datasource currently has content Used to check if the datasource has encrypted content that can be loaded. May be used when attempting to open a vault in offline mode.

Kind: instance property of NextcloudDatasource

nextcloudDatasource.toObject() ⇒ Object

Output the datasource as an object

Kind: instance method of NextcloudDatasource
Overrides: toObject
Returns: Object - An object describing the datasource

nextcloudDatasource.load(credentials) ⇒ Promise.<Array.<String>>

Load archive history from the datasource

Kind: instance method of NextcloudDatasource
Returns: Promise.<Array.<String>> - A promise resolving archive history

Param Type Description
credentials Credentials The credentials for archive decryption

nextcloudDatasource.save(history, credentials) ⇒ Promise

Save archive contents to the WebDAV service

Kind: instance method of NextcloudDatasource
Returns: Promise - A promise resolving when the save is complete

Param Type Description
history Array.<String> Archive history
credentials Credentials The credentials for encryption

nextcloudDatasource.supportsRemoteBypass() ⇒ Boolean

Whether or not the datasource supports bypassing remote fetch operations

Kind: instance method of NextcloudDatasource
Returns: Boolean - True if content can be set to bypass fetch operations, false otherwise

nextcloudDatasource.setContent(content) ⇒ TextDatasource

Set the text content

Kind: instance method of NextcloudDatasource
Returns: TextDatasource - Self

Param Type Description
content String The encrypted text content

nextcloudDatasource.toString() ⇒ String

Output the datasource configuration as a string

Kind: instance method of NextcloudDatasource
Returns: String - The string representation of the datasource

NextcloudDatasource.fromObject(obj, [hostCredentials]) ⇒ NextcloudDatasource

Create a new instance from an object

Kind: static method of NextcloudDatasource
Returns: NextcloudDatasource - A new instance
Throws:

  • Error Throws for an invalid type specification
Param Type Description
obj Object The object representation of an instance
[hostCredentials] Credentials The remote server credentials

NextcloudDatasource.fromString(str, [hostCredentials]) ⇒ NextcloudDatasource

Create a new instance from a string

Kind: static method of NextcloudDatasource
Returns: NextcloudDatasource - A new instance
Throws:

  • Error Throws for an invalid type specification
Param Type Description
str String The string representation of an instance
[hostCredentials] Credentials The remote server credentials

OwnCloudDatasource ⇐ WebDAVDatasource

Datasource for OwnCloud archives

Kind: global class
Extends: WebDAVDatasource

new OwnCloudDatasource(owncloudURL, resourcePath, [credentials])

Datasource for Owncloud connections

Param Type Description
owncloudURL String The URL to the owncloud instance, without "remote.php/webdav" etc.
resourcePath String The file path
[credentials] Credentials The credentials (username/password) for owncloud

ownCloudDatasource.client : Object

The WebDAV client instance

Kind: instance property of OwnCloudDatasource

ownCloudDatasource.endpoint : String

The remote WebDAV endpoint

Kind: instance property of OwnCloudDatasource

ownCloudDatasource.path : String

The remote archive path

Kind: instance property of OwnCloudDatasource

ownCloudDatasource.hasContent : Boolean

Whether the datasource currently has content Used to check if the datasource has encrypted content that can be loaded. May be used when attempting to open a vault in offline mode.

Kind: instance property of OwnCloudDatasource

ownCloudDatasource.toObject() ⇒ Object

Output the datasource as an object

Kind: instance method of OwnCloudDatasource
Overrides: toObject
Returns: Object - An object describing the datasource

ownCloudDatasource.load(credentials) ⇒ Promise.<Array.<String>>

Load archive history from the datasource

Kind: instance method of OwnCloudDatasource
Returns: Promise.<Array.<String>> - A promise resolving archive history

Param Type Description
credentials Credentials The credentials for archive decryption

ownCloudDatasource.save(history, credentials) ⇒ Promise

Save archive contents to the WebDAV service

Kind: instance method of OwnCloudDatasource
Returns: Promise - A promise resolving when the save is complete

Param Type Description
history Array.<String> Archive history
credentials Credentials The credentials for encryption

ownCloudDatasource.supportsRemoteBypass() ⇒ Boolean

Whether or not the datasource supports bypassing remote fetch operations

Kind: instance method of OwnCloudDatasource
Returns: Boolean - True if content can be set to bypass fetch operations, false otherwise

ownCloudDatasource.setContent(content) ⇒ TextDatasource

Set the text content

Kind: instance method of OwnCloudDatasource
Returns: TextDatasource - Self

Param Type Description
content String The encrypted text content

ownCloudDatasource.toString() ⇒ String

Output the datasource configuration as a string

Kind: instance method of OwnCloudDatasource
Returns: String - The string representation of the datasource

OwnCloudDatasource.fromObject(obj, [hostCredentials]) ⇒ OwnCloudDatasource

Create an instance from an object

Kind: static method of OwnCloudDatasource
Returns: OwnCloudDatasource - A new instance
Throws:

  • Error Throws for an invalid type specification
Param Type Description
obj Object The object representation of the datasource
[hostCredentials] Credentials Remote server credentials

OwnCloudDatasource.fromString(str, [hostCredentials]) ⇒ OwnCloudDatasource

Create an instance from a string

Kind: static method of OwnCloudDatasource
Returns: OwnCloudDatasource - A new instance
Throws:

  • Error Throws for an invalid type specification
Param Type Description
str String The string representation of the datasource
[hostCredentials] Credentials The remote server credentials

TextDatasource

Datasource for text input and output

Kind: global class

new TextDatasource(content)

Constructor for the text datasource

Param Type Description
content string The content to load from

textDatasource.hasContent : Boolean

Whether the datasource currently has content Used to check if the datasource has encrypted content that can be loaded. May be used when attempting to open a vault in offline mode.

Kind: instance property of TextDatasource

textDatasource.load(credentials) ⇒ Promise.<Array.<String>>

Load from the stored content using a password to decrypt

Kind: instance method of TextDatasource
Returns: Promise.<Array.<String>> - A promise that resolves with decrypted history
Throws:

  • Error Rejects if content is empty
Param Type Description
credentials Credentials The password or Credentials instance to decrypt with

textDatasource.save(history, credentials) ⇒ Promise.<string>

Save archive contents with a password

Kind: instance method of TextDatasource
Returns: Promise.<string> - A promise resolving with the encrypted content

Param Type Description
history Array.<String> Archive history to save
credentials Credentials The Credentials instance to encrypt with

textDatasource.setContent(content) ⇒ TextDatasource

Set the text content

Kind: instance method of TextDatasource
Returns: TextDatasource - Self

Param Type Description
content String The encrypted text content

textDatasource.supportsRemoteBypass() ⇒ Boolean

Whether or not the datasource supports bypassing remote fetch operations

Kind: instance method of TextDatasource
Returns: Boolean - True if content can be set to bypass fetch operations, false otherwise

textDatasource.toObject() ⇒ Object

Output the datasource as an object

Kind: instance method of TextDatasource
Returns: Object - The object representation

textDatasource.toString() ⇒ String

Output the datasource configuration as a string

Kind: instance method of TextDatasource
Returns: String - The string representation of the datasource

WebDAVDatasource ⇐ TextDatasource

WebDAV datasource for reading and writing remote archives

Kind: global class
Extends: TextDatasource

new WebDAVDatasource(endpoint, webDAVPath, [credentials])

Constructor for the datasource

Param Type Description
endpoint string URL for the WebDAV service (without resource path)
webDAVPath string Resource path on the WebDAV service
[credentials] Credentials Credentials (username/password) for the WebDAV service

webDAVDatasource.client : Object

The WebDAV client instance

Kind: instance property of WebDAVDatasource

webDAVDatasource.endpoint : String

The remote WebDAV endpoint

Kind: instance property of WebDAVDatasource

webDAVDatasource.path : String

The remote archive path

Kind: instance property of WebDAVDatasource

webDAVDatasource.hasContent : Boolean

Whether the datasource currently has content Used to check if the datasource has encrypted content that can be loaded. May be used when attempting to open a vault in offline mode.

Kind: instance property of WebDAVDatasource

webDAVDatasource.load(credentials) ⇒ Promise.<Array.<String>>

Load archive history from the datasource

Kind: instance method of WebDAVDatasource
Overrides: load
Returns: Promise.<Array.<String>> - A promise resolving archive history

Param Type Description
credentials Credentials The credentials for archive decryption

webDAVDatasource.save(history, credentials) ⇒ Promise

Save archive contents to the WebDAV service

Kind: instance method of WebDAVDatasource
Overrides: save
Returns: Promise - A promise resolving when the save is complete

Param Type Description
history Array.<String> Archive history
credentials Credentials The credentials for encryption

webDAVDatasource.supportsRemoteBypass() ⇒ Boolean

Whether or not the datasource supports bypassing remote fetch operations

Kind: instance method of WebDAVDatasource
Overrides: supportsRemoteBypass
Returns: Boolean - True if content can be set to bypass fetch operations, false otherwise

webDAVDatasource.toObject() ⇒ Object

Output the datasource as an object

Kind: instance method of WebDAVDatasource
Overrides: toObject
Returns: Object - An object describing the datasource

webDAVDatasource.setContent(content) ⇒ TextDatasource

Set the text content

Kind: instance method of WebDAVDatasource
Returns: TextDatasource - Self

Param Type Description
content String The encrypted text content

webDAVDatasource.toString() ⇒ String

Output the datasource configuration as a string

Kind: instance method of WebDAVDatasource
Returns: String - The string representation of the datasource

WebDAVDatasource.fromObject(obj, [hostCredentials])

Create an instance from an object

Kind: static method of WebDAVDatasource

Param Type Description
obj Object The WebDAV info object
[hostCredentials] Credentials The server credentials

WebDAVDatasource.fromString(str, [hostCredentials])

Create an instance from a string

Kind: static method of WebDAVDatasource

Param Type Description
str String The string representation of the datasource
[hostCredentials] Credentials The server credentials

fireInstantiationHandlers(datasource)

Execute all datasource postprocessors

Kind: global function

Param Type Description
datasource TextDatasource The datasource instance

objectToDatasource(obj, [hostCredentials]) ⇒ null | TextDatasource

Create a datasource from an object The object must have the required properties (as output by the corresponding toObject call of the datasource).

Kind: global function
Returns: null | TextDatasource - A datasource instance or null of none found
Access: public

Param Type Description
obj Object The object
[hostCredentials] Credentials Credentials instance for remote host authentication (not required for File/Text datasources)

registerDatasource(datasourceType, DSClass)

Register a new datasource This is called internally by the built-in datasources, but should be called if a custom datasource is used.

Kind: global function
Access: public

Param Type Description
datasourceType String The name (slug) of the datasource
DSClass Object The class for the new datasource

registerDatasourcePostProcessor(callback) ⇒ RegisterDatasourcePostProcessorResult

Register a post-processor for a datasource being instantiated

Kind: global function
Returns: RegisterDatasourcePostProcessorResult - The result of the registration

Param Type Description
callback function The callback to execute with the instantiated datasource

stringToDatasource(str, [hostCredentials]) ⇒ null | TextDatasource

Create a datasource from a string

Kind: global function
Returns: null | TextDatasource - A new datasource instance or null of not found
Access: public
See: objectToDatasource

Param Type Description
str String The string representation of a datasource, as output by the toString method on the corresponding datasource
[hostCredentials] Credentials The remote authentication credentials

RegisterDatasourcePostProcessorResult : Object

Kind: global typedef
Properties

Name Type Description
remove function Function to call to remove the handler