barchart-sms-validator-client v2.1.10

sms-validator-client-js

Javascript client library connect to phone validation server

This library allows a user to validate phone number ownership via SMS messages.

The remote service exposes a REST API and this library is simply a convenience-wrapper.

Unit Testing

Gulp and Jasmine are used. Execute unit tests, as follows:

> npm install
> gulp test

Complete Documentation

You can generate complete JSDoc documentation, as follows:

> npm install
> gulp document

The output will be available here:

./docs/index.html

Quick Start

Example Page

An example browser-based implementation can be found in the git repository at:

./example/browser/example.html

instantiate (browser)

This library will create object's in the global namespace. Create an instance of the SmsValidationManager as follows:

var validationManager = new Barchart.Sms.SmsValidationManager();

instantiate (node.js)

Reference the SmsValidationManager module and create a new instance, as follows:

var ValidationManager = require('sms-validator-client/lib/sms/SmsValidationManager');
var validationManager = new ValidationManager();

lookupPhone

Accepts a string, determines if it's a valid phone number, and returns the E.164 formatted phone number.

JSON-in:

{
	"phone": "123-456-7890"
}

JSON-out:

{
	"e164": "+11234567890",
	"success": true
}

Response Details:

* success: A Boolean value that indicates if the phone number is valid.

createValidation

Starts the validation process. The server will generate a random code and send an SMS message to the phone number provided.

JSON-in:

{
	"phone": "+11234567890,
	"system": "Bob's Dirt Farm"
}

JSON-out:

{
	"phone": "+11234567890",
	"success": true
}

Response Details:

* success: A Boolean value that indicates if the text message was successfully transmitted to the device.

confirmValidation

Once the confirmation code is received, it can be confirmed, as follows:

JSON-in:

{
	"phone": "+11234567890,
	"code": "351892"
}

JSON-out:

{
	"phone": "+11234567890",
	"success": true,
	"result": "VALIDATION_SUCCESS",
	"hmac": "1521e4e48c08dba5d127a1b1a65843119d5577c17a03c5b8c11e2eab25a66377"
}

Response Details:

• success: A Boolean value that indicates if validation code matches the code sent to the device.
• result: One of four possible string-based codes:
  • "VALIDATION_SUCCESS" - The validation code matches the code sent to the device.
  • "VALIDATION_FAILED_UNKNOWN_PHONE" - The system has no record of a validation code. This can happen when no validation code has been sent, or the code has already been confirmed, or too many incorrect attempts to validate the code have occurred.
  • "VALIDATION_FAILED_WRONG_CODE" - The validation code does not match the code sent to the device. Another attempt can be made to validate the code.
  • "VALIDATION_FAILED_TOO_MANY_ATTEMPTS" - The validation code does not match the code sent to the device. No further attempts can be made to validate the code, instead a new code must be generated.
• hmac: The server does not store validated phone numbers. Instead, the server provides a "hashed message authentication code" which can be used, in conjunction with the phone number, to determine is the phone number has been previously validated.

verifyValidation

Using the phone number and HMAC, client systems can verify that the phone number has been previously validated.

JSON-in:

{
	"phone": "+11234567890",
	"hmac": "94b6239ae1d309a46163bb1e2f64213170ef201fb3f99ed1908caee899a34d2b",
}

JSON-out:

{
	"phone": "+11234567890",
	"hmac": "94b6239ae1d309a46163bb1e2f64213170ef201fb3f99ed1908caee899a34d2b",
	"valid": true
}

Response Details:

• valid: A Boolean value that indicates if phone number has been previously validated.