@superfaceai/one-sdk NPM

Superface One SDK (one-sdk-js)

GitHub Workflow Status NPM

Superface is the core SDK of the Superface project. It is the library that communicates with registry and performs operations on profiles/maps, including input/output validations.

Background

Superface (super-interface) is a higher-order API, an abstraction on top of the modern APIs like GraphQL and REST. Superface is one interface to discover, connect, and query any capabilities available via conventional APIs.

Through its focus on application-level semantics, Superface decouples the clients from servers, enabling fully autonomous evolution. As such it minimizes the code base as well as errors and downtimes while providing unmatched resiliency and redundancy.

Superface allows for switching capability providers without development at a runtime in milliseconds. Furthermore, Superface decentralizes the composition and aggregation, and thus creates an Autonomous Integration Mesh.

Motivation behind Superface is nicely described in this video from APIdays conference.

You can get more information at https://superface.ai and https://superface.ai/docs.

Install

To install the package, run in the project directory:

# npm users
npm install @superfaceai/one-sdk
# yarn users
yarn add @superfaceai/one-sdk

Usage

Using the OneSDK

To interact with Superface, initialize a new Superface OneSDK instance, references the profile and use case you're wanting to use, then perform it to get the result. You can use either the typed or untyped interface for the SuperfaceClient.

Initializing the OneSDK client

import { SuperfaceClient } from '@superface/one-sdk';

const client = new SuperfaceClient();

Performing the use case

Note: You can change url of API requests by setting SUPERFACE_API_URL environment variable to desired base url.

Make sure a profile is installed by running superface install <profileName>[@<profileVersion>] in the project directory, then load the profile:

const profile = await client.getProfile('<profileName>');

Next, make sure at least one provider is configured in super.json or select one manually. You can configure providers in super.json by running superface configure <providerName> and you can add additional or overriding configuration by calling .configure on the Provider object:

const provider = await client.getProvider('<providerName>');
// provider.configure(...)

Then, obtain a use case and perform it with selected provider:

const result = await profile.getUsecase('<usecaseName>').perform(
  {
    inputField: 1,
    anotherInputField: 'hello',
  },
  // optional, if provider is missing selects first configured provider from super.json
  { provider }
);

Using the Typed OneSDK

You can also use generated typed client, which is very similar:

Make sure a profile is installed with types by running superface install --types <profileName>[@<profileVersion>] in the project directory.

 // This should point to superface directory in project root
 // instead of @superfaceai/one-sdk
import { SuperfaceClient } from 'superface/sdk';

const client = new SuperfaceClient();
// This client should now autocomplete your installed profileVersion
const profile = await client.getProfile('myProfile'); 
const result = await profile.useCases.myUseCase.perform(
  {
    inputField: 1,
    anotherInputField: 'hello',
  },
  // optional, if provider is missing selects first configured provider from super.json
  { provider }
);

Handling the results from `perform`

The perform method will take your inputs and additional information and perform the use case asynchronously. This method always returns a Result type that is either Ok or Err. This follows the neverthrow approach. The SDK provides multiple ways to work with result.

Conditionals

You can use conditionals to check if the result was OK or if it errored. Use isOk() or isErr()to check type of result.

if (result.isErr()) {
  // Result is error, error.toString() returns human readable description of what went wrong
  console.log(result.error.toString());
} else {
  // Result is ok and you can accees value here
  console.log(result.value);
}

Matching a value or error

The Result type also provides a match method to use functions to use the values or errors. The match method takes two functions, the first of which is for handling the Ok result and the the second for handling the Err result. The example above using isOk and isErr can be written using match like below.

result.match(
  value => console.log(value),
  error => console.log(error.toString())
);

Unsafely unwrapping the result

Lastly, you can just use unwrap, which is less safe because it will throw an error.

try {
  // Possible error is thrown here and it contains human readable description of what went wrong :)
  const value = result.unwrap();
  // You can accees value here
  console.log(value);
} catch (e) {
  console.log(e);
}

Configuration

The Superface OneSDK is configurable through various environment variables:

SUPERFACE_SDK_TOKEN - your auth token to integrate your running instance with Superface services
SUPERFACE_API_URL - URL of the Superface services, you probably don't need to change this; default is https://superface.ai
SUPERFACE_PATH - path to your super.json file; default is ./superface/super.json
SUPERFACE_METRIC_DEBOUNCE_TIME_MIN and SUPERFACE_METRIC_DEBOUNCE_TIME_MAX - to rate limit metric reporting, OneSDK will send aggregated metrics after at least MIN milliseconds and at most MAX milliseconds; default is 1000 for min and 60000 for max
SUPERFACE_DISABLE_METRIC_REPORTING - set this variable to disable metric reporting; enabled by default

Metric reporting

The Superface OneSDK will send info about usage to Superface services. This info is anonymized, rate limited and allows you to see how the client is performing on your dashboard. To be able to see those metrics, you need to provide your auth token. There are three kinds of metrics reported at present - one is sent when the client instance is created, one after each perform (reporting success or failure) and one when a provider failover happens. The reports can be disabled or configured with environment variables. For metrics to be successfuly sent, the application needs to be properly exited, i.e. there should be no unhandled Promise rejections or exceptions.

Security

Superface is not man-in-the-middle so it does not require any access to secrets that are needed to communicate with provider API. Superface SDK only reads super.json file, resolved authorization secrets from environment variables or from the file itself and applies them to network requests as required by the specific map.

More about the journey of the secrets within SDK can be found in Security.