@buildable/messages
Version:
A fully managed messaging service that lets you easily exchange event data across any app or resource.
174 lines (117 loc) • 6.24 kB
Markdown
# `/messages`
[](https://buildable.dev) [](https://badge.fury.io/js/@buildable%2Fmessages)  [](https://github.com/buildable/node-sdk) [](https://twitter.com/BuildableHQ)
[Buildable](https://www.buildable.dev/messages) is the easiest way to collect, transform, send and action your backend system events. Buildable simplifies the process of communicating between services or cloud apps, via Messages.
**This library allows you to quickly and easily emit and listen on messages via Node.js.**
## Setup
In order to use emit and listen on messages, you'll need a Buildable account and Secret Key. Follow these steps:
1. Create an account at [messages.buildable.dev](https://messages.buildable.dev/sign-in)
2. Head over to the [Secret Keys](https://messages.buildable.dev/settings/secret-keys) section in the Settings page
3. Click the `+ Create secret key` button
4. Name your Secret Key
5. Click `Create`
*Ensure you store the `test` and `live` keys somewhere safe (like a password manager).*
## Install Package
Install the `/messages` NPM package in your working code space:
```
> npm install /messages
```
## Emitting Messages
A message contains:
1. `event` - The name of the event
2. `payload` - The data of the event
Once a message is emitted, it will be visible immediately in the Messages Stream on your Buildable account.
### NodeJS
```javascript
const { createClient } = require('/messages');
const client = createClient(process.env.BUILDABLE_SECRET_KEY);
client.emit("user.created", {
name: "John Doe"
});
```
### Using cURL
```bash
curl --location --request POST 'https://events.buildable.dev/emit' \
--header 'X-Buildable-Secret: <YOUR SECRET KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
"event": "user.created",
"payload": {
"name": "John Doe"
}
}'
```
## Listening on Messages
### What is a transaction?
A transaction is an action that can be triggered when a message is received. A message can have multiple transactions. Each transaction has:
1. An input value
2. An output value
3. A unique transaction key (`txKey`) per message
There are two cases for transacting on messages:
1. Messages from internal apps using the Buildable SDK
2. Messages from third-party cloud apps using Buildable Connections
### Messages from internal apps using the Buildable SDK
```javascript
const { createClient } = require('/messages');
const client = createClient(process.env.BUILDABLE_SECRET_KEY);
// Transact on `user.created`
client.on("user.created", async ({ event, payload }) => {
console.log("Receieved message with payload: ", payload);
// Any value returned here will be set as the transaction's output
});
```
### Messages from third-party cloud apps using Buildable Connections
All [Connections](https://hub.buildable.dev/fundamentals/emitting-messages#emit-using-connections) act as a source of events, leveraging the power of WebHooks. Once you’ve created a Connection in Buildable and subscribed to at least 1 event, messages will continually enter the Messages Stream. In most cases, once you create a Connection once, you can forget about it!
When listening on messages from cloud apps, simply add two additional options to the listener:
```javascript
const { createClient } = require('/messages');
const client = createClient(process.env.BUILDABLE_SECRET_KEY);
// Listen on `customer.created` from Stripe
client.on("customer.created", async ({ event, payload }) => {
console.log("Receieved message with payload: ", payload);
// Any value returned here will be set as the transaction's output
}, {
platform: "stripe", // Platform name
label: "my-stripe-connection" // Connection name
});
```
### Multiple transactions on a message
In order to trigger multiple transactions on the same message, you must specify a custom transaction key (`txKey`). For example, if two services need to listen on the same message and trigger different custom logic, each service must pass a unique txKey to the listener.
```javascript
const { createClient } = require('/messages');
const client = createClient(process.env.BUILDABLE_SECRET_KEY);
// Transaction #1 on `user.created` from service A
client.on("user.created", async ({ event, payload }) => {
// Set the notification.sent transaction output
return await sendNotification(payload);
}, {
txKey: "notification.sent"
});
// Transaction #2 on `user.created` from service B
client.on("user.created", async ({ event, payload }) => {
// Set the salesforce.customer.created transaction output
return await createCustomerOnSalesForce(payload);
}, {
txKey: "salesforce.customer.created"
});
```
*By default, the `txKey` is set to `sdk.{{EVENT_NAME}}`
### Transacting on older messages
In order to transact on messages that have already been emitted, simply pass in the additional configuration argument `since`. For example, to transact on messages from 10 days ago:
```javascript
client.on("user.created", async ({ event, payload }) => {
// Set the notification.sent transaction output
return await sendNotification(payload);
}, {
txKey: "notification.sent",
since: Date.now() - (10 * 24 * 60 * 60 * 1000) // Since 10 days ago
});
```
## API
Alternatively, you can use the `Messages API`. Learn more about it at [hub.buildable.dev](https://hub.buildable.dev/using-the-api)
## Need More Help?
💻 Website: [https://buildable.dev/messages](https://buildable.dev/messages)
📄 Docs: [https://hub.buildable.dev](https://hub.buildable.dev/)
💬 Discord: [https://discord.com/invite/47AJ42Wzys](https://discord.com/invite/47AJ42Wzys)
🐦 Twitter: [https://twitter.com/BuildableHQ](https://twitter.com/BuildableHQ)
### License
© 2022, Buildable Technologies Inc. - Released under the MIT License