@superfaceai/one-sdk

Website | Get Started | Documentation | GitHub Discussions | Twitter | Support

Superface OneSDK

One SDK for all the APIs you want to integrate with.

OneClient is a universal API client which provides an unparalleled developer experience for every HTTP API. It enhances resiliency to API changes, and comes with built-in integration monitoring and provider failover.

For more details about Superface, visit How it Works and Get Started.

Important Links

• Superface website
• Get Started
• Documentation
• Support

Install

To install OneSDK into the project, run:

npm install @superfaceai/one-sdk@beta

Setup

OneClient uses three files (also called Comlink) which together make the integration:

• Profile - describe business capabilities apart from the implementation details, what is expected as input and what will be the result. Profile name have optional scope before / and required name [scope/]<name>
• Provider - Define a provider's API services and security schemes to use in a Comlink Map
• Map - describe implementation details for fulfilling a business capability from a Comlink Profile

To glue all the parts together, OneClient uses name and file structure convention.

.
└── superface/ - directory with all the Comlinks in project root
    ├── <profileScope>.<profileName>.profile - profile file
    ├── <providerName>.provider.json - provider file
    ├── <profileScope>.<profileName>.<providerName>.map.js - map file
    └── ... - repeat for all the Comlinks

Send email example

As an example, lets send an email with Mailchimp. The use-case is described in the profile communication/send-email and the map with implementation.

1. Start with creating a new directory superface in the root of your project.
2. Add the profile. Because profile name contains have scope we need to replace / with .. So, the profile with name communication/send-email have corresponding filename communication.send-email.profile.
3. Add the provider. The provider name is the same as the filename. So the provider with name mailchimp have corresponding filename mailchimp.provider.json.
4. Add the map. Map connects profile and provider, so the filename is consists of both as well communication.send-email.mailchimp.map.js.

The final structure should look like this:

.
└── superface/
    ├── communication.send-email.mailchimp.map.js
    ├── communication.send-email.profile
    └── mailchimp.provider.json

Use in Node.js

Create index.mjs file with following content and update:

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

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

try {
  const result = await profile.getUseCase('<usecaseName>').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
        },
      },
    }
  );

  console.log('RESULT:', result);
} catch (e) {
  if (e instanceof PerformError) {
    console.log('ERROR RESULT:', e.errorResult);
  } else if (e instanceof ValidationError) {
    console.error('VALIDATION ERROR:', e.message);
  } else if (e instanceof UnexpectedError) {
    console.error('ERROR:', e);
  } else {
    throw e;
  }
}

Then run the script with:

node index.mjs

Note: If you are running Node.js before version 18.17.0 you need to enable WASI by providing flag to Node.js:

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

---

OneSDK uses ECMAScript modules. More on using ECMAScript modules is well described in Pure ESM Package guide.

Use in Cloudflare

The main difference compared to Node.js is a need to use a virtual filesystem to load the Comlink files. It is needed due to the deployment process, where all files need to be bundled together.

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

import profileFile from '../superface/[scope.]<name>.profile';
import mapFile from '../superface/[scope.]<name>.<providerName>.map.js';
import providerFile from '../superface/<providerName>.provider.json';

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url);

    const client = new OneClient({
      env: {
        ONESDK_LOG: 'off' // use `on` for debugging
      },
      // preopens describes the virtual filesystem whith the OneClient file convention mapped to assets
      preopens: {
        'superface/[scope.]<name>.profile': new Uint8Array(profileFile),
        'superface/[scope.]<name>.<providerName>.map.js': new Uint8Array(mapFile),
        'superface/<providerName>.provider.json': new Uint8Array(providerFile)
      }
    });
    const profile = await client.getProfile('<profileName>');  // profile id as defined in *.profile
    const usecase = profile.getUseCase('<usecaseName>'); // use case name as defined in the profile
    const result = usecase.perform(
      // Input parameters as defined in profile:
      '<key>': '<value>'
      // provider configuration
      {
        provider: '<providerName>', // provider name as defined in *.provider.json
        parameters: {
          // Provider specific integration parameters:
          '<integrationParameterName>': '<integrationParameterValue>'
        },
        security: {
          // Provider specific security values:
          '<securityValueId>': {
            // Security values as described in provider or on profile page
          }
        }
      }
    );

    try {
      // result as defined in the profile
      const ok = await result;
      return new Response(`Result: ${JSON.stringify(ok, null, 2)}`);
    } catch (error) {
      if (error instanceof PerformError) {
        // error as defined in the profile
        return new Response(`Error: ${JSON.stringify(error.errorResult, null, 2)}`, { status: 400 });
      } else {
        // exception - should not be part of a normal flow
        return new Response(`${error.name}\n${error.message}`, { status: 500 });
      }
    }
  }
}

Check full demo with Shopify use-cases and more details.

Todos & limitations

The next-gen OneSDK is still in beta stage and several features are not yet implemented. We welcome any and all feedback. The current limitations include:

• OneSDK Client can't be instantiated in the global scope

  • We discovered Cloudflare is not allowing synchronisation between requests. We need to make sure, that two different requests are not accessing OneSDK Core at the same time. The problem.

• Build-time integrations only

  • Currently the maps (integration glue) needs to be bundled with the worker at the build time
  • Future OneSDK will be fetching the maps at the runtime to enable dynamic healing and recovery

Cloudflare Workers specific

• The compiled WASM OneSDK is hitting the 1MB limit of the Cloudflare workers free tier

License

OneSDK is licensed under the MIT License.

© 2023 Superface s.r.o.