@superfaceai/one-sdk-cloudflare v1.0.0-beta.1
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
Install
To install OneSDK into the project, run:
npm install @superfaceai/one-sdk-cloudflare@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.
- Start with creating a new directory
superface
in the root of your project. - Add the profile. Because profile name contains have scope we need to replace
/
with.
. So, the profile with namecommunication/send-email
have corresponding filenamecommunication.send-email.profile
. - Add the provider. The provider name is the same as the filename. So the provider with name
mailchimp
have corresponding filenamemailchimp.provider.json
. - 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
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,
} 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 });
}
}
}
}
And Wrangler configuration to properly load all files:
name = "example"
main = "index.ts"
compatibility_date = "2023-04-18"
workers_dev = true
rules = [
{ type = "Data", globs = ["**/*.map.js", "**/*.profile", "**/*.provider.json"], fallthrough = true }
]
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
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.
2 months ago
3 months ago
4 months ago
6 months ago
8 months ago
8 months ago