[template] align Shopify data layer (#306)

* [template] align Shopify operation error contract

Standardize how lib/shopify/operations/* signal failure: transport and
GraphQL errors always throw; missing resources return undefined/null/[].
Render-tolerant callers wrap with the new withFallback helper instead of
operations swallowing errors internally.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* [template] inspect userErrors on every cart mutation

Adds ShopifyUserError + unwrapCartMutation helpers so cart mutation
responses are validated uniformly. Previously the line mutations
(cartCreate, cartLinesAdd, cartLinesUpdate, cartLinesRemove) didn't
select userErrors at all; the address/note mutations selected them but
silently ignored them. Now any non-empty userErrors throws with the
Shopify-provided messages, which the action wrappers surface as
{ success: false, error }.

Also removes the dead if (!result) branches from lib/cart/action.ts
that the new contract makes unreachable.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* [template] unify Shopify operation locale calling convention

Convert the eight read operations that took positional (id, locale)
arguments to a single params object, matching the convention already
used by getCollections/getCatalogProducts/searchIndexProducts etc.

Drops the unused _locale param from getMenu while we're here.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* [template] consolidate Shopify fragment and query locations

Apply one rule: shared fragments live in fragments.ts; single-use
queries are named top-level consts in the operation file; nothing is
inlined inside shopifyFetch calls.

- Move CART_FRAGMENT from cart.ts into fragments.ts and rewrite its
  inline money/image selections to reuse MoneyFields / ImageFields,
  matching the composition pattern used by PRODUCT_CARD_FRAGMENT et al.
- Add COLLECTION_FIELDS_FRAGMENT shared by getCollection and
  getCollections, replacing the duplicated inline field selection.
- Hoist all 11 inline cart queries/mutations and the 2 inline
  collection queries to top-level SCREAMING_SNAKE_CASE consts.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* [template] centralize cart cookie reads/writes

Adds getCartIdFromCookie, setCartIdCookie, and
buildCartIdSetCookieHeader to lib/cart/server.ts so the cookie name and
attributes (HttpOnly, Secure, SameSite=Strict, 7-day Max-Age, Path=/)
live in one place. Replaces 11 inline reads and one inline write in
lib/shopify/operations/cart.ts and the manual Set-Cookie string
construction in the chat route.

While inlining, surfaced a latent type narrowing issue in the chat
route's cart-create path — Cart.id is typed as string | undefined
because optimistic client carts have no id, so the streaming
Set-Cookie path now guards explicitly instead of template-literal'ing
undefined.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* [template] fix dead cache tag in getProductById

The "product-id-${id}" tag is never pushed by app/api/webhooks/shopify
or anywhere else — it invalidated nothing. Replace it with
"product-${handle}" added after the fetch resolves, matching the
format the webhook does push (so a Shopify product webhook now
actually invalidates the by-id cache entry).

The numeric-id tag via tagProducts already covered the
admin_graphql_api_id webhook path; this restores the handle path too.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* [template] symmetric transform layout

Move menu transforms (ShopifyMenuItem, ShopifyMenuResponse,
transformShopifyMenu) from lib/shopify/operations/menu.ts to a new
lib/shopify/transforms/menu.ts, matching every other resource (cart,
collection, product, search).

Push filter transformation inside getCollectionProducts and
getSearchFacets. Both now accept an activeFilters param and return
domain Filter[] + PriceRange? instead of raw ShopifyFilter[].
transformShopifyFilters loses its bogus default priceRange {0,1000}
when no PRICE_RANGE filter exists — the optional return type now
matches reality.

4 call sites stop running transformShopifyFilters themselves and stop
maintaining the hasPriceRange workaround they used to detect the
default. Filter sidebar and markdown generators already guard
priceRange with truthy checks, so the behavior shift is visible only
when Shopify returns no price filter at all: the price slider no
longer renders a placeholder 0-1000 range.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Fix: The Storefront API docs describe an operation error-handling contract that is the exact inverse of the actual code after this PR

This commit fixes the issue reported at apps/docs/content/docs/reference/storefront-api.mdx:163

BUG: The "Error handling" section of apps/docs/content/docs/reference/storefront-api.mdx (line ~163) states: "getCart() wraps the call in try-catch and returns undefined on failure, while getProduct() throws if the product isn't found." Both claims are now factually wrong:

1. getProduct() in apps/template/lib/shopify/operations/products.ts now does `if (!data.productByHandle) { return undefined; }` — it RETURNS undefined when the product is missing, it does not throw.

2. getCart() in apps/template/lib/shopify/operations/cart.ts no longer has any try/catch — it throws on transport/GraphQL failure and only returns undefined when there is genuinely no cart/cartId. Render-tolerant callers (components/nav/cart.tsx, app/cart/page.tsx, lib/cart/action.ts) now wrap the call in `withFallback(getCart(), undefined)` (defined in lib/shopify/errors.ts).

This documents the opposite of the PR's headline error contract: operations throw on transport/GraphQL failure and return undefined/null/[] on missing, with withFallback for render-tolerant callers. Per repo guidelines, template feature changes that are documented must have their docs updated. The trigger is concrete: any reader following the docs would implement/expect the inverse error behavior.

FIX: Rewrote the paragraph to describe the new contract — operations throw on transport/GraphQL failure and return undefined/null/[] when a resource is missing; getProduct() returns undefined when not found; getCart() returns undefined when there's no cart; and render paths use the withFallback(promise, fallback) helper to degrade gracefully.

Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
Co-authored-by: laugharn <laugharn@gmail.com>

* Fix: enable-shopify-menus skill shows broken getMenu copy-paste code using the old positional `getMenu("HANDLE", locale)` signature after getMenu was changed to a single object arg `getMenu({ handle })` with no locale

This commit fixes the issue reported at packages/plugin/skills/enable-shopify-menus/SKILL.md:41

BUG: This PR changed `getMenu` in apps/template/lib/shopify/operations/menu.ts from the old positional signature `getMenu(handle: string, _locale: string = defaultLocale)` to a single object parameter `getMenu({ handle }: { handle: string }): Promise<Menu | null>`, removing the locale parameter entirely. However the `enable-shopify-menus` skill (packages/plugin/skills/enable-shopify-menus/SKILL.md lines 41 and 62) and its mirrored docs (apps/docs/content/docs/skills/enable-shopify-menus.mdx lines 52 and 73) still instruct users to copy-paste `const menu = await getMenu("NAV_HANDLE", locale);` and `const menu = await getMenu("FOOTER_HANDLE", locale);`.

Concrete failure trigger: A user following the skill pastes `getMenu("NAV_HANDLE", locale)`. Under the new signature, this passes the string `"NAV_HANDLE"` as the destructured object argument (so `handle` becomes `undefined`), passes an unexpected second `locale` argument, and—in a TypeScript project—fails to compile because a string is not assignable to `{ handle: string }`. The resulting menu query runs with `handle: undefined`, returning no menu. So the skill produces broken, non-compiling code.

Additionally, the `enable-shopify-markets` skill/docs ("update getMenu to derive country and language from the active locale") was inconsistent because getMenu no longer accepts a locale at all.

FIX: Updated the four broken examples to the new object-arg form `getMenu({ handle: "NAV_HANDLE" })` / `getMenu({ handle: "FOOTER_HANDLE" })` in both the SKILL.md and the mirrored .mdx, keeping skill and docs in sync. Also reconciled the markets skill/docs guidance to state that getMenu currently takes only `{ handle }` and must be extended (e.g. `getMenu({ handle, locale })`) to add market scoping, rather than implying it already accepts a locale.

Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>
Co-authored-by: laugharn <laugharn@gmail.com>

* [docs] update getProduct example to match current operation signature

Two "this is the canonical operation pattern" code blocks still
demonstrated the old positional getProduct(handle, locale) form.
Update them to the params-object form, show the Promise<X | undefined>
return type and the if (!data.X) return undefined missing-resource
branch, so a reader copying the example gets the current contract.

Also fix the @/lib/shopify/client import path in the REFERENCE.md
example — that file was renamed to lib/shopify/fetch.ts on 2026-04-25
but the example never got updated.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* [docs] sync remaining lib/shopify/client references to fetch.ts

Three places still referenced the old lib/shopify/client.ts path
(renamed to fetch.ts on 2026-04-25). While in the CMS skill examples,
also bring the example signatures up to the params-object convention
from this PR — getHomepage({ locale }), getMarketingPage({ slug,
locale }).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com>
Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>

Author: 3 people

apps/docs/content/docs/reference/storefront-api.mdx

@@ -89,8 +89,15 @@ import { cacheLife, cacheTag } from "next/cache";
 import { shopifyFetch } from "../fetch";
 import { PRODUCT_FRAGMENT } from "../fragments";
 import { defaultLocale, getCountryCode, getLanguageCode } from "@/lib/i18n";
-
-export async function getProduct(handle: string, locale: string = defaultLocale) {
+import type { ProductDetails } from "@/lib/types";
+
+export async function getProduct({
+  handle,
+  locale = defaultLocale,
+}: {
+  handle: string;
+  locale?: string;
+}): Promise<ProductDetails | undefined> {
   "use cache";
   cacheLife("max");
   cacheTag("products", `product-${handle}`);
@@ -105,6 +112,8 @@ export async function getProduct(handle: string, locale: string = defaultLocale)
     },
   });
 
+  if (!data.productByHandle) return undefined;
+
   return transformShopifyProductDetails(data.productByHandle);
 }
 ```
@@ -160,7 +169,7 @@ The client handles errors at two levels:
 
 **GraphQL errors** - if the response contains `errors` and no `data`, the client throws. If there are errors but `data` is also present (partial success), it logs a warning and returns the partial data.
 
-Individual operations add their own handling on top. For example, `getCart()` wraps the call in try-catch and returns `undefined` on failure, while `getProduct()` throws if the product isn't found.
+Individual operations follow a consistent contract on top of this: they **throw** on transport or GraphQL failure, and **return** `undefined`/`null`/`[]` when a resource is simply missing. For example, `getProduct()` returns `undefined` when the product isn't found (rather than throwing), and `getCart()` returns `undefined` when there's no cart. For render paths that should degrade gracefully instead of crashing on a transport error, wrap the call in the `withFallback(promise, fallback)` helper — e.g. `withFallback(getCart(), undefined)` in the nav and cart page.
 
 ## Debug logging
 

apps/docs/content/docs/skills/enable-shopify-cms.mdx

@@ -62,20 +62,28 @@ Add Shopify metaobject-based CMS support to the shop template. This replaces the
 Implement three operations that return domain types from `lib/types.ts`:
 
 ```ts
-import { shopifyFetch } from "@/lib/shopify/client";
+import { defaultLocale } from "@/lib/i18n";
+import { shopifyFetch } from "@/lib/shopify/fetch";
 import type { Homepage, MarketingPage } from "@/lib/types";
 
-export async function getHomepage(locale: string): Promise<Homepage | null> {
+export async function getHomepage({
+  locale = defaultLocale,
+}: {
+  locale?: string;
+} = {}): Promise<Homepage | null> {
   "use cache";
   cacheLife("max");
   cacheTag("cms-content");
   // Query cms_homepage metaobject, transform to Homepage type
 }
 
-export async function getMarketingPage(
-  slug: string,
-  locale: string,
-): Promise<MarketingPage | null> {
+export async function getMarketingPage({
+  slug,
+  locale = defaultLocale,
+}: {
+  slug: string;
+  locale?: string;
+}): Promise<MarketingPage | null> {
   "use cache";
   cacheLife("max");
   cacheTag("cms-content");

apps/docs/content/docs/skills/enable-shopify-markets.mdx

@@ -330,7 +330,7 @@ export default getRequestConfig(async () => {
 
 ### Scope menu queries for markets
 
-The base template keeps [`lib/shopify/operations/menu.ts`](../../lib/shopify/operations/menu.ts) unscoped so menus load before Shopify Markets is configured. When enabling markets, update `getMenu` to derive `country` and `language` from the active locale and query `menu` with `@inContext(country: $country, language: $language)`. Without that change, quick links and footer menu stay pinned to the default market. If the `enable-shopify-menus` skill has been run, the megamenu will also need this scoping.
+The base template keeps [`lib/shopify/operations/menu.ts`](../../lib/shopify/operations/menu.ts) unscoped (it takes only `{ handle }`) so menus load before Shopify Markets is configured. When enabling markets, extend `getMenu` to accept the active locale (e.g. `getMenu({ handle, locale })`), derive `country` and `language` from that locale, and query `menu` with `@inContext(country: $country, language: $language)`. Without that change, quick links and footer menu stay pinned to the default market. If the `enable-shopify-menus` skill has been run, the megamenu will also need this scoping.
 
 ---
 

apps/docs/content/docs/skills/enable-shopify-menus.mdx

@@ -49,7 +49,7 @@ import { getMenu } from "@/lib/shopify/operations/menu";
 Inside `Nav`, replace `const items = navItems;` with:
 
 ```tsx
-const menu = await getMenu("NAV_HANDLE", locale);
+const menu = await getMenu({ handle: "NAV_HANDLE" });
 const items = menu?.items ?? navItems;
 ```
 
@@ -70,7 +70,7 @@ import { getMenu } from "@/lib/shopify/operations/menu";
 Change the signature to `async` and replace `const items = footerItems;` with:
 
 ```tsx
-const menu = await getMenu("FOOTER_HANDLE", locale);
+const menu = await getMenu({ handle: "FOOTER_HANDLE" });
 const items = menu?.items ?? footerItems;
 ```
 

apps/template/app/api/chat/route.ts

@@ -5,11 +5,11 @@ import {
   createUIMessageStreamResponse,
   safeValidateUIMessages,
 } from "ai";
-import { cookies } from "next/headers";
-
 import { createAgent, type PageContext, type User, withAgentContext } from "@/lib/agent/server";
+import { buildCartIdSetCookieHeader, getCartIdFromCookie } from "@/lib/cart/server";
 import { agent as agentConfig } from "@/lib/config";
 import { defaultLocale, type Locale } from "@/lib/i18n";
+import { withFallback } from "@/lib/shopify/errors";
 import { createCartWithoutCookie } from "@/lib/shopify/operations/cart";
 import { getCollection } from "@/lib/shopify/operations/collections";
 import { getProduct } from "@/lib/shopify/operations/products";
@@ -46,25 +46,15 @@ async function resolvePageContext(
   const pageType = segments[0];
 
   if (pageType === "products" && segments.length >= 2) {
-    try {
-      const handle = segments[1];
-      const product = await getProduct(handle, locale);
-      return { type: "product", product };
-    } catch {
-      // Product not found — fall through to other branches.
-    }
+    const handle = segments[1];
+    const product = await withFallback(getProduct({ handle, locale }), undefined);
+    if (product) return { type: "product", product };
   }
 
   if (pageType === "collections" && segments.length >= 2) {
-    try {
-      const handle = segments[1];
-      const collection = await getCollection(handle, locale);
-      if (collection) {
-        return { type: "collection", handle, title: collection.title };
-      }
-    } catch {
-      // Collection not found — fall through to other branches.
-    }
+    const handle = segments[1];
+    const collection = await withFallback(getCollection({ handle, locale }), undefined);
+    if (collection) return { type: "collection", handle, title: collection.title };
   }
 
   if (pageType === "search") {
@@ -90,7 +80,6 @@ export async function POST(request: Request) {
   }
 
   const body = await request.json();
-  const store = await cookies();
   const { messages, chatId } = body;
 
   if (!chatId) {
@@ -111,15 +100,15 @@ export async function POST(request: Request) {
   const page = await resolvePageContext(segments, locale, referer);
 
   // Get or create cart before streaming (cookies can't be set during stream)
-  let cartId = store.get("shopify_cartId")?.value;
+  let cartId = await getCartIdFromCookie();
   let newCartCookie: string | undefined;
 
   if (!cartId) {
     const newCart = await createCartWithoutCookie(locale);
-    cartId = newCart.id;
-    const secure = process.env.NODE_ENV === "production";
-    const maxAge = 60 * 60 * 24 * 7; // 7 days
-    newCartCookie = `shopify_cartId=${cartId}; Path=/; HttpOnly; SameSite=Strict; Max-Age=${maxAge}${secure ? "; Secure" : ""}`;
+    if (newCart.id) {
+      cartId = newCart.id;
+      newCartCookie = buildCartIdSetCookieHeader(newCart.id);
+    }
   }
 
   return withAgentContext(

apps/template/app/cart/page.tsx

@@ -15,6 +15,7 @@ import { Page } from "@/components/ui/page";
 import { Sections } from "@/components/ui/sections";
 import type { Locale } from "@/lib/i18n";
 import { getLocale } from "@/lib/params";
+import { withFallback } from "@/lib/shopify/errors";
 import { getCart } from "@/lib/shopify/operations/cart";
 
 export async function generateMetadata(): Promise<Metadata> {
@@ -41,7 +42,10 @@ export default async function CartPage() {
 }
 
 async function CartContent({ locale }: { locale: Locale }) {
-  const [cart, messages] = await Promise.all([getCart(), getMessages()]);
+  const [cart, messages] = await Promise.all([
+    withFallback(getCart(), undefined),
+    getMessages(),
+  ]);
 
   return (
     <NextIntlClientProvider messages={{ cart: messages.cart }}>

apps/template/app/collections/[handle]/page.tsx

@@ -30,7 +30,7 @@ export async function generateMetadata({
   }
 
   const [collection, t] = await Promise.all([
-    getCollection(handle, locale),
+    getCollection({ handle, locale }),
     getTranslations("seo"),
   ]);
 
@@ -96,7 +96,7 @@ export default async function CollectionPage({
     if (handle === PLACEHOLDER_HANDLE) notFound();
     return handle;
   });
-  const collectionPromise = handlePromise.then((handle) => getCollection(handle, locale));
+  const collectionPromise = handlePromise.then((handle) => getCollection({ handle, locale }));
   const searchStatePromise = getCollectionSearchState(searchParams);
   const collectionResultsDataPromise = getCollectionResultsData({
     handlePromise,

apps/template/app/md/collections/[handle]/route.ts

@@ -5,7 +5,6 @@ import {
   buildProductFiltersFromParams,
   getCollectionProducts,
 } from "@/lib/shopify/operations/products";
-import { transformShopifyFilters } from "@/lib/shopify/transforms/filters";
 import { RESULTS_PER_PAGE, parseFiltersFromSearchParams, searchParamsToRecord } from "@/lib/utils";
 
 function markdownHeaders(cacheControl: string): HeadersInit {
@@ -29,8 +28,9 @@ export async function GET(request: Request, { params }: { params: Promise<{ hand
 
   try {
     const [collection, result] = await Promise.all([
-      getCollection(handle, locale),
+      getCollection({ handle, locale }),
       getCollectionProducts({
+        activeFilters,
         collection: handle,
         sortKey: sort,
         limit: RESULTS_PER_PAGE,
@@ -50,13 +50,11 @@ export async function GET(request: Request, { params }: { params: Promise<{ hand
       );
     }
 
-    const transformedFilters = transformShopifyFilters(result.filters, { activeFilters });
-    const hasPriceRange = result.filters.some((filter) => filter.type === "PRICE_RANGE");
     const markdown = collectionToMarkdown({
       collection,
       products: result.products,
-      filters: transformedFilters.filters,
-      priceRange: hasPriceRange ? transformedFilters.priceRange : undefined,
+      filters: result.filters,
+      priceRange: result.priceRange,
       activeFilters,
       pageInfo: result.pageInfo,
       locale,

apps/template/app/md/products/[handle]/route.ts

@@ -8,7 +8,23 @@ export async function GET(request: Request, { params }: { params: Promise<{ hand
   const locale = resolveLocale(url.searchParams.get("locale") || defaultLocale);
 
   try {
-    const product = await getProduct(handle, locale);
+    const product = await getProduct({ handle, locale });
+
+    if (!product) {
+      return new Response(
+        `# Product Not Found\n\nThe product with handle \`${handle}\` could not be found.`,
+        {
+          status: 404,
+          headers: {
+            "Content-Type": "text/markdown; charset=utf-8",
+            "Cache-Control": "public, max-age=3600, stale-while-revalidate=604800",
+            Vary: "Accept",
+            "X-Robots-Tag": "noindex",
+          },
+        },
+      );
+    }
+
     const markdown = productToMarkdown(product, locale);
 
     return new Response(markdown, {
@@ -19,21 +35,14 @@ export async function GET(request: Request, { params }: { params: Promise<{ hand
         "X-Robots-Tag": "noindex",
       },
     });
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const isNotFound = message.includes("Product not found");
-
+  } catch {
     return new Response(
-      isNotFound
-        ? `# Product Not Found\n\nThe product with handle \`${handle}\` could not be found.`
-        : `# Server Error\n\nAn error occurred while retrieving the product. Please try again later.`,
+      `# Server Error\n\nAn error occurred while retrieving the product. Please try again later.`,
       {
-        status: isNotFound ? 404 : 500,
+        status: 500,
         headers: {
           "Content-Type": "text/markdown; charset=utf-8",
-          "Cache-Control": isNotFound
-            ? "public, max-age=3600, stale-while-revalidate=604800"
-            : "no-cache, no-store, must-revalidate",
+          "Cache-Control": "no-cache, no-store, must-revalidate",
           Vary: "Accept",
           "X-Robots-Tag": "noindex",
         },

apps/template/app/md/search/route.ts

@@ -5,7 +5,6 @@ import {
   getSearchFacets,
   searchIndexProducts,
 } from "@/lib/shopify/operations/products";
-import { transformShopifyFilters } from "@/lib/shopify/transforms/filters";
 import { RESULTS_PER_PAGE, parseFiltersFromSearchParams, searchParamsToRecord } from "@/lib/utils";
 
 function markdownHeaders(cacheControl: string): HeadersInit {
@@ -39,18 +38,16 @@ export async function GET(request: Request) {
         filters: shopifyFilters,
         locale,
       }),
-      getSearchFacets({ query, collection, filters: shopifyFilters, locale }),
+      getSearchFacets({ activeFilters, query, collection, filters: shopifyFilters, locale }),
     ]);
 
-    const transformedFilters = transformShopifyFilters(facets.filters, { activeFilters });
-    const hasPriceRange = facets.filters.some((filter) => filter.type === "PRICE_RANGE");
     const markdown = searchResultsToMarkdown({
       query,
       collection,
       products: results.products,
       total: facets.total,
-      filters: transformedFilters.filters,
-      priceRange: hasPriceRange ? transformedFilters.priceRange : undefined,
+      filters: facets.filters,
+      priceRange: facets.priceRange,
       activeFilters,
       pageInfo: results.pageInfo,
       locale,