JavaScript SDK for CloudEvents

The CloudEvents SDK for JavaScript.

Features

Represent CloudEvents in memory
Serialize and deserialize CloudEvents in different event formats.
Send and recieve CloudEvents with via different protocol bindings.

Note: Supports CloudEvent versions 0.3, 1.0

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 cloudevents-sdk

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,
  HTTPReceiver
} = 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 latest supported specification version, in binary mode. You can emit version specific events by providing the specication version in the constructor to HTTPEmitter. To send structured events, add that string as a parameter to emitter.send().

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	:heavy_check_mark:	:heavy_check_mark:
AMQP Protocol Binding	:x:	:x:
AVRO Event Format	:x:	:x:
HTTP Protocol Binding	:heavy_check_mark:	:heavy_check_mark:
JSON Event Format	:heavy_check_mark:	:heavy_check_mark:
Kafka Protocol Binding	:x:	:x:
NATS Protocol Binding	:x:	:x:
STAN Protocol Binding	:x:	:x:

Community

There are bi-weekly calls immediately following the [Serverless/CloudEvents call](https://github.com/cloudevents/spec#meeting-time) 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.

cloudevents-sdk