classeur-api-client

Node.js client for the REST API of http://classeur.io/

Classeur is an online writing and collaboration platform by the authors of StackEdit. In addition to a web and desktop UI, it provides a read-only REST API. classeur-api-client is a simple object-oriented Node.js library for interacting with that API.

This is alpha software: this is the first release of this client library. While I've done my best to write thorough unit and integration tests, there may be bugs, and the API is subject to change in future versions.

NPM package versions will follow Semantic Versioning.

API Documentation

API documentation is available at http://zbentley.github.io/classeur-api-client

That documentation is generated via JSDoc information written alongside this module's code. Bugs or issues with the documentation should be reported in the same way as issues with the module's functionality.

Installation

npm install classeur-api-client

Usage

Getting Started

This module provides an object-oriented interface to the Classeur API. Once it is installed, you should be able to to write:

const ClasseurClient = require('classeur-api-client');
const myClient = new ClasseurClient({ userId: "my id", apiKey: "my key" });

...and be up and running.

Getting Files

For more information on method arguments, return types, etc., see the full API Documentation.

ClasseurClient#GetFile can be used to retrieve single files:

const fs = require('fs'),
    myClient = new ClasseurClient({ userId: "my id", apiKey: "my key" });
myClient.getFile("some file ID", function(error, result) {
    if ( error ) {
        console.log(`Oh no! Something went wrong: ${error}`);
    } else {
        console.log(`Saving file ${result.name}...`);
        fs.writeFile("/path/to/file.md", result.content.text, function(error, result) {
        ...
        });
    }
});

ClasseurClient#getFiles or getFolders can be used to get more than one file or folder at a time (at the cost of one API hit, done in parallel, per file):

myClient.getFiles(["id1", "id2", ... ], function(error, results) {
    if ( error ) {
        console.log(`Oh no! Something went wrong: ${error}`);
    } else {
        results.forEach(function (result) {
            console.log(`Found file ${result.name} with ${result.content.text}`);
        });
    }
});

getFiles and getFolders are multisignature functions, which means they can also be called with lists of parameters, e.g. GetFiles("id1", "id2", ..., function(error, result) { ... }). This does not depend on ES6 rest parameters.

Getting Metadata

Metadata getters (e.g. getUserMetadata, or getFoldersMetadata) work in much the same way as getFile and getFiles. There are single versions:

myClient.getUserMetadata("some user id", function(error, result) {
    if ( error ) {
        console.log(`Oh no! Something went wrong: ${error}`);
    } else {
        console.log(`User id ${result.id}'s real name is ${result.name}`);
    }
});

. . . and plural versions:

myClient.getFilesMetadata(["file id 1", "file id 2" ... ], function(error, result) {
    if ( error ) {
        console.log(`Oh no! Something went wrong: ${error}`);
    } else {
        results.forEach(function (result) {
            console.log(`File ${result.name} was last updated at ${result.updated}`);
        });
    }
});

Note on IDs

The REST API operates only by ID. You cannot get any information by human-visible name; you have to use the object IDs of files and folders to retrieve them using classeur-api-client. The IDs of files are visible in the URI bar of Classeur (if you are using Classeur in a browser). IDs of other objects, including files, are visible via the "properties" windows of those objects in the Classeur UI.

Making Changes

See the Developer's Guide for more info.

Bugs

File a GitHub issue on the main repository.