@godaddy/gd-commerce-server 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,5 +1,5 @@
 import { Router } from "express";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 
 //#region src/lib/commerce/checkout-config.ts
 const DEFAULT_CHECKOUT_CONFIGURATION = {
@@ -35,6 +35,68 @@ function parseCommerceCheckoutConfiguration(raw) {
 	};
 }
 
+//#endregion
+//#region src/lib/commerce/errors.ts
+var CommerceError = class extends Error {
+	httpStatus;
+	code;
+	publicMessage;
+	details;
+	constructor(httpStatus, code, message, options = {}) {
+		super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+		this.name = "CommerceError";
+		this.httpStatus = httpStatus;
+		this.code = code;
+		this.publicMessage = options.publicMessage;
+		this.details = options.details;
+	}
+};
+var InvalidRequestError = class extends CommerceError {
+	constructor(publicMessage, { message = publicMessage,...options } = {}) {
+		super(400, "invalid_request", message, {
+			...options,
+			publicMessage
+		});
+		this.name = "InvalidRequestError";
+	}
+};
+var ScopeMismatchError = class extends CommerceError {
+	constructor() {
+		const publicMessage = "The connected store changed. Reload the page before continuing.";
+		super(409, "scope_mismatch", publicMessage, { publicMessage });
+		this.name = "ScopeMismatchError";
+	}
+};
+var NotFoundError = class extends CommerceError {
+	constructor(publicMessage, { message = publicMessage,...options } = {}) {
+		super(404, "not_found", message, {
+			...options,
+			publicMessage
+		});
+		this.name = "NotFoundError";
+	}
+};
+var CommerceNotConfiguredError = class extends CommerceError {
+	constructor(message, { publicMessage = "Commerce configuration is unavailable. Complete the store connection before continuing.",...options } = {}) {
+		super(503, "not_configured", message, {
+			...options,
+			publicMessage
+		});
+		this.name = "CommerceNotConfiguredError";
+	}
+};
+/**
+* Commerce returned a failure, an unexpected response, or could not be reached. Always 502:
+* even an upstream 401/403 concerns this server's client credentials, not the caller, and
+* answering 401 would collide with the host's own authentication handling.
+*/
+var UpstreamError = class extends CommerceError {
+	constructor(message, { unauthorized = false,...options } = {}) {
+		super(502, unauthorized ? "upstream_unauthorized" : "upstream_error", message, options);
+		this.name = "UpstreamError";
+	}
+};
+
 //#endregion
 //#region src/lib/commerce/config.ts
 const DEFAULT_API_BASE_URL = "https://api.godaddy.com";
@@ -43,14 +105,14 @@ function normalizeApiBaseUrl(raw) {
 	try {
 		url = new URL(raw);
 	} catch {
-		throw new Error("Commerce config: apiBaseUrl must be a valid HTTPS origin.");
+		throw new CommerceNotConfiguredError("Commerce config: apiBaseUrl must be a valid HTTPS origin.");
 	}
-	if (url.protocol !== "https:" || url.username || url.password || url.pathname !== "/" || url.search || url.hash) throw new Error("Commerce config: apiBaseUrl must be an HTTPS origin without credentials, path, query, or fragment.");
+	if (url.protocol !== "https:" || url.username || url.password || url.pathname !== "/" || url.search || url.hash) throw new CommerceNotConfiguredError("Commerce config: apiBaseUrl must be an HTTPS origin without credentials, path, query, or fragment.");
 	return url.origin;
 }
 function requireValue(environment, key) {
 	const value = environment[key]?.trim();
-	if (!value) throw new Error(`Commerce config: ${key} is missing. Configure it in the server environment.`);
+	if (!value) throw new CommerceNotConfiguredError(`Commerce config: ${key} is missing. Configure it in the server environment.`);
 	return value;
 }
 /** Read server environment values on each call. Loading files or secret stores belongs to the host. */
@@ -73,20 +135,81 @@ function createRuntimeCommerceConfiguration(options = {}) {
 		readCheckout: () => parseCommerceCheckoutConfiguration((options.environment ?? process.env).GODADDY_CHECKOUT_CONFIGURATION)
 	};
 }
+function fromHost(read) {
+	try {
+		return read();
+	} catch (cause) {
+		if (cause instanceof CommerceError) throw cause;
+		throw new CommerceNotConfiguredError("Commerce configuration could not be read", { cause });
+	}
+}
+const CONNECTION_STATES = new Set([
+	"unbound",
+	"connecting",
+	"ready"
+]);
+/** The host-reported connection state, or `undefined` when the host does not report one. */
+function readCommerceConnectionState(configuration) {
+	const state = fromHost(() => configuration.readConnectionState?.());
+	if (state !== void 0 && !CONNECTION_STATES.has(state)) throw new CommerceNotConfiguredError("Invalid Commerce connection state.");
+	return state;
+}
+/** Nonready connection states must never use leftover credentials. */
+function assertCommerceConnectionReady(configuration) {
+	const state = readCommerceConnectionState(configuration);
+	if (state === "unbound" || state === "connecting") throw new CommerceNotConfiguredError("Commerce store connection is not ready.", { details: { connectionState: state } });
+}
+function readReadyCommerceConfig(configuration) {
+	assertCommerceConnectionReady(configuration);
+	return fromHost(() => configuration.read());
+}
+function readReadyCheckoutConfig(configuration) {
+	assertCommerceConnectionReady(configuration);
+	return fromHost(() => configuration.readCheckout());
+}
 function commerceConfigurationForResponse(res) {
-	const configuration = res.locals.commerceConfiguration;
-	if (configuration && typeof configuration === "object" && "read" in configuration && typeof configuration.read === "function" && "readCheckout" in configuration && typeof configuration.readCheckout === "function") return configuration;
-	return createRuntimeCommerceConfiguration();
+	const supplied = res.locals.commerceConfiguration;
+	return supplied && typeof supplied === "object" && "read" in supplied && typeof supplied.read === "function" && "readCheckout" in supplied && typeof supplied.readCheckout === "function" ? supplied : createRuntimeCommerceConfiguration();
 }
 function readCommerceConfigForResponse(res) {
-	const configuration = commerceConfigurationForResponse(res);
-	assertCommerceConnectionReady(configuration);
-	return configuration.read();
+	return readReadyCommerceConfig(commerceConfigurationForResponse(res));
 }
-/** Nonready and invalid connection states must never use leftover credentials. */
-function assertCommerceConnectionReady(configuration) {
-	const state = configuration.readConnectionState?.();
-	if (state !== void 0 && state !== "ready") throw new Error("Commerce store connection is not ready. Complete the store connection before continuing.");
+
+//#endregion
+//#region src/lib/commerce/upstream-http.ts
+async function fetchUpstream(input, init, { operation, details }, fetchImplementation = fetch) {
+	try {
+		return await fetchImplementation(input, init);
+	} catch (cause) {
+		throw new UpstreamError(`${operation} could not reach Commerce`, {
+			cause,
+			details
+		});
+	}
+}
+async function readUpstreamJson(response, { operation, details }) {
+	try {
+		return await response.json();
+	} catch (cause) {
+		throw new UpstreamError(`${operation} returned a non-JSON response`, {
+			cause,
+			details: {
+				...details,
+				upstreamStatus: response.status
+			}
+		});
+	}
+}
+/** Builds the error for a non-2xx response. 401 and 403 always mean this server's credentials were rejected. */
+async function upstreamStatusError(response, { operation, details }, { unauthorized = false } = {}) {
+	if (!response.bodyUsed) await response.body?.cancel();
+	return new UpstreamError(`${operation} failed: upstream returned ${response.status}`, {
+		unauthorized: unauthorized || response.status === 401 || response.status === 403,
+		details: {
+			...details,
+			upstreamStatus: response.status
+		}
+	});
 }
 
 //#endregion
@@ -128,22 +251,52 @@ function checkoutGraphqlEndpoint({ apiBaseUrl }) {
 function authorizationHeaders({ accessToken }) {
 	return { Authorization: `Bearer ${accessToken}` };
 }
+const UNAUTHORIZED_OAUTH_ERRORS = new Set([
+	"invalid_client",
+	"invalid_grant",
+	"unauthorized_client",
+	"invalid_scope"
+]);
+async function readOAuthError(response) {
+	try {
+		const body = await response.json();
+		return body && typeof body === "object" && "error" in body && typeof body.error === "string" ? body.error : void 0;
+	} catch {
+		return;
+	}
+}
 async function getOAuthAccessToken({ clientId, clientSecret, apiBaseUrl, scope = "commerce.product:read", fetch: fetchImplementation }) {
-	if (!clientId || !clientSecret) throw new Error("clientId and clientSecret are required");
-	const requestFetch = fetchImplementation ?? fetch;
+	if (!clientId || !clientSecret) throw new CommerceNotConfiguredError("clientId and clientSecret are required");
 	const body = new URLSearchParams();
 	body.append("grant_type", "client_credentials");
 	body.append("client_id", clientId);
 	body.append("client_secret", clientSecret);
 	body.append("scope", scope);
-	const response = await requestFetch(new URL("/v2/oauth2/token", apiBaseUrl).toString(), {
+	const endpoint = new URL("/v2/oauth2/token", apiBaseUrl);
+	const request = {
+		operation: "Access token request",
+		details: {
+			endpoint: endpoint.href,
+			scope
+		}
+	};
+	const response = await fetchUpstream(endpoint, {
 		method: "POST",
 		headers: { "Content-Type": "application/x-www-form-urlencoded" },
 		body: body.toString(),
 		cache: "no-store"
-	});
-	if (!response.ok) throw new Error(`Failed to get access token: ${response.status} ${response.statusText}`);
-	return await response.json();
+	}, request, fetchImplementation);
+	if (!response.ok) {
+		const oauthError = response.status === 400 ? await readOAuthError(response) : void 0;
+		throw await upstreamStatusError(response, {
+			...request,
+			details: {
+				...request.details,
+				oauthError
+			}
+		}, { unauthorized: oauthError !== void 0 && UNAUTHORIZED_OAUTH_ERRORS.has(oauthError) });
+	}
+	return readUpstreamJson(response, request);
 }
 function buildBuyNowCheckoutInput({ storeId, skuId, quantity = 1, returnUrl, successUrl, channelId }, overrides = {}) {
 	return applyCheckoutDefaults({
@@ -181,10 +334,18 @@ function buildNonCatalogCheckoutInput({ storeId, lineItemData, quantity = 1, ret
 
 //#endregion
 //#region src/lib/commerce/gql.ts
-var GraphQLErrorWithCodes = class extends Error {
+/** `status` is the upstream HTTP status; the route responds with `httpStatus` (502) unless mapped. */
+var GraphQLErrorWithCodes = class extends UpstreamError {
 	constructor(errors, status) {
 		const errorMessage = errors.length === 1 ? `${errors[0]?.message || "Unknown error"}` : errors.map((error) => error.message).filter(Boolean).join("; ");
-		super(errorMessage);
+		super(errorMessage, {
+			unauthorized: [status, ...errors.map((error) => error.status)].some((value) => value === 401 || value === 403),
+			details: {
+				upstreamStatus: status,
+				upstreamCodes: errors.map((error) => error.code).filter(Boolean),
+				upstreamStatuses: errors.map((error) => error.status).filter((value) => typeof value === "number")
+			}
+		});
 		this.errors = errors;
 		this.status = status;
 		this.name = "GraphQLErrorWithCodes";
@@ -209,7 +370,7 @@ async function gqlRequest({ endpoint, query, variables, headers: headersInit, fe
 	const requestHeaders = new Headers(headersInit);
 	requestHeaders.set("Accept", "application/json");
 	requestHeaders.set("Content-Type", "application/json");
-	const response = await (fetchImplementation ?? fetch)(endpoint, {
+	const response = await fetchUpstream(endpoint, {
 		method: "POST",
 		headers: requestHeaders,
 		body: JSON.stringify({
@@ -217,7 +378,10 @@ async function gqlRequest({ endpoint, query, variables, headers: headersInit, fe
 			variables: variables ?? {}
 		}),
 		cache: "no-store"
-	});
+	}, {
+		operation: "GraphQL request",
+		details: { endpoint }
+	}, fetchImplementation);
 	let result;
 	try {
 		result = await response.json();
@@ -236,7 +400,7 @@ async function gqlRequest({ endpoint, query, variables, headers: headersInit, fe
 		message: `GraphQL request failed: ${response.status} ${response.statusText}`,
 		status: response.status
 	}], response.status);
-	if (result.data === void 0) throw new Error("GraphQL response did not include data");
+	if (result.data === void 0) throw new UpstreamError("GraphQL response did not include data", { details: { endpoint } });
 	return result.data;
 }
 
@@ -331,15 +495,14 @@ function promotionCodesEnabled(configuration) {
 }
 async function createCheckoutSession(params, configuration = createRuntimeCommerceConfiguration()) {
 	const { draftOrderId, skuId, quantity, lineItemData, returnUrl, successUrl } = params;
-	if (!returnUrl || !successUrl) throw new Error("createCheckoutSession: returnUrl and successUrl are required");
+	if (!returnUrl || !successUrl) throw new InvalidRequestError("createCheckoutSession: returnUrl and successUrl are required");
 	if ([
 		draftOrderId,
 		skuId,
 		lineItemData
-	].filter(Boolean).length !== 1) throw new Error("createCheckoutSession: exactly one of draftOrderId, skuId, or lineItemData is required");
-	assertCommerceConnectionReady(configuration);
-	const { storeId, channelId, clientId, clientSecret, apiBaseUrl, sourceApp, owner, currencyCode: configCurrencyCode } = configuration.read();
-	const checkoutConfiguration = configuration.readCheckout();
+	].filter(Boolean).length !== 1) throw new InvalidRequestError("createCheckoutSession: exactly one of draftOrderId, skuId, or lineItemData is required");
+	const { storeId, channelId, clientId, clientSecret, apiBaseUrl, sourceApp, owner, currencyCode: configCurrencyCode } = readReadyCommerceConfig(configuration);
+	const checkoutConfiguration = readReadyCheckoutConfig(configuration);
 	const enablePromotionCodes = promotionCodesEnabled(checkoutConfiguration);
 	const catalogShippingEnabled = lineItemData === void 0 && checkoutConfiguration.enableShipping;
 	const token = await getOAuthAccessToken({
@@ -402,16 +565,20 @@ async function createCheckoutSession(params, configuration = createRuntimeCommer
 			headers: authorizationHeaders({ accessToken: token.access_token })
 		});
 	} catch (error) {
-		throw new Error("Commerce checkout session could not be created", { cause: error });
+		throw new UpstreamError("Commerce checkout session could not be created", {
+			cause: error,
+			unauthorized: error instanceof UpstreamError && error.code === "upstream_unauthorized",
+			details: error instanceof UpstreamError ? error.details : void 0
+		});
 	}
 	const session = result.createCheckoutSession;
-	if (!session?.url || !session.id) throw new Error("Checkout session was not created");
-	if (session.storeId !== storeId || session.channelId !== channelId) throw new Error(`Checkout session binding mismatch: expected store ${storeId} and channel ${channelId}, received store ${session.storeId ?? "missing"} and channel ${session.channelId ?? "missing"}`);
+	if (!session?.url || !session.id) throw new UpstreamError("Checkout session was not created");
+	if (session.storeId !== storeId || session.channelId !== channelId) throw new UpstreamError(`Checkout session binding mismatch: expected store ${storeId} and channel ${channelId}, received store ${session.storeId ?? "missing"} and channel ${session.channelId ?? "missing"}`);
 	const expectedShipping = lineItemData === void 0 && checkoutConfiguration.enableShipping;
-	if (lineItemData === void 0 && enablePromotionCodes && session.enablePromotionCodes !== true) throw new Error("Checkout session did not enable configured promotion codes");
-	if (checkoutConfiguration.enableTaxCollection && session.enableTaxCollection !== true) throw new Error("Checkout session did not enable configured tax collection");
-	if (expectedShipping && (session.enableShipping !== true || session.enableShippingAddressCollection !== true)) throw new Error("Checkout session did not enable configured shipping and address collection");
-	if (!session.paymentMethods?.card?.processor) throw new Error("Checkout session did not configure payment methods.");
+	if (lineItemData === void 0 && enablePromotionCodes && session.enablePromotionCodes !== true) throw new UpstreamError("Checkout session did not enable configured promotion codes");
+	if (checkoutConfiguration.enableTaxCollection && session.enableTaxCollection !== true) throw new UpstreamError("Checkout session did not enable configured tax collection");
+	if (expectedShipping && (session.enableShipping !== true || session.enableShippingAddressCollection !== true)) throw new UpstreamError("Checkout session did not enable configured shipping and address collection");
+	if (!session.paymentMethods?.card?.processor) throw new UpstreamError("Checkout session did not configure payment methods.");
 	return {
 		url: session.url,
 		id: session.id,
@@ -426,32 +593,73 @@ async function createCheckoutSession(params, configuration = createRuntimeCommer
 
 //#endregion
 //#region src/lib/commerce/get-order-status.ts
+/** `CommerceOrderStatus.status` when the Orders API reports no payment status. */
+const ORDER_STATUS_UNKNOWN = "unknown";
+var InvalidOrderIdError = class extends InvalidRequestError {
+	constructor() {
+		super("missing or invalid orderId query parameter", { message: "getOrderStatus: a valid orderId is required" });
+		this.name = "InvalidOrderIdError";
+	}
+};
+var OrderNotFoundError = class extends NotFoundError {
+	constructor() {
+		super("Order not found");
+		this.name = "OrderNotFoundError";
+	}
+};
+function isBindingId(value) {
+	return typeof value === "string" && value !== "";
+}
+async function readErrorCode(response) {
+	try {
+		const body = await response.json();
+		return body && typeof body === "object" && "code" in body && typeof body.code === "string" ? body.code : null;
+	} catch {
+		return null;
+	}
+}
 async function getOrderStatus(orderId, configuration = createRuntimeCommerceConfiguration()) {
-	if (typeof orderId !== "string" || !orderId.trim() || orderId === "." || orderId === "..") throw new Error("getOrderStatus: a valid orderId is required");
-	assertCommerceConnectionReady(configuration);
-	const { storeId, channelId, clientId, clientSecret, apiBaseUrl, currencyCode } = configuration.read();
+	if (typeof orderId !== "string" || !orderId || orderId !== orderId.trim() || orderId === "." || orderId === "..") throw new InvalidOrderIdError();
+	const { storeId, channelId, clientId, clientSecret, apiBaseUrl, currencyCode } = readReadyCommerceConfig(configuration);
 	const token = await getOAuthAccessToken({
 		clientId,
 		clientSecret,
 		apiBaseUrl,
 		scope: "commerce.order:read"
 	});
-	const response = await fetch(new URL(`/v1/commerce/stores/${encodeURIComponent(storeId)}/orders/${encodeURIComponent(orderId)}`, apiBaseUrl), {
+	const endpoint = new URL(`/v1/commerce/stores/${encodeURIComponent(storeId)}/orders/${encodeURIComponent(orderId)}`, apiBaseUrl);
+	const request = {
+		operation: "Order lookup",
+		details: { endpoint: endpoint.href }
+	};
+	const response = await fetchUpstream(endpoint, {
 		method: "GET",
 		headers: {
 			...authorizationHeaders({ accessToken: token.access_token }),
 			Accept: "application/json"
 		},
 		cache: "no-store"
-	});
-	if (!response.ok) throw new Error(`Failed to load order: upstream returned ${response.status}`);
-	const order = (await response.json())?.order;
-	if (!order?.id || order.id !== orderId) throw new Error("Order lookup did not return the requested order");
-	if (order.context?.storeId !== storeId || order.context?.channelId !== channelId) throw new Error("Order lookup returned a different store or channel");
+	}, request);
+	if (!response.ok) {
+		const code = response.status === 404 || response.status === 422 ? await readErrorCode(response) : void 0;
+		if (response.status === 404 && code === "NOT_FOUND") throw new OrderNotFoundError();
+		if (response.status === 422 && code === "VALIDATION_FAILED") throw new InvalidOrderIdError();
+		throw await upstreamStatusError(response, {
+			...request,
+			details: {
+				...request.details,
+				upstreamCode: code ?? void 0
+			}
+		});
+	}
+	const order = (await readUpstreamJson(response, request))?.order;
+	const context = order?.context;
+	if (!isBindingId(order?.id) || order.id !== orderId || !isBindingId(context?.storeId) || !isBindingId(context?.channelId)) throw new UpstreamError("Order lookup did not return the requested order", { details: { endpoint: endpoint.href } });
+	if (context.storeId !== storeId || context.channelId !== channelId) throw new OrderNotFoundError();
 	const total = order.totals?.total;
 	return {
 		id: order.id,
-		status: order.statuses?.paymentStatus ?? "unknown",
+		status: order.statuses?.paymentStatus ?? ORDER_STATUS_UNKNOWN,
 		amount: total?.value ?? 0,
 		currency: total?.currencyCode ?? currencyCode,
 		createdAt: order.createdAt,
@@ -505,6 +713,75 @@ function createCheckoutReturnUrlValidator(policy) {
 	};
 }
 
+//#endregion
+//#region src/lib/commerce/commerce-route.ts
+const consoleCommerceLogger = { error: (message, context) => console.error(message, context) };
+const REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+function observabilityLocals(res) {
+	return res.locals;
+}
+function resolveRequestId(req, resolver) {
+	let supplied;
+	try {
+		supplied = resolver?.(req);
+	} catch {
+		supplied = void 0;
+	}
+	return typeof supplied === "string" && REQUEST_ID_PATTERN.test(supplied) ? supplied : randomUUID();
+}
+function requestIdFor(req, res) {
+	const locals = observabilityLocals(res);
+	locals.commerceRequestId ??= resolveRequestId(req, locals.commerceRequestIdResolver);
+	return locals.commerceRequestId;
+}
+/**
+* The single place Commerce failures become HTTP responses. Typed errors keep their status and
+* public message; unmapped upstream failures are 502 and anything else is 500. 5xx detail goes
+* to the configured logger, never into the body.
+*/
+function sendCommerceError(req, res, label, error, { failureFields = {}, classifyUpstreamError } = {}) {
+	const resolved = error instanceof UpstreamError ? classifyUpstreamError?.(error) ?? error : error instanceof CommerceError ? error : void 0;
+	const httpStatus = resolved?.httpStatus ?? 500;
+	const code = resolved?.code ?? "internal_error";
+	const requestId = requestIdFor(req, res);
+	if (httpStatus >= 500) {
+		const context = {
+			requestId,
+			method: req.method,
+			path: req.path,
+			httpStatus,
+			code,
+			...resolved?.details ? { details: resolved.details } : {},
+			error
+		};
+		try {
+			(observabilityLocals(res).commerceLogger ?? consoleCommerceLogger).error(`commerce-server: ${label}`, context);
+		} catch (loggerError) {
+			console.error(`commerce-server: ${label} (host logger failed)`, {
+				...context,
+				loggerError
+			});
+		}
+	}
+	if (res.headersSent) return;
+	res.status(httpStatus).json({
+		...failureFields,
+		error: resolved?.publicMessage ?? label,
+		code,
+		requestId
+	});
+}
+/** Wraps a route so thrown errors are answered by `sendCommerceError` with the route's label. */
+function commerceRoute(label, handler, options = {}) {
+	return async (req, res) => {
+		try {
+			await handler(req, res);
+		} catch (error) {
+			sendCommerceError(req, res, label, error, options);
+		}
+	};
+}
+
 //#endregion
 //#region src/lib/commerce/cart-scope.ts
 /** Public cache/storage scope, not an authorization credential. */
@@ -517,11 +794,10 @@ function getCommerceCartScope(config) {
 	])).digest("hex").slice(0, 32);
 }
 /** Existing custom clients may omit the header; managed components always send it. */
-function validateCommerceCartScope(req, res, config) {
+function assertCommerceCartScope(req, config) {
 	const suppliedScope = req.headers?.["x-commerce-scope"];
-	if (suppliedScope === void 0 || suppliedScope === getCommerceCartScope(config)) return true;
-	res.status(409).json({ error: "The connected store changed. Reload the page before continuing." });
-	return false;
+	if (suppliedScope === void 0 || suppliedScope === getCommerceCartScope(config)) return;
+	throw new ScopeMismatchError();
 }
 
 //#endregion
@@ -731,61 +1007,7 @@ const getCartOrderQuery = `
 `;
 
 //#endregion
-//#region src/server/api/commerce/cart/[id]/discounts/POST.ts
-const applyDiscountCodesMutation = `
-  mutation ApplyDiscountCodes($input: ApplyDiscountCodesInput!) {
-    applyDiscountCodes(input: $input) {
-      id
-    }
-  }
-`;
-async function handler(req, res) {
-	try {
-		const cartId = req.params.id;
-		if (typeof cartId !== "string" || !cartId) {
-			res.status(400).json({ error: "Missing cart id" });
-			return;
-		}
-		const body = req.body ?? {};
-		const codes = Array.isArray(body.discountCodes) ? body.discountCodes.filter((code) => typeof code === "string" && code.length > 0) : [];
-		if (codes.length === 0) {
-			res.status(400).json({ error: "discountCodes must be a non-empty string array" });
-			return;
-		}
-		const config = readCommerceConfigForResponse(res);
-		if (!validateCommerceCartScope(req, res, config)) return;
-		const { storeId, clientId, apiBaseUrl } = config;
-		const endpoint = orderStorefrontEndpoint({ apiBaseUrl });
-		const headers = storefrontHeaders({
-			storeId,
-			clientId
-		});
-		await gqlRequest({
-			endpoint,
-			query: applyDiscountCodesMutation,
-			variables: { input: {
-				orderId: cartId,
-				discountCodes: codes
-			} },
-			headers
-		});
-		const hydrated = await gqlRequest({
-			endpoint,
-			query: getCartOrderQuery,
-			variables: { id: cartId },
-			headers
-		});
-		res.json({ cart: hydrated.orderById ?? null });
-	} catch (error) {
-		res.status(500).json({
-			error: "Failed to apply discount codes",
-			message: error instanceof Error ? error.message : String(error)
-		});
-	}
-}
-
-//#endregion
-//#region src/server/api/commerce/cart/[id]/GET.ts
+//#region src/lib/commerce/upstream-errors.ts
 function isCartNotFoundError(error) {
 	if (!(error instanceof GraphQLErrorWithCodes)) return false;
 	const isFailure = (status) => status !== void 0 && status >= 400 && status !== 404 && status !== 410;
@@ -798,17 +1020,68 @@ function isCartNotFoundError(error) {
 		return /\b(?:cart|(?:draft[ -])?order)\s+(?:(?:is|was|has)\s+)?(?:not found|expired)\b/i.test(message ?? "");
 	});
 }
-async function handler$1(req, res) {
+const CART_UPSTREAM_ERROR_RULES = [{
+	matches: isCartNotFoundError,
+	toError: (error) => new NotFoundError("Cart not found", { cause: error })
+}];
+/** For routes acting on an existing saved cart (`/cart/:id`); creating a cart has none to miss. */
+function classifyCartUpstreamError(error) {
+	return CART_UPSTREAM_ERROR_RULES.find((rule) => rule.matches(error))?.toError(error) ?? error;
+}
+
+//#endregion
+//#region src/server/api/commerce/cart/[id]/discounts/POST.ts
+const applyDiscountCodesMutation = `
+  mutation ApplyDiscountCodes($input: ApplyDiscountCodesInput!) {
+    applyDiscountCodes(input: $input) {
+      id
+    }
+  }
+`;
+async function applyDiscountCodes(req, res) {
+	const cartId = req.params.id;
+	if (typeof cartId !== "string" || !cartId) throw new InvalidRequestError("Missing cart id");
+	const body = req.body ?? {};
+	const codes = Array.isArray(body.discountCodes) ? body.discountCodes.filter((code) => typeof code === "string" && code.length > 0) : [];
+	if (codes.length === 0) throw new InvalidRequestError("discountCodes must be a non-empty string array");
+	const config = readCommerceConfigForResponse(res);
+	assertCommerceCartScope(req, config);
+	const { storeId, clientId, apiBaseUrl } = config;
+	const endpoint = orderStorefrontEndpoint({ apiBaseUrl });
+	const headers = storefrontHeaders({
+		storeId,
+		clientId
+	});
+	await gqlRequest({
+		endpoint,
+		query: applyDiscountCodesMutation,
+		variables: { input: {
+			orderId: cartId,
+			discountCodes: codes
+		} },
+		headers
+	});
+	const hydrated = await gqlRequest({
+		endpoint,
+		query: getCartOrderQuery,
+		variables: { id: cartId },
+		headers
+	});
+	res.json({ cart: hydrated.orderById ?? null });
+}
+var POST_default = commerceRoute("Failed to apply discount codes", applyDiscountCodes, { classifyUpstreamError: classifyCartUpstreamError });
+
+//#endregion
+//#region src/server/api/commerce/cart/[id]/GET.ts
+async function readCart(req, res) {
+	const cartId = req.params.id;
+	if (typeof cartId !== "string" || !cartId) throw new InvalidRequestError("Missing cart id");
+	const config = readCommerceConfigForResponse(res);
+	assertCommerceCartScope(req, config);
+	const { storeId, clientId, apiBaseUrl } = config;
+	let data;
 	try {
-		const cartId = req.params.id;
-		if (typeof cartId !== "string" || !cartId) {
-			res.status(400).json({ error: "Missing cart id" });
-			return;
-		}
-		const config = readCommerceConfigForResponse(res);
-		if (!validateCommerceCartScope(req, res, config)) return;
-		const { storeId, clientId, apiBaseUrl } = config;
-		const data = await gqlRequest({
+		data = await gqlRequest({
 			endpoint: orderStorefrontEndpoint({ apiBaseUrl }),
 			query: getCartOrderQuery,
 			variables: { id: cartId },
@@ -817,18 +1090,16 @@ async function handler$1(req, res) {
 				clientId
 			})
 		});
-		res.json({ cart: data.orderById ?? null });
 	} catch (error) {
 		if (isCartNotFoundError(error)) {
 			res.status(200).json({ cart: null });
 			return;
 		}
-		res.status(500).json({
-			error: "Failed to load cart",
-			message: error instanceof Error ? error.message : String(error)
-		});
+		throw error;
 	}
+	res.json({ cart: data.orderById ?? null });
 }
+var GET_default = commerceRoute("Failed to load cart", readCart, { classifyUpstreamError: classifyCartUpstreamError });
 
 //#endregion
 //#region src/server/api/commerce/cart/[id]/items/[itemId]/DELETE.ts
@@ -837,45 +1108,36 @@ const deleteLineItemByIdMutation = `
     deleteLineItemById(id: $id, orderId: $orderId)
   }
 `;
-async function handler$2(req, res) {
-	try {
-		const cartId = req.params.id;
-		const itemId = req.params.itemId;
-		if (typeof cartId !== "string" || !cartId || typeof itemId !== "string" || !itemId) {
-			res.status(400).json({ error: "Missing cart id or item id" });
-			return;
-		}
-		const config = readCommerceConfigForResponse(res);
-		if (!validateCommerceCartScope(req, res, config)) return;
-		const { storeId, clientId, apiBaseUrl } = config;
-		const endpoint = orderStorefrontEndpoint({ apiBaseUrl });
-		const headers = storefrontHeaders({
-			storeId,
-			clientId
-		});
-		await gqlRequest({
-			endpoint,
-			query: deleteLineItemByIdMutation,
-			variables: {
-				id: itemId,
-				orderId: cartId
-			},
-			headers
-		});
-		const hydrated = await gqlRequest({
-			endpoint,
-			query: getCartOrderQuery,
-			variables: { id: cartId },
-			headers
-		});
-		res.json({ cart: hydrated.orderById ?? null });
-	} catch (error) {
-		res.status(500).json({
-			error: "Failed to delete line item",
-			message: error instanceof Error ? error.message : String(error)
-		});
-	}
+async function deleteLineItem(req, res) {
+	const cartId = req.params.id;
+	const itemId = req.params.itemId;
+	if (typeof cartId !== "string" || !cartId || typeof itemId !== "string" || !itemId) throw new InvalidRequestError("Missing cart id or item id");
+	const config = readCommerceConfigForResponse(res);
+	assertCommerceCartScope(req, config);
+	const { storeId, clientId, apiBaseUrl } = config;
+	const endpoint = orderStorefrontEndpoint({ apiBaseUrl });
+	const headers = storefrontHeaders({
+		storeId,
+		clientId
+	});
+	await gqlRequest({
+		endpoint,
+		query: deleteLineItemByIdMutation,
+		variables: {
+			id: itemId,
+			orderId: cartId
+		},
+		headers
+	});
+	const hydrated = await gqlRequest({
+		endpoint,
+		query: getCartOrderQuery,
+		variables: { id: cartId },
+		headers
+	});
+	res.json({ cart: hydrated.orderById ?? null });
 }
+var DELETE_default = commerceRoute("Failed to delete line item", deleteLineItem, { classifyUpstreamError: classifyCartUpstreamError });
 
 //#endregion
 //#region src/server/api/commerce/cart/[id]/items/[itemId]/PATCH.ts
@@ -886,52 +1148,43 @@ const updateLineItemByIdMutation = `
     }
   }
 `;
-async function handler$3(req, res) {
-	try {
-		const cartId = req.params.id;
-		const itemId = req.params.itemId;
-		if (typeof cartId !== "string" || !cartId || typeof itemId !== "string" || !itemId) {
-			res.status(400).json({ error: "Missing cart id or item id" });
-			return;
-		}
-		const body = req.body ?? {};
-		const config = readCommerceConfigForResponse(res);
-		if (!validateCommerceCartScope(req, res, config)) return;
-		const { storeId, clientId, apiBaseUrl } = config;
-		const endpoint = orderStorefrontEndpoint({ apiBaseUrl });
-		const headers = storefrontHeaders({
-			storeId,
-			clientId
-		});
-		await gqlRequest({
-			endpoint,
-			query: updateLineItemByIdMutation,
-			variables: { input: {
-				id: itemId,
-				orderId: cartId,
-				name: body.name,
-				quantity: body.quantity,
-				fulfillmentMode: body.fulfillmentMode,
-				status: body.status,
-				type: body.type,
-				details: body.details
-			} },
-			headers
-		});
-		const hydrated = await gqlRequest({
-			endpoint,
-			query: getCartOrderQuery,
-			variables: { id: cartId },
-			headers
-		});
-		res.json({ cart: hydrated.orderById ?? null });
-	} catch (error) {
-		res.status(500).json({
-			error: "Failed to update line item",
-			message: error instanceof Error ? error.message : String(error)
-		});
-	}
+async function updateLineItem(req, res) {
+	const cartId = req.params.id;
+	const itemId = req.params.itemId;
+	if (typeof cartId !== "string" || !cartId || typeof itemId !== "string" || !itemId) throw new InvalidRequestError("Missing cart id or item id");
+	const body = req.body ?? {};
+	const config = readCommerceConfigForResponse(res);
+	assertCommerceCartScope(req, config);
+	const { storeId, clientId, apiBaseUrl } = config;
+	const endpoint = orderStorefrontEndpoint({ apiBaseUrl });
+	const headers = storefrontHeaders({
+		storeId,
+		clientId
+	});
+	await gqlRequest({
+		endpoint,
+		query: updateLineItemByIdMutation,
+		variables: { input: {
+			id: itemId,
+			orderId: cartId,
+			name: body.name,
+			quantity: body.quantity,
+			fulfillmentMode: body.fulfillmentMode,
+			status: body.status,
+			type: body.type,
+			details: body.details
+		} },
+		headers
+	});
+	const hydrated = await gqlRequest({
+		endpoint,
+		query: getCartOrderQuery,
+		variables: { id: cartId },
+		headers
+	});
+	res.json({ cart: hydrated.orderById ?? null });
 }
+var PATCH_default = commerceRoute("Failed to update line item", updateLineItem, { classifyUpstreamError: classifyCartUpstreamError });
 
 //#endregion
 //#region src/server/api/commerce/cart/[id]/items/POST.ts
@@ -942,50 +1195,38 @@ const addLineItemBySkuIdMutation$1 = `
     }
   }
 `;
-async function handler$4(req, res) {
-	try {
-		const cartId = req.params.id;
-		if (typeof cartId !== "string" || !cartId) {
-			res.status(400).json({ error: "Missing cart id" });
-			return;
-		}
-		const body = req.body ?? {};
-		if (!body.skuId || !body.name || typeof body.quantity !== "number") {
-			res.status(400).json({ error: "Missing required fields: skuId, name, quantity" });
-			return;
-		}
-		const config = readCommerceConfigForResponse(res);
-		if (!validateCommerceCartScope(req, res, config)) return;
-		const { storeId, clientId, apiBaseUrl } = config;
-		const endpoint = orderStorefrontEndpoint({ apiBaseUrl });
-		const headers = storefrontHeaders({
-			storeId,
-			clientId
-		});
-		await gqlRequest({
-			endpoint,
-			query: addLineItemBySkuIdMutation$1,
-			variables: { input: buildAddLineItemBySkuIdInput(cartId, {
-				skuId: body.skuId,
-				name: body.name,
-				quantity: body.quantity
-			}) },
-			headers
-		});
-		const hydrated = await gqlRequest({
-			endpoint,
-			query: getCartOrderQuery,
-			variables: { id: cartId },
-			headers
-		});
-		res.status(201).json({ cart: hydrated.orderById ?? null });
-	} catch (error) {
-		res.status(500).json({
-			error: "Failed to add line item",
-			message: error instanceof Error ? error.message : String(error)
-		});
-	}
+async function addLineItem(req, res) {
+	const cartId = req.params.id;
+	if (typeof cartId !== "string" || !cartId) throw new InvalidRequestError("Missing cart id");
+	const body = req.body ?? {};
+	if (!body.skuId || !body.name || typeof body.quantity !== "number") throw new InvalidRequestError("Missing required fields: skuId, name, quantity");
+	const config = readCommerceConfigForResponse(res);
+	assertCommerceCartScope(req, config);
+	const { storeId, clientId, apiBaseUrl } = config;
+	const endpoint = orderStorefrontEndpoint({ apiBaseUrl });
+	const headers = storefrontHeaders({
+		storeId,
+		clientId
+	});
+	await gqlRequest({
+		endpoint,
+		query: addLineItemBySkuIdMutation$1,
+		variables: { input: buildAddLineItemBySkuIdInput(cartId, {
+			skuId: body.skuId,
+			name: body.name,
+			quantity: body.quantity
+		}) },
+		headers
+	});
+	const hydrated = await gqlRequest({
+		endpoint,
+		query: getCartOrderQuery,
+		variables: { id: cartId },
+		headers
+	});
+	res.status(201).json({ cart: hydrated.orderById ?? null });
 }
+var POST_default$1 = commerceRoute("Failed to add line item", addLineItem, { classifyUpstreamError: classifyCartUpstreamError });
 
 //#endregion
 //#region src/server/api/commerce/cart/POST.ts
@@ -1003,156 +1244,100 @@ const addLineItemBySkuIdMutation = `
     }
   }
 `;
-async function handler$5(req, res) {
-	try {
-		const body = req.body ?? {};
-		const initialItems = Array.isArray(body.lineItems) ? body.lineItems : [];
-		for (const item of initialItems) if (!item.skuId || !item.name || typeof item.quantity !== "number") {
-			res.status(400).json({ error: "Each lineItem must have skuId, a non-empty name, and a numeric quantity" });
-			return;
-		}
-		const config = readCommerceConfigForResponse(res);
-		if (!validateCommerceCartScope(req, res, config)) return;
-		const { storeId, channelId, clientId, apiBaseUrl, currencyCode } = config;
-		const endpoint = orderStorefrontEndpoint({ apiBaseUrl });
-		const headers = storefrontHeaders({
+async function createCart(req, res) {
+	const body = req.body ?? {};
+	const initialItems = Array.isArray(body.lineItems) ? body.lineItems : [];
+	for (const item of initialItems) if (!item.skuId || !item.name || typeof item.quantity !== "number") throw new InvalidRequestError("Each lineItem must have skuId, a non-empty name, and a numeric quantity");
+	const config = readCommerceConfigForResponse(res);
+	assertCommerceCartScope(req, config);
+	const { storeId, channelId, clientId, apiBaseUrl, currencyCode } = config;
+	const endpoint = orderStorefrontEndpoint({ apiBaseUrl });
+	const headers = storefrontHeaders({
+		storeId,
+		clientId
+	});
+	const newCartId = (await gqlRequest({
+		endpoint,
+		query: addCartOrderMutation,
+		variables: { input: buildEmptyCartOrderInput({
 			storeId,
-			clientId
-		});
-		const newCartId = (await gqlRequest({
-			endpoint,
-			query: addCartOrderMutation,
-			variables: { input: buildEmptyCartOrderInput({
-				storeId,
-				channelId,
-				owner: config.owner,
-				currencyCode: body.currencyCode ?? currencyCode
-			}) },
-			headers
-		})).addDraftOrder?.id;
-		if (!newCartId) {
-			res.status(500).json({ error: "Failed to create cart: missing id in mutation response" });
-			return;
-		}
-		for (const item of initialItems) await gqlRequest({
-			endpoint,
-			query: addLineItemBySkuIdMutation,
-			variables: { input: buildAddLineItemBySkuIdInput(newCartId, item) },
-			headers
-		});
-		const hydrated = await gqlRequest({
-			endpoint,
-			query: getCartOrderQuery,
-			variables: { id: newCartId },
-			headers
-		});
-		res.status(201).json({ cart: hydrated.orderById ?? null });
-	} catch (error) {
-		res.status(500).json({
-			error: "Failed to create cart",
-			message: error instanceof Error ? error.message : String(error)
-		});
-	}
+			channelId,
+			owner: config.owner,
+			currencyCode: body.currencyCode ?? currencyCode
+		}) },
+		headers
+	})).addDraftOrder?.id;
+	if (!newCartId) throw new UpstreamError("addDraftOrder response did not include a cart id");
+	for (const item of initialItems) await gqlRequest({
+		endpoint,
+		query: addLineItemBySkuIdMutation,
+		variables: { input: buildAddLineItemBySkuIdInput(newCartId, item) },
+		headers
+	});
+	const hydrated = await gqlRequest({
+		endpoint,
+		query: getCartOrderQuery,
+		variables: { id: newCartId },
+		headers
+	});
+	res.status(201).json({ cart: hydrated.orderById ?? null });
 }
+var POST_default$2 = commerceRoute("Failed to create cart", createCart);
 
 //#endregion
 //#region src/server/api/commerce/checkout/POST.ts
-async function handler$6(req, res) {
-	try {
-		const configuration = commerceConfigurationForResponse(res);
-		const { draftOrderId, skuId, quantity, lineItemData, returnUrl, successUrl } = req.body ?? {};
-		if (lineItemData !== void 0) {
-			res.status(400).json({ error: "Non-catalog checkout must be created by the server." });
-			return;
-		}
-		if ([draftOrderId, skuId].filter(Boolean).length !== 1 || [draftOrderId, skuId].some((value) => value !== void 0 && (typeof value !== "string" || !value.trim()))) {
-			res.status(400).json({ error: "exactly one non-empty draftOrderId or skuId is required" });
-			return;
-		}
-		if (quantity !== void 0 && (!Number.isSafeInteger(quantity) || quantity < 1)) {
-			res.status(400).json({ error: "quantity must be a positive whole number" });
-			return;
-		}
-		if (req.headers?.["x-commerce-scope"] !== void 0) {
-			assertCommerceConnectionReady(configuration);
-			if (!validateCommerceCartScope(req, res, configuration.read())) return;
-		}
-		const validateReturnUrls = res.locals.commerceCheckoutReturnUrlValidator;
-		if (!validateReturnUrls) {
-			res.status(503).json({ error: "Checkout return destinations are not configured." });
-			return;
-		}
-		const destinations = validateReturnUrls(returnUrl, successUrl);
-		if (!destinations) {
-			res.status(400).json({ error: "Checkout return destinations are not allowed." });
-			return;
-		}
-		const session = await createCheckoutSession({
-			draftOrderId,
-			skuId,
-			quantity,
-			...destinations
-		}, configuration);
-		res.status(200).json(session);
-	} catch (error) {
-		res.status(500).json({
-			error: "Failed to create checkout session",
-			message: error instanceof Error ? error.message : String(error)
-		});
-	}
+async function createCheckout(req, res) {
+	const configuration = commerceConfigurationForResponse(res);
+	const { draftOrderId, skuId, quantity, lineItemData, returnUrl, successUrl } = req.body ?? {};
+	if (lineItemData !== void 0) throw new InvalidRequestError("Non-catalog checkout must be created by the server.");
+	if ([draftOrderId, skuId].filter(Boolean).length !== 1 || [draftOrderId, skuId].some((value) => value !== void 0 && (typeof value !== "string" || !value.trim()))) throw new InvalidRequestError("exactly one non-empty draftOrderId or skuId is required");
+	if (quantity !== void 0 && (!Number.isSafeInteger(quantity) || quantity < 1)) throw new InvalidRequestError("quantity must be a positive whole number");
+	if (req.headers?.["x-commerce-scope"] !== void 0) assertCommerceCartScope(req, readReadyCommerceConfig(configuration));
+	const validateReturnUrls = res.locals.commerceCheckoutReturnUrlValidator;
+	if (!validateReturnUrls) throw new CommerceNotConfiguredError("Checkout return URLs are not configured on the router.", { publicMessage: "Checkout return destinations are not configured." });
+	const destinations = validateReturnUrls(returnUrl, successUrl);
+	if (!destinations) throw new InvalidRequestError("Checkout return destinations are not allowed.");
+	const session = await createCheckoutSession({
+		draftOrderId,
+		skuId,
+		quantity,
+		...destinations
+	}, configuration);
+	res.status(200).json(session);
 }
+var POST_default$3 = commerceRoute("Failed to create checkout session", createCheckout);
 
 //#endregion
 //#region src/server/api/commerce/config/GET.ts
-async function handler$7(_req, res) {
+async function readPublicConfig(_req, res) {
 	res.setHeader("Cache-Control", "no-store");
-	try {
-		const configuration = commerceConfigurationForResponse(res);
-		const state = configuration.readConnectionState?.();
-		if (state === "unbound" || state === "connecting") {
-			res.json({ state });
-			return;
-		}
-		if (state !== void 0 && state !== "ready") throw new Error("Invalid Commerce connection state.");
-		const config = configuration.read();
-		res.json({
-			...state === "ready" ? { state } : {},
-			cartScope: getCommerceCartScope(config),
-			currencyCode: config.currencyCode
-		});
-	} catch (cause) {
-		res.status(503).json({
-			error: "Commerce configuration is unavailable. Complete the store connection before continuing.",
-			message: cause instanceof Error ? cause.message : "Invalid Commerce configuration."
-		});
+	const configuration = commerceConfigurationForResponse(res);
+	const state = readCommerceConnectionState(configuration);
+	if (state === "unbound" || state === "connecting") {
+		res.json({ state });
+		return;
 	}
+	const config = readReadyCommerceConfig(configuration);
+	res.json({
+		...state === "ready" ? { state } : {},
+		cartScope: getCommerceCartScope(config),
+		currencyCode: config.currencyCode
+	});
 }
+var GET_default$1 = commerceRoute("Failed to load Commerce configuration", readPublicConfig);
 
 //#endregion
 //#region src/server/api/commerce/order-status/GET.ts
-async function handler$8(req, res) {
-	try {
-		const { orderId } = req.query;
-		if (!orderId || typeof orderId !== "string") {
-			res.status(400).json({
-				success: false,
-				error: "missing or invalid orderId query parameter"
-			});
-			return;
-		}
-		const order = await getOrderStatus(orderId, commerceConfigurationForResponse(res));
-		res.status(200).json({
-			success: true,
-			order
-		});
-	} catch (error) {
-		res.status(500).json({
-			success: false,
-			error: "Failed to get order status",
-			message: error instanceof Error ? error.message : String(error)
-		});
-	}
+async function readOrderStatus(req, res) {
+	const { orderId } = req.query;
+	if (typeof orderId !== "string") throw new InvalidOrderIdError();
+	const order = await getOrderStatus(orderId, commerceConfigurationForResponse(res));
+	res.status(200).json({
+		success: true,
+		order
+	});
 }
+var GET_default$2 = commerceRoute("Failed to get order status", readOrderStatus, { failureFields: { success: false } });
 
 //#endregion
 //#region src/lib/commerce/catalog-subgraph.ts
@@ -1275,45 +1460,33 @@ function asNumber$1(value) {
 	const n = Number(value);
 	return Number.isFinite(n) ? n : void 0;
 }
-async function handler$9(req, res) {
-	try {
-		const productId = req.params.id;
-		if (typeof productId !== "string" || !productId) {
-			res.status(400).json({ error: "Missing product id" });
-			return;
-		}
-		const config = readCommerceConfigForResponse(res);
-		if (!validateCommerceCartScope(req, res, config)) return;
-		const { storeId, clientId, apiBaseUrl } = config;
-		const variables = buildSkuGroupVariables({
-			productId,
-			selectedAttributeValues: asStringArray$1(req.query.attributeValues),
-			skuGroupFirst: asNumber$1(req.query.skuGroupFirst)
-		});
-		const data = await gqlRequest({
-			endpoint: catalogStorefrontEndpoint({
-				storeId,
-				apiBaseUrl
-			}),
-			query: skuGroupQuery,
-			variables,
-			headers: storefrontHeaders({
-				storeId,
-				clientId
-			})
-		});
-		if (!data.skuGroup || !data.activeSkuGroups?.edges?.some((edge) => edge?.node?.id === productId)) {
-			res.status(404).json({ error: "Product not found" });
-			return;
-		}
-		res.json({ skuGroup: data.skuGroup });
-	} catch (error) {
-		res.status(500).json({
-			error: "Failed to load product",
-			message: error instanceof Error ? error.message : String(error)
-		});
-	}
+async function readProduct(req, res) {
+	const productId = req.params.id;
+	if (typeof productId !== "string" || !productId) throw new InvalidRequestError("Missing product id");
+	const config = readCommerceConfigForResponse(res);
+	assertCommerceCartScope(req, config);
+	const { storeId, clientId, apiBaseUrl } = config;
+	const variables = buildSkuGroupVariables({
+		productId,
+		selectedAttributeValues: asStringArray$1(req.query.attributeValues),
+		skuGroupFirst: asNumber$1(req.query.skuGroupFirst)
+	});
+	const data = await gqlRequest({
+		endpoint: catalogStorefrontEndpoint({
+			storeId,
+			apiBaseUrl
+		}),
+		query: skuGroupQuery,
+		variables,
+		headers: storefrontHeaders({
+			storeId,
+			clientId
+		})
+	});
+	if (!data.skuGroup || !data.activeSkuGroups?.edges?.some((edge) => edge?.node?.id === productId)) throw new NotFoundError("Product not found");
+	res.json({ skuGroup: data.skuGroup });
 }
+var GET_default$3 = commerceRoute("Failed to load product", readProduct);
 
 //#endregion
 //#region src/server/api/commerce/products/GET.ts
@@ -1414,38 +1587,32 @@ function asNumber(value) {
 	const n = Number(value);
 	return Number.isFinite(n) ? n : void 0;
 }
-async function handler$10(req, res) {
-	try {
-		const config = readCommerceConfigForResponse(res);
-		if (!validateCommerceCartScope(req, res, config)) return;
-		const { storeId, clientId, apiBaseUrl } = config;
-		const variables = buildSkuGroupsVariables({
-			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,
-			productIds: asStringArray(req.query.productIds),
-			categoryIds: asStringArray(req.query.categoryIds)
-		});
-		const data = await gqlRequest({
-			endpoint: catalogStorefrontEndpoint({
-				storeId,
-				apiBaseUrl
-			}),
-			query: skuGroupsQuery,
-			variables,
-			headers: storefrontHeaders({
-				storeId,
-				clientId
-			})
-		});
-		res.json(data);
-	} catch (error) {
-		res.status(500).json({
-			error: "Failed to load products",
-			message: error instanceof Error ? error.message : String(error)
-		});
-	}
+async function listProducts(req, res) {
+	const config = readCommerceConfigForResponse(res);
+	assertCommerceCartScope(req, config);
+	const { storeId, clientId, apiBaseUrl } = config;
+	const variables = buildSkuGroupsVariables({
+		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,
+		productIds: asStringArray(req.query.productIds),
+		categoryIds: asStringArray(req.query.categoryIds)
+	});
+	const data = await gqlRequest({
+		endpoint: catalogStorefrontEndpoint({
+			storeId,
+			apiBaseUrl
+		}),
+		query: skuGroupsQuery,
+		variables,
+		headers: storefrontHeaders({
+			storeId,
+			clientId
+		})
+	});
+	res.json(data);
 }
+var GET_default$4 = commerceRoute("Failed to load products", listProducts);
 
 //#endregion
 //#region src/server/api/commerce/skus/[id]/GET.ts
@@ -1505,36 +1672,27 @@ const skuQuery = `
     }
   }
 `;
-async function handler$11(req, res) {
-	try {
-		const skuId = req.params.id;
-		if (typeof skuId !== "string" || !skuId) {
-			res.status(400).json({ error: "Missing sku id" });
-			return;
-		}
-		const config = readCommerceConfigForResponse(res);
-		if (!validateCommerceCartScope(req, res, config)) return;
-		const { storeId, clientId, apiBaseUrl } = config;
-		const data = await gqlRequest({
-			endpoint: catalogStorefrontEndpoint({
-				storeId,
-				apiBaseUrl
-			}),
-			query: skuQuery,
-			variables: { id: skuId },
-			headers: storefrontHeaders({
-				storeId,
-				clientId
-			})
-		});
-		res.json(data);
-	} catch (error) {
-		res.status(500).json({
-			error: "Failed to load sku",
-			message: error instanceof Error ? error.message : String(error)
-		});
-	}
+async function readSku(req, res) {
+	const skuId = req.params.id;
+	if (typeof skuId !== "string" || !skuId) throw new InvalidRequestError("Missing sku id");
+	const config = readCommerceConfigForResponse(res);
+	assertCommerceCartScope(req, config);
+	const { storeId, clientId, apiBaseUrl } = config;
+	const data = await gqlRequest({
+		endpoint: catalogStorefrontEndpoint({
+			storeId,
+			apiBaseUrl
+		}),
+		query: skuQuery,
+		variables: { id: skuId },
+		headers: storefrontHeaders({
+			storeId,
+			clientId
+		})
+	});
+	res.json(data);
 }
+var GET_default$5 = commerceRoute("Failed to load sku", readSku);
 
 //#endregion
 //#region src/router.ts
@@ -1543,32 +1701,39 @@ function createCommerceRouter(options = {}) {
 	const configuration = options.configuration ?? createRuntimeCommerceConfiguration();
 	const catalogEnabled = options.features?.catalog ?? true;
 	const paymentsEnabled = options.features?.payments ?? true;
+	const logger = options.logger ?? consoleCommerceLogger;
 	const validateCheckoutReturnUrls = options.checkoutReturnUrls ? createCheckoutReturnUrlValidator(options.checkoutReturnUrls) : void 0;
 	router.use((_req, res, next) => {
+		const observability = {
+			commerceLogger: logger,
+			commerceRequestIdResolver: options.getRequestId
+		};
+		Object.assign(res.locals, observability);
 		res.locals.commerceConfiguration = configuration;
 		res.locals.commerceCheckoutReturnUrlValidator = validateCheckoutReturnUrls;
 		next();
 	});
 	if (catalogEnabled) {
-		router.get("/config", handler$7);
-		router.get("/products", handler$10);
-		router.get("/products/:id", handler$9);
-		router.get("/skus/:id", handler$11);
-		router.post("/cart", handler$5);
-		router.get("/cart/:id", handler$1);
-		router.post("/cart/:id/items", handler$4);
-		router.patch("/cart/:id/items/:itemId", handler$3);
-		router.delete("/cart/:id/items/:itemId", handler$2);
-		router.post("/cart/:id/discounts", handler);
+		router.get("/config", GET_default$1);
+		router.get("/products", GET_default$4);
+		router.get("/products/:id", GET_default$3);
+		router.get("/skus/:id", GET_default$5);
+		router.post("/cart", POST_default$2);
+		router.get("/cart/:id", GET_default);
+		router.post("/cart/:id/items", POST_default$1);
+		router.patch("/cart/:id/items/:itemId", PATCH_default);
+		router.delete("/cart/:id/items/:itemId", DELETE_default);
+		router.post("/cart/:id/discounts", POST_default);
 	}
 	if (paymentsEnabled) {
-		router.post("/checkout", handler$6);
-		router.get("/order-status", handler$8);
+		router.post("/checkout", POST_default$3);
+		router.get("/order-status", GET_default$2);
 	}
 	return router;
 }
-function createCommerceCatalogRouter(configuration) {
+function createCommerceCatalogRouter(configuration, observability = {}) {
 	return createCommerceRouter({
+		...observability,
 		configuration,
 		features: {
 			catalog: true,
@@ -1576,8 +1741,9 @@ function createCommerceCatalogRouter(configuration) {
 		}
 	});
 }
-function createGoDaddyPaymentsRouter(configuration, checkoutReturnUrls) {
+function createGoDaddyPaymentsRouter(configuration, checkoutReturnUrls, observability = {}) {
 	return createCommerceRouter({
+		...observability,
 		configuration,
 		checkoutReturnUrls,
 		features: {
@@ -1588,4 +1754,4 @@ function createGoDaddyPaymentsRouter(configuration, checkoutReturnUrls) {
 }
 
 //#endregion
-export { createCheckoutSession, createCommerceCatalogRouter, createCommerceRouter, createGoDaddyPaymentsRouter, createRuntimeCommerceConfiguration, getOrderStatus, parseCommerceCheckoutConfiguration, readCommerceConfig };
+export { CommerceError, CommerceNotConfiguredError, InvalidOrderIdError, InvalidRequestError, NotFoundError, ORDER_STATUS_UNKNOWN, OrderNotFoundError, ScopeMismatchError, UpstreamError, createCheckoutSession, createCommerceCatalogRouter, createCommerceRouter, createGoDaddyPaymentsRouter, createRuntimeCommerceConfiguration, getOrderStatus, parseCommerceCheckoutConfiguration, readCommerceConfig };