Quick Start (OneSDK)

The Superface OneSDK is the interface between your application, and the API provider you want to work with. It uses the Comlinks generated by the Superface CLI to perform the use cases you define.

Here's how you get it up and running in your project.

Install OneSDK

Before you start

Superface OneSDK requires either Node.js version 18.0.0 or newer to be installed, and Python 3.8 or newer if you want to output for your Python project.

In your app directory, install the OneSDK library:

Node.js

npm install @superfaceai/one-sdk@beta

Python

pip install one-sdk

Create your code

This example assumes that the Comlink files generated by the CLI will be a folder named superface, however if you have a different folder structure you can set the assetsPath as an option of the OneClient() set up below:

Node.js

index.mjs

import { OneClient, PerformError, UnexpectedError } from '@superfaceai/one-sdk';

async function main() {
  const client = new OneClient({
    // The token for monitoring your Comlinks at https://superface.ai
    token: process.env.SUPERFACE_ONESDK_TOKEN,
    // Path to Comlinks within your project
    assetsPath: '<path_to_superface_comlinks>'
  });

  // Assign our CLI generated profile so it matches
  // the 'name' in the .profile file.
  // Example: email-communication/email-sending

  const profile = await client.getProfile('<profileName>');
  const useCase = profile.getUseCase('<usecaseName>'); // The <usecaseName> is also found in the .profile file

  try {
    const result = await useCase
      .perform(
        {
          // Input parameters as defined in profile:
          <key>: '<value>',
        },
        {
          provider: '<providerName>',
          parameters: {
            // Provider specific integration parameters:
            '<integrationParameterName>': '<integrationParameterValue>',
          },
          security: {
            // Provider specific security values:
            '<securityValueId>': {
              // Security values as described in provider or on profile page
            },
          },
        }
      );

  // output result on success
    console.log("RESULT:", JSON.stringify(result, null, 2));
  } catch (e) {
  if (e instanceof PerformError) {
    console.log('ERROR RESULT:', e.errorResult);
  } else if (e instanceof UnexpectedError) {
    console.error('ERROR:', e);
  } else {
    throw e;
  }
}

main();

Python

main.py

import sys
import os

from one_sdk import OneClient, PerformError, UnexpectedError

client = OneClient(
  # The token for monitoring your Comlinks at https://superface.ai
  token = os.getenv("SUPERFACE_ONESDK_TOKEN"),
  # Path to Comlinks within your project
  assets_path = "/Users/martyndavies/development/superface/demos/email-demo/superface"
)

profile = client.get_profile("<profileName>")
use_case = profile.get_usecase("<usecaseName>")
try:
    r = use_case.perform(
        {
            # Input parameters as defined in profile:
            '<key>': '<value>'
        },
        provider = '<providerName>',
        # Provider specific integration parameters:
        parameters = {
            '<integrationParameterName>': '<integrationParameterValue>'
        },
        security = {
            # Provider specific security values:
            '<securityValueId>': {
                # Security values as described in provider or on profile page
            }
        }
    )
    print(f"RESULT: {r}")
except PerformError as e:
    print(f"ERROR RESULT: {e.error_result}")
except UnexpectedError as e:
    print(f"ERROR: {e}", file=sys.stderr)
except Exception as e:
    raise e
finally:
    client.send_metrics_to_superface()

Run

It's time to run your app!

Node.js

Because the Superface OneSDK is built with WASM, it requires that you pass the --experimental-wasi-unstable-preview1 flag if using Node.js version 18.17.0 or earlier.

node --experimental-wasi-unstable-preview1 index.mjs

For later versions of Node.js, you can run the script as normal:

node index.mjs

Python

python main.py

Debugging

Set the environment variable ONESDK_LOG to on to see API calls from OneSDK to the API you are connecting to:

Node.js

ONESDK_LOG="on" node --experimental-wasi-unstable-preview1 index.mjs

Python

ONESDK_LOG="on" python main.py

caution

This can print out potentially sensitive information, like API keys and access tokens.