RingCentral TypeScript SDK is now available

TypeScript(TS) is becoming increasingly popular for JavaScript development and I wanted to build a brand new RingCentral SDK in native TS to enable JS developers and maintainers to leverage all the advantages of TS. This SDK contains features of both the official JS SDK and JS Client, but with slightly different APIs. Let’s see how TS help me build the SDK.

Advanced IDE IntelliSense

For any imported library that is written in TS or has typings, VS Code will use IntelliSense that greatly improve my efficiency. And luckily, typings are available for all of the JS builtin APIs(including the latest ES6/ES7 APIs), browser APIs, node APIs and most of the popular libraries on npm(even some less popular ones).

While typing, VS Code gives me suggestions and autocompletion. Live docs are also available while calling functions, so that I don’t have to guess the types of the function parameters or search for the documents and switch between my code editor and the documentation back and forth any more.

Suggestions in VS Code
Live docs for function arguments

It’s easy to navigate around, with just a click of the code hyper link, I can go to the definition of a function/method or type, and find all the references, no need to search the whole project by text any more.

Click the code hyper link to go to the definition
Find all the references of the method

Have you ever tried to refractor your JS code, but with the fear to break your project? TS is the rescue, so that I can refactor my code more safely and with more confidence. It’s easy to rename a symbol and all the references will be modified accordingly, no need to worry about the missing reference any more. When a declaration is deleted or changed, all the references will be marked as error.

Rename a symbol
References to deleted declaration will be marked as error

The IDE IntelliSense also helps users get started with SDK quickly even without reading the docs.

Autocompletion for SDK constructor parameters in VS Code
Suggestions to build the endpoint urls in VS Code
Suggestions of the endpoint operation in VS Code

Error checking

The TS compiler tsc is a highly advanced linter for me, it knows the type, so it will report all errors for calling not existing methods, reading not existing properties and passing the wrong type of arguments. The compilation process is configured in the Travis CI, so most errors will be unveiled at compile time, not run time, which improves robustness.

Explicit interface

JavaScript has no concept of interface in the language, so you can only define interface in the comment or document in your own way which does not have any constraint for your code. While TS has interface support, which helps you clearly define interface without ambiguity, and it will help you check if implementation exactly satisfies the interface. For example, TokenStore defines all the method signatures with TS syntax, so users know how to implement their own TokenStore, and tsc will also check the implementation.

Code easier to read and understand

With type information, I can easily examine the structure of every object and signatures of functions.

Latest ES features are available

One of TS’s goals is Align with current and future ECMAScript proposals, so all the features of ES6/ES7 are available in the project.

Getting Started

Let’s get started with the SDK. First, install the module by yarn or npm:

yarn add ringcentral-ts

Or

npm install ringcentral-ts --save

Now you can log into RingCentral and make API calls with just these lines of code:

Rate limit handling

When you run into rate limit, the SDK will throttle any subsequent API calls until the service is available again. By default, throttled API calls will be postponed and resend immediately when the service recovers. To disable auto-resending, you can set the handleRateLimit option of the constructor to false:

let rc = new RingCentral({
handleRateLimit: false, // Any throttled API calls will throw Rate limit exceeded exception immediately

});
```

TokenStore

Every RingCentral SDK instance has a TokenStore. The default one is MemoryTokenStore, so the Token will be lost when the process exits in node or the web page reloads. There are two other prefined TokenStores to help you store token in localStorage or file:

Except for the predefined TokenStore, you can also implement your own TokenStore to cache the token in other places.

Subscription

You can subscribe for server events(e.g. phone call starts or ends, SMS comes) by creating Subscription. The list of server events can be found here.

Creating subscription and register the message event listener:

let subscription = rc.createSubscription();
subscription.onMessage(msg => {
let presenceEvt = msg.body;
console.log(‘>> telephonyStatus’, presenceEvt.telephonyStatus);
console.log(‘>> activeCalls’, presenceEvt.activeCalls);
console.log(‘@@ presence event’, presenceEvt);
});

Then you should subscribe the events from the server. There 3 ways to subscribe.

#1 Subscribe by event filters, this is the most common one:

#2 If you have an existing subscription, you can subscribe by the id of that subscription:

subscription.id = ‘{theExistingSubscriptionId}’;
subsription.subscribe();

#3 If you have the subscription data returned from RingCentral REST API, you can subscribe by this data:

subsription.setData(subscriptionData);

Once subscribed successfully, the subscription will keep receiving events from the server, unless you explicitly cancel it:

subsription.cancel();

Making API Calls with Url Builder

Url Builders are methods that help you build API endpoint urls. Every segment of the endpoint url has a corresponding method, and the path parameter is the parameter that method. Let’s see some examples of making API calls by UrlBuilder.

Telephony Calls

  1. Make phone calls by ringout:

2. Track the telephony status

To get notifications when calls come in, go out or ends, subscribe to the Presence Event:

3. View the list of active calls

4. View the recent calls

Send SMS

Send Fax

For all supported options and mediatype, please refer to the docs. The API is the same for both node.js and browser.

Extension management

Get detail information of an extension:

List extensions of an account:

Update information of an extension:

This SDK is used by some RingCentral internal projects and still in its early stage, so any feature request or bug report is welcome, just submit them on GitHub.