@koloseum/utils 0.2.28 → 0.3.0

package/dist/platform.js

@@ -0,0 +1,764 @@
+import { Transform } from "./formatting.js";
+import { v4 as uuidv4 } from "uuid";
+import validator from "validator";
+/* HELPERS */
+const { trim, escape } = validator;
+const { KenyaAdministrativeDivisions } = (await import("kenya-administrative-divisions")).default;
+/* CONFIG HELPERS */
+export const Config = {
+    /**
+     * A reference of microservices available on the platform, represented as an object with each user group (i.e. `public`, `players`, `lounges`, and `backroom`) having its own array of microservices. Each microservice in a list is an object with the following properties:
+     * - `name`: The name of the microservice.
+     * - `description`: A description of the microservice.
+     * - `slug`: The slug of the microservice.
+     * - `features`: An array of features that the microservice has.
+     * - `roles`: An array of roles attached to the microservice.
+     */
+    microservices: {
+        backroom: [
+            {
+                name: "Compliance",
+                description: "Management of compliance and regulatory adherence for Players and Lounges.",
+                slug: "compliance",
+                features: [
+                    {
+                        name: "Players",
+                        description: "Search, review, and manage Player data.",
+                        slug: "players",
+                        tabs: [
+                            {
+                                name: "Profile",
+                                description: "Review basic Player data.",
+                                root: true
+                            },
+                            {
+                                name: "Documents",
+                                description: "Review Player documents.",
+                                slug: "documents"
+                            },
+                            {
+                                name: "Data updates",
+                                description: "Review Player data updates.",
+                                slug: "data-updates",
+                                tabs: [
+                                    {
+                                        name: "Requests",
+                                        description: "Review Player data update requests.",
+                                        root: true
+                                    },
+                                    {
+                                        name: "History",
+                                        description: "Review Player data update history.",
+                                        slug: "history"
+                                    }
+                                ]
+                            },
+                            {
+                                name: "Credits",
+                                description: "Review Koloseum Credits data for the Player.",
+                                slug: "credits",
+                                tabs: [
+                                    {
+                                        name: "Transactions",
+                                        description: "Review Player transactions with Koloseum Credits.",
+                                        root: true
+                                    },
+                                    {
+                                        name: "Transfers",
+                                        description: "Review Player transfers with Koloseum Credits.",
+                                        slug: "transfers"
+                                    },
+                                    {
+                                        name: "Subscriptions",
+                                        description: "Review Player subscriptions with Koloseum Credits.",
+                                        slug: "subscriptions"
+                                    }
+                                ]
+                            },
+                            {
+                                name: "Misconduct",
+                                description: "Review Player reports and sanctions.",
+                                slug: "misconduct",
+                                tabs: [
+                                    {
+                                        name: "Reports",
+                                        description: "Review Player reports.",
+                                        root: true
+                                    },
+                                    {
+                                        name: "Sanctions",
+                                        description: "Review Player sanctions.",
+                                        slug: "sanctions"
+                                    }
+                                ]
+                            },
+                            {
+                                name: "Points / KXP",
+                                description: "Review Koloseum Experience Points (KXP) transactions for the Player.",
+                                slug: "points"
+                            }
+                        ]
+                    },
+                    {
+                        name: "Lounges",
+                        description: "Search, review, and manage Lounge data.",
+                        slug: "lounges",
+                        tabs: [
+                            {
+                                name: "Profile",
+                                description: "Review basic Lounge data.",
+                                root: true
+                            },
+                            {
+                                name: "Documents",
+                                description: "Review Lounge documents.",
+                                slug: "documents"
+                            },
+                            {
+                                name: "Staff",
+                                description: "Search, review, and manage Lounge staff data.",
+                                slug: "staff"
+                            },
+                            {
+                                name: "Branches",
+                                description: "Review Lounge branches.",
+                                slug: "branches",
+                                tabs: [
+                                    {
+                                        name: "Profile",
+                                        description: "Review basic Lounge branch data.",
+                                        root: true
+                                    },
+                                    {
+                                        name: "Amenities",
+                                        description: "Review Lounge branch amenities.",
+                                        slug: "amenities"
+                                    },
+                                    {
+                                        name: "Staff",
+                                        description: "Search, review, and manage Lounge branchstaff data.",
+                                        slug: "staff"
+                                    }
+                                ]
+                            },
+                            {
+                                name: "Data updates",
+                                description: "Review Lounge data updates.",
+                                slug: "data-updates",
+                                tabs: [
+                                    {
+                                        name: "Requests",
+                                        description: "Review Lounge data update requests.",
+                                        root: true
+                                    },
+                                    {
+                                        name: "History",
+                                        description: "Review Lounge data update history.",
+                                        slug: "history"
+                                    }
+                                ]
+                            },
+                            {
+                                name: "Credits",
+                                description: "Review Koloseum Credits data for the Lounge.",
+                                slug: "credits",
+                                tabs: [
+                                    {
+                                        name: "Transactions",
+                                        description: "Review Lounge transactions with Koloseum Credits.",
+                                        root: true
+                                    },
+                                    {
+                                        name: "Transfers",
+                                        description: "Review Lounge transfers with Koloseum Credits.",
+                                        slug: "transfers"
+                                    },
+                                    {
+                                        name: "Subscriptions",
+                                        description: "Review Lounge subscriptions with Koloseum Credits.",
+                                        slug: "subscriptions"
+                                    }
+                                ]
+                            },
+                            {
+                                name: "Misconduct",
+                                description: "Review Lounge reports and sanctions.",
+                                slug: "misconduct",
+                                tabs: [
+                                    {
+                                        name: "Reports",
+                                        description: "Review Lounge reports.",
+                                        root: true
+                                    },
+                                    {
+                                        name: "Sanctions",
+                                        description: "Review Lounge sanctions.",
+                                        slug: "sanctions"
+                                    }
+                                ]
+                            },
+                            {
+                                name: "Points / KXP",
+                                description: "Review Koloseum Experience Points (KXP) transactions for the Lounge.",
+                                slug: "points"
+                            }
+                        ]
+                    }
+                ],
+                roles: [
+                    {
+                        name: "Compliance",
+                        slug: "compliance",
+                        root: true
+                    },
+                    {
+                        name: "Players",
+                        slug: "players",
+                        featureSlugs: ["players"]
+                    },
+                    {
+                        name: "Lounges",
+                        slug: "lounges",
+                        featureSlugs: ["lounges"]
+                    }
+                ]
+            },
+            {
+                name: "Competitions",
+                description: "Management of competitions data and live events across Markets.",
+                slug: "competitions",
+                features: [
+                    {
+                        name: "Ma Esto",
+                        description: "Manage football esports data for Ma Esto.",
+                        slug: "fbl"
+                    },
+                    {
+                        name: "Savanna FGC",
+                        description: "Manage fighting games esports data for Savanna FGC.",
+                        slug: "fgc",
+                        tabs: [
+                            {
+                                name: "Savanna Circuit",
+                                description: "Manage competition data for the Savanna Circuit.",
+                                slug: "league",
+                                tabs: [
+                                    {
+                                        name: "Rankings",
+                                        description: "Manage rankings for any Savanna Circuit season.",
+                                        root: true
+                                    },
+                                    {
+                                        name: "Tournaments",
+                                        description: "Manage tournaments for any Savanna Circuit season.",
+                                        slug: "tournaments",
+                                        tabs: [
+                                            {
+                                                name: "Events",
+                                                description: "Manage events for any Savanna Circuit tournament.",
+                                                root: true
+                                            },
+                                            {
+                                                name: "Tickets",
+                                                description: "Manage tickets for any Savanna Circuit tournament.",
+                                                slug: "tickets"
+                                            },
+                                            {
+                                                name: "Settings",
+                                                description: "Manage settings for any Savanna Circuit tournament.",
+                                                slug: "settings"
+                                            }
+                                        ]
+                                    },
+                                    {
+                                        name: "Settings",
+                                        description: "Manage settings for any Savanna Circuit season.",
+                                        slug: "settings"
+                                    }
+                                ]
+                            },
+                            {
+                                name: "Savanna Fight Night",
+                                description: "Manage competition data for Savanna Fight Night.",
+                                slug: "challenges"
+                            }
+                        ]
+                    },
+                    {
+                        name: "Hit List",
+                        description: "Manage battle royale esports data for Hit List.",
+                        slug: "bryl"
+                    }
+                ],
+                roles: [
+                    {
+                        name: "Competitions",
+                        slug: "competitions",
+                        root: true
+                    },
+                    {
+                        name: "Ma Esto",
+                        slug: "fbl",
+                        featureSlugs: ["fbl"]
+                    },
+                    {
+                        name: "Savanna FGC",
+                        slug: "fgc",
+                        featureSlugs: ["fgc"]
+                    },
+                    {
+                        name: "Hit List",
+                        slug: "bryl",
+                        featureSlugs: ["bryl"]
+                    }
+                ]
+            },
+            {
+                name: "KLSM",
+                description: "Management of game and console trades between users.",
+                slug: "commerce",
+                features: [],
+                roles: [
+                    {
+                        name: "Commerce",
+                        slug: "commerce",
+                        root: true
+                    }
+                ]
+            },
+            {
+                name: "Staff",
+                description: "Management of Backroom staff authorisation.",
+                slug: "staff",
+                features: [
+                    {
+                        name: "Roles",
+                        description: "Review and manage Backroom roles.",
+                        slug: "roles"
+                    },
+                    {
+                        name: "Users",
+                        description: "Review and manage Backroom users.",
+                        slug: "users"
+                    }
+                ],
+                roles: [
+                    {
+                        name: "Human Resources",
+                        slug: "hr",
+                        root: true
+                    }
+                ]
+            }
+        ],
+        players: [
+            {
+                name: "Sessions",
+                description: "Track your gaming sessions at registered lounges.",
+                slug: "sessions",
+                features: [],
+                roles: null
+            },
+            {
+                name: "KLSM",
+                description: "Trade used games and consoles with other users at affordable prices.",
+                slug: "commerce",
+                features: [],
+                roles: null
+            },
+            {
+                name: "Savanna FGC",
+                description: "Check out the latest news and competitions from Savanna FGC.",
+                slug: "fgc",
+                features: [
+                    {
+                        name: "Home",
+                        description: "Learn more about the Savanna Circuit.",
+                        root: true
+                    },
+                    {
+                        name: "Rules",
+                        description: "Review the rules and regulations of the Savanna Circuit.",
+                        slug: "rules"
+                    },
+                    {
+                        name: "Tournaments",
+                        description: "Review and join upcoming tournaments on the Savanna Circuit.",
+                        slug: "tournaments"
+                    }
+                ],
+                roles: null
+            },
+            {
+                name: "Account",
+                description: "Review Player account settings and preferences.",
+                slug: "account",
+                features: [
+                    {
+                        name: "General",
+                        description: "Review and manage your general settings.",
+                        slug: "general"
+                    },
+                    {
+                        name: "Documents",
+                        description: "Review and manage your ID documents.",
+                        slug: "documents"
+                    },
+                    {
+                        name: "Personal",
+                        description: "Review and manage your personal information.",
+                        slug: "personal"
+                    },
+                    {
+                        name: "Gaming & Socials",
+                        description: "Review and manage your gaming and social media information.",
+                        slug: "gaming-socials"
+                    },
+                    {
+                        name: "Notifications",
+                        description: "Review and manage your notification preferences.",
+                        slug: "notifications"
+                    },
+                    {
+                        name: "Security",
+                        description: "Review and manage your security preferences.",
+                        slug: "security"
+                    },
+                    {
+                        name: "Lounges",
+                        description: "Review your access to Lounges microservices.",
+                        slug: "lounges"
+                    },
+                    {
+                        name: "Backroom",
+                        description: "Review your access to Backroom microservices.",
+                        slug: "backroom"
+                    }
+                ],
+                roles: null
+            }
+        ]
+    }
+};
+/* DUMMY DATA */
+export const Mock = {
+    /**
+     * A generic authenticated user.
+     * @param {string} id - The user ID; defaults to a random UUID
+     * @param {Date} date - The date and time; defaults to the current date and time
+     * @param {string} phone - The phone number; defaults to a generic Kenyan phone number
+     * @param {string} identityId - A default identity ID; defaults to a random UUID
+     * @returns A generic authenticated user.
+     */
+    authenticatedUser: (id = uuidv4(), date = new Date(), phone = "254111222333", identityId = uuidv4()) => {
+        // Convert date to ISO string
+        const time = date.toISOString();
+        // User data
+        return {
+            id,
+            aud: "authenticated",
+            role: "authenticated",
+            email: "",
+            phone,
+            phone_confirmed_at: time,
+            confirmation_sent_at: time,
+            confirmed_at: time,
+            last_sign_in_at: time,
+            app_metadata: {
+                person_data: { player_id: "KP1234567", first_name: "John", last_name: "Test", pseudonym: "JDtest" },
+                provider: "phone",
+                providers: ["phone"],
+                roles: ["player", "backroom_superuser"]
+            },
+            user_metadata: {
+                email_verified: false,
+                phone_verified: false,
+                sub: id,
+                backroom: {
+                    welcome_notification_sent: true
+                },
+                players: {
+                    welcome_notification_sent: true
+                }
+            },
+            identities: [
+                {
+                    identity_id: identityId,
+                    id,
+                    user_id: id,
+                    identity_data: {
+                        email_verified: false,
+                        phone_verified: false,
+                        sub: id
+                    },
+                    provider: "phone",
+                    last_sign_in_at: time,
+                    created_at: time,
+                    updated_at: time
+                }
+            ],
+            created_at: time,
+            updated_at: time,
+            is_anonymous: false
+        };
+    }
+};
+/* RESOURCE HELPERS */
+export const Resource = {
+    /**
+     * Returns a list of all counties in Kenya.
+     * @param {"name" | "code"} sortBy - The field to sort the counties by, i.e. `name` or `code`; defaults to `name`
+     * @returns {Promise<County[]>} A list of objects with the county `name`, `code`, and a list of `subCounties`
+     */
+    getKenyaCounties: async (sortBy = "name") => {
+        // Create Kenya administrative divisions instance
+        const kenyaAdmin = new KenyaAdministrativeDivisions();
+        // Get all counties
+        const countiesData = await kenyaAdmin.getAll();
+        // Format counties
+        const counties = countiesData.map((county) => {
+            // Get list of sub-counties
+            const subCounties = [];
+            for (const subCounty of county.constituencies)
+                subCounties.push(subCounty.constituency_name);
+            subCounties.sort();
+            // Format county name and add to list
+            const countyName = county.county_name.split(" ");
+            let name = county.county_name;
+            if (countyName.length > 1)
+                name = countyName.map((word) => Transform.capitalise(word)).join(" ");
+            // Return county
+            return { name, code: county.county_code, subCounties };
+        });
+        // Return sorted counties
+        return counties.sort((a, b) => (sortBy === "name" ? a.name.localeCompare(b.name) : a.code - b.code));
+    },
+    /**
+     * Returns the parent URL for a given base URL.
+     * @param {string} base - The base URL
+     * @returns {string} The parent URL
+     */
+    getParentUrl: (base) => {
+        // Validate input
+        if (typeof base !== "string")
+            return "";
+        // Return parent URL
+        return base.replace(/\/$/, "").split("/").slice(0, -1).join("/") || "/";
+    },
+    /**
+     * Returns the redirect URL for a given URI.
+     * @param {string} uri - The URI to get the redirect URL for, i.e. `microserviceGroup:path` (e.g. `players:fgc/tournaments`)
+     * @param {"development" | "production"} env - The environment to use for the redirect URL; defaults to `production`
+     * @returns {string} An object with the redirect `url`, or an `error` if any occurs
+     */
+    getRedirectUrl: (uri, env = "production") => {
+        // Get microservice groups
+        const microserviceGroups = ["public", "players", "lounges", "backroom"];
+        // Extract microservice group and path from URI
+        let [microserviceGroup, path] = uri.split(":");
+        if (!microserviceGroup || !path)
+            return { error: { code: 400, message: "URI is invalid." } };
+        if (!microserviceGroups.includes(microserviceGroup))
+            return { error: { code: 400, message: "Microservice group is invalid." } };
+        // Initialise port number for local development
+        let port;
+        // Return redirect URL for Public microservices
+        if (microserviceGroup === "public") {
+            // Initialise subdomain for production
+            let subdomain = "";
+            // Handle Authentication microservice
+            if (path.startsWith("auth")) {
+                subdomain = "auth.";
+                port = 5173;
+                path = path.replace("auth", "");
+            }
+            // Handle Legal microservice
+            else if (path.startsWith("legal")) {
+                subdomain = "legal.";
+                port = 5174;
+                path = path.replace("legal", "");
+            }
+            // Handle Landing microservice
+            else if (path.startsWith("landing")) {
+                port = 5184;
+                path = path.replace("landing", "");
+            }
+            // Return redirect URL
+            return {
+                url: env === "production"
+                    ? `https://${subdomain}koloseum.ke${path || ""}`
+                    : `http://127.0.0.1:${port}${path || ""}`
+            };
+        }
+        // Handle Players microservices
+        if (microserviceGroup === "players") {
+            if (path.startsWith("account")) {
+                port = 5175;
+                if (env === "development")
+                    path = path.replace("account", "");
+            }
+            if (path.startsWith("fgc")) {
+                port = 5178;
+                if (env === "development")
+                    path = path.replace("fgc", "");
+            }
+            if (path.startsWith("commerce")) {
+                port = 5179;
+                if (env === "development")
+                    path = path.replace("commerce", "");
+            }
+        }
+        // Handle Lounges microservices
+        if (microserviceGroup === "lounges") {
+            if (path.startsWith("branches")) {
+                port = 5181;
+                if (env === "development")
+                    path = path.replace("branches", "");
+            }
+            if (path.startsWith("staff")) {
+                port = 5182;
+                if (env === "development")
+                    path = path.replace("staff", "");
+            }
+        }
+        // Handle Backroom microservices
+        if (microserviceGroup === "backroom") {
+            if (path.startsWith("compliance")) {
+                port = 5176;
+                if (env === "development")
+                    path = path.replace("compliance", "");
+            }
+            if (path.startsWith("competitions")) {
+                port = 5177;
+                if (env === "development")
+                    path = path.replace("competitions", "");
+            }
+            if (path.startsWith("commerce")) {
+                port = 5180;
+                if (env === "development")
+                    path = path.replace("commerce", "");
+            }
+            if (path.startsWith("staff")) {
+                port = 5183;
+                if (env === "development")
+                    path = path.replace("staff", "");
+            }
+        }
+        // Return redirect URL
+        return {
+            url: env === "production"
+                ? `https://${microserviceGroup}.koloseum.ke/${path || ""}`
+                : `http://127.0.0.1:${port}${path || ""}`
+        };
+    },
+    /**
+     * Parses a resource request and returns the URL and path.
+     * @param request - The request to parse.
+     * @returns An object with the `url` and `path` of the request.
+     */
+    parseResourceRequest: (request) => {
+        // Get the request URL and path
+        const url = new URL(request.url);
+        const path = url.pathname.split("/").pop();
+        // Return the request URL and path
+        return { url, path };
+    },
+    /**
+     * Validates address data submitted in a form and returns the validated data.
+     * @param {FormData} formData - The submitted form data
+     * @returns An object with the validated `address`, or an `error` if any has occurred
+     */
+    validateAddress: async (formData) => {
+        // Create Kenya administrative divisions instance
+        const kenyaAdmin = new KenyaAdministrativeDivisions();
+        // Building name
+        let buildingName = formData.get("building-name");
+        if (!buildingName)
+            return { error: { code: 400, message: "Building name is required." } };
+        buildingName = Transform.sanitiseHtml(trim(escape(buildingName)));
+        // Unit number
+        let unitNumber = formData.get("unit-number") || undefined;
+        if (unitNumber) {
+            unitNumber = Transform.sanitiseHtml(trim(escape(unitNumber)));
+            if (unitNumber === "")
+                unitNumber = undefined;
+        }
+        // Street name
+        let streetName = formData.get("street-name");
+        if (!streetName)
+            return { error: { code: 400, message: "Street name is required." } };
+        streetName = Transform.sanitiseHtml(trim(escape(streetName)));
+        // P.O. box and postal code
+        let boxNumber = formData.get("box-number") || undefined;
+        let postalCode = formData.get("postal-code") || undefined;
+        if (boxNumber) {
+            boxNumber = Transform.sanitiseHtml(trim(escape(boxNumber)));
+            if (boxNumber === "")
+                boxNumber = undefined;
+            if (boxNumber && !postalCode)
+                return { error: { code: 400, message: "Postal code is required." } };
+        }
+        if (postalCode) {
+            postalCode = Transform.sanitiseHtml(trim(escape(postalCode)));
+            if (postalCode === "")
+                postalCode = undefined;
+            if (postalCode && !boxNumber)
+                return { error: { code: 400, message: "P.O. box is required." } };
+        }
+        // Town
+        let town = formData.get("town");
+        if (!town)
+            return { error: { code: 400, message: "City/town is required." } };
+        town = Transform.sanitiseHtml(trim(escape(town)));
+        // County
+        let county = undefined;
+        const countyCode = Number(formData.get("county-code"));
+        if (isNaN(countyCode))
+            return { error: { code: 400, message: "County is invalid." } };
+        if (!countyCode)
+            return { error: { code: 400, message: "County is required." } };
+        const counties = await kenyaAdmin.getAll();
+        if (!counties || counties.length === 0)
+            return { error: { code: 400, message: "County is invalid." } };
+        const countyData = counties.find(({ county_code }) => county_code === countyCode);
+        if (!countyData)
+            return { error: { code: 400, message: "County is invalid." } };
+        const { county_name, constituencies } = countyData;
+        county = county_name;
+        // Sub-county
+        let subCounty = formData.get("sub-county") || undefined;
+        if (subCounty) {
+            subCounty = Transform.sanitiseHtml(trim(escape(subCounty)));
+            if (subCounty === "")
+                subCounty = undefined;
+            else {
+                // Check if constituencies exists and is an array before mapping
+                if (!constituencies || !Array.isArray(constituencies))
+                    return { error: { code: 400, message: "Sub-county data is unavailable." } };
+                // Get list of sub-counties
+                const subCounties = constituencies.map(({ constituency_name: name }) => name);
+                if (!subCounties.includes(subCounty))
+                    return { error: { code: 400, message: "Sub-county is invalid." } };
+            }
+        }
+        // Additional information
+        let additionalInfo = formData.get("address-additional-info") || undefined;
+        if (additionalInfo) {
+            additionalInfo = Transform.sanitiseHtml(trim(escape(additionalInfo)));
+            if (additionalInfo === "")
+                additionalInfo = undefined;
+        }
+        // Create address object
+        const address = {
+            buildingName,
+            unitNumber,
+            streetName,
+            town,
+            subCounty,
+            county,
+            additionalInfo
+        };
+        // Return data
+        return { address };
+    }
+};