Module: classeur-downloader

npm install classeur-downloader

const downloader = require('classeur-downloader')
downloader.saveSingleFile({
    file: 'some file ID',
    userId: 'user ID',
    apiKey: 'api key',
    path: '/some/path.md',
    markdown: true
}, (error) => {
    if (error) throw error
})

// Saves all files contained in 'folder1' and 'folder2' in subdirectories of mydir/ with those same names:
downloader.saveTree({
    folders: ['folder1', 'folder2' ]
    userId: 'user ID',
    apiKey: 'api key',
    path: 'mydir/',
    markdown: true
}, (error) => {
    if (error) throw error
})

Methods

---

<static> saveSingleFile(options, callback)

Saves a single Classeur file to a specified path on the local filesystem.

This function can be used when you don't need/want to create container folders for your retrieved Classeur content.

Parameters:

Name	Type	Description
options	module:classeur-downloader~Options:DownloadSingleFile	options.folders may not be supplied to this function. options.byId is ignored by this function. File content will be saved directly to options.path no folders or other metadata files will be created. File extensions (e.g. .md) will not be added by SaveSingleFile write the extension you want into options.path directly.
callback	module:classeur-downloader~CompletionCallback	Called with an error, if one occurred, or null if all operations were successful.

Source:

• classeur-downloader.js, line 339

Example

Saving a single file's markdown content

const downloader = require('classeur-downloader')
downloader.saveSingleFile({
    files: 'some file id',
    userId: 'user ID',
    apiKey: 'api key',
    path: 'myfile.markdown',
    markdown: true
}, (error) => { if (error) throw error })

---

<static> saveTree(options, callback)

Saves Classeur files and folders to a specified path on the local filesystem.

Folders in the options.folders array will be saved as root directories (with names determined by the presence or absence of options.byId), and all of the files they contain will be saved within them. Files in options.files will be saved at the top level. If the options.byId is true, files and folders' root names will be their Classeur object IDs. Extensions will be added regardless of options.byId, depending on the value of options.addExtension.

Parameters:

Name	Type	Description
options	module:classeur-downloader~Options:DownloadFilesAndFolders	Options for which Classeur files and folders to retrieve, and how to save them.
callback	module:classeur-downloader~CompletionCallback	Called with an error, if one occurred, or null if all operations were successful.

Source:

• classeur-downloader.js, line 315

Examples

Saving files by ID

// Assume the folder with ID 'abcd' contains files with the IDs 'foo', 'bar', and 'baz'.
const downloader = require('classeur-downloader')
downloader.saveTree({
    files: [ 'quux' ],
    folders: [ 'abcde' ],
    userId: 'user ID',
    apiKey: 'api key',
    path: 'mydir/',
    folderMetadata: true
}, (error) => { if (error) throw error })
// 'mydir' will now contain:
//    quux.json
//    abcde.folder_metadata.json
//    abcde
//        \_ foo.json
//        \_ bar.json
//        \_ baz.json

Saving markdown content

// Assume the folder with ID 'abcd' has the UI-visible name 'My Folder'.
// Assume it contains two files with IDs 'foo' and 'bar', and the names 'My Stuff' and 'My Other Stuff'.
downloader.saveTree({
    folders: [ 'abcde' ],
    userId: 'user ID',
    apiKey: 'api key',
    path: 'mydir/'
    markdown: true
}, (error) => { if (error) throw error })
// 'mydir' will now contain:
//    My Folder
//        \_ My Stuff.md
//        \_ My Other Stuff.md

---

<static> showTree(options, callback)

Prints out (to the console) a tree structure of the Classeur hierarchy of supplied files and folders.

Parameters:

Name	Type	Description
options	module:classeur-downloader~Options:Global	Options for which Classeur files and folders to retrieve, and how to display them. Folders in the options.folders will be printed as root directories, and all of the files they contain will be printed. If the options.byId is true, files and folders will be printed out as 'id (name)'. Otherwise, they will be printed as 'name (id)', where 'name' is the human-readable name of an object in the Classeur UI.
callback	module:classeur-downloader~CompletionCallback	Called with an error, if one occurred, or null if all operations were successful.

Source:

• classeur-downloader.js, line 270

Type Definitions

---

CompletionCallback(error, result)

Parameters:

Name	Type	Argument	Description
error	Error	<nullable>	An throwable Error (or subclass thereof) if an error occurrend. For errors in writing files, error may be any of the errors raised by the fs module. For errors retrieving data from the Classeur API, error may be one of the Error subclasses used by classeur-api-client. Errors will be supplied to CompletionCallbacks in the same way they will be supplied to ClasseurClient~ScrubbedCallbacks. error will always be null (not undefined or another falsy value) if no error occurred.
result	*	<nullable>	Behavior of result is not defined it should not be used. Will usually be null. May sometimes contain an array of partial result objects.

Source:

• classeur-downloader.js, line 254

---

Options:DownloadFilesAndFolders

Options for configuring the bulk download behavior of classeur-downloader. All options used by module:classeur-downloader~Options:Global are also accepted.

Type:

• Object

Properties:

Name	Type	Argument	Default	Description
path	String			Destination path to save files and folders from Classeur. path must be an existent, writable folder. All files in options.files will be saved inside of path. All folders in the options.folders will be created (with names according to the byId property) in path, and the files they contain will be created within those folders. If options.overwrite is not set and name collisions occur with files being saved into path, an error will be raised and save operations will halt. Partial results may exist on the filesystem.
overwrite	boolean	<optional>	false	If true, items in path that already exist will be overwritten.
folderMetadata	boolean	<optional>	false	If true, generate JSON folder metadata for all folders in folders. If true, a single JSON file will be created next to every Classeur folder downloaded. That JSON file will be named after the folder, and will end in .folder_metadata.json. It will contain the full Classeur API metadata information for the folder. This is usually not useful, unless you are using classeur-downlaoder to back up a locally-hosted Classeur instance with the intent of using the generated files for some future restoration process.
markdown	boolean	<optional>	false	Whether or not to write markdown content for files. If true, saved files' content will be the markdown content of Classeur documents. If false, files' content will be their full JSON data from Classeur. Full JSON data objects include markdown content and other fields, and will likely not be able to be opened directly in a Markdown editor.
addExtension	boolean	<optional>	true	Whether or not appropriate extensions should be added to files written. If true, files saved with options.markdown set to true will have the .md extension, and files saved outside of markdown mode will have the .json extension. If false, extensions will not be added to files.

Source:

• classeur-downloader.js, line 223

---

Options:DownloadSingleFile

Options for configuring the single-file download behavior of classeur-downloader. All options used by module:classeur-downloader~Options:Global are also accepted.

Type:

• Object

Properties:

Name	Type	Argument	Default	Description
path	String			Destination path to save files and folders from Classeur. Must be either a nonexistent path in a writable directory, or an existent, writable file (if options.overwrite is set).
file	String	<optional>	options.files[0]	Single file ID to download and save. If not provided, options.files[0] will be used. This option is mutually exclusive with options.files.
overwrite	boolean	<optional>	false	If true, path will be overwritten with the new Classeur file content retrieved.
markdown	boolean	<optional>	false	Whether or not to write markdown content for options.file. If true, options.file's content will be that file's markdown content, visible in the Classeur UI. If false, options.file's content will be its full JSON data from Classeur. Full JSON data objects include markdown content and other fields, and will likely not be able to be opened directly in a Markdown editor.

Source:

• classeur-downloader.js, line 241

---

Options:Global

Options for configuring classeur-downloader.

Type:

• Object

Properties:

Name	Type	Argument	Default	Description
userId	String			User ID with which to connect to the Classeur API.
apiKey	String			API key to use when connecting to the Classeur API. This can be obtained by re-generating your key in the Classeur 'User' preferences pane.
files	Array.<String>	<optional>		Array of file IDs to operate on. At least one value must be supplied in options.files or options.folders, otherwise an error will be raised.
folders	Array.<String>	<optional>		Array of folder IDs to operate on. At least one value must be supplied in options.files or options.folders, otherwise an error will be raised.
byId	boolean	<optional>	false	If true, files and folders will be handled (saved or printed) by ID. If false, they will be handled by Classeur human-readable name.

Source:

• classeur-downloader.js, line 211