@simpleapps-com/augur-utils 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-utils 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`
@@ -40,9 +40,12 @@ Version: 2.0.21
40
40
  | `getShippingLeadDate` | function | Get shipping lead date estimate based on days string. |
41
41
  | `isAddressDifferent` | function | Compares a user-entered address with a SmartyStreets-validated address. |
42
42
  | `normalizePath` | function | Normalizes an image path by: |
43
+ | `paginateOffset` | function | Returns a copy of filters with offset adjusted for the given page. |
43
44
  | `pushTrackingData` | function | Push ecommerce tracking data to window.dataLayer using the GA4 clear-then-push pattern. |
44
45
  | `resolveStock` | function | Pure stock resolution -- usable in hooks AND server components. |
45
46
  | `sanitizeHtmlImages` | function | Rewrites `<img src="...">` attributes in an HTML string to use agr.media URLs. |
47
+ | `serializeCategoryFilters` | function | Converts TItemsFilters to the SDK params shape for category item endpoints. |
48
+ | `serializeSearchParams` | function | Converts TItemsFilters to the SDK params shape for search endpoints. |
46
49
  | `serializeTransforms` | function | Serializes transform options into the CDN path segment. |
47
50
  | `trackAddToCart` | function | Track add_to_cart event to Google Analytics dataLayer. |
48
51
  | `trackViewItem` | function | Track view_item event to Google Analytics dataLayer. |
@@ -52,7 +55,7 @@ Version: 2.0.21
52
55
 
53
56
  ### Types
54
57
 
55
- `AddToCartEventParams`, `BillingAddress`, `BreadcrumbJsonLdItem`, `BuildTrackingDataInput`, `CacheTier`, `CheckoutInput`, `CheckoutPayment`, `CustomerDocument`, `DerivePriceInput`, `DerivedPrice`, `ImageConfig`, `ImageTransforms`, `ImageUrlOptions`, `MenuItem`, `OeHdr`, `OeLine`, `OrderHeader`, `OrderLine`, `OrderNote`, `OrderPayment`, `PaymentStatus`, `PaymentStatusInvoice`, `ProductJsonLdAggregateRating`, `ProductJsonLdOptions`, `ProductJsonLdSeller`, `ResolveStockInput`, `ResolvedStock`, `SafeActionResult`, `SchemaAvailability`, `ShipToAddress`, `ShippingAddress`, `TAccountQuery`, `TApiResponse`, `TAttribute`, `TAttributeValue`, `TBillingUpdate`, `TCardInfo`, `TCartHdrUid`, `TCartLine`, `TCartLookUp`, `TCategory`, `TCategoryChild`, `TCategoryItemsResult`, `TCheckoutResult`, `TInvMast`, `TInvMastDoc`, `TInventorySupplier`, `TItemAccessory`, `TItemAttribute`, `TItemAttributes`, `TItemCategory`, `TItemDetails`, `TItemRelatedProduct`, `TItemUom`, `TItemsFilters`, `TJoomlaContent`, `TJoomlaContentFilters`, `TLibraryPriceBreak`, `TLibraryPriceData`, `TLtlRatesResponse`, `TLtlShipmentData`, `TMenu`, `TMenuFilters`, `TMetaTags`, `TOrderCartLine`, `TPasswordVerification`, `TPaymentValidation`, `TPriceData`, `TProductCategory`, `TProductItem`, `TProductStockData`, `TProfileValues`, `TRelatedProduct`, `TSearchSuggestion`, `TSearchSuggestionsResponse`, `TShippingMethod`, `TSmartyStreets`, `TStock`, `TStockData`, `TSurcharge`, `TTax`, `TTaxItem`, `TTransactionSetup`, `TUserProfile`, `TWebDesc`, `TrackingData`, `TrackingItem`, `USStateCode`, `UserAddress`, `ViewItemEventParams`
58
+ `AddToCartEventParams`, `BillingAddress`, `BreadcrumbJsonLdItem`, `BuildTrackingDataInput`, `CacheTier`, `CategoryFilterOptions`, `CheckoutInput`, `CheckoutPayment`, `CustomerDocument`, `DerivePriceInput`, `DerivedPrice`, `ImageConfig`, `ImageTransforms`, `ImageUrlOptions`, `MenuItem`, `OeHdr`, `OeLine`, `OrderHeader`, `OrderLine`, `OrderNote`, `OrderPayment`, `PaymentStatus`, `PaymentStatusInvoice`, `ProductJsonLdAggregateRating`, `ProductJsonLdOptions`, `ProductJsonLdSeller`, `ResolveStockInput`, `ResolvedStock`, `SafeActionResult`, `SchemaAvailability`, `SearchParamOptions`, `ShipToAddress`, `ShippingAddress`, `TAccountQuery`, `TApiResponse`, `TAttribute`, `TAttributeValue`, `TBillingUpdate`, `TCardInfo`, `TCartHdrUid`, `TCartLine`, `TCartLookUp`, `TCategory`, `TCategoryChild`, `TCategoryItemsResult`, `TCheckoutResult`, `TInvMast`, `TInvMastDoc`, `TInventorySupplier`, `TItemAccessory`, `TItemAttribute`, `TItemAttributes`, `TItemCategory`, `TItemDetails`, `TItemRelatedProduct`, `TItemUom`, `TItemsFilters`, `TJoomlaContent`, `TJoomlaContentFilters`, `TLibraryPriceBreak`, `TLibraryPriceData`, `TLtlRatesResponse`, `TLtlShipmentData`, `TMenu`, `TMenuFilters`, `TMetaTags`, `TOrderCartLine`, `TPasswordVerification`, `TPaymentValidation`, `TPriceData`, `TProductCategory`, `TProductItem`, `TProductStockData`, `TProfileValues`, `TRelatedProduct`, `TSearchSuggestion`, `TSearchSuggestionsResponse`, `TShippingMethod`, `TSmartyStreets`, `TStock`, `TStockData`, `TSurcharge`, `TTax`, `TTaxItem`, `TTransactionSetup`, `TUserProfile`, `TWebDesc`, `TrackingData`, `TrackingItem`, `USStateCode`, `UserAddress`, `ViewItemEventParams`
56
59
 
57
60
  ```ts
58
61
  import { BLUR_DATA_URL, BillingAddressInvoiceSchema, BillingAddressSchema } from "@simpleapps-com/augur-utils";
package/README.md ADDED
@@ -0,0 +1,196 @@
1
+ # @simpleapps-com/augur-utils
2
+
3
+ > Shared types, cache configuration, and utility functions 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-utils
13
+ ```
14
+
15
+ ### Peer Dependencies
16
+
17
+ `clsx`, `tailwind-merge`, `valibot`
18
+
19
+ ## Entry Points
20
+
21
+ | Import | Description |
22
+ |--------|-------------|
23
+ | `@simpleapps-com/augur-utils` | 41 exports, 92 types |
24
+ | `@simpleapps-com/augur-utils/web` | 1 exports, 0 types |
25
+
26
+ ## Exports
27
+
28
+ ### Analytics
29
+
30
+ | Export | Kind | Description |
31
+ |--------|------|-------------|
32
+ | `buildTrackingData` | function | Build a GA4 begin_checkout ecommerce payload from cart lines, item details, and prices. |
33
+ | `pushTrackingData` | function | Push ecommerce tracking data to window.dataLayer using the GA4 clear-then-push pattern. |
34
+
35
+ ### Cart
36
+
37
+ | Export | Kind | Description |
38
+ |--------|------|-------------|
39
+ | `trackAddToCart` | function | Track add_to_cart event to Google Analytics dataLayer. |
40
+
41
+ ### Configuration
42
+
43
+ | Export | Kind | Description |
44
+ |--------|------|-------------|
45
+ | `CACHE_CONFIG` | const | Centralized cache configuration for React Query (TanStack Query) |
46
+
47
+ ### Formatting & Dates
48
+
49
+ | Export | Kind | Description |
50
+ |--------|------|-------------|
51
+ | `getBusinessDay` | function | Get the Nth business day from today (skipping weekends). |
52
+
53
+ ### Image & CDN
54
+
55
+ | Export | Kind | Description |
56
+ |--------|------|-------------|
57
+ | `BLUR_DATA_URL` | const | 1x1 transparent PNG for Next.js `<Image blurDataURL={...}>` placeholders. |
58
+ | `buildImageLoader` | function | Returns a loader function compatible with Next.js `<Image loader={...}>`. |
59
+ | `createImageConfig` | function | Creates a frozen ImageConfig object. |
60
+ | `getDefaultImageUrl` | function | Returns the default/placeholder image URL. |
61
+ | `getImageSrcSet` | function | Generates a `srcset` string for responsive images. |
62
+ | `getImageUrl` | function | Builds a full agr.media URL for the given image path and transforms. |
63
+ | `sanitizeHtmlImages` | function | Rewrites `<img src="...">` attributes in an HTML string to use agr.media URLs. |
64
+
65
+ ### Items & Categories
66
+
67
+ | Export | Kind | Description |
68
+ |--------|------|-------------|
69
+ | `generateProductJsonLd` | function | |
70
+ | `serializeCategoryFilters` | function | Converts TItemsFilters to the SDK params shape for category item endpoints. |
71
+ | `trackViewItem` | function | Track view_item event to Google Analytics dataLayer. |
72
+
73
+ ### Payment & Checkout
74
+
75
+ | Export | Kind | Description |
76
+ |--------|------|-------------|
77
+ | `BillingAddressInvoiceSchema` | const | Valibot schema for billing address with required PO number (invoice payments). |
78
+ | `BillingAddressSchema` | const | Valibot schema for billing address validation. |
79
+ | `buildCheckoutPayload` | function | |
80
+ | `getPaymentStatus` | function | |
81
+
82
+ ### Pricing
83
+
84
+ | Export | Kind | Description |
85
+ |--------|------|-------------|
86
+ | `derivePrice` | function | Pure price derivation — usable in hooks AND server components. |
87
+ | `formatPrice` | function | Locale-aware currency formatting. |
88
+
89
+ ### Search
90
+
91
+ | Export | Kind | Description |
92
+ |--------|------|-------------|
93
+ | `serializeSearchParams` | function | Converts TItemsFilters to the SDK params shape for search endpoints. |
94
+
95
+ ### SEO & Structured Data
96
+
97
+ | Export | Kind | Description |
98
+ |--------|------|-------------|
99
+ | `generateBreadcrumbJsonLd` | function | |
100
+
101
+ ### Shipping & Address
102
+
103
+ | Export | Kind | Description |
104
+ |--------|------|-------------|
105
+ | `ShippingAddressSchema` | const | Valibot schema for shipping address validation. |
106
+ | `getShippingLeadDate` | function | Get shipping lead date estimate based on days string. |
107
+ | `isAddressDifferent` | function | Compares a user-entered address with a SmartyStreets-validated address. |
108
+ | `transformShipToAddress` | function | |
109
+
110
+ ### Stock
111
+
112
+ | Export | Kind | Description |
113
+ |--------|------|-------------|
114
+ | `resolveStock` | function | Pure stock resolution -- usable in hooks AND server components. |
115
+
116
+ ### Transforms
117
+
118
+ | Export | Kind | Description |
119
+ |--------|------|-------------|
120
+ | `paginateOffset` | function | Returns a copy of filters with offset adjusted for the given page. |
121
+ | `serializeTransforms` | function | Serializes transform options into the CDN path segment. |
122
+
123
+ ### Validation
124
+
125
+ | Export | Kind | Description |
126
+ |--------|------|-------------|
127
+ | `VALIDATION_PATTERNS` | const | Common regex patterns used for form validation across augur-hosted sites. |
128
+ | `getSchemaAvailability` | function | Maps resolved stock to a Schema.org availability URL. |
129
+
130
+ ### Utilities
131
+
132
+ | Export | Kind | Description |
133
+ |--------|------|-------------|
134
+ | `cn` | value | |
135
+ | `unwrap` | function | Extracts the data from a `SafeActionResult`, throwing on error. |
136
+ | `unwrapOr` | function | Extracts the data from a `SafeActionResult`, returning `null` on error. |
137
+ | `cn` | function | Merge Tailwind classes without conflicts. Web only (tailwind-merge is meaningless in RN). |
138
+
139
+ ### Other
140
+
141
+ | Export | Kind | Description |
142
+ |--------|------|-------------|
143
+ | `CONTIGUOUS_STATES` | const | Lower 48 contiguous states. |
144
+ | `USState` | value | |
145
+ | `US_STATES` | const | All US states and territories — backward-compatible {code, name} shape. |
146
+ | `US_STATES_FULL` | const | All US states and territories — full data from states-us. |
147
+ | `US_TERRITORIES` | const | US territories (PR, GU, VI, AS, MP). |
148
+ | `normalizePath` | function | Normalizes an image path by: |
149
+
150
+ ## Examples
151
+
152
+ ### paginateOffset
153
+
154
+ ```tsx
155
+ useInfiniteQuery({
156
+ ...q.items.itemCategory.categoryItems.list(
157
+ uid,
158
+ serializeCategoryFilters(paginateOffset(filters, pageParam), site)
159
+ ),
160
+ initialPageParam: 0,
161
+ getNextPageParam: (last, _all, lastPage) =>
162
+ (lastPage + 1) * filters.limit < last.total ? lastPage + 1 : undefined,
163
+ });
164
+ ```
165
+
166
+ ### unwrap
167
+
168
+ ```ts
169
+ const cart = unwrap(await getCartLines(cartId));
170
+ ```
171
+
172
+ ### unwrapOr
173
+
174
+ ```ts
175
+ const cart = unwrapOr(await getCartLines(cartId));
176
+ if (!cart) { /* handle missing data *\/ }
177
+ ```
178
+
179
+ ## Types
180
+
181
+ `AddToCartEventParams`, `BillingAddress`, `BreadcrumbJsonLdItem`, `BuildTrackingDataInput`, `CacheTier`, `CategoryFilterOptions`, `CheckoutInput`, `CheckoutPayment`, `CustomerDocument`, `DerivePriceInput`, `DerivedPrice`, `ImageConfig`, `ImageTransforms`, `ImageUrlOptions`, `MenuItem`, `OeHdr`, `OeLine`, `OrderHeader`, `OrderLine`, `OrderNote`, `OrderPayment`, `PaymentStatus`, `PaymentStatusInvoice`, `ProductJsonLdAggregateRating`, `ProductJsonLdOptions`, `ProductJsonLdSeller`, `ResolveStockInput`, `ResolvedStock`, `SafeActionResult`, `SchemaAvailability`, `SearchParamOptions`, `ShipToAddress`, `ShippingAddress`, `TAccountQuery`, `TApiResponse`, `TAttribute`, `TAttributeValue`, `TBillingUpdate`, `TCardInfo`, `TCartHdrUid`, `TCartLine`, `TCartLookUp`, `TCategory`, `TCategoryChild`, `TCategoryItemsResult`, `TCheckoutResult`, `TInvMast`, `TInvMastDoc`, `TInventorySupplier`, `TItemAccessory`, `TItemAttribute`, `TItemAttributes`, `TItemCategory`, `TItemDetails`, `TItemRelatedProduct`, `TItemUom`, `TItemsFilters`, `TJoomlaContent`, `TJoomlaContentFilters`, `TLibraryPriceBreak`, `TLibraryPriceData`, `TLtlRatesResponse`, `TLtlShipmentData`, `TMenu`, `TMenuFilters`, `TMetaTags`, `TOrderCartLine`, `TPasswordVerification`, `TPaymentValidation`, `TPriceData`, `TProductCategory`, `TProductItem`, `TProductStockData`, `TProfileValues`, `TRelatedProduct`, `TSearchSuggestion`, `TSearchSuggestionsResponse`, `TShippingMethod`, `TSmartyStreets`, `TStock`, `TStockData`, `TSurcharge`, `TTax`, `TTaxItem`, `TTransactionSetup`, `TUserProfile`, `TWebDesc`, `TrackingData`, `TrackingItem`, `USStateCode`, `UserAddress`, `ViewItemEventParams`
182
+
183
+
184
+ ## Related Packages
185
+
186
+ All packages use fixed versioning -- same version number across the platform.
187
+
188
+ | Package | Description |
189
+ |---------|-------------|
190
+ | `@simpleapps-com/augur-config` | Shared tooling configuration presets for Augur ecommerce sites |
191
+ | `@simpleapps-com/augur-core` | Universal foundation for Augur packages — proxy infrastructure, cache keys, method classification, shared types |
192
+ | `@simpleapps-com/augur-hooks` | Cross-platform React Query hooks and Zustand stores for Augur ecommerce sites |
193
+ | `@simpleapps-com/augur-mobile` | React Native/Expo adapters for Augur ecommerce apps (offline sync, biometrics, push) |
194
+ | `@simpleapps-com/augur-server` | Server-side utilities for Augur ecommerce sites (Redis caching, SDK helpers, auth) |
195
+ | `@simpleapps-com/augur-tailwind` | Shared Tailwind CSS v4 theme with HSL variables for Augur ecommerce sites |
196
+ | `@simpleapps-com/augur-web` | Shared React UI components for Augur ecommerce sites (Radix + Tailwind) |
package/llms.txt CHANGED
@@ -1,8 +1,30 @@
1
+ # Augur Platform Packages
2
+
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.
7
+
8
+ ## Sibling packages
9
+
10
+ - @simpleapps-com/augur-config - Shared tooling configuration presets for Augur ecommerce sites
11
+ - @simpleapps-com/augur-core - Universal foundation for Augur packages — proxy infrastructure, cache keys, method classification, shared types
12
+ - @simpleapps-com/augur-hooks - 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
+ - @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 (this package) - Shared types, cache configuration, and utility functions for Augur ecommerce sites
17
+ - @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.
20
+
21
+ ---
22
+
1
23
  # @simpleapps-com/augur-utils
2
24
 
3
25
  > Shared types, cache configuration, and utility functions for Augur ecommerce sites
4
26
 
5
- Version: 2.0.21
27
+ Version: 2.2.10
6
28
 
7
29
  ## @simpleapps-com/augur-utils
8
30
 
@@ -35,9 +57,12 @@ Version: 2.0.21
35
57
  - function: getShippingLeadDate - Get shipping lead date estimate based on days string.
36
58
  - function: isAddressDifferent - Compares a user-entered address with a SmartyStreets-validated address.
37
59
  - function: normalizePath - Normalizes an image path by:
60
+ - function: paginateOffset - Returns a copy of filters with offset adjusted for the given page.
38
61
  - function: pushTrackingData - Push ecommerce tracking data to window.dataLayer using the GA4 clear-then-push pattern.
39
62
  - function: resolveStock - Pure stock resolution -- usable in hooks AND server components.
40
63
  - function: sanitizeHtmlImages - Rewrites `<img src="...">` attributes in an HTML string to use agr.media URLs.
64
+ - function: serializeCategoryFilters - Converts TItemsFilters to the SDK params shape for category item endpoints.
65
+ - function: serializeSearchParams - Converts TItemsFilters to the SDK params shape for search endpoints.
41
66
  - function: serializeTransforms - Serializes transform options into the CDN path segment.
42
67
  - function: trackAddToCart - Track add_to_cart event to Google Analytics dataLayer.
43
68
  - function: trackViewItem - Track view_item event to Google Analytics dataLayer.
@@ -49,6 +74,7 @@ Version: 2.0.21
49
74
  - type: BreadcrumbJsonLdItem
50
75
  - type: BuildTrackingDataInput
51
76
  - type: CacheTier
77
+ - type: CategoryFilterOptions
52
78
  - type: CheckoutInput
53
79
  - type: CheckoutPayment
54
80
  - type: CustomerDocument
@@ -73,6 +99,7 @@ Version: 2.0.21
73
99
  - type: ResolvedStock
74
100
  - type: SafeActionResult
75
101
  - type: SchemaAvailability
102
+ - type: SearchParamOptions
76
103
  - type: ShipToAddress
77
104
  - type: ShippingAddress
78
105
  - type: TAccountQuery
@@ -135,6 +162,33 @@ Version: 2.0.21
135
162
  - type: UserAddress
136
163
  - type: ViewItemEventParams
137
164
 
165
+ ### Examples
166
+
167
+ paginateOffset:
168
+ ```tsx
169
+ useInfiniteQuery({
170
+ ...q.items.itemCategory.categoryItems.list(
171
+ uid,
172
+ serializeCategoryFilters(paginateOffset(filters, pageParam), site)
173
+ ),
174
+ initialPageParam: 0,
175
+ getNextPageParam: (last, _all, lastPage) =>
176
+ (lastPage + 1) * filters.limit < last.total ? lastPage + 1 : undefined,
177
+ });
178
+ ```
179
+
180
+ unwrap:
181
+ ```ts
182
+ const cart = unwrap(await getCartLines(cartId));
183
+ ```
184
+
185
+ unwrapOr:
186
+ ```ts
187
+ const cart = unwrapOr(await getCartLines(cartId));
188
+ if (!cart) { /* handle missing data *\/ }
189
+ ```
190
+
191
+
138
192
  ## @simpleapps-com/augur-utils/web
139
193
 
140
194
  - function: cn - Merge Tailwind classes without conflicts. Web only (tailwind-merge is meaningless in RN).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@simpleapps-com/augur-utils",
3
- "version": "2.2.10",
3
+ "version": "2.2.11",
4
4
  "description": "Shared types, cache configuration, and utility functions for Augur ecommerce sites",
5
5
  "license": "MIT",
6
6
  "repository": {