@adventurelabs/scout-core 1.4.47 → 1.4.49

package/dist/helpers/auth.d.ts

@@ -1 +1,4 @@
+import { SupabaseClient } from "@supabase/supabase-js";
+import { Database } from "../types/supabase";
 export declare function isEmailValidForLogin(email: string, approved_domains?: string[]): boolean;
+export declare function isCurrentUserPlatformSuperadmin(client: SupabaseClient<Database>): Promise<boolean>;

package/dist/helpers/auth.js

@@ -6,3 +6,11 @@ export function isEmailValidForLogin(email, approved_domains = APPROVED_DOMAINS)
 function isEmailFromApprovedDomain(email, approved_domains = APPROVED_DOMAINS) {
     return approved_domains.filter((domain) => email.endsWith(domain)).length > 0;
 }
+export async function isCurrentUserPlatformSuperadmin(client) {
+    const { data, error } = await client.rpc("is_platform_superadmin_current_user");
+    if (error) {
+        console.warn("[scout-core auth] Failed to check platform superadmin status:", error.message);
+        return false;
+    }
+    return data === true;
+}

package/dist/helpers/index.d.ts

@@ -13,6 +13,7 @@ export * from "./herds";
 export * from "./location";
 export * from "./plans";
 export * from "./sessions";
+export * from "./segmentations_sam3";
 export * from "./tags";
 export * from "./time";
 export * from "./ui";

package/dist/helpers/index.js

@@ -13,6 +13,7 @@ export * from "./herds";
 export * from "./location";
 export * from "./plans";
 export * from "./sessions";
+export * from "./segmentations_sam3";
 export * from "./tags";
 export * from "./time";
 export * from "./ui";

package/dist/helpers/segmentations_sam3.d.ts

@@ -0,0 +1,18 @@
+import { ISegmentationSam3Pretty } from "../types/db";
+import { IWebResponseCompatible } from "../types/requests";
+/** SAM3 masks for an artifact; optional timestamp_observation range and max_elements (omit or null for no limit). */
+export declare function server_get_segmentations_sam3_for_artifact(artifactId: number, options?: {
+    start_timestamp?: string | null;
+    end_timestamp?: string | null;
+    max_elements?: number | null;
+}): Promise<IWebResponseCompatible<ISegmentationSam3Pretty[]>>;
+/** SAM3 masks for an event; optional timestamp_observation range and max_elements (omit or null for no limit). */
+export declare function server_get_segmentations_sam3_for_event(eventId: number, options?: {
+    start_timestamp?: string | null;
+    end_timestamp?: string | null;
+    max_elements?: number | null;
+}): Promise<IWebResponseCompatible<ISegmentationSam3Pretty[]>>;
+/** SAM3 masks for an artifact by inclusive frame_index range; optional min_conf and max_elements (omit or null for no limit on rows). */
+export declare function server_get_segmentations_sam3_for_artifact_by_frame_index(artifactId: number, frameIndexStart: number, frameIndexEnd: number, minConf?: number | null, maxElements?: number | null): Promise<IWebResponseCompatible<ISegmentationSam3Pretty[]>>;
+/** SAM3 masks for an artifact and subject_id; omit maxElements (or null) for no row limit. */
+export declare function server_get_segmentations_sam3_for_artifact_by_subject_id(artifactId: number, subjectId: number, maxElements?: number | null): Promise<IWebResponseCompatible<ISegmentationSam3Pretty[]>>;

package/dist/helpers/segmentations_sam3.js

@@ -0,0 +1,91 @@
+"use server";
+import { newServerClient } from "../supabase/server";
+import { EnumWebResponse, IWebResponse, } from "../types/requests";
+/** SAM3 masks for an artifact; optional timestamp_observation range and max_elements (omit or null for no limit). */
+export async function server_get_segmentations_sam3_for_artifact(artifactId, options) {
+    const supabase = await newServerClient();
+    const { data, error } = await supabase.rpc("get_segmentations_sam3_for_artifact", {
+        artifact_id_caller: artifactId,
+        ...(options?.start_timestamp != null && {
+            start_timestamp_caller: options.start_timestamp,
+        }),
+        ...(options?.end_timestamp != null && {
+            end_timestamp_caller: options.end_timestamp,
+        }),
+        ...(options?.max_elements != null && {
+            max_elements_caller: options.max_elements,
+        }),
+    });
+    if (error) {
+        console.warn("Error fetching segmentations_sam3 for artifact:", error.message);
+        return {
+            status: EnumWebResponse.ERROR,
+            msg: error.message,
+            data: [],
+        };
+    }
+    return IWebResponse.success(data ?? []).to_compatible();
+}
+/** SAM3 masks for an event; optional timestamp_observation range and max_elements (omit or null for no limit). */
+export async function server_get_segmentations_sam3_for_event(eventId, options) {
+    const supabase = await newServerClient();
+    const { data, error } = await supabase.rpc("get_segmentations_sam3_for_event", {
+        event_id_caller: eventId,
+        ...(options?.start_timestamp != null && {
+            start_timestamp_caller: options.start_timestamp,
+        }),
+        ...(options?.end_timestamp != null && {
+            end_timestamp_caller: options.end_timestamp,
+        }),
+        ...(options?.max_elements != null && {
+            max_elements_caller: options.max_elements,
+        }),
+    });
+    if (error) {
+        console.warn("Error fetching segmentations_sam3 for event:", error.message);
+        return {
+            status: EnumWebResponse.ERROR,
+            msg: error.message,
+            data: [],
+        };
+    }
+    return IWebResponse.success(data ?? []).to_compatible();
+}
+/** SAM3 masks for an artifact by inclusive frame_index range; optional min_conf and max_elements (omit or null for no limit on rows). */
+export async function server_get_segmentations_sam3_for_artifact_by_frame_index(artifactId, frameIndexStart, frameIndexEnd, minConf = null, maxElements = null) {
+    const supabase = await newServerClient();
+    const { data, error } = await supabase.rpc("get_segmentations_sam3_for_artifact_by_frame_index", {
+        artifact_id_caller: artifactId,
+        frame_index_start_caller: frameIndexStart,
+        frame_index_end_caller: frameIndexEnd,
+        ...(minConf != null && { min_conf_caller: minConf }),
+        ...(maxElements != null && { max_elements_caller: maxElements }),
+    });
+    if (error) {
+        console.warn("Error fetching segmentations_sam3 for artifact by frame index:", error.message);
+        return {
+            status: EnumWebResponse.ERROR,
+            msg: error.message,
+            data: [],
+        };
+    }
+    return IWebResponse.success(data ?? []).to_compatible();
+}
+/** SAM3 masks for an artifact and subject_id; omit maxElements (or null) for no row limit. */
+export async function server_get_segmentations_sam3_for_artifact_by_subject_id(artifactId, subjectId, maxElements = null) {
+    const supabase = await newServerClient();
+    const { data, error } = await supabase.rpc("get_segmentations_sam3_for_artifact_by_subject_id", {
+        artifact_id_caller: artifactId,
+        subject_id_caller: subjectId,
+        ...(maxElements != null && { max_elements_caller: maxElements }),
+    });
+    if (error) {
+        console.warn("Error fetching segmentations_sam3 for artifact by subject id:", error.message);
+        return {
+            status: EnumWebResponse.ERROR,
+            msg: error.message,
+            data: [],
+        };
+    }
+    return IWebResponse.success(data ?? []).to_compatible();
+}

package/dist/helpers/sessions.js

@@ -1,6 +1,7 @@
 "use server";
 import { newServerClient } from "../supabase/server";
 import { EnumWebResponse, IWebResponse, } from "../types/requests";
+import { generateSignedUrlsBatch } from "./storage";
 // Get session by ID with coordinates
 export async function server_get_session_by_id(sessionId, client) {
     const supabase = client || (await newServerClient());
@@ -69,7 +70,23 @@ export async function server_get_events_and_tags_by_session_id(sessionId, limit
             data: [],
         };
     }
-    return IWebResponse.success(data || []).to_compatible();
+    const eventData = (data || []);
+    const filePaths = eventData
+        .map((event) => event.file_path)
+        .filter((path) => !!path);
+    let eventsWithSignedUrls = eventData;
+    if (filePaths.length > 0) {
+        const signedUrls = await generateSignedUrlsBatch(filePaths, undefined, supabase);
+        const urlMap = new Map();
+        filePaths.forEach((path, index) => {
+            urlMap.set(path, signedUrls[index]);
+        });
+        eventsWithSignedUrls = eventData.map((event) => ({
+            ...event,
+            media_url: event.file_path ? urlMap.get(event.file_path) || null : null,
+        }));
+    }
+    return IWebResponse.success(eventsWithSignedUrls).to_compatible();
 }
 // Insert new sessions (accepts array for batch operations)
 export async function server_insert_session(sessions, client) {

package/dist/helpers/tags.d.ts

@@ -1,4 +1,4 @@
-import { IEventAndTagsPrettyLocation, ITag, ITagPrettyLocation } from "../types/db";
+import { IEventAndTagsPrettyLocation, IMinimalSubjectForArtifact, ITag, ITagPrettyLocation } from "../types/db";
 import { IWebResponseCompatible } from "../types/requests";
 export declare function test_event_loading(device_id: number): Promise<boolean>;
 export declare function server_create_tags(tags: ITag[]): Promise<IWebResponseCompatible<ITag[]>>;
@@ -10,15 +10,28 @@ export declare function server_get_events_and_tags_for_devices_batch(device_ids:
     [device_id: number]: IEventAndTagsPrettyLocation[];
 }>>;
 export declare function get_event_and_tags_by_event_id(event_id: number): Promise<IWebResponseCompatible<IEventAndTagsPrettyLocation>>;
-/** Tags for an artifact with optional timestamp range and max items. */
+/** Tags for an artifact with optional timestamp range, detector filter, and max_elements (omit or null for no limit). */
 export declare function server_get_tags_for_artifact(artifactId: number, options?: {
     start_timestamp?: string | null;
     end_timestamp?: string | null;
-    max_elements?: number;
+    max_elements?: number | null;
+    detection_models?: string[] | null;
 }): Promise<IWebResponseCompatible<ITagPrettyLocation[]>>;
-/** Tags for an event with optional timestamp range and max items. */
+/** Tags for an artifact filtered by frame_index range and minimum confidence. Omit maxElements (or pass null) for no row limit. */
+export declare function server_get_tags_for_artifact_by_frame_index(artifactId: number, minConf: number, frameIndexStart: number, frameIndexEnd: number, detection_models?: string[] | null, maxElements?: number | null): Promise<IWebResponseCompatible<ITagPrettyLocation[]>>;
+/** Tags for an artifact and subject_id. Omit maxElements (or pass null) for no row limit. */
+export declare function server_get_tags_for_artifact_by_subject_id(artifactId: number, subjectId: number, detection_models?: string[] | null, maxElements?: number | null): Promise<IWebResponseCompatible<ITagPrettyLocation[]>>;
+/** Per-subject aggregates for tags on an artifact (rows with subject_id only). Optional min_avg_conf / min_count / detection_models; max_elements caps subject rows (omit or null for no cap). */
+export declare function server_get_minimal_subjects_for_artifact(artifactId: number, options?: {
+    min_avg_conf?: number | null;
+    min_count?: number | null;
+    detection_models?: string[] | null;
+    max_elements?: number | null;
+}): Promise<IWebResponseCompatible<IMinimalSubjectForArtifact[]>>;
+/** Tags for an event with optional timestamp range, detector filter, and max_elements (omit or null for no limit). */
 export declare function server_get_tags_for_event(eventId: number, options?: {
     start_timestamp?: string | null;
     end_timestamp?: string | null;
-    max_elements?: number;
+    max_elements?: number | null;
+    detection_models?: string[] | null;
 }): Promise<IWebResponseCompatible<ITagPrettyLocation[]>>;

package/dist/helpers/tags.js

@@ -54,6 +54,12 @@ function extractLongitude(location) {
     }
     return null;
 }
+function rpcDetectorModelsParam(detection_models) {
+    if (detection_models != null && detection_models.length > 0) {
+        return { detector_models_caller: detection_models };
+    }
+    return {};
+}
 // Test function to verify individual event loading works
 export async function test_event_loading(device_id) {
     try {
@@ -457,18 +463,21 @@ export async function get_event_and_tags_by_event_id(event_id) {
     }
     return IWebResponse.success(eventWithSignedUrl).to_compatible();
 }
-/** Tags for an artifact with optional timestamp range and max items. */
+/** Tags for an artifact with optional timestamp range, detector filter, and max_elements (omit or null for no limit). */
 export async function server_get_tags_for_artifact(artifactId, options) {
     const supabase = await newServerClient();
     const { data, error } = await supabase.rpc("get_tags_for_artifact", {
         artifact_id_caller: artifactId,
-        max_elements_caller: options?.max_elements ?? 1000,
         ...(options?.start_timestamp != null && {
             start_timestamp_caller: options.start_timestamp,
         }),
         ...(options?.end_timestamp != null && {
             end_timestamp_caller: options.end_timestamp,
         }),
+        ...rpcDetectorModelsParam(options?.detection_models),
+        ...(options?.max_elements != null && {
+            max_elements_caller: options.max_elements,
+        }),
     });
     if (error) {
         console.warn("Error fetching tags for artifact:", error.message);
@@ -480,18 +489,87 @@ export async function server_get_tags_for_artifact(artifactId, options) {
     }
     return IWebResponse.success(data ?? []).to_compatible();
 }
-/** Tags for an event with optional timestamp range and max items. */
+/** Tags for an artifact filtered by frame_index range and minimum confidence. Omit maxElements (or pass null) for no row limit. */
+export async function server_get_tags_for_artifact_by_frame_index(artifactId, minConf, frameIndexStart, frameIndexEnd, detection_models = null, maxElements = null) {
+    const supabase = await newServerClient();
+    const { data, error } = await supabase.rpc("get_tags_for_artifact_by_frame_index", {
+        artifact_id_caller: artifactId,
+        min_conf_caller: minConf,
+        frame_index_start_caller: frameIndexStart,
+        frame_index_end_caller: frameIndexEnd,
+        ...rpcDetectorModelsParam(detection_models),
+        ...(maxElements != null && { max_elements_caller: maxElements }),
+    });
+    if (error) {
+        console.warn("Error fetching tags for artifact by frame index:", error.message);
+        return {
+            status: EnumWebResponse.ERROR,
+            msg: error.message,
+            data: [],
+        };
+    }
+    return IWebResponse.success(data ?? []).to_compatible();
+}
+/** Tags for an artifact and subject_id. Omit maxElements (or pass null) for no row limit. */
+export async function server_get_tags_for_artifact_by_subject_id(artifactId, subjectId, detection_models = null, maxElements = null) {
+    const supabase = await newServerClient();
+    const { data, error } = await supabase.rpc("get_tags_for_artifact_by_subject_id", {
+        artifact_id_caller: artifactId,
+        subject_id_caller: subjectId,
+        ...rpcDetectorModelsParam(detection_models),
+        ...(maxElements != null && { max_elements_caller: maxElements }),
+    });
+    if (error) {
+        console.warn("Error fetching tags for artifact by subject id:", error.message);
+        return {
+            status: EnumWebResponse.ERROR,
+            msg: error.message,
+            data: [],
+        };
+    }
+    return IWebResponse.success(data ?? []).to_compatible();
+}
+/** Per-subject aggregates for tags on an artifact (rows with subject_id only). Optional min_avg_conf / min_count / detection_models; max_elements caps subject rows (omit or null for no cap). */
+export async function server_get_minimal_subjects_for_artifact(artifactId, options) {
+    const supabase = await newServerClient();
+    const { data, error } = await supabase.rpc("get_minimal_subjects_for_artifact", {
+        artifact_id_caller: artifactId,
+        ...(options?.min_avg_conf != null && {
+            min_avg_conf_caller: options.min_avg_conf,
+        }),
+        ...(options?.min_count != null && {
+            min_count_caller: options.min_count,
+        }),
+        ...rpcDetectorModelsParam(options?.detection_models),
+        ...(options?.max_elements != null && {
+            max_elements_caller: options.max_elements,
+        }),
+    });
+    if (error) {
+        console.warn("Error fetching minimal subjects for artifact:", error.message);
+        return {
+            status: EnumWebResponse.ERROR,
+            msg: error.message,
+            data: [],
+        };
+    }
+    return IWebResponse.success(data ?? []).to_compatible();
+}
+/** Tags for an event with optional timestamp range, detector filter, and max_elements (omit or null for no limit). */
 export async function server_get_tags_for_event(eventId, options) {
     const supabase = await newServerClient();
     const { data, error } = await supabase.rpc("get_tags_for_event", {
         event_id_caller: eventId,
-        max_elements_caller: options?.max_elements ?? 1000,
         ...(options?.start_timestamp != null && {
             start_timestamp_caller: options.start_timestamp,
         }),
         ...(options?.end_timestamp != null && {
             end_timestamp_caller: options.end_timestamp,
         }),
+        ...rpcDetectorModelsParam(options?.detection_models),
+        ...(options?.max_elements != null && {
+            max_elements_caller: options.max_elements,
+        }),
     });
     if (error) {
         console.warn("Error fetching tags for event:", error.message);

package/dist/hooks/index.d.ts

@@ -8,5 +8,7 @@ export { useScoutRealtimeSessions } from "./useScoutRealtimeSessions";
 export { useScoutRealtimePlans } from "./useScoutRealtimePlans";
 export { useScoutRealtimePins } from "./useScoutRealtimePins";
 export { useScoutRealtimeParts } from "./useScoutRealtimeParts";
+export { useScoutRealtimeAnalysisJobs } from "./useScoutRealtimeAnalysisJobs";
+export { useScoutRealtimeAnalysisTasks } from "./useScoutRealtimeAnalysisTasks";
 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

@@ -8,6 +8,8 @@ export { useScoutRealtimeSessions } from "./useScoutRealtimeSessions";
 export { useScoutRealtimePlans } from "./useScoutRealtimePlans";
 export { useScoutRealtimePins } from "./useScoutRealtimePins";
 export { useScoutRealtimeParts } from "./useScoutRealtimeParts";
+export { useScoutRealtimeAnalysisJobs } from "./useScoutRealtimeAnalysisJobs";
+export { useScoutRealtimeAnalysisTasks } from "./useScoutRealtimeAnalysisTasks";
 // 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/useScoutRealtimeAnalysisJobs.d.ts

@@ -0,0 +1,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];

package/dist/hooks/useScoutRealtimeAnalysisJobs.js

@@ -0,0 +1,61 @@
+"use client";
+import { useEffect, useRef, useCallback, useState } from "react";
+import { EnumRealtimeOperation } from "../types/realtime";
+export function useScoutRealtimeAnalysisJobs(scoutSupabase) {
+    const channels = useRef([]);
+    const [latestJobUpdate, setLatestJobUpdate] = useState(null);
+    const handleAnalysisJobBroadcast = useCallback((payload) => {
+        const { payload: data } = payload;
+        const jobData = data.record || data.old_record;
+        if (!jobData) {
+            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] ANALYSIS_JOB ${data.operation} received for job ${jobData.id}:`, JSON.stringify(jobData));
+        const realtimeData = {
+            data: jobData,
+            operation,
+        };
+        setLatestJobUpdate(realtimeData);
+    }, []);
+    const clearLatestUpdate = useCallback(() => {
+        setLatestJobUpdate(null);
+    }, []);
+    useEffect(() => {
+        if (!scoutSupabase)
+            return;
+        channels.current.forEach((channel) => scoutSupabase.removeChannel(channel));
+        channels.current = [];
+        clearLatestUpdate();
+        const channel = scoutSupabase
+            .channel("analysis_jobs_changes", { config: { private: true } })
+            .on("broadcast", { event: "*" }, handleAnalysisJobBroadcast)
+            .subscribe((status) => {
+            if (status === "SUBSCRIBED") {
+                console.log("[ANALYSIS_JOBS] ✅ Connected to analysis jobs broadcasts");
+            }
+            else if (status === "CHANNEL_ERROR") {
+                console.warn("[ANALYSIS_JOBS] 🟡 Failed to connect to analysis jobs broadcasts");
+            }
+        });
+        channels.current.push(channel);
+        return () => {
+            channels.current.forEach((ch) => scoutSupabase.removeChannel(ch));
+            channels.current = [];
+        };
+    }, [scoutSupabase, handleAnalysisJobBroadcast, clearLatestUpdate]);
+    return [latestJobUpdate, clearLatestUpdate];
+}

package/dist/hooks/useScoutRealtimeAnalysisTasks.d.ts

@@ -0,0 +1,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];

package/dist/hooks/useScoutRealtimeAnalysisTasks.js

@@ -0,0 +1,61 @@
+"use client";
+import { useEffect, useRef, useCallback, useState } from "react";
+import { EnumRealtimeOperation } from "../types/realtime";
+export function useScoutRealtimeAnalysisTasks(scoutSupabase) {
+    const channels = useRef([]);
+    const [latestTaskUpdate, setLatestTaskUpdate] = useState(null);
+    const handleAnalysisTaskBroadcast = useCallback((payload) => {
+        const { payload: data } = payload;
+        const taskData = data.record || data.old_record;
+        if (!taskData) {
+            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] ANALYSIS_TASK ${data.operation} received for task ${taskData.id} (job ${taskData.job_id}):`, JSON.stringify(taskData));
+        const realtimeData = {
+            data: taskData,
+            operation,
+        };
+        setLatestTaskUpdate(realtimeData);
+    }, []);
+    const clearLatestUpdate = useCallback(() => {
+        setLatestTaskUpdate(null);
+    }, []);
+    useEffect(() => {
+        if (!scoutSupabase)
+            return;
+        channels.current.forEach((channel) => scoutSupabase.removeChannel(channel));
+        channels.current = [];
+        clearLatestUpdate();
+        const channel = scoutSupabase
+            .channel("analysis_tasks_changes", { config: { private: true } })
+            .on("broadcast", { event: "*" }, handleAnalysisTaskBroadcast)
+            .subscribe((status) => {
+            if (status === "SUBSCRIBED") {
+                console.log("[ANALYSIS_TASKS] ✅ Connected to analysis tasks broadcasts");
+            }
+            else if (status === "CHANNEL_ERROR") {
+                console.warn("[ANALYSIS_TASKS] 🟡 Failed to connect to analysis tasks broadcasts");
+            }
+        });
+        channels.current.push(channel);
+        return () => {
+            channels.current.forEach((ch) => scoutSupabase.removeChannel(ch));
+            channels.current = [];
+        };
+    }, [scoutSupabase, handleAnalysisTaskBroadcast, clearLatestUpdate]);
+    return [latestTaskUpdate, clearLatestUpdate];
+}

package/dist/index.d.ts

@@ -28,6 +28,7 @@ export * from "./helpers/pins";
 export * from "./helpers/plans";
 export * from "./helpers/layers";
 export * from "./helpers/sessions";
+export * from "./helpers/segmentations_sam3";
 export * from "./helpers/tags";
 export * from "./helpers/time";
 export * from "./helpers/ui";
@@ -54,6 +55,8 @@ export * from "./hooks/useScoutRealtimeSessions";
 export * from "./hooks/useScoutRealtimeParts";
 export * from "./hooks/useScoutRealtimePlans";
 export * from "./hooks/useScoutRealtimePins";
+export * from "./hooks/useScoutRealtimeAnalysisJobs";
+export * from "./hooks/useScoutRealtimeAnalysisTasks";
 export * from "./hooks/useScoutRefresh";
 export * from "./hooks/useInfiniteQuery";
 export * from "./providers";

package/dist/index.js

@@ -31,6 +31,7 @@ export * from "./helpers/pins";
 export * from "./helpers/plans";
 export * from "./helpers/layers";
 export * from "./helpers/sessions";
+export * from "./helpers/segmentations_sam3";
 export * from "./helpers/tags";
 export * from "./helpers/time";
 export * from "./helpers/ui";
@@ -58,6 +59,8 @@ export * from "./hooks/useScoutRealtimeSessions";
 export * from "./hooks/useScoutRealtimeParts";
 export * from "./hooks/useScoutRealtimePlans";
 export * from "./hooks/useScoutRealtimePins";
+export * from "./hooks/useScoutRealtimeAnalysisJobs";
+export * from "./hooks/useScoutRealtimeAnalysisTasks";
 export * from "./hooks/useScoutRefresh";
 export * from "./hooks/useInfiniteQuery";
 // Providers

package/dist/providers/ScoutRefreshProvider.d.ts

@@ -1076,6 +1076,7 @@ export declare function useSupabase(): SupabaseClient<Database, "public", "publi
         segmentations_sam3: {
             Row: {
                 artifact_id: number | null;
+                conf: number | null;
                 created_at: string;
                 event_id: number | null;
                 frame_index: number;
@@ -1090,11 +1091,13 @@ export declare function useSupabase(): SupabaseClient<Database, "public", "publi
                 sensor_roll: number | null;
                 sensor_yaw: number | null;
                 subject_height: number | null;
+                subject_id: number | null;
                 subject_location: unknown;
                 timestamp_observation: string | null;
             };
             Insert: {
                 artifact_id?: number | null;
+                conf?: number | null;
                 created_at?: string;
                 event_id?: number | null;
                 frame_index?: number;
@@ -1109,11 +1112,13 @@ export declare function useSupabase(): SupabaseClient<Database, "public", "publi
                 sensor_roll?: number | null;
                 sensor_yaw?: number | null;
                 subject_height?: number | null;
+                subject_id?: number | null;
                 subject_location?: unknown;
                 timestamp_observation?: string | null;
             };
             Update: {
                 artifact_id?: number | null;
+                conf?: number | null;
                 created_at?: string;
                 event_id?: number | null;
                 frame_index?: number;
@@ -1128,6 +1133,7 @@ export declare function useSupabase(): SupabaseClient<Database, "public", "publi
                 sensor_roll?: number | null;
                 sensor_yaw?: number | null;
                 subject_height?: number | null;
+                subject_id?: number | null;
                 subject_location?: unknown;
                 timestamp_observation?: string | null;
             };
@@ -2337,6 +2343,22 @@ export declare function useSupabase(): SupabaseClient<Database, "public", "publi
                 isSetofReturn: true;
             };
         };
+        get_minimal_subjects_for_artifact: {
+            Args: {
+                artifact_id_caller: number;
+                detector_models_caller?: string[];
+                max_elements_caller?: number;
+                min_avg_conf_caller?: number;
+                min_count_caller?: number;
+            };
+            Returns: {
+                avg_conf: number;
+                first_tag_frame_index: number;
+                last_tag_frame_index: number;
+                num_tags: number;
+                subject_id: number;
+            }[];
+        };
         get_pins_for_herd: {
             Args: {
                 herd_id_caller: number;
@@ -2349,6 +2371,66 @@ export declare function useSupabase(): SupabaseClient<Database, "public", "publi
                 isSetofReturn: true;
             };
         };
+        get_segmentations_sam3_for_artifact: {
+            Args: {
+                artifact_id_caller: number;
+                end_timestamp_caller?: string;
+                max_elements_caller?: number;
+                start_timestamp_caller?: string;
+            };
+            Returns: Database["public"]["CompositeTypes"]["segmentations_sam3_pretty"][];
+            SetofOptions: {
+                from: "*";
+                to: "segmentations_sam3_pretty";
+                isOneToOne: false;
+                isSetofReturn: true;
+            };
+        };
+        get_segmentations_sam3_for_artifact_by_frame_index: {
+            Args: {
+                artifact_id_caller: number;
+                frame_index_end_caller: number;
+                frame_index_start_caller: number;
+                max_elements_caller?: number;
+                min_conf_caller?: number;
+            };
+            Returns: Database["public"]["CompositeTypes"]["segmentations_sam3_pretty"][];
+            SetofOptions: {
+                from: "*";
+                to: "segmentations_sam3_pretty";
+                isOneToOne: false;
+                isSetofReturn: true;
+            };
+        };
+        get_segmentations_sam3_for_artifact_by_subject_id: {
+            Args: {
+                artifact_id_caller: number;
+                max_elements_caller?: number;
+                subject_id_caller: number;
+            };
+            Returns: Database["public"]["CompositeTypes"]["segmentations_sam3_pretty"][];
+            SetofOptions: {
+                from: "*";
+                to: "segmentations_sam3_pretty";
+                isOneToOne: false;
+                isSetofReturn: true;
+            };
+        };
+        get_segmentations_sam3_for_event: {
+            Args: {
+                end_timestamp_caller?: string;
+                event_id_caller: number;
+                max_elements_caller?: number;
+                start_timestamp_caller?: string;
+            };
+            Returns: Database["public"]["CompositeTypes"]["segmentations_sam3_pretty"][];
+            SetofOptions: {
+                from: "*";
+                to: "segmentations_sam3_pretty";
+                isOneToOne: false;
+                isSetofReturn: true;
+            };
+        };
         get_session_by_id: {
             Args: {
                 session_id_caller: number;
@@ -2444,6 +2526,7 @@ export declare function useSupabase(): SupabaseClient<Database, "public", "publi
         get_tags_for_artifact: {
             Args: {
                 artifact_id_caller: number;
+                detector_models_caller?: string[];
                 end_timestamp_caller?: string;
                 max_elements_caller?: number;
                 start_timestamp_caller?: string;
@@ -2456,8 +2539,41 @@ export declare function useSupabase(): SupabaseClient<Database, "public", "publi
                 isSetofReturn: true;
             };
         };
+        get_tags_for_artifact_by_frame_index: {
+            Args: {
+                artifact_id_caller: number;
+                detector_models_caller?: string[];
+                frame_index_end_caller: number;
+                frame_index_start_caller: number;
+                max_elements_caller?: number;
+                min_conf_caller: number;
+            };
+            Returns: Database["public"]["CompositeTypes"]["tags_pretty_location"][];
+            SetofOptions: {
+                from: "*";
+                to: "tags_pretty_location";
+                isOneToOne: false;
+                isSetofReturn: true;
+            };
+        };
+        get_tags_for_artifact_by_subject_id: {
+            Args: {
+                artifact_id_caller: number;
+                detector_models_caller?: string[];
+                max_elements_caller?: number;
+                subject_id_caller: number;
+            };
+            Returns: Database["public"]["CompositeTypes"]["tags_pretty_location"][];
+            SetofOptions: {
+                from: "*";
+                to: "tags_pretty_location";
+                isOneToOne: false;
+                isSetofReturn: true;
+            };
+        };
         get_tags_for_event: {
             Args: {
+                detector_models_caller?: string[];
                 end_timestamp_caller?: string;
                 event_id_caller: number;
                 max_elements_caller?: number;
@@ -2504,6 +2620,10 @@ export declare function useSupabase(): SupabaseClient<Database, "public", "publi
                 isSetofReturn: true;
             };
         };
+        is_platform_superadmin_current_user: {
+            Args: never;
+            Returns: boolean;
+        };
         load_api_keys: {
             Args: {
                 id_of_device: number;
@@ -2809,6 +2929,31 @@ export declare function useSupabase(): SupabaseClient<Database, "public", "publi
             latitude: number | null;
             longitude: number | null;
         };
+        segmentations_sam3_pretty: {
+            id: number | null;
+            created_at: string | null;
+            event_id: number | null;
+            artifact_id: number | null;
+            frame_index: number | null;
+            mask_rle: import("../types/supabase").Json | null;
+            conf: number | null;
+            timestamp_observation: string | null;
+            origin_location: unknown;
+            origin_pitch: number | null;
+            origin_heading: number | null;
+            origin_roll: number | null;
+            sensor_pitch: number | null;
+            sensor_yaw: number | null;
+            sensor_roll: number | null;
+            origin_height: number | null;
+            subject_location: unknown;
+            subject_height: number | null;
+            origin_latitude: number | null;
+            origin_longitude: number | null;
+            subject_latitude: number | null;
+            subject_longitude: number | null;
+            subject_id: number | null;
+        };
         session_with_coordinates: {
             id: number | null;
             device_id: number | null;

package/dist/types/db.d.ts

@@ -15,6 +15,8 @@ export type IPin = Database["public"]["CompositeTypes"]["pins_pretty_location"];
 export type IEvent = Database["public"]["Tables"]["events"]["Row"];
 export type ITag = Database["public"]["Tables"]["tags"]["Row"];
 export type ITagPrettyLocation = Database["public"]["CompositeTypes"]["tags_pretty_location"];
+export type ISegmentationSam3 = Database["public"]["Tables"]["segmentations_sam3"]["Row"];
+export type ISegmentationSam3Pretty = Database["public"]["CompositeTypes"]["segmentations_sam3_pretty"];
 export type IPlan = Database["public"]["Tables"]["plans"]["Row"];
 export type ILayer = Database["public"]["Tables"]["layers"]["Row"];
 export type IAction = Database["public"]["Tables"]["actions"]["Row"];
@@ -32,6 +34,7 @@ export type IVersionsSoftware = Database["public"]["Tables"]["versions_software"
 export type IArtifact = Database["public"]["Tables"]["artifacts"]["Row"];
 export type IHealthMetric = Database["public"]["Tables"]["health_metrics"]["Row"];
 export type IHealthMetricSummaryRow = Database["public"]["Functions"]["get_health_metrics_summary"]["Returns"][number];
+export type IMinimalSubjectForArtifact = Database["public"]["Functions"]["get_minimal_subjects_for_artifact"]["Returns"][number];
 export type IAnalysisJob = Database["public"]["Tables"]["analysis_jobs"]["Row"];
 export type IAnalysisTask = Database["public"]["Tables"]["analysis_tasks"]["Row"];
 export type IArtifactWithMediaUrl = IArtifact & {

package/dist/types/supabase.d.ts

@@ -1132,6 +1132,7 @@ export type Database = {
             segmentations_sam3: {
                 Row: {
                     artifact_id: number | null;
+                    conf: number | null;
                     created_at: string;
                     event_id: number | null;
                     frame_index: number;
@@ -1146,11 +1147,13 @@ export type Database = {
                     sensor_roll: number | null;
                     sensor_yaw: number | null;
                     subject_height: number | null;
+                    subject_id: number | null;
                     subject_location: unknown;
                     timestamp_observation: string | null;
                 };
                 Insert: {
                     artifact_id?: number | null;
+                    conf?: number | null;
                     created_at?: string;
                     event_id?: number | null;
                     frame_index?: number;
@@ -1165,11 +1168,13 @@ export type Database = {
                     sensor_roll?: number | null;
                     sensor_yaw?: number | null;
                     subject_height?: number | null;
+                    subject_id?: number | null;
                     subject_location?: unknown;
                     timestamp_observation?: string | null;
                 };
                 Update: {
                     artifact_id?: number | null;
+                    conf?: number | null;
                     created_at?: string;
                     event_id?: number | null;
                     frame_index?: number;
@@ -1184,6 +1189,7 @@ export type Database = {
                     sensor_roll?: number | null;
                     sensor_yaw?: number | null;
                     subject_height?: number | null;
+                    subject_id?: number | null;
                     subject_location?: unknown;
                     timestamp_observation?: string | null;
                 };
@@ -2422,6 +2428,22 @@ export type Database = {
                     isSetofReturn: true;
                 };
             };
+            get_minimal_subjects_for_artifact: {
+                Args: {
+                    artifact_id_caller: number;
+                    detector_models_caller?: string[];
+                    max_elements_caller?: number;
+                    min_avg_conf_caller?: number;
+                    min_count_caller?: number;
+                };
+                Returns: {
+                    avg_conf: number;
+                    first_tag_frame_index: number;
+                    last_tag_frame_index: number;
+                    num_tags: number;
+                    subject_id: number;
+                }[];
+            };
             get_pins_for_herd: {
                 Args: {
                     herd_id_caller: number;
@@ -2434,6 +2456,66 @@ export type Database = {
                     isSetofReturn: true;
                 };
             };
+            get_segmentations_sam3_for_artifact: {
+                Args: {
+                    artifact_id_caller: number;
+                    end_timestamp_caller?: string;
+                    max_elements_caller?: number;
+                    start_timestamp_caller?: string;
+                };
+                Returns: Database["public"]["CompositeTypes"]["segmentations_sam3_pretty"][];
+                SetofOptions: {
+                    from: "*";
+                    to: "segmentations_sam3_pretty";
+                    isOneToOne: false;
+                    isSetofReturn: true;
+                };
+            };
+            get_segmentations_sam3_for_artifact_by_frame_index: {
+                Args: {
+                    artifact_id_caller: number;
+                    frame_index_end_caller: number;
+                    frame_index_start_caller: number;
+                    max_elements_caller?: number;
+                    min_conf_caller?: number;
+                };
+                Returns: Database["public"]["CompositeTypes"]["segmentations_sam3_pretty"][];
+                SetofOptions: {
+                    from: "*";
+                    to: "segmentations_sam3_pretty";
+                    isOneToOne: false;
+                    isSetofReturn: true;
+                };
+            };
+            get_segmentations_sam3_for_artifact_by_subject_id: {
+                Args: {
+                    artifact_id_caller: number;
+                    max_elements_caller?: number;
+                    subject_id_caller: number;
+                };
+                Returns: Database["public"]["CompositeTypes"]["segmentations_sam3_pretty"][];
+                SetofOptions: {
+                    from: "*";
+                    to: "segmentations_sam3_pretty";
+                    isOneToOne: false;
+                    isSetofReturn: true;
+                };
+            };
+            get_segmentations_sam3_for_event: {
+                Args: {
+                    end_timestamp_caller?: string;
+                    event_id_caller: number;
+                    max_elements_caller?: number;
+                    start_timestamp_caller?: string;
+                };
+                Returns: Database["public"]["CompositeTypes"]["segmentations_sam3_pretty"][];
+                SetofOptions: {
+                    from: "*";
+                    to: "segmentations_sam3_pretty";
+                    isOneToOne: false;
+                    isSetofReturn: true;
+                };
+            };
             get_session_by_id: {
                 Args: {
                     session_id_caller: number;
@@ -2529,6 +2611,7 @@ export type Database = {
             get_tags_for_artifact: {
                 Args: {
                     artifact_id_caller: number;
+                    detector_models_caller?: string[];
                     end_timestamp_caller?: string;
                     max_elements_caller?: number;
                     start_timestamp_caller?: string;
@@ -2541,8 +2624,41 @@ export type Database = {
                     isSetofReturn: true;
                 };
             };
+            get_tags_for_artifact_by_frame_index: {
+                Args: {
+                    artifact_id_caller: number;
+                    detector_models_caller?: string[];
+                    frame_index_end_caller: number;
+                    frame_index_start_caller: number;
+                    max_elements_caller?: number;
+                    min_conf_caller: number;
+                };
+                Returns: Database["public"]["CompositeTypes"]["tags_pretty_location"][];
+                SetofOptions: {
+                    from: "*";
+                    to: "tags_pretty_location";
+                    isOneToOne: false;
+                    isSetofReturn: true;
+                };
+            };
+            get_tags_for_artifact_by_subject_id: {
+                Args: {
+                    artifact_id_caller: number;
+                    detector_models_caller?: string[];
+                    max_elements_caller?: number;
+                    subject_id_caller: number;
+                };
+                Returns: Database["public"]["CompositeTypes"]["tags_pretty_location"][];
+                SetofOptions: {
+                    from: "*";
+                    to: "tags_pretty_location";
+                    isOneToOne: false;
+                    isSetofReturn: true;
+                };
+            };
             get_tags_for_event: {
                 Args: {
+                    detector_models_caller?: string[];
                     end_timestamp_caller?: string;
                     event_id_caller: number;
                     max_elements_caller?: number;
@@ -2589,6 +2705,10 @@ export type Database = {
                     isSetofReturn: true;
                 };
             };
+            is_platform_superadmin_current_user: {
+                Args: never;
+                Returns: boolean;
+            };
             load_api_keys: {
                 Args: {
                     id_of_device: number;
@@ -2894,6 +3014,31 @@ export type Database = {
                 latitude: number | null;
                 longitude: number | null;
             };
+            segmentations_sam3_pretty: {
+                id: number | null;
+                created_at: string | null;
+                event_id: number | null;
+                artifact_id: number | null;
+                frame_index: number | null;
+                mask_rle: Json | null;
+                conf: number | null;
+                timestamp_observation: string | null;
+                origin_location: unknown;
+                origin_pitch: number | null;
+                origin_heading: number | null;
+                origin_roll: number | null;
+                sensor_pitch: number | null;
+                sensor_yaw: number | null;
+                sensor_roll: number | null;
+                origin_height: number | null;
+                subject_location: unknown;
+                subject_height: number | null;
+                origin_latitude: number | null;
+                origin_longitude: number | null;
+                subject_latitude: number | null;
+                subject_longitude: number | null;
+                subject_id: number | null;
+            };
             session_with_coordinates: {
                 id: number | null;
                 device_id: number | null;

package/package.json

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