@doswiftly/storefront-operations 13.1.0 → 14.0.0

package/llms-full.txt

@@ -1,6 +1,6 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **13.1.0**
+> Schema version: **14.0.0**
 > 50 queries · 40 mutations · 100 fragments
 
 Auto-generated from `.graphql` source files. Do not edit by hand — this file is
@@ -41,7 +41,7 @@ query Shop {
 
 **Section**: Products
 
-**Description**: 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).
+**Description**: 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).
 
 **Variables**:
 - `$id`: `ID`
@@ -274,18 +274,18 @@ query Collections($first: Int = 20, $after: String, $query: String, $sortKey: Co
 
 **Section**: Categories
 
-**Description**: 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.
+**Description**: 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.
 
 **Variables**:
 - `$id`: `ID`
-- `$slug`: `String`
+- `$handle`: `String`
 
 **Fragments used**: `Category`
 
 **GraphQL**:
 ```graphql
-query Category($id: ID, $slug: String) {
-  category(id: $id, slug: $slug) {
+query Category($id: ID, $handle: String) {
+  category(id: $id, handle: $handle) {
     ...Category
     parent {
       ...Category
@@ -1018,13 +1018,13 @@ query WishlistById($id: ID!) {
 
 **Section**: Blog
 
-**Description**: 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.
+**Description**: 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.
 
 **Variables**:
 - `$first`: `Int` *(default: `20`)*
 - `$after`: `String`
-- `$categorySlug`: `String`
-- `$tagSlug`: `String`
+- `$categoryHandle`: `String`
+- `$tagHandle`: `String`
 - `$featured`: `Boolean`
 - `$sortKey`: `BlogPostSortKey` *(default: `PUBLISHED_AT`)*
 - `$reverse`: `Boolean` *(default: `false`)*
@@ -1033,12 +1033,12 @@ query WishlistById($id: ID!) {
 
 **GraphQL**:
 ```graphql
-query BlogPosts($first: Int = 20, $after: String, $categorySlug: String, $tagSlug: String, $featured: Boolean, $sortKey: BlogPostSortKey = PUBLISHED_AT, $reverse: Boolean = false) {
+query BlogPosts($first: Int = 20, $after: String, $categoryHandle: String, $tagHandle: String, $featured: Boolean, $sortKey: BlogPostSortKey = PUBLISHED_AT, $reverse: Boolean = false) {
   blogPosts(
     first: $first
     after: $after
-    categorySlug: $categorySlug
-    tagSlug: $tagSlug
+    categoryHandle: $categoryHandle
+    tagHandle: $tagHandle
     featured: $featured
     sortKey: $sortKey
     reverse: $reverse
@@ -1061,18 +1061,18 @@ query BlogPosts($first: Int = 20, $after: String, $categorySlug: String, $tagSlu
 
 **Section**: Blog
 
-**Description**: 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).
+**Description**: 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).
 
 **Variables**:
 - `$id`: `ID`
-- `$slug`: `String`
+- `$handle`: `String`
 
 **Fragments used**: `BlogPost`
 
 **GraphQL**:
 ```graphql
-query BlogPost($id: ID, $slug: String) {
-  blogPost(id: $id, slug: $slug) {
+query BlogPost($id: ID, $handle: String) {
+  blogPost(id: $id, handle: $handle) {
     ...BlogPost
   }
 }
@@ -1202,7 +1202,7 @@ query Pages($first: Int = 20, $after: String, $sortKey: PageSortKeys = TITLE, $r
 
 **Section**: Content: Navigation Menus
 
-**Description**: 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.
+**Description**: 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.
 
 **Variables**:
 - `$handle`: `String!`
@@ -2590,7 +2590,7 @@ fragment ProductCard on Product {
   vendor
   categories {
     id
-    slug
+    handle
     name
   }
   isAvailable
@@ -2723,7 +2723,7 @@ fragment Collection on Collection {
 
 **Section**: Categories
 
-**Description**: 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.
+**Description**: 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.
 
 **Uses fragments**: `ImageCard`
 
@@ -2732,7 +2732,7 @@ fragment Collection on Collection {
 fragment Category on Category {
   id
   name
-  slug
+  handle
   description
   image {
     ...ImageCard
@@ -3904,14 +3904,14 @@ fragment PriceRangeFilter on PriceRange {
 
 **Section**: Attribute Filters
 
-**Description**: 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.
+**Description**: 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.
 
 **GraphQL**:
 ```graphql
 fragment CategoryFilterOption on CategoryFilterOption {
   id
   name
-  slug
+  handle
   productCount
   level
   parentId
@@ -4094,7 +4094,7 @@ fragment LoyaltyTransaction on LoyaltyTransaction {
 fragment LoyaltyReward on LoyaltyReward {
   id
   name
-  slug
+  handle
   type
   pointsCost
   discountPercent
@@ -4327,14 +4327,14 @@ fragment Wishlist on Wishlist {
 
 **Section**: Blog
 
-**Description**: Blog category — name, slug, description, post count. Spread on category navigation and post category labels.
+**Description**: Blog category — name, handle, description, post count. Spread on category navigation and post category labels.
 
 **GraphQL**:
 ```graphql
 fragment BlogCategory on BlogCategory {
   id
   name
-  slug
+  handle
   description
   postCount
 }
@@ -4344,14 +4344,14 @@ fragment BlogCategory on BlogCategory {
 
 **Section**: Blog
 
-**Description**: Blog tag — name, slug, post count. Spread on tag clouds and post tag labels.
+**Description**: Blog tag — name, handle, post count. Spread on tag clouds and post tag labels.
 
 **GraphQL**:
 ```graphql
 fragment BlogTag on BlogTag {
   id
   name
-  slug
+  handle
   postCount
 }
 ```
@@ -4360,7 +4360,7 @@ fragment BlogTag on BlogTag {
 
 **Section**: Blog
 
-**Description**: 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.
+**Description**: 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.
 
 **Uses fragments**: `BlogCategory`, `BlogTag`, `ImageCard`, `ImageThumbnail`
 
@@ -4369,7 +4369,7 @@ fragment BlogTag on BlogTag {
 fragment BlogPost on BlogPost {
   id
   title
-  slug
+  handle
   excerpt
   content
   contentFormat
@@ -4575,7 +4575,7 @@ fragment VariantStoreAvailability on ProductVariant {
 
 **Section**: Pages
 
-**Description**: CMS page — handle (URL slug), title, body (HTML), excerpt, SEO metadata, publish date. Spread on About / Privacy / Terms / Returns Policy pages.
+**Description**: CMS page — handle (URL-friendly identifier), title, body (HTML), excerpt, SEO metadata, publish date. Spread on About / Privacy / Terms / Returns Policy pages.
 
 **GraphQL**:
 ```graphql
@@ -4599,7 +4599,7 @@ fragment ShopPage on ShopPage {
 
 **Section**: Navigation Menus
 
-**Description**: 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.
+**Description**: 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.
 
 **Uses fragments**: `Image`
 
@@ -4611,6 +4611,35 @@ 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
+    }
+  }
   image {
     ...Image
   }
@@ -4620,12 +4649,70 @@ 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
+        }
+      }
     }
   }
 }
@@ -4723,7 +4810,7 @@ fragment ProductAttributeOption on ProductAttributeOption {
 fragment ProductAttributeDefinition on ProductAttributeDefinition {
   id
   name
-  slug
+  handle
   description
   type
   fillingMode

package/operations.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "13.1.0",
+  "schemaVersion": "14.0.0",
   "queries": [
     {
       "name": "Shop",
@@ -16,7 +16,7 @@
       "name": "Product",
       "kind": "query",
       "section": "Products",
-      "description": "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).",
+      "description": "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).",
       "variables": [
         {
           "name": "id",
@@ -236,7 +236,7 @@
       "name": "Category",
       "kind": "query",
       "section": "Categories",
-      "description": "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.",
+      "description": "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.",
       "variables": [
         {
           "name": "id",
@@ -244,7 +244,7 @@
           "defaultValue": null
         },
         {
-          "name": "slug",
+          "name": "handle",
           "type": "String",
           "defaultValue": null
         }
@@ -252,7 +252,7 @@
       "fragmentRefs": [
         "Category"
       ],
-      "body": "query Category($id: ID, $slug: String) {\n  category(id: $id, slug: $slug) {\n    ...Category\n    parent {\n      ...Category\n    }\n    children {\n      ...Category\n    }\n  }\n}"
+      "body": "query Category($id: ID, $handle: String) {\n  category(id: $id, handle: $handle) {\n    ...Category\n    parent {\n      ...Category\n    }\n    children {\n      ...Category\n    }\n  }\n}"
     },
     {
       "name": "Categories",
@@ -758,7 +758,7 @@
       "name": "BlogPosts",
       "kind": "query",
       "section": "Blog",
-      "description": "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.",
+      "description": "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.",
       "variables": [
         {
           "name": "first",
@@ -771,12 +771,12 @@
           "defaultValue": null
         },
         {
-          "name": "categorySlug",
+          "name": "categoryHandle",
           "type": "String",
           "defaultValue": null
         },
         {
-          "name": "tagSlug",
+          "name": "tagHandle",
           "type": "String",
           "defaultValue": null
         },
@@ -800,13 +800,13 @@
         "BlogPost",
         "PageInfo"
       ],
-      "body": "query BlogPosts($first: Int = 20, $after: String, $categorySlug: String, $tagSlug: String, $featured: Boolean, $sortKey: BlogPostSortKey = PUBLISHED_AT, $reverse: Boolean = false) {\n  blogPosts(\n    first: $first\n    after: $after\n    categorySlug: $categorySlug\n    tagSlug: $tagSlug\n    featured: $featured\n    sortKey: $sortKey\n    reverse: $reverse\n  ) {\n    edges {\n      node {\n        ...BlogPost\n      }\n      cursor\n    }\n    pageInfo {\n      ...PageInfo\n    }\n    totalCount\n  }\n}"
+      "body": "query BlogPosts($first: Int = 20, $after: String, $categoryHandle: String, $tagHandle: String, $featured: Boolean, $sortKey: BlogPostSortKey = PUBLISHED_AT, $reverse: Boolean = false) {\n  blogPosts(\n    first: $first\n    after: $after\n    categoryHandle: $categoryHandle\n    tagHandle: $tagHandle\n    featured: $featured\n    sortKey: $sortKey\n    reverse: $reverse\n  ) {\n    edges {\n      node {\n        ...BlogPost\n      }\n      cursor\n    }\n    pageInfo {\n      ...PageInfo\n    }\n    totalCount\n  }\n}"
     },
     {
       "name": "BlogPost",
       "kind": "query",
       "section": "Blog",
-      "description": "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).",
+      "description": "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).",
       "variables": [
         {
           "name": "id",
@@ -814,7 +814,7 @@
           "defaultValue": null
         },
         {
-          "name": "slug",
+          "name": "handle",
           "type": "String",
           "defaultValue": null
         }
@@ -822,7 +822,7 @@
       "fragmentRefs": [
         "BlogPost"
       ],
-      "body": "query BlogPost($id: ID, $slug: String) {\n  blogPost(id: $id, slug: $slug) {\n    ...BlogPost\n  }\n}"
+      "body": "query BlogPost($id: ID, $handle: String) {\n  blogPost(id: $id, handle: $handle) {\n    ...BlogPost\n  }\n}"
     },
     {
       "name": "BlogCategories",
@@ -937,7 +937,7 @@
       "name": "Menu",
       "kind": "query",
       "section": "Content: Navigation Menus",
-      "description": "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.",
+      "description": "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.",
       "variables": [
         {
           "name": "handle",
@@ -1944,7 +1944,7 @@
         "ImageCard",
         "Money"
       ],
-      "body": "fragment ProductCard on Product {\n  id\n  handle\n  title\n  vendor\n  categories {\n    id\n    slug\n    name\n  }\n  isAvailable\n  averageRating\n  reviewCount\n  tags\n  featuredImage {\n    ...ImageCard\n  }\n  priceRange {\n    minVariantPrice {\n      ...Money\n    }\n    maxVariantPrice {\n      ...Money\n    }\n  }\n  compareAtPriceRange {\n    minVariantPrice {\n      ...Money\n    }\n    maxVariantPrice {\n      ...Money\n    }\n  }\n}",
+      "body": "fragment ProductCard on Product {\n  id\n  handle\n  title\n  vendor\n  categories {\n    id\n    handle\n    name\n  }\n  isAvailable\n  averageRating\n  reviewCount\n  tags\n  featuredImage {\n    ...ImageCard\n  }\n  priceRange {\n    minVariantPrice {\n      ...Money\n    }\n    maxVariantPrice {\n      ...Money\n    }\n  }\n  compareAtPriceRange {\n    minVariantPrice {\n      ...Money\n    }\n    maxVariantPrice {\n      ...Money\n    }\n  }\n}",
       "onType": "Product"
     },
     {
@@ -1990,12 +1990,12 @@
       "name": "Category",
       "kind": "fragment",
       "section": "Categories",
-      "description": "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.",
+      "description": "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.",
       "variables": [],
       "fragmentRefs": [
         "ImageCard"
       ],
-      "body": "fragment Category on Category {\n  id\n  name\n  slug\n  description\n  image {\n    ...ImageCard\n  }\n  level\n  path\n  productCount\n  sortOrder\n}",
+      "body": "fragment Category on Category {\n  id\n  name\n  handle\n  description\n  image {\n    ...ImageCard\n  }\n  level\n  path\n  productCount\n  sortOrder\n}",
       "onType": "Category"
     },
     {
@@ -2571,10 +2571,10 @@
       "name": "CategoryFilterOption",
       "kind": "fragment",
       "section": "Attribute Filters",
-      "description": "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.",
+      "description": "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.",
       "variables": [],
       "fragmentRefs": [],
-      "body": "fragment CategoryFilterOption on CategoryFilterOption {\n  id\n  name\n  slug\n  productCount\n  level\n  parentId\n}",
+      "body": "fragment CategoryFilterOption on CategoryFilterOption {\n  id\n  name\n  handle\n  productCount\n  level\n  parentId\n}",
       "onType": "CategoryFilterOption"
     },
     {
@@ -2672,7 +2672,7 @@
         "LoyaltyTier",
         "Money"
       ],
-      "body": "fragment LoyaltyReward on LoyaltyReward {\n  id\n  name\n  slug\n  type\n  pointsCost\n  discountPercent\n  discountAmount {\n    ...Money\n  }\n  description\n  image {\n    ...ImageCard\n  }\n  isAvailable\n  tierRequired {\n    ...LoyaltyTier\n  }\n  redemptionsRemaining\n}",
+      "body": "fragment LoyaltyReward on LoyaltyReward {\n  id\n  name\n  handle\n  type\n  pointsCost\n  discountPercent\n  discountAmount {\n    ...Money\n  }\n  description\n  image {\n    ...ImageCard\n  }\n  isAvailable\n  tierRequired {\n    ...LoyaltyTier\n  }\n  redemptionsRemaining\n}",
       "onType": "LoyaltyReward"
     },
     {
@@ -2790,27 +2790,27 @@
       "name": "BlogCategory",
       "kind": "fragment",
       "section": "Blog",
-      "description": "Blog category — name, slug, description, post count. Spread on category navigation and post category labels.",
+      "description": "Blog category — name, handle, description, post count. Spread on category navigation and post category labels.",
       "variables": [],
       "fragmentRefs": [],
-      "body": "fragment BlogCategory on BlogCategory {\n  id\n  name\n  slug\n  description\n  postCount\n}",
+      "body": "fragment BlogCategory on BlogCategory {\n  id\n  name\n  handle\n  description\n  postCount\n}",
       "onType": "BlogCategory"
     },
     {
       "name": "BlogTag",
       "kind": "fragment",
       "section": "Blog",
-      "description": "Blog tag — name, slug, post count. Spread on tag clouds and post tag labels.",
+      "description": "Blog tag — name, handle, post count. Spread on tag clouds and post tag labels.",
       "variables": [],
       "fragmentRefs": [],
-      "body": "fragment BlogTag on BlogTag {\n  id\n  name\n  slug\n  postCount\n}",
+      "body": "fragment BlogTag on BlogTag {\n  id\n  name\n  handle\n  postCount\n}",
       "onType": "BlogTag"
     },
     {
       "name": "BlogPost",
       "kind": "fragment",
       "section": "Blog",
-      "description": "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.",
+      "description": "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.",
       "variables": [],
       "fragmentRefs": [
         "BlogCategory",
@@ -2818,7 +2818,7 @@
         "ImageCard",
         "ImageThumbnail"
       ],
-      "body": "fragment BlogPost on BlogPost {\n  id\n  title\n  slug\n  excerpt\n  content\n  contentFormat\n  featuredImage {\n    ...ImageCard\n  }\n  author {\n    id\n    name\n    bio\n    avatar {\n      ...ImageThumbnail\n    }\n  }\n  category {\n    ...BlogCategory\n  }\n  tags {\n    ...BlogTag\n  }\n  publishedAt\n  readingTimeMinutes\n  viewCount\n  commentCount\n  allowComments\n  isFeatured\n  status\n  seo {\n    title\n    description\n  }\n  createdAt\n  updatedAt\n}",
+      "body": "fragment BlogPost on BlogPost {\n  id\n  title\n  handle\n  excerpt\n  content\n  contentFormat\n  featuredImage {\n    ...ImageCard\n  }\n  author {\n    id\n    name\n    bio\n    avatar {\n      ...ImageThumbnail\n    }\n  }\n  category {\n    ...BlogCategory\n  }\n  tags {\n    ...BlogTag\n  }\n  publishedAt\n  readingTimeMinutes\n  viewCount\n  commentCount\n  allowComments\n  isFeatured\n  status\n  seo {\n    title\n    description\n  }\n  createdAt\n  updatedAt\n}",
       "onType": "BlogPost"
     },
     {
@@ -2907,7 +2907,7 @@
       "name": "ShopPage",
       "kind": "fragment",
       "section": "Pages",
-      "description": "CMS page — handle (URL slug), title, body (HTML), excerpt, SEO metadata, publish date. Spread on About / Privacy / Terms / Returns Policy pages.",
+      "description": "CMS page — handle (URL-friendly identifier), title, body (HTML), excerpt, SEO metadata, publish date. Spread on About / Privacy / Terms / Returns Policy pages.",
       "variables": [],
       "fragmentRefs": [],
       "body": "fragment ShopPage on ShopPage {\n  id\n  handle\n  title\n  body\n  excerpt\n  seo {\n    title\n    description\n  }\n  publishedAt\n  createdAt\n  updatedAt\n}",
@@ -2917,12 +2917,12 @@
       "name": "MenuItem",
       "kind": "fragment",
       "section": "Navigation Menus",
-      "description": "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.",
+      "description": "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.",
       "variables": [],
       "fragmentRefs": [
         "Image"
       ],
-      "body": "fragment MenuItem on MenuItem {\n  id\n  title\n  url\n  type\n  resourceId\n  image {\n    ...Image\n  }\n  items {\n    id\n    title\n    url\n    type\n    resourceId\n    items {\n      id\n      title\n      url\n      type\n      resourceId\n    }\n  }\n}",
+      "body": "fragment MenuItem on MenuItem {\n  id\n  title\n  url\n  type\n  resourceId\n  resource {\n    __typename\n    ... on Category {\n      id\n      handle\n      name\n    }\n    ... on Collection {\n      id\n      handle\n      title\n    }\n    ... on ShopPage {\n      id\n      handle\n      title\n    }\n    ... on Product {\n      id\n      handle\n      title\n    }\n    ... on Brand {\n      id\n      handle\n      name\n      logo\n    }\n  }\n  image {\n    ...Image\n  }\n  items {\n    id\n    title\n    url\n    type\n    resourceId\n    resource {\n      __typename\n      ... on Category {\n        id\n        handle\n        name\n      }\n      ... on Collection {\n        id\n        handle\n        title\n      }\n      ... on ShopPage {\n        id\n        handle\n        title\n      }\n      ... on Product {\n        id\n        handle\n        title\n      }\n      ... on Brand {\n        id\n        handle\n        name\n        logo\n      }\n    }\n    items {\n      id\n      title\n      url\n      type\n      resourceId\n      resource {\n        __typename\n        ... on Category {\n          id\n          handle\n          name\n        }\n        ... on Collection {\n          id\n          handle\n          title\n        }\n        ... on ShopPage {\n          id\n          handle\n          title\n        }\n        ... on Product {\n          id\n          handle\n          title\n        }\n        ... on Brand {\n          id\n          handle\n          name\n          logo\n        }\n      }\n    }\n  }\n}",
       "onType": "MenuItem"
     },
     {
@@ -2978,7 +2978,7 @@
       "fragmentRefs": [
         "ProductAttributeOption"
       ],
-      "body": "fragment ProductAttributeDefinition on ProductAttributeDefinition {\n  id\n  name\n  slug\n  description\n  type\n  fillingMode\n  billingMode\n  taxClassId\n  scopeProductId\n  isRequired\n  isVisible\n  displayOrder\n  minValue\n  maxValue\n  options {\n    ...ProductAttributeOption\n  }\n}",
+      "body": "fragment ProductAttributeDefinition on ProductAttributeDefinition {\n  id\n  name\n  handle\n  description\n  type\n  fillingMode\n  billingMode\n  taxClassId\n  scopeProductId\n  isRequired\n  isVisible\n  displayOrder\n  minValue\n  maxValue\n  options {\n    ...ProductAttributeOption\n  }\n}",
       "onType": "ProductAttributeDefinition"
     }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-operations",
-  "version": "13.1.0",
+  "version": "14.0.0",
   "description": "GraphQL operations for DoSwiftly Storefront - SSOT from backend",
   "homepage": "https://doswiftly.pl",
   "publishConfig": {

package/queries.graphql

@@ -18,7 +18,7 @@ query Shop {
 # Products
 # ============================================
 
-# 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).
+# 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).
 query Product($id: ID, $handle: String) {
   product(id: $id, handle: $handle) {
     ...ProductFull
@@ -139,9 +139,9 @@ query Collections($first: Int = 20, $after: String, $query: String, $sortKey: Co
 # Categories
 # ============================================
 
-# 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.
-query Category($id: ID, $slug: String) {
-  category(id: $id, slug: $slug) {
+# 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.
+query Category($id: ID, $handle: String) {
+  category(id: $id, handle: $handle) {
     ...Category
     parent {
       ...Category
@@ -539,9 +539,9 @@ query WishlistById($id: ID!) {
 # Blog
 # ============================================
 
-# 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.
-query BlogPosts($first: Int = 20, $after: String, $categorySlug: String, $tagSlug: String, $featured: Boolean, $sortKey: BlogPostSortKey = PUBLISHED_AT, $reverse: Boolean = false) {
-  blogPosts(first: $first, after: $after, categorySlug: $categorySlug, tagSlug: $tagSlug, featured: $featured, sortKey: $sortKey, reverse: $reverse) {
+# 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.
+query BlogPosts($first: Int = 20, $after: String, $categoryHandle: String, $tagHandle: String, $featured: Boolean, $sortKey: BlogPostSortKey = PUBLISHED_AT, $reverse: Boolean = false) {
+  blogPosts(first: $first, after: $after, categoryHandle: $categoryHandle, tagHandle: $tagHandle, featured: $featured, sortKey: $sortKey, reverse: $reverse) {
     edges {
       node {
         ...BlogPost
@@ -555,9 +555,9 @@ query BlogPosts($first: Int = 20, $after: String, $categorySlug: String, $tagSlu
   }
 }
 
-# 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).
-query BlogPost($id: ID, $slug: String) {
-  blogPost(id: $id, slug: $slug) {
+# 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).
+query BlogPost($id: ID, $handle: String) {
+  blogPost(id: $id, handle: $handle) {
     ...BlogPost
   }
 }
@@ -618,7 +618,7 @@ query Pages($first: Int = 20, $after: String, $sortKey: PageSortKeys = TITLE, $r
 # Content: Navigation Menus
 # ============================================
 
-# 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.
+# 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.
 query Menu($handle: String!) {
   menu(handle: $handle) {
     ...Menu