@godaddy/gd-commerce-storefront 0.11.0 → 0.11.1

package/README.md

@@ -512,6 +512,16 @@ Cart mutations share one queue, including initial cart creation. The cart ID is
 
 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.
 
+## Troubleshooting
+
+**"The store could not be reached" with `returned an HTML page instead of JSON` in the console.** A request under
+`/api/commerce` got the application's HTML page. The Commerce routes are not mounted on this origin, or a static
+file, single-page app or SSR fallback route answers before them. Mount them at `/api/commerce` ahead of those
+routes; with a separate API server in development, proxy `/api/commerce` to it. Opening `/api/commerce/config` in
+the browser should return JSON. A missing route never shows sample products, even with `sampleProducts`: the server
+must report `state: 'unbound'`. See [Before a store is connected](#before-a-store-is-connected) and the server
+package's [example for a site before its store connects](../commerce-server/README.md#a-site-before-its-store-connects).
+
 ## Guides
 
 - [Server API contract](docs/server-api.md)

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { a as StorefrontMessages, i as StorefrontMessageKey, n as MessageValues, o as enUS, r as StorefrontMessage, s as formatMessage, t as CommerceErrorCode } from "./messages-CHl-bWx9.js";
+import { a as StorefrontMessages, i as StorefrontMessageKey, n as MessageValues, o as enUS, r as StorefrontMessage, s as formatMessage, t as CommerceErrorCode } from "./messages-peJIfMO4.js";
 import { CSSProperties, ReactElement, ReactNode } from "react";
 import * as react_jsx_runtime0 from "react/jsx-runtime";
 

package/dist/index.js

@@ -14,6 +14,7 @@ const englishText = {
 	requestFailed: "Commerce request failed. Please retry.",
 	requestFailedStatus: "Commerce request failed ({status}). Please retry.",
 	requestTimeout: "Commerce information took too long to load. Please retry.",
+	apiUnavailable: "The store could not be reached. Please retry.",
 	unknownError: "Something went wrong. Please retry.",
 	storageUnavailable: "Your browser cannot save the cart. Keep this page open while shopping.",
 	invalidAddItem: "Select a product variant and a positive quantity.",
@@ -219,8 +220,22 @@ var ApiError = class extends Error {
 		this.text = options?.text;
 	}
 };
+const warnedHtmlPaths = /* @__PURE__ */ new Set();
+function warnHtmlResponse(input) {
+	if (process.env.NODE_ENV === "production") return;
+	const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+	const path = url.split(/[?#]/)[0] ?? url;
+	if (warnedHtmlPaths.has(path)) return;
+	warnedHtmlPaths.add(path);
+	console.error(`[gd-commerce-storefront] ${path} returned an HTML page instead of JSON. Mount the commerce routes at /api/commerce on this origin, before any static file or single-page app fallback route.`);
+}
 const checkedFetch = async (input, init) => {
 	const response = await fetch(input, init);
+	if (response.status < 500 && /^\s*text\/html\b/i.test(response.headers.get("Content-Type") ?? "")) {
+		warnHtmlResponse(input);
+		const text = { key: "apiUnavailable" };
+		throw new ApiError(formatMessage(enUS, text.key), 502, { text });
+	}
 	if (!response.ok) {
 		const data = await response.text();
 		const parsed = (() => {

package/dist/messages/fr-FR.d.ts

@@ -1,4 +1,4 @@
-import { a as StorefrontMessages } from "../messages-CHl-bWx9.js";
+import { a as StorefrontMessages } from "../messages-peJIfMO4.js";
 
 //#region src/locales/fr-fr.d.ts
 /** The package's text in French (France). Pass it to `CommerceProvider` as `messages`, with `locale='fr-FR'`. */

package/dist/messages/fr-FR.js

@@ -20,6 +20,7 @@ const frFR = {
 	requestFailed: "La requête a échoué. Veuillez réessayer.",
 	requestFailedStatus: "La requête a échoué ({status}). Veuillez réessayer.",
 	requestTimeout: "Le chargement des informations a pris trop de temps. Veuillez réessayer.",
+	apiUnavailable: "La boutique est injoignable. Veuillez réessayer.",
 	unknownError: "Un problème est survenu. Veuillez réessayer.",
 	storageUnavailable: "Votre navigateur ne peut pas enregistrer le panier. Gardez cette page ouverte pendant vos achats.",
 	invalidAddItem: "Sélectionnez une variante du produit et une quantité positive.",

package/dist/{messages-CHl-bWx9.d.ts → messages-peJIfMO4.d.ts}

@@ -15,6 +15,7 @@ declare const englishText: {
   requestFailed: string;
   requestFailedStatus: string;
   requestTimeout: string;
+  apiUnavailable: string;
   unknownError: string;
   storageUnavailable: string;
   invalidAddItem: string;

package/docs/server-api.md

@@ -9,7 +9,7 @@ Server implementations can use GoDaddy Commerce APIs or their existing integrati
 - Requests use same-origin browser credentials. JSON writes set `Content-Type: application/json`.
 - Cart, catalog and checkout requests include `X-Commerce-Scope` from `/config`. Validate that scope against the server's current store/channel binding, especially before writes. Treat it as a stale-binding guard, not authorization. Authenticate and authorize requests independently.
 - Read requests use `cache: no-store`, cancellation, and a 15-second timeout. The initial cart creation/add request is also a write and is never retried automatically.
-- Return a non-2xx response with `{ "error": "A useful customer-facing message" }` for failure. HTML error pages are also handled as failures.
+- Return a non-2xx response with `{ "error": "A useful customer-facing message" }` for failure. HTML error pages are also handled as failures. A `text/html` response below 500, such as a single-page app fallback or an HTML 404 page answering an unmounted route, is reported as "The store could not be reached" with status 502, so it never clears a saved cart.
 - Only cart reads with HTTP 404 or 410 clear an expired saved cart. Network errors, 401/403/409/5xx, and other failures preserve the ID and block writes until hydration succeeds.
 - Resolve prices and availability on the server. The cart does not calculate shipping, taxes, or discounts; it explains that they are calculated at checkout. Browser SKU names and quantities are input, not pricing authority. Protect mutations against CSRF as appropriate for the host application's authentication.
 
@@ -31,7 +31,9 @@ Server implementations can use GoDaddy Commerce APIs or their existing integrati
 
 `/checkout` is required only when checkout is enabled. `/discounts` is needed if the host uses `applyDiscount`. The standard catalog/detail/cart flow uses the other routes. All product/cart IDs in request paths are encoded.
 
-The companion `@godaddy/gd-commerce-server` returns 404 from product details when the group is missing or excluded by the catalog's ACTIVE filter, including direct links to inactive products.
+The companion `@godaddy/gd-commerce-server` filters `GET /products` to ACTIVE groups available on the server-configured channel. It returns 404 from `GET /products/:id` when the group is missing, inactive, or unavailable on that channel, including direct product links. Browser callers cannot override the configured channel. This browsing filter does not check product-channel eligibility for `GET /skus/:id`, cart creation, or item addition by SKU ID; hosts must enforce any required restrictions on those operations. See the [server package's channel visibility notes][server-channel-visibility] for stale-channel troubleshooting and upstream lookup costs.
+
+[server-channel-visibility]: ../../commerce-server/README.md#product-channel-visibility
 
 ## Configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@godaddy/gd-commerce-storefront",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Opinionated React storefront templates for GoDaddy Commerce",
   "type": "module",
   "license": "MIT",