Skip to main content

Cloudflare Workers

In this example, we will outline the implementation differences required to use OneSDK with Cloudflare Workers.

The main difference compared to the Node.js implementation is the need to use a virtual filesystem to load the Comlink files. This is needed due to the deployment process for Cloudflare Workers, where they expect that all files will be bundled together.

Have you created Comlinks?

This guide assumes that you have already installed and run the Superface CLI to generate the Comlinks for the API integration you want to work with. If not, please start here.

Create a new Cloudflare Worker project​

Cloudflare has created a CLI that allows for easy setup of Worker projects. You can run this without the need to install anything via NPX.

npx wrangler dev

Install OneSDK​

We've created a specific library for working with Cloudflare Workers as part of OneSDK, so installing it will give you everything you need out of the box.

npm i @superfaceai/one-sdk@beta

Wrangler will have created a worker file at src/worker.js, you can open this and replace the code with the code from the next steps.

If you created your Comlinks with the Superface CLI in a different folder, please move them to a superface folder at the root of your application where your Worker file lives. The following files are expected by OneSDK.

.
└── 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

Create the Worker​

Unlike a standard Node.js implementation, Cloudflare Workers must explicitly import every file that will be used in order to ensure everything is available at the time the code is run.

As such the imports are different, as outlined here:

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';

Next, we will define the function for the Worker itself. Note the preopens option that is used in the OneClient instatiation.

The full outline and explaination of the different elements of a Cloudflare Worker can be found in their Getting Started guide.

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

    const client = new OneClient({
      env: {
        SF_LOG: 'info' // use `debug` or `trace` for development 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)
      }
    });

From this point the OneSDK code for working with Comlinks is the same as the Node.js implementation

    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
          }
        }
      }
    );

Finally, we've included helpers for wrangling the results into formats that keep Cloudflare happy and you can see these in use below.

    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 });
      }
    }
  }
}

All combined, you can then deploy the Worker via Wrangler.

npx wrangler deploy

If you run into any deployment issues, please consult the Cloudflare Worker Getting Started guide.

Cloudflare Free Tier Limitation

The fully compiled WASM version of OneSDK currently hits the 1MB limit of the Cloudflare Workers free tier. When combined with other code, you may need to upgrade your account in order to work with Superface at this time.

Demo: Shopify, Superface & Cloudflare Workers​

In order to best illustrate how Superface can be used in context, take a look at our Cloudflare Workers, Shopify & Superface demo application on GitHub.