@doswiftly/storefront-sdk 12.0.0 → 13.1.0

package/CHANGELOG.md

@@ -1,5 +1,244 @@
 # Changelog
 
+## 13.1.0
+
+### Minor Changes
+
+- 2e137ad: Added cart-aware shipping methods discovery: `Cart.requiresShipping`, `CartLine.requiresShipping`, and `cart.availableShippingMethods(address)`.
+
+  **What's new for the storefront**
+  - **`cart.requiresShipping: Boolean!`** — single signal whether the cart needs physical shipping at all. `false` for carts that contain only digital goods (downloads, gift cards, services, subscriptions). Use it to skip the shipping picker step in checkout entirely.
+  - **`cart.lines.nodes[].requiresShipping: Boolean!`** — per-line classification. Useful in cart drawer UI to flag physical vs digital lines independently.
+  - **`cart.availableShippingMethods(address: ShippingAddressInput!): AvailableShippingMethodsPayload!`** — field on `Cart` that returns shipping methods for the cart's contents at the given destination. The backend pulls subtotal and weight from the cart aggregate — you no longer need to compute them on the client. For digital-only carts the response is `{ methods: [], userErrors: [{ code: 'DIGITAL_ONLY_NO_SHIPPING' }] }`.
+  - **`CartAvailableShippingMethods` query** — new named operation ready to drop into your storefront codegen pipeline.
+
+  **Recommended checkout flow**
+
+  ```graphql
+  query CartAvailableShippingMethods(
+    $cartId: ID!
+    $address: ShippingAddressInput!
+  ) {
+    cart(id: $cartId) {
+      id
+      requiresShipping
+      availableShippingMethods(address: $address) {
+        methods {
+          id
+          name
+          price {
+            amount
+            currencyCode
+          }
+        }
+        userErrors {
+          code
+          message
+          field
+        }
+      }
+    }
+  }
+  ```
+
+  If `cart.requiresShipping === false`, skip rendering the shipping picker and proceed straight to payment. Calling `cartSelectShippingMethod` on a digital-only cart returns `userErrors[{ code: 'FORBIDDEN_SHIPPING_METHOD' }]`, matching the readiness check that `cartComplete` already enforces.
+
+  **Backward compatibility**
+  - The existing standalone `availableShippingMethods(address, cart: CartShippingInput)` query is **unchanged**. Keep using it for pre-cart shipping calculators on product detail pages (when the customer has not created a cart yet).
+  - The new field and new query are purely additive. No existing operations change shape.
+
+  **Free-shipping progress + delivery estimates are now localized**
+
+  The `freeShippingProgress.message` field and `estimatedDelivery.description` field used to be hardcoded in English. They now respect the `Accept-Language` header (defaults to Polish — `pl`). If your storefront previously parsed these strings, switch to the structured fields (`qualifies`, `progressPercent`, `remaining.amount`, `minDays`, `maxDays`) instead.
+
+  **Reason codes on shipping `userErrors`**
+
+  | Code                       | When                             | UI reaction                                  |
+  | -------------------------- | -------------------------------- | -------------------------------------------- |
+  | `DIGITAL_ONLY_NO_SHIPPING` | Cart contains only digital items | Skip shipping picker, go straight to payment |
+  | `NO_SHIPPING_METHODS`      | Address has no matching zone     | Show "no delivery to your country"           |
+  | `SHIPPING_ERROR`           | Internal service error (rare)    | Retry or fall back to pre-cart preview query |
+
+  **Why both packages bump together**
+
+  `@doswiftly/storefront-sdk` ships local copies of the cart fragments that this update extends with `requiresShipping`, so the SDK release pairs with the schema/operations release. `@doswiftly/commerce-policy` exports `NON_PHYSICAL_TYPES` for downstream tooling that wants to mirror the same classification on the client side.
+
+## 13.0.0
+
+### Major Changes
+
+- 783ce01: Faceted aggregation accuracy + DX naming consolidation w `productFilters` API. Plus boolean facet count dla "availableForSale" + payload cleanup w Cart query.
+
+  ## BREAKING — `AvailableFilters.matchCount` removed → `totalCount`
+
+  Pole `matchCount` zostało usunięte. Użyj `totalCount` — semantyka identyczna (produkty w current context PRZED zaaplikowaniem faceted filters), nazwa zaligned z `ProductConnection.totalCount` (Relay Connection spec).
+
+  **Migration** (1:1 rename):
+
+  ```graphql
+  # PRZED
+  query Listing {
+    productFilters {
+      matchCount # ❌ removed
+      activeCount
+    }
+  }
+
+  # PO
+  query Listing {
+    productFilters {
+      totalCount # ✅ same semantics, Relay-aligned
+      activeCount
+    }
+  }
+  ```
+
+  ## BREAKING — `ProductFilter.available: true` semantics
+
+  Filter teraz includuje untracked produkty (gift cards, digital, made-to-order — wszystko z `trackQuantity = false`). Semantyka zgodna z `Product.isAvailable` resolver — single source of truth dla "co jest sellable".
+
+  **Pre-fix**: `available: true` zwracał tylko produkty z fizycznym stockiem (`available > 0`), wykluczał untracked. Storefront widział "Dostępne (3)" w sidebar (computed via `isAvailable`), po kliku dostawał 2 produkty (SQL filter różny).
+
+  **Post-fix**: oba źródła zwracają to samo.
+
+  Jeśli polegałeś na exclusion untracked przez `available: true` (np. żeby ukryć gift cards) — użyj `ProductFilter.type` lub osobnej logiki klienckiej.
+
+  ## NEW — `AvailableFilters.availableCount: Int!`
+
+  Nowy boolean facet count — liczba produktów spełniających `Product.isAvailable` w current context. Storefront UI renderuje "Dostępne (N)" w sidebar facet panel.
+
+  Exclude-self: gdy `AvailableFiltersInput.available` jest provided w `currentFilters`, `availableCount` IGNORUJE ten filter (pokazuje "ile produktów ten facet odsłoni gdy włączysz") — inne facets aplikują go normalnie.
+
+  ## NEW — `AvailableFiltersInput.available: Boolean`
+
+  Storefront może passować obecny `available` filter context do `productFilters` query — wymagane dla exclude-self semantyki. Pomiń (null/undefined) gdy filtr "Dostępne" nie jest aktywny w UI.
+
+  ## IMPROVEMENT — Faceted count accuracy (`productCount` mismatch eliminated)
+
+  Per-attribute / per-brand / per-category `productCount` teraz używa exclude-self aggregation pattern. Facet count MATCHUJE `products(filters).totalCount` gdy storefront aplikuje facet jako filter.
+
+  **Pre-fix**: `productFilters({categoryId, available: true}).attributes[producent].filterValues[Funko].productCount = 4` (ignoring `available`), `products({categoryId, available: true, attributes: [Funko]}).totalCount = 3` (3 sellable + 1 OOS Funko). Storefront pokazywał "Funko (4)", user dostawał 3 — utracone zaufanie do countów.
+
+  **Post-fix**: oba zwracają 3. Facet ignoruje WYŁĄCZNIE swój wymiar w `currentFilters`, aplikuje pozostałe + `available` + context (categoryId/collectionId/searchQuery).
+
+  ## IMPROVEMENT — Cart query payload size
+
+  `Cart.lines` query w SDK używał obu form (`edges + nodes`) z których konsumowane były wyłącznie `nodes`. Backend serializował `CartLine` fragment 2× per request. Usunięcie duplikatu — redukcja payload typowo 5-20KB per cart request (proportional do liczby pozycji).
+
+  Brak API change widzialnej dla consumer — SDK używa `cart.lines.nodes` jak wcześniej. Internal SDK improvement.
+
+  ## Example: end-to-end facet sidebar query (post-rename)
+
+  ```graphql
+  query ProductListing($input: AvailableFiltersInput) {
+    productFilters(input: $input) {
+      totalCount # ile produktów w current context (przed faceted filters)
+      availableCount # ile sellable (boolean facet, exclude-self)
+      activeCount # input.currentFilters.length
+      attributes {
+        handle
+        filterValues {
+          value
+          productCount
+        } # per-value facet count (exclude-self per attrDef)
+      }
+      brands {
+        slug
+        name
+        productCount
+      } # per-brand facet count
+      categories {
+        slug
+        name
+        productCount
+      } # per-category facet count
+      priceRange {
+        min {
+          amount
+          currencyCode
+        }
+        max {
+          amount
+          currencyCode
+        }
+      }
+    }
+
+    products(
+      filters: [
+        { available: true }
+        { attributes: [{ attributeId: "producent", values: ["Funko"] }] }
+      ]
+    ) {
+      totalCount
+      nodes {
+        id
+        title
+        isAvailable
+      }
+    }
+  }
+  ```
+
+  Gdy storefront aplikuje "Dostępne + Producent=Funko" jako filter w UI:
+
+  ```graphql
+  variables: {
+    input: {
+      available: true,
+      currentFilters: [{ attributeId: "producent", values: ["Funko"] }]
+    }
+  }
+  ```
+
+  - `availableCount` = liczba sellable Funko w context (ignoring `input.available`, applying `producent: Funko`)
+  - `attributes[producent].filterValues[Funko].productCount` = liczba sellable produktów (ignoring `producent`, applying `available: true`) = `products(filters).totalCount`
+
+### Minor Changes
+
+- e64cfc5: Brand entity available in Storefront API: filter products by canonical brand + read brand details per product.
+
+  **What's new in Storefront API**
+  - **`Product.brand: BrandSummary`** — every product now exposes its canonical brand (when assigned). Returns `{ id, name, slug, logo }` or `null` if the product has no brand. Resolved via DataLoader so listing 50 products incurs at most 1 brand query (no N+1).
+  - **`ProductFilter.brand: BrandFilter`** — new filter input accepting either `{ id: "uuid" }` or `{ slug: "funko" }`. Multiple `brand` entries in `filters[]` use OR semantics. Combine with other filters (price, tags, attributes) using AND across different field names.
+  - **`AvailableFilters.brands: [BrandFilterValue!]!`** — `productFilters` query now returns aggregated brands present in the current product set, each with `productCount`. Build a brand facet (checkbox list or dropdown with logo) directly from this response. Only active brands with at least one product in context are included.
+
+  **Example: brand facet + filter on a listing page**
+
+  ```graphql
+  query Listing {
+    productFilters {
+      brands {
+        id
+        name
+        slug
+        logo
+        productCount
+      }
+    }
+    products(filters: [{ brand: { slug: "funko" } }]) {
+      totalCount
+      nodes {
+        id
+        title
+        brand {
+          name
+          slug
+          logo
+        }
+      }
+    }
+  }
+  ```
+
+  **Migration**
+  - Existing `Product.vendor: String` (legacy free-text) remains supported. New brand-based filtering uses `ProductFilter.brand` instead of `productVendor`.
+  - No breaking changes. All new fields are nullable / optional — queries written before this release continue to work.
+
+  **SDK**
+
+  Regenerated types include `BrandSummary`, `BrandFilter`, `BrandFilterValue`, and `Product.brand`. Import them from `@doswiftly/storefront-operations` schema types.
+
 ## 12.0.0
 
 ### Major Changes

package/dist/core/operations/cart.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cart.d.ts","sourceRoot":"","sources":["../../../src/core/operations/cart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAwSH,eAAO,MAAM,UAAU,QAOrB,CAAC;AAMH,eAAO,MAAM,WAAW,QAWtB,CAAC;AAEH,eAAO,MAAM,cAAc,QAWzB,CAAC;AAEH,eAAO,MAAM,iBAAiB,QAW5B,CAAC;AAEH,eAAO,MAAM,iBAAiB,QAW5B,CAAC;AAEH,eAAO,MAAM,0BAA0B,QAWrC,CAAC;AAEH,eAAO,MAAM,gBAAgB,QAW3B,CAAC;AAEH,eAAO,MAAM,0BAA0B,QAWrC,CAAC;AAMH,eAAO,MAAM,yBAAyB,QAWpC,CAAC;AAEH,eAAO,MAAM,wBAAwB,QAWnC,CAAC;AAEH,eAAO,MAAM,2BAA2B,QAWtC,CAAC;AAEH,eAAO,MAAM,0BAA0B,QAWrC,CAAC;AAEH,eAAO,MAAM,oBAAoB,QAW/B,CAAC;AAEH,eAAO,MAAM,qBAAqB,QAWhC,CAAC;AAEH,eAAO,MAAM,+BAA+B,QAW1C,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,QAWxB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QASzB,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,QAoBtC,CAAC"}
+{"version":3,"file":"cart.d.ts","sourceRoot":"","sources":["../../../src/core/operations/cart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAsSH,eAAO,MAAM,UAAU,QAOrB,CAAC;AAMH,eAAO,MAAM,WAAW,QAWtB,CAAC;AAEH,eAAO,MAAM,cAAc,QAWzB,CAAC;AAEH,eAAO,MAAM,iBAAiB,QAW5B,CAAC;AAEH,eAAO,MAAM,iBAAiB,QAW5B,CAAC;AAEH,eAAO,MAAM,0BAA0B,QAWrC,CAAC;AAEH,eAAO,MAAM,gBAAgB,QAW3B,CAAC;AAEH,eAAO,MAAM,0BAA0B,QAWrC,CAAC;AAMH,eAAO,MAAM,yBAAyB,QAWpC,CAAC;AAEH,eAAO,MAAM,wBAAwB,QAWnC,CAAC;AAEH,eAAO,MAAM,2BAA2B,QAWtC,CAAC;AAEH,eAAO,MAAM,0BAA0B,QAWrC,CAAC;AAEH,eAAO,MAAM,oBAAoB,QAW/B,CAAC;AAEH,eAAO,MAAM,qBAAqB,QAWhC,CAAC;AAEH,eAAO,MAAM,+BAA+B,QAW1C,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,QAWxB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QASzB,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,QAoBtC,CAAC"}

package/dist/core/operations/cart.js

@@ -113,6 +113,7 @@ const CART_LINE_FRAGMENT = `
     productTitle
     productHandle
     productType
+    requiresShipping
   }
   ${CART_LINE_COST_FRAGMENT}
   ${PRODUCT_VARIANT_FRAGMENT}
@@ -191,10 +192,6 @@ const CART_FRAGMENT = `
     totalQuantity
     cost { ...CartCost }
     lines(first: 100) {
-      edges {
-        cursor
-        node { ... on CartLine { ...CartLine } }
-      }
       nodes { ... on CartLine { ...CartLine } }
       pageInfo { ...PageInfo }
       totalCount
@@ -211,6 +208,7 @@ const CART_FRAGMENT = `
     selectedShippingMethod { ...CartShippingMethod }
     selectedPaymentMethod { ...CartSelectedPaymentMethod }
     appliedGiftCards { ...CartAppliedGiftCard }
+    requiresShipping
     createdAt
     updatedAt
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-sdk",
-  "version": "12.0.0",
+  "version": "13.1.0",
   "description": "Storefront runtime SDK for DoSwiftly Commerce — layered transport, middleware pipeline, React providers, Zustand stores, cache strategies. 0 runtime dependencies in core.",
   "type": "module",
   "sideEffects": false,