What’s new at Superface: November 2021
Tags: node, javascript, news, startup
Published: 2021-12-10 15:58:18

November has been a busy month at Superface. We've opened up registration and released lots of great new features. Cozy up and grab an eggnog as we share what we've been up to.

## Registration is now open for all

[Register for a Superface account](https://superface.ai/create-account?utm_source=dev.to&utm_medium=blog&utm_campaign=changelog-november-2021) and get access to the [use-cases catalog](https://superface.ai/catalog?utm_source=dev.to&utm_medium=blog&utm_campaign=changelog-november-2021) and [integrations monitoring](https://superface.ai/docs/integrations-monitoring) dashboard. We have also prepared a sweet promo video for the occasion.

{% twitter 1465317611533651975 %}

## OneSDK and CLI hit version 1.0

With the public launch, we have also released 1.0 versions of [OneSDK](https://github.com/superfaceai/one-sdk-js), [Superface CLI](https://github.com/superfaceai/cli), and supporting libraries. We're committed to backwards compatibility, so you can expect our APIs to remain stable.

We will publish release candidates for general testing under the `next` dist-tag.

## New in catalog: Computer Vision, Natural Language Processing and others

You can find new use-cases and providers in our ever-growing [catalog](https://superface.ai/catalog?utm_source=dev.to&utm_medium=blog&utm_campaign=changelog-november-2021):

- [communication/send-message](https://superface.ai/communication/send-message) for sending text messages over Slack
- [computer-vision/face-detection](https://superface.ai/computer-vision/face-detection) detects faces and emotions in images using Google Cloud Vision API
- [crm/contacts](https://superface.ai/crm/contacts) for managing customers and users in various systems; Crisp, Hubspot, Mixpanel, and Sendgrid are available
- [crypto/exchange-rate](https://superface.ai/crypto/exchange-rate) fetches exchange rate of cryptocurrencies using Binance
- [language/analyze-plain-text-sentiment](https://superface.ai/language/analyze-plain-text-sentiment) analyzes emotions and prevailing sentiment in text with IBM Watson Natural Language Understanding and Google Cloud Natural Language APIs
- [language/translate](https://superface.ai/language/translate) translates text using DeepL Translator
- [speech/synthesis](https://superface.ai/speech/synthesis) turns text into natural-sounding speech with Google Cloud Text-to-Speech and IBM Watson Text to Speech
- [speech/recognize](https://superface.ai/speech/recognize) turns speech into text with AssemblyAI, and Speech to Text services by Google Cloud, IBM Watson, and Microsoft Azure

All use-cases from the catalog are maintained in the [Station repository](https://github.com/superfaceai/station). If you are curious what we are working on, check out our open pull requests. And of course, you are more than welcome to contribute new providers and use-cases.

## Integration parameters and examples in Comlink

[Comlink](https://superface.ai/docs/comlink) is a domain-specific language (DSL) which powers Superface integrations. Recently, we have improved support for integration parameters and introduced examples into profiles.

### Provider integration parameters

Some providers require additional information for working with their APIs. For example, calls to Twilio include “Account String Identifier” (SID) and IBM Cloud lets you pick a preferred region for their services. Unlike security values (API keys and access tokens) these information usually aren’t sensitive and in some cases can have a default value.

We call these values “integration parameters”. They are specified inside the [provider definition](https://superface.ai/docs/comlink/reference/provider) file:

```json
{
  "name": "ibm-cloud-natural-language-understanding",
  // ...
  "parameters": [
    {
      "name": "REGION",
      "description": "Your natural language understanding instance region (eu-de, us-east, ...)"
    },
    {
      "name": "INSTANCE_ID",
      "description": "Your natural language understanding instance id"
    }
  ]
}
```

With these parameters defined, maps can access them through `parameters` object:

```hcl
map AnalyzePlainTextSentiment {
  http POST "/instances/{parameters.INSTANCE_ID}/v1/analyze?version=2021-08-01" {
    // ...
  }
}
```

We have improved the discovery of these parameters in our catalog and CLI. Now you can preview all the required parameters in the provider details.

<figure>

<figcaption>

See it in action on <a href="https://superface.ai/language/analyze-plain-text-sentiment">Analyze plain text sentiment</a> IBM provider detail.

</figcaption>

![Preview of integration parameters on IBM Cloud provider](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/e8askp1nquc8s5p72svn.png)

</figure>

And the Superface CLI will inform you when configuring the provider:

```shell
$ npx @superfaceai/cli  configure ibm-cloud-natural-language-understanding -p language/analyze-plain-text-sentiment
Installing provider to 'super.json' on path 'superface/super.json'
Installing provider: "ibm-cloud-natural-language-understanding"
🆗 All security schemes have been configured successfully.
Provider ibm-cloud-natural-language-understanding has integration parameters that must be configured. You can configure them in super.json on path: superface/super.json or set the environment variables as defined below.
🆗 Parameter REGION with description "Your natural language understanding instance region (eu-de, us-east, ...)" has been configured to use value of environment value "$IBM_CLOUD_NATURAL_LANGUAGE_UNDERSTANDING_REGION".
Please, configure this environment value.
🆗 Parameter INSTANCE_ID with description "Your natural language understanding instance id" has been configured to use value of environment value "$IBM_CLOUD_NATURAL_LANGUAGE_UNDERSTANDING_INSTANCE_ID".
Please, configure this environment value.
```

By default OneSDK will look for the parameters in environment variables, but you can also define them directly in the `super.json` configuration file.

### Profile examples

[Comlink profile](https://superface.ai/docs/comlink/reference/profile) defines an interface, or “contract”, between your application and the provider-specific API. Profile specifies inputs, outputs, and error models. It is now possible to document example inputs with expected outputs or errors:

```hcl
usecase ReverseGeocode {
  // ...
  example Successful {
    input {
      latitude = 37.423199,
      longitude = -122.084068
    }

    result [{
      addressCountry = 'us',
      addressLocality = 'Mountain View',
      addressRegion = 'CA',
      formattedAddress = 'Amphitheatre Parkway, Mountain View, CA 94043, United States of America',
      postalCode = '94043',
      streetAddress = 'Amphitheatre Parkway',
    }]
  }

  example Failed {
    input {
      latitude = 720,
      longitude = 540
    }

    error {
      title = 'Bad request',
      detail = 'The provided coordinates in query are invalid, out of range, or not in the expected format'
    }
  }
}
```

<figure>

<figcaption>

Examples are also rendered in the use-case’s detail, you can see it in action on <a href="https://superface.ai/address/geocoding">Geocoding</a> use-cases.

</figcaption>

![Preview of input examples for ReverseGeocode use-case](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/0j0n9ptvl8alkysbz24s.png)

</figure>

## First Superface webinar

We have organized the first Superface webinar to show how easy it is to integrate multiple APIs and take advantage of provider fail-overs and other features. You can watch the recording on YouTube.

{% youtube Sl9rdbw0CtM %}

## More to come

November was an important milestone for us, but we are just getting started. Expect more exciting news in 2022. Don’t forget to [join our Discord](https://sfc.is/discord) and follow us on [Twitter](https://twitter.com/superfaceai) and [LinkedIn](https://www.linkedin.com/company/superfaceai).

From Superface, we wish you happy Holidays and a wonderful 2022!