Scout Core

Scout core provides easy routines for managing and updating scout state in your web applications.

Runtime entrypoints

Import browser code from @adventurelabs/scout-core/client and server code from @adventurelabs/scout-core/server. Data helpers use the same name and query arguments in both locations. Client helpers additionally receive a Supabase client as their first argument:

import { get_devices_by_herd } from "@adventurelabs/scout-core/client";

const response = await get_devices_by_herd(supabase, herdId);

import { get_devices_by_herd } from "@adventurelabs/scout-core/server";

const response = await get_devices_by_herd(herdId);

Both forms run with the current user's row-level security permissions. Shared types can be imported from @adventurelabs/scout-core/types.

Server helpers are ordinary server-only functions for React Server Components; they are not client-invokable Server Actions. Import middleware and direct Supabase access from /server/middleware and /server/supabase respectively.

The package root is no longer exported. Existing root imports must move to the runtime where they execute. Hooks, providers, Redux, and cache helpers are client-only. Middleware, cookie handling, API-key actions, and privileged key operations are server-only.

When moving server imports, remove the old server_ prefix from helper names. Use get_versions_software_with_build_urls for signed build artifact URLs.

ScoutRefreshProvider reuses an injected Supabase client when provided. Its automatic refresh hydrates from IndexedDB and revalidates online. Manual and reconnect refreshes go directly to the network.

Set enabled={false} to suspend refreshes, authentication subscriptions, token minting, timers, and reconnect listeners. Re-enabling the provider initializes those processes normally.

Use useScoutRefreshActions() within the provider to access its shared handleRefresh and clearCache actions. Do not create another useScoutRefresh() instance in descendants.

IndexedDB is scoped per authenticated user and Supabase project. Call clearScoutClientState() from the client on sign-out (before redirect) so the scoped cache is wiped; the provider also clears on SIGNED_OUT.

Devices, parts, and products

Herd modules hold devices with their bare parts. Products are stored once in state.scout.product_catalog, keyed by product id, with a product_id_by_number index that resolves parts.product_number. Each catalog product includes manufacturers.name from the products join. A fleet sharing a few product lines therefore keeps one copy of each product instead of one per part. Consumers can show the maker with product.manufacturers?.name.

Resolve a product where it is rendered rather than storing it next to a device:

import {
  useProductForPart,
  useProductsForDevice,
} from "@adventurelabs/scout-core/client";

const product = useProductForPart(part);
const deviceProducts = useProductsForDevice(device);

get_product_for_part and get_products_for_device are the same lookups without React, for code that already holds an IProductCatalog (for example the catalog returned alongside load_herd_modules or get_parts_by_herd_ids).

Key Features

• Real-time Updates: Supabase-powered real-time data synchronization
• State Management: Redux-based state management with loading states
• Proactive Cacheing: Load data from local storage and refresh with network for snappy loading
• Team Management: Swap between teams and roles