@adventurelabs/scout-core 1.0.69 → 1.0.71

package/dist/helpers/bounding_boxes.js

@@ -17,6 +17,7 @@ export function convertManualBoundingBoxToTag(boundingBox, event_id) {
         observation_type: "manual",
         class_name: newClassName,
         event_id: event_id,
+        location: null,
     };
     return newTag;
 }

package/dist/helpers/tags.d.ts

@@ -1,11 +1,11 @@
-import { IEventWithTags, ITag } from "../types/db";
+import { IEventAndTagsPrettyLocation, ITag } from "../types/db";
 import { IWebResponseCompatible } from "../types/requests";
 export declare function server_create_tags(tags: ITag[]): Promise<IWebResponseCompatible<ITag[]>>;
 export declare function server_delete_tags_by_ids(tag_ids: number[]): Promise<IWebResponseCompatible<boolean>>;
 export declare function server_update_tags(tags: ITag[]): Promise<IWebResponseCompatible<ITag[]>>;
-export declare function server_get_more_events_with_tags_by_herd(herd_id: number, offset: number, page_count?: number): Promise<IWebResponseCompatible<IEventWithTags[]>>;
-export declare function server_get_events_and_tags_for_device(device_id: number, limit?: number): Promise<IWebResponseCompatible<IEventWithTags[]>>;
+export declare function server_get_more_events_with_tags_by_herd(herd_id: number, offset: number, page_count?: number): Promise<IWebResponseCompatible<IEventAndTagsPrettyLocation[]>>;
+export declare function server_get_events_and_tags_for_device(device_id: number, limit?: number): Promise<IWebResponseCompatible<IEventAndTagsPrettyLocation[]>>;
 export declare function server_get_events_and_tags_for_devices_batch(device_ids: number[], limit?: number): Promise<IWebResponseCompatible<{
-    [device_id: number]: IEventWithTags[];
+    [device_id: number]: IEventAndTagsPrettyLocation[];
 }>>;
-export declare function get_event_and_tags_by_event_id(event_id: number): Promise<IWebResponseCompatible<IEventWithTags>>;
+export declare function get_event_and_tags_by_event_id(event_id: number): Promise<IWebResponseCompatible<IEventAndTagsPrettyLocation>>;

package/dist/helpers/tags.js

@@ -1,6 +1,57 @@
 "use server";
 // add tag to db
 import { newServerClient } from "../supabase/server";
+// Helper functions to extract coordinates from location field
+function extractLatitude(location) {
+    try {
+        if (typeof location === "object" && location !== null) {
+            if ("coordinates" in location && Array.isArray(location.coordinates)) {
+                return location.coordinates[1]; // latitude is second coordinate
+            }
+            if ("y" in location) {
+                return location.y;
+            }
+        }
+        if (typeof location === "string") {
+            const match = location.match(/Point\(([^)]+)\)/);
+            if (match) {
+                const coords = match[1].split(" ").map(Number);
+                if (coords.length === 2) {
+                    return coords[1]; // latitude is second coordinate
+                }
+            }
+        }
+    }
+    catch (error) {
+        console.warn("Error extracting latitude:", error);
+    }
+    return null;
+}
+function extractLongitude(location) {
+    try {
+        if (typeof location === "object" && location !== null) {
+            if ("coordinates" in location && Array.isArray(location.coordinates)) {
+                return location.coordinates[0]; // longitude is first coordinate
+            }
+            if ("x" in location) {
+                return location.x;
+            }
+        }
+        if (typeof location === "string") {
+            const match = location.match(/Point\(([^)]+)\)/);
+            if (match) {
+                const coords = match[1].split(" ").map(Number);
+                if (coords.length === 2) {
+                    return coords[0]; // longitude is first coordinate
+                }
+            }
+        }
+    }
+    catch (error) {
+        console.warn("Error extracting longitude:", error);
+    }
+    return null;
+}
 import { EnumWebResponse, IWebResponse, } from "../types/requests";
 import { addSignedUrlsToEvents, addSignedUrlToEvent } from "./storage";
 export async function server_create_tags(tags) {
@@ -195,13 +246,13 @@ export async function server_get_events_and_tags_for_devices_batch(device_ids, l
 }
 export async function get_event_and_tags_by_event_id(event_id) {
     const supabase = await newServerClient();
-    // use actual sql query to get event and tags instead of rpc
+    // Get event and tags
     const { data, error } = await supabase
         .from("events")
         .select(`
       *,
       tags: tags (*)
-      `)
+    `)
         .eq("id", event_id);
     if (error) {
         console.warn("Error fetching event with tags by event id:", error.message);
@@ -218,6 +269,20 @@ export async function get_event_and_tags_by_event_id(event_id) {
             data: null,
         };
     }
+    // Get herd_id from device
+    const { data: deviceData, error: deviceError } = await supabase
+        .from("devices")
+        .select("herd_id")
+        .eq("id", data[0].device_id)
+        .single();
+    if (deviceError) {
+        console.warn("Error fetching device herd_id:", deviceError.message);
+        return {
+            status: EnumWebResponse.ERROR,
+            msg: deviceError.message,
+            data: null,
+        };
+    }
     // Transform location to latitude/longitude with better error handling
     let latitude = null;
     let longitude = null;
@@ -266,7 +331,22 @@ export async function get_event_and_tags_by_event_id(event_id) {
         device_id: data[0].device_id,
         timestamp_observation: data[0].timestamp_observation,
         is_public: data[0].is_public,
-        tags: data[0].tags || [],
+        herd_id: deviceData.herd_id,
+        tags: (data[0].tags || []).map((tag) => ({
+            id: tag.id,
+            inserted_at: tag.inserted_at,
+            x: tag.x,
+            y: tag.y,
+            width: tag.width,
+            conf: tag.conf,
+            observation_type: tag.observation_type,
+            event_id: tag.event_id,
+            class_name: tag.class_name,
+            height: tag.height,
+            location: tag.location,
+            latitude: tag.location ? extractLatitude(tag.location) : null,
+            longitude: tag.location ? extractLongitude(tag.location) : null,
+        })),
         earthranger_url: data[0].earthranger_url,
         file_path: data[0].file_path,
     };

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export * from "./types/bounding_boxes";
 export * from "./types/events";
 export * from "./helpers/auth";
 export * from "./helpers/bounding_boxes";
+export * from "./helpers/chat";
 export * from "./helpers/db";
 export * from "./helpers/devices";
 export * from "./helpers/email";

package/dist/index.js

@@ -14,6 +14,7 @@ export * from "./types/events";
 // Helpers
 export * from "./helpers/auth";
 export * from "./helpers/bounding_boxes";
+export * from "./helpers/chat";
 export * from "./helpers/db";
 export * from "./helpers/devices";
 export * from "./helpers/email";

package/dist/providers/ScoutRefreshProvider.d.ts

@@ -52,18 +52,21 @@ export declare function useSupabase(): SupabaseClient<Database, "public", {
                 file_path: string;
                 id: number;
                 session_id: number | null;
+                timestamp_observation: string | null;
             };
             Insert: {
                 created_at?: string;
                 file_path: string;
                 id?: number;
                 session_id?: number | null;
+                timestamp_observation?: string | null;
             };
             Update: {
                 created_at?: string;
                 file_path?: string;
                 id?: number;
                 session_id?: number | null;
+                timestamp_observation?: string | null;
             };
             Relationships: [{
                 foreignKeyName: "artifacts_session_id_fkey";
@@ -465,6 +468,7 @@ export declare function useSupabase(): SupabaseClient<Database, "public", {
                 height: number;
                 id: number;
                 inserted_at: string;
+                location: unknown | null;
                 observation_type: Database["public"]["Enums"]["tag_observation_type"];
                 width: number;
                 x: number;
@@ -477,6 +481,7 @@ export declare function useSupabase(): SupabaseClient<Database, "public", {
                 height?: number;
                 id?: number;
                 inserted_at?: string;
+                location?: unknown | null;
                 observation_type: Database["public"]["Enums"]["tag_observation_type"];
                 width: number;
                 x: number;
@@ -489,6 +494,7 @@ export declare function useSupabase(): SupabaseClient<Database, "public", {
                 height?: number;
                 id?: number;
                 inserted_at?: string;
+                location?: unknown | null;
                 observation_type?: Database["public"]["Enums"]["tag_observation_type"];
                 width?: number;
                 x?: number;
@@ -890,7 +896,7 @@ export declare function useSupabase(): SupabaseClient<Database, "public", {
             device_id: number | null;
             timestamp_observation: string | null;
             is_public: boolean | null;
-            tags: Database["public"]["Tables"]["tags"]["Row"][] | null;
+            tags: Database["public"]["CompositeTypes"]["tags_pretty_location"][] | null;
             herd_id: number | null;
         };
         event_plus_tags: {
@@ -941,6 +947,21 @@ export declare function useSupabase(): SupabaseClient<Database, "public", {
             distance_total: number | null;
             distance_max_from_start: number | null;
         };
+        tags_pretty_location: {
+            id: number | null;
+            inserted_at: string | null;
+            x: number | null;
+            y: number | null;
+            width: number | null;
+            conf: number | null;
+            observation_type: Database["public"]["Enums"]["tag_observation_type"] | null;
+            event_id: number | null;
+            class_name: string | null;
+            height: number | null;
+            location: unknown | null;
+            latitude: number | null;
+            longitude: number | null;
+        };
         zones_and_actions_pretty_location: {
             id: number | null;
             inserted_at: string | null;

package/dist/supabase/server.d.ts

@@ -43,18 +43,21 @@ export declare function newServerClient(): Promise<import("@supabase/supabase-js
                 file_path: string;
                 id: number;
                 session_id: number | null;
+                timestamp_observation: string | null;
             };
             Insert: {
                 created_at?: string;
                 file_path: string;
                 id?: number;
                 session_id?: number | null;
+                timestamp_observation?: string | null;
             };
             Update: {
                 created_at?: string;
                 file_path?: string;
                 id?: number;
                 session_id?: number | null;
+                timestamp_observation?: string | null;
             };
             Relationships: [{
                 foreignKeyName: "artifacts_session_id_fkey";
@@ -456,6 +459,7 @@ export declare function newServerClient(): Promise<import("@supabase/supabase-js
                 height: number;
                 id: number;
                 inserted_at: string;
+                location: unknown | null;
                 observation_type: Database["public"]["Enums"]["tag_observation_type"];
                 width: number;
                 x: number;
@@ -468,6 +472,7 @@ export declare function newServerClient(): Promise<import("@supabase/supabase-js
                 height?: number;
                 id?: number;
                 inserted_at?: string;
+                location?: unknown | null;
                 observation_type: Database["public"]["Enums"]["tag_observation_type"];
                 width: number;
                 x: number;
@@ -480,6 +485,7 @@ export declare function newServerClient(): Promise<import("@supabase/supabase-js
                 height?: number;
                 id?: number;
                 inserted_at?: string;
+                location?: unknown | null;
                 observation_type?: Database["public"]["Enums"]["tag_observation_type"];
                 width?: number;
                 x?: number;
@@ -881,7 +887,7 @@ export declare function newServerClient(): Promise<import("@supabase/supabase-js
             device_id: number | null;
             timestamp_observation: string | null;
             is_public: boolean | null;
-            tags: Database["public"]["Tables"]["tags"]["Row"][] | null;
+            tags: Database["public"]["CompositeTypes"]["tags_pretty_location"][] | null;
             herd_id: number | null;
         };
         event_plus_tags: {
@@ -932,6 +938,21 @@ export declare function newServerClient(): Promise<import("@supabase/supabase-js
             distance_total: number | null;
             distance_max_from_start: number | null;
         };
+        tags_pretty_location: {
+            id: number | null;
+            inserted_at: string | null;
+            x: number | null;
+            y: number | null;
+            width: number | null;
+            conf: number | null;
+            observation_type: Database["public"]["Enums"]["tag_observation_type"] | null;
+            event_id: number | null;
+            class_name: string | null;
+            height: number | null;
+            location: unknown | null;
+            latitude: number | null;
+            longitude: number | null;
+        };
         zones_and_actions_pretty_location: {
             id: number | null;
             inserted_at: string | null;

package/dist/types/db.d.ts

@@ -7,10 +7,11 @@ export type TagObservationType = Database["public"]["Enums"]["tag_observation_ty
 export type IUser = User;
 export type IDevice = Database["public"]["CompositeTypes"]["device_pretty_location"] & {
     api_keys_scout?: IApiKeyScout[];
-    recent_events?: IEventWithTags[];
+    recent_events?: IEventAndTagsPrettyLocation[];
 };
 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 IPlan = Database["public"]["Tables"]["plans"]["Row"];
 export type ILayer = Database["public"]["Tables"]["layers"]["Row"];
 export type IAction = Database["public"]["Tables"]["actions"]["Row"];

package/dist/types/supabase.d.ts

@@ -52,18 +52,21 @@ export type Database = {
                     file_path: string;
                     id: number;
                     session_id: number | null;
+                    timestamp_observation: string | null;
                 };
                 Insert: {
                     created_at?: string;
                     file_path: string;
                     id?: number;
                     session_id?: number | null;
+                    timestamp_observation?: string | null;
                 };
                 Update: {
                     created_at?: string;
                     file_path?: string;
                     id?: number;
                     session_id?: number | null;
+                    timestamp_observation?: string | null;
                 };
                 Relationships: [
                     {
@@ -486,6 +489,7 @@ export type Database = {
                     height: number;
                     id: number;
                     inserted_at: string;
+                    location: unknown | null;
                     observation_type: Database["public"]["Enums"]["tag_observation_type"];
                     width: number;
                     x: number;
@@ -498,6 +502,7 @@ export type Database = {
                     height?: number;
                     id?: number;
                     inserted_at?: string;
+                    location?: unknown | null;
                     observation_type: Database["public"]["Enums"]["tag_observation_type"];
                     width: number;
                     x: number;
@@ -510,6 +515,7 @@ export type Database = {
                     height?: number;
                     id?: number;
                     inserted_at?: string;
+                    location?: unknown | null;
                     observation_type?: Database["public"]["Enums"]["tag_observation_type"];
                     width?: number;
                     x?: number;
@@ -930,7 +936,7 @@ export type Database = {
                 device_id: number | null;
                 timestamp_observation: string | null;
                 is_public: boolean | null;
-                tags: Database["public"]["Tables"]["tags"]["Row"][] | null;
+                tags: Database["public"]["CompositeTypes"]["tags_pretty_location"][] | null;
                 herd_id: number | null;
             };
             event_plus_tags: {
@@ -981,6 +987,21 @@ export type Database = {
                 distance_total: number | null;
                 distance_max_from_start: number | null;
             };
+            tags_pretty_location: {
+                id: number | null;
+                inserted_at: string | null;
+                x: number | null;
+                y: number | null;
+                width: number | null;
+                conf: number | null;
+                observation_type: Database["public"]["Enums"]["tag_observation_type"] | null;
+                event_id: number | null;
+                class_name: string | null;
+                height: number | null;
+                location: unknown | null;
+                latitude: number | null;
+                longitude: number | null;
+            };
             zones_and_actions_pretty_location: {
                 id: number | null;
                 inserted_at: string | null;

package/helpers/README.md

@@ -0,0 +1,135 @@
+# Scout Core Helpers
+
+## Storage and Signed URLs
+
+This module provides functionality for handling file storage and signed URL generation for media files.
+
+### Key Features
+
+- **Signed URL Generation**: Generate secure, time-limited URLs for accessing media files
+- **Backward Compatibility**: Support for both new signed URLs and legacy public URLs
+- **Seamless Integration**: Signed URLs are automatically set as `media_url` for easy use
+- **Efficient Client Usage**: Accepts existing Supabase client to avoid creating multiple instances
+
+### Files
+
+- **`storage.ts`**: Server-side functions for generating signed URLs (requires "use server")
+- **`eventUtils.ts`**: Client-side utility functions for working with event media URLs
+
+### Storage Functions (Server-side)
+
+#### `generateSignedUrl(filePath, expiresIn, supabaseClient?)`
+
+Generates a signed URL for a file in Supabase storage.
+
+```typescript
+// With existing client
+const signedUrl = await generateSignedUrl(
+  "events/123/image.jpg",
+  3600,
+  supabaseClient
+);
+
+// Without existing client (creates new one)
+const signedUrl = await generateSignedUrl("events/123/image.jpg", 3600);
+```
+
+#### `addSignedUrlsToEvents(events, supabaseClient?)`
+
+Adds signed URLs to an array of events, setting them as `media_url`.
+
+```typescript
+// With existing client
+const eventsWithUrls = await addSignedUrlsToEvents(events, supabaseClient);
+
+// Without existing client (creates new one)
+const eventsWithUrls = await addSignedUrlsToEvents(events);
+```
+
+#### `addSignedUrlToEvent(event, supabaseClient?)`
+
+Adds a signed URL to a single event, setting it as `media_url`.
+
+```typescript
+// With existing client
+const eventWithUrl = await addSignedUrlToEvent(event, supabaseClient);
+
+// Without existing client (creates new one)
+const eventWithUrl = await addSignedUrlToEvent(event);
+```
+
+### Event Utility Functions (Client-side)
+
+#### `getEventMediaUrl(event)`
+
+Gets the media URL for an event (now simply returns `event.media_url`).
+
+```typescript
+const mediaUrl = getEventMediaUrl(event);
+```
+
+#### `hasEventMedia(event)`
+
+Checks if an event has any media URL available.
+
+```typescript
+const hasMedia = hasEventMedia(event);
+```
+
+### Usage in Components
+
+```typescript
+import { getEventMediaUrl, hasEventMedia } from "@adventurelabs/scout-core";
+
+function EventMedia({ event }) {
+  const mediaUrl = getEventMediaUrl(event);
+
+  if (!hasEventMedia(event)) {
+    return <div>No media available</div>;
+  }
+
+  return <img src={mediaUrl} alt="Event media" />;
+}
+```
+
+### Database Schema
+
+Events now have two URL-related fields:
+
+- `file_path`: The storage path for generating signed URLs
+- `media_url`: The URL for accessing media (signed URL when file_path exists, legacy public URL otherwise)
+
+### How It Works
+
+1. **Event Creation**: Files are uploaded and `file_path` is stored (no `media_url` initially)
+2. **Event Fetching**: When events are retrieved, signed URLs are generated and set as `media_url`
+3. **URL Access**: Components simply use `event.media_url` as before
+4. **Fallback**: If signed URL generation fails, existing `media_url` is preserved
+
+### Performance Optimization
+
+The storage functions accept an optional `supabaseClient` parameter to reuse existing client instances:
+
+```typescript
+// Efficient: Reuse existing client
+const supabase = await newServerClient();
+const events = await fetchEvents(supabase);
+const eventsWithUrls = await addSignedUrlsToEvents(events, supabase);
+
+// Less efficient: Creates new client for each operation
+const events = await fetchEvents();
+const eventsWithUrls = await addSignedUrlsToEvents(events); // Creates new client
+```
+
+### Migration Strategy
+
+1. **Phase 1**: Store `file_path` for new events (no `media_url`)
+2. **Phase 2**: Generate signed URLs on fetch and set as `media_url`
+3. **Phase 3**: All events use signed URLs seamlessly
+
+### Security Benefits
+
+- **Time-limited access**: URLs expire after a configurable time
+- **Secure access**: URLs are cryptographically signed
+- **No public exposure**: Files are not publicly accessible without signed URLs
+- **Seamless integration**: No changes needed in existing components

package/hooks/README.md

@@ -0,0 +1,93 @@
+# Scout Hooks
+
+This directory contains React hooks for the Scout application.
+
+## useScoutRefresh
+
+A hook for refreshing scout data with detailed timing measurements for performance monitoring and debugging.
+
+### Features
+
+- **Automatic refresh**: Automatically refreshes data on component mount
+- **Manual refresh**: Provides a function to manually trigger refreshes
+- **Detailed timing**: Measures the duration of each portion of the loading process
+- **Concurrent protection**: Prevents multiple simultaneous refresh operations
+- **Error handling**: Graceful error handling with state consistency
+
+### Timing Measurements
+
+The hook tracks the duration of several key operations:
+
+1. **Herd Modules API Call** (`herd_modules_api_duration_ms`): Time taken to fetch herd modules from the server
+2. **User API Call** (`user_api_duration_ms`): Time taken to fetch user data from the server
+3. **Data Processing** (`data_processing_duration_ms`): Time taken to process and dispatch data to the store
+4. **LocalStorage Operations** (`localStorage_duration_ms`): Time taken for localStorage read/write operations
+5. **Total Duration** (`herd_modules_loaded_in_ms`): Overall time from start to completion
+
+### Usage
+
+```tsx
+import { useScoutRefresh } from "../hooks";
+
+function MyComponent() {
+  const { handleRefresh, getTimingStats } = useScoutRefresh({
+    autoRefresh: true,
+    onRefreshComplete: () => {
+      console.log("Refresh completed!");
+    },
+  });
+
+  const handleManualRefresh = async () => {
+    await handleRefresh();
+
+    // Get timing statistics
+    const stats = getTimingStats();
+    console.log("Performance breakdown:");
+    console.log(`- Herd modules API: ${stats.herdModulesApi}ms`);
+    console.log(`- User API: ${stats.userApi}ms`);
+    console.log(`- Data processing: ${stats.dataProcessing}ms`);
+    console.log(`- LocalStorage: ${stats.localStorage}ms`);
+    console.log(`- Total: ${stats.totalDuration}ms`);
+  };
+
+  return (
+    <div>
+      <button onClick={handleManualRefresh}>Refresh Data</button>
+    </div>
+  );
+}
+```
+
+### Redux State
+
+The hook automatically updates the Redux store with timing information:
+
+```tsx
+// Access timing data from the store
+const timingData = useSelector((state) => ({
+  herdModulesApi: state.scout.herd_modules_api_duration_ms,
+  userApi: state.scout.user_api_duration_ms,
+  dataProcessing: state.scout.data_processing_duration_ms,
+  localStorage: state.scout.localStorage_duration_ms,
+  total: state.scout.herd_modules_loaded_in_ms,
+}));
+```
+
+### Performance Monitoring
+
+Use these timing measurements to:
+
+- Identify performance bottlenecks in the loading process
+- Monitor API response times
+- Track data processing efficiency
+- Debug localStorage performance issues
+- Set performance budgets and alerts
+
+### Error Handling
+
+The hook includes comprehensive error handling:
+
+- API response validation
+- Graceful fallbacks for localStorage failures
+- Consistent state updates even on errors
+- Detailed error logging for debugging

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adventurelabs/scout-core",
-  "version": "1.0.69",
+  "version": "1.0.71",
   "description": "Core utilities and helpers for Adventure Labs Scout applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -33,9 +33,9 @@
   },
   "homepage": "https://github.com/Adventurous-Bytes/scout#readme",
   "peerDependencies": {
+    "next": ">=15.0.0",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
-    "next": ">=15.0.0",
     "react-redux": ">=9.0.0"
   },
   "devDependencies": {
@@ -44,9 +44,9 @@
     "typescript": "^5.0.0"
   },
   "dependencies": {
-    "@supabase/supabase-js": "^2.53.0",
-    "@supabase/ssr": "^0.6.1",
     "@reduxjs/toolkit": "^2.0.0",
+    "@supabase/ssr": "^0.6.1",
+    "@supabase/supabase-js": "^2.53.0",
     "zustand": "^4.0.0"
   }
 }