fix: surface userErrors and warnings from cart mutations in hydrogen-react

[umxr]

WHY are these changes introduced?

Fixes #3378

All cart mutations in hydrogen-react silently discard userErrors and warnings returned by the Storefront API. The mutation queries only select the cart object from the response payload, meaning validation errors (e.g., invalid quantity) and warnings (e.g., discount not applicable) are lost. This makes it impossible for merchants to provide meaningful feedback to customers when a cart operation partially fails or produces warnings.

The hydrogen package already handles this correctly — each mutation query includes userErrors and warnings fields and surfaces them through formatAPIResult. This PR brings hydrogen-react in line with that behavior.

WHAT is this pull request doing?

• cart-queries.ts — Adds userErrors { code field message } and warnings { code message target } to all 8 cart mutation queries (cartCreate, cartLinesAdd, cartLinesUpdate, cartLinesRemove, cartNoteUpdate, cartBuyerIdentityUpdate, cartAttributesUpdate, cartDiscountCodesUpdate)
• cart-types.ts — Adds userErrors and warnings to CartMachineContext, CartWithActions, and the RESOLVE event payload
• useCartActions.tsx — Updates fetch type generics to include userErrors and warnings in mutation response types
• useCartAPIStateMachine.tsx — Extracts userErrors/warnings from each mutation response, passes them through the state machine, and clears them on error/completion transitions
• CartProvider.tsx — Exposes userErrors and warnings on the useCart() return value

After this change, merchants can access errors and warnings like so:

const { userErrors, warnings } = useCart();

HOW to test your changes?

1. pnpm install
2. Run the existing + new tests: cd packages/hydrogen-react && npx vitest run src/CartProvider.test.tsx
3. All 60 tests should pass, including 3 new ones:
   • surfaces userErrors from the mutation response
   • surfaces warnings from the mutation response
   • clears userErrors and warnings on subsequent successful mutation
4. Type check: npx tsc --noEmit --project packages/hydrogen-react/tsconfig.json — no new errors

Checklist

• I've read the Contributing Guidelines
• I've considered possible cross-platform impacts (Mac, Linux, Windows)
• I've added a changeset if this PR contains user-facing or functional changes. Test changes or internal-only config changes do not require a changeset.
• I've added tests to cover my changes
• I've added or updated the documentation

[fredericoo]

blocking: all three new tests are missing "before" assertions for userErrors and warnings.

The tests assert the final state after the mutation, but don't verify the initial state before. A "before" assertion confirms the mutation is what causes the state change, not some pre-existing value.

let's add assertions before each void act() call:

// Before linesAdd
expect(result.current.userErrors).toBeUndefined();
expect(result.current.warnings).toBeUndefined();

void act(() => {
  result.current.linesAdd([{merchandiseId: '123'}]);
});

Same applies to the "clears userErrors and warnings" test - the initial state before the first mutation should be verified too.

[umxr]

done in fc0d51d

[fredericoo]

non-blocking: the userErrors and warnings field selections are copy-pasted into all 8 mutations (80 lines of duplication).

The hydrogen package avoids this with GraphQL fragments (USER_ERROR_FRAGMENT, CART_WARNING_FRAGMENT in packages/hydrogen/src/cart/queries/cart-fragments.ts). If the Storefront API ever adds a field to CartUserError or CartWarning, all 8 mutations would need updating in lockstep - classic change amplification.

A simple extraction would eliminate this:

const CART_MUTATION_FIELDS = `
  userErrors { code field message }
  warnings { code message target }
`;

Then reference via ${CART_MUTATION_FIELDS} in each mutation. The existing hydrogen-react queries don't use fragments so this is consistent with the current pattern, but the duplication is substantial enough to warrant extraction.

[umxr]

done in f8b0f9c

[fredericoo]

non-blocking: when GraphQL-level errors exist, userErrors and warnings from the same response are silently discarded here.

The CartMachineFetchResultEvent ERROR case doesn't include these fields in its type either. If a mutation response contains both GraphQL errors and userErrors, the userErrors are lost.

This follows the pre-existing pattern for how errors takes priority over everything else, so it's consistent. But worth noting as a known behavioural limitation - a Storefront API response can technically contain both.

[fredericoo]

non-blocking: eventFromFetchResult now takes 5 positional params with a type asymmetry - these last two accept Array<PartialDeep<CartUserError> | undefined> and filter internally to CartUserError[]. The PartialDeep wrapper from the generic fetchCart return type leaks into the function interface.

The internal narrowing is correct (pull complexity downward), but the interface exposes an implementation detail of the data pipeline. Not worth changing in this PR since it follows the existing pattern, but something to keep in mind for future work.

[fredericoo]

nit: these eslint-disable-next-line comments follow the existing pattern in the file (same comments exist for errors and rawCartResult clearing). Pre-existing pattern issue, not introduced by this PR.

[fredericoo]

praise: nice - the introduction of CartMutationResponse centralises the mutation response shape, makes it impossible to forget userErrors or warnings in a new mutation, and reduces cognitive load across the 8 callbacks.

[fredericoo]

praise: good use of CartUserError and CartWarning from storefront-api-types rather than defining custom types. The type guard filter here is a proper narrowing pattern - nice.