@doswiftly/storefront-operations 13.0.0 → 14.0.0

package/AGENTS.md

@@ -27,8 +27,8 @@ consumer's `codegen.ts` references this package's `.graphql` files as
 live in the consumer's repo.
 
 <!-- AUTOGEN:STATS:BEGIN — auto-regenerated, do not edit by hand -->
-- **Schema version**: 13.0.0
-- **Queries**: 49
+- **Schema version**: 14.0.0
+- **Queries**: 50
 - **Mutations**: 40
 - **Fragments**: 100
 <!-- AUTOGEN:STATS:END -->

package/CHANGELOG.md

@@ -1,5 +1,249 @@
 # Changelog
 
+## 14.0.0
+
+### Major Changes
+
+- 1fda2ab: **BREAKING**: URL identifier unification (`slug` → `handle`) + type renames for naming consistency.
+
+  ### What changed
+
+  URL-friendly identifiers across the storefront GraphQL API now consistently use `handle` (previously a mix of `slug` and `handle`). Canonical product brand entity renamed from `BrandSummary` to `Brand`. Shop branding type `Brand` renamed to `ShopBrand` to free the `Brand` name for the product entity.
+
+  ### Field renames (GraphQL response)
+
+  | Type                         | Old    | New      |
+  | ---------------------------- | ------ | -------- |
+  | `Category`                   | `slug` | `handle` |
+  | `BlogPost`                   | `slug` | `handle` |
+  | `BlogCategory`               | `slug` | `handle` |
+  | `BlogTag`                    | `slug` | `handle` |
+  | `LoyaltyReward`              | `slug` | `handle` |
+  | `BrandFilter` (input)        | `slug` | `handle` |
+  | `BrandFilterValue`           | `slug` | `handle` |
+  | `ProductAttributeDefinition` | `slug` | `handle` |
+  | `CategoryFilterOption`       | `slug` | `handle` |
+
+  ### Type renames
+  - `BrandSummary` → `Brand` (canonical product brand entity, e.g. Funko, Nike). Update `__typename` checks and fragment spreads.
+  - `Brand` (shop branding) → `ShopBrand` (tenant-scoped shop metadata: logo, slogan, colors).
+
+  ### Query args renamed
+
+  ```graphql
+  # Old
+  query { category(slug: "figurki") { id name } }
+  query { blogPost(slug: "post-handle") { title } }
+  query BlogPosts($categorySlug: String, $tagSlug: String) {
+    blogPosts(categorySlug: $categorySlug, tagSlug: $tagSlug) { ... }
+  }
+
+  # New
+  query { category(handle: "figurki") { id name } }
+  query { blogPost(handle: "post-handle") { title } }
+  query BlogPosts($categoryHandle: String, $tagHandle: String) {
+    blogPosts(categoryHandle: $categoryHandle, tagHandle: $tagHandle) { ... }
+  }
+  ```
+
+  ### Brand filter input
+
+  ```graphql
+  # Old
+  products(filters: [{ brand: { slug: "funko" } }]) { ... }
+
+  # New
+  products(filters: [{ brand: { handle: "funko" } }]) { ... }
+  ```
+
+  ### MenuItem resource union
+
+  ```graphql
+  # Old
+  fragment MenuItem on MenuItem {
+    resource {
+      __typename
+      ... on Category {
+        id
+        slug
+        name
+      }
+      ... on BrandSummary {
+        id
+        slug
+        name
+        logo
+      }
+    }
+  }
+
+  # New
+  fragment MenuItem on MenuItem {
+    resource {
+      __typename
+      ... on Category {
+        id
+        handle
+        name
+      }
+      ... on Brand {
+        id
+        handle
+        name
+        logo
+      }
+    }
+  }
+  ```
+
+  ### Migration steps
+  1. Update to `@doswiftly/storefront-operations@^14.0.0` + `@doswiftly/storefront-sdk@^14.0.0`.
+  2. Run your codegen — TypeScript will surface every call site that needs update.
+  3. Find/replace in storefront code:
+     - `.slug` → `.handle` on response fields listed above.
+     - `__typename === 'BrandSummary'` → `__typename === 'Brand'`.
+     - `{ brand: { slug } }` filter input → `{ brand: { handle } }`.
+     - `categorySlug`/`tagSlug` query args → `categoryHandle`/`tagHandle`.
+  4. Update GraphQL fragments selecting renamed fields.
+  5. Re-run codegen, fix any remaining TypeScript errors.
+
+  ### Why
+
+  A single naming convention (`handle`) across all URL identifiers removes ambiguity and matches common e-commerce GraphQL convention. The `BrandSummary` suffix was misleading — no full `Brand` ObjectType existed, so the suffix suggested a missing parent type. Shop branding `Brand` blocked the cleaner name for the product entity.
+
+  Full migration guide with code examples: <https://docs.doswiftly.pl/storefront-developer/migration-14.0>
+
+  Naming conventions reference: <https://docs.doswiftly.pl/storefront-developer/api/naming-conventions>
+
+### Minor Changes
+
+- 507d487: Storefront GraphQL: nowy `attributeOptionsSearch(input)` query — paginated + searchable lista opcji atrybutu (Relay Connection).
+
+  Use case: storefront UI z dużymi filtrami atrybutów (np. 800+ licencji, materiałów, rozmiarów, kolorów) — dropdown z autocomplete i paginacją bez zassania całej listy. `productFilters.attributes[].filterValues[]` zostaje jako quick browse facets (top N), `attributeOptionsSearch` służy do drill-into specific filter card z searchem.
+
+  Dla **marek/producentów** preferuj dedykowane API `productFilters.brands[]` (Brand jest pełnoprawną encją z logo i productCount) — `attributeOptionsSearch(handle: "marka")` jest legacy fallback dla katalogów bez kanonicznej Brand entity.
+
+  **Input** (`AttributeOptionsSearchInput`):
+  - `handle: String!` — slug atrybutu (np. `"marka"`)
+  - `contextInput: AvailableFiltersInput` — produktowy kontekst (kategoria/kolekcja/search/currentFilters) z exclude-self semantyką
+  - `first: Int` (1–100, default 50)
+  - `after: String` — opaque cursor
+  - `search: String` — case-insensitive ILIKE (max 100 znaków)
+  - `sort: AttributeOptionsSearchSort` — `COUNT_DESC` (default, most popular first) lub `LABEL_ASC` (alfabetycznie z polskim collation)
+
+  **Output** (`AttributeFilterValueConnection`): `edges { cursor node }`, `nodes` (shortcut), `pageInfo`, `totalCount`. Wspiera atrybuty `SELECT`/`CHECKBOX`/`RADIO`/`COLOR` (z bazy `attribute_options`) oraz `TEXT`/`TEXTAREA` (z aggregated unique values).
+
+  **Migration**: brak breaking changes — `productFilters` zachowuje obecny shape. Jeśli budujesz "Pokaż wszystkie marki" UI, przenoś logikę na nowy query żeby uniknąć over-fetching.
+
+- 6f8d873: `CartWarningCode` enum gains a fourth value, `SHIPPING_METHOD_AUTO_CLEARED`.
+
+  Cart line mutations (`cartAddLines`, `cartUpdateLines`, `cartRemoveLines`) now reconcile the selected shipping method against cart contents on every call. When a mutation leaves the cart with no items that require physical delivery (digital-only or empty) but a shipping method is still set, the method is cleared automatically and the mutation response surfaces a `CartWarning { code: "SHIPPING_METHOD_AUTO_CLEARED", target: "selectedShippingMethod", message: "…" }`.
+
+  This closes the gap where a mixed cart that lost its last physical line via the storefront UI would persist a stale shipping method and fail later at checkout submit with `FORBIDDEN_SHIPPING_METHOD`. There is no escape hatch needed on the storefront — the mutation accepts non-null `shippingMethodId` only, so the backend takes responsibility for the transition.
+
+  **Storefront impact**: none required. Reads of `cart.selectedShippingMethod` already returned `null` once cleared. Apps that already consume the `warnings[]` array (Apps that follow the standard `userErrors[]` + `warnings[]` payload shape) will surface the auto-clear toast for free. Apps that ignore `warnings[]` continue to work — the mutation still succeeds and the cart is left in a consistent state.
+
+  **Locale**: `message` is translated server-side (`Accept-Language`) — for example, `pl` returns "Wybrana metoda wysyłki została usunięta, ponieważ koszyk nie wymaga już dostawy.", `en` returns "The selected shipping method was removed because the cart no longer requires delivery."
+
+  The warning fires only on the line mutation that triggers the transition, never on subsequent reads or unrelated mutations. Decrementing a physical line quantity from `3` to `1`, removing one physical line while another remains, or adding digital lines to a mixed cart all leave the shipping method untouched.
+
+- 1fda2ab: Storefront navigation menus: typed `resource` field eksponowany w `MenuItem` fragment + nowy typ linku `BRAND`.
+
+  **Co nowego**:
+  - `MenuItem.resource: MenuItemResource` — typed union (`Category` / `Collection` / `ShopPage` / `Product` / `BrandSummary`) wystawiony w `MenuItem` fragment na wszystkich 3 poziomach zagnieżdżenia. Każdy member zwraca `slug` (Category/Product/BrandSummary) lub `handle` (Collection/ShopPage) gotowy do budowy własnego URL.
+  - `MenuItemType.BRAND` — nowy typ linku menu dla marek producentów. `BrandSummary` w `resource` union (`id`, `name`, `slug`, `logo`).
+  - `MenuItem.url` dla `BRAND` resolve'uje się serwerowo jako `/brands/<slug>` — spójnie z istniejącą konwencją `/categories|/collections|/pages|/products/<slug>`.
+
+  **Dwa sposoby renderingu link target**:
+  1. **Standard route convention** — użyj `item.url` jak dotąd. Działa jeśli storefront ma routy `/categories/[slug]`, `/collections/[handle]`, `/pages/[handle]`, `/products/[handle]`, `/brands/[slug]`.
+  2. **Custom routing** (Next.js single-segment, Remix, itd.) — odczytaj `item.resource.__typename` + per-type `slug`/`handle`:
+
+  ```ts
+  function buildHref(item: MenuItem): string {
+    if (!item.resource) return item.url ?? "#";
+    switch (item.resource.__typename) {
+      case "Category":
+        return `/${item.resource.slug}`;
+      case "Collection":
+        return `/${item.resource.handle}`;
+      case "ShopPage":
+        return `/${item.resource.handle}`;
+      case "Product":
+        return `/p/${item.resource.handle}`;
+      case "BrandSummary":
+        return `/marka/${item.resource.slug}`;
+    }
+    return item.url ?? "#";
+  }
+  ```
+
+  **Performance**: wszystkie resource lookupy są batchowane per request — zero N+1 nawet w głębokich menu.
+
+  **Migration**: brak breaking changes. Kod używający tylko `item.url` działa bez zmian. `resource` jest opt-in dopóki nie zaczniesz go selekcjonować w custom fragmencie.
+
+## 13.1.0
+
+### Minor Changes
+
+- 2e137ad: Added cart-aware shipping methods discovery: `Cart.requiresShipping`, `CartLine.requiresShipping`, and `cart.availableShippingMethods(address)`.
+
+  **What's new for the storefront**
+  - **`cart.requiresShipping: Boolean!`** — single signal whether the cart needs physical shipping at all. `false` for carts that contain only digital goods (downloads, gift cards, services, subscriptions). Use it to skip the shipping picker step in checkout entirely.
+  - **`cart.lines.nodes[].requiresShipping: Boolean!`** — per-line classification. Useful in cart drawer UI to flag physical vs digital lines independently.
+  - **`cart.availableShippingMethods(address: ShippingAddressInput!): AvailableShippingMethodsPayload!`** — field on `Cart` that returns shipping methods for the cart's contents at the given destination. The backend pulls subtotal and weight from the cart aggregate — you no longer need to compute them on the client. For digital-only carts the response is `{ methods: [], userErrors: [{ code: 'DIGITAL_ONLY_NO_SHIPPING' }] }`.
+  - **`CartAvailableShippingMethods` query** — new named operation ready to drop into your storefront codegen pipeline.
+
+  **Recommended checkout flow**
+
+  ```graphql
+  query CartAvailableShippingMethods(
+    $cartId: ID!
+    $address: ShippingAddressInput!
+  ) {
+    cart(id: $cartId) {
+      id
+      requiresShipping
+      availableShippingMethods(address: $address) {
+        methods {
+          id
+          name
+          price {
+            amount
+            currencyCode
+          }
+        }
+        userErrors {
+          code
+          message
+          field
+        }
+      }
+    }
+  }
+  ```
+
+  If `cart.requiresShipping === false`, skip rendering the shipping picker and proceed straight to payment. Calling `cartSelectShippingMethod` on a digital-only cart returns `userErrors[{ code: 'FORBIDDEN_SHIPPING_METHOD' }]`, matching the readiness check that `cartComplete` already enforces.
+
+  **Backward compatibility**
+  - The existing standalone `availableShippingMethods(address, cart: CartShippingInput)` query is **unchanged**. Keep using it for pre-cart shipping calculators on product detail pages (when the customer has not created a cart yet).
+  - The new field and new query are purely additive. No existing operations change shape.
+
+  **Free-shipping progress + delivery estimates are now localized**
+
+  The `freeShippingProgress.message` field and `estimatedDelivery.description` field used to be hardcoded in English. They now respect the `Accept-Language` header (defaults to Polish — `pl`). If your storefront previously parsed these strings, switch to the structured fields (`qualifies`, `progressPercent`, `remaining.amount`, `minDays`, `maxDays`) instead.
+
+  **Reason codes on shipping `userErrors`**
+
+  | Code                       | When                             | UI reaction                                  |
+  | -------------------------- | -------------------------------- | -------------------------------------------- |
+  | `DIGITAL_ONLY_NO_SHIPPING` | Cart contains only digital items | Skip shipping picker, go straight to payment |
+  | `NO_SHIPPING_METHODS`      | Address has no matching zone     | Show "no delivery to your country"           |
+  | `SHIPPING_ERROR`           | Internal service error (rare)    | Retry or fall back to pre-cart preview query |
+
+  **Why both packages bump together**
+
+  `@doswiftly/storefront-sdk` ships local copies of the cart fragments that this update extends with `requiresShipping`, so the SDK release pairs with the schema/operations release. `@doswiftly/commerce-policy` exports `NON_PHYSICAL_TYPES` for downstream tooling that wants to mirror the same classification on the client side.
+
 ## 13.0.0
 
 ### Major Changes

package/README.md

@@ -168,7 +168,7 @@ full executable body of each operation.
 
 | Operation | Description |
 | --- | --- |
-| `Product` | Fetches a single product by `id` or `handle` (URL slug). Pass either — whichever is provided wins; if both are missing, returns null. Returns null if the product is not storefront-accessible (must be `ACTIVE` status with `PUBLIC` or `BUNDLE_ONLY` visibility). |
+| `Product` | Fetches a single product by `id` or `handle` (URL-friendly identifier). Pass either — whichever is provided wins; if both are missing, returns null. Returns null if the product is not storefront-accessible (must be `ACTIVE` status with `PUBLIC` or `BUNDLE_ONLY` visibility). |
 | `ProductConfigurator` | Fetches a product together with its filtered attribute definitions, optimized for the configurator UI (e.g. customer-facing text fields, finishing options, scoped variants). `fillingMode: "CUSTOMER"` returns only customer-facing attributes; pass `"BOTH"` to also include attributes shared with the merchant admin. Single round-trip — saves a separate `attributes` query. |
 | `Products` | Paginated product list (Relay Connection, default page size 20, max 100). The `query` argument supports a structured search syntax — `tag:summer`, `vendor:foo`, `product_type:shirts`, `variants.price:>10`, plus `AND`/`OR`/`NOT` — falling back to free-text title/content search. The `filters[]` array uses multi-filter logic: same field name appears multiple times → OR; different fields → AND. Sort: `RELEVANCE`, `TITLE`, `PRICE`, `NEWEST`, `OLDEST`, `BEST_SELLING`. The response includes a `filters` block for faceted navigation (counts per filterable attribute value). |
 | `ProductSearch` | Full-text product search — `$query` is required. Functionally equivalent to `Products` with `$query` set, minus the `sortKey` argument (search defaults to relevance ranking). Use for the search results page; combine with `filters[]` for guided refinement. |
@@ -185,7 +185,7 @@ full executable body of each operation.
 
 | Operation | Description |
 | --- | --- |
-| `Category` | Fetches a single category by `id` or `slug` with its parent and immediate children. Use for breadcrumbs and sub-navigation. Nested queries on `parent` / `children` are batched server-side — safe to use in lists without N+1 concerns. |
+| `Category` | Fetches a single category by `id` or `handle` with its parent and immediate children. Use for breadcrumbs and sub-navigation. Nested queries on `parent` / `children` are batched server-side — safe to use in lists without N+1 concerns. |
 | `Categories` | Returns active root categories for the shop. Each root exposes its `children` — build the tree client-side by walking those fields (server batches the lookups, no N+1). The hierarchy is not depth-capped server-side. Use for nav mega-menus and category pages. |
 
 #### Cart
@@ -241,7 +241,8 @@ full executable body of each operation.
 
 | Operation | Description |
 | --- | --- |
-| `AvailableShippingMethods` | Returns shipping methods for a given destination address and cart shape (subtotal, total weight, currency). The query computes everything from the inputs alone — no existing cart is required, so it can be used for "shipping cost preview" UIs before the customer adds anything to a cart. Each method includes price, free-shipping progress (`{ qualifies, currentAmount, threshold, remaining, progressPercent }`), estimated delivery, and carrier metadata. Sorted by the merchant's `sortOrder`, then by price. |
+| `AvailableShippingMethods` | Returns shipping methods for a given destination address and cart shape (subtotal, total weight, currency). The query computes everything from the inputs alone — no existing cart is required, so it can be used for "shipping cost preview" UIs (e.g. product detail page shipping calculator) before the customer adds anything to a cart. Each method includes price, free-shipping progress (`{ qualifies, currentAmount, threshold, remaining, progressPercent }`), estimated delivery, and carrier metadata. Sorted by the merchant's `sortOrder`, then by price. For a cart-bound checkout flow (where the cart is already known and the storefront wants the resolver to skip non-physical items and surface a `DIGITAL_ONLY_NO_SHIPPING` user error for all-digital carts), use `CartAvailableShippingMethods` against `cart.availableShippingMethods(address)` instead. |
+| `CartAvailableShippingMethods` | Cart-aware shipping methods discovery. Returns shipping methods available for the cart's contents at the given destination, with subtotal and physical-item weight pulled from the cart aggregate (no need to compute them client-side). When the cart contains only non-physical items (digital, gift card, service, subscription), the response is `methods: []` plus a `DIGITAL_ONLY_NO_SHIPPING` user error — use this as the signal to skip rendering the shipping picker step. Prefer this query over the standalone `AvailableShippingMethods` once a cart has been created (`cartCreate`). For pre-cart "shipping cost preview" UIs on product detail pages, the standalone query remains the right tool. |
 
 #### Attribute Filters
 
@@ -279,8 +280,8 @@ full executable body of each operation.
 
 | Operation | Description |
 | --- | --- |
-| `BlogPosts` | Paginated list of published blog posts. Filter by `categorySlug`, `tagSlug`, or `featured` (boolean flag, not enum). Sort: `PUBLISHED_AT` (default), `TITLE`, `VIEW_COUNT`, or `CREATED_AT`. Public; no auth required. |
-| `BlogPost` | Fetches a single blog post by `id` or `slug`. Visibility-gated: returns null if the post is not yet `PUBLISHED` or if its publish date is in the future (scheduled posts stay hidden until their publish time). Side effect: fetching a post increments its `view_count` asynchronously (does not block the response). |
+| `BlogPosts` | Paginated list of published blog posts. Filter by `categoryHandle`, `tagHandle`, or `featured` (boolean flag, not enum). Sort: `PUBLISHED_AT` (default), `TITLE`, `VIEW_COUNT`, or `CREATED_AT`. Public; no auth required. |
+| `BlogPost` | Fetches a single blog post by `id` or `handle`. Visibility-gated: returns null if the post is not yet `PUBLISHED` or if its publish date is in the future (scheduled posts stay hidden until their publish time). Side effect: fetching a post increments its `view_count` asynchronously (does not block the response). |
 | `BlogCategories` | Lists all blog categories with per-category `postCount` and SEO metadata. Use to render category navigation on blog pages. Public; no auth required. |
 | `BlogTags` | Lists blog tags with usage counts (`postCount` per tag). Use to render a tag cloud. Public; no auth required. |
 
@@ -301,7 +302,7 @@ full executable body of each operation.
 
 | Operation | Description |
 | --- | --- |
-| `Menu` | Fetches a navigation menu by `handle` (e.g. `"main-menu"`, `"footer"`, `"mobile"`). Returns the nested item tree. Each item is typed as one of: `HTTP`, `FRONTPAGE`, `SEARCH`, `CATALOG`, `BLOG`, `PRODUCT`, `COLLECTION`, `CATEGORY`, or `PAGE` — switch on the type to render the right link target. Linked resources and URLs are resolved on demand by the field selections in the `Menu` fragment. |
+| `Menu` | Fetches a navigation menu by `handle` (e.g. `"main-menu"`, `"footer"`, `"mobile"`). Returns the nested item tree (up to 3 levels). Each item is typed as one of: `HTTP`, `FRONTPAGE`, `SEARCH`, `CATALOG`, `BLOG`, `PRODUCT`, `COLLECTION`, `CATEGORY`, `PAGE`, or `BRAND` — switch on the type to render the right link target. Each resource-linked item exposes both a pre-resolved `url` (standard `/categories\|/collections\|/pages\|/products\|/brands/<handle>` convention) and a typed `resource` union with the raw handle so storefronts with custom routing can construct their own paths instead. All resource lookups are batched per request — no N+1 even for deep menus. |
 
 #### Content: URL Redirects
 
@@ -458,7 +459,7 @@ full executable body of each operation.
 
 | Fragment | On Type | Description |
 | --- | --- | --- |
-| `Category` | `Category` | Category node in the shop's taxonomy — name, slug, hero image, depth `level`, materialized `path`, product count, sort order. Spread on category cards and breadcrumb segments. Does NOT include parent / children — query those fields separately and let the server batch them. |
+| `Category` | `Category` | Category node in the shop's taxonomy — name, handle, hero image, depth `level`, materialized `path`, product count, sort order. Spread on category cards and breadcrumb segments. Does NOT include parent / children — query those fields separately and let the server batch them. |
 
 #### Customer
 
@@ -553,7 +554,7 @@ full executable body of each operation.
 | `AttributeFilterValue` | `AttributeFilterValue` | One discrete value in a filterable attribute (e.g. "Red" for the Color filter). Includes `productCount` in the current listing context (for "(12)" badges next to filter values), optional swatch and price modifier. |
 | `AttributeDefinition` | `AttributeDefinition` | Filterable attribute exposed on the storefront — name, type (SELECT / CHECKBOX / SLIDER / etc.), filterability flags, display order, and either discrete `filterValues[]` or numeric `rangeBounds`. Spread inside `availableFilters.attributes[]`. |
 | `PriceRangeFilter` | `PriceRange` | Min / max price range across products in the current listing context. Use to bound the price slider. |
-| `CategoryFilterOption` | `CategoryFilterOption` | One category option in the categories filter — id, name, slug, count of products in this category within the current listing context, level + parentId for tree rendering. |
+| `CategoryFilterOption` | `CategoryFilterOption` | One category option in the categories filter — id, name, handle, count of products in this category within the current listing context, level + parentId for tree rendering. |
 | `AvailableFilters` | `AvailableFilters` | Full result of the `productFilters($input)` query — attribute filters, price range, category filters, brands, count of currently active filters, total products in context (Relay-aligned `totalCount`), and boolean facet count for `availableForSale` (`availableCount`). Spread on listing pages to render filter sidebars. Per-facet counts (`attributes[].filterValues[].productCount`, `brands[].productCount`, `categories[].productCount`, `availableCount`) use exclude-self aggregation: when a dimension is in `input.currentFilters` / `input.available`, its own facet count IGNORES that filter (shows "how many products would appear if this facet were toggled"), while OTHER dimensions APPLY their filters. This matches industry convention for accurate facet UX. |
 
 #### Loyalty Program
@@ -592,9 +593,9 @@ full executable body of each operation.
 
 | Fragment | On Type | Description |
 | --- | --- | --- |
-| `BlogCategory` | `BlogCategory` | Blog category — name, slug, description, post count. Spread on category navigation and post category labels. |
-| `BlogTag` | `BlogTag` | Blog tag — name, slug, post count. Spread on tag clouds and post tag labels. |
-| `BlogPost` | `BlogPost` | Full blog post — title, slug, excerpt, content (with `contentFormat` indicating HTML/Markdown), featured image, author, category, tags, publish date, reading time, view + comment counts, SEO metadata. Spread on the post detail page. |
+| `BlogCategory` | `BlogCategory` | Blog category — name, handle, description, post count. Spread on category navigation and post category labels. |
+| `BlogTag` | `BlogTag` | Blog tag — name, handle, post count. Spread on tag clouds and post tag labels. |
+| `BlogPost` | `BlogPost` | Full blog post — title, handle, excerpt, content (with `contentFormat` indicating HTML/Markdown), featured image, author, category, tags, publish date, reading time, view + comment counts, SEO metadata. Spread on the post detail page. |
 
 #### Store Availability (BOPIS / multi-location)
 
@@ -612,13 +613,13 @@ full executable body of each operation.
 
 | Fragment | On Type | Description |
 | --- | --- | --- |
-| `ShopPage` | `ShopPage` | CMS page — handle (URL slug), title, body (HTML), excerpt, SEO metadata, publish date. Spread on About / Privacy / Terms / Returns Policy pages. |
+| `ShopPage` | `ShopPage` | CMS page — handle (URL-friendly identifier), title, body (HTML), excerpt, SEO metadata, publish date. Spread on About / Privacy / Terms / Returns Policy pages. |
 
 #### Navigation Menus
 
 | Fragment | On Type | Description |
 | --- | --- | --- |
-| `MenuItem` | `MenuItem` | One menu item with up to 3 levels of nested children — title, URL, type (`HTTP` / `FRONTPAGE` / `SEARCH` / `CATALOG` / `BLOG` / `PRODUCT` / `COLLECTION` / `CATEGORY` / `PAGE`), `resourceId` for typed items, optional image. Switch on `type` to render the right link target. |
+| `MenuItem` | `MenuItem` | One menu item with up to 3 levels of nested children — title, URL, type (`HTTP` / `FRONTPAGE` / `SEARCH` / `CATALOG` / `BLOG` / `PRODUCT` / `COLLECTION` / `CATEGORY` / `PAGE` / `BRAND`), `resourceId` for typed items, optional image, and a typed `resource` union (Category / Collection / ShopPage / Product / Brand) carrying the linked resource's handle. Two ways to render the link target: (1) use the pre-resolved `url` if your storefront follows the standard `/categories\|/collections\|/pages\|/products\|/brands/<handle>` route convention; (2) read `resource.__typename` + the per-type `handle` and build your own paths if your storefront uses different routing. Switch on `type` to decide which static (FRONTPAGE/SEARCH/CATALOG/BLOG) or dynamic target to render. |
 | `Menu` | `Menu` | Navigation menu — handle (e.g. "main-menu", "footer", "mobile"), title, nested item tree. Returned by `menu($handle)` query. |
 
 #### URL Redirects

package/fragments.graphql

@@ -119,7 +119,7 @@ fragment ProductCard on Product {
   vendor
   categories {
     id
-    slug
+    handle
     name
   }
   isAvailable
@@ -225,11 +225,11 @@ fragment Collection on Collection {
 # Categories
 # ============================================
 
-# Category node in the shop's taxonomy — name, slug, hero image, depth `level`, materialized `path`, product count, sort order. Spread on category cards and breadcrumb segments. Does NOT include parent / children — query those fields separately and let the server batch them.
+# Category node in the shop's taxonomy — name, handle, hero image, depth `level`, materialized `path`, product count, sort order. Spread on category cards and breadcrumb segments. Does NOT include parent / children — query those fields separately and let the server batch them.
 fragment Category on Category {
   id
   name
-  slug
+  handle
   description
   image {
     ...ImageCard
@@ -407,6 +407,7 @@ fragment CartLine on CartLine {
   productTitle
   productHandle
   productType
+  requiresShipping
 }
 
 # Buyer identity associated with the cart. Note: only `customerId` is currently persisted server-side; `email`, `phone`, `countryCode` are accepted in the input but ignored.
@@ -488,6 +489,7 @@ fragment Cart on Cart {
   appliedGiftCards {
     ...CartAppliedGiftCard
   }
+  requiresShipping
   createdAt
   updatedAt
 }
@@ -1002,11 +1004,11 @@ fragment PriceRangeFilter on PriceRange {
   }
 }
 
-# One category option in the categories filter — id, name, slug, count of products in this category within the current listing context, level + parentId for tree rendering.
+# One category option in the categories filter — id, name, handle, count of products in this category within the current listing context, level + parentId for tree rendering.
 fragment CategoryFilterOption on CategoryFilterOption {
   id
   name
-  slug
+  handle
   productCount
   level
   parentId
@@ -1119,7 +1121,7 @@ fragment LoyaltyTransaction on LoyaltyTransaction {
 fragment LoyaltyReward on LoyaltyReward {
   id
   name
-  slug
+  handle
   type
   pointsCost
   discountPercent
@@ -1269,28 +1271,28 @@ fragment Wishlist on Wishlist {
 # Blog
 # ============================================
 
-# Blog category — name, slug, description, post count. Spread on category navigation and post category labels.
+# Blog category — name, handle, description, post count. Spread on category navigation and post category labels.
 fragment BlogCategory on BlogCategory {
   id
   name
-  slug
+  handle
   description
   postCount
 }
 
-# Blog tag — name, slug, post count. Spread on tag clouds and post tag labels.
+# Blog tag — name, handle, post count. Spread on tag clouds and post tag labels.
 fragment BlogTag on BlogTag {
   id
   name
-  slug
+  handle
   postCount
 }
 
-# Full blog post — title, slug, excerpt, content (with `contentFormat` indicating HTML/Markdown), featured image, author, category, tags, publish date, reading time, view + comment counts, SEO metadata. Spread on the post detail page.
+# Full blog post — title, handle, excerpt, content (with `contentFormat` indicating HTML/Markdown), featured image, author, category, tags, publish date, reading time, view + comment counts, SEO metadata. Spread on the post detail page.
 fragment BlogPost on BlogPost {
   id
   title
-  slug
+  handle
   excerpt
   content
   contentFormat
@@ -1425,7 +1427,7 @@ fragment VariantStoreAvailability on ProductVariant {
 # Pages
 # ============================================
 
-# CMS page — handle (URL slug), title, body (HTML), excerpt, SEO metadata, publish date. Spread on About / Privacy / Terms / Returns Policy pages.
+# CMS page — handle (URL-friendly identifier), title, body (HTML), excerpt, SEO metadata, publish date. Spread on About / Privacy / Terms / Returns Policy pages.
 fragment ShopPage on ShopPage {
   id
   handle
@@ -1445,13 +1447,21 @@ fragment ShopPage on ShopPage {
 # Navigation Menus
 # ============================================
 
-# One menu item with up to 3 levels of nested children — title, URL, type (`HTTP` / `FRONTPAGE` / `SEARCH` / `CATALOG` / `BLOG` / `PRODUCT` / `COLLECTION` / `CATEGORY` / `PAGE`), `resourceId` for typed items, optional image. Switch on `type` to render the right link target.
+# One menu item with up to 3 levels of nested children — title, URL, type (`HTTP` / `FRONTPAGE` / `SEARCH` / `CATALOG` / `BLOG` / `PRODUCT` / `COLLECTION` / `CATEGORY` / `PAGE` / `BRAND`), `resourceId` for typed items, optional image, and a typed `resource` union (Category / Collection / ShopPage / Product / Brand) carrying the linked resource's handle. Two ways to render the link target: (1) use the pre-resolved `url` if your storefront follows the standard `/categories|/collections|/pages|/products|/brands/<handle>` route convention; (2) read `resource.__typename` + the per-type `handle` and build your own paths if your storefront uses different routing. Switch on `type` to decide which static (FRONTPAGE/SEARCH/CATALOG/BLOG) or dynamic target to render.
 fragment MenuItem on MenuItem {
   id
   title
   url
   type
   resourceId
+  resource {
+    __typename
+    ... on Category { id handle name }
+    ... on Collection { id handle title }
+    ... on ShopPage { id handle title }
+    ... on Product { id handle title }
+    ... on Brand { id handle name logo }
+  }
   image {
     ...Image
   }
@@ -1461,12 +1471,28 @@ fragment MenuItem on MenuItem {
     url
     type
     resourceId
+    resource {
+      __typename
+      ... on Category { id handle name }
+      ... on Collection { id handle title }
+      ... on ShopPage { id handle title }
+      ... on Product { id handle title }
+      ... on Brand { id handle name logo }
+    }
     items {
       id
       title
       url
       type
       resourceId
+      resource {
+        __typename
+        ... on Category { id handle name }
+        ... on Collection { id handle title }
+        ... on ShopPage { id handle title }
+        ... on Product { id handle title }
+        ... on Brand { id handle name logo }
+      }
     }
   }
 }
@@ -1526,7 +1552,7 @@ fragment ProductAttributeOption on ProductAttributeOption {
 fragment ProductAttributeDefinition on ProductAttributeDefinition {
   id
   name
-  slug
+  handle
   description
   type
   fillingMode