@doswiftly/storefront-operations 6.1.0 → 7.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-operations",
-  "version": "6.1.0",
+  "version": "7.1.0",
   "description": "GraphQL operations for DoSwiftly Storefront - SSOT from backend",
   "homepage": "https://doswiftly.pl",
   "publishConfig": {
@@ -14,6 +14,9 @@
     "./fragments.graphql": "./fragments.graphql",
     "./*.graphql": "./*.graphql"
   },
+  "devDependencies": {
+    "graphql": "^16.13.2"
+  },
   "keywords": [
     "graphql",
     "operations",
@@ -28,11 +31,15 @@
     "queries.graphql",
     "mutations.graphql",
     "fragments.graphql",
+    "operations.json",
     "README.md",
+    "AGENTS.md",
+    "llms-full.txt",
     "CHANGELOG.md"
   ],
   "scripts": {
     "sync": "node scripts/sync-operations.js",
-    "build": "npm run sync"
+    "build": "npm run sync",
+    "test": "node --test scripts/__tests__/*.test.js"
   }
 }

package/queries.graphql

@@ -7,6 +7,7 @@
 # Shop
 # ============================================
 
+# Returns shop configuration: name, base + supported currencies, supported locales, branding (logo, colors, fonts, social links), contact info, active payment methods, brand metadata, money format template, and the list of countries the shop ships to. Public; no auth required. Call once per session and cache — almost everything else is contextualized by the shop returned here.
 query Shop {
   shop {
     ...Shop
@@ -17,16 +18,14 @@ 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).
 query Product($id: ID, $handle: String) {
   product(id: $id, handle: $handle) {
     ...ProductFull
   }
 }
 
-# Single-query configurator fetch (Faza 1 + Faza 1.5 — Decision D-A v3).
-# Returns product details + union of set/scoped AttributeDefinitions filtered by CUSTOMER fillingMode.
-# Showcase: hurtowniakopiarek.pl Konica Bizhub C258 — 4 customer text fields (from shared set)
-# + Finiszer/Podstawa/Podajnik ADF (per-product scoped z linkedVariantId).
+# 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.
 query ProductConfigurator($handle: String!, $fillingMode: String = "CUSTOMER") {
   product(handle: $handle) {
     ...ProductFull
@@ -36,6 +35,7 @@ query ProductConfigurator($handle: String!, $fillingMode: String = "CUSTOMER") {
   }
 }
 
+# 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).
 query Products(
   $first: Int = 20
   $after: String
@@ -61,6 +61,7 @@ query Products(
   }
 }
 
+# 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.
 query ProductSearch($query: String!, $first: Int = 20, $after: String, $filters: [ProductFilter!]) {
   products(query: $query, first: $first, after: $after, filters: $filters) {
     edges {
@@ -79,6 +80,7 @@ query ProductSearch($query: String!, $first: Int = 20, $after: String, $filters:
   }
 }
 
+# Type-ahead suggestions for the storefront search input. Returns up to `$limit` matching products (hard cap 50) plus up to 5 styled query suggestions with `<mark>` tags around matched spans. Polish-language aware (handles morphology in suggestions). Run on each keystroke (debounce 200-300ms). The `$query` is capped at 100 characters server-side.
 query PredictiveSearch($query: String!, $limit: Int = 10) {
   predictiveSearch(query: $query, limit: $limit) {
     products {
@@ -95,6 +97,7 @@ query PredictiveSearch($query: String!, $limit: Int = 10) {
 # Collections
 # ============================================
 
+# Fetches a single collection by `id` or `handle`, with paginated products. Collections come in two types: **MANUAL** (curated — products explicitly added by the merchant) and **AUTO** (rule-based — products matched dynamically). Both surfaces use the same field selection.
 query Collection($id: ID, $handle: String, $productsFirst: Int = 20, $productsAfter: String, $productsFilters: [ProductFilter!]) {
   collection(id: $id, handle: $handle) {
     ...Collection
@@ -116,6 +119,7 @@ query Collection($id: ID, $handle: String, $productsFirst: Int = 20, $productsAf
   }
 }
 
+# Paginated list of all active collections (default 20, max 100). Sort by `TITLE` or `UPDATED_AT` via `sortKey`. Note: the `query` argument is reserved for future text filtering — it is currently accepted but ignored.
 query Collections($first: Int = 20, $after: String, $query: String, $sortKey: CollectionSortKeys = TITLE, $reverse: Boolean = false) {
   collections(first: $first, after: $after, query: $query, sortKey: $sortKey, reverse: $reverse) {
     edges {
@@ -135,6 +139,7 @@ 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) {
     ...Category
@@ -147,6 +152,7 @@ query Category($id: ID, $slug: String) {
   }
 }
 
+# Returns active categories for the shop. Each category exposes its `parent` and `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.
 query Categories {
   categories {
     roots {
@@ -166,6 +172,7 @@ query Categories {
 # Cart
 # ============================================
 
+# Fetches a cart by `id` (the value persisted by the SDK in the `cart-id` cookie). The cart query is public — no auth needed to read it — but once a customer logs in and gets associated with the cart, mutations enforce ownership. Returns line items (paginated up to 100), totals, applied discount codes, gift cards, buyer identity, note, attributes, and warnings. Refetch after every cart mutation.
 query Cart($id: ID!) {
   cart(id: $id) {
     ...Cart
@@ -176,6 +183,7 @@ query Cart($id: ID!) {
 # Customer (requires auth)
 # ============================================
 
+# Full customer profile — basic info plus the first 10 addresses and first 10 orders. Heaviest customer query; for narrow use cases prefer `CustomerProfile` (no orders / addresses) or `CustomerOrder` (single order). Returns null if unauthenticated.
 query Customer {
   customer {
     ...Customer
@@ -209,15 +217,14 @@ query Customer {
   }
 }
 
-# Lightweight customer profile query (no orders, no addresses list)
-# Use for settings/profile pages that only need basic customer info.
+# Lightweight customer profile (no orders, no addresses list). Use for settings / profile pages that only need basic customer info — much cheaper than `Customer`. Returns null if unauthenticated.
 query CustomerProfile {
   customer {
     ...Customer
   }
 }
 
-# Single order query — more efficient than fetching all customer data
+# Single order by `orderId`. Returns only orders that belong to the authenticated customer (cross-customer access returns null, not an error). Much cheaper than fetching the full `Customer` payload to access one order. Use on the order detail page.
 query CustomerOrder($orderId: ID!) {
   customerOrder(orderId: $orderId) {
     ...Order
@@ -228,6 +235,7 @@ query CustomerOrder($orderId: ID!) {
 # Checkout
 # ============================================
 
+# Fetches a checkout session by `id`. **Important**: `checkoutId` and `cartId` are 1:1 — there is no separate "checkout" record, the response is built dynamically from the cart. Returns line items, addresses, selected shipping rate, available shipping rates + payment methods, applied discount/gift cards (gift card codes are masked for security), and totals (`cost`, `tax`, `paymentDue`). Public read; ownership enforced on mutations. Refetch after every checkout mutation.
 query Checkout($id: ID!) {
   checkout(id: $id) {
     ...Checkout
@@ -235,9 +243,10 @@ query Checkout($id: ID!) {
 }
 
 # ============================================
-# Payment Methods (R23 - Payment Methods)
+# Payment Methods
 # ============================================
 
+# Returns the active payment methods for the shop, sorted by the merchant-configured display position. Shop-level — does NOT vary by cart amount or currency. Each method exposes `type` (`CARD`, `BANK_TRANSFER`, `BLIK`, `PAYPAL`, `APPLE_PAY`, `GOOGLE_PAY`, `CASH_ON_DELIVERY`, `OTHER`), provider, icon, description, and supported currencies. Use to render the payment step of checkout.
 query AvailablePaymentMethods {
   availablePaymentMethods {
     ...AvailablePaymentMethods
@@ -245,9 +254,10 @@ query AvailablePaymentMethods {
 }
 
 # ============================================
-# Shipments (R29 - Shipment Tracking)
+# Shipments / Tracking
 # ============================================
 
+# Fetches a shipment by `id` with status, tracking events, recipient address, and shipped/delivered timestamps. **Auth required** — customer access token plus ownership of the parent order. Wrapped response: `{ shipment, userErrors[] }`. Error codes: `INVALID_TOKEN`, `NOT_FOUND` (also returned on ownership mismatch to prevent enumeration), `FETCH_FAILED`.
 query Shipment($id: ID!) {
   shipment(id: $id) {
     shipment {
@@ -259,6 +269,7 @@ query Shipment($id: ID!) {
   }
 }
 
+# **Public** shipment lookup by carrier tracking number — no auth required. Designed for "Track my order" landing pages reachable without login. Returns the basic shipment fragment including recipient address. Wrapped response: `{ shipment, userErrors[] }`. Error codes: `INVALID_INPUT`, `NOT_FOUND`, `FETCH_FAILED`.
 query ShipmentByTrackingNumber($trackingNumber: String!) {
   shipmentByTrackingNumber(trackingNumber: $trackingNumber) {
     shipment {
@@ -271,9 +282,10 @@ query ShipmentByTrackingNumber($trackingNumber: String!) {
 }
 
 # ============================================
-# Returns (R30 - Returns/RMA)
+# Returns / RMA
 # ============================================
 
+# Fetches a single return (RMA) by `id` with line items, refund/compensation info, and history. **Auth required** — customer access token plus ownership of the return. Wrapped response: `{ return, userErrors[] }`. Error codes: `INVALID_TOKEN`, `NOT_FOUND` (also returned on ownership mismatch), `FETCH_FAILED`.
 query Return($id: ID!) {
   return(id: $id) {
     return {
@@ -285,6 +297,7 @@ query Return($id: ID!) {
   }
 }
 
+# Lists returns for a given order (paginated, default page size 20, cursor-based). **Auth required** — customer access token plus ownership of the order; the connection is empty (no explicit error) on auth failure. Use on the order detail page to show return history.
 query ReturnsByOrder($orderId: ID!) {
   returnsByOrder(orderId: $orderId) {
     edges {
@@ -300,6 +313,7 @@ query ReturnsByOrder($orderId: ID!) {
   }
 }
 
+# Returns the standard list of return reasons used by the RMA flow: `DEFECTIVE`, `NOT_AS_DESCRIBED`, `WRONG_ITEM`, `CHANGED_MIND`, `BETTER_PRICE`, `DAMAGED_SHIPPING`, `OTHER`. The list is fixed across all shops — not per-shop configurable. Public; no auth required.
 query ReturnReasons {
   returnReasons {
     ...ReturnReasonOption
@@ -307,15 +321,17 @@ query ReturnReasons {
 }
 
 # ============================================
-# Gift Cards (R32 - Gift Cards)
+# Gift Cards
 # ============================================
 
+# Public gift-card lookup by `code`. Returns balance, currency, expiry, and `maskedCode` (first 4 + last 4 chars only — the full code never leaks back). Returns null if the code is unknown (rather than an explicit error, to limit enumeration). **Rate-limited**: 10 requests per 60 seconds per IP.
 query GiftCard($code: String!) {
   giftCard(code: $code) {
     ...GiftCard
   }
 }
 
+# Validates whether a gift card is usable (and optionally for a given `$amount`). Checks status (`DISABLED`, `USED`, `EXPIRED`), expiry date, and — when `$amount` is provided — sufficient balance. Returns `{ validation: { isValid, availableBalance, error: { code, message } }, userErrors[] }`. Validation error codes: `NOT_FOUND`, `DISABLED`, `ALREADY_USED`, `EXPIRED`, `INSUFFICIENT_BALANCE`. **Rate-limited**: 10 / 60s.
 query GiftCardValidate($code: String!, $amount: Float) {
   giftCardValidate(code: $code, amount: $amount) {
     validation {
@@ -328,9 +344,10 @@ query GiftCardValidate($code: String!, $amount: Float) {
 }
 
 # ============================================
-# Shipping Methods (R33 - Shipping Methods)
+# Shipping Methods
 # ============================================
 
+# 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.
 query AvailableShippingMethods($address: ShippingAddressInput!, $cart: CartShippingInput) {
   availableShippingMethods(address: $address, cart: $cart) {
     methods {
@@ -346,9 +363,10 @@ query AvailableShippingMethods($address: ShippingAddressInput!, $cart: CartShipp
 }
 
 # ============================================
-# Attribute Filters (R35 - Dynamic Attributes)
+# Attribute Filters
 # ============================================
 
+# Returns the dynamic facet filters available for a listing context — pass `collectionId`, `categoryId`, or `searchQuery`. For each visible & filterable attribute, returns either discrete value counts (for `SELECT` / `CHECKBOX` types) or numeric range bounds (for `SLIDER` types). Plus `priceRange`, per-category counts, `activeCount` (length of `currentFilters` input), and `matchCount` (total products in the context). Use to render filter sidebars on listing/search pages.
 query AvailableFilters($input: AvailableFiltersInput) {
   availableFilters(input: $input) {
     ...AvailableFilters
@@ -356,27 +374,31 @@ query AvailableFilters($input: AvailableFiltersInput) {
 }
 
 # ============================================
-# Loyalty Program (R7, R8, R10.4)
+# Loyalty Program
 # ============================================
 
+# Returns the logged-in customer's loyalty membership: points (current, pending, redeemed, expired, expiring), current tier, tier progress, annual spend, last activity. Returns null if the customer is not enrolled — there is **no auto-enrollment** here (enrollment happens via signup or a first qualifying order). Auth required.
 query LoyaltyMember {
   loyaltyMember {
     ...LoyaltyMember
   }
 }
 
+# Lists the loyalty tiers configured for the shop (`BRONZE`, `SILVER`, `GOLD`, `PLATINUM`, `DIAMOND` etc.) with their `minPoints`, `minAnnualSpend`, `pointsMultiplier`, and custom benefits. Sorted by `minPoints` ASC. Public; no auth required.
 query LoyaltyTiers {
   loyaltyTiers {
     ...LoyaltyTier
   }
 }
 
+# Lists rewards customers can redeem (free shipping, percent off, free product, gift card). Filtered to **active** rewards only (`is_active = true` AND inside their `starts_at`/`ends_at` window). Public; no auth required.
 query LoyaltyRewards {
   loyaltyRewards {
     ...LoyaltyReward
   }
 }
 
+# Paginated history of loyalty point transactions for the logged-in customer (default 20). Transaction `type` enum: `EARN_PURCHASE`, `EARN_SIGNUP`, `EARN_REFERRAL`, `EARN_REVIEW`, `EARN_BIRTHDAY`, `EARN_BONUS`, `REDEEM`, `EXPIRE`, `ADJUST`, `REFUND_REVERSAL`. Auth required — empty connection if unauthenticated.
 query LoyaltyTransactions($first: Int = 20, $after: String) {
   loyaltyTransactions(first: $first, after: $after) {
     edges {
@@ -392,18 +414,21 @@ query LoyaltyTransactions($first: Int = 20, $after: String) {
   }
 }
 
+# Returns the loyalty program configuration: `isEnabled`, `pointsName` (e.g. "stars"), `pointsPerCurrency`, `pointsExpiryMonths`, available earn actions, referral settings. Use this at app boot to decide whether to render any loyalty UI at all. Public; no auth required.
 query LoyaltySettings {
   loyaltySettings {
     ...LoyaltySettings
   }
 }
 
+# Estimates how many loyalty points the customer would earn for an order of `$orderTotal` (in major currency units). When the customer is authenticated, the result accounts for their current tier's points multiplier. Use on cart/checkout to show "Earn X points with this order".
 query EstimatePoints($orderTotal: Float!) {
   estimatePoints(orderTotal: $orderTotal) {
     ...PointsEstimate
   }
 }
 
+# Returns the customer's referral statistics: `referralCode`, `shareUrl`, `totalReferred`, `completedReferrals`, `pendingReferrals`, `totalPointsEarned`. Auth required. Returns null if unauthenticated or if the referral program is disabled for the shop.
 query ReferralStats {
   referralStats {
     ...ReferralStats
@@ -414,6 +439,7 @@ query ReferralStats {
 # Reviews
 # ============================================
 
+# Paginated list of customer reviews for a product, **filtered to APPROVED reviews only** (PENDING / REJECTED reviews are not exposed to the storefront). Sort by `CREATED_AT` (default), helpfulness, or rating. Public; no auth required.
 query ProductReviews($productId: ID!, $first: Int = 10, $after: String, $sortKey: ReviewSortKey = CREATED_AT, $reverse: Boolean = true) {
   productReviews(productId: $productId, first: $first, after: $after, sortKey: $sortKey, reverse: $reverse) {
     edges {
@@ -429,6 +455,7 @@ query ProductReviews($productId: ID!, $first: Int = 10, $after: String, $sortKey
   }
 }
 
+# Aggregate review statistics for a product: average rating, total count, distribution per star (1-5). Computed from APPROVED reviews only. Use for product card review summaries. Public; no auth required.
 query ReviewStats($productId: ID!) {
   reviewStats(productId: $productId) {
     ...ReviewStats
@@ -439,6 +466,7 @@ query ReviewStats($productId: ID!) {
 # Wishlists
 # ============================================
 
+# Paginated list of the logged-in customer's wishlists (default 20). Auth required — empty connection if unauthenticated. Customers typically have a small set (<10).
 query Wishlists($first: Int = 20, $after: String) {
   wishlists(first: $first, after: $after) {
     edges {
@@ -460,6 +488,7 @@ query Wishlists($first: Int = 20, $after: String) {
   }
 }
 
+# Fetches a single wishlist by `id`. Private wishlists are visible only to the owner; public wishlists are visible to anyone. Note: this query supports lookup by `id` only — there is currently no way to fetch a wishlist by its share token.
 query WishlistById($id: ID!) {
   wishlist(id: $id) {
     ...Wishlist
@@ -470,6 +499,7 @@ 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) {
     edges {
@@ -485,18 +515,21 @@ 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) {
     ...BlogPost
   }
 }
 
+# Lists all blog categories with per-category `postCount` and SEO metadata. Use to render category navigation on blog pages. Public; no auth required.
 query BlogCategories {
   blogCategories {
     ...BlogCategory
   }
 }
 
+# Lists blog tags with usage counts (`postCount` per tag). Use to render a tag cloud. Public; no auth required.
 query BlogTags {
   blogTags {
     ...BlogTag
@@ -507,6 +540,7 @@ query BlogTags {
 # Recommendations
 # ============================================
 
+# Returns up to `$limit` recommended products related to `$productId`. Default `$intent: SIMILAR` — products sharing categories or tags. Use on PDP "You may also like" sections. Public; no auth required.
 query ProductRecommendations($productId: ID!, $limit: Int = 8, $intent: RecommendationIntent = SIMILAR) {
   productRecommendations(productId: $productId, limit: $limit, intent: $intent) {
     ...ProductCard
@@ -517,12 +551,14 @@ query ProductRecommendations($productId: ID!, $limit: Int = 8, $intent: Recommen
 # Content: Pages
 # ============================================
 
+# Fetches a single CMS page (About, Privacy, Returns Policy, Terms, etc.) by `handle` or `id`. Visibility-gated: returns null if the page is hidden or if its publish date is in the future. Public; no auth required.
 query Page($handle: String, $id: ID) {
   page(handle: $handle, id: $id) {
     ...ShopPage
   }
 }
 
+# Paginated list of visible, already-published CMS pages. Use for sitemap, footer link list, or page directory. The `query` argument supports text search over the page title/handle. Public; no auth required.
 query Pages($first: Int = 20, $after: String, $sortKey: PageSortKeys = TITLE, $reverse: Boolean = false, $query: String) {
   pages(first: $first, after: $after, sortKey: $sortKey, reverse: $reverse, query: $query) {
     edges {
@@ -542,6 +578,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.
 query Menu($handle: String!) {
   menu(handle: $handle) {
     ...Menu
@@ -552,6 +589,7 @@ query Menu($handle: String!) {
 # Content: URL Redirects
 # ============================================
 
+# Returns the shop's URL redirects (legacy `path` → new `target` mappings). Use server-side at the edge or in SSR to issue 301 redirects for migrated routes (preserves SEO equity). Default page size 250 — most shops fit in a single page.
 query UrlRedirects($first: Int = 250, $after: String) {
   urlRedirects(first: $first, after: $after) {
     nodes {
@@ -566,9 +604,8 @@ query UrlRedirects($first: Int = 250, $after: String) {
 # ============================================
 # Store Availability: per-location stock (BOPIS / multi-location)
 # ============================================
-# Field returns null for single-location shops (storefront can skip the store picker).
-# `near`, `locationType`, and `@inContext(preferredLocationId)` shape the ordering.
 
+# Fetches a product (by `handle` or `id`) along with per-variant availability across the merchant's physical locations — for the BOPIS / multi-location flow. The `storeAvailability` connection lives on each `ProductVariant`; its arguments (`first`, `after`, `near`, `locationType`) are set inside the `VariantStoreAvailability` fragment. The connection returns null for single-location shops (in which case the storefront can skip the store picker entirely). `availableStock` is null for anonymous users and an integer for authenticated customers. Apply `@inContext(preferredLocationId: ...)` on the operation to pin the customer's preferred location to the top of the result.
 query ProductStoreAvailability($handle: String, $id: ID) {
   product(handle: $handle, id: $id) {
     id
@@ -584,6 +621,7 @@ query ProductStoreAvailability($handle: String, $id: ID) {
 # Locations (store picker UI)
 # ============================================
 
+# Paginated list of active store locations (default 20, max 100). Filters: `near` (`{ latitude, longitude }`) for proximity search — sorts ascending by distance; `hasPickupEnabled` for pickup-only filtering; `locationType` (`RETAIL`, `WAREHOUSE`, `PICKUP_POINT`). When `near` is omitted, results are sorted by the merchant's `priority`, then name. Use for the BOPIS store picker UI. Public; no auth required.
 query Locations(
   $first: Int = 20
   $after: String
@@ -611,6 +649,7 @@ query Locations(
   }
 }
 
+# Fetches a single store location by `id` — full address, coordinates, business hours, pickup config (lead time, hours, timezone), and services. Returns null if the location is not found, not active, or owned by another shop. Use on the location detail page. Public; no auth required.
 query Location($id: ID!) {
   location(id: $id) {
     ...Location