From 21f5cbab494a08b7a583d3bd736ccd36a42b1d5d Mon Sep 17 00:00:00 2001 From: Lawrence Ephrim Date: Mon, 22 Apr 2024 18:17:42 +0000 Subject: [PATCH] docs: add readme --- README.md | 175 ++++++++++++++++++++ src/gateways/emergent_technology.gateway.ts | 1 + thesis.code-workspace | 3 - todos.todo | 28 ++-- 4 files changed, 192 insertions(+), 15 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..9af6374 --- /dev/null +++ b/README.md @@ -0,0 +1,175 @@ +# Ananse USSD Framework + +[Ananse](https://www.npmjs.com/package/ananse/) is a lightweight NodeJs/Typescript framework with batteries included for building efficient, scalable and maintainable USSD applications. It provides intuitive and flexible APIs for building USSD menus. + +Ananse has built-in support for session state management, menu routing, input validation, pagination and command line simulator. + +## Features + +- Intuitive menu routing +- Supports any USSD gateway (Wigal, Hubtel, AfricasTalking, etc) +- Session state management +- Session storage +- Input validation +- Pagination +- Command line simulator +- E2E Testing with Japa + +## Installation + +Use your favour nodejs package manager to install [anase](https://www.npmjs.com/package/ananse/). + +```bash +npm install ananse +``` + +## Base Usage + +Ananse comes with a built-in HTTP server suitable for a new project. An ExpressJs wrapper is also available for use in existing projects. + +### Configuration + +The `configure` exposes several options to configure the framework - the ussd gateway, session storage and pagination options. + +```typescript + +import { Ananse } from "ananse"; + +const ananse = new Ananse().configure({ + gateway: "wigal", // USSD gateway to use, eg. hubtel, africas_talking. + session: { type: "redis" }, // Database to store session data. Eg. mysql, postgres and redis +}); + +export default ananse; +``` + +### Define the Menus + +There are two ways to define menus Ananse - **functional** and **class based** menus. While both offers the same API features, **class based** menus are recommended for complex applications. + +Each menu must have a unique name/id, this is similar to route path in expressJS. Ananse uses the id in navigating the user between menus in the application. It is recommended to define menu ids in enum for easy debugging. + +Functional menus are automatically discovered by the framework. However, class menus must be added manually. + +```typescript +// +// Functional style menu definition +// +MenuRouter + .menu(MenuType.account_type) + .start() + .message("Choose account type") + .actions([ + { + choice: "1", + display: "1. Customer", + next_menu: async (req: Request, _res: Response) => { + return MenuType.account_login + }, + }, + { + choice: "2", + display: "2. Sales Executive", + next_menu: MenuType.sales_executive, + }, + ]); +``` + +After defining a class based menu, it must be added to the list of menu routes using the `MenuRouter.add([menu-class], [menu-id])`. + +```typescript +// +// Class based menus +// +import { BaseMenu, MenuAction, Request, Response } from "ananse"; +import { MenuType } from "../../enums"; + +export class AmountTypeMenu extends BaseMenu { + async nextMenu() { + return MenuType.account_type; + } + + async message() { + return "Choose account type"; + } + + async actions(): Promise { + return [ + { + choice: "1", + display: "1. Customer", + next_menu: async (req: Request, _res: Response) => { + return MenuType.account_login + }, + }, + { + choice: "2", + display: "2. Sales Executive", + next_menu: MenuType.sales_executive, + }, + ]; + } +} + +// Add the menu to the list of ananse routes +MenuRouter.add(AmountTypeMenu, MenuType.account_type); +``` + +### Star the Server + +Ananse can be added to an existing express application by simply mount a new route for it. + +```typescript + +import ananse from "./ussd"; + +const app = express(); + +app.get('/ussd', (req, res) => { + return ananse.express(req, res); +}) +``` + +To use the built-in HTTP server, simply call the `listen` function with the port number. + +```typescript +import ananse from "./ussd"; + +ananse.listen(3000, "localhost", () => { + console.log("Ananse server listening on port 3000"); +}); +``` + +### Sample projects + +For more examples, refer to the available [sample projects](https://github.com/ephrimlawrence/ananse/blob/bee6f84743bc6c9b3859cee38de487eba922e575/tests/sample-apps). + +## Contributing + +Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. + +Please make sure to update tests as appropriate. + +## License + +[MIT](https://choosealicense.com/licenses/mit/) + +## TODOs + +### Documentation + +- Core components + - validation + - forms + - menus + - forms + - pagination + - simulator + - japa e2e testing + - design philosophy + +### Pending Features + +- Simplify navigation to use stack data structure +- GUI menu builder +- Vscode extension diff --git a/src/gateways/emergent_technology.gateway.ts b/src/gateways/emergent_technology.gateway.ts index f0f591c..52b052e 100644 --- a/src/gateways/emergent_technology.gateway.ts +++ b/src/gateways/emergent_technology.gateway.ts @@ -29,6 +29,7 @@ export class EmergentTechnologyGateway extends Gateway { _state.userData = body.Message; this.request.state = _state; + this.request.msisdn = _state.msisdn // The content of Message for session initiation is always the service short code value // We don't really need it given that is start of a session diff --git a/thesis.code-workspace b/thesis.code-workspace index bdb1fac..bcf1210 100644 --- a/thesis.code-workspace +++ b/thesis.code-workspace @@ -2,9 +2,6 @@ "folders": [ { "path": "." - }, - { - "path": "../direct-debit-ussd" } ], "settings": { diff --git a/todos.todo b/todos.todo index 0eb220f..dc3b317 100644 --- a/todos.todo +++ b/todos.todo @@ -1,13 +1,17 @@ Pending features: - ✔ rewrite cli simulator to support all provider modes @done(23-12-02 15:23) - ✔ redis session management @done(23-12-02 17:44) - ☐ add 'end' to dyanmic menu actions - ☐ add 'end' to action menu class - ☐ add session management to dynamic menu - ☐ session management - ☐ set - ☐ get - ☐ update - ☐ remove - ☐ State/session hydration to disk - ☐ reload hydated state on request + ☐ implement on demand termination from anywhere in the code + ☐ add 'socket' params to redis config + +Archive: + ✔ rewrite cli simulator to support all provider modes @done(23-12-02 15:23) @project(Pending features) + ✔ redis session management @done(23-12-02 17:44) @project(Pending features) + ✔ add 'end' to dyanmic menu actions @done(24-03-19 07:25) @project(Pending features) + ✔ add 'end' to action menu class @done(24-03-19 07:25) @project(Pending features) + ✔ add session management to dynamic menu @done(24-03-19 07:25) @project(Pending features) + ✔ session management @done(24-03-19 07:25) @project(Pending features) + ✔ set @done(24-03-19 07:25) @project(Pending features) + ✔ get @done(24-03-19 07:25) @project(Pending features) + ✔ update @done(24-03-19 07:25) @project(Pending features) + ✔ remove @done(24-03-19 07:25) @project(Pending features) + ✔ State/session hydration to disk @done(24-03-19 07:25) @project(Pending features) + ✔ reload hydated state on request @done(24-03-19 07:25) @project(Pending features)