Introduction to JavaScript SDK

Overview

Integration with the backend has to be done following a strict internal protocol. All kinds of messages are exchanged in a well-defined binary format. We use a Connection class to abstract all the network-related stuff.

Real-time updates

Real-time updates are the way we update our local user state about any transient or persistent change and how we make our applications react to specific changes. For example, when a call offer is received by a user, you want to allow your user to accept, decline, mute, etc.

See below what kinds of updates our backend support.

Transient

Updates that notify about any transient state (i.e. a call offer was received, the user started typing a message):

/**
 * Traits:
 *
 * - updates.OrganizationUpdate
 * - tpl::InstantUpdate
 */
export interface TransientUpdateOffer {
  readonly _id: -115912433;
  readonly _name: "updates.transientUpdateOffer";
  readonly _type: "updates.TransientUpdate";
  readonly organizationId: number;
  readonly peer: TPeer;
  readonly callParticipant: TCallParticipant;
  /**
   * call identifier
   */
  readonly legacyCallId: number;
  readonly callUuid: string;
  readonly date: number;
  readonly offer: TOffer;
}

Persistent

Updates that notify about a permanent change of an entity. See below an example of a:

/**
 * Update about new user phone
 *
 * Traits:
 *
 * - updates.OrganizationUpdate
 * - updates.PersistUpdate
 */
export interface UserUpdateUserPhone {
  readonly _id: 894028713;
  readonly _name: "updates.userUpdateUserPhone";
  readonly _type: "updates.UserUpdate";
  /**
   * Organization identifier
   */
  readonly organizationId: number;
  /**
   * User identifier
   */
  readonly userId: number;
  /**
   * new user phone
   */
  readonly phone: string;
  /**
   * seq number of UserUpdate
   */
  readonly seq: number;
}

Synchronization

Imagine the following scenario:

1. You are connected and receiving messages, making calls, etc.

2. The user loses connection with the server for 10 hours

What happened during the time this user was offline and unable to receive any update from the backend? A new group might've been created with this user, new messages from his contacts might have accepted a meeting request.

We need to be able to get our local data up-to-date with the current user state. Our backend offers an updates API so we can synchronize with the backend. Please see an example of how to do that below:

import {
  TUserState,
  updateUserState
} from 'digita-schema/updates/UserState';
import {GetUserDifference} from 'digita-schema/updates/GetUserDifference';
import {GetUserState} from 'digita-schema/updates/GetUserState';

let state: TUserState | undefined;
/**
 * Get initial user state
 */
setup = async () => {
  const result = await client.sendMessage(
    GetUserState()
  );
  if(result._name !== 'updates.userState') {
    console.error('Could not update user state due to error: %o', result);
    return;
  }
  state = result;
};
/**
 * Update state as new updates are received
 */
onUpdate = (update: TUserUpdate) => {
  if(state) {
    state = updateUserState({seq: update.seq}, state);
  }
};
/**
 * Will run `GetUserDifference` until we're synchronized
 */
synchronize = async () => {
  if(!state) {
    return;
  }
  const result = await client.sendMessage(GetUserDifference({
    seq: state.seq
  }));
  switch(result._name) {
    /**
     * Current state is up-to-date
     */
    case 'updates.userDifferenceEmpty':
      break;
    case 'updates.userDifference':
    case 'updates.userDifferenceSlice':
      state = result.state;
      /**
       * If updates.userDifferenceSlice is received, it means more updates
       * are available
       */
      if(result._name === 'updates.userDifferenceSlice') {
        await synchronize();
      }
      break;
  }
};

This is only valid for persistent updates.

Bot Integration

Our backend has bultin support for a bots API. You can use our MS Bot Framework adapter to create your own bot. See an example below on how to achieve that:

import {DigitaAdapter} from 'digita-bot';
const bot = new CustomBot();
const adapter = new DigitaAdapter({
    username: 'bot username',
    server: 'dev-api.digita.com',
    port: 9933,
    token: 'bot token',
    organizationId: 1
});
adapter.onUpdate(context => bot.run(context));

Connection

Connection will deal with all the means on how to send or receive messages appropriately. That will all depend on the layer version selected during the class instantiation. See a small example on how to instantiate the Connection class:

import {
  Connection,
  ConnectionLifeKeeper,
  Native,
  Schema,
  NetworkMessage,
  WebSocketDOM
} from 'digita-protocol';
import {InitConnection} from 'digita-schema/InitConnection';
import {sessionTypeRpc} from 'digita-schema/SessionType';
import schemas from 'digita-schema/schemas';

(async () => {
  const native = await Native.init();
  const networkMessage = new NetworkMessage(native.runtime);

  const socket = new WebSocketDOM({
    networkMessage
  });
  const schema = new Schema(schemas);
  const connection = new Connection({
    schema,
    native,
    socket,
    initConnection: InitConnection({
      /**
       * Layer version
       */
      layer: 6400,
      type: sessionTypeRpc()
    }),
    /**
     * This will make sure a ping is sent to backend every minute.
     */
    lifeKeeper: new ConnectionLifeKeeper({
      pingEvery: 60000
    })
  });
})();

After connection is created, you can, for example, authenticate using your phone number:

import type {Connection} from 'digita-protocol';
import {SendCode} from 'digita-schema/auth/SendCode';
import {authCodeDeliveryTypeSMS} from 'digita-schema/auth/AuthCodeDeliveryType';
import {TSentCode} from 'digita-schema/auth/SentCode';
import {AuthorizeAccount} from 'digita-schema/auth/AuthorizeAccount';

/**
 * For the purpose of this example, I won't go any deeper on how to
 * retrieve the following variables as it was either previously explained or
 * it is not the intent of this code.
 */
declare const connection: Connection;
declare const phoneNumber: string;
declare const secretCode: string;
declare const reCaptchaToken: string;

async function authorize(sentCode: TSentCode) {
  const result = await connection.sendMessage(AuthorizeAccount({
    phoneNumber,
    phoneCode: secretCode
  }));
  switch(result._name) {
    case 'auth.authorization':
      // Authorization was successful
      break;
    default:
      // Handle authorization error (i.e. invalid secret code, too many attempts)
  }
}

async run() {
  const result = await connection.sendMessage(SendCode({
    phoneNumber,
    deliveryType: authCodeDeliveryTypeSMS(),
    langCode: '',
    reCaptchaToken
  }));
  switch(result._name) {
    case 'auth.sentCode':
      // Proceed to authorize
      await authorize(result);
      break;
    default:
      console.error('Failed to send code with error: %o', result);
      break;
  }
}

WebAssembly

Following our protocol guidelines, we need to perform encryption every time we send or receive a message. To make sure we're able to keep a certain performance standard, we compile OpenSSL + custom C99 code to WebAssembly so our users can take advantage of the features provided by this technology.

To initialize the protocol WebAssembly JS runtime, you can do so by using the Native class:

import {Native} from 'digita-protocol';

(async () => {
  const runtime = await Native.init();
})();

This class will be used by the internal implementation of the protocol to perform all kinds of low-level stuff using WebAssembly.

Authentication Key

Before you can actually start sending messages, you need to generate an authentication key. During this process, for a short period, there will be unencrypted communication with the backend.

Please see below an example of how to generate an authentication key:

authkey({
  publicKeys,
  native: await Native.init(),
  schema,
  connection
});

Layers

Our backend can provide backward compatibility with older clients. So if you've developed a client targetting version 1.8.0 and it has been updated to a version 2.0.0, your client targetting the old version will continue to be stable.

Worth noticing that you're free to use the newer 2.0.0 version as well when you're ready.