@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

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 | 55 exports, 16 types | | @simpleapps-com/augur-hooks/server | 6 exports, 3 types | | @simpleapps-com/augur-hooks/web | 5 exports, 0 types | | @simpleapps-com/augur-hooks/checkout | 2 exports, 14 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 | | | clearFromSession | function | Removes a checkout persistence key from sessionStorage. | | loadFromSession | function | Loads a value from sessionStorage, checking TTL and optionally validating. | | saveToSession | function | Saves a value to sessionStorage with a timestamp for TTL expiration. | | 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. | | createCheckoutProvider | function | |

Cart

| Export | Kind | Description | |--------|------|-------------| | 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. |

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. |

Orders

| Export | Kind | Description | |--------|------|-------------| | determineOrderReadiness | function | Pure function that determines if an order is ready to submit. | | useOrderReadiness | function | Debounced order readiness hook. | | ORDER_CONFIRMATION_KEY | const | sessionStorage key for persisted order confirmation data. |

Payment & Checkout

| Export | Kind | Description | |--------|------|-------------| | clearCheckoutPersistence | function | Clears all checkout persistence keys from sessionStorage. | | useCheckoutPersistence | function | Hook that persists checkout state fields to sessionStorage and restores on mount. | | usePaymentFlow | function | |

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 | | | useStock | function | Fetches full TStock data and resolves it into a normalized stock object. |

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 | | | useModalLifecycle | function | Shared modal lifecycle hook -- scroll lock, Escape key, client-side hydration gate. | | 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

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

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

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;
}

createAugurOptions

// 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, CheckoutPersistField, FormatPriceCallOptions, GetItemCategoryApiOptions, OrderReadinessParams, PageData, PaymentBillingAddress, PaymentFlowCallbacks, UseFormatPriceOptions, UseStockOptions, AugurApiClient, BatchQueryConfig, PageData, CheckoutAddress, CheckoutContext, CheckoutContextValue, CheckoutIdentityConfig, CheckoutLifecycleHooks, CheckoutOrderConfig, CheckoutPaymentConfig, CheckoutPaymentModal, CheckoutProviderConfig, CheckoutProviderProps, CheckoutShippingConfig, CheckoutUIConfig, DefaultCheckoutStep, OrderConfirmation

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) |