@adventurelabs/scout-core 1.4.96 → 1.5.1

package/dist/hooks/index.d.ts

@@ -1,5 +1,5 @@
 export { useScoutRefresh, type UseScoutRefreshOptions, } from "./useScoutRefresh";
-export { useScoutRealtimeBroadcast } from "./useScoutRealtimeBroadcast";
+export { useScoutRealtimeBroadcast, type ScoutRealtimeBroadcastOptions, type ScoutRealtimeAuthErrorMode, } from "./useScoutRealtimeBroadcast";
 export { useScoutRealtimeConnectivity } from "./useScoutRealtimeConnectivity";
 export { useScoutRealtimeDevices } from "./useScoutRealtimeDevices";
 export { useScoutRealtimeVersionsSoftware } from "./useScoutRealtimeVersionsSoftware";
@@ -15,5 +15,6 @@ export { useScoutRealtimeDocuments, type DocumentRealtimeChannel, } from "./useS
 export { useScoutRealtimeMaintenanceRequests } from "./useScoutRealtimeMaintenanceRequests";
 export { useScoutRealtimeContacts } from "./useScoutRealtimeContacts";
 export { useScoutRealtimeSessionIncidents } from "./useScoutRealtimeSessionIncidents";
+export { useScoutRealtimeOperatingContexts, type OperatingContextRealtimeData, type OperatingContextRealtimeRow, } from "./useScoutRealtimeOperatingContexts";
 export { useInfiniteSessionsByHerd, useInfiniteSessionsByDevice, useInfiniteEventsByHerd, useInfiniteEventsByDevice, useInfiniteArtifactsByHerd, useInfiniteArtifactsByDevice, useInfiniteFeedByHerd, useInfiniteFeedByDevice, useInfiniteAnalysisJobs, useInfiniteAnalysisTasks, useIntersectionObserver, type UseInfiniteScrollOptions, type UseAnalysisJobsInfiniteOptions, type UseAnalysisTasksInfiniteOptions, } from "./useInfiniteQuery";
 export { useLoadingPerformance, useSessionSummariesByHerd, useHasSessionSummaries, } from "../store/hooks";

package/dist/hooks/index.js

@@ -1,5 +1,5 @@
 export { useScoutRefresh, } from "./useScoutRefresh";
-export { useScoutRealtimeBroadcast } from "./useScoutRealtimeBroadcast";
+export { useScoutRealtimeBroadcast, } from "./useScoutRealtimeBroadcast";
 export { useScoutRealtimeConnectivity } from "./useScoutRealtimeConnectivity";
 export { useScoutRealtimeDevices } from "./useScoutRealtimeDevices";
 export { useScoutRealtimeVersionsSoftware } from "./useScoutRealtimeVersionsSoftware";
@@ -15,6 +15,7 @@ export { useScoutRealtimeDocuments, } from "./useScoutRealtimeDocuments";
 export { useScoutRealtimeMaintenanceRequests } from "./useScoutRealtimeMaintenanceRequests";
 export { useScoutRealtimeContacts } from "./useScoutRealtimeContacts";
 export { useScoutRealtimeSessionIncidents } from "./useScoutRealtimeSessionIncidents";
+export { useScoutRealtimeOperatingContexts, } from "./useScoutRealtimeOperatingContexts";
 // RTK Query infinite scroll hooks
 export { useInfiniteSessionsByHerd, useInfiniteSessionsByDevice, useInfiniteEventsByHerd, useInfiniteEventsByDevice, useInfiniteArtifactsByHerd, useInfiniteArtifactsByDevice, useInfiniteFeedByHerd, useInfiniteFeedByDevice, useInfiniteAnalysisJobs, useInfiniteAnalysisTasks, useIntersectionObserver, } from "./useInfiniteQuery";
 // Session summaries and performance hooks

package/dist/hooks/useAuthorizedRealtimeTopics.d.ts

@@ -0,0 +1 @@
+export declare function useAuthorizedRealtimeTopics(topics: string[]): string[];

package/dist/hooks/useAuthorizedRealtimeTopics.js

@@ -0,0 +1,14 @@
+"use client";
+import { useMemo } from "react";
+import { filter_realtime_topics } from "../helpers/realtime_topic_access";
+import { useOptionalClientAbilitiesMint } from "../providers/ScoutRefreshProvider";
+export function useAuthorizedRealtimeTopics(topics) {
+    const abilities = useOptionalClientAbilitiesMint();
+    const topicsKey = topics.join("|");
+    return useMemo(() => {
+        const requested = topicsKey.split("|").filter(Boolean);
+        if (!abilities)
+            return requested;
+        return filter_realtime_topics(abilities.status, abilities.mint, requested);
+    }, [abilities, topicsKey]);
+}

package/dist/hooks/useScoutRealtimeAnalysisJobs.d.ts

@@ -2,4 +2,5 @@ import { SupabaseClient } from "@supabase/supabase-js";
 import { Database } from "../types/supabase";
 import { IAnalysisJob } from "../types/db";
 import { RealtimeData } from "../types/realtime";
-export declare function useScoutRealtimeAnalysisJobs(scoutSupabase: SupabaseClient<Database>): [RealtimeData<IAnalysisJob> | null, () => void];
+import { ScoutRealtimeBroadcastOptions } from "./useScoutRealtimeBroadcast";
+export declare function useScoutRealtimeAnalysisJobs(scoutSupabase: SupabaseClient<Database>, options?: ScoutRealtimeBroadcastOptions): [RealtimeData<IAnalysisJob> | null, () => void];

package/dist/hooks/useScoutRealtimeAnalysisJobs.js

@@ -1,7 +1,5 @@
 "use client";
-import { useScoutRealtimeBroadcast } from "./useScoutRealtimeBroadcast";
-export function useScoutRealtimeAnalysisJobs(scoutSupabase) {
-    return useScoutRealtimeBroadcast(scoutSupabase, [
-        "analysis_jobs_changes",
-    ]);
+import { useScoutRealtimeBroadcast, } from "./useScoutRealtimeBroadcast";
+export function useScoutRealtimeAnalysisJobs(scoutSupabase, options) {
+    return useScoutRealtimeBroadcast(scoutSupabase, ["analysis_jobs_changes"], options);
 }

package/dist/hooks/useScoutRealtimeAnalysisTasks.d.ts

@@ -2,4 +2,5 @@ import { SupabaseClient } from "@supabase/supabase-js";
 import { Database } from "../types/supabase";
 import { IAnalysisTask } from "../types/db";
 import { RealtimeData } from "../types/realtime";
-export declare function useScoutRealtimeAnalysisTasks(scoutSupabase: SupabaseClient<Database>): [RealtimeData<IAnalysisTask> | null, () => void];
+import { ScoutRealtimeBroadcastOptions } from "./useScoutRealtimeBroadcast";
+export declare function useScoutRealtimeAnalysisTasks(scoutSupabase: SupabaseClient<Database>, options?: ScoutRealtimeBroadcastOptions): [RealtimeData<IAnalysisTask> | null, () => void];

package/dist/hooks/useScoutRealtimeAnalysisTasks.js

@@ -1,7 +1,5 @@
 "use client";
-import { useScoutRealtimeBroadcast } from "./useScoutRealtimeBroadcast";
-export function useScoutRealtimeAnalysisTasks(scoutSupabase) {
-    return useScoutRealtimeBroadcast(scoutSupabase, [
-        "analysis_tasks_changes",
-    ]);
+import { useScoutRealtimeBroadcast, } from "./useScoutRealtimeBroadcast";
+export function useScoutRealtimeAnalysisTasks(scoutSupabase, options) {
+    return useScoutRealtimeBroadcast(scoutSupabase, ["analysis_tasks_changes"], options);
 }

package/dist/hooks/useScoutRealtimeBroadcast.d.ts

@@ -1,8 +1,12 @@
 import { SupabaseClient } from "@supabase/supabase-js";
 import { Database } from "../types/supabase";
 import { RealtimeData } from "../types/realtime";
-/**
- * Subscribes to private realtime topics and reports the most recent row change across them.
- * Changing the topic set resubscribes and clears the pending change.
- */
-export declare function useScoutRealtimeBroadcast<T>(scoutSupabase: SupabaseClient<Database>, topics: string[]): [RealtimeData<T> | null, () => void];
+export type ScoutRealtimeAuthErrorMode = "stop" | "backoff";
+export type ScoutRealtimeBroadcastOptions = {
+    /** `stop` prevents Phoenix rejoin loops on auth failure. */
+    authErrorRetry?: ScoutRealtimeAuthErrorMode;
+    backoffInitialMs?: number;
+    backoffMaxMs?: number;
+    backoffMaxAttempts?: number;
+};
+export declare function useScoutRealtimeBroadcast<T>(scoutSupabase: SupabaseClient<Database>, topics: string[], options?: ScoutRealtimeBroadcastOptions, rowFilter?: (row: T) => boolean): [RealtimeData<T> | null, () => void];

package/dist/hooks/useScoutRealtimeBroadcast.js

@@ -1,44 +1,137 @@
 "use client";
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 import { EnumRealtimeOperation } from "../types/realtime";
+import { useAuthorizedRealtimeTopics } from "./useAuthorizedRealtimeTopics";
 const OPERATIONS = {
     INSERT: EnumRealtimeOperation.INSERT,
     UPDATE: EnumRealtimeOperation.UPDATE,
     DELETE: EnumRealtimeOperation.DELETE,
 };
-/**
- * Subscribes to private realtime topics and reports the most recent row change across them.
- * Changing the topic set resubscribes and clears the pending change.
- */
-export function useScoutRealtimeBroadcast(scoutSupabase, topics) {
+const DEFAULT_BACKOFF_INITIAL_MS = 1000;
+const DEFAULT_BACKOFF_MAX_MS = 60000;
+function isRealtimeAuthError(error) {
+    const message = error?.message ?? "";
+    return /unauthorized|permission/i.test(message);
+}
+function backoffDelayMs(attempt, initialMs, maxMs) {
+    return Math.min(maxMs, initialMs * 2 ** Math.max(0, attempt));
+}
+export function useScoutRealtimeBroadcast(scoutSupabase, topics, options = {}, rowFilter) {
+    const { authErrorRetry = "stop", backoffInitialMs = DEFAULT_BACKOFF_INITIAL_MS, backoffMaxMs = DEFAULT_BACKOFF_MAX_MS, backoffMaxAttempts = Number.POSITIVE_INFINITY, } = options;
     const [latestUpdate, setLatestUpdate] = useState(null);
-    // Key the subscription on the topic set rather than the array identity, so callers can build
-    // their topics inline.
-    const topicsKey = topics.join("|");
-    const subscribedTopics = useMemo(() => topicsKey.split("|").filter(Boolean), [topicsKey]);
+    const subscribedTopics = useAuthorizedRealtimeTopics(topics);
     const clearLatestUpdate = useCallback(() => setLatestUpdate(null), []);
     useEffect(() => {
         setLatestUpdate(null);
         if (!scoutSupabase || subscribedTopics.length === 0)
             return;
-        const channels = subscribedTopics.map((topic) => scoutSupabase
-            .channel(topic, { config: { private: true } })
-            .on("broadcast", { event: "*" }, (message) => {
-            const change = message.payload;
-            const operation = OPERATIONS[change.operation];
-            const row = change.record ?? change.old_record;
-            if (operation === undefined || !row)
+        let cancelled = false;
+        const channels = new Map();
+        const authAttempts = new Map();
+        const blockedTopics = new Set();
+        const retryTimers = new Map();
+        const removeTopicChannel = (topic) => {
+            const channel = channels.get(topic);
+            if (!channel)
+                return;
+            channels.delete(topic);
+            void scoutSupabase.removeChannel(channel);
+        };
+        const scheduleRetry = (topic) => {
+            if (authErrorRetry !== "backoff" || cancelled)
+                return;
+            const attempt = authAttempts.get(topic) ?? 0;
+            if (attempt >= backoffMaxAttempts)
                 return;
-            setLatestUpdate({ data: row, operation });
-        })
-            .subscribe((status) => {
-            if (status === "CHANNEL_ERROR") {
-                console.warn(`[scout-core realtime] 🟡 ${topic} unavailable`);
+            authAttempts.set(topic, attempt + 1);
+            const existing = retryTimers.get(topic);
+            if (existing)
+                clearTimeout(existing);
+            retryTimers.set(topic, setTimeout(() => {
+                retryTimers.delete(topic);
+                void authenticateAndJoin([topic]);
+            }, backoffDelayMs(attempt, backoffInitialMs, backoffMaxMs)));
+        };
+        const joinTopic = (topic) => {
+            if (cancelled || channels.has(topic))
+                return;
+            const channel = scoutSupabase
+                .channel(topic, { config: { private: true } })
+                .on("broadcast", { event: "*" }, (message) => {
+                const change = message.payload;
+                const operation = OPERATIONS[change.operation];
+                const row = change.record ?? change.old_record;
+                if (operation === undefined || !row)
+                    return;
+                if (rowFilter && !rowFilter(row))
+                    return;
+                setLatestUpdate({ data: row, operation, table: change.table });
+            });
+            channels.set(topic, channel);
+            channel.subscribe((status, error) => {
+                if (status === "SUBSCRIBED") {
+                    authAttempts.delete(topic);
+                    blockedTopics.delete(topic);
+                    return;
+                }
+                if (status !== "CHANNEL_ERROR")
+                    return;
+                console.warn(`[scout-core realtime] 🟡 ${topic} unavailable`, error?.message ?? "");
+                if (!isRealtimeAuthError(error) || cancelled)
+                    return;
+                blockedTopics.add(topic);
+                removeTopicChannel(topic);
+                scheduleRetry(topic);
+            });
+        };
+        async function authenticateAndJoin(topicsToJoin) {
+            try {
+                await scoutSupabase.realtime.setAuth();
+            }
+            catch (error) {
+                console.warn("[scout-core realtime] failed to refresh auth", error);
+            }
+            if (!cancelled)
+                topicsToJoin.forEach(joinTopic);
+        }
+        const retryBlockedTopics = () => {
+            const topicsToRetry = Array.from(blockedTopics);
+            blockedTopics.forEach((topic) => {
+                const timer = retryTimers.get(topic);
+                if (timer)
+                    clearTimeout(timer);
+                retryTimers.delete(topic);
+                authAttempts.delete(topic);
+            });
+            if (topicsToRetry.length > 0)
+                void authenticateAndJoin(topicsToRetry);
+        };
+        const { data: { subscription: authSubscription }, } = scoutSupabase.auth.onAuthStateChange((event) => {
+            if (event === "INITIAL_SESSION" ||
+                event === "SIGNED_IN" ||
+                event === "TOKEN_REFRESHED") {
+                retryBlockedTopics();
             }
-        }));
+        });
+        void authenticateAndJoin(subscribedTopics);
         return () => {
-            channels.forEach((channel) => scoutSupabase.removeChannel(channel));
+            cancelled = true;
+            authSubscription.unsubscribe();
+            retryTimers.forEach((timer) => clearTimeout(timer));
+            retryTimers.clear();
+            channels.forEach((channel) => {
+                void scoutSupabase.removeChannel(channel);
+            });
+            channels.clear();
         };
-    }, [scoutSupabase, subscribedTopics]);
+    }, [
+        scoutSupabase,
+        subscribedTopics,
+        authErrorRetry,
+        backoffInitialMs,
+        backoffMaxMs,
+        backoffMaxAttempts,
+        rowFilter,
+    ]);
     return [latestUpdate, clearLatestUpdate];
 }

package/dist/hooks/useScoutRealtimeConnectivity.d.ts

@@ -2,4 +2,5 @@ import { SupabaseClient } from "@supabase/supabase-js";
 import { Database } from "../types/supabase";
 import { IConnectivityWithCoordinates } from "../types/db";
 import { RealtimeData } from "../types/realtime";
-export declare function useScoutRealtimeConnectivity(scoutSupabase: SupabaseClient<Database>): [RealtimeData<IConnectivityWithCoordinates> | null, () => void];
+import { ScoutRealtimeBroadcastOptions } from "./useScoutRealtimeBroadcast";
+export declare function useScoutRealtimeConnectivity(scoutSupabase: SupabaseClient<Database>, options?: ScoutRealtimeBroadcastOptions): [RealtimeData<IConnectivityWithCoordinates> | null, () => void];

package/dist/hooks/useScoutRealtimeConnectivity.js

@@ -1,84 +1,26 @@
 "use client";
 import { useSelector } from "react-redux";
-import { useEffect, useRef, useCallback, useState, useMemo } from "react";
-import { EnumRealtimeOperation } from "../types/realtime";
-export function useScoutRealtimeConnectivity(scoutSupabase) {
-    const channels = useRef([]);
-    const [latestConnectivityUpdate, setLatestConnectivityUpdate] = useState(null);
+import { useMemo } from "react";
+import { useScoutRealtimeBroadcast, } from "./useScoutRealtimeBroadcast";
+const GPS_DEVICE_TYPES = [
+    "gps_tracker",
+    "gps_tracker_vehicle",
+    "gps_tracker_person",
+];
+function isGpsConnectivity(row) {
+    return Boolean(row.device_id && !row.session_id);
+}
+export function useScoutRealtimeConnectivity(scoutSupabase, options) {
     const activeHerdId = useSelector((state) => state.scout.active_herd_id);
     const herdModules = useSelector((state) => state.scout.herd_modules);
-    // Create stable reference for GPS device IDs to prevent unnecessary refetching
-    const gpsDeviceIds = useMemo(() => {
+    const hasGpsDevices = useMemo(() => {
         if (!activeHerdId)
-            return "";
+            return false;
         const activeHerdModule = herdModules.find((hm) => hm.herd.id?.toString() === activeHerdId);
-        if (!activeHerdModule)
-            return "";
-        const gpsDevices = activeHerdModule.devices.filter((device) => device.device_type &&
-            ["gps_tracker", "gps_tracker_vehicle", "gps_tracker_person"].includes(device.device_type));
-        return gpsDevices
-            .map((d) => d.id)
-            .filter(Boolean)
-            .sort()
-            .join(",");
+        return activeHerdModule?.devices.some((device) => device.device_type &&
+            GPS_DEVICE_TYPES.includes(device.device_type)) ?? false;
     }, [activeHerdId, herdModules]);
-    // Handle connectivity broadcasts
-    const handleConnectivityBroadcast = useCallback((payload) => {
-        const { event, payload: data } = payload;
-        const connectivityData = data.record || data.old_record;
-        // Only process GPS tracker data (no session_id)
-        if (!connectivityData?.device_id || connectivityData.session_id) {
-            return;
-        }
-        let operation;
-        switch (data.operation) {
-            case "INSERT":
-                operation = EnumRealtimeOperation.INSERT;
-                break;
-            case "UPDATE":
-                operation = EnumRealtimeOperation.UPDATE;
-                break;
-            case "DELETE":
-                operation = EnumRealtimeOperation.DELETE;
-                break;
-            default:
-                return;
-        }
-        console.log(`[scout-core realtime] CONNECTIVITY ${data.operation} received for device ${connectivityData.device_id}:`, JSON.stringify(connectivityData));
-        const realtimeData = {
-            data: connectivityData,
-            operation,
-        };
-        setLatestConnectivityUpdate(realtimeData);
-    }, []);
-    // Clear latest update
-    const clearLatestUpdate = useCallback(() => {
-        setLatestConnectivityUpdate(null);
-    }, []);
-    useEffect(() => {
-        if (!scoutSupabase || gpsDeviceIds === "")
-            return;
-        // Clean up existing channels
-        channels.current.forEach((channel) => scoutSupabase.removeChannel(channel));
-        channels.current = [];
-        // Clear previous update when switching herds
-        clearLatestUpdate();
-        // Create connectivity channel
-        const channel = scoutSupabase
-            .channel(`${activeHerdId}-connectivity`, { config: { private: true } })
-            .on("broadcast", { event: "*" }, handleConnectivityBroadcast)
-            .subscribe();
-        channels.current.push(channel);
-        return () => {
-            channels.current.forEach((ch) => scoutSupabase.removeChannel(ch));
-            channels.current = [];
-        };
-    }, [
-        scoutSupabase,
-        gpsDeviceIds,
-        activeHerdId,
-        handleConnectivityBroadcast,
-        clearLatestUpdate,
-    ]);
-    return [latestConnectivityUpdate, clearLatestUpdate];
+    return useScoutRealtimeBroadcast(scoutSupabase, activeHerdId && hasGpsDevices
+        ? [`${activeHerdId}-connectivity`]
+        : [], options, isGpsConnectivity);
 }

package/dist/hooks/useScoutRealtimeContacts.d.ts

@@ -2,4 +2,5 @@ import { SupabaseClient } from "@supabase/supabase-js";
 import { Database } from "../types/supabase";
 import { IContact } from "../types/db";
 import { RealtimeData } from "../types/realtime";
-export declare function useScoutRealtimeContacts(scoutSupabase: SupabaseClient<Database>): [RealtimeData<IContact> | null, () => void];
+import { ScoutRealtimeBroadcastOptions } from "./useScoutRealtimeBroadcast";
+export declare function useScoutRealtimeContacts(scoutSupabase: SupabaseClient<Database>, options?: ScoutRealtimeBroadcastOptions): [RealtimeData<IContact> | null, () => void];

package/dist/hooks/useScoutRealtimeContacts.js

@@ -1,7 +1,7 @@
 "use client";
 import { useSelector } from "react-redux";
-import { useScoutRealtimeBroadcast } from "./useScoutRealtimeBroadcast";
-export function useScoutRealtimeContacts(scoutSupabase) {
+import { useScoutRealtimeBroadcast, } from "./useScoutRealtimeBroadcast";
+export function useScoutRealtimeContacts(scoutSupabase, options) {
     const activeHerdId = useSelector((state) => state.scout.active_herd_id);
-    return useScoutRealtimeBroadcast(scoutSupabase, activeHerdId ? [`${activeHerdId}-contacts`] : []);
+    return useScoutRealtimeBroadcast(scoutSupabase, activeHerdId ? [`${activeHerdId}-contacts`] : [], options);
 }

package/dist/hooks/useScoutRealtimeDevices.d.ts

@@ -2,4 +2,5 @@ import { SupabaseClient } from "@supabase/supabase-js";
 import { Database } from "../types/supabase";
 import { IDevicePrettyLocation } from "../types/db";
 import { RealtimeData } from "../types/realtime";
-export declare function useScoutRealtimeDevices(scoutSupabase: SupabaseClient<Database>): [RealtimeData<IDevicePrettyLocation> | null, () => void];
+import { ScoutRealtimeBroadcastOptions } from "./useScoutRealtimeBroadcast";
+export declare function useScoutRealtimeDevices(scoutSupabase: SupabaseClient<Database>, options?: ScoutRealtimeBroadcastOptions): [RealtimeData<IDevicePrettyLocation> | null, () => void];

package/dist/hooks/useScoutRealtimeDevices.js

@@ -1,68 +1,7 @@
 "use client";
 import { useSelector } from "react-redux";
-import { useEffect, useRef, useCallback, useState } from "react";
-import { EnumRealtimeOperation } from "../types/realtime";
-export function useScoutRealtimeDevices(scoutSupabase) {
-    const channels = useRef([]);
-    const [latestDeviceUpdate, setLatestDeviceUpdate] = useState(null);
+import { useScoutRealtimeBroadcast, } from "./useScoutRealtimeBroadcast";
+export function useScoutRealtimeDevices(scoutSupabase, options) {
     const activeHerdId = useSelector((state) => state.scout.active_herd_id);
-    const handleDeviceBroadcast = useCallback((message) => {
-        const { payload: data } = message;
-        if (data.table !== "devices" || data.schema !== "public") {
-            return;
-        }
-        const deviceData = data.operation === "DELETE"
-            ? data.old_record
-            : data.record ?? data.old_record;
-        if (!deviceData)
-            return;
-        let operation;
-        switch (data.operation) {
-            case "INSERT":
-                operation = EnumRealtimeOperation.INSERT;
-                break;
-            case "UPDATE":
-                operation = EnumRealtimeOperation.UPDATE;
-                break;
-            case "DELETE":
-                operation = EnumRealtimeOperation.DELETE;
-                break;
-            default:
-                return;
-        }
-        const realtimeData = {
-            data: deviceData,
-            operation,
-        };
-        setLatestDeviceUpdate(realtimeData);
-    }, []);
-    const clearLatestUpdate = useCallback(() => {
-        setLatestDeviceUpdate(null);
-    }, []);
-    useEffect(() => {
-        if (!scoutSupabase)
-            return;
-        channels.current.forEach((channel) => scoutSupabase.removeChannel(channel));
-        channels.current = [];
-        clearLatestUpdate();
-        if (activeHerdId) {
-            const channel = scoutSupabase
-                .channel(`${activeHerdId}-devices`, { config: { private: true } })
-                .on("broadcast", { event: "*" }, handleDeviceBroadcast)
-                .subscribe((status) => {
-                if (status === "SUBSCRIBED") {
-                    console.log(`[Devices] ✅ Connected to herd ${activeHerdId}`);
-                }
-                else if (status === "CHANNEL_ERROR") {
-                    console.warn(`[Devices] 🟡 Failed to connect to herd ${activeHerdId}`);
-                }
-            });
-            channels.current.push(channel);
-        }
-        return () => {
-            channels.current.forEach((ch) => scoutSupabase.removeChannel(ch));
-            channels.current = [];
-        };
-    }, [scoutSupabase, activeHerdId, handleDeviceBroadcast, clearLatestUpdate]);
-    return [latestDeviceUpdate, clearLatestUpdate];
+    return useScoutRealtimeBroadcast(scoutSupabase, activeHerdId ? [`${activeHerdId}-devices`] : [], options);
 }

package/dist/hooks/useScoutRealtimeDocuments.d.ts

@@ -2,6 +2,6 @@ import { SupabaseClient } from "@supabase/supabase-js";
 import { Database } from "../types/supabase";
 import { IDocument } from "../types/db";
 import { RealtimeData } from "../types/realtime";
-/** One channel per document owner class, each gated on that class's read ability. */
-export type DocumentRealtimeChannel = "herd" | "device" | "user" | "own" | "product";
-export declare function useScoutRealtimeDocuments(scoutSupabase: SupabaseClient<Database>, channels?: DocumentRealtimeChannel[]): [RealtimeData<IDocument> | null, () => void];
+import { ScoutRealtimeBroadcastOptions } from "./useScoutRealtimeBroadcast";
+export type DocumentRealtimeChannel = "herd" | "device" | "user" | "own" | "product" | "operating_context";
+export declare function useScoutRealtimeDocuments(scoutSupabase: SupabaseClient<Database>, channels?: DocumentRealtimeChannel[], options?: ScoutRealtimeBroadcastOptions): [RealtimeData<IDocument> | null, () => void];

package/dist/hooks/useScoutRealtimeDocuments.js

@@ -1,22 +1,24 @@
 "use client";
+import { useMemo } from "react";
 import { useSelector } from "react-redux";
-import { useScoutRealtimeBroadcast } from "./useScoutRealtimeBroadcast";
+import { useScoutRealtimeBroadcast, } from "./useScoutRealtimeBroadcast";
 const ALL_DOCUMENT_CHANNELS = [
     "herd",
     "device",
     "user",
     "own",
     "product",
+    "operating_context",
 ];
-export function useScoutRealtimeDocuments(scoutSupabase, channels = ALL_DOCUMENT_CHANNELS) {
+export function useScoutRealtimeDocuments(scoutSupabase, channels = ALL_DOCUMENT_CHANNELS, options) {
     const activeHerdId = useSelector((state) => state.scout.active_herd_id);
     const userId = useSelector((state) => state.scout.user?.id ?? null);
-    const topics = channels.flatMap((channel) => {
+    const topics = useMemo(() => channels.flatMap((channel) => {
         if (channel === "product")
             return ["product_documents_changes"];
         if (channel === "own")
             return userId ? [`user_${userId}-documents`] : [];
         return activeHerdId ? [`${activeHerdId}-${channel}_documents`] : [];
-    });
-    return useScoutRealtimeBroadcast(scoutSupabase, topics);
+    }), [channels, activeHerdId, userId]);
+    return useScoutRealtimeBroadcast(scoutSupabase, topics, options);
 }

package/dist/hooks/useScoutRealtimeEvents.d.ts

@@ -2,4 +2,5 @@ import { SupabaseClient } from "@supabase/supabase-js";
 import { Database } from "../types/supabase";
 import { IEventAndTagsPrettyLocation } from "../types/db";
 import { RealtimeData } from "../types/realtime";
-export declare function useScoutRealtimeEvents(scoutSupabase: SupabaseClient<Database>): [RealtimeData<IEventAndTagsPrettyLocation> | null, () => void];
+import { ScoutRealtimeBroadcastOptions } from "./useScoutRealtimeBroadcast";
+export declare function useScoutRealtimeEvents(scoutSupabase: SupabaseClient<Database>, options?: ScoutRealtimeBroadcastOptions): [RealtimeData<IEventAndTagsPrettyLocation> | null, () => void];

package/dist/hooks/useScoutRealtimeEvents.js

@@ -1,73 +1,7 @@
 "use client";
 import { useSelector } from "react-redux";
-import { useEffect, useRef, useCallback, useState } from "react";
-import { EnumRealtimeOperation } from "../types/realtime";
-export function useScoutRealtimeEvents(scoutSupabase) {
-    const channels = useRef([]);
-    const [latestEventUpdate, setLatestEventUpdate] = useState(null);
+import { useScoutRealtimeBroadcast, } from "./useScoutRealtimeBroadcast";
+export function useScoutRealtimeEvents(scoutSupabase, options) {
     const activeHerdId = useSelector((state) => state.scout.active_herd_id);
-    // Event broadcast handler - just pass data, don't mutate state
-    const handleEventBroadcast = useCallback((payload) => {
-        console.log("[Events] Broadcast received:", payload.payload.operation);
-        const data = payload.payload;
-        const eventData = data.record || data.old_record;
-        if (!eventData)
-            return;
-        let operation;
-        switch (data.operation) {
-            case "INSERT":
-                operation = EnumRealtimeOperation.INSERT;
-                console.log("[Events] New event received:", data.record);
-                break;
-            case "UPDATE":
-                operation = EnumRealtimeOperation.UPDATE;
-                console.log("[Events] Event updated:", data.record);
-                break;
-            case "DELETE":
-                operation = EnumRealtimeOperation.DELETE;
-                console.log("[Events] Event deleted:", data.old_record);
-                break;
-            default:
-                return;
-        }
-        const realtimeData = {
-            data: eventData,
-            operation,
-        };
-        console.log(`[scout-core realtime] EVENT ${data.operation} received:`, JSON.stringify(realtimeData));
-        setLatestEventUpdate(realtimeData);
-    }, []);
-    // Clear latest update
-    const clearLatestUpdate = useCallback(() => {
-        setLatestEventUpdate(null);
-    }, []);
-    const cleanupChannels = () => {
-        channels.current.forEach((channel) => scoutSupabase.removeChannel(channel));
-        channels.current = [];
-    };
-    const createEventsChannel = (herdId) => {
-        return scoutSupabase
-            .channel(`${herdId}-events`, { config: { private: true } })
-            .on("broadcast", { event: "*" }, handleEventBroadcast)
-            .subscribe((status) => {
-            if (status === "SUBSCRIBED") {
-                console.log(`[Events] ✅ Connected to herd ${herdId}`);
-            }
-            else if (status === "CHANNEL_ERROR") {
-                console.warn(`[Events] 🟡 Failed to connect to herd ${herdId}`);
-            }
-        });
-    };
-    useEffect(() => {
-        cleanupChannels();
-        // Clear previous update when switching herds
-        clearLatestUpdate();
-        // Create events channel for active herd
-        if (activeHerdId) {
-            const channel = createEventsChannel(activeHerdId);
-            channels.current.push(channel);
-        }
-        return cleanupChannels;
-    }, [activeHerdId, clearLatestUpdate]);
-    return [latestEventUpdate, clearLatestUpdate];
+    return useScoutRealtimeBroadcast(scoutSupabase, activeHerdId ? [`${activeHerdId}-events`] : [], options);
 }

package/dist/hooks/useScoutRealtimeMaintenanceRequests.d.ts

@@ -2,4 +2,5 @@ import { SupabaseClient } from "@supabase/supabase-js";
 import { Database } from "../types/supabase";
 import { IMaintenanceRequest } from "../types/db";
 import { RealtimeData } from "../types/realtime";
-export declare function useScoutRealtimeMaintenanceRequests(scoutSupabase: SupabaseClient<Database>): [RealtimeData<IMaintenanceRequest> | null, () => void];
+import { ScoutRealtimeBroadcastOptions } from "./useScoutRealtimeBroadcast";
+export declare function useScoutRealtimeMaintenanceRequests(scoutSupabase: SupabaseClient<Database>, options?: ScoutRealtimeBroadcastOptions): [RealtimeData<IMaintenanceRequest> | null, () => void];

package/dist/hooks/useScoutRealtimeMaintenanceRequests.js

@@ -1,7 +1,7 @@
 "use client";
 import { useSelector } from "react-redux";
-import { useScoutRealtimeBroadcast } from "./useScoutRealtimeBroadcast";
-export function useScoutRealtimeMaintenanceRequests(scoutSupabase) {
+import { useScoutRealtimeBroadcast, } from "./useScoutRealtimeBroadcast";
+export function useScoutRealtimeMaintenanceRequests(scoutSupabase, options) {
     const activeHerdId = useSelector((state) => state.scout.active_herd_id);
-    return useScoutRealtimeBroadcast(scoutSupabase, activeHerdId ? [`${activeHerdId}-maintenance_requests`] : []);
+    return useScoutRealtimeBroadcast(scoutSupabase, activeHerdId ? [`${activeHerdId}-maintenance_requests`] : [], options);
 }