Sms Delivery Microservices Client SDK for Node.js

Node.js client API for Sms delivery microservice is a thin layer on the top of communication protocols. It hides details related to specific protocol implementation and provides high-level API to access the microservice for simple and productive development.

Table of Contents

• Installation
• Getting Started
• Development Guide
• API Reference
  • Data Types
  • Client Interfaces
  • Client Implementations
• Contributing

Installation

To work with the client SDK add dependency into package.json file:

{
    "dependencies": {
        "client-sms2-node": "^1.0.*"
    }
}

Then download the dependency using npm:

# Installing dependencies
npm install

# Updating dependencies
npm update

Getting Started

This is a simple example on how to work with the microservice using REST client:

// Get Client SDK for Version 1
var sdk = new require('client-sms2-node');

// Client configuration
var config = {
    parameters: {
        server_url: 'http://localhost:3000',
        client_url: 'http://localhost:8000',
        client_name: 'PipControllers Sample',
        welcome_message: 'Congratulations with your signup in {{ clientName }}!',
        signature: 'Sincerely, {{ clientName }} Team'
    }
    connection: {
        protocol: 'http',
        host: 'localhost',
        port: 8005
    }
};

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

// Open client connection to the microservice
await client.open(null);

console.log('Opened connection');

// Send sms message to address
try {
    await client.sendMessage(
        null,
        {
            to: '+1234546345',
            text: 'This is a test message. Please, ignore it'
        },
        null
    );
    console.log('Sms message was successfully sent');
} catch (err) {
    console.error(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

Building

This client SDK 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

Unless you have to do something special, you don't need to worry about configuring and running the microservice. The tests are designed to do that task automatically.

Command to run unit tests:

npm test

You can also execute benchmarks as:

npm run benchmark

API Reference

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

Client Interfaces

ISmsClientV1 interface

If you are using Typescript, you can use ISmsClientV1 as a common interface across all client implementations. If you are using plain Javascript, you shall not worry about ISmsClient interface. You can just expect that all methods defined in this interface are implemented by all client classes.

interface ISmsClientV1 {
    sendMessage(context: IContext, message, parameters);
    sendMessageToRecipient(context: IContext, recipient, message, parameters);
    sendMessageToRecipients(context: IContext, recipients, message, parameters);
}

Client Implementations

SmsHttpClientV1 class

SmsHttpClientV1 is a client that implements HTTP protocol

class SmsHttpClientV1 extends CommandableHttpClient implements ISmsClientV1 {
    constructor(config?: any);
    setReferences(refs);
    open(context: IContext);
    close(context: IContext);
    sendMessage(context: IContext, message, parameters);
    sendMessageToRecipient(context: IContext, recipient, message, parameters);
    sendMessageToRecipients(context: IContext, recipients, message, parameters);
}

Constructor config properties:

• parameters: Object - (optional) default parameters to augment content passed in each request
• 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

SmsSenecaClientV1 class

SmsSenecaClientV1 is a client that implements Seneca protocol

class SmsSenecaClientV1 extends CommandableSenecaClient implements ISmsClientV1 {
    constructor(config?: any);
    setReferences(refs);
    open(context: IContext);
    close(ccontext: IContext);
    sendMessage(context: IContext, message, parameters);
    sendMessageToRecipient(context: IContext, recipient, message, parameters);
    sendMessageToRecipients(context: IContext, recipients, message, parameters);
}

SmsDirectClientV1 class

SmsDirectClientV1 is a client that calls controller from the same container. It is intended to be used in monolythic deployments.

class SmsDirectClientV1 extends DirectClient implements ISmsClientV1 {
    constructor();
    setReferences(refs);
    open(context: IContext);
    close(context: IContext);
    sendMessage(context: IContext, message, parameters);
    sendMessageToRecipient(context: IContext, recipient, subscription, message, parameters);
    sendMessageToRecipients(context: IContext, recipients, subscription, message, parameters);
}

SmsNullClientV1 class

SmsNullClientV1 is a dummy client that mimics the real client but doesn't call a microservice. It can be useful in testing scenarios to cut dependencies on external microservices.

class SmsNullClientV1 implements ISmsClientV1 {
    constructor();
    sendMessage(context: IContext, message, parameters);
    sendMessageToRecipient(context: IContext, recipient, message, parameters);
    sendMessageToRecipients(context: IContext, recipients, message, parameters);
}

Contributing

Developers interested in contributing should read the following instructions:

• How to Contribute
• Guidelines
• Styleguide
• ChangeLog

Please do not ask general questions in an issue. Issues are only to report bugs, request enhancements, or request new features. For general questions and discussions, use the Contributors Forum.

Acknowledgements

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