@koloseum/utils 0.1.3 → 0.1.4

package/dist/utils.d.ts

@@ -0,0 +1,139 @@
+import type { Database } from "@koloseum/types/database";
+import type { CustomError, SocialMediaPlatform } from "@koloseum/types/public/auth";
+import type { PostgrestError, SupabaseClient } from "@supabase/supabase-js";
+import type { MobilePhoneLocale } from "validator";
+export declare const Status: {
+    /**
+     * A generic error message.
+     */
+    ERROR: string;
+    /**
+     * A generic loading message.
+     */
+    LOADING: string;
+    /**
+     * A generic password reset request message.
+     */
+    PASSWORD_RESET_REQUESTED: string;
+};
+export declare const Utility: {
+    /**
+     * Calls an Edge function.
+     * @param {SupabaseClient} supabase - The Supabase client
+     * @param {string} path - The path to the Edge function
+     * @param {"GET" | "POST"} [method="GET"] - The HTTP method to use
+     * @returns The response from the Edge function
+     */
+    callEdgeFunction: (supabase: SupabaseClient<Database>, path: string, method?: "GET" | "POST") => Promise<{
+        data?: any;
+        error?: string;
+    }>;
+    /**
+     * Capitalises a given word.
+     * @param {string} word - The word to be capitalised
+     * @returns The capitalised word
+     */
+    capitalise: (word: string) => string;
+    /**
+     * Returns a custom error object.
+     * @param {number} code - The error code; defaults to `500` if not provided or invalid
+     * @param {string} message - The error message
+     * @returns An object with the error `code` and `message`
+     */
+    customError: (code: number | undefined, message: string) => CustomError;
+    /**
+     * A regular expression for E.164 phone numbers.
+     *
+     * - Source: https://www.twilio.com/docs/glossary/what-e164
+     */
+    e164Regex: RegExp;
+    /**
+     * Formats a date in the format DD/MM/YYYY (by default) or YYYY-MM-DD (for client).
+     * @param {string} date - Date to be formatted
+     * @param {boolean} forClient - Specify whether the data is for displaying on the client; defaults to `false`
+     * @returns The formatted date string, or `null` if invalid input or in case of an error
+     */
+    formatDate: (date: string, forClient?: boolean) => string | null;
+    /**
+     * Formats a social media platform for display.
+     * @param {SocialMediaPlatform} platform - The social media platform to be formatted
+     * @returns The formatted social media platform string
+     */
+    formatSocialMediaPlatform: (platform: SocialMediaPlatform) => string;
+    /**
+     * Returns an age in years given a birth date.
+     * @param {string} dateOfBirth - The date of birth as a string, e.g. `DD-MM-YYYY`
+     * @returns The age in years, or `NaN` if the input is invalid
+     */
+    getAge: (dateOfBirth: string) => number;
+    /**
+     * A regular expression for Koloseum Lounge Branch IDs. It covers the following rules:
+     * - 9 characters long
+     * - begins with "KLB" followed by 7 digits
+     */
+    loungeBranchIdRegex: RegExp;
+    /**
+     * A regular expression for Koloseum Lounge IDs. It covers the following rules:
+     * - 9 characters long
+     * - begins with "KL" followed by 7 digits
+     */
+    loungeIdRegex: RegExp;
+    /**
+     * The minimum birth date (from today's date) for a user who is a minor, i.e. `YYYY-MM-DD`
+     */
+    minimumMinorBirthDate: string;
+    /**
+     * Parses a `CustomError` object within a page/layout server load function and returns an error to be thrown.
+     * @param {CustomError} error - The error object
+     * @returns A new `Error` object if the error is unexpected, or a Svelte error otherwise
+     */
+    parseLoadError: (error: CustomError) => Error;
+    /**
+     * Parses a `PostgrestError` object and returns a custom error object if any has occurred.
+     * @param {PostgrestError | null} postgrestError - The `PostgrestError` object, or `null` if no error occurred
+     * @returns An object with an `error` if any has occurred
+     */
+    parsePostgrestError: (postgrestError: PostgrestError | null) => {
+        error?: CustomError;
+    };
+    /**
+     * A regular expression for user passwords to match during authentication. It covers the following rules:
+     * - at least 8 characters long
+     * - at least one digit
+     * - at least one lowercase letter
+     * - at least one uppercase letter
+     * - at least one symbol
+     */
+    passwordRegex: RegExp;
+    /**
+     * A regular expression for Koloseum Player IDs. It covers the following rules:
+     * - 9 characters long
+     * - begins with "KP" followed by 7 digits
+     */
+    playerIdRegex: RegExp;
+    /**
+     * Sanitises any potential HTML injected into user input.
+     * @param {string} input - The input to be sanitised
+     * @returns A sanitised string, or an empty string if the input is invalid
+     */
+    sanitiseHtml: (input: string) => string;
+    /**
+     * A regular expression for social media handles, without a leading slash or @ character.
+     *
+     * - Source: https://stackoverflow.com/a/74579651
+     */
+    socialMediaHandleRegex: RegExp;
+    /**
+     * Validates an E.164 phone number.
+     * @param {string} phoneNumber - The phone number to be validated
+     * @param {"any" | MobilePhoneLocale | MobilePhoneLocale[]} [locale="any"] - The locale(s) to validate the phone number against
+     * @returns `true` if the phone number is valid; `false` otherwise
+     */
+    validateE164: (phoneNumber: string, locale?: "any" | MobilePhoneLocale | MobilePhoneLocale[]) => boolean;
+    /**
+     * Validates a social media handle.
+     * @param {string} handle - The social media handle to be validated
+     * @returns `true` if the handle is valid; `false` otherwise
+     */
+    validateSocialMediaHandle: (handle: string) => boolean;
+};

package/dist/utils.js

@@ -0,0 +1,250 @@
+import { FunctionsFetchError, FunctionsHttpError, FunctionsRelayError } from "@supabase/supabase-js";
+import { error as svelteError } from "@sveltejs/kit";
+import parser from "any-date-parser";
+import sanitize from "sanitize-html";
+import validator from "validator";
+/* Helper functions */
+const { isMobilePhone, isURL } = validator;
+/* Status messages */
+export const Status = {
+    /**
+     * A generic error message.
+     */
+    ERROR: "An unexpected error occurred. Kindly try again.",
+    /**
+     * A generic loading message.
+     */
+    LOADING: "Please wait…",
+    /**
+     * A generic password reset request message.
+     */
+    PASSWORD_RESET_REQUESTED: "If the provided email address is registered, you will receive a password reset link shortly.",
+};
+/* Utility functions */
+export const Utility = {
+    /**
+     * Calls an Edge function.
+     * @param {SupabaseClient} supabase - The Supabase client
+     * @param {string} path - The path to the Edge function
+     * @param {"GET" | "POST"} [method="GET"] - The HTTP method to use
+     * @returns The response from the Edge function
+     */
+    callEdgeFunction: async (supabase, path, method = "GET") => {
+        // Fetch response
+        const { data, error } = await supabase.functions.invoke(path, { method });
+        // Return error if any
+        if (error instanceof FunctionsHttpError)
+            return { error: await error.context.json() };
+        else if (error instanceof FunctionsRelayError)
+            return { error: error.message };
+        else if (error instanceof FunctionsFetchError)
+            return { error: error.message };
+        // Return response
+        return { data };
+    },
+    /**
+     * Capitalises a given word.
+     * @param {string} word - The word to be capitalised
+     * @returns The capitalised word
+     */
+    capitalise: (word) => word.charAt(0).toUpperCase() +
+        word
+            .slice(1)
+            .split("")
+            .map((c) => c.toLowerCase())
+            .join(""),
+    /**
+     * Returns a custom error object.
+     * @param {number} code - The error code; defaults to `500` if not provided or invalid
+     * @param {string} message - The error message
+     * @returns An object with the error `code` and `message`
+     */
+    customError: (code, message) => (!code || code < 400 || code > 599 ? { code: 500, message: Status.ERROR } : { code, message }),
+    /**
+     * A regular expression for E.164 phone numbers.
+     *
+     * - Source: https://www.twilio.com/docs/glossary/what-e164
+     */
+    e164Regex: /^\+?[1-9]\d{1,14}$/,
+    /**
+     * Formats a date in the format DD/MM/YYYY (by default) or YYYY-MM-DD (for client).
+     * @param {string} date - Date to be formatted
+     * @param {boolean} forClient - Specify whether the data is for displaying on the client; defaults to `false`
+     * @returns The formatted date string, or `null` if invalid input or in case of an error
+     */
+    formatDate: (date, forClient = false) => {
+        if (date === "")
+            return null;
+        try {
+            const formattedDate = new Intl.DateTimeFormat(forClient ? "fr-CA" : "en-KE", {
+                day: "2-digit",
+                month: "2-digit",
+                year: "numeric",
+                // @ts-ignore: .fromString method exists but is not typed in `any-date-parser` package
+            }).format(parser.fromString(date));
+            return formattedDate;
+        }
+        catch (error) {
+            return null;
+        }
+    },
+    /**
+     * Formats a social media platform for display.
+     * @param {SocialMediaPlatform} platform - The social media platform to be formatted
+     * @returns The formatted social media platform string
+     */
+    formatSocialMediaPlatform: (platform) => {
+        const platforms = ["facebook", "instagram", "kick", "tiktok", "twitch", "twitter", "youtube"];
+        if (!platforms.includes(platform))
+            return "";
+        if (platform === "tiktok")
+            return "TikTok";
+        if (platform === "twitter")
+            return "X (formerly Twitter)";
+        if (platform === "youtube")
+            return "YouTube";
+        return Utility.capitalise(platform);
+    },
+    /**
+     * Returns an age in years given a birth date.
+     * @param {string} dateOfBirth - The date of birth as a string, e.g. `DD-MM-YYYY`
+     * @returns The age in years, or `NaN` if the input is invalid
+     */
+    getAge: (dateOfBirth) => {
+        if (dateOfBirth === "" || typeof dateOfBirth !== "string")
+            return NaN;
+        dateOfBirth = Utility.formatDate(dateOfBirth, true);
+        const birthDate = new Date(dateOfBirth);
+        const currentDate = new Date();
+        let age = currentDate.getFullYear() - birthDate.getFullYear();
+        const monthDiff = currentDate.getMonth() - birthDate.getMonth();
+        return monthDiff < 0 || (monthDiff === 0 && currentDate.getDate() < birthDate.getDate()) ? --age : age;
+    },
+    /**
+     * A regular expression for Koloseum Lounge Branch IDs. It covers the following rules:
+     * - 9 characters long
+     * - begins with "KLB" followed by 7 digits
+     */
+    loungeBranchIdRegex: /^KLB\d{7}$/,
+    /**
+     * A regular expression for Koloseum Lounge IDs. It covers the following rules:
+     * - 9 characters long
+     * - begins with "KL" followed by 7 digits
+     */
+    loungeIdRegex: /^KL\d{7}$/,
+    /**
+     * The minimum birth date (from today's date) for a user who is a minor, i.e. `YYYY-MM-DD`
+     */
+    minimumMinorBirthDate: (() => {
+        const today = new Date();
+        const tomorrow = new Date();
+        tomorrow.setUTCDate(today.getDate() + 1);
+        const tomorrow18YearsAgo = tomorrow.getFullYear() - 18;
+        tomorrow.setFullYear(tomorrow18YearsAgo);
+        return tomorrow.toISOString().split("T")[0];
+    })(),
+    /**
+     * Parses a `CustomError` object within a page/layout server load function and returns an error to be thrown.
+     * @param {CustomError} error - The error object
+     * @returns A new `Error` object if the error is unexpected, or a Svelte error otherwise
+     */
+    parseLoadError: (error) => (error.code === 500 ? new Error(error.message) : svelteError(error.code, { message: error.message })),
+    /**
+     * Parses a `PostgrestError` object and returns a custom error object if any has occurred.
+     * @param {PostgrestError | null} postgrestError - The `PostgrestError` object, or `null` if no error occurred
+     * @returns An object with an `error` if any has occurred
+     */
+    parsePostgrestError: (postgrestError) => {
+        // Return undefined if no error occurred
+        let error;
+        if (!postgrestError)
+            return { error };
+        // Return custom error if hint is a number between 400 and 599
+        const customErrorCode = Number(postgrestError.hint);
+        if (!isNaN(customErrorCode) && customErrorCode >= 400 && customErrorCode <= 599) {
+            error = Utility.customError(customErrorCode, postgrestError.message);
+            return { error };
+        }
+        // Map Postgrest error codes to custom error codes
+        const errorMap = [
+            { code: "08", status: 503 },
+            { code: "09", status: 500 },
+            { code: "0L", status: 403 },
+            { code: "0P", status: 403 },
+            { code: "23503", status: 409 },
+            { code: "23505", status: 409 },
+            { code: "25006", status: 405 },
+            { code: "25", status: 500 },
+            { code: "28", status: 403 },
+            { code: "2D", status: 500 },
+            { code: "38", status: 500 },
+            { code: "39", status: 500 },
+            { code: "3B", status: 500 },
+            { code: "40", status: 500 },
+            { code: "53400", status: 500 },
+            { code: "53", status: 503 },
+            { code: "54", status: 500 },
+            { code: "55", status: 500 },
+            { code: "57", status: 500 },
+            { code: "58", status: 500 },
+            { code: "F0", status: 500 },
+            { code: "HV", status: 500 },
+            { code: "P0001", status: 400 },
+            { code: "P0", status: 500 },
+            { code: "XX", status: 500 },
+            { code: "42883", status: 404 },
+            { code: "42P01", status: 404 },
+            { code: "42P17", status: 500 },
+            { code: "42501", status: 403 },
+        ];
+        // Return custom error if Postgrest error code is found
+        for (const { code, status } of errorMap)
+            if (postgrestError.code === code || postgrestError.code.startsWith(code)) {
+                error = Utility.customError(status, Status.ERROR);
+                return { error };
+            }
+        // Return generic error
+        error = Utility.customError(500, Status.ERROR);
+        return { error };
+    },
+    /**
+     * A regular expression for user passwords to match during authentication. It covers the following rules:
+     * - at least 8 characters long
+     * - at least one digit
+     * - at least one lowercase letter
+     * - at least one uppercase letter
+     * - at least one symbol
+     */
+    passwordRegex: /^(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[!@#$%^&*()-_+=|{}[\]:;'<>,.?/~]).{8,}$/,
+    /**
+     * A regular expression for Koloseum Player IDs. It covers the following rules:
+     * - 9 characters long
+     * - begins with "KP" followed by 7 digits
+     */
+    playerIdRegex: /^KP\d{7}$/,
+    /**
+     * Sanitises any potential HTML injected into user input.
+     * @param {string} input - The input to be sanitised
+     * @returns A sanitised string, or an empty string if the input is invalid
+     */
+    sanitiseHtml: (input) => (typeof input !== "string" ? "" : sanitize(input, { allowedTags: [], allowedAttributes: {} })),
+    /**
+     * A regular expression for social media handles, without a leading slash or @ character.
+     *
+     * - Source: https://stackoverflow.com/a/74579651
+     */
+    socialMediaHandleRegex: /^([A-Za-z0-9_.]{3,25})$/gm,
+    /**
+     * Validates an E.164 phone number.
+     * @param {string} phoneNumber - The phone number to be validated
+     * @param {"any" | MobilePhoneLocale | MobilePhoneLocale[]} [locale="any"] - The locale(s) to validate the phone number against
+     * @returns `true` if the phone number is valid; `false` otherwise
+     */
+    validateE164: (phoneNumber, locale = "en-KE") => isMobilePhone(phoneNumber, locale) && Boolean(phoneNumber.match(Utility.e164Regex)),
+    /**
+     * Validates a social media handle.
+     * @param {string} handle - The social media handle to be validated
+     * @returns `true` if the handle is valid; `false` otherwise
+     */
+    validateSocialMediaHandle: (handle) => !isURL(handle, { require_protocol: false }) && !handle.startsWith("@") && Boolean(handle.match(Utility.socialMediaHandleRegex)),
+};

package/package.json

@@ -1,7 +1,8 @@
 {
 	"name": "@koloseum/utils",
-	"version": "0.1.3",
+	"version": "0.1.4",
 	"author": "Koloseum Technologies Limited",
+	"type": "module",
 	"description": "Utility logic for use across Koloseum web apps (TypeScript)",
 	"keywords": [
 		"Koloseum"
@@ -14,14 +15,16 @@
 		"type": "git",
 		"url": "git+https://github.com/koloseum-technologies/npm-utils.git"
 	},
-	"main": "./src/utils.ts",
+	"main": "./dist/utils.js",
 	"exports": {
-		"./src": "./src/utils.ts"
+		"./src": "./dist/utils.js"
 	},
 	"files": [
-		"./src/**/*.ts"
+		"./src/**/*.ts",
+		"./dist/**/*"
 	],
 	"scripts": {
+		"build": "npx tsc",
 		"test": "vitest --run"
 	},
 	"dependencies": {

package/src/utils.test.ts

@@ -28,7 +28,7 @@ describe("Utility helper", () => {
 		parsePostgrestError,
 		sanitiseHtml,
 		validateE164,
-		validateSocialMediaHandle
+		validateSocialMediaHandle,
 	} = Utility;
 
 	// Test each helper
@@ -99,65 +99,65 @@ describe("Utility helper", () => {
 		expect(parsePostgrestError(null)).toEqual({ error: undefined });
 		expect(
 			parsePostgrestError({
-                code: "42501",
-                name: "insufficient_privilege",
+				code: "42501",
+				name: "insufficient_privilege",
 				message: 'Insufficient privileges: permission denied for relation "restricted_table"',
 				details: 'User does not have the necessary permissions to access the relation "restricted_table".',
-				hint: ""
+				hint: "",
 			})
 		).toEqual({ error: { code: 403, message: Status.ERROR } });
 		expect(
 			parsePostgrestError({
-                code: "42883",
-                name: "undefined_function",
+				code: "42883",
+				name: "undefined_function",
 				message: "Undefined function: function non_existent_function() does not exist",
 				details: "Function non_existent_function() does not exist.",
-				hint: "No function matches the given name and argument types. You might need to add explicit type casts."
+				hint: "No function matches the given name and argument types. You might need to add explicit type casts.",
 			})
 		).toEqual({ error: { code: 404, message: Status.ERROR } });
 		expect(
 			parsePostgrestError({
-                code: "25006",
-                name: "read_only_sql_transaction",
+				code: "25006",
+				name: "read_only_sql_transaction",
 				message: "Read only SQL transaction: cannot execute INSERT in a read-only transaction",
 				details: "Cannot execute INSERT in a read-only transaction.",
-				hint: ""
+				hint: "",
 			})
 		).toEqual({ error: { code: 405, message: Status.ERROR } });
 		expect(
 			parsePostgrestError({
-                code: "23505",
-                name: "unique_violation",
+				code: "23505",
+				name: "unique_violation",
 				message: 'Uniqueness violation: duplicate key value violates unique constraint "users_username_key"',
 				details: "Key (username)=(john_doe) already exists.",
-				hint: ""
+				hint: "",
 			})
 		).toEqual({ error: { code: 409, message: Status.ERROR } });
 		expect(
 			parsePostgrestError({
-                code: "53400",
-                name: "configuration_file_error",
+				code: "53400",
+				name: "configuration_file_error",
 				message: "invalid page header in block 0 of relation base/12345/67890",
 				details: "The page header is corrupted. This may indicate hardware or file system issues.",
-				hint: ""
+				hint: "",
 			})
 		).toEqual({ error: { code: 500, message: Status.ERROR } });
 		expect(
 			parsePostgrestError({
-                code: "08003",
-                name: "connection_does_not_exist",
+				code: "08003",
+				name: "connection_does_not_exist",
 				message: "connection does not exist",
 				details: "The connection to the database was lost or never established.",
-				hint: ""
+				hint: "",
 			})
 		).toEqual({ error: { code: 503, message: Status.ERROR } });
 		expect(
 			parsePostgrestError({
-                code: "P0001",
-                name: "raise_exception",
+				code: "P0001",
+				name: "raise_exception",
 				message: "I'm a teapot!",
 				details: "Pretty simple",
-				hint: "418"
+				hint: "418",
 			})
 		).toEqual({ error: { code: 418, message: "I'm a teapot!" } });
 	});

package/src/utils.ts

@@ -1,11 +1,9 @@
 import type { Database } from "@koloseum/types/database";
 import type { CustomError, SocialMediaPlatform } from "@koloseum/types/public/auth";
 
-import type { Page, Locator } from "@playwright/test";
 import type { PostgrestError, SupabaseClient } from "@supabase/supabase-js";
 import type { MobilePhoneLocale } from "validator";
 
-import { expect } from "@playwright/test";
 import { FunctionsFetchError, FunctionsHttpError, FunctionsRelayError } from "@supabase/supabase-js";
 import { error as svelteError } from "@sveltejs/kit";
 
@@ -91,8 +89,8 @@ export const Utility = {
 				day: "2-digit",
 				month: "2-digit",
 				year: "numeric",
-			// @ts-ignore: .fromString method exists but is not typed in `any-date-parser` package
-			}).format(parser.fromString(date)); 
+				// @ts-ignore: .fromString method exists but is not typed in `any-date-parser` package
+			}).format(parser.fromString(date));
 
 			return formattedDate;
 		} catch (error) {
@@ -264,32 +262,3 @@ export const Utility = {
 	 */
 	validateSocialMediaHandle: (handle: string) => !isURL(handle, { require_protocol: false }) && !handle.startsWith("@") && Boolean(handle.match(Utility.socialMediaHandleRegex)),
 };
-
-/* Testing functions */
-export const Testing = {
-	/**
-	 * Asserts the absence of a field on the page.
-	 * @param {Locator[]} fields - The fields to check for absence
-	 * @returns A promise that resolves when the check is complete
-	 */
-	assertFieldAbsence: async (...fields: Locator[]) => {
-		for (const field of fields) await expect(field).not.toBeVisible();
-	},
-	/**
-	 * Clicks a locator and waits for a response.
-	 * @param {Page} page - The page on which to click the locator
-	 * @param {Locator} locator - The locator to click
-	 * @param {string} endpoint - The endpoint to wait for
-	 * @returns A promise that resolves when the click and response are complete
-	 */
-	clickAndWait: async (page: Page, locator: Locator, endpoint: string) => {
-		// Ensure the locator is visible
-		await expect(locator).toBeVisible();
-
-		// Click with force option to ensure the click happens
-		await locator.click({ force: true });
-
-		// Wait for the API response
-		await page.waitForResponse(endpoint);
-	},
-};