Designed as a non-intrusive middleware. Pocket offers :

• Automatic API generation
• Schema validation (pocket schema)
• User and session management
• Admin panel
• Multi-db support (Currently Mongo and Nedb)
• File uploads
• Server stats

Features planned:

• Logs
• API Keys
• Plugin support

Table of Contents generated with DocToc

• Getting started
• Configuration
  • Datastores
    • Mongo
    • Disk
  • Filestores
    • Disk
• Using the CMS
  • Resources
    • Methods
      • Creating a record
      • Updating a record
      • Updating multiple records
      • Reading a single record
      • Reading multiple records
      • Removing a record
      • Removing multiple records
      • Attaching a file to a record
      • Deleting an attachment
      • Reading an attachment
  • Schema
    • CMS properties
    • Indexes
    • Hooks
  • Users
    • Groups
  • REST API
    • Authentication
    • Resource management
    • ACL
      • Admins
      • Schema access configuration
      • Group access configuration

Firstly, install pocket-cms as a dependency of your project.

npm install --save pocket-cms

In your Node project, hook pocket to your express server :

var express = require("express");
var Pocket = require("pocket-cms");

var app = express();
var cms = new Pocket();

app.use(cms.middleware());

app.listen(3000, () => { console.log('Server running'); })

Done ! A pocket cms is now running in your server.

Pocket takes an optional configuration object during construction.

e.g

new Pocket({
    datastore: {
        adapter: 'mongo',
        options: {
            dbName: 'pocket_dev',
            url: 'localhost:27017'
        }
    }
})

The following options are available:

Currently the following stores are available :

The mongodb adapter requires the following options :

The disk adapter supports the following options :

Currently Pocket only supports files saved on disk. S3 support is on the roadmap

Pocket uses the generic term Resource to define a data type within the CMS. Each resource has :

• A schema
  • Enables validation of posted data
  • Allows the admin panel to generate a form to edit the records
• An automatically generated rest endpoint

Resources are created using the following CMS api :

let cms = new Pocket();

cms.resource('cars', schema);

Resources are retrieved using the following CMS api :

const cars = cms.resource('cars');

await cars.find({});

await resource.create(payload, opts = {}) will create a record matching the payload parameter. Options :

• skipValidation allows the record to be created without being validated against its schema. Use with care
• userId will set the _createdBy property of a record

await resource.mergeOne(id, payload, opts = {}) will update the record specified by id by overriding the properties set in payload. Options :

• skipValidation allows the record to be created without being validated against its schema. Use with care

await resource.update(query, operations, options = {}) will update records specified by query with the operations formatted in a mongo like syntax. Options :

• multi will enable the update to run on multiple records. Defaults to true.

await resource.get(id) will return the record specified by id

await resource.find(query = {}, opts = {}) will return records that match the query argument. Options :

• pageSize and page will allow to retrieve paginated records

await resource.removeOne(id) will delete the record specified by id

await resource.remove(query, opts = {}) will remove all elements that match the query argument. Options :

• multi will allow multiple records to be removed if set to true. Otherwise only one of them will be deleted

await resource.attach(recordId, fileName, file) will save the file specified by the file argument in the file store, add add it to the record's _attachments list. file can either be a String pointing to the file on disk or a Stream

await resource.deleteAttachment(recordId, attachmentId) will delete the file from the file store and remove the attachment from its record

await resource.readAttachment(attachmentId) will return a node stream of the file

Pocket exposes a Schema class which can be used to create a resource's schema. More details can be found on the Pocket Schema repo.

e.g

const Pocket = require('pocket-cms');
const { Schema } = Pocket;

const carSchema = new Schema({
    additionalProperties: false,
    fields: {
        name: {
	    type: 'string',
	    index: {
		unique: true
	    }
	}
	brand: {
	    type: 'text',
	    maxLength: 64
	},
	noOfWheels: {
	    type: 'number',
	    required: true,
	},
	color: {
	    type: 'select',
	    options: ['red', 'yellow', 'magenta']
	},
	tags: {
	    type: 'array',
	    items: { type: 'string' }
	}
    }
});

The following types are available :

• any

• array|list - options:

  • items? A field definition of the expected array items

• checkbox|boolean

• date - options:

  • format? The expected date format (defaults to YYYY-MM-DD)

• datetime

• email - options:

  • match? A regular expression to match the email against

• map - options:

  • items? A field definition of the expected map items

• multiselect - options:

  • options List or options to select from. An async function can also be passed

• number - options:

  • min? Minimum allowed value
  • max? Maximum allowed value

• object|json - options:

  • schema? Schema used to validate the object against

• password - options:

  • minLength? The minimum length of the password

• select|enum - options:

  • options List or options to select from. An async function can also be passed

• text|string - options:

  • minLength? The minimum length of the string
  • maxLength? The maximum length of the string
  • match? A regular expression to match the string against

• time

• timestamp

When records are created/updated the CMS automatically adds and keeps track of a number or private properties which cannot be updated manually. All those private properties start by underscore _.

Currently those are:

• _id
• _createdAt
• _updatedAt
• _createdBy
• _attachments the list of attachments

To mark a field as a database index, its schema field supports the index parameter. Which can either be :

• A true|false value
• An object with the following properties :
  • unique true|false

Example :

const Pocket = require('pocket-cms');
const { Schema } = Pocket;

const person = new Schema({
    fields: {
        name: {
            type: 'string',
	    index: {
	        unique: true
	}
    }
});

Pre and Post hooks can be added to a schema which allow adding extra functionality and ACL to the CMS.

Available api :

• schema.before(action, method)
• schema.after(action, method)

Available methods

• create
• remove
• update
• save
• validate
• read

Example usage

const Pocket = require('pocket-cms');
const { Schema } = Pocket;

const postSchema = new Schema({
    fields: {
        message: {
	    type: 'string',
	}
    }
})
.before('save', async ({ record }, ctx) => {
    const { user } = ctx;

    if (await userCheck(user, record) === false) {
        throw 'User should not save this record';
    }
});

const cms = new Pocket();

pocket.resource('posts', postSchema);

The Pocket CMS class exposes a user manager that can be used to create/remove and authenticate users.

e.g

const Pocket = require('pocket-cms');

const cms = new Pocket();

// Creating a user
await pocket.users.create('username', 'password', [ 'users' ]);

// Authenticating a user
const user = await pocket.users.auth('username', 'password');

// Extracting a user from the JWT auth token
const user = await pocket.users.fromJWT(token)

The underlying resource is named _users

By default the following groups are created :

• admins
• users

Groups can be added by using the underlying resource _groups

For each resource created, a generic rest api is automatically created for it.

Here's a rundown of the different endpoints

• POST /users/signup to create a user. The following JSON body is expected

  • username
  • password
  • groups (defaults to ['users'])

• POST /users/login to log in a user.
  Important: This endpoint will return a Java Web Token, which should be included into following requests -> Authorization: Bearer <token>. The following JSON body is expected

  • username
  • password

• POST /users/logout to logout out. NOTE: As authentication is done via JWT, this endpoint doesn't actually do anything. It exists as a placeholder for future additions (hooks/logs/etc)

• GET /users/status to retrieve the user and status of an existing JWT Token

• GET /rest/{resource} lists records for the given resource. Available options :

  • pageSize - The number of records to return per page
  • page - The page to return

• GET /rest/{resource}/{id} returns a single record specified by id

• POST /rest/{resource} creates a record of the resource type

• PUT /rest/{resource}/{id} updates the record specified by id of the resource type

• DELETE /rest/{resource}/{id} deletes the record specified by id`

• POST /rest/{resource}/{id}/attachments uploads a file and a attach it to the record specified by id

• GET /rest/{resource}/{id}/attachments/{attachmentId} downloads the attachment of a record

• DELETE /rest/{resource}/{id}/attachments/{attachmentId} deletes the attachment of a record

The resource key of the endpoints listed above can all be prefixed with a user id to filter on records createdBy that user.

e.g

GET /rest/users/:userId/{resource}/{id} will return only records created by the user specified by userId

There are multiple rules and ways to control the access of resources by users.

We either allow or deny actions on certain resources. The following actions exist:

• read
• create
• update
• remove

Users from the admins group are whitelisted and have permission to make any change to any resources.

Private CMS resources (prefixed with _) cannot be modified by any other group. Currently those are :

• _users
• _groups

A entire resource can be configured to only be accessible to a certain set of groups.

That is done on the schema level with the following 2 methods :

• schema.allow(group, actions[])
• deny(group, actions[])

Note: A wildcard * can be used as a group name to represent all of them

Example :

const Pocket = require('pocket-cms');
const { Schema } = Pocket;

const postSchema = new Schema({
    fields: {
        message: {
        type: 'string'
        }
    }
})
.allow('users', [ 'read' ])
.allow('moderators', [ 'read', 'create', 'update', 'delete' ])

A group can be given access to a resource through its permissions field.

e.g

pocket.resource('_groups').create({
    name: 'moderators',
    permissions: {
        '*': ['read'],
        'posts': ['read', 'create', 'update', 'delete' ]
    }
});