[
{
"path": ".eslintrc.json",
"content": "{\n \"env\": {\n \"es6\": true,\n \"node\": true,\n \"mocha\": true\n },\n \"extends\": \"eslint:recommended\",\n \"rules\": {\n \"indent\": [\n \"error\",\n 4\n ],\n \"quotes\": [\n \"error\",\n \"single\"\n ],\n \"semi\": [\n \"error\",\n \"always\"\n ],\n \"no-consolse\": 0\n }\n}"
},
{
"path": ".gitignore",
"content": "# Logs\nlogs\n*.log\nnpm-debug.log*\n\n# Runtime data\npids\n*.pid\n*.seed\n\n# Directory for instrumented libs generated by jscoverage/JSCover\nlib-cov\n\n# Coverage directory used by tools like istanbul\ncoverage\n\n# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)\n.grunt\n\n# node-waf configuration\n.lock-wscript\n\n# Compiled binary addons (http://nodejs.org/api/addons.html)\nbuild/Release\n\n# Dependency directory\nnode_modules\n\n# Optional npm cache directory\n.npm\n\n# Optional REPL history\n.node_repl_history\n\n.vscode\ncoverage\nyarn.lock\n"
},
{
"path": ".travis.yml",
"content": "language: node_js\nnode_js:\n - \"10\"\n - \"9\"\n - \"8\"\n - \"6\"\n - \"node\"\nscript: \"npm run coveralls\""
},
{
"path": "LICENSE",
"content": "The MIT License (MIT)\n\nCopyright (c) 2016 Clément Habinshuti\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n"
},
{
"path": "README.md",
"content": "# ussd-menu-builder\n\n[](https://travis-ci.org/habbes/ussd-menu-builder)\n[](https://coveralls.io/github/habbes/ussd-menu-builder?branch=master)\n\n\nEasily compose USSD menus in Node.js, compatible with\n[Africastalking API](https://africastalking.com) or [Hubtel API](https://developers.hubtel.com/reference#ussd).\n\n## Installation\n\n```\n$ npm install ussd-menu-builder\n```\nor\n```\n$ yarn add ussd-menu-builder\n```\n\n## Features\n- Use intuitive states to compose USSD menus\n- Makes it easier to build complex nested menus\n- Use simple input matching or regular expressions, custom asynchronous\nfunctions to resolve routes from one state to another\n- The state-based approach allows you to easily modularize complex menus\nin different files\n\n## Quick Example\n\n```javascript\nconst UssdMenu = require('ussd-menu-builder');\nlet menu = new UssdMenu();\n\n// Define menu states\nmenu.startState({\n run: () => {\n // use menu.con() to send response without terminating session \n menu.con('Welcome. Choose option:' +\n '\\n1. Show Balance' +\n '\\n2. Buy Airtime');\n },\n // next object links to next state based on user input\n next: {\n '1': 'showBalance',\n '2': 'buyAirtime'\n }\n});\n\nmenu.state('showBalance', {\n run: () => {\n // fetch balance\n fetchBalance(menu.args.phoneNumber).then(function(bal){\n // use menu.end() to send response and terminate session\n menu.end('Your balance is KES ' + bal);\n });\n }\n});\n\nmenu.state('buyAirtime', {\n run: () => {\n menu.con('Enter amount:');\n },\n next: {\n // using regex to match user input to next state\n '*\\\\d+': 'buyAirtime.amount'\n }\n});\n\n// nesting states\nmenu.state('buyAirtime.amount', {\n run: () => {\n // use menu.val to access user input value\n var amount = Number(menu.val);\n buyAirtime(menu.args.phoneNumber, amount).then(function(res){\n menu.end('Airtime bought successfully.');\n });\n }\n});\n\n// Registering USSD handler with Express\n\napp.post('/ussd', function(req, res){\n menu.run(req.body, ussdResult => {\n res.send(ussdResult);\n });\n});\n\n```\n\n# Guide\n## Introduction\nThe USSD Menu Builder uses a state machine to create a USSD menu. A state\nis created for each menu. Each state has a unique name and a set of rules\nused to link to other states based on the user input.\n\n### Creating a menu\nBefore you can create any states, you first need to create an instance of\nthe menu.\n\n```javascript\nconst UssdMenu = require('ussd-menu-builder');\nconst menu = new UssdMenu();\n```\n\n### Running the menu\nThe **```menu.run(args, resultCallback)```** goes through the menu and finds\nthe appropriate state to run based on the user input.\n\nThe **```args```** object should contain the following keys coming from\nthe [Africastalking API](https://africastalking.com):\n\n- **`sessionId`**: unique session ID that persists through the entire USSD session,\ncan be used to store temporary that may be retrieved from different states\nduring the session\n- **`serviceCode`**: the USSD code registered with your serviceCode\n- **`phoneNumber`**: the end user's phone Number\n- **`text`**: The raw USSD input. It has the following format ```1*2*4*1```:\na string containing the input at each hop, separated by the asterisk symbol (```*```).\nThis is parsed by the ```UssdMenu``` to find the appropriate state to run at each hop.\n\nAfter the matched state runs, the resultCallback is called with the response from the state.\n\n**`Note: `** *The menu also returns a promise that can be resolved if you need to do anything with the final response.\nfor example:*\n```javascript\nlet resp = await menu.run(args) // resultCallback is not necessarry if you intend to run the menu in an async function\n\n```\nHere's an example registering a handler with the [express](https://expressjs.com) framework:\n```javascript\n\napp.post('/ussd', (req, res) => {\n let args = {\n phoneNumber: req.body.phoneNumber,\n sessionId: req.body.sessionId,\n serviceCode: req.body.serviceCode,\n text: req.body.text\n };\n menu.run(args, resMsg => {\n res.send(resMsg);\n });\n})\n\n```\n\nHandling menu.run response:\n```javascript\n\napp.post('/ussd', async (req, res) => {\n let args = {\n phoneNumber: req.body.phoneNumber,\n sessionId: req.body.sessionId,\n serviceCode: req.body.serviceCode,\n text: req.body.text\n };\n let resMsg = await menu.run(args);\n res.send(resMsg);\n})\n\n```\n\n## Defining states\n\nThe **`menu.state(name, options)`** method is used to define states. I takes the name of the state\nand an object with the following properites:\n- **`run`**: a function that's called when the state is resolved\n- **`next` (optional)**: an object that contains rules of how to match the input of this state\nto other states. *This is not required for final states*.\n- **`defaultNext` (optional)**: the name of the state to default to if the user\ninput could not be matched by the rules defined in the `next` object.\nIf not provided, the same state will be used as a fallback i.e. the same menu will\nbe displayed to the user.\n\nHere's an example:\n```javascript\nmenu.state('stateName', {\n run: function(){\n menu.con('Choose Option' +\n '\\n1. Load Account' +\n '\\n2. View Catalogue' +\n '\\n3. Check Balance'\n );\n },\n next: {\n '1': 'loadAccount',\n '2': 'catalogue',\n '3': 'balance'\n },\n defaultNext: 'invalidOption'\n});\n```\n\n### The **`run`** function\nEach state defines it's own `run` method which is called when that\nstate is matched. This is where you should place the logic for a given\nstate.\n\n#### Retrieving user input\nUse **```menu.val```** property to access the current user input.\n\n#### Accessing ussd parameters\nYou can access the ussd parameters through the **```menu.args```** object.\nThis parameters should come from the API Gateway and are passed to the\n```menu.run``` method.\n\n#### Sending the response\nYou must use either (not both) of the two methods to send\na response to be displayed to the user:\n- **`menu.con(msg)`**: Sends the result to be displayed to the user without\nterminating the session i.e. the user can reply with further input.\n- **`menu.end(msg)`**: Sends the response to be displayed to the user and\nrequests the session to be terminated i.e. the user cannot provide further\ninput. **Note:** *This consequently makes the state a final state and therefore the\n```next``` object does not need to be defined*\n\nExample:\n\n```javascript\nmenu.state('thisState', {\n run: function(){\n let value = menu.val;\n let session = getSession(menu.args.sessionId);\n let phone = menu.args.phoneNumber;\n session.set('phone', phone);\n session.set('value', value);\n menu.end('You entered: ' + value);\n }\n});\n```\n\n### The Start State\nThis is the first state or first menu to be displayed by the user.\nIt is created using the **```menu.startState(options)```**. It uses\nthe reserved name ```'__start__'```.\n\n``` javascript\nmenu.startState({\n run: function(){\n ...\n }\n next: {\n ...\n }\n});\n```\n\n***\n**Note**: the ```menu.state()``` and ```menu.startState()``` methods return\nthe same menu object instance for convenience.\n\n```javascript\nmenu.startState({\n ...\n})\n.state('state1', {\n ...\n})\n.state('state2', {\n ...\n})\n```\n***\n\n### Matching States\nTo link states you use the ```next``` object to map user input to a state name.\nYou can match input directly by value or with a regular expression.\n\n#### Matching direct values\nSimply add the expected string value as a key in the next object.\n\n#### Matching with regular expressions\nBegin the key with an asterisk (**```*```**) to indicate that the key should\nbe treated like a regular expression e.g. ```'*\\\\[a-zA-Z]+'``` would match\nany input containing only lowercase or uppercase letters.\n\nRemember you can use ```menu.val``` in the matched state to retrieve the actual user input.\n\nExample:\n```javascript\nmenu.state('registration', {\n run: function(){\n menu.con('Enter your name');\n },\n next: {\n '*[a-zA-Z]+': 'registration.name'\n }\n});\n\nmenu.state('registration.name', {\n run: function(){\n let name = menu.val;\n let session = getSession(menu.args.sessionId);\n session.set('name', name);\n menu.con('Enter your email');\n },\n next: {\n '*\\\\w+@\\\\w+\\\\.\\\\w+': 'registration.email'\n }\n});\n```\n\n#### Matching with empty rule on Start State\nIf the start state does not define a ```run``` method, you provide\nan empty string as key in ```next``` to redirect to another state.\n\n```javascript\nmenu.startState({\n next: {\n '': function(){\n if(user){\n return 'userMenu';\n }\n else {\n return 'registerMenu';\n }\n }\n }\n});\n```\n### Linking states\nBeside mapping user input directly to a state name, you can map it to\na function with returns a state name, synchronously with a simple\nreturn statement or asynchronously with a callback or a promise.\n\n#### Mapping to a direct state name\n```javascript\nmenu.state('thisState', {\n ...\n next: {\n 'input': 'nextState'\n }\n})\n```\n\n#### Mapping to a synchronous function\n```javascript\nmenu.state('thisState', {\n ...\n next: {\n 'input': function(){\n if(test){\n return 'nextState';\n } else {\n return 'otherState';\n }\n }\n }\n});\n```\n#### Mapping to an async function with callback\n```javascript\nmenu.state('thisState', {\n ...\n next: {\n 'input': function(callback){\n runAsyncCode(function(err, res){\n if(res){\n callback('nextState');\n } else {\n callback('otherState');\n }\n })\n }\n }\n});\n```\n\n#### Mapping to an async function with promise\n```javascript\nmenu.state('thisState', {\n ...\n next: {\n 'input': function(){\n return new Promise((resolve, reject) => {\n resolve('nextState');\n });\n }\n }\n});\n```\n\n### Jumping to different state\nYou can jump to a different state from the ```run``` function of one\nstate using the **```menu.go(stateName)```** method. This effectively\nbreaks the state chain (subsequent states will not be reachable) \nand is therefore only useful if jumping to a final state.\n\n```javascript\nmenu.state('thisState', {\n run: function(){\n menu.go('otherState');\n }\n});\n\nmenu.state('otherState', {\n run: function(){\n menu.end('Thank you!');\n }\n});\n```\n\nThe **```menu.goStart()```** method can be used to jump to the start state\nfrom within another state.\n\n## Nesting states\nThe library treats a USSD menu like a chain of interlinked states and therefore\nhas not internal concept of nesting. However you can achieve complex menus\nwith nested submenus by linking states appropriately. In addition you\ncould use a naming convention of your choice to make it clearer to see how\nstates are related. In these examples I used the following convention of \nseparating menu levels with a dot.\n\n## Sessions\nYou can store temporary user data that persists through an entire session.\nThe library provides a way for you to define your own custom session\nhandler so you're free to use whatever storage backend or driver you want.\nThe menu provides an easy interface to set and retrieve session data\nwithin states based on the implementation you provide.\n\n### Configuring handlers\n\nThe **`menu.sessionConfig(config)`** method is used to define your session\nhandler. It accepts an object with the implementations of the following\nmethods:\n\n- `start` [**`function(sessionId, callback)`**]: used to initialize a new\nsession, invoked internally by the `menu.run()` method before any state\nis called.\n- `end` [**`function(sessionId, callback)`**]: used to delete current session,\ninvoked internally by the `menu.end()` method.\n- `set` [**`function(sessionId, key, value, callback)`**]: used to store\na key-value pair in the current session, invoked internally by\n`menu.session.set()`.\n- `get` [**`function(sessionId, key, callback)`**]: used to retrieve a\nvalue from the current session by key, invoked internally by \n`menu.session.get()`.\n\n#### Example using local memory for storage\n\n```javascript\n\nlet sessions = {};\n\nlet menu = new UssdMenu();\nmenu.sessionConfig({\n start: (sessionId, callback){\n // initialize current session if it doesn't exist\n // this is called by menu.run()\n if(!(sessionId in sessions)) sessions[sessionId] = {};\n callback();\n },\n end: (sessionId, callback){\n // clear current session\n // this is called by menu.end()\n delete sessions[sessionId];\n callback();\n },\n set: (sessionId, key, value, callback) => {\n // store key-value pair in current session\n sessions[sessionId][key] = value;\n callback();\n },\n get: (sessionId, key, callback){\n // retrieve value by key in current session\n let value = sessions[sessionId][key];\n callback(null, value);\n }\n});\n\n```\n\n***\n**Note:** Instead of callbacks, you may also return promises from\nthose methods:\n```javascript\nmenu.sessionConfig({\n ...\n get: function(sessionId, key){\n return new Promise((resolve, reject) => {\n let value = sessions[sessionId][key];\n resolve(value);\n });\n }\n})\n```\n\n\n### Setting and getting data from the current session\n\nAnd then to add and retrieve data inside states, use the\n`menu.session` object:\n\n```javascript\n\nmenu.state('someState', {\n run: () => {\n let firstName = menu.val;\n menu.session.set('firstName', firstName)\n .then( () => {\n menu.con('Enter your last name');\n })\n }\n ...\n})\n...\nmenu.state('otherState', {\n run: () => {\n menu.session.get('firstName')\n .then( firstName => {\n // do something with the value\n console.log(firstName);\n ...\n menu.con('Next');\n })\n }\n})\n...\n```\n\n***\n**Note**: The `menu.session`'s methods also work with callbacks:\n```javascript\nmenu.session.set('key', 'value', (err) => {\n menu.con('...');\n});\n\nmenu.session.get('key', (err, value) => {\n console.log(value);\n ...\n});\n```\n***\n\n***\n**Note**: It's not required to configure a session handler. You can\naccess your storage driver directly if you prefer. However if you\ndo configure a handler using the above method then you should provide\nimplementations for all the 4 methods as shown above..\n***\n\n## Errors\n\n`UssdMenu` instances emit an **`error` event** when an error occurs during the\nstate resolution process (e.g: **\"state not found\"** or **\"run function not defined\"**).\n\n```javascript\n\nmenu.startState({\n ...\n next: {\n '1': 'nonExistentState'\n }\n});\n\nmenu.on('error', (err) => {\n // handle errors\n console.log('Error', err);\n});\n\n\nargs.text = '1';\nmenu.run(args);\n\n```\n\nIn addition, errors passed to the callback of the session handler's methods or \nrejected by their promises will also trigger the `error` event for convenience\nso that you can handle your handle errors in one place.\n\n```javascript\n\nmenu.sessionConfig({\n ...\n get: (sessionId, key, callback){\n callback(new Error('error'));\n }\n});\n\nmenu.on('error', err => {\n // handle errors\n console.log(err);\n});\n\n...\n\nmenu.state('someState', {\n run: () => {\n menu.session.get('key').then(val => {\n ...\n });\n // you don't have to catch the error here\n }\n});\n\n```\n\n## Hubtel Support\n\nAs of version 1.1.0, ussd-menu-builder has added support for Hubtel's USSD API by providing the `provider` option when creating the **UssdMenu** object. There are no changes to the way states are defined, and the HTTP request parameters sent by Hubtel are mapped as usual to `menu.args`, and the result of `menu.run` is mapped to the HTTP response object expected by Hubtel (`menu.con` returns a _Type: Respons & `menu.end` returns a Type: Release). The additional HTTP request parameters like Operator, ClientState, and Sequence are not used.\n\nThe key difference with Hubtel is that the service only sends the most recent response message, rather than the full route string. The library handles that using the Sessions feature, which requires that a SessionConfig is defined in order to store the session's full route. This is stored in the key `route`, so if you use that key in your application it could cause issues.\n\n\n### Example\n\n```javascript\nmenu = new UssdMenu({ provider: 'hubtel' });\n// Define Session Config & States normally\nmenu.sessionConfig({ ... });\nmenu.state('thisState', {\n run: function(){\n ...\n });\n});\n\napp.post('/ussdHubtel', (req, res) => {\n menu.run(req.body, resMsg => {\n // resMsg would return an object like:\n // { \"Type\": \"Response\", \"Message\": \"Some Response\" }\n res.json(resMsg);\n });\n})\n```\n"
},
{
"path": "index.d.ts",
"content": "/// \n\n// Type definitions for ussd-menu-builder 1.0.0\n// Project: ussd-menu-builder\n// Definitions by: Jason Schapiro \n\nimport { EventEmitter } from \"events\";\n\nexport = UssdMenu;\n\ndeclare class UssdState {\n constructor(menu: UssdMenu);\n\n defaultNext?: string;\n\n menu: UssdMenu;\n\n name: string;\n\n run(): void;\n\n val: string;\n}\n\ndeclare class UssdMenu extends EventEmitter {\n constructor(opts?: UssdMenu.UssdMenuOptions);\n\n session: any;\n provider: UssdMenu.UssdMenuProvider;\n args: UssdMenu.UssdGatewayArgs;\n states: Array;\n result: string;\n val: string;\n\n callOnResult(): void;\n\n con(text: string): void;\n\n end(text: string): void;\n\n getRoute(args: UssdMenu.UssdGatewayArgs | UssdMenu.HubtelArgs): Promise;\n\n go(state: string): void;\n\n goStart(): void;\n\n mapArgs(args: UssdMenu.UssdGatewayArgs | UssdMenu.HubtelArgs): UssdMenu.UssdGatewayArgs;\n\n\n onResult?(result: string | UssdMenu.HubtelResponse): void;\n\n resolveRoute(route: string, callback: Function): void;\n\n resolve?(value: string): void;\n\n run(args: UssdMenu.UssdGatewayArgs, onResult?: Function): Promise;\n\n runState(state: UssdState): void;\n\n sessionConfig(config: UssdMenu.UssdSessionConfig): void;\n\n startState(options: UssdMenu.UssdStateOptions): void;\n\n state(name: string, options: UssdMenu.UssdStateOptions): UssdMenu;\n\n testLinkRule(rule: string, val: string): boolean;\n\n static START_STATE: string;\n}\n\n/*~ If you want to expose types from your module as well, you can\n *~ place them in this block.\n */\ndeclare namespace UssdMenu {\n interface NextState {\n [state: string]: Function | string;\n }\n\n interface UssdGatewayArgs {\n text: string;\n phoneNumber: string;\n sessionId: string;\n serviceCode: string;\n }\n\n interface HubtelResponse {\n Type: 'Response' | 'Release';\n Message: string;\n }\n\n interface HubtelArgs {\n Mobile: string;\n SessionId: string;\n ServiceCode: string;\n Type: 'Initiation' | 'Response' | 'Release' | 'Timeout';\n Message: string;\n Operator: 'Tigo' | 'Airtel' | 'MTN' | 'Vodafone' | 'Safaricom';\n Sequence: number;\n ClientState?: any;\n }\n\n type UssdMenuProvider = 'africasTalking' | 'hubtel';\n interface UssdMenuOptions {\n provider?: UssdMenuProvider;\n }\n \n interface UssdStateOptions {\n run(): void;\n next?: NextState;\n defaultNext?: string;\n }\n \n interface UssdSessionConfig {\n start(sessionId: string, callback?: Function): (Promise | void);\n \n end(sessionId: string, callback?: Function): (Promise | void);\n \n get(sessionId: string, key: string, callback?: Function): (Promise | void);\n \n set(sessionId: string, key: string, value: any, callback?: Function): (Promise | void);\n }\n}\n\n\n"
},
{
"path": "index.js",
"content": "\nmodule.exports = require('./lib/ussd-menu');"
},
{
"path": "lib/ussd-menu.js",
"content": "'use strict';\nconst async = require('async');\nconst EventEmitter = require('events');\n\n\nclass UssdMenu extends EventEmitter {\n\n constructor (opts = {}) {\n super();\n const validProviders = ['hubtel', 'africasTalking'];\n this.provider = opts.provider || 'africasTalking';\n if (!validProviders.includes(this.provider)) {\n throw Error('error', new Error(`Invalid Provider Option: ${this.provider}`));\n }\n this.session = null;\n this.args = null;\n this.states = {};\n this.result = '';\n this.onResult = null;\n this.val = '';\n this.resolve = null;\n }\n\n callOnResult () {\n if(this.onResult){\n this.onResult(this.result);\n }\n if(this.resolve){\n this.resolve(this.result);\n }\n }\n\n con (text) {\n if (this.provider === 'hubtel') {\n this.result = {\n Message: text,\n Type: 'Response',\n };\n } else {\n this.result = 'CON ' + text;\n }\n this.callOnResult();\n }\n\n end (text) {\n if (this.provider === 'hubtel') {\n this.result = {\n Message: text,\n Type: 'Release',\n };\n } else {\n this.result = 'END ' + text;\n }\n this.callOnResult();\n if(this.session){\n this.session.end();\n }\n }\n\n testLinkRule (rule, val) {\n //if rule starts with *, treat as regex\n if (typeof rule === 'string' && rule[0] === '*') {\n var re = new RegExp(rule.substr(1));\n return re.test(val);\n }\n return rule == val;\n }\n\n /**\n * find state based on route\n * @param string route a ussd text in form 1*2*7\n * @return UssdState\n */\n resolveRoute (route, callback) {\n // separate route parts\n var parts = route === ''? [] : route.split('*');\n // follow the links from start state\n var state = this.states[UssdMenu.START_STATE];\n \n if(!state.next || Object.keys(state.next).length === 0){\n // if first state has no next link defined\n return callback(null, this.states[state.defaultNext]);\n }\n\n // if the first state has route rule for empty string,\n // prepend it to route parts\n if ('' in state.next) {\n parts.unshift('');\n }\n \n async.whilst(\n () => parts.length > 0 ,\n (whileCb) => {\n \n // get next link from route\n var part = parts.shift();\n var nextFound = false;\n this.val = part;\n //check if link matches any declared on current next\n async.forEachOfSeries(\n state.next,\n (next, link, itCb) => {\n \n /* called when next path has been retrieved\n * either synchronously or with async callback or promise\n */\n let nextPathCallback = (nextPath) => {\n state = this.states[nextPath];\n if (!state) {\n return itCb(\n new Error(`declared state does not exist: ${nextPath}`));\n }\n\n state.val = part;\n nextFound = true;\n return itCb({ intended: true });\n };\n \n if (this.testLinkRule(link, part)) {\n var nextPath;\n // get next state based\n // the type of value linked\n switch (typeof next) {\n case 'string':\n // get the state based on name\n nextPath = next;\n break;\n case 'function':\n // custom function declared\n nextPath = next(nextPathCallback);\n break;\n }\n if (typeof nextPath === 'string') {\n // nextPath determined synchronously,\n // manually call callback\n return nextPathCallback(nextPath);\n }\n else if (nextPath && nextPath.then) {\n // promise used to retrieve nextPath\n return nextPath.then(nextPathCallback);\n }\n\n }\n else {\n return itCb();\n }\n },\n (err) => {\n if (err && !err.intended) {\n \n return whileCb(err);\n }\n if (!nextFound && state.defaultNext) {\n // if link not found, resort to default if specified\n state = this.states[state.defaultNext];\n state.val = part;\n }\n\n whileCb();\n }\n ); \n \n // end iterator\n },\n (err) => {\n if(err){\n return callback(err);\n }\n \n return callback(null, state);\n }\n );\n }\n\n runState (state) {\n if (!state.run) {\n return this.emit('error', new Error(`run function not defined for state: ${state.name}`));\n }\n state.run(state);\n }\n\n go (stateName) {\n var state = this.states[stateName];\n state.val = this.val;\n this.runState(state);\n }\n\n goStart () {\n this.go(UssdMenu.START_STATE);\n }\n\n /**\n * configure custom session handler\n * @param {Object} config object with implementation\n * for get, set, start and end methods\n */\n sessionConfig (config) {\n /*\n the following 2 functions are used to make session\n method cross-compatible between callbacks and promises\n */\n\n /**\n * creates a callback function that calls\n * the promise resolve and reject functions as well as\n * the provided callback\n * \n */\n let makeCb = (resolve, reject, cb) => {\n return (err, res) => {\n if(err){\n if(cb) cb(err); \n reject(err);\n this.emit('error', err);\n }\n else {\n if(cb) cb(null, res);\n resolve(res); \n }\n };\n };\n\n /**\n * if p is a promise, handle its resolve and reject\n * chains and invoke the provided callback\n */\n let resolveIfPromise = (p, resolve, reject, cb) => {\n if(p && p.then){\n p.then( res => {\n if(cb) cb(null, res);\n resolve(res); \n }).catch(err => {\n if(cb) cb(err);\n reject(err); \n this.emit('error', err);\n });\n }\n };\n\n // implement session methods based on user-defined handlers\n this.session = {\n start: (cb) => {\n return new Promise((resolve, reject) => {\n let res = config.start(this.args.sessionId, makeCb(resolve, reject, cb));\n resolveIfPromise(res, resolve, reject, cb);\n });\n },\n get: (key, cb) => {\n return new Promise((resolve, reject) => {\n let res = config.get(this.args.sessionId, key, makeCb(resolve, reject, cb));\n resolveIfPromise(res, resolve, reject, cb);\n }); \n },\n set: (key, val, cb) => {\n return new Promise((resolve, reject) => {\n let res = config.set(this.args.sessionId, key, val, makeCb(resolve, reject, cb));\n resolveIfPromise(res, resolve, reject, cb);\n }); \n },\n end: (cb) => {\n return new Promise((resolve, reject) => {\n let res = config.end(this.args.sessionId, makeCb(resolve, reject, cb));\n resolveIfPromise(res, resolve, reject, cb);\n });\n }\n };\n }\n\n /**\n * create a state on the ussd chain\n * @param string name name of the state\n * @param object options\n * @param object options.next object mapping of route \n * val to state names\n * @param string options.defaultNext name of state to run\n * when the given route from this state can't be resolved\n * @param function options.run the method to run when this\n * state is resolved\n * @return Ussd the same instance of Ussd\n */\n state (name, options) {\n var state = new UssdState(this);\n this.states[name] = state;\n \n state.name = name;\n state.next = options.next;\n state.run = options.run;\n // default defaultNext to same state\n state.defaultNext = options.defaultNext || name;\n \n \n return this;\n }\n\n /**\n * create the start state of the ussd chain\n */\n startState (options) {\n return this.state(UssdMenu.START_STATE, options); \n }\n\n /*\n * maps incoming API arguments to the format used by Africa's Talking\n */\n mapArgs (args) {\n if (this.provider === 'hubtel') {\n this.args = {\n sessionId: args.SessionId,\n phoneNumber: `+${args.Mobile}`,\n serviceCode: args.ServiceCode,\n text: args.Type === 'Initiation' ? this.parseHubtelInitiationText(args) : args.Message,\n };\n } else {\n this.args = args;\n }\n }\n\n /*\n * If message equals shortcode, ignore.\n * Otherwise parse message as an initial route\n * For example, if servicecode is *714*5# and initial text is\n * *714*5*3*100*1#, then the text/route is 3*100*1\n */\n parseHubtelInitiationText(hubtelArgs) {\n const { ServiceCode: serviceCode, Message: text } = hubtelArgs;\n if (text === `*${serviceCode}#`) {\n return '';\n } else {\n // Remove service code, first asterisk and end hash, treat rest as a route\n const routeStart = serviceCode.length + 2;\n return text.slice(routeStart, -1);\n }\n }\n\n /*\n * Returns the full route string joined by asterisks, ex: 1*2*41\n * Africa's Talking Provides full route string, but hubtel only has the\n * message text sent and must be concatinated.\n */\n getRoute(args) {\n if (this.provider === 'hubtel') {\n if (this.session === null) {\n return this.emit('error', new Error('Session config required for Hubtel provider'));\n } else if (args.Type === 'Initiation') {\n // Parse initial message for a route\n const route = this.parseHubtelInitiationText(args);\n return this.session.set('route', route).then(() => route);\n } else {\n return this.session.get('route').then(pastRoute => {\n const route = pastRoute ? `${pastRoute}*${this.args.text}` : this.args.text;\n return this.session.set('route', route).then(() => route);\n });\n }\n } else {\n return Promise.resolve(this.args.text);\n }\n }\n\n /**\n * run the ussd menu\n * @param object args request args from the gateway api\n * @param string args.text\n * @param string args.phoneNumber\n * @param string args.sessionId\n * @param string args.serviceCode\n */\n run (args, onResult) {\n this.mapArgs(args);\n this.onResult = onResult;\n\n let run = () => {\n this.getRoute(args).then(route => {\n this.resolveRoute(route, (err, state) => {\n if (err) {\n return this.emit('error', new Error(err));\n }\n this.runState(state);\n });\n }).catch(err => {\n console.error('Failed to get route:', err);\n return this.emit('error', new Error(err));\n })\n };\n\n if(this.session){\n this.session.start().then(run);\n }\n else {\n run();\n }\n\n return new Promise((resolve,reject)=>{\n this.resolve = resolve;\n });\n\n }\n\n}\n\nUssdMenu.START_STATE = '__start__';\n\n\nclass UssdState {\n \n constructor (menu) {\n this.menu = menu;\n this.name = null;\n this.run = null;\n this.defaultNext = null;\n this.val = null;\n } \n \n}\n\nmodule.exports = UssdMenu;"
},
{
"path": "package.json",
"content": "{\n \"name\": \"ussd-menu-builder\",\n \"version\": \"1.2.0\",\n \"description\": \"Easily compose USSD menus using states, compatible with Africastalking API\",\n \"main\": \"index.js\",\n \"types\": \"index.d.ts\",\n \"scripts\": {\n \"test\": \"mocha test\",\n \"coverage\": \"istanbul cover node_modules/mocha/bin/_mocha test -- -R spec\",\n \"coveralls\": \"istanbul cover ./node_modules/mocha/bin/_mocha --report lcovonly -- -R spec && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js && rm -rf ./coverage\"\n },\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/habbes/ussd-menu-builder\"\n },\n \"keywords\": [\n \"ussd-menu-builder\",\n \"ussd\",\n \"africastalking\",\n \"ussd-menu\",\n \"hubtel\"\n ],\n \"author\": \"Habbes \",\n \"license\": \"MIT\",\n \"bugs\": {\n \"url\": \"https://github.com/habbes/ussd-menu-builder/issues\"\n },\n \"homepage\": \"https://github.com/habbes/ussd-menu-builder\",\n \"dependencies\": {\n \"async\": \"^2.6.1\"\n },\n \"devDependencies\": {\n \"chai\": \"^4.2.0\",\n \"coveralls\": \"^3.0.2\",\n \"istanbul\": \"^0.4.5\",\n \"mocha\": \"^5.2.0\",\n \"mocha-lcov-reporter\": \"^1.3.0\"\n }\n}\n"
},
{
"path": "test/ussd-menu.js",
"content": "'use strict';\nconst expect = require('chai').expect;\nconst UssdMenu = require('../lib/ussd-menu');\n\ndescribe('UssdMenu', function () {\n let menu,\n args = {\n phoneNumber: '+2547123456789',\n serviceCode: '111',\n sessionId: 'sfdsfdsafdsf',\n text: ''\n };\n beforeEach(function () {\n menu = new UssdMenu();\n });\n\n describe('States', function () {\n\n it('should create start state', function () {\n menu.startState({\n run: function () {\n menu.con('1. Next');\n },\n next: {\n '1': 'next'\n }\n });\n\n let state = menu.states[UssdMenu.START_STATE];\n expect(state).to.be.an('object');\n expect(state.next).to.be.an('object');\n expect(state.next['1']).to.equal('next');\n expect(state.run).to.be.a('function');\n });\n\n it('should create states', function () {\n menu.state('state1', {\n run: function () {\n menu.con('1. State 2');\n },\n next: {\n '1': 'state2'\n }\n });\n\n menu.state('state2', {\n run: function () {\n menu.end('End.');\n }\n });\n\n let state = menu.states['state1'];\n expect(state).to.be.an('object');\n expect(state.next).to.be.an('object');\n expect(state.next['1']).to.equal('state2');\n expect(state.run).to.be.a('function');\n\n state = menu.states['state2'];\n expect(state).to.be.an('object');\n expect(state.run).to.be.a('function');\n });\n });\n\n describe('State Resolution', function () {\n\n it('should run the start state if no empty rule exists', function (done) {\n args.text = '';\n menu.startState({\n run: function () {\n done();\n },\n next: {\n '1': 'state2'\n }\n });\n\n menu.run(args);\n });\n\n it('should follow the empty rule on the start state if declared', function (done) {\n\n args.text = '';\n menu.startState({\n run: function () {\n done('Error: start state called');\n },\n next: {\n '': 'state1'\n }\n });\n\n menu.state('state1', {\n run: function () {\n done();\n }\n });\n\n menu.run(args);\n });\n\n it('should pass the state to the run function', function (done) {\n\n args.text = '1';\n menu.startState({\n next: {\n '1': 'state1'\n }\n });\n menu.state('state1', {\n run: function (state) {\n expect(state.val).to.equal('1');\n expect(menu.val).to.equal('1');\n expect(state.menu).to.equal(menu);\n expect(state.menu.args).to.deep.equal(args);\n done();\n }\n });\n\n menu.run(args);\n });\n\n it('should resolve simple string rules', function (done) {\n\n args.text = '1*4';\n menu.startState({\n next: {\n '1': 'state1'\n }\n });\n\n menu.state('state1', {\n next: {\n '4': 'state1.4'\n }\n });\n\n menu.state('state1.4', {\n run: function (state) {\n expect(state.val).to.equal('4');\n done();\n }\n });\n\n menu.run(args);\n });\n\n it('should resolve regex rules when starting with *', function (done) {\n\n args.text = '1*James';\n menu.startState({\n next: {\n '1': 'state1'\n }\n });\n\n menu.state('state1', {\n next: {\n '*\\\\w+': 'state1.name'\n }\n });\n\n menu.state('state1.name', {\n run: function (state) {\n expect(state.val).to.equal('James');\n done();\n }\n });\n\n menu.run(args);\n });\n\n it('should resolve regex first if declared before conflicting rule', function (done) {\n\n args.text = 'input';\n menu.startState({\n next: {\n '*\\\\w+': 'state1',\n 'input': 'state2' // conflicts with \\w+ regex\n }\n });\n\n menu.state('state1', {\n run: function (state) {\n expect(state.val).to.equal('input');\n done();\n }\n });\n\n menu.state('state2', {\n run: function (state) {\n done('state2 not supposed to be called');\n }\n });\n\n menu.run(args);\n });\n\n it('should not resolve regex first if declared after conflicting rule', function (done) {\n\n args.text = 'rule';\n menu.startState({\n next: {\n 'rule': 'state1',\n '*\\\\w+': 'state2'\n }\n });\n\n menu.state('state1', {\n run: function (state) {\n expect(state.val).to.equal('rule');\n done();\n }\n });\n\n menu.state('state2', {\n run: function (state) {\n done('state2 not supposed to be called');\n }\n });\n\n menu.run(args);\n });\n\n it('should successfully resolve state based on sync function', function (done) {\n\n args.text = '1';\n menu.startState({\n next: {\n '1': function () {\n return 'state1';\n }\n }\n });\n\n menu.state('state1', {\n run: function (state) {\n expect(state.val).to.equal('1');\n done();\n }\n });\n\n menu.run(args);\n });\n\n it('should successfully resolve state based on async function using callback', function (done) {\n\n args.text = '1';\n menu.startState({\n next: {\n '1': function (callback) {\n return callback('state1');\n }\n }\n });\n\n menu.state('state1', {\n run: function (state) {\n expect(state.val).to.equal('1');\n done();\n }\n });\n\n menu.run(args);\n });\n\n it('should successfully resolve state based on async function using promise', function (done) {\n\n args.text = '1';\n menu.startState({\n next: {\n '1': function () {\n return new Promise((resolve, reject) => {\n return resolve('state1');\n });\n }\n }\n });\n\n menu.state('state1', {\n run: function (state) {\n expect(state.val).to.equal('1');\n done();\n }\n });\n\n menu.run(args);\n });\n\n it('should fall back to declared default if link not found', function (done) {\n args.text = '1*invalid';\n menu.startState({\n next: {\n '1': 'state1'\n }\n });\n\n menu.state('state1', {\n next: {\n '1': 'state1.1',\n '2': 'state1.2',\n },\n\n defaultNext: 'state1.default'\n });\n\n menu.state('state1.default', {\n run: function (state) {\n expect(state.val).to.equal('invalid');\n done();\n }\n });\n\n menu.run(args);\n });\n\n if ('should use same state as default if no default is declared', function (done) {\n args.text = '1*invalid';\n menu.startState({\n next: {\n '1': 'state1'\n }\n });\n\n menu.state('state1', {\n run: function (state) {\n expect(state.val).to.equal('invalid');\n done();\n },\n next: {\n '1': 'state1.1',\n '2': 'state1.2',\n }\n });\n });\n\n it('should redirect to a different state using the go method', function (done) {\n args.text = '1';\n menu.startState({\n next: {\n '1': 'state1',\n '2': 'state2'\n }\n });\n menu.state('state1', {\n run: function (state) {\n menu.go('state2');\n }\n });\n menu.state('state2', {\n run: function (state) {\n expect(state.val).to.equal('1'); //retains the val of the referring state\n expect(menu.val).to.equal('1');\n done();\n }\n });\n menu.run(args);\n\n });\n\n it('should redirect to the start state using goStart method', function (done) {\n args.text = '1';\n menu.startState({\n run: function (state) {\n expect(state.val).to.equal('1');\n expect(menu.val).to.equal('1');\n done();\n },\n next: {\n '1': 'state1',\n '2': 'state2'\n }\n });\n menu.state('state1', {\n run: function (state) {\n menu.goStart();\n }\n });\n\n menu.run(args);\n });\n\n });\n\n\n\n describe('Response', function () {\n let args = {\n phoneNumber: '+254123456789',\n serviceCode: '111',\n sessionId: 'dsfsfsdfsd',\n text: ''\n };\n it('should successfully return a CON response', function (done) {\n\n let message = 'Choose option';\n menu.startState({\n run: function () {\n menu.con(message);\n }\n });\n\n menu.run(args, function (res) {\n expect(res).to.equal('CON ' + message);\n done();\n });\n });\n\n it('should successfully return an END response', function (done) {\n\n let message = 'Thank you';\n menu.startState({\n run: function () {\n menu.end(message);\n }\n });\n menu.run(args, function (res) {\n expect(res).to.equal('END ' + message);\n done();\n });\n });\n\n });\n\n\n describe('Sessions', function () {\n\n describe('Callback-based config', function () {\n let menu;\n let session;\n let args = {\n serviceCode: '*111#',\n phoneNumber: '123456',\n sessionId: '324errw44we'\n };\n let config = {\n start: (id, cb) => {\n if (!(id in session)) session[id] = {};\n cb();\n },\n end: (id, cb) => {\n delete session[id];\n cb();\n },\n get: (id, key, cb) => {\n let val = session[id][key];\n cb(null, val);\n },\n set: (id, key, val, cb) => {\n session[id][key] = val;\n cb();\n }\n };\n\n\n it('should manage session using promises', function (done) {\n session = {};\n menu = new UssdMenu();\n menu.sessionConfig(config);\n menu.startState({\n run: () => {\n menu.session.set('name', 'Habbes').then(() => {\n expect(session[args.sessionId].name).to.equal('Habbes');\n menu.con('Next');\n })\n .catch(err => {\n done(err);\n });\n },\n next: {\n '1': 'state1'\n }\n });\n\n menu.state('state1', {\n run: () => {\n menu.session.get('name').then(val => {\n expect(val).to.equal('Habbes');\n menu.end();\n })\n .catch(err => {\n console.log('STATE1 error', err);\n done(err);\n });\n }\n });\n\n args.text = '';\n menu.run(args, () => {\n expect(session[args.sessionId]).to.deep.equal({ name: 'Habbes' });\n args.text = '1';\n menu.run(args, () => {\n process.nextTick(() => {\n // expect session to be deleted\n expect(session[args.sessionId]).to.not.be.ok;\n done();\n });\n\n });\n });\n\n\n\n });\n\n\n it('should manage session using callbacks', function (done) {\n session = {};\n menu = new UssdMenu();\n menu.sessionConfig(config);\n menu.startState({\n run: () => {\n menu.session.set('name', 'Habbes', err => {\n if (err) return done(err);\n expect(session[args.sessionId].name).to.equal('Habbes');\n menu.con('Next');\n });\n },\n next: {\n '1': 'state1'\n }\n });\n\n menu.state('state1', {\n run: () => {\n menu.session.get('name', (err, val) => {\n if (err) return done(err);\n expect(val).to.equal('Habbes');\n menu.end();\n });\n }\n });\n\n args.text = '';\n menu.run(args, () => {\n expect(session[args.sessionId]).to.deep.equal({ name: 'Habbes' });\n args.text = '1';\n menu.run(args, _ => {\n process.nextTick(() => {\n // expect session to be deleted\n expect(session[args.sessionId]).to.not.be.ok;\n done();\n });\n\n });\n });\n\n\n\n });\n\n\n });\n\n\n describe('Promise-based config', function () {\n let menu;\n let session;\n let args = {\n serviceCode: '*111#',\n phoneNumber: '123456',\n sessionId: '324errw44we'\n };\n let config = {\n start: (id) => {\n return new Promise((resolve, reject) => {\n if (!(id in session)) session[id] = {};\n return resolve();\n });\n },\n end: (id) => {\n return new Promise((resolve, reject) => {\n delete session[id];\n return resolve();\n });\n },\n get: (id, key) => {\n return new Promise((resolve, reject) => {\n let val = session[id][key];\n return resolve(val);\n });\n },\n set: (id, key, val) => {\n return new Promise((resolve, reject) => {\n session[id][key] = val;\n return resolve();\n });\n }\n };\n\n\n it('should manage session using promises', function (done) {\n session = {};\n menu = new UssdMenu();\n menu.sessionConfig(config);\n menu.startState({\n run: () => {\n menu.session.set('name', 'Habbes').then(() => {\n expect(session[args.sessionId].name).to.equal('Habbes');\n menu.con('Next');\n })\n .catch(done);\n },\n next: {\n '1': 'state1'\n }\n });\n\n menu.state('state1', {\n run: () => {\n menu.session.get('name').then(val => {\n expect(val).to.equal('Habbes');\n menu.end();\n })\n .catch(done);\n }\n });\n\n args.text = '';\n menu.run(args, () => {\n expect(session[args.sessionId]).to.deep.equal({ name: 'Habbes' });\n args.text = '1';\n menu.run(args, _ => {\n process.nextTick(() => {\n // expect session to be deleted\n expect(session[args.sessionId]).to.not.be.ok;\n done();\n });\n\n });\n });\n\n\n\n });\n\n\n it('should manage session using callbacks', function (done) {\n session = {};\n menu = new UssdMenu();\n menu.sessionConfig(config);\n menu.startState({\n run: () => {\n menu.session.set('name', 'Habbes', err => {\n if (err) return done(err);\n expect(session[args.sessionId].name).to.equal('Habbes');\n menu.con('Next');\n });\n },\n next: {\n '1': 'state1'\n }\n });\n\n menu.state('state1', {\n run: () => {\n menu.session.get('name', (err, val) => {\n if (err) return done(err);\n expect(val).to.equal('Habbes');\n menu.end();\n });\n }\n });\n\n args.text = '';\n menu.run(args, () => {\n expect(session[args.sessionId]).to.deep.equal({ name: 'Habbes' });\n args.text = '1';\n menu.run(args, _ => {\n process.nextTick(() => {\n // expect session to be deleted\n expect(session[args.sessionId]).to.not.be.ok;\n done();\n });\n\n });\n });\n\n\n\n });\n\n\n });\n\n });\n\n describe('Error handling', function () {\n\n it('should emit error when route cannot be reached', function (done) {\n menu = new UssdMenu();\n menu.startState({\n run: () => {\n menu.con('Next');\n },\n next: {\n '1': 'unknown'\n }\n });\n args.text = '1';\n menu.on('error', err => {\n expect(err).to.be.an('error');\n done();\n });\n menu.run(args);\n });\n\n it('should emit error when run function not defined on matched route', function (done) {\n menu = new UssdMenu();\n menu.startState({\n run: () => {\n menu.con('Next');\n },\n next: {\n '1': 'state1'\n }\n });\n menu.state('state1', {});\n args.text = '1';\n menu.on('error', err => {\n expect(err).to.be.an('error');\n done();\n });\n menu.run(args);\n\n });\n\n describe('Session Handler errors', function () {\n\n it('should emit error when session start handler returns error in callback', function (done) {\n let config = {\n start: (sessionId, cb) => {\n cb(new Error('start error'));\n },\n };\n\n menu.on('error', err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('start error');\n done();\n });\n menu.sessionConfig(config);\n menu.run(args);\n\n });\n\n it('should emit error when session start handler returns error in promise', function (done) {\n let config = {\n start: () => {\n return new Promise((resolve, reject) => {\n return reject(new Error('start error'))\n });\n },\n };\n\n menu.on('error', err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('start error');\n done();\n });\n menu.sessionConfig(config);\n menu.run(args);\n\n });\n\n it('should emit error when session start handler throws error in promise', function (done) {\n let config = {\n start: () => {\n return new Promise(() => {\n throw new Error('start error');\n });\n },\n };\n\n menu.on('error', err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('start error');\n done();\n });\n menu.sessionConfig(config);\n menu.run(args);\n\n });\n\n it('should emit error when set handler returns error in callback', function (done) {\n let config = {\n start: (id, cb) => {\n cb();\n },\n set: (sessionId, key, val, cb) => {\n cb(new Error('set error'));\n },\n };\n menu.sessionConfig(config);\n menu.on('error', err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('set error');\n done();\n });\n\n menu.startState({\n run: () => {\n menu.session.set('key', 'value');\n }\n });\n menu.run(args);\n\n });\n\n it('should emit error when set handler returns error in promise', function (done) {\n let config = {\n start: (id, cb) => {\n cb();\n },\n set: () => {\n return new Promise((resolve, reject) => {\n reject(new Error('set error'));\n });\n },\n };\n menu.sessionConfig(config);\n menu.on('error', err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('set error');\n done();\n });\n\n menu.startState({\n run: () => {\n menu.session.set('key', 'value');\n }\n });\n menu.run(args);\n\n });\n\n it('should emit error when set handler throws error in promise', function (done) {\n let config = {\n start: (id, cb) => {\n cb();\n },\n set: () => {\n return new Promise(() => {\n throw new Error('set error');\n });\n },\n };\n menu.sessionConfig(config);\n menu.on('error', err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('set error');\n done();\n });\n\n menu.startState({\n run: () => {\n menu.session.set('key', 'value');\n }\n });\n menu.run(args);\n\n });\n\n\n it('should pass error in callback to session.set when set handler passes error to callback', function (done) {\n let config = {\n start: (id, cb) => {\n cb();\n },\n set: (id, key, val, cb) => {\n cb(new Error('set error'));\n },\n };\n menu.sessionConfig(config);\n\n menu.startState({\n run: () => {\n menu.session.set('key', 'value', err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('set error');\n done();\n });\n }\n });\n menu.run(args);\n });\n\n\n it('should catch error in promise in session.set when set handler passes error to callback', function (done) {\n let config = {\n start: (id, cb) => {\n cb();\n },\n set: (id, key, val, cb) => {\n cb(new Error('set error'));\n },\n };\n menu.sessionConfig(config);\n\n menu.startState({\n run: () => {\n menu.session.set('key', 'value')\n .catch(err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('set error');\n done();\n });\n }\n });\n menu.run(args);\n });\n\n\n it('should pass error in callback to session.set when set handler rejects error in promise', function (done) {\n let config = {\n start: (id, cb) => {\n cb();\n },\n set: () => {\n return new Promise((resolve, reject) => {\n reject(new Error('set error'));\n });\n },\n };\n menu.sessionConfig(config);\n\n menu.startState({\n run: () => {\n menu.session.set('key', 'value', err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('set error');\n done();\n });\n }\n });\n menu.run(args);\n });\n\n\n it('should catch error in promise in session.set when set handler rejects error in promise', function (done) {\n let config = {\n start: (id, cb) => {\n cb();\n },\n set: () => {\n return new Promise((resolve, reject) => {\n reject(new Error('set error'));\n });\n },\n };\n menu.sessionConfig(config);\n\n menu.startState({\n run: () => {\n menu.session.set('key', 'value')\n .catch(err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('set error');\n done();\n });\n }\n });\n menu.run(args);\n });\n\n\n\n it('should emit error when get handler returns error in callback', function (done) {\n let config = {\n start: (id, cb) => {\n cb();\n },\n get: (sessionId, key, cb) => {\n cb(new Error('set error'));\n },\n };\n menu.sessionConfig(config);\n menu.on('error', err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('set error');\n done();\n });\n\n menu.startState({\n run: () => {\n menu.session.get('key');\n }\n });\n menu.run(args);\n\n });\n\n\n it('should emit error when get handler returns error in promise', function (done) {\n let config = {\n start: (id, cb) => {\n cb();\n },\n get: () => {\n return new Promise((resolve, reject) => {\n return reject(new Error('set error'));\n });\n },\n };\n menu.sessionConfig(config);\n menu.on('error', err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('set error');\n done();\n });\n\n menu.startState({\n run: () => {\n menu.session.get('key');\n }\n });\n menu.run(args);\n\n });\n\n\n it('should emit error when get handler throws error in promise', function (done) {\n let config = {\n start: (id, cb) => {\n cb();\n },\n get: () => {\n return new Promise(() => {\n throw new Error('set error');\n });\n },\n };\n menu.sessionConfig(config);\n menu.on('error', err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('set error');\n done();\n });\n\n menu.startState({\n run: () => {\n menu.session.get('key');\n }\n });\n menu.run(args);\n\n });\n\n it('should pass error in callback to session.get when get handler passes error to callback', function (done) {\n let config = {\n start: (id, cb) => {\n cb();\n },\n get: (id, key, cb) => {\n cb(new Error('get error'));\n },\n };\n menu.sessionConfig(config);\n\n menu.startState({\n run: () => {\n menu.session.get('key', err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('get error');\n done();\n });\n }\n });\n menu.run(args);\n });\n\n\n it('should catch error in promise in session.get when get handler passes error to callback', function (done) {\n let config = {\n start: (id, cb) => {\n cb();\n },\n get: (id, key, cb) => {\n cb(new Error('get error'));\n },\n };\n menu.sessionConfig(config);\n\n menu.startState({\n run: () => {\n menu.session.get('key')\n .catch(err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('get error');\n done();\n });\n }\n });\n menu.run(args);\n });\n\n\n it('should pass error in callback to session.get when get handler rejects error in promise', function (done) {\n let config = {\n start: (id, cb) => {\n cb();\n },\n get: () => {\n return new Promise((resolve, reject) => {\n reject(new Error('get error'));\n });\n },\n };\n menu.sessionConfig(config);\n\n menu.startState({\n run: () => {\n menu.session.get('key', err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('get error');\n done();\n });\n }\n });\n menu.run(args);\n });\n\n\n it('should catch error in promise in session.get when get handler passes error to callback', function (done) {\n let config = {\n start: (id, cb) => {\n cb();\n },\n get: () => {\n return new Promise((resolve, reject) => {\n reject(new Error('get error'));\n });\n },\n };\n menu.sessionConfig(config);\n\n menu.startState({\n run: () => {\n menu.session.get('key')\n .catch(err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('get error');\n done();\n });\n }\n });\n menu.run(args);\n });\n\n // SESSION END HANDLER\n\n\n it('should emit error when session end handler returns error in callback', function (done) {\n let config = {\n start: (id, cb) => {\n cb();\n },\n end: (id, cb) => {\n cb(new Error('end error'));\n }\n };\n\n menu.on('error', err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('end error');\n done();\n });\n menu.sessionConfig(config);\n menu.startState({\n run: () => {\n menu.end();\n }\n });\n menu.run(args);\n\n });\n\n it('should emit error when session end handler returns error in promise', function (done) {\n let config = {\n start: (id, cb) => {\n cb();\n },\n end: () => {\n return new Promise((resolve, reject) => {\n return reject(new Error('end error'));\n });\n }\n };\n\n menu.on('error', err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('end error');\n done();\n });\n menu.sessionConfig(config);\n menu.startState({\n run: () => {\n menu.end();\n }\n });\n menu.run(args);\n\n });\n\n\n it('should emit error when session end handler throws error in promise', function (done) {\n let config = {\n start: (id, cb) => {\n cb();\n },\n end: () => {\n return new Promise(() => {\n throw new Error('end error');\n });\n }\n };\n\n menu.on('error', err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('end error');\n done();\n });\n menu.sessionConfig(config);\n menu.startState({\n run: () => {\n menu.end();\n }\n });\n menu.run(args);\n\n });\n\n\n });\n\n });\n\n describe('Hubtel Support', function () {\n let menu;\n let session = {};\n let args;\n\n let config = {\n start: (id) => {\n return new Promise((resolve, reject) => {\n if (!(id in session)) session[id] = {};\n return resolve();\n });\n },\n end: (id) => {\n return new Promise((resolve, reject) => {\n delete session[id];\n return resolve();\n });\n },\n get: (id, key) => {\n return new Promise((resolve, reject) => {\n let val = session[id][key];\n return resolve(val);\n });\n },\n set: (id, key, val) => {\n return new Promise((resolve, reject) => {\n session[id][key] = val;\n return resolve();\n });\n }\n };\n\n beforeEach(function () {\n menu = new UssdMenu({ provider: 'hubtel' });\n session = {};\n args = {\n Mobile: '233208183783',\n SessionId: 'bd7bc392496b4b28af2033ba83f5e400',\n ServiceCode: '713*4',\n Type: 'Response',\n Message: '',\n Operator: 'MTN',\n Sequence: 2\n };\n });\n\n it('should emit error when invalid provider in menu config', function (done) {\n try {\n menu = new UssdMenu({ provider: 'otherTelco' });\n } catch (err) {\n expect(err).to.be.an('error');\n done();\n }\n });\n\n it('should emit error when session config not set up', function (done) {\n menu = new UssdMenu({ provider: 'hubtel' });\n menu.startState({\n run: () => {\n menu.con('Next');\n }\n });\n menu.on('error', err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('Session config required for Hubtel provider');\n done();\n });\n menu.run(args);\n });\n\n it('should emit error if unable to map route', function (done) {\n menu = new UssdMenu({ provider: 'hubtel' });\n args.Message = '1';\n args.Type = 'Initiation';\n\n let config = {\n start: (id, cb) => {\n cb();\n },\n get: (id, key) => {\n return new Promise((resolve, reject) => {\n let val = session[id][key];\n return resolve(val);\n });\n },\n set: (id, key, val) => {\n return new Promise((resolve, reject) => {\n if (key === 'route') {\n return reject('Cannot set route key');\n } else {\n session[id][key] = val;\n return resolve();\n }\n });\n },\n end: () => {\n return new Promise((resolve, reject) => {\n return reject(new Error('end error'));\n });\n }\n };\n\n menu.sessionConfig(config);\n menu.startState({\n run: () => {\n menu.con('Next');\n },\n next: {\n '1': 'state1'\n }\n });\n menu.on('error', err => {\n expect(err).to.be.an('error');\n expect(err.message).to.equal('Cannot set route key');\n done();\n });\n\n menu.run(args);\n\n });\n\n it('should map incoming hubtel request to menu.args', function (done) {\n menu.sessionConfig(config);\n\n args.Message = '1';\n menu.startState({\n next: {\n '1': 'state1'\n }\n });\n menu.state('state1', {\n run: function (state) {\n expect(state.menu.args.phoneNumber).to.equal(`+${args.Mobile}`);\n expect(state.menu.args.sessionId).to.equal(args.SessionId);\n expect(state.menu.args.serviceCode).to.equal(args.ServiceCode);\n expect(state.menu.args.text).to.equal(args.Message);\n expect(state.val).to.equal(args.Message);\n expect(menu.val).to.equal(args.Message);\n done();\n }\n });\n\n menu.run(args);\n });\n it('should override message from Initiation call with empty string if no extra params', function(done) {\n menu.sessionConfig(config);\n const initArgs = Object.assign(args, {\n Sequence: 1,\n Message: '*713*4#',\n Type: 'Initiation',\n });\n\n menu.startState({\n run: function (state) {\n expect(menu.val).to.equal('');\n expect(state.menu.args.text).to.equal('');\n done();\n }\n });\n\n menu.run(initArgs);\n });\n\n it('should map Message from Initiation call to a route if extra params', function(done) {\n menu.sessionConfig(config);\n const initArgs = Object.assign(args, {\n Sequence: 1,\n Message: '*713*4*3*5#',\n Type: 'Initiation',\n });\n\n menu.startState({\n run: function(state){\n // Should not reach this function\n expect(10).to.equal(20);\n },\n next: {\n '3': 'state1'\n }\n });\n menu.state('state1', {\n run: function(state){\n // Should not reach this function\n expect(15).to.equal(5);\n },\n next: {\n '5': 'state2'\n }\n });\n\n menu.state('state2', {\n run: function(state){\n expect(state.menu.args.phoneNumber).to.equal(`+${args.Mobile}`);\n expect(state.menu.args.sessionId).to.equal(args.SessionId);\n expect(state.menu.args.serviceCode).to.equal(args.ServiceCode);\n expect(state.menu.args.text).to.equal('3*5');\n done();\n },\n next: {\n // Should not reach here\n '*\\\\d+': 'state1'\n }\n });\n\n menu.run(initArgs);\n });\n\n it('should return Response object from menu.con', function(done) {\n menu.sessionConfig(config);\n menu.startState({\n run: () => {\n menu.con('Next');\n },\n });\n\n menu.run(args, res => {\n expect(res).to.be.an('object');\n expect(res.Message).to.equal('Next');\n expect(res.Type).to.equal('Response');\n done();\n });\n });\n\n it('should return Release object from menu.end', function (done) {\n menu.sessionConfig(config);\n menu.startState({\n run: () => {\n menu.end('End');\n },\n });\n\n menu.run(args, res => {\n expect(res).to.be.an('object');\n expect(res.Message).to.equal('End');\n expect(res.Type).to.equal('Release');\n done();\n });\n });\n\n it('should be able to map first text to route', function (done) {\n menu.sessionConfig(config);\n\n const testResponse = 'state1 response';\n\n menu.startState({\n run: () => {\n menu.con('Next');\n },\n next: {\n '1': 'state1'\n }\n });\n menu.state('state1', {\n run: () => {\n menu.con(testResponse);\n }\n });\n\n menu.run(args, () => {\n expect(session[args.SessionId].route).to.equal('');\n args.Message = '1';\n menu.run(args, res => {\n process.nextTick(() => {\n // expect session to be deleted\n expect(res.Message).to.equal(testResponse);\n expect(session[args.SessionId].route).to.equal(args.Message);\n done();\n });\n });\n });\n });\n it('should be able to map text after first sequence to route', function (done) {\n menu.sessionConfig(config);\n\n const initArgs = Object.assign({}, args, {\n Sequence: 1,\n Message: '*713*4#',\n Type: 'Initiation',\n });\n const firstResponseArgs = Object.assign({}, args, {\n Sequence: 2,\n Message: '1',\n });\n const secondResponseArgs = Object.assign({}, args, {\n Sequence: 3,\n Message: '3',\n });\n\n const testResponse = 'state1 response';\n const test2Response = 'state2 response';\n\n menu.startState({\n run: () => {\n menu.con('Next');\n },\n next: {\n '1': 'state1'\n }\n });\n menu.state('state1', {\n run: () => {\n menu.con(testResponse);\n },\n next: {\n '3': 'state2'\n }\n });\n\n menu.state('state2', {\n run: () => {\n menu.end(test2Response);\n }\n });\n\n menu.run(initArgs, initResponse => {\n expect(session[args.SessionId].route).to.equal('');\n expect(initResponse.Message).to.equal('Next');\n expect(initResponse.Type).to.equal('Response');\n menu.run(firstResponseArgs, res => {\n // expect session to be deleted\n expect(res.Message).to.equal(testResponse);\n expect(res.Type).to.equal('Response');\n menu.run(secondResponseArgs, res2 => {\n expect(res2.Message).to.equal(test2Response);\n expect(res2.Type).to.equal('Release');\n expect(session[args.SessionId].route).to.equal('1*3');\n done();\n });\n });\n });\n });\n\n });\n describe(\"Menu Run Returns Promise\", function () {\n it('menu.run should return a resolvable promise', function (done) {\n let message = 'It works!';\n menu.startState({\n run: function () {\n menu.end(message);\n }\n });\n menu.run(args).then(function (res) {\n expect(res).to.equal('END ' + message);\n done();\n });\n });\n\n });\n\n});"
}
]