@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

Create index.mjs file with following content and update:

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

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.

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

License

OneSDK is licensed under the MIT License.

© 2023 Superface s.r.o.