Synqly Client SDK

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

To use this SDK you must have access to a Synqly organization. If you aren't yet a Synqly customer and like to know more, please contact us to schedule a demo.

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.

Installation

Use your favorite package manager to install @synqly/client-sdk:

npm install @synqly/client-sdk

Usage

The Synqly Client SDK consists of two API 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.

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)

Request & Response Types

The SDK exports all request and response types as TypeScript interfaces. Simply import them with the Management or Engine namespaces, for example:

import { Management } from "Management";

const request: Management.ListAccountsRequest = {
    ...
};

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.

Advanced

Additional Headers

If you would like to send additional headers as part of the request, use the headers request option.

const response = await client.accounts.create(..., {
    headers: {
        'X-Custom-Header': 'custom value'
    }
});

Additional Query String Parameters

If you would like to send additional query string parameters as part of the request, use the queryParams request option.

const response = await client.accounts.create(..., {
    queryParams: {
        'customQueryParamKey': 'custom query param value'
    }
});

Retries

The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2).

A request is deemed retryable when any of the following HTTP status codes is returned:

• 408 (Timeout)
• 429 (Too Many Requests)
• 5XX (Internal Server Errors)

Use the maxRetries request option to configure this behavior.

const response = await client.accounts.create(..., {
    maxRetries: 0 // override maxRetries at the request level
});

Timeouts

The SDK defaults to a 60 second timeout. Use the timeoutInSeconds option to configure this behavior.

const response = await client.accounts.create(..., {
    timeoutInSeconds: 30 // override timeout to 30s
});

Aborting Requests

The SDK allows users to abort requests at any point by passing in an abort signal.

const controller = new AbortController();
const response = await client.accounts.create(..., {
    abortSignal: controller.signal
});
controller.abort(); // aborts the request

Access Raw Response Data

The SDK provides access to raw response data, including headers, through the .withRawResponse() method. The .withRawResponse() method returns a promise that results to an object with a data and a rawResponse property.

const { data, rawResponse } = await client.accounts.create(...).withRawResponse();

console.log(data);
console.log(rawResponse.headers['X-My-Header']);

Runtime Compatibility

The SDK works in the following runtimes:

• Node.js 18+
• Vercel
• Cloudflare Workers
• Deno v1.25+
• Bun 1.0+
• React Native

Customizing Fetch Client

The SDK provides a way for you to customize the underlying HTTP client / Fetch function. If you're running in an unsupported environment, this provides a way for you to break glass and ensure the SDK works.

import { ManagementClient } from "Management";

const client = new ManagementClient({
    ...
    fetcher: // provide your implementation here
});

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.