npm package: @simpleapps-com/augur-utils
Description: Shared types, cache configuration, and utility functions for Augur ecommerce sites
Latest version: 2.2.29

# @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

```bash
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 |  |
| `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 |  |
| `getPaymentStatus` | function |  |

### 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 |  |

### 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 |  |

### 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

```tsx
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

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

### unwrapOr

```ts
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) |