@simpleapps-com/augur-hooks 2.2.10 → 2.2.11

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.
package/EXPORTS.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @simpleapps-com/augur-hooks exports
2
2
 
3
- Version: 2.0.21
3
+ Version: 2.2.10
4
4
 
5
5
  > Auto-generated from built type declarations. Do not edit manually.
6
6
  > Regenerate with: `pnpm run generate-exports`
@@ -33,10 +33,10 @@ Version: 2.0.21
33
33
  | `SearchSuggestionsResponse` | value | |
34
34
  | `executeBatchQuery` | function | |
35
35
  | `getCartPricingQueryOptions` | function | |
36
- | `getRegisteredQueryAction` | function | Returns the registered query action function or null |
36
+ | `getRegisteredQueryAction` | function | Returns the registered query action, or null if none registered. |
37
37
  | `getStockKey` | value | |
38
38
  | `getStockOptions` | value | |
39
- | `registerQueryAction` | function | Registers a query action function for auto-detection by the provider and hooks |
39
+ | `registerQueryAction` | function | Register a query action function (called by augur-server/hooks.ts on import). |
40
40
  | `useAugurApi` | function | |
41
41
  | `useAugurApiOptional` | value | |
42
42
  | `useAugurAuth` | value | |
package/README.md ADDED
@@ -0,0 +1,267 @@
1
+ # @simpleapps-com/augur-hooks
2
+
3
+ > Cross-platform React Query hooks and Zustand stores for Augur ecommerce sites
4
+
5
+ > Auto-generated. Do not edit manually. Regenerate with: `pnpm run generate-exports`
6
+
7
+ Part of the **@simpleapps-com/augur-\*** platform. All packages use fixed versioning (same version number).
8
+
9
+ ## Install
10
+
11
+ ```bash
12
+ pnpm add @simpleapps-com/augur-hooks
13
+ ```
14
+
15
+ ### Peer Dependencies
16
+
17
+ `@simpleapps-com/augur-api`, `@tanstack/react-query`, `@tanstack/react-query-persist-client`, `react`, `zustand`
18
+
19
+ ## Entry Points
20
+
21
+ | Import | Description |
22
+ |--------|-------------|
23
+ | `@simpleapps-com/augur-hooks` | 50 exports, 14 types |
24
+ | `@simpleapps-com/augur-hooks/server` | 9 exports, 3 types |
25
+ | `@simpleapps-com/augur-hooks/web` | 5 exports, 0 types |
26
+
27
+ ## Exports
28
+
29
+ ### Auth & Context
30
+
31
+ | Export | Kind | Description |
32
+ |--------|------|-------------|
33
+ | `AugurAuthContext` | value | |
34
+ | `AugurHooksProvider` | value | |
35
+ | `AugurSiteConfig` | value | |
36
+ | `AugurSiteDefaults` | value | |
37
+ | `AugurSiteFormatting` | value | |
38
+ | `CacheProvider` | value | |
39
+ | `DeepQueryOptions` | value | |
40
+ | `ProxyMutationOptions` | value | |
41
+ | `ProxyQueryOptions` | value | |
42
+ | `useAugurApi` | function | |
43
+ | `useAugurAuth` | value | |
44
+ | `useAugurOptions` | value | |
45
+ | `useAugurSite` | value | |
46
+ | `AugurAuthContext` | value | |
47
+ | `createAugurOptions` | function | Creates server-side query options proxy for prefetching. |
48
+ | `MobileProvider` | function | Optional provider that tracks hydration state. |
49
+
50
+ ### Cart
51
+
52
+ | Export | Kind | Description |
53
+ |--------|------|-------------|
54
+ | `getCartPricingQueryOptions` | function | |
55
+ | `useCartActions` | function | Optimistic cart actions hook with automatic rollback on failure. |
56
+ | `useCartHdrUid` | const | Select the current cart header UID. |
57
+ | `useCartInitialization` | function | Initialize cart state from session (authenticated) or cookie (guest). |
58
+ | `useCartLineCount` | const | Select the number of distinct line items in the cart. |
59
+ | `useCartLines` | const | Select the current cart line items array. |
60
+ | `useCartPricing` | function | Centralized hook for cart/checkout pricing. |
61
+ | `useCartQuantityTotal` | const | Select the total quantity summed across all cart lines. |
62
+ | `useCartStore` | const | Zustand store for cart state. Prefer the individual selector hooks below for optimal re-renders. |
63
+ | `useClearCart` | const | Get the `clearCart` action (stable reference). |
64
+ | `useSetCartHdrUid` | const | Get the `setCartHdrUid` action (stable reference). |
65
+ | `useSetCartLines` | const | Get the `setCartLines` action (stable reference). Also recomputes totals. |
66
+ | `getCartPricingQueryOptions` | function | |
67
+
68
+ ### Configuration
69
+
70
+ | Export | Kind | Description |
71
+ |--------|------|-------------|
72
+ | `CacheConfig` | value | |
73
+ | `CacheTierConfig` | value | |
74
+ | `CacheConfig` | value | |
75
+
76
+ ### Image & CDN
77
+
78
+ | Export | Kind | Description |
79
+ |--------|------|-------------|
80
+ | `useImageWithFallback` | function | Preloads an agr.media image and shows a fallback while loading. |
81
+
82
+ ### Items & Categories
83
+
84
+ | Export | Kind | Description |
85
+ |--------|------|-------------|
86
+ | `useItemFiltersStore` | const | Zustand store for item list filters, sorting, and pagination state. |
87
+
88
+ ### Payment & Checkout
89
+
90
+ | Export | Kind | Description |
91
+ |--------|------|-------------|
92
+ | `usePaymentFlow` | function | Manages the full Element/Unified payment lifecycle: |
93
+
94
+ ### Persistence
95
+
96
+ | Export | Kind | Description |
97
+ |--------|------|-------------|
98
+ | `PersistenceConfig` | value | |
99
+ | `useAugurPersistence` | function | Returns a fully configured `persistOptions` object for use with |
100
+
101
+ ### Pricing
102
+
103
+ | Export | Kind | Description |
104
+ |--------|------|-------------|
105
+ | `DerivePriceInput` | value | |
106
+ | `DerivedPrice` | value | |
107
+ | `useFormatPrice` | function | Hook that returns a price formatter. |
108
+
109
+ ### Search
110
+
111
+ | Export | Kind | Description |
112
+ |--------|------|-------------|
113
+ | `SearchSuggestion` | value | |
114
+ | `SearchSuggestionsResponse` | value | |
115
+
116
+ ### Stock
117
+
118
+ | Export | Kind | Description |
119
+ |--------|------|-------------|
120
+ | `ResolveStockInput` | value | |
121
+ | `ResolvedStock` | value | |
122
+ | `getStockKey` | value | |
123
+ | `getStockOptions` | value | |
124
+ | `useStock` | function | Fetches full TStock data and resolves it into a normalized stock object. |
125
+ | `getStockKey` | value | |
126
+ | `getStockOptions` | value | |
127
+
128
+ ### Utilities
129
+
130
+ | Export | Kind | Description |
131
+ |--------|------|-------------|
132
+ | `useDebounce` | function | Debounces a rapidly-changing value. |
133
+ | `useIsHydrated` | function | Returns true only after the client has hydrated. |
134
+ | `useIsMobile` | function | Returns whether the screen is mobile-sized. |
135
+ | `useMobileOptimizedIntersection` | const | IntersectionObserver hook with mobile-optimized root margins. |
136
+
137
+ ### Other
138
+
139
+ | Export | Kind | Description |
140
+ |--------|------|-------------|
141
+ | `EdgeCacheValue` | value | |
142
+ | `InfiniteScrollPage` | value | |
143
+ | `executeBatchQuery` | function | |
144
+ | `getRegisteredQueryAction` | function | Returns the registered query action, or null if none registered. |
145
+ | `registerQueryAction` | function | Register a query action function (called by augur-server/hooks.ts on import). |
146
+ | `useAugurApiOptional` | value | |
147
+ | `useAugurCache` | value | |
148
+ | `usePaginationPrefetch` | const | Prefetch adjacent pages on hover for instant pagination. |
149
+ | `InfiniteScrollPage` | value | |
150
+ | `executeBatchQuery` | function | |
151
+ | `getQueryClient` | const | Returns a per-request singleton QueryClient for React Server Components. |
152
+
153
+ ## Examples
154
+
155
+ ### useAugurPersistence
156
+
157
+ ```tsx
158
+ import { useAugurPersistence } from "@simpleapps-com/augur-hooks";
159
+
160
+ function Providers({ children }) {
161
+ const [queryClient] = useState(() => new QueryClient({ ... }));
162
+ const persistOptions = useAugurPersistence({
163
+ key: "my-site-cache",
164
+ buster: "1.0.0",
165
+ persistableKeys: ["price", "categories", "invMast"],
166
+ limits: { invMast: 100 },
167
+ });
168
+
169
+ return (
170
+ <PersistQueryClientProvider client={queryClient} persistOptions={persistOptions}>
171
+ <augur.Provider api={api} auth={auth}>
172
+ {children}
173
+ </augur.Provider>
174
+ </PersistQueryClientProvider>
175
+ );
176
+ }
177
+ ```
178
+
179
+ ### useCartActions
180
+
181
+ ```tsx
182
+ import { useCartActions } from "@simpleapps-com/augur-hooks";
183
+ import { addToCart, updateCartLines, deleteItemsFromCart } from "@/lib/actions/commerce";
184
+ import { toast } from "react-toastify";
185
+
186
+ const cart = useCartActions({
187
+ addToCart, updateCartLines, deleteItemsFromCart,
188
+ toast: { info: toast.info, error: toast.error },
189
+ });
190
+
191
+ await cart.addToCart({ invMastUid: 123, quantity: 1, unitOfMeasure: "EA" });
192
+ ```
193
+
194
+ ### useCartInitialization
195
+
196
+ ```tsx
197
+ import { useCartInitialization } from "@simpleapps-com/augur-hooks";
198
+ import { useSession } from "next-auth/react";
199
+ import { cartHdrLookup, getCartLines } from "@/lib/actions/commerce";
200
+
201
+ function CartInitializer() {
202
+ const { data: session, status } = useSession();
203
+
204
+ // Minimal setup — token storage defaults to localStorage,
205
+ // token generation defaults to crypto.randomUUID().
206
+ useCartInitialization(
207
+ {
208
+ status,
209
+ userId: session?.user?.id,
210
+ cartHdrUid: session?.user?.cartHdrUid,
211
+ },
212
+ { cartHdrLookup, getCartLines },
213
+ );
214
+
215
+ return null;
216
+ }
217
+ ```
218
+
219
+ ### usePaymentFlow
220
+
221
+ ```tsx
222
+ import { usePaymentFlow } from "@simpleapps-com/augur-hooks";
223
+ import { transactionSetup, cardInfo, validatePayment, accountQuery, billingUpdate } from "@/lib/actions/payments";
224
+
225
+ const payment = usePaymentFlow({
226
+ callbacks: { transactionSetup, cardInfo, validatePayment, accountQuery, billingUpdate },
227
+ customerId,
228
+ billingAddress,
229
+ paymentMethod: "credit-card",
230
+ shippingAccepted: true,
231
+ });
232
+ ```
233
+
234
+ ### createAugurOptions
235
+
236
+ ```ts
237
+ // With SDK client (traditional)
238
+ const q = createAugurOptions(site.client, cacheConfig);
239
+
240
+ // With queryAction (server-only JWT sites)
241
+ import { queryAction } from "@simpleapps-com/augur-server/query-action";
242
+ const q = createAugurOptions(queryAction, cacheConfig);
243
+
244
+ // With auto-registered queryAction (zero args -- requires augur-server/hooks import)
245
+ const q = createAugurOptions();
246
+
247
+ await queryClient.prefetchQuery(q.items.invMast.doc.get(42));
248
+ ```
249
+
250
+ ## Types
251
+
252
+ `AugurApiClient`, `BatchQueryConfig`, `CartActionCallbacks`, `CartInitCallbacks`, `CartPriceData`, `CartPricingResult`, `CartSessionInfo`, `FormatPriceCallOptions`, `GetItemCategoryApiOptions`, `PageData`, `PaymentBillingAddress`, `PaymentFlowCallbacks`, `UseFormatPriceOptions`, `UseStockOptions`, `AugurApiClient`, `BatchQueryConfig`, `PageData`
253
+
254
+
255
+ ## Related Packages
256
+
257
+ All packages use fixed versioning -- same version number across the platform.
258
+
259
+ | Package | Description |
260
+ |---------|-------------|
261
+ | `@simpleapps-com/augur-config` | Shared tooling configuration presets for Augur ecommerce sites |
262
+ | `@simpleapps-com/augur-core` | Universal foundation for Augur packages — proxy infrastructure, cache keys, method classification, shared types |
263
+ | `@simpleapps-com/augur-mobile` | React Native/Expo adapters for Augur ecommerce apps (offline sync, biometrics, push) |
264
+ | `@simpleapps-com/augur-server` | Server-side utilities for Augur ecommerce sites (Redis caching, SDK helpers, auth) |
265
+ | `@simpleapps-com/augur-tailwind` | Shared Tailwind CSS v4 theme with HSL variables for Augur ecommerce sites |
266
+ | `@simpleapps-com/augur-utils` | Shared types, cache configuration, and utility functions for Augur ecommerce sites |
267
+ | `@simpleapps-com/augur-web` | Shared React UI components for Augur ecommerce sites (Radix + Tailwind) |
@@ -1,8 +1,9 @@
1
1
  import { TStock, TPriceData } from '@simpleapps-com/augur-utils';
2
- import { AugurAuthContext, CacheConfig, AugurSiteConfig } from '@simpleapps-com/augur-core';
2
+ import { AugurAuthContext, CacheConfig, AugurSiteConfig, DeepQueryOptions } from '@simpleapps-com/augur-core';
3
3
  import { QueryClient } from '@tanstack/react-query';
4
4
  import * as react_jsx_runtime from 'react/jsx-runtime';
5
5
  import { ReactNode } from 'react';
6
+ import { AugurAPI } from '@simpleapps-com/augur-api';
6
7
 
7
8
  /**
8
9
  * Minimal type for the augur-api SDK instance.
@@ -64,7 +65,7 @@ declare function AugurHooksProvider({ api, auth, cache, site, children }: AugurH
64
65
  * });
65
66
  * ```
66
67
  */
67
- declare function useAugurOptions<T = unknown>(): T;
68
+ declare function useAugurOptions<T = DeepQueryOptions<AugurAPI>>(): T;
68
69
  /**
69
70
  * Returns the augur-api SDK instance from context, or null if not provided.
70
71
  * Used internally by hooks that need the SDK for fallback queries.
@@ -1,8 +1,9 @@
1
1
  import { TStock, TPriceData } from '@simpleapps-com/augur-utils';
2
- import { AugurAuthContext, CacheConfig, AugurSiteConfig } from '@simpleapps-com/augur-core';
2
+ import { AugurAuthContext, CacheConfig, AugurSiteConfig, DeepQueryOptions } from '@simpleapps-com/augur-core';
3
3
  import { QueryClient } from '@tanstack/react-query';
4
4
  import * as react_jsx_runtime from 'react/jsx-runtime';
5
5
  import { ReactNode } from 'react';
6
+ import { AugurAPI } from '@simpleapps-com/augur-api';
6
7
 
7
8
  /**
8
9
  * Minimal type for the augur-api SDK instance.
@@ -64,7 +65,7 @@ declare function AugurHooksProvider({ api, auth, cache, site, children }: AugurH
64
65
  * });
65
66
  * ```
66
67
  */
67
- declare function useAugurOptions<T = unknown>(): T;
68
+ declare function useAugurOptions<T = DeepQueryOptions<AugurAPI>>(): T;
68
69
  /**
69
70
  * Returns the augur-api SDK instance from context, or null if not provided.
70
71
  * Used internally by hooks that need the SDK for fallback queries.