@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.
- package/EXPORTS.md +25 -65
- package/README.md +21 -246
- package/dist/checkout/create-checkout-provider.d.ts +25 -0
- package/dist/checkout/create-checkout-provider.d.ts.map +1 -0
- package/dist/checkout/index.cjs +123 -106
- package/dist/checkout/index.cjs.map +1 -1
- package/dist/checkout/index.d.ts +5 -293
- package/dist/checkout/index.d.ts.map +1 -0
- package/dist/checkout/index.js +99 -82
- package/dist/checkout/index.js.map +1 -1
- package/dist/checkout/{index.d.cts → types.d.ts} +18 -40
- package/dist/checkout/types.d.ts.map +1 -0
- package/dist/chunk-6Z6JGK2C.cjs.map +1 -1
- package/dist/chunk-QB7VB5FZ.cjs +523 -0
- package/dist/chunk-QB7VB5FZ.cjs.map +1 -0
- package/dist/{chunk-JNOHB4OP.js → chunk-UTDAFIQP.js} +234 -94
- package/dist/chunk-UTDAFIQP.js.map +1 -0
- package/dist/hooks/use-cart-actions.d.ts +68 -0
- package/dist/hooks/use-cart-actions.d.ts.map +1 -0
- package/dist/hooks/use-cart-initialization.d.ts +60 -0
- package/dist/hooks/use-cart-initialization.d.ts.map +1 -0
- package/dist/hooks/use-cart-pricing.d.ts +41 -0
- package/dist/hooks/use-cart-pricing.d.ts.map +1 -0
- package/dist/hooks/use-checkout-persistence.d.ts +40 -0
- package/dist/hooks/use-checkout-persistence.d.ts.map +1 -0
- package/dist/hooks/use-debounce.d.ts +6 -0
- package/dist/hooks/use-debounce.d.ts.map +1 -0
- package/dist/hooks/use-format-price.d.ts +29 -0
- package/dist/hooks/use-format-price.d.ts.map +1 -0
- package/dist/hooks/use-latest.d.ts +8 -0
- package/dist/hooks/use-latest.d.ts.map +1 -0
- package/dist/hooks/use-modal-lifecycle.d.ts +11 -0
- package/dist/hooks/use-modal-lifecycle.d.ts.map +1 -0
- package/dist/hooks/use-order-readiness.d.ts +47 -0
- package/dist/hooks/use-order-readiness.d.ts.map +1 -0
- package/dist/hooks/use-pagination-prefetch.d.ts +26 -0
- package/dist/hooks/use-pagination-prefetch.d.ts.map +1 -0
- package/dist/{use-order-readiness-DZTIfRzw.d.ts → hooks/use-payment-flow.d.ts} +23 -67
- package/dist/hooks/use-payment-flow.d.ts.map +1 -0
- package/dist/hooks/use-stock.d.ts +32 -0
- package/dist/hooks/use-stock.d.ts.map +1 -0
- package/dist/index.cjs +215 -178
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +32 -456
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +193 -156
- package/dist/index.js.map +1 -1
- package/dist/persistence/apply-limits.d.ts +8 -0
- package/dist/persistence/apply-limits.d.ts.map +1 -0
- package/dist/persistence/create-persister.d.ts +10 -0
- package/dist/persistence/create-persister.d.ts.map +1 -0
- package/dist/persistence/serializer.d.ts +11 -0
- package/dist/persistence/serializer.d.ts.map +1 -0
- package/dist/persistence/use-persistence.d.ts +59 -0
- package/dist/persistence/use-persistence.d.ts.map +1 -0
- package/dist/persistence/use-storage-monitor.d.ts +11 -0
- package/dist/persistence/use-storage-monitor.d.ts.map +1 -0
- package/dist/provider.d.ts +89 -0
- package/dist/provider.d.ts.map +1 -0
- package/dist/queries/batch-query.d.ts +23 -0
- package/dist/queries/batch-query.d.ts.map +1 -0
- package/dist/queries/cache-helper.d.ts +16 -0
- package/dist/queries/cache-helper.d.ts.map +1 -0
- package/dist/queries/index.d.ts +3 -0
- package/dist/queries/index.d.ts.map +1 -0
- package/dist/query-action-registry.d.ts +19 -0
- package/dist/query-action-registry.d.ts.map +1 -0
- package/dist/rules.d.ts +130 -0
- package/dist/rules.d.ts.map +1 -0
- package/dist/server.cjs.map +1 -1
- package/dist/server.d.ts +10 -12
- package/dist/server.d.ts.map +1 -0
- package/dist/stores/cart-store.d.ts +51 -0
- package/dist/stores/cart-store.d.ts.map +1 -0
- package/dist/stores/items-filters-store.d.ts +30 -0
- package/dist/stores/items-filters-store.d.ts.map +1 -0
- package/dist/types.d.ts +48 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/web/use-image-with-fallback.d.ts +16 -0
- package/dist/web/use-image-with-fallback.d.ts.map +1 -0
- package/dist/web/use-mobile-detection.d.ts +28 -0
- package/dist/web/use-mobile-detection.d.ts.map +1 -0
- package/dist/web/use-mobile-optimized-intersection.d.ts +17 -0
- package/dist/web/use-mobile-optimized-intersection.d.ts.map +1 -0
- package/dist/web.cjs.map +1 -1
- package/dist/web.d.ts +4 -60
- package/dist/web.d.ts.map +1 -0
- package/dist/web.js.map +1 -1
- package/llms.txt +76 -54
- package/package.json +25 -14
- package/dist/batch-query-CTlvxSmL.d.cts +0 -165
- package/dist/batch-query-CTlvxSmL.d.ts +0 -165
- package/dist/chunk-F5DUFW57.cjs +0 -383
- package/dist/chunk-F5DUFW57.cjs.map +0 -1
- package/dist/chunk-JNOHB4OP.js.map +0 -1
- package/dist/index.d.cts +0 -456
- package/dist/server.d.cts +0 -44
- package/dist/use-order-readiness-DZTIfRzw.d.cts +0 -137
- package/dist/web.d.cts +0 -60
package/EXPORTS.md
CHANGED
|
@@ -1,9 +1,7 @@
|
|
|
1
1
|
# @simpleapps-com/augur-hooks exports
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
> Auto-generated from built type declarations. Do not edit manually.
|
|
6
|
-
> Regenerate with: `pnpm run generate-exports`
|
|
3
|
+
> Generated from the package's build by `pnpm -C repo/sites/augur-build generate`. Do not edit by hand.
|
|
4
|
+
> Guide: https://augur.build/docs/packages/augur-hooks
|
|
7
5
|
|
|
8
6
|
## `@simpleapps-com/augur-hooks`
|
|
9
7
|
|
|
@@ -11,44 +9,25 @@ Version: 2.2.29
|
|
|
11
9
|
|
|
12
10
|
| Export | Kind | Description |
|
|
13
11
|
|--------|------|-------------|
|
|
14
|
-
| `
|
|
15
|
-
| `AugurHooksProvider` | value | |
|
|
16
|
-
| `AugurSiteConfig` | value | |
|
|
17
|
-
| `AugurSiteDefaults` | value | |
|
|
18
|
-
| `AugurSiteFormatting` | value | |
|
|
19
|
-
| `CacheConfig` | value | |
|
|
20
|
-
| `CacheProvider` | value | |
|
|
21
|
-
| `CacheTierConfig` | value | |
|
|
22
|
-
| `DeepQueryOptions` | value | |
|
|
23
|
-
| `DerivePriceInput` | value | |
|
|
24
|
-
| `DerivedPrice` | value | |
|
|
25
|
-
| `EdgeCacheValue` | value | |
|
|
26
|
-
| `InfiniteScrollPage` | value | |
|
|
27
|
-
| `PersistenceConfig` | value | |
|
|
28
|
-
| `ProxyMutationOptions` | value | |
|
|
29
|
-
| `ProxyQueryOptions` | value | |
|
|
30
|
-
| `ResolveStockInput` | value | |
|
|
31
|
-
| `ResolvedStock` | value | |
|
|
32
|
-
| `SearchSuggestion` | value | |
|
|
33
|
-
| `SearchSuggestionsResponse` | value | |
|
|
12
|
+
| `AugurHooksProvider` | function | Provides the augur-api SDK instance, proxy options, and auth to all hooks. |
|
|
34
13
|
| `clearCheckoutPersistence` | function | Clears all checkout persistence keys from sessionStorage. |
|
|
35
14
|
| `clearFromSession` | function | Removes a checkout persistence key from sessionStorage. |
|
|
36
15
|
| `determineOrderReadiness` | function | Pure function that determines if an order is ready to submit. |
|
|
37
|
-
| `executeBatchQuery` | function |
|
|
16
|
+
| `executeBatchQuery` | function | Generic batch query executor. |
|
|
38
17
|
| `getRegisteredQueryAction` | function | Returns the registered query action, or null if none registered. |
|
|
39
18
|
| `loadFromSession` | function | Loads a value from sessionStorage, checking TTL and optionally validating. |
|
|
40
19
|
| `registerQueryAction` | function | Register a query action function (called by augur-server/hooks.ts on import). |
|
|
41
20
|
| `saveToSession` | function | Saves a value to sessionStorage with a timestamp for TTL expiration. |
|
|
42
|
-
| `useAugurApi` | function |
|
|
43
|
-
| `useAugurApiOptional` |
|
|
44
|
-
| `useAugurAuth` |
|
|
45
|
-
| `useAugurCache` |
|
|
46
|
-
| `useAugurOptions` |
|
|
47
|
-
| `useAugurPersistence` | function | Returns a fully configured `persistOptions` object for use with |
|
|
48
|
-
| `useAugurSite` |
|
|
21
|
+
| `useAugurApi` | function | Returns the augur-api SDK instance from context. Throws if called outside of `<AugurHooksProvider>` or when no api is provided. |
|
|
22
|
+
| `useAugurApiOptional` | function | Returns the augur-api SDK instance from context, or null if not provided. Used internally by hooks that need the SDK for fallback queries. |
|
|
23
|
+
| `useAugurAuth` | function | 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. |
|
|
24
|
+
| `useAugurCache` | function | Returns the provider-level cache configuration, if any. Used internally by hooks to enable edge/Redis caching. |
|
|
25
|
+
| `useAugurOptions` | function | Returns the deep proxy for creating TanStack Query options. |
|
|
26
|
+
| `useAugurPersistence` | function | Returns a fully configured `persistOptions` object for use with `PersistQueryClientProvider` from `@tanstack/react-query-persist-client`. |
|
|
27
|
+
| `useAugurSite` | function | Returns the site configuration from the nearest `AugurHooksProvider`. Returns `undefined` when no `site` prop is provided. |
|
|
49
28
|
| `useCartActions` | function | Optimistic cart actions hook with automatic rollback on failure. |
|
|
50
29
|
| `useCartHdrUid` | const | Select the current cart header UID. |
|
|
51
|
-
| `useCartInitialization` | function | Initialize cart state from session (authenticated) or cookie (guest). |
|
|
30
|
+
| `useCartInitialization` | function | Initialize cart state from session (authenticated) or cookie (guest). Call once in the root layout. |
|
|
52
31
|
| `useCartLineCount` | const | Select the number of distinct line items in the cart. |
|
|
53
32
|
| `useCartLines` | const | Select the current cart line items array. |
|
|
54
33
|
| `useCartPricing` | function | Centralized hook for cart/checkout pricing. |
|
|
@@ -56,24 +35,20 @@ Version: 2.2.29
|
|
|
56
35
|
| `useCartStore` | const | Zustand store for cart state. Prefer the individual selector hooks below for optimal re-renders. |
|
|
57
36
|
| `useCheckoutPersistence` | function | Hook that persists checkout state fields to sessionStorage and restores on mount. |
|
|
58
37
|
| `useClearCart` | const | Get the `clearCart` action (stable reference). |
|
|
59
|
-
| `useDebounce` | function | Debounces a rapidly-changing value. |
|
|
60
|
-
| `useFormatPrice` | function | Hook that returns a price formatter. |
|
|
38
|
+
| `useDebounce` | function | Debounces a rapidly-changing value. Returns the latest value only after `delay` ms of inactivity. |
|
|
39
|
+
| `useFormatPrice` | function | Hook that returns a price formatter. Reads defaults from site config when params are omitted. |
|
|
61
40
|
| `useItemFiltersStore` | const | Zustand store for item list filters, sorting, and pagination state. |
|
|
62
41
|
| `useModalLifecycle` | function | Shared modal lifecycle hook -- scroll lock, Escape key, client-side hydration gate. |
|
|
63
42
|
| `useOrderReadiness` | function | Debounced order readiness hook. |
|
|
64
|
-
| `usePaginationPrefetch` | const | Prefetch adjacent pages on hover for instant pagination. |
|
|
65
|
-
| `usePaymentFlow` | function |
|
|
43
|
+
| `usePaginationPrefetch` | const | Prefetch adjacent pages on hover for instant pagination. Accepts a generic queryFn so it works with any paginated resource. |
|
|
44
|
+
| `usePaymentFlow` | function | Manages the full Element/Unified payment lifecycle: transactionSetup -> cardInfo -> validatePayment -> accountQuery -> billingUpdate |
|
|
66
45
|
| `useSetCartHdrUid` | const | Get the `setCartHdrUid` action (stable reference). |
|
|
67
46
|
| `useSetCartLines` | const | Get the `setCartLines` action (stable reference). Also recomputes totals. |
|
|
68
47
|
| `useStock` | function | Fetches full TStock data and resolves it into a normalized stock object. |
|
|
69
48
|
|
|
70
49
|
### Types
|
|
71
50
|
|
|
72
|
-
`AugurApiClient`, `BatchQueryConfig`, `CartActionCallbacks`, `CartInitCallbacks`, `CartPriceData`, `CartPricingResult`, `CartSessionInfo`, `CheckoutPersistField`, `FormatPriceCallOptions`, `GetItemCategoryApiOptions`, `OrderReadinessParams`, `PageData`, `PaymentBillingAddress`, `PaymentFlowCallbacks`, `UseFormatPriceOptions`, `UseStockOptions`
|
|
73
|
-
|
|
74
|
-
```ts
|
|
75
|
-
import { AugurAuthContext, AugurHooksProvider, AugurSiteConfig } from "@simpleapps-com/augur-hooks";
|
|
76
|
-
```
|
|
51
|
+
`AugurApiClient`, `AugurAuthContext`, `AugurSiteConfig`, `AugurSiteDefaults`, `AugurSiteFormatting`, `BatchQueryConfig`, `CacheConfig`, `CacheProvider`, `CacheTierConfig`, `CartActionCallbacks`, `CartInitCallbacks`, `CartPriceData`, `CartPricingResult`, `CartSessionInfo`, `CheckoutPersistField`, `DeepQueryOptions`, `DerivedPrice`, `DerivePriceInput`, `EdgeCacheValue`, `FormatPriceCallOptions`, `GetItemCategoryApiOptions`, `InfiniteScrollPage`, `OrderReadinessParams`, `PageData`, `PaymentBillingAddress`, `PaymentFlowCallbacks`, `PersistenceConfig`, `ProxyMutationOptions`, `ProxyQueryOptions`, `ResolvedStock`, `ResolveStockInput`, `SearchSuggestion`, `SearchSuggestionsResponse`, `UseFormatPriceOptions`, `UseStockOptions`
|
|
77
52
|
|
|
78
53
|
## `@simpleapps-com/augur-hooks/server`
|
|
79
54
|
|
|
@@ -81,20 +56,13 @@ import { AugurAuthContext, AugurHooksProvider, AugurSiteConfig } from "@simpleap
|
|
|
81
56
|
|
|
82
57
|
| Export | Kind | Description |
|
|
83
58
|
|--------|------|-------------|
|
|
84
|
-
| `AugurAuthContext` | value | |
|
|
85
|
-
| `CacheConfig` | value | |
|
|
86
|
-
| `InfiniteScrollPage` | value | |
|
|
87
59
|
| `createAugurOptions` | function | Creates server-side query options proxy for prefetching. |
|
|
88
|
-
| `executeBatchQuery` | function |
|
|
60
|
+
| `executeBatchQuery` | function | Generic batch query executor. |
|
|
89
61
|
| `getQueryClient` | const | Returns a per-request singleton QueryClient for React Server Components. |
|
|
90
62
|
|
|
91
63
|
### Types
|
|
92
64
|
|
|
93
|
-
`AugurApiClient`, `BatchQueryConfig`, `PageData`
|
|
94
|
-
|
|
95
|
-
```ts
|
|
96
|
-
import { AugurAuthContext, CacheConfig, InfiniteScrollPage } from "@simpleapps-com/augur-hooks/server";
|
|
97
|
-
```
|
|
65
|
+
`AugurApiClient`, `AugurAuthContext`, `BatchQueryConfig`, `CacheConfig`, `InfiniteScrollPage`, `PageData`
|
|
98
66
|
|
|
99
67
|
## `@simpleapps-com/augur-hooks/web`
|
|
100
68
|
|
|
@@ -102,15 +70,11 @@ import { AugurAuthContext, CacheConfig, InfiniteScrollPage } from "@simpleapps-c
|
|
|
102
70
|
|
|
103
71
|
| Export | Kind | Description |
|
|
104
72
|
|--------|------|-------------|
|
|
105
|
-
| `MobileProvider` | function | Optional provider that tracks hydration state. |
|
|
73
|
+
| `MobileProvider` | function | Optional provider that tracks hydration state. Wrap your app with this if you need to conditionally render mobile-only content after hydration. |
|
|
106
74
|
| `useImageWithFallback` | function | Preloads an agr.media image and shows a fallback while loading. |
|
|
107
|
-
| `useIsHydrated` | function | Returns true only after the client has hydrated. |
|
|
108
|
-
| `useIsMobile` | function | Returns whether the screen is mobile-sized. |
|
|
109
|
-
| `useMobileOptimizedIntersection` | const | IntersectionObserver hook with mobile-optimized root margins. |
|
|
110
|
-
|
|
111
|
-
```ts
|
|
112
|
-
import { MobileProvider, useImageWithFallback, useIsHydrated } from "@simpleapps-com/augur-hooks/web";
|
|
113
|
-
```
|
|
75
|
+
| `useIsHydrated` | function | Returns true only after the client has hydrated. Prevents hydration mismatches with conditional rendering. |
|
|
76
|
+
| `useIsMobile` | function | Returns whether the screen is mobile-sized. Uses `useSyncExternalStore` for proper SSR support. |
|
|
77
|
+
| `useMobileOptimizedIntersection` | const | IntersectionObserver hook with mobile-optimized root margins. Uses larger margins on mobile for more aggressive prefetching/lazy loading. |
|
|
114
78
|
|
|
115
79
|
## `@simpleapps-com/augur-hooks/checkout`
|
|
116
80
|
|
|
@@ -118,13 +82,9 @@ import { MobileProvider, useImageWithFallback, useIsHydrated } from "@simpleapps
|
|
|
118
82
|
|
|
119
83
|
| Export | Kind | Description |
|
|
120
84
|
|--------|------|-------------|
|
|
121
|
-
| `ORDER_CONFIRMATION_KEY` | const | sessionStorage key for persisted order confirmation data. |
|
|
122
85
|
| `createCheckoutProvider` | function | |
|
|
86
|
+
| `ORDER_CONFIRMATION_KEY` | const | sessionStorage key for persisted order confirmation data. |
|
|
123
87
|
|
|
124
88
|
### Types
|
|
125
89
|
|
|
126
|
-
`CheckoutAddress`, `CheckoutContext`, `CheckoutContextValue`, `CheckoutIdentityConfig`, `CheckoutLifecycleHooks`, `CheckoutOrderConfig`, `CheckoutPaymentConfig`, `CheckoutPaymentModal`, `CheckoutProviderConfig`, `CheckoutProviderProps`, `CheckoutShippingConfig`, `CheckoutUIConfig`, `DefaultCheckoutStep`, `OrderConfirmation`
|
|
127
|
-
|
|
128
|
-
```ts
|
|
129
|
-
import { ORDER_CONFIRMATION_KEY, createCheckoutProvider } from "@simpleapps-com/augur-hooks/checkout";
|
|
130
|
-
```
|
|
90
|
+
`CheckoutAddress`, `CheckoutContext`, `CheckoutContextValue`, `CheckoutIdentityConfig`, `CheckoutLifecycleHooks`, `CheckoutOrderConfig`, `CheckoutPaymentConfig`, `CheckoutPaymentModal`, `CheckoutProviderConfig`, `CheckoutProviderProps`, `CheckoutShippingConfig`, `CheckoutUIConfig`, `DefaultCheckoutStep`, `OrderConfirmation`, `TCartLine`
|
package/README.md
CHANGED
|
@@ -1,10 +1,13 @@
|
|
|
1
1
|
# @simpleapps-com/augur-hooks
|
|
2
2
|
|
|
3
|
-
> Cross-platform React Query hooks
|
|
3
|
+
> Cross-platform React Query hooks, the options proxy, Zustand stores and the checkout provider for Augur sites
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Part of the **@simpleapps-com/augur-\*** platform. Each package releases on its own CalVer
|
|
6
|
+
version; nothing requires them to share one.
|
|
6
7
|
|
|
7
|
-
|
|
8
|
+
- Guide: https://augur.build/docs/packages/augur-hooks
|
|
9
|
+
- Every export: [`EXPORTS.md`](EXPORTS.md) (generated from the build)
|
|
10
|
+
- Releases: https://augur.build/docs/packages/changelog
|
|
8
11
|
|
|
9
12
|
## Install
|
|
10
13
|
|
|
@@ -12,251 +15,23 @@ Part of the **@simpleapps-com/augur-\*** platform. All packages use fixed versio
|
|
|
12
15
|
pnpm add @simpleapps-com/augur-hooks
|
|
13
16
|
```
|
|
14
17
|
|
|
15
|
-
|
|
18
|
+
| Import | Runs in | Purpose |
|
|
19
|
+
| -------------------------------------- | ----------------- | ------------------------------------------------------------- |
|
|
20
|
+
| `@simpleapps-com/augur-hooks` | Anywhere | Provider, `useAugurOptions`, named hooks, stores, persistence |
|
|
21
|
+
| `@simpleapps-com/augur-hooks/server` | Server components | `getQueryClient`, `createAugurOptions`, `executeBatchQuery` |
|
|
22
|
+
| `@simpleapps-com/augur-hooks/web` | Browser | Mobile detection, hydration, intersection, image fallback |
|
|
23
|
+
| `@simpleapps-com/augur-hooks/checkout` | Browser | `createCheckoutProvider` |
|
|
16
24
|
|
|
17
|
-
|
|
25
|
+
## Development
|
|
18
26
|
|
|
19
|
-
|
|
27
|
+
TypeScript in `src/`, built to `dist/` (ESM and CJS) by tsup. The decisions are proved
|
|
28
|
+
(`src/rules.ts`; model `models/AugurHooks.dfy`, link `models/links/augur-hooks-rules.dfy`); the
|
|
29
|
+
hooks are tested at 100% under jsdom.
|
|
20
30
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
| `@simpleapps-com/augur-hooks/server` | 6 exports, 3 types |
|
|
25
|
-
| `@simpleapps-com/augur-hooks/web` | 5 exports, 0 types |
|
|
26
|
-
| `@simpleapps-com/augur-hooks/checkout` | 2 exports, 14 types |
|
|
27
|
-
|
|
28
|
-
## Exports
|
|
29
|
-
|
|
30
|
-
### Auth & Context
|
|
31
|
-
|
|
32
|
-
| Export | Kind | Description |
|
|
33
|
-
|--------|------|-------------|
|
|
34
|
-
| `AugurAuthContext` | value | |
|
|
35
|
-
| `AugurHooksProvider` | value | |
|
|
36
|
-
| `AugurSiteConfig` | value | |
|
|
37
|
-
| `AugurSiteDefaults` | value | |
|
|
38
|
-
| `AugurSiteFormatting` | value | |
|
|
39
|
-
| `CacheProvider` | value | |
|
|
40
|
-
| `DeepQueryOptions` | value | |
|
|
41
|
-
| `ProxyMutationOptions` | value | |
|
|
42
|
-
| `ProxyQueryOptions` | value | |
|
|
43
|
-
| `clearFromSession` | function | Removes a checkout persistence key from sessionStorage. |
|
|
44
|
-
| `loadFromSession` | function | Loads a value from sessionStorage, checking TTL and optionally validating. |
|
|
45
|
-
| `saveToSession` | function | Saves a value to sessionStorage with a timestamp for TTL expiration. |
|
|
46
|
-
| `useAugurApi` | function | |
|
|
47
|
-
| `useAugurAuth` | value | |
|
|
48
|
-
| `useAugurOptions` | value | |
|
|
49
|
-
| `useAugurSite` | value | |
|
|
50
|
-
| `AugurAuthContext` | value | |
|
|
51
|
-
| `createAugurOptions` | function | Creates server-side query options proxy for prefetching. |
|
|
52
|
-
| `MobileProvider` | function | Optional provider that tracks hydration state. |
|
|
53
|
-
| `createCheckoutProvider` | function | |
|
|
54
|
-
|
|
55
|
-
### Cart
|
|
56
|
-
|
|
57
|
-
| Export | Kind | Description |
|
|
58
|
-
|--------|------|-------------|
|
|
59
|
-
| `useCartActions` | function | Optimistic cart actions hook with automatic rollback on failure. |
|
|
60
|
-
| `useCartHdrUid` | const | Select the current cart header UID. |
|
|
61
|
-
| `useCartInitialization` | function | Initialize cart state from session (authenticated) or cookie (guest). |
|
|
62
|
-
| `useCartLineCount` | const | Select the number of distinct line items in the cart. |
|
|
63
|
-
| `useCartLines` | const | Select the current cart line items array. |
|
|
64
|
-
| `useCartPricing` | function | Centralized hook for cart/checkout pricing. |
|
|
65
|
-
| `useCartQuantityTotal` | const | Select the total quantity summed across all cart lines. |
|
|
66
|
-
| `useCartStore` | const | Zustand store for cart state. Prefer the individual selector hooks below for optimal re-renders. |
|
|
67
|
-
| `useClearCart` | const | Get the `clearCart` action (stable reference). |
|
|
68
|
-
| `useSetCartHdrUid` | const | Get the `setCartHdrUid` action (stable reference). |
|
|
69
|
-
| `useSetCartLines` | const | Get the `setCartLines` action (stable reference). Also recomputes totals. |
|
|
70
|
-
|
|
71
|
-
### Configuration
|
|
72
|
-
|
|
73
|
-
| Export | Kind | Description |
|
|
74
|
-
|--------|------|-------------|
|
|
75
|
-
| `CacheConfig` | value | |
|
|
76
|
-
| `CacheTierConfig` | value | |
|
|
77
|
-
| `CacheConfig` | value | |
|
|
78
|
-
|
|
79
|
-
### Image & CDN
|
|
80
|
-
|
|
81
|
-
| Export | Kind | Description |
|
|
82
|
-
|--------|------|-------------|
|
|
83
|
-
| `useImageWithFallback` | function | Preloads an agr.media image and shows a fallback while loading. |
|
|
84
|
-
|
|
85
|
-
### Items & Categories
|
|
86
|
-
|
|
87
|
-
| Export | Kind | Description |
|
|
88
|
-
|--------|------|-------------|
|
|
89
|
-
| `useItemFiltersStore` | const | Zustand store for item list filters, sorting, and pagination state. |
|
|
90
|
-
|
|
91
|
-
### Orders
|
|
92
|
-
|
|
93
|
-
| Export | Kind | Description |
|
|
94
|
-
|--------|------|-------------|
|
|
95
|
-
| `determineOrderReadiness` | function | Pure function that determines if an order is ready to submit. |
|
|
96
|
-
| `useOrderReadiness` | function | Debounced order readiness hook. |
|
|
97
|
-
| `ORDER_CONFIRMATION_KEY` | const | sessionStorage key for persisted order confirmation data. |
|
|
98
|
-
|
|
99
|
-
### Payment & Checkout
|
|
100
|
-
|
|
101
|
-
| Export | Kind | Description |
|
|
102
|
-
|--------|------|-------------|
|
|
103
|
-
| `clearCheckoutPersistence` | function | Clears all checkout persistence keys from sessionStorage. |
|
|
104
|
-
| `useCheckoutPersistence` | function | Hook that persists checkout state fields to sessionStorage and restores on mount. |
|
|
105
|
-
| `usePaymentFlow` | function | |
|
|
106
|
-
|
|
107
|
-
### Persistence
|
|
108
|
-
|
|
109
|
-
| Export | Kind | Description |
|
|
110
|
-
|--------|------|-------------|
|
|
111
|
-
| `PersistenceConfig` | value | |
|
|
112
|
-
| `useAugurPersistence` | function | Returns a fully configured `persistOptions` object for use with |
|
|
113
|
-
|
|
114
|
-
### Pricing
|
|
115
|
-
|
|
116
|
-
| Export | Kind | Description |
|
|
117
|
-
|--------|------|-------------|
|
|
118
|
-
| `DerivePriceInput` | value | |
|
|
119
|
-
| `DerivedPrice` | value | |
|
|
120
|
-
| `useFormatPrice` | function | Hook that returns a price formatter. |
|
|
121
|
-
|
|
122
|
-
### Search
|
|
123
|
-
|
|
124
|
-
| Export | Kind | Description |
|
|
125
|
-
|--------|------|-------------|
|
|
126
|
-
| `SearchSuggestion` | value | |
|
|
127
|
-
| `SearchSuggestionsResponse` | value | |
|
|
128
|
-
|
|
129
|
-
### Stock
|
|
130
|
-
|
|
131
|
-
| Export | Kind | Description |
|
|
132
|
-
|--------|------|-------------|
|
|
133
|
-
| `ResolveStockInput` | value | |
|
|
134
|
-
| `ResolvedStock` | value | |
|
|
135
|
-
| `useStock` | function | Fetches full TStock data and resolves it into a normalized stock object. |
|
|
136
|
-
|
|
137
|
-
### Utilities
|
|
138
|
-
|
|
139
|
-
| Export | Kind | Description |
|
|
140
|
-
|--------|------|-------------|
|
|
141
|
-
| `useDebounce` | function | Debounces a rapidly-changing value. |
|
|
142
|
-
| `useIsHydrated` | function | Returns true only after the client has hydrated. |
|
|
143
|
-
| `useIsMobile` | function | Returns whether the screen is mobile-sized. |
|
|
144
|
-
| `useMobileOptimizedIntersection` | const | IntersectionObserver hook with mobile-optimized root margins. |
|
|
145
|
-
|
|
146
|
-
### Other
|
|
147
|
-
|
|
148
|
-
| Export | Kind | Description |
|
|
149
|
-
|--------|------|-------------|
|
|
150
|
-
| `EdgeCacheValue` | value | |
|
|
151
|
-
| `InfiniteScrollPage` | value | |
|
|
152
|
-
| `executeBatchQuery` | function | |
|
|
153
|
-
| `getRegisteredQueryAction` | function | Returns the registered query action, or null if none registered. |
|
|
154
|
-
| `registerQueryAction` | function | Register a query action function (called by augur-server/hooks.ts on import). |
|
|
155
|
-
| `useAugurApiOptional` | value | |
|
|
156
|
-
| `useAugurCache` | value | |
|
|
157
|
-
| `useModalLifecycle` | function | Shared modal lifecycle hook -- scroll lock, Escape key, client-side hydration gate. |
|
|
158
|
-
| `usePaginationPrefetch` | const | Prefetch adjacent pages on hover for instant pagination. |
|
|
159
|
-
| `InfiniteScrollPage` | value | |
|
|
160
|
-
| `executeBatchQuery` | function | |
|
|
161
|
-
| `getQueryClient` | const | Returns a per-request singleton QueryClient for React Server Components. |
|
|
162
|
-
|
|
163
|
-
## Examples
|
|
164
|
-
|
|
165
|
-
### useAugurPersistence
|
|
166
|
-
|
|
167
|
-
```tsx
|
|
168
|
-
import { useAugurPersistence } from "@simpleapps-com/augur-hooks";
|
|
169
|
-
|
|
170
|
-
function Providers({ children }) {
|
|
171
|
-
const [queryClient] = useState(() => new QueryClient({ ... }));
|
|
172
|
-
const persistOptions = useAugurPersistence({
|
|
173
|
-
key: "my-site-cache",
|
|
174
|
-
buster: "1.0.0",
|
|
175
|
-
persistableKeys: ["price", "categories", "invMast"],
|
|
176
|
-
limits: { invMast: 100 },
|
|
177
|
-
});
|
|
178
|
-
|
|
179
|
-
return (
|
|
180
|
-
<PersistQueryClientProvider client={queryClient} persistOptions={persistOptions}>
|
|
181
|
-
<augur.Provider api={api} auth={auth}>
|
|
182
|
-
{children}
|
|
183
|
-
</augur.Provider>
|
|
184
|
-
</PersistQueryClientProvider>
|
|
185
|
-
);
|
|
186
|
-
}
|
|
187
|
-
```
|
|
188
|
-
|
|
189
|
-
### useCartActions
|
|
190
|
-
|
|
191
|
-
```tsx
|
|
192
|
-
import { useCartActions } from "@simpleapps-com/augur-hooks";
|
|
193
|
-
import { addToCart, updateCartLines, deleteItemsFromCart } from "@/lib/actions/commerce";
|
|
194
|
-
import { toast } from "react-toastify";
|
|
195
|
-
|
|
196
|
-
const cart = useCartActions({
|
|
197
|
-
addToCart, updateCartLines, deleteItemsFromCart,
|
|
198
|
-
toast: { info: toast.info, error: toast.error },
|
|
199
|
-
});
|
|
200
|
-
|
|
201
|
-
await cart.addToCart({ invMastUid: 123, quantity: 1, unitOfMeasure: "EA" });
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
### useCartInitialization
|
|
205
|
-
|
|
206
|
-
```tsx
|
|
207
|
-
import { useCartInitialization } from "@simpleapps-com/augur-hooks";
|
|
208
|
-
import { useSession } from "next-auth/react";
|
|
209
|
-
import { cartHdrLookup, getCartLines } from "@/lib/actions/commerce";
|
|
210
|
-
|
|
211
|
-
function CartInitializer() {
|
|
212
|
-
const { data: session, status } = useSession();
|
|
213
|
-
|
|
214
|
-
// Minimal setup — token storage defaults to localStorage,
|
|
215
|
-
// token generation defaults to crypto.randomUUID().
|
|
216
|
-
useCartInitialization(
|
|
217
|
-
{
|
|
218
|
-
status,
|
|
219
|
-
userId: session?.user?.id,
|
|
220
|
-
cartHdrUid: session?.user?.cartHdrUid,
|
|
221
|
-
},
|
|
222
|
-
{ cartHdrLookup, getCartLines },
|
|
223
|
-
);
|
|
224
|
-
|
|
225
|
-
return null;
|
|
226
|
-
}
|
|
227
|
-
```
|
|
228
|
-
|
|
229
|
-
### createAugurOptions
|
|
230
|
-
|
|
231
|
-
```ts
|
|
232
|
-
// With SDK client (traditional)
|
|
233
|
-
const q = createAugurOptions(site.client, cacheConfig);
|
|
234
|
-
|
|
235
|
-
// With queryAction (server-only JWT sites)
|
|
236
|
-
import { queryAction } from "@simpleapps-com/augur-server/query-action";
|
|
237
|
-
const q = createAugurOptions(queryAction, cacheConfig);
|
|
238
|
-
|
|
239
|
-
// With auto-registered queryAction (zero args -- requires augur-server/hooks import)
|
|
240
|
-
const q = createAugurOptions();
|
|
241
|
-
|
|
242
|
-
await queryClient.prefetchQuery(q.items.invMast.doc.get(42));
|
|
31
|
+
```bash
|
|
32
|
+
pnpm -C repo/packages/augur-hooks test
|
|
33
|
+
pnpm -C repo/packages/augur-hooks proofs
|
|
243
34
|
```
|
|
244
35
|
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
`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`
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
## Related Packages
|
|
251
|
-
|
|
252
|
-
All packages use fixed versioning -- same version number across the platform.
|
|
253
|
-
|
|
254
|
-
| Package | Description |
|
|
255
|
-
|---------|-------------|
|
|
256
|
-
| `@simpleapps-com/augur-config` | Shared tooling configuration presets for Augur ecommerce sites |
|
|
257
|
-
| `@simpleapps-com/augur-core` | Universal foundation for Augur packages — proxy infrastructure, cache keys, method classification, shared types |
|
|
258
|
-
| `@simpleapps-com/augur-mobile` | React Native/Expo adapters for Augur ecommerce apps (offline sync, biometrics, push) |
|
|
259
|
-
| `@simpleapps-com/augur-server` | Server-side utilities for Augur ecommerce sites (Redis caching, SDK helpers, auth) |
|
|
260
|
-
| `@simpleapps-com/augur-tailwind` | Shared Tailwind CSS v4 theme with HSL variables for Augur ecommerce sites |
|
|
261
|
-
| `@simpleapps-com/augur-utils` | Shared types, cache configuration, and utility functions for Augur ecommerce sites |
|
|
262
|
-
| `@simpleapps-com/augur-web` | Shared React UI components for Augur ecommerce sites (Radix + Tailwind) |
|
|
36
|
+
A change to its exports MUST come with `pnpm -C repo/sites/augur-build generate` (the drift
|
|
37
|
+
test fails otherwise), and the guide changes in the same PR.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import { type ReactElement } from "react";
|
|
2
|
+
import type { PaymentFlowCallbacks } from "../hooks/use-payment-flow";
|
|
3
|
+
import type { CheckoutAddress, CheckoutContextValue, CheckoutProviderConfig, CheckoutProviderProps } from "./types";
|
|
4
|
+
/** sessionStorage key for persisted order confirmation data. */
|
|
5
|
+
export declare const ORDER_CONFIRMATION_KEY = "orderConfirmation";
|
|
6
|
+
/** Shape of persisted order confirmation data. */
|
|
7
|
+
export interface OrderConfirmation {
|
|
8
|
+
orderData: Record<string, unknown>;
|
|
9
|
+
result: unknown;
|
|
10
|
+
shippingAddress: CheckoutAddress | undefined;
|
|
11
|
+
billingAddress: CheckoutAddress | undefined;
|
|
12
|
+
shippingFee: number | undefined;
|
|
13
|
+
shippingMethod: string | undefined;
|
|
14
|
+
taxRate: number | undefined;
|
|
15
|
+
paymentMethod: string;
|
|
16
|
+
carrierId: string;
|
|
17
|
+
orderCartLines: unknown[] | undefined;
|
|
18
|
+
}
|
|
19
|
+
/** No-op callbacks for when payment is not configured. Each resolves to undefined. */
|
|
20
|
+
export declare const NOOP_PAYMENT_CALLBACKS: PaymentFlowCallbacks;
|
|
21
|
+
export declare function createCheckoutProvider<TCustom extends Record<string, unknown> = Record<string, never>>(config: CheckoutProviderConfig<TCustom>): {
|
|
22
|
+
CheckoutProvider: ({ children, identity: propsIdentity, }: CheckoutProviderProps) => ReactElement;
|
|
23
|
+
useCheckout: () => CheckoutContextValue<TCustom>;
|
|
24
|
+
};
|
|
25
|
+
//# sourceMappingURL=create-checkout-provider.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"create-checkout-provider.d.ts","sourceRoot":"","sources":["../../src/checkout/create-checkout-provider.tsx"],"names":[],"mappings":"AAEA,OAAc,EAOZ,KAAK,YAAY,EAClB,MAAM,OAAO,CAAC;AAGf,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AActE,OAAO,KAAK,EACV,eAAe,EACf,oBAAoB,EAGpB,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAEjB,gEAAgE;AAChE,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAsM1D,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,MAAM,EAAE,OAAO,CAAC;IAChB,eAAe,EAAE,eAAe,GAAG,SAAS,CAAC;IAC7C,cAAc,EAAE,eAAe,GAAG,SAAS,CAAC;IAC5C,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,OAAO,EAAE,GAAG,SAAS,CAAC;CACvC;AAuJD,sFAAsF;AACtF,eAAO,MAAM,sBAAsB,EAAE,oBAMpC,CAAC;AA2DF,wBAAgB,sBAAsB,CACpC,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAC/D,MAAM,EAAE,sBAAsB,CAAC,OAAO,CAAC;+DAOpC,qBAAqB,KAAG,YAAY;uBAkTf,oBAAoB,CAAC,OAAO,CAAC;EAStD"}
|