docs: update README and examples with new API

This commit modifies the README to show new API usage for the
`HTTPReceiver` and `CloudEvent` classes, and updates the examples
to use this as well.

Fixes: #128

Signed-off-by: Lance Ball <[email protected]>

Author: lance

README.md

@@ -11,28 +11,9 @@
 
 The CloudEvents SDK for JavaScript.
 
-## Status
+## CloudEvents Specification Support
 
-This SDK is still considered a work in progress.
-
-This SDK current supports the following versions of CloudEvents:
-
-- v1.0
-
-**Checkout the [changelog](CHANGELOG.md) to see what's going on!**
-
-## Installation
-
-This CloudEvents SDK requires nodejs 6.11+
-
-### Nodejs
-
-```sh
-npm install cloudevents-sdk
-```
-## Specification Support
-
-These are the supported specifications by this version.
+This SDK supports the 0.3 and 1.0 versions of the CloudEvents specification:
 
 | **Specifications**                    | v0.3 | **v1.0** |
 |---------------------------------------|------|----------|
@@ -41,244 +22,78 @@ These are the supported specifications by this version.
 | HTTP Transport Binding  - Binary      | yes  |   yes    |
 | JSON Event Format                     | yes  |   yes    |
 
-### What we can do
-
-| **What**                            | v0.3 | **v1.0** |
+| **Capabilities**                    | v0.3 | **v1.0** |
 |-------------------------------------|------|----------|
 | Create events                       | yes  |   yes    |
 | Emit Structured events over HTTP    | yes  |   yes    |
 | Emit Binary events over HTTP        | yes  |   yes    |
-| JSON Event Format                   | yes  |   yes    |
 | Receive Structured events over HTTP | yes  |   yes    |
 | Receive Binary events over HTTP     | yes  |   yes    |
 
-## How to use
+### A Note on Versioning
 
-### Usage
+The CloudEvents protocol version is distinct from this module's version number.
+For example, this module may be versioned as v2.0.0 but support the v0.3 and v1.0
+versions of the CloudEvent specification.
 
-```js
-const v1 = require("cloudevents-sdk/v1");
+## Usage
 
-/*
- * Creating an event
- */
-let myevent = v1.event()
-  .type("com.github.pull.create")
-  .source("urn:event:from:myapi/resource/123");
-```
+**See the full working example: [here](./examples/express-ex).**
 
-#### Formatting
-
-```js
-const v1 = require("cloudevents-sdk/v1");
+### Installation
 
-/*
- * Creating an event
- */
-let myevent = v1.event()
-  .type("com.github.pull.create")
-  .source("urn:event:from:myapi/resource/123");
+The CloudEvents SDK requires a current LTS version of Node.js. At the moment
+those are Node.js 10.x and Node.js 12.x. To install in your Node.js project:
 
-/*
- * Format the payload and return it
- */
-let formatted = myevent.format();
+```console
+npm install --save cloudevents-sdk
 ```
 
-#### Emitting
-
-```js
-const v1 = require("cloudevents-sdk/v1");
-
-/*
- * Creating an event
- */
-let myevent = v1.event()
-  .type("com.github.pull.create")
-  .source("urn:event:from:myapi/resource/123");
-
-// The binding configuration using POST
-let config = {
-  method: "POST",
-  url   : "https://myserver.com"
-};
-
-// The binding instance
-let binding = new v1.StructuredHTTPEmitter(config);
-
-// Emit the event using Promise
-binding.emit(myevent)
-  .then(response => {
-    // Treat the response
-    console.log(response.data);
-
-  }).catch(err => {
-    // Deal with errors
-    console.error(err);
-  });
-```
+### Receiving and Emitting Events
 
 #### Receiving Events
 
-You can choose any framework for port binding. But, use the
-StructuredHTTPReceiver or BinaryHTTPReceiver to process the HTTP Payload and
-HTTP Headers, extracting the CloudEvents.
-
-:smiley: **Checkout the full working example: [here](./examples/express-ex).**
-
-```js
-// some parts were removed //
-
-const v1 = require("cloudevents-sdk/v1");
-
-const receiver = new v1.StructuredHTTPReceiver();
-
-// some parts were removed //
-
-app.post("/", (req, res) => {
-  try {
-    let myevent = receiver.parse(req.body, req.headers);
-
-    // TODO use the event
-
-    res.status(201).send("Event Accepted");
-
-  } catch(err) {
-    // TODO deal with errors
-    console.error(err);
-    res.status(415)
-          .header("Content-Type", "application/json")
-          .send(JSON.stringify(err));
-  }
-});
-```
-
-## Unit Testing
-
-The unit test checks the result of formatted payload and the constraints.
-
-```bash
-npm test
-```
-
-## The API
-
-### `CloudEvent` class
+You can choose almost any popular web framework for port binding. Use an
+`HTTPReceiver` to process the incoming HTTP request. The receiver accepts
+binary and structured events in either the 1.0 or 0.3 protocol formats.
 
 ```js
-/*
- * Format the payload and return an Object.
- */
-Object CloudEvent.format()
-
-/*
- * Format the payload as String.
- */
-String CloudEvent.toString()
-```
+const {
+  CloudEvent,
+  HTTPReceiever
+} = require("cloudevents-sdk");
 
-### `Formatter` classes
+// Create a receiver to accept events over HTTP
+const receiver = new HTTPReceiver();
 
-Every formatter class must implement these methods to work properly.
-
-```js
-/*
- * Format the CloudEvent payload argument and return an Object.
- */
-Object Formatter.format(Object)
-
-/*
- * Format the CloudEvent payload as String.
- */
-String Formatter.toString(Object)
-```
-
-### `Parser` classes
-
-Every Parser class must implement these methods to work properly.
-
-```js
-/*
- * The default constructor with Parser as decorator
- */
-Parser(Parser)
-
-/*
- * Try to parse the payload to some event format
- */
-Object Parser.parse(payload)
+// body and headers come from an incoming HTTP request, e.g. express.js
+const receivedEvent = receiver.accept(req.body, req.headers);
+console.log(receivedEvent.format());
 ```
 
-### `Spec` classes
+#### Emitting Events
 
-Every Spec class must implement these methods to work properly.
+Currently, to emit events, you'll need to decide whether the event is in
+binary or structured format, and determine what version of the CloudEvents
+specification you want to send the event as.
 
 ```js
-/*
- * The constructor must receives the CloudEvent type.
- */
-Spec(CloudEvent)
-
-/*
- * Checks the spec constraints, throwing an error if do not pass.
- * @throws Error when it is an invalid event
- */
-Spec.check()
-
-/*
- * Checks if the argument pass through the spec constraints
- * @throws Error when it is an invalid event
- */
-Spec.check(Object)
-```
+const { CloudEvent } = require("cloudevents-sdk");
+const { StructuredHTTPEmitter } = require("cloudevents-sdk/v1");
 
-### `Binding` classes
-
-Every Binding class must implement these methods to work properly.
-
-#### Emitter Binding
-
-Following we have the signature for the binding to emit CloudEvents.
-
-```js
-/*
- * The constructor must receives the map of configurations.
- */
-Binding(config)
-
-/*
- * Emits the event using an instance of CloudEvent.
- */
-Binding.emit(cloudEvent)
-```
-
-#### Receiver Binding
-
-Following we have the signature for the binding to receive CloudEvents.
-
-```js
-/*
- * The constructor must receives the map of configurations.
- */
-Receiver(config)
+const myevent = new CloudEvent()
+  .type("com.github.pull.create")
+  .source("urn:event:from:myapi/resource/123");
 
-/*
- * Checks if some Object and a Map of headers
- * follows the binding definition, throwing an error if did not follow
- */
-Receiver.check(Object, Map)
+const emitter = new StructuredHTTPEmitter({
+  method: "POST",
+  url   : "https://myserver.com"
+});
 
-/*
- * Checks and parse as CloudEvent
- */
-CloudEvent Receiver.parse(Object, Map)
+// Emit the event
+emitter.emit(myevent)
 ```
 
-## Versioning
-
-- `x.M.p`: where `x` relates to spec version, `M` relates to minor and `p` relates
-to fixes. See [semver](https://semver.org/)
-
 ## Community
 
 - There are bi-weekly calls immediately following the [Serverless/CloudEvents
@@ -291,3 +106,9 @@ to fixes. See [semver](https://semver.org/)
   [CNCF's Slack workspace](https://slack.cncf.io/).
 - Email: https://lists.cncf.io/g/cncf-cloudevents-sdk
 - Contact for additional information: Fabio José (`@fabiojose` on slack).
+
+## Contributing
+
+We love contributions from the community! Please check the
+[Contributor's Guide](https://github.com/cloudevents/sdk-javascript/blob/master/CONTRIBUTING.md)
+for information on how to get involved.