@koloseum/utils 0.3.6 → 0.3.8

package/dist/client.js

@@ -367,7 +367,9 @@ export const Access = {
         if (!user)
             return null;
         // Initialise variables
-        let features = Config.microservices.players.filter(({ slug }) => slug === "account").flatMap(({ features }) => features);
+        let features = Config.microservices.players
+            .filter(({ slug }) => slug === "account")
+            .flatMap(({ features }) => features);
         let loungesCount = 0;
         let backroomCount = 0;
         // Count number of Lounges and Backroom roles
@@ -441,11 +443,16 @@ export const Interface = {
                 if (result.type === "redirect" && result.location) {
                     const { goto } = await import("$app/navigation");
                     await goto(result.location);
+                    // Restore button if not an OTP button
+                    if (!button.classList.contains("otp-button")) {
+                        button.disabled = false;
+                        button.innerHTML = innerHTML;
+                    }
                     return;
                 }
                 // Update form
-                // OTP buttons are not restored on failure/error so OTP flows keep the loading state
                 await update();
+                // OTP buttons are not restored on failure/error so OTP flows keep the loading state
                 const isOtpButton = button.classList.contains("otp-button");
                 const isFailureOrError = result.type === "failure" || result.type === "error";
                 if (!isOtpButton || !isFailureOrError) {

package/dist/formatting.d.ts

@@ -1,4 +1,4 @@
-import type { IdentityType, PronounsItem, Sex, SocialMediaPlatform, SocialMediaPlatformObject } from "@koloseum/types/public/auth";
+import type { BranchAddressObject, IdentityType, PronounsItem, Sex, SocialMediaPlatform, SocialMediaPlatformObject } from "@koloseum/types/public/auth";
 import type { MobilePhoneLocale } from "validator";
 export declare const Transform: {
     /**
@@ -14,24 +14,33 @@ export declare const Transform: {
      */
     cleanUrl: (url: string) => string;
     /**
-     * Formats a Koloseum Credits balance in Kenyan shillings (e.g. "Ksh 12.34").
-     * @param {number | null | undefined} cents - The balance to be formatted
-     * @returns {string} The formatted balance string, or "—" if the input is invalid
+     * Formats an amount in cents to Kenyan shillings (e.g. "Ksh 12.34").
+     * @param {number | null | undefined} cents - The amount to be formatted
+     * @param {number} decimalPlaces - The number of decimal places to display; defaults to 2
+     * @returns {string} The formatted string, or "—" if the input is invalid
      */
-    formatCreditsBalance: (cents: number | null | undefined) => string;
+    formatCentsToKsh: (cents: number | null | undefined, decimalPlaces?: number) => string;
     /**
      * 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
+     * @param {boolean} forClient - Specify whether the data is for displaying on the client (if not `isLocaleDateString`); defaults to `false`
+     * @param {boolean} isLocaleDateString - Specify whether the date should be returned as a locale date string; defaults to `false`
+     * @param {"short" | "medium" | "long" | "full"} dateStyle - The style of the date to return (if `isLocaleDateString`); defaults to `long`
+     * @returns The formatted date string, or an empty string if `isLocaleDateString` is `true`, or `null` if invalid input or in case of an error
      */
-    formatDate: (date: string, forClient?: boolean) => string | null;
+    formatDate: (date: string, forClient?: boolean, isLocaleDateString?: boolean, dateStyle?: "short" | "medium" | "long" | "full") => string | null;
     /**
      * Formats a Koloseum Experience Points (KXP) balance as an integer (e.g. "1,234 KXP").
      * @param {number | null | undefined} kxp - The balance to be formatted
      * @returns {string} The formatted balance string, or "—" if the input is invalid
      */
     formatKxpBalance: (kxp: number | null | undefined) => string;
+    /**
+     * Formats a PostgreSQL time string as "HH:MM".
+     * @param {string} time - The time string to be formatted (i.e. from PostgreSQL `time` or `timetz`)
+     * @returns {string} The formatted time string "HH:MM", or an empty string if the input is invalid
+     */
+    formatPostgresTime: (time: string) => string;
     /**
      * Formats a social media platform for display.
      * @param {SocialMediaPlatform} platform - The social media platform to be formatted
@@ -47,11 +56,12 @@ export declare const Transform: {
     /**
      * Formats a date as a locale-specific string.
      * @param {Date | string | number | null} date - Date to be formatted
-     * @param {boolean} withTime - Specify whether the date should include time; defaults to `false`
+     * @param {boolean} withTime - Whether the date should include time; defaults to `false`
      * @param {string} timeZone - The time zone to use for formatting; defaults to `Africa/Nairobi`
+     * @param {boolean} timeOnly - Whether to output time only (no date), if `withTime` is `true`; defaults to `false`
      * @returns The formatted date string, or an empty string if invalid input
      */
-    getDateString: (date: Date | string | number | null, withTime?: boolean, timeZone?: string) => string;
+    getDateString: (date: Date | string | number | null, withTime?: boolean, timeZone?: string, timeOnly?: boolean) => string;
     /**
      * Formats an identity type for display.
      * @param {IdentityType} identityType - The identity type to be formatted
@@ -84,6 +94,12 @@ export declare const Transform: {
         paginatedItems: T[];
         totalPages: number;
     };
+    /**
+     * Parses a Lounge branch address into an array of formatted address details.
+     * @param {BranchAddressObject} address - The address to parse
+     * @returns {string[]} The formatted address details array
+     */
+    parseLoungeBranchAddress: (address: BranchAddressObject) => string[];
     /**
      * Sanitises any potential HTML injected into user input.
      * @param {string} input - The input to be sanitised

package/dist/formatting.js

@@ -22,21 +22,22 @@ export const Transform = {
      */
     cleanUrl: (url) => url.replace(/^https?:\/\//, "").replace(/\/+$/, ""),
     /**
-     * Formats a Koloseum Credits balance in Kenyan shillings (e.g. "Ksh 12.34").
-     * @param {number | null | undefined} cents - The balance to be formatted
-     * @returns {string} The formatted balance string, or "—" if the input is invalid
+     * Formats an amount in cents to Kenyan shillings (e.g. "Ksh 12.34").
+     * @param {number | null | undefined} cents - The amount to be formatted
+     * @param {number} decimalPlaces - The number of decimal places to display; defaults to 2
+     * @returns {string} The formatted string, or "—" if the input is invalid
      */
-    formatCreditsBalance: (cents) => {
-        // Return placeholder if no balance is provided or input is invalid
+    formatCentsToKsh: (cents, decimalPlaces = 2) => {
+        // Return placeholder if no amount is provided or input is invalid
         if (cents == null || typeof cents !== "number")
             return "—";
-        // Format balance
+        // Format amount
         const value = cents / 100;
         let formatted = new Intl.NumberFormat("en-KE", {
             style: "currency",
             currency: "KES",
-            minimumFractionDigits: 2,
-            maximumFractionDigits: 2
+            minimumFractionDigits: decimalPlaces,
+            maximumFractionDigits: decimalPlaces
         }).format(value);
         formatted = formatted.replace(/\u00A0/g, " ");
         // Return formatted string
@@ -45,20 +46,25 @@ export const Transform = {
     /**
      * 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
+     * @param {boolean} forClient - Specify whether the data is for displaying on the client (if not `isLocaleDateString`); defaults to `false`
+     * @param {boolean} isLocaleDateString - Specify whether the date should be returned as a locale date string; defaults to `false`
+     * @param {"short" | "medium" | "long" | "full"} dateStyle - The style of the date to return (if `isLocaleDateString`); defaults to `long`
+     * @returns The formatted date string, or an empty string if `isLocaleDateString` is `true`, or `null` if invalid input or in case of an error
      */
-    formatDate: (date, forClient = false) => {
+    formatDate: (date, forClient = false, isLocaleDateString = false, dateStyle = "long") => {
         // Return null if no date is provided
+        const nullDate = isLocaleDateString ? "" : null;
         if (date === "" || typeof date !== "string")
-            return null;
+            return nullDate;
         // Handle input
         try {
             // Parse date string
             const parsedDate = Date.parse(date);
-            // Return null if date string is not parseable
             if (isNaN(parsedDate))
-                return null;
+                return nullDate;
+            // Return locale date string if requested
+            if (isLocaleDateString)
+                return new Date(parsedDate).toLocaleDateString("en-KE", { dateStyle });
             // Use the Intl.DateTimeFormat with explicit options to ensure correct formatting
             const formattedDate = new Intl.DateTimeFormat(forClient ? "fr-CA" : "en-KE", {
                 day: "2-digit",
@@ -71,7 +77,7 @@ export const Transform = {
         }
         catch (error) {
             console.error(error);
-            return null;
+            return nullDate;
         }
     },
     /**
@@ -85,6 +91,39 @@ export const Transform = {
         const formatted = new Intl.NumberFormat("en-KE").format(kxp);
         return `${formatted} KXP`;
     },
+    /**
+     * Formats a PostgreSQL time string as "HH:MM".
+     * @param {string} time - The time string to be formatted (i.e. from PostgreSQL `time` or `timetz`)
+     * @returns {string} The formatted time string "HH:MM", or an empty string if the input is invalid
+     */
+    formatPostgresTime: (time) => {
+        // Return empty string if no time is provided or input is not a string
+        if (time == null || typeof time !== "string")
+            return "";
+        const trimmed = time.trim();
+        if (trimmed === "")
+            return "";
+        // Match PostgreSQL/ISO-style time: H:MM, HH:MM, HH:MM:SS, or HH:MM:SS.ffffff
+        const match = trimmed.match(/^(\d{1,2}):(\d{2})(?::(\d{1,2})(?:\.\d+)?)?$/);
+        if (!match)
+            return "";
+        const hours = Number.parseInt(match[1], 10);
+        const minutes = Number.parseInt(match[2], 10);
+        const seconds = match[3] !== undefined ? Number.parseInt(match[3], 10) : 0;
+        // Validate ranges: hour 0–24, minute 0–59, second 0–60; 24:00:00 is end-of-day
+        if (hours < 0 || hours > 24)
+            return "";
+        if (minutes < 0 || minutes > 59)
+            return "";
+        if (seconds < 0 || seconds > 60)
+            return "";
+        if (hours === 24 && (minutes !== 0 || seconds !== 0))
+            return "";
+        // Return formatted time
+        const h = String(hours).padStart(2, "0");
+        const m = String(minutes).padStart(2, "0");
+        return `${h}:${m}`;
+    },
     /**
      * Formats a social media platform for display.
      * @param {SocialMediaPlatform} platform - The social media platform to be formatted
@@ -148,11 +187,12 @@ export const Transform = {
     /**
      * Formats a date as a locale-specific string.
      * @param {Date | string | number | null} date - Date to be formatted
-     * @param {boolean} withTime - Specify whether the date should include time; defaults to `false`
+     * @param {boolean} withTime - Whether the date should include time; defaults to `false`
      * @param {string} timeZone - The time zone to use for formatting; defaults to `Africa/Nairobi`
+     * @param {boolean} timeOnly - Whether to output time only (no date), if `withTime` is `true`; defaults to `false`
      * @returns The formatted date string, or an empty string if invalid input
      */
-    getDateString: (date, withTime = false, timeZone = "Africa/Nairobi") => {
+    getDateString: (date, withTime = false, timeZone = "Africa/Nairobi", timeOnly = false) => {
         // Return empty string if no date is provided
         if (!date)
             return "";
@@ -178,9 +218,9 @@ export const Transform = {
         // Format date
         return dateToFormat.toLocaleString("en-KE", {
             timeZone,
-            year: "numeric",
-            month: "long",
-            day: "numeric",
+            year: withTime && timeOnly ? undefined : "numeric",
+            month: withTime && timeOnly ? undefined : "long",
+            day: withTime && timeOnly ? undefined : "numeric",
             hour: withTime ? "numeric" : undefined,
             minute: withTime ? "2-digit" : undefined,
             hour12: withTime ? true : undefined
@@ -330,6 +370,36 @@ export const Transform = {
         // Return data
         return { paginatedItems, totalPages };
     },
+    /**
+     * Parses a Lounge branch address into an array of formatted address details.
+     * @param {BranchAddressObject} address - The address to parse
+     * @returns {string[]} The formatted address details array
+     */
+    parseLoungeBranchAddress: (address) => {
+        // Validate address
+        if (!address || Array.isArray(address) || typeof address !== "object")
+            return [];
+        // Destructure address
+        const { buildingName, unitNumber, streetName, boxNumber, postalCode, town, county } = address;
+        // Require fields used in template literals to avoid "undefined" in output
+        const required = typeof buildingName === "string" &&
+            typeof streetName === "string" &&
+            typeof town === "string" &&
+            typeof county === "string";
+        if (!required)
+            return [];
+        // Define address details
+        const addressDetails = [];
+        // Add address details
+        addressDetails.push(`${buildingName}${unitNumber ? `, ${unitNumber}` : ""}`);
+        addressDetails.push(streetName);
+        if (boxNumber && postalCode)
+            addressDetails.push(`P.O. Box ${boxNumber}-${postalCode}`);
+        addressDetails.push(town);
+        addressDetails.push(`${county} County`);
+        // Return address details
+        return addressDetails;
+    },
     /**
      * Sanitises any potential HTML injected into user input.
      * @param {string} input - The input to be sanitised

package/dist/platform.js

@@ -4,7 +4,6 @@ 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 = {
     /**
@@ -104,12 +103,12 @@ export const Config = {
                     {
                         name: "Start Session",
                         description: "Search for a Lounge, choose game and station, check in or reserve, and manage your session to checkout.",
-                        slug: "start-session"
+                        slug: "start"
                     },
                     {
                         name: "Find a Lounge",
                         description: "Browse Lounges, view branches and stations, start a session, or file a report.",
-                        slug: "find-lounge"
+                        slug: "lounges"
                     }
                 ],
                 roles: null
@@ -165,7 +164,7 @@ export const Config = {
                     {
                         name: "Game Exchange",
                         description: "Discover and reserve used games and consoles for sale.",
-                        slug: "game-exchange"
+                        slug: "exchange"
                     }
                 ],
                 roles: null
@@ -446,7 +445,7 @@ export const Config = {
                     {
                         name: "Game Exchange",
                         description: "Review and manage used game and console listings and track revenue.",
-                        slug: "game-exchange"
+                        slug: "exchange"
                     }
                 ],
                 roles: [
@@ -472,13 +471,13 @@ export const Config = {
                     },
                     {
                         name: "Box Office",
-                        slug: "box-office",
+                        slug: "events",
                         featureSlugs: ["dashboard", "events"]
                     },
                     {
                         name: "Game Exchange",
-                        slug: "game-exchange",
-                        featureSlugs: ["dashboard", "game-exchange"]
+                        slug: "exchange",
+                        featureSlugs: ["dashboard", "exchange"]
                     }
                 ]
             },
@@ -591,6 +590,7 @@ export const Resource = {
      */
     getKenyaCounties: async (sortBy = "name") => {
         // Create Kenya administrative divisions instance
+        const { KenyaAdministrativeDivisions } = (await import("kenya-administrative-divisions")).default;
         const kenyaAdmin = new KenyaAdministrativeDivisions();
         // Get all counties
         const countiesData = await kenyaAdmin.getAll();
@@ -810,6 +810,7 @@ export const Resource = {
      */
     validateAddress: async (formData) => {
         // Create Kenya administrative divisions instance
+        const { KenyaAdministrativeDivisions } = (await import("kenya-administrative-divisions")).default;
         const kenyaAdmin = new KenyaAdministrativeDivisions();
         // Building name
         let buildingName = formData.get("building-name");

package/dist/server.d.ts

@@ -1,6 +1,6 @@
 import type { Database } from "@koloseum/types/database";
 import type { CustomError, Microservice, MicroserviceGroup, UserWithCustomMetadata } from "@koloseum/types/general";
-import type { SupabaseClient, FunctionInvokeOptions, PostgrestError } from "@supabase/supabase-js";
+import type { FunctionInvokeOptions, PostgrestError, SupabaseClient } from "@supabase/supabase-js";
 export declare const Instance: {
     /**
      * Calls a Supabase Edge function.
@@ -35,7 +35,7 @@ export declare const Instance: {
      * @param {Object} options - The options for the function.
      * @param {MicroserviceGroup} options.microserviceGroup - The microservice group.
      * @param {Microservice<MicroserviceGroup> | string} options.microservice - The microservice.
-     * @param {string} options.playersUrl - The URL to the Players microservice.
+     * @param {string} options.playersUrl - The URL to the Players microservice; include only if `microserviceGroup` is not `players`.
      * @param {(role: string) => string} options.requestedPermission - A function that returns the requested permission for a given role.
      * @returns {Promise<{ isAuthorised?: boolean; redirect?: { code: number; url: string }; error?: CustomError }>} The result of the function.
      */
@@ -73,10 +73,10 @@ export declare const Exception: {
     customError: (code: number | undefined, message: string) => CustomError;
     /**
      * Parses a `CustomError` object within a page/layout server load function and returns an error to be thrown.
-     * @param {CustomError} error - The error object
+     * @param {CustomError | PostgrestError | null} error - The error object
      * @returns A new `Error` object if the error is unexpected, or a Svelte error otherwise
      */
-    parseLoadError: (error: CustomError) => Error | never;
+    parseLoadError: (error: CustomError | PostgrestError | null) => Error | never;
     /**
      * 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
@@ -87,3 +87,40 @@ export declare const Exception: {
         error?: CustomError;
     };
 };
+export declare const Phone: {
+    /**
+     * Requests an OTP to be sent to the given phone.
+     * Logs the attempt to compliance.phone_verification_attempts via log_phone_verification.
+     * @param {SupabaseClient<Database>} supabase - The Supabase client
+     * @param {string} phone - The phone number in E.164 format
+     * @param {Object} options - The options for the function.
+     * @param {boolean} options.dev - Whether the environment is development/test; defaults to `false`
+     * @param {string} options.supabaseUrl - The URL of the Supabase instance; defaults to `env.PUBLIC_SUPABASE_URL`
+     * @returns An object with `success` if the OTP request succeeded, or an `error` if any occurred
+     */
+    requestOtp: (supabase: SupabaseClient<Database>, phone: string, options: {
+        dev: boolean;
+        supabaseUrl: string;
+    }) => Promise<{
+        twilioSid?: string;
+        error?: CustomError;
+    }>;
+    /**
+     * Verifies an OTP code.
+     * Updates the attempt in compliance.phone_verification_attempts via log_phone_verification.
+     * @param {SupabaseClient<Database>} supabase - The Supabase client
+     * @param {string} phone - The phone number in E.164 format
+     * @param {string} code - The one-time passcode entered by the user
+     * @param {Object} options - The options for the function.
+     * @param {boolean} options.dev - Whether the environment is development/test; defaults to `false`
+     * @param {string} options.supabaseUrl - The URL of the Supabase instance; defaults to `env.PUBLIC_SUPABASE_URL`
+     * @returns An object with `success` if the OTP verification succeeded, or an `error` if any occurred
+     */
+    verifyOtp: (supabase: SupabaseClient<Database>, phone: string, code: string, options: {
+        dev: boolean;
+        supabaseUrl: string;
+    }) => Promise<{
+        twilioSid?: string;
+        error?: CustomError;
+    }>;
+};

package/dist/server.js

@@ -1,4 +1,5 @@
 import { Status } from "./general.js";
+import { Resource } from "./platform.js";
 import { error as svelteError } from "@sveltejs/kit";
 import { FunctionsFetchError, FunctionsHttpError, FunctionsRelayError } from "@supabase/supabase-js";
 /* INSTANCE HELPERS */
@@ -100,7 +101,7 @@ export const Instance = {
      * @param {Object} options - The options for the function.
      * @param {MicroserviceGroup} options.microserviceGroup - The microservice group.
      * @param {Microservice<MicroserviceGroup> | string} options.microservice - The microservice.
-     * @param {string} options.playersUrl - The URL to the Players microservice.
+     * @param {string} options.playersUrl - The URL to the Players microservice; include only if `microserviceGroup` is not `players`.
      * @param {(role: string) => string} options.requestedPermission - A function that returns the requested permission for a given role.
      * @returns {Promise<{ isAuthorised?: boolean; redirect?: { code: number; url: string }; error?: CustomError }>} The result of the function.
      */
@@ -113,6 +114,8 @@ export const Instance = {
         // Validate user metadata and app metadata
         if (!user.user_metadata || !user.app_metadata)
             return { error: Exception.customError(400, "User metadata is required.") };
+        if (!Array.isArray(user.app_metadata.roles))
+            return { error: Exception.customError(400, "User roles are required.") };
         // Get user's roles and the role prefix
         const roles = [];
         const rolePrefix = microserviceGroup === "backroom" ? "backroom" : microserviceGroup.slice(0, -1);
@@ -134,47 +137,33 @@ export const Instance = {
             // Redirect to Players microservices
             return { redirect: { code: 307, url: playersUrl } };
         }
-        // Destructure role
-        const [role] = roles;
-        // Define condition variables
-        const isPlayer = microserviceGroup === "players" && role === "player";
-        const isSuperuser = (microserviceGroup === "backroom" || microserviceGroup === "lounges") && role === "superuser";
-        let isAuthorised = false;
         // Grant access if Player (accessing Players microservices), superuser, or account microservice
-        if (isPlayer || isSuperuser || microservice === "account")
-            isAuthorised = true;
-        // Evaluate access
-        else if (microserviceGroup !== "players") {
+        let isAuthorised = (microserviceGroup === "players" && roles.includes("player")) ||
+            ((microserviceGroup === "backroom" || microserviceGroup === "lounges") && roles.includes("superuser")) ||
+            microservice === "account" ||
+            false;
+        // Evaluate access for each role until one grants permission
+        if (!isAuthorised) {
+            // Return false if not a Players microservice; no permissions to check
+            if (microserviceGroup === "players")
+                return { isAuthorised };
             // Return error if requested permission is not provided
             if (!options.requestedPermission)
                 return { error: Exception.customError(400, "Requested permission is required.") };
-            // Get user's role and requested app permission
-            const requestedPermission = options.requestedPermission(role);
-            // Check if user has the requested permission
-            const { data, error: isAuthorisedError } = await supabase
-                .schema("compliance")
-                .rpc("authorise", { requested_permission: requestedPermission });
-            if (isAuthorisedError)
-                return Exception.parsePostgrestError(isAuthorisedError);
-            // Assign result of authorisation check
-            isAuthorised = data;
-        }
-        // If user has completed Player registration
-        if (roles.includes("player")) {
-            // Prepare person data
-            let personData = {};
-            if (user.app_metadata.person_data) {
-                const { first_name: firstName, last_name: lastName, pseudonym } = user.app_metadata.person_data;
-                personData = { firstName, lastName, phone: user.phone, pseudonym };
+            for (const role of roles) {
+                if (role == null)
+                    continue;
+                const requestedPermission = options.requestedPermission(role);
+                const { data, error: isAuthorisedError } = await supabase
+                    .schema("compliance")
+                    .rpc("authorise", { requested_permission: requestedPermission });
+                if (isAuthorisedError)
+                    return Exception.parsePostgrestError(isAuthorisedError);
+                if (data) {
+                    isAuthorised = true;
+                    break;
+                }
             }
-            // Validate SuprSend subscriber
-            const { code, error: validationError } = await Instance.callEdgeFunction(false, supabase, `suprsend/validate-subscriber?user-id=${user.id}`, { method: "POST", headers: { "Content-Type": "application/json" }, body: personData });
-            if (validationError)
-                return { error: Exception.customError(code, validationError) };
-            // Send welcome notification if not already sent
-            const { error: welcomeError } = await Instance.sendWelcomeNotification(supabase, user, microserviceGroup);
-            if (welcomeError)
-                return { error: welcomeError };
         }
         // Return result
         return { isAuthorised };
@@ -201,7 +190,9 @@ export const Instance = {
                 }
             });
             if (updateError)
-                return { error: Exception.customError(updateError.status ?? 500, updateError.message) };
+                return {
+                    error: Exception.customError(updateError.status ?? 500, updateError.message)
+                };
             // Only send notification if flag was successfully updated
             const updatedBackroom = updatedUser.user?.user_metadata?.backroom;
             if (updatedBackroom?.welcome_notification_sent === true &&
@@ -219,7 +210,11 @@ export const Instance = {
                     ]
                 };
                 // Send welcome notification
-                const { code, error: workflowError } = await Instance.callEdgeFunction(false, supabase, `suprsend/trigger-workflow?user-id=${user.id}`, { method: "POST", headers: { "Content-Type": "application/json" }, body: workflowBody });
+                const { code, error: workflowError } = await Instance.callEdgeFunction(false, supabase, `suprsend/trigger-workflow?user-id=${user.id}`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: workflowBody
+                });
                 // If notification fails, revert the flag and return error
                 if (workflowError) {
                     await supabase.auth.updateUser({
@@ -252,10 +247,27 @@ export const Exception = {
     customError: (code, message) => !code || code < 400 || code > 599 ? { code: 500, message: Status.ERROR } : { code, message },
     /**
      * Parses a `CustomError` object within a page/layout server load function and returns an error to be thrown.
-     * @param {CustomError} error - The error object
+     * @param {CustomError | PostgrestError | null} 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 }),
+    parseLoadError: (error) => {
+        // Return generic error if no error was provided
+        if (!error)
+            return new Error(Status.ERROR);
+        // Parse Postgrest error if provided
+        let parsedError;
+        if ("hint" in error)
+            ({ error: parsedError } = Exception.parsePostgrestError(error));
+        else
+            parsedError = error;
+        // Treat missing parsed error as generic server error
+        if (!parsedError)
+            return new Error(Status.ERROR);
+        // Return error to be thrown
+        if (parsedError.code === 500)
+            return new Error(parsedError.message);
+        return svelteError(Number(parsedError.code), { message: parsedError.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
@@ -269,7 +281,8 @@ export const Exception = {
             return { error };
         // Get custom error code from hint
         const customErrorCode = Number(postgrestError.hint);
-        // Clamp 5xx errors down to 422 to prevent Sentry from capturing them as unhandled; see https://koloseum-technologies.sentry.io/issues/6766267685/
+        // Clamp 5xx errors down to 422 to prevent Sentry from capturing them as unhandled
+        // see https://koloseum-technologies.sentry.io/issues/6766267685/
         let statusCode = clientSafe ? (customErrorCode >= 500 ? 422 : customErrorCode) : customErrorCode;
         // Return custom error if hint is a number between 400 and 599
         if (!isNaN(customErrorCode) && customErrorCode >= 400 && customErrorCode <= 599) {
@@ -320,3 +333,79 @@ export const Exception = {
         return { error };
     }
 };
+/* PHONE HELPERS */
+export const Phone = {
+    /**
+     * Requests an OTP to be sent to the given phone.
+     * Logs the attempt to compliance.phone_verification_attempts via log_phone_verification.
+     * @param {SupabaseClient<Database>} supabase - The Supabase client
+     * @param {string} phone - The phone number in E.164 format
+     * @param {Object} options - The options for the function.
+     * @param {boolean} options.dev - Whether the environment is development/test; defaults to `false`
+     * @param {string} options.supabaseUrl - The URL of the Supabase instance; defaults to `env.PUBLIC_SUPABASE_URL`
+     * @returns An object with `success` if the OTP request succeeded, or an `error` if any occurred
+     */
+    requestOtp: async (supabase, phone, options) => {
+        // Request OTP
+        const result = await Instance.callEdgeFunction(false, supabase, `twilio/request-otp?phone=${encodeURIComponent(phone)}`);
+        if (result.error)
+            return { error: Exception.customError(result.code, result.error) };
+        // Destructure options
+        const { dev, supabaseUrl } = options;
+        // Parse response
+        const data = result.data;
+        let { dateCreated, dateUpdated } = data;
+        if (dev || Resource.isLocalSupabase(supabaseUrl)) {
+            dateCreated = new Date().toISOString();
+            dateUpdated = new Date().toISOString();
+        }
+        // Log attempt to database
+        const { error } = await supabase.schema("compliance").rpc("log_phone_verification", {
+            p_twilio_sid: data.sid,
+            p_phone: data.to,
+            p_send_code_attempts: data.sendCodeAttempts,
+            p_status: data.status,
+            p_created_at: new Date(dateCreated),
+            p_updated_at: new Date(dateUpdated)
+        });
+        if (error)
+            return Exception.parsePostgrestError(error);
+        // Return Twilio SID
+        return { twilioSid: data.sid };
+    },
+    /**
+     * Verifies an OTP code.
+     * Updates the attempt in compliance.phone_verification_attempts via log_phone_verification.
+     * @param {SupabaseClient<Database>} supabase - The Supabase client
+     * @param {string} phone - The phone number in E.164 format
+     * @param {string} code - The one-time passcode entered by the user
+     * @param {Object} options - The options for the function.
+     * @param {boolean} options.dev - Whether the environment is development/test; defaults to `false`
+     * @param {string} options.supabaseUrl - The URL of the Supabase instance; defaults to `env.PUBLIC_SUPABASE_URL`
+     * @returns An object with `success` if the OTP verification succeeded, or an `error` if any occurred
+     */
+    verifyOtp: async (supabase, phone, code, options) => {
+        // Verify OTP
+        const result = await Instance.callEdgeFunction(false, supabase, `twilio/verify-otp?phone=${encodeURIComponent(phone)}&code=${encodeURIComponent(code)}`);
+        if (result.error)
+            return { error: Exception.customError(result.code, result.error) };
+        // Destructure options
+        const { dev, supabaseUrl } = options;
+        // Parse response
+        const data = result.data;
+        let { dateUpdated } = data;
+        if (dev || Resource.isLocalSupabase(supabaseUrl)) {
+            dateUpdated = new Date().toISOString();
+        }
+        // Update attempt in database
+        const { error } = await supabase.schema("compliance").rpc("log_phone_verification", {
+            p_twilio_sid: data.sid,
+            p_status: data.status,
+            p_updated_at: new Date(dateUpdated)
+        });
+        if (error)
+            return Exception.parsePostgrestError(error);
+        // Return Twilio SID
+        return { twilioSid: data.sid };
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@koloseum/utils",
-	"version": "0.3.6",
+	"version": "0.3.8",
 	"author": "Koloseum Technologies Limited",
 	"type": "module",
 	"description": "Utility logic for use across Koloseum web apps (TypeScript)",
@@ -62,7 +62,7 @@
 		"validator": "^13.15.15"
 	},
 	"devDependencies": {
-		"@koloseum/types": "^0.3.5",
+		"@koloseum/types": "^0.3.7",
 		"@playwright/test": "^1.55.0",
 		"@suprsend/web-components": "^0.4.0",
 		"@types/sanitize-html": "^2.16.0",