@adventurelabs/scout-core 1.0.0

package/README.md

@@ -0,0 +1,90 @@
+# @adventurelabs/scout-core
+
+Core utilities and helpers for Adventure Labs Scout applications.
+
+## Installation
+
+```bash
+npm install @adventurelabs/scout-core
+# or
+yarn add @adventurelabs/scout-core
+```
+
+## Usage
+
+```typescript
+import {
+  HerdModule,
+  IDevice,
+  IEvent,
+  isEmailValidForLogin,
+  useScoutDbListener,
+  useScoutRefresh,
+} from "@adventurelabs/scout-core";
+
+// Use the HerdModule class
+const herdModule = new HerdModule(herd, devices, events, Date.now());
+
+// Use helper functions
+const isValidEmail = isEmailValidForLogin("user@adventurelabs.earth");
+
+// Use React hooks for real-time database listening
+useScoutDbListener(); // Automatically listens for changes to plans, devices, and tags
+
+// Use refresh hook
+const { handleRefresh } = useScoutRefresh({ autoRefresh: true });
+```
+
+## Available Modules
+
+### Types
+
+- Database types from Supabase
+- Herd, Device, Event, User interfaces
+- Request/Response types
+
+### Helpers
+
+- Authentication utilities
+- Database operations
+- Email validation
+- GPS and location helpers
+- Device and event management
+- Tag and annotation utilities
+
+### Hooks
+
+- `useScoutDbListener` - Real-time database listening for plans, devices, and tags
+- `useScoutRefresh` - Data refresh utilities
+
+### Store
+
+- Zustand-based state management for Scout applications
+
+### Supabase
+
+- Client, server, and middleware utilities for Supabase integration
+
+### API Keys
+
+- API key management utilities
+
+## Development
+
+```bash
+# Install dependencies
+yarn install
+
+# Build the package
+yarn build
+
+# Watch for changes
+yarn dev
+
+# Clean build artifacts
+yarn clean
+```
+
+## License
+
+MIT

package/dist/api_keys/actions.d.ts

@@ -0,0 +1,2 @@
+import { IApiKeyScout } from "../types/db";
+export declare function server_list_api_keys(device_id: string): Promise<IApiKeyScout[]>;

package/dist/api_keys/actions.js

@@ -0,0 +1,20 @@
+"use server";
+import { newServerClient } from "../supabase/server";
+export async function server_list_api_keys(device_id) {
+    const supabase = await newServerClient();
+    const { data, error } = await supabase.rpc("load_api_keys", {
+        id_of_device: device_id,
+    });
+    if (error) {
+        console.error("Error listing API keys:", error.message);
+    }
+    if (!data)
+        return [];
+    const data_to_return = [];
+    for (let i = 0; i < data.length; i++) {
+        // convert data to IApiKeyScout
+        const converted_data = JSON.parse(data[i]);
+        data_to_return.push(converted_data);
+    }
+    return data_to_return;
+}

package/dist/api_keys/index.d.ts

@@ -0,0 +1 @@
+export * from "./actions";

package/dist/api_keys/index.js

@@ -0,0 +1 @@
+export * from "./actions";

package/dist/constants/annotator.d.ts

@@ -0,0 +1 @@
+export declare const LABELS: string[];

package/dist/constants/annotator.js

@@ -0,0 +1,11 @@
+export const LABELS = [
+    "boar",
+    "human",
+    "vehicle",
+    "deer",
+    "giraffe",
+    "gorilla",
+    "lion",
+    "penguin",
+    "undefined",
+];

package/dist/constants/app.d.ts

@@ -0,0 +1,2 @@
+export declare const MAX_ITEMS_PER_PAGE_EVENTS = 24;
+export declare const VALID_VIEWS: string[];

package/dist/constants/app.js

@@ -0,0 +1,2 @@
+export const MAX_ITEMS_PER_PAGE_EVENTS = 24;
+export const VALID_VIEWS = ["overview", "events", "security"];

package/dist/constants/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./annotator";
+export * from "./app";

package/dist/constants/index.js

@@ -0,0 +1,2 @@
+export * from "./annotator";
+export * from "./app";

package/dist/helpers/auth.d.ts

@@ -0,0 +1 @@
+export declare function isEmailValidForLogin(email: string, approved_domains?: string[]): boolean;

package/dist/helpers/auth.js

@@ -0,0 +1,8 @@
+import { validateEmail } from "./email";
+const APPROVED_DOMAINS = ["adventurelabs.earth", "conservaition.ai"];
+export function isEmailValidForLogin(email, approved_domains = APPROVED_DOMAINS) {
+    return (validateEmail(email) && isEmailFromApprovedDomain(email, approved_domains));
+}
+function isEmailFromApprovedDomain(email, approved_domains = APPROVED_DOMAINS) {
+    return approved_domains.filter((domain) => email.endsWith(domain)).length > 0;
+}

package/dist/helpers/bounding_boxes.d.ts

@@ -0,0 +1,5 @@
+import { BoundingBox, EnumSourceBoundingBox } from "../types/bounding_boxes";
+import { Tag } from "../types/db";
+export declare function convertManualBoundingBoxToTag(boundingBox: BoundingBox, event_id: number): Tag;
+export declare function convertTagToBoundingBox(tag: Tag, source: EnumSourceBoundingBox): BoundingBox;
+export declare function formatBoundingBoxLabel(label: string): string;

package/dist/helpers/bounding_boxes.js

@@ -0,0 +1,43 @@
+import { SelectionStatus, } from "../types/bounding_boxes";
+export function convertManualBoundingBoxToTag(boundingBox, event_id) {
+    const newClassName = boundingBox.label;
+    // try to convert if nan, make it 0
+    let newId = Number(boundingBox.id);
+    if (isNaN(newId)) {
+        newId = 0;
+    }
+    const newTag = {
+        id: newId,
+        x: boundingBox.xCenterPercentage,
+        y: boundingBox.yCenterPercentage,
+        width: boundingBox.widthPercentage,
+        height: boundingBox.heightPercentage,
+        inserted_at: new Date().toISOString(),
+        conf: 1,
+        observation_type: "manual",
+        class_name: newClassName,
+        event_id: event_id,
+    };
+    return newTag;
+}
+export function convertTagToBoundingBox(tag, source) {
+    const newBoundingBox = {
+        xCenterPercentage: tag.x,
+        yCenterPercentage: tag.y,
+        widthPercentage: tag.width,
+        heightPercentage: tag.height,
+        label: tag.class_name,
+        id: tag.id ? tag.id.toString() : "0",
+        left: 0,
+        top: 0,
+        width: 0,
+        height: 0,
+        anchorPoint: { x: 0, y: 0 },
+        status: SelectionStatus.ARCHIVED,
+        source: source,
+    };
+    return newBoundingBox;
+}
+export function formatBoundingBoxLabel(label) {
+    return label;
+}

package/dist/helpers/db.d.ts

@@ -0,0 +1,3 @@
+import { SupabaseClient } from "@supabase/supabase-js";
+import { Database } from "../types/supabase";
+export declare function createClientWithApiKey(user_api_key: string): SupabaseClient<Database> | null;

package/dist/helpers/db.js

@@ -0,0 +1,22 @@
+import { createClient } from "@supabase/supabase-js";
+export function createClientWithApiKey(user_api_key) {
+    const supabase_url = process.env.NEXT_PUBLIC_SUPABASE_URL;
+    const supabase_anon_key = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;
+    if (!supabase_url || !supabase_anon_key) {
+        return null;
+    }
+    // EXCHANGE API KEY FOR JWT
+    const supabase_anon = createClient(supabase_url, supabase_anon_key, {
+        global: {
+            headers: {
+                api_key: `${user_api_key}`,
+            },
+        },
+        auth: {
+            persistSession: false,
+            detectSessionInUrl: false,
+            autoRefreshToken: false,
+        },
+    });
+    return supabase_anon;
+}

package/dist/helpers/devices.d.ts

@@ -0,0 +1,8 @@
+import { IDevice } from "../types/db";
+import { IWebResponseCompatible } from "../types/requests";
+import { SupabaseClient } from "@supabase/supabase-js";
+export declare function get_devices_by_herd(herd_id: number, client: SupabaseClient): Promise<IWebResponseCompatible<IDevice[]>>;
+export declare function get_device_by_id(device_id: number, client?: SupabaseClient): Promise<IWebResponseCompatible<IDevice | null>>;
+export declare function serverUpdateDevice(updatedDevice: IDevice): Promise<IWebResponseCompatible<IDevice | null>>;
+export declare function serverCreateDevice(newDevice: any): Promise<IWebResponseCompatible<IDevice | null>>;
+export declare function serverDeleteDeviceById(device_id: number): Promise<IWebResponseCompatible<IDevice | null>>;

package/dist/helpers/devices.js

@@ -0,0 +1,92 @@
+"use server";
+import { newServerClient } from "../supabase/server";
+import { IWebResponse } from "../types/requests";
+export async function get_devices_by_herd(herd_id, client) {
+    // call get_devices_for_herd with rpc
+    const { data, error } = await client.rpc("get_devices_for_herd", {
+        herd_id_caller: herd_id,
+    });
+    if (!data) {
+        return IWebResponse.error("No devices found").to_compatible();
+    }
+    else {
+        let response = IWebResponse.success(data);
+        return response.to_compatible();
+    }
+}
+export async function get_device_by_id(device_id, client) {
+    if (!client) {
+        client = await newServerClient();
+    }
+    const { data, error } = await client.rpc("get_device_by_id", {
+        device_id_caller: device_id,
+    });
+    if (!data) {
+        return IWebResponse.error("No device found").to_compatible();
+    }
+    else {
+        let response = IWebResponse.success(data);
+        return response.to_compatible();
+    }
+}
+export async function serverUpdateDevice(updatedDevice) {
+    // delete api keys, latitide, and longitude
+    const device_formatted = { ...updatedDevice };
+    delete device_formatted.api_keys_scout;
+    const device_latitude = device_formatted.latitude;
+    const device_longitude = device_formatted.longitude;
+    delete device_formatted.latitude;
+    delete device_formatted.longitude;
+    delete device_formatted.recent_events;
+    const supabase = await newServerClient();
+    const { data, error } = await supabase
+        .from("devices")
+        .update(device_formatted)
+        .match({ id: device_formatted.id })
+        .select("*");
+    if (error) {
+        return IWebResponse.error(error.message).to_compatible();
+    }
+    else {
+        const updatedDevice = {
+            ...data[0],
+            latitude: device_latitude,
+            longitude: device_longitude,
+        };
+        return IWebResponse.success(updatedDevice).to_compatible();
+    }
+}
+export async function serverCreateDevice(newDevice) {
+    const supabase = await newServerClient();
+    const user = await supabase.auth.getUser();
+    const userId = user?.data?.user?.id;
+    newDevice.created_by = userId;
+    // strip id field from herd object
+    const { data, error } = await supabase
+        .from("devices")
+        .insert([newDevice])
+        .select("*");
+    if (error) {
+        // TODO: ALLOW PROPERTY INSTANTION OF CPMPATIBLE WEB RESPONSE
+        return IWebResponse.error(error.message).to_compatible();
+    }
+    else {
+        const newDevice = { ...data[0], latitude: 0, longitude: 0 };
+        return IWebResponse.success(newDevice).to_compatible();
+    }
+}
+export async function serverDeleteDeviceById(device_id) {
+    const supabase = await newServerClient();
+    const { data, error } = await supabase
+        .from("devices")
+        .delete()
+        .match({ id: device_id })
+        .select("*");
+    if (error) {
+        return IWebResponse.error(error.message).to_compatible();
+    }
+    else {
+        const deletedDevice = { ...data[0], latitude: 0, longitude: 0 };
+        return IWebResponse.success(deletedDevice).to_compatible();
+    }
+}

package/dist/helpers/email.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Ensure email conforms to basic email format x@y.z
+ * @param email
+ * @returns boolean
+ *
+ */
+export declare function validateEmail(email: string): boolean;

package/dist/helpers/email.js

@@ -0,0 +1,22 @@
+/**
+ * Ensure email conforms to basic email format x@y.z
+ * @param email
+ * @returns boolean
+ *
+ */
+export function validateEmail(email) {
+    // emails should be x@y
+    const parts = email.split("@");
+    if (parts.length !== 2) {
+        return false;
+    }
+    // x should not be empty
+    if (parts[0].length === 0) {
+        return false;
+    }
+    // y should have at least one dot
+    if (!parts[1].includes(".")) {
+        return false;
+    }
+    return true;
+}

package/dist/helpers/events.d.ts

@@ -0,0 +1,6 @@
+import { IEvent } from "../types/db";
+import { IWebResponseCompatible } from "../types/requests";
+export declare function server_get_events_by_herd(herd_id: number): Promise<IWebResponseCompatible<IEvent[]>>;
+export declare function server_get_more_events_by_herd(herd_id: number, offset: number, page_count?: number): Promise<IWebResponseCompatible<IEvent[]>>;
+export declare function server_get_total_events_by_herd(herd_id: number): Promise<IWebResponseCompatible<number>>;
+export declare function server_create_event(newEvent: any): Promise<IWebResponseCompatible<boolean>>;

package/dist/helpers/events.js

@@ -0,0 +1,71 @@
+"use server";
+import { newServerClient } from "../supabase/server";
+import { EnumWebResponse, IWebResponse, } from "../types/requests";
+export async function server_get_events_by_herd(herd_id) {
+    const supabase = await newServerClient();
+    // fetch events and include devices
+    // sort by timestamp
+    const { data } = await supabase
+        .from("events")
+        .select(`
+      *,
+      devices: devices!inner(*)
+      `)
+        .eq("devices.herd_id", herd_id)
+        .order("timestamp_observation", { ascending: false });
+    // TODO: DETERMINE WHEN TO PASS ERROR
+    let response = IWebResponse.success(data ? data : []);
+    return response.to_compatible();
+}
+export async function server_get_more_events_by_herd(herd_id, offset, page_count = 10) {
+    const from = offset * page_count;
+    const to = from + page_count - 1;
+    const supabase = await newServerClient();
+    // fetch events and include devices
+    // sort by timestamp
+    const { data } = await supabase
+        .from("events")
+        .select(`
+      *,
+      devices: devices!inner(*)
+      `)
+        .eq("devices.herd_id", herd_id)
+        .range(from, to)
+        .order("timestamp_observation", { ascending: false });
+    // TODO: DETERMINE WHEN TO PASS ERROR
+    let response = IWebResponse.success(data ? data : []);
+    return response.to_compatible();
+}
+// function to get total number of events for a herd
+export async function server_get_total_events_by_herd(herd_id) {
+    const supabase = await newServerClient();
+    // call public.get_total_events_for_herd(herd_id)
+    const { data, error } = await supabase.rpc("get_total_events_for_herd", {
+        herd_id_caller: herd_id,
+    });
+    if (error) {
+        return {
+            status: EnumWebResponse.ERROR,
+            msg: error.message,
+            data: 0,
+        };
+    }
+    else {
+        return IWebResponse.success(data).to_compatible();
+    }
+}
+export async function server_create_event(newEvent) {
+    const supabase = await newServerClient();
+    // strip id field from herd object
+    const { data, error } = await supabase.from("events").insert([newEvent]);
+    if (error) {
+        return {
+            status: EnumWebResponse.ERROR,
+            msg: error.message,
+            data: null,
+        };
+    }
+    else {
+        return IWebResponse.success(true).to_compatible();
+    }
+}

package/dist/helpers/finance.d.ts

@@ -0,0 +1,9 @@
+declare function convertToSubcurrency(amount: number, factor?: number): number;
+export declare function roundToTwoDecimals(amount: number): number;
+/**
+ * This function takes a number and returns a string with commas and a dollar sign
+ * @param amount
+ * @returns
+ */
+export declare function formatDollarAmountforDisplay(amount: number): string;
+export default convertToSubcurrency;

package/dist/helpers/finance.js

@@ -0,0 +1,16 @@
+function convertToSubcurrency(amount, factor = 100) {
+    return Math.round(amount * factor);
+}
+export function roundToTwoDecimals(amount) {
+    return Math.round(amount * 100) / 100;
+}
+/**
+ * This function takes a number and returns a string with commas and a dollar sign
+ * @param amount
+ * @returns
+ */
+export function formatDollarAmountforDisplay(amount) {
+    // add commas to the number and prefix with $
+    return `$${amount.toLocaleString()}`;
+}
+export default convertToSubcurrency;

package/dist/helpers/gps.d.ts

@@ -0,0 +1,5 @@
+import { ILocationObject } from "../types/gps";
+export default function get_gps_center(gpsList: ILocationObject[]): {
+    latitude: number;
+    longitude: number;
+};

package/dist/helpers/gps.js

@@ -0,0 +1,11 @@
+export default function get_gps_center(gpsList) {
+    let latitude = 0;
+    let longitude = 0;
+    gpsList.forEach((gps) => {
+        latitude += gps.latitude;
+        longitude += gps.longitude;
+    });
+    latitude /= gpsList.length;
+    longitude /= gpsList.length;
+    return { latitude, longitude };
+}

package/dist/helpers/herds.d.ts

@@ -0,0 +1,9 @@
+import { IHerd } from "../types/db";
+import { IWebResponseCompatible } from "../types/requests";
+import { SupabaseClient } from "@supabase/supabase-js";
+import { IHerdModule } from "../types/herd_module";
+export declare function get_herds(client: SupabaseClient): Promise<IWebResponseCompatible<IHerd[]>>;
+export declare function get_herd_by_slug(slug: string): Promise<IWebResponseCompatible<IHerd>>;
+export declare function deleteHerd(herd_id: number): Promise<IWebResponseCompatible<boolean>>;
+export declare function createHerd(newHerd: any): Promise<IWebResponseCompatible<boolean>>;
+export declare function server_load_herd_modules(): Promise<IHerdModule[]>;

package/dist/helpers/herds.js

@@ -0,0 +1,80 @@
+"use server";
+import { newServerClient } from "../supabase/server";
+import { EnumWebResponse, IWebResponse, } from "../types/requests";
+import { HerdModule } from "../types/herd_module";
+export async function get_herds(client) {
+    const { data: herds } = await client.from("herds").select();
+    if (!herds) {
+        return {
+            status: EnumWebResponse.ERROR,
+            msg: "No herds found",
+            data: null,
+        };
+    }
+    else {
+        let response = IWebResponse.success(herds);
+        return response.to_compatible();
+    }
+}
+export async function get_herd_by_slug(slug) {
+    const supabase = await newServerClient();
+    const { data: herds } = await supabase
+        .from("herds")
+        .select()
+        .eq("slug", slug)
+        .limit(1);
+    if (!herds) {
+        return {
+            status: EnumWebResponse.ERROR,
+            msg: "No herds found",
+            data: null,
+        };
+    }
+    return IWebResponse.success(herds[0]);
+}
+export async function deleteHerd(herd_id) {
+    const supabase = await newServerClient();
+    const { error } = await supabase.from("herds").delete().match({ id: 20 });
+    if (error) {
+        return {
+            status: EnumWebResponse.ERROR,
+            msg: error.message,
+            data: null,
+        };
+    }
+    else {
+        return IWebResponse.success(true).to_compatible();
+    }
+}
+export async function createHerd(newHerd) {
+    const supabase = await newServerClient();
+    const user = await supabase.auth.getUser();
+    const userId = user?.data?.user?.id;
+    newHerd.created_by = userId;
+    // strip id field from herd object
+    const { data, error } = await supabase.from("herds").insert([newHerd]);
+    if (error) {
+        return {
+            status: EnumWebResponse.ERROR,
+            msg: error.message,
+            data: null,
+        };
+    }
+    else {
+        return IWebResponse.success(true).to_compatible();
+    }
+}
+export async function server_load_herd_modules() {
+    // load herds
+    const client_supabase = await newServerClient();
+    let new_herds = await get_herds(client_supabase);
+    if (new_herds.status != EnumWebResponse.SUCCESS || !new_herds.data) {
+        return [];
+    }
+    let new_herd_modules = [];
+    const herdModulePromises = new_herds.data.map((herd) => HerdModule.from_herd(herd, client_supabase));
+    new_herd_modules = await Promise.all(herdModulePromises);
+    // now serialize the herd modules
+    let serialized_herd_modules = new_herd_modules.map((herd_module) => herd_module.to_serializable());
+    return serialized_herd_modules;
+}

package/dist/helpers/index.d.ts

@@ -0,0 +1,17 @@
+export * from "./auth";
+export * from "./bounding_boxes";
+export * from "./db";
+export * from "./devices";
+export * from "./email";
+export * from "./events";
+export * from "./finance";
+export * from "./gps";
+export * from "./herds";
+export * from "./location";
+export * from "./plans";
+export * from "./tags";
+export * from "./time";
+export * from "./ui";
+export * from "./users";
+export * from "./web";
+export * from "./zones";

package/dist/helpers/index.js

@@ -0,0 +1,17 @@
+export * from "./auth";
+export * from "./bounding_boxes";
+export * from "./db";
+export * from "./devices";
+export * from "./email";
+export * from "./events";
+export * from "./finance";
+export * from "./gps";
+export * from "./herds";
+export * from "./location";
+export * from "./plans";
+export * from "./tags";
+export * from "./time";
+export * from "./ui";
+export * from "./users";
+export * from "./web";
+export * from "./zones";

package/dist/helpers/location.d.ts

@@ -0,0 +1 @@
+export declare function format_coordinates_for_db(lat: number, long: number): string;

package/dist/helpers/location.js

@@ -0,0 +1,3 @@
+export function format_coordinates_for_db(lat, long) {
+    return `POINT(${long} ${lat})`;
+}

package/dist/helpers/plans.d.ts

@@ -0,0 +1,5 @@
+import { IPlan } from "../types/db";
+import { IWebResponseCompatible } from "../types/requests";
+export declare function server_get_plans_by_herd(herd_id: number): Promise<IWebResponseCompatible<IPlan[]>>;
+export declare function server_create_plans(plans: IPlan[]): Promise<IWebResponseCompatible<IPlan[]>>;
+export declare function server_delete_plans_by_ids(plan_ids: number[]): Promise<IWebResponseCompatible<boolean>>;