@asstio-dev/storefront 0.16.1 → 0.16.3

package/README.md

@@ -412,6 +412,44 @@ Problem codes you will meet here: `CART_EMPTY`, `CHECKOUT_CART_CHANGED` (with `c
 
   `https://*.kustom.co` covers the playground (`js.playground.kustom.co`) and production (`js.kustom.co`).
 
+### Shipping
+
+The shopper chooses delivery inside the provider's widget (Kustom's shipping assistant, Qliro's shipping step), so
+there is **no shipping picker to build and no price, VAT or method id to send**. The `klarna-kco` (Kustom) and `qliro-q1`
+controllers answer for the widget; the page's part is the estimate before the checkout and the shipping block on the order.
+
+```ts
+// The estimate: an estimate, never a quote (the destination is not known yet). No lookup, `no-store`.
+const { data: estimate } = await storefront.GET("/v1/cart/shipping-estimate", {
+  params: { header: { "X-Cart-Token": token } },
+});
+if (estimate?.available) {
+  const headline = estimate.options.find((option) => option.preselected); // `fee` is gross kronor, "49.00"
+  // estimate.freeShipping: { free, threshold, remaining } — progress comes from here, never a hard-coded threshold
+}
+// `available: false` means show nothing about shipping. `reason: null`: no block published on the market, and the
+// checkout works as before. `reason: "unavailable"`: a block that cannot be served now; the cart works, but
+// POST /v1/checkout refuses a new attempt with 503 SHIPPING_UNAVAILABLE (Retry-After 60) until it is fixed.
+
+// The order page: `order.shipping` is `OrderShippingDto | null`.
+// null = the selection was not matched or confirmed (the charged shipping line is still in `order.lines`), or the
+// market has no block. Show the block only when it is present; never read null as "no shipping was paid".
+```
+
+- `ShippingEstimateOptionDto`: `key`, `name`, `deliveryType` (`delivery`, `pickup` or `mailbox`), `fee`, `regularFee`
+  (the price without the free-shipping rule; set only when `fee` is `"0.00"` and that price is above 0, so `null`
+  for an always-free method: render no comparison price then), `labels`, `pointsAtCheckout` (the pickup point is
+  chosen in the checkout; none is listed here) and `preselected`. The estimate has **no delivery time**.
+- `OrderShippingDto`: `option`, `name`, `deliveryType`, `carrier`, `fee`, `point` (name, street, postal code, city; null
+  when the carrier assigned it or after the privacy scrub) and `deliveryTime` (`mode` `carrierEstimate`, `fixed` or
+  `text`; `minDays` and `maxDays` are each nullable: render only the bounds that are present, or `text`).
+- **Do not re-render the widget** when shipping changes, and do not write your own Qliro unlock: on a market with a
+  shipping block Qliro's total includes the fee and so can differ from the cart's, and the `qliro-q1` controller unlocks on the echoed cart version
+  (`MerchantUpdateVersion`) or on the confirmed total (see the Qliro notes above).
+- Shipping never blocks a purchase. If a selection cannot be matched when the shopper pays, the order is accepted and
+  normally held in Asstio with its reason (rarely the export waits for an operator instead); the page has nothing to
+  do for it.
+
 ## Headers
 
 Every call the client makes carries these; you never set them by hand.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asstio-dev/storefront",
-  "version": "0.16.1",
+  "version": "0.16.3",
   "description": "Typed client for the Asstio Storefront API (generated from OpenAPI).",
   "repository": {
     "type": "git",