@godaddy/gd-commerce-server 0.4.0 → 0.4.1

package/README.md

@@ -50,6 +50,16 @@ Hosts with their own configuration service can implement `CommerceConfiguration`
 
 The HTTP checkout route accepts an existing `draftOrderId` or a direct `skuId`; Commerce resolves catalog prices. It rejects `lineItemData`. For non-catalog charges such as fixed-price deposits, calculate the amount on the server and call `createCheckoutSession(params, configuration)` directly. Never forward browser-supplied prices to this trusted helper. Server callers can also use `getOrderStatus(orderId, configuration)` without an HTTP loopback.
 
+### Product channel visibility
+
+`GET /products` and `GET /products/:id` use the channel from the server configuration and request only `ACTIVE` products. Search, category filters, and explicit product IDs retain that channel filter. Product-detail requests for products unavailable on that channel return 404. Browser query parameters cannot select a different channel. Products configured for all channels remain available when the configured channel is active and registered to the store.
+
+If a configured `GODADDY_CHANNEL_ID` is inactive or is not registered to the configured store, the Catalog API returns an empty product list and product-detail requests return 404. These are successful empty results from the Catalog API, not configuration errors. When an expected catalog is empty, verify that the channel is active and registered to `GODADDY_STORE_ID`, then check product status and channel assignments. A missing `GODADDY_CHANNEL_ID` is different: the default configuration reader rejects it with 503 `not_configured`.
+
+The Catalog API resolves active store channels through the paginated `/v1/commerce/channels` endpoint when evaluating a channel filter. Those lookups are not currently cached by the Catalog API, so channel-filtered catalog requests can add upstream calls and latency.
+
+These checks control product browsing. `GET /skus/:id`, cart creation (`POST /cart`), and item addition (`POST /cart/:id/items`) forward SKU IDs without this package checking whether their products are available on the configured channel. A 404 from product details does not establish that a SKU lookup or cart write will be rejected. Hosts that require channel-based restrictions on these operations must enforce them before forwarding the SKU IDs; browsing filters are not an authorization boundary.
+
 ## Checkout return destinations
 
 Configure `checkoutReturnUrls` on the router using trusted deployment settings. Both lists contain complete absolute HTTPS URLs; scheme, origin, port, path, and configured query parameters must match. Success URLs may add a single `orderId` query parameter. Additional query parameters, fragments, credentials, relative URLs, and unlisted destinations are rejected. Configure separate cancel and success destinations as shown above; do not derive the allowlist from request headers or request bodies.
@@ -79,6 +89,38 @@ report `unbound` again only after it is deliberately disconnected. The storefron
 the generic sample products and local sample cart; this server never creates sample Commerce
 records or simulates checkout.
 
+#### A site before its store connects
+
+A template that shows the storefront's sample products before a store connects needs the catalog routes and an
+explicit connection state. Here `COMMERCE_CONNECTION_STATE` is a host-owned setting, set to `unbound` when the site
+is created and to `ready` by the host's connection flow. Read it from whatever records the connection; never derive
+it from missing `GODADDY_*` variables.
+
+```ts
+import express from 'express';
+import { createCommerceCatalogRouter, createRuntimeCommerceConfiguration } from '@godaddy/gd-commerce-server';
+
+const runtime = createRuntimeCommerceConfiguration();
+const configuration = {
+  ...runtime,
+  readConnectionState() {
+    const state = process.env.COMMERCE_CONNECTION_STATE;
+    if (state === 'unbound' || state === 'connecting' || state === 'ready') return state;
+    throw new Error('COMMERCE_CONNECTION_STATE must be unbound, connecting, or ready.');
+  },
+};
+
+const app = express();
+app.use(express.json());
+// Before static files and any single-page app or SSR fallback, which would answer /api/commerce with HTML.
+app.use('/api/commerce', createCommerceCatalogRouter(configuration));
+app.use(express.static('dist'));
+```
+
+`createCommerceCatalogRouter` exposes no checkout routes, so a site without checkout needs no `checkoutReturnUrls`.
+`GET /api/commerce/config` should return `{"state":"unbound"}` as JSON. If it returns the app's HTML page, the
+router is not mounted, or a fallback route runs before it.
+
 ## Errors
 
 Every route reports failures the same way. The body is `{ "error": "<customer-facing message>", "code": "<code>", "requestId": "<id>" }` (order-status also includes `success: false`). The same id is passed to the logger. Bodies never contain upstream messages, configuration details, or credentials.

package/dist/index.js

@@ -1349,6 +1349,7 @@ function buildSkuGroupsVariables(input) {
 	const categoryIds = input.categoryIds?.filter(Boolean) ?? [];
 	const hasExplicitFilters = productIds.length > 0 || categoryIds.length > 0;
 	return {
+		channelId: input.channelId,
 		...input.first !== void 0 && { first: input.first },
 		...input.after && { after: input.after },
 		...productIds.length > 0 && { id: { in: [...productIds] } },
@@ -1356,9 +1357,10 @@ function buildSkuGroupsVariables(input) {
 		...!hasExplicitFilters && input.searchQuery && { label: { contains: input.searchQuery } }
 	};
 }
-function buildSkuGroupVariables({ productId, selectedAttributeValues, skuGroupFirst }) {
+function buildSkuGroupVariables({ channelId, productId, selectedAttributeValues, skuGroupFirst }) {
 	const attributeValues = selectedAttributeValues ? [...selectedAttributeValues] : [];
 	return {
+		channelId,
 		id: productId,
 		attributeValues,
 		...!attributeValues.length && { first: skuGroupFirst ?? 50 }
@@ -1368,8 +1370,8 @@ function buildSkuGroupVariables({ productId, selectedAttributeValues, skuGroupFi
 //#endregion
 //#region src/server/api/commerce/products/[id]/GET.ts
 const skuGroupQuery = `
-  query SkuGroup($id: String!, $first: Int, $attributeValues: [String!] = []) {
-    activeSkuGroups: skuGroups(id: { in: [$id] }, status: { eq: "ACTIVE" }, first: 1) {
+  query SkuGroup($channelId: String!, $id: String!, $first: Int, $attributeValues: [String!] = []) {
+    activeSkuGroups: skuGroups(id: { in: [$id] }, channelId: { eq: $channelId }, status: { eq: "ACTIVE" }, first: 1) {
       edges { node { id } }
     }
     skuGroup(id: $id) {
@@ -1468,8 +1470,9 @@ async function readProduct(req, res) {
 	if (typeof productId !== "string" || !productId) throw new InvalidRequestError("Missing product id");
 	const config = readCommerceConfigForResponse(res);
 	assertCommerceCartScope(req, config);
-	const { storeId, clientId, apiBaseUrl } = config;
+	const { storeId, channelId, clientId, apiBaseUrl } = config;
 	const variables = buildSkuGroupVariables({
+		channelId,
 		productId,
 		selectedAttributeValues: asStringArray$1(req.query.attributeValues),
 		skuGroupFirst: asNumber$1(req.query.skuGroupFirst)
@@ -1494,8 +1497,9 @@ var GET_default$3 = commerceRoute("Failed to load product", readProduct);
 //#endregion
 //#region src/server/api/commerce/products/GET.ts
 const skuGroupsQuery = `
-  query SkuGroups($first: Int, $after: String, $id: SKUGroupIdsFilter, $listId: ListIdFilter, $label: LabelFilter) {
+  query SkuGroups($channelId: String!, $first: Int, $after: String, $id: SKUGroupIdsFilter, $listId: ListIdFilter, $label: LabelFilter) {
     skuGroups(
+      channelId: { eq: $channelId }
       first: $first
       after: $after
       id: $id
@@ -1593,8 +1597,9 @@ function asNumber(value) {
 async function listProducts(req, res) {
 	const config = readCommerceConfigForResponse(res);
 	assertCommerceCartScope(req, config);
-	const { storeId, clientId, apiBaseUrl } = config;
+	const { storeId, channelId, clientId, apiBaseUrl } = config;
 	const variables = buildSkuGroupsVariables({
+		channelId,
 		first: asNumber(req.query.first) ?? 24,
 		after: typeof req.query.after === "string" ? req.query.after : void 0,
 		searchQuery: typeof req.query.searchQuery === "string" ? req.query.searchQuery : void 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@godaddy/gd-commerce-server",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Opinionated Express server integration for GoDaddy Commerce",
   "type": "module",
   "license": "MIT",