@doswiftly/storefront-operations 4.4.0 → 5.4.1

package/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+## 5.4.1
+
+### Patch Changes
+
+- 7846bdb: Fix `doswiftly dev` port pre-flight on Windows (and any host where another
+  process binds the port on IPv6 `::` only): the probe now checks IPv4 and
+  IPv6 in parallel and requires BOTH free before marking a port as available.
+  Previously an IPv6-only conflict (common on Windows, where Next.js binds
+  `::` by default) slipped past the IPv4-only probe — the banner advertised
+  `http://localhost:3000` and the framework immediately crashed with
+  `EADDRINUSE :::3000`. With this fix `doswiftly dev` falls back to the next
+  free port (3001, 3002, …) as documented.
+
+  Also ship `CHANGELOG.md` inside the npm tarball. Previous releases packed
+  only `dist`/`bin`/`templates` (and `schema.graphql`/operations for
+  `storefront-operations`, `dist` for `storefront-sdk`), so consumers who
+  `npm install @doswiftly/cli` got a version number with no user-visible
+  release notes.
+
+## 5.4.0
+
+### Minor Changes
+
+- 770fcd3: Added `Product.purchasable: Boolean!` to the storefront schema. The field mirrors `visibility === 'PUBLIC'` server-side and lets templates hide the "Add to cart" / "Buy now" path for component products that are only reachable through a parent product's configurator.
+
+  Templates can render a non-purchasable banner on the PDP instead of exposing a purchase action that the server will reject. Requesting the field is additive — operations that omit it keep working.
+
+All notable changes to @doswiftly/storefront-operations will be documented in this file.
+
+## [5.0.0] - 2026-04-12
+
+### Breaking
+
+- Removed `type InventoryLevel`, `fragment InventoryLevel`, `fragment VariantInventoryLevels`, and `query ProductInventory`.
+- Removed `ProductVariant.inventoryLevels(locationType)` field — replaced by `ProductVariant.storeAvailability`.
+
+### Added
+
+- Shopify-parity `StoreAvailability` surface on `ProductVariant`:
+  - `type StoreAvailability { available, quantityAvailable (token-gated), pickUpTime, location }`
+  - `type Location`, `LocationAddress`, `BusinessHours`, `BusinessHoursWindow` — full pickup-aware payload.
+  - `type StoreAvailabilityConnection` + `StoreAvailabilityEdge` — cursor-paginated, supports `near`, `locationType`, `@inContext(preferredLocationId)`.
+- Root-level queries: `locations(first, after, near, hasPickupEnabled, locationType)` and `location(id)`.
+- `directive @inContext(preferredLocationId: ID) on QUERY | MUTATION | SUBSCRIPTION` — Shopify operation directive for contextual hints (country / language / buyer to follow).
+- Fragments: `StoreAvailability`, `StoreAvailabilityConnection`, `Location`, `LocationAddress`, `BusinessHours`, `BusinessHoursWindow`, `VariantStoreAvailability`.
+- Queries: `ProductStoreAvailability`, `Locations`, `Location`.
+
+### Migration
+
+Replace:
+
+```graphql
+query ProductInventory($handle: String) {
+  product(handle: $handle) {
+    variants {
+      ...VariantInventoryLevels
+    }
+  }
+}
+```
+
+with:
+
+```graphql
+query ProductStoreAvailability($handle: String) {
+  product(handle: $handle) {
+    variants {
+      ...VariantStoreAvailability
+    }
+  }
+}
+```
+
+`quantityAvailable` is now token-gated (null for anonymous, Int when `x-customer-access-token` is sent) — matches Shopify Storefront API.
+
+## [1.0.0] - 2025-12-09
+
+### Added
+
+- Initial release of @doswiftly/storefront-operations package
+- GraphQL operations synced from backend SSOT
+- Queries: Shop, Product, Products, ProductSearch, Collection, Collections, Category, Categories, Cart, Customer
+- Mutations: Cart operations, Customer auth, Profile management, Address management, Password recovery
+- Fragments: All reusable fragments for products, collections, cart, customer, etc.
+- Sync script to copy operations from backend
+- Package exports for .graphql files
+- README with usage instructions
+
+### Purpose
+
+Enable direct GraphQL codegen approach for Next.js storefronts while maintaining Single Source of Truth from backend.

package/fragments.graphql

@@ -20,6 +20,7 @@ fragment UserError on UserError {
   field
 }
 
+# Base Image — no transform (for logos, favicons, branding assets that are already small)
 fragment Image on Image {
   id
   url
@@ -28,6 +29,37 @@ fragment Image on Image {
   height
 }
 
+# Thumbnail — cart items, variant swatches, author avatars (rendered at ~96px, 300px covers 3x DPI)
+# No preferredContentType — imgproxy auto-negotiates AVIF/WEBP from Accept header
+fragment ImageThumbnail on Image {
+  id
+  url(transform: { maxWidth: 300 })
+  altText
+  width
+  height
+  thumbhash
+}
+
+# Card — product cards, collection/category cards, blog posts (rendered at ~400px, 800px covers 2x DPI)
+fragment ImageCard on Image {
+  id
+  url(transform: { maxWidth: 800 })
+  altText
+  width
+  height
+  thumbhash
+}
+
+# Full — product detail gallery, hero images (rendered at ~800px, 1600px covers 2x DPI)
+fragment ImageFull on Image {
+  id
+  url(transform: { maxWidth: 1600 })
+  altText
+  width
+  height
+  thumbhash
+}
+
 # Simple money (for originalPrice fields and non-converted prices)
 fragment Money on Money {
   amount
@@ -79,7 +111,7 @@ fragment ProductVariant on ProductVariant {
   available
   quantityAvailable
   image {
-    ...Image
+    ...ImageThumbnail
   }
   selectedOptions {
     ...SelectedOption
@@ -102,7 +134,7 @@ fragment ProductCard on Product {
   reviewCount
   tags
   featuredImage {
-    ...Image
+    ...ImageCard
   }
   priceRange {
     minVariantPrice {
@@ -146,6 +178,9 @@ fragment ProductBase on Product {
   totalInventory
   type
   collectRecipientInfo
+  # Faza 1.5 (Decision D-A v3 + D-B)
+  visibility
+  attributeSetId
   createdAt
   updatedAt
 }
@@ -153,7 +188,7 @@ fragment ProductBase on Product {
 fragment ProductFull on Product {
   ...ProductBase
   images(first: 20) {
-    ...Image
+    ...ImageFull
   }
   variants(first: 100) {
     ...ProductVariant
@@ -175,7 +210,7 @@ fragment Collection on Collection {
   description
   descriptionHtml
   image {
-    ...Image
+    ...ImageCard
   }
   seo {
     title
@@ -195,7 +230,7 @@ fragment Category on Category {
   slug
   description
   image {
-    ...Image
+    ...ImageCard
   }
   level
   path
@@ -311,6 +346,24 @@ fragment CartLineCost on CartLineCost {
   }
 }
 
+# Typed customer-filled attribute snapshot (Faza 1 R5 + Decision D-A v3 + D-I).
+# Distinct from CartLine.attributes (Shopify raw KV line item properties).
+fragment AttributeSelection on AttributeSelection {
+  attributeDefinitionId
+  attributeName
+  type
+  fillingMode
+  billingMode
+  optionId
+  optionLabel
+  optionIds
+  textValue
+  surchargeAmount
+  surchargeType
+  taxClassId
+  linkedVariantId
+}
+
 fragment CartLine on CartLine {
   id
   quantity
@@ -324,6 +377,9 @@ fragment CartLine on CartLine {
     key
     value
   }
+  attributeSelections {
+    ...AttributeSelection
+  }
   productId
   productTitle
   productHandle
@@ -587,7 +643,7 @@ fragment CheckoutLineItem on CheckoutLineItem {
   productId
   sku
   image {
-    ...Image
+    ...ImageThumbnail
   }
 }
 
@@ -1092,7 +1148,7 @@ fragment LoyaltyReward on LoyaltyReward {
   }
   description
   image {
-    ...Image
+    ...ImageCard
   }
   available
   tierRequired {
@@ -1242,14 +1298,14 @@ fragment BlogPost on BlogPost {
   content
   contentType
   featuredImage {
-    ...Image
+    ...ImageCard
   }
   author {
     id
     name
     bio
     avatar {
-      ...Image
+      ...ImageThumbnail
     }
   }
   category {
@@ -1306,24 +1362,210 @@ fragment CartRecommendation on CartRecommendations {
 }
 
 # ============================================
-# Inventory Level Fragments (Multi-Warehouse)
+# Store Availability Fragments (Shopify parity — BOPIS / multi-location)
 # ============================================
+# Field access:
+# - `available: Boolean!` — always public.
+# - `pickUpTime: String` — public, localized merchant-configured string.
+# - `quantityAvailable: Int` — TOKEN-GATED (null for anonymous, Int for authenticated).
+# - `location: Location!` — public, includes coords + businessHours when configured.
+
+fragment LocationAddress on LocationAddress {
+  address1
+  address2
+  city
+  country
+  countryCode
+  province
+  provinceCode
+  zip
+  phone
+  latitude
+  longitude
+  formatted
+}
+
+fragment BusinessHoursWindow on BusinessHoursWindow {
+  openHour
+  closeHour
+}
+
+fragment BusinessHours on BusinessHours {
+  monday { ...BusinessHoursWindow }
+  tuesday { ...BusinessHoursWindow }
+  wednesday { ...BusinessHoursWindow }
+  thursday { ...BusinessHoursWindow }
+  friday { ...BusinessHoursWindow }
+  saturday { ...BusinessHoursWindow }
+  sunday { ...BusinessHoursWindow }
+}
+
+fragment Location on Location {
+  id
+  name
+  type
+  pickupEnabled
+  timezone
+  pickupInstructions
+  address {
+    ...LocationAddress
+  }
+  businessHours {
+    ...BusinessHours
+  }
+}
 
-fragment InventoryLevel on InventoryLevel {
-  locationId
-  locationName
-  locationType
+fragment StoreAvailability on StoreAvailability {
   available
-  onHand
+  quantityAvailable
+  pickUpTime
+  location {
+    ...Location
+  }
 }
 
-fragment VariantInventoryLevels on ProductVariant {
+fragment StoreAvailabilityConnection on StoreAvailabilityConnection {
+  totalCount
+  pageInfo {
+    ...PageInfo
+  }
+  edges {
+    cursor
+    node {
+      ...StoreAvailability
+    }
+  }
+}
+
+fragment VariantStoreAvailability on ProductVariant {
   id
   title
   sku
   available
   quantityAvailable
-  inventoryLevels {
-    ...InventoryLevel
+  storeAvailability(first: 10) {
+    ...StoreAvailabilityConnection
+  }
+}
+
+# ============================================
+# Content: Pages
+# ============================================
+
+fragment ShopPage on ShopPage {
+  id
+  handle
+  title
+  body
+  bodySummary
+  seo {
+    title
+    description
+  }
+  publishedAt
+  createdAt
+  updatedAt
+}
+
+# ============================================
+# Content: Navigation Menus
+# ============================================
+
+fragment MenuItem on MenuItem {
+  id
+  title
+  url
+  type
+  resourceId
+  image {
+    ...Image
+  }
+  items {
+    id
+    title
+    url
+    type
+    resourceId
+    items {
+      id
+      title
+      url
+      type
+      resourceId
+    }
+  }
+}
+
+fragment Menu on Menu {
+  id
+  handle
+  title
+  itemsCount
+  items {
+    ...MenuItem
+  }
+}
+
+# ============================================
+# Content: URL Redirects
+# ============================================
+
+fragment UrlRedirect on UrlRedirect {
+  path
+  target
+}
+
+# ============================================
+# Unified Product Configurator (Faza 1 + Faza 1.5 — Decision D-A v3 + D-I)
+# ============================================
+# Hybrid Magento binding:
+#   - Product.attributes returns UNION of set definitions (via Product.attributeSetId)
+#     and per-product scoped definitions (AttributeDefinition.scopeProductId = product.id)
+#   - CUSTOMER fillingMode → rendered in storefront configurator UX
+#   - MERCHANT fillingMode → product metadata (filtering, display)
+#   - BOTH fillingMode → admin default + customer override in cart
+
+fragment LinkedVariantSummary on LinkedVariantSummary {
+  id
+  productId
+  title
+  sku
+  quantityAvailable
+  isAvailable
+  trackQuantity
+}
+
+fragment ProductAttributeOption on ProductAttributeOption {
+  id
+  value
+  label
+  sortOrder
+  colorHex
+  surchargeAmount
+  surchargeType
+  isDefault
+  linkedVariantId
+  linkedVariant {
+    ...LinkedVariantSummary
+  }
+}
+
+fragment ProductAttributeDefinition on ProductAttributeDefinition {
+  id
+  name
+  slug
+  description
+  type
+  fillingMode
+  billingMode
+  taxClassId
+  scopeProductId
+  isRequired
+  isVisible
+  displayOrder
+  minValue
+  maxValue
+  options {
+    ...ProductAttributeOption
   }
 }

package/mutations.graphql

@@ -497,3 +497,18 @@ mutation WishlistDelete($wishlistId: ID!) {
     userErrors
   }
 }
+
+# ============================================
+# Cart Attributes
+# ============================================
+
+mutation CartAttributesUpdate($cartId: ID!, $attributes: [CartAttributeInput!]!) {
+  cartAttributesUpdate(cartId: $cartId, attributes: $attributes) {
+    cart {
+      ...Cart
+    }
+    userErrors {
+      ...UserError
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-operations",
-  "version": "4.4.0",
+  "version": "5.4.1",
   "description": "GraphQL operations for DoSwiftly Storefront - SSOT from backend",
   "homepage": "https://doswiftly.pl",
   "publishConfig": {
@@ -14,10 +14,6 @@
     "./fragments.graphql": "./fragments.graphql",
     "./*.graphql": "./*.graphql"
   },
-  "scripts": {
-    "sync": "node scripts/sync-operations.js",
-    "build": "npm run sync"
-  },
   "keywords": [
     "graphql",
     "operations",
@@ -32,6 +28,11 @@
     "queries.graphql",
     "mutations.graphql",
     "fragments.graphql",
-    "README.md"
-  ]
-}
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "sync": "node scripts/sync-operations.js",
+    "build": "npm run sync"
+  }
+}

package/queries.graphql

@@ -23,6 +23,19 @@ query Product($id: ID, $handle: String) {
   }
 }
 
+# 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).
+query ProductConfigurator($handle: String!, $fillingMode: String = "CUSTOMER") {
+  product(handle: $handle) {
+    ...ProductFull
+    attributes(filter: { fillingMode: $fillingMode }) {
+      ...ProductAttributeDefinition
+    }
+  }
+}
+
 query Products(
   $first: Int = 20
   $after: String
@@ -460,7 +473,7 @@ query ProductRecommendations($productId: ID!, $limit: Int = 8, $intent: Recommen
 query SimilarProducts($productId: String!, $first: Int = 6) {
   similarProducts(productId: $productId, first: $first) {
     items {
-      ...ProductCard
+      ...ProductRecommendation
     }
     totalCount
   }
@@ -468,11 +481,110 @@ query SimilarProducts($productId: String!, $first: Int = 6) {
 
 query CartRecommendations($cartId: String!, $first: Int = 4) {
   cartRecommendations(cartId: $cartId, first: $first) {
-    frequentlyBoughtTogether {
-      ...ProductCard
+    ...CartRecommendation
+  }
+}
+
+# ============================================
+# Content: Pages
+# ============================================
+
+query Page($handle: String, $id: ID) {
+  page(handle: $handle, id: $id) {
+    ...ShopPage
+  }
+}
+
+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 {
+      node {
+        ...ShopPage
+      }
+      cursor
     }
-    youMayAlsoLike {
-      ...ProductCard
+    pageInfo {
+      ...PageInfo
     }
+    totalCount
+  }
+}
+
+# ============================================
+# Content: Navigation Menus
+# ============================================
+
+query Menu($handle: String!) {
+  menu(handle: $handle) {
+    ...Menu
+  }
+}
+
+# ============================================
+# Content: URL Redirects
+# ============================================
+
+query UrlRedirects($first: Int = 250, $after: String) {
+  urlRedirects(first: $first, after: $after) {
+    nodes {
+      ...UrlRedirect
+    }
+    pageInfo {
+      ...PageInfo
+    }
+  }
+}
+
+# ============================================
+# Store Availability: per-location stock (Shopify parity — BOPIS / multi-location)
+# ============================================
+# Field returns null for single-location shops (storefront can skip the store picker).
+# `near`, `locationType`, and `@inContext(preferredLocationId)` shape the ordering.
+
+query ProductStoreAvailability($handle: String, $id: ID) {
+  product(handle: $handle, id: $id) {
+    id
+    handle
+    title
+    variants {
+      ...VariantStoreAvailability
+    }
+  }
+}
+
+# ============================================
+# Locations (store picker UI, Shopify parity)
+# ============================================
+
+query Locations(
+  $first: Int = 20
+  $after: String
+  $near: GeoCoordinateInput
+  $hasPickupEnabled: Boolean
+  $locationType: LocationType
+) {
+  locations(
+    first: $first
+    after: $after
+    near: $near
+    hasPickupEnabled: $hasPickupEnabled
+    locationType: $locationType
+  ) {
+    totalCount
+    pageInfo {
+      ...PageInfo
+    }
+    edges {
+      cursor
+      node {
+        ...Location
+      }
+    }
+  }
+}
+
+query Location($id: ID!) {
+  location(id: $id) {
+    ...Location
   }
 }