@doswiftly/storefront-operations 13.0.0 → 14.0.0

package/llms-full.txt

@@ -1,7 +1,7 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **13.0.0**
-> 49 queries · 40 mutations · 100 fragments
+> 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
 regenerated on every release to match the published schema.
@@ -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
@@ -676,7 +676,7 @@ query GiftCardValidate($code: String!, $amount: Float) {
 
 **Section**: Shipping Methods
 
-**Description**: 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.
+**Description**: 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.
 
 **Variables**:
 - `$address`: `ShippingAddressInput!`
@@ -701,6 +701,39 @@ query AvailableShippingMethods($address: ShippingAddressInput!, $cart: CartShipp
 }
 ```
 
+### Query: `CartAvailableShippingMethods`
+
+**Section**: Shipping Methods
+
+**Description**: 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.
+
+**Variables**:
+- `$cartId`: `ID!`
+- `$address`: `ShippingAddressInput!`
+
+**Fragments used**: `AvailableShippingMethod`, `FreeShippingProgress`, `UserError`
+
+**GraphQL**:
+```graphql
+query CartAvailableShippingMethods($cartId: ID!, $address: ShippingAddressInput!) {
+  cart(id: $cartId) {
+    id
+    requiresShipping
+    availableShippingMethods(address: $address) {
+      methods {
+        ...AvailableShippingMethod
+      }
+      freeShippingProgress {
+        ...FreeShippingProgress
+      }
+      userErrors {
+        ...UserError
+      }
+    }
+  }
+}
+```
+
 ### Query: `ProductFilters`
 
 **Section**: Attribute Filters
@@ -985,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`)*
@@ -1000,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
@@ -1028,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
   }
 }
@@ -1169,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!`
@@ -2557,7 +2590,7 @@ fragment ProductCard on Product {
   vendor
   categories {
     id
-    slug
+    handle
     name
   }
   isAvailable
@@ -2690,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`
 
@@ -2699,7 +2732,7 @@ fragment Collection on Collection {
 fragment Category on Category {
   id
   name
-  slug
+  handle
   description
   image {
     ...ImageCard
@@ -2943,6 +2976,7 @@ fragment CartLine on CartLine {
   productTitle
   productHandle
   productType
+  requiresShipping
 }
 ```
 
@@ -3060,6 +3094,7 @@ fragment Cart on Cart {
   appliedGiftCards {
     ...CartAppliedGiftCard
   }
+  requiresShipping
   createdAt
   updatedAt
 }
@@ -3869,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
@@ -4059,7 +4094,7 @@ fragment LoyaltyTransaction on LoyaltyTransaction {
 fragment LoyaltyReward on LoyaltyReward {
   id
   name
-  slug
+  handle
   type
   pointsCost
   discountPercent
@@ -4292,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
 }
@@ -4309,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
 }
 ```
@@ -4325,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`
 
@@ -4334,7 +4369,7 @@ fragment BlogTag on BlogTag {
 fragment BlogPost on BlogPost {
   id
   title
-  slug
+  handle
   excerpt
   content
   contentFormat
@@ -4540,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
@@ -4564,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`
 
@@ -4576,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
   }
@@ -4585,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
+        }
+      }
     }
   }
 }
@@ -4688,7 +4810,7 @@ fragment ProductAttributeOption on ProductAttributeOption {
 fragment ProductAttributeDefinition on ProductAttributeDefinition {
   id
   name
-  slug
+  handle
   description
   type
   fillingMode