@kizlo/woocommerce 0.14.0 → 0.15.0

package/README.md

@@ -58,6 +58,8 @@ The native value maps to the official registered `kizlo/tax-id` address field. F
 
 Raw introspection preserves `kizlo/tax-id` in both address schemas. Normalized billing `additionalFields` omits it from types and values: use the native property. Raw billing inputs using that key are rejected even when a duplicate equals `taxId`; there is no raw-only compatibility alias. Other registered and compatible unknown response extras retain their usual buckets.
 
+Registered billing extras retain their named enum and scalar types in reads, partial cart updates, and full confirmation/retry inputs, including registrations with a scalar string index. Full submissions require the registered answers and reject values outside their enums; partial cart updates allow omitted answers. These are compile-time guarantees from the consumer's registered contract. WooCommerce continues to validate against its live registry at runtime.
+
 Customer reads use the grouped `billing.additional_fields` adapter backed by public CheckoutFields helpers. Orders read their own snapshot, never the current profile. Storage remains `_wc_billing/kizlo/tax-id`, so existing saved values need no migration. Order admin edits set/replace/clear the order alone; profile edits affect later cart hydration. The retry validation/persistence bridge and shipping cleanup remain required on WooCommerce 11.0.1.
 
 Consumers should deploy the matching WooCommerce plugin and regenerate their contract after upgrading; the old per-field raw `billing.tax_id` response is removed. The native API remains `customer.billing.taxId` and `billingAddress.taxId`. This feature does not validate jurisdiction-specific identifiers or calculate tax exemptions.
@@ -68,6 +70,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: