Integration SDK

integration.webhook

Extends EntityBase_1.default.WebhookBase

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 function
  • connectorName string The name of the Connector from the service to interact with
  • tenantId 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 function
  • connectorName string The name of the Connector from the service to interact with
  • installId 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 function
  • connectorName string The name of the Connector from the service to interact with
  • tags 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 function
  • data object? The Webhook data to send
  • url 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

Extends EntityBase.ServiceBase

getSdk

Get an authenticated SDK for the specified Connector, using a given Install.

  • Parameters
  • ctx FusebitContext The context object provided by the route function
  • connectorName string The name of the Connector from the service to interact with
  • installId 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 function
  • connectorNames Array<string> An array of Connector names
  • installId 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 function
  • installId 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
  • ctx The context object provided by the route function
  • tagKey string?
  • tagValue string?

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 function
  • task The specification for the task to invoke

Examples

integration.service.scheduleTask(ctx, { path: '/api/update', notBefore: '1657763386' });

integration.tenant

Extends EntityBase_1.default.TenantBase

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 function
  • connectorName string The name of the Connector from the service to interact with
  • tenantId 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 function
  • tenantId 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 function
  • dataKey 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

    • body.data string Any valid JSON with the data you want to store
    • body.version string? Version coming from the original getData in order
      to prevent conflicts when multiple writers may attempt to write at the same time
    • body.expires string? Set an expiration date (ISO 8601 format) for your data

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 function
  • dataKey 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 function
  • dataKeyPrefix string The bucket name
  • options 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 function
  • dataKey string Reference the key name used for storing the data
  • version 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 function
  • dataKeyPrefix string The bucket name
  • version 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.

Note: The validate function includes a joi member to allow callers to easily specify validation rules.

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

Extends KoaRouter

The FusebitRouter is exposed as an HttpRouter on an entity.

integration.router

Extends FusebitRouter

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.

Note: This object follows the pattern established originally in Express and extended by Koa.

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 schedule
  • middleware 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.

Note: This object follows the pattern established originally in Express and extended by Koa.

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