feat(apps-nuvemshop): minicart cart loader and typed checkout errors

[JonasJesus42]

What

The minicart data for @decocms/apps-nuvemshop, using the Storefront API.

The cart stays in the browser (useCart, localStorage). Checkout goes through POST /checkouts. We don't use the theme's classic /comprar/ endpoint: after about 15 carts created in a few minutes, Nuvemshop returned 403 on every /comprar/ from that IP for over 40 minutes. A server-side proxy would send every buyer through the Worker's egress IPs, so one spike could block add-to-cart for the whole store. Details are in the apps-nuvemshop skill.

• loaders/cart turns the client items into minicart lines: name, variant, image, price, list price, subtotal and maxQuantity, plus totals and savings.

  • Products are fetched by ids, up to 30 per call, through the existing SWR cache.
  • Quantities are clamped to stock, because POST /checkouts rejects a line above it with 422 checkout_rejected.
  • Missing, hidden and sold-out variants go to unavailable and are left out of the totals.

• createCheckout now returns { error, message } instead of throwing. The success shape ({ checkoutUrl }) is unchanged.

  API response	error
  422 coupon_rejected	coupon_rejected
  422 checkout_rejected	out_of_stock
  404 resource_not_found	unavailable
  400 invalid_request	invalid

  NuvemshopApiError carries the API's status and code.

• Hooks: fetchCartDetails and useCartDetails() back the minicart; checkout() throws a CheckoutError with the code, so the UI can show the right message.

• There is no coupon preview before checkout, because the API has none. The checkout validates the coupon.

Stacked on #631.

Verified

• 103 tests pass; tsc, biome and skills:check are clean.
• Live against the demo store:
  • a 50-unit line is clamped to the variant's stock of 17, and the same line without the clamp is rejected as out_of_stock;
  • a promotional item shows R$169.90 against a list price of R$199.90;
  • a removed variant lands in unavailable;
  • an invalid coupon returns coupon_rejected;
  • the created checkout's subtotal and total (R$3,698.10) equal the loader's subtotal.

🤖 Generated with Claude Code

---

Summary by cubic

Adds a minicart loader and typed checkout errors to @decocms/apps-nuvemshop, moving checkout to the Storefront API instead of the classic /comprar/ endpoint, which IP-blocks server-side proxies after a handful of carts.

• loaders/cart resolves client-held useCart items into minicart lines (name, variant, image, prices, subtotal) with totals and savings, fetching products by ids, batched ≤30 per call and cached.
• Quantities are clamped to stock so POST /checkouts doesn't reject a line with 422 checkout_rejected; missing, hidden, and sold-out variants move to unavailable and are excluded from totals.
• createCheckout now returns { error, message } on failures instead of throwing, mapping API codes to typed errors (coupon_rejected, out_of_stock, unavailable, invalid); the success shape { checkoutUrl } is unchanged and NuvemshopApiError carries the status and code.
• New fetchCartDetails/useCartDetails hooks back the minicart; checkout() throws a CheckoutError carrying the code so the UI can react.
• There is no coupon preview before checkout because the API has none.

^{Written for commit e0cca9a. Summary will update on new commits.}

[github-actions]

🎉 This PR is included in version 7.77.0 🎉

The release is available on:

• blocks-v7.77.0
• GitHub release

Your semantic-release bot 📦🚀