@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

package/dist/core/request-routing/handle-shopify-redirects.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"handle-shopify-redirects.mjs","names":[],"sources":["../../../src/core/request-routing/handle-shopify-redirects.ts"],"sourcesContent":["import type { StorefrontClient } from \"../../client\";\nimport { getLogger } from \"../logging\";\nimport type { ShopifyRouteTemplates } from \"../standard-routes/index\";\nimport { handleAdminRedirect } from \"./interceptors/admin-redirect\";\nimport { handleQueryParamRedirect } from \"./interceptors/query-param-redirect\";\nimport { handleStandardRouteRedirects } from \"./interceptors/standard-routes\";\nimport { handleUrlRedirects } from \"./interceptors/url-redirects\";\nimport { safeApplyResponseHeaders } from \"./safe-apply-response-headers\";\n\nconst log = getLogger(\"redirects\");\n\nexport type RedirectOptions = {\n  request: Request;\n  storefrontClient: StorefrontClient;\n  routeTemplates: ShopifyRouteTemplates;\n};\n\n/**\n * Resolves Shopify redirects after framework routing returns a 404. Matched\n * responses already include request-context response headers.\n */\nexport async function handleShopifyRedirects(options: RedirectOptions): Promise<Response | null> {\n  const { request, storefrontClient } = options;\n  let redirect: Response | null = null;\n\n  try {\n    redirect = handleAdminRedirect(options);\n    redirect ??= handleStandardRouteRedirects(options);\n    redirect ??= handleQueryParamRedirect(request);\n    redirect ??= await handleUrlRedirects(options);\n  } catch (error) {\n    const url = new URL(request.url);\n    log.error(`failed to resolve Shopify redirects for route ${url.pathname}`, { error });\n  }\n\n  return redirect ? safeApplyResponseHeaders(redirect, storefrontClient.requestContext) : null;\n}\n"],"mappings":";;;;;;;;AASA,MAAM,MAAM,UAAU,YAAY;;;;;AAYlC,eAAsB,uBAAuB,SAAoD;CAC/F,MAAM,EAAE,SAAS,qBAAqB;CACtC,IAAI,WAA4B;AAEhC,KAAI;AACF,aAAW,oBAAoB,QAAQ;AACvC,eAAa,6BAA6B,QAAQ;AAClD,eAAa,yBAAyB,QAAQ;AAC9C,eAAa,MAAM,mBAAmB,QAAQ;UACvC,OAAO;EACd,MAAM,MAAM,IAAI,IAAI,QAAQ,IAAI;AAChC,MAAI,MAAM,iDAAiD,IAAI,YAAY,EAAE,OAAO,CAAC;;AAGvF,QAAO,WAAW,yBAAyB,UAAU,iBAAiB,eAAe,GAAG"}
+{"version":3,"file":"handle-shopify-redirects.mjs","names":[],"sources":["../../../src/core/request-routing/handle-shopify-redirects.ts"],"sourcesContent":["import type { StorefrontClient } from \"../../client\";\nimport { getLogger } from \"../logging\";\nimport type { ShopifyRouteTemplates } from \"../standard-routes/index\";\nimport { handleAdminRedirect } from \"./interceptors/admin-redirect\";\nimport { handleQueryParamRedirect } from \"./interceptors/query-param-redirect\";\nimport { handleStandardRouteRedirects } from \"./interceptors/standard-routes\";\nimport { handleUrlRedirects } from \"./interceptors/url-redirects\";\nimport { safeApplyResponseHeaders } from \"./safe-apply-response-headers\";\n\nconst log = getLogger(\"redirects\");\n\n/** The unmatched request, the Storefront API client, and your app's route templates. */\nexport type RedirectOptions = {\n  /** The request that your framework's router answered with a `404` response. */\n  request: Request;\n  /** The Storefront API client for the current request. Hydrogen looks up the store's URL redirects with the client, and reads the locale path prefix from the client's request context. */\n  storefrontClient: StorefrontClient;\n  /** Your app's route templates. Hydrogen redirects Shopify's default resource paths to these templates. */\n  routeTemplates: ShopifyRouteTemplates;\n};\n\n/**\n * Finds the Shopify redirect for a request that your framework's router can't match. Call the\n * function when the router returns a `404` response, and return that `404` response when the function\n * resolves to `null`.\n *\n * The function checks these redirects in order and returns the first match as a `301` response: `/admin` to the store's admin, Shopify's default resource paths to your route templates, same-origin `return_to` and `redirect` query parameters, and the store's URL redirects. The response already carries the request context's headers. When a redirect lookup fails, the function logs the error and resolves to `null`.\n *\n * @param options The unmatched request, the Storefront API client, and your app's route templates.\n * @returns A promise for the matched redirect response, or `null` when no redirect matches.\n * @publicDocs\n */\nexport async function handleShopifyRedirects(options: RedirectOptions): Promise<Response | null> {\n  const { request, storefrontClient } = options;\n  let redirect: Response | null = null;\n\n  try {\n    redirect = handleAdminRedirect(options);\n    redirect ??= handleStandardRouteRedirects(options);\n    redirect ??= handleQueryParamRedirect(request);\n    redirect ??= await handleUrlRedirects(options);\n  } catch (error) {\n    const url = new URL(request.url);\n    log.error(`failed to resolve Shopify redirects for route ${url.pathname}`, { error });\n  }\n\n  return redirect ? safeApplyResponseHeaders(redirect, storefrontClient.requestContext) : null;\n}\n"],"mappings":";;;;;;;;AASA,MAAM,MAAM,UAAU,YAAY;;;;;;;;;;;;AAuBlC,eAAsB,uBAAuB,SAAoD;CAC/F,MAAM,EAAE,SAAS,qBAAqB;CACtC,IAAI,WAA4B;AAEhC,KAAI;AACF,aAAW,oBAAoB,QAAQ;AACvC,eAAa,6BAA6B,QAAQ;AAClD,eAAa,yBAAyB,QAAQ;AAC9C,eAAa,MAAM,mBAAmB,QAAQ;UACvC,OAAO;EACd,MAAM,MAAM,IAAI,IAAI,QAAQ,IAAI;AAChC,MAAI,MAAM,iDAAiD,IAAI,YAAY,EAAE,OAAO,CAAC;;AAGvF,QAAO,WAAW,yBAAyB,UAAU,iBAAiB,eAAe,GAAG"}

package/dist/core/request-routing/handle-shopify-routes.d.mts

@@ -2,11 +2,11 @@ import { HydrogenRouteHandler } from "./route-types.mjs";
 
 //#region src/core/request-routing/handle-shopify-routes.d.ts
 /**
- * Matches a request against Shopify standard routes and any registered handler
- * groups, returning a raw `Response` (redirect or JSON) when one matches, or
- * `null` when none do. Use it as the first step of request handling, before
- * framework routing. Matched responses already include request-context
- * response headers.
+ * Serves Shopify's storefront endpoints and your custom route handlers.
+ * Returns a promise for the matched response, or `null` when no route matches.
+ * The matched response already carries the request context's headers.
+ *
+ * @publicDocs
  */
 declare const handleShopifyRoutes: HydrogenRouteHandler;
 //#endregion

package/dist/core/request-routing/handle-shopify-routes.mjs

@@ -6,6 +6,7 @@ import { handleBuyPermalinkRedirect, handleCheckoutRedirect } from "./intercepto
 import { handleMcpProxy } from "./interceptors/mcp-proxy.mjs";
 import { handleSfapiProxy } from "./interceptors/sfapi-proxy.mjs";
 import { handleUcpMcpProxy } from "./interceptors/ucp-mcp-proxy.mjs";
+import { handleUcpProfileProxy } from "./interceptors/ucp-profile-proxy.mjs";
 import { handleWellKnownProxy } from "./interceptors/well-known.mjs";
 import { handleShopifyRouteHandlers } from "./registered-routes.mjs";
 
@@ -17,17 +18,18 @@ const SHOPIFY_ROUTE_INTERCEPTORS = [
 	handleShopifyRouteHandlers,
 	handleBuyPermalinkRedirect,
 	handleCheckoutRedirect,
+	handleUcpProfileProxy,
 	handleWellKnownProxy,
 	handleUcpMcpProxy,
 	handleMcpProxy,
 	handleAjaxApi
 ];
 /**
-* Matches a request against Shopify standard routes and any registered handler
-* groups, returning a raw `Response` (redirect or JSON) when one matches, or
-* `null` when none do. Use it as the first step of request handling, before
-* framework routing. Matched responses already include request-context
-* response headers.
+* Serves Shopify's storefront endpoints and your custom route handlers.
+* Returns a promise for the matched response, or `null` when no route matches.
+* The matched response already carries the request context's headers.
+*
+* @publicDocs
 */
 const handleShopifyRoutes = (options) => {
 	if (options.requestContext !== options.storefrontClient.requestContext) throw new Error("handleShopifyRoutes must receive the same requestContext used by storefrontClient.");

package/dist/core/request-routing/handle-shopify-routes.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"handle-shopify-routes.mjs","names":[],"sources":["../../../src/core/request-routing/handle-shopify-routes.ts"],"sourcesContent":["import { handleProductVariantId } from \"../product/accept-variant-id\";\nimport { handleAjaxApi } from \"./interceptors/ajax-api\";\nimport { handleShopifyApiProxy } from \"./interceptors/api-proxy\";\nimport { handleBuyPermalinkRedirect, handleCheckoutRedirect } from \"./interceptors/checkout\";\nimport { handleMcpProxy } from \"./interceptors/mcp-proxy\";\nimport { handleSfapiProxy } from \"./interceptors/sfapi-proxy\";\nimport { handleUcpMcpProxy } from \"./interceptors/ucp-mcp-proxy\";\nimport { handleWellKnownProxy } from \"./interceptors/well-known\";\nimport { handleShopifyRouteHandlers } from \"./registered-routes\";\nimport type { HydrogenRouteHandler, HydrogenRouteInterceptor } from \"./route-types\";\nimport { safeApplyResponseHeaders } from \"./safe-apply-response-headers\";\n\nconst SHOPIFY_ROUTE_INTERCEPTORS = [\n  handleShopifyApiProxy,\n  handleSfapiProxy,\n  handleProductVariantId,\n  handleShopifyRouteHandlers,\n  handleBuyPermalinkRedirect,\n  handleCheckoutRedirect,\n  handleWellKnownProxy,\n  handleUcpMcpProxy,\n  handleMcpProxy,\n  handleAjaxApi,\n] satisfies readonly HydrogenRouteInterceptor[];\n\n/**\n * Matches a request against Shopify standard routes and any registered handler\n * groups, returning a raw `Response` (redirect or JSON) when one matches, or\n * `null` when none do. Use it as the first step of request handling, before\n * framework routing. Matched responses already include request-context\n * response headers.\n */\nexport const handleShopifyRoutes: HydrogenRouteHandler = (options) => {\n  if (options.requestContext !== options.storefrontClient.requestContext) {\n    throw new Error(\n      \"handleShopifyRoutes must receive the same requestContext used by storefrontClient.\",\n    );\n  }\n\n  const url = new URL(options.request.url);\n\n  for (const interceptor of SHOPIFY_ROUTE_INTERCEPTORS) {\n    const responsePromise = interceptor(url, options);\n    if (!responsePromise) continue;\n\n    return responsePromise.then((response) =>\n      safeApplyResponseHeaders(response, options.requestContext),\n    );\n  }\n\n  return null;\n};\n"],"mappings":";;;;;;;;;;;;AAYA,MAAM,6BAA6B;CACjC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;AASD,MAAa,uBAA6C,YAAY;AACpE,KAAI,QAAQ,mBAAmB,QAAQ,iBAAiB,eACtD,OAAM,IAAI,MACR,qFACD;CAGH,MAAM,MAAM,IAAI,IAAI,QAAQ,QAAQ,IAAI;AAExC,MAAK,MAAM,eAAe,4BAA4B;EACpD,MAAM,kBAAkB,YAAY,KAAK,QAAQ;AACjD,MAAI,CAAC,gBAAiB;AAEtB,SAAO,gBAAgB,MAAM,aAC3B,yBAAyB,UAAU,QAAQ,eAAe,CAC3D;;AAGH,QAAO"}
+{"version":3,"file":"handle-shopify-routes.mjs","names":[],"sources":["../../../src/core/request-routing/handle-shopify-routes.ts"],"sourcesContent":["import { handleProductVariantId } from \"../product/accept-variant-id\";\nimport { handleAjaxApi } from \"./interceptors/ajax-api\";\nimport { handleShopifyApiProxy } from \"./interceptors/api-proxy\";\nimport { handleBuyPermalinkRedirect, handleCheckoutRedirect } from \"./interceptors/checkout\";\nimport { handleMcpProxy } from \"./interceptors/mcp-proxy\";\nimport { handleSfapiProxy } from \"./interceptors/sfapi-proxy\";\nimport { handleUcpMcpProxy } from \"./interceptors/ucp-mcp-proxy\";\nimport { handleUcpProfileProxy } from \"./interceptors/ucp-profile-proxy\";\nimport { handleWellKnownProxy } from \"./interceptors/well-known\";\nimport { handleShopifyRouteHandlers } from \"./registered-routes\";\nimport type {\n  HydrogenRouteHandler,\n  HydrogenRouteInterceptor,\n  HydrogenRoutesOptions,\n} from \"./route-types\";\nimport { safeApplyResponseHeaders } from \"./safe-apply-response-headers\";\n\nconst SHOPIFY_ROUTE_INTERCEPTORS = [\n  handleShopifyApiProxy,\n  handleSfapiProxy,\n  handleProductVariantId,\n  handleShopifyRouteHandlers,\n  handleBuyPermalinkRedirect,\n  handleCheckoutRedirect,\n  handleUcpProfileProxy,\n  handleWellKnownProxy,\n  handleUcpMcpProxy,\n  handleMcpProxy,\n  handleAjaxApi,\n] satisfies readonly HydrogenRouteInterceptor[];\n\n/**\n * Serves Shopify's storefront endpoints and your custom route handlers.\n * Returns a promise for the matched response, or `null` when no route matches.\n * The matched response already carries the request context's headers.\n *\n * @publicDocs\n */\nexport const handleShopifyRoutes: HydrogenRouteHandler = (options) => {\n  if (options.requestContext !== options.storefrontClient.requestContext) {\n    throw new Error(\n      \"handleShopifyRoutes must receive the same requestContext used by storefrontClient.\",\n    );\n  }\n\n  const url = new URL(options.request.url);\n\n  for (const interceptor of SHOPIFY_ROUTE_INTERCEPTORS) {\n    const responsePromise = interceptor(url, options);\n    if (!responsePromise) continue;\n\n    return responsePromise.then((response) =>\n      safeApplyResponseHeaders(response, options.requestContext),\n    );\n  }\n\n  return null;\n};\n\n/**\n * Serves Shopify's storefront endpoints and your custom route handlers from your app. Call the function at the start of request handling, before your framework's router.\n *\n * When a route matches, the function returns a promise for the response. Return that response as is, because the response already carries the request context's headers. When no route matches, the function returns `null` synchronously, and your framework's router handles the request. The function throws when `requestContext` differs from the Storefront API client's request context. When a route handler throws, the returned promise rejects. Inside a `try` block, use `return await` on the result.\n *\n * The function checks these routes in order and returns the first match: the Shopify API proxy at `/__shopify`, the Storefront API proxy at `/api/{version}/graphql.json`, Liquid-style `?variant=` product URLs, registered handler groups, UCP buy permalinks at `/buy/...`, checkout and cart permalinks, allowlisted `.well-known` resources, the UCP MCP proxy at `/api/ucp/mcp`, the MCP proxy at `/api/mcp`, and AJAX cart URLs.\n *\n * Some routes answer unsupported methods with a `405` response. A registered handler path returns `405` for any method that no handler on that path registers. Checkout and cart permalinks accept only `GET` and `HEAD`. Buy permalinks accept only `GET`, and the UCP MCP proxy accepts only `POST`.\n *\n * When your bundler resolves the package's `development` export condition, the function also serves the GraphiQL explorer at `/graphiql` for GET requests that match no other route, and accepts a `graphiql` option. Set `graphiql.customerAccount` to an object with `apiUrl`, `accessToken`, and `schemaUrl` to add a Customer Account API tab. The explorer skips the tab when it can't fetch the schema.\n *\n * @publicDocs\n */\nexport type HandleShopifyRoutesForDocs =\n  /**\n   * @param options - The request, its context and session, the Storefront API client, your route templates, and your handler groups.\n   * @returns A promise for the matched route's response, or `null` when no route matches.\n   */\n  (options: HydrogenRoutesOptions) => null | Promise<Response>;\n"],"mappings":";;;;;;;;;;;;;AAiBA,MAAM,6BAA6B;CACjC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;AASD,MAAa,uBAA6C,YAAY;AACpE,KAAI,QAAQ,mBAAmB,QAAQ,iBAAiB,eACtD,OAAM,IAAI,MACR,qFACD;CAGH,MAAM,MAAM,IAAI,IAAI,QAAQ,QAAQ,IAAI;AAExC,MAAK,MAAM,eAAe,4BAA4B;EACpD,MAAM,kBAAkB,YAAY,KAAK,QAAQ;AACjD,MAAI,CAAC,gBAAiB;AAEtB,SAAO,gBAAgB,MAAM,aAC3B,yBAAyB,UAAU,QAAQ,eAAe,CAC3D;;AAGH,QAAO"}

package/dist/core/request-routing/interceptors/proxy.mjs

@@ -8,16 +8,13 @@ function createProxyInterceptor(descriptor) {
 	const log = getLogger(descriptor.scope);
 	const formatError = descriptor.formatError ?? defaultFormatError;
 	return (url, options) => {
-		const { request, storefrontClient } = options;
+		const { request } = options;
 		if (!descriptor.match.test(url.pathname)) return null;
-		if (url.searchParams.has("callback")) return Promise.resolve(new Response(JSON.stringify(formatError("JSONP requests are not supported")), {
+		if (url.searchParams.has("callback")) return Promise.resolve(createProxyRejectionResponse({
 			status: 400,
-			headers: {
-				"content-type": "application/json",
-				"cache-control": PROXY_ERROR_CACHE_CONTROL
-			}
-		}));
-		if (descriptor.methods && !descriptor.methods.includes(request.method)) return Promise.resolve(new Response(JSON.stringify(formatError("Method Not Allowed")), {
+			body: formatError("JSONP requests are not supported")
+		}, request.method));
+		if (descriptor.methods && !descriptor.methods.includes(request.method)) return Promise.resolve(new Response(request.method === "HEAD" ? null : JSON.stringify(formatError("Method Not Allowed")), {
 			status: 405,
 			headers: {
 				allow: descriptor.methods.join(", "),
@@ -25,52 +22,80 @@ function createProxyInterceptor(descriptor) {
 				"cache-control": PROXY_ERROR_CACHE_CONTROL
 			}
 		}));
-		let upstreamUrl;
-		let init;
+		let requestInit;
 		try {
-			const upstreamPathname = descriptor.rewritePathname?.(url.pathname) ?? url.pathname;
-			upstreamUrl = new URL(upstreamPathname + url.search, storefrontClient.storeUrl);
-			init = {
-				method: request.method,
-				body: request.body,
-				headers: createProxyRequestHeaders(descriptor, {
-					...options,
-					url
-				}),
-				signal: AbortSignal.timeout(PROXY_TIMEOUT_MS),
-				redirect: descriptor.redirect ?? "manual"
-			};
-			if (request.body) init.duplex = "half";
+			requestInit = createProxyRequestInit(descriptor, options, url);
 		} catch (error) {
 			log.error("request failed", { error });
-			return Promise.resolve(createProxyErrorResponse(error, 500, formatError));
+			return Promise.resolve(createProxyErrorResponse(error, "setup", descriptor.mapError, formatError, request.method));
 		}
-		return fetch(upstreamUrl, init).then((upstreamResponse) => {
-			const headers = createProxyResponseHeaders(upstreamResponse.headers);
-			descriptor.responseHeaders?.prepare?.(headers, {
-				...options,
-				url,
-				response: upstreamResponse
-			});
-			options.requestContext.consumeStorefrontResponseHeaders(headers);
-			return new Response(upstreamResponse.body, {
-				status: upstreamResponse.status,
-				statusText: upstreamResponse.statusText,
-				headers
-			});
-		}).catch((error) => {
+		return fetch(requestInit.upstreamUrl, requestInit.init).then((upstreamResponse) => buildProxyResponse(upstreamResponse, descriptor, options, url, log)).catch((error) => {
 			log.error("request failed", { error });
-			return createProxyErrorResponse(error, 502, formatError);
+			return createProxyErrorResponse(error, "fetch", descriptor.mapError, formatError, request.method);
 		});
 	};
 }
+function createProxyRequestInit(descriptor, options, url) {
+	const { request, storefrontClient } = options;
+	const upstreamPathname = descriptor.rewritePathname?.(url.pathname) ?? url.pathname;
+	const search = descriptor.forwardSearch === false ? "" : url.search;
+	const upstreamUrl = new URL(upstreamPathname + search, storefrontClient.storeUrl);
+	const init = {
+		method: request.method,
+		body: request.body,
+		headers: createProxyRequestHeaders(descriptor, {
+			...options,
+			url
+		}),
+		signal: AbortSignal.timeout(descriptor.timeoutMs ?? PROXY_TIMEOUT_MS),
+		redirect: descriptor.redirect ?? "manual"
+	};
+	if (request.body) init.duplex = "half";
+	return {
+		upstreamUrl,
+		init
+	};
+}
+function buildProxyResponse(upstreamResponse, descriptor, options, url, log) {
+	const upstream = {
+		ok: upstreamResponse.ok,
+		status: upstreamResponse.status,
+		statusText: upstreamResponse.statusText,
+		headers: upstreamResponse.headers
+	};
+	const rejection = descriptor.responseValidation?.(upstream, options, url);
+	if (rejection) {
+		upstreamResponse.body?.cancel().catch(() => {});
+		if (rejection.logMessage) log.error(rejection.logMessage, rejection.log ?? {});
+		return createProxyRejectionResponse(rejection, options.request.method);
+	}
+	const headers = buildProxyResponseHeaders(upstreamResponse.headers, descriptor.responseHeaders?.allow);
+	descriptor.responseHeaders?.prepare?.(headers, {
+		...options,
+		url,
+		response: upstream
+	});
+	options.requestContext.consumeStorefrontResponseHeaders(headers);
+	return new Response(upstreamResponse.body, {
+		status: upstreamResponse.status,
+		statusText: upstreamResponse.statusText,
+		headers
+	});
+}
 function defaultFormatError(message) {
 	return { error: message };
 }
-function createProxyErrorResponse(error, status, formatError) {
+function createProxyErrorResponse(error, phase, mapError, formatError, method) {
 	const message = error instanceof Error ? error.message : "Internal proxy error";
-	return new Response(JSON.stringify(formatError(message)), {
-		status,
+	const mapping = mapError?.(error, phase);
+	return createProxyRejectionResponse({
+		status: mapping?.status ?? (phase === "setup" ? 500 : 502),
+		body: mapping?.body === void 0 ? formatError(message) : mapping.body
+	}, method);
+}
+function createProxyRejectionResponse(rejection, method) {
+	return new Response(method === "HEAD" ? null : JSON.stringify(rejection.body), {
+		status: rejection.status,
 		headers: {
 			"content-type": "application/json",
 			"cache-control": PROXY_ERROR_CACHE_CONTROL
@@ -81,11 +106,22 @@ function createProxyRequestHeaders(descriptor, options) {
 	const { request, requestContext } = options;
 	const { allow, deny, prepare } = descriptor.requestHeaders;
 	const headers = allow ? new Headers(extractHeaders((key) => request.headers.get(key), allow)) : new Headers(request.headers);
-	requestContext.applyStorefrontRequestHeaders(headers);
+	if (descriptor.requestHeaders.applyStorefrontHeaders !== false) requestContext.applyStorefrontRequestHeaders(headers);
 	for (const header of deny ?? []) headers.delete(header);
 	prepare?.(headers, options);
 	return headers;
 }
+function buildProxyResponseHeaders(upstreamHeaders, allow) {
+	if (allow) {
+		const headers = new Headers();
+		for (const name of allow) {
+			const value = upstreamHeaders.get(name);
+			if (value !== null) headers.set(name, value);
+		}
+		return headers;
+	}
+	return createProxyResponseHeaders(upstreamHeaders);
+}
 function createProxyResponseHeaders(upstreamHeaders) {
 	const headers = new Headers(upstreamHeaders);
 	headers.delete("content-encoding");

package/dist/core/request-routing/interceptors/proxy.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"proxy.mjs","names":[],"sources":["../../../../src/core/request-routing/interceptors/proxy.ts"],"sourcesContent":["import { extractHeaders } from \"../../headers\";\nimport { getLogger } from \"../../logging\";\nimport type { HydrogenRouteInterceptor, HydrogenRoutesOptions } from \"../route-types\";\n\nconst PROXY_TIMEOUT_MS = 30_000;\n\n// Proxy errors are transient and may be buyer-specific: never cache them.\nconst PROXY_ERROR_CACHE_CONTROL = \"no-store\";\n\ntype ProxyHeaderContext = HydrogenRoutesOptions & { url: URL };\n\ntype PrepareHeaders<ExtraContext extends object = object> = (\n  headers: Headers,\n  context: ProxyHeaderContext & ExtraContext,\n) => void;\n\ntype ProxyRequestHeaderOptions = (\n  | { allow: readonly string[]; deny?: never }\n  | { allow?: never; deny: readonly string[] }\n) & {\n  prepare?: PrepareHeaders;\n};\n\ntype ProxyResponseHeaderOptions = {\n  prepare?: PrepareHeaders<{ response: Response }>;\n};\n\ntype ProxyDescriptor = {\n  match: RegExp;\n  methods?: readonly string[];\n  formatError?: (message: string) => unknown;\n  redirect?: RequestRedirect;\n  scope: string;\n  rewritePathname?: (pathname: string) => string;\n  requestHeaders: ProxyRequestHeaderOptions;\n  responseHeaders?: ProxyResponseHeaderOptions;\n};\n\nexport function createProxyInterceptor(descriptor: ProxyDescriptor): HydrogenRouteInterceptor {\n  const log = getLogger(descriptor.scope);\n  const formatError = descriptor.formatError ?? defaultFormatError;\n\n  return (url, options) => {\n    const { request, storefrontClient } = options;\n    if (!descriptor.match.test(url.pathname)) return null;\n\n    // Disable JSONP requests for security:\n    if (url.searchParams.has(\"callback\")) {\n      return Promise.resolve(\n        new Response(JSON.stringify(formatError(\"JSONP requests are not supported\")), {\n          status: 400,\n          headers: {\n            \"content-type\": \"application/json\",\n            \"cache-control\": PROXY_ERROR_CACHE_CONTROL,\n          },\n        }),\n      );\n    }\n\n    if (descriptor.methods && !descriptor.methods.includes(request.method)) {\n      // Method not allowed. Shape the body via formatError, like other errors.\n      return Promise.resolve(\n        new Response(JSON.stringify(formatError(\"Method Not Allowed\")), {\n          status: 405,\n          headers: {\n            allow: descriptor.methods.join(\", \"),\n            \"content-type\": \"application/json\",\n            \"cache-control\": PROXY_ERROR_CACHE_CONTROL,\n          },\n        }),\n      );\n    }\n\n    let upstreamUrl: URL;\n    let init: RequestInit & { duplex?: \"half\" };\n    try {\n      const upstreamPathname = descriptor.rewritePathname?.(url.pathname) ?? url.pathname;\n      upstreamUrl = new URL(upstreamPathname + url.search, storefrontClient.storeUrl);\n\n      init = {\n        method: request.method,\n        body: request.body,\n        headers: createProxyRequestHeaders(descriptor, { ...options, url }),\n        signal: AbortSignal.timeout(PROXY_TIMEOUT_MS),\n        redirect: descriptor.redirect ?? \"manual\",\n      };\n\n      // Node's fetch requires this when forwarding a streaming request body.\n      if (request.body) init.duplex = \"half\";\n    } catch (error) {\n      log.error(\"request failed\", { error });\n      return Promise.resolve(createProxyErrorResponse(error, 500, formatError));\n    }\n\n    return fetch(upstreamUrl, init)\n      .then((upstreamResponse) => {\n        const headers = createProxyResponseHeaders(upstreamResponse.headers);\n        descriptor.responseHeaders?.prepare?.(headers, {\n          ...options,\n          url,\n          response: upstreamResponse,\n        });\n        options.requestContext.consumeStorefrontResponseHeaders(headers);\n\n        return new Response(upstreamResponse.body, {\n          status: upstreamResponse.status,\n          statusText: upstreamResponse.statusText,\n          headers,\n        });\n      })\n      .catch((error) => {\n        log.error(\"request failed\", { error });\n        return createProxyErrorResponse(error, 502, formatError);\n      });\n  };\n}\n\nfunction defaultFormatError(message: string): { error: string } {\n  return { error: message };\n}\n\nfunction createProxyErrorResponse(\n  error: unknown,\n  status: number,\n  formatError: (message: string) => unknown,\n): Response {\n  const message = error instanceof Error ? error.message : \"Internal proxy error\";\n  return new Response(JSON.stringify(formatError(message)), {\n    status,\n    headers: {\n      \"content-type\": \"application/json\",\n      \"cache-control\": PROXY_ERROR_CACHE_CONTROL,\n    },\n  });\n}\n\nfunction createProxyRequestHeaders(\n  descriptor: ProxyDescriptor,\n  options: ProxyHeaderContext,\n): Headers {\n  const { request, requestContext } = options;\n  const { allow, deny, prepare } = descriptor.requestHeaders;\n  const headers = allow\n    ? new Headers(extractHeaders((key) => request.headers.get(key), allow))\n    : new Headers(request.headers);\n\n  requestContext.applyStorefrontRequestHeaders(headers);\n\n  for (const header of deny ?? []) headers.delete(header);\n  prepare?.(headers, options);\n\n  return headers;\n}\n\nexport function createProxyResponseHeaders(upstreamHeaders: Headers): Headers {\n  const headers = new Headers(upstreamHeaders);\n  headers.delete(\"content-encoding\");\n  headers.delete(\"content-length\");\n  headers.delete(\"server-timing\");\n  return headers;\n}\n"],"mappings":"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"}
+{"version":3,"file":"proxy.mjs","names":[],"sources":["../../../../src/core/request-routing/interceptors/proxy.ts"],"sourcesContent":["import { extractHeaders } from \"../../headers\";\nimport { getLogger } from \"../../logging\";\nimport type { HydrogenRouteInterceptor, HydrogenRoutesOptions } from \"../route-types\";\n\nconst PROXY_TIMEOUT_MS = 30_000;\n\n// Proxy errors are transient and may be buyer-specific: never cache them.\nconst PROXY_ERROR_CACHE_CONTROL = \"no-store\";\n\ntype ScopedLogger = ReturnType<typeof getLogger>;\n\ntype ProxyHeaderContext = HydrogenRoutesOptions & { url: URL };\n\ntype PrepareHeaders<ExtraContext extends object = object> = (\n  headers: Headers,\n  context: ProxyHeaderContext & ExtraContext,\n) => void;\n\ntype ProxyRequestHeaderOptions = (\n  | { allow: readonly string[]; deny?: never }\n  | { allow?: never; deny: readonly string[] }\n) & {\n  prepare?: PrepareHeaders;\n  applyStorefrontHeaders?: boolean;\n};\n\ntype ProxyUpstreamInfo = {\n  ok: boolean;\n  status: number;\n  statusText: string;\n  headers: Headers;\n};\n\ntype ProxyResponseHeaderOptions = {\n  allow?: readonly string[];\n  prepare?: PrepareHeaders<{ response: ProxyUpstreamInfo }>;\n};\n\ntype ProxyResponseRejection = {\n  status: number;\n  body: unknown;\n  logMessage?: string;\n  log?: Record<string, unknown>;\n};\n\ntype ProxyResponseValidation = (\n  upstream: ProxyUpstreamInfo,\n  options: HydrogenRoutesOptions,\n  url: URL,\n) => ProxyResponseRejection | null;\n\ntype ProxyErrorPhase = \"setup\" | \"fetch\";\n\ntype ProxyErrorMapping = { status?: number; body?: unknown };\n\ntype MapProxyError = (error: unknown, phase: ProxyErrorPhase) => ProxyErrorMapping;\n\ntype ProxyDescriptor = {\n  match: RegExp;\n  methods?: readonly string[];\n  formatError?: (message: string) => unknown;\n  redirect?: RequestRedirect;\n  scope: string;\n  timeoutMs?: number;\n  forwardSearch?: boolean;\n  rewritePathname?: (pathname: string) => string;\n  requestHeaders: ProxyRequestHeaderOptions;\n  responseHeaders?: ProxyResponseHeaderOptions;\n  responseValidation?: ProxyResponseValidation;\n  mapError?: MapProxyError;\n};\n\ntype ProxyRequestInit = { upstreamUrl: URL; init: RequestInit & { duplex?: \"half\" } };\n\nexport function createProxyInterceptor(descriptor: ProxyDescriptor): HydrogenRouteInterceptor {\n  const log = getLogger(descriptor.scope);\n  const formatError = descriptor.formatError ?? defaultFormatError;\n\n  return (url, options) => {\n    const { request } = options;\n    if (!descriptor.match.test(url.pathname)) return null;\n\n    // Disable JSONP requests for security:\n    if (url.searchParams.has(\"callback\")) {\n      return Promise.resolve(\n        createProxyRejectionResponse(\n          {\n            status: 400,\n            body: formatError(\"JSONP requests are not supported\"),\n          },\n          request.method,\n        ),\n      );\n    }\n\n    if (descriptor.methods && !descriptor.methods.includes(request.method)) {\n      // Method not allowed. Shape the body via formatError, like other errors.\n      return Promise.resolve(\n        new Response(\n          request.method === \"HEAD\" ? null : JSON.stringify(formatError(\"Method Not Allowed\")),\n          {\n            status: 405,\n            headers: {\n              allow: descriptor.methods.join(\", \"),\n              \"content-type\": \"application/json\",\n              \"cache-control\": PROXY_ERROR_CACHE_CONTROL,\n            },\n          },\n        ),\n      );\n    }\n\n    let requestInit: ProxyRequestInit;\n    try {\n      requestInit = createProxyRequestInit(descriptor, options, url);\n    } catch (error) {\n      log.error(\"request failed\", { error });\n      return Promise.resolve(\n        createProxyErrorResponse(error, \"setup\", descriptor.mapError, formatError, request.method),\n      );\n    }\n\n    return fetch(requestInit.upstreamUrl, requestInit.init)\n      .then((upstreamResponse) =>\n        buildProxyResponse(upstreamResponse, descriptor, options, url, log),\n      )\n      .catch((error) => {\n        log.error(\"request failed\", { error });\n        return createProxyErrorResponse(\n          error,\n          \"fetch\",\n          descriptor.mapError,\n          formatError,\n          request.method,\n        );\n      });\n  };\n}\n\nfunction createProxyRequestInit(\n  descriptor: ProxyDescriptor,\n  options: HydrogenRoutesOptions,\n  url: URL,\n): ProxyRequestInit {\n  const { request, storefrontClient } = options;\n  const upstreamPathname = descriptor.rewritePathname?.(url.pathname) ?? url.pathname;\n  const search = descriptor.forwardSearch === false ? \"\" : url.search;\n  const upstreamUrl = new URL(upstreamPathname + search, storefrontClient.storeUrl);\n  const init: RequestInit & { duplex?: \"half\" } = {\n    method: request.method,\n    body: request.body,\n    headers: createProxyRequestHeaders(descriptor, { ...options, url }),\n    signal: AbortSignal.timeout(descriptor.timeoutMs ?? PROXY_TIMEOUT_MS),\n    redirect: descriptor.redirect ?? \"manual\",\n  };\n\n  // Node's fetch requires this when forwarding a streaming request body.\n  if (request.body) init.duplex = \"half\";\n  return { upstreamUrl, init };\n}\n\nfunction buildProxyResponse(\n  upstreamResponse: Response,\n  descriptor: ProxyDescriptor,\n  options: HydrogenRoutesOptions,\n  url: URL,\n  log: ScopedLogger,\n): Response {\n  const upstream: ProxyUpstreamInfo = {\n    ok: upstreamResponse.ok,\n    status: upstreamResponse.status,\n    statusText: upstreamResponse.statusText,\n    headers: upstreamResponse.headers,\n  };\n\n  const rejection = descriptor.responseValidation?.(upstream, options, url);\n  if (rejection) {\n    // Centralized drain: response hooks receive only a body-less view, so the factory\n    // owns the sole cancellation and no validator can leak the upstream connection.\n    upstreamResponse.body?.cancel().catch(() => {});\n    if (rejection.logMessage) log.error(rejection.logMessage, rejection.log ?? {});\n    return createProxyRejectionResponse(rejection, options.request.method);\n  }\n\n  const headers = buildProxyResponseHeaders(\n    upstreamResponse.headers,\n    descriptor.responseHeaders?.allow,\n  );\n  descriptor.responseHeaders?.prepare?.(headers, { ...options, url, response: upstream });\n  options.requestContext.consumeStorefrontResponseHeaders(headers);\n\n  return new Response(upstreamResponse.body, {\n    status: upstreamResponse.status,\n    statusText: upstreamResponse.statusText,\n    headers,\n  });\n}\n\nfunction defaultFormatError(message: string): { error: string } {\n  return { error: message };\n}\n\nfunction createProxyErrorResponse(\n  error: unknown,\n  phase: ProxyErrorPhase,\n  mapError: MapProxyError | undefined,\n  formatError: (message: string) => unknown,\n  method: string,\n): Response {\n  const message = error instanceof Error ? error.message : \"Internal proxy error\";\n  const mapping = mapError?.(error, phase);\n  const status = mapping?.status ?? (phase === \"setup\" ? 500 : 502);\n  const body = mapping?.body === undefined ? formatError(message) : mapping.body;\n  return createProxyRejectionResponse({ status, body }, method);\n}\n\nfunction createProxyRejectionResponse(rejection: ProxyResponseRejection, method: string): Response {\n  return new Response(method === \"HEAD\" ? null : JSON.stringify(rejection.body), {\n    status: rejection.status,\n    headers: {\n      \"content-type\": \"application/json\",\n      \"cache-control\": PROXY_ERROR_CACHE_CONTROL,\n    },\n  });\n}\n\nfunction createProxyRequestHeaders(\n  descriptor: ProxyDescriptor,\n  options: ProxyHeaderContext,\n): Headers {\n  const { request, requestContext } = options;\n  const { allow, deny, prepare } = descriptor.requestHeaders;\n  const headers = allow\n    ? new Headers(extractHeaders((key) => request.headers.get(key), allow))\n    : new Headers(request.headers);\n\n  if (descriptor.requestHeaders.applyStorefrontHeaders !== false) {\n    requestContext.applyStorefrontRequestHeaders(headers);\n  }\n\n  for (const header of deny ?? []) headers.delete(header);\n  prepare?.(headers, options);\n\n  return headers;\n}\n\nfunction buildProxyResponseHeaders(upstreamHeaders: Headers, allow?: readonly string[]): Headers {\n  if (allow) {\n    const headers = new Headers();\n    for (const name of allow) {\n      const value = upstreamHeaders.get(name);\n      if (value !== null) headers.set(name, value);\n    }\n    return headers;\n  }\n  return createProxyResponseHeaders(upstreamHeaders);\n}\n\nexport function createProxyResponseHeaders(upstreamHeaders: Headers): Headers {\n  const headers = new Headers(upstreamHeaders);\n  headers.delete(\"content-encoding\");\n  headers.delete(\"content-length\");\n  headers.delete(\"server-timing\");\n  return headers;\n}\n"],"mappings":"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"}

package/dist/core/request-routing/interceptors/ucp-profile-proxy.mjs

@@ -0,0 +1,69 @@
+import { UCP_RE } from "../../url.mjs";
+import { createProxyInterceptor } from "./proxy.mjs";
+
+//#region src/core/request-routing/interceptors/ucp-profile-proxy.ts
+const UCP_CACHE_CONTROL = "public, max-age=60, s-maxage=60, stale-while-revalidate=300, stale-if-error=300";
+const UCP_NO_CACHE_CONTROL = "no-store";
+const UCP_PROFILE_PATH = "/.well-known/ucp";
+const proxyUcpProfileRequest = createProxyInterceptor({
+	match: UCP_RE,
+	scope: "ucp-profile-proxy",
+	timeoutMs: 5e3,
+	forwardSearch: false,
+	rewritePathname: () => UCP_PROFILE_PATH,
+	requestHeaders: {
+		allow: ["if-none-match", "if-modified-since"],
+		applyStorefrontHeaders: false,
+		prepare: (headers) => {
+			headers.set("accept", "application/json");
+		}
+	},
+	responseHeaders: {
+		allow: [
+			"content-type",
+			"etag",
+			"last-modified"
+		],
+		prepare: (headers, { response }) => {
+			headers.set("cache-control", response.ok || response.status === 304 ? UCP_CACHE_CONTROL : UCP_NO_CACHE_CONTROL);
+			headers.set("access-control-allow-origin", "*");
+		}
+	},
+	responseValidation: (upstream) => {
+		if (upstream.status === 304) return null;
+		if (upstream.status === 404) return {
+			status: 404,
+			body: { error: "Shopify UCP profile not found" }
+		};
+		const contentType = upstream.headers.get("content-type");
+		const mediaType = contentType?.split(";", 1)[0]?.trim().toLowerCase();
+		const isRedirect = upstream.status >= 300 && upstream.status < 400;
+		if (isRedirect || mediaType !== "application/json") {
+			const status = isRedirect || upstream.ok ? 502 : upstream.status;
+			return {
+				status,
+				body: { error: "Shopify UCP profile unavailable" },
+				...status === 502 && {
+					logMessage: "invalid profile response",
+					log: {
+						status: upstream.status,
+						contentType
+					}
+				}
+			};
+		}
+		return null;
+	},
+	mapError: (error, phase) => ({
+		status: phase === "fetch" && error instanceof DOMException && error.name === "TimeoutError" ? 504 : void 0,
+		body: { error: "Unable to fetch the Shopify UCP profile" }
+	})
+});
+const handleUcpProfileProxy = (url, options) => {
+	if (options.request.method !== "GET" && options.request.method !== "HEAD") return null;
+	return proxyUcpProfileRequest(url, options);
+};
+
+//#endregion
+export { handleUcpProfileProxy };
+//# sourceMappingURL=ucp-profile-proxy.mjs.map

package/dist/core/request-routing/interceptors/ucp-profile-proxy.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ucp-profile-proxy.mjs","names":[],"sources":["../../../../src/core/request-routing/interceptors/ucp-profile-proxy.ts"],"sourcesContent":["import { UCP_RE } from \"../../url\";\nimport type { HydrogenRouteInterceptor } from \"../route-types\";\nimport { createProxyInterceptor } from \"./proxy\";\n\n// UCP requires at least 60s of freshness; limit stale signing keys to a further 300s.\nconst UCP_CACHE_CONTROL =\n  \"public, max-age=60, s-maxage=60, stale-while-revalidate=300, stale-if-error=300\";\nconst UCP_NO_CACHE_CONTROL = \"no-store\";\nconst UCP_PROFILE_PATH = \"/.well-known/ucp\";\nconst UCP_FETCH_TIMEOUT_MS = 5_000;\n// Accept is fixed upstream; its Vary header does not describe the downstream representation.\nconst UCP_RESPONSE_HEADERS = [\"content-type\", \"etag\", \"last-modified\"] as const;\n\nconst proxyUcpProfileRequest = createProxyInterceptor({\n  match: UCP_RE,\n  scope: \"ucp-profile-proxy\",\n  timeoutMs: UCP_FETCH_TIMEOUT_MS,\n  forwardSearch: false,\n  rewritePathname: () => UCP_PROFILE_PATH,\n  requestHeaders: {\n    allow: [\"if-none-match\", \"if-modified-since\"],\n    applyStorefrontHeaders: false,\n    prepare: (headers) => {\n      headers.set(\"accept\", \"application/json\");\n    },\n  },\n  responseHeaders: {\n    allow: UCP_RESPONSE_HEADERS,\n    prepare: (headers, { response }) => {\n      headers.set(\n        \"cache-control\",\n        response.ok || response.status === 304 ? UCP_CACHE_CONTROL : UCP_NO_CACHE_CONTROL,\n      );\n      // The profile is public; match the Online Store so browser-based agents can read it.\n      headers.set(\"access-control-allow-origin\", \"*\");\n    },\n  },\n  responseValidation: (upstream) => {\n    if (upstream.status === 304) return null;\n    if (upstream.status === 404) {\n      return {\n        status: 404,\n        body: { error: \"Shopify UCP profile not found\" },\n      };\n    }\n\n    const contentType = upstream.headers.get(\"content-type\");\n    const mediaType = contentType?.split(\";\", 1)[0]?.trim().toLowerCase();\n    // UCP profile hosting forbids redirects; 304 revalidation is handled above.\n    const isRedirect = upstream.status >= 300 && upstream.status < 400;\n    if (isRedirect || mediaType !== \"application/json\") {\n      const status = isRedirect || upstream.ok ? 502 : upstream.status;\n      return {\n        status,\n        body: { error: \"Shopify UCP profile unavailable\" },\n        ...(status === 502 && {\n          logMessage: \"invalid profile response\",\n          log: { status: upstream.status, contentType },\n        }),\n      };\n    }\n    return null;\n  },\n  mapError: (error, phase) => ({\n    status:\n      phase === \"fetch\" && error instanceof DOMException && error.name === \"TimeoutError\"\n        ? 504\n        : undefined,\n    body: { error: \"Unable to fetch the Shopify UCP profile\" },\n  }),\n});\n\nexport const handleUcpProfileProxy: HydrogenRouteInterceptor = (url, options) => {\n  // Unlike reserved API routes, unsupported discovery methods fall through to the app.\n  if (options.request.method !== \"GET\" && options.request.method !== \"HEAD\") return null;\n  return proxyUcpProfileRequest(url, options);\n};\n"],"mappings":";;;;AAKA,MAAM,oBACJ;AACF,MAAM,uBAAuB;AAC7B,MAAM,mBAAmB;AAKzB,MAAM,yBAAyB,uBAAuB;CACpD,OAAO;CACP,OAAO;CACP,WAAW;CACX,eAAe;CACf,uBAAuB;CACvB,gBAAgB;EACd,OAAO,CAAC,iBAAiB,oBAAoB;EAC7C,wBAAwB;EACxB,UAAU,YAAY;AACpB,WAAQ,IAAI,UAAU,mBAAmB;;EAE5C;CACD,iBAAiB;EACf,OAAO;GAhBmB;GAAgB;GAAQ;GAgBvB;EAC3B,UAAU,SAAS,EAAE,eAAe;AAClC,WAAQ,IACN,iBACA,SAAS,MAAM,SAAS,WAAW,MAAM,oBAAoB,qBAC9D;AAED,WAAQ,IAAI,+BAA+B,IAAI;;EAElD;CACD,qBAAqB,aAAa;AAChC,MAAI,SAAS,WAAW,IAAK,QAAO;AACpC,MAAI,SAAS,WAAW,IACtB,QAAO;GACL,QAAQ;GACR,MAAM,EAAE,OAAO,iCAAiC;GACjD;EAGH,MAAM,cAAc,SAAS,QAAQ,IAAI,eAAe;EACxD,MAAM,YAAY,aAAa,MAAM,KAAK,EAAE,CAAC,IAAI,MAAM,CAAC,aAAa;EAErE,MAAM,aAAa,SAAS,UAAU,OAAO,SAAS,SAAS;AAC/D,MAAI,cAAc,cAAc,oBAAoB;GAClD,MAAM,SAAS,cAAc,SAAS,KAAK,MAAM,SAAS;AAC1D,UAAO;IACL;IACA,MAAM,EAAE,OAAO,mCAAmC;IAClD,GAAI,WAAW,OAAO;KACpB,YAAY;KACZ,KAAK;MAAE,QAAQ,SAAS;MAAQ;MAAa;KAC9C;IACF;;AAEH,SAAO;;CAET,WAAW,OAAO,WAAW;EAC3B,QACE,UAAU,WAAW,iBAAiB,gBAAgB,MAAM,SAAS,iBACjE,MACA;EACN,MAAM,EAAE,OAAO,2CAA2C;EAC3D;CACF,CAAC;AAEF,MAAa,yBAAmD,KAAK,YAAY;AAE/E,KAAI,QAAQ,QAAQ,WAAW,SAAS,QAAQ,QAAQ,WAAW,OAAQ,QAAO;AAClF,QAAO,uBAAuB,KAAK,QAAQ"}

package/dist/core/request-routing/interceptors/url-redirects.mjs

@@ -6,7 +6,12 @@ const PLACEHOLDER_BASE = "https://0.0.0.0";
 async function handleUrlRedirects({ request, storefrontClient }) {
 	const { pathname, searchParams } = new URL(request.url);
 	const queryPath = pathname.toLowerCase().replace(/\/+$/, "");
-	const target = (await storefrontClient.graphql(REDIRECT_QUERY, { variables: { query: `path:${queryPath}` } })).data?.urlRedirects?.edges[0]?.node.target;
+	const result = await storefrontClient.graphql(REDIRECT_QUERY, { variables: { query: `path:${queryPath}` } });
+	if (result.errors) {
+		const messages = result.errors.map(({ message }) => message).join(", ");
+		throw new Error(`Storefront API errors: ${messages}`, { cause: result.errors });
+	}
+	const target = result.data?.urlRedirects?.edges[0]?.node.target;
 	if (!target) return null;
 	return createRedirectResponse(createRedirectLocation(target, searchParams));
 }

package/dist/core/request-routing/interceptors/url-redirects.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"url-redirects.mjs","names":[],"sources":["../../../../src/core/request-routing/interceptors/url-redirects.ts"],"sourcesContent":["import { gql } from \"../../../graphql\";\nimport type { RedirectOptions } from \"../handle-shopify-redirects\";\n\ntype UrlRedirectOptions = Pick<RedirectOptions, \"request\" | \"storefrontClient\">;\n\nconst REDIRECT_QUERY = gql(`\n  query redirects($query: String) {\n    urlRedirects(first: 1, query: $query) {\n      edges {\n        node {\n          target\n        }\n      }\n    }\n  }\n`);\n\n// Used as a base for `new URL()` when constructing relative redirect URLs.\n// Stripped from the output — only needed because `new URL` requires a base for relative paths.\nconst PLACEHOLDER_BASE = \"https://0.0.0.0\";\n\nexport async function handleUrlRedirects({\n  request,\n  storefrontClient,\n}: UrlRedirectOptions): Promise<Response | null> {\n  const url = new URL(request.url);\n  const { pathname, searchParams } = url;\n\n  const queryPath = pathname.toLowerCase().replace(/\\/+$/, \"\");\n  const result = await storefrontClient.graphql(REDIRECT_QUERY, {\n    variables: { query: `path:${queryPath}` },\n  });\n\n  const target = result.data?.urlRedirects?.edges[0]?.node.target;\n  if (!target) return null;\n\n  return createRedirectResponse(createRedirectLocation(target, searchParams));\n}\n\nexport function createRedirectLocation(location: string, searchParams: URLSearchParams): string {\n  const url = new URL(location, PLACEHOLDER_BASE);\n\n  for (const [key, value] of searchParams) {\n    url.searchParams.append(key, value);\n  }\n\n  return url.toString().replace(PLACEHOLDER_BASE, \"\");\n}\n\nexport function createRedirectResponse(location: string, status: number = 301): Response {\n  return new Response(null, {\n    status,\n    headers: { location },\n  });\n}\n"],"mappings":";;;AAKA,MAAA,iBAAA,IAAA,0FAUA;AAIA,MAAA,mBAAA;AAEA,eAAA,mBAAA,EACA,SACA,oBACA;CAEA,MAAA,EAAA,UAAA,iBAAA,IADA,IAAA,QAAA,IACA;CAEA,MAAA,YAAA,SAAA,aAAA,CAAA,QAAA,QAAA,GAAA;CAKA,MAAA,UAAA,MAJA,iBAAA,QAAA,gBAAA,EACA,WAAA,EAAA,OAAA,QAAA,aAAA,EACA,CAAA,EAEA,MAAA,cAAA,MAAA,IAAA,KAAA;AACA,KAAA,CAAA,OAAA,QAAA;AAEA,QAAA,uBAAA,uBAAA,QAAA,aAAA,CAAA;;AAGA,SAAA,uBAAA,UAAA,cAAA;CACA,MAAA,MAAA,IAAA,IAAA,UAAA,iBAAA;AAEA,MAAA,MAAA,CAAA,KAAA,UAAA,aACA,KAAA,aAAA,OAAA,KAAA,MAAA;AAGA,QAAA,IAAA,UAAA,CAAA,QAAA,kBAAA,GAAA;;AAGA,SAAA,uBAAA,UAAA,SAAA,KAAA;AACA,QAAA,IAAA,SAAA,MAAA;EACA;EACA,SAAA,EAAA,UAAA;EACA,CAAA"}
+{"version":3,"file":"url-redirects.mjs","names":[],"sources":["../../../../src/core/request-routing/interceptors/url-redirects.ts"],"sourcesContent":["import { gql } from \"../../../graphql\";\nimport type { RedirectOptions } from \"../handle-shopify-redirects\";\n\ntype UrlRedirectOptions = Pick<RedirectOptions, \"request\" | \"storefrontClient\">;\n\nconst REDIRECT_QUERY = gql(`\n  query redirects($query: String) {\n    urlRedirects(first: 1, query: $query) {\n      edges {\n        node {\n          target\n        }\n      }\n    }\n  }\n`);\n\n// Used as a base for `new URL()` when constructing relative redirect URLs.\n// Stripped from the output — only needed because `new URL` requires a base for relative paths.\nconst PLACEHOLDER_BASE = \"https://0.0.0.0\";\n\nexport async function handleUrlRedirects({\n  request,\n  storefrontClient,\n}: UrlRedirectOptions): Promise<Response | null> {\n  const url = new URL(request.url);\n  const { pathname, searchParams } = url;\n\n  const queryPath = pathname.toLowerCase().replace(/\\/+$/, \"\");\n  const result = await storefrontClient.graphql(REDIRECT_QUERY, {\n    variables: { query: `path:${queryPath}` },\n  });\n\n  if (result.errors) {\n    const messages = result.errors.map(({ message }) => message).join(\", \");\n    throw new Error(`Storefront API errors: ${messages}`, { cause: result.errors });\n  }\n\n  const target = result.data?.urlRedirects?.edges[0]?.node.target;\n  if (!target) return null;\n\n  return createRedirectResponse(createRedirectLocation(target, searchParams));\n}\n\nexport function createRedirectLocation(location: string, searchParams: URLSearchParams): string {\n  const url = new URL(location, PLACEHOLDER_BASE);\n\n  for (const [key, value] of searchParams) {\n    url.searchParams.append(key, value);\n  }\n\n  return url.toString().replace(PLACEHOLDER_BASE, \"\");\n}\n\nexport function createRedirectResponse(location: string, status: number = 301): Response {\n  return new Response(null, {\n    status,\n    headers: { location },\n  });\n}\n"],"mappings":";;;AAKA,MAAA,iBAAA,IAAA,0FAUA;AAIA,MAAA,mBAAA;AAEA,eAAA,mBAAA,EACA,SACA,oBACA;CAEA,MAAA,EAAA,UAAA,iBAAA,IADA,IAAA,QAAA,IACA;CAEA,MAAA,YAAA,SAAA,aAAA,CAAA,QAAA,QAAA,GAAA;CACA,MAAA,SAAA,MAAA,iBAAA,QAAA,gBAAA,EACA,WAAA,EAAA,OAAA,QAAA,aAAA,EACA,CAAA;AAEA,KAAA,OAAA,QAAA;EACA,MAAA,WAAA,OAAA,OAAA,KAAA,EAAA,cAAA,QAAA,CAAA,KAAA,KAAA;AACA,QAAA,IAAA,MAAA,0BAAA,YAAA,EAAA,OAAA,OAAA,QAAA,CAAA;;CAGA,MAAA,SAAA,OAAA,MAAA,cAAA,MAAA,IAAA,KAAA;AACA,KAAA,CAAA,OAAA,QAAA;AAEA,QAAA,uBAAA,uBAAA,QAAA,aAAA,CAAA;;AAGA,SAAA,uBAAA,UAAA,cAAA;CACA,MAAA,MAAA,IAAA,IAAA,UAAA,iBAAA;AAEA,MAAA,MAAA,CAAA,KAAA,UAAA,aACA,KAAA,aAAA,OAAA,KAAA,MAAA;AAGA,QAAA,IAAA,UAAA,CAAA,QAAA,kBAAA,GAAA;;AAGA,SAAA,uBAAA,UAAA,SAAA,KAAA;AACA,QAAA,IAAA,SAAA,MAAA;EACA;EACA,SAAA,EAAA,UAAA;EACA,CAAA"}

package/dist/core/request-routing/interceptors/well-known.mjs

@@ -7,7 +7,7 @@ import { createProxyInterceptor } from "./proxy.mjs";
 * Proxies allowlisted Shopify `.well-known` resources through the headless
 * storefront origin to the Online Store, so first-party services (Apple Pay
 * domain verification, Frontend Event Collector ingress) behave the same way
-* they do on Online Store storefronts. See {@link WELL_KNOWN_RE} for the
+* they do on Online Store storefronts. See `WELL_KNOWN_RE` for the
 * allowlist.
 */
 const handleWellKnownProxy = createProxyInterceptor({

package/dist/core/request-routing/interceptors/well-known.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"well-known.mjs","names":[],"sources":["../../../../src/core/request-routing/interceptors/well-known.ts"],"sourcesContent":["import { PROXY_REQUEST_HEADER_DENYLIST } from \"../../headers\";\nimport { WELL_KNOWN_RE } from \"../../url\";\nimport { createProxyInterceptor } from \"./proxy\";\n\n/**\n * Proxies allowlisted Shopify `.well-known` resources through the headless\n * storefront origin to the Online Store, so first-party services (Apple Pay\n * domain verification, Frontend Event Collector ingress) behave the same way\n * they do on Online Store storefronts. See {@link WELL_KNOWN_RE} for the\n * allowlist.\n */\nexport const handleWellKnownProxy = createProxyInterceptor({\n  match: WELL_KNOWN_RE,\n  requestHeaders: { deny: PROXY_REQUEST_HEADER_DENYLIST },\n  redirect: \"follow\",\n  scope: \"well-known-proxy\",\n});\n"],"mappings":";;;;;;;;;;;;AAWA,MAAa,uBAAuB,uBAAuB;CACzD,OAAO;CACP,gBAAgB,EAAE,MAAM,+BAA+B;CACvD,UAAU;CACV,OAAO;CACR,CAAC"}
+{"version":3,"file":"well-known.mjs","names":[],"sources":["../../../../src/core/request-routing/interceptors/well-known.ts"],"sourcesContent":["import { PROXY_REQUEST_HEADER_DENYLIST } from \"../../headers\";\nimport { WELL_KNOWN_RE } from \"../../url\";\nimport { createProxyInterceptor } from \"./proxy\";\n\n/**\n * Proxies allowlisted Shopify `.well-known` resources through the headless\n * storefront origin to the Online Store, so first-party services (Apple Pay\n * domain verification, Frontend Event Collector ingress) behave the same way\n * they do on Online Store storefronts. See `WELL_KNOWN_RE` for the\n * allowlist.\n */\nexport const handleWellKnownProxy = createProxyInterceptor({\n  match: WELL_KNOWN_RE,\n  requestHeaders: { deny: PROXY_REQUEST_HEADER_DENYLIST },\n  redirect: \"follow\",\n  scope: \"well-known-proxy\",\n});\n"],"mappings":";;;;;;;;;;;;AAWA,MAAa,uBAAuB,uBAAuB;CACzD,OAAO;CACP,gBAAgB,EAAE,MAAM,+BAA+B;CACvD,UAAU;CACV,OAAO;CACR,CAAC"}

package/dist/core/request-routing/registered-routes.d.mts

@@ -1,6 +1,18 @@
 import { CallableRouteHandler, ShopifyRedirectStatus, ShopifyRouteError, ShopifyRouteErrorResult, ShopifyRouteHandler, ShopifyRouteHandlerContext, ShopifyRouteHandlerGroup, ShopifyRouteHandlerResult, ShopifyRouteJsonResult, ShopifyRouteRedirectResult, ShopifyRouteSessionManager } from "./route-types.mjs";
 
 //#region src/core/request-routing/registered-routes.d.ts
+/**
+ * Creates a custom endpoint in your app for one pathname and HTTP method. Collect handlers in an
+ * object, and pass an array of handler objects to `handleShopifyRoutes` in its `handlers` option.
+ *
+ * Use paths other than `/api/cart`, which the cart server handlers use. Return a JSON, redirect, or error result from the handler. Hydrogen sends a JSON result with status `200`, an error result with status `400` by default, and a redirect result with status `303` by default. When a redirect result uses a status other than `301`, `302`, `303`, 307, or 308, the promise from `handleShopifyRoutes` rejects.
+ *
+ * @param pathname The exact URL pathname that the handler matches. Hydrogen doesn't match path parameters or prefixes.
+ * @param method The HTTP method that the handler matches, in uppercase, such as `POST`.
+ * @param handler The function that receives the request, its context, the session, and the Storefront API client, and returns a JSON, redirect, or error result.
+ * @returns The handler to add to a handler object.
+ * @publicDocs
+ */
 declare function createShopifyRouteHandler<const TPathname extends string, const TMethod extends string>(pathname: TPathname, method: TMethod, handler: (context: ShopifyRouteHandlerContext) => Promise<ShopifyRouteHandlerResult>): ShopifyRouteHandler<TPathname, TMethod>;
 //#endregion
 export { createShopifyRouteHandler };

package/dist/core/request-routing/registered-routes.mjs

@@ -10,6 +10,18 @@ const VALID_REDIRECT_STATUSES = [
 	307,
 	308
 ];
+/**
+* Creates a custom endpoint in your app for one pathname and HTTP method. Collect handlers in an
+* object, and pass an array of handler objects to `handleShopifyRoutes` in its `handlers` option.
+*
+* Use paths other than `/api/cart`, which the cart server handlers use. Return a JSON, redirect, or error result from the handler. Hydrogen sends a JSON result with status `200`, an error result with status `400` by default, and a redirect result with status `303` by default. When a redirect result uses a status other than `301`, `302`, `303`, 307, or 308, the promise from `handleShopifyRoutes` rejects.
+*
+* @param pathname The exact URL pathname that the handler matches. Hydrogen doesn't match path parameters or prefixes.
+* @param method The HTTP method that the handler matches, in uppercase, such as `POST`.
+* @param handler The function that receives the request, its context, the session, and the Storefront API client, and returns a JSON, redirect, or error result.
+* @returns The handler to add to a handler object.
+* @publicDocs
+*/
 function createShopifyRouteHandler(pathname, method, handler) {
 	return createCallableRouteHandler(pathname, method, handler);
 }

package/dist/core/request-routing/registered-routes.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"registered-routes.mjs","names":[],"sources":["../../../src/core/request-routing/registered-routes.ts"],"sourcesContent":["import type {\n  CallableRouteHandler,\n  HydrogenRouteInterceptor,\n  ShopifyRouteHandler,\n  ShopifyRouteHandlerContext,\n  ShopifyRouteHandlerResult,\n  ShopifyRedirectStatus,\n} from \"./route-types\";\n\nexport type {\n  CallableRouteHandler,\n  ShopifyRouteError,\n  ShopifyRouteErrorResult,\n  ShopifyRouteHandler,\n  ShopifyRouteHandlerContext,\n  ShopifyRouteHandlerGroup,\n  ShopifyRouteHandlerResult,\n  ShopifyRouteJsonResult,\n  ShopifyRouteRedirectResult,\n  ShopifyRedirectStatus,\n  ShopifyRouteSessionManager,\n} from \"./route-types\";\n\nconst HTTP_OK_STATUS = 200;\nconst HTTP_SEE_OTHER_STATUS = 303;\nconst HTTP_METHOD_NOT_ALLOWED_STATUS = 405;\nconst HTTP_BAD_REQUEST_STATUS = 400;\nconst VALID_REDIRECT_STATUSES = [\n  301, 302, 303, 307, 308,\n] as const satisfies readonly ShopifyRedirectStatus[];\n\nexport function createShopifyRouteHandler<\n  const TPathname extends string,\n  const TMethod extends string,\n>(\n  pathname: TPathname,\n  method: TMethod,\n  handler: (context: ShopifyRouteHandlerContext) => Promise<ShopifyRouteHandlerResult>,\n): ShopifyRouteHandler<TPathname, TMethod> {\n  return createCallableRouteHandler(pathname, method, handler);\n}\n\nexport function createCallableRouteHandler<\n  const TPathname extends string,\n  const TMethod extends string,\n  TContext,\n  TResult,\n>(\n  pathname: TPathname,\n  method: TMethod,\n  handler: (context: TContext) => Promise<TResult>,\n): CallableRouteHandler<TContext, TResult, TPathname, TMethod> {\n  return Object.assign(handler, { pathname, method });\n}\n\nexport const handleShopifyRouteHandlers: HydrogenRouteInterceptor = (\n  url,\n  { request, sessionManager, storefrontClient, requestContext, handlers = [] },\n) => {\n  const context = { request, sessionManager, storefrontClient, requestContext };\n  const routeHandlers = handlers.flatMap((group) => Object.values(group));\n  if (routeHandlers.length === 0) return null;\n\n  const pathMatches = routeHandlers.filter((entry) => entry.pathname === url.pathname);\n  if (pathMatches.length === 0) return null;\n\n  const match = pathMatches.find((candidate) => candidate.method === request.method);\n  if (!match)\n    return Promise.resolve(\n      new Response(\"Method Not Allowed\", { status: HTTP_METHOD_NOT_ALLOWED_STATUS }),\n    );\n\n  return match(context).then((result) => createShopifyRouteResponse(result, request));\n};\n\nfunction createShopifyRouteResponse(result: ShopifyRouteHandlerResult, request: Request): Response {\n  if (result.type === \"redirect\") {\n    const headers = new Headers(result.headers);\n    headers.set(\"location\", resolveRedirectLocation(result.location, request));\n    return new Response(null, {\n      status: getRedirectStatus(result.status),\n      headers,\n    });\n  }\n\n  if (result.type === \"error\") {\n    const headers = new Headers(result.headers);\n    headers.set(\"content-type\", \"application/json\");\n    return new Response(JSON.stringify({ error: result.error }), {\n      status: result.status ?? HTTP_BAD_REQUEST_STATUS,\n      headers,\n    });\n  }\n\n  const headers = new Headers(result.headers);\n  headers.set(\"content-type\", \"application/json\");\n  return new Response(JSON.stringify(result.data), {\n    status: HTTP_OK_STATUS,\n    headers,\n  });\n}\n\nfunction getRedirectStatus(status: ShopifyRedirectStatus | undefined): ShopifyRedirectStatus {\n  const redirectStatus = status ?? HTTP_SEE_OTHER_STATUS;\n  if (VALID_REDIRECT_STATUSES.some((validStatus) => validStatus === redirectStatus)) {\n    return redirectStatus;\n  }\n\n  throw new Error(\n    `Invalid Shopify route redirect status ${redirectStatus}. Expected one of: ${VALID_REDIRECT_STATUSES.join(\", \")}.`,\n  );\n}\n\nfunction resolveRedirectLocation(location: string, request: Request): string {\n  // Absolute Location headers are the best common denominator: browsers accept\n  // relative redirects, but framework proxy runtimes like Next.js can require\n  // absolute URLs when returning a Response from middleware/proxy code.\n  return new URL(location, new URL(request.url).origin).toString();\n}\n"],"mappings":";AAuBA,MAAM,iBAAiB;AACvB,MAAM,wBAAwB;AAC9B,MAAM,iCAAiC;AACvC,MAAM,0BAA0B;AAChC,MAAM,0BAA0B;CAC9B;CAAK;CAAK;CAAK;CAAK;CACrB;AAED,SAAgB,0BAId,UACA,QACA,SACyC;AACzC,QAAO,2BAA2B,UAAU,QAAQ,QAAQ;;AAG9D,SAAgB,2BAMd,UACA,QACA,SAC6D;AAC7D,QAAO,OAAO,OAAO,SAAS;EAAE;EAAU;EAAQ,CAAC;;AAGrD,MAAa,8BACX,KACA,EAAE,SAAS,gBAAgB,kBAAkB,gBAAgB,WAAW,EAAE,OACvE;CACH,MAAM,UAAU;EAAE;EAAS;EAAgB;EAAkB;EAAgB;CAC7E,MAAM,gBAAgB,SAAS,SAAS,UAAU,OAAO,OAAO,MAAM,CAAC;AACvE,KAAI,cAAc,WAAW,EAAG,QAAO;CAEvC,MAAM,cAAc,cAAc,QAAQ,UAAU,MAAM,aAAa,IAAI,SAAS;AACpF,KAAI,YAAY,WAAW,EAAG,QAAO;CAErC,MAAM,QAAQ,YAAY,MAAM,cAAc,UAAU,WAAW,QAAQ,OAAO;AAClF,KAAI,CAAC,MACH,QAAO,QAAQ,QACb,IAAI,SAAS,sBAAsB,EAAE,QAAQ,gCAAgC,CAAC,CAC/E;AAEH,QAAO,MAAM,QAAQ,CAAC,MAAM,WAAW,2BAA2B,QAAQ,QAAQ,CAAC;;AAGrF,SAAS,2BAA2B,QAAmC,SAA4B;AACjG,KAAI,OAAO,SAAS,YAAY;EAC9B,MAAM,UAAU,IAAI,QAAQ,OAAO,QAAQ;AAC3C,UAAQ,IAAI,YAAY,wBAAwB,OAAO,UAAU,QAAQ,CAAC;AAC1E,SAAO,IAAI,SAAS,MAAM;GACxB,QAAQ,kBAAkB,OAAO,OAAO;GACxC;GACD,CAAC;;AAGJ,KAAI,OAAO,SAAS,SAAS;EAC3B,MAAM,UAAU,IAAI,QAAQ,OAAO,QAAQ;AAC3C,UAAQ,IAAI,gBAAgB,mBAAmB;AAC/C,SAAO,IAAI,SAAS,KAAK,UAAU,EAAE,OAAO,OAAO,OAAO,CAAC,EAAE;GAC3D,QAAQ,OAAO,UAAU;GACzB;GACD,CAAC;;CAGJ,MAAM,UAAU,IAAI,QAAQ,OAAO,QAAQ;AAC3C,SAAQ,IAAI,gBAAgB,mBAAmB;AAC/C,QAAO,IAAI,SAAS,KAAK,UAAU,OAAO,KAAK,EAAE;EAC/C,QAAQ;EACR;EACD,CAAC;;AAGJ,SAAS,kBAAkB,QAAkE;CAC3F,MAAM,iBAAiB,UAAU;AACjC,KAAI,wBAAwB,MAAM,gBAAgB,gBAAgB,eAAe,CAC/E,QAAO;AAGT,OAAM,IAAI,MACR,yCAAyC,eAAe,qBAAqB,wBAAwB,KAAK,KAAK,CAAC,GACjH;;AAGH,SAAS,wBAAwB,UAAkB,SAA0B;AAI3E,QAAO,IAAI,IAAI,UAAU,IAAI,IAAI,QAAQ,IAAI,CAAC,OAAO,CAAC,UAAU"}
+{"version":3,"file":"registered-routes.mjs","names":[],"sources":["../../../src/core/request-routing/registered-routes.ts"],"sourcesContent":["import type {\n  CallableRouteHandler,\n  HydrogenRouteInterceptor,\n  ShopifyRouteHandler,\n  ShopifyRouteHandlerContext,\n  ShopifyRouteHandlerResult,\n  ShopifyRedirectStatus,\n} from \"./route-types\";\n\nexport type {\n  CallableRouteHandler,\n  ShopifyRouteError,\n  ShopifyRouteErrorResult,\n  ShopifyRouteHandler,\n  ShopifyRouteHandlerContext,\n  ShopifyRouteHandlerGroup,\n  ShopifyRouteHandlerResult,\n  ShopifyRouteJsonResult,\n  ShopifyRouteRedirectResult,\n  ShopifyRedirectStatus,\n  ShopifyRouteSessionManager,\n} from \"./route-types\";\n\nconst HTTP_OK_STATUS = 200;\nconst HTTP_SEE_OTHER_STATUS = 303;\nconst HTTP_METHOD_NOT_ALLOWED_STATUS = 405;\nconst HTTP_BAD_REQUEST_STATUS = 400;\nconst VALID_REDIRECT_STATUSES = [\n  301, 302, 303, 307, 308,\n] as const satisfies readonly ShopifyRedirectStatus[];\n\n/**\n * Creates a custom endpoint in your app for one pathname and HTTP method. Collect handlers in an\n * object, and pass an array of handler objects to `handleShopifyRoutes` in its `handlers` option.\n *\n * Use paths other than `/api/cart`, which the cart server handlers use. Return a JSON, redirect, or error result from the handler. Hydrogen sends a JSON result with status `200`, an error result with status `400` by default, and a redirect result with status `303` by default. When a redirect result uses a status other than `301`, `302`, `303`, 307, or 308, the promise from `handleShopifyRoutes` rejects.\n *\n * @param pathname The exact URL pathname that the handler matches. Hydrogen doesn't match path parameters or prefixes.\n * @param method The HTTP method that the handler matches, in uppercase, such as `POST`.\n * @param handler The function that receives the request, its context, the session, and the Storefront API client, and returns a JSON, redirect, or error result.\n * @returns The handler to add to a handler object.\n * @publicDocs\n */\nexport function createShopifyRouteHandler<\n  const TPathname extends string,\n  const TMethod extends string,\n>(\n  pathname: TPathname,\n  method: TMethod,\n  handler: (context: ShopifyRouteHandlerContext) => Promise<ShopifyRouteHandlerResult>,\n): ShopifyRouteHandler<TPathname, TMethod> {\n  return createCallableRouteHandler(pathname, method, handler);\n}\n\nexport function createCallableRouteHandler<\n  const TPathname extends string,\n  const TMethod extends string,\n  TContext,\n  TResult,\n>(\n  pathname: TPathname,\n  method: TMethod,\n  handler: (context: TContext) => Promise<TResult>,\n): CallableRouteHandler<TContext, TResult, TPathname, TMethod> {\n  return Object.assign(handler, { pathname, method });\n}\n\nexport const handleShopifyRouteHandlers: HydrogenRouteInterceptor = (\n  url,\n  { request, sessionManager, storefrontClient, requestContext, handlers = [] },\n) => {\n  const context = { request, sessionManager, storefrontClient, requestContext };\n  const routeHandlers = handlers.flatMap((group) => Object.values(group));\n  if (routeHandlers.length === 0) return null;\n\n  const pathMatches = routeHandlers.filter((entry) => entry.pathname === url.pathname);\n  if (pathMatches.length === 0) return null;\n\n  const match = pathMatches.find((candidate) => candidate.method === request.method);\n  if (!match)\n    return Promise.resolve(\n      new Response(\"Method Not Allowed\", { status: HTTP_METHOD_NOT_ALLOWED_STATUS }),\n    );\n\n  return match(context).then((result) => createShopifyRouteResponse(result, request));\n};\n\nfunction createShopifyRouteResponse(result: ShopifyRouteHandlerResult, request: Request): Response {\n  if (result.type === \"redirect\") {\n    const headers = new Headers(result.headers);\n    headers.set(\"location\", resolveRedirectLocation(result.location, request));\n    return new Response(null, {\n      status: getRedirectStatus(result.status),\n      headers,\n    });\n  }\n\n  if (result.type === \"error\") {\n    const headers = new Headers(result.headers);\n    headers.set(\"content-type\", \"application/json\");\n    return new Response(JSON.stringify({ error: result.error }), {\n      status: result.status ?? HTTP_BAD_REQUEST_STATUS,\n      headers,\n    });\n  }\n\n  const headers = new Headers(result.headers);\n  headers.set(\"content-type\", \"application/json\");\n  return new Response(JSON.stringify(result.data), {\n    status: HTTP_OK_STATUS,\n    headers,\n  });\n}\n\nfunction getRedirectStatus(status: ShopifyRedirectStatus | undefined): ShopifyRedirectStatus {\n  const redirectStatus = status ?? HTTP_SEE_OTHER_STATUS;\n  if (VALID_REDIRECT_STATUSES.some((validStatus) => validStatus === redirectStatus)) {\n    return redirectStatus;\n  }\n\n  throw new Error(\n    `Invalid Shopify route redirect status ${redirectStatus}. Expected one of: ${VALID_REDIRECT_STATUSES.join(\", \")}.`,\n  );\n}\n\nfunction resolveRedirectLocation(location: string, request: Request): string {\n  // Absolute Location headers are the best common denominator: browsers accept\n  // relative redirects, but framework proxy runtimes like Next.js can require\n  // absolute URLs when returning a Response from middleware/proxy code.\n  return new URL(location, new URL(request.url).origin).toString();\n}\n"],"mappings":";AAuBA,MAAM,iBAAiB;AACvB,MAAM,wBAAwB;AAC9B,MAAM,iCAAiC;AACvC,MAAM,0BAA0B;AAChC,MAAM,0BAA0B;CAC9B;CAAK;CAAK;CAAK;CAAK;CACrB;;;;;;;;;;;;;AAcD,SAAgB,0BAId,UACA,QACA,SACyC;AACzC,QAAO,2BAA2B,UAAU,QAAQ,QAAQ;;AAG9D,SAAgB,2BAMd,UACA,QACA,SAC6D;AAC7D,QAAO,OAAO,OAAO,SAAS;EAAE;EAAU;EAAQ,CAAC;;AAGrD,MAAa,8BACX,KACA,EAAE,SAAS,gBAAgB,kBAAkB,gBAAgB,WAAW,EAAE,OACvE;CACH,MAAM,UAAU;EAAE;EAAS;EAAgB;EAAkB;EAAgB;CAC7E,MAAM,gBAAgB,SAAS,SAAS,UAAU,OAAO,OAAO,MAAM,CAAC;AACvE,KAAI,cAAc,WAAW,EAAG,QAAO;CAEvC,MAAM,cAAc,cAAc,QAAQ,UAAU,MAAM,aAAa,IAAI,SAAS;AACpF,KAAI,YAAY,WAAW,EAAG,QAAO;CAErC,MAAM,QAAQ,YAAY,MAAM,cAAc,UAAU,WAAW,QAAQ,OAAO;AAClF,KAAI,CAAC,MACH,QAAO,QAAQ,QACb,IAAI,SAAS,sBAAsB,EAAE,QAAQ,gCAAgC,CAAC,CAC/E;AAEH,QAAO,MAAM,QAAQ,CAAC,MAAM,WAAW,2BAA2B,QAAQ,QAAQ,CAAC;;AAGrF,SAAS,2BAA2B,QAAmC,SAA4B;AACjG,KAAI,OAAO,SAAS,YAAY;EAC9B,MAAM,UAAU,IAAI,QAAQ,OAAO,QAAQ;AAC3C,UAAQ,IAAI,YAAY,wBAAwB,OAAO,UAAU,QAAQ,CAAC;AAC1E,SAAO,IAAI,SAAS,MAAM;GACxB,QAAQ,kBAAkB,OAAO,OAAO;GACxC;GACD,CAAC;;AAGJ,KAAI,OAAO,SAAS,SAAS;EAC3B,MAAM,UAAU,IAAI,QAAQ,OAAO,QAAQ;AAC3C,UAAQ,IAAI,gBAAgB,mBAAmB;AAC/C,SAAO,IAAI,SAAS,KAAK,UAAU,EAAE,OAAO,OAAO,OAAO,CAAC,EAAE;GAC3D,QAAQ,OAAO,UAAU;GACzB;GACD,CAAC;;CAGJ,MAAM,UAAU,IAAI,QAAQ,OAAO,QAAQ;AAC3C,SAAQ,IAAI,gBAAgB,mBAAmB;AAC/C,QAAO,IAAI,SAAS,KAAK,UAAU,OAAO,KAAK,EAAE;EAC/C,QAAQ;EACR;EACD,CAAC;;AAGJ,SAAS,kBAAkB,QAAkE;CAC3F,MAAM,iBAAiB,UAAU;AACjC,KAAI,wBAAwB,MAAM,gBAAgB,gBAAgB,eAAe,CAC/E,QAAO;AAGT,OAAM,IAAI,MACR,yCAAyC,eAAe,qBAAqB,wBAAwB,KAAK,KAAK,CAAC,GACjH;;AAGH,SAAS,wBAAwB,UAAkB,SAA0B;AAI3E,QAAO,IAAI,IAAI,UAAU,IAAI,IAAI,QAAQ,IAAI,CAAC,OAAO,CAAC,UAAU"}

package/dist/core/request-routing/route-types.d.mts

@@ -3,53 +3,78 @@ import { StorefrontClient } from "../../client/types.mjs";
 import { ShopifyRouteTemplates } from "../standard-routes/types.mjs";
 
 //#region src/core/request-routing/route-types.d.ts
+/** A value or a promise for that value. */
 type Awaitable<T> = T | Promise<T>;
+/** The session storage that route handlers and the customer session read and write. Implement the methods with your app's session. */
 type ShopifyRouteSessionManager = {
-  getSessionOrigin(): Awaitable<string>;
-  getSessionItem(key: string): Awaitable<unknown>;
-  setSessionItem(key: string, value: unknown): Awaitable<void>;
-  removeSessionItem(key: string): Awaitable<void>;
+  /** Returns your storefront's HTTPS origin. Customer account sign-in builds its OAuth redirect URL from the origin. */getSessionOrigin(): Awaitable<string>; /** Returns the session value stored under a key. */
+  getSessionItem(key: string): Awaitable<unknown>; /** Stores a value in the session under a key. */
+  setSessionItem(key: string, value: unknown): Awaitable<void>; /** Deletes the session value stored under a key. */
+  removeSessionItem(key: string): Awaitable<void>; /** Saves session changes and returns the headers, such as a cookie, to add to the response. */
   commit?(): Awaitable<HeadersInit | void>;
 };
+/** The values that Hydrogen passes to each registered route handler. */
 type ShopifyRouteHandlerContext = {
-  request: Request;
-  sessionManager: ShopifyRouteSessionManager;
-  storefrontClient: StorefrontClient;
+  /** The incoming request that matched the handler's pathname and method. */request: Request; /** Your app's session storage for the current request. */
+  sessionManager: ShopifyRouteSessionManager; /** The Storefront API client for the current request. */
+  storefrontClient: StorefrontClient; /** The current request's context, the same one the Storefront API client uses. */
   requestContext: ShopifyRequestContext;
 };
+/** A route handler result that Hydrogen sends as a `200` JSON response. */
 type ShopifyRouteJsonResult<TData = unknown> = {
-  type: "json";
-  data: TData;
+  /** Set to `json` for a JSON response. */type: "json"; /** The value that Hydrogen serializes as the response body. */
+  data: TData; /** Extra headers for the response. Hydrogen sets `content-type` to `application/json` and overrides any value you pass. */
   headers?: HeadersInit;
 };
+/** The HTTP status codes a route handler can use for a redirect. */
 type ShopifyRedirectStatus = 301 | 302 | 303 | 307 | 308;
+/** A route handler result that Hydrogen sends as a redirect response. */
 type ShopifyRouteRedirectResult = {
-  type: "redirect";
-  location: string; /** HTTP redirect status. Defaults to 303 (See Other). */
-  status?: ShopifyRedirectStatus;
+  /** Set to `redirect` for a redirect response. */type: "redirect"; /** The redirect target. Hydrogen resolves a relative path against the request's origin. */
+  location: string; /** The HTTP redirect status. Defaults to `303`. */
+  status?: ShopifyRedirectStatus; /** Extra headers for the redirect response. */
   headers?: HeadersInit;
 };
+/**
+ * The code and message that an error result sends in the response body's `error` field.
+ *
+ * @publicDocs
+ */
 type ShopifyRouteError = {
-  code: string;
+  /** A machine-readable error code. */code: string; /** A human-readable error message. */
   message: string;
 };
+/** A route handler result that Hydrogen sends as a JSON error response. */
 type ShopifyRouteErrorResult<TError extends ShopifyRouteError = ShopifyRouteError> = {
-  type: "error";
-  error: TError;
-  status?: number;
+  /** Set to `error` for an error response. */type: "error"; /** The error that Hydrogen serializes as the response body's `error` field. */
+  error: TError; /** The HTTP status for the error response. Defaults to `400`. */
+  status?: number; /** Extra headers for the error response. Hydrogen sets `content-type` to `application/json` and overrides any value you pass. */
   headers?: HeadersInit;
 };
+/** The JSON, redirect, or error result that a route handler returns. */
 type ShopifyRouteHandlerResult<TData = unknown, TError extends ShopifyRouteError = ShopifyRouteError> = ShopifyRouteJsonResult<TData> | ShopifyRouteRedirectResult | ShopifyRouteErrorResult<TError>;
+/** A route handler function that also carries the pathname and HTTP method it matches. */
 type CallableRouteHandler<TContext, TResult, TPathname extends string = string, TMethod extends string = string> = ((context: TContext) => Promise<TResult>) & {
   readonly pathname: TPathname;
   readonly method: TMethod;
 };
+/** A handler for one pathname and HTTP method, created with createShopifyRouteHandler. */
 type ShopifyRouteHandler<TPathname extends string = string, TMethod extends string = string> = CallableRouteHandler<ShopifyRouteHandlerContext, ShopifyRouteHandlerResult, TPathname, TMethod>;
+/**
+ * An object of route handlers keyed by name. Pass an array of groups to `handleShopifyRoutes` as `handlers`.
+ *
+ * @publicDocs
+ */
 type ShopifyRouteHandlerGroup = Record<string, ShopifyRouteHandler>;
-type HydrogenRoutesOptions = ShopifyRouteHandlerContext & {
+/** The request, its context and session, the Storefront API client, your route templates, and your handler groups. */
+interface HydrogenRoutesOptions extends ShopifyRouteHandlerContext {
+  /**
+   * Your app's route templates. Hydrogen redirects Liquid-style `?variant=` URLs on your product paths and on Shopify's default product paths.
+   */
   routeTemplates?: ShopifyRouteTemplates;
+  /** The handler groups for your app's custom endpoints. */
   handlers?: readonly ShopifyRouteHandlerGroup[];
-};
+}
 type HydrogenRouteHandler<TExtraOptions extends object = object> = (options: HydrogenRoutesOptions & TExtraOptions) => null | Promise<Response>;
 //#endregion
 export { CallableRouteHandler, HydrogenRouteHandler, ShopifyRedirectStatus, ShopifyRouteError, ShopifyRouteErrorResult, ShopifyRouteHandler, ShopifyRouteHandlerContext, ShopifyRouteHandlerGroup, ShopifyRouteHandlerResult, ShopifyRouteJsonResult, ShopifyRouteRedirectResult, ShopifyRouteSessionManager };