@doswiftly/storefront-operations 13.1.0 → 15.1.0

package/llms-full.txt

@@ -1,7 +1,7 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **13.1.0**
-> 50 queries · 40 mutations · 100 fragments
+> Schema version: **15.1.0**
+> 51 queries · 40 mutations · 101 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
@@ -410,6 +410,33 @@ query CustomerProfile {
 }
 ```
 
+### Query: `CustomerAddresses`
+
+**Section**: Customer (requires auth)
+
+**Description**: Authenticated customer's saved address book — used on checkout to let the buyer pick a previously-used shipping / billing address instead of typing it. Each entry carries B2B invoicing fields (`taxId`, `vatNumber`) and the `isDefault` flag so the same list serves both as the shipping picker and as the billing/invoice picker. Returns up to 50 addresses (Relay Connection — buyers rarely keep more); for the unauthenticated case the connection is empty (no error). The default address is also surfaced as `Customer.defaultAddress`.
+
+**Variables**: none
+
+**Fragments used**: `MailingAddress`, `PageInfo`
+
+**GraphQL**:
+```graphql
+query CustomerAddresses {
+  customer {
+    addresses(first: 50) {
+      nodes {
+        ...MailingAddress
+      }
+      pageInfo {
+        ...PageInfo
+      }
+      totalCount
+    }
+  }
+}
+```
+
 ### Query: `CustomerOrder`
 
 **Section**: Customer (requires auth)
@@ -1018,13 +1045,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 +1060,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 +1088,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 +1229,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 +2617,7 @@ fragment ProductCard on Product {
   vendor
   categories {
     id
-    slug
+    handle
     name
   }
   isAvailable
@@ -2723,7 +2750,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 +2759,7 @@ fragment Collection on Collection {
 fragment Category on Category {
   id
   name
-  slug
+  handle
   description
   image {
     ...ImageCard
@@ -2744,11 +2771,29 @@ fragment Category on Category {
 }
 ```
 
+### Fragment: `PickupPoint` on `PickupPoint`
+
+**Section**: Customer
+
+**Description**: Selected pickup point (parcel locker or collection point) attached to a delivery address. Returned on `MailingAddress.pickupPoint` when the buyer chose a non-home delivery method (`deliveryType` other than `HOME`). Null for home delivery.
+
+**GraphQL**:
+```graphql
+fragment PickupPoint on PickupPoint {
+  provider
+  pointId
+  name
+  address
+}
+```
+
 ### Fragment: `MailingAddress` on `MailingAddress`
 
 **Section**: Customer
 
-**Description**: Customer mailing address — full street/city/state/country/postal code with names and phone. `isDefault` flips when this address is the default for shipping. Spread on the address book UI and order summaries.
+**Description**: Customer mailing address — full street/city/state/country/postal code with names and phone. `isDefault` flips when this address is the default for shipping. Carries B2B invoicing fields (`taxId`, `vatNumber`) and the selected `pickupPoint` for parcel locker / collection point deliveries. Spread on the address book UI, checkout shipping/billing forms, and order summaries.
+
+**Uses fragments**: `PickupPoint`
 
 **GraphQL**:
 ```graphql
@@ -2768,6 +2813,11 @@ fragment MailingAddress on MailingAddress {
   stateCode
   postalCode
   isDefault
+  taxId
+  vatNumber
+  pickupPoint {
+    ...PickupPoint
+  }
 }
 ```
 
@@ -3123,13 +3173,14 @@ fragment CartShippingMethod on CartShippingMethod {
 
 **Section**: Cart
 
-**Description**: Gift card applied to a cart — masked code for display, last 4 chars for matching, applied amount + remaining balance. Balance NIE debited yet — actual deduction atomically at `cartComplete`.
+**Description**: Gift card applied to a cart — `id` is the stable handle the storefront passes to `cartRemoveGiftCard` (no need to keep the raw code around). Plus masked code for display, last 4 chars for matching, applied amount + remaining balance. Balance NIE debited yet — actual deduction atomically at `cartComplete`.
 
 **Uses fragments**: `Money`
 
 **GraphQL**:
 ```graphql
 fragment CartAppliedGiftCard on CartAppliedGiftCard {
+  id
   maskedCode
   lastCharacters
   appliedAmount {
@@ -3772,7 +3823,7 @@ fragment FreeShippingProgress on FreeShippingProgress {
 
 **Section**: Shipping Methods
 
-**Description**: One shipping method offered for the destination + cart — id, name, carrier, price, free-shipping progress, estimated delivery, sort order. Spread on the checkout shipping step.
+**Description**: One shipping method offered for the destination + cart — id, name, carrier, price, free-shipping progress, estimated delivery, sort order. `deliveryType` signals whether to render a pickup-point / locker picker (`HOME` vs `PICKUP_POINT` / `LOCKER`) so the storefront does not have to infer it from the method name. Spread on the checkout shipping step.
 
 **Uses fragments**: `DeliveryEstimate`, `FreeShippingProgress`, `Money`, `ShippingCarrier`
 
@@ -3782,6 +3833,7 @@ fragment AvailableShippingMethod on AvailableShippingMethod {
   id
   name
   description
+  deliveryType
   carrier {
     ...ShippingCarrier
   }
@@ -3904,14 +3956,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 +4146,7 @@ fragment LoyaltyTransaction on LoyaltyTransaction {
 fragment LoyaltyReward on LoyaltyReward {
   id
   name
-  slug
+  handle
   type
   pointsCost
   discountPercent
@@ -4327,14 +4379,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 +4396,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 +4412,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 +4421,7 @@ fragment BlogTag on BlogTag {
 fragment BlogPost on BlogPost {
   id
   title
-  slug
+  handle
   excerpt
   content
   contentFormat
@@ -4575,7 +4627,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 +4651,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 +4663,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 +4701,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 +4862,7 @@ fragment ProductAttributeOption on ProductAttributeOption {
 fragment ProductAttributeDefinition on ProductAttributeDefinition {
   id
   name
-  slug
+  handle
   description
   type
   fillingMode