Merge pull request #1 from smaxwellstewart/dev

v.1.1
kidtronnix · Sep 29, 2014 · 5f4a4e5 · 5f4a4e5
2 parents 1c0c9fe + c09c830
commit 5f4a4e5
Show file tree

Hide file tree

Showing 5 changed files with 570 additions and 180 deletions.
diff --git a/README.md b/README.md
@@ -3,21 +3,21 @@ Toothache
 
 A Hapi plugin that removes the toothache from creating CRUD endpoints for MongoDB.
 
-Current version: **1.0.x** [![Build Status](https://travis-ci.org/smaxwellstewart/toothache.svg?branch=master)](https://travis-ci.org/smaxwellstewart/toothache) [![Coverage Status](https://img.shields.io/coveralls/smaxwellstewart/toothache.svg)](https://coveralls.io/r/smaxwellstewart/toothache?branch=master)
+Current version: **1.1.x** [![Build Status](https://travis-ci.org/smaxwellstewart/toothache.svg?branch=master)](https://travis-ci.org/smaxwellstewart/toothache) [![Coverage Status](https://img.shields.io/coveralls/smaxwellstewart/toothache.svg)](https://coveralls.io/r/smaxwellstewart/toothache?branch=master)
 
-### What is this plugin?
+## What is this plugin?
 
 This plugin instantly adds the following functionality to any mongo db...
 
 * Plug 'n' play CRUD Routes
 * Set custom fields to bcrypt and/or timestamp at doc creation, if required
 * Access control of resources.
 
-### Usage
+## Usage
 
 The below is intended to be added into a hapi plugin. In our example case, we will make a `User` endpoint for a Hapi server.
 
-##### Configure
+### Configure
 
 Configure toothache with desired behaviour... 
 
@@ -28,33 +28,41 @@ var CRUD = {
     collection: 'users',    // MongoDB collection
     // Create options
     create: {
-        bcrypt: 'password', // Sets 'password' field to be bcrypted at doc creation
-        date: 'created',    // Sets 'created' field to be dated at doc creation
+        // Valid create payload 
         payload: Joi.object().keys({ 
             email: Joi.string().required(),
             password: Joi.string().required()
-        }),                 // Valid create payload 
+        }),                 
         defaults: {         // Default values that will be added at doc creation
             access: 'normal',
             activated: false,
             uId: true       // Field used for access control. This is a special field that when set to true will default to user's id 
                             // The value comes from, 'request.auth.artifacts.id' ie the id the user authenticates with
         },
+        bcrypt: 'password', // Sets 'password' field to be bcrypted at doc creation
+        date: 'created',    // Sets 'created' field to be dated at doc creation
         access: "admin"     // Sets which role can create 
     },
     // Read options for get and find
     read: {
         whitelist: ['email'],   // Array of fields that will be returned, all other fields will be excluded 
-        blacklist: ['password'] // Array of fields that will be removed, all other fields will be included
+        blacklist: ['password'], // Array of fields that will be removed, all other fields will be included
+        access: 'normal'        // Sets which role can read 
     }
     // Update options
     update: {
-        bcrypt: 'password', // Sets 'password' field to be bcrypted at doc update
-        date: 'updated',    // Sets 'updated' field to be dated at doc update
+        // Valid update payload
         payload: Joi.object().keys({
             email: Joi.string(),
             password: Joi.string()
-        }) // Valid update payload 
+        }), 
+        bcrypt: 'password', // Sets 'password' field to be bcrypted at doc update
+        date: 'updated',    // Sets 'updated' field to be dated at doc update
+        access: 'normal' // Sets which role can update  
+    },
+    // Delete options
+    delete: {
+        access: 'normal' // Sets which role can update 
     },
     // Joi options when validating payloads    
     validationOpts: {
@@ -66,62 +74,103 @@ var CRUD = {
 var User = require('toothache')(CRUD);
 ```
 
-##### Add Routes
-
-Once we have configured toothache, we have the following CRUD request handlers will be exposed:
-
-* User.create
-* User.get
-* User.find
-* User.update
-* User.del
+### Request Handlers
+
+Once we have configured toothache, the following request handlers will be exposed:
+
+#### `.create`
+ - This handler will insert any supplied `payload` into MongoDB.
+ - Accepted methods: `GET` with `payload` in URL or, `POST` or `PUT` with `payload` in request body.
+ - The following toothache `options` will affect this handler:
+  - `db` - MongoDB connection object, connection [example](https://gist.github.com/smaxwellstewart/9cf26df20cb58a3f5d02). 
+  - 'collection' - the MongoDB collection to create, read, update and delete from.
+  - `create.payload` - [Joi](https://github.com/hapijs/joi) object payload is validated against.
+  - `create.defaults` - Object of default fields, the payload will extend this object before insertion, 
+  e.g. supplied payload will join and override this default object.
+  - `create.bcrypt` - Field name of `payload` field to be bcrypted before doc creation.
+  - `create.date` - Will add a javasctipt `new Date()` timestamp to field name at doc creation.
+  - `create.access` - If set to `admin` only admin users will be able to create a doc. If set to normal, both admin and normal users have create access.
+
+#### `.get`
+ - This handler will return an individual MongoDB document.
+ - Accepted methods: `GET` with an `id` parameter set in route's `path` field.
+ - The following toothache `options` will affect this handler:
+  - `read.whitelist` - Array of fields that will be returned when doc is fetched.
+  - `read.blacklist` - Array of fields that will be excluded when doc is fetched. Not recommened to be set with `read.whitelist`.
+  - `read.access` - If set to `admin` only admin users will be able to read a doc. If set to normal, both admin and normal users have read access.
+
+#### `.find`
+ - This handler will return an array of MongoDB documents. The search will query with a supplied `payload`, if none is supplied will return all docs. For normal users
+ - Accepted methods: `GET` with `payload` in URL or, `POST` or `PUT` with `payload` in request body.
+ - The following toothache `options` will affect this handler:
+  - `read.whitelist` - Array of fields that will be returned when docs are fetched.
+  - `read.blacklist` - Array of fields that will be excluded when docs are fetched. Not recommened to be set with `read.whitelist`.
+  - `read.access` - If set to `admin` only admin users will be able to read a doc. If set to normal, both admin and normal users have read access.
+
+#### `.update`
+ - This route will update a doc with any supplied `payload`. The handler expects an `id` parameter to be set in route's `path` field.
+ - Accepted methods: `GET` with `payload` in URL or, `POST` or `PUT` with `payload` in request body.
+ - The following toothache `options` will affect this handler:
+  - `update.payload` - [Joi](https://github.com/hapijs/joi) object payload is validated against.
+  e.g. supplied payload will join and override this default object.
+  - `update.bcrypt` - Field name of `payload` field to be bcrypted when doc is updated.
+  - `update.date` - Will add a javasctipt `new Date()` timestamp to field name when doc is updated.
+  - `update.access` - If set to `admin` only admin users will be able to update a doc. If set to normal, both admin and normal users have update access. 
+
+#### `.del`
+ - This route will delete a doc with any supplied `payload`.
+ - Accepted methods: `DELETE` with an `id` parameter set in route's `path` field.
+ - The following toothache `options` will affect this handler:
+  - `delete.access` - If set to `admin` only admin users will be able to delete a doc. If set to normal, both admin and normal users have delete access. 
+
+*Example*
 
 These can be used in a Hapi plugin like this...
 
 ```js
 // Create
 plugin.route({
-    method: 'POST', path: '/api/user',
+    method: 'POST', path: '/user',
     config: {
         handler: User.create
     }
 });
 
 // Get a resource, must use 'id' parameter to refer to mongo's '_id' field
 plugin.route({
-    method: 'GET', path: '/api/user/{id}',
+    method: 'GET', path: '/user/{id}',
     config: {
         handler: User.get
     }
 });
 
 // Get All
 plugin.route({
-    method: 'GET', path: '/api/user',
+    method: 'GET', path: '/user',
     config: {
         handler: User.find
     }
 });
 
 // Find, will search collection using payload for criteria
 plugin.route({
-    method: 'POST', path: '/api/user/find',
+    method: 'POST', path: '/user/find',
     config: {
         handler: User.find
     }
 });
 
 // Update, must use 'id' parameter to refer to mongo's '_id' field
 plugin.route({
-    method: 'PUT', path: '/api/user/{id}',
+    method: 'PUT', path: '/user/{id}',
     config: {
         handler: User.update
     }
 });
 
 // Delete, must use 'id' parameter to refer to mongo's '_id' field
 plugin.route({
-    method: 'DELETE', path: '/api/user/{id}',
+    method: 'DELETE', path: '/user/{id}',
     config: {
         handler: User.del
     }
@@ -130,9 +179,15 @@ plugin.route({
 
 ### Access Control
 
+#### Roles
+ - `admin`
+ - `normal`
+
+
 Access control is only added if a route is authenticated. An `access` field must be added to user's credentials at authentication. For example:
 
 ```js
+// Example: Hawk Auth Lookup
 getCredentialsFunc: function (id, callback) {
     var credentials = {
         user1: {