@doswiftly/storefront-operations 19.1.0 → 19.2.0

package/AGENTS.md

@@ -27,7 +27,7 @@ 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**: 19.1.0
+- **Schema version**: 19.2.0
 - **Queries**: 52
 - **Mutations**: 41
 - **Fragments**: 104

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # Changelog
 
+## 19.2.0
+
+### Minor Changes
+
+- b60dcaf: Discount codes now report real per-code applicability and reasons on the cart and order.
+
+  **Why**: a recognised discount code previously always showed `isApplicable: true` even when it
+  reduced nothing — minimum-order not met, code expired, or no cart items within the code's product
+  scope — and `discountAllocations` only ever reflected the first code. The contract now tells the
+  truth per code, so a storefront can show the buyer exactly which codes apply and why the others do
+  not, and the order carries the same breakdown the buyer saw in the cart.
+
+  **Additive (backward-compatible)**:
+  1. `Cart.discountCodes[].isApplicable` is computed per code — `true` only when the code reduces the
+     price or grants free shipping — instead of being hard-coded to `true`.
+  2. `Cart.discountAllocations` contains one entry per applicable code, not just the first.
+  3. `cartDiscountCodesUpdate` returns a `warning` per non-applicable code
+     (`CartWarningCode.DISCOUNT_CODE_NOT_APPLICABLE`) whose localized message explains the reason. The
+     code stays on the cart, so adding a qualifying product can still activate it.
+  4. New `DiscountErrorCode.NOT_APPLICABLE_TO_CART` — the code is valid but no cart items fall within
+     its product/collection/category scope.
+  5. New `Order.discountAllocations` — the per-code breakdown frozen onto the order at checkout
+     (parity with `Cart.discountAllocations`), so a confirmation page renders the same rows.
+  6. `cartValidateDiscountCode` (the read-only preview) now mirrors the apply result: a code that is
+     recognised but out of scope for the cart returns `isValid: false` with
+     `error.code: NOT_APPLICABLE_TO_CART`. Inline "is this code valid?" feedback no longer reports a code
+     as valid when applying it would reduce nothing — preview and apply always agree.
+
+  **Usage example**:
+
+  ```ts
+  const { cart, warnings } = await cartDiscountCodesUpdate({
+    id,
+    discountCodes: ["SUMMER20"],
+  });
+
+  for (const entry of cart.discountCodes) {
+    if (!entry.isApplicable) {
+      // The code is recognised but not reducing the price — explain why.
+      const reason = warnings.find((w) => w.target === entry.code)?.message;
+      showInlineHint(entry.code, reason);
+    }
+  }
+  ```
+
+  **Migration checklist for existing storefronts**:
+  - [ ] If you render a discount chip, branch on `discountCodes[].isApplicable` instead of assuming the code applied.
+  - [ ] Surface `cartDiscountCodesUpdate.warnings` (code `DISCOUNT_CODE_NOT_APPLICABLE`) next to the chip to tell the buyer why a code is inactive.
+  - [ ] Sum `discountAllocations[].amount` to display a per-code discount breakdown; it equals the cart/order discount total.
+  - [ ] Optionally read `Order.discountAllocations` on the confirmation page for the same breakdown after checkout.
+  - [ ] If you preview codes with `cartValidateDiscountCode`, handle `isValid: false` + `NOT_APPLICABLE_TO_CART` — don't show "valid" for a scope-mismatch code (the preview now matches what apply returns).
+
+- d7b0185: Add `pickupConfig` to `AvailableShippingMethod` — render carrier pickup-point pickers at checkout
+
+  Shipping methods that deliver to a pickup point (`deliveryType` `LOCKER` or `PICKUP_POINT`) now expose a `pickupConfig` object with everything the storefront needs to let the buyer choose a collection point:
+  - `selectionMode: WIDGET` — render the carrier map widget. `widgetToken` (a public, domain-scoped browser token, e.g. the InPost Geowidget token — never a carrier API secret) and `scriptUrl` (the widget script to load) are provided.
+  - `selectionMode: SEARCH` — no browser widget; look points up server-side and render your own list. `widgetToken` and `scriptUrl` are `null` for this mode.
+
+  `pickupConfig` is `null` for `HOME` (street-address) delivery and when the merchant has not yet configured the carrier's public widget token — do not render a map in that case. The `AvailableShippingMethod` fragment now includes `pickupConfig`, so queries that spread it pick the new field up automatically once you regenerate your types.
+
+  Flow: render the picker from `pickupConfig`, then send the chosen point with `cartSetShippingAddress({ pickupPoint })` before `cartSelectShippingMethod` — the latter rejects a pickup method selected without a point (`PICKUP_POINT_REQUIRED`).
+
+- 88cd617: Expose pickup-point configuration on shipping methods, so a storefront can render the carrier point picker directly from the cart's available shipping methods.
+
+  `availableShippingMethods` now returns a `pickupConfig` for methods whose `deliveryType` is `PICKUP_POINT` or `LOCKER`:
+  - `provider` — carrier code the config belongs to (e.g. `"inpost"`).
+  - `selectionMode` — `WIDGET` (render the carrier map) or `SEARCH` (query points server-side and render your own list).
+  - `widgetToken` — public, domain-scoped widget token (e.g. the InPost Geowidget token) used to initialise the map. **Never** a carrier API secret. Null in `SEARCH` mode and when the merchant has not configured the public token.
+  - `scriptUrl` — CDN URL of the carrier widget script to load before rendering the map. Null in `SEARCH` mode.
+
+  `pickupConfig` is `null` for `HOME` delivery methods.
+
+  **Additive (backward-compatible)** — existing code that does not read `pickupConfig` keeps working unchanged.
+
 ## 19.1.0
 
 ### Minor Changes

package/README.md

@@ -550,7 +550,7 @@ full executable body of each operation.
 | `ShippingCarrier` | `ShippingCarrier` | Carrier offering the shipping method — id, display name, logo image (transformable), internal service code. |
 | `DeliveryEstimate` | `DeliveryEstimate` | Estimated delivery window — `minDays` to `maxDays` plus a human-readable description (e.g. "2-4 business days"). |
 | `FreeShippingProgress` | `FreeShippingProgress` | Free-shipping progress info — `qualifies` flag, current cart amount, threshold, remaining to qualify, percent progress, and a localized message ("Add 20 PLN more for free shipping"). Use to render a free-shipping progress bar in the cart drawer. |
-| `AvailableShippingMethod` | `AvailableShippingMethod` | 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. |
+| `AvailableShippingMethod` | `AvailableShippingMethod` | 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. For pickup methods, `pickupConfig` carries the public data needed to render the carrier point picker — `selectionMode = WIDGET` gives a `widgetToken` (e.g. the InPost Geowidget public token, never a carrier API secret) + `scriptUrl` to load the map; `selectionMode = SEARCH` means query points server-side. `pickupConfig` is null for HOME methods and when the merchant has not configured the carrier's public widget token (do not render a map then). Spread on the checkout shipping step. |
 
 #### Attribute Filters
 

package/fragments.graphql

@@ -339,6 +339,12 @@ fragment Order on Order {
     ...MailingAddress
   }
   itemCount
+  discountAllocations {
+    discountCode
+    amount {
+      ...Money
+    }
+  }
   canCreatePayment
   paymentMethodType
 }
@@ -1016,12 +1022,18 @@ fragment FreeShippingProgress on FreeShippingProgress {
   message
 }
 
-# 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.
+# 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. For pickup methods, `pickupConfig` carries the public data needed to render the carrier point picker — `selectionMode = WIDGET` gives a `widgetToken` (e.g. the InPost Geowidget public token, never a carrier API secret) + `scriptUrl` to load the map; `selectionMode = SEARCH` means query points server-side. `pickupConfig` is null for HOME methods and when the merchant has not configured the carrier's public widget token (do not render a map then). Spread on the checkout shipping step.
 fragment AvailableShippingMethod on AvailableShippingMethod {
   id
   name
   description
   deliveryType
+  pickupConfig {
+    provider
+    selectionMode
+    widgetToken
+    scriptUrl
+  }
   carrier {
     ...ShippingCarrier
   }

package/llms-full.txt

@@ -1,6 +1,6 @@
 # DoSwiftly Storefront Operations — Full Reference
 
-> Schema version: **19.1.0**
+> Schema version: **19.2.0**
 > 52 queries · 41 mutations · 104 fragments
 
 Auto-generated from `.graphql` source files. Do not edit by hand — this file is
@@ -2961,6 +2961,12 @@ fragment Order on Order {
     ...MailingAddress
   }
   itemCount
+  discountAllocations {
+    discountCode
+    amount {
+      ...Money
+    }
+  }
   canCreatePayment
   paymentMethodType
 }
@@ -3982,7 +3988,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. `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.
+**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. For pickup methods, `pickupConfig` carries the public data needed to render the carrier point picker — `selectionMode = WIDGET` gives a `widgetToken` (e.g. the InPost Geowidget public token, never a carrier API secret) + `scriptUrl` to load the map; `selectionMode = SEARCH` means query points server-side. `pickupConfig` is null for HOME methods and when the merchant has not configured the carrier's public widget token (do not render a map then). Spread on the checkout shipping step.
 
 **Uses fragments**: `DeliveryEstimate`, `FreeShippingProgress`, `Money`, `ShippingCarrier`
 
@@ -3993,6 +3999,12 @@ fragment AvailableShippingMethod on AvailableShippingMethod {
   name
   description
   deliveryType
+  pickupConfig {
+    provider
+    selectionMode
+    widgetToken
+    scriptUrl
+  }
   carrier {
     ...ShippingCarrier
   }

package/operations.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "19.1.0",
+  "schemaVersion": "19.2.0",
   "queries": [
     {
       "name": "Shop",
@@ -2096,7 +2096,7 @@
         "MailingAddress",
         "Money"
       ],
-      "body": "fragment Order on Order {\n  id\n  orderNumber\n  accessToken\n  totals {\n    total {\n      ...Money\n    }\n    subtotal {\n      ...Money\n    }\n    totalTax {\n      ...Money\n    }\n    totalShipping {\n      ...Money\n    }\n  }\n  status\n  paymentStatus\n  fulfillmentStatus\n  processedAt\n  confirmedAt\n  cancelledAt\n  expiredAt\n  shippingAddress {\n    ...MailingAddress\n  }\n  itemCount\n  canCreatePayment\n  paymentMethodType\n}",
+      "body": "fragment Order on Order {\n  id\n  orderNumber\n  accessToken\n  totals {\n    total {\n      ...Money\n    }\n    subtotal {\n      ...Money\n    }\n    totalTax {\n      ...Money\n    }\n    totalShipping {\n      ...Money\n    }\n  }\n  status\n  paymentStatus\n  fulfillmentStatus\n  processedAt\n  confirmedAt\n  cancelledAt\n  expiredAt\n  shippingAddress {\n    ...MailingAddress\n  }\n  itemCount\n  discountAllocations {\n    discountCode\n    amount {\n      ...Money\n    }\n  }\n  canCreatePayment\n  paymentMethodType\n}",
       "onType": "Order"
     },
     {
@@ -2597,7 +2597,7 @@
       "name": "AvailableShippingMethod",
       "kind": "fragment",
       "section": "Shipping Methods",
-      "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.",
+      "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. For pickup methods, `pickupConfig` carries the public data needed to render the carrier point picker — `selectionMode = WIDGET` gives a `widgetToken` (e.g. the InPost Geowidget public token, never a carrier API secret) + `scriptUrl` to load the map; `selectionMode = SEARCH` means query points server-side. `pickupConfig` is null for HOME methods and when the merchant has not configured the carrier's public widget token (do not render a map then). Spread on the checkout shipping step.",
       "variables": [],
       "fragmentRefs": [
         "DeliveryEstimate",
@@ -2605,7 +2605,7 @@
         "Money",
         "ShippingCarrier"
       ],
-      "body": "fragment AvailableShippingMethod on AvailableShippingMethod {\n  id\n  name\n  description\n  deliveryType\n  carrier {\n    ...ShippingCarrier\n  }\n  price {\n    ...Money\n  }\n  isFree\n  estimatedDelivery {\n    ...DeliveryEstimate\n  }\n  freeShippingProgress {\n    ...FreeShippingProgress\n  }\n  sortOrder\n}",
+      "body": "fragment AvailableShippingMethod on AvailableShippingMethod {\n  id\n  name\n  description\n  deliveryType\n  pickupConfig {\n    provider\n    selectionMode\n    widgetToken\n    scriptUrl\n  }\n  carrier {\n    ...ShippingCarrier\n  }\n  price {\n    ...Money\n  }\n  isFree\n  estimatedDelivery {\n    ...DeliveryEstimate\n  }\n  freeShippingProgress {\n    ...FreeShippingProgress\n  }\n  sortOrder\n}",
       "onType": "AvailableShippingMethod"
     },
     {

package/package.json

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

package/schema.graphql

@@ -453,6 +453,11 @@ type AvailableShippingMethod {
   """Display name of the method (e.g. "DPD Standard")."""
   name: String!
 
+  """
+  Pickup-point selection config — present only for pickup methods (deliveryType LOCKER / PICKUP_POINT) whose carrier exposes a public pickup mechanism. Null for HOME delivery and when the merchant has not configured the carrier's public widget token. Carries only browser-safe data (e.g. the InPost Geowidget public token), never the carrier API secret.
+  """
+  pickupConfig: ShippingPickupConfig
+
   """
   Cost of the method for the current cart (in the buyer preferred currency).
   """
@@ -1882,6 +1887,7 @@ type CartWarning {
 Stable, machine-readable codes for non-fatal cart warnings. The mutation succeeded; the storefront can surface a toast or stay silent based on the code.
 """
 enum CartWarningCode {
+  DISCOUNT_CODE_NOT_APPLICABLE
   MERCHANDISE_NOT_AVAILABLE
   MERCHANDISE_NOT_ENOUGH_STOCK
   PAYMENTS_AMOUNT_REGION_MISMATCH
@@ -2893,6 +2899,7 @@ enum DiscountErrorCode {
   INACTIVE
   MINIMUM_ORDER_NOT_MET
   MINIMUM_QUANTITY_NOT_MET
+  NOT_APPLICABLE_TO_CART
   NOT_FOUND
   NOT_STARTED
   SHOP_NOT_FOUND
@@ -4430,6 +4437,11 @@ type Order implements Node {
   """
   confirmedAt: DateTime
 
+  """
+  Per-code discount allocations on the order (parity with `Cart.discountAllocations`). One entry per code that reduced the price; empty when no discount applied. The sum of `amount` equals the order-level discount.
+  """
+  discountAllocations: [OrderDiscountAllocation!]!
+
   """
   When the order expired (e.g. pending payment timed out). Null when not expired.
   """
@@ -4515,6 +4527,17 @@ type OrderConnection {
   totalCount: Int!
 }
 
+"""
+Per-code discount applied to an order. Mirrors a cart discount allocation; the sum across allocations equals the order-level discount.
+"""
+type OrderDiscountAllocation {
+  """Amount discounted by this code on the order, in the order currency."""
+  amount: Money!
+
+  """The discount code that produced this allocation."""
+  discountCode: String!
+}
+
 """Order edge for pagination"""
 type OrderEdge {
   """Cursor"""
@@ -5032,6 +5055,21 @@ input PickupPointInput {
   provider: String!
 }
 
+"""
+How the buyer selects a pickup point for a shipping method that requires one.
+"""
+enum PickupSelectionMode {
+  """
+  No browser widget — query points server-side (by city / postal code) and render your own list. `widgetToken` / `scriptUrl` are null for this mode.
+  """
+  SEARCH
+
+  """
+  Render the carrier map widget (e.g. InPost Geowidget) initialised with `pickupConfig.widgetToken` + `pickupConfig.scriptUrl`. The buyer picks a point on the map.
+  """
+  WIDGET
+}
+
 """Points estimate for an order"""
 type PointsEstimate {
   """Base points to earn"""
@@ -6911,6 +6949,31 @@ type ShippingCarrier {
   serviceCode: String
 }
 
+"""
+Pickup-point selection config for a shipping method whose `deliveryType` is LOCKER or PICKUP_POINT. Contains ONLY public, browser-safe data — for InPost this is the domain-scoped Geowidget token, never the ShipX API secret. Use it to render the carrier map (`selectionMode = WIDGET`) or to drive a server-side point search (`selectionMode = SEARCH`).
+"""
+type ShippingPickupConfig {
+  """
+  Carrier code this config belongs to (e.g. "inpost"). Matches `carrier.serviceCode`'s provider.
+  """
+  provider: String!
+
+  """
+  CDN URL of the carrier widget script to load before rendering the map. Null for SEARCH mode.
+  """
+  scriptUrl: String
+
+  """
+  How to let the buyer pick a point — WIDGET (carrier map) or SEARCH (server-side point lookup).
+  """
+  selectionMode: PickupSelectionMode!
+
+  """
+  PUBLIC widget token used to initialise the carrier map (InPost Geowidget domain-scoped token). Never the carrier API secret. Null for SEARCH mode and when the merchant has not configured the public token (do not render the map — offer SEARCH or hide the method).
+  """
+  widgetToken: String
+}
+
 """Shop information"""
 type Shop {
   """Shop physical address"""