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

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.

const { CloudEvent } = require("cloudevents-sdk");
const { StructuredHTTPEmitter } = require("cloudevents-sdk/v1");

const myevent = new CloudEvent()
  .type("com.github.pull.create")
  .source("urn:event:from:myapi/resource/123");

const emitter = new StructuredHTTPEmitter({
  method: "POST",
  url   : "https://myserver.com"
});

// Emit the event
emitter.emit(myevent)

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 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.