ts-server-lib 0.0.17

package/ussd/TSUssdMenu.d.ts

@@ -0,0 +1,139 @@
+/**
+ *  USSD Menu with state
+ *
+ *  - General rules
+ *      - Routing
+ *          - ussd text in form 1*2*7
+ *          - * bring back to start menu
+ *
+ *  - Development Section
+ *      - To publish local ussd receiver to remote through ssh
+ *      # ssh -R 9093:localhost:9090 root@185.41.154.247 -N
+ *
+ */
+import { EventEmitter } from 'events';
+export declare class TSUssdState {
+    menu: TSUssdMenu;
+    name: string | null;
+    run: ((state: TSUssdState) => void) | null;
+    defaultNext: string | null;
+    val: string | null;
+    next: Record<string, unknown> | null;
+    constructor(menu: TSUssdMenu);
+}
+export declare class TSUssdMenu extends EventEmitter {
+    map: Record<string, unknown>;
+    static START_STATE: string;
+    static config: any;
+    session: any;
+    args: any;
+    states: any;
+    result: string;
+    onResult: any;
+    current: any;
+    val: string;
+    static forOwn(items: unknown[] | Record<string, unknown>, cb: (v: unknown, key?: number | string) => void): void;
+    static mapArgs(args?: Record<string, unknown>, map?: Record<string, unknown>): Record<string, unknown>;
+    static cleanRoute(route: string): string;
+    constructor(args: Record<string, unknown> | undefined, map: Record<string, unknown>);
+    /**
+     * A callback after result is set
+     */
+    callOnResult(): void;
+    /**
+     * This method send message to the client and take the session opened
+     *
+     * @param text string Message to sent
+     */
+    con(text: string): string;
+    /**
+     * This method send message to the client and close the session
+     *
+     * @param text string Message to sent
+     */
+    end(text: string): string;
+    /**
+    * This method format the message and if debug calcualte the length
+    *
+    * @param text string Message to sent
+    */
+    print(text: string): string;
+    testLinkRule(rule: string | RegExp | unknown, val: string): boolean;
+    /**
+     * Find state based on route — async/await, no external dependencies.
+     *
+     * next values may be: a string, a callback-based function (cb) => void,
+     * a function returning a string synchronously, or a function returning a Promise.
+     */
+    resolveRoute(route: string): Promise<TSUssdState | undefined>;
+    runState(state: TSUssdState): boolean | undefined;
+    go(stateName: string): void;
+    goStart(): void;
+    /**
+     * Configure custom session handler cross-compatible between callbacks and promises
+     *
+     * @example Memory configuration example with callback
+     *
+     * let sessions = {};
+     * let menu = new UssdMenu();
+     * menu.sessionConfig({
+     *   start: (sessionId, callback) {
+     *     // initialize current session if it doesn't exist this is called by menu.run()
+     *     if(!(sessionId in sessions)) sessions[sessionId] = {};
+     *     callback();
+     *   },
+     *   end: (sessionId, callback) {
+     *     // clear current session this is called by menu.end()
+     *     delete sessions[sessionId];
+     *     callback();
+     *   },
+     *   set: (sessionId, key, value, callback) {
+     *       // store key-value pair in current session
+     *       sessions[sessionId][key] = value;
+     *       callback();
+     *   },
+     *   get: (sessionId, key, callback) {
+     *       // retrieve value by key in current session
+     *       callback(null, sessions[sessionId][key]);
+     *   },
+     *   del: (sessionId, key, callback) {
+     *       delete sessions[sessionId][key];
+     *       callback();
+     *   }
+     * });
+     *
+     * @param {Object} c object with implementation for get, set, start and end methods
+     * @param {String} a attribute of args
+     */
+    sessionConfig(c: Record<string, (...args: unknown[]) => unknown>, a?: string): void;
+    /**
+     * Create a state on the ussd chain
+     *
+     * @param string name name of the state
+     * @param object options
+     * @param object options.next object mapping of route val to state names
+     * @param string options.defaultNext name of state to run when the given route from this state can't be resolved
+     * @param function options.run the method to run when this state is resolved
+     * @return TSUssdMenu the same instance of Ussd
+     */
+    state(name: string, options: {
+        next?: Record<string, unknown>;
+        defaultNext?: string;
+        run?: (state: TSUssdState) => void;
+    }): this;
+    /**
+     * Create the start state of the ussd chain
+     */
+    startState(options: {
+        next?: Record<string, unknown>;
+        defaultNext?: string;
+        run?: (state: TSUssdState) => void;
+    }): this;
+    /**
+     * Run the ussd menu
+     *
+     * @param function onResult a callback to handle on result
+     * @param TSUssdArgs options request args from the gateway api
+     */
+    run(onResult: (result: string) => void, map: Record<string, unknown>): void;
+}

package/ussd/TSUssdMenu.js

@@ -0,0 +1,364 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TSUssdMenu = exports.TSUssdState = void 0;
+/**
+ *  USSD Menu with state
+ *
+ *  - General rules
+ *      - Routing
+ *          - ussd text in form 1*2*7
+ *          - * bring back to start menu
+ *
+ *  - Development Section
+ *      - To publish local ussd receiver to remote through ssh
+ *      # ssh -R 9093:localhost:9090 root@185.41.154.247 -N
+ *
+ */
+const events_1 = require("events");
+class TSUssdState {
+    menu;
+    name;
+    run;
+    defaultNext;
+    val;
+    next = null;
+    constructor(menu) {
+        this.menu = menu;
+        this.name = null;
+        this.run = null;
+        this.defaultNext = null;
+        this.val = null;
+    }
+}
+exports.TSUssdState = TSUssdState;
+class TSUssdMenu extends events_1.EventEmitter {
+    map;
+    static START_STATE = '__start__';
+    static config = {
+        debug: true,
+        general: { separator: ')' },
+        navigation: { back: '00', main: '01' },
+        pager: {
+            default: 3, maxLength: 90, mapping: {},
+            strategies: [{ term: ' - ', enabled: true, type: 'truncate' }]
+        }
+    };
+    session;
+    args;
+    states;
+    result;
+    onResult;
+    current;
+    val;
+    static forOwn(items, cb) {
+        const obj = items;
+        for (const i in obj) {
+            if (Object.hasOwn(obj, i)) {
+                cb(obj[i], i);
+            }
+        }
+    }
+    static mapArgs(args = {}, map = {}) {
+        const results = { provider: map.provider };
+        for (const p in args) {
+            if (Object.hasOwn(args, p) && Object.hasOwn(map, p)) {
+                results[String(map[p])] = args[p];
+            }
+            else if (Object.hasOwn(args, p)) {
+                results[p] = args[p];
+            }
+        }
+        return results;
+    }
+    static cleanRoute(route) {
+        if (route && route.includes('*000')) {
+            const reset = route.substring(route.lastIndexOf('*000') + 4);
+            route = '*' + (reset === '0' ? '' : reset);
+        }
+        return route;
+    }
+    constructor(args = {}, map) {
+        super();
+        this.map = map;
+        this.session = null;
+        this.args = TSUssdMenu.mapArgs(args, map);
+        this.states = {};
+        this.result = '';
+        this.onResult = null;
+        this.val = '';
+    }
+    /**
+     * A callback after result is set
+     */
+    callOnResult() {
+        if (this.onResult) {
+            this.onResult(this.result);
+        }
+    }
+    /**
+     * This method send message to the client and take the session opened
+     *
+     * @param text string Message to sent
+     */
+    con(text) {
+        this.result = 'CON ' + this.print(text);
+        this.callOnResult();
+        return this.result;
+    }
+    /**
+     * This method send message to the client and close the session
+     *
+     * @param text string Message to sent
+     */
+    end(text) {
+        this.result = 'END ' + this.print(text);
+        this.callOnResult();
+        if (this.session) {
+            this.session.end();
+        }
+        return this.result;
+    }
+    /**
+    * This method format the message and if debug calcualte the length
+    *
+    * @param text string Message to sent
+    */
+    print(text) {
+        return TSUssdMenu.config.debug ? '[' + (this.current ? this.current.name : 'N/A') + ':' + text.length + '] ' + text : text;
+    }
+    testLinkRule(rule, val) {
+        // if rule starts with *, treat as regex
+        if (typeof rule === 'string' && rule.startsWith('*')) {
+            return new RegExp(rule.substring(1)).test(val);
+        }
+        return rule === val;
+    }
+    /**
+     * Find state based on route — async/await, no external dependencies.
+     *
+     * next values may be: a string, a callback-based function (cb) => void,
+     * a function returning a string synchronously, or a function returning a Promise.
+     */
+    async resolveRoute(route) {
+        route = TSUssdMenu.cleanRoute(route);
+        const parts = !route ? [] : route.split('*');
+        let state = this.states[TSUssdMenu.START_STATE];
+        if (!state.next || Object.keys(state.next).length === 0) {
+            return this.states[state.defaultNext];
+        }
+        if ('' in state.next) {
+            parts.unshift('');
+        }
+        while (parts.length > 0) {
+            const part = parts.shift();
+            let nextFound = false;
+            this.val = part ?? '';
+            for (const [link, next] of Object.entries(state.next)) {
+                if (!this.testLinkRule(link, part ?? ''))
+                    continue;
+                let nextPath;
+                if (typeof next === 'string') {
+                    nextPath = next;
+                }
+                else if (typeof next === 'function') {
+                    // supports: callback-based fn(cb), sync-returning fn, and promise-returning fn
+                    nextPath = await new Promise((resolve, reject) => {
+                        const result = next(resolve);
+                        if (typeof result === 'string')
+                            resolve(result);
+                        else if (result && typeof result.then === 'function')
+                            result.then(resolve).catch(reject);
+                    });
+                }
+                if (!nextPath)
+                    continue;
+                state = this.states[nextPath];
+                this.current = state;
+                if (!state)
+                    throw new Error(`[TSUssdMenu]: declared state does not exist: ${nextPath}`);
+                state.val = part ?? '';
+                nextFound = true;
+                break;
+            }
+            if (!nextFound && state.defaultNext) {
+                state = this.states[state.defaultNext];
+                this.current = state;
+                state.val = part;
+            }
+        }
+        return state;
+    }
+    runState(state) {
+        if (!state.run) {
+            return this.emit('error', new Error(`run function not defined for state: ${state.name}`));
+        }
+        state.run(state);
+    }
+    go(stateName) {
+        const state = this.states[stateName];
+        state.val = this.val;
+        this.current = state;
+        this.runState(state);
+    }
+    goStart() {
+        this.go(TSUssdMenu.START_STATE);
+    }
+    /**
+     * Configure custom session handler cross-compatible between callbacks and promises
+     *
+     * @example Memory configuration example with callback
+     *
+     * let sessions = {};
+     * let menu = new UssdMenu();
+     * menu.sessionConfig({
+     *   start: (sessionId, callback) {
+     *     // initialize current session if it doesn't exist this is called by menu.run()
+     *     if(!(sessionId in sessions)) sessions[sessionId] = {};
+     *     callback();
+     *   },
+     *   end: (sessionId, callback) {
+     *     // clear current session this is called by menu.end()
+     *     delete sessions[sessionId];
+     *     callback();
+     *   },
+     *   set: (sessionId, key, value, callback) {
+     *       // store key-value pair in current session
+     *       sessions[sessionId][key] = value;
+     *       callback();
+     *   },
+     *   get: (sessionId, key, callback) {
+     *       // retrieve value by key in current session
+     *       callback(null, sessions[sessionId][key]);
+     *   },
+     *   del: (sessionId, key, callback) {
+     *       delete sessions[sessionId][key];
+     *       callback();
+     *   }
+     * });
+     *
+     * @param {Object} c object with implementation for get, set, start and end methods
+     * @param {String} a attribute of args
+     */
+    sessionConfig(c, a = 'sessionId') {
+        // creates a callback that calls the promise resolve and reject functions as well as the provided callback
+        const makeCb = (resolve, reject, cb) => (err, res) => {
+            if (err) {
+                if (cb) {
+                    cb(err);
+                }
+                reject(err);
+                this.emit('error', err);
+            }
+            else {
+                if (cb) {
+                    cb(null, res);
+                }
+                resolve(res);
+            }
+        };
+        // if p is a promise, handle its resolve and reject chains and invoke the provided callback
+        const resolveIfPromise = (p, resolve, reject, cb) => {
+            if (p && typeof p.then === 'function') {
+                p.then((res) => {
+                    if (cb) {
+                        cb(null, res);
+                    }
+                    resolve(res);
+                }).catch((err) => {
+                    if (cb) {
+                        cb(err);
+                    }
+                    reject(err);
+                    this.emit('error', err);
+                });
+            }
+        };
+        // implement session methods based on user-defined handlers
+        this.session = {
+            start: async (cb) => new Promise((resolve, reject) => {
+                const res = c.start(this.args[a], makeCb(resolve, reject, cb));
+                resolveIfPromise(res, resolve, reject, cb);
+            }),
+            get: async (key, cb) => new Promise((resolve, reject) => {
+                const res = c.get(this.args[a], key, makeCb(resolve, reject, cb));
+                resolveIfPromise(res, resolve, reject, cb);
+            }),
+            del: async (key, cb) => new Promise((resolve, reject) => {
+                const res = c.del(this.args[a], key, makeCb(resolve, reject, cb));
+                resolveIfPromise(res, resolve, reject, cb);
+            }),
+            set: async (key, val, cb) => new Promise((resolve, reject) => {
+                const res = c.set(this.args[a], key, val, makeCb(resolve, reject, cb));
+                resolveIfPromise(res, resolve, reject, cb);
+            }),
+            end: async (cb) => new Promise((resolve, reject) => {
+                const res = c.end(this.args[a], makeCb(resolve, reject, cb));
+                resolveIfPromise(res, resolve, reject, cb);
+            })
+        };
+    }
+    /**
+     * Create a state on the ussd chain
+     *
+     * @param string name name of the state
+     * @param object options
+     * @param object options.next object mapping of route val to state names
+     * @param string options.defaultNext name of state to run when the given route from this state can't be resolved
+     * @param function options.run the method to run when this state is resolved
+     * @return TSUssdMenu the same instance of Ussd
+     */
+    state(name, options) {
+        const state = new TSUssdState(this);
+        this.states[name] = state;
+        state.name = name;
+        state.next = options.next ?? null;
+        state.run = options.run ?? null;
+        // default defaultNext to same state
+        state.defaultNext = options.defaultNext || name;
+        return this;
+    }
+    /**
+     * Create the start state of the ussd chain
+     */
+    startState(options) {
+        return this.state(TSUssdMenu.START_STATE, options);
+    }
+    /**
+     * Run the ussd menu
+     *
+     * @param function onResult a callback to handle on result
+     * @param TSUssdArgs options request args from the gateway api
+     */
+    run(onResult, map) {
+        if (map.provider !== this.args.provider) {
+            this.args = TSUssdMenu.mapArgs(this.args, map);
+        }
+        const mapAny = map;
+        const mapUnderscore = mapAny._;
+        if (mapUnderscore?.[String(this.args.phoneNumber)] && /\d/.test(String(mapUnderscore[String(this.args.phoneNumber)]))) {
+            this.args.phoneNumber = mapUnderscore[String(this.args.phoneNumber)];
+        }
+        else if (mapUnderscore) {
+            this.args._ = mapUnderscore;
+        }
+        this.onResult = onResult;
+        const run = async () => {
+            try {
+                const state = await this.resolveRoute(this.args.message);
+                this.current = state;
+                if (state)
+                    this.runState(state);
+            }
+            catch (err) {
+                this.emit('error', err);
+            }
+        };
+        if (this.session) {
+            void this.session.start().then(run);
+        }
+        else {
+            void run();
+        }
+    }
+}
+exports.TSUssdMenu = TSUssdMenu;

package/ussd/TSUssdScreen.d.ts

@@ -0,0 +1,58 @@
+import { TSUssdMenu } from './TSUssdMenu';
+type PagerStrategy = {
+    term?: string;
+    type?: string;
+};
+export declare class TSUssdScreen {
+    menu: TSUssdMenu;
+    storage?: {
+        hget: (k: string, f: string) => Promise<unknown>;
+        hset: (k: string, f: string, d: unknown) => Promise<unknown>;
+    } | undefined;
+    strategies: {
+        truncate: (data: {
+            name?: string;
+        }[], c: PagerStrategy & {
+            term: string;
+        }, factor: number) => {
+            name?: string;
+        }[];
+    };
+    static nav(command: number | string): unknown;
+    static pagerChoice(max?: number, min?: number): string;
+    constructor(menu: TSUssdMenu, storage?: {
+        hget: (k: string, f: string) => Promise<unknown>;
+        hset: (k: string, f: string, d: unknown) => Promise<unknown>;
+    } | undefined);
+    render(items: unknown[]): void;
+    bind(m: number | string, s: unknown): void;
+    screen(title: number | string, items: Record<string, unknown>): any;
+    list(items: unknown[], title?: string, key?: string, meta?: Record<string, boolean>): string;
+    getAndSet(key: string, field: string): Promise<Record<string, unknown> | null>;
+    pager(items: {
+        name?: string;
+        length?: number;
+    }[] | undefined, key: string, pagerSize: number): Promise<{
+        meta: {
+            command: number;
+            total: number;
+            length: number;
+            offset: number;
+            limit: number;
+        };
+        data: unknown[];
+    }>;
+    _pager(items: unknown[] | undefined, key: string, pagerSize: number): Promise<{
+        meta: {
+            command: number;
+            total: number;
+            length: number;
+            offset: number;
+            limit: number;
+        };
+        data: unknown[];
+    }>;
+    pagerPickAndSet(dataSet: unknown[] | undefined, field: string, size?: number): Promise<any>;
+    checkPick(entity: unknown, state?: string): boolean;
+}
+export {};