@koloseum/utils 0.2.14 → 0.2.16

package/dist/utils.d.ts

@@ -223,9 +223,10 @@ export declare const Utility: {
     /**
      * 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) => {
+    parsePostgrestError: (postgrestError: PostgrestError | null, clientSafe?: boolean) => {
         error?: CustomError;
     };
     /**
@@ -249,6 +250,16 @@ export declare const Utility: {
      * @returns A sanitised string, or an empty string if the input is invalid
      */
     sanitiseHtml: (input: string) => string;
+    /**
+     * Sends a welcome notification to a 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;
+    }>;
     /**
      * A regular expression for social media handles, without a leading slash or @ character.
      *

package/dist/utils.js

@@ -703,6 +703,9 @@ export const Utility = {
         // 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: Utility.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);
@@ -748,43 +751,9 @@ export const Utility = {
         if (validationError)
             return { error: Utility.customError(code, validationError) };
         // Send welcome notification if needed
-        if (!user.user_metadata.backroom || !user.user_metadata.backroom.welcome_notification_sent) {
-            // Initialise backroom metadata if it doesn't exist
-            if (!user.user_metadata.backroom) {
-                // Update user metadata in database
-                const { error: updateError } = await supabase.auth.updateUser({
-                    data: { backroom: { welcome_notification_sent: false } }
-                });
-                if (updateError)
-                    return { error: Utility.customError(updateError.status ?? 500, updateError.message) };
-                // Update user object in memory
-                user.user_metadata.backroom = { welcome_notification_sent: false };
-            }
-            // 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 Utility.callEdgeFunction(false, supabase, `suprsend/trigger-workflow?user-id=${user.id}`, { method: "POST", body: workflowBody });
-            if (workflowError)
-                return { error: Utility.customError(code, workflowError) };
-            // Update user metadata in database
-            const { error: updateError } = await supabase.auth.updateUser({
-                data: { backroom: { welcome_notification_sent: true } }
-            });
-            if (updateError)
-                return { error: Utility.customError(updateError.status ?? 500, updateError.message) };
-            // Update user object in memory
-            user.user_metadata.backroom.welcome_notification_sent = true;
-        }
+        const { error: welcomeError } = await Utility.sendWelcomeNotification(supabase, user, microserviceGroup);
+        if (welcomeError)
+            return { error: welcomeError };
         // Return result
         return { isAuthorised };
     },
@@ -1268,17 +1237,21 @@ export const Utility = {
     /**
      * 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) => {
+    parsePostgrestError: (postgrestError, clientSafe = true) => {
         // Return undefined if no error occurred
         let error;
         if (!postgrestError)
             return { error };
-        // Return custom error if hint is a number between 400 and 599
+        // 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 = Utility.customError(customErrorCode, postgrestError.message);
+            error = Utility.customError(statusCode, postgrestError.message);
             return { error };
         }
         // Map Postgrest error codes to custom error codes
@@ -1316,11 +1289,12 @@ export const Utility = {
         // 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);
+                statusCode = clientSafe ? (status >= 500 ? 422 : status) : status;
+                error = Utility.customError(statusCode, Status.ERROR);
                 return { error };
             }
         // Return generic error
-        error = Utility.customError(500, Status.ERROR);
+        error = Utility.customError(clientSafe ? 422 : 500, Status.ERROR);
         return { error };
     },
     /**
@@ -1352,6 +1326,67 @@ export const Utility = {
      * @returns A sanitised string, or an empty string if the input is invalid
      */
     sanitiseHtml: (input) => typeof input !== "string" ? "" : sanitize(input, { allowedTags: [], allowedAttributes: {} }),
+    /**
+     * Sends a welcome notification to a 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: Utility.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 Utility.callEdgeFunction(false, supabase, `suprsend/trigger-workflow?user-id=${user.id}`, { method: "POST", 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: Utility.customError(code, workflowError) };
+                }
+                // Update user object in memory
+                user.user_metadata.backroom = updatedBackroom;
+            }
+        }
+        // Return empty object
+        return {};
+    },
     /**
      * A regular expression for social media handles, without a leading slash or @ character.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@koloseum/utils",
-	"version": "0.2.14",
+	"version": "0.2.16",
 	"author": "Koloseum Technologies Limited",
 	"type": "module",
 	"description": "Utility logic for use across Koloseum web apps (TypeScript)",
@@ -38,7 +38,7 @@
 		"validator": "^13.15.15"
 	},
 	"devDependencies": {
-		"@koloseum/types": "^0.2.4",
+		"@koloseum/types": "^0.2.5",
 		"@playwright/test": "^1.53.1",
 		"@suprsend/web-components": "^0.2.1",
 		"@types/sanitize-html": "^2.16.0",