feat(types,medusa): add inventory quantity to products endpoint (#7541)

what:

- when inventory_quantity is requested through the API, we calculate the inventory based on sales channels + stock locations and return the total available inventory.

A variant can have multiple inventory items. As an example:

Table: (variant)
  - 4 (required_quantity via link) x legs (inventory item)
  - 2 x table top

Only if all individual inventory items of a variant are available, do we mark the variant as available as a single unit. 

RESOLVES CORE-2187

packages/medusa/src/api/store/products/[id]/route.ts

@@ -1,12 +1,22 @@
 import { isPresent } from "@medusajs/utils"
 import { MedusaRequest, MedusaResponse } from "../../../../types/routing"
-import { refetchProduct } from "../helpers"
+import { refetchProduct, wrapVariantsWithInventoryQuantity } from "../helpers"
 import { StoreGetProductsParamsType } from "../validators"
 
 export const GET = async (
   req: MedusaRequest<StoreGetProductsParamsType>,
   res: MedusaResponse
 ) => {
+  const withInventoryQuantity = req.remoteQueryConfig.fields.some((field) =>
+    field.includes("variants.inventory_quantity")
+  )
+
+  if (withInventoryQuantity) {
+    req.remoteQueryConfig.fields = req.remoteQueryConfig.fields.filter(
+      (field) => !field.includes("variants.inventory_quantity")
+    )
+  }
+
   const filters: object = {
     id: req.params.id,
     ...req.filterableFields,
@@ -24,5 +34,9 @@ export const GET = async (
     req.remoteQueryConfig.fields
   )
 
+  if (withInventoryQuantity) {
+    await wrapVariantsWithInventoryQuantity(req, product.variants || [])
+  }
+
   res.json({ product })
 }

packages/medusa/src/api/store/products/helpers.ts

@@ -1,5 +1,11 @@
-import { MedusaContainer } from "@medusajs/types"
-import { refetchEntity } from "../../utils/refetch-entity"
+import { InventoryItemDTO, MedusaContainer } from "@medusajs/types"
+import {
+  ContainerRegistrationKeys,
+  MedusaError,
+  remoteQueryObjectFromString,
+} from "@medusajs/utils"
+import { MedusaRequest } from "../../../types/routing"
+import { refetchEntities, refetchEntity } from "../../utils/refetch-entity"
 
 export const refetchProduct = async (
   idOrFilter: string | object,
@@ -8,3 +14,117 @@ export const refetchProduct = async (
 ) => {
   return await refetchEntity("product", idOrFilter, scope, fields)
 }
+
+type VariantInventoryType = {
+  variant_id: string
+  variant: { manage_inventory: boolean }
+  required_quantity: number
+  inventory: InventoryItemDTO
+}
+
+export const wrapVariantsWithInventoryQuantity = async (
+  req: MedusaRequest,
+  variants: {
+    id: string
+    inventory_quantity?: number
+    manage_inventory?: boolean
+  }[]
+) => {
+  const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
+  const variantIds = variants.map((variant) => variant.id).flat(1)
+
+  if (!variantIds.length) {
+    return
+  }
+
+  if (!req.context?.stock_location_id?.length) {
+    throw new MedusaError(
+      MedusaError.Types.INVALID_DATA,
+      `Stock locations are required to compute inventory`
+    )
+  }
+
+  const linkQuery = remoteQueryObjectFromString({
+    entryPoint: "product_variant_inventory_item",
+    variables: {
+      filters: { variant_id: variantIds },
+      inventory: {
+        filters: {
+          location_levels: {
+            location_id: req.context?.stock_location_id || [],
+          },
+        },
+      },
+    },
+    fields: [
+      "variant_id",
+      "variant.manage_inventory",
+      "required_quantity",
+      "inventory.*",
+      "inventory.location_levels.*",
+    ],
+  })
+
+  const links: VariantInventoryType[] = await remoteQuery(linkQuery)
+  const variantInventoriesMap = new Map<string, VariantInventoryType[]>()
+
+  links.forEach((link) => {
+    const array: VariantInventoryType[] =
+      variantInventoriesMap.get(link.variant_id) || []
+
+    array.push(link)
+
+    variantInventoriesMap.set(link.variant_id, array)
+  })
+
+  for (const variant of variants || []) {
+    if (!variant.manage_inventory) {
+      continue
+    }
+
+    const links = variantInventoriesMap.get(variant.id) || []
+    const inventoryQuantities: number[] = []
+
+    for (const link of links) {
+      const requiredQuantity = link.required_quantity
+      const availableQuantity = (link.inventory.location_levels || []).reduce(
+        (sum, level) => sum + level.available_quantity || 0,
+        0
+      )
+
+      // This will give us the maximum deliverable quantities for each inventory item
+      const maxInventoryQuantity = Math.floor(
+        availableQuantity / requiredQuantity
+      )
+
+      inventoryQuantities.push(maxInventoryQuantity)
+    }
+
+    // Since each of these inventory items need to be available to perform an order,
+    // we pick the smallest of the deliverable quantities as the total inventory quantity.
+    variant.inventory_quantity = inventoryQuantities.length
+      ? Math.min(...inventoryQuantities)
+      : 0
+  }
+}
+
+export const maybeApplyStockLocationId = async (req: MedusaRequest, ctx) => {
+  const withInventoryQuantity = req.remoteQueryConfig.fields.some((field) =>
+    field.includes("variants.inventory_quantity")
+  )
+
+  if (!withInventoryQuantity) {
+    return
+  }
+
+  const salesChannelId = req.filterableFields.sales_channel_id || []
+
+  const entities = await refetchEntities(
+    "sales_channel_location",
+    { sales_channel_id: salesChannelId },
+    req.scope,
+    ["stock_location_id"]
+  )
+
+  return entities.map((entity) => entity.stock_location_id)
+}

packages/medusa/src/api/store/products/middlewares.ts

@@ -6,7 +6,9 @@ import {
   filterByValidSalesChannels,
   setPricingContext,
 } from "../../utils/middlewares"
+import { setContext } from "../../utils/middlewares/common/set-context"
 import { validateAndTransformQuery } from "../../utils/validate-query"
+import { maybeApplyStockLocationId } from "./helpers"
 import * as QueryConfig from "./query-config"
 import {
   StoreGetProductsParams,
@@ -23,6 +25,9 @@ export const storeProductRoutesMiddlewares: MiddlewareRoute[] = [
         QueryConfig.listProductQueryConfig
       ),
       filterByValidSalesChannels(),
+      setContext({
+        stock_location_id: maybeApplyStockLocationId,
+      }),
       maybeApplyLinkFilter({
         entryPoint: "product_sales_channel",
         resourceId: "product_id",
@@ -53,6 +58,9 @@ export const storeProductRoutesMiddlewares: MiddlewareRoute[] = [
         QueryConfig.retrieveProductQueryConfig
       ),
       filterByValidSalesChannels(),
+      setContext({
+        stock_location_id: maybeApplyStockLocationId,
+      }),
       maybeApplyLinkFilter({
         entryPoint: "product_sales_channel",
         resourceId: "product_id",

packages/medusa/src/api/store/products/route.ts

@@ -4,6 +4,7 @@ import {
   remoteQueryObjectFromString,
 } from "@medusajs/utils"
 import { MedusaRequest, MedusaResponse } from "../../../types/routing"
+import { wrapVariantsWithInventoryQuantity } from "./helpers"
 import { StoreGetProductsParamsType } from "./validators"
 
 export const GET = async (
@@ -12,6 +13,15 @@ export const GET = async (
 ) => {
   const remoteQuery = req.scope.resolve(ContainerRegistrationKeys.REMOTE_QUERY)
   const context: object = {}
+  const withInventoryQuantity = req.remoteQueryConfig.fields.some((field) =>
+    field.includes("variants.inventory_quantity")
+  )
+
+  if (withInventoryQuantity) {
+    req.remoteQueryConfig.fields = req.remoteQueryConfig.fields.filter(
+      (field) => !field.includes("variants.inventory_quantity")
+    )
+  }
 
   if (isPresent(req.pricingContext)) {
     context["variants.calculated_price"] = {
@@ -31,6 +41,13 @@ export const GET = async (
 
   const { rows: products, metadata } = await remoteQuery(queryObject)
 
+  if (withInventoryQuantity) {
+    await wrapVariantsWithInventoryQuantity(
+      req,
+      products.map((product) => product.variants).flat(1)
+    )
+  }
+
   res.json({
     products,
     count: metadata.count,

packages/medusa/src/api/utils/middlewares/common/set-context.ts

@@ -0,0 +1,22 @@
+import { NextFunction } from "express"
+import { MedusaRequest } from "../../../../types/routing"
+
+export function setContext(context: Record<string, any>) {
+  return async (req: MedusaRequest, _, next: NextFunction) => {
+    const ctx: Record<string, any> = { ...(req.context || {}) }
+
+    for (const [contextKey, contextValue] of Object.entries(context || {})) {
+      let valueToApply = contextValue
+
+      if (typeof contextValue === "function") {
+        valueToApply = await contextValue(req, ctx)
+      }
+
+      ctx[contextKey] = valueToApply
+    }
+
+    req.context = ctx
+
+    return next()
+  }
+}

packages/medusa/src/types/routing.ts

@@ -57,6 +57,10 @@ export interface MedusaRequest<Body = unknown>
    * An object that carries the context that is used to calculate prices for variants
    */
   pricingContext?: MedusaPricingContext
+  /**
+   * A generic context object that can be used across the request lifecycle
+   */
+  context?: Record<string, any>
 }
 
 export interface AuthContext {