codex-commerce-platform

Non-visual commerce utilities for Codex client-owned storefronts.

This package is intentionally not an RR7 storefront and does not own client UI. It should expose typed data helpers for Shopify, carts, catalog/search, images, money, errors, and connector mapping.

Boundary

Allowed here:

• Types for products, collections, carts, money, images, and catalog results
• Pure money formatting helpers
• Generic image URL helpers
• Generic route/error classification and safe logging helpers
• Connector-specific taxonomy helpers, starting with Pinnacle
• Explicit runtime config builders

Not allowed here:

• JSX, React components, CSS, routes, layouts, page composition, static pages, product cards, mega menus, brand assets, client copy, tenant navigation, or generated client configs

Imports

import { formatMoney } from "codex-commerce-platform/money";
import { classifyRouteError } from "codex-commerce-platform/errors";
import type { StorefrontProduct } from "codex-commerce-platform/types";

Root exports are also available:

import { formatMoney, classifyRouteError } from "codex-commerce-platform";

Client storefronts may temporarily alias this package as @codex/commerce-platform in package.json to avoid broad import churn while moving away from local file: dependencies.

Automotive parts taxonomy

The Pinnacle connector exposes the approved strict automotive taxonomy used by Shopify storefronts:

import {
  buildPinnacleAutomotivePartsHref,
  parsePinnacleCatalogState,
  pinnacleSearchInputFromState,
  resolvePinnacleProductType,
} from "@codex/commerce-platform/connectors/pinnacle";

The hierarchy contains eight families, 35 groups, and 195 exact Pinnacle product_type assignments. Unknown codes resolve to null; the strict API never guesses from titles or silently defaults a product into a category. Storefronts own category presentation, labels, ordering, imagery, and menu composition.

The approved review workbook and audit notes live in docs/reference/pinnacle/ and are intentionally excluded from the npm package.

Runtime Config

The package should receive explicit config from the app:

createShopifyStorefrontConfig({
  storeDomain,
  storefrontAccessToken,
  apiVersion,
});

It must not read hidden tenant config, generated site config, or app globals.

Vehicle compatibility

The vehicle-compatibility entrypoint owns non-visual vehicle, garage, VIN-persistence and compatibility-result contracts. Storefronts remain responsible for UI, tenant copy and selecting the active vehicle.

import {
  evaluateVehicleCompatibility,
  resolveVehicleCompatibilityConfig,
  sanitizeGarageState,
} from "codex-commerce-platform/vehicle-compatibility";

Donor taxonomy is candidate evidence only. A storefront must not render a confirmed compatibility claim unless the result is backed by a verified product application, manual verification or VIN verification.