fix(cart): fetch totals with all fields + fix inconsistent total calculation (#16022)

Note: this should be merged after #16021 to use the shared `normalizeBigNumbers` utility

## Fix 1: Return totals when * fields are selected

Previously, we only returned totals when they're explicitely selected as the computation is expensive. However, this leads to unexpected results when a user passes `*` in the fields. So the following wouldn't work as expected:

```ts
// doesn't return totals
const { data: carts } = await query.graph({
    entity: "cart",
    fields: ["*"]
  })

// also doesn't return total. We strip all fields at the query layer when * is present
const { data: carts } = await query.graph({
    entity: "cart",
    fields: ["*", "total"]
  })

// this works
const { data: carts } = await query.graph({
    entity: "cart",
    fields: ["total", "id"]
  })
```

With the change in this PR, the totals will be returned as expected with `*`. This is fair as `*` by generally expensive and discouraged in the docs, and it matches the expectations of a user using it.

### Caveat

All retrievals of `*` fields or not passing `select` to `listOrders` (and similar methods) will result in totals retrieval, since those will retrieve all order fields. Need to be documented and included as part of the next release notes. To avoid retrieving them, users must pass either an empty array (retrieving no fields), or specify specific fields to retrieve.

## Fix 2: Total miscalculations based on retrieved items

In some use cases when a retrieving a specific field of cart's items without retrieving the quantity, the calculated totals are miscalculated. For example:

```ts
// totals are calculated
const { data: carts } = await query.graph({
    entity: "cart",
    fields: ["total", "items.quantity"]
  })

// totals are miscalculated as there's no quantity on the item
const { data: carts } = await query.graph({
    entity: "cart",
    fields: ["total", "items.unit_price"]
  })
```

This is unexpected behavior, the total shouldn't be impacted by which fields the user selects.

The solution in this PR has a caveat, which is that the quantity of items is now always returned when totals are returned even if not explicitely selected.

Co-authored-by: Nicolas Gorga <62995075+NicolasGorga@users.noreply.github.com>

Author: shahednasser

.changeset/humble-icons-invent.md

@@ -0,0 +1,5 @@
+---
+"@medusajs/cart": patch
+---
+
+fix(cart): fetch totals with all fields + fix inconsistent total calculation

integration-tests/http/__tests__/cart/cart-totals-query.spec.ts

@@ -0,0 +1,153 @@
+import { medusaIntegrationTestRunner } from "@medusajs/test-utils"
+import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils"
+
+jest.setTimeout(120000)
+
+// query.graph returns totals as BigNumber instances; coerce for numeric assertions.
+const num = (value) => Number(value)
+
+medusaIntegrationTestRunner({
+  testSuite: ({ getContainer }) => {
+    describe("Cart totals via Query (query.graph)", () => {
+      let query
+      let cartModule
+      let cartId
+
+      // 2 x $10 item + $10 shipping, no taxes/discounts =>
+      //   total 30, subtotal 30, item_subtotal 20, item[0].quantity 2, item[0].total 20
+      const seedCart = async () => {
+        const cart = await cartModule.createCarts({
+          currency_code: "usd",
+          email: "test@medusajs.com",
+          items: [
+            {
+              title: "Test item",
+              product_title: "Cool Product",
+              thumbnail: "https://example.com/thumb.png",
+              quantity: 2,
+              unit_price: 10,
+            },
+          ],
+        })
+        await cartModule.addShippingMethods([
+          { cart_id: cart.id, name: "Standard", amount: 10 },
+        ])
+        return cart.id
+      }
+
+      beforeAll(() => {
+        const container = getContainer()
+        query = container.resolve(ContainerRegistrationKeys.QUERY)
+        cartModule = container.resolve(Modules.CART)
+      })
+
+      beforeEach(async () => {
+        cartId = await seedCart()
+      })
+
+      afterEach(async () => {
+        await cartModule.deleteCarts([cartId])
+      })
+
+      it("returns cart totals when explicit total fields are requested", async () => {
+        const {
+          data: [cart],
+        } = await query.graph({
+          entity: "cart",
+          fields: [
+            "id",
+            "currency_code",
+            "total",
+            "subtotal",
+            "tax_total",
+            "shipping_total",
+            "item_subtotal",
+            "items.*",
+          ],
+          filters: { id: cartId },
+        })
+
+        expect(num(cart.total)).toEqual(30)
+        expect(num(cart.subtotal)).toEqual(30)
+        expect(num(cart.tax_total)).toEqual(0)
+        expect(num(cart.shipping_total)).toEqual(10)
+        expect(num(cart.item_subtotal)).toEqual(20)
+
+        expect(num(cart.items[0].quantity)).toEqual(2)
+        expect(num(cart.items[0].unit_price)).toEqual(10)
+        expect(num(cart.items[0].total)).toEqual(20)
+        expect(num(cart.items[0].subtotal)).toEqual(20)
+      })
+
+      it('returns cart totals when fields is a bare wildcard ("*")', async () => {
+        const {
+          data: [cart],
+        } = await query.graph({
+          entity: "cart",
+          fields: ["*"],
+          filters: { id: cartId },
+        })
+
+        // A bare "*" must NOT suppress the computed totals.
+        expect(num(cart.total)).toEqual(30)
+        expect(num(cart.subtotal)).toEqual(30)
+        expect(num(cart.item_subtotal)).toEqual(20)
+      })
+
+      it('returns cart totals when "*" is combined with explicit total fields', async () => {
+        const {
+          data: [cart],
+        } = await query.graph({
+          entity: "cart",
+          fields: ["*", "total", "subtotal"],
+          filters: { id: cartId },
+        })
+
+        expect(num(cart.total)).toEqual(30)
+        expect(num(cart.subtotal)).toEqual(30)
+      })
+
+      it("computes correct cart total when scoped item totals are requested alongside a total", async () => {
+        // Regression: requesting computed item totals (`items.total`,
+        // `items.subtotal`) next to a scoped scalar used to under-count the cart
+        // total to shipping-only (10) with item totals of 0.
+        const {
+          data: [cart],
+        } = await query.graph({
+          entity: "cart",
+          fields: [
+            "total",
+            "item_subtotal",
+            "items.total",
+            "items.subtotal",
+            "items.product_title",
+          ],
+          filters: { id: cartId },
+        })
+
+        expect(num(cart.total)).toEqual(30)
+        expect(num(cart.item_subtotal)).toEqual(20)
+        expect(num(cart.items[0].total)).toEqual(20)
+        expect(num(cart.items[0].subtotal)).toEqual(20)
+        expect(cart.items[0].product_title).toEqual("Cool Product")
+      })
+
+      it("computes correct totals with a partial scoped item selection", async () => {
+        // `items.quantity` without `items.unit_price` previously starved the
+        // calc, zeroing the item total and under-counting the cart total.
+        const {
+          data: [cart],
+        } = await query.graph({
+          entity: "cart",
+          fields: ["total", "item_subtotal", "items.quantity", "items.total"],
+          filters: { id: cartId },
+        })
+
+        expect(num(cart.total)).toEqual(30)
+        expect(num(cart.item_subtotal)).toEqual(20)
+        expect(num(cart.items[0].quantity)).toEqual(2)
+        expect(num(cart.items[0].total)).toEqual(20)
+      })
+    })
+  },
+})