> ## Documentation Index
> Fetch the complete documentation index at: https://dhanurgo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Hooks Reference

> Complete reference for all custom React hooks in the HostMetrics codebase

# Hooks Reference

HostMetrics uses custom React hooks extensively for data fetching, state management, and business logic. All hooks live in `src/hooks/`.

## Complete Hook Index

### Data Fetching and CRUD Hooks

| Hook                     | File                                  | Purpose                     | Key Returns                               |
| ------------------------ | ------------------------------------- | --------------------------- | ----------------------------------------- |
| `useKPIs`                | `src/hooks/useKPIs.ts`                | Dashboard KPI calculations  | `kpis`, `isLoading`, `error`              |
| `useBookings`            | `src/hooks/useBookings.ts`            | Trip data with filtering    | `bookings`, `stats`, `filters`            |
| `useCalendarBookings`    | `src/hooks/useCalendarBookings.ts`    | Calendar view trip data     | `bookings`, `dateRange`                   |
| `useVehicles`            | `src/hooks/useVehicles.ts`            | Vehicle CRUD operations     | `vehicles`, `addVehicle`, `updateVehicle` |
| `useVehicle360`          | `src/hooks/useVehicle360.ts`          | Vehicle deep analytics      | `analytics`, `trends`                     |
| `useVehicleDepreciation` | `src/hooks/useVehicleDepreciation.ts` | Depreciation calculations   | `depreciation`, `method`                  |
| `useVehiclePhotos`       | `src/hooks/useVehiclePhotos.ts`       | Photo upload and management | `photos`, `upload`, `reorder`             |
| `useVehicleInvestments`  | `src/hooks/useVehicleInvestments.ts`  | Vehicle investment tracking | `investments`                             |
| `useExpenses`            | `src/hooks/useExpenses.ts`            | Expense management          | `expenses`, `addExpense`, `deleteExpense` |
| `useMiscIncome`          | `src/hooks/useMiscIncome.ts`          | Non-trip income tracking    | `incomes`, `addIncome`                    |
| `useDocuments`           | `src/hooks/useDocuments.ts`           | Document management         | `documents`, `upload`, `delete`           |
| `useProfile`             | `src/hooks/useProfile.ts`             | User profile data           | `profile`, `updateProfile`                |

### Partner and Investor Hooks

| Hook                      | File                                   | Purpose                      | Key Returns                    |
| ------------------------- | -------------------------------------- | ---------------------------- | ------------------------------ |
| `useInvestors`            | `src/hooks/useInvestors.ts`            | Investor CRUD                | `investors`, `addInvestor`     |
| `useInvestorAgreements`   | `src/hooks/useInvestorAgreements.ts`   | Agreement management         | `agreements`, `create`, `sign` |
| `useInvestorDetailModals` | `src/hooks/useInvestorDetailModals.ts` | Modal state management       | `modalStates`, `open`, `close` |
| `useVehiclePayouts`       | `src/hooks/useVehiclePayouts.ts`       | Investor payout calculations | `payouts`, `calculate`         |
| `useAgreementTemplate`    | `src/hooks/useAgreementTemplate.ts`    | Agreement templates          | `template`, `update`           |

### Financial and Analytics Hooks

| Hook                       | File                                    | Purpose                   | Key Returns                        |
| -------------------------- | --------------------------------------- | ------------------------- | ---------------------------------- |
| `useTollReconciliation`    | `src/hooks/useTollReconciliation.ts`    | Toll-to-trip matching     | `reconciliation`, `stats`          |
| `useTollAccounts`          | `src/hooks/useTollAccounts.ts`          | Toll account connections  | `accounts`, `connect`, `test`      |
| `useEarningsDiscrepancies` | `src/hooks/useEarningsDiscrepancies.ts` | Unmatched trip detection  | `discrepancies`, `resolve`         |
| `useUtilization`           | `src/hooks/useUtilization.ts`           | Fleet utilization metrics | `utilization`, `trends`            |
| `useTaxData`               | `src/hooks/useTaxData.ts`               | Tax document data         | `taxData`, `generate1099`          |
| `useBilling`               | `src/hooks/useBilling.ts`               | Subscription and billing  | `subscription`, `plan`, `invoices` |

### Infrastructure Hooks

| Hook                      | File                                   | Purpose                     | Key Returns                 |
| ------------------------- | -------------------------------------- | --------------------------- | --------------------------- |
| `useFundingRounds`        | `src/hooks/useFundingRounds.ts`        | Funding round management    | `rounds`, `create`          |
| `useFleetPages`           | `src/hooks/useFleetPages.ts`           | Fleet page CRUD             | `pages`, `create`, `update` |
| `useFleetVehicleControls` | `src/hooks/useFleetVehicleControls.ts` | Fleet page vehicle controls | `controls`                  |
| `useNotifications`        | `src/hooks/useNotifications.ts`        | Notification management     | `notifications`, `markRead` |
| `usePortalAccessLogs`     | `src/hooks/usePortalAccessLogs.ts`     | Portal access audit logs    | `logs`                      |

## Common Usage Patterns

### Basic Data Fetching

Most hooks follow the same pattern: fetch data on mount, expose loading/error states, and provide mutation functions.

```tsx theme={null}
'use client';

import { useAuth } from "@/components/auth/AuthProvider";
import { useKPIs } from "@/hooks/useKPIs";
import { useBookings } from "@/hooks/useBookings";
import { useVehicles } from "@/hooks/useVehicles";

export function DashboardPage() {
  const { user } = useAuth();
  const { kpis, isLoading: kpisLoading } = useKPIs();
  const { bookings, stats } = useBookings(filters);
  const { vehicles } = useVehicles();

  if (kpisLoading) return <LoadingSkeleton />;

  return (
    <div>
      <StatGrid kpis={kpis} />
      <TripTable bookings={bookings} />
    </div>
  );
}
```

### Hooks with Filters

Some hooks accept filter parameters that trigger re-fetching when changed:

```tsx theme={null}
const [filters, setFilters] = useState({
  status: "completed",
  dateRange: { start: "2026-01-01", end: "2026-03-10" },
  vehicleId: null,
});

const { bookings, stats, isLoading } = useBookings(filters);
```

### CRUD Operations

Hooks that support mutations return functions for create, update, and delete:

```tsx theme={null}
const { vehicles, addVehicle, updateVehicle, deleteVehicle } = useVehicles();

// Create
await addVehicle({ make: "Tesla", model: "Model 3", year: 2023 });

// Update
await updateVehicle(vehicleId, { status: "inactive" });

// Delete (soft delete)
await deleteVehicle(vehicleId);
```

### Combining Multiple Hooks

Complex pages often compose several hooks together:

```tsx theme={null}
const { vehicles } = useVehicles();
const { expenses } = useExpenses({ vehicleId: selectedVehicle });
const { documents } = useDocuments({ vehicleId: selectedVehicle });
const { depreciation } = useVehicleDepreciation(selectedVehicle);
```

## Hook Conventions

* All hooks that fetch data include `isLoading` and `error` in their return value
* Data is fetched on component mount via `useEffect`
* Hooks call database modules from `src/lib/db/` — they never call Supabase directly
* Auth context (`useAuth`) provides the current user for all downstream queries
* Hooks use `useCallback` for stable mutation function references