@vtex/faststore 0.0.1

package/dist/sdk/cart/optimistic.d.ts

@@ -0,0 +1,24 @@
+import { CartEntity, CartItemEntity, CartItemQuantityDecreasePayload, CartItemQuantityIncreasePayload, CartItemRemovePayload } from "./operations.js";
+//#region src/sdk/cart/optimistic.d.ts
+/**
+ * Predicts the cart after `cartItemQuantityIncrease(input: { variantId, quantityToAdd })`.
+ */
+export declare function buildOptimisticIncrease(cart: CartEntity, item: CartItemEntity, by?: number): {
+  cartItemQuantityIncrease: CartItemQuantityIncreasePayload;
+};
+/**
+ * Predicts the cart after `cartItemQuantityDecrease(input: { variantId, quantityToRemove })`.
+ *
+ * If the resulting quantity would be `<= 0`, the line is removed entirely.
+ */
+export declare function buildOptimisticDecrease(cart: CartEntity, item: CartItemEntity, by?: number): {
+  cartItemQuantityDecrease: CartItemQuantityDecreasePayload;
+};
+/**
+ * Predicts the cart after `cartItemRemove(input: { variantId })`.
+ */
+export declare function buildOptimisticRemove(cart: CartEntity, item: CartItemEntity): {
+  cartItemRemove: CartItemRemovePayload;
+};
+//#endregion
+//# sourceMappingURL=optimistic.d.ts.map

package/dist/sdk/cart/optimistic.js

@@ -0,0 +1,164 @@
+//#region src/sdk/cart/optimistic.ts
+/**
+* Pure optimistic-response builders for the three cache-propagating cart mutations
+* (specs/mutation-contract.md AD-3 / AD-D6).
+*
+* Each builder takes the current `CartEntity` and the affected `CartItemEntity` and returns the
+* predicted post-mutation `Cart` carrying every field the canonical `CartFragment` selects:
+* `id`, `items`, `totalizers`, `total`. The shape MUST match Apollo's normalised cache slot for
+* the entity, so `__typename` and the same `id` are preserved.
+*
+* Lines are matched by their opaque `id` (Base64("CartItem:<orderFormId>:<uniqueId>")).
+*
+* Recomputation rules (kept simple — server reconciles drift on response):
+*   - `Items` totalizer (matched by `id === 'Items'`) is adjusted by `item.sellingPrice * delta`.
+*   - `total` (the cart's grand total) is adjusted by the same delta.
+*   - All other totalizers (Shipping, Discounts, …) stay as-is until the server response lands.
+*/
+function moneyAdd(money, delta) {
+	return {
+		__typename: "Money",
+		amount: Number(money.amount) + delta,
+		currencyCode: money.currencyCode
+	};
+}
+function adjustItemsTotalizer(totalizers, delta) {
+	return totalizers.map((t) => t.id === "Items" ? {
+		...t,
+		value: moneyAdd(t.value, delta)
+	} : t);
+}
+function emptyUserErrors() {
+	return [];
+}
+/**
+* Predicts the cart after `cartItemQuantityIncrease(input: { variantId, quantityToAdd })`.
+*/
+function buildOptimisticIncrease(cart, item, by = 1) {
+	if (by <= 0) return { cartItemQuantityIncrease: {
+		__typename: "CartItemQuantityIncreasePayload",
+		cart,
+		userErrors: emptyUserErrors()
+	} };
+	const currentItem = cart.items.find((i) => i.id === item.id);
+	if (!currentItem) return { cartItemQuantityIncrease: {
+		__typename: "CartItemQuantityIncreasePayload",
+		cart,
+		userErrors: emptyUserErrors()
+	} };
+	const newQuantity = currentItem.quantity + by;
+	const delta = currentItem.sellingPrice.amount * by;
+	const updatedItems = cart.items.map((i) => i.id === item.id ? {
+		...i,
+		quantity: newQuantity
+	} : i);
+	return { cartItemQuantityIncrease: {
+		__typename: "CartItemQuantityIncreasePayload",
+		cart: {
+			__typename: "Cart",
+			id: cart.id,
+			items: updatedItems,
+			totalizers: adjustItemsTotalizer(cart.totalizers, delta),
+			total: moneyAdd(cart.total, delta),
+			messages: cart.messages,
+			appliedCoupons: cart.appliedCoupons
+		},
+		userErrors: emptyUserErrors()
+	} };
+}
+/**
+* Predicts the cart after `cartItemQuantityDecrease(input: { variantId, quantityToRemove })`.
+*
+* If the resulting quantity would be `<= 0`, the line is removed entirely.
+*/
+function buildOptimisticDecrease(cart, item, by = 1) {
+	if (by <= 0) return { cartItemQuantityDecrease: {
+		__typename: "CartItemQuantityDecreasePayload",
+		cart,
+		userErrors: emptyUserErrors()
+	} };
+	const currentItem = cart.items.find((i) => i.id === item.id);
+	if (!currentItem) return { cartItemQuantityDecrease: {
+		__typename: "CartItemQuantityDecreasePayload",
+		cart,
+		userErrors: emptyUserErrors()
+	} };
+	const requestedQuantity = currentItem.quantity - by;
+	const removed = requestedQuantity <= 0;
+	const actualDelta = removed ? currentItem.quantity : by;
+	const priceDelta = -currentItem.sellingPrice.amount * actualDelta;
+	const updatedItems = removed ? cart.items.filter((i) => i.id !== item.id) : cart.items.map((i) => i.id === item.id ? {
+		...i,
+		quantity: requestedQuantity
+	} : i);
+	return { cartItemQuantityDecrease: {
+		__typename: "CartItemQuantityDecreasePayload",
+		cart: {
+			__typename: "Cart",
+			id: cart.id,
+			items: updatedItems,
+			totalizers: adjustItemsTotalizer(cart.totalizers, priceDelta),
+			total: moneyAdd(cart.total, priceDelta),
+			messages: cart.messages,
+			appliedCoupons: cart.appliedCoupons
+		},
+		userErrors: emptyUserErrors()
+	} };
+}
+/**
+* Predicts the cart after `cartItemRemove(input: { variantId })`.
+*/
+function buildOptimisticRemove(cart, item) {
+	const currentItem = cart.items.find((i) => i.id === item.id);
+	if (!currentItem) return { cartItemRemove: {
+		__typename: "CartItemRemovePayload",
+		cart,
+		userErrors: emptyUserErrors()
+	} };
+	const priceDelta = -currentItem.sellingPrice.amount * currentItem.quantity;
+	return { cartItemRemove: {
+		__typename: "CartItemRemovePayload",
+		cart: {
+			__typename: "Cart",
+			id: cart.id,
+			items: cart.items.filter((i) => i.id !== item.id),
+			totalizers: adjustItemsTotalizer(cart.totalizers, priceDelta),
+			total: moneyAdd(cart.total, priceDelta),
+			messages: cart.messages,
+			appliedCoupons: cart.appliedCoupons
+		},
+		userErrors: emptyUserErrors()
+	} };
+}
+/**
+* Predicts the cart after `cartItemsRemove(input: { variantIds })` — the N-line generalisation of
+* `buildOptimisticRemove`. Lines absent from the cart are ignored; the summed price delta of the
+* matched lines adjusts the `Items` totalizer and the grand total.
+*/
+function buildOptimisticRemoveItems(cart, items) {
+	const removedIds = new Set(items.map((item) => item.id));
+	const removedLines = cart.items.filter((i) => removedIds.has(i.id));
+	if (removedLines.length === 0) return { cartItemsRemove: {
+		__typename: "CartItemsRemovePayload",
+		cart,
+		userErrors: emptyUserErrors()
+	} };
+	const priceDelta = removedLines.reduce((sum, line) => sum - line.sellingPrice.amount * line.quantity, 0);
+	return { cartItemsRemove: {
+		__typename: "CartItemsRemovePayload",
+		cart: {
+			__typename: "Cart",
+			id: cart.id,
+			items: cart.items.filter((i) => !removedIds.has(i.id)),
+			totalizers: adjustItemsTotalizer(cart.totalizers, priceDelta),
+			total: moneyAdd(cart.total, priceDelta),
+			messages: cart.messages,
+			appliedCoupons: cart.appliedCoupons
+		},
+		userErrors: emptyUserErrors()
+	} };
+}
+//#endregion
+export { buildOptimisticDecrease, buildOptimisticIncrease, buildOptimisticRemove, buildOptimisticRemoveItems };
+
+//# sourceMappingURL=optimistic.js.map

package/dist/sdk/cart/optimistic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimistic.js","names":[],"sources":["../../../src/sdk/cart/optimistic.ts"],"sourcesContent":["import type {\n  CartEntity,\n  CartItemEntity,\n  CartItemQuantityDecreasePayload,\n  CartItemQuantityIncreasePayload,\n  CartItemRemovePayload,\n  CartItemsRemovePayload,\n  CartTotalizer,\n  Money,\n} from './operations.js';\n\n/**\n * Pure optimistic-response builders for the three cache-propagating cart mutations\n * (specs/mutation-contract.md AD-3 / AD-D6).\n *\n * Each builder takes the current `CartEntity` and the affected `CartItemEntity` and returns the\n * predicted post-mutation `Cart` carrying every field the canonical `CartFragment` selects:\n * `id`, `items`, `totalizers`, `total`. The shape MUST match Apollo's normalised cache slot for\n * the entity, so `__typename` and the same `id` are preserved.\n *\n * Lines are matched by their opaque `id` (Base64(\"CartItem:<orderFormId>:<uniqueId>\")).\n *\n * Recomputation rules (kept simple — server reconciles drift on response):\n *   - `Items` totalizer (matched by `id === 'Items'`) is adjusted by `item.sellingPrice * delta`.\n *   - `total` (the cart's grand total) is adjusted by the same delta.\n *   - All other totalizers (Shipping, Discounts, …) stay as-is until the server response lands.\n */\n\nfunction moneyAdd(money: Money, delta: number): Money {\n  // `Money.amount` is typed as `number` by codegen but arrives over the wire as a decimal *string*\n  // (the server's `Decimal` scalar = `(cents / 100).toFixed(2)`). Without coercing, `string + number`\n  // concatenates (e.g. \"49.99\" + 49.99 → \"49.9949.99\"), which formats to NaN during the optimistic\n  // window until the server response replaces it. Number() restores numeric addition.\n  return { __typename: 'Money', amount: Number(money.amount) + delta, currencyCode: money.currencyCode };\n}\n\nfunction adjustItemsTotalizer(totalizers: readonly CartTotalizer[], delta: number): CartTotalizer[] {\n  return totalizers.map((t) => (t.id === 'Items' ? { ...t, value: moneyAdd(t.value, delta) } : t));\n}\n\nfunction emptyUserErrors<T>(): T[] {\n  return [];\n}\n\n/**\n * Predicts the cart after `cartItemQuantityIncrease(input: { variantId, quantityToAdd })`.\n */\nexport function buildOptimisticIncrease(\n  cart: CartEntity,\n  item: CartItemEntity,\n  by = 1,\n): { cartItemQuantityIncrease: CartItemQuantityIncreasePayload } {\n  if (by <= 0) {\n    return {\n      cartItemQuantityIncrease: {\n        __typename: 'CartItemQuantityIncreasePayload',\n        cart,\n        userErrors: emptyUserErrors(),\n      },\n    };\n  }\n\n  const currentItem = cart.items.find((i) => i.id === item.id);\n  if (!currentItem) {\n    return {\n      cartItemQuantityIncrease: {\n        __typename: 'CartItemQuantityIncreasePayload',\n        cart,\n        userErrors: emptyUserErrors(),\n      },\n    };\n  }\n\n  const newQuantity = currentItem.quantity + by;\n  const delta = currentItem.sellingPrice.amount * by;\n\n  const updatedItems = cart.items.map((i) => (i.id === item.id ? { ...i, quantity: newQuantity } : i));\n\n  return {\n    cartItemQuantityIncrease: {\n      __typename: 'CartItemQuantityIncreasePayload',\n      cart: {\n        __typename: 'Cart',\n        id: cart.id,\n        items: updatedItems,\n        totalizers: adjustItemsTotalizer(cart.totalizers, delta),\n        total: moneyAdd(cart.total, delta),\n        messages: cart.messages,\n        appliedCoupons: cart.appliedCoupons,\n      },\n      userErrors: emptyUserErrors(),\n    },\n  };\n}\n\n/**\n * Predicts the cart after `cartItemQuantityDecrease(input: { variantId, quantityToRemove })`.\n *\n * If the resulting quantity would be `<= 0`, the line is removed entirely.\n */\nexport function buildOptimisticDecrease(\n  cart: CartEntity,\n  item: CartItemEntity,\n  by = 1,\n): { cartItemQuantityDecrease: CartItemQuantityDecreasePayload } {\n  if (by <= 0) {\n    return {\n      cartItemQuantityDecrease: {\n        __typename: 'CartItemQuantityDecreasePayload',\n        cart,\n        userErrors: emptyUserErrors(),\n      },\n    };\n  }\n\n  const currentItem = cart.items.find((i) => i.id === item.id);\n  if (!currentItem) {\n    return {\n      cartItemQuantityDecrease: {\n        __typename: 'CartItemQuantityDecreasePayload',\n        cart,\n        userErrors: emptyUserErrors(),\n      },\n    };\n  }\n\n  const requestedQuantity = currentItem.quantity - by;\n  const removed = requestedQuantity <= 0;\n  const actualDelta = removed ? currentItem.quantity : by;\n  const priceDelta = -currentItem.sellingPrice.amount * actualDelta;\n\n  const updatedItems = removed\n    ? cart.items.filter((i) => i.id !== item.id)\n    : cart.items.map((i) => (i.id === item.id ? { ...i, quantity: requestedQuantity } : i));\n\n  return {\n    cartItemQuantityDecrease: {\n      __typename: 'CartItemQuantityDecreasePayload',\n      cart: {\n        __typename: 'Cart',\n        id: cart.id,\n        items: updatedItems,\n        totalizers: adjustItemsTotalizer(cart.totalizers, priceDelta),\n        total: moneyAdd(cart.total, priceDelta),\n        messages: cart.messages,\n        appliedCoupons: cart.appliedCoupons,\n      },\n      userErrors: emptyUserErrors(),\n    },\n  };\n}\n\n/**\n * Predicts the cart after `cartItemRemove(input: { variantId })`.\n */\nexport function buildOptimisticRemove(\n  cart: CartEntity,\n  item: CartItemEntity,\n): { cartItemRemove: CartItemRemovePayload } {\n  const currentItem = cart.items.find((i) => i.id === item.id);\n  if (!currentItem) {\n    return {\n      cartItemRemove: {\n        __typename: 'CartItemRemovePayload',\n        cart,\n        userErrors: emptyUserErrors(),\n      },\n    };\n  }\n\n  const priceDelta = -currentItem.sellingPrice.amount * currentItem.quantity;\n\n  return {\n    cartItemRemove: {\n      __typename: 'CartItemRemovePayload',\n      cart: {\n        __typename: 'Cart',\n        id: cart.id,\n        items: cart.items.filter((i) => i.id !== item.id),\n        totalizers: adjustItemsTotalizer(cart.totalizers, priceDelta),\n        total: moneyAdd(cart.total, priceDelta),\n        messages: cart.messages,\n        appliedCoupons: cart.appliedCoupons,\n      },\n      userErrors: emptyUserErrors(),\n    },\n  };\n}\n\n/**\n * Predicts the cart after `cartItemsRemove(input: { variantIds })` — the N-line generalisation of\n * `buildOptimisticRemove`. Lines absent from the cart are ignored; the summed price delta of the\n * matched lines adjusts the `Items` totalizer and the grand total.\n */\nexport function buildOptimisticRemoveItems(\n  cart: CartEntity,\n  items: readonly CartItemEntity[],\n): { cartItemsRemove: CartItemsRemovePayload } {\n  const removedIds = new Set(items.map((item) => item.id));\n  const removedLines = cart.items.filter((i) => removedIds.has(i.id));\n  if (removedLines.length === 0) {\n    return {\n      cartItemsRemove: {\n        __typename: 'CartItemsRemovePayload',\n        cart,\n        userErrors: emptyUserErrors(),\n      },\n    };\n  }\n\n  const priceDelta = removedLines.reduce((sum, line) => sum - line.sellingPrice.amount * line.quantity, 0);\n\n  return {\n    cartItemsRemove: {\n      __typename: 'CartItemsRemovePayload',\n      cart: {\n        __typename: 'Cart',\n        id: cart.id,\n        items: cart.items.filter((i) => !removedIds.has(i.id)),\n        totalizers: adjustItemsTotalizer(cart.totalizers, priceDelta),\n        total: moneyAdd(cart.total, priceDelta),\n        messages: cart.messages,\n        appliedCoupons: cart.appliedCoupons,\n      },\n      userErrors: emptyUserErrors(),\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/sdk/cart/use-cart-actions.d.ts

@@ -0,0 +1,56 @@
+import "../../core/dist/index.js";
+import { CartUserError } from "./operations.js";
+import { ApolloClient } from "@apollo/client";
+//#region src/sdk/cart/use-cart-actions.d.ts
+export type AddItemPayload = Readonly<{
+  variantId: string;
+  quantity?: number;
+  /** Seller global Node ID, e.g. base64("Seller:1"). The server rejects raw ids with INVALID_SELLER_ID. */
+  seller: string;
+}>;
+/** Existing-line payloads address the line by its opaque cart-item `id`; the handler reads the rest from cache. */
+export type CartLinePayload = Readonly<{
+  id: string;
+}>;
+/** Batch payloads address several lines by their opaque cart-item `id`s. */
+export type CartLinesPayload = Readonly<{
+  ids: readonly string[];
+}>;
+export type CartQuantityPayload = Readonly<{
+  id: string;
+  by?: number;
+}>;
+/** Coupon writes address the coupon by its `code`; the server resolves the cart from the cookie. */
+export type CartCouponPayload = Readonly<{
+  code: string;
+}>;
+/**
+ * The `cart` namespace surface. Item writes return the resulting `userErrors` (empty on success)
+ * and publish them to `cartUserErrorsVar`; coupon writes publish to the dedicated
+ * `cartCouponErrorsVar` (specs/fspg-830-coupon-entry.md AD-2).
+ */
+export type CartActions = Readonly<{
+  /** Add an item to the cart. Async (no optimistic response). Creates the cart on first add. */
+  addItem: (payload: AddItemPayload) => Promise<readonly CartUserError[]>;
+  /** Remove a line entirely. Optimistic. */
+  removeItem: (payload: CartLinePayload) => Promise<readonly CartUserError[]>;
+  /** Remove several lines in one mutation. Optimistic. Ids missing from the cache are skipped. */
+  removeItems: (payload: CartLinesPayload) => Promise<readonly CartUserError[]>;
+  /** Increase a line's quantity by N (default 1). Optimistic. */
+  increaseQuantity: (payload: CartQuantityPayload) => Promise<readonly CartUserError[]>;
+  /** Decrease a line's quantity by N (default 1). Optimistic. Removes the line when result <= 0. */
+  decreaseQuantity: (payload: CartQuantityPayload) => Promise<readonly CartUserError[]>;
+  /** Apply a coupon code. Async (no optimistic). Publishes userErrors to cartCouponErrorsVar. */
+  applyCoupon: (payload: CartCouponPayload) => Promise<readonly CartUserError[]>;
+  /** Remove a coupon code by code. Async (no optimistic). Publishes userErrors to cartCouponErrorsVar. */
+  removeCoupon: (payload: CartCouponPayload) => Promise<readonly CartUserError[]>;
+  /**
+   * Re-check the active cart against the platform and adopt corrected availability. Async (no
+   * optimistic), read-only upstream. Returns userErrors (empty on success) to its caller and stamps
+   * the freshness window on success. Unlike the item writes it does NOT publish to
+   * `cartUserErrorsVar` — a speculative open-time failure must raise no error banner (Decision 6).
+   */
+  validate: () => Promise<readonly CartUserError[]>;
+}>;
+//#endregion
+//# sourceMappingURL=use-cart-actions.d.ts.map

package/dist/sdk/cart/use-cart-actions.js

@@ -0,0 +1,348 @@
+"use client";
+import { defineActions } from "../../core/dist/actions/registry.js";
+import "../../core/dist/index.js";
+import { cartCouponErrorsVar, cartLastAddVar, cartUserErrorsVar, orderFormIdVar } from "../state/cart.js";
+import { CART_COUPON_APPLY, CART_COUPON_REMOVE, CART_ITEMS_REMOVE, CART_ITEM_ADD, CART_ITEM_QUANTITY_DECREASE, CART_ITEM_QUANTITY_INCREASE, CART_ITEM_REMOVE, CART_VALIDATE, CartFragment } from "./operations.js";
+import { buildOptimisticDecrease, buildOptimisticIncrease, buildOptimisticRemove, buildOptimisticRemoveItems } from "./optimistic.js";
+import { markAvailabilityFresh, trackCartWrite } from "./write-gate.js";
+import { useApolloClient, useMutation } from "@apollo/client/react";
+import { useCallback, useMemo } from "react";
+//#region src/sdk/cart/use-cart-actions.ts
+/**
+* The `cart` action namespace — the consolidated, context-free owner of every cart write
+* (specs/actions.md, docs/storefront-core/adr-0010-actions-own-the-write-side.md).
+*
+* It replaces `useCartMutations` + the mutation handlers `CartRoot` used to publish through
+* `CartDataContext`. A handler reads the current cart from the normalized Apollo cache (keyed by
+* `orderFormIdVar`), not from component props or React context, so any component anywhere in the
+* tree can dispatch a write through the compiler-injected `$actions.cart.*` prop — the cache is the
+* only meeting point between the read side and the write side (ADR-0010).
+*
+* `userErrors` from every call are published to `cartUserErrorsVar` (cleared at the start of the
+* next call) so `CartError` can surface them without a data context, and also returned to the caller.
+*/
+/**
+* Thrown by the existing-line handlers (remove / quantity) when invoked before the cart resolves.
+* The first `addItem` mints the cart and hydrates `orderFormIdVar`; until then there is no cached
+* cart entity to read for the optimistic response.
+*/
+var CartNotReadyError = class extends Error {
+	constructor(message) {
+		super(message ?? "CartNotReadyError: no cart in cache yet; add an item (or load the cart) before mutating a line.");
+		this.name = "CartNotReadyError";
+	}
+};
+const NETWORK_USER_ERROR = {
+	code: "NETWORK_ERROR",
+	message: "Unable to update cart. Please try again."
+};
+function publish(errors) {
+	cartUserErrorsVar(errors);
+	return errors;
+}
+/** Coupon-scoped publish — keeps coupon feedback off the shared item-error channel (AD-2). */
+function publishCoupon(errors) {
+	cartCouponErrorsVar(errors);
+	return errors;
+}
+/**
+* Publish a write's outcome and, when it came back clean, stamp the availability freshness window —
+* a clean write's payload carries the platform's recomputed cart, which is what lets the
+* validate-on-open call skip (specs/mini-cart-validation-wiring.md, Decision 2). Used only on paths
+* where a mutation actually reached the server: a `userErrors` response carries `cart: null` and a
+* no-op (unknown line) issues no request, so neither refreshes availability.
+*/
+function publishWrite(errors) {
+	if (errors.length === 0) markAvailabilityFresh();
+	return publish(errors);
+}
+/** Coupon-channel counterpart of `publishWrite`. */
+function publishCouponWrite(errors) {
+	if (errors.length === 0) markAvailabilityFresh();
+	return publishCoupon(errors);
+}
+/**
+* Backfill `orderFormIdVar` from a mutation's returned `cart.id` when local state is still cold.
+* A coupon op can be the first cart write (SSR cold / drawer closed on first load); without this the
+* later `requireLine` paths short-circuit on `orderFormIdVar() === null` and throw `CartNotReadyError`.
+* Mirrors the `addItem` first-add handoff.
+*/
+function hydrateCartId(cartId) {
+	if (cartId && orderFormIdVar() === null) orderFormIdVar(cartId);
+}
+/**
+* Read the live cart entity from the normalized cache (ADR-0010), keyed by `orderFormIdVar`. Returns
+* null before the cart is minted/loaded. Module-level so it can be shared with the read-only callers
+* that live outside this hook — the pre-checkout gate re-reads the corrected cart this way after
+* `validate` resolves, because Apollo commits the mutation's cache write before the promise settles
+* (specs/mini-cart-validation-wiring.md, Decision 3). The codegen `CartFragment` document embeds its
+* nested fragments, so it is a self-contained read.
+*/
+function readCartFromCache(client) {
+	const cartId = orderFormIdVar();
+	if (!cartId) return null;
+	const cacheId = client.cache.identify({
+		__typename: "Cart",
+		id: cartId
+	});
+	if (!cacheId) return null;
+	return client.cache.readFragment({
+		id: cacheId,
+		fragment: CartFragment,
+		fragmentName: "CartFragment"
+	}) ?? null;
+}
+/**
+* The `cart` namespace hook. Registered with the first-party action registry via `cartActions`
+* below; the compiler-emitted `CartActionProvider` calls it and threads the narrowed methods into
+* each consumer's `$actions.cart`.
+*/
+function useCartActions() {
+	const client = useApolloClient();
+	const [addMutation] = useMutation(CART_ITEM_ADD);
+	const [removeMutation] = useMutation(CART_ITEM_REMOVE);
+	const [removeItemsMutation] = useMutation(CART_ITEMS_REMOVE);
+	const [increaseMutation] = useMutation(CART_ITEM_QUANTITY_INCREASE);
+	const [decreaseMutation] = useMutation(CART_ITEM_QUANTITY_DECREASE);
+	const [applyCouponMutation] = useMutation(CART_COUPON_APPLY);
+	const [removeCouponMutation] = useMutation(CART_COUPON_REMOVE);
+	const [validateMutation] = useMutation(CART_VALIDATE);
+	const readCart = useCallback(() => readCartFromCache(client), [client]);
+	const requireLine = useCallback((id) => {
+		const cart = readCart();
+		if (!cart) throw new CartNotReadyError();
+		const line = cart.items.find((item) => item.id === id);
+		if (!line) return null;
+		return {
+			cart,
+			line
+		};
+	}, [readCart]);
+	const addItem = useCallback(async (payload) => {
+		cartUserErrorsVar([]);
+		try {
+			const result = await trackCartWrite(addMutation({ variables: { input: {
+				variantId: payload.variantId,
+				quantity: payload.quantity ?? 1,
+				seller: payload.seller
+			} } }));
+			if (orderFormIdVar() === null) {
+				const newId = result.data?.cartItemAdd?.cart?.id ?? null;
+				if (newId) orderFormIdVar(newId);
+			}
+			const errors = result.data?.cartItemAdd?.userErrors ?? [];
+			if (errors.length === 0) cartLastAddVar(cartLastAddVar() + 1);
+			return publishWrite(errors);
+		} catch (error) {
+			console.error("[cart.addItem] cartItemAdd failed", error);
+			return publish([NETWORK_USER_ERROR]);
+		}
+	}, [addMutation]);
+	const removeItem = useCallback(async (payload) => {
+		const found = requireLine(payload.id);
+		if (!found) return publish([]);
+		cartUserErrorsVar([]);
+		try {
+			return publishWrite((await trackCartWrite(removeMutation({
+				variables: { input: { variantId: found.line.variant.variantId } },
+				optimisticResponse: buildOptimisticRemove(found.cart, found.line)
+			}))).data?.cartItemRemove?.userErrors ?? []);
+		} catch (error) {
+			console.error("[cart.removeItem] cartItemRemove failed", error);
+			return publish([NETWORK_USER_ERROR]);
+		}
+	}, [requireLine, removeMutation]);
+	const removeItems = useCallback(async (payload) => {
+		const cart = readCart();
+		if (!cart) throw new CartNotReadyError();
+		const lines = cart.items.filter((item) => payload.ids.includes(item.id));
+		if (lines.length === 0) return publish([]);
+		const variantIds = [...new Set(lines.map((line) => line.variant.variantId))];
+		cartUserErrorsVar([]);
+		try {
+			return publishWrite((await trackCartWrite(removeItemsMutation({
+				variables: { input: { variantIds } },
+				optimisticResponse: buildOptimisticRemoveItems(cart, lines)
+			}))).data?.cartItemsRemove?.userErrors ?? []);
+		} catch (error) {
+			console.error("[cart.removeItems] cartItemsRemove failed", error);
+			return publish([NETWORK_USER_ERROR]);
+		}
+	}, [readCart, removeItemsMutation]);
+	const increaseQuantity = useCallback(async (payload) => {
+		const by = payload.by ?? 1;
+		const found = requireLine(payload.id);
+		if (!found) return publish([]);
+		cartUserErrorsVar([]);
+		try {
+			return publishWrite((await trackCartWrite(increaseMutation({
+				variables: { input: {
+					variantId: found.line.variant.variantId,
+					quantityToAdd: by
+				} },
+				optimisticResponse: buildOptimisticIncrease(found.cart, found.line, by)
+			}))).data?.cartItemQuantityIncrease?.userErrors ?? []);
+		} catch (error) {
+			console.error("[cart.increaseQuantity] cartItemQuantityIncrease failed", error);
+			return publish([NETWORK_USER_ERROR]);
+		}
+	}, [requireLine, increaseMutation]);
+	const decreaseQuantity = useCallback(async (payload) => {
+		const by = payload.by ?? 1;
+		const found = requireLine(payload.id);
+		if (!found) return publish([]);
+		cartUserErrorsVar([]);
+		try {
+			return publishWrite((await trackCartWrite(decreaseMutation({
+				variables: { input: {
+					variantId: found.line.variant.variantId,
+					quantityToRemove: by
+				} },
+				optimisticResponse: buildOptimisticDecrease(found.cart, found.line, by)
+			}))).data?.cartItemQuantityDecrease?.userErrors ?? []);
+		} catch (error) {
+			console.error("[cart.decreaseQuantity] cartItemQuantityDecrease failed", error);
+			return publish([NETWORK_USER_ERROR]);
+		}
+	}, [requireLine, decreaseMutation]);
+	const applyCoupon = useCallback(async (payload) => {
+		cartCouponErrorsVar([]);
+		try {
+			const result = await trackCartWrite(applyCouponMutation({ variables: { input: { code: payload.code } } }));
+			hydrateCartId(result.data?.cartCouponApply?.cart?.id ?? null);
+			return publishCouponWrite(result.data?.cartCouponApply?.userErrors ?? []);
+		} catch (error) {
+			console.error("[cart.applyCoupon] cartCouponApply failed", error);
+			return publishCoupon([NETWORK_USER_ERROR]);
+		}
+	}, [applyCouponMutation]);
+	const removeCoupon = useCallback(async (payload) => {
+		cartCouponErrorsVar([]);
+		try {
+			const result = await trackCartWrite(removeCouponMutation({ variables: { input: { code: payload.code } } }));
+			hydrateCartId(result.data?.cartCouponRemove?.cart?.id ?? null);
+			return publishCouponWrite(result.data?.cartCouponRemove?.userErrors ?? []);
+		} catch (error) {
+			console.error("[cart.removeCoupon] cartCouponRemove failed", error);
+			return publishCoupon([NETWORK_USER_ERROR]);
+		}
+	}, [removeCouponMutation]);
+	const validate = useCallback(async () => {
+		try {
+			const result = await validateMutation();
+			hydrateCartId(result.data?.cartValidate?.cart?.id ?? null);
+			const errors = result.data?.cartValidate?.userErrors ?? [];
+			if (errors.length === 0) markAvailabilityFresh();
+			return errors;
+		} catch (error) {
+			console.error("[cart.validate] cartValidate failed", error);
+			return [NETWORK_USER_ERROR];
+		}
+	}, [validateMutation]);
+	return useMemo(() => ({
+		addItem,
+		removeItem,
+		removeItems,
+		increaseQuantity,
+		decreaseQuantity,
+		applyCoupon,
+		removeCoupon,
+		validate
+	}), [
+		addItem,
+		removeItem,
+		removeItems,
+		increaseQuantity,
+		decreaseQuantity,
+		applyCoupon,
+		removeCoupon,
+		validate
+	]);
+}
+defineActions({
+	namespace: "cart",
+	description: "Mutation-backed writes against the current cart (consolidates useCartMutations / CartRoot).",
+	provider: {
+		name: "CartActionProvider",
+		importPath: "@vtex/faststore/internal/client"
+	},
+	methods: {
+		addItem: {
+			description: "Add an item to the cart (async strategy). Creates the cart on first add.",
+			payload: [
+				{
+					name: "variantId",
+					type: "string"
+				},
+				{
+					name: "seller",
+					type: "string"
+				},
+				{
+					name: "quantity",
+					type: "number",
+					optional: true
+				}
+			]
+		},
+		removeItem: {
+			description: "Remove a line from the cart (optimistic strategy).",
+			payload: [{
+				name: "id",
+				type: "string"
+			}]
+		},
+		removeItems: {
+			description: "Remove several lines from the cart in one call (optimistic strategy).",
+			payload: [{
+				name: "ids",
+				type: "string[]"
+			}]
+		},
+		increaseQuantity: {
+			description: "Increase a line's quantity by N (default 1, optimistic strategy).",
+			payload: [{
+				name: "id",
+				type: "string"
+			}, {
+				name: "by",
+				type: "number",
+				optional: true
+			}]
+		},
+		decreaseQuantity: {
+			description: "Decrease a line's quantity by N (default 1, optimistic). Removes the line at <= 0.",
+			payload: [{
+				name: "id",
+				type: "string"
+			}, {
+				name: "by",
+				type: "number",
+				optional: true
+			}]
+		},
+		applyCoupon: {
+			description: "Apply a coupon code to the cart (async strategy). Server recomputes totals.",
+			payload: [{
+				name: "code",
+				type: "string"
+			}]
+		},
+		removeCoupon: {
+			description: "Remove a coupon code from the cart (async strategy). Server recomputes totals.",
+			payload: [{
+				name: "code",
+				type: "string"
+			}]
+		},
+		validate: {
+			description: "Re-check the active cart against the platform and adopt corrected availability (async, read-only upstream).",
+			payload: []
+		}
+	},
+	use: useCartActions
+});
+//#endregion
+export { CartNotReadyError, readCartFromCache, useCartActions };
+
+//# sourceMappingURL=use-cart-actions.js.map