@adventurelabs/scout-core 1.0.36 → 1.0.38

package/README.md

@@ -54,8 +54,48 @@ export default function ScoutLayout({
 
 ### Hooks
 
-- `useScoutDbListener` - Real-time database listening for plans, devices, and tags
+- `useScoutDbListener` - Real-time database listening for plans, devices, and tags with robust disconnect handling
 - `useScoutRefresh` - Data refresh utilities
+- `useConnectionStatus` - Connection status monitoring and manual reconnection controls
+
+#### Robust Connection Features
+
+The `useScoutDbListener` hook includes several features to handle network disconnections and connection issues:
+
+- **Automatic Reconnection**: Automatically attempts to reconnect when the connection is lost
+- **Exponential Backoff**: Uses exponential backoff with jitter to avoid overwhelming the server
+- **Connection State Tracking**: Provides real-time connection status (connected, connecting, disconnected, error)
+- **Error Handling**: Comprehensive error handling with detailed error messages
+- **Manual Reconnection**: Allows manual reconnection attempts via the `reconnect()` function
+- **Retry Limits**: Configurable maximum retry attempts to prevent infinite reconnection loops
+- **Graceful Cleanup**: Proper cleanup of resources when the component unmounts
+
+Example usage:
+
+```tsx
+import { useConnectionStatus } from "@adventurelabs/scout-core";
+
+function ConnectionStatus() {
+  const { isConnected, isConnecting, lastError, retryCount, reconnect } =
+    useConnectionStatus();
+
+  if (isConnecting) {
+    return <div>Connecting to database...</div>;
+  }
+
+  if (lastError) {
+    return (
+      <div>
+        <p>Connection error: {lastError}</p>
+        <p>Retry attempts: {retryCount}</p>
+        <button onClick={reconnect}>Reconnect</button>
+      </div>
+    );
+  }
+
+  return <div>Status: {isConnected ? "Connected" : "Disconnected"}</div>;
+}
+```
 
 ### Store
 

package/dist/hooks/useScoutDbListener.d.ts

@@ -1,3 +1,65 @@
 import { SupabaseClient } from "@supabase/supabase-js";
 import { Database } from "../types/supabase";
-export declare function useScoutDbListener(scoutSupabase: SupabaseClient<Database>): void;
+declare enum ConnectionState {
+    DISCONNECTED = "disconnected",
+    CONNECTING = "connecting",
+    CONNECTED = "connected",
+    ERROR = "error"
+}
+/**
+ * Hook for listening to real-time database changes with robust disconnect handling.
+ *
+ * Features:
+ * - Automatic reconnection with exponential backoff
+ * - Connection state tracking
+ * - Error handling and retry logic
+ * - Manual reconnection capability
+ *
+ * @param scoutSupabase - The Supabase client instance
+ * @returns Connection status and control functions
+ */
+export declare function useScoutDbListener(scoutSupabase: SupabaseClient<Database>): {
+    connectionState: ConnectionState;
+    lastError: string | null;
+    retryCount: number;
+    reconnect: () => void;
+    isConnected: boolean;
+    isConnecting: boolean;
+};
+export {};
+/**
+ * Return type for useScoutDbListener hook
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const {
+ *     isConnected,
+ *     isConnecting,
+ *     lastError,
+ *     retryCount,
+ *     reconnect
+ *   } = useConnectionStatus();
+ *
+ *   if (isConnecting) {
+ *     return <div>Connecting to database...</div>;
+ *   }
+ *
+ *   if (lastError) {
+ *     return (
+ *       <div>
+ *         <p>Connection error: {lastError}</p>
+ *         <p>Retry attempts: {retryCount}</p>
+ *         <button onClick={reconnect}>Reconnect</button>
+ *       </div>
+ *     );
+ *   }
+ *
+ *   if (!isConnected) {
+ *     return <div>Disconnected from database</div>;
+ *   }
+ *
+ *   return <div>Connected to database</div>;
+ * }
+ * ```
+ */

package/dist/hooks/useScoutDbListener.js

@@ -1,284 +1,327 @@
 "use client";
 import { useAppDispatch } from "../store/hooks";
-import { useEffect, useRef } from "react";
+import { useEffect, useRef, useState, useCallback } from "react";
 import { addDevice, addPlan, addTag, addSessionToStore, deleteDevice, deletePlan, deleteSessionFromStore, deleteTag, updateDevice, updatePlan, updateSessionInStore, updateTag, } from "../store/scout";
+// Connection state enum
+var ConnectionState;
+(function (ConnectionState) {
+    ConnectionState["DISCONNECTED"] = "disconnected";
+    ConnectionState["CONNECTING"] = "connecting";
+    ConnectionState["CONNECTED"] = "connected";
+    ConnectionState["ERROR"] = "error";
+})(ConnectionState || (ConnectionState = {}));
+// Reconnection configuration
+const RECONNECTION_CONFIG = {
+    MAX_RETRIES: 10,
+    INITIAL_DELAY: 1000, // 1 second
+    MAX_DELAY: 30000, // 30 seconds
+    BACKOFF_MULTIPLIER: 2,
+    JITTER_FACTOR: 0.1, // 10% jitter
+};
+/**
+ * Hook for listening to real-time database changes with robust disconnect handling.
+ *
+ * Features:
+ * - Automatic reconnection with exponential backoff
+ * - Connection state tracking
+ * - Error handling and retry logic
+ * - Manual reconnection capability
+ *
+ * @param scoutSupabase - The Supabase client instance
+ * @returns Connection status and control functions
+ */
 export function useScoutDbListener(scoutSupabase) {
     const supabase = useRef(null);
     const channels = useRef([]);
     const dispatch = useAppDispatch();
-    function handleTagInserts(payload) {
-        console.log("[DB Listener] Tag INSERT received:", payload);
-        // Broadcast payload contains the record directly
-        const tagData = payload.new || payload;
-        dispatch(addTag(tagData));
-    }
-    function handleTagDeletes(payload) {
-        console.log("[DB Listener] Tag DELETE received:", payload);
-        console.log("[DB Listener] Tag DELETE - payload structure:", {
-            hasOld: !!payload.old,
-            oldId: payload.old?.id,
-            oldEventId: payload.old?.event_id,
-            oldClassName: payload.old?.class_name,
-            fullPayload: payload,
+    // Connection state management
+    const [connectionState, setConnectionState] = useState(ConnectionState.DISCONNECTED);
+    const [lastError, setLastError] = useState(null);
+    const [retryCount, setRetryCount] = useState(0);
+    // Reconnection management
+    const reconnectTimeoutRef = useRef(null);
+    const isInitializingRef = useRef(false);
+    const isDestroyedRef = useRef(false);
+    // Calculate exponential backoff delay with jitter
+    const calculateBackoffDelay = useCallback((attempt) => {
+        const baseDelay = Math.min(RECONNECTION_CONFIG.INITIAL_DELAY *
+            Math.pow(RECONNECTION_CONFIG.BACKOFF_MULTIPLIER, attempt), RECONNECTION_CONFIG.MAX_DELAY);
+        const jitter = baseDelay * RECONNECTION_CONFIG.JITTER_FACTOR * (Math.random() - 0.5);
+        return Math.max(100, baseDelay + jitter); // Minimum 100ms delay
+    }, []);
+    // Clean up all channels
+    const cleanupChannels = useCallback(() => {
+        console.log("[DB Listener] 🧹 Cleaning up channels");
+        channels.current.forEach((channel) => {
+            if (channel && supabase.current) {
+                try {
+                    supabase.current.removeChannel(channel);
+                }
+                catch (error) {
+                    console.warn("[DB Listener] Error removing channel:", error);
+                }
+            }
         });
-        // Broadcast payload contains the old record
-        const tagData = payload.old || payload;
-        if (!tagData || !tagData.id) {
-            console.error("[DB Listener] Tag DELETE - Invalid payload, missing tag data");
-            return;
-        }
-        console.log("[DB Listener] Tag DELETE - Dispatching deleteTag action with ID:", tagData.id);
-        dispatch(deleteTag(tagData));
-    }
-    function handleTagUpdates(payload) {
-        console.log("[DB Listener] Tag UPDATE received:", payload);
-        // Broadcast payload contains the new record
-        const tagData = payload.new || payload;
-        dispatch(updateTag(tagData));
-    }
-    async function handleDeviceInserts(payload) {
-        console.log("[DB Listener] Device INSERT received:", payload);
-        // Broadcast payload contains the record directly
-        const deviceData = payload.new || payload;
-        dispatch(addDevice(deviceData));
-    }
-    function handleDeviceDeletes(payload) {
-        console.log("[DB Listener] Device DELETE received:", payload);
-        // Broadcast payload contains the old record
-        const deviceData = payload.old || payload;
-        dispatch(deleteDevice(deviceData));
-    }
-    async function handleDeviceUpdates(payload) {
-        console.log("[DB Listener] Device UPDATE received:", payload);
-        // Broadcast payload contains the new record
-        const deviceData = payload.new || payload;
-        dispatch(updateDevice(deviceData));
-    }
-    function handlePlanInserts(payload) {
-        console.log("[DB Listener] Plan INSERT received:", payload);
-        // Broadcast payload contains the record directly
-        const planData = payload.new || payload;
-        dispatch(addPlan(planData));
-    }
-    function handlePlanDeletes(payload) {
-        console.log("[DB Listener] Plan DELETE received:", payload);
-        // Broadcast payload contains the old record
-        const planData = payload.old || payload;
-        dispatch(deletePlan(planData));
-    }
-    function handlePlanUpdates(payload) {
-        console.log("[DB Listener] Plan UPDATE received:", payload);
-        // Broadcast payload contains the new record
-        const planData = payload.new || payload;
-        dispatch(updatePlan(planData));
-    }
-    function handleSessionInserts(payload) {
-        console.log("[DB Listener] Session INSERT received:", payload);
-        // Broadcast payload contains the record directly
-        const sessionData = payload.new || payload;
-        dispatch(addSessionToStore(sessionData));
-    }
-    function handleSessionDeletes(payload) {
-        console.log("[DB Listener] Session DELETE received:", payload);
-        // Broadcast payload contains the old record
-        const sessionData = payload.old || payload;
-        dispatch(deleteSessionFromStore(sessionData));
-    }
-    function handleSessionUpdates(payload) {
-        console.log("[DB Listener] Session UPDATE received:", payload);
-        // Broadcast payload contains the new record
-        const sessionData = payload.new || payload;
-        dispatch(updateSessionInStore(sessionData));
-    }
-    function handleConnectivityInserts(payload) {
-        console.log("[DB Listener] Connectivity INSERT received:", payload);
-        // For now, we'll just log connectivity changes since they're related to sessions
-        // In the future, we might want to update session connectivity data
-    }
-    function handleConnectivityDeletes(payload) {
-        console.log("[DB Listener] Connectivity DELETE received:", payload);
-        // For now, we'll just log connectivity changes since they're related to sessions
-        // In the future, we might want to update session connectivity data
-    }
-    function handleConnectivityUpdates(payload) {
-        console.log("[DB Listener] Connectivity UPDATE received:", payload);
-        // For now, we'll just log connectivity changes since they're related to sessions
-        // In the future, we might want to update session connectivity data
-    }
-    useEffect(() => {
-        console.log("=== SCOUT DB LISTENER DEBUG ===");
-        console.log("[DB Listener] Using shared Supabase client from ScoutRefreshProvider context");
-        if (!scoutSupabase) {
-            console.error("[DB Listener] No Supabase client available from ScoutRefreshProvider context");
-            return;
+        channels.current = [];
+    }, []);
+    // Cancel any pending reconnection attempts
+    const cancelReconnection = useCallback(() => {
+        if (reconnectTimeoutRef.current) {
+            clearTimeout(reconnectTimeoutRef.current);
+            reconnectTimeoutRef.current = null;
         }
-        supabase.current = scoutSupabase;
-        // Test authentication first
-        const testAuth = async () => {
-            try {
-                const { data: { user }, error, } = await scoutSupabase.auth.getUser();
-                console.log("[DB Listener] Auth test - User:", user ? "authenticated" : "anonymous");
-                console.log("[DB Listener] Auth test - Error:", error);
+    }, []);
+    // Test database connection
+    const testDbConnection = useCallback(async () => {
+        if (!supabase.current)
+            return false;
+        try {
+            const { data, error } = await supabase.current
+                .from("tags")
+                .select("count")
+                .limit(1);
+            if (error) {
+                console.warn("[DB Listener] DB connection test failed:", error);
+                return false;
             }
-            catch (err) {
-                console.warn("[DB Listener] Auth test failed:", err);
+            console.log("[DB Listener] ✅ DB connection test successful");
+            return true;
+        }
+        catch (err) {
+            console.error("[DB Listener] DB connection test failed:", err);
+            return false;
+        }
+    }, []);
+    // Set up realtime authentication
+    const setupRealtimeAuth = useCallback(async () => {
+        if (!supabase.current)
+            return false;
+        try {
+            await supabase.current.realtime.setAuth();
+            console.log("[DB Listener] ✅ Realtime authentication set up successfully");
+            return true;
+        }
+        catch (err) {
+            console.warn("[DB Listener] ❌ Failed to set up realtime authentication:", err);
+            return false;
+        }
+    }, []);
+    // Generic event handler factory
+    const createEventHandler = useCallback((action, dataKey, entityName) => {
+        return (payload) => {
+            console.log(`[DB Listener] ${entityName} ${payload.event} received:`, payload);
+            const data = payload[dataKey];
+            if (!data) {
+                console.error(`[DB Listener] ${entityName} ${payload.event} - Invalid payload, missing ${dataKey} data`);
+                return;
             }
+            action(data);
         };
-        testAuth();
-        // Set up authentication for Realtime Authorization (required for broadcast)
-        const setupRealtimeAuth = async () => {
+    }, []);
+    // Create event handlers using the factory
+    const handlers = useCallback(() => ({
+        tags: {
+            INSERT: createEventHandler(dispatch.bind(null, addTag), "new", "Tag"),
+            UPDATE: createEventHandler(dispatch.bind(null, updateTag), "new", "Tag"),
+            DELETE: createEventHandler(dispatch.bind(null, deleteTag), "old", "Tag"),
+        },
+        devices: {
+            INSERT: createEventHandler(dispatch.bind(null, addDevice), "new", "Device"),
+            UPDATE: createEventHandler(dispatch.bind(null, updateDevice), "new", "Device"),
+            DELETE: createEventHandler(dispatch.bind(null, deleteDevice), "old", "Device"),
+        },
+        plans: {
+            INSERT: createEventHandler(dispatch.bind(null, addPlan), "new", "Plan"),
+            UPDATE: createEventHandler(dispatch.bind(null, updatePlan), "new", "Plan"),
+            DELETE: createEventHandler(dispatch.bind(null, deletePlan), "old", "Plan"),
+        },
+        sessions: {
+            INSERT: createEventHandler(dispatch.bind(null, addSessionToStore), "new", "Session"),
+            UPDATE: createEventHandler(dispatch.bind(null, updateSessionInStore), "new", "Session"),
+            DELETE: createEventHandler(dispatch.bind(null, deleteSessionFromStore), "old", "Session"),
+        },
+        connectivity: {
+            INSERT: (payload) => console.log("[DB Listener] Connectivity INSERT received:", payload),
+            UPDATE: (payload) => console.log("[DB Listener] Connectivity UPDATE received:", payload),
+            DELETE: (payload) => console.log("[DB Listener] Connectivity DELETE received:", payload),
+        },
+    }), [createEventHandler, dispatch]);
+    // Create a channel with proper error handling
+    const createChannel = useCallback((tableName) => {
+        if (!supabase.current)
+            return null;
+        const channelName = `scout_broadcast_${tableName}_${Date.now()}`;
+        console.log(`[DB Listener] Creating broadcast channel for ${tableName}:`, channelName);
+        try {
+            const channel = supabase.current.channel(channelName, {
+                config: { private: true },
+            });
+            // Add system event handlers for connection monitoring
+            channel
+                .on("system", { event: "disconnect" }, () => {
+                console.log(`[DB Listener] 🔌 ${tableName} channel disconnected`);
+                setConnectionState(ConnectionState.DISCONNECTED);
+                setLastError("Channel disconnected");
+            })
+                .on("system", { event: "reconnect" }, () => {
+                console.log(`[DB Listener] 🔗 ${tableName} channel reconnected`);
+            })
+                .on("system", { event: "error" }, (error) => {
+                console.warn(`[DB Listener] ❌ ${tableName} channel error:`, error);
+                setLastError(`Channel error: ${error}`);
+            });
+            return channel;
+        }
+        catch (error) {
+            console.error(`[DB Listener] Failed to create ${tableName} channel:`, error);
+            return null;
+        }
+    }, []);
+    // Set up all channels
+    const setupChannels = useCallback(async () => {
+        if (!supabase.current)
+            return false;
+        cleanupChannels();
+        const tableHandlers = handlers();
+        const tables = Object.keys(tableHandlers);
+        let successCount = 0;
+        const totalChannels = tables.length;
+        for (const tableName of tables) {
+            const channel = createChannel(tableName);
+            if (!channel)
+                continue;
             try {
-                await scoutSupabase.realtime.setAuth();
-                console.log("[DB Listener] ✅ Realtime authentication set up successfully");
+                // Set up event handlers
+                const tableHandler = tableHandlers[tableName];
+                Object.entries(tableHandler).forEach(([event, handler]) => {
+                    channel.on("broadcast", { event }, handler);
+                });
+                // Subscribe to the channel
+                channel.subscribe((status) => {
+                    console.log(`[DB Listener] ${tableName} channel status:`, status);
+                    if (status === "SUBSCRIBED") {
+                        successCount++;
+                        if (successCount === totalChannels) {
+                            setConnectionState(ConnectionState.CONNECTED);
+                            setRetryCount(0);
+                            setLastError(null);
+                            console.log("[DB Listener] ✅ All channels successfully subscribed");
+                        }
+                    }
+                    else if (status === "CHANNEL_ERROR" || status === "TIMED_OUT") {
+                        console.error(`[DB Listener] ${tableName} channel failed to subscribe:`, status);
+                        setLastError(`Channel subscription failed: ${status}`);
+                    }
+                });
+                channels.current.push(channel);
             }
-            catch (err) {
-                console.warn("[DB Listener] ❌ Failed to set up realtime authentication:", err);
+            catch (error) {
+                console.error(`[DB Listener] Failed to set up ${tableName} channel:`, error);
             }
-        };
-        setupRealtimeAuth();
-        // Create channels for each table using broadcast
-        const createBroadcastChannel = (tableName) => {
-            const channelName = `scout_broadcast_${tableName}_${Date.now()}`;
-            console.log(`[DB Listener] Creating broadcast channel for ${tableName}:`, channelName);
-            return scoutSupabase.channel(channelName, {
-                config: { private: true }, // Required for broadcast with Realtime Authorization
-            });
-        };
-        // Plans channel
-        const plansChannel = createBroadcastChannel("plans");
-        plansChannel
-            .on("broadcast", { event: "INSERT" }, (payload) => {
-            console.log("[DB Listener] Plans INSERT received:", payload);
-            handlePlanInserts(payload);
-        })
-            .on("broadcast", { event: "UPDATE" }, (payload) => {
-            console.log("[DB Listener] Plans UPDATE received:", payload);
-            handlePlanUpdates(payload);
-        })
-            .on("broadcast", { event: "DELETE" }, (payload) => {
-            console.log("[DB Listener] Plans DELETE received:", payload);
-            handlePlanDeletes(payload);
-        })
-            .subscribe((status) => {
-            console.log(`[DB Listener] Plans channel status:`, status);
-        });
-        // Devices channel
-        const devicesChannel = createBroadcastChannel("devices");
-        devicesChannel
-            .on("broadcast", { event: "INSERT" }, (payload) => {
-            console.log("[DB Listener] Devices INSERT received:", payload);
-            handleDeviceInserts(payload);
-        })
-            .on("broadcast", { event: "UPDATE" }, (payload) => {
-            console.log("[DB Listener] Devices UPDATE received:", payload);
-            handleDeviceUpdates(payload);
-        })
-            .on("broadcast", { event: "DELETE" }, (payload) => {
-            console.log("[DB Listener] Devices DELETE received:", payload);
-            handleDeviceDeletes(payload);
-        })
-            .subscribe((status) => {
-            console.log(`[DB Listener] Devices channel status:`, status);
-        });
-        // Tags channel
-        const tagsChannel = createBroadcastChannel("tags");
-        tagsChannel
-            .on("broadcast", { event: "INSERT" }, (payload) => {
-            console.log("[DB Listener] Tags INSERT received:", payload);
-            handleTagInserts(payload);
-        })
-            .on("broadcast", { event: "UPDATE" }, (payload) => {
-            console.log("[DB Listener] Tags UPDATE received:", payload);
-            handleTagUpdates(payload);
-        })
-            .on("broadcast", { event: "DELETE" }, (payload) => {
-            console.log("[DB Listener] Tags DELETE received:", payload);
-            handleTagDeletes(payload);
-        })
-            .subscribe((status) => {
-            console.log(`[DB Listener] Tags channel status:`, status);
-        });
-        // Sessions channel
-        const sessionsChannel = createBroadcastChannel("sessions");
-        sessionsChannel
-            .on("broadcast", { event: "INSERT" }, (payload) => {
-            console.log("[DB Listener] Sessions INSERT received:", payload);
-            handleSessionInserts(payload);
-        })
-            .on("broadcast", { event: "UPDATE" }, (payload) => {
-            console.log("[DB Listener] Sessions UPDATE received:", payload);
-            handleSessionUpdates(payload);
-        })
-            .on("broadcast", { event: "DELETE" }, (payload) => {
-            console.log("[DB Listener] Sessions DELETE received:", payload);
-            handleSessionDeletes(payload);
-        })
-            .subscribe((status) => {
-            console.log(`[DB Listener] Sessions channel status:`, status);
-        });
-        // Connectivity channel
-        const connectivityChannel = createBroadcastChannel("connectivity");
-        connectivityChannel
-            .on("broadcast", { event: "INSERT" }, (payload) => {
-            console.log("[DB Listener] Connectivity INSERT received:", payload);
-            handleConnectivityInserts(payload);
-        })
-            .on("broadcast", { event: "UPDATE" }, (payload) => {
-            console.log("[DB Listener] Connectivity UPDATE received:", payload);
-            handleConnectivityUpdates(payload);
-        })
-            .on("broadcast", { event: "DELETE" }, (payload) => {
-            console.log("[DB Listener] Connectivity DELETE received:", payload);
-            handleConnectivityDeletes(payload);
-        })
-            .subscribe((status) => {
-            console.log(`[DB Listener] Connectivity channel status:`, status);
-        });
-        // Add all channels to the channels array
-        channels.current.push(plansChannel, devicesChannel, tagsChannel, sessionsChannel, connectivityChannel);
-        // Test the connection with system events
-        const testChannelName = `test_connection_${Date.now()}`;
-        console.log("[DB Listener] Creating test channel:", testChannelName);
-        const testChannel = scoutSupabase.channel(testChannelName);
-        testChannel
-            .on("system", { event: "disconnect" }, () => {
-            console.log("[DB Listener] 🔌 Disconnected from Supabase");
-        })
-            .on("system", { event: "reconnect" }, () => {
-            console.log("[DB Listener] 🔗 Reconnected to Supabase");
-        })
-            .on("system", { event: "error" }, (error) => {
-            console.warn("[DB Listener] ❌ System error:", error);
-        })
-            .subscribe((status) => {
-            console.log("[DB Listener] Test channel status:", status);
-        });
-        channels.current.push(testChannel);
-        // Test a simple database query to verify connection
-        const testDbConnection = async () => {
-            try {
-                const { data, error } = await scoutSupabase
-                    .from("tags")
-                    .select("count")
-                    .limit(1);
-                console.log("[DB Listener] DB connection test - Success:", !!data);
-                console.log("[DB Listener] DB connection test - Error:", error);
+        }
+        return successCount > 0;
+    }, [cleanupChannels, createChannel, handlers]);
+    // Schedule reconnection with exponential backoff
+    const scheduleReconnection = useCallback(() => {
+        if (isDestroyedRef.current ||
+            retryCount >= RECONNECTION_CONFIG.MAX_RETRIES) {
+            console.log("[DB Listener] Max reconnection attempts reached or hook destroyed");
+            setConnectionState(ConnectionState.ERROR);
+            return;
+        }
+        const delay = calculateBackoffDelay(retryCount);
+        console.log(`[DB Listener] Scheduling reconnection attempt ${retryCount + 1} in ${delay}ms`);
+        reconnectTimeoutRef.current = setTimeout(() => {
+            if (!isDestroyedRef.current) {
+                initializeConnection();
+            }
+        }, delay);
+    }, [retryCount, calculateBackoffDelay]);
+    // Initialize connection
+    const initializeConnection = useCallback(async () => {
+        if (isDestroyedRef.current || isInitializingRef.current)
+            return;
+        isInitializingRef.current = true;
+        setConnectionState(ConnectionState.CONNECTING);
+        try {
+            console.log("[DB Listener] 🔄 Initializing connection...");
+            // Test database connection
+            const dbConnected = await testDbConnection();
+            if (!dbConnected) {
+                throw new Error("Database connection test failed");
             }
-            catch (err) {
-                console.error("[DB Listener] DB connection test failed:", err);
+            // Set up realtime authentication
+            const authSuccess = await setupRealtimeAuth();
+            if (!authSuccess) {
+                throw new Error("Realtime authentication failed");
             }
-        };
-        testDbConnection();
-        console.log("=== END SCOUT DB LISTENER DEBUG ===");
+            // Set up channels
+            const channelsSuccess = await setupChannels();
+            if (!channelsSuccess) {
+                throw new Error("Channel setup failed");
+            }
+            console.log("[DB Listener] ✅ Connection initialized successfully");
+        }
+        catch (error) {
+            console.error("[DB Listener] ❌ Connection initialization failed:", error);
+            setLastError(error instanceof Error ? error.message : "Unknown error");
+            setConnectionState(ConnectionState.ERROR);
+            setRetryCount((prev) => prev + 1);
+            // Schedule reconnection
+            scheduleReconnection();
+        }
+        finally {
+            isInitializingRef.current = false;
+        }
+    }, [
+        testDbConnection,
+        setupRealtimeAuth,
+        setupChannels,
+        scheduleReconnection,
+    ]);
+    // Manual reconnection function
+    const reconnect = useCallback(() => {
+        if (isDestroyedRef.current)
+            return;
+        console.log("[DB Listener] 🔄 Manual reconnection requested");
+        cancelReconnection();
+        setRetryCount(0);
+        setLastError(null);
+        initializeConnection();
+    }, [cancelReconnection, initializeConnection]);
+    // Main effect
+    useEffect(() => {
+        console.log("=== SCOUT DB LISTENER INITIALIZATION ===");
+        if (!scoutSupabase) {
+            console.error("[DB Listener] No Supabase client available");
+            setConnectionState(ConnectionState.ERROR);
+            setLastError("No Supabase client available");
+            return;
+        }
+        supabase.current = scoutSupabase;
+        isDestroyedRef.current = false;
+        // Initialize connection
+        initializeConnection();
         // Cleanup function
         return () => {
-            console.log("[DB Listener] 🧹 Cleaning up channels");
-            channels.current.forEach((channel) => {
-                if (channel) {
-                    scoutSupabase.removeChannel(channel);
-                }
-            });
-            channels.current = [];
+            console.log("[DB Listener] 🧹 Cleaning up hook");
+            isDestroyedRef.current = true;
+            cancelReconnection();
+            cleanupChannels();
         };
-    }, [scoutSupabase, dispatch]);
+    }, [
+        scoutSupabase,
+        initializeConnection,
+        cancelReconnection,
+        cleanupChannels,
+    ]);
+    // Return connection state and manual reconnect function
+    return {
+        connectionState,
+        lastError,
+        retryCount,
+        reconnect,
+        isConnected: connectionState === ConnectionState.CONNECTED,
+        isConnecting: connectionState === ConnectionState.CONNECTING,
+    };
 }

package/dist/providers/ScoutRefreshProvider.d.ts

@@ -1,6 +1,13 @@
 import { ReactNode } from "react";
 import { SupabaseClient } from "@supabase/supabase-js";
 import { Database } from "../types/supabase";
+interface ConnectionStatus {
+    isConnected: boolean;
+    isConnecting: boolean;
+    lastError: string | null;
+    retryCount: number;
+    reconnect: () => void;
+}
 export declare function useSupabase(): SupabaseClient<Database, "public", {
     Tables: {
         actions: {
@@ -883,7 +890,9 @@ export declare function useSupabase(): SupabaseClient<Database, "public", {
         };
     };
 }>;
+export declare function useConnectionStatus(): ConnectionStatus;
 export interface ScoutRefreshProviderProps {
     children: ReactNode;
 }
 export declare function ScoutRefreshProvider({ children }: ScoutRefreshProviderProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/providers/ScoutRefreshProvider.js

@@ -6,6 +6,7 @@ import { createContext, useContext, useRef } from "react";
 import { createBrowserClient } from "@supabase/ssr";
 // Create context for the Supabase client
 const SupabaseContext = createContext(null);
+const ConnectionStatusContext = createContext(null);
 // Hook to use the Supabase client
 export function useSupabase() {
     const supabase = useContext(SupabaseContext);
@@ -14,6 +15,14 @@ export function useSupabase() {
     }
     return supabase;
 }
+// Hook to use connection status
+export function useConnectionStatus() {
+    const connectionStatus = useContext(ConnectionStatusContext);
+    if (!connectionStatus) {
+        throw new Error("useConnectionStatus must be used within a ScoutRefreshProvider");
+    }
+    return connectionStatus;
+}
 export function ScoutRefreshProvider({ children }) {
     const url = process.env.NEXT_PUBLIC_SUPABASE_URL || "";
     const anon_key = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY || "";
@@ -23,7 +32,18 @@ export function ScoutRefreshProvider({ children }) {
         supabaseRef.current = createBrowserClient(url, anon_key);
         console.log("[ScoutRefreshProvider] Created Supabase client");
     }
+    // Use the enhanced DB listener with connection status
     useScoutDbListener(supabaseRef.current);
     useScoutRefresh();
+    // // Log connection status changes for debugging
+    // if (connectionStatus.lastError) {
+    //   console.warn(
+    //     "[ScoutRefreshProvider] DB Listener error:",
+    //     connectionStatus.lastError
+    //   );
+    // }
+    // if (connectionStatus.isConnected) {
+    //   console.log("[ScoutRefreshProvider] ✅ DB Listener connected");
+    // }
     return (_jsx(SupabaseContext.Provider, { value: supabaseRef.current, children: children }));
 }

package/dist/store/scout.js

@@ -68,7 +68,10 @@ export const scoutSlice = createSlice({
         addTag(state, action) {
             for (const herd_module of state.herd_modules) {
                 for (const event of herd_module.events) {
-                    if (event.id === action.payload.event_id && event.tags) {
+                    if (event.id === action.payload.event_id) {
+                        if (event.tags == undefined || event.tags == null) {
+                            event.tags = [];
+                        }
                         event.tags.push(action.payload);
                         return;
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adventurelabs/scout-core",
-  "version": "1.0.36",
+  "version": "1.0.38",
   "description": "Core utilities and helpers for Adventure Labs Scout applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",