@koloseum/utils 0.2.15 → 0.2.17

package/dist/utils.d.ts

@@ -250,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.
      *
@@ -279,3 +289,43 @@ export declare const Utility: {
      */
     validateSocialMediaHandle: (handle: string) => boolean;
 };
+export declare const Cache: {
+    /**
+     * Delete cached data from Valkey.
+     * @param valkey - The Valkey client instance
+     * @param cachePrefix - The cache prefix
+     * @param key - The cache key
+     */
+    deleteData: (valkey: any, cachePrefix: string, key: string) => Promise<void>;
+    /**
+     * Generate cache key with consistent formatting
+     * @param prefix - The key prefix
+     * @param params - Additional parameters to include in the key
+     * @returns The formatted cache key
+     */
+    generateDataKey: (prefix: string, ...params: (string | number)[]) => string;
+    /**
+     * Get cached data from Valkey.
+     * @param valkey - The Valkey client instance
+     * @param cachePrefix - The cache prefix
+     * @param key - The cache key
+     * @returns The cached data, or `null` if not found
+     */
+    getData: <T>(valkey: any, cachePrefix: string, key: string) => Promise<T | null>;
+    /**
+     * Invalidate cache by pattern
+     * @param valkey - The Valkey client instance
+     * @param cachePrefix - The cache prefix
+     * @param pattern - The pattern to match keys against (e.g., "app-config*")
+     */
+    invalidateDataByPattern: (valkey: any, cachePrefix: string, pattern: string) => Promise<void>;
+    /**
+     * Set data in Valkey cache.
+     * @param valkey - The Valkey client instance
+     * @param cachePrefix - The cache prefix
+     * @param key - The cache key
+     * @param data - The data to cache
+     * @param ttl - The time to live in seconds; defaults to 1 hour
+     */
+    setData: <T>(valkey: any, cachePrefix: string, key: string, data: T, ttl?: number) => Promise<void>;
+};

package/dist/utils.js

@@ -6,6 +6,8 @@ import validator from "validator";
 const parsePgInterval = (await import("postgres-interval")).default;
 const sanitize = (await import("sanitize-html")).default;
 const { trim, escape, isMobilePhone, isURL } = validator;
+// Cache constants
+const DEFAULT_TTL = 3600; // 1 hour in seconds
 const { KenyaAdministrativeDivisions } = (await import("kenya-administrative-divisions")).default;
 /* DUMMY DATA */
 export const Data = {
@@ -703,6 +705,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 +753,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 };
     },
@@ -1357,6 +1328,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.
      *
@@ -1477,3 +1509,76 @@ export const Utility = {
         !handle.startsWith("@") &&
         Boolean(handle.match(Utility.socialMediaHandleRegex))
 };
+/* CACHE FUNCTIONS */
+export const Cache = {
+    /**
+     * Delete cached data from Valkey.
+     * @param valkey - The Valkey client instance
+     * @param cachePrefix - The cache prefix
+     * @param key - The cache key
+     */
+    deleteData: async (valkey, cachePrefix, key) => {
+        try {
+            await valkey.del(`${cachePrefix}${key}`);
+        }
+        catch (error) {
+            console.error("Cache delete error:", error);
+        }
+    },
+    /**
+     * Generate cache key with consistent formatting
+     * @param prefix - The key prefix
+     * @param params - Additional parameters to include in the key
+     * @returns The formatted cache key
+     */
+    generateDataKey: (prefix, ...params) => `${prefix}:${params.join(":")}`,
+    /**
+     * Get cached data from Valkey.
+     * @param valkey - The Valkey client instance
+     * @param cachePrefix - The cache prefix
+     * @param key - The cache key
+     * @returns The cached data, or `null` if not found
+     */
+    getData: async (valkey, cachePrefix, key) => {
+        try {
+            const cached = await valkey.get(`${cachePrefix}${key}`);
+            return cached ? JSON.parse(cached) : null;
+        }
+        catch (error) {
+            console.error("Cache get error:", error);
+            return null;
+        }
+    },
+    /**
+     * Invalidate cache by pattern
+     * @param valkey - The Valkey client instance
+     * @param cachePrefix - The cache prefix
+     * @param pattern - The pattern to match keys against (e.g., "app-config*")
+     */
+    invalidateDataByPattern: async (valkey, cachePrefix, pattern) => {
+        try {
+            const keys = await valkey.keys(`${cachePrefix}${pattern}`);
+            if (keys.length > 0)
+                await valkey.del(...keys);
+        }
+        catch (error) {
+            console.error("Cache pattern invalidation error:", error);
+        }
+    },
+    /**
+     * Set data in Valkey cache.
+     * @param valkey - The Valkey client instance
+     * @param cachePrefix - The cache prefix
+     * @param key - The cache key
+     * @param data - The data to cache
+     * @param ttl - The time to live in seconds; defaults to 1 hour
+     */
+    setData: async (valkey, cachePrefix, key, data, ttl = DEFAULT_TTL) => {
+        try {
+            await valkey.setex(`${cachePrefix}${key}`, ttl, JSON.stringify(data));
+        }
+        catch (error) {
+            console.error("Cache set error:", error);
+        }
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@koloseum/utils",
-	"version": "0.2.15",
+	"version": "0.2.17",
 	"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",