https://github.com/serverless/event-gateway-sdk
Event Gateway JavaScript SDK
https://github.com/serverless/event-gateway-sdk
event-gateway faas sdk-js sdk-nodejs serverless
Last synced: 8 months ago
JSON representation
Event Gateway JavaScript SDK
- Host: GitHub
- URL: https://github.com/serverless/event-gateway-sdk
- Owner: serverless
- License: mit
- Created: 2018-02-12T14:04:53.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2018-12-13T10:22:00.000Z (about 7 years ago)
- Last Synced: 2024-11-03T05:23:41.674Z (about 1 year ago)
- Topics: event-gateway, faas, sdk-js, sdk-nodejs, serverless
- Language: JavaScript
- Homepage:
- Size: 387 KB
- Stars: 44
- Watchers: 31
- Forks: 11
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Event Gateway JavaScript SDK
Javascript library for interacting with the [Event Gateway](https://github.com/serverless/event-gateway).
[](https://travis-ci.org/serverless/event-gateway-sdk)
[](https://snyk.io/test/github/serverless/event-gateway-sdk)
## Contents
- [Background](#background)
- [Target Audience](#target-audience)
- [Installation](#installation)
- [Usage](#usage)
- [Constructor](#constructor)
- [API Reference](#api-reference)
- [Contributing](#contributing)
## Background
This is the Javascript SDK for interacting with the [Event Gateway](https://github.com/serverless/event-gateway), the hub for connecting events to serverless functions. It is designed to work both on the server with Node.js and in the browser.
## Target Audience
This SDK can be used both to *configure* the Event Gateway, by registering functions and subscriptions, and to *interact* with the Event Gateway, by emitting events from your application to be sent to subscribed functions.
This README is focused on the latter use case -- interacting with the Event Gateway by emitting events. If you're interested in using the Event Gateway SDK to configure the Event Gateway, please check the [API reference](./docs/api.md) for the available methods, as well as the main [Event Gateway repository](https://github.com/serverless/event-gateway). You may also be interested in using the [Event Gateway plugin](https://github.com/serverless/serverless-event-gateway-plugin) for the [Serverless Framework](https://github.com/serverless/serverless) to configure the Event Gateway.
## Installation
Node:
```bash
npm install @serverless/event-gateway-sdk
```
Browser:
```html
```
The EventGateway SDK will then be attached to window e.g. and you can access it via `window.EventGatewaySDK`
## Usage
Use the `emit` command to emit a [CloudEvent](https://github.com/cloudevents/spec) payload to your Event Gateway. The event will be received by any function that is subscribed to your event.
```javascript
// Construct your client
const SDK = require('@serverless/event-gateway-sdk');
const eventGateway = new SDK({
url: 'https://mytenant-myapp.slsgateway.com',
})
// Emit your event
eventGateway
.emit({
eventID: '1',
eventType: 'user.created',
cloudEventsVersion: '0.1',
source: '/services/users',
contentType: 'application/json',
data: {
userID: 'foo'
}
}, {
path: '/users',
headers: {
"Authorization": "Bearer 124567890"
}
})
// If a sync subscription, then do something with the response.
.then(res => res.json())
.then(json => console.log(json))
```
The `emit()` function takes two arguments: an `event` which is a valid CloudEvent, plus an optional `options` object to include a path and/or headers to pass with your event.
The function returns a [`fetch`](https://github.com/bitinn/node-fetch) response object. If your event has a `sync` subscription attached, the `fetch` response will have the status code and body from the subscription. If not, the response will return a `202 Accepted` status code with an empty body.
## Constructor
In the example above, we created an Event Gateway client using the application URL from the [hosted Event Gateway](https://dashboard.serverless.com/) provided by Serverless, Inc.
You can also use the Event Gateway SDK with your own, self-hosted Event Gateway. Constructor details are listed below.
**Parameters**
Object:
- `url` - `string` - required, Events API URL
- `configurationUrl` - `string` - optional, Configuration API URL. By default, it's the same as `url` but with `4001` port
- `space` - `string` - optional, space name, default: `default`
- `accessKey` - `string` - optional, access key for hosted Event Gateway. Access key is required for using Configuration API methods on hosted Event Gateway
- `fetchClient` - `object` - optional, `fetch` client
**Example**
```js
const SDK = require('@serverless/event-gateway-sdk');
const eventGateway = new SDK({
url: 'http://localhost',
space: 'mycompany-prod',
accessKey: '1234abcd'
})
```
## API Reference
For all available methods in the Event Gateway SDK, please see the [API reference](./docs/api.md).
## Contribute
If you are interested to contribute we recommend to check out the [Contributing](https://github.com/serverless/event-gateway-sdk/blob/master/CONTRIBUTING.md) document as it explains how to get started and some of the design decisions for this library.