@simpleapps-com/augur-utils 2.4.0 → 2026.11.2

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 (114) hide show
  1. package/EXPORTS.md +28 -31
  2. package/README.md +19 -180
  3. package/dist/address-comparison.d.ts +18 -0
  4. package/dist/address-comparison.d.ts.map +1 -0
  5. package/dist/address-schemas.d.ts +45 -0
  6. package/dist/address-schemas.d.ts.map +1 -0
  7. package/dist/analytics.d.ts +66 -0
  8. package/dist/analytics.d.ts.map +1 -0
  9. package/dist/build-checkout-payload.d.ts +37 -0
  10. package/dist/build-checkout-payload.d.ts.map +1 -0
  11. package/dist/cache-config.d.ts +42 -0
  12. package/dist/cache-config.d.ts.map +1 -0
  13. package/dist/chunk-5UMFBGVA.cjs.map +1 -1
  14. package/dist/date-helpers.d.ts +16 -0
  15. package/dist/date-helpers.d.ts.map +1 -0
  16. package/dist/derive-price.d.ts +49 -0
  17. package/dist/derive-price.d.ts.map +1 -0
  18. package/dist/format-price.d.ts +6 -0
  19. package/dist/format-price.d.ts.map +1 -0
  20. package/dist/get-payment-status.d.ts +10 -0
  21. package/dist/get-payment-status.d.ts.map +1 -0
  22. package/dist/image-rules.d.ts +70 -0
  23. package/dist/image-rules.d.ts.map +1 -0
  24. package/dist/image.d.ts +80 -0
  25. package/dist/image.d.ts.map +1 -0
  26. package/dist/index.cjs +545 -166
  27. package/dist/index.cjs.map +1 -1
  28. package/dist/index.d.ts +63 -1448
  29. package/dist/index.d.ts.map +1 -0
  30. package/dist/index.js +544 -165
  31. package/dist/index.js.map +1 -1
  32. package/dist/json-ld-rules.d.ts +50 -0
  33. package/dist/json-ld-rules.d.ts.map +1 -0
  34. package/dist/json-ld.d.ts +47 -0
  35. package/dist/json-ld.d.ts.map +1 -0
  36. package/dist/money.d.ts +37 -0
  37. package/dist/money.d.ts.map +1 -0
  38. package/dist/price-breaks.d.ts +16 -0
  39. package/dist/price-breaks.d.ts.map +1 -0
  40. package/dist/price-outcome.d.ts +19 -0
  41. package/dist/price-outcome.d.ts.map +1 -0
  42. package/dist/resolve-stock.d.ts +22 -0
  43. package/dist/resolve-stock.d.ts.map +1 -0
  44. package/dist/result.d.ts +33 -0
  45. package/dist/result.d.ts.map +1 -0
  46. package/dist/rules.d.ts +45 -0
  47. package/dist/rules.d.ts.map +1 -0
  48. package/dist/schema-availability.d.ts +11 -0
  49. package/dist/schema-availability.d.ts.map +1 -0
  50. package/dist/transform-ship-to-address.d.ts +15 -0
  51. package/dist/transform-ship-to-address.d.ts.map +1 -0
  52. package/dist/transforms.d.ts +70 -0
  53. package/dist/transforms.d.ts.map +1 -0
  54. package/dist/types/api.d.ts +8 -0
  55. package/dist/types/api.d.ts.map +1 -0
  56. package/dist/types/attribute.d.ts +12 -0
  57. package/dist/types/attribute.d.ts.map +1 -0
  58. package/dist/types/cart.d.ts +25 -0
  59. package/dist/types/cart.d.ts.map +1 -0
  60. package/dist/types/category-items.d.ts +4 -0
  61. package/dist/types/category-items.d.ts.map +1 -0
  62. package/dist/types/category.d.ts +19 -0
  63. package/dist/types/category.d.ts.map +1 -0
  64. package/dist/types/checkout.d.ts +4 -0
  65. package/dist/types/checkout.d.ts.map +1 -0
  66. package/dist/types/customer.d.ts +4 -0
  67. package/dist/types/customer.d.ts.map +1 -0
  68. package/dist/types/filter.d.ts +9 -0
  69. package/dist/types/filter.d.ts.map +1 -0
  70. package/dist/types/inventory.d.ts +10 -0
  71. package/dist/types/inventory.d.ts.map +1 -0
  72. package/dist/types/joomla.d.ts +11 -0
  73. package/dist/types/joomla.d.ts.map +1 -0
  74. package/dist/types/ltl-shipping.d.ts +45 -0
  75. package/dist/types/ltl-shipping.d.ts.map +1 -0
  76. package/dist/types/menu.d.ts +14 -0
  77. package/dist/types/menu.d.ts.map +1 -0
  78. package/dist/types/meta.d.ts +11 -0
  79. package/dist/types/meta.d.ts.map +1 -0
  80. package/dist/types/order.d.ts +72 -0
  81. package/dist/types/order.d.ts.map +1 -0
  82. package/dist/types/password.d.ts +7 -0
  83. package/dist/types/password.d.ts.map +1 -0
  84. package/dist/types/payment.d.ts +69 -0
  85. package/dist/types/payment.d.ts.map +1 -0
  86. package/dist/types/pricing.d.ts +25 -0
  87. package/dist/types/pricing.d.ts.map +1 -0
  88. package/dist/types/product.d.ts +58 -0
  89. package/dist/types/product.d.ts.map +1 -0
  90. package/dist/types/search.d.ts +16 -0
  91. package/dist/types/search.d.ts.map +1 -0
  92. package/dist/types/shipping.d.ts +4 -0
  93. package/dist/types/shipping.d.ts.map +1 -0
  94. package/dist/types/smarty-streets.d.ts +4 -0
  95. package/dist/types/smarty-streets.d.ts.map +1 -0
  96. package/dist/types/supplier.d.ts +4 -0
  97. package/dist/types/supplier.d.ts.map +1 -0
  98. package/dist/types/tax.d.ts +6 -0
  99. package/dist/types/tax.d.ts.map +1 -0
  100. package/dist/types/uom.d.ts +4 -0
  101. package/dist/types/uom.d.ts.map +1 -0
  102. package/dist/types/user-profile.d.ts +5 -0
  103. package/dist/types/user-profile.d.ts.map +1 -0
  104. package/dist/us-states.d.ts +15 -0
  105. package/dist/us-states.d.ts.map +1 -0
  106. package/dist/validation-patterns.d.ts +22 -0
  107. package/dist/validation-patterns.d.ts.map +1 -0
  108. package/dist/web.cjs.map +1 -1
  109. package/dist/web.d.ts +3 -5
  110. package/dist/web.d.ts.map +1 -0
  111. package/llms.txt +49 -38
  112. package/package.json +25 -13
  113. package/dist/index.d.cts +0 -1448
  114. package/dist/web.d.cts +0 -6
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 (this package) - Shared types, cache configuration, and utility functions for Augur ecommerce sites
12
11
  - @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
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 (this package) - 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,51 +21,56 @@ Each package ships its own llms.txt with exports and usage patterns.
24
21
 
25
22
  > Shared types, cache configuration, and utility functions for Augur ecommerce sites
26
23
 
27
- Version: 2.2.29
28
-
29
24
  ## @simpleapps-com/augur-utils
30
25
 
31
- - const: BLUR_DATA_URL - 1x1 transparent PNG for Next.js `<Image blurDataURL={...}>` placeholders.
32
26
  - const: BillingAddressInvoiceSchema - Valibot schema for billing address with required PO number (invoice payments).
33
- - const: BillingAddressSchema - Valibot schema for billing address validation.
34
- - const: CACHE_CONFIG - Centralized cache configuration for React Query (TanStack Query)
35
- - const: CONTIGUOUS_STATES - Lower 48 contiguous states.
36
- - const: ShippingAddressSchema - Valibot schema for shipping address validation.
37
- - value: USState
38
- - const: US_STATES - All US states and territories — backward-compatible {code, name} shape.
39
- - const: US_STATES_FULL - All US states and territories — full data from states-us.
40
- - const: US_TERRITORIES - US territories (PR, GU, VI, AS, MP).
41
- - const: VALIDATION_PATTERNS - Common regex patterns used for form validation across augur-hosted sites.
27
+ - const: BillingAddressSchema - Valibot schema for billing address validation. Less strict than shipping: allows PO Box, no email/phone required.
28
+ - const: BLUR_DATA_URL - 1x1 transparent PNG for Next.js `<Image blurDataURL={...}>` placeholders.
29
+ - const: breadcrumbLd - A breadcrumb trail's BreadcrumbList as text.
42
30
  - function: buildCheckoutPayload - Builds the oe_hdr + oe_line payload required by the commerce checkout API from cart data.
43
31
  - function: buildImageLoader - Returns a loader function compatible with Next.js `<Image loader={...}>`.
44
32
  - function: buildTrackingData - Build a GA4 begin_checkout ecommerce payload from cart lines, item details, and prices.
45
- - value: cn
33
+ - const: CACHE_CONFIG - Centralized cache configuration for React Query (TanStack Query)
34
+ - function: categorySortBy - serializeCategoryFilters' sortBy: the prefix applied only when both are non-empty.
35
+ - function: cleanMoney - Remove JS float noise from a money product or sum.
36
+ - function: cn - Merge Tailwind classes without conflicts. Web only (tailwind-merge is meaningless in RN).
37
+ - const: CONTIGUOUS_STATES - Lower 48 contiguous states.
46
38
  - function: createImageConfig - Creates a frozen ImageConfig object.
47
39
  - function: derivePrice - Pure price derivation — usable in hooks AND server components.
48
- - function: formatPrice - Locale-aware currency formatting.
40
+ - const: faqLd - A FAQ page's FAQPage markup as text: one Question per entry.
41
+ - function: formatPrice - Locale-aware currency formatting. Defaults to USD -- consumers can override locale and currency.
49
42
  - function: generateBreadcrumbJsonLd - Generates a Schema.org BreadcrumbList JSON-LD object from an array of breadcrumb items.
50
43
  - function: generateProductJsonLd - Generates a Schema.org Product JSON-LD string from an inventory document. Returns null if the item is suppressed, unnamed, or has no price.
51
44
  - function: getBusinessDay - Get the Nth business day from today (skipping weekends).
52
- - function: getDefaultImageUrl - Returns the default/placeholder image URL.
45
+ - function: getDefaultImageUrl - Returns the default/placeholder image URL. Per-call `options.defaultImage` overrides `config.defaultImage`.
53
46
  - function: getImageSrcSet - Generates a `srcset` string for responsive images.
54
47
  - function: getImageUrl - Builds a full agr.media URL for the given image path and transforms.
55
48
  - function: getPaymentStatus - Returns "Paid", "Partially Paid", or "Unpaid" based on invoice payment flags and amounts.
56
49
  - function: getSchemaAvailability - Maps resolved stock to a Schema.org availability URL.
57
- - function: getShippingLeadDate - Get shipping lead date estimate based on days string.
58
- - function: isAddressDifferent - Compares a user-entered address with a SmartyStreets-validated address.
59
- - function: normalizePath - Normalizes an image path by:
50
+ - function: getShippingLeadDate - Get shipping lead date estimate based on days string (the table is `shippingLeadOf`).
51
+ - function: hasPriceBreaks - Type guard: true when `libraryPriceData` is the price-page shape with quantity `breaks`.
52
+ - const: idRef - A reference to another node by its @id, as JSON text.
53
+ - function: isAddressDifferent - Compares a user-entered address with a SmartyStreets-validated address. Returns true if any field differs (case-insensitive for address/city, exact match for state abbreviation and zip code).
54
+ - const: nodeHead - The schema.org context and a node's type: its first two members, as JSON text.
55
+ - function: normalizePath - Normalizes an image path by: 1. Returning it as-is if it starts with `http` (external URL). 2. Stripping configured prefixes (defaults: `/images`, `images`). 3. Prepending `defaultPath` for bare filenames (no `/`). 4. Stripping leading slashes.
60
56
  - function: paginateOffset - Returns a copy of filters with offset adjusted for the given page.
61
57
  - function: pushTrackingData - Push ecommerce tracking data to window.dataLayer using the GA4 clear-then-push pattern.
62
58
  - function: resolveStock - Pure stock resolution -- usable in hooks AND server components.
63
- - function: sanitizeHtmlImages - Rewrites `<img src="...">` attributes in an HTML string to use agr.media URLs.
59
+ - function: roundHalfAway - Round half away from zero to `decimals` places.
60
+ - function: sanitizeHtmlImages - Rewrites `<img src="...">` attributes in an HTML string to use agr.media URLs. Useful for CMS/Joomla content that contains raw image references.
64
61
  - function: serializeCategoryFilters - Converts TItemsFilters to the SDK params shape for category item endpoints.
65
62
  - function: serializeSearchParams - Converts TItemsFilters to the SDK params shape for search endpoints.
66
- - function: serializeTransforms - Serializes transform options into the CDN path segment.
63
+ - function: serializeTransforms - Serializes transform options into the CDN path segment. Example: `{ width: 400, format: "webp" }` → `"w_400,f_webp"`
64
+ - const: ShippingAddressSchema - Valibot schema for shipping address validation. Enforces no PO Box, requires street number, formats phone number.
67
65
  - function: trackAddToCart - Track add_to_cart event to Google Analytics dataLayer.
68
66
  - function: trackViewItem - Track view_item event to Google Analytics dataLayer.
69
67
  - function: transformShipToAddress - Normalizes a raw ship-to address object (camelCase or snake_case, physical or mailing) into a consistent ShipToAddress shape.
70
68
  - function: unwrap - Extracts the data from a `SafeActionResult`, throwing on error.
71
69
  - function: unwrapOr - Extracts the data from a `SafeActionResult`, returning `null` on error.
70
+ - const: US_STATES - All US states and territories — backward-compatible {code, name} shape.
71
+ - const: US_STATES_FULL - All US states and territories — full data from states-us.
72
+ - const: US_TERRITORIES - US territories (PR, GU, VI, AS, MP).
73
+ - const: VALIDATION_PATTERNS - Common regex patterns used for form validation across augur-hosted sites.
72
74
  - type: AddToCartEventParams
73
75
  - type: BillingAddress
74
76
  - type: BreadcrumbJsonLdItem
@@ -78,8 +80,9 @@ Version: 2.2.29
78
80
  - type: CheckoutInput
79
81
  - type: CheckoutPayment
80
82
  - type: CustomerDocument
81
- - type: DerivePriceInput
82
83
  - type: DerivedPrice
84
+ - type: DerivePriceInput
85
+ - type: Faq
83
86
  - type: ImageConfig
84
87
  - type: ImageTransforms
85
88
  - type: ImageUrlOptions
@@ -95,13 +98,13 @@ Version: 2.2.29
95
98
  - type: ProductJsonLdAggregateRating
96
99
  - type: ProductJsonLdOptions
97
100
  - type: ProductJsonLdSeller
98
- - type: ResolveStockInput
99
101
  - type: ResolvedStock
102
+ - type: ResolveStockInput
100
103
  - type: SafeActionResult
101
104
  - type: SchemaAvailability
102
105
  - type: SearchParamOptions
103
- - type: ShipToAddress
104
106
  - type: ShippingAddress
107
+ - type: ShipToAddress
105
108
  - type: TAccountQuery
106
109
  - type: TApiResponse
107
110
  - type: TAttribute
@@ -115,19 +118,20 @@ Version: 2.2.29
115
118
  - type: TCategoryChild
116
119
  - type: TCategoryItemsResult
117
120
  - type: TCheckoutResult
121
+ - type: TInventorySupplier
118
122
  - type: TInvMast
119
123
  - type: TInvMastDoc
120
- - type: TInventorySupplier
121
124
  - type: TItemAccessory
122
125
  - type: TItemAttribute
123
126
  - type: TItemAttributes
124
127
  - type: TItemCategory
125
128
  - type: TItemDetails
126
129
  - type: TItemRelatedProduct
127
- - type: TItemUom
128
130
  - type: TItemsFilters
131
+ - type: TItemUom
129
132
  - type: TJoomlaContent
130
133
  - type: TJoomlaContentFilters
134
+ - type: TLibraryMultiplierData
131
135
  - type: TLibraryPriceBreak
132
136
  - type: TLibraryPriceData
133
137
  - type: TLtlRatesResponse
@@ -143,6 +147,8 @@ Version: 2.2.29
143
147
  - type: TProductItem
144
148
  - type: TProductStockData
145
149
  - type: TProfileValues
150
+ - type: TrackingData
151
+ - type: TrackingItem
146
152
  - type: TRelatedProduct
147
153
  - type: TSearchSuggestion
148
154
  - type: TSearchSuggestionsResponse
@@ -156,14 +162,20 @@ Version: 2.2.29
156
162
  - type: TTransactionSetup
157
163
  - type: TUserProfile
158
164
  - type: TWebDesc
159
- - type: TrackingData
160
- - type: TrackingItem
161
- - type: USStateCode
162
165
  - type: UserAddress
166
+ - type: USState
167
+ - type: USStateCode
163
168
  - type: ViewItemEventParams
164
169
 
165
170
  ### Examples
166
171
 
172
+ hasPriceBreaks:
173
+ ```ts
174
+ if (hasPriceBreaks(priceData.libraryPriceData)) {
175
+ priceData.libraryPriceData.breaks.map((tier) => tier.startQuantity);
176
+ }
177
+ ```
178
+
167
179
  paginateOffset:
168
180
  ```tsx
169
181
  useInfiniteQuery({
@@ -188,7 +200,6 @@ const cart = unwrapOr(await getCartLines(cartId));
188
200
  if (!cart) { /* handle missing data *\/ }
189
201
  ```
190
202
 
191
-
192
203
  ## @simpleapps-com/augur-utils/web
193
204
 
194
205
  - function: cn - Merge Tailwind classes without conflicts. Web only (tailwind-merge is meaningless in RN).
package/package.json CHANGED
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "@simpleapps-com/augur-utils",
3
- "version": "2.4.0",
3
+ "version": "2026.11.2",
4
4
  "description": "Shared types, cache configuration, and utility functions 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-utils"
10
10
  },
11
11
  "type": "module",
@@ -31,6 +31,7 @@
31
31
  "states-us": "^1.1.1"
32
32
  },
33
33
  "peerDependencies": {
34
+ "@simpleapps-com/augur-api": "^2026.10.17",
34
35
  "clsx": "^2.1.0",
35
36
  "tailwind-merge": "^2.0.0 || ^3.0.0",
36
37
  "valibot": "^1.0.0"
@@ -47,21 +48,32 @@
47
48
  }
48
49
  },
49
50
  "devDependencies": {
50
- "@vitest/coverage-v8": "^3.2.4",
51
+ "@types/node": "^26.6.6",
52
+ "@vitest/coverage-v8": "~5.0.3",
51
53
  "clsx": "^2.1.1",
54
+ "eslint": "^10.12.0",
52
55
  "jsdom": "^28.1.0",
56
+ "lemmascript": "0.6.5",
53
57
  "tailwind-merge": "^3.5.0",
54
- "tsup": "^8.5.0",
55
- "valibot": "^1.0.0",
56
- "vitest": "^3.2.0",
57
- "@augur-packages/tsconfig": "0.0.0"
58
+ "tsup": "^9.0.0",
59
+ "typescript": "~6.0.3",
60
+ "valibot": "^1.5.0",
61
+ "vitest": "~5.0.3",
62
+ "@atlas/eslint-config": "0.0.0",
63
+ "@atlas/tsconfig": "0.0.0",
64
+ "@atlas/tsup-config": "0.0.0",
65
+ "@atlas/utils": "0.0.0",
66
+ "@atlas/vitest-config": "0.0.0",
67
+ "@simpleapps-com/augur-api": "2026.11.2"
68
+ },
69
+ "engines": {
70
+ "node": ">=22.0.0"
58
71
  },
59
72
  "scripts": {
60
- "build": "tsup",
61
- "dev": "tsup --watch",
62
- "lint": "eslint src/",
63
- "test": "vitest run --passWithNoTests --coverage",
64
- "typecheck": "tsc --noEmit",
65
- "check-exports": "publint"
73
+ "build": "tsup && tsc -p tsconfig.build.json",
74
+ "lint": "eslint .",
75
+ "proofs": "lsc check --backend=dafny",
76
+ "test": "vitest run --coverage",
77
+ "typecheck": "tsc --noEmit"
66
78
  }
67
79
  }