trello-snapshots

A snapshotting library for polling Trello and persisting serialised versions of boards to disk.

Can be used as a backup method for saving snapshots of boards (note - only a large subset of board data is stored) or retrieving data from boards at regular intervals.

Usage

To use trello-snapshots add the npm package to your project.

npm i trello-snapshots

You will need to get a Trello API key and token. To allow trello-snapshots to pull data you will need a read token. To get your key and token follow the steps:

1. Sign in to Trello and navigate to https://trello.com/app-key.
2. Navigate to https://trello.com/1/connect?key=...&name=MyApp&response_type=token&scope=read, substituting your key in.

Basic Usage

const Snapshotter = require('trello-snapshots')

let mySnapshotter = new Snapshotter(key, token, 'my board', './snapshots');
mySnapshotter.start();

API Reference

Classes

FileStore ⇐ CoEvents

Class representing a FileStore, contains methods to query the file store.

Snapshotter ⇐ FileStore

Class representing a snapshotter, contains methods to poll trello and event/return data at set intervals.

Events

"file-write" (data, date)

"preSnapshot" (date, count)

"snapshot" (board, date, count)

Typedefs

preCondition ⇒ boolean

preCondition handler, is given the time of the snapshot and count, can return false to stop the current snapshot from continuing.

onSnapshot : function

onSnapshot handler, is given the board, time of the snapshot and count.

FileStore ⇐ CoEvents

Class representing a FileStore, contains methods to query the file store.

Kind: global class
Extends: CoEvents
Access: public

• FileStore ⇐ CoEvents
  • new FileStore(path)
  • .readAll() ⇒ Array.<{timestamp: date, data: json}>
  • .read(date1, date2) ⇒ Array.<{timestamp: date, data: json}>
  • .readLastX(count) ⇒ Array.<{timestamp: date, data: json}>
  • .readLatest() ⇒ Object
  • .write(data, [date])

new FileStore(path)

Creates a FileStore

Param	Type	Description
path	string	The path to store files at.

fileStore.readAll() ⇒ Array.<{timestamp: date, data: json}>

Reads all the files in the file store.

Kind: instance method of FileStore
Returns: Array.<{timestamp: date, data: json}> - The files data and timestamp.
Access: public
Generator:

fileStore.read(date1, date2) ⇒ Array.<{timestamp: date, data: json}>

Reads files from the file store. If only date1 is supplied then only files created with that timestamp are returned. If both dates are supplied then files within the date range are returned.

Kind: instance method of FileStore
Returns: Array.<{timestamp: date, data: json}> - The files data and timestamp.
Throws:

• A date must be provided.
• An invalid first date was provided.

Access: public
Thows: An invalid second date was provided.
Generator:

Param	Type	Description
date1	date	The start or exact match date.
date2	date	The end date.

fileStore.readLastX(count) ⇒ Array.<{timestamp: date, data: json}>

Reads the last x number of files in the file store.

Kind: instance method of FileStore
Returns: Array.<{timestamp: date, data: json}> - The files data and timestamp.
Access: public
Generator:

Param	Type	Description
count	number	The last x number of files to return.

fileStore.readLatest() ⇒ Object

Reads the lastest file in the file store.

Kind: instance method of FileStore
Returns: Object - The file's data and timestamp.
Access: public
Generator:

fileStore.write(data, [date])

Write into the file store. Events out 'file-write'.

Kind: instance method of FileStore
Emits: file-write
Access: public
Generator:

Param	Type	Default	Description
data	*		The data to write to file.
[date]	date	new Date()	The date of the file write.

Snapshotter ⇐ FileStore

Class representing a snapshotter, contains methods to poll trello and event/return data at set intervals.

Kind: global class
Extends: FileStore
Access: public

• Snapshotter ⇐ FileStore
  • new Snapshotter(key, token, boardName, [fileStorePath])
  • .snapshotRate
  • .persistRate
  • .preCondition
  • .onSnapshot
  • .start()
  • .stop()
  • .readAll() ⇒ Array.<{timestamp: date, data: json}>
  • .read(date1, date2) ⇒ Array.<{timestamp: date, data: json}>
  • .readLastX(count) ⇒ Array.<{timestamp: date, data: json}>
  • .readLatest() ⇒ Object
  • .write(data, [date])

new Snapshotter(key, token, boardName, [fileStorePath])

Create a Snapshotter.

Param	Type	Default	Description
key	string		Trello Api key.
token	string		Trello Api token.
boardName	string		The name of the board to snapshot on Trello.
[fileStorePath]	string	"../Data"	The file path to save snapshots at.

snapshotter.snapshotRate

Sets the snapshot rate, the rate at which the snapshotter will poll the trello board. If 0 then .start() will only poll once.

Kind: instance property of Snapshotter
Throws:

• Snapshot rate must be an integer.

Access: public

Param	Type	Default	Description
[rate]	number	1200000	The rate in milliseconds (default 20 minutes).

snapshotter.persistRate

Sets the persist rate, the rate at which the snapshotter save the result from polling the board. If 0 then snapshots are neve saved.

Kind: instance property of Snapshotter
Throws:

• Persist rate must be an integer.

Access: public

Param	Type	Default	Description
[rate]	number	1	The rate in milliseconds.

snapshotter.preCondition

Setter for the handler to be called when a poll begins before data is pulled..

Kind: instance property of Snapshotter
Throws:

• Pre-condition handler must be a function or undefined.

Access: public

Param	Type	Description
handler	preCondition	The handler function.

snapshotter.onSnapshot

Setter for the handler to be called when a poll completes.

Kind: instance property of Snapshotter
Throws:

• Snapshot handler must be a function or undefined.

Access: public

Param	Type	Description
handler	onSnapshot	The handler function.

snapshotter.start()

Starts polling the trello board with the settings defined on the Snapshotter class. Resets count to 0.

Kind: instance method of Snapshotter
Emits: preSnapshot, event:snapshots
Access: public

snapshotter.stop()

Stops polling of the trello board.

Kind: instance method of Snapshotter
Access: public

snapshotter.readAll() ⇒ Array.<{timestamp: date, data: json}>

Reads all the files in the file store.

Kind: instance method of Snapshotter
Returns: Array.<{timestamp: date, data: json}> - The files data and timestamp.
Access: public
Generator:

snapshotter.read(date1, date2) ⇒ Array.<{timestamp: date, data: json}>

Reads files from the file store. If only date1 is supplied then only files created with that timestamp are returned. If both dates are supplied then files within the date range are returned.

Kind: instance method of Snapshotter
Returns: Array.<{timestamp: date, data: json}> - The files data and timestamp.
Throws:

• A date must be provided.
• An invalid first date was provided.

Access: public
Thows: An invalid second date was provided.
Generator:

Param	Type	Description
date1	date	The start or exact match date.
date2	date	The end date.

snapshotter.readLastX(count) ⇒ Array.<{timestamp: date, data: json}>

Reads the last x number of files in the file store.

Kind: instance method of Snapshotter
Returns: Array.<{timestamp: date, data: json}> - The files data and timestamp.
Access: public
Generator:

Param	Type	Description
count	number	The last x number of files to return.

snapshotter.readLatest() ⇒ Object

Reads the lastest file in the file store.

Kind: instance method of Snapshotter
Returns: Object - The file's data and timestamp.
Access: public
Generator:

snapshotter.write(data, [date])

Write into the file store. Events out 'file-write'.

Kind: instance method of Snapshotter
Emits: file-write
Access: public
Generator:

Param	Type	Default	Description
data	*		The data to write to file.
[date]	date	new Date()	The date of the file write.

"file-write" (data, date)

Kind: event emitted

Param	Type	Description
data	json	The contents of the file.
date	data	The date of the snapshot.

"preSnapshot" (date, count)

Kind: event emitted

Param	Type	Description
date	data	The date of the snapshot.
count	number	The count of the snapshot.

"snapshot" (board, date, count)

Kind: event emitted

Param	Type	Description
board	GoodTrelloBoard	The board itself.
date	data	The date of the snapshot.
count	number	The count of the snapshot.

preCondition ⇒ boolean

preCondition handler, is given the time of the snapshot and count, can return false to stop the current snapshot from continuing.

Kind: global typedef
Returns: boolean - Return false to stop the current snapshot.

Param	Type	Description
snapshotTime	date	The time that the snapshot was taken.
counts	number	The count of the snapshot (count since .start() was called).

onSnapshot : function

onSnapshot handler, is given the board, time of the snapshot and count.

Kind: global typedef

Param	Type	Description
board	GoodTrelloBoard	The board data.
snapshotTime	date	The time that the snapshot was taken.
counts	number	The count of the snapshot (count since .start() was called).

##Tests Run tests using npm test.

##Contribution Feel free to extend, use and contribute to the project! Test coverage should be coming soon. However due to the lack of test coverage, there may be bugs present, please raise an issue or PR.