@pmesh/api v1.0.2

Pagemesh Api

This is the Javascript (Node.JS and Browser) module to easily access the Pagemesh WebSocket API. This is currently the primary API to access Pagemesh content. To better understand Pagemesh concepts, you should read the platform documentation.

Getting Started

Node.JS

From the root of your Node.JS project, execute the following command: npm install @pmesh/js-api --save

To use in your app,

const Pagemesh = require('@pmesh/api');
const handleError = (err) => console.error(err);

// Connect to the platform
const client = Pagemesh("https://api.pagemesh.com");

client.login('joel@pagemesh.com', 'my-very-secret-password').then(token => {

    // Create any kind of reading session you want. 
    const sessionSpec = {
        lang: 'en'
    };

    return client.createReadingSession(sessionSpec).then(session => {

        // Subscribe to scenes flow
        client.subscribe('session', session.id, 'scenes', action(arcs => {
            console.log("Received scene arcs", arcs);
            
            // Do something with these damn arcs!
        }));

        return client.loadSessionScenes(session.id)
    });
}).catch(handleError);

Browser

Add this script tag to your header.

<script src="https://raw.githubusercontent.com/Pagemesh/js-api/master/dist/pagemesh-api.umd.js"></script>

Authentication

You need to be authenticated to access most (other than registerUser) commands. You need a Pagemesh account. You can request one using the registerUser command, providing the following fields:

// Using promise style
client.registerUser({
    username: 'me',
    email: 'me@pagemesh.com',
    password: 'my-password-in-plain-text'
}).then(user => console.log('New User account:', user)).catch(err => console.error(err));

// Using async/await style
try {
    let user = await client.registerUser({
        username: 'me',
        email: 'me@pagemesh.com',
        password: 'my-password-in-plain-text'
    });
    console.log('New User account:', user);
}
catch(err) {
    console.error(err);
}

During the ALPHA and BETA phases, accounts are reviewed manually. Someone from our team will contact you by email to complete the registration process. Once your account is activated, you'll be able to obtain a token.

Getting a token

You need to pass a token in all command payload requiring authentication. You can retrieve a token by sending your credentials to the platform. This token will be good for 1h.

try {
    let token = await client.login('me@pagemesh.com', 'my-password-in-plain-text');
    let sessions = await client.listReadingSessions();
    console.log("Use the list of sessions...", sessions);
}
catch(err) {
    console.error("Unable to authenticate", err);
}

In future releases, refresh tokens will be implemented to automatically create a new access token without having to resend credentials.

Available Commands

All these commands are accessible directly through the Pagemesh client instance. They are grouped in categories for clarity only.

Sessions

    { 
        loadSessionScenes(session, { reply = false }),
        listProofs(scene),
        recordTransition(session, from, to, type, rating, last = false),
        updateReadingSession(id, ...updatedFields),
        saveScene(session, op, arc, scene, comment),
        getSessionHistory(session),
        jumpTo(session, from, to),
        listReadingSessions(q),
        createReadingSession(sessionSpec),
        getSceneDetails(id),
        getArcDetails(id),
        addSessionToFavorite(id),
        removeSessionFromFavorite(id),
        deleteReadingSession(id)
    }

Universes

    { 
        lookupAnchor(text, universe),
        loadUniverse(id),
        loadUniverseBrowserData(id, filter),
        updateUniverse(universe),
        deleteUniverse(id),
        listUniverses(predicate),
        addUniverseToFavorite(id),
        removeUniverseFromFavorite(id)
    }

Activities

    { 
        loadSessionScenes(session, { reply = false }),
        listProofs(scene),
        acceptProof(scene, proof),
        rejectProof(scene, proof),
        listActivities(predicate),
        loadActivity(id),
        updateActivity(activity, read = true)
    }

Users

    { 
        login(usernameOrEmail, password),
        getCurrentUser(),
        findUsers(query),
        registerUser(data)
    }

Analytics

    { 
        loadDashboard(key = 'default')
    }