Natural Polyglot Machine

    @superfaceai/one-sdk
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.0 • Public • Published

    Website | Get Started | Documentation | Discord | Twitter | Support

    Superface

    Superface OneSDK

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

    GitHub Workflow Status npm license TypeScript Discord

    OneSDK 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

    Install

    To install OneSDK into a Node.js project, run:

    npm install @superfaceai/one-sdk

    or Yarn:

    yarn add @superfaceai/one-sdk

    Usage

    First time use

    💡 For a quick usage example, check out Get Started.

    Superface is all about use cases. You can start with one of the publically available use cases from the Superface Catalog.

    Once you've got your use case, you need to provide OneSDK with:

    • profile name and version
    • use case name
    • provider name
    • input parameters
    • (if necessary) provider-specific integration parameters
    • (if necessary) provider-specific security values

    These can be found on the profile page (e.g. vcs/user-repos). Security values need to be obtained through the relevant provider (e.g. on their website, in your account settings, by contacting them, etc.).

    const { SuperfaceClient } = require('@superfaceai/one-sdk');
    
    const sdk = new SuperfaceClient();
    
    async function run() {
      const profile = await sdk.getProfile({ id: '<profileName>', version: '<profileVersion>'});
    
      const result = await profile.getUseCase('<usecaseName>').perform({
        // Input parameters in format:
        '<key>': '<value>'
      },
      {
        provider: '<providerName>',
        parameters: {
          // Provider specific integration parameters in format:
          '<integrationParameterName>': '<integrationParameterValue>'
        },
        security: {
          // Provider specific security values in format:
          '<securityValueId>': {
            // Security values as described on profile page
          }
        }
      });
    
      console.log(result.unwrap());
    }
    
    run();

    If you are missing a use case, let us know! You can also always add your own use-case or API provider.

    Advanced usage

    As your project grows in size and complexity, you may find it useful to have a central location for configuring details concerning your API integrations. There are also some features that cannot be used with the simple approach described above, namely:

    For these cases, there's Superface configuration. To find out more, visit Advanced Usage.

    Security

    Superface is not a proxy. The calls are always going directly from your application to API providers. Their contents are never sent anywhere else but to the selected provider's API.

    OneSDK accesses superface/super.json file if instructed to, and accesses cache in node_modules/superface/.cache directory. It also accesses local maps, profiles, and provider configuration as per configuration. Non-local maps, profiles and providers are loaded from the Superface remote registry at runtime, and cached locally. OneSDK also sends diagnostic usage report to Superface as described below.

    More about how OneSDK handles secrets can be found in SECURITY.

    Metrics Reporting

    Superface allows you to monitor your integrations and display the metrics on a dashboard. There are three kinds of metrics reported:

    1. When an OneSDK instance is created
    2. After each perform - reporting success or failure of a given use case
    3. When provider failover is triggered - what provider failed and which one was switched to

    These metrics contain no personal information nor the contents of the API calls and are rate limited as to not impact performance.

    Utilizing this functionality requires you to obtain and set a SUPERFACE_SDK_TOKEN. For more information, see Integrations Monitoring.

    However, even without an SUPERFACE_SDK_TOKEN set, this data is sent anonymized to Superface services for diagnostic purposes. All metrics reporting can be disabled by setting an environment variable:

    SUPERFACE_DISABLE_METRIC_REPORTING=true

    For metrics to be successfuly sent, the application needs to exit properly, i.e. there should be no unhandled Promise rejections or exceptions.

    Support

    If you have any questions, want to report a bug, request a feature or you just want to talk, feel free to open an issue or hop on our Discord server.

    You can find more options for reaching us on the Support page.

    Public API

    Only functions and APIs of entities below are a part of the public API, and can be safely relied upon not to break between semver-compatible releases.

    Using other parts of this package is at your own risk.

    • SuperfaceClient API
    • Profile API
    • UseCase API
    • SuperJsonDocument Object
    • Result API

    Use of public APIs is described in the reference.

    Contributing

    We welcome all kinds of contributions! Please see the Contribution Guide to learn how to participate.

    License

    OneSDK is licensed under the MIT License.

    © 2022 Superface s.r.o.

    Install

    npm i @superfaceai/one-sdk

    DownloadsWeekly Downloads

    695

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    955 kB

    Total Files

    437

    Last publish

    Collaborators

    • zdne
    • freaz
    • superface-bot