Integrations

The integrations API lets you build plugins integrating third party API services into Qatium. The integrations API allows to fetch HTTP requests through Qatium’s gateway, and manage user secrets for authentication, and other uses.

The integrations.secrets API lets you store and retrieve secret data for users and networks. Storing these secrets let users configure all required credentials for API integrations, such as usernames and passwords, API keys, API URLs, etc.

Secrets are being stored safely in Qatium’s infrastructure, ensuring privacy and confidentiality.

Fetch API

fetch()

Performs a HTTP fetch proxied through Qatium’s API integration gateway. Behaves in the same way as the built in fetch() method. Check the fetch method documentation to know more.

Resolves to no-op when running in developer mode unless your developer account is approved by Qatium to do third party API integrations

Using secrets

The fetch API works in combination with the Secrets API, to provide a secure way of integrating with third party APIs. You can use the stored secrets in the API requests using the format $(secret:SECRET_KEY) being SECRET_KEY the name of the secret stored.

You can find an example of how to combine secrets in API integrations in this example.

Parameters

input: URL as string, URL Object or Request object

init: (Optional) HTTP request options

Returns

Promise resolving with the HTTP response

Example

Perform a request to a third party API:

async init() {
  const reponse = await sdk.integrations.fetch("https://example.com");
  const result = await response.text();
}

Perform a request to a third party API using secrets:

async init() {
  const reponse = await sdk.integrations.fetch("https://example.com");
  const result = await response.text();
}

async onMessage<MessageFromUI>({ username, password }) {
  // Set the username and password
  await sdk.integrations.secrets.set("USERNAME", username);
  await sdk.integrations.secrets.set("PASSWORD", password);

  const response = await sdk.integrations.fetch("https://my-api.com", {
    body: {
      username: "$(secret:USERNAME)",
      password: "$(secret:PASSWORD)",
    }
  })
}

Secrets

secrets.get()

Returns a secret value by name.

Resolves to no-op when running in developer mode unless your developer account is approved by Qatium to do third party API integrations

Method signature

get(key: string): Promise<string>

Parameters

key: Secret name.

Returns

A promise which will resolve after the secret value is retrieved from Qatium’s infrastructure. If the secret does not exist or an error raises, an empty string will be returned ("").

Example

async run() {
  // Retrieve username
  const username = await sdk.integrations.secrets.get("USERNAME");
}

secrets.has()

Returns whether a secret exists by name.

Resolves to no-op when running in developer mode unless your developer account is approved by Qatium to do 3rd party API integrations

Method signature

has(key: string): Promise<boolean>

Parameters

key: Secret name.

Returns

A promise which will resolve after verifying whether the secret exists in Qatium’s infrastructure. If the secret does not exist or an error raises, false will be returned.

Example

async run() {
  // Check if username is set
  const hasUsername = await sdk.integrations.secrets.has("username");
}

secrets.set()

Sets the value for a secret by key.

Resolves to no-op when running in developer mode unless your developer account is approved by Qatium to do third party API integrations

Method signature

set(key: string, value: string): Promise<Success | Failure>

Parameters

key: Secret name.

value: Secret value.

Returns

A promise which will resolve after the secret value has been updated. The returned value informs whether the operation has succeeded or failed.

Example

async onMessage<MessageFromUI>({ username }) {
  // Set the username
  const result = await sdk.integrations.secrets.set("USERNAME", username);

  if (result.status === "success") {
    // all good!
  } else {
    // something went wrong
    console.log("error: ", result.error);
  }
}