@kizlo/woocommerce 0.14.1 → 0.16.0

package/README.md

@@ -42,6 +42,29 @@ pnpm add @kizlo/woocommerce
 
 See the [docs](https://kizlo.io/docs) for setup and usage.
 
+## Read cart separately from checkout
+
+Checkout get, update, confirm, and retry responses no longer include `cart`. Replace reads of `checkout.cart` with `cart.get`, or use the cart returned by a cart mutation:
+
+```ts
+const checkout = await kizlo.woocommerce.checkout.get.call()
+const cart = await kizlo.woocommerce.cart.get.call()
+```
+
+Refresh cart separately after checkout changes when your UI needs current totals or items. Checkout conflict errors still carry `data.cart` evidence; see [reviewed total protection](#protect-a-reviewed-checkout-total). Update consumers before deploying the companion plugin update.
+
+## Require login for checkout
+
+Set `allowGuest: false` to require a session from your configured Kizlo auth adapter for `checkout.get`, `checkout.update`, `checkout.confirm`, and `checkout.retry`. Anonymous calls return `UNAUTHORIZED` (401) before changing guest cookies or contacting WooCommerce. Register the integration alongside your auth integration in `createKizlo`; commerce hooks need no auth-provider client state.
+
+```ts
+import { woocommerce } from "@kizlo/woocommerce"
+
+const commerce = woocommerce({ allowGuest: false })
+```
+
+`allowGuest` defaults to `true`, permitting logged-out checkout subject to WooCommerce's own guest-checkout settings and validation. Customer APIs such as `customers.get` always require login. Guest carts, product/storefront reads, and order ownership/key checks (including guest receipts) keep their existing behavior. After installing a release containing this option, replace your application checkout-auth wrapper with `woocommerce({ allowGuest: false })`; procedure inputs, outputs, and hooks stay the same.
+
 ## Billing Tax IDs
 
 Billing addresses expose `taxId` on customers, carts, checkout responses, and orders. The field is always a string on output and defaults to `""` when it has not been set. Billing address inputs accept an optional `taxId`; shipping addresses have no native `taxId`, and Kizlo discards managed shipping copies independently of the hidden UI rule.
@@ -70,6 +93,28 @@ Storefront field definitions include SDK binding paths derived from the same add
 
 Update, confirm, and retry expose `CHECKOUT_VALIDATION_FAILED.data = { issues }`. Registered fields carry literal IDs and normalized SDK buckets for Kit or standalone consumers to match against loaded bindings. The browser entry retains schemas/types; the SDK resolver is removed. See [client handling and Kit requirements](./docs/checkout-validation.md) and the [breaking handler migration](./docs/checkout-validation-migration.md).
 
+## Protect a reviewed checkout total
+
+Pass optional `expectedTotal` when confirming checkout to protect the amount your shopper reviewed. Capture it with the cart you display, in minor units: `"1250"` means 12.50 in a currency with two decimal places. The input accepts digits-only strings, including `"0"`, and forwards them unchanged as WooCommerce's `expected_total`.
+
+```ts
+const reviewedTotal = String(cart.totals.total)
+
+const result = await kizlo.client.woocommerce.checkout.confirm({
+  body: { ...checkoutInput, expectedTotal: reviewedTotal },
+})
+
+if (!result.success && result.error.code === "CHECKOUT_TOTAL_MISMATCH") {
+  const { cart: updatedCart, expectedTotal, actualTotal } = result.error.data
+  // Display the available evidence and ask the shopper to review again.
+}
+```
+
+Upgrade `kizlo` to 0.26.1 or later alongside `@kizlo/woocommerce` so browser clients preserve the typed conflict. This protection requires [WooCommerce 11.1.0 or later](https://github.com/woocommerce/woocommerce/blob/11.1.0/plugins/woocommerce/src/StoreApi/Routes/V1/Checkout.php). An increased recalculated total returns `CHECKOUT_TOTAL_MISMATCH` with status 409 before order creation or payment; equal and decreased totals are allowed. Error data contains `cart: Cart | null` and optional minor-unit digit strings `expectedTotal` and `actualTotal`; missing or malformed evidence preserves the conflict. Omit the field for manual or express flows that cannot know the total up front, and on older WooCommerce versions that do not enforce it.
+
+- Keep the reviewed amount until the shopper approves a new one. Confirmation performs no cart refresh, amount substitution, or automatic retry.
+- `checkout.retry` pays an existing order through a separate protocol and does not accept `expectedTotal`.
+
 ## Storefront settings
 
 `storefront.get` returns the store-wide settings a storefront renders with, so nothing has to be hardcoded:

package/dist/checkout-validation.d.ts

@@ -1,2 +1,2 @@
-import { f as CheckoutRegisteredFieldReference, m as CheckoutValidationIssue, o as StorefrontField, p as CheckoutValidationData } from "./schema-ScTHhVY4.js";
+import { f as CheckoutRegisteredFieldReference, m as CheckoutValidationIssue, o as StorefrontField, p as CheckoutValidationData } from "./schema-CWDJjtW7.js";
 export { CheckoutRegisteredFieldReference, CheckoutValidationData, CheckoutValidationIssue, type StorefrontField };