npm-pkg-hook 1.12.4 → 1.12.8

package/src/hooks/useSales/helpers/apply-discount-to-cart.utils.ts

@@ -0,0 +1,292 @@
+export enum TypeDiscount {
+  PERCENT = 'PERCENT',
+  AMOUNT = 'AMOUNT'
+}
+interface DiscountPayload {
+  type: TypeDiscount
+  value: number
+}
+
+/**
+ * Apply a discount to the reducer state in a mathematically-exact way.
+ *
+ * - Supports two discount types: "PERCENT" (0-100) and "AMOUNT" (fixed currency amount).
+ * - Works in integer cents to avoid floating point errors, distributes rounding
+ *   remainders using the Largest Remainder Method so allocations sum exactly.
+ * - BEFORE applying a new discount, restores original prices if they were previously saved
+ *   (originalProPrice and originalNewExtraPrice). This prevents stacking discounts.
+ * - Applies discount first to `ProPrice` (base) and, if needed, to `dataExtra[].newExtraPrice`
+ *   proportionally, never producing negative prices.
+ * - Returns a new state (immutable) and sets metadata: discountType, discountPercent,
+ *   discountAmount, discountBreakdown and preserves original prices in `originalProPrice`
+ *   and `dataExtra[].originalNewExtraPrice`.
+ *
+ * NOTE: Uses optional `sendNotification` to report errors/success.
+ *
+ * @param {any} state - current reducer state
+ * @param {{ type: string, value: number }} payload - { type: 'PERCENT'|'AMOUNT', value: number }
+ * @param {(notification: {title:string,backgroundColor:'success'|'error'|'warning'|'info',description:string}) => void} sendNotification
+ * @returns {any} new state with discounts applied (idempotent w.r.t repeated calls)
+ */
+export const applyDiscountToCart = (
+  state: any,
+  payload: DiscountPayload,
+  sendNotification?: (notification: {
+    title: string
+    backgroundColor: 'success' | 'error' | 'warning' | 'info'
+    description: string
+  }) => void
+) => {
+  const discountType = (payload?.type ?? TypeDiscount.PERCENT).toString().toUpperCase()
+  const rawValue = Number(payload?.value)
+
+  // Basic validations
+  if (!Array.isArray(state?.PRODUCT) || state.PRODUCT.length === 0) {
+    sendNotification?.({
+      title: 'Warning',
+      backgroundColor: 'warning',
+      description: 'No items in cart to apply discount.'
+    })
+    return {
+      ...state,
+      discountType,
+      discountPercent: 0,
+      discountAmount: 0,
+      discountBreakdown: []
+    }
+  }
+
+  if (Number.isNaN(rawValue) || rawValue < 0) {
+    sendNotification?.({
+      title: 'Error',
+      backgroundColor: 'error',
+      description: 'Invalid discount value.'
+    })
+    return state
+  }
+
+  if (discountType !== TypeDiscount.PERCENT && discountType !== TypeDiscount.AMOUNT) {
+    sendNotification?.({
+      title: 'Error',
+      backgroundColor: 'error',
+      description: 'Invalid discount type.'
+    })
+    return state
+  }
+
+  if (discountType === TypeDiscount.PERCENT && (rawValue < 0 || rawValue > 100)) {
+    sendNotification?.({
+      title: 'Error',
+      backgroundColor: 'warning',
+      description: 'Percentage must be between 0 and 100.'
+    })
+    return state
+  }
+
+  // Helpers - work in cents to preserve exactness
+  const toCents = (n: number) => {return Math.round((Number(n) || 0) * 100)}
+  const fromCents = (c: number) => {return c / 100}
+
+  // --- Normalize / Restore originals to avoid stacking discounts ---
+  // For each product, use saved original prices if present; otherwise use current as "original"
+  const normalizedItems = state.PRODUCT.map((item: any) => {
+    // Determine original base price (prefer originalProPrice if present)
+    const origBaseRaw =
+      item.originalProPrice !== undefined && item.originalProPrice !== null
+        ? Number(item.originalProPrice)
+        : Number(item.ProPrice || 0)
+
+    const baseCents = toCents(origBaseRaw)
+
+    // Normalize extras: preserve originalNewExtraPrice if exists, else take current newExtraPrice
+    const extrasRaw = Array.isArray(item.dataExtra) ? item.dataExtra : []
+    const extrasNormalized = extrasRaw.map((ex: any) => {
+      const origExRaw =
+        ex.originalNewExtraPrice !== undefined && ex.originalNewExtraPrice !== null
+          ? Number(ex.originalNewExtraPrice)
+          : Number(ex.newExtraPrice || 0)
+      return {
+        originalExtraObject: ex,
+        originalNewExtraPriceRaw: origExRaw,
+        originalNewExtraPriceCents: toCents(origExRaw)
+      }
+    })
+
+    const extrasCentsList = extrasNormalized.map((e: any) => {return e.originalNewExtraPriceCents})
+    const extrasTotalCents = extrasCentsList.reduce((s: number, v: number) => {return s + v}, 0)
+    const itemTotalCents = baseCents + extrasTotalCents
+
+    return {
+      originalItem: item,
+      baseCents,
+      extrasNormalized,
+      extrasCentsList,
+      extrasTotalCents,
+      itemTotalCents
+    }
+  })
+
+  const cartTotalCents = normalizedItems.reduce((s: number, it: any) => {return s + it.itemTotalCents}, 0)
+
+  if (cartTotalCents === 0) {
+    sendNotification?.({
+      title: 'Warning',
+      backgroundColor: 'warning',
+      description: 'Cart total is zero; nothing to discount.'
+    })
+    return {
+      ...state,
+      discountType,
+      discountPercent: 0,
+      discountAmount: 0,
+      discountBreakdown: []
+    }
+  }
+
+  // Determine requested total discount in cents
+  let totalDiscountCents = 0
+  if (discountType === TypeDiscount.PERCENT) {
+    totalDiscountCents = Math.round((cartTotalCents * rawValue) / 100)
+  } else {
+    totalDiscountCents = toCents(rawValue)
+    // Cap to cart total
+    if (totalDiscountCents > cartTotalCents) {
+      totalDiscountCents = cartTotalCents
+    }
+  }
+
+  // If no discount to apply
+  if (totalDiscountCents <= 0) {
+    sendNotification?.({
+      title: 'Notice',
+      backgroundColor: 'info',
+      description: 'No discount applied.'
+    })
+    return {
+      ...state,
+      discountType,
+      discountPercent: discountType === TypeDiscount.PERCENT ? rawValue : +((totalDiscountCents / cartTotalCents) * 100).toFixed(2),
+      discountAmount: fromCents(totalDiscountCents),
+      discountBreakdown: []
+    }
+  }
+
+  // ---- Allocation using Largest Remainder Method (exact cents) ----
+  const rawAllocs = normalizedItems.map((it: any) => {return (it.itemTotalCents * totalDiscountCents) / cartTotalCents})
+  const floorAllocs = rawAllocs.map((v: any) => {return Math.floor(v)})
+  const remainders = rawAllocs.map((v: any, i: number) => {return { idx: i, rem: v - floorAllocs[i] }})
+  const sumFloor = floorAllocs.reduce((s: number, v: number) => {return s + v}, 0)
+  let remainingCents = totalDiscountCents - sumFloor
+
+  remainders.sort((a: any, b: any) => {return b.rem - a.rem})
+  const finalAllocs = [...floorAllocs]
+  for (let i = 0; i < remainders.length && remainingCents > 0; i++) {
+    finalAllocs[remainders[i].idx] += 1
+    remainingCents -= 1
+  }
+
+  // ---- Apply allocations to restored originals (base first, then extras) ----
+  const breakdown: { pId: string | number; discountAmount: number }[] = []
+  const newProducts = normalizedItems.map((it: any, idx: number) => {
+    const allocated = finalAllocs[idx] // cents
+    let remainingToTake = allocated
+
+    // Apply on base
+    const origBaseCents = it.baseCents
+    const usedOnBase = Math.min(origBaseCents, remainingToTake)
+    const baseAfter = origBaseCents - usedOnBase
+    remainingToTake -= usedOnBase
+
+    // Apply on extras proportionally if needed
+    let newExtrasCentsList = it.extrasCentsList.slice() // copy
+    if (remainingToTake > 0 && it.extrasTotalCents > 0) {
+      const extrasTotal = it.extrasTotalCents
+      // raw per-extra allocation
+      const rawExtraAllocs = newExtrasCentsList.map((exCents: number) => {return (exCents / extrasTotal) * remainingToTake})
+      const floorExtraAllocs = rawExtraAllocs.map((v: number) => {return Math.floor(v)})
+      const usedExtraFloor = floorExtraAllocs.reduce((s: number, v: number) => {return s + v}, 0)
+      let rest = remainingToTake - usedExtraFloor
+
+      const extraRemainders = rawExtraAllocs.map((v: number, i: number) => {return { idx: i, rem: v - floorExtraAllocs[i] }})
+      extraRemainders.sort((a: any, b: any) => {return b.rem - a.rem})
+      const finalExtraAllocs = [...floorExtraAllocs]
+      for (let k = 0; k < extraRemainders.length && rest > 0; k++) {
+        finalExtraAllocs[extraRemainders[k].idx] += 1
+        rest -= 1
+      }
+
+      // apply finalExtraAllocs with cap
+      newExtrasCentsList = newExtrasCentsList.map((exCents: number, i: number) => {
+        const reduceBy = Math.min(exCents, finalExtraAllocs[i])
+        return exCents - reduceBy
+      })
+
+      remainingToTake = 0
+    }
+
+    // Build updated product object:
+    const newBaseCents = baseAfter
+    const newProPrice = fromCents(newBaseCents)
+
+    const originalExtrasObjects = it.extrasNormalized.map((e: any) => {return e.originalExtraObject || {}})
+    const newDataExtra = originalExtrasObjects.map((exObj: any, i: number) => {
+      const newExtraPrice = fromCents(newExtrasCentsList[i] || 0)
+      // preserve originalNewExtraPrice on each extra (if not already)
+      return {
+        ...exObj,
+        originalNewExtraPrice: exObj.originalNewExtraPrice !== undefined ? exObj.originalNewExtraPrice : exObj.newExtraPrice,
+        newExtraPrice
+      }
+    })
+
+    const appliedDiscountCents = allocated - remainingToTake
+    breakdown.push({ pId: it.originalItem.pId, discountAmount: fromCents(appliedDiscountCents) })
+
+    const itemTotalCentsBefore = it.itemTotalCents || 0
+    const itemDiscountPercent = itemTotalCentsBefore > 0 ? +((appliedDiscountCents / itemTotalCentsBefore) * 100).toFixed(4) : 0
+
+    return {
+      ...it.originalItem,
+      // save originalProPrice if not present (so future calls can restore)
+      originalProPrice:
+        it.originalItem.originalProPrice !== undefined && it.originalItem.originalProPrice !== null
+          ? it.originalItem.originalProPrice
+          : fromCents(it.baseCents),
+      ProPrice: newProPrice,
+      dataExtra: newDataExtra,
+      // per-item metadata
+      discountAmount: fromCents(appliedDiscountCents),
+      discountPercent: itemDiscountPercent
+    }
+  })
+
+  // Final safety check & tiny correction if needed
+  const allocatedSumCents = breakdown.reduce((s, b) => {return s + toCents(Number(b.discountAmount) || 0)}, 0)
+  if (allocatedSumCents !== totalDiscountCents) {
+    const diff = totalDiscountCents - allocatedSumCents
+    if (newProducts.length > 0 && diff !== 0) {
+      const first = newProducts[0]
+      first.discountAmount = Number(first.discountAmount || 0) + fromCents(diff)
+      const adjustOnBase = Math.min(toCents(first.ProPrice), diff)
+      first.ProPrice = fromCents(Math.max(0, toCents(first.ProPrice) - adjustOnBase))
+      breakdown[0].discountAmount = Number(breakdown[0].discountAmount || 0) + fromCents(diff)
+    }
+  }
+
+  const overallPercent = +((totalDiscountCents / cartTotalCents) * 100).toFixed(4)
+
+  sendNotification?.({
+    title: 'Discount applied',
+    backgroundColor: 'success',
+    description: `${discountType === TypeDiscount.PERCENT ? rawValue + '%' : fromCents(totalDiscountCents)} discount applied successfully.`
+  })
+
+  return {
+    ...state,
+    PRODUCT: newProducts,
+    discountType,
+    discountPercent: discountType === TypeDiscount.PERCENT ? rawValue : overallPercent,
+    discountAmount: fromCents(totalDiscountCents),
+    discountBreakdown: breakdown
+  }
+}

package/src/hooks/useSales/helpers/comment-product.utils.ts

@@ -0,0 +1,41 @@
+/**
+ * Adds or removes a comment from a product in cart.
+ * - Pure function (reducer-safe)
+ * - Supports delete mode
+ * - Avoids unnecessary re-renders
+ *
+ * @param {Object} params
+ * @param {Object} params.state - Current reducer state
+ * @param {string | number} params.productId - Product identifier
+ * @param {string} params.comment - Comment text
+ * @param {boolean} params.deleteValue - If true, removes the comment
+ *
+ * @returns {Object} Updated state
+ */
+export const commentProduct = ({
+  state,
+  productId,
+  comment = '',
+  deleteValue = false
+}: {
+  state: any;
+  productId: string | number;
+  comment?: string;
+  deleteValue?: boolean;
+}) => {
+  if (!productId) return state
+
+  const PRODUCT = state.PRODUCT.map((item: any) =>
+  {return item.pId === productId
+    ? {
+      ...item,
+      comment: deleteValue ? '' : comment
+    }
+    : item}
+  )
+
+  return {
+    ...state,
+    PRODUCT
+  }
+}

package/src/hooks/useSales/helpers/constants/index.ts

@@ -0,0 +1,38 @@
+import { SalesState } from '../../types'
+import { TypeDiscount } from '../apply-discount-to-cart.utils'
+
+export enum SalesActionTypes {
+    ADD_TO_CART = 'ADD_TO_CART',
+    ADD_PRODUCT = 'ADD_PRODUCT',
+    REMOVE_PRODUCT = 'REMOVE_PRODUCT',
+    REMOVE_PRODUCT_TO_CART = 'REMOVE_PRODUCT_TO_CART',
+    ON_CHANGE = 'ON_CHANGE',
+    UPDATE_SUCCESS_QUANTITY_EDITING_PRODUCT = 'UPDATE_SUCCESS_QUANTITY_EDITING_PRODUCT',
+    CANCEL_UPDATE_QUANTITY_EDITING_PRODUCT = 'CANCEL_UPDATE_QUANTITY_EDITING_PRODUCT',
+    REMOVE_ALL_PRODUCTS = 'REMOVE_ALL_PRODUCTS',
+    TOGGLE_FREE_PRODUCT = 'TOGGLE_FREE_PRODUCT',
+    TOGGLE_EDITING_PRODUCT = 'TOGGLE_EDITING_PRODUCT',
+    INCREMENT = 'INCREMENT',
+    DECREMENT = 'DECREMENT',
+    PUT_COMMENT = 'PUT_COMMENT',
+    PUT_EXTRA_PRODUCTS_AND_OPTIONAL_PRODUCT = 'PUT_EXTRA_PRODUCTS_AND_OPTIONAL_PRODUCT',
+    PRICE_RANGE = 'PRICE_RANGE',
+    SORT = 'SORT',
+    PAYMENT_METHOD = 'PAYMENT_METHOD',
+    APPLY_DISCOUNT = 'APPLY_DISCOUNT'
+}
+export const initialStateSales: SalesState = {
+  animateType: '',
+  counter: 0,
+  discountAmount: 0,
+  discountPercent: 0,
+  discountType: TypeDiscount.PERCENT,
+  itemsInCart: 0,
+  payId: '',
+  priceRange: 0,
+  PRODUCT: [],
+  sortBy: null,
+  startAnimateUp: '',
+  totalAmount: 0,
+  totalPrice: 0
+}

package/src/hooks/useSales/helpers/extras.utils.ts

@@ -0,0 +1,42 @@
+/**
+ * extrasUtils.ts
+ * Increment/decrement extras handling as pure functions returning new arrays.
+ */
+
+/**
+ * Increment extra entry
+ * @param {Array} dataExtra
+ * @param {string|number} exPid
+ * @returns {Array}
+ */
+export const incrementExtra = (dataExtra = [], exPid: string | number) => {
+  if (!Array.isArray(dataExtra)) return []
+  return dataExtra.map((producto: any) => {
+    if (producto.exPid === exPid) {
+      const initialQuantity = producto.quantity ? producto.quantity : 0
+      const newQuantity = initialQuantity + 1
+      const newExtraPrice = (producto.extraPrice || 0) * newQuantity
+      return { ...producto, quantity: newQuantity, newExtraPrice }
+    }
+    return producto
+  })
+}
+
+/**
+ * Decrement extra entry
+ * @param {Array} dataExtra
+ * @param {string|number} exPid
+ * @returns {Array}
+ */
+export const decrementExtra = (dataExtra = [], exPid: string | number) => {
+  if (!Array.isArray(dataExtra)) return []
+  return dataExtra.map((producto: any) => {
+    if (producto.exPid === exPid) {
+      const { quantity = 0, extraPrice = 0 } = producto
+      const newQuantity = Math.max(quantity - 1, 0)
+      const newExtraPrice = newQuantity === 0 ? extraPrice : extraPrice * newQuantity
+      return { ...producto, quantity: newQuantity, newExtraPrice }
+    }
+    return producto
+  })
+}

package/src/hooks/useSales/helpers/filterProductsByCarProId.utils.ts

@@ -0,0 +1,17 @@
+/**
+ * Filter products by carProId.
+ * @param {Array} products - Array of products to filter.
+ * @param {Array} carProIds - Array of carProId to filter by.
+ * @returns {Array} - Filtered array of products or all products if no matches found.
+ */
+export function filterProductsByCarProId(products: any[], carProIds: (string | number)[]) {
+  if (!Array.isArray(products)) {
+    return []
+  }
+
+  if (!Array.isArray(carProIds) || carProIds.length === 0) {
+    return products
+  }
+
+  return products.filter(product => {return carProIds.includes(product.carProId)})
+}

package/src/hooks/useSales/helpers/increment-product-quantity.utils.ts

@@ -0,0 +1,76 @@
+/**
+ * Increments product quantity in cart safely.
+ * - Validates stock
+ * - Respects free mode
+ * - Avoids unnecessary mutations
+ *
+ * @param {Object} params
+ * @param {Object} params.state - Current reducer state
+ * @param {string | number} params.productId - Product identifier
+ * @param {Object[]} params.productsFood - Source products list
+ * @param {Function} params.sendNotification - Notification handler
+ *
+ * @returns {Object} Updated state
+ */
+export const incrementProductQuantity = ({
+  state,
+  productId,
+  productsFood = [],
+  sendNotification = () => {}
+}: {
+  state: any;
+  productId: string | number;
+  productsFood: any[];
+  sendNotification?: Function;
+}) => {
+  const sourceProduct = productsFood.find(
+    (product) => {return product.pId === productId}
+  )
+
+  if (!sourceProduct) return state
+
+  const PRODUCT = state.PRODUCT.map((item: any) => {
+    if (item.pId !== productId) return item
+
+    const {
+      stock = 0,
+      manageStock,
+      ProPrice: unitPrice = 0
+    } = sourceProduct
+
+    const isFree = Boolean(item.free)
+    const newQuantity = item.ProQuantity + 1
+
+    // Stock = 0
+    if (stock === 0) {
+      sendNotification({
+        title: 'Sin stock',
+        backgroundColor: 'warning',
+        description: `El producto ${item.pName} está agotado y no puede ser añadido al carrito.`
+      })
+      return item
+    }
+
+    // Stock exceeded
+    if (manageStock && newQuantity > stock) {
+      sendNotification({
+        title: 'Stock insuficiente',
+        backgroundColor: 'warning',
+        description: `No puedes agregar más unidades de ${item.pName}, stock disponible: ${stock}`
+      })
+      return item
+    }
+
+    return {
+      ...item,
+      ProQuantity: newQuantity,
+      ProPrice: isFree ? 0 : newQuantity * unitPrice
+    }
+  })
+
+  return {
+    ...state,
+    counter: state.counter + 1,
+    PRODUCT
+  }
+}

package/src/hooks/useSales/helpers/index.ts

@@ -0,0 +1,3 @@
+export * from './extras.utils'
+export * from './remove-product.utils'
+export * from './filterProductsByCarProId.utils'

package/src/hooks/useSales/helpers/initializer.utils.ts

@@ -0,0 +1,22 @@
+import { Cookies } from '../../../cookies'
+import { SalesState } from '../types'
+
+import { initialStateSales } from './constants'
+
+/**
+ * Initializes sales state from cookies or fallback state
+ * @param initialValue
+ */
+export const initializer = (
+  initialValue: SalesState = initialStateSales
+): SalesState => {
+  try {
+    const raw = Cookies.get(process.env.NEXT_LOCAL_SALES_STORE)
+
+    if (!raw) return initialValue
+
+    return JSON.parse(raw) as SalesState
+  } catch {
+    return initialValue
+  }
+}

package/src/hooks/useSales/helpers/isStockInsufficient.ts

@@ -0,0 +1,3 @@
+export const isStockInsufficient = (currentQuantity: number, stock: number) => {
+  return currentQuantity >= stock
+}

package/src/hooks/useSales/helpers/remove-product.utils.test.ts

@@ -0,0 +1,49 @@
+import { handleRemoveProduct } from './remove-product.utils'
+
+describe('handleRemoveProduct', () => {
+  test('decrements product quantity and updates price when ProQuantity > 1', () => {
+    const state = {
+      counter: 5,
+      totalAmount: 100,
+      PRODUCT: [
+        { pId: 'p1', ProQuantity: 3, ProPrice: 30 },
+        { pId: 'p2', ProQuantity: 1, ProPrice: 20 }
+      ]
+    }
+    const productsFood = [{ pId: 'p1', ProPrice: 10 }]
+    const action = { payload: { pId: 'p1', ProQuantity: 3, ProPrice: 10 } }
+
+    const result = handleRemoveProduct(state as any, action as any, productsFood as any)
+
+    expect(result.counter).toBe(4)
+    expect(result.totalAmount).toBe(90)
+    expect(result.PRODUCT).toHaveLength(2)
+
+    const updated = result.PRODUCT.find((p: any) => {return p.pId === 'p1'})
+    expect(updated).toEqual({ pId: 'p1', ProQuantity: 2, ProPrice: 20 })
+
+    const unchanged = result.PRODUCT.find((p: any) => {return p.pId === 'p2'})
+    expect(unchanged).toEqual({ pId: 'p2', ProQuantity: 1, ProPrice: 20 })
+  })
+
+  test('removes product from PRODUCT when ProQuantity === 1', () => {
+    const state = {
+      counter: 2,
+      totalAmount: 30,
+      PRODUCT: [
+        { pId: 'p1', ProQuantity: 1, ProPrice: 15 },
+        { pId: 'p2', ProQuantity: 1, ProPrice: 15 }
+      ]
+    }
+    const productsFood = [{ pId: 'p1', ProPrice: 15 }]
+    const action = { payload: { pId: 'p1', ProQuantity: 1, ProPrice: 15 } }
+
+    const result = handleRemoveProduct(state as any, action as any, productsFood as any)
+
+    expect(result.counter).toBe(1)
+    expect(result.totalAmount).toBe(15)
+    expect(result.PRODUCT).toHaveLength(1)
+    expect(result.PRODUCT.find((p: any) => {return p.pId === 'p1'})).toBeUndefined()
+    expect(result.PRODUCT[0]).toEqual({ pId: 'p2', ProQuantity: 1, ProPrice: 15 })
+  })
+})

package/src/hooks/useSales/helpers/remove-product.utils.ts

@@ -0,0 +1,34 @@
+/**
+ *
+ * @param state
+ * @param action
+ * @param productsFood
+ */
+export function handleRemoveProduct(state: any, action: any, productsFood: any) {
+  const productExist = state?.PRODUCT.find((items: any) => {
+    return items.pId === action.payload.pId
+  })
+  const OurProduct = productsFood.find((items: any) => {
+    return items.pId === action.payload.pId
+  })
+  return {
+    ...state,
+    counter: state.counter - 1,
+    totalAmount: state.totalAmount - action.payload.ProPrice,
+    PRODUCT:
+      action.payload.ProQuantity > 1
+        ? state.PRODUCT.map((items: any) => {
+          return items.pId === action.payload.pId
+            ? {
+              ...items,
+              pId: action.payload.pId,
+              ProQuantity: items.ProQuantity - 1,
+              ProPrice: productExist.ProPrice - OurProduct?.ProPrice
+            }
+            : items
+        })
+        : state.PRODUCT.filter((items: any) => {
+          return items.pId !== action.payload.pId
+        })
+  }
+}

package/src/hooks/useSales/helpers/resolveProduct.ts

@@ -0,0 +1,29 @@
+/**
+ * resolveProduct - resolve product from local memory or fetch from API
+ * @param {{ pId: string, productsFood?: any[], fetchProduct: (params:{pId:string}) => Promise<any> }} args
+ * @returns {Promise<any|null>} resolved product or null if not found
+ */
+export const resolveProduct = async ({
+  pId,
+  productsFood = [],
+  fetchProduct
+}: {
+  pId: string
+  productsFood?: any[]
+  fetchProduct: (params: { pId: string }) => Promise<any>
+}): Promise<any | null> => {
+  if (!pId) return null
+
+  // fast memory lookup
+  const mem = productsFood.find((it: any) => {return it?.pId === pId})
+  if (mem) return mem
+
+  // fetch from API and normalize
+  try {
+    const res = await fetchProduct({ pId })
+    return res?.data?.productFoodsOne ?? null
+  } catch (err) {
+    // bubble up null — caller will notify
+    return null
+  }
+}