integration.webhook
Webhook utilities that give you access to Webhook client SDKs
getSdkByTenant
Get an authenticated Webhook SDK for each Connector in the list, using a given Tenant ID
- Parameters
ctx
The context object provided by the route functionconnectorName
string The name of the Connector from the service to interact withtenantId
string Represents a single user of this Integration,
usually corresponding to a user or account in your own system
Examples
router.post('/api/:connectorName/:tenant', async (ctx) => {
const webhookClient = await integration.webhook.getSdkByTenant(ctx, ctx.params.connectorName, ctx.params.tenant);
// use client methods . . .
});
Returns Promise<any> Authenticated SDK you would use to interact with the
Connector service on behalf of your user.
getSdk
Get an authenticated Webhook SDK for each Connector in the list, using a given Tenant ID
- Parameters
ctx
object The context object provided by the route functionconnectorName
string The name of the Connector from the service to interact withinstallId
string Represents a single installation of this Integration
Examples
router.post('/api/:connectorName/:installId', async (ctx) => {
const webhookClient = await integration.webhook.getSdk(ctx, ctx.params.connectorName, ctx.params.installId);
// use client methods . . .
});
Returns Promise<any> Authenticated SDK you would use to interact with the
Connector service on behalf of your user.
searchInstalls
List all Integration Installs that match a particular set of webhook tags
- Parameters
ctx
object The context object provided by the route functionconnectorName
string The name of the Connector from the service to interact withtags
object A key-pair object representing the tags used to search the Installs
Examples
router.post('/api/:connectorName/:installId', async (ctx) => {
const installs = await integration.webhook.searchInstalls(ctx, ctx.params.connectorName, {
tag1: value,
tag2: value
});
});
- Throws NotFoundError Will throw a NotFoundError with a statusCode of 404
Returns Promise<Array<Integration.Types.IInstall>> An Installs list
send
Send an Incoming Webhook request
- Parameters
ctx
object The context object provided by the route functiondata
object? The Webhook data to sendurl
string The url used for executing the Webhook
Examples
await integration.webhook.send(ctx, { text: 'It works!'});
Returns Promise<any> The response body of the Webhook request
integration.service
getSdk
Get an authenticated SDK for the specified Connector, using a given Install.
- Parameters
ctx
FusebitContext The context object provided by the route functionconnectorName
string The name of the Connector from the service to interact withinstallId
string The identifier of the Install to get the associated Connector
Examples
router.post('/api/:connectorName', async (ctx) => {
const client = await integration.service.getSdk(ctx, ctx.params.connectorName, ctx.req.body.instanceIds[0]);
// use client methods . . .
});
Returns Promise<any> Authenticated SDK you would use to interact with the Connector service
on behalf of your user
getSdks
Get an authenticated SDK for each Connector in the list, using a given Install.
- Parameters
ctx
The context object provided by the route functionconnectorNames
Array<string> An array of Connector namesinstallId
string The identifier of the Install to get the associated Connectors
Examples
router.post('/api/components', async (ctx) => {
const clients = await integration.service.getSdks(ctx, ['mySlackConnector', 'myHubSpotConnector'], ctx.req.body.instanceIds[0]);
for await (const sdk of clients) {
// Access sdk methods here . . .
}
});
Returns Promise<Array<any>> Array of official Connector SDK instances already
authorized with the proper credentials
getInstall
Get a configured Integration with a set of identities and other values that represent
a single user of the Integration.
Read more: https://developer.fusebit.io/docs/fusebit-system-architecture#installation-lifecycle
- Parameters
ctx
The context object provided by the route functioninstallId
string
Examples
router.post('/api/test', async (ctx) => {
const client = await integration.service.getInstall(ctx, ctx.req.body.installIds[0]);
// use client methods . . .
});
listInstalls
List all Integration Installs, or only Installs that match a particular tag with an optional value.
- Parameters
Examples
router.post('/api/test', async (ctx) => {
const installs = await integration.service.listInstalls(ctx, 'serviceTag');
const client = await integration.service.getSdk(ctx, connectorName, installs[0].id);
// use the client . . .
});
scheduleTask
Schedule a new task to be executed based on the task
object.
- Parameters
ctx
The context object provided by the route functiontask
The specification for the task to invoke
Examples
integration.service.scheduleTask(ctx, { path: '/api/update', notBefore: '1657763386' });
integration.tenant
Tenant utilities that give you access to Connector client SDKs.
A Tenant represents a single user of an Integration, usually corresponding to a user or account in your own system.
Read more: https://developer.fusebit.io/docs/integration-programming-model#fusebit-tenancy-model
getSdkByTenant
Get an authenticated SDK for each Connector in the list, using a given Tenant ID
- Parameters
ctx
The context object provided by the route functionconnectorName
string The name of the Connector from the service to interact withtenantId
string Represents a single user of this Integration,
usually corresponding to a user or account in your own system
Examples
router.post('/api/:connectorName/:tenant', async (ctx) => {
const client = await integration.tenant.getSdkByTenant(ctx, ctx.params.connectorName, ctx.params.tenant);
// use client methods . . .
});
Returns Promise<any> Authenticated SDK you would use to interact with the
Connector service on behalf of your user
getTenantInstalls
Get a list of Integration Installs associated with a given Tenant
- Parameters
ctx
The context object provided by the route functiontenantId
string Represents a single user of this Integration,
usually corresponding to a user or account in your own system
Examples
router.post('/api/:tenant', async (ctx) => {
const installs = await integration.service.getTenantInstalls(ctx, ctx.params.tenant);
});
Returns Promise<Array<EntityBase.IInstall>> An array of Installs
integration.storage
Secure and reliable storage utilities. You can write, read, update and delete hierarchical data in a versioned fashion.
setData
Save any data in JSON format up to ~400Kb in size.
- Parameters
ctx
The context object provided by the route functiondataKey
string Represents a reference to your data that you will use in further
operations like read, delete and update
Properties
-
body
Storage.IStorageBucketItemParams Represents the storage data and metadata
Examples
router.post('/api/tenant/:tenantId/colors', async (ctx) => {
const bucketName = '/my-bucket/';
const key = 'colors';
const data = ['green', 'blue'];
const result = await integration.storage.setData(ctx, `${bucketName}${key}`, { data });
ctx.body = result;
});
Storing temporary data that expires at specific date:
router.post('/api/tenant/:tenantId/colors', async (ctx) => {
const bucketName = '/my-bucket/';
const key = 'colors';
const expirationDate = new Date();
expirationDate.setDate(expirationDate.getDate() + 1);
const data = ['green', 'blue'];
const result = await integration.storage.setData(ctx, `${bucketName}${key}`,
{
data,
expires: expirationDate.toISOString()
});
ctx.body = result;
});
Returns Promise<Storage.IStorageBucketResponse>
getData
Get saved data
- Parameters
ctx
The context object provided by the route functiondataKey
string The key name used for referencing the stored data
Returns Promise<(Storage.IStorageBucketResponse | undefined)>
listData
A listing operation query data stored in an artifact known as a Bucket (Buckets are
collections of keys where you can store related data). Read more at
https://developer.fusebit.io/docs/integration-programming-model#listing-data
- Parameters
ctx
The context object provided by the route functiondataKeyPrefix
string The bucket nameoptions
Storage.IListOption The bucket name
Examples
router.get('/api/tenant/:tenantId/my-bucket', async (ctx) => {
const bucketName = '/my-bucket/';
const result = await integration.storage.listData(ctx, bucketName);
ctx.body = result;
});
Returns Promise<Storage.IStorageBucketList> A list of Storage items
deleteData
Delete data
- Parameters
ctx
The context object provided by the route functiondataKey
string Reference the key name used for storing the dataversion
string? Delete a specific version of the stored data
Returns Promise<Storage.IStorageBucketResponseDelete>
deletePrefixedData
Delete data stored in an artifact known as a Bucket
(This function will remove a collection of keys stored under the specified Bucket).
- Parameters
ctx
The context object provided by the route functiondataKeyPrefix
string The bucket nameversion
string? Delete a specific version of the Bucket
Returns Promise<Storage.IStorageBucketResponseDelete>
integration.middleware
Powerful and useful middlewares like user authorization and input validation.
authorize
Usually, the routes you define in an integration require protection against unauthorized access.
This function restricts access to users authenticated in Fusebit with the specified permission.
- Parameters
action
string Name of the action to authorize
Examples
router.post('/api/tenant/:tenantId/test', integration.middleware.authorizeUser('instance:get'), async (ctx) => {
// Implement your code here
});
- Throws Error With 403 code, meaning access to the requested resource is forbidden.
Returns Promise<any>
validate
Middleware that can be used to perform input and parameter validation, using Joi, on handlers.
See the Joi documentation for more details.
Examples
const integration = new Integration();
const Joi = integration.middleware.validate.joi;
integration.router.get('/api/example',
integration.middleware.validate({query: Joi.object({ aKey: Joi.string().required() }) }),
async (ctx) => {
ctx.body = { result: ctx.query.aKey };
}
);
session
Middleware that adds the ability to create new users of an integration without a backend.
integration.response
Response utilities that give you access to useful functionalities like Json Forms creation.
FusebitRouter
The FusebitRouter is exposed as an HttpRouter on an entity.
integration.router
HttpRouter extends the pattern defined by a Koa.Router, and supports all of the usual HTTP verbs.
As such, an integration can create a handler on an arbitrary URL endpoint in a simple fashion.
Use the koa documentation as a reference
Examples
router.get('/hello', async (ctx) => { ctx.body = 'Hello World'; });
CronRouter
A CronRouter extends the normal HTTP-style router to enable capturing specific events generated
through a cron trigger, as specified in the fusebit.json of the entity.
- Parameters
baseRouter
CronRouter.on
Cron events get to be named (the 'path' parameter) in the fusebit.json object
with a particular schedule.
On execution, they get mapped to particular handlers declared via .cron(name, ...)
.
The response is discarded, outside of analytics and event reporting.
- Parameters
name
string the name of the cron schedulemiddleware
any Koa request handler
EventRouter
An EventRouter is used to capture events coming from both internal components as well as external
components, such as WebHook events from a connector.
- Parameters
baseRouter
EventRouter.on
Register for an event.
Each event is invoked with the set of parameters as an object in the first parameter, followed by an
optional next parameter for event chaining support.
- Parameters
TaskRouter
TaskRouter extends the pattern defined by a Koa.Router, and supports the TASK verb.
Use the koa documentation as a reference
- Parameters
baseRouter
Examples
integration.task.on('/api/hello', async (ctx) => { ctx.body = 'Hello World'; });
TaskRouter.on
Register to handle a scheduled task.
A task is equivilent in many respects to a normal HTTP invocation, except that it appears to be
asynchronous from the perspective of the caller and may take more than a minute to complete.
The contents of ctx.body
will be made available to the caller after the invocation completes.
- Parameters
Form
Create an HTML Form, using MaterialUI, from the supplied JSON Schema.
- Parameters
spec
IFormSpecification