@adventurelabs/scout-core 1.0.35 → 1.0.37

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,30 @@
 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",
+    RECONNECTING = "reconnecting",
+    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 {};

package/dist/hooks/useScoutDbListener.js

@@ -1,188 +1,461 @@
 "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["RECONNECTING"] = "reconnecting";
+    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.new);
-        dispatch(addTag(payload.new));
-    }
-    function handleTagDeletes(payload) {
-        console.log("[DB Listener] Tag DELETE received:", payload.old);
-        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);
+                }
+            }
         });
+        channels.current = [];
+    }, []);
+    // Cancel any pending reconnection attempts
+    const cancelReconnection = useCallback(() => {
+        if (reconnectTimeoutRef.current) {
+            clearTimeout(reconnectTimeoutRef.current);
+            reconnectTimeoutRef.current = null;
+        }
+    }, []);
+    // 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;
+            }
+            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;
+        }
+    }, []);
+    // Event handlers
+    const handleTagInserts = useCallback((payload) => {
+        console.log("[DB Listener] Tag INSERT received:", payload);
+        if (!payload.new) {
+            console.error("[DB Listener] Tag INSERT - Invalid payload, missing new data");
+            return;
+        }
+        dispatch(addTag(payload.new));
+    }, [dispatch]);
+    const handleTagDeletes = useCallback((payload) => {
+        console.log("[DB Listener] Tag DELETE received:", payload);
         if (!payload.old || !payload.old.id) {
             console.error("[DB Listener] Tag DELETE - Invalid payload, missing tag data");
             return;
         }
-        console.log("[DB Listener] Tag DELETE - Dispatching deleteTag action with ID:", payload.old.id);
         dispatch(deleteTag(payload.old));
-    }
-    function handleTagUpdates(payload) {
-        console.log("[DB Listener] Tag UPDATE received:", payload.new);
+    }, [dispatch]);
+    const handleTagUpdates = useCallback((payload) => {
+        console.log("[DB Listener] Tag UPDATE received:", payload);
+        if (!payload.new) {
+            console.error("[DB Listener] Tag UPDATE - Invalid payload, missing new data");
+            return;
+        }
         dispatch(updateTag(payload.new));
-    }
-    async function handleDeviceInserts(payload) {
-        console.log("[DB Listener] Device INSERT received:", payload.new);
-        // For now, just dispatch the raw payload since we don't have the device helper
+    }, [dispatch]);
+    const handleDeviceInserts = useCallback((payload) => {
+        console.log("[DB Listener] Device INSERT received:", payload);
+        if (!payload.new) {
+            console.error("[DB Listener] Device INSERT - Invalid payload, missing new data");
+            return;
+        }
         dispatch(addDevice(payload.new));
-    }
-    function handleDeviceDeletes(payload) {
-        console.log("[DB Listener] Device DELETE received:", payload.old);
+    }, [dispatch]);
+    const handleDeviceDeletes = useCallback((payload) => {
+        console.log("[DB Listener] Device DELETE received:", payload);
+        if (!payload.old) {
+            console.error("[DB Listener] Device DELETE - Invalid payload, missing old data");
+            return;
+        }
         dispatch(deleteDevice(payload.old));
-    }
-    async function handleDeviceUpdates(payload) {
-        console.log("[DB Listener] Device UPDATE received:", payload.new);
-        // For now, just dispatch the raw payload since we don't have the device helper
+    }, [dispatch]);
+    const handleDeviceUpdates = useCallback((payload) => {
+        console.log("[DB Listener] Device UPDATE received:", payload);
+        if (!payload.new) {
+            console.error("[DB Listener] Device UPDATE - Invalid payload, missing new data");
+            return;
+        }
         dispatch(updateDevice(payload.new));
-    }
-    function handlePlanInserts(payload) {
-        console.log("[DB Listener] Plan INSERT received:", payload.new);
+    }, [dispatch]);
+    const handlePlanInserts = useCallback((payload) => {
+        console.log("[DB Listener] Plan INSERT received:", payload);
+        if (!payload.new) {
+            console.error("[DB Listener] Plan INSERT - Invalid payload, missing new data");
+            return;
+        }
         dispatch(addPlan(payload.new));
-    }
-    function handlePlanDeletes(payload) {
-        console.log("[DB Listener] Plan DELETE received:", payload.old);
+    }, [dispatch]);
+    const handlePlanDeletes = useCallback((payload) => {
+        console.log("[DB Listener] Plan DELETE received:", payload);
+        if (!payload.old) {
+            console.error("[DB Listener] Plan DELETE - Invalid payload, missing old data");
+            return;
+        }
         dispatch(deletePlan(payload.old));
-    }
-    function handlePlanUpdates(payload) {
-        console.log("[DB Listener] Plan UPDATE received:", payload.new);
+    }, [dispatch]);
+    const handlePlanUpdates = useCallback((payload) => {
+        console.log("[DB Listener] Plan UPDATE received:", payload);
+        if (!payload.new) {
+            console.error("[DB Listener] Plan UPDATE - Invalid payload, missing new data");
+            return;
+        }
         dispatch(updatePlan(payload.new));
-    }
-    function handleSessionInserts(payload) {
-        console.log("[DB Listener] Session INSERT received:", payload.new);
+    }, [dispatch]);
+    const handleSessionInserts = useCallback((payload) => {
+        console.log("[DB Listener] Session INSERT received:", payload);
+        if (!payload.new) {
+            console.error("[DB Listener] Session INSERT - Invalid payload, missing new data");
+            return;
+        }
         dispatch(addSessionToStore(payload.new));
-    }
-    function handleSessionDeletes(payload) {
-        console.log("[DB Listener] Session DELETE received:", payload.old);
+    }, [dispatch]);
+    const handleSessionDeletes = useCallback((payload) => {
+        console.log("[DB Listener] Session DELETE received:", payload);
+        if (!payload.old) {
+            console.error("[DB Listener] Session DELETE - Invalid payload, missing old data");
+            return;
+        }
         dispatch(deleteSessionFromStore(payload.old));
-    }
-    function handleSessionUpdates(payload) {
-        console.log("[DB Listener] Session UPDATE received:", payload.new);
+    }, [dispatch]);
+    const handleSessionUpdates = useCallback((payload) => {
+        console.log("[DB Listener] Session UPDATE received:", payload);
+        if (!payload.new) {
+            console.error("[DB Listener] Session UPDATE - Invalid payload, missing new data");
+            return;
+        }
         dispatch(updateSessionInStore(payload.new));
-    }
-    function handleConnectivityInserts(payload) {
-        console.log("[DB Listener] Connectivity INSERT received:", payload.new);
+    }, [dispatch]);
+    const handleConnectivityInserts = useCallback((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.old);
+    }, []);
+    const handleConnectivityDeletes = useCallback((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.new);
+    }, []);
+    const handleConnectivityUpdates = useCallback((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;
+    }, []);
+    // 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`);
+                if (connectionState === ConnectionState.CONNECTED) {
+                    setConnectionState(ConnectionState.DISCONNECTED);
+                    setLastError("Channel disconnected");
+                    scheduleReconnection();
+                }
+            })
+                .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;
         }
-        supabase.current = scoutSupabase;
-        // Test authentication first
-        const testAuth = async () => {
+        catch (error) {
+            console.error(`[DB Listener] Failed to create ${tableName} channel:`, error);
+            return null;
+        }
+    }, [connectionState]);
+    // Set up all channels
+    const setupChannels = useCallback(async () => {
+        if (!supabase.current)
+            return false;
+        cleanupChannels();
+        const channelConfigs = [
+            {
+                name: "plans",
+                handlers: {
+                    INSERT: handlePlanInserts,
+                    UPDATE: handlePlanUpdates,
+                    DELETE: handlePlanDeletes,
+                },
+            },
+            {
+                name: "devices",
+                handlers: {
+                    INSERT: handleDeviceInserts,
+                    UPDATE: handleDeviceUpdates,
+                    DELETE: handleDeviceDeletes,
+                },
+            },
+            {
+                name: "tags",
+                handlers: {
+                    INSERT: handleTagInserts,
+                    UPDATE: handleTagUpdates,
+                    DELETE: handleTagDeletes,
+                },
+            },
+            {
+                name: "sessions",
+                handlers: {
+                    INSERT: handleSessionInserts,
+                    UPDATE: handleSessionUpdates,
+                    DELETE: handleSessionDeletes,
+                },
+            },
+            {
+                name: "connectivity",
+                handlers: {
+                    INSERT: handleConnectivityInserts,
+                    UPDATE: handleConnectivityUpdates,
+                    DELETE: handleConnectivityDeletes,
+                },
+            },
+        ];
+        let successCount = 0;
+        const totalChannels = channelConfigs.length;
+        for (const config of channelConfigs) {
+            const channel = createChannel(config.name);
+            if (!channel)
+                continue;
             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);
+                // Set up event handlers
+                Object.entries(config.handlers).forEach(([event, handler]) => {
+                    channel.on("broadcast", { event }, handler);
+                });
+                // Subscribe to the channel
+                const _subscription = channel.subscribe((status) => {
+                    console.log(`[DB Listener] ${config.name} 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] ${config.name} channel failed to subscribe:`, status);
+                        setLastError(`Channel subscription failed: ${status}`);
+                    }
+                });
+                channels.current.push(channel);
             }
-            catch (err) {
-                console.error("[DB Listener] Auth test failed:", err);
+            catch (error) {
+                console.error(`[DB Listener] Failed to set up ${config.name} channel:`, error);
             }
-        };
-        testAuth();
-        // Create a single channel for all operations with unique name
-        const channelName = `scout_realtime_${Date.now()}`;
-        console.log("[DB Listener] Creating channel:", channelName);
-        const mainChannel = scoutSupabase.channel(channelName);
-        // Subscribe to all events
-        mainChannel
-            .on("postgres_changes", { event: "INSERT", schema: "public", table: "plans" }, handlePlanInserts)
-            .on("postgres_changes", { event: "DELETE", schema: "public", table: "plans" }, handlePlanDeletes)
-            .on("postgres_changes", { event: "UPDATE", schema: "public", table: "plans" }, handlePlanUpdates)
-            .on("postgres_changes", { event: "INSERT", schema: "public", table: "devices" }, handleDeviceInserts)
-            .on("postgres_changes", { event: "DELETE", schema: "public", table: "devices" }, handleDeviceDeletes)
-            .on("postgres_changes", { event: "UPDATE", schema: "public", table: "devices" }, handleDeviceUpdates)
-            .on("postgres_changes", { event: "INSERT", schema: "public", table: "tags" }, handleTagInserts)
-            .on("postgres_changes", { event: "DELETE", schema: "public", table: "tags" }, handleTagDeletes)
-            .on("postgres_changes", { event: "UPDATE", schema: "public", table: "tags" }, handleTagUpdates)
-            .on("postgres_changes", { event: "INSERT", schema: "public", table: "connectivity" }, handleConnectivityInserts)
-            .on("postgres_changes", { event: "DELETE", schema: "public", table: "connectivity" }, handleConnectivityDeletes)
-            .on("postgres_changes", { event: "UPDATE", schema: "public", table: "connectivity" }, handleConnectivityUpdates)
-            .on("postgres_changes", { event: "INSERT", schema: "public", table: "sessions" }, handleSessionInserts)
-            .on("postgres_changes", { event: "DELETE", schema: "public", table: "sessions" }, handleSessionDeletes)
-            .on("postgres_changes", { event: "UPDATE", schema: "public", table: "sessions" }, handleSessionUpdates)
-            .subscribe((status) => {
-            console.log("[DB Listener] Subscription status:", status);
-            if (status === "SUBSCRIBED") {
-                console.log("[DB Listener] ✅ Successfully subscribed to real-time updates");
+        }
+        return successCount > 0;
+    }, [
+        cleanupChannels,
+        createChannel,
+        handlePlanInserts,
+        handlePlanUpdates,
+        handlePlanDeletes,
+        handleDeviceInserts,
+        handleDeviceUpdates,
+        handleDeviceDeletes,
+        handleTagInserts,
+        handleTagUpdates,
+        handleTagDeletes,
+        handleSessionInserts,
+        handleSessionUpdates,
+        handleSessionDeletes,
+        handleConnectivityInserts,
+        handleConnectivityUpdates,
+        handleConnectivityDeletes,
+    ]);
+    // 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();
             }
-            else if (status === "CHANNEL_ERROR") {
-                console.error("[DB Listener] ❌ Channel error occurred");
+        }, 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");
             }
-            else if (status === "TIMED_OUT") {
-                console.error("[DB Listener] ⏰ Subscription timed out");
+            // Set up realtime authentication
+            const authSuccess = await setupRealtimeAuth();
+            if (!authSuccess) {
+                throw new Error("Realtime authentication failed");
             }
-            else if (status === "CLOSED") {
-                console.log("[DB Listener] 🔒 Channel closed");
+            // Set up channels
+            const channelsSuccess = await setupChannels();
+            if (!channelsSuccess) {
+                throw new Error("Channel setup failed");
             }
-        });
-        channels.current.push(mainChannel);
-        // 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.error("[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);
-            }
-            catch (err) {
-                console.error("[DB Listener] DB connection test failed:", err);
-            }
-        };
-        testDbConnection();
-        console.log("=== END SCOUT DB LISTENER DEBUG ===");
+            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 ||
+            connectionState === ConnectionState.RECONNECTING,
+    };
 }

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,15 @@ export function ScoutRefreshProvider({ children }) {
         supabaseRef.current = createBrowserClient(url, anon_key);
         console.log("[ScoutRefreshProvider] Created Supabase client");
     }
-    useScoutDbListener(supabaseRef.current);
+    // Use the enhanced DB listener with connection status
+    const connectionStatus = useScoutDbListener(supabaseRef.current);
     useScoutRefresh();
-    return (_jsx(SupabaseContext.Provider, { value: supabaseRef.current, children: children }));
+    // 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: _jsx(ConnectionStatusContext.Provider, { value: connectionStatus, children: children }) }));
 }

package/package.json

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