@simpleapps-com/augur-utils

Shared types, cache configuration, and utility functions for Augur ecommerce sites

Auto-generated. Do not edit manually. Regenerate with: pnpm run generate-exports

Part of the @simpleapps-com/augur-* platform. All packages use fixed versioning (same version number).

Install

pnpm add @simpleapps-com/augur-utils

Peer Dependencies

clsx, tailwind-merge, valibot

Entry Points

| Import | Description | |--------|-------------| | @simpleapps-com/augur-utils | 41 exports, 92 types | | @simpleapps-com/augur-utils/web | 1 exports, 0 types |

Exports

Analytics

| Export | Kind | Description | |--------|------|-------------| | buildTrackingData | function | Build a GA4 begin_checkout ecommerce payload from cart lines, item details, and prices. | | pushTrackingData | function | Push ecommerce tracking data to window.dataLayer using the GA4 clear-then-push pattern. |

Cart

| Export | Kind | Description | |--------|------|-------------| | trackAddToCart | function | Track add_to_cart event to Google Analytics dataLayer. |

Configuration

| Export | Kind | Description | |--------|------|-------------| | CACHE_CONFIG | const | Centralized cache configuration for React Query (TanStack Query) |

Formatting & Dates

| Export | Kind | Description | |--------|------|-------------| | getBusinessDay | function | Get the Nth business day from today (skipping weekends). |

Image & CDN

| Export | Kind | Description | |--------|------|-------------| | BLUR_DATA_URL | const | 1x1 transparent PNG for Next.js <Image blurDataURL={...}> placeholders. | | buildImageLoader | function | Returns a loader function compatible with Next.js <Image loader={...}>. | | createImageConfig | function | Creates a frozen ImageConfig object. | | getDefaultImageUrl | function | Returns the default/placeholder image URL. | | getImageSrcSet | function | Generates a srcset string for responsive images. | | getImageUrl | function | Builds a full agr.media URL for the given image path and transforms. | | sanitizeHtmlImages | function | Rewrites <img src="..."> attributes in an HTML string to use agr.media URLs. |

Items & Categories

| Export | Kind | Description | |--------|------|-------------| | generateProductJsonLd | function | Generates a Schema.org Product JSON-LD string from an inventory document. Returns null if the item is suppressed, unnamed, or has no price. | | serializeCategoryFilters | function | Converts TItemsFilters to the SDK params shape for category item endpoints. | | trackViewItem | function | Track view_item event to Google Analytics dataLayer. |

Payment & Checkout

| Export | Kind | Description | |--------|------|-------------| | BillingAddressInvoiceSchema | const | Valibot schema for billing address with required PO number (invoice payments). | | BillingAddressSchema | const | Valibot schema for billing address validation. | | buildCheckoutPayload | function | Builds the oe_hdr + oe_line payload required by the commerce checkout API from cart data. | | getPaymentStatus | function | Returns "Paid", "Partially Paid", or "Unpaid" based on invoice payment flags and amounts. |

Pricing

| Export | Kind | Description | |--------|------|-------------| | derivePrice | function | Pure price derivation — usable in hooks AND server components. | | formatPrice | function | Locale-aware currency formatting. |

Search

| Export | Kind | Description | |--------|------|-------------| | serializeSearchParams | function | Converts TItemsFilters to the SDK params shape for search endpoints. |

SEO & Structured Data

| Export | Kind | Description | |--------|------|-------------| | generateBreadcrumbJsonLd | function | Generates a Schema.org BreadcrumbList JSON-LD object from an array of breadcrumb items. |

Shipping & Address

| Export | Kind | Description | |--------|------|-------------| | ShippingAddressSchema | const | Valibot schema for shipping address validation. | | getShippingLeadDate | function | Get shipping lead date estimate based on days string. | | isAddressDifferent | function | Compares a user-entered address with a SmartyStreets-validated address. | | transformShipToAddress | function | Normalizes a raw ship-to address object (camelCase or snake_case, physical or mailing) into a consistent ShipToAddress shape. |

Stock

| Export | Kind | Description | |--------|------|-------------| | resolveStock | function | Pure stock resolution -- usable in hooks AND server components. |

Transforms

| Export | Kind | Description | |--------|------|-------------| | paginateOffset | function | Returns a copy of filters with offset adjusted for the given page. | | serializeTransforms | function | Serializes transform options into the CDN path segment. |

Validation

| Export | Kind | Description | |--------|------|-------------| | VALIDATION_PATTERNS | const | Common regex patterns used for form validation across augur-hosted sites. | | getSchemaAvailability | function | Maps resolved stock to a Schema.org availability URL. |

Utilities

| Export | Kind | Description | |--------|------|-------------| | cn | value | | | unwrap | function | Extracts the data from a SafeActionResult, throwing on error. | | unwrapOr | function | Extracts the data from a SafeActionResult, returning null on error. | | cn | function | Merge Tailwind classes without conflicts. Web only (tailwind-merge is meaningless in RN). |

Other

| Export | Kind | Description | |--------|------|-------------| | CONTIGUOUS_STATES | const | Lower 48 contiguous states. | | USState | value | | | US_STATES | const | All US states and territories — backward-compatible {code, name} shape. | | US_STATES_FULL | const | All US states and territories — full data from states-us. | | US_TERRITORIES | const | US territories (PR, GU, VI, AS, MP). | | normalizePath | function | Normalizes an image path by: |

Examples

paginateOffset

useInfiniteQuery({
  ...q.items.itemCategory.categoryItems.list(
    uid,
    serializeCategoryFilters(paginateOffset(filters, pageParam), site)
  ),
  initialPageParam: 0,
  getNextPageParam: (last, _all, lastPage) =>
    (lastPage + 1) * filters.limit < last.total ? lastPage + 1 : undefined,
});

unwrap

const cart = unwrap(await getCartLines(cartId));

unwrapOr

const cart = unwrapOr(await getCartLines(cartId));
if (!cart) { /* handle missing data *\/ }

Types

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

Related Packages

All packages use fixed versioning -- same version number across the platform.

| Package | Description | |---------|-------------| | @simpleapps-com/augur-config | Shared tooling configuration presets for Augur ecommerce sites | | @simpleapps-com/augur-core | Universal foundation for Augur packages — proxy infrastructure, cache keys, method classification, shared types | | @simpleapps-com/augur-hooks | Cross-platform React Query hooks and Zustand stores for Augur ecommerce sites | | @simpleapps-com/augur-mobile | React Native/Expo adapters for Augur ecommerce apps (offline sync, biometrics, push) | | @simpleapps-com/augur-server | Server-side utilities for Augur ecommerce sites (Redis caching, SDK helpers, auth) | | @simpleapps-com/augur-tailwind | Shared Tailwind CSS v4 theme with HSL variables for Augur ecommerce sites | | @simpleapps-com/augur-web | Shared React UI components for Augur ecommerce sites (Radix + Tailwind) |