@koloseum/utils 0.1.1

package/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "@koloseum/utils",
+	"version": "0.1.1",
+	"author": "Koloseum Technologies Limited",
+	"description": "Utility logic for use across Koloseum web apps (TypeScript)",
+	"keywords": [
+		"Koloseum"
+	],
+	"homepage": "https://github.com/koloseum-technologies/npm-utils#readme",
+	"bugs": {
+		"url": "https://github.com/koloseum-technologies/npm-utils/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/koloseum-technologies/npm-utils.git"
+	},
+	"main": "./src/utils.ts",
+	"exports": {
+		"./src": "./src/utils.ts"
+	},
+	"files": [
+		"./src/**/*.ts"
+	],
+	"scripts": {
+		"test": "vitest --run"
+	},
+	"dependencies": {
+		"@koloseum/types": "^0.1.0",
+		"@supabase/supabase-js": "^2.48.1",
+		"@sveltejs/kit": "^2.17.1",
+		"any-date-parser": "^2.0.3",
+		"sanitize-html": "^2.14.0",
+		"validator": "^13.12.0"
+	},
+	"devDependencies": {
+		"@types/sanitize-html": "^2.13.0",
+		"@types/validator": "^13.12.2",
+		"typescript": "^5.0.0"
+	}
+}

package/src/utils.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, it, vi } from "vitest";
+import { Status, Utility } from "./utils";
+
+describe("Status helper", () => {
+	// Destructure the Status object
+	const { ERROR, LOADING } = Status;
+
+	// Test each helper
+	it("contains an error message", () => {
+		expect(ERROR).toBe("An unexpected error occurred. Kindly try again.");
+	});
+
+	it("contains a loading message", () => {
+		expect(LOADING).toBe("Please wait…");
+	});
+});
+
+describe("Utility helper", () => {
+	// Destructure the Utility object
+	const {
+		capitalise,
+		customError,
+		formatDate,
+		formatSocialMediaPlatform,
+		getAge,
+		minimumMinorBirthDate,
+		parseLoadError,
+		parsePostgrestError,
+		sanitiseHtml,
+		validateE164,
+		validateSocialMediaHandle
+	} = Utility;
+
+	// Test each helper
+	it("capitalises a word", () => {
+		expect(capitalise("word")).toBe("Word");
+		expect(capitalise("WORD")).toBe("Word");
+		expect(capitalise("wOrD")).toBe("Word");
+	});
+
+	it("generates a custom error", () => {
+		expect(customError(200, "OK")).toEqual({ code: 500, message: Status.ERROR });
+		expect(customError(400, "Bad Request")).toEqual({ code: 400, message: "Bad Request" });
+		expect(customError(500, "Internal Server Error")).toEqual({ code: 500, message: "Internal Server Error" });
+		expect(customError(700, "Unknown")).toEqual({ code: 500, message: Status.ERROR });
+	});
+
+	it("formats dates", () => {
+		expect(formatDate("31st December 2021")).toBe("31/12/2021");
+		expect(formatDate("31st December 2021", true)).toBe("2021-12-31");
+		expect(formatDate("31st December 2021", false)).toBe("31/12/2021");
+	});
+
+	it("formats social media platforms", () => {
+		expect(formatSocialMediaPlatform("facebook")).toBe("Facebook");
+		expect(formatSocialMediaPlatform("instagram")).toBe("Instagram");
+		expect(formatSocialMediaPlatform("kick")).toBe("Kick");
+		expect(formatSocialMediaPlatform("tiktok")).toBe("TikTok");
+		expect(formatSocialMediaPlatform("twitter")).toBe("X (formerly Twitter)");
+		expect(formatSocialMediaPlatform("youtube")).toBe("YouTube");
+	});
+
+	it("gets the age of a person", () => {
+		// Set system time to 1 January 2024
+		vi.useFakeTimers();
+		vi.setSystemTime(new Date("2024-01-01"));
+
+		// Test age calculation
+		expect(getAge("2000-01-01")).toBe(24);
+		expect(getAge("2000-12-31")).toBe(23);
+		expect(getAge("2024-01-03")).toBe(-1);
+
+		// Reset timers
+		vi.useRealTimers();
+	});
+
+	it("gets the minimum birth date for a minor", () => {
+		// Calculate expected minimum birth date
+		const today = new Date();
+		const tomorrow = new Date();
+		tomorrow.setUTCDate(today.getDate() + 1);
+
+		const tomorrow18YearsAgo = tomorrow.getFullYear() - 18;
+		tomorrow.setFullYear(tomorrow18YearsAgo);
+
+		const expectedMinimumMinorBirthDate = tomorrow.toISOString().split("T")[0];
+
+		// Test minimum birth date calculation
+		expect(minimumMinorBirthDate).toBe(expectedMinimumMinorBirthDate);
+	});
+
+	it("parses a SvelteKit load error", () => {
+		const error = { code: 500, message: "Internal Server Error" };
+		expect(parseLoadError(error)).toEqual(new Error("Internal Server Error"));
+		// add assertion to check for SvelteKit `error` function?
+	});
+
+	it("parses a Postgrest error", () => {
+		expect(parsePostgrestError(null)).toEqual({ error: undefined });
+		expect(
+			parsePostgrestError({
+                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: ""
+			})
+		).toEqual({ error: { code: 403, message: Status.ERROR } });
+		expect(
+			parsePostgrestError({
+                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."
+			})
+		).toEqual({ error: { code: 404, message: Status.ERROR } });
+		expect(
+			parsePostgrestError({
+                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: ""
+			})
+		).toEqual({ error: { code: 405, message: Status.ERROR } });
+		expect(
+			parsePostgrestError({
+                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: ""
+			})
+		).toEqual({ error: { code: 409, message: Status.ERROR } });
+		expect(
+			parsePostgrestError({
+                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: ""
+			})
+		).toEqual({ error: { code: 500, message: Status.ERROR } });
+		expect(
+			parsePostgrestError({
+                code: "08003",
+                name: "connection_does_not_exist",
+				message: "connection does not exist",
+				details: "The connection to the database was lost or never established.",
+				hint: ""
+			})
+		).toEqual({ error: { code: 503, message: Status.ERROR } });
+		expect(
+			parsePostgrestError({
+                code: "P0001",
+                name: "raise_exception",
+				message: "I'm a teapot!",
+				details: "Pretty simple",
+				hint: "418"
+			})
+		).toEqual({ error: { code: 418, message: "I'm a teapot!" } });
+	});
+
+	it("sanitises HTML", () => {
+		expect(sanitiseHtml("<script>alert('Hello!');</script>")).toBe("");
+		expect(sanitiseHtml("<p>Hello!</p>")).toBe("Hello!");
+		expect(sanitiseHtml("<p>Hello!</p><script>alert('Hello!');</script>")).toBe("Hello!");
+	});
+
+	it("validates E.164 phone numbers", () => {
+		// Valid phone number
+		expect(validateE164("+254712345678")).toBe(true);
+		expect(validateE164("+254712345678", "en-KE")).toBe(true);
+		expect(validateE164("+254712345678", "en-RW")).toBe(false);
+
+		// Invalid phone numbers
+		expect(validateE164("+254812345678")).toBe(false);
+		expect(validateE164("254812345678")).toBe(false);
+		expect(validateE164("+2548123456789")).toBe(false);
+		expect(validateE164("2548123456789")).toBe(false);
+		expect(validateE164("08123456789")).toBe(false);
+	});
+
+	it("validates social media handles", () => {
+		expect(validateSocialMediaHandle("username")).toBe(true);
+		expect(validateSocialMediaHandle("@username")).toBe(false);
+		expect(validateSocialMediaHandle("/username")).toBe(false);
+		expect(validateSocialMediaHandle("https://www.facebook.com/username")).toBe(false);
+	});
+});

package/src/utils.ts

@@ -0,0 +1,264 @@
+import type { Database } from "@koloseum/types/database";
+import type { CustomError, SocialMediaPlatform } from "@koloseum/types/public/auth.js";
+
+import type { PostgrestError, SupabaseClient } from "@supabase/supabase-js";
+import type { MobilePhoneLocale } from "validator";
+
+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: SupabaseClient<Database>, path: string, method: "GET" | "POST" = "GET"): Promise<{ data?: any; error?: string }> => {
+		// 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: string) =>
+		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: number | undefined, message: string): CustomError => (!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: string, forClient: boolean = 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: SocialMediaPlatform) => {
+		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: string) => {
+		if (dateOfBirth === "" || typeof dateOfBirth !== "string") return NaN;
+		dateOfBirth = Utility.formatDate(dateOfBirth, true) as string;
+
+		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: CustomError) => (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: PostgrestError | null): { error?: CustomError } => {
+		// Return undefined if no error occurred
+		let error: CustomError | undefined;
+		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: string) => (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: string, locale: "any" | MobilePhoneLocale | MobilePhoneLocale[] = "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: string) => !isURL(handle, { require_protocol: false }) && !handle.startsWith("@") && Boolean(handle.match(Utility.socialMediaHandleRegex)),
+};