@doswiftly/storefront-operations 13.0.0 → 13.1.0

package/AGENTS.md

@@ -27,8 +27,8 @@ consumer's `codegen.ts` references this package's `.graphql` files as
 live in the consumer's repo.
 
 <!-- AUTOGEN:STATS:BEGIN — auto-regenerated, do not edit by hand -->
-- **Schema version**: 13.0.0
-- **Queries**: 49
+- **Schema version**: 13.1.0
+- **Queries**: 50
 - **Mutations**: 40
 - **Fragments**: 100
 <!-- AUTOGEN:STATS:END -->

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # 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

package/README.md

@@ -241,7 +241,8 @@ full executable body of each operation.
 
 | Operation | Description |
 | --- | --- |
-| `AvailableShippingMethods` | 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. |
+| `AvailableShippingMethods` | 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. |
+| `CartAvailableShippingMethods` | 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. |
 
 #### Attribute Filters
 

package/fragments.graphql

@@ -407,6 +407,7 @@ fragment CartLine on CartLine {
   productTitle
   productHandle
   productType
+  requiresShipping
 }
 
 # Buyer identity associated with the cart. Note: only `customerId` is currently persisted server-side; `email`, `phone`, `countryCode` are accepted in the input but ignored.
@@ -488,6 +489,7 @@ fragment Cart on Cart {
   appliedGiftCards {
     ...CartAppliedGiftCard
   }
+  requiresShipping
   createdAt
   updatedAt
 }

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: **13.1.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.
@@ -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
@@ -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
 }

package/operations.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "13.0.0",
+  "schemaVersion": "13.1.0",
   "queries": [
     {
       "name": "Shop",
@@ -504,7 +504,7 @@
       "name": "AvailableShippingMethods",
       "kind": "query",
       "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": [
         {
           "name": "address",
@@ -524,6 +524,30 @@
       ],
       "body": "query AvailableShippingMethods($address: ShippingAddressInput!, $cart: CartShippingInput) {\n  availableShippingMethods(address: $address, cart: $cart) {\n    methods {\n      ...AvailableShippingMethod\n    }\n    freeShippingProgress {\n      ...FreeShippingProgress\n    }\n    userErrors {\n      ...UserError\n    }\n  }\n}"
     },
+    {
+      "name": "CartAvailableShippingMethods",
+      "kind": "query",
+      "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": [
+        {
+          "name": "cartId",
+          "type": "ID!",
+          "defaultValue": null
+        },
+        {
+          "name": "address",
+          "type": "ShippingAddressInput!",
+          "defaultValue": null
+        }
+      ],
+      "fragmentRefs": [
+        "AvailableShippingMethod",
+        "FreeShippingProgress",
+        "UserError"
+      ],
+      "body": "query CartAvailableShippingMethods($cartId: ID!, $address: ShippingAddressInput!) {\n  cart(id: $cartId) {\n    id\n    requiresShipping\n    availableShippingMethods(address: $address) {\n      methods {\n        ...AvailableShippingMethod\n      }\n      freeShippingProgress {\n        ...FreeShippingProgress\n      }\n      userErrors {\n        ...UserError\n      }\n    }\n  }\n}"
+    },
     {
       "name": "ProductFilters",
       "kind": "query",
@@ -2065,7 +2089,7 @@
         "CartLineCost",
         "ProductVariant"
       ],
-      "body": "fragment CartLine on CartLine {\n  id\n  quantity\n  variant {\n    ...ProductVariant\n  }\n  cost {\n    ...CartLineCost\n  }\n  attributes {\n    key\n    value\n  }\n  attributeSelections {\n    ...AttributeSelection\n  }\n  productId\n  productTitle\n  productHandle\n  productType\n}",
+      "body": "fragment CartLine on CartLine {\n  id\n  quantity\n  variant {\n    ...ProductVariant\n  }\n  cost {\n    ...CartLineCost\n  }\n  attributes {\n    key\n    value\n  }\n  attributeSelections {\n    ...AttributeSelection\n  }\n  productId\n  productTitle\n  productHandle\n  productType\n  requiresShipping\n}",
       "onType": "CartLine"
     },
     {
@@ -2118,7 +2142,7 @@
         "MailingAddress",
         "PageInfo"
       ],
-      "body": "fragment Cart on Cart {\n  id\n  checkoutUrl\n  totalQuantity\n  cost {\n    ...CartCost\n  }\n  lines(first: 100) {\n    edges {\n      cursor\n      node {\n        ... on CartLine {\n          ...CartLine\n        }\n      }\n    }\n    nodes {\n      ... on CartLine {\n        ...CartLine\n      }\n    }\n    pageInfo {\n      ...PageInfo\n    }\n    totalCount\n  }\n  buyerIdentity {\n    ...CartBuyerIdentity\n  }\n  discountCodes {\n    ...CartDiscountCode\n  }\n  discountAllocations {\n    ...CartDiscountAllocation\n  }\n  note\n  attributes {\n    key\n    value\n  }\n  email\n  phone\n  shippingAddress {\n    ...MailingAddress\n  }\n  billingAddress {\n    ...MailingAddress\n  }\n  selectedShippingMethod {\n    ...CartShippingMethod\n  }\n  selectedPaymentMethod {\n    ...CartSelectedPaymentMethod\n  }\n  appliedGiftCards {\n    ...CartAppliedGiftCard\n  }\n  createdAt\n  updatedAt\n}",
+      "body": "fragment Cart on Cart {\n  id\n  checkoutUrl\n  totalQuantity\n  cost {\n    ...CartCost\n  }\n  lines(first: 100) {\n    edges {\n      cursor\n      node {\n        ... on CartLine {\n          ...CartLine\n        }\n      }\n    }\n    nodes {\n      ... on CartLine {\n        ...CartLine\n      }\n    }\n    pageInfo {\n      ...PageInfo\n    }\n    totalCount\n  }\n  buyerIdentity {\n    ...CartBuyerIdentity\n  }\n  discountCodes {\n    ...CartDiscountCode\n  }\n  discountAllocations {\n    ...CartDiscountAllocation\n  }\n  note\n  attributes {\n    key\n    value\n  }\n  email\n  phone\n  shippingAddress {\n    ...MailingAddress\n  }\n  billingAddress {\n    ...MailingAddress\n  }\n  selectedShippingMethod {\n    ...CartShippingMethod\n  }\n  selectedPaymentMethod {\n    ...CartSelectedPaymentMethod\n  }\n  appliedGiftCards {\n    ...CartAppliedGiftCard\n  }\n  requiresShipping\n  createdAt\n  updatedAt\n}",
       "onType": "Cart"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-operations",
-  "version": "13.0.0",
+  "version": "13.1.0",
   "description": "GraphQL operations for DoSwiftly Storefront - SSOT from backend",
   "homepage": "https://doswiftly.pl",
   "publishConfig": {

package/queries.graphql

@@ -368,7 +368,7 @@ query GiftCardValidate($code: String!, $amount: Float) {
 # 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.
+# 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.
 query AvailableShippingMethods($address: ShippingAddressInput!, $cart: CartShippingInput) {
   availableShippingMethods(address: $address, cart: $cart) {
     methods {
@@ -383,6 +383,25 @@ query AvailableShippingMethods($address: ShippingAddressInput!, $cart: CartShipp
   }
 }
 
+# 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.
+query CartAvailableShippingMethods($cartId: ID!, $address: ShippingAddressInput!) {
+  cart(id: $cartId) {
+    id
+    requiresShipping
+    availableShippingMethods(address: $address) {
+      methods {
+        ...AvailableShippingMethod
+      }
+      freeShippingProgress {
+        ...FreeShippingProgress
+      }
+      userErrors {
+        ...UserError
+      }
+    }
+  }
+}
+
 # ============================================
 # Attribute Filters
 # ============================================

package/schema.graphql

@@ -776,6 +776,11 @@ type Cart implements Node {
   """Available payment methods dla tego cart (shop-configured providers)"""
   availablePaymentMethods: [PaymentMethod!]!
 
+  """
+  Cart-aware shipping methods discovery. Returns empty methods + DIGITAL_ONLY_NO_SHIPPING user error when the cart contains only non-physical items (digital, gift card, service, subscription). Physical / mixed carts get the same method computation as the standalone `availableShippingMethods` query but with subtotal and weight pulled from the cart aggregate.
+  """
+  availableShippingMethods(address: ShippingAddressInput!): AvailableShippingMethodsPayload!
+
   """
   Billing address ustawiony przez cartSetBillingAddress (jeśli różny od shipping)
   """
@@ -821,6 +826,11 @@ type Cart implements Node {
   """Product recommendations based on cart contents"""
   recommendations(first: Int = 4): CartRecommendations
 
+  """
+  True if any line in the cart requires physical shipping. False when every line is non-physical (digital, gift card, service, subscription). Use as the single signal to render or skip the shipping picker in checkout.
+  """
+  requiresShipping: Boolean!
+
   """Selected payment method (PayU/Stripe/COD/etc.)"""
   selectedPaymentMethod: PaymentMethod
 
@@ -1139,6 +1149,11 @@ type CartLine {
   """Quantity of this item"""
   quantity: Int!
 
+  """
+  True if this line item requires physical shipping (productType=PHYSICAL). False for digital, gift card, service, and subscription items. Use to skip the shipping step in checkout when every line is non-physical.
+  """
+  requiresShipping: Boolean!
+
   """Product variant being purchased"""
   variant: ProductVariant!
 }