chore: updates readme with the new API

README.md

@@ -1,27 +1,221 @@
-# Gavel.js — Validator of HTTP Transactions
-
 [![npm version](https://badge.fury.io/js/gavel.svg)](https://badge.fury.io/js/gavel)
 [![Build Status](https://travis-ci.org/apiaryio/gavel.js.svg?branch=master)](https://travis-ci.org/apiaryio/gavel.js)
 [![Build status](https://ci.appveyor.com/api/projects/status/0cpnaoakhs8q58tn/branch/master?svg=true)](https://ci.appveyor.com/project/Apiary/gavel-js/branch/master)
-[![Dependency Status](https://david-dm.org/apiaryio/gavel.js.svg)](https://david-dm.org/apiaryio/gavel.js)
-[![devDependency Status](https://david-dm.org/apiaryio/gavel.js/dev-status.svg)](https://david-dm.org/apiaryio/gavel.js#info=devDependencies)
-[![Greenkeeper badge](https://badges.greenkeeper.io/apiaryio/gavel.js.svg)](https://greenkeeper.io/)
 [![Coverage Status](https://coveralls.io/repos/apiaryio/gavel.js/badge.svg?branch=master)](https://coveralls.io/r/apiaryio/gavel.js?branch=master)
 [![Known Vulnerabilities](https://snyk.io/test/npm/gavel/badge.svg)](https://snyk.io/test/npm/gavel)
 
-![Gavel.js - Validator of HTTP Transactions](https://raw.github.com/apiaryio/gavel/master/img/gavel.png?v=1)
+<br />
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/apiaryio/gavel/master/img/gavel.png?v=1" alt="Gavel logo" />
+</p>
+
+<h1 align="center">Gavel</h1>
+
+<p align="center">Gavel is a library that validates a given HTTP transaction (request/response pair).</p>
+
+## Install
+
+```bash
+npm install gavel
+```
+
+## Usage
+
+### CLI
+
+```bash
+# (Optional) Record HTTP messages
+curl -s --trace - http://httpbin.org/ip | curl-trace-parser > expected
+curl -s --trace - http://httpbin.org/ip | curl-trace-parser > actual
+
+# Perform the validation
+cat actual | gavel expected
+```
+
+> Example above uses [`curl-trace-parser`](https://github.com/apiaryio/curl-trace-parser).
+
+### NodeJS
+
+```js
+const gavel = require('gavel');
+
+// Define HTTP messages
+const expected = {
+  statusCode: 200,
+  headers: {
+    'Content-Type': 'application/json'
+  }
+};
+
+const actual = {
+  statusCode: 404,
+  headers: {
+    'Content-Type': 'application/json'
+  }
+};
+
+// Perform the validation
+const result = gavel.validate(expected, actual);
+```
+
+The code above wouold return the next validation `result`:
 
-Gavel detects important differences between actual and expected HTTP transactions (HTTP request and response pairs). Gavel also decides whether the actual HTTP transaction is valid or not.
+```js
+{
+  valid: false,
+  fields: {
+    statusCode: {
+      valid: false,
+      kind: 'text',
+      values: {
+        expected: 200,
+        actual: 404
+      },
+      errors: [
+        {
+          message: `Expected status code '200', but got '404'.`,
+          values: {
+            expected: 200,
+            actual: 404
+          }
+        }
+      ]
+    },
+    headers: {
+      valid: true,
+      kind: 'json',
+      values: {
+        expected: {
+          'Content-Type': 'application/json'
+        },
+        actual: {
+          'Content-Type': 'application/json'
+        }
+      },
+      errors: []
+    }
+  }
+}
+```
+
+### Usage with JSON Schema
+
+You can describe the body expectations using [JSON Schema](https://json-schema.org/) by providing a valid schema to the `bodySchema` property of the expected HTTP message:
+
+```js
+const gavel = require('gavel');
+
+const expected = {
+  bodySchema: {
+    type: 'object',
+    properties: {
+      fruits: {
+        type: 'array',
+        items: {
+          type: 'string'
+        }
+      }
+    }
+  }
+};
+
+const actual = {
+  body: JSON.stringify({
+    fruits: ['apple', 'banana', 2]
+  })
+};
+
+const result = gavel.validate(expected, actual);
+```
+
+The validation `result` against the given JSON Schema will look as follows:
+
+```js
+{
+  valid: false,
+  fields: {
+    body: {
+      valid: false,
+      kind: 'json',
+      values: {
+        actual: "{\"fruits\":[\"apple\",\"banana\",2]}"
+      },
+      errors: [
+        {
+          message: `At '/fruits/2' Invalid type: number (expected string)`,
+          location: {
+            pointer: '/fruits/2'
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+## Type definitions
+
+### Input
+
+> Gavel has no assumptions over the validity of a given HTTP message. It is the end user responsibility to operate on the valid data. Gavel will throw an exception when given invalid input data.
+
+Both expected and actual HTTP messages inherit from a generic `HttpMessage` interface:
 
-## Installation
+```ts
+interface HttpMessage {
+  method?: string;
+  statusCode?: number;
+  headers?: Record<string> | string;
+  body?: string;
+  bodySchema?: Object | string;
+}
+```
+
+### Output
+
+```ts
+// Field kind describes the type of a field's values
+// subjected to the end comparison.
+enum FieldKind {
+  null // non-comparable data (validation didn't happen)
+  text // compared as text
+  json // compared as JSON
+}
 
-```sh
-$ npm install gavel
+interface ValidationResult {
+  valid: boolean // validity of the actual message
+  fields: {
+    [fieldName: string]: {
+      valid: boolean // validity of a single field
+      kind: FieldKind
+      values: { // end compared values (coerced, normalized)
+        actual: any
+        expected: any
+      }
+      errors: FieldError[]
+    }
+  }
+}
+
+interface FieldError {
+  message: string
+  location?: { // kind-specific additional information
+    // JSON
+    pointer?: string
+    property?: string
+  }
+  values?: {
+    expected: any
+    actual: any
+  }
+}
 ```
 
-## Documentation
+## API
+
+- `validate(expected: HttpMessage, actual: HttpMessage): ValidationResult`
 
-Gavel.js is a JavaScript implementation of the [Gavel behavior specification](https://www.relishapp.com/apiary/gavel/) ([repository](https://github.com/apiaryio/gavel-spec)):
+## License
 
-- [Gavel.js-specific documentation](https://www.relishapp.com/apiary/gavel/docs/javascript/)
-- [CLI documentation](https://www.relishapp.com/apiary/gavel/docs/command-line-interface/)
+MIT