@serverless/platform-client
Advanced tools
Comparing version 3.0.0-beta.0 to 3.0.0-beta.1
{ | ||
"name": "@serverless/platform-client", | ||
"version": "3.0.0-beta.0", | ||
"version": "3.0.0-beta.1", | ||
"main": "./src/index.js", | ||
@@ -5,0 +5,0 @@ "jsdelivr": "dist-web/serverless-platform-client.min.js", |
764
README.md
@@ -66,13 +66,2 @@ # Serverless Platform SDK | ||
- [new ServerlessSDK()](#new_ServerlessSDK_new) | ||
- [.events](#ServerlessSDK+events) : <code>object</code> | ||
- [.publish(event)](#ServerlessSDK+events.publish) ⇒ <code>Promise.<null></code> | ||
- [.get(uid)](#ServerlessSDK+events.get) ⇒ <code>Promise.<Object></code> | ||
- [.list([options])](#ServerlessSDK+events.list) ⇒ <code>Promise.<Object></code> | ||
- ~~[.send(event)](#ServerlessSDK+events.send) ⇒ <code>null</code> \| <code>Promise.<null></code>~~ | ||
- [.webhooks](#ServerlessSDK+webhooks) : <code>object</code> | ||
- [.register(url)](#ServerlessSDK+webhooks.register) ⇒ <code>Promise.<object></code> | ||
- [.list()](#ServerlessSDK+webhooks.list) ⇒ <code>Promise.<object></code> | ||
- [.get(uid)](#ServerlessSDK+webhooks.get) ⇒ <code>Promise.<object></code> | ||
- [.update(uid)](#ServerlessSDK+webhooks.update) ⇒ <code>Promise.<object></code> | ||
- [.delete(uid)](#ServerlessSDK+webhooks.delete) ⇒ <code>Promise.<object></code> | ||
- [.config()](#ServerlessSDK+config) ⇒ <code>null</code> | ||
@@ -107,2 +96,6 @@ - [.getDomain(serviceName)](#ServerlessSDK+getDomain) ⇒ <code>string</code> | ||
- [.isConnected()](#ServerlessSDK+isConnected) ⇒ <code>boolean</code> | ||
- [.publish()](#ServerlessSDK+publish) ⇒ <code>null</code> | ||
- [.publishSync(events)](#ServerlessSDK+publishSync) ⇒ <code>Promise.<null></code> | ||
- [.getEvent(uid)](#ServerlessSDK+getEvent) ⇒ <code>Promise.<object></code> | ||
- [.listEvents(options)](#ServerlessSDK+listEvents) ⇒ <code>Promise.<object></code> | ||
- [.unpublishFromRegistry(registryPackage)](#ServerlessSDK+unpublishFromRegistry) | ||
@@ -123,2 +116,7 @@ - [.publishToRegistry(registryPackage)](#ServerlessSDK+publishToRegistry) ⇒ <code>object</code> | ||
- [.stopInterceptingLogs()](#ServerlessSDK+stopInterceptingLogs) | ||
- [.registerWebhook(url)](#ServerlessSDK+registerWebhook) ⇒ <code>Promise.<object></code> | ||
- [.listWebhooks()](#ServerlessSDK+listWebhooks) ⇒ <code>Promise.<object></code> | ||
- [.getWebhook(uid)](#ServerlessSDK+getWebhook) ⇒ <code>Promise.<object></code> | ||
- [.updateWebhook(uid)](#ServerlessSDK+updateWebhook) ⇒ <code>Promise.<object></code> | ||
- [.deleteWebhook(uid)](#ServerlessSDK+deleteWebhook) ⇒ <code>Promise.<object></code> | ||
@@ -160,62 +158,36 @@ <a name="new_ServerlessSDK_new"></a> | ||
<a name="ServerlessSDK+events"></a> | ||
<a name="ServerlessSDK+config"></a> | ||
### serverlessSDK.events : <code>object</code> | ||
### serverlessSDK.config() ⇒ <code>null</code> | ||
Publish and retrieve Serverless Platform Events | ||
Updates the SDK configuration | ||
**Kind**: instance namespace of [<code>ServerlessSDK</code>](#ServerlessSDK) | ||
**Kind**: instance method of [<code>ServerlessSDK</code>](#ServerlessSDK) | ||
- [.events](#ServerlessSDK+events) : <code>object</code> | ||
- [.publish(event)](#ServerlessSDK+events.publish) ⇒ <code>Promise.<null></code> | ||
- [.get(uid)](#ServerlessSDK+events.get) ⇒ <code>Promise.<Object></code> | ||
- [.list([options])](#ServerlessSDK+events.list) ⇒ <code>Promise.<Object></code> | ||
- ~~[.send(event)](#ServerlessSDK+events.send) ⇒ <code>null</code> \| <code>Promise.<null></code>~~ | ||
| Param | Type | Description | | ||
| -------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| [config.accessKey] | <code>string</code> | Can either be a Serverless Platform Access Key or an ID Token. | | ||
| [config.platformStage] | <code>string</code> | The Serverless Platform Stage you wish to interact with. This can also be set by the environment variable SERVERLESS_PLATFORM_STAGE= | | ||
| [context.orgName] | <code>string</code> | The name of the Serverless Platform Organization you wish to interact with. If set, this value is used upon creating a Websockets connection, and auto-added to every Event you publish. | | ||
| [context.orgUid] | <code>string</code> | The ID of the Serverless Platform Organization you wish to interact with. If set, this value is used upon creating a Websockets connection, and auto-added to every Event you publish. | | ||
| [context.stageName] | <code>string</code> | The Serverless Platform Organization Stage you wish to interact with. If set, this value is auto-added to every Event you publish. | | ||
| [context.appName] | <code>string</code> | The Serverless Platform Application you wish to interact with. If set, this value is auto-added to every Event you publish. | | ||
| [context.instanceName] | <code>string</code> | The Serverless Platform Instance you wish to interact with. If set, this value is auto-added to every Event you publish. | | ||
| [context.componentName] | <code>string</code> | The Serverless Platform Component you wish to interact with. If set, this value is auto-added to every Event you publish. | | ||
| [context.componentVersion] | <code>string</code> | The Serverless Platform Component version you wish to interact with. If set, this value is auto-added to every Event you publish. | | ||
<a name="ServerlessSDK+events.publish"></a> | ||
**Example** | ||
#### events.publish(event) ⇒ <code>Promise.<null></code> | ||
Publishes Serverless Platform Event(s) via HTTP API. The use-case for this is synchronous publishing, where you do not want to open a websockets connection. | ||
**Kind**: static method of [<code>events</code>](#ServerlessSDK+events) | ||
**Returns**: <code>Promise.<null></code> - A successful publish request will be ack'ed with a `200:OK` HTTP status and empty response. | ||
| Param | Type | Description | | ||
| ----------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| event | <code>Object</code> \| <code>Array.<Object></code> | An event object, or if publishing a batch of events, an array of event objects. | | ||
| event.event | <code>string</code> | Event type. Serverless Platform system events are required to follow a `<entity>[.<sub-entity>].<action>` naming convention (e.g. `user.created`, `org.membership.updated`, etc). | | ||
| event.data | <code>Object</code> | Event metadata. Serverless Platform system events are required to be formatted as described in the example below. | | ||
**Example** _(user event)_ | ||
```js | ||
const { ServerlessSDK } = require("@serverless/platform-client"); | ||
const sdk = new ServerlessSDK({ accessKey: "123456789" }); | ||
await sdk.events.publish({ | ||
event: "user.created", | ||
data: { | ||
id: "user-123", | ||
username: "testuser", | ||
}, | ||
}); | ||
``` | ||
**Example** _(system event)_ | ||
```js | ||
const { ServerlessSDK } = require("@serverless/platform-client"); | ||
const sdk = new ServerlessSDK({ accessKey: "123456789" }); | ||
await sdk.events.publish({ | ||
event: "entity.updated", | ||
data: { | ||
object: { | ||
// state of the Serverless Platform object as of after the operation | ||
object: "name", | ||
// ...properties | ||
}, | ||
previous_attributes: { | ||
// only being set on `*.updated` event types and contains modified property values as of before the update | ||
//...properties | ||
}, | ||
const sdk = new ServerlessSDK(); | ||
sdk.config({ | ||
accessKey: "123456789", | ||
context: { | ||
orgName: "my-org", | ||
orgUid: "1234", | ||
stageName: "prod", | ||
appName: "my-app", | ||
instanceName: "my-instance", | ||
}, | ||
@@ -225,375 +197,2 @@ }); | ||
<a name="ServerlessSDK+events.get"></a> | ||
#### events.get(uid) ⇒ <code>Promise.<Object></code> | ||
Retrieve a Serverless Platform Event. | ||
**Kind**: static method of [<code>events</code>](#ServerlessSDK+events) | ||
**Returns**: <code>Promise.<Object></code> - An event object if a valid id was provided. All Serverless Platform system events share a common structure, detailed below. The only property that will differ is the `data` payload. | ||
```json | ||
{ | ||
"uid": "evt_P3Soi8VviLNve2QYd6zasxSc", | ||
"event": "application.init_token.created", | ||
"created": 1594652316623, | ||
"data": { | ||
"object": { | ||
"object": "init_token", | ||
"template": { | ||
"directory": "my-fullstack-app", | ||
"packageName": "fullstack-app", | ||
"projectType": "components", | ||
"serviceName": "my-fullstack-app", | ||
"type": "registry" | ||
}, | ||
"uid": "ae9L37wJym0", | ||
"user_uid": "MswS9z6GtpSd6gG694", | ||
"username": "testuser123" | ||
} | ||
} | ||
} | ||
``` | ||
| Param | Type | Description | | ||
| ----- | ------------------- | --------------------------- | | ||
| uid | <code>string</code> | UID of event to be fetched. | | ||
<a name="ServerlessSDK+events.list"></a> | ||
#### events.list([options]) ⇒ <code>Promise.<Object></code> | ||
List all Serverless Platform events. | ||
**Kind**: static method of [<code>events</code>](#ServerlessSDK+events) | ||
**Returns**: <code>Promise.<Object></code> - A dictionary with a `data` property that contains an array of up to `limit` events, starting after event `starting_after`. Each entry in the array is a separate `event` Object. If no more events are available, the resulting array will be empty. | ||
```json | ||
{ | ||
"object": "list", | ||
"data": [ | ||
{ | ||
"uid": "evt_P3Soi8VviLNve2QYd6zasxSc", | ||
"event": "application.init_token.created", | ||
"created": 1594652316623, | ||
"data": { | ||
"object": { | ||
"object": "init_token", | ||
"template": { | ||
"directory": "my-fullstack-app", | ||
"packageName": "fullstack-app", | ||
"projectType": "components", | ||
"serviceName": "my-fullstack-app", | ||
"type": "registry" | ||
}, | ||
"uid": "ae9L37wJym0", | ||
"user_uid": "MswS9z6GtpSd6gG694", | ||
"username": "testuser123" | ||
} | ||
} | ||
} | ||
{...}, | ||
{...} | ||
] | ||
} | ||
``` | ||
| Param | Type | Description | | ||
| ---------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ||
| [options] | <code>Object</code> | List options | | ||
| options.org_name | <code>string</code> | The name of the Serverless Platform Organization. Optional. By default, fetches events under the connecting organization. | | ||
| options.org_uid | <code>string</code> | UID of the Serverless Platform Organization. Optional. By default, fetches events under the connecting organization. | | ||
| options.event | <code>string</code> | A string containing a specific event name, or all events by using `'*'` as a wildcard. | | ||
| options.limit | <code>number</code> | A limit on the number of events to be returned. Limit can range between 1 and 100, and the default is 10. | | ||
| options.created | <code>number</code> | A filter on the list based on the object created field. The value can be an integer Unix timestamp, or it can be a dictionary with the following options: - `created.gt`, `created.gte`, `created.lt`, `created.lte` returning results where the event `created` field is greater, greater than or equal to, lesser than, or lesser than or equal to respectively. | | ||
| options.starting_after | <code>string</code> | A cursor for use in pagination. `starting_after` is an event ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `evt_foo`, your subsequent call can include `starting_after=evt_foo` in order to fetch the next page of the list. | | ||
<a name="ServerlessSDK+events.send"></a> | ||
#### ~~events.send(event) ⇒ <code>null</code> \| <code>Promise.<null></code>~~ | ||
**_Deprecated_** | ||
Dispatches a Serverless Platform Event via Websockets. The use-case for this is asynchronous publishing, where you do not want to synchronous auth requests, where every message must be authorized first, adding latency. | ||
**Kind**: static method of [<code>events</code>](#ServerlessSDK+events) | ||
| Param | Type | Description | | ||
| ----------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| event | <code>Object</code> \| <code>Array.<Object></code> | An event object, or if publishing a batch of events, an array of event objects. | | ||
| event.event | <code>string</code> | Event type. Serverless Platform system events are required to follow a `<entity>[.<sub-entity>].<action>` naming convention (e.g. `user.created`, `org.membership.updated`, etc). | | ||
| event.data | <code>Object</code> | Event metadata. Serverless Platform system events are required to be formatted as described in the example below. | | ||
**Example** _(user event)_ | ||
```js | ||
const { ServerlessSDK } = require("@serverless/platform-client"); | ||
const sdk = new ServerlessSDK({ accessKey: "123456789" }); | ||
sdk.connect({ | ||
orgName: "serverless", | ||
}); | ||
sdk.events.send({ | ||
event: "user.created", | ||
data: { | ||
id: "user-123", | ||
username: "testuser", | ||
}, | ||
}); | ||
``` | ||
**Example** _(system event)_ | ||
const { ServerlessSDK } = require('@serverless/platform-client'); | ||
const sdk = new ServerlessSDK({ accessKey: '123456789' }); | ||
sdk.connect({ | ||
orgName: 'serverless', | ||
}); | ||
sdk.events.send({ | ||
event: 'entity.updated', | ||
data: { | ||
object: { // state of the Serverless Platform object as of after the operation | ||
object: 'name', | ||
// ...properties | ||
}, | ||
previous_attributes: { // only being set on `*.updated` event types and contains modified property values as of before the update | ||
//...properties | ||
}, | ||
}, | ||
}); | ||
```` | ||
<a name="ServerlessSDK+webhooks"></a> | ||
### serverlessSDK.webhooks : <code>object</code> | ||
Register, modify and query Serverless Platform Event Webhooks | ||
**Kind**: instance namespace of [<code>ServerlessSDK</code>](#ServerlessSDK) | ||
* [.webhooks](#ServerlessSDK+webhooks) : <code>object</code> | ||
* [.register(url)](#ServerlessSDK+webhooks.register) ⇒ <code>Promise.<object></code> | ||
* [.list()](#ServerlessSDK+webhooks.list) ⇒ <code>Promise.<object></code> | ||
* [.get(uid)](#ServerlessSDK+webhooks.get) ⇒ <code>Promise.<object></code> | ||
* [.update(uid)](#ServerlessSDK+webhooks.update) ⇒ <code>Promise.<object></code> | ||
* [.delete(uid)](#ServerlessSDK+webhooks.delete) ⇒ <code>Promise.<object></code> | ||
<a name="ServerlessSDK+webhooks.register"></a> | ||
#### webhooks.register(url) ⇒ <code>Promise.<object></code> | ||
Registers a webhook endpoint to receive Serverless Platform events. Endpoint should be able to receieve JSON formatted event as a HTTP POST payload. | ||
**Kind**: static method of [<code>webhooks</code>](#ServerlessSDK+webhooks) | ||
**Returns**: <code>Promise.<object></code> - Registered webhook endpoint. | ||
```json | ||
{ | ||
"uid": "whk_2y9fUcnZroc8BhMjC26tQdg8", | ||
"object": "webhook_endpoint", | ||
"url": "https://postb.in/1598300732037-0682672155089", | ||
"description": "This is my webhook, I like it a lot", | ||
"filter": { | ||
"enabled_events": ["*"] | ||
}, | ||
"status": { | ||
"disabled": false | ||
}, | ||
"created": 1593710260258 | ||
} | ||
```` | ||
| Param | Type | Description | | ||
| ----------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------- | | ||
| url | <code>string</code> | HTTP webhook endpoint URL. | | ||
| options.description | <code>string</code> | An optional description of what the webhook is used for. | | ||
| options.filter | <code>Object</code> | Optionally, filter which events this endpoint should receive. | | ||
| options.filter.enabled_events | <code>Array.<string></code> | The list of events to enable for this endpoint. `["*"]` indicates that all events are enabled. | | ||
<a name="ServerlessSDK+webhooks.list"></a> | ||
#### webhooks.list() ⇒ <code>Promise.<object></code> | ||
Lists all regsitered webhook endpoints. | ||
**Kind**: static method of [<code>webhooks</code>](#ServerlessSDK+webhooks) | ||
**Returns**: <code>Promise.<object></code> - A dictionary with a `data` property that contains an array, with each entry being a `webhook` object. | ||
```json | ||
{ | ||
"object": "list", | ||
"data": [ | ||
{ | ||
"uid": "whk_2y9fUcnZroc8BhMjC26tQdg8", | ||
"object": "webhook_endpoint", | ||
"url": "https://postb.in/1598300732037-0682672155089", | ||
"description": "This is my webhook, I like it a lot", | ||
"filter": { | ||
"enabled_events": ["*"] | ||
}, | ||
"status": { | ||
"disabled": false, | ||
"most_recent_delivery": { | ||
"event_uid": "evt_5cmXN7kqdu5YY69HFKegmiGR", | ||
"response_status_code": 200, | ||
"response_headers": { | ||
"content-length": "12", | ||
"connection": "close", | ||
"content-type": "application/json" | ||
}, | ||
"request_headers": { | ||
"User-Agent": "Serverless-Webhook/0.1", | ||
"Content-type": "application/json", | ||
"X-Serverless-Delivery": "e1701c44-5d92-4515-8bfb-6c9173a89b60", | ||
"X-Serverless-Event": "test.webhook.send2" | ||
}, | ||
"response_text": "{\"ok\": true}", | ||
"error_message": null, | ||
"timestamp": 1599595612876 | ||
} | ||
}, | ||
"created": 1599591851267, | ||
"updated": 1599595613099 | ||
}, | ||
{...}, | ||
{...} | ||
] | ||
} | ||
``` | ||
| Param | Type | Description | | ||
| ---------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| options.starting_after | <code>string</code> | A cursor for use in pagination. `starting_after` is a webhook endpoint object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `whe_foo`, your subsequent call can include `starting_after=whe_foo` in order to fetch the next page of the list. | | ||
| options.limit | <code>number</code> | A limit on the number of webhook endpoints to be returned. Limit can range between 1 and 100, and the default is 10. | | ||
<a name="ServerlessSDK+webhooks.get"></a> | ||
#### webhooks.get(uid) ⇒ <code>Promise.<object></code> | ||
Retrieves a webhook endpoint with the given ID. | ||
**Kind**: static method of [<code>webhooks</code>](#ServerlessSDK+webhooks) | ||
**Returns**: <code>Promise.<object></code> - A webhook endpoint if a valid webhook endpoint ID was provided. | ||
````json | ||
{ | ||
"uid": "whk_2y9fUcnZroc8BhMjC26tQdg8", | ||
"object": "webhook_endpoint", | ||
"url": "https://postb.in/1598300732037-0682672155089", | ||
"description": "This is my webhook, I like it a lot", | ||
"filter": { | ||
"enabled_events": ["*"] | ||
}, | ||
"status": { | ||
"disabled": false, | ||
"most_recent_delivery": { | ||
"event_uid": "evt_5cmXN7kqdu5YY69HFKegmiGR", | ||
"response_status_code": 200, | ||
"response_headers": { | ||
"content-length": "12", | ||
"connection": "close", | ||
"content-type": "application/json" | ||
}, | ||
"request_headers": { | ||
"User-Agent": "Serverless-Webhook/0.1", | ||
"Content-type": "application/json", | ||
"X-Serverless-Delivery": "e1701c44-5d92-4515-8bfb-6c9173a89b60", | ||
"X-Serverless-Event": "test.webhook.send2" | ||
}, | ||
"response_text": "{\"ok\": true}", | ||
"error_message": null, | ||
"timestamp": 1599595612876 | ||
} | ||
}, | ||
"created": 1599591851267, | ||
"updated": 1599595613099 | ||
} | ||
| Param | Type | Description | | ||
| --- | --- | --- | | ||
| uid | <code>string</code> | Webhook endpoint ID. | | ||
<a name="ServerlessSDK+webhooks.update"></a> | ||
#### webhooks.update(uid) ⇒ <code>Promise.<object></code> | ||
Updates the registered webhook endpoint. You may edit the url, description, the list of filters, and the status of your endpoint. | ||
**Kind**: static method of [<code>webhooks</code>](#ServerlessSDK+webhooks) | ||
**Returns**: <code>Promise.<object></code> - Updated webhook endpoint. | ||
```json | ||
{ | ||
"uid": "whk_2y9fUcnZroc8BhMjC26tQdg8", | ||
"object": "webhook_endpoint", | ||
"url": "https://postb.in/1598300732037-0682672155089", | ||
"description": "This is my webhook, I like it a lot", | ||
"filter": { | ||
"enabled_events": ["*"] | ||
}, | ||
"status": { | ||
"disabled": false | ||
}, | ||
"created": 1593710260258 | ||
} | ||
```` | ||
| Param | Type | Description | | ||
| ----------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | ||
| uid | <code>string</code> | Webhook endpoint ID. | | ||
| updates.url | <code>string</code> | HTTP webhook endpoint url, if updating. | | ||
| updates.description | <code>string</code> | An optional updated description of what the webhook is used for. | | ||
| updates.filter | <code>Object</code> | Optionally, update filter which events this endpoint should receive. An existing filter can reset by setting it to `null`. | | ||
| updates.filter.enabled_events | <code>Array.<string></code> | The list of events to enable for this endpoint. `["*"]` indicates that all events are enabled. | | ||
| updates.status.disabled | <code>boolean</code> | Enable/disable the webhook endpoint. | | ||
<a name="ServerlessSDK+webhooks.delete"></a> | ||
#### webhooks.delete(uid) ⇒ <code>Promise.<object></code> | ||
Deletes the webhook endpoint with the given ID. | ||
**Kind**: static method of [<code>webhooks</code>](#ServerlessSDK+webhooks) | ||
**Returns**: <code>Promise.<object></code> - An object with the deleted webhook endpoints’s ID if a valid webhook endpoint ID was provided. Otherwise, this call throws an error, such as if the webhook endpoint has already been deleted. | ||
````json | ||
{ | ||
"uid": "whk_2y9fUcnZroc8BhMjC26tQdg8", | ||
"object": "webhook_endpoint", | ||
"deleted": true | ||
} | ||
| Param | Type | Description | | ||
| --- | --- | --- | | ||
| uid | <code>string</code> | Webhook endpoint ID. | | ||
<a name="ServerlessSDK+config"></a> | ||
### serverlessSDK.config() ⇒ <code>null</code> | ||
Updates the SDK configuration | ||
**Kind**: instance method of [<code>ServerlessSDK</code>](#ServerlessSDK) | ||
| Param | Type | Description | | ||
| --- | --- | --- | | ||
| [config.accessKey] | <code>string</code> | Can either be a Serverless Platform Access Key or an ID Token. | | ||
| [config.platformStage] | <code>string</code> | The Serverless Platform Stage you wish to interact with. This can also be set by the environment variable SERVERLESS_PLATFORM_STAGE= | | ||
| [context.orgName] | <code>string</code> | The name of the Serverless Platform Organization you wish to interact with. If set, this value is used upon creating a Websockets connection, and auto-added to every Event you publish. | | ||
| [context.orgUid] | <code>string</code> | The ID of the Serverless Platform Organization you wish to interact with. If set, this value is used upon creating a Websockets connection, and auto-added to every Event you publish. | | ||
| [context.stageName] | <code>string</code> | The Serverless Platform Organization Stage you wish to interact with. If set, this value is auto-added to every Event you publish. | | ||
| [context.appName] | <code>string</code> | The Serverless Platform Application you wish to interact with. If set, this value is auto-added to every Event you publish. | | ||
| [context.instanceName] | <code>string</code> | The Serverless Platform Instance you wish to interact with. If set, this value is auto-added to every Event you publish. | | ||
| [context.componentName] | <code>string</code> | The Serverless Platform Component you wish to interact with. If set, this value is auto-added to every Event you publish. | | ||
| [context.componentVersion] | <code>string</code> | The Serverless Platform Component version you wish to interact with. If set, this value is auto-added to every Event you publish. | | ||
**Example** | ||
```js | ||
const { ServerlessSDK } = require('@serverless/platform-client') | ||
const sdk = new ServerlessSDK() | ||
sdk.config({ | ||
accessKey: '123456789', | ||
context: { | ||
orgName: 'my-org', | ||
orgUid: '1234', | ||
stageName: 'prod', | ||
appName: 'my-app', | ||
instanceName: 'my-instance' | ||
} | ||
}) | ||
```` | ||
<a name="ServerlessSDK+getDomain"></a> | ||
@@ -956,2 +555,107 @@ | ||
**Returns**: <code>boolean</code> - Will return true if the websocket connection is active. | ||
<a name="ServerlessSDK+publish"></a> | ||
### serverlessSDK.publish() ⇒ <code>null</code> | ||
Publishes a Serverless Platform Event via Websockets. The use-case for this is asynchronous publishing, where you do not want to synchronous auth requests, where every message must be authorized first, adding latency. | ||
**Kind**: instance method of [<code>ServerlessSDK</code>](#ServerlessSDK) | ||
<a name="ServerlessSDK+publishSync"></a> | ||
### serverlessSDK.publishSync(events) ⇒ <code>Promise.<null></code> | ||
Publishes Serverless Platform Event(s) via HTTP API. The use-case for this is synchronous publishing, where you do not want to open a websockets connection. | ||
**Kind**: instance method of [<code>ServerlessSDK</code>](#ServerlessSDK) | ||
**Returns**: <code>Promise.<null></code> - A successful publish request will be ack'ed with a 200:OK HTTP status and empty response. | ||
| Param | Type | Description | | ||
| ------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| events | <code>object</code> | An event object, or if publishing a batch of events, an array of event objects, each structured as follows: `json { "event": "name", "data": { "object": { "object": "name", ...properties }, "previous_attributes": { ...properties } } } ` With `previous_attributes` only being set on `*.updated` event types, and contains the properties with values as of before the update. | | ||
<a name="ServerlessSDK+getEvent"></a> | ||
### serverlessSDK.getEvent(uid) ⇒ <code>Promise.<object></code> | ||
Retrieve a Serverless Platform Event. | ||
**Kind**: instance method of [<code>ServerlessSDK</code>](#ServerlessSDK) | ||
**Returns**: <code>Promise.<object></code> - An event object if a valid id was provided. All events share a common structure, detailed below. The only property that will differ is the `data` payload. | ||
```json | ||
{ | ||
"uid": "evt_P3Soi8VviLNve2QYd6zasxSc", | ||
"event": "application.init_token.created", | ||
"created": 1594652316623, | ||
"data": { | ||
"object": { | ||
"object": "init_token", | ||
"template": { | ||
"directory": "my-fullstack-app", | ||
"packageName": "fullstack-app", | ||
"projectType": "components", | ||
"serviceName": "my-fullstack-app", | ||
"type": "registry" | ||
}, | ||
"uid": "ae9L37wJym0", | ||
"user_uid": "MswS9z6GtpSd6gG694", | ||
"username": "testuser123" | ||
} | ||
} | ||
} | ||
``` | ||
| Param | Type | Description | | ||
| ----- | ------------------- | -------------------------- | | ||
| uid | <code>string</code> | UID of event to be fetched | | ||
<a name="ServerlessSDK+listEvents"></a> | ||
### serverlessSDK.listEvents(options) ⇒ <code>Promise.<object></code> | ||
List all Serverless Platform events. | ||
**Kind**: instance method of [<code>ServerlessSDK</code>](#ServerlessSDK) | ||
**Returns**: <code>Promise.<object></code> - A dictionary with a `data` property that contains an array of up to `limit` events, starting after event `starting_after`. Each entry in the array is a separate `event` object. If no more events are available, the resulting array will be empty. | ||
```json | ||
{ | ||
"object": "list", | ||
"data": [ | ||
{ | ||
"uid": "evt_P3Soi8VviLNve2QYd6zasxSc", | ||
"event": "application.init_token.created", | ||
"created": 1594652316623, | ||
"data": { | ||
"object": { | ||
"object": "init_token", | ||
"template": { | ||
"directory": "my-fullstack-app", | ||
"packageName": "fullstack-app", | ||
"projectType": "components", | ||
"serviceName": "my-fullstack-app", | ||
"type": "registry" | ||
}, | ||
"uid": "ae9L37wJym0", | ||
"user_uid": "MswS9z6GtpSd6gG694", | ||
"username": "testuser123" | ||
} | ||
} | ||
} | ||
{...}, | ||
{...} | ||
] | ||
} | ||
``` | ||
| Param | Type | Description | | ||
| ---------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ||
| options | <code>Object</code> | List options | | ||
| options.org_name | <code>string</code> | The name of the Serverless Platform Organization. Optional. By default, fetches events under the connecting organization. | | ||
| options.org_uid | <code>string</code> | UID of the Serverless Platform Organization. Optional. By default, fetches events under the connecting organization. | | ||
| options.event | <code>string</code> | A string containing a specific event name, or all events by using `'*'` as a wildcard. | | ||
| options.limit | <code>number</code> | A limit on the number of events to be returned. Limit can range between 1 and 100, and the default is 10. | | ||
| options.created | <code>number</code> | A filter on the list based on the object created field. The value can be an integer Unix timestamp, or it can be a dictionary with the following options: - `created.gt`, `created.gte`, `created.lt`, `created.lte` returning results where the event `created` field is greater, greater than or equal to, lesser than, or lesser than or equal to respectively. | | ||
| options.starting_after | <code>string</code> | A cursor for use in pagination. `starting_after` is an event ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `evt_foo`, your subsequent call can include `starting_after=evt_foo` in order to fetch the next page of the list. | | ||
<a name="ServerlessSDK+unpublishFromRegistry"></a> | ||
@@ -1143,4 +847,191 @@ | ||
**Kind**: instance method of [<code>ServerlessSDK</code>](#ServerlessSDK) | ||
<a name="ServerlessSDK+registerWebhook"></a> | ||
### serverlessSDK.registerWebhook(url) ⇒ <code>Promise.<object></code> | ||
Registers a webhook endpoint to receive Serverless Platform events. Endpoint should be able to receieve JSON formatted event as a HTTP POST payload. | ||
**Kind**: instance method of [<code>ServerlessSDK</code>](#ServerlessSDK) | ||
**Returns**: <code>Promise.<object></code> - Registered webhook endpoint. | ||
```json | ||
{ | ||
"uid": "whk_2y9fUcnZroc8BhMjC26tQdg8", | ||
"object": "webhook_endpoint", | ||
"url": "https://postb.in/1598300732037-0682672155089", | ||
"description": "This is my webhook, I like it a lot", | ||
"filter": { | ||
"enabled_events": ["*"] | ||
}, | ||
"status": { | ||
"disabled": false | ||
}, | ||
"created": 1593710260258 | ||
} | ||
``` | ||
| Param | Type | Description | | ||
| ----------------------------- | ------------------- | ---------------------------------------------------------------------------------------------- | | ||
| url | <code>string</code> | HTTP webhook endpoint URL. | | ||
| options.description | <code>string</code> | An optional description of what the webhook is used for. | | ||
| options.filter | <code>object</code> | Optionally, filter which events this endpoint should receive. | | ||
| options.filter.enabled_events | <code>object</code> | The list of events to enable for this endpoint. `["*"]` indicates that all events are enabled. | | ||
<a name="ServerlessSDK+listWebhooks"></a> | ||
### serverlessSDK.listWebhooks() ⇒ <code>Promise.<object></code> | ||
Lists all regsitered webhook endpoints. | ||
**Kind**: instance method of [<code>ServerlessSDK</code>](#ServerlessSDK) | ||
**Returns**: <code>Promise.<object></code> - A dictionary with a `data` property that contains an array, with each entry being a `webhook` object. | ||
```json | ||
{ | ||
"object": "list", | ||
"data": [ | ||
{ | ||
"uid": "whk_2y9fUcnZroc8BhMjC26tQdg8", | ||
"object": "webhook_endpoint", | ||
"url": "https://postb.in/1598300732037-0682672155089", | ||
"description": "This is my webhook, I like it a lot", | ||
"filter": { | ||
"enabled_events": ["*"] | ||
}, | ||
"status": { | ||
"disabled": false, | ||
"most_recent_delivery": { | ||
"event_uid": "evt_5cmXN7kqdu5YY69HFKegmiGR", | ||
"response_status_code": 200, | ||
"response_headers": { | ||
"content-length": "12", | ||
"connection": "close", | ||
"content-type": "application/json" | ||
}, | ||
"request_headers": { | ||
"User-Agent": "Serverless-Webhook/0.1", | ||
"Content-type": "application/json", | ||
"X-Serverless-Delivery": "e1701c44-5d92-4515-8bfb-6c9173a89b60", | ||
"X-Serverless-Event": "test.webhook.send2" | ||
}, | ||
"response_text": "{\"ok\": true}", | ||
"error_message": null, | ||
"timestamp": 1599595612876 | ||
} | ||
}, | ||
"created": 1599591851267, | ||
"updated": 1599595613099 | ||
}, | ||
{...}, | ||
{...} | ||
] | ||
} | ||
``` | ||
| Param | Type | Description | | ||
| ---------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| options.starting_after | <code>string</code> | A cursor for use in pagination. `starting_after` is a webhook endpoint object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `whe_foo`, your subsequent call can include `starting_after=whe_foo` in order to fetch the next page of the list. | | ||
| options.limit | <code>number</code> | A limit on the number of webhook endpoints to be returned. Limit can range between 1 and 100, and the default is 10. | | ||
<a name="ServerlessSDK+getWebhook"></a> | ||
### serverlessSDK.getWebhook(uid) ⇒ <code>Promise.<object></code> | ||
Retrieves a webhook endpoint with the given ID. | ||
**Kind**: instance method of [<code>ServerlessSDK</code>](#ServerlessSDK) | ||
**Returns**: <code>Promise.<object></code> - A webhook endpoint if a valid webhook endpoint ID was provided. | ||
````json | ||
{ | ||
"uid": "whk_2y9fUcnZroc8BhMjC26tQdg8", | ||
"object": "webhook_endpoint", | ||
"url": "https://postb.in/1598300732037-0682672155089", | ||
"description": "This is my webhook, I like it a lot", | ||
"filter": { | ||
"enabled_events": ["*"] | ||
}, | ||
"status": { | ||
"disabled": false, | ||
"most_recent_delivery": { | ||
"event_uid": "evt_5cmXN7kqdu5YY69HFKegmiGR", | ||
"response_status_code": 200, | ||
"response_headers": { | ||
"content-length": "12", | ||
"connection": "close", | ||
"content-type": "application/json" | ||
}, | ||
"request_headers": { | ||
"User-Agent": "Serverless-Webhook/0.1", | ||
"Content-type": "application/json", | ||
"X-Serverless-Delivery": "e1701c44-5d92-4515-8bfb-6c9173a89b60", | ||
"X-Serverless-Event": "test.webhook.send2" | ||
}, | ||
"response_text": "{\"ok\": true}", | ||
"error_message": null, | ||
"timestamp": 1599595612876 | ||
} | ||
}, | ||
"created": 1599591851267, | ||
"updated": 1599595613099 | ||
} | ||
| Param | Type | Description | | ||
| --- | --- | --- | | ||
| uid | <code>string</code> | Webhook endpoint ID. | | ||
<a name="ServerlessSDK+updateWebhook"></a> | ||
### serverlessSDK.updateWebhook(uid) ⇒ <code>Promise.<object></code> | ||
Updates the registered webhook endpoint. You may edit the url, description, the list of filters, and the status of your endpoint. | ||
**Kind**: instance method of [<code>ServerlessSDK</code>](#ServerlessSDK) | ||
**Returns**: <code>Promise.<object></code> - Updated webhook endpoint. | ||
```json | ||
{ | ||
"uid": "whk_2y9fUcnZroc8BhMjC26tQdg8", | ||
"object": "webhook_endpoint", | ||
"url": "https://postb.in/1598300732037-0682672155089", | ||
"description": "This is my webhook, I like it a lot", | ||
"filter": { | ||
"enabled_events": ["*"] | ||
}, | ||
"status": { | ||
"disabled": false | ||
}, | ||
"created": 1593710260258 | ||
} | ||
```` | ||
| Param | Type | Description | | ||
| ----------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------- | | ||
| uid | <code>string</code> | Webhook endpoint ID. | | ||
| updates.url | <code>string</code> | HTTP webhook endpoint url, if updating. | | ||
| updates.description | <code>string</code> | An optional updated description of what the webhook is used for. | | ||
| updates.filter | <code>object</code> | Optionally, update filter which events this endpoint should receive. An existing filter can reset by setting it to `null`. | | ||
| updates.filter.enabled_events | <code>object</code> | The list of events to enable for this endpoint. `["*"]` indicates that all events are enabled. | | ||
| updates.status.disabled | <code>boolean</code> | Enable/disable the webhook endpoint. | | ||
<a name="ServerlessSDK+deleteWebhook"></a> | ||
### serverlessSDK.deleteWebhook(uid) ⇒ <code>Promise.<object></code> | ||
Deletes the webhook endpoint with the given ID. | ||
**Kind**: instance method of [<code>ServerlessSDK</code>](#ServerlessSDK) | ||
**Returns**: <code>Promise.<object></code> - An object with the deleted webhook endpoints’s ID if a valid webhook endpoint ID was provided. Otherwise, this call throws an error, such as if the webhook endpoint has already been deleted. | ||
```json | ||
{ | ||
"uid": "whk_2y9fUcnZroc8BhMjC26tQdg8", | ||
"object": "webhook_endpoint", | ||
"deleted": true | ||
} | ||
| Param | Type | Description | | ||
| --- | --- | --- | | ||
| uid | <code>string</code> | Webhook endpoint ID. | | ||
## Publishing the SDK | ||
@@ -1150,4 +1041,5 @@ | ||
--- | ||
* * * | ||
© Serverless Inc. | ||
``` |
@@ -7,14 +7,14 @@ 'use strict'; | ||
* Validate a publish event(s) request | ||
* @param {*} events | ||
* @param {Object|Object[]} event An event object, or if publishing a batch of events, an array of event objects. | ||
*/ | ||
function validate(events) { | ||
if (!events) { | ||
function validate(event) { | ||
if (!event) { | ||
throw new Error('An "event" is required'); | ||
} | ||
if (typeof events !== 'object') { | ||
if (typeof event !== 'object') { | ||
throw new Error('The "event" argument must be an object'); | ||
} | ||
const validEvent = (event) => { | ||
if (!event.event || typeof event.event !== 'string') { | ||
const validateObject = ({ event: type }) => { | ||
if (!type || typeof type !== 'string') { | ||
throw new Error( | ||
@@ -26,4 +26,4 @@ 'The "event" property containing the event type is required and must be a string' | ||
if (Array.isArray(events)) { | ||
if (!events.length) { | ||
if (Array.isArray(event)) { | ||
if (!event.length) { | ||
throw new Error('Event batch must be non empty'); | ||
@@ -35,5 +35,9 @@ } | ||
events.forEach((event) => { | ||
validEvent(event); | ||
if (orgUid && (event.org_uid || event.orgUid) && orgUid !== (event.org_uid || event.orgUid)) { | ||
event.forEach((object) => { | ||
validateObject(object); | ||
if ( | ||
orgUid && | ||
(object.org_uid || object.orgUid) && | ||
orgUid !== (object.org_uid || object.orgUid) | ||
) { | ||
throw new Error('All events in batch must belong to the same org uid'); | ||
@@ -43,49 +47,47 @@ } | ||
orgName && | ||
(event.org_name || event.orgName) && | ||
orgName !== (event.org_name || event.orgName) | ||
(object.org_name || object.orgName) && | ||
orgName !== (object.org_name || object.orgName) | ||
) { | ||
throw new Error('All events in batch must belong to the same org name'); | ||
} | ||
orgUid = event.org_uid || event.orgUid || orgUid; | ||
orgName = event.org_name || event.orgName || orgName; | ||
orgUid = object.org_uid || object.orgUid || orgUid; | ||
orgName = object.org_name || object.orgName || orgName; | ||
}); | ||
if (orgUid) { | ||
events[0].orgUid = events[0].org_uid = orgUid; | ||
event[0].orgUid = event[0].org_uid = orgUid; | ||
} | ||
if (orgName) { | ||
events[0].orgName = events[0].org_name = orgName; | ||
event[0].orgName = event[0].org_name = orgName; | ||
} | ||
} else { | ||
validEvent(events); | ||
validateObject(event); | ||
} | ||
return events; | ||
return event; | ||
} | ||
function safeEvent(event) { | ||
return { | ||
event: event.event.trim(), | ||
user_uid: event.user_uid || event.userUid, | ||
stage_name: event.stage_name || event.stageName, | ||
app_name: event.app_name || event.appName, | ||
instance_name: event.instance_name || event.instanceName, | ||
component_name: event.component_name || event.componentName, | ||
component_version: event.component_version || event.componentVersion, | ||
data: event.data || {}, | ||
created: event.created || Date.now(), | ||
}; | ||
} | ||
/** | ||
* Convert to a safe Serverless Platform Event | ||
* @param {object} events Event object, or if publishing a batch, an array of event objects | ||
* @param {Object|Object[]} event An event object, or if publishing a batch of events, an array of event objects. | ||
* @param {object} context SDK context that gets passed on to the event(s) | ||
* @param {string} accessKey Serverless Platform access key | ||
*/ | ||
function transform(events, context, accessKey) { | ||
function transform(event, context, accessKey) { | ||
const safeEvent = (object) => ({ | ||
event: object.event.trim(), | ||
user_uid: object.user_uid || object.userUid, | ||
stage_name: object.stage_name || object.stageName, | ||
app_name: object.app_name || object.appName, | ||
instance_name: object.instance_name || object.instanceName, | ||
component_name: object.component_name || object.componentName, | ||
component_version: object.component_version || object.componentVersion, | ||
data: object.data || {}, | ||
created: object.created || Date.now(), | ||
}); | ||
let transformed; | ||
if (Array.isArray(events)) { | ||
if (Array.isArray(event)) { | ||
const safe = safeEvent({ | ||
event: 'batch', | ||
data: events.map((event) => safeEvent(event)), | ||
data: event.map((object) => safeEvent(object)), | ||
}); | ||
@@ -95,4 +97,4 @@ // Set batch metadata from sdk context (overridden by individual event metadata, if any) | ||
...safe, | ||
org_uid: events[0].orgUid || context.orgUid, | ||
org_name: events[0].orgName || context.orgName, | ||
org_uid: event[0].orgUid || context.orgUid, | ||
org_name: event[0].orgName || context.orgName, | ||
stage_name: context.stageName, | ||
@@ -105,8 +107,8 @@ app_name: context.appName, | ||
} else { | ||
const safe = safeEvent(events); | ||
const safe = safeEvent(event); | ||
// Add missing metdata from sdk context if required | ||
transformed = { | ||
...safe, | ||
org_uid: events.org_uid || events.orgUid || context.orgUid, | ||
org_name: events.org_name || events.orgName || context.orgName, | ||
org_uid: event.org_uid || event.orgUid || context.orgUid, | ||
org_name: event.org_name || event.orgName || context.orgName, | ||
stage_name: safe.stage_name || context.stageName, | ||
@@ -131,3 +133,3 @@ app_name: safe.app_name || context.appName, | ||
* Send an event via the Websockets connection. | ||
* @param {*} event | ||
* @param {Object|Object[]} event An event object, or if publishing a batch of events, an array of event objects. | ||
*/ | ||
@@ -143,6 +145,6 @@ module.exports.send = (event, connection, context, accessKey) => { | ||
/** | ||
* Publish event(s) synchornously, via the HTTP API | ||
* @param {*} events | ||
* Publish event(s) synchornously, via the HTTP API. | ||
* @param {Object|Object[]} event An event object, or if publishing a batch of events, an array of event objects. | ||
*/ | ||
module.exports.publish = (events, domain, context, accessKey) => { | ||
module.exports.publish = (event, domain, context, accessKey) => { | ||
return utils.request({ | ||
@@ -152,3 +154,3 @@ endpoint: `${domain}/publish`, | ||
method: 'POST', | ||
data: transform(validate(events), context), | ||
data: transform(validate(event), context), | ||
}); | ||
@@ -171,5 +173,8 @@ }; | ||
* Retrieve a Serverless Platform Event synchronously via HTTP API. | ||
* @param {Object} options List options | ||
* @param {string} domain Serverless Platform Events service domain name. | ||
* @param {Object} context Current SDK context. | ||
* @param {string} accessKey Serverless Platform access key. | ||
* @param {Object} options List options. | ||
*/ | ||
module.exports.list = (options, domain, context, accessKey) => { | ||
module.exports.list = (domain, context, accessKey, options = {}) => { | ||
const { | ||
@@ -182,3 +187,3 @@ org_name: orgName = null, | ||
starting_after: startingAfter, | ||
} = options || {}; | ||
} = options; | ||
@@ -196,2 +201,5 @@ const params = new URLSearchParams({ event, limit }); | ||
} | ||
if (!params.has('org_uid') && !params.has('org_name')) { | ||
throw new Error('Must pass in options or set SDK context for `org_uid`/`org_name`'); | ||
} | ||
@@ -198,0 +206,0 @@ if (created) { |
465
src/index.js
@@ -74,4 +74,3 @@ 'use strict'; | ||
* @example <caption>user event</caption> | ||
* const { ServerlessSDK } = require('@serverless/platform-client'); | ||
* const sdk = new ServerlessSDK({ accessKey: '123456789' }); | ||
* sdk.config({ context: { orgUid: '3xVy2MWGFqpGYSlRMd' } }); | ||
* await sdk.events.publish({ | ||
@@ -86,12 +85,20 @@ * event: 'user.created', | ||
* @example <caption>system event</caption> | ||
* const { ServerlessSDK } = require('@serverless/platform-client'); | ||
* const sdk = new ServerlessSDK({ accessKey: '123456789' }); | ||
* await sdk.events.publish({ | ||
* event: 'entity.updated', | ||
* data: { | ||
* object: { // state of the Serverless Platform object as of after the operation | ||
* event: 'entity.updated', // follows a `<entity>[.<sub-entity>].<action>` naming convention | ||
* user_uid: 'user-111', // user attributable for event action if applicable - optional | ||
* // either of the following properties are required to be set and if not, inherit from current sdk context | ||
* org_uid: 'org-42', | ||
* org_name: 'serverless', | ||
* // the following properties are optional and default to inheriting from current sdk context | ||
* app_name: 'app-222', | ||
* instance_name: 'instance-333', | ||
* stage_name: 'us-east-1', | ||
* component_name: 'component-444', | ||
* component_version: '1.2.3', | ||
* data: { // event payload - required and must match the format below | ||
* object: { // Serverless Platform object targeted by action | ||
* object: 'name', | ||
* // ...properties | ||
* }, | ||
* previous_attributes: { // only being set on `*.updated` event types and contains modified property values as of before the update | ||
* previous_attributes: { // only set on `*.updated` event types and contains modified property values as of before the update | ||
* //...properties | ||
@@ -108,25 +115,27 @@ * }, | ||
* @param {string} uid UID of event to be fetched. | ||
* @returns {Promise<Object>} An event object if a valid id was provided. All Serverless Platform system events share a common structure, detailed below. The only property that will differ is the `data` payload. | ||
* ```json | ||
* { | ||
* "uid": "evt_P3Soi8VviLNve2QYd6zasxSc", | ||
* "event": "application.init_token.created", | ||
* "created": 1594652316623, | ||
* "data": { | ||
* "object": { | ||
* "object": "init_token", | ||
* "template": { | ||
* "directory": "my-fullstack-app", | ||
* "packageName": "fullstack-app", | ||
* "projectType": "components", | ||
* "serviceName": "my-fullstack-app", | ||
* "type": "registry" | ||
* }, | ||
* "uid": "ae9L37wJym0", | ||
* "user_uid": "MswS9z6GtpSd6gG694", | ||
* "username": "testuser123" | ||
* } | ||
* } | ||
* } | ||
* ``` | ||
* @returns {Promise<Object>} An event object if a valid id was provided. | ||
* | ||
* @example | ||
* const event = await sdk.events.get('evt_EsbM82sYTVscqYvcD4CKcLe1'); | ||
* console.log(JSON.stringify(event, null, 2)); | ||
* // outputs: | ||
* // { | ||
* // "uid": "evt_EsbM82sYTVscqYvcD4CKcLe1", | ||
* // "event": "member.invite.sent", | ||
* // "org_uid": "3xVy2MWGFqpGYSlRMd", | ||
* // "user_uid": "ps4Vt2phVXsMyD0byW", | ||
* // "object": "event", | ||
* // "created": 1600686488878, | ||
* // "data": { | ||
* // "object": { | ||
* // "org_uid": "3xVy2MWGFqpGYSlRMd", | ||
* // "role": "collaborator", | ||
* // "invited_by_user_uid": "ps4Vt2phVXsMyD0byW", | ||
* // "created": "2020-09-21T11:08:08.603Z", | ||
* // "recipient_email": "dev@serverless.com", | ||
* // "org_name": "serverless", | ||
* // "object": "invite" | ||
* // } | ||
* // } | ||
* // } | ||
*/ | ||
@@ -138,4 +147,4 @@ get: (uid) => events.get(uid, this.getDomain('events'), this.accessKey), | ||
* @param {Object=} options List options | ||
* @param {string} options.org_name The name of the Serverless Platform Organization. Optional. By default, fetches events under the connecting organization. | ||
* @param {string} options.org_uid UID of the Serverless Platform Organization. Optional. By default, fetches events under the connecting organization. | ||
* @param {string} options.org_uid UID of the Serverless Platform Organization. Optional - defaults to inheriting from current SDK context. | ||
* @param {string} options.org_name Name of the Serverless Platform Organization. Optional - defaults to inheriting from current SDK context. | ||
* @param {string} options.event A string containing a specific event name, or all events by using `'*'` as a wildcard. | ||
@@ -146,38 +155,41 @@ * @param {number} options.limit A limit on the number of events to be returned. Limit can range between 1 and 100, and the default is 10. | ||
* @returns {Promise<Object>} A dictionary with a `data` property that contains an array of up to `limit` events, starting after event `starting_after`. Each entry in the array is a separate `event` Object. If no more events are available, the resulting array will be empty. | ||
* ```json | ||
* { | ||
* "object": "list", | ||
* "data": [ | ||
* { | ||
* "uid": "evt_P3Soi8VviLNve2QYd6zasxSc", | ||
* "event": "application.init_token.created", | ||
* "created": 1594652316623, | ||
* "data": { | ||
* "object": { | ||
* "object": "init_token", | ||
* "template": { | ||
* "directory": "my-fullstack-app", | ||
* "packageName": "fullstack-app", | ||
* "projectType": "components", | ||
* "serviceName": "my-fullstack-app", | ||
* "type": "registry" | ||
* }, | ||
* "uid": "ae9L37wJym0", | ||
* "user_uid": "MswS9z6GtpSd6gG694", | ||
* "username": "testuser123" | ||
* } | ||
* } | ||
* } | ||
* {...}, | ||
* {...} | ||
* ] | ||
* } | ||
* ``` | ||
* | ||
* @example | ||
* const events = await sdk.events.list({ | ||
* event: 'member.invite.accepted', | ||
* created: { | ||
* gte: 1600686488878, | ||
* }, | ||
* limit: 1, | ||
* }); | ||
* console.log(JSON.stringify(events, null, 2)); | ||
* // outputs: | ||
* // { | ||
* // "object": "list", | ||
* // "data": [ | ||
* // { | ||
* // "uid": "evt_DdUCdz2tsY7gZr1a9Z6Xw9BD", | ||
* // "event": "member.invite.accepted", | ||
* // "object": "event", | ||
* // "created": 1600707548900, | ||
* // "data": { | ||
* // "object": { | ||
* // "object": "invite", | ||
* // "org_uid": "3xVy2MWGFqpGYSlRMd", | ||
* // "role": "collaborator", | ||
* // "invited_by_user_uid": "ps4Vt2phVXsMyD0byW", | ||
* // "recipient_email": "dev@serverless.com", | ||
* // "org_name": "serverless", | ||
* // "created": "2020-09-21T11:08:08.603Z", | ||
* // } | ||
* // } | ||
* // } | ||
* // ] | ||
* // } | ||
*/ | ||
list: (options) => | ||
events.list(options, this.getDomain('events'), this.context, this.accessKey), | ||
list: (options = {}) => | ||
events.list(this.getDomain('events'), this.context, this.accessKey, options), | ||
/** | ||
* Dispatches a Serverless Platform Event via Websockets. The use-case for this is asynchronous publishing, where you do not want to synchronous auth requests, where every message must be authorized first, adding latency. | ||
* @return {null} | ||
* Dispatches a Serverless Platform Event via Websockets. The use-case for this is asynchronous publishing, where you do not want to synchronous auth requests, where every message must be authorized first, adding latency. | ||
* @deprecated since v2.0 - use {@link ServerelessSDK.events.publish} instead | ||
@@ -188,36 +200,3 @@ * @param {(Object|Object[])} event An event object, or if publishing a batch of events, an array of event objects. | ||
* @returns {Promise<null>} A successful publish request will be ack'ed with a `200: OK` HTTP status and empty response. | ||
* | ||
* @example <caption>user event</caption> | ||
* const { ServerlessSDK } = require('@serverless/platform-client'); | ||
* const sdk = new ServerlessSDK({ accessKey: '123456789' }); | ||
* sdk.connect({ | ||
* orgName: 'serverless', | ||
* }); | ||
* sdk.events.send({ | ||
* event: 'user.created', | ||
* data: { | ||
* id: 'user-123', | ||
* username: 'testuser', | ||
* }, | ||
* }); | ||
* | ||
* @example <caption>system event</caption> | ||
* const { ServerlessSDK } = require('@serverless/platform-client'); | ||
* const sdk = new ServerlessSDK({ accessKey: '123456789' }); | ||
* sdk.connect({ | ||
* orgName: 'serverless', | ||
* }); | ||
* sdk.events.send({ | ||
* event: 'entity.updated', | ||
* data: { | ||
* object: { // state of the Serverless Platform object as of after the operation | ||
* object: 'name', | ||
* // ...properties | ||
* }, | ||
* previous_attributes: { // only being set on `*.updated` event types and contains modified property values as of before the update | ||
* //...properties | ||
* }, | ||
* }, | ||
* }); | ||
* ``` | ||
* @see {@link ServerlessSDK#events.publish} | ||
*/ | ||
@@ -233,73 +212,98 @@ send: (event) => events.send(event, this.connection, this.context, this.accessKey), | ||
/** | ||
* Registers a webhook endpoint to receive Serverless Platform events. Endpoint should be able to receieve JSON formatted event as a HTTP POST payload. | ||
* Registers a webhook endpoint to receive Serverless Platform events. | ||
* | ||
* Endpoint should be able to receieve JSON formatted events as a HTTP POST payload. | ||
* Furthermore, a `3` second timeout limit is enforced on event delivery with no additional retries performed. | ||
* The following HTTP headers are set on the POST request: | ||
* | Header | Value | | ||
* | ----------------------- | ------------------------------- | | ||
* | `Content-type` | `application/json` | | ||
* | `X-Serverless-Event` | Event type | | ||
* | `X-Serverless-Delivery` | Unique delivery ID | | ||
* | `User-Agent` | Prefix of `Serverless-Webhook/` | | ||
* | ||
* @param {string} url HTTP webhook endpoint URL. | ||
* @param {Object=} options Registration options. | ||
* @param {string} options.description An optional description of what the webhook is used for. | ||
* @param {string} options.org_uid UID of the Serverless Platform Organization. Optional - defaults to inheriting from current SDK context. If registering a Serverless Platform system webhook, use a special wildcard value of `'*'` to consume events generated from *all* orgs. | ||
* @param {string} options.org_name Name of the Serverless Platform Organization. Optional - defaults to inheriting from current SDK context. | ||
* @param {Object} options.filter Optionally, filter which events this endpoint should receive. | ||
* @param {string[]} options.filter.enabled_events The list of events to enable for this endpoint. `["*"]` indicates that all events are enabled. | ||
* @returns {Promise<object>} Registered webhook endpoint. | ||
* ```json | ||
* { | ||
* "uid": "whk_2y9fUcnZroc8BhMjC26tQdg8", | ||
* "object": "webhook_endpoint", | ||
* "url": "https://postb.in/1598300732037-0682672155089", | ||
* "description": "This is my webhook, I like it a lot", | ||
* "filter": { | ||
* "enabled_events": ["*"] | ||
* }, | ||
* "status": { | ||
* "disabled": false | ||
* }, | ||
* "created": 1593710260258 | ||
* } | ||
* ``` | ||
* | ||
* @example | ||
* const webhook = await sdk.webhooks.register( | ||
* 'https://postb.in/1598300732037-0682672155089', | ||
* { description: 'This is my webhook, I like it a lot' }, | ||
* ); | ||
* console.log(JSON.stringify(webhook, null, 2)); | ||
* // outputs: | ||
* // { | ||
* // "uid": "whe_FPYDtTL37ye13m3sJvtcdyuF", | ||
* // "object": "webhook_endpoint", | ||
* // "url": "https://postb.in/1598300732037-0682672155089", | ||
* // "description": "This is my webhook, I like it a lot", | ||
* // "filter": { | ||
* // "enabled_events": [ | ||
* // "*" | ||
* // ] | ||
* // }, | ||
* // "status": { | ||
* // "disabled": false | ||
* // }, | ||
* // "created": 1602078105978 | ||
* // } | ||
*/ | ||
register: (url, options = {}) => | ||
webhooks.register(this, url, options.description, options.filter || {}), | ||
register: (url, options = {}) => webhooks.register(this, url, options), | ||
/** | ||
* Lists all regsitered webhook endpoints. | ||
* @param {Object=} options List options. | ||
* @param {string} options.starting_after A cursor for use in pagination. `starting_after` is a webhook endpoint object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `whe_foo`, your subsequent call can include `starting_after=whe_foo` in order to fetch the next page of the list. | ||
* @param {number} options.limit A limit on the number of webhook endpoints to be returned. Limit can range between 1 and 100, and the default is 10. | ||
* @returns {Promise<object>} A dictionary with a `data` property that contains an array, with each entry being a `webhook` object. | ||
* ```json | ||
* { | ||
* "object": "list", | ||
* "data": [ | ||
* { | ||
* "uid": "whk_2y9fUcnZroc8BhMjC26tQdg8", | ||
* "object": "webhook_endpoint", | ||
* "url": "https://postb.in/1598300732037-0682672155089", | ||
* "description": "This is my webhook, I like it a lot", | ||
* "filter": { | ||
* "enabled_events": ["*"] | ||
* }, | ||
* "status": { | ||
* "disabled": false, | ||
* "most_recent_delivery": { | ||
* "event_uid": "evt_5cmXN7kqdu5YY69HFKegmiGR", | ||
* "response_status_code": 200, | ||
* "response_headers": { | ||
* "content-length": "12", | ||
* "connection": "close", | ||
* "content-type": "application/json" | ||
* }, | ||
* "request_headers": { | ||
* "User-Agent": "Serverless-Webhook/0.1", | ||
* "Content-type": "application/json", | ||
* "X-Serverless-Delivery": "e1701c44-5d92-4515-8bfb-6c9173a89b60", | ||
* "X-Serverless-Event": "test.webhook.send2" | ||
* }, | ||
* "response_text": "{\"ok\": true}", | ||
* "error_message": null, | ||
* "timestamp": 1599595612876 | ||
* } | ||
* }, | ||
* "created": 1599591851267, | ||
* "updated": 1599595613099 | ||
* }, | ||
* {...}, | ||
* {...} | ||
* ] | ||
* } | ||
* ``` | ||
* | ||
* @example | ||
* const webhooks = await sdk.webhooks.list({ | ||
* limit: 1, | ||
* }); | ||
* console.log(JSON.stringify(webhooks, null, 2)); | ||
* // outputs: | ||
* // { | ||
* // "object": "list", | ||
* // "data": [ | ||
* // { | ||
* // "uid": "whe_FPYDtTL37ye13m3sJvtcdyuF", | ||
* // "object": "webhook_endpoint", | ||
* // "url": "https://postb.in/1598300732037-0682672155089", | ||
* // "description": "This is my webhook, I like it a lot", | ||
* // "filter": { | ||
* // "enabled_events": ["*"] | ||
* // }, | ||
* // "status": { | ||
* // "disabled": false, | ||
* // "most_recent_delivery": { | ||
* // "event_uid": "evt_5cmXN7kqdu5YY69HFKegmiGR", | ||
* // "response_status_code": 200, | ||
* // "response_headers": { | ||
* // "content-length": "12", | ||
* // "connection": "close", | ||
* // "content-type": "application/json" | ||
* // }, | ||
* // "request_headers": { | ||
* // "User-Agent": "Serverless-Webhook/0.1", | ||
* // "Content-type": "application/json", | ||
* // "X-Serverless-Delivery": "e1701c44-5d92-4515-8bfb-6c9173a89b60", | ||
* // "X-Serverless-Event": "test.webhook.send2" | ||
* // }, | ||
* // "response_text": "{\"ok\": true}", | ||
* // "error_message": null, | ||
* // "timestamp": 1599595612876 | ||
* // } | ||
* // }, | ||
* // "created": 1599591851267, | ||
* // "updated": 1599595613099 | ||
* // }, | ||
* // ] | ||
* // } | ||
*/ | ||
@@ -315,35 +319,39 @@ list: (options = {}) => { | ||
* @returns {Promise<object>} A webhook endpoint if a valid webhook endpoint ID was provided. | ||
* ```json | ||
* { | ||
* "uid": "whk_2y9fUcnZroc8BhMjC26tQdg8", | ||
* "object": "webhook_endpoint", | ||
* "url": "https://postb.in/1598300732037-0682672155089", | ||
* "description": "This is my webhook, I like it a lot", | ||
* "filter": { | ||
* "enabled_events": ["*"] | ||
* }, | ||
* "status": { | ||
* "disabled": false, | ||
* "most_recent_delivery": { | ||
* "event_uid": "evt_5cmXN7kqdu5YY69HFKegmiGR", | ||
* "response_status_code": 200, | ||
* "response_headers": { | ||
* "content-length": "12", | ||
* "connection": "close", | ||
* "content-type": "application/json" | ||
* }, | ||
* "request_headers": { | ||
* "User-Agent": "Serverless-Webhook/0.1", | ||
* "Content-type": "application/json", | ||
* "X-Serverless-Delivery": "e1701c44-5d92-4515-8bfb-6c9173a89b60", | ||
* "X-Serverless-Event": "test.webhook.send2" | ||
* }, | ||
* "response_text": "{\"ok\": true}", | ||
* "error_message": null, | ||
* "timestamp": 1599595612876 | ||
* } | ||
* }, | ||
* "created": 1599591851267, | ||
* "updated": 1599595613099 | ||
* } | ||
* | ||
* @example | ||
* const webhook = await sdk.webhooks.get('whe_FPYDtTL37ye13m3sJvtcdyuF'); | ||
* console.log(JSON.stringify(webhook, null, 2)); | ||
* // outputs: | ||
* // { | ||
* // "uid": "whe_FPYDtTL37ye13m3sJvtcdyuF", | ||
* // "object": "webhook_endpoint", | ||
* // "url": "https://postb.in/1598300732037-0682672155089", | ||
* // "description": "This is my webhook, I like it a lot", | ||
* // "filter": { | ||
* // "enabled_events": ["*"] | ||
* // }, | ||
* // "status": { | ||
* // "disabled": false, | ||
* // "most_recent_delivery": { | ||
* // "event_uid": "evt_5cmXN7kqdu5YY69HFKegmiGR", | ||
* // "response_status_code": 200, | ||
* // "response_headers": { | ||
* // "content-length": "12", | ||
* // "connection": "close", | ||
* // "content-type": "application/json" | ||
* // }, | ||
* // "request_headers": { | ||
* // "User-Agent": "Serverless-Webhook/0.1", | ||
* // "Content-type": "application/json", | ||
* // "X-Serverless-Delivery": "e1701c44-5d92-4515-8bfb-6c9173a89b60", | ||
* // "X-Serverless-Event": "test.webhook.send2" | ||
* // }, | ||
* // "response_text": "{\"ok\": true}", | ||
* // "error_message": null, | ||
* // "timestamp": 1599595612876 | ||
* // } | ||
* // }, | ||
* // "created": 1599591851267, | ||
* // "updated": 1599595613099 | ||
* // } | ||
*/ | ||
@@ -361,17 +369,32 @@ get: (uid) => webhooks.get(this, uid), | ||
* @returns {Promise<object>} Updated webhook endpoint. | ||
* ```json | ||
* { | ||
* "uid": "whk_2y9fUcnZroc8BhMjC26tQdg8", | ||
* "object": "webhook_endpoint", | ||
* "url": "https://postb.in/1598300732037-0682672155089", | ||
* "description": "This is my webhook, I like it a lot", | ||
* "filter": { | ||
* "enabled_events": ["*"] | ||
* }, | ||
* "status": { | ||
* "disabled": false | ||
* }, | ||
* "created": 1593710260258 | ||
* } | ||
* ``` | ||
* | ||
* @example | ||
* const webhook = await sdk.webhooks.update( 'whe_FPYDtTL37ye13m3sJvtcdyuF', { | ||
* url: 'http://437f01fa092e.ngrok.io', | ||
* filter: { | ||
* enabled_events: [ | ||
* 'user.created', | ||
* 'member.invite.sent' | ||
* ] | ||
* } | ||
* }); | ||
* console.log(JSON.stringify(webhook, null, 2)); | ||
* // outputs: | ||
* // { | ||
* // "uid": "whe_FPYDtTL37ye13m3sJvtcdyuF", | ||
* // "object": "webhook_endpoint", | ||
* // "url": "http://437f01fa092e.ngrok.io", | ||
* // "description": "This is my webhook, I like it a lot", | ||
* // "filter": { | ||
* // "enabled_events": [ | ||
* // "user.created", | ||
* // "member.invite.sent" | ||
* // ] | ||
* // }, | ||
* // "status": { | ||
* // "disabled": false | ||
* // }, | ||
* // "created": 1602078105978, | ||
* // "updated": 1602078663800 | ||
* // } | ||
*/ | ||
@@ -384,8 +407,24 @@ update: (uid, updates) => webhooks.update(this, uid, updates || {}), | ||
* @returns {Promise<object>} An object with the deleted webhook endpoints’s ID if a valid webhook endpoint ID was provided. Otherwise, this call throws an error, such as if the webhook endpoint has already been deleted. | ||
* ```json | ||
* { | ||
* "uid": "whk_2y9fUcnZroc8BhMjC26tQdg8", | ||
* "object": "webhook_endpoint", | ||
* "deleted": true | ||
* } | ||
* | ||
* @example | ||
* const webhook = await sdk.webhooks.delete('whe_FPYDtTL37ye13m3sJvtcdyuF'); | ||
* console.log(JSON.stringify(webhook, null, 2)); | ||
* // outputs: | ||
* // { | ||
* // "uid": "whe_FPYDtTL37ye13m3sJvtcdyuF", | ||
* // "object": "webhook_endpoint", | ||
* // "url": "http://437f01fa092e.ngrok.io", | ||
* // "description": "This is my webhook, I like it a lot", | ||
* // "filter": { | ||
* // "enabled_events": [ | ||
* // "user.created", | ||
* // "member.invite.sent" | ||
* // ] | ||
* // }, | ||
* // "status": { | ||
* // "disabled": false | ||
* // }, | ||
* // "created": 1602078105978, | ||
* // "updated": 1602078663800 | ||
* // } | ||
*/ | ||
@@ -392,0 +431,0 @@ delete: (uid) => webhooks.remove(this, uid), |
@@ -6,3 +6,6 @@ 'use strict'; | ||
const register = (sdk, url, description, filter) => { | ||
const register = (sdk, url, options = {}) => { | ||
if (!options.org_uid && !sdk.context.orgUid && !options.org_name && !sdk.context.orgName) { | ||
throw new Error('Must pass in options or set SDK context for `org_uid`/`org_name`'); | ||
} | ||
return utils.request({ | ||
@@ -13,7 +16,7 @@ endpoint: `${sdk.getDomain('event-webhooks')}/webhooks`, | ||
data: { | ||
org_uid: sdk.context.orgUid, | ||
org_name: sdk.context.orgName, | ||
url, | ||
description, | ||
filter, | ||
org_uid: options.org_uid || sdk.context.orgUid, | ||
org_name: options.org_name || sdk.context.orgName, | ||
description: options.description, | ||
filter: options.filter, | ||
}, | ||
@@ -20,0 +23,0 @@ }); |
Sorry, the diff of this file is too big to display
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
744227
5037
1038