@koloseum/utils 0.2.28 → 0.3.0

package/dist/server.d.ts

@@ -0,0 +1,77 @@
+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";
+export declare const Instance: {
+    /**
+     * Calls a Supabase Edge function.
+     * @param {boolean} browser - Whether the function is being called in the browser
+     * @param {SupabaseClient<Database>} supabase - The Supabase client
+     * @param {string} path - The path to the Edge function
+     * @param {FunctionInvokeOptions} [options] - The options to use for the function invocation; defaults to `{ method: "GET" }`
+     * @returns The response from the Edge function
+     */
+    callEdgeFunction: (browser: boolean, supabase: SupabaseClient<Database>, path: string, options?: FunctionInvokeOptions) => Promise<{
+        code: number;
+        data?: any;
+        error?: string;
+        context?: Record<string, any>;
+    }>;
+    /**
+     * Checks if a user is authorised to access a microservice.
+     * @param {SupabaseClient<Database>} supabase - The Supabase client.
+     * @param {UserWithCustomMetadata} user - The user to check.
+     * @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 {(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.
+     */
+    isUserAuthorised: (supabase: SupabaseClient<Database>, user: UserWithCustomMetadata, options: {
+        microserviceGroup: MicroserviceGroup;
+        microservice: Microservice<MicroserviceGroup> | string;
+        playersUrl?: string;
+        requestedPermission?: (role: string) => string;
+    }) => Promise<{
+        isAuthorised?: boolean;
+        redirect?: {
+            code: number;
+            url: string;
+        };
+        error?: CustomError;
+    }>;
+    /**
+     * Sends a welcome notification to a new user.
+     * @param {SupabaseClient<Database>} supabase - The Supabase client
+     * @param {UserWithCustomMetadata} user - The user to send the notification to
+     * @param {MicroserviceGroup} microserviceGroup - The microservice group the user belongs to
+     * @returns An object with an `error` if any has occurred
+     */
+    sendWelcomeNotification: (supabase: SupabaseClient<Database>, user: UserWithCustomMetadata, microserviceGroup: MicroserviceGroup) => Promise<{
+        error?: CustomError;
+    }>;
+};
+export declare const Exception: {
+    /**
+     * 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;
+    /**
+     * 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 | 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
+     * @param {boolean} clientSafe - Whether to clamp 5xx errors down to 422 to prevent Sentry from capturing them as unhandled; defaults to `true`
+     * @returns An object with an `error` if any has occurred
+     */
+    parsePostgrestError: (postgrestError: PostgrestError | null, clientSafe?: boolean) => {
+        error?: CustomError;
+    };
+};

package/dist/server.js

@@ -0,0 +1,300 @@
+import { Status } from "./general.js";
+import { error as svelteError } from "@sveltejs/kit";
+import { FunctionsFetchError, FunctionsHttpError, FunctionsRelayError } from "@supabase/supabase-js";
+/* INSTANCE HELPERS */
+export const Instance = {
+    /**
+     * Calls a Supabase Edge function.
+     * @param {boolean} browser - Whether the function is being called in the browser
+     * @param {SupabaseClient<Database>} supabase - The Supabase client
+     * @param {string} path - The path to the Edge function
+     * @param {FunctionInvokeOptions} [options] - The options to use for the function invocation; defaults to `{ method: "GET" }`
+     * @returns The response from the Edge function
+     */
+    callEdgeFunction: async (browser, supabase, path, options = { method: "GET" }) => {
+        try {
+            // Only add Origin header in browser environment
+            if (browser)
+                options.headers = { ...options.headers, Origin: window.location.origin };
+            // Fetch response with additional options for better cross-origin handling
+            const { data, error } = await supabase.functions.invoke(path, options);
+            // Handle different error types
+            if (error) {
+                // Define context
+                const context = {};
+                // Define error code and message
+                const code = Number(error.context?.status) || 500;
+                let message = error.context?.statusText || Status.ERROR;
+                // Handle HTTP errors
+                if (error instanceof FunctionsHttpError) {
+                    try {
+                        // Get content type header safely
+                        const contentType = error.context?.headers?.get("content-type") || "";
+                        // If content type is JSON, get error data
+                        if (contentType.includes("application/json")) {
+                            try {
+                                const errorData = await error.context.json();
+                                message = errorData.message || message;
+                                // Assign attempt ID to context if present
+                                if (path.includes("verify-id") && errorData.attemptId)
+                                    context.attemptId = errorData.attemptId;
+                            }
+                            catch (jsonError) {
+                                console.error("Failed to parse JSON error response:", jsonError);
+                            }
+                        }
+                        // If content type is plain text, get error message
+                        else if (contentType.includes("text/plain")) {
+                            try {
+                                message = await error.context.text();
+                            }
+                            catch (textError) {
+                                console.error("Failed to parse text error response:", textError);
+                            }
+                        }
+                    }
+                    catch (parseError) {
+                        console.error("Failed to parse error response:", parseError);
+                    }
+                }
+                // Handle relay and fetch errors
+                else if (error instanceof FunctionsRelayError || error instanceof FunctionsFetchError)
+                    message = error.message;
+                // Return error
+                return { code: code, error: message, context };
+            }
+            // Return response
+            return { code: 200, data };
+        }
+        catch (unexpectedError) {
+            console.error("Unexpected error:", unexpectedError);
+            return { code: 500, error: Status.ERROR };
+        }
+    },
+    /**
+     * Checks if a user is authorised to access a microservice.
+     * @param {SupabaseClient<Database>} supabase - The Supabase client.
+     * @param {UserWithCustomMetadata} user - The user to check.
+     * @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 {(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.
+     */
+    isUserAuthorised: async (supabase, user, options) => {
+        // Destructure options
+        const { microserviceGroup, microservice, playersUrl } = options;
+        // Return true if microservice group is public
+        if (microserviceGroup === "public")
+            return { isAuthorised: true };
+        // Validate user metadata and app metadata
+        if (!user.user_metadata || !user.app_metadata)
+            return { error: Exception.customError(400, "User metadata is required.") };
+        // Get user's roles and the role prefix
+        const roles = [];
+        const rolePrefix = microserviceGroup === "backroom" ? "backroom" : microserviceGroup.slice(0, -1);
+        for (const role of user.app_metadata.roles) {
+            if (role === "player") {
+                if (microserviceGroup === "players")
+                    roles.push(role);
+                else
+                    continue;
+            }
+            if (role.startsWith(`${rolePrefix}_`))
+                roles.push(role.replace(`${rolePrefix}_`, ""));
+        }
+        // Redirect to Players microservices if user does not have any roles for the microservice group
+        if (roles.length === 0 && microserviceGroup !== "players") {
+            // Return error if Players URL is not provided
+            if (!playersUrl)
+                return { error: Exception.customError(400, "Players URL is required.") };
+            // 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") {
+            // 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 };
+            }
+            // 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 };
+    },
+    /**
+     * Sends a welcome notification to a new user.
+     * @param {SupabaseClient<Database>} supabase - The Supabase client
+     * @param {UserWithCustomMetadata} user - The user to send the notification to
+     * @param {MicroserviceGroup} microserviceGroup - The microservice group the user belongs to
+     * @returns An object with an `error` if any has occurred
+     */
+    sendWelcomeNotification: async (supabase, user, microserviceGroup) => {
+        // Backroom
+        if (microserviceGroup === "backroom" && !user.user_metadata.backroom?.welcome_notification_sent) {
+            // Use atomic update with timestamp to prevent race conditions
+            const currentTime = new Date().toISOString();
+            const { data: updatedUser, error: updateError } = await supabase.auth.updateUser({
+                data: {
+                    backroom: {
+                        ...user.user_metadata.backroom,
+                        welcome_notification_sent: true,
+                        welcome_notification_timestamp: currentTime
+                    }
+                }
+            });
+            if (updateError)
+                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 &&
+                updatedBackroom?.welcome_notification_timestamp === currentTime) {
+                // Define SuprSend workflow body
+                const workflowBody = {
+                    name: "welcome-to-backroom",
+                    template: "welcome-to-backroom",
+                    notification_category: "system",
+                    users: [
+                        {
+                            distinct_id: user.id,
+                            $skip_create: true
+                        }
+                    ]
+                };
+                // 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 });
+                // If notification fails, revert the flag and return error
+                if (workflowError) {
+                    await supabase.auth.updateUser({
+                        data: {
+                            backroom: {
+                                ...user.user_metadata.backroom,
+                                welcome_notification_sent: false,
+                                welcome_notification_timestamp: undefined
+                            }
+                        }
+                    });
+                    return { error: Exception.customError(code, workflowError) };
+                }
+                // Update user object in memory
+                user.user_metadata.backroom = updatedBackroom;
+            }
+        }
+        // Return empty object
+        return {};
+    }
+};
+/* EXCEPTION HELPERS */
+export const Exception = {
+    /**
+     * 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 },
+    /**
+     * 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
+     * @param {boolean} clientSafe - Whether to clamp 5xx errors down to 422 to prevent Sentry from capturing them as unhandled; defaults to `true`
+     * @returns An object with an `error` if any has occurred
+     */
+    parsePostgrestError: (postgrestError, clientSafe = true) => {
+        // Return undefined if no error occurred
+        let error;
+        if (!postgrestError)
+            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/
+        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) {
+            error = Exception.customError(statusCode, 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)) {
+                statusCode = clientSafe ? (status >= 500 ? 422 : status) : status;
+                error = Exception.customError(statusCode, Status.ERROR);
+                return { error };
+            }
+        // Return generic error
+        error = Exception.customError(clientSafe ? 422 : 500, Status.ERROR);
+        return { error };
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@koloseum/utils",
-	"version": "0.2.28",
+	"version": "0.3.0",
 	"author": "Koloseum Technologies Limited",
 	"type": "module",
 	"description": "Utility logic for use across Koloseum web apps (TypeScript)",
@@ -15,9 +15,31 @@
 		"type": "git",
 		"url": "git+https://github.com/koloseum-technologies/npm-utils.git"
 	},
-	"main": "./dist/utils.js",
 	"exports": {
-		".": "./dist/utils.js"
+		"./client": "./dist/client.js",
+		"./formatting": "./dist/formatting.js",
+		"./general": "./dist/general.js",
+		"./platform": "./dist/platform.js",
+		"./server": "./dist/server.js"
+	},
+	"typesVersions": {
+		"*": {
+			"client": [
+				"./dist/client.d.ts"
+			],
+			"formatting": [
+				"./dist/formatting.d.ts"
+			],
+			"general": [
+				"./dist/general.d.ts"
+			],
+			"platform": [
+				"./dist/platform.d.ts"
+			],
+			"server": [
+				"./dist/server.d.ts"
+			]
+		}
 	},
 	"files": [
 		"./dist/**/*"