@synqly/client-sdk

Synqly Client SDK

The Synqly Client SDK provides access to the Synqly API from JavaScript/TypeScript environments, such as Node or a web browser.

Documentation

API reference documentation is available at https://docs.synqly.com.

Installation

[!IMPORTANT] While Synqly is in private beta, the [Synqly Client SDK] and [Synqly Connect React SDK] can only be installed from a private npm packages. To install, make sure you've first logged in to npm:

npm login

Please contact us if you need access or support.

Usage

The Synqly Client SDK consists of two clients:

• Management: used to manage your Synqly organization
• Engine: used to interact with configured integrations using Synqly connectors

Both clients are instantiated similarly, but require different kinds of access tokens to work.

The Management client requires an organization token. The organization token can be reset from the [Synqly Management Console] (https://app.synqly.com/settings/secrets).

The Engine client requires integration tokens, which are issued when first creating an integration. They can also be reset using an organization token.

More information about authentication is available in the Synqly API documentation.

To instantiate the clients, you must provide a valid token:

import { EngineClient, ManagementClient }
from '@synqly/client-sdk'

// The management client is used to manage your Synqly organization
const management = new ManagementClient({ token: 'ORGANIZATION_TOKEN', })

// The engine client is used to interact with a single integration. To
// interact with multiple integrations you must create a new client for
// each.
const engine = new EngineClient({ token: 'INTEGRATION_TOKEN' })

[!TIP] Instantiating a new client is cheap and has no side-effects. It is often more convenient to create a new client than keep instances around.

Using the Management Client

The Management client is used to manage details about your organization, such as inviting members or creating integrations.

[!NOTE] Creating integrations using this client however requires having full details of your tenant's provider details. To make this easier to maintain, and to reduce the complexities of gathering and maintaining all of this data, Synqly offers Connect UI – a hosted experience that can be embedded right into your app.

Everything you can do with the [Synqly Management Console] (https://app.synqly.com) can be done with the Management client.

Using the Engine Client

The Engine client is used to interact with individual integrations. You must create a new client for each integration you wish to use, as the required token parameter is used to authenticate requests for a single integration.

Each integration is of a specific Connector type, and the Engine client namespaces all Connector APIs making it trivial to deconstruct the relevant connect API for your integration.

Here's an example of how you may use a SIEM integration:

const { siem } = new Engine({ token: 'INTEGRATION_TOKEN' })

siem.postEvents(event)

Responses & Errors

Both the Management and Engine clients return a result object regardless of whether it was successful or not. If it's successful, the body of the response will be available in the body field. If not, the error will be available in the error field.

The body and error fields are mutually exclusive, you will never receive both a body and an error at the same time. This allows you to deal with the result without having to wrap any calls in try/catch blocks.

Here's an example of creating an account:

const { body, error } = await management.accounts.create({ fullname })

if (error) {
  // Handle the error however you please, here we just throw it.
  throw errror
}

// The `body` field is guaranteed to exist at this point, since `body` and
// `error` are mutually exclusive fields on the response object.
const { account } = body.result

API Reference.

API Documentation

Both the Management and Engine clients are generated from our OpenAPI specification. All operations in the reference documentation are available in this SDK.

Contributing

We greatly appreciate open-source contributions, however the majority of this library is generated programmatically. Changes made to this repository are likely to be overwritten by the next release. We do welcome PRs and issues however, even if they may not be merged directly.