Augur

augur-utils

Framework-free types, money math, pricing and stock derivation, formatters, image URLs, analytics and address schemas.

@simpleapps-com/augur-utils

Shared types and pure helpers with no framework or DOM dependencies, so they run in Next.js server components, the browser and React Native alike. Every other augur package depends on it.

pnpm add @simpleapps-com/augur-utils

Peer dependencies: @simpleapps-com/augur-api (for the pricing types). Optional: clsx and tailwind-merge for cn, valibot for the address schemas. Every export, with its description: API Reference.

Entry points

Import Purpose
@simpleapps-com/augur-utils Everything below
@simpleapps-com/augur-utils/web cn only, for sites that import it from there

Helpers

Area Exports
Pricing, stock derivePrice, hasPriceBreaks, resolveStock, getSchemaAvailability
Money cleanMoney, roundHalfAway, formatPrice(price, locale = "en-US", currency = "USD")
Checkout, orders buildCheckoutPayload, getPaymentStatus, isAddressDifferent, transformShipToAddress
Item queries serializeCategoryFilters, serializeSearchParams, categorySortBy, paginateOffset
Images getImageUrl, getImageSrcSet, getDefaultImageUrl, buildImageLoader, createImageConfig, normalizePath, serializeTransforms, sanitizeHtmlImages, BLUR_DATA_URL
SEO generateProductJsonLd, generateBreadcrumbJsonLd
Analytics (GA4) trackAddToCart, trackViewItem, buildTrackingData, pushTrackingData
Results unwrap(result) throws on error; unwrapOr(result) returns null
Forms ShippingAddressSchema, BillingAddressSchema, BillingAddressInvoiceSchema, VALIDATION_PATTERNS
Dates, places getBusinessDay, getShippingLeadDate, US_STATES, US_STATES_FULL, US_TERRITORIES, CONTIGUOUS_STATES
Styling cn(...classes) (clsx and tailwind-merge)

derivePrice and resolveStock are pure, so a server component and a hook give the same answer from the same data.

Money

JavaScript numbers are binary floats: 38.0714 * 3 is 114.21419999999999. Every product or running sum of money MUST go through cleanMoney, which rounds half away from zero to 8 decimals, enough for 4-decimal prices times quantities. Rounding to cents for a payload MUST use roundHalfAway(value, 2); Math.round(value * 100) / 100 and toFixed(2) round ties such as 1.005 down.

In the packages, derivePrice, augur-hooks' useCartPricing and useFormatPrice clean their products and sums, and the analytics helpers round the GA4 value to cents. Display rounding is left to Intl.NumberFormat, which rounds ties the same way.

Pricing types come from the SDK

TPriceData, TLibraryPriceData, TLibraryMultiplierData, TLibraryPriceBreak, TTax and TTaxItem are type-only aliases of augur-api's PricingTypes, which are generated from the pricing service's OpenAPI document. Response types MUST alias the SDK rather than restate it, since hand-copied types drift.

TPriceData["libraryPriceData"] is TLibraryPriceData | TLibraryMultiplierData | null, and only the first carries quantity breaks (lowest quantity first; the last tier has break: null and endQuantity: null; unitPrice is false when a tier couldn't be calculated). Narrow with hasPriceBreaks(libraryPriceData) before reading breaks: "breaks" in libraryPriceData doesn't narrow, because both SDK shapes allow extra keys.

CACHE_CONFIG

Named tiers for setting React Query's staleTime and gcTime by hand. The proxies use augur-core's own tiers instead (cache tiers).

Tier staleTime gcTime For
STATIC 1 h 24 h Categories, menus, item details
SEMI_STATIC 10 min 4 h Pricing, stock, search results
DYNAMIC 5 min 30 min Infinite scroll
CART 2 min 30 min Cart lines and header
REALTIME 0 5 min Active orders, checkout state

The gcTime values MUST be used in the browser only. On the server a finite gcTime starts a timer that keeps the whole per-request cache in memory until it fires, enough to exhaust the heap on a busy site. That includes a provider's defaultOptions.queries.gcTime, because client components render on the server too. Use augur-core's resolveGcTime(CACHE_CONFIG.STATIC.gcTime), which gives Infinity on the server, or leave gcTime unset there.

Types

Types cover carts, categories, items and inventory, pricing, attributes, UOMs, suppliers, filters, customers, menus, orders, shipping (including LTL), search, tax, checkout, payments, metadata, Joomla content, SmartyStreets and user profiles. The full list is in the API Reference.