@godaddy/gd-commerce-storefront 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 GoDaddy Operating Company, LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# Commerce storefront
+
+`@godaddy/gd-commerce-storefront` provides complete React storefront templates: a catalog, product details with variant selection, a shared cart, and a cart drawer. Applications import compiled components instead of copying and maintaining their implementation.
+
+This is an opinionated package for React applications that use React Router 7 or 8.3+, TanStack Query 5, and the documented same-origin Commerce API. It works with the host application’s router and query provider and does not require Tailwind configuration.
+
+## Installation
+
+This package is not published yet. Use the local workspace example while reviewing this branch. After the first release, install it with:
+
+```sh
+pnpm add @godaddy/gd-commerce-storefront @tanstack/react-query react react-dom react-router
+```
+
+Import the stylesheet once. Mount `CommerceStorefront` once inside your application's existing router and query provider. It owns the commerce state and renders one cart drawer. Keep your header and page routes inside it so cart buttons share that state.
+
+#### Example application
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { BrowserRouter, Route, Routes } from 'react-router';
+import {
+  Catalog, CartButton, CommerceStorefront, ProductDetails,
+} from '@godaddy/gd-commerce-storefront';
+import '@godaddy/gd-commerce-storefront/styles.css';
+
+const client = new QueryClient();
+
+export function App() {
+  return (
+    <QueryClientProvider client={client}>
+      <BrowserRouter>
+        <CommerceStorefront>
+          <header><a href='/'>My store</a><CartButton /></header>
+          <main>
+            <Routes>
+              <Route path='/shop' element={<Catalog />} />
+              <Route path='/products/:productId' element={<ProductDetails />} />
+            </Routes>
+          </main>
+        </CommerceStorefront>
+      </BrowserRouter>
+    </QueryClientProvider>
+  );
+}
+```
+
+Use the providers your application already has; do not create another router or query client for this package. Your server must implement the [server API contract](docs/server-api.md) before these components can load products. Express hosts can mount `@godaddy/gd-commerce-server`; custom servers can implement the contract directly. The host owns store credentials, merchant provisioning, payment readiness, and runtime configuration.
+
+## Configuration
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `catalogPath` | `/shop` | Same-origin catalog route |
+| `productPath` | `/products` | Same-origin prefix for product links; register `${productPath}/:productId` |
+| `checkoutSuccessPath` | unset | Same-origin return route; enables checkout UI only when supplied |
+| `theme` | neutral palette | CSS custom properties applied to storefront surfaces and the portalled drawer |
+
+Provide root-relative paths without a trailing slash. Enable `checkoutSuccessPath` only after your server supports checkout and validates merchant readiness. Mount a corresponding return page. A redirect back from checkout is **not proof of payment**; that page must obtain authoritative payment status from your server. This package does not provide a payment receipt page or merchant onboarding.
+
+`GET /api/commerce/config` supplies the currency and opaque cart scope. The scope must change when the store, channel, or currency binding changes. The draft-order cart displays its subtotal and explains that shipping, taxes, and discounts are calculated at checkout. The explanation has the stable `commerce-cart-checkout-adjustments-note` class so applications can hide it when needed. The cart does not create a checkout session or calculate adjustments. Applications do not pass store IDs or credentials into the browser package. One storefront binding is supported per page and query client.
+
+A connection failure leaves the surrounding application and its state mounted. Catalog and product surfaces show the connection error and retry action. Custom integrations can render `CommerceStatus` or inspect `useCommerce().connection`.
+
+#### Example appearance and copy
+
+```tsx
+<CommerceStorefront
+  catalogPath='/collection'
+  productPath='/item'
+  theme={{
+    '--commerce-accent': '#174c3c',
+    '--commerce-accent-hover': '#10362b',
+    '--commerce-on-accent': '#ffffff',
+    '--commerce-surface': '#ffffff',
+    '--commerce-text': '#171717',
+    '--commerce-radius': '0.75rem',
+  }}
+>
+  {/* Register /collection and /item/:productId in your router. */}
+  <Catalog title='Our collection' description='Made for everyday use.' />
+</CommerceStorefront>
+```
+
+The stylesheet includes all required utilities and scopes them to the package's surfaces. The build removes CSS layer wrappers in their declared order, so the exported CSS can pass through a host Tailwind v3 PostCSS pipeline without `@tailwind` directives. Import it directly; consumers do not need to copy or rewrite the CSS. It does not add a global reset or require dependency scanning by a host Tailwind build. The `theme` prop reaches the drawer even though it is portalled into `document.body`. Keep text, controls and focus indicators accessible when changing colors. Utility class names and internal markup are not a customization API.
+
+The first release uses English UI text and `en-US` currency formatting. Catalog title and description are configurable. Full localization and arbitrary component slots are outside this initial API.
+
+## Compatibility
+
+The package supports React Router 7 and React Router 8.3 or later in the 8.x series. The host still owns the router and query client; no integration API changes are needed between these versions.
+
+The repository example uses React Router 7. Follow each router version's own React and browser requirements.
+
+## Components and hooks
+
+| Export | Purpose |
+| --- | --- |
+| `CommerceStorefront` | Recommended integration: provider and one drawer |
+| `Catalog` | Six products per cursor page, with `title`, `description`, and `showHeader` props |
+| `ProductDetails` | Reads `:productId`; validates URL option selections against catalog results |
+| `ProductCard` | Renders one `SKUGroup` with direct add or a product-details link |
+| `CartButton` | Opens the shared drawer and displays item count |
+| `AddToCartButton` | Adds a verified `sku`, `name`, and optional integer `quantity` |
+| `CommerceStatus` | Connection progress/error/retry for custom layouts |
+| `useCommerce` | Cart, connection, pending/error state and serialized cart actions |
+| `CommerceProvider`, `CartDrawer` | Lower-level composition when the recommended wrapper does not fit; mount each once |
+
+The package exports TypeScript catalog/cart response types and selection/summary helpers for custom product layouts. `useCommerce` actions return `Promise<boolean>`: `false` means an operation failed or its connection became stale. Inspect `error` for active-session failures. Do not automatically retry a failed mutation: the server may have committed it before the response failed. `applyDiscount(code)` is available to custom layouts; the default drawer does not render a promotion form.
+
+`Catalog` renders its `title` as an H1 by default. When the host page owns its semantic heading, render that page H1 and pass `showHeader={false}` so the document still has exactly one H1.
+
+## How it works
+
+Products are SKU groups. The package purchases only an unambiguous SKU, verifies all selected attributes through the server, uses SKU prices/images, and distinguishes untracked inventory from sold-out inventory. Server-side inventory and pricing checks remain mandatory.
+
+Cart mutations share one queue, including initial cart creation. The cart ID is saved under `godaddy:commerce-storefront:cart:<scope>`. Browser Web Locks coordinate tabs where supported; storage/focus events refresh the cart. If storage fails, the current page keeps the cart ID in memory and shows a warning. Browsers without Web Locks have only per-provider serialization; the server must handle concurrent writes correctly.
+
+Changing the server-provided cart scope resets cart state and prevents old responses from affecting the new connection. A failed configuration refresh temporarily disables commerce and also invalidates pending responses. Normal configuration loading and failures do not unmount host content.
+
+## Guides
+
+- [Server API contract](docs/server-api.md)
+- [Independent Vite consumer](../../examples/commerce-storefront/README.md)
+
+## Commands
+
+From the repository root, with Node 24:
+
+```sh
+pnpm install
+pnpm --filter @godaddy/gd-commerce-storefront build
+pnpm --filter @godaddy/gd-commerce-storefront typecheck
+pnpm --filter @godaddy/gd-commerce-storefront lint
+pnpm --filter @godaddy/gd-commerce-storefront test
+pnpm --filter commerce-storefront-example build
+pnpm --filter commerce-storefront-example dev
+```
+
+Build before testing: artifact tests check the compiled JavaScript and shipped CSS as well as source behavior. The build uses local locked tool versions. Nothing in these commands publishes the package.
+
+## License
+
+[MIT](LICENSE.md).

package/dist/index.d.ts

@@ -0,0 +1,395 @@
+import { CSSProperties, ReactElement, ReactNode } from "react";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+
+//#region src/api.d.ts
+interface StorefrontConfig {
+  cartScope: string;
+  currencyCode: string;
+  catalogPath: string;
+  productPath: string;
+  checkoutSuccessPath?: string;
+}
+declare class ApiError extends Error {
+  readonly status: number;
+  constructor(message: string, status: number, options?: ErrorOptions);
+}
+declare function money(value: number, currency: string): string;
+//#endregion
+//#region src/cart-model.d.ts
+interface Money {
+  value?: number | null;
+  currencyCode?: string | null;
+}
+interface DraftOrderContext {
+  storeId?: string | null;
+  channelId?: string | null;
+  owner?: string | null;
+}
+interface OrderTotals {
+  subTotal?: Money | null;
+  shippingTotal?: Money | null;
+  taxTotal?: Money | null;
+  discountTotal?: Money | null;
+  productDiscountTotal?: Money | null;
+  shippingDiscountTotal?: Money | null;
+  feeTotal?: Money | null;
+  total?: Money | null;
+}
+interface LineItemTotals {
+  subTotal?: Money | null;
+  taxTotal?: Money | null;
+  discountTotal?: Money | null;
+  feeTotal?: Money | null;
+}
+interface CartSelectedOption {
+  attribute?: string | null;
+  values?: string[] | null;
+}
+interface CartSelectedAddonValue {
+  name?: string | null;
+  costAdjustment?: Money | null;
+}
+interface CartSelectedAddon {
+  attribute?: string | null;
+  sku?: string | null;
+  values?: CartSelectedAddonValue[] | null;
+}
+interface CartLineItemDetails {
+  productAssetUrl?: string | null;
+  sku?: string | null;
+  unitOfMeasure?: string | null;
+  selectedOptions?: CartSelectedOption[] | null;
+  selectedAddons?: CartSelectedAddon[] | null;
+}
+interface CartDiscount {
+  id?: string | null;
+  name?: string | null;
+  code?: string | null;
+  amount?: Money | null;
+  ratePercentage?: string | null;
+  appliedBeforeTax?: boolean | null;
+}
+interface CartTax {
+  id?: string | null;
+  name?: string | null;
+  amount?: Money | null;
+  ratePercentage?: string | null;
+  included?: boolean | null;
+  exempted?: boolean | null;
+}
+interface CartNote {
+  id?: string | null;
+  content?: string | null;
+  author?: string | null;
+  authorType?: string | null;
+  createdAt?: string | null;
+}
+interface CartLineItem {
+  id?: string | null;
+  name?: string | null;
+  quantity?: number | null;
+  skuId?: string | null;
+  type?: string | null;
+  fulfillmentMode?: string | null;
+  details?: CartLineItemDetails | null;
+  totals?: LineItemTotals | null;
+  discounts?: CartDiscount[] | null;
+  taxes?: CartTax[] | null;
+  notes?: CartNote[] | null;
+  createdAt?: string | null;
+  updatedAt?: string | null;
+}
+interface CartAddress {
+  addressLine1?: string | null;
+  addressLine2?: string | null;
+  addressLine3?: string | null;
+  adminArea1?: string | null;
+  adminArea2?: string | null;
+  adminArea3?: string | null;
+  adminArea4?: string | null;
+  postalCode?: string | null;
+  countryCode?: string | null;
+}
+interface CartShippingInfo {
+  firstName?: string | null;
+  lastName?: string | null;
+  email?: string | null;
+  phone?: string | null;
+  companyName?: string | null;
+  address?: CartAddress | null;
+}
+interface CartOrder {
+  id?: string | null;
+  customerId?: string | null;
+  createdAt?: string | null;
+  updatedAt?: string | null;
+  context?: DraftOrderContext | null;
+  lineItems?: CartLineItem[] | null;
+  totals?: OrderTotals | null;
+  discounts?: CartDiscount[] | null;
+  taxes?: CartTax[] | null;
+  shipping?: CartShippingInfo | null;
+  notes?: CartNote[] | null;
+  tags?: string[] | null;
+}
+interface AddToCartItemInput {
+  skuId: string;
+  name: string;
+  quantity: number;
+}
+interface CartSummaryTotals {
+  itemCount: number;
+  currencyCode: string;
+  subtotal: number;
+  shipping: number;
+  taxes: number;
+  discount: number;
+  total: number;
+}
+declare function addToCart(cartId: string | null, item: AddToCartItemInput, fetchFn?: typeof globalThis.fetch): Promise<{
+  cart: CartOrder | null;
+}>;
+declare function getCartSummaryTotals(order: CartOrder | null | undefined): CartSummaryTotals;
+//#endregion
+//#region src/catalog-model.d.ts
+interface PageInfo {
+  hasNextPage?: boolean | null;
+  hasPreviousPage?: boolean | null;
+  startCursor?: string | null;
+  endCursor?: string | null;
+}
+interface ConnectionEdge<T> {
+  cursor?: string | null;
+  node?: T | null;
+}
+interface Connection<T> {
+  edges?: Array<ConnectionEdge<T> | null> | null;
+  pageInfo?: PageInfo | null;
+  totalCount?: number | null;
+}
+interface PriceRange {
+  min?: number | null;
+  max?: number | null;
+}
+interface MediaObject {
+  id?: string | null;
+  url?: string | null;
+  type?: string | null;
+  label?: string | null;
+  position?: number | null;
+}
+interface InventoryCount {
+  id?: string | null;
+  quantity?: number | null;
+  type?: string | null;
+}
+interface SKUGroupAttributeValue {
+  id?: string | null;
+  name?: string | null;
+  label?: string | null;
+}
+interface SKUGroupAttribute {
+  id?: string | null;
+  name?: string | null;
+  label?: string | null;
+  description?: string | null;
+  htmlDescription?: string | null;
+  values?: Connection<SKUGroupAttributeValue> | null;
+}
+type SKUGroupSKU = SKU;
+interface SKUGroup {
+  id?: string | null;
+  status?: string | null;
+  name?: string | null;
+  label?: string | null;
+  description?: string | null;
+  htmlDescription?: string | null;
+  type?: string | null;
+  priceRange?: PriceRange | null;
+  compareAtPriceRange?: PriceRange | null;
+  mediaObjects?: Connection<MediaObject> | null;
+  attributes?: Connection<SKUGroupAttribute> | null;
+  skus?: Connection<SKUGroupSKU> | null;
+}
+interface SKUPrice {
+  id?: string | null;
+  value?: Money | null;
+  compareAtValue?: Money | null;
+}
+interface SKUAttributeValue {
+  id?: string | null;
+  name?: string | null;
+  label?: string | null;
+}
+interface SKU {
+  id?: string | null;
+  label?: string | null;
+  name?: string | null;
+  description?: string | null;
+  htmlDescription?: string | null;
+  code?: string | null;
+  prices?: Connection<SKUPrice> | null;
+  inventoryCounts?: Connection<InventoryCount> | null;
+  mediaObjects?: Connection<MediaObject> | null;
+  attributeValues?: Connection<SKUAttributeValue> | null;
+}
+interface StringInFilter {
+  in: string[];
+}
+interface LabelFilter {
+  contains: string;
+}
+interface SkuGroupsVariables {
+  first?: number | null;
+  after?: string | null;
+  id?: StringInFilter;
+  listId?: StringInFilter;
+  label?: LabelFilter;
+}
+interface SkuGroupVariables {
+  id: string;
+  first?: number | null;
+  /** Attribute value `name` fields — the catalog API's `has` filter matches by `name`, not `id`. */
+  attributeValues?: string[];
+}
+interface SkuVariables {
+  id: string;
+}
+interface SkuGroupsResult {
+  skuGroups?: Connection<SKUGroup> | null;
+}
+interface SkuGroupResult {
+  skuGroup?: SKUGroup | null;
+}
+interface SkuResult {
+  sku?: SKU | null;
+}
+interface ProductGridVariablesInput {
+  first?: number | null;
+  after?: string | null;
+  productIds?: readonly string[];
+  categoryIds?: readonly string[];
+  searchQuery?: string;
+}
+interface ProductDetailsVariablesInput {
+  productId: string;
+  /** Attribute value `name` fields, not `id`. */
+  selectedAttributeValues?: readonly string[];
+  /** Number of SKUs to request before attributes are selected. Defaults to 50. */
+  skuGroupFirst?: number;
+}
+interface StorefrontProductAttributeValue {
+  id: string;
+  name: string;
+  label: string;
+}
+interface StorefrontProductAttribute {
+  id: string;
+  name: string;
+  label: string;
+  values: StorefrontProductAttributeValue[];
+}
+type InventoryCountContainer = {
+  inventoryCounts?: Connection<InventoryCount> | null;
+};
+type MediaObjectContainer = {
+  mediaObjects?: Connection<MediaObject> | null;
+};
+declare function getSingleMatchedSkuId(skuGroup: SKUGroup | null | undefined): string | null;
+declare function getSingleMatchedSku(skuGroup: SKUGroup | null | undefined): SKU | null;
+declare function getLabeledSkuOptions(skuGroup: SKUGroup | null | undefined): SKU[];
+declare function getAvailableInventoryQuantity(item: InventoryCountContainer | null | undefined): number | null;
+declare function getImageUrls(item: MediaObjectContainer | null | undefined): string[];
+declare function getPrimaryImageUrl(item: MediaObjectContainer | null | undefined): string | null;
+declare function getProductAttributes(skuGroup: SKUGroup | null | undefined): StorefrontProductAttribute[];
+//#endregion
+//#region src/cart.d.ts
+declare function CartButton(): ReactElement;
+declare function AddToCartButton({
+  sku,
+  name,
+  quantity
+}: {
+  sku: SKU;
+  name: string;
+  quantity?: number;
+}): ReactElement;
+declare function CartDrawer(): ReactElement;
+//#endregion
+//#region src/catalog.d.ts
+declare function ProductCard({
+  product
+}: {
+  product: SKUGroup;
+}): ReactElement;
+interface CatalogProps {
+  title?: string;
+  description?: string;
+  showHeader?: boolean;
+}
+declare function Catalog(props: CatalogProps): ReactElement;
+//#endregion
+//#region src/commerce-provider.d.ts
+interface CommerceContextValue {
+  connection: 'loading' | 'ready' | 'error';
+  connectionError: string | null;
+  retryConnection: () => void;
+  theme: StorefrontTheme;
+  config: StorefrontConfig;
+  cart: CartOrder | null;
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  /** Restores the initiating control after the cart drawer closes. */
+  restoreFocus: () => void;
+  pending: boolean;
+  hydrating: boolean;
+  error: string | null;
+  storageWarning: string | null;
+  announcement: string;
+  addItem: (item: AddToCartItemInput) => Promise<boolean>;
+  changeQuantity: (itemId: string, quantity: number) => Promise<boolean>;
+  removeItem: (itemId: string) => Promise<boolean>;
+  applyDiscount: (code: string) => Promise<boolean>;
+  refresh: () => Promise<boolean>;
+  checkout: () => Promise<boolean>;
+}
+declare function useCommerce(): CommerceContextValue;
+type StorefrontTheme = CSSProperties & {
+  '--commerce-accent'?: string;
+  '--commerce-accent-hover'?: string;
+  '--commerce-on-accent'?: string;
+  '--commerce-surface'?: string;
+  '--commerce-text'?: string;
+  '--commerce-radius'?: string;
+};
+interface CommerceProviderProps {
+  children: ReactNode;
+  catalogPath?: string;
+  productPath?: string;
+  /** Applied to storefront surfaces and the portalled cart drawer. */
+  theme?: StorefrontTheme;
+  /** Set only when your server has enabled checkout and this return route exists. */
+  checkoutSuccessPath?: string;
+}
+declare function CommerceProvider({
+  children,
+  catalogPath,
+  productPath,
+  checkoutSuccessPath,
+  theme
+}: CommerceProviderProps): ReactElement;
+//#endregion
+//#region src/commerce-storefront.d.ts
+/** Mount once inside the application's Router and QueryClientProvider. */
+declare function CommerceStorefront({
+  children,
+  ...props
+}: CommerceProviderProps): react_jsx_runtime0.JSX.Element;
+//#endregion
+//#region src/product-details.d.ts
+declare function ProductDetails(): ReactElement;
+//#endregion
+//#region src/storefront-surface.d.ts
+declare function CommerceStatus(): ReactElement | null;
+//#endregion
+export { AddToCartButton, AddToCartItemInput, ApiError, CartAddress, CartButton, CartDiscount, CartDrawer, CartLineItem, CartLineItemDetails, CartNote, CartOrder, CartSelectedAddon, CartSelectedAddonValue, CartSelectedOption, CartShippingInfo, CartSummaryTotals, CartTax, Catalog, type CatalogProps, type CommerceContextValue, CommerceProvider, type CommerceProviderProps, CommerceStatus, CommerceStorefront, Connection, ConnectionEdge, DraftOrderContext, InventoryCount, LabelFilter, LineItemTotals, MediaObject, Money, OrderTotals, PageInfo, PriceRange, ProductCard, ProductDetails, ProductDetailsVariablesInput, ProductGridVariablesInput, SKU, SKUAttributeValue, SKUGroup, SKUGroupAttribute, SKUGroupAttributeValue, SKUGroupSKU, SKUPrice, SkuGroupResult, SkuGroupVariables, SkuGroupsResult, SkuGroupsVariables, SkuResult, SkuVariables, type StorefrontConfig, StorefrontProductAttribute, StorefrontProductAttributeValue, type StorefrontTheme, StringInFilter, addToCart, getAvailableInventoryQuantity, getCartSummaryTotals, getImageUrls, getLabeledSkuOptions, getPrimaryImageUrl, getProductAttributes, getSingleMatchedSku, getSingleMatchedSkuId, money, useCommerce };