npm package: @simpleapps-com/augur-hooks
Description: Cross-platform React Query hooks and Zustand stores for Augur ecommerce sites
Latest version: 2.2.29

# @simpleapps-com/augur-hooks

> Cross-platform React Query hooks and Zustand stores for Augur ecommerce sites

> Auto-generated. Do not edit manually. Regenerate with: `pnpm run generate-exports`

Part of the **@simpleapps-com/augur-\*** platform. All packages use fixed versioning (same version number).

## Install

```bash
pnpm add @simpleapps-com/augur-hooks
```

### Peer Dependencies

`@simpleapps-com/augur-api`, `@tanstack/react-query`, `@tanstack/react-query-persist-client`, `react`, `zustand`

## Entry Points

| Import | Description |
|--------|-------------|
| `@simpleapps-com/augur-hooks` | 50 exports, 14 types |
| `@simpleapps-com/augur-hooks/server` | 9 exports, 3 types |
| `@simpleapps-com/augur-hooks/web` | 5 exports, 0 types |

## Exports

### Auth & Context

| Export | Kind | Description |
|--------|------|-------------|
| `AugurAuthContext` | value |  |
| `AugurHooksProvider` | value |  |
| `AugurSiteConfig` | value |  |
| `AugurSiteDefaults` | value |  |
| `AugurSiteFormatting` | value |  |
| `CacheProvider` | value |  |
| `DeepQueryOptions` | value |  |
| `ProxyMutationOptions` | value |  |
| `ProxyQueryOptions` | value |  |
| `useAugurApi` | function |  |
| `useAugurAuth` | value |  |
| `useAugurOptions` | value |  |
| `useAugurSite` | value |  |
| `AugurAuthContext` | value |  |
| `createAugurOptions` | function | Creates server-side query options proxy for prefetching. |
| `MobileProvider` | function | Optional provider that tracks hydration state. |

### Cart

| Export | Kind | Description |
|--------|------|-------------|
| `getCartPricingQueryOptions` | function |  |
| `useCartActions` | function | Optimistic cart actions hook with automatic rollback on failure. |
| `useCartHdrUid` | const | Select the current cart header UID. |
| `useCartInitialization` | function | Initialize cart state from session (authenticated) or cookie (guest). |
| `useCartLineCount` | const | Select the number of distinct line items in the cart. |
| `useCartLines` | const | Select the current cart line items array. |
| `useCartPricing` | function | Centralized hook for cart/checkout pricing. |
| `useCartQuantityTotal` | const | Select the total quantity summed across all cart lines. |
| `useCartStore` | const | Zustand store for cart state. Prefer the individual selector hooks below for optimal re-renders. |
| `useClearCart` | const | Get the `clearCart` action (stable reference). |
| `useSetCartHdrUid` | const | Get the `setCartHdrUid` action (stable reference). |
| `useSetCartLines` | const | Get the `setCartLines` action (stable reference). Also recomputes totals. |
| `getCartPricingQueryOptions` | function |  |

### Configuration

| Export | Kind | Description |
|--------|------|-------------|
| `CacheConfig` | value |  |
| `CacheTierConfig` | value |  |
| `CacheConfig` | value |  |

### Image & CDN

| Export | Kind | Description |
|--------|------|-------------|
| `useImageWithFallback` | function | Preloads an agr.media image and shows a fallback while loading. |

### Items & Categories

| Export | Kind | Description |
|--------|------|-------------|
| `useItemFiltersStore` | const | Zustand store for item list filters, sorting, and pagination state. |

### Payment & Checkout

| Export | Kind | Description |
|--------|------|-------------|
| `usePaymentFlow` | function | Manages the full Element/Unified payment lifecycle: |

### Persistence

| Export | Kind | Description |
|--------|------|-------------|
| `PersistenceConfig` | value |  |
| `useAugurPersistence` | function | Returns a fully configured `persistOptions` object for use with |

### Pricing

| Export | Kind | Description |
|--------|------|-------------|
| `DerivePriceInput` | value |  |
| `DerivedPrice` | value |  |
| `useFormatPrice` | function | Hook that returns a price formatter. |

### Search

| Export | Kind | Description |
|--------|------|-------------|
| `SearchSuggestion` | value |  |
| `SearchSuggestionsResponse` | value |  |

### Stock

| Export | Kind | Description |
|--------|------|-------------|
| `ResolveStockInput` | value |  |
| `ResolvedStock` | value |  |
| `getStockKey` | value |  |
| `getStockOptions` | value |  |
| `useStock` | function | Fetches full TStock data and resolves it into a normalized stock object. |
| `getStockKey` | value |  |
| `getStockOptions` | value |  |

### Utilities

| Export | Kind | Description |
|--------|------|-------------|
| `useDebounce` | function | Debounces a rapidly-changing value. |
| `useIsHydrated` | function | Returns true only after the client has hydrated. |
| `useIsMobile` | function | Returns whether the screen is mobile-sized. |
| `useMobileOptimizedIntersection` | const | IntersectionObserver hook with mobile-optimized root margins. |

### Other

| Export | Kind | Description |
|--------|------|-------------|
| `EdgeCacheValue` | value |  |
| `InfiniteScrollPage` | value |  |
| `executeBatchQuery` | function |  |
| `getRegisteredQueryAction` | function | Returns the registered query action, or null if none registered. |
| `registerQueryAction` | function | Register a query action function (called by augur-server/hooks.ts on import). |
| `useAugurApiOptional` | value |  |
| `useAugurCache` | value |  |
| `usePaginationPrefetch` | const | Prefetch adjacent pages on hover for instant pagination. |
| `InfiniteScrollPage` | value |  |
| `executeBatchQuery` | function |  |
| `getQueryClient` | const | Returns a per-request singleton QueryClient for React Server Components. |

## Examples

### useAugurPersistence

```tsx
import { useAugurPersistence } from "@simpleapps-com/augur-hooks";

function Providers({ children }) {
  const [queryClient] = useState(() => new QueryClient({ ... }));
  const persistOptions = useAugurPersistence({
    key: "my-site-cache",
    buster: "1.0.0",
    persistableKeys: ["price", "categories", "invMast"],
    limits: { invMast: 100 },
  });

  return (
    <PersistQueryClientProvider client={queryClient} persistOptions={persistOptions}>
      <augur.Provider api={api} auth={auth}>
        {children}
      </augur.Provider>
    </PersistQueryClientProvider>
  );
}
```

### useCartActions

```tsx
import { useCartActions } from "@simpleapps-com/augur-hooks";
import { addToCart, updateCartLines, deleteItemsFromCart } from "@/lib/actions/commerce";
import { toast } from "react-toastify";

const cart = useCartActions({
  addToCart, updateCartLines, deleteItemsFromCart,
  toast: { info: toast.info, error: toast.error },
});

await cart.addToCart({ invMastUid: 123, quantity: 1, unitOfMeasure: "EA" });
```

### useCartInitialization

```tsx
import { useCartInitialization } from "@simpleapps-com/augur-hooks";
import { useSession } from "next-auth/react";
import { cartHdrLookup, getCartLines } from "@/lib/actions/commerce";

function CartInitializer() {
  const { data: session, status } = useSession();

  // Minimal setup — token storage defaults to localStorage,
  // token generation defaults to crypto.randomUUID().
  useCartInitialization(
    {
      status,
      userId: session?.user?.id,
      cartHdrUid: session?.user?.cartHdrUid,
    },
    { cartHdrLookup, getCartLines },
  );

  return null;
}
```

### usePaymentFlow

```tsx
import { usePaymentFlow } from "@simpleapps-com/augur-hooks";
import { transactionSetup, cardInfo, validatePayment, accountQuery, billingUpdate } from "@/lib/actions/payments";

const payment = usePaymentFlow({
  callbacks: { transactionSetup, cardInfo, validatePayment, accountQuery, billingUpdate },
  customerId,
  billingAddress,
  paymentMethod: "credit-card",
  shippingAccepted: true,
});
```

### createAugurOptions

```ts
// With SDK client (traditional)
const q = createAugurOptions(site.client, cacheConfig);

// With queryAction (server-only JWT sites)
import { queryAction } from "@simpleapps-com/augur-server/query-action";
const q = createAugurOptions(queryAction, cacheConfig);

// With auto-registered queryAction (zero args -- requires augur-server/hooks import)
const q = createAugurOptions();

await queryClient.prefetchQuery(q.items.invMast.doc.get(42));
```

## Types

`AugurApiClient`, `BatchQueryConfig`, `CartActionCallbacks`, `CartInitCallbacks`, `CartPriceData`, `CartPricingResult`, `CartSessionInfo`, `FormatPriceCallOptions`, `GetItemCategoryApiOptions`, `PageData`, `PaymentBillingAddress`, `PaymentFlowCallbacks`, `UseFormatPriceOptions`, `UseStockOptions`, `AugurApiClient`, `BatchQueryConfig`, `PageData`


## Related Packages

All packages use fixed versioning -- same version number across the platform.

| Package | Description |
|---------|-------------|
| `@simpleapps-com/augur-config` | Shared tooling configuration presets for Augur ecommerce sites |
| `@simpleapps-com/augur-core` | Universal foundation for Augur packages — proxy infrastructure, cache keys, method classification, shared types |
| `@simpleapps-com/augur-mobile` | React Native/Expo adapters for Augur ecommerce apps (offline sync, biometrics, push) |
| `@simpleapps-com/augur-server` | Server-side utilities for Augur ecommerce sites (Redis caching, SDK helpers, auth) |
| `@simpleapps-com/augur-tailwind` | Shared Tailwind CSS v4 theme with HSL variables for Augur ecommerce sites |
| `@simpleapps-com/augur-utils` | Shared types, cache configuration, and utility functions for Augur ecommerce sites |
| `@simpleapps-com/augur-web` | Shared React UI components for Augur ecommerce sites (Radix + Tailwind) |