SMS Delivery Microservice for Node.js / ES2017 V2

This is a sms sending microservice from Pip.Services library. This microservice is intended mostly to send sms to specified recipients.

The microservice currently supports the following deployment options:

• Deployment platforms: Standalone Process, Seneca
• External APIs: HTTP/REST, Seneca

Quick Links:

• Development Guide
• Configuration Guide
• Deployment Guide
• Client SDKs
  • Node.js SDK
• Communication Protocols
  • HTTP Version 1
  • Seneca Version 1

Contract

Logical contract of the microservice is presented below. For physical implementation (HTTP/REST, Thrift, Seneca, Lambda, etc.), please, refer to documentation of the specific protocol.

class SmsMessageV1 {
  public from: string;
  public to: string;
  public text: string;
}

class SmsRecipientV1 {
  public id: string;
  public name: string;
  public phone: string;
  public language: string;
}

interface ISmsV1 {
  sendMessage(
    context: IContext,
    message: SmsMessageV1,
    parameters: ConfigParams,
    callback?: (err: any) => void
  ): void;
  sendMessageToRecipient(
    context: IContext,
    recipient: SmsRecipientV1,
    message: SmsMessageV1,
    parameters: ConfigParams,
    callback?: (err: any) => void
  );
  sendMessageToRecipients(
    context: IContext,
    recipients: SmsRecipientV1[],
    message: SmsMessageV1,
    parameters: ConfigParams,
    callback?: (err: any) => void
  ): void;
}

Message text can be set by handlebars template, that it processed using parameters set. Here is an example of the template:

Dear {{ name }},
Please, help us to verify your sms address. Your verification code is <%= code %>.
{{ signature }}

Download

Right now the only way to get the microservice is to check it out directly from github repository

git clone [email protected]:entinco/eic-services-infrastructure2.git

Pip.Service team is working to implement packaging and make stable releases available for your as zip downloadable archieves.

Run

Add config.yml file to the root of the microservice folder and set configuration parameters. As the starting point you can use example configuration from config.example.yml file. Example of microservice configuration

---
- descriptor: "service-commons:logger:console:default:1.0"
  level: "trace"

- descriptor: "sms:controller:default:default:1.0"
  message:
    from: "+12453453445"
    to: "+79532347823"
  credential:
    access_id: "xxx"
    access_key: "xxx"

- descriptor: "sms:service:commandable-http:default:1.0"
  connection:
    protocol: "http"
    host: "0.0.0.0"
    port: 8080

For more information on the microservice configuration see Configuration Guide.

Start the microservice using the command:

node run

Use

The easiest way to work with the microservice is to use client SDK. The complete list of available client SDKs for different languages is listed in the Quick Links

If you use Node.js then you should add dependency to the client SDK into package.json file of your project

{
    ...
    "dependencies": {
        ....
        "clients-sms-node": "^1.0.*",
        ...
    }
}

Inside your code get the reference to the client SDK

var sdk = new require("pip-clients-sms-node");

Define client configuration parameters that match configuration of the microservice external API

// Client configuration
var config = {
  connection: {
    protocol: "http",
    host: "localhost",
    port: 8080,
  },
};

Instantiate the client and open connection to the microservice

// Create the client instance
var client = sdk.SmsHttpClientV1(config);

// Connect to the microservice
client.open(null, function(err) {
    if (err) {
        console.error('Connection to the microservice failed');
        console.error(err);
        return;
    }

    // Work with the microservice
    ...
});

Now the client is ready to perform operations

// Send sms message to address
client.sendMessage(
    null,
    {
        to: '+13452345324',
        text: 'This is a test message. Please, ignore it'
    },
    function (err) {
        ...
    }
);

// Send sms message to users
client.sendMessageToRecipients(
    null,
    [
        { id: '123', phone: '+123455534' },
        { id: '321', phone: '+123408289' }
    ],
    'test'
    {
        text: 'This is a test message. Please, ignore it'
    },
    function (err) {
        ...
    }
);

Development Guide

Environment Setup

This is a Node.js project and you have to install Node.js tools. You can download them from official Node.js website: https://nodejs.org/en/download/

After node is installed you can check it by running the following command:

node -version

Then you need to configure node tools:

# Install typescript compiler
npm install typescript -g

# Install mocha test runner
npm install mocha -g

To work with GitHub code repository you need to install Git from: https://git-scm.com/downloads

If you are planning to develop and test using persistent storages other than flat files you may need to install database servers:

• Download and install MongoDB database from https://www.mongodb.org/downloads

Installing

After your environment is ready you can check out microservice source code from the Github repository:

git clone [email protected]:entinco/eic-services-infrastructure2.git

Then go to the project folder and install dependent modules:

# Install dependencies
npm install

If you worked with the microservice before you can check out latest changes and update the dependencies:

# Update source code updates from github
git pull

# Update dependencies
npm update

Building

This microservice is written in TypeScript language which is transcompiled into JavaScript. So, if you make changes to the source code you need to compile it before running or committing to github. The process will output compiled javascript files into /bin folder.

tsc

When you do continuous edit-build-test cycle, you can run typescript compiler with --watch option to detect and compile changes you make automatically:

tsc --watch

Testing

Before you execute tests you need to set configuration options in config.yml file. As a starting point you can use example from config.example.yml:

copy config.example.yml config.yml

After that check all configuration options. Specifically, pay attention to connection options for database and dependent microservices.

Command to run unit tests:

npm test

Configuration Guide

Sms delivery microservice configuration structure follows the standard configuration structure.

Service Configuration

Service has the following configuration properties:

• message: hashmap - Message default properties
  • from: string - sender address
  • cc: string - CC address
  • to: string - default recipient address
  • reply_to: string - Reply-To address
• connection: ConnectionParams - SMTP connection parameters
• credential: CredentialParams - SMTP credentials

Example:

- descriptor: "sms:service:default:default:1.0"
  message:
    from: "[email protected]"
    to: "[email protected]"
  credential:
    access_id: "XXXXXXXXX"
    access_key: "XXXXXXXXX"

Controllers

The controller components (also called endpoints) expose external microservice API for the consumers. Each microservice can expose multiple APIs (HTTP/REST, Thrift or Seneca) and multiple versions of the same API type. At least one service is required for the microservice to run successfully.

HTTP Controller

HTTP/REST controller has the following configuration properties:

• connection: object - HTTP transport configuration options
  • protocol: string - HTTP protocol - 'http' or 'https' (default is 'http')
  • host: string - IP address/hostname binding (default is '0.0.0.0')
  • port: number - HTTP port number

Example:

- descriptor: "sms:controller:commandable-http:default:1.0"
  connection:
    protocol: "http"
    host: "0.0.0.0"
    port: 3000

Seneca Controller

Seneca service has the following configuration properties:

• connection: object - Seneca transport configuration options. See http://senecajs.org/api/ for details.
  • type: string - Seneca transport type
  • host: string - IP address/hostname binding (default is '0.0.0.0')
  • port: number - Seneca port number

Example:

- descriptor: "sms:controller:seneca:default:1.0"
  connection:
    protocol: "http"
    host: "0.0.0.0"
    port: 3000

Deployment Guide

Sms delivery microservice can be used in different deployment scenarios.

Standalone Process

The simplest way to deploy the microservice is to run it as a standalone process. This microservice is implemented in JavaScript and requires installation of Node.js. You can get it from the official site at https://nodejs.org/en/download

Step 1. Download microservices by following instructions

Step 2. Add config.json file to the root of the microservice folder and set configuration parameters. See Configuration Guide for details.

Step 3. Start the microservice using the command:

node run

Seneca Plugin

The SysLog microservice can also be used as a Seneca plugin. To learn more about Seneca microservices framework to go http://senecajs.org

Step 1. Include dependency into package.json file:

{
    ...
    "dependencies": {
        ....
        "service-sms2-node": "^1.0.0",
        ...
    }
}

Then install dependencies using npm

# Install dependencies
npm install

# Update existing dependencies
npm update

Step 2. Load seneca plugin within your code.

Configuration parameters for the plugin are identical to the microservice configuration. See Configuration Guide for details.

var seneca = require("seneca")();

var config = {
  logger: {
    level: "debug",
  },
  controller: {
    message: {
      from: "Somebody <[email protected]>",
    },
    credentials: {
      access_id: "XXXXXXXXXXX",
      access_key: "XXXXXXXXXXX",
    },
  },
};

var plugin = require("service-sms-node").SmsSenecaPlugin;

seneca.use(plugin, config);

API Documentation

HTTP REST Protocol

Sms delivery microservice implements a REST compatible API, that can be accessed on configured port. All input and output data is serialized in JSON format. Errors are returned in standard format.

Data Types

SmsMessageV1 class

Message object with sender and recipient addresses, subject and content

Properties:

• to: string or [string] - one or several addresses of message recipient
• from: string - (optional) sender address
• text: string - (optional) message plain text body

SmsRecipientV1 class

Recipient properties. If some properties are not set, the service tries to restore them from sms settings.

Properties:

• id: string - unique user id
• name: string - (optional) user full name
• phone: string - (optional) primary user sms
• language: string - (optional) user preferred language

Operations

POST /sms/send_message

Sends sms message to specified address or addresses

Arguments:

• message: SmsMessageV1 - message to be sent
• parameters: Object - (optional) template parameters

Response body: error or null for success

POST /sms/send_message_to_recipient

Sends sms message to specified recipient

Request body:

• recipient: SmsRecipientV1 - recipient properties, including id
• message: SmsMessageV1 - message to be sent
• parameters: Object - (optional) template parameters

Response body: error or null for success

POST /sms/send_messsage_to_recipients

Sends sms message to multiple recipients

Request body:

• recipients: SmsRecipientV1[] - array of recipient properties, including id
• message: SmsMessageV1 - message to be sent
• parameters: Object - (optional) template parameters

Response body: error or null for success

Seneca Protocol

Sms delivery microservice implements a Seneca compatible API. Seneca port and protocol can be specified in the microservice configuration.

var seneca = require("seneca")();

seneca.client({
  connection: {
    protocol: "tcp", // Microservice seneca protocol
    host: "localhost", // Microservice localhost
    port: 8805, // Microservice seneca port
  },
});

The microservice responds on the following requests:

seneca.act(
    {
        role: 'sms',
        version: 1,
        cmd: ...cmd name....
        ... Arguments ...
    },
    function (err, result) {
        ...
    }
);

Data Types

Same as in HTTP REST Protocol section.

Operations

cmd: 'send_message'

Sends sms message to specified address or addresses

Arguments:

• message: SmsMessageV1 - message to be sent
• parameters: Object - (optional) template parameters

Returns:

• err: Error - occurred error or null for success

cmd: 'send_message_to_recipient'

Sends sms message to specified recipient

Arguments:

• recipient: SmsRecipientV1 - recipient properties, including id
• message: SmsMessageV1 - message to be sent
• parameters: Object - (optional) template parameters

Returns:

• err: Error - occurred error or null for success

cmd: 'send_messages_to_recipients'

Sends sms message to multiple recipients

Arguments:

• recipients: SmsRecipientV1[] - array of recipient properties, including id
• message: SmsMessageV1 - message to be sent
• parameters: Object - (optional) template parameters

Returns:

• err: Error - occurred error or null for success

Acknowledgements

This microservice was created by Sergey Seroukhov and is currently maintained by Danylo Kuznetsov.