@simpleapps-com/augur-hooks 2.4.0 → 2026.11.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/EXPORTS.md +25 -65
  2. package/README.md +21 -246
  3. package/dist/checkout/create-checkout-provider.d.ts +25 -0
  4. package/dist/checkout/create-checkout-provider.d.ts.map +1 -0
  5. package/dist/checkout/index.cjs +123 -106
  6. package/dist/checkout/index.cjs.map +1 -1
  7. package/dist/checkout/index.d.ts +5 -293
  8. package/dist/checkout/index.d.ts.map +1 -0
  9. package/dist/checkout/index.js +99 -82
  10. package/dist/checkout/index.js.map +1 -1
  11. package/dist/checkout/{index.d.cts → types.d.ts} +18 -40
  12. package/dist/checkout/types.d.ts.map +1 -0
  13. package/dist/chunk-6Z6JGK2C.cjs.map +1 -1
  14. package/dist/chunk-QB7VB5FZ.cjs +523 -0
  15. package/dist/chunk-QB7VB5FZ.cjs.map +1 -0
  16. package/dist/{chunk-JNOHB4OP.js → chunk-UTDAFIQP.js} +234 -94
  17. package/dist/chunk-UTDAFIQP.js.map +1 -0
  18. package/dist/hooks/use-cart-actions.d.ts +68 -0
  19. package/dist/hooks/use-cart-actions.d.ts.map +1 -0
  20. package/dist/hooks/use-cart-initialization.d.ts +60 -0
  21. package/dist/hooks/use-cart-initialization.d.ts.map +1 -0
  22. package/dist/hooks/use-cart-pricing.d.ts +41 -0
  23. package/dist/hooks/use-cart-pricing.d.ts.map +1 -0
  24. package/dist/hooks/use-checkout-persistence.d.ts +40 -0
  25. package/dist/hooks/use-checkout-persistence.d.ts.map +1 -0
  26. package/dist/hooks/use-debounce.d.ts +6 -0
  27. package/dist/hooks/use-debounce.d.ts.map +1 -0
  28. package/dist/hooks/use-format-price.d.ts +29 -0
  29. package/dist/hooks/use-format-price.d.ts.map +1 -0
  30. package/dist/hooks/use-latest.d.ts +8 -0
  31. package/dist/hooks/use-latest.d.ts.map +1 -0
  32. package/dist/hooks/use-modal-lifecycle.d.ts +11 -0
  33. package/dist/hooks/use-modal-lifecycle.d.ts.map +1 -0
  34. package/dist/hooks/use-order-readiness.d.ts +47 -0
  35. package/dist/hooks/use-order-readiness.d.ts.map +1 -0
  36. package/dist/hooks/use-pagination-prefetch.d.ts +26 -0
  37. package/dist/hooks/use-pagination-prefetch.d.ts.map +1 -0
  38. package/dist/{use-order-readiness-DZTIfRzw.d.ts → hooks/use-payment-flow.d.ts} +23 -67
  39. package/dist/hooks/use-payment-flow.d.ts.map +1 -0
  40. package/dist/hooks/use-stock.d.ts +32 -0
  41. package/dist/hooks/use-stock.d.ts.map +1 -0
  42. package/dist/index.cjs +215 -178
  43. package/dist/index.cjs.map +1 -1
  44. package/dist/index.d.ts +32 -456
  45. package/dist/index.d.ts.map +1 -0
  46. package/dist/index.js +193 -156
  47. package/dist/index.js.map +1 -1
  48. package/dist/persistence/apply-limits.d.ts +8 -0
  49. package/dist/persistence/apply-limits.d.ts.map +1 -0
  50. package/dist/persistence/create-persister.d.ts +10 -0
  51. package/dist/persistence/create-persister.d.ts.map +1 -0
  52. package/dist/persistence/serializer.d.ts +11 -0
  53. package/dist/persistence/serializer.d.ts.map +1 -0
  54. package/dist/persistence/use-persistence.d.ts +59 -0
  55. package/dist/persistence/use-persistence.d.ts.map +1 -0
  56. package/dist/persistence/use-storage-monitor.d.ts +11 -0
  57. package/dist/persistence/use-storage-monitor.d.ts.map +1 -0
  58. package/dist/provider.d.ts +89 -0
  59. package/dist/provider.d.ts.map +1 -0
  60. package/dist/queries/batch-query.d.ts +23 -0
  61. package/dist/queries/batch-query.d.ts.map +1 -0
  62. package/dist/queries/cache-helper.d.ts +16 -0
  63. package/dist/queries/cache-helper.d.ts.map +1 -0
  64. package/dist/queries/index.d.ts +3 -0
  65. package/dist/queries/index.d.ts.map +1 -0
  66. package/dist/query-action-registry.d.ts +19 -0
  67. package/dist/query-action-registry.d.ts.map +1 -0
  68. package/dist/rules.d.ts +130 -0
  69. package/dist/rules.d.ts.map +1 -0
  70. package/dist/server.cjs.map +1 -1
  71. package/dist/server.d.ts +10 -12
  72. package/dist/server.d.ts.map +1 -0
  73. package/dist/stores/cart-store.d.ts +51 -0
  74. package/dist/stores/cart-store.d.ts.map +1 -0
  75. package/dist/stores/items-filters-store.d.ts +30 -0
  76. package/dist/stores/items-filters-store.d.ts.map +1 -0
  77. package/dist/types.d.ts +48 -0
  78. package/dist/types.d.ts.map +1 -0
  79. package/dist/web/use-image-with-fallback.d.ts +16 -0
  80. package/dist/web/use-image-with-fallback.d.ts.map +1 -0
  81. package/dist/web/use-mobile-detection.d.ts +28 -0
  82. package/dist/web/use-mobile-detection.d.ts.map +1 -0
  83. package/dist/web/use-mobile-optimized-intersection.d.ts +17 -0
  84. package/dist/web/use-mobile-optimized-intersection.d.ts.map +1 -0
  85. package/dist/web.cjs.map +1 -1
  86. package/dist/web.d.ts +4 -60
  87. package/dist/web.d.ts.map +1 -0
  88. package/dist/web.js.map +1 -1
  89. package/llms.txt +76 -54
  90. package/package.json +25 -14
  91. package/dist/batch-query-CTlvxSmL.d.cts +0 -165
  92. package/dist/batch-query-CTlvxSmL.d.ts +0 -165
  93. package/dist/chunk-F5DUFW57.cjs +0 -383
  94. package/dist/chunk-F5DUFW57.cjs.map +0 -1
  95. package/dist/chunk-JNOHB4OP.js.map +0 -1
  96. package/dist/index.d.cts +0 -456
  97. package/dist/server.d.cts +0 -44
  98. package/dist/use-order-readiness-DZTIfRzw.d.cts +0 -137
  99. package/dist/web.d.cts +0 -60
package/dist/web.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/web/use-mobile-detection.tsx","../src/web/use-mobile-optimized-intersection.ts","../src/web/use-image-with-fallback.ts"],"sourcesContent":["import { createContext, useContext, useSyncExternalStore, type ReactNode } from \"react\";\n\nconst MOBILE_BREAKPOINT = 992;\nconst THROTTLE_MS = 150;\n\n// Singleton state for mobile detection\nlet isMobileState = false;\nconst listeners: Set<() => void> = new Set();\nlet throttleTimeout: ReturnType<typeof setTimeout> | null = null;\nlet cleanupResize: (() => void) | null = null;\n\nfunction getSnapshot(): boolean {\n return isMobileState;\n}\n\n/* v8 ignore next 3 */\nfunction getServerSnapshot(): boolean {\n return false;\n}\n\nfunction subscribe(callback: () => void): () => void {\n if (listeners.size === 0 && typeof window !== \"undefined\") {\n isMobileState = window.innerWidth <= MOBILE_BREAKPOINT;\n\n const handleResize = () => {\n if (throttleTimeout) return;\n\n throttleTimeout = setTimeout(() => {\n throttleTimeout = null;\n const newValue = window.innerWidth <= MOBILE_BREAKPOINT;\n if (newValue !== isMobileState) {\n isMobileState = newValue;\n listeners.forEach((listener) => listener());\n }\n }, THROTTLE_MS);\n };\n\n window.addEventListener(\"resize\", handleResize, { passive: true });\n\n cleanupResize = () => {\n window.removeEventListener(\"resize\", handleResize);\n if (throttleTimeout) {\n clearTimeout(throttleTimeout);\n throttleTimeout = null;\n }\n };\n }\n\n listeners.add(callback);\n\n return () => {\n listeners.delete(callback);\n if (listeners.size === 0 && cleanupResize) {\n cleanupResize();\n cleanupResize = null;\n }\n };\n}\n\n/**\n * Returns whether the screen is mobile-sized.\n * Uses `useSyncExternalStore` for proper SSR support.\n *\n * - SSR-safe: returns false on server, updates on client after hydration\n * - Single listener: one resize listener regardless of component count\n * - Throttled: resize events throttled to prevent excessive re-renders\n */\nexport function useIsMobile(): boolean {\n return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n}\n\nconst HydrationContext = createContext(false);\n\ninterface MobileProviderProps {\n children: ReactNode;\n}\n\n/**\n * Optional provider that tracks hydration state.\n * Wrap your app with this if you need to conditionally render\n * mobile-only content after hydration.\n */\nexport function MobileProvider({ children }: MobileProviderProps) {\n const isHydrated = useSyncExternalStore(\n () => () => {},\n () => true,\n () => false,\n );\n\n return <HydrationContext.Provider value={isHydrated}>{children}</HydrationContext.Provider>;\n}\n\n/**\n * Returns true only after the client has hydrated.\n * Prevents hydration mismatches with conditional rendering.\n */\nexport function useIsHydrated(): boolean {\n return useContext(HydrationContext);\n}\n","\"use client\";\n\nimport { useEffect, useState, useRef } from \"react\";\n\ninterface UseMobileOptimizedIntersectionOptions {\n rootMarginMobile?: string;\n rootMarginDesktop?: string;\n threshold?: number;\n enabled?: boolean;\n mobileBreakpoint?: number;\n}\n\n/**\n * IntersectionObserver hook with mobile-optimized root margins.\n * Uses larger margins on mobile for more aggressive prefetching/lazy loading.\n */\nexport const useMobileOptimizedIntersection = ({\n rootMarginMobile = \"300px\",\n rootMarginDesktop = \"150px\",\n threshold = 0,\n enabled = true,\n mobileBreakpoint = 992,\n}: UseMobileOptimizedIntersectionOptions = {}) => {\n const [isIntersecting, setIsIntersecting] = useState(false);\n const elementRef = useRef<HTMLDivElement | null>(null);\n\n useEffect(() => {\n if (!enabled || !elementRef.current) return;\n\n const isMobile = window.innerWidth <= mobileBreakpoint;\n\n const observer = new IntersectionObserver(\n (entries) => {\n entries.forEach((entry) => {\n if (entry.isIntersecting && !isIntersecting) {\n setIsIntersecting(true);\n }\n });\n },\n {\n rootMargin: isMobile ? rootMarginMobile : rootMarginDesktop,\n threshold,\n },\n );\n\n observer.observe(elementRef.current);\n\n return () => {\n observer.disconnect();\n };\n }, [enabled, rootMarginMobile, rootMarginDesktop, threshold, isIntersecting, mobileBreakpoint]);\n\n return {\n ref: elementRef,\n isIntersecting,\n };\n};\n","\"use client\";\n\nimport { useEffect, useState, useRef } from \"react\";\nimport type { ImageConfig, ImageUrlOptions } from \"@simpleapps-com/augur-utils\";\nimport { getImageUrl, getDefaultImageUrl } from \"@simpleapps-com/augur-utils\";\n\ninterface UseImageWithFallbackResult {\n src: string;\n isLoading: boolean;\n hasError: boolean;\n}\n\n/**\n * Preloads an agr.media image and shows a fallback while loading.\n *\n * 1. Returns the default image immediately.\n * 2. Preloads the real image via `new Image()`.\n * 3. Swaps to the real URL on success; keeps the fallback on error.\n */\nexport function useImageWithFallback(\n config: ImageConfig,\n imagePath: string | undefined,\n options?: ImageUrlOptions,\n): UseImageWithFallbackResult {\n const defaultSrc = getDefaultImageUrl(config, options);\n const realSrc = imagePath ? getImageUrl(config, imagePath) : \"\";\n\n const [src, setSrc] = useState(defaultSrc);\n const [isLoading, setIsLoading] = useState(!!realSrc);\n const [hasError, setHasError] = useState(false);\n const imageRef = useRef<HTMLImageElement | null>(null);\n\n useEffect(() => {\n if (!realSrc) {\n setSrc(defaultSrc);\n setIsLoading(false);\n setHasError(false);\n return;\n }\n\n setSrc(defaultSrc);\n setIsLoading(true);\n setHasError(false);\n\n const img = new Image();\n imageRef.current = img;\n\n img.onload = () => {\n setSrc(realSrc);\n setIsLoading(false);\n };\n\n img.onerror = () => {\n setIsLoading(false);\n setHasError(true);\n };\n\n img.src = realSrc;\n\n return () => {\n img.onload = null;\n img.onerror = null;\n imageRef.current = null;\n };\n }, [realSrc, defaultSrc]);\n\n return { src, isLoading, hasError };\n}\n"],"mappings":"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","names":["useEffect","useState","useRef"]}
1
+ {"version":3,"sources":["../src/web/use-mobile-detection.tsx","../src/web/use-mobile-optimized-intersection.ts","../src/web/use-image-with-fallback.ts"],"sourcesContent":["import { createContext, useContext, useSyncExternalStore, type ReactNode } from \"react\";\n\nconst MOBILE_BREAKPOINT = 992;\nconst THROTTLE_MS = 150;\n\n// Singleton state for mobile detection\nlet isMobileState = false;\nconst listeners: Set<() => void> = new Set();\nlet throttleTimeout: ReturnType<typeof setTimeout> | null = null;\nlet cleanupResize: (() => void) | null = null;\n\nfunction getSnapshot(): boolean {\n return isMobileState;\n}\n\nfunction getServerSnapshot(): boolean {\n return false;\n}\n\n/** The store's subscribe: one throttled resize listener shared by every subscriber (none without a window). */\nexport function subscribe(callback: () => void): () => void {\n if (listeners.size === 0 && typeof window !== \"undefined\") {\n isMobileState = window.innerWidth <= MOBILE_BREAKPOINT;\n\n const handleResize = () => {\n if (throttleTimeout) return;\n\n throttleTimeout = setTimeout(() => {\n throttleTimeout = null;\n const newValue = window.innerWidth <= MOBILE_BREAKPOINT;\n if (newValue !== isMobileState) {\n isMobileState = newValue;\n listeners.forEach((listener) => listener());\n }\n }, THROTTLE_MS);\n };\n\n window.addEventListener(\"resize\", handleResize, { passive: true });\n\n cleanupResize = () => {\n window.removeEventListener(\"resize\", handleResize);\n if (throttleTimeout) {\n clearTimeout(throttleTimeout);\n throttleTimeout = null;\n }\n };\n }\n\n listeners.add(callback);\n\n return () => {\n listeners.delete(callback);\n if (listeners.size === 0 && cleanupResize) {\n cleanupResize();\n cleanupResize = null;\n }\n };\n}\n\n/**\n * Returns whether the screen is mobile-sized.\n * Uses `useSyncExternalStore` for proper SSR support.\n *\n * - SSR-safe: returns false on server, updates on client after hydration\n * - Single listener: one resize listener regardless of component count\n * - Throttled: resize events throttled to prevent excessive re-renders\n */\nexport function useIsMobile(): boolean {\n return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n}\n\nconst HydrationContext = createContext(false);\n\ninterface MobileProviderProps {\n children: ReactNode;\n}\n\n/**\n * Optional provider that tracks hydration state.\n * Wrap your app with this if you need to conditionally render\n * mobile-only content after hydration.\n */\nexport function MobileProvider({ children }: MobileProviderProps) {\n const isHydrated = useSyncExternalStore(\n () => () => {},\n () => true,\n () => false,\n );\n\n return <HydrationContext.Provider value={isHydrated}>{children}</HydrationContext.Provider>;\n}\n\n/**\n * Returns true only after the client has hydrated.\n * Prevents hydration mismatches with conditional rendering.\n */\nexport function useIsHydrated(): boolean {\n return useContext(HydrationContext);\n}\n","\"use client\";\n\nimport { useEffect, useState, useRef } from \"react\";\n\ninterface UseMobileOptimizedIntersectionOptions {\n rootMarginMobile?: string;\n rootMarginDesktop?: string;\n threshold?: number;\n enabled?: boolean;\n mobileBreakpoint?: number;\n}\n\n/**\n * IntersectionObserver hook with mobile-optimized root margins.\n * Uses larger margins on mobile for more aggressive prefetching/lazy loading.\n */\nexport const useMobileOptimizedIntersection = ({\n rootMarginMobile = \"300px\",\n rootMarginDesktop = \"150px\",\n threshold = 0,\n enabled = true,\n mobileBreakpoint = 992,\n}: UseMobileOptimizedIntersectionOptions = {}) => {\n const [isIntersecting, setIsIntersecting] = useState(false);\n const elementRef = useRef<HTMLDivElement | null>(null);\n\n useEffect(() => {\n if (!enabled || !elementRef.current) return;\n\n const isMobile = window.innerWidth <= mobileBreakpoint;\n\n const observer = new IntersectionObserver(\n (entries) => {\n entries.forEach((entry) => {\n if (entry.isIntersecting && !isIntersecting) {\n setIsIntersecting(true);\n }\n });\n },\n {\n rootMargin: isMobile ? rootMarginMobile : rootMarginDesktop,\n threshold,\n },\n );\n\n observer.observe(elementRef.current);\n\n return () => {\n observer.disconnect();\n };\n }, [enabled, rootMarginMobile, rootMarginDesktop, threshold, isIntersecting, mobileBreakpoint]);\n\n return {\n ref: elementRef,\n isIntersecting,\n };\n};\n","\"use client\";\n\nimport { useEffect, useState, useRef } from \"react\";\nimport type { ImageConfig, ImageUrlOptions } from \"@simpleapps-com/augur-utils\";\nimport { getImageUrl, getDefaultImageUrl } from \"@simpleapps-com/augur-utils\";\n\ninterface UseImageWithFallbackResult {\n src: string;\n isLoading: boolean;\n hasError: boolean;\n}\n\n/**\n * Preloads an agr.media image and shows a fallback while loading.\n *\n * 1. Returns the default image immediately.\n * 2. Preloads the real image via `new Image()`.\n * 3. Swaps to the real URL on success; keeps the fallback on error.\n */\nexport function useImageWithFallback(\n config: ImageConfig,\n imagePath: string | undefined,\n options?: ImageUrlOptions,\n): UseImageWithFallbackResult {\n const defaultSrc = getDefaultImageUrl(config, options);\n const realSrc = imagePath ? getImageUrl(config, imagePath) : \"\";\n\n const [src, setSrc] = useState(defaultSrc);\n const [isLoading, setIsLoading] = useState(!!realSrc);\n const [hasError, setHasError] = useState(false);\n const imageRef = useRef<HTMLImageElement | null>(null);\n\n useEffect(() => {\n if (!realSrc) {\n setSrc(defaultSrc);\n setIsLoading(false);\n setHasError(false);\n return;\n }\n\n setSrc(defaultSrc);\n setIsLoading(true);\n setHasError(false);\n\n const img = new Image();\n imageRef.current = img;\n\n img.onload = () => {\n setSrc(realSrc);\n setIsLoading(false);\n };\n\n img.onerror = () => {\n setIsLoading(false);\n setHasError(true);\n };\n\n img.src = realSrc;\n\n return () => {\n img.onload = null;\n img.onerror = null;\n imageRef.current = null;\n };\n }, [realSrc, defaultSrc]);\n\n return { src, isLoading, hasError };\n}\n"],"mappings":"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","names":["useEffect","useState","useRef"]}
package/llms.txt CHANGED
@@ -1,22 +1,19 @@
1
1
  # Augur Platform Packages
2
2
 
3
3
  This package is part of the @simpleapps-com/augur-* platform.
4
- All packages use fixed versioning (same version number).
5
- The proxy pattern (createServerQueryProxy) is the primary data fetching API.
6
- Pure transform utilities bridge user-facing types to SDK params without breaking proxy type safety.
4
+ Each package releases on its own CalVer version; nothing requires them to share one.
5
+ The docs are at https://augur.build/docs/packages (the API reference lists every export).
7
6
 
8
7
  ## Sibling packages
9
8
 
10
- - @simpleapps-com/augur-config - Shared tooling configuration presets for Augur ecommerce sites
11
9
  - @simpleapps-com/augur-core - Universal foundation for Augur packages — proxy infrastructure, cache keys, method classification, shared types
10
+ - @simpleapps-com/augur-utils - Shared types, cache configuration, and utility functions for Augur ecommerce sites
12
11
  - @simpleapps-com/augur-hooks (this package) - Cross-platform React Query hooks and Zustand stores for Augur ecommerce sites
13
- - @simpleapps-com/augur-mobile - React Native/Expo adapters for Augur ecommerce apps (offline sync, biometrics, push)
14
12
  - @simpleapps-com/augur-server - Server-side utilities for Augur ecommerce sites (Redis caching, SDK helpers, auth)
15
- - @simpleapps-com/augur-tailwind - Shared Tailwind CSS v4 theme with HSL variables for Augur ecommerce sites
16
- - @simpleapps-com/augur-utils - Shared types, cache configuration, and utility functions for Augur ecommerce sites
17
13
  - @simpleapps-com/augur-web - Shared React UI components for Augur ecommerce sites (Radix + Tailwind)
18
-
19
- Each package ships its own llms.txt with exports and usage patterns.
14
+ - @simpleapps-com/augur-mobile - React Native/Expo adapters for Augur ecommerce apps (offline sync, biometrics, push)
15
+ - @simpleapps-com/augur-tailwind - Shared Tailwind CSS v4 theme with HSL variables for Augur ecommerce sites
16
+ - @simpleapps-com/augur-config - Shared tooling configuration presets for Augur ecommerce sites
20
17
 
21
18
  ---
22
19
 
@@ -24,48 +21,27 @@ Each package ships its own llms.txt with exports and usage patterns.
24
21
 
25
22
  > Cross-platform React Query hooks and Zustand stores for Augur ecommerce sites
26
23
 
27
- Version: 2.2.29
28
-
29
24
  ## @simpleapps-com/augur-hooks
30
25
 
31
- - value: AugurAuthContext
32
- - value: AugurHooksProvider
33
- - value: AugurSiteConfig
34
- - value: AugurSiteDefaults
35
- - value: AugurSiteFormatting
36
- - value: CacheConfig
37
- - value: CacheProvider
38
- - value: CacheTierConfig
39
- - value: DeepQueryOptions
40
- - value: DerivePriceInput
41
- - value: DerivedPrice
42
- - value: EdgeCacheValue
43
- - value: InfiniteScrollPage
44
- - value: PersistenceConfig
45
- - value: ProxyMutationOptions
46
- - value: ProxyQueryOptions
47
- - value: ResolveStockInput
48
- - value: ResolvedStock
49
- - value: SearchSuggestion
50
- - value: SearchSuggestionsResponse
26
+ - function: AugurHooksProvider - Provides the augur-api SDK instance, proxy options, and auth to all hooks.
51
27
  - function: clearCheckoutPersistence - Clears all checkout persistence keys from sessionStorage.
52
28
  - function: clearFromSession - Removes a checkout persistence key from sessionStorage.
53
29
  - function: determineOrderReadiness - Pure function that determines if an order is ready to submit.
54
- - function: executeBatchQuery
30
+ - function: executeBatchQuery - Generic batch query executor.
55
31
  - function: getRegisteredQueryAction - Returns the registered query action, or null if none registered.
56
32
  - function: loadFromSession - Loads a value from sessionStorage, checking TTL and optionally validating.
57
33
  - function: registerQueryAction - Register a query action function (called by augur-server/hooks.ts on import).
58
34
  - function: saveToSession - Saves a value to sessionStorage with a timestamp for TTL expiration.
59
- - function: useAugurApi
60
- - value: useAugurApiOptional
61
- - value: useAugurAuth
62
- - value: useAugurCache
63
- - value: useAugurOptions
64
- - function: useAugurPersistence - Returns a fully configured `persistOptions` object for use with
65
- - value: useAugurSite
35
+ - function: useAugurApi - Returns the augur-api SDK instance from context. Throws if called outside of `<AugurHooksProvider>` or when no api is provided.
36
+ - function: useAugurApiOptional - Returns the augur-api SDK instance from context, or null if not provided. Used internally by hooks that need the SDK for fallback queries.
37
+ - function: useAugurAuth - Returns the provider-level auth context, if any. Used internally by hooks to fall back to provider auth when auth fields are not passed directly as hook parameters.
38
+ - function: useAugurCache - Returns the provider-level cache configuration, if any. Used internally by hooks to enable edge/Redis caching.
39
+ - function: useAugurOptions - Returns the deep proxy for creating TanStack Query options.
40
+ - function: useAugurPersistence - Returns a fully configured `persistOptions` object for use with `PersistQueryClientProvider` from `@tanstack/react-query-persist-client`.
41
+ - function: useAugurSite - Returns the site configuration from the nearest `AugurHooksProvider`. Returns `undefined` when no `site` prop is provided.
66
42
  - function: useCartActions - Optimistic cart actions hook with automatic rollback on failure.
67
43
  - const: useCartHdrUid - Select the current cart header UID.
68
- - function: useCartInitialization - Initialize cart state from session (authenticated) or cookie (guest).
44
+ - function: useCartInitialization - Initialize cart state from session (authenticated) or cookie (guest). Call once in the root layout.
69
45
  - const: useCartLineCount - Select the number of distinct line items in the cart.
70
46
  - const: useCartLines - Select the current cart line items array.
71
47
  - function: useCartPricing - Centralized hook for cart/checkout pricing.
@@ -73,35 +49,68 @@ Version: 2.2.29
73
49
  - const: useCartStore - Zustand store for cart state. Prefer the individual selector hooks below for optimal re-renders.
74
50
  - function: useCheckoutPersistence - Hook that persists checkout state fields to sessionStorage and restores on mount.
75
51
  - const: useClearCart - Get the `clearCart` action (stable reference).
76
- - function: useDebounce - Debounces a rapidly-changing value.
77
- - function: useFormatPrice - Hook that returns a price formatter.
52
+ - function: useDebounce - Debounces a rapidly-changing value. Returns the latest value only after `delay` ms of inactivity.
53
+ - function: useFormatPrice - Hook that returns a price formatter. Reads defaults from site config when params are omitted.
78
54
  - const: useItemFiltersStore - Zustand store for item list filters, sorting, and pagination state.
79
55
  - function: useModalLifecycle - Shared modal lifecycle hook -- scroll lock, Escape key, client-side hydration gate.
80
56
  - function: useOrderReadiness - Debounced order readiness hook.
81
- - const: usePaginationPrefetch - Prefetch adjacent pages on hover for instant pagination.
82
- - function: usePaymentFlow
57
+ - const: usePaginationPrefetch - Prefetch adjacent pages on hover for instant pagination. Accepts a generic queryFn so it works with any paginated resource.
58
+ - function: usePaymentFlow - Manages the full Element/Unified payment lifecycle: transactionSetup -> cardInfo -> validatePayment -> accountQuery -> billingUpdate
83
59
  - const: useSetCartHdrUid - Get the `setCartHdrUid` action (stable reference).
84
60
  - const: useSetCartLines - Get the `setCartLines` action (stable reference). Also recomputes totals.
85
61
  - function: useStock - Fetches full TStock data and resolves it into a normalized stock object.
86
62
  - type: AugurApiClient
63
+ - type: AugurAuthContext
64
+ - type: AugurSiteConfig
65
+ - type: AugurSiteDefaults
66
+ - type: AugurSiteFormatting
87
67
  - type: BatchQueryConfig
68
+ - type: CacheConfig
69
+ - type: CacheProvider
70
+ - type: CacheTierConfig
88
71
  - type: CartActionCallbacks
89
72
  - type: CartInitCallbacks
90
73
  - type: CartPriceData
91
74
  - type: CartPricingResult
92
75
  - type: CartSessionInfo
93
76
  - type: CheckoutPersistField
77
+ - type: DeepQueryOptions
78
+ - type: DerivedPrice
79
+ - type: DerivePriceInput
80
+ - type: EdgeCacheValue
94
81
  - type: FormatPriceCallOptions
95
82
  - type: GetItemCategoryApiOptions
83
+ - type: InfiniteScrollPage
96
84
  - type: OrderReadinessParams
97
85
  - type: PageData
98
86
  - type: PaymentBillingAddress
99
87
  - type: PaymentFlowCallbacks
88
+ - type: PersistenceConfig
89
+ - type: ProxyMutationOptions
90
+ - type: ProxyQueryOptions
91
+ - type: ResolvedStock
92
+ - type: ResolveStockInput
93
+ - type: SearchSuggestion
94
+ - type: SearchSuggestionsResponse
100
95
  - type: UseFormatPriceOptions
101
96
  - type: UseStockOptions
102
97
 
103
98
  ### Examples
104
99
 
100
+ useAugurOptions:
101
+ ```tsx
102
+ // With api (direct SDK access):
103
+ const q = useAugurOptions();
104
+ const { data } = useQuery(q.items.invMast.get(42));
105
+
106
+ // Without api (server-only JWT):
107
+ const q = useAugurOptions();
108
+ const { data } = useQuery({
109
+ ...q.items.invMast.doc.get(42),
110
+ queryFn: () => getItemAction(42), // server action
111
+ });
112
+ ```
113
+
105
114
  useAugurPersistence:
106
115
  ```tsx
107
116
  import { useAugurPersistence } from "@simpleapps-com/augur-hooks";
@@ -163,17 +172,30 @@ function CartInitializer() {
163
172
  }
164
173
  ```
165
174
 
175
+ usePaymentFlow:
176
+ ```tsx
177
+ import { usePaymentFlow } from "@simpleapps-com/augur-hooks";
178
+ import { transactionSetup, cardInfo, validatePayment, accountQuery, billingUpdate } from "@/lib/actions/payments";
179
+
180
+ const payment = usePaymentFlow({
181
+ callbacks: { transactionSetup, cardInfo, validatePayment, accountQuery, billingUpdate },
182
+ customerId,
183
+ billingAddress,
184
+ paymentMethod: "credit-card",
185
+ shippingAccepted: true,
186
+ });
187
+ ```
166
188
 
167
189
  ## @simpleapps-com/augur-hooks/server
168
190
 
169
- - value: AugurAuthContext
170
- - value: CacheConfig
171
- - value: InfiniteScrollPage
172
191
  - function: createAugurOptions - Creates server-side query options proxy for prefetching.
173
- - function: executeBatchQuery
192
+ - function: executeBatchQuery - Generic batch query executor.
174
193
  - const: getQueryClient - Returns a per-request singleton QueryClient for React Server Components.
175
194
  - type: AugurApiClient
195
+ - type: AugurAuthContext
176
196
  - type: BatchQueryConfig
197
+ - type: CacheConfig
198
+ - type: InfiniteScrollPage
177
199
  - type: PageData
178
200
 
179
201
  ### Examples
@@ -193,19 +215,18 @@ const q = createAugurOptions();
193
215
  await queryClient.prefetchQuery(q.items.invMast.doc.get(42));
194
216
  ```
195
217
 
196
-
197
218
  ## @simpleapps-com/augur-hooks/web
198
219
 
199
- - function: MobileProvider - Optional provider that tracks hydration state.
220
+ - function: MobileProvider - Optional provider that tracks hydration state. Wrap your app with this if you need to conditionally render mobile-only content after hydration.
200
221
  - function: useImageWithFallback - Preloads an agr.media image and shows a fallback while loading.
201
- - function: useIsHydrated - Returns true only after the client has hydrated.
202
- - function: useIsMobile - Returns whether the screen is mobile-sized.
203
- - const: useMobileOptimizedIntersection - IntersectionObserver hook with mobile-optimized root margins.
222
+ - function: useIsHydrated - Returns true only after the client has hydrated. Prevents hydration mismatches with conditional rendering.
223
+ - function: useIsMobile - Returns whether the screen is mobile-sized. Uses `useSyncExternalStore` for proper SSR support.
224
+ - const: useMobileOptimizedIntersection - IntersectionObserver hook with mobile-optimized root margins. Uses larger margins on mobile for more aggressive prefetching/lazy loading.
204
225
 
205
226
  ## @simpleapps-com/augur-hooks/checkout
206
227
 
207
- - const: ORDER_CONFIRMATION_KEY - sessionStorage key for persisted order confirmation data.
208
228
  - function: createCheckoutProvider
229
+ - const: ORDER_CONFIRMATION_KEY - sessionStorage key for persisted order confirmation data.
209
230
  - type: CheckoutAddress
210
231
  - type: CheckoutContext
211
232
  - type: CheckoutContextValue
@@ -220,3 +241,4 @@ await queryClient.prefetchQuery(q.items.invMast.doc.get(42));
220
241
  - type: CheckoutUIConfig
221
242
  - type: DefaultCheckoutStep
222
243
  - type: OrderConfirmation
244
+ - type: TCartLine
package/package.json CHANGED
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "@simpleapps-com/augur-hooks",
3
- "version": "2.4.0",
3
+ "version": "2026.11.1",
4
4
  "description": "Cross-platform React Query hooks and Zustand stores for Augur ecommerce sites",
5
5
  "license": "MIT",
6
6
  "repository": {
7
7
  "type": "git",
8
- "url": "https://github.com/simpleapps-com/augur-packages.git",
8
+ "url": "https://github.com/simpleapps-com/atlas.git",
9
9
  "directory": "packages/augur-hooks"
10
10
  },
11
11
  "type": "module",
@@ -38,11 +38,11 @@
38
38
  "llms.txt"
39
39
  ],
40
40
  "dependencies": {
41
- "@simpleapps-com/augur-core": "2.4.0",
42
- "@simpleapps-com/augur-utils": "2.4.0"
41
+ "@simpleapps-com/augur-core": "^2026.11.1",
42
+ "@simpleapps-com/augur-utils": "^2026.11.1"
43
43
  },
44
44
  "peerDependencies": {
45
- "@simpleapps-com/augur-api": "^2026.4.7",
45
+ "@simpleapps-com/augur-api": "^2026.10.17",
46
46
  "@tanstack/react-query": "^5.80.0",
47
47
  "@tanstack/react-query-persist-client": "^5.80.0",
48
48
  "react": "^19.0.0",
@@ -50,25 +50,36 @@
50
50
  },
51
51
  "devDependencies": {
52
52
  "@tanstack/react-query": "^5.80.0",
53
+ "@tanstack/react-query-persist-client": "^5.80.0",
53
54
  "@testing-library/react": "^16.3.2",
54
- "@types/node": "^22.0.0",
55
+ "@types/node": "^26.6.6",
55
56
  "@types/react": "^19.0.0",
56
57
  "@types/react-dom": "^19.0.0",
57
- "@vitest/coverage-v8": "^3.2.4",
58
+ "@vitest/coverage-v8": "~5.0.3",
59
+ "eslint": "^10.12.0",
58
60
  "jsdom": "^28.1.0",
61
+ "lemmascript": "0.6.5",
59
62
  "react": "^19.0.0",
60
63
  "react-dom": "^19.2.4",
61
- "tsup": "^8.5.0",
62
- "vitest": "^3.2.0",
64
+ "tsup": "^9.0.0",
65
+ "typescript": "~6.0.3",
66
+ "vitest": "~5.0.3",
63
67
  "zustand": "^5.0.0",
64
- "@augur-packages/tsconfig": "0.0.0"
68
+ "@atlas/eslint-config": "0.0.0",
69
+ "@atlas/tsconfig": "0.0.0",
70
+ "@atlas/tsup-config": "0.0.0",
71
+ "@atlas/utils": "0.0.0",
72
+ "@atlas/vitest-config": "0.0.0",
73
+ "@simpleapps-com/augur-api": "2026.11.2"
74
+ },
75
+ "engines": {
76
+ "node": ">=22.0.0"
65
77
  },
66
78
  "scripts": {
67
- "build": "tsup",
68
- "dev": "tsup --watch",
69
- "lint": "eslint src/",
79
+ "build": "tsup && tsc -p tsconfig.build.json",
80
+ "lint": "eslint .",
70
81
  "test": "vitest run --coverage",
71
82
  "typecheck": "tsc --noEmit",
72
- "check-exports": "node scripts/check-exports.mjs"
83
+ "proofs": "lsc check --backend=dafny"
73
84
  }
74
85
  }
@@ -1,165 +0,0 @@
1
- import * as react_jsx_runtime from 'react/jsx-runtime';
2
- import { ReactNode } from 'react';
3
- import { AugurAuthContext, CacheConfig, AugurSiteConfig, DeepQueryOptions } from '@simpleapps-com/augur-core';
4
- import { AugurAPI } from '@simpleapps-com/augur-api';
5
- import { QueryClient } from '@tanstack/react-query';
6
-
7
- /**
8
- * Minimal type for the augur-api SDK instance.
9
- * Consumers provide their concrete AugurAPI instance; we keep the type
10
- * loose so augur-hooks doesn't need to depend directly on the SDK package.
11
- */
12
- type AugurApiClient = any;
13
- interface AugurHooksProviderProps {
14
- /** SDK client instance. When omitted, `useAugurOptions()` returns a keys-only
15
- * proxy — consumers MUST override queryFn with a server action at each call site. */
16
- api?: AugurApiClient;
17
- /** Optional auth context — hooks fall back to these values when not passed directly. */
18
- auth?: AugurAuthContext;
19
- /** Optional cache configuration — controls edge and Redis caching per tier. */
20
- cache?: CacheConfig;
21
- /** Optional site configuration — hooks read defaults and formatting from this. */
22
- site?: AugurSiteConfig;
23
- children: ReactNode;
24
- }
25
- /**
26
- * Provides the augur-api SDK instance, proxy options, and auth to all hooks.
27
- *
28
- * ```tsx
29
- * <AugurHooksProvider api={api} auth={authContext} cache={cacheConfig}>
30
- * <App />
31
- * </AugurHooksProvider>
32
- * ```
33
- *
34
- * Components use `useAugurOptions()` to get the proxy:
35
- * ```tsx
36
- * const q = useAugurOptions();
37
- * const { data } = useQuery(q.items.invMast.get(42));
38
- * ```
39
- */
40
- declare function AugurHooksProvider({ api, auth, cache, site, children }: AugurHooksProviderProps): react_jsx_runtime.JSX.Element;
41
- /**
42
- * Returns the deep proxy for creating TanStack Query options.
43
- *
44
- * When an `api` prop is provided to the provider, every path returns
45
- * full query options (queryKey, queryFn, staleTime, gcTime).
46
- *
47
- * When no `api` is provided (server-only JWT sites), returns a keys-only
48
- * proxy — queryKey, staleTime, and gcTime are generated normally, but
49
- * queryFn throws unless overridden. This lets B2B sites use the proxy
50
- * for deterministic keys and cache tiers while routing data through
51
- * server actions.
52
- *
53
- * @example
54
- * ```tsx
55
- * // With api (direct SDK access):
56
- * const q = useAugurOptions();
57
- * const { data } = useQuery(q.items.invMast.get(42));
58
- *
59
- * // Without api (server-only JWT):
60
- * const q = useAugurOptions();
61
- * const { data } = useQuery({
62
- * ...q.items.invMast.doc.get(42),
63
- * queryFn: () => getItemAction(42), // server action
64
- * });
65
- * ```
66
- */
67
- declare function useAugurOptions<T = DeepQueryOptions<AugurAPI>>(): T;
68
- /**
69
- * Returns the augur-api SDK instance from context, or null if not provided.
70
- * Used internally by hooks that need the SDK for fallback queries.
71
- */
72
- declare function useAugurApiOptional(): AugurApiClient | null;
73
- /**
74
- * Returns the augur-api SDK instance from context.
75
- * Throws if called outside of `<AugurHooksProvider>` or when no api is provided.
76
- */
77
- declare function useAugurApi(): AugurApiClient;
78
- /**
79
- * Returns the provider-level auth context, if any.
80
- * Used internally by hooks to fall back to provider auth when
81
- * auth fields are not passed directly as hook parameters.
82
- */
83
- declare function useAugurAuth(): AugurAuthContext | undefined;
84
- /**
85
- * Returns the provider-level cache configuration, if any.
86
- * Used internally by hooks to enable edge/Redis caching.
87
- */
88
- declare function useAugurCache(): CacheConfig | undefined;
89
- /**
90
- * Returns the site configuration from the nearest `AugurHooksProvider`.
91
- * Returns `undefined` when no `site` prop is provided.
92
- */
93
- declare function useAugurSite(): AugurSiteConfig | undefined;
94
-
95
- /**
96
- * Hook-specific types that don't belong in augur-utils or augur-core.
97
- * These describe hook parameters and API response shapes.
98
- */
99
-
100
- /** Parameters for product search queries. */
101
- type PageData = {
102
- categoryIdList?: string;
103
- filters?: [string, string][];
104
- limit: number;
105
- page: number;
106
- offset: number;
107
- q: string;
108
- sortBy: string;
109
- tagslist?: string;
110
- itemCategoryUid?: number;
111
- };
112
-
113
- /** Configuration for React Query localStorage persistence. */
114
- interface PersistenceConfig {
115
- /** localStorage key for the persisted cache. */
116
- key: string;
117
- /** Cache buster string. When changed, persisted data is discarded. In development, defaults to Date.now(). */
118
- buster?: string;
119
- /** Max age of persisted data in ms. Default: 24 hours. */
120
- maxAge?: number;
121
- /** Query key prefixes to persist. Only successful queries whose first key element matches are persisted. */
122
- persistableKeys: string[];
123
- /** Per-key-prefix LRU limits. Queries exceeding the limit are evicted oldest-first by dataUpdatedAt. */
124
- limits?: Record<string, number>;
125
- /** localStorage size threshold in MB before eviction runs. Default: 3. */
126
- maxStorageMB?: number;
127
- /** Write throttle in ms. Default: 1000. */
128
- throttleMs?: number;
129
- }
130
- /** API options for item category queries. */
131
- interface GetItemCategoryApiOptions {
132
- childrenFilter?: string;
133
- childrenLimit?: number;
134
- childrenOffset?: number;
135
- classId5List?: string;
136
- filters?: Record<string, string>;
137
- orderBy?: string;
138
- path?: string;
139
- productCollection?: string;
140
- rootItemCategoryId?: string;
141
- }
142
-
143
- interface BatchQueryConfig<TParam, TData> {
144
- params: TParam[];
145
- queryClient: QueryClient;
146
- /** Build individual cache key for a single param. */
147
- getItemKey: (param: TParam) => readonly unknown[];
148
- /** Build the string key for the result Record from a param. */
149
- getResultKey: (param: TParam) => string;
150
- /** Fetch only uncached items, return keyed Record. */
151
- fetchItems: (uncached: TParam[]) => Promise<Record<string, TData>>;
152
- /** Extract individual cache key from a fetched result entry (for seeding). */
153
- getSeedKey: (resultKey: string, data: TData) => readonly unknown[];
154
- }
155
- /**
156
- * Generic batch query executor.
157
- *
158
- * 1. Checks queryClient cache for each param
159
- * 2. Fetches only uncached items in a single batch call
160
- * 3. Seeds individual cache entries from the response
161
- * 4. Returns merged cached + fetched record
162
- */
163
- declare function executeBatchQuery<TParam, TData>(config: BatchQueryConfig<TParam, TData>): Promise<Record<string, TData>>;
164
-
165
- export { type AugurApiClient as A, type BatchQueryConfig as B, type GetItemCategoryApiOptions as G, type PersistenceConfig as P, AugurHooksProvider as a, type PageData as b, useAugurApiOptional as c, useAugurAuth as d, executeBatchQuery as e, useAugurCache as f, useAugurOptions as g, useAugurSite as h, useAugurApi as u };