classeur-downloader

Module: classeur-downloader

Module for downloading and listing files and folders stored in Classeur.

Source:
See:

  • The README for an overview and more usage examples.

  • The source code on GitHub.

  • The classeur-api-client module (which classeur-downloader is built around) for a lower-level way to interact with the Classeur API.

Examples

Installation

npm install classeur-downloader

Saving a single file's markdown content

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;
});

Saving directories

// 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:
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:
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:

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:

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:

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:

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: