@gatekeeper-technology/utils

Gatekeeper's generic utilities package, designed to provide reusable utility functions for various common operations. This package is shared via NPM and can be used across multiple projects.

Features

• Date and Time Utilities: Functions for handling and formatting dates and times.
• General Utilities: Common utility functions such as sorting arrays, formatting text, and more.
• Session Utilities: Functions for handling user sessions.

Installation

Install the package via Yarn:

yarn add @gatekeeper-technology/utils

Usage

General Utils:

Import the utilities you need:

import { getDisplayValue, formatText, sortArrayByField } from "@gatekeeper-technology/utils";

// Example usage
const formattedText = formatText("   This is a Text   ");
console.log(formattedText); // Output: "this_is_a_text"

Session Utils:

import { clearUserSessions, clearOtherActiveSessions, getActiveSessions, getUserInfo, USER_SESSIONS } from "@gatekeeper-technology/utils";

const user: DB.user = await DB.user.first(params.user_id);
const TOKEN = this.backend.token;
const URL = this.backend.url

// Get session details of a user from the JourneyApps backend
const user_info = await getUserInfo(user, TOKEN, URL) as USER_SESSIONS;

// Get an array of all the active sessions for a user
const sessions = await getActiveSessions(user, TOKEN, URL);

// Unenroll all sessions for a user
await clearUserSessions(user_info, TOKEN, URL);

// Unenroll all sessions not linked to the provided 'device_id'
await clearOtherActiveSessions(user_info, TOKEN, URL, device_id);

Practical Session Example

Template Object model:

<model name="user_session_details" label="User Session Details">
    <field name="status" label="Status" type="single-choice" >
        <option key="locked">LOCKED</option>
        <option key="enrolled">ENROLLED</option>
        <option key="reset">RESET</option>
        <option key="never_enrolled">NEVER_ENROLLED</option>
    </field>
    <field name="device_identifier" label="Device ID" type="text" />
    <field name="session_identifier" label="Session ID" type="text" />
    <field name="device_type" label="Device Type/Model" type="text" />
    <field name="device_platform" label="Devicie Platform" type="text" />
    <field name="last_active" label="Last Active" type="datetime" />
    <field name="error_message" label="Error Message" type="text" />
    
    <belongs-to model="user" />
    <display></display>
</model>

XML View:

<object-table query="user_session_details" label="User Session Details" empty-message="Your items will appear here">
    <column heading="Device Type">{device_type}</column>
    <column heading="Device Platform">{device_platform}</column>
    <column heading="Last Active">{getLastActive($object)}</column>
    <column heading="Status">{status}</column>
</object-table>

Call the CC function to fetch session details and bind the results to the object-table query:

async function getUserSessionDetails() {
    const params = {
        user_id: view.current_user.id,
        device_id: journey.device.id
    }
    
    await CloudCode.callTask('fetch_user_session_details', params);
    await refresh();
}

Map the values to your object

import { TaskContext } from "@journeyapps/cloudcode";
import { getActiveSessions } from "@gatekeeper-technology/utils";

export async function run(this: TaskContext, params) {
    console.log(`[+] fetch_user_session_details running with params:\n${JSON.stringify(params, null, 2)}`);
    const user = await DB.user.first(params.user_id);
    const enrolled_sessions = await getActiveSessions(user,this.backend.token, this.backend.url)
    
    const _batch = new DB.Batch();
    
    const user_session_details = []
    for(const session of enrolled_sessions){
        const current_device_record = await DB.user_session_details.first('device_identifier = ?',session.device.id)
        if(session.device.id === params.device_id && !!current_device_record) continue;
        
        const session_details = DB.user_session_details.create();
        session_details.device_identifier = session.device.id;
        session_details.session_identifier = session.id;
        session_details.device_type = session.label;
        session_details.device_platform = session.container.platform;
        session_details.last_active = new Date(session.last_connected_at);
        session_details.status = session.state.toLowerCase();
        
        user_session_details.push(session_details);
        
        session_details.user_id = params.user_id;
        _batch.save(session_details);
    }
    
    await _batch.execute();
}

Utilities Overview

General Utilities

• getDisplayValue(object, field): Safely retrieves the value of a field from an object.
• getDisplayLabel(object, field): Retrieves a label for a field from an object.
• formatText(inputText, type?): Formats text by replacing spaces with underscores and converting to lowercase or uppercase.
• sortArrayByField(array, fieldName, sortDirection): Sorts an array of objects by a specified field.

Date and Time Utilities

Utilities for working with dates and times are available in the date_time_utils module.

Session Utilities

• getUserInfo(user, TOKEN, URL) as USER_SESSIONS: Fetches the full USER_SESSIONS record for a user from the backend.
• getActiveSessions(user, TOKEN, URL): Fetches the user record and returns only the active (non-RESET) sessions.
• clearUserSessions(user_info, TOKEN, URL): Wipes ALL active sessions for a user. Requires a USER_SESSIONS object — call getUserInfo first if you only have a DB user.
• clearOtherActiveSessions(user_info, TOKEN, URL, device_id): Wipes all active sessions EXCEPT the one belonging to device_id. Use this to clear other devices while keeping the current session alive. device_id is required — use clearUserSessions to wipe all sessions.

Development

Building the Project To build the project, run:

yarn build

Running Tests This project uses Jest for testing. To run the tests, execute:

yarn test

Directory Structure

• src/: Contains the source code for the utilities.
• test/: Contains unit tests for the utilities.
• coverage/: Contains code coverage reports.

License

This project is licensed under the GNU Lesser General Public License v2.1 or later. See the LICENSE file for details.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

Author

David Holtzhausen