JavaScript SDK for CloudEvents

The CloudEvents SDK for JavaScript.

This module will help you to:

Represent CloudEvents in memory
Use Event Formats to serialize/deserialize CloudEvents
Use Protocol Bindings to send/receive CloudEvents

Note: Supported CloudEvents specification: 0.3, 1.0

A Note on Versioning

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.

Usage

See the full working example: here.

Installation

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:

npm install --save cloudevents-sdk

Receiving and Emitting Events

Receiving Events

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.

const {
  CloudEvent,
  HTTPReceiever
} = require("cloudevents-sdk");

// Create a receiver to accept events over HTTP
const receiver = new HTTPReceiver();

// 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());

Emitting Events

To emit events, you'll need to decide whether the event should be sent in binary or structured format, and determine what version of the CloudEvents specification you want to send the event as.

By default, the HTTPEmitter will emit events over HTTP POST using the 1.0 specification, in binary mode. You can emit 0.3 events by providing the specication version in the constructor to HTTPEmitter. To send structured events, add that string as a parameter to emitter.sent().

const { CloudEvent, HTTPEmitter } = require("cloudevents-sdk");

// With only an endpoint URL, this creates a v1 emitter
const v1Emitter = new HTTPEmitter({
  url: "https://cloudevents.io/example"
});
const event = new CloudEvent({
  type, source, data
});

// By default, the emitter will send binary events
v1Emitter.send(event).then((response) => {
    // handle the response
  }).catch(console.error);

// To send a structured event, just add that as an option
v1Emitter.send(event, { mode: "structured" })
  .then((response) => {
    // handle the response
  }).catch(console.error);

// To send an event to an alternate URL, add that as an option
v1Emitter.send(event, { url: "https://alternate.com/api" })
  .then((response) => {
    // handle the response
  }).catch(console.error);

// Sending a v0.3 event works the same, just let the emitter know when
// you create it that you are working with the 0.3 spec
const v03Emitter = new HTTPEmitter({
  url: "https://cloudevents.io/example",
  version: "0.3"
});

// Again, the default is to send binary events
// To send a structured event or to an alternate URL, provide those
// as parameters in a options object as above
v3Emitter.send(event)
  .then((response) => {
    // handle the response
  }).catch(console.error);

Supported specification features

	v0.3	v1.0
CloudEvents Core	✔️	✔️
AMQP Protocol Binding	❌	❌
AVRO Event Format	❌	❌
HTTP Protocol Binding	✔️	✔️
JSON Event Format	✔️	✔️
Kafka Protocol Binding	❌	❌
NATS Protocol Binding	❌	❌
STAN Protocol Binding	❌	❌

Community

There are bi-weekly calls immediately following the Serverless/CloudEvents call at 9am PT (US Pacific). Which means they will typically start at 10am PT, but if the other call ends early then the SDK call will start early as well. See the CloudEvents meeting minutes to determine which week will have the call.
Slack: #cloudeventssdk channel under CNCF's Slack workspace.
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 for information on how to get involved.

n3wscott/sdk-javascript