@adventurelabs/scout-core 1.0.77 → 1.0.79

package/dist/helpers/cache-usage-example.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Example usage of the ScoutCache system
+ * This demonstrates how to use the cache-first loading pattern
+ */
+import { CacheStats, TimingStats } from "./cache";
+export declare function ExampleBasicUsage(): {
+    handleRefresh: () => Promise<void>;
+    clearCache: () => Promise<void>;
+    stats: () => TimingStats;
+    cacheStats: () => Promise<CacheStats>;
+};
+export declare function ExampleAdvancedCacheManagement(): Promise<void>;
+export declare function ExampleBackgroundPreloading(): Promise<void>;
+export declare function ExamplePerformanceMonitoring(): {
+    getTimingStats: () => TimingStats;
+    getCacheStats: () => Promise<CacheStats>;
+};

package/dist/helpers/cache-usage-example.js

@@ -0,0 +1,82 @@
+/**
+ * Example usage of the ScoutCache system
+ * This demonstrates how to use the cache-first loading pattern
+ */
+import { useScoutRefresh } from "../hooks/useScoutRefresh";
+import { scoutCache } from "./cache";
+// Example 1: Basic usage with cache-first loading
+export function ExampleBasicUsage() {
+    const { handleRefresh, getTimingStats, clearCache, getCacheStats } = useScoutRefresh({
+        autoRefresh: true,
+        cacheFirst: true,
+        cacheTtlMs: 10 * 60 * 1000, // 10 minutes
+        onRefreshComplete: () => {
+            console.log("Refresh completed!");
+        }
+    });
+    // Get timing stats
+    const stats = getTimingStats();
+    console.log("Performance stats:", stats);
+    // Get cache stats
+    const cacheStats = getCacheStats();
+    console.log("Cache stats:", cacheStats);
+    return {
+        handleRefresh,
+        clearCache,
+        stats: getTimingStats,
+        cacheStats: getCacheStats,
+    };
+}
+// Example 2: Advanced cache management
+export async function ExampleAdvancedCacheManagement() {
+    // Check if cache is valid
+    const isValid = await scoutCache.isCacheValid(5 * 60 * 1000); // 5 minutes
+    console.log("Cache is valid:", isValid);
+    // Check if we should refresh
+    const shouldRefresh = await scoutCache.shouldRefresh(2 * 60 * 1000, // max age 2 minutes
+    false // not forcing refresh
+    );
+    console.log("Should refresh:", shouldRefresh);
+    // Get cache age
+    const age = await scoutCache.getCacheAge();
+    console.log("Cache age:", Math.round(age / 1000), "seconds");
+    // Invalidate cache
+    await scoutCache.invalidateHerdModules();
+    console.log("Cache invalidated");
+    // Clear all cache data
+    await scoutCache.clearHerdModules();
+    console.log("Cache cleared");
+}
+// Example 3: Background preloading
+export async function ExampleBackgroundPreloading() {
+    // Simulate a function that loads herd modules
+    const loadHerdModules = async () => {
+        // This would be your actual API call
+        const response = await fetch("/api/herd-modules");
+        return response.json();
+    };
+    // Preload cache in background
+    await scoutCache.preloadCache(loadHerdModules, 15 * 60 * 1000); // 15 minutes TTL
+    console.log("Background preload completed");
+}
+// Example 4: Performance monitoring
+export function ExamplePerformanceMonitoring() {
+    const { getTimingStats, getCacheStats } = useScoutRefresh({
+        cacheFirst: true,
+        onRefreshComplete: async () => {
+            const stats = getTimingStats();
+            const cacheStats = await getCacheStats();
+            console.log("=== Performance Report ===");
+            console.log("Total duration:", stats.totalDuration, "ms");
+            console.log("Cache load:", stats.cacheLoad, "ms");
+            console.log("API calls:", stats.herdModulesApi + stats.userApi, "ms");
+            console.log("Cache save:", stats.cacheSave, "ms");
+            console.log("Data processing:", stats.dataProcessing, "ms");
+            console.log("LocalStorage:", stats.localStorage, "ms");
+            console.log("Cache hit rate:", (cacheStats.hitRate * 100).toFixed(1) + "%");
+            console.log("Cache size:", cacheStats.size, "herd modules");
+            console.log("Cache age:", Math.round((Date.now() - cacheStats.lastUpdated) / 1000), "seconds");
+        }
+    });
+    return { getTimingStats, getCacheStats };
+}

package/dist/helpers/cache.d.ts

@@ -0,0 +1,52 @@
+import { IHerdModule } from "../types/herd_module";
+export interface CacheMetadata {
+    key: string;
+    timestamp: number;
+    ttl: number;
+    version: string;
+    etag?: string;
+    lastModified?: number;
+}
+export interface CacheResult<T> {
+    data: T | null;
+    isStale: boolean;
+    age: number;
+    metadata: CacheMetadata | null;
+}
+export interface CacheStats {
+    size: number;
+    lastUpdated: number;
+    isStale: boolean;
+    hitRate: number;
+    totalHits: number;
+    totalMisses: number;
+}
+export interface TimingStats {
+    totalDuration: number;
+    cacheLoad: number;
+    herdModulesApi: number;
+    userApi: number;
+    cacheSave: number;
+    dataProcessing: number;
+    localStorage: number;
+}
+export declare class ScoutCache {
+    private db;
+    private initPromise;
+    private stats;
+    private init;
+    setHerdModules(herdModules: IHerdModule[], ttlMs?: number, etag?: string): Promise<void>;
+    getHerdModules(): Promise<CacheResult<IHerdModule[]>>;
+    clearHerdModules(): Promise<void>;
+    invalidateHerdModules(): Promise<void>;
+    getCacheStats(): Promise<CacheStats>;
+    isCacheValid(ttlMs?: number): Promise<boolean>;
+    getCacheAge(): Promise<number>;
+    shouldRefresh(maxAgeMs?: number, forceRefresh?: boolean): Promise<{
+        shouldRefresh: boolean;
+        reason: string;
+    }>;
+    preloadCache(loadFunction: () => Promise<IHerdModule[]>, ttlMs?: number): Promise<void>;
+    getDefaultTtl(): number;
+}
+export declare const scoutCache: ScoutCache;

package/dist/helpers/cache.js

@@ -0,0 +1,223 @@
+const DB_NAME = "ScoutCache";
+const DB_VERSION = 1;
+const HERD_MODULES_STORE = "herd_modules";
+const CACHE_METADATA_STORE = "cache_metadata";
+// Default TTL: 24 hours (1 day)
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+export class ScoutCache {
+    constructor() {
+        this.db = null;
+        this.initPromise = null;
+        this.stats = {
+            hits: 0,
+            misses: 0,
+        };
+    }
+    async init() {
+        if (this.db)
+            return;
+        if (this.initPromise)
+            return this.initPromise;
+        this.initPromise = new Promise((resolve, reject) => {
+            const request = indexedDB.open(DB_NAME, DB_VERSION);
+            request.onerror = () => {
+                console.error("[ScoutCache] Failed to open IndexedDB:", request.error);
+                reject(request.error);
+            };
+            request.onsuccess = () => {
+                this.db = request.result;
+                console.log("[ScoutCache] IndexedDB initialized successfully");
+                resolve();
+            };
+            request.onupgradeneeded = (event) => {
+                const db = event.target.result;
+                // Create herd modules store
+                if (!db.objectStoreNames.contains(HERD_MODULES_STORE)) {
+                    const herdModulesStore = db.createObjectStore(HERD_MODULES_STORE, {
+                        keyPath: "herdId",
+                    });
+                    herdModulesStore.createIndex("timestamp", "timestamp", {
+                        unique: false,
+                    });
+                }
+                // Create cache metadata store
+                if (!db.objectStoreNames.contains(CACHE_METADATA_STORE)) {
+                    const metadataStore = db.createObjectStore(CACHE_METADATA_STORE, {
+                        keyPath: "key",
+                    });
+                }
+                console.log("[ScoutCache] Database schema upgraded");
+            };
+        });
+        return this.initPromise;
+    }
+    async setHerdModules(herdModules, ttlMs = DEFAULT_TTL_MS, etag) {
+        await this.init();
+        if (!this.db)
+            throw new Error("Database not initialized");
+        const transaction = this.db.transaction([HERD_MODULES_STORE, CACHE_METADATA_STORE], "readwrite");
+        return new Promise((resolve, reject) => {
+            transaction.onerror = () => reject(transaction.error);
+            transaction.oncomplete = () => resolve();
+            const herdModulesStore = transaction.objectStore(HERD_MODULES_STORE);
+            const metadataStore = transaction.objectStore(CACHE_METADATA_STORE);
+            const timestamp = Date.now();
+            const version = "1.0.0";
+            // Store each herd module
+            herdModules.forEach((herdModule) => {
+                const cacheEntry = {
+                    herdId: herdModule.herd.id.toString(),
+                    data: herdModule,
+                    timestamp,
+                };
+                herdModulesStore.put(cacheEntry);
+            });
+            // Store cache metadata
+            const metadata = {
+                key: "herd_modules",
+                timestamp,
+                ttl: ttlMs,
+                version,
+                etag,
+                lastModified: timestamp,
+            };
+            metadataStore.put(metadata);
+        });
+    }
+    async getHerdModules() {
+        await this.init();
+        if (!this.db)
+            throw new Error("Database not initialized");
+        const transaction = this.db.transaction([HERD_MODULES_STORE, CACHE_METADATA_STORE], "readonly");
+        return new Promise((resolve, reject) => {
+            transaction.onerror = () => reject(transaction.error);
+            const herdModulesStore = transaction.objectStore(HERD_MODULES_STORE);
+            const metadataStore = transaction.objectStore(CACHE_METADATA_STORE);
+            // Get metadata first
+            const metadataRequest = metadataStore.get("herd_modules");
+            metadataRequest.onsuccess = () => {
+                const metadata = metadataRequest.result;
+                const now = Date.now();
+                if (!metadata) {
+                    this.stats.misses++;
+                    resolve({ data: null, isStale: true, age: 0, metadata: null });
+                    return;
+                }
+                const age = now - metadata.timestamp;
+                const isStale = age > metadata.ttl;
+                // Get all herd modules
+                const getAllRequest = herdModulesStore.getAll();
+                getAllRequest.onsuccess = () => {
+                    const cacheEntries = getAllRequest.result;
+                    const herdModules = cacheEntries
+                        .filter((entry) => entry.data && entry.data.herd && entry.data.herd.slug)
+                        .map((entry) => entry.data)
+                        .sort((a, b) => (a.herd?.slug || "").localeCompare(b.herd?.slug || ""));
+                    // Update stats
+                    if (herdModules.length > 0) {
+                        this.stats.hits++;
+                    }
+                    else {
+                        this.stats.misses++;
+                    }
+                    resolve({
+                        data: herdModules,
+                        isStale,
+                        age,
+                        metadata,
+                    });
+                };
+            };
+        });
+    }
+    async clearHerdModules() {
+        await this.init();
+        if (!this.db)
+            throw new Error("Database not initialized");
+        const transaction = this.db.transaction([HERD_MODULES_STORE, CACHE_METADATA_STORE], "readwrite");
+        return new Promise((resolve, reject) => {
+            transaction.onerror = () => reject(transaction.error);
+            transaction.oncomplete = () => resolve();
+            const herdModulesStore = transaction.objectStore(HERD_MODULES_STORE);
+            const metadataStore = transaction.objectStore(CACHE_METADATA_STORE);
+            herdModulesStore.clear();
+            metadataStore.delete("herd_modules");
+        });
+    }
+    async invalidateHerdModules() {
+        await this.init();
+        if (!this.db)
+            throw new Error("Database not initialized");
+        const transaction = this.db.transaction([CACHE_METADATA_STORE], "readwrite");
+        return new Promise((resolve, reject) => {
+            transaction.onerror = () => reject(transaction.error);
+            transaction.oncomplete = () => resolve();
+            const metadataStore = transaction.objectStore(CACHE_METADATA_STORE);
+            metadataStore.delete("herd_modules");
+        });
+    }
+    async getCacheStats() {
+        const result = await this.getHerdModules();
+        const totalRequests = this.stats.hits + this.stats.misses;
+        const hitRate = totalRequests > 0 ? this.stats.hits / totalRequests : 0;
+        return {
+            size: result.data?.length || 0,
+            lastUpdated: result.data ? Date.now() - result.age : 0,
+            isStale: result.isStale,
+            hitRate: Math.round(hitRate * 100) / 100,
+            totalHits: this.stats.hits,
+            totalMisses: this.stats.misses,
+        };
+    }
+    async isCacheValid(ttlMs) {
+        const result = await this.getHerdModules();
+        if (!result.data || !result.metadata)
+            return false;
+        const effectiveTtl = ttlMs || result.metadata.ttl;
+        return !result.isStale && result.age < effectiveTtl;
+    }
+    async getCacheAge() {
+        const result = await this.getHerdModules();
+        return result.age;
+    }
+    // Method to check if we should refresh based on various conditions
+    async shouldRefresh(maxAgeMs, forceRefresh) {
+        if (forceRefresh) {
+            return { shouldRefresh: true, reason: "Force refresh requested" };
+        }
+        const result = await this.getHerdModules();
+        if (!result.data || result.data.length === 0) {
+            return { shouldRefresh: true, reason: "No cached data" };
+        }
+        if (result.isStale) {
+            return { shouldRefresh: true, reason: "Cache is stale" };
+        }
+        if (maxAgeMs && result.age > maxAgeMs) {
+            return {
+                shouldRefresh: true,
+                reason: `Cache age (${Math.round(result.age / 1000)}s) exceeds max age (${Math.round(maxAgeMs / 1000)}s)`,
+            };
+        }
+        return { shouldRefresh: false, reason: "Cache is valid and fresh" };
+    }
+    // Method to preload cache with background refresh
+    async preloadCache(loadFunction, ttlMs = DEFAULT_TTL_MS) {
+        try {
+            console.log("[ScoutCache] Starting background cache preload...");
+            const startTime = Date.now();
+            const herdModules = await loadFunction();
+            await this.setHerdModules(herdModules, ttlMs);
+            const duration = Date.now() - startTime;
+            console.log(`[ScoutCache] Background preload completed in ${duration}ms`);
+        }
+        catch (error) {
+            console.warn("[ScoutCache] Background preload failed:", error);
+        }
+    }
+    // Get the default TTL value
+    getDefaultTtl() {
+        return DEFAULT_TTL_MS;
+    }
+}
+// Singleton instance
+export const scoutCache = new ScoutCache();

package/dist/helpers/index.d.ts

@@ -16,3 +16,4 @@ export * from "./ui";
 export * from "./users";
 export * from "./web";
 export * from "./zones";
+export * from "./cache";

package/dist/helpers/index.js

@@ -16,3 +16,4 @@ export * from "./ui";
 export * from "./users";
 export * from "./web";
 export * from "./zones";
+export * from "./cache";

package/dist/hooks/data-source-usage-example.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Example components demonstrating how to use data source tracking
+ */
+export declare function DataSourceIndicator(): import("react/jsx-runtime").JSX.Element;
+export declare function ConditionalContent(): import("react/jsx-runtime").JSX.Element;
+export declare function PerformanceMetrics(): import("react/jsx-runtime").JSX.Element;
+export declare function SmartRefreshButton(): import("react/jsx-runtime").JSX.Element;
+export declare function HeaderWithDataSource(): import("react/jsx-runtime").JSX.Element;
+export declare function DataSourceDebugger(): import("react/jsx-runtime").JSX.Element;

package/dist/hooks/data-source-usage-example.js

@@ -0,0 +1,68 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useDataSource, useDataSourceDescription } from './useDataSource';
+import { useScoutRefresh } from './useScoutRefresh';
+// Example 1: Basic data source display
+export function DataSourceIndicator() {
+    const { dataSource, isFromCache, cacheAge, isStale } = useDataSource();
+    const description = useDataSourceDescription();
+    return (_jsxs("div", { className: "data-source-indicator", children: [_jsx("div", { className: `source-badge ${dataSource.toLowerCase()}`, children: dataSource }), _jsxs("div", { className: "source-details", children: [_jsx("p", { children: description }), isFromCache && (_jsxs("div", { className: "cache-info", children: [_jsxs("span", { children: ["Cache age: ", Math.round(cacheAge / 1000), "s"] }), _jsx("span", { className: isStale ? 'stale' : 'fresh', children: isStale ? 'Stale' : 'Fresh' })] }))] })] }));
+}
+// Example 2: Conditional rendering based on data source
+export function ConditionalContent() {
+    const { isFromCache, isFromDatabase, isStale } = useDataSource();
+    return (_jsxs("div", { children: [isFromCache && (_jsx("div", { className: "cache-notice", children: isStale ? (_jsx("p", { children: "\u26A0\uFE0F Showing cached data (may be outdated)" })) : (_jsx("p", { children: "\u2705 Showing fresh cached data" })) })), isFromDatabase && (_jsx("div", { className: "database-notice", children: _jsx("p", { children: "\uD83D\uDD04 Showing live data from database" }) }))] }));
+}
+// Example 3: Performance metrics with data source
+export function PerformanceMetrics() {
+    const { dataSource, cacheAge } = useDataSource();
+    const { getTimingStats, getCacheStats } = useScoutRefresh();
+    const handleShowMetrics = () => {
+        const timing = getTimingStats();
+        console.log('Performance Metrics:', {
+            dataSource,
+            cacheAge: cacheAge ? Math.round(cacheAge / 1000) : 'N/A',
+            totalDuration: timing.totalDuration,
+            cacheLoad: timing.cacheLoad,
+            apiCalls: timing.herdModulesApi + timing.userApi,
+        });
+    };
+    return (_jsxs("div", { className: "performance-metrics", children: [_jsx("h3", { children: "Performance Metrics" }), _jsxs("p", { children: ["Data Source: ", dataSource] }), cacheAge && _jsxs("p", { children: ["Cache Age: ", Math.round(cacheAge / 1000), "s"] }), _jsx("button", { onClick: handleShowMetrics, children: "Show Detailed Metrics" })] }));
+}
+// Example 4: Data source aware refresh button
+export function SmartRefreshButton() {
+    const { isFromCache, isStale, cacheAge } = useDataSource();
+    const { handleRefresh } = useScoutRefresh();
+    const getButtonText = () => {
+        if (isFromCache) {
+            if (isStale) {
+                return 'Refresh Stale Data';
+            }
+            else {
+                const ageSeconds = Math.round(cacheAge / 1000);
+                return `Refresh (${ageSeconds}s old)`;
+            }
+        }
+        return 'Refresh Data';
+    };
+    const getButtonStyle = () => {
+        if (isFromCache && isStale) {
+            return 'refresh-button stale';
+        }
+        else if (isFromCache) {
+            return 'refresh-button cached';
+        }
+        return 'refresh-button fresh';
+    };
+    return (_jsx("button", { className: getButtonStyle(), onClick: handleRefresh, children: getButtonText() }));
+}
+// Example 5: Data source status in header
+export function HeaderWithDataSource() {
+    const description = useDataSourceDescription();
+    const { handleRefresh } = useScoutRefresh();
+    return (_jsxs("header", { className: "app-header", children: [_jsx("h1", { children: "Scout Dashboard" }), _jsxs("div", { className: "header-controls", children: [_jsx("span", { className: "data-source-status", children: description }), _jsx("button", { onClick: handleRefresh, children: "Refresh" })] })] }));
+}
+// Example 6: Data source debugging component
+export function DataSourceDebugger() {
+    const { dataSource, dataSourceInfo, isFromCache, isFromDatabase, isUnknown } = useDataSource();
+    return (_jsxs("div", { className: "data-source-debugger", children: [_jsx("h3", { children: "Data Source Debug Info" }), _jsxs("div", { className: "debug-info", children: [_jsxs("p", { children: [_jsx("strong", { children: "Source:" }), " ", dataSource] }), _jsxs("p", { children: [_jsx("strong", { children: "From Cache:" }), " ", isFromCache ? 'Yes' : 'No'] }), _jsxs("p", { children: [_jsx("strong", { children: "From Database:" }), " ", isFromDatabase ? 'Yes' : 'No'] }), _jsxs("p", { children: [_jsx("strong", { children: "Unknown:" }), " ", isUnknown ? 'Yes' : 'No'] }), dataSourceInfo && (_jsxs("div", { className: "detailed-info", children: [_jsxs("p", { children: [_jsx("strong", { children: "Timestamp:" }), " ", new Date(dataSourceInfo.timestamp).toISOString()] }), dataSourceInfo.cacheAge && (_jsxs("p", { children: [_jsx("strong", { children: "Cache Age:" }), " ", Math.round(dataSourceInfo.cacheAge / 1000), "s"] })), typeof dataSourceInfo.isStale === 'boolean' && (_jsxs("p", { children: [_jsx("strong", { children: "Is Stale:" }), " ", dataSourceInfo.isStale ? 'Yes' : 'No'] }))] }))] })] }));
+}

package/dist/hooks/useDataSource.d.ts

@@ -0,0 +1,43 @@
+import { EnumDataSource, IDataSourceInfo } from "../types/data_source";
+/**
+ * Hook to access data source information from the Redux store
+ *
+ * @returns Object containing:
+ * - dataSource: The current data source (CACHE, DATABASE, or UNKNOWN)
+ * - dataSourceInfo: Detailed information about the data source
+ * - isFromCache: Boolean indicating if data is from cache
+ * - isFromDatabase: Boolean indicating if data is from database
+ * - cacheAge: Age of cached data in milliseconds (if from cache)
+ * - isStale: Whether cached data is stale (if from cache)
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { dataSource, isFromCache, cacheAge, isStale } = useDataSource();
+ *
+ *   return (
+ *     <div>
+ *       <p>Data source: {dataSource}</p>
+ *       {isFromCache && (
+ *         <p>Cache age: {Math.round(cacheAge! / 1000)}s, Stale: {isStale ? 'Yes' : 'No'}</p>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useDataSource(): {
+    dataSource: EnumDataSource;
+    dataSourceInfo: IDataSourceInfo | null;
+    isFromCache: boolean;
+    isFromDatabase: boolean;
+    isUnknown: boolean;
+    cacheAge: number | undefined;
+    isStale: boolean | undefined;
+};
+/**
+ * Hook to get a human-readable description of the data source
+ *
+ * @returns String description of the current data source
+ */
+export declare function useDataSourceDescription(): string;

package/dist/hooks/useDataSource.js

@@ -0,0 +1,63 @@
+import { useSelector } from "react-redux";
+import { EnumDataSource } from "../types/data_source";
+/**
+ * Hook to access data source information from the Redux store
+ *
+ * @returns Object containing:
+ * - dataSource: The current data source (CACHE, DATABASE, or UNKNOWN)
+ * - dataSourceInfo: Detailed information about the data source
+ * - isFromCache: Boolean indicating if data is from cache
+ * - isFromDatabase: Boolean indicating if data is from database
+ * - cacheAge: Age of cached data in milliseconds (if from cache)
+ * - isStale: Whether cached data is stale (if from cache)
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { dataSource, isFromCache, cacheAge, isStale } = useDataSource();
+ *
+ *   return (
+ *     <div>
+ *       <p>Data source: {dataSource}</p>
+ *       {isFromCache && (
+ *         <p>Cache age: {Math.round(cacheAge! / 1000)}s, Stale: {isStale ? 'Yes' : 'No'}</p>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useDataSource() {
+    const dataSource = useSelector((state) => state.scout.data_source);
+    const dataSourceInfo = useSelector((state) => state.scout.data_source_info);
+    const isFromCache = dataSource === EnumDataSource.CACHE;
+    const isFromDatabase = dataSource === EnumDataSource.DATABASE;
+    const isUnknown = dataSource === EnumDataSource.UNKNOWN;
+    return {
+        dataSource,
+        dataSourceInfo,
+        isFromCache,
+        isFromDatabase,
+        isUnknown,
+        cacheAge: dataSourceInfo?.cacheAge,
+        isStale: dataSourceInfo?.isStale,
+    };
+}
+/**
+ * Hook to get a human-readable description of the data source
+ *
+ * @returns String description of the current data source
+ */
+export function useDataSourceDescription() {
+    const { dataSource, cacheAge, isStale } = useDataSource();
+    switch (dataSource) {
+        case EnumDataSource.CACHE:
+            const ageSeconds = cacheAge ? Math.round(cacheAge / 1000) : 0;
+            return `Loaded from cache (${ageSeconds}s old${isStale ? ', stale' : ', fresh'})`;
+        case EnumDataSource.DATABASE:
+            return 'Loaded from database (fresh data)';
+        case EnumDataSource.UNKNOWN:
+        default:
+            return 'Data source unknown';
+    }
+}

package/dist/hooks/useScoutRefresh.d.ts

@@ -1,21 +1,31 @@
+import { CacheStats, TimingStats } from "../helpers/cache";
 export interface UseScoutRefreshOptions {
     autoRefresh?: boolean;
     onRefreshComplete?: () => void;
+    cacheFirst?: boolean;
+    cacheTtlMs?: number;
 }
 /**
- * Hook for refreshing scout data with detailed timing measurements
+ * Hook for refreshing scout data with detailed timing measurements and cache-first loading
  *
  * @param options - Configuration options for the refresh behavior
  * @param options.autoRefresh - Whether to automatically refresh on mount (default: true)
  * @param options.onRefreshComplete - Callback function called when refresh completes
+ * @param options.cacheFirst - Whether to load from cache first, then refresh (default: true)
+ * @param options.cacheTtlMs - Cache time-to-live in milliseconds (default: 24 hours)
  *
  * @returns Object containing:
  * - handleRefresh: Function to manually trigger a refresh
  * - getTimingStats: Function to get detailed timing statistics for the last refresh
+ * - clearCache: Function to clear the cache
+ * - getCacheStats: Function to get cache statistics
  *
  * @example
  * ```tsx
- * const { handleRefresh, getTimingStats } = useScoutRefresh();
+ * const { handleRefresh, getTimingStats, clearCache, getCacheStats } = useScoutRefresh({
+ *   cacheFirst: true,
+ *   cacheTtlMs: 10 * 60 * 1000 // 10 minutes
+ * });
  *
  * // Get timing stats after a refresh
  * const stats = getTimingStats();
@@ -28,11 +38,7 @@ export interface UseScoutRefreshOptions {
  */
 export declare function useScoutRefresh(options?: UseScoutRefreshOptions): {
     handleRefresh: () => Promise<void>;
-    getTimingStats: () => {
-        totalDuration: number;
-        herdModulesApi: number;
-        userApi: number;
-        dataProcessing: number;
-        localStorage: number;
-    };
+    getTimingStats: () => TimingStats;
+    clearCache: () => Promise<void>;
+    getCacheStats: () => Promise<CacheStats>;
 };

package/dist/hooks/useScoutRefresh.js

@@ -1,24 +1,32 @@
 import { useEffect, useCallback, useRef } from "react";
 import { useAppDispatch } from "../store/hooks";
-import { EnumScoutStateStatus, setActiveHerdId, setHerdModules, setStatus, setHerdModulesLoadingState, setHerdModulesLoadedInMs, setHerdModulesApiDuration, setUserApiDuration, setDataProcessingDuration, setLocalStorageDuration, setUser, } from "../store/scout";
+import { EnumScoutStateStatus, setActiveHerdId, setHerdModules, setStatus, setHerdModulesLoadingState, setHerdModulesLoadedInMs, setHerdModulesApiDuration, setUserApiDuration, setDataProcessingDuration, setLocalStorageDuration, setUser, setDataSource, setDataSourceInfo, } from "../store/scout";
 import { EnumHerdModulesLoadingState } from "../types/herd_module";
 import { server_load_herd_modules } from "../helpers/herds";
 import { server_get_user } from "../helpers/users";
-import { EnumWebResponse } from "../types/requests";
+import { scoutCache } from "../helpers/cache";
+import { EnumDataSource } from "../types/data_source";
 /**
- * Hook for refreshing scout data with detailed timing measurements
+ * Hook for refreshing scout data with detailed timing measurements and cache-first loading
  *
  * @param options - Configuration options for the refresh behavior
  * @param options.autoRefresh - Whether to automatically refresh on mount (default: true)
  * @param options.onRefreshComplete - Callback function called when refresh completes
+ * @param options.cacheFirst - Whether to load from cache first, then refresh (default: true)
+ * @param options.cacheTtlMs - Cache time-to-live in milliseconds (default: 24 hours)
  *
  * @returns Object containing:
  * - handleRefresh: Function to manually trigger a refresh
  * - getTimingStats: Function to get detailed timing statistics for the last refresh
+ * - clearCache: Function to clear the cache
+ * - getCacheStats: Function to get cache statistics
  *
  * @example
  * ```tsx
- * const { handleRefresh, getTimingStats } = useScoutRefresh();
+ * const { handleRefresh, getTimingStats, clearCache, getCacheStats } = useScoutRefresh({
+ *   cacheFirst: true,
+ *   cacheTtlMs: 10 * 60 * 1000 // 10 minutes
+ * });
  *
  * // Get timing stats after a refresh
  * const stats = getTimingStats();
@@ -30,7 +38,8 @@ import { EnumWebResponse } from "../types/requests";
  * ```
  */
 export function useScoutRefresh(options = {}) {
-    const { autoRefresh = true, onRefreshComplete } = options;
+    const { autoRefresh = true, onRefreshComplete, cacheFirst = true, cacheTtlMs = 24 * 60 * 60 * 1000, // 24 hours default (1 day)
+     } = options;
     const dispatch = useAppDispatch();
     const refreshInProgressRef = useRef(false);
     // Refs to store timing measurements
@@ -40,6 +49,8 @@ export function useScoutRefresh(options = {}) {
         userApiDuration: 0,
         dataProcessingDuration: 0,
         localStorageDuration: 0,
+        cacheLoadDuration: 0,
+        cacheSaveDuration: 0,
     });
     const handleRefresh = useCallback(async () => {
         // Prevent concurrent refresh calls
@@ -53,14 +64,66 @@ export function useScoutRefresh(options = {}) {
         try {
             dispatch(setStatus(EnumScoutStateStatus.LOADING));
             dispatch(setHerdModulesLoadingState(EnumHerdModulesLoadingState.LOADING));
-            // Run API requests in parallel for better performance
-            console.log("[useScoutRefresh] Starting parallel API requests...");
+            let cachedHerdModules = null;
+            let cacheLoadDuration = 0;
+            // Step 1: Load from cache first if enabled
+            if (cacheFirst) {
+                const cacheStartTime = Date.now();
+                try {
+                    console.log("[useScoutRefresh] Loading from cache...");
+                    const cacheResult = await scoutCache.getHerdModules();
+                    cacheLoadDuration = Date.now() - cacheStartTime;
+                    timingRefs.current.cacheLoadDuration = cacheLoadDuration;
+                    if (cacheResult.data && cacheResult.data.length > 0) {
+                        cachedHerdModules = cacheResult.data;
+                        console.log(`[useScoutRefresh] Loaded ${cachedHerdModules.length} herd modules from cache in ${cacheLoadDuration}ms (age: ${Math.round(cacheResult.age / 1000)}s, stale: ${cacheResult.isStale})`);
+                        // Set data source to CACHE
+                        dispatch(setDataSource(EnumDataSource.CACHE));
+                        dispatch(setDataSourceInfo({
+                            source: EnumDataSource.CACHE,
+                            timestamp: Date.now(),
+                            cacheAge: cacheResult.age,
+                            isStale: cacheResult.isStale,
+                        }));
+                        // Immediately update the store with cached data
+                        dispatch(setHerdModules(cachedHerdModules));
+                        dispatch(setHerdModulesLoadingState(EnumHerdModulesLoadingState.SUCCESSFULLY_LOADED));
+                        // If cache is fresh, we can return early
+                        if (!cacheResult.isStale) {
+                            console.log("[useScoutRefresh] Cache is fresh, skipping API call");
+                            // Still need to load user data
+                            const userStartTime = Date.now();
+                            const res_new_user = await server_get_user();
+                            const userApiDuration = Date.now() - userStartTime;
+                            timingRefs.current.userApiDuration = userApiDuration;
+                            dispatch(setUserApiDuration(userApiDuration));
+                            if (res_new_user && res_new_user.data) {
+                                dispatch(setUser(res_new_user.data));
+                            }
+                            const totalDuration = Date.now() - startTime;
+                            dispatch(setHerdModulesLoadedInMs(totalDuration));
+                            dispatch(setStatus(EnumScoutStateStatus.DONE_LOADING));
+                            console.log(`[useScoutRefresh] Cache-first refresh completed in ${totalDuration}ms`);
+                            onRefreshComplete?.();
+                            return;
+                        }
+                    }
+                    else {
+                        console.log("[useScoutRefresh] No cached data found");
+                    }
+                }
+                catch (cacheError) {
+                    console.warn("[useScoutRefresh] Cache load failed:", cacheError);
+                    // Continue with API call
+                }
+            }
+            // Step 2: Load fresh data from API
+            console.log("[useScoutRefresh] Loading fresh data from API...");
             const parallelStartTime = Date.now();
             const [herdModulesResult, userResult] = await Promise.all([
                 (async () => {
                     const start = Date.now();
                     console.log(`[useScoutRefresh] Starting herd modules request at ${new Date(start).toISOString()}`);
-                    // High priority request with optimization
                     const result = await server_load_herd_modules();
                     const duration = Date.now() - start;
                     console.log(`[useScoutRefresh] Herd modules request completed in ${duration}ms`);
@@ -69,7 +132,6 @@ export function useScoutRefresh(options = {}) {
                 (async () => {
                     const start = Date.now();
                     console.log(`[useScoutRefresh] Starting user request at ${new Date(start).toISOString()}`);
-                    // High priority request with optimization
                     const result = await server_get_user();
                     const duration = Date.now() - start;
                     console.log(`[useScoutRefresh] User request completed in ${duration}ms`);
@@ -83,43 +145,12 @@ export function useScoutRefresh(options = {}) {
             const res_new_user = userResult.result;
             const herdModulesDuration = herdModulesResult.duration;
             const userApiDuration = userResult.duration;
-            // Calculate request timing breakdown
-            const requestStartTime = parallelStartTime;
-            const requestEndTime = Date.now();
-            const totalRequestTime = requestEndTime - requestStartTime;
-            console.log(`[useScoutRefresh] Request timing breakdown:`);
-            console.log(`  - Request started at: ${new Date(requestStartTime).toISOString()}`);
-            console.log(`  - Request completed at: ${new Date(requestEndTime).toISOString()}`);
-            console.log(`  - Total request time: ${totalRequestTime}ms`);
-            console.log(`  - Parallel execution time: ${parallelDuration}ms`);
-            console.log(`  - Request overhead: ${totalRequestTime - parallelDuration}ms`);
-            // Calculate network latency for herd modules
-            let networkLatencyMs = 0;
-            if (herdModulesResponse.status === EnumWebResponse.SUCCESS &&
-                herdModulesResponse.data) {
-                const serverFinishTime = herdModulesResponse.time_finished;
-                const clientReceiveTime = Date.now();
-                const estimatedNetworkLatency = clientReceiveTime - serverFinishTime;
-                networkLatencyMs = Math.max(0, estimatedNetworkLatency);
-                console.log(`[useScoutRefresh] Herd modules performance:`);
-                console.log(`  - Server processing: ${herdModulesResponse.server_processing_time_ms}ms`);
-                console.log(`  - Network latency: ${networkLatencyMs}ms`);
-                console.log(`  - Total client time: ${herdModulesDuration}ms`);
-            }
             // Store timing values
             timingRefs.current.herdModulesDuration = herdModulesDuration;
             timingRefs.current.userApiDuration = userApiDuration;
             // Dispatch timing actions
             dispatch(setHerdModulesApiDuration(herdModulesDuration));
             dispatch(setUserApiDuration(userApiDuration));
-            // Calculate network overhead
-            const totalApiTime = herdModulesDuration + userApiDuration;
-            const networkOverhead = parallelDuration - Math.max(herdModulesDuration, userApiDuration);
-            console.log(`[useScoutRefresh] API performance:`);
-            console.log(`  - Herd modules: ${herdModulesDuration}ms`);
-            console.log(`  - User API: ${userApiDuration}ms`);
-            console.log(`  - Parallel execution: ${parallelDuration}ms`);
-            console.log(`  - Time saved with parallel: ${totalApiTime - parallelDuration}ms`);
             // Validate API responses
             const validationStartTime = Date.now();
             if (!herdModulesResponse.data ||
@@ -133,7 +164,24 @@ export function useScoutRefresh(options = {}) {
             console.log(`[useScoutRefresh] Data validation took: ${validationDuration}ms`);
             // Use the validated data
             const compatible_new_herd_modules = herdModulesResponse.data;
-            // Measure data processing duration
+            // Set data source to DATABASE
+            dispatch(setDataSource(EnumDataSource.DATABASE));
+            dispatch(setDataSourceInfo({
+                source: EnumDataSource.DATABASE,
+                timestamp: Date.now(),
+            }));
+            // Step 3: Update cache with fresh data
+            const cacheSaveStartTime = Date.now();
+            try {
+                await scoutCache.setHerdModules(compatible_new_herd_modules, cacheTtlMs);
+                const cacheSaveDuration = Date.now() - cacheSaveStartTime;
+                timingRefs.current.cacheSaveDuration = cacheSaveDuration;
+                console.log(`[useScoutRefresh] Cache updated in ${cacheSaveDuration}ms with TTL: ${Math.round(cacheTtlMs / 1000)}s`);
+            }
+            catch (cacheError) {
+                console.warn("[useScoutRefresh] Cache save failed:", cacheError);
+            }
+            // Step 4: Update store with fresh data
             const dataProcessingStartTime = Date.now();
             dispatch(setHerdModules(compatible_new_herd_modules));
             dispatch(setUser(res_new_user.data));
@@ -141,9 +189,8 @@ export function useScoutRefresh(options = {}) {
             const dataProcessingDuration = Date.now() - dataProcessingStartTime;
             timingRefs.current.dataProcessingDuration = dataProcessingDuration;
             dispatch(setDataProcessingDuration(dataProcessingDuration));
-            // Measure localStorage operations duration
+            // Step 5: Handle localStorage operations
             const localStorageStartTime = Date.now();
-            // Safely handle localStorage operations
             try {
                 // Check local storage for a last selected herd
                 const lastSelectedHerd = localStorage.getItem("last_selected_herd");
@@ -177,15 +224,24 @@ export function useScoutRefresh(options = {}) {
             // Log essential performance metrics
             console.log(`[useScoutRefresh] Refresh completed successfully:`);
             console.log(`  - Total duration: ${loadingDuration}ms`);
-            console.log(`  - Herd modules: ${herdModulesDuration}ms`);
+            console.log(`  - Cache load: ${cacheLoadDuration}ms`);
+            console.log(`  - Herd modules API: ${herdModulesDuration}ms`);
             console.log(`  - User API: ${userApiDuration}ms`);
-            console.log(`  - Parallel execution: ${parallelDuration}ms`);
-            console.log(`  - Time saved with parallel: ${totalApiTime - parallelDuration}ms`);
+            console.log(`  - Cache save: ${timingRefs.current.cacheSaveDuration}ms`);
+            console.log(`  - Data processing: ${dataProcessingDuration}ms`);
+            console.log(`  - LocalStorage: ${localStorageDuration}ms`);
+            console.log(`  - Cache TTL: ${Math.round(cacheTtlMs / 1000)}s`);
             onRefreshComplete?.();
         }
         catch (error) {
             const loadingDuration = Date.now() - startTime;
             console.error("Error refreshing scout data:", error);
+            // Set data source to UNKNOWN on error
+            dispatch(setDataSource(EnumDataSource.UNKNOWN));
+            dispatch(setDataSourceInfo({
+                source: EnumDataSource.UNKNOWN,
+                timestamp: Date.now(),
+            }));
             // Ensure consistent state updates on error
             dispatch(setHerdModulesLoadingState(EnumHerdModulesLoadingState.UNSUCCESSFULLY_LOADED));
             dispatch(setHerdModulesLoadedInMs(loadingDuration));
@@ -199,7 +255,7 @@ export function useScoutRefresh(options = {}) {
         finally {
             refreshInProgressRef.current = false;
         }
-    }, [dispatch, onRefreshComplete]);
+    }, [dispatch, onRefreshComplete, cacheFirst, cacheTtlMs]);
     useEffect(() => {
         if (autoRefresh) {
             handleRefresh();
@@ -211,14 +267,45 @@ export function useScoutRefresh(options = {}) {
         const startTime = timingRefs.current.startTime;
         return {
             totalDuration: startTime > 0 ? now - startTime : 0,
+            cacheLoad: timingRefs.current.cacheLoadDuration,
             herdModulesApi: timingRefs.current.herdModulesDuration,
             userApi: timingRefs.current.userApiDuration,
+            cacheSave: timingRefs.current.cacheSaveDuration,
             dataProcessing: timingRefs.current.dataProcessingDuration,
             localStorage: timingRefs.current.localStorageDuration,
         };
     }, []);
+    // Utility function to clear cache
+    const clearCache = useCallback(async () => {
+        try {
+            await scoutCache.clearHerdModules();
+            console.log("[useScoutRefresh] Cache cleared successfully");
+        }
+        catch (error) {
+            console.error("[useScoutRefresh] Failed to clear cache:", error);
+        }
+    }, []);
+    // Utility function to get cache statistics
+    const getCacheStats = useCallback(async () => {
+        try {
+            return await scoutCache.getCacheStats();
+        }
+        catch (error) {
+            console.error("[useScoutRefresh] Failed to get cache stats:", error);
+            return {
+                size: 0,
+                lastUpdated: 0,
+                isStale: true,
+                hitRate: 0,
+                totalHits: 0,
+                totalMisses: 0,
+            };
+        }
+    }, []);
     return {
         handleRefresh,
         getTimingStats,
+        clearCache,
+        getCacheStats,
     };
 }

package/dist/store/scout.d.ts

@@ -1,5 +1,6 @@
 import { IUser } from "../types/db";
 import { IHerdModule, EnumHerdModulesLoadingState } from "../types/herd_module";
+import { EnumDataSource, IDataSourceInfo } from "../types/data_source";
 export declare enum EnumScoutStateStatus {
     LOADING = "LOADING",
     DONE_LOADING = "DONE_LOADING"
@@ -17,6 +18,11 @@ export interface ScoutState {
     active_device_id: string | null;
     lastRefreshed: number;
     user: IUser | null;
+    data_source: EnumDataSource;
+    data_source_info: IDataSourceInfo | null;
+}
+export interface RootState {
+    scout: ScoutState;
 }
 export declare const scoutSlice: import("@reduxjs/toolkit").Slice<ScoutState, {
     setHerdModules: (state: import("immer").WritableDraft<ScoutState>, action: {
@@ -59,6 +65,14 @@ export declare const scoutSlice: import("@reduxjs/toolkit").Slice<ScoutState, {
         payload: any;
         type: string;
     }) => void;
+    setDataSource: (state: import("immer").WritableDraft<ScoutState>, action: {
+        payload: any;
+        type: string;
+    }) => void;
+    setDataSourceInfo: (state: import("immer").WritableDraft<ScoutState>, action: {
+        payload: any;
+        type: string;
+    }) => void;
     replaceEventsForHerdModule: (state: import("immer").WritableDraft<ScoutState>, action: {
         payload: any;
         type: string;
@@ -140,6 +154,6 @@ export declare const scoutSlice: import("@reduxjs/toolkit").Slice<ScoutState, {
         type: string;
     }) => void;
 }, "scout", "scout", import("@reduxjs/toolkit").SliceSelectors<ScoutState>>;
-export declare const setHerdModules: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setHerdModules">, setStatus: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setStatus">, setHerdModulesLoadingState: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setHerdModulesLoadingState">, setHerdModulesLoadedInMs: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setHerdModulesLoadedInMs">, setHerdModulesApiDuration: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setHerdModulesApiDuration">, setUserApiDuration: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setUserApiDuration">, setDataProcessingDuration: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setDataProcessingDuration">, setLocalStorageDuration: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setLocalStorageDuration">, setActiveHerdId: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setActiveHerdId">, setActiveDeviceId: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setActiveDeviceId">, appendEventsToHerdModule: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/appendEventsToHerdModule">, replaceEventsForHerdModule: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/replaceEventsForHerdModule">, updateEventValuesForHerdModule: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/updateEventValuesForHerdModule">, updatePageIndexForHerdModule: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/updatePageIndexForHerdModule">, appendPlansToHerdModule: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/appendPlansToHerdModule">, setUser: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setUser">, addTag: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/addTag">, deleteTag: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/deleteTag">, updateTag: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/updateTag">, addNewDeviceToHerdModule: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/addNewDeviceToHerdModule">, updateDeviceForHerdModule: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/updateDeviceForHerdModule">, addDevice: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/addDevice">, deleteDevice: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/deleteDevice">, updateDevice: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/updateDevice">, addPlan: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/addPlan">, deletePlan: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/deletePlan">, updatePlan: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/updatePlan">, addSessionToStore: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/addSessionToStore">, deleteSessionFromStore: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/deleteSessionFromStore">, updateSessionInStore: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/updateSessionInStore">;
+export declare const setHerdModules: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setHerdModules">, setStatus: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setStatus">, setHerdModulesLoadingState: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setHerdModulesLoadingState">, setHerdModulesLoadedInMs: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setHerdModulesLoadedInMs">, setHerdModulesApiDuration: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setHerdModulesApiDuration">, setUserApiDuration: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setUserApiDuration">, setDataProcessingDuration: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setDataProcessingDuration">, setLocalStorageDuration: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setLocalStorageDuration">, setActiveHerdId: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setActiveHerdId">, setActiveDeviceId: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setActiveDeviceId">, setDataSource: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setDataSource">, setDataSourceInfo: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setDataSourceInfo">, appendEventsToHerdModule: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/appendEventsToHerdModule">, replaceEventsForHerdModule: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/replaceEventsForHerdModule">, updateEventValuesForHerdModule: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/updateEventValuesForHerdModule">, updatePageIndexForHerdModule: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/updatePageIndexForHerdModule">, appendPlansToHerdModule: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/appendPlansToHerdModule">, setUser: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/setUser">, addTag: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/addTag">, deleteTag: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/deleteTag">, updateTag: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/updateTag">, addNewDeviceToHerdModule: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/addNewDeviceToHerdModule">, updateDeviceForHerdModule: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/updateDeviceForHerdModule">, addDevice: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/addDevice">, deleteDevice: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/deleteDevice">, updateDevice: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/updateDevice">, addPlan: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/addPlan">, deletePlan: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/deletePlan">, updatePlan: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/updatePlan">, addSessionToStore: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/addSessionToStore">, deleteSessionFromStore: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/deleteSessionFromStore">, updateSessionInStore: import("@reduxjs/toolkit").ActionCreatorWithPayload<any, "scout/updateSessionInStore">;
 declare const _default: import("redux").Reducer<ScoutState>;
 export default _default;

package/dist/store/scout.js

@@ -1,5 +1,6 @@
 import { createSlice } from "@reduxjs/toolkit";
 import { EnumHerdModulesLoadingState } from "../types/herd_module";
+import { EnumDataSource } from "../types/data_source";
 export var EnumScoutStateStatus;
 (function (EnumScoutStateStatus) {
     EnumScoutStateStatus["LOADING"] = "LOADING";
@@ -19,6 +20,9 @@ const initialState = {
     active_herd_id: null,
     active_device_id: null,
     user: null,
+    // Initialize data source tracking
+    data_source: EnumDataSource.UNKNOWN,
+    data_source_info: null,
 };
 export const scoutSlice = createSlice({
     name: "scout",
@@ -55,6 +59,12 @@ export const scoutSlice = createSlice({
         setActiveDeviceId: (state, action) => {
             state.active_device_id = action.payload;
         },
+        setDataSource: (state, action) => {
+            state.data_source = action.payload;
+        },
+        setDataSourceInfo: (state, action) => {
+            state.data_source_info = action.payload;
+        },
         replaceEventsForHerdModule: (state, action) => {
             const { herd_id, events } = action.payload;
             const herd_module = state.herd_modules.find((hm) => hm.herd.id.toString() === herd_id);
@@ -254,5 +264,5 @@ export const scoutSlice = createSlice({
     },
 });
 // Action creators are generated for each case reducer function
-export const { setHerdModules, setStatus, setHerdModulesLoadingState, setHerdModulesLoadedInMs, setHerdModulesApiDuration, setUserApiDuration, setDataProcessingDuration, setLocalStorageDuration, setActiveHerdId, setActiveDeviceId, appendEventsToHerdModule, replaceEventsForHerdModule, updateEventValuesForHerdModule, updatePageIndexForHerdModule, appendPlansToHerdModule, setUser, addTag, deleteTag, updateTag, addNewDeviceToHerdModule, updateDeviceForHerdModule, addDevice, deleteDevice, updateDevice, addPlan, deletePlan, updatePlan, addSessionToStore, deleteSessionFromStore, updateSessionInStore, } = scoutSlice.actions;
+export const { setHerdModules, setStatus, setHerdModulesLoadingState, setHerdModulesLoadedInMs, setHerdModulesApiDuration, setUserApiDuration, setDataProcessingDuration, setLocalStorageDuration, setActiveHerdId, setActiveDeviceId, setDataSource, setDataSourceInfo, appendEventsToHerdModule, replaceEventsForHerdModule, updateEventValuesForHerdModule, updatePageIndexForHerdModule, appendPlansToHerdModule, setUser, addTag, deleteTag, updateTag, addNewDeviceToHerdModule, updateDeviceForHerdModule, addDevice, deleteDevice, updateDevice, addPlan, deletePlan, updatePlan, addSessionToStore, deleteSessionFromStore, updateSessionInStore, } = scoutSlice.actions;
 export default scoutSlice.reducer;

package/dist/types/data_source.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Enum representing the source of data in the Scout application
+ */
+export declare enum EnumDataSource {
+    CACHE = "CACHE",
+    DATABASE = "DATABASE",
+    UNKNOWN = "UNKNOWN"
+}
+/**
+ * Interface for data source information
+ */
+export interface IDataSourceInfo {
+    source: EnumDataSource;
+    timestamp: number;
+    cacheAge?: number;
+    isStale?: boolean;
+}

package/dist/types/data_source.js

@@ -0,0 +1,9 @@
+/**
+ * Enum representing the source of data in the Scout application
+ */
+export var EnumDataSource;
+(function (EnumDataSource) {
+    EnumDataSource["CACHE"] = "CACHE";
+    EnumDataSource["DATABASE"] = "DATABASE";
+    EnumDataSource["UNKNOWN"] = "UNKNOWN";
+})(EnumDataSource || (EnumDataSource = {}));

package/dist/types/index.d.ts

@@ -5,3 +5,4 @@ export * from "./requests";
 export * from "./gps";
 export * from "./supabase";
 export * from "./events";
+export * from "./data_source";

package/dist/types/index.js

@@ -5,3 +5,4 @@ export * from "./requests";
 export * from "./gps";
 export * from "./supabase";
 export * from "./events";
+export * from "./data_source";

package/package.json

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