Add inventory cache with 6h TTL and forceRefreshInventory support

Cache ecosystem inventory items in memory to reduce API calls. Both
getInventoryItems and awardBadge now use the shared cache. The client
reads forceRefreshInventory from URL search params and passes it through
to the server, which bypasses the cache when set to true.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: LinaBell

client/src/pages/Home.jsx

@@ -1,4 +1,5 @@
 import { useContext, useState, useEffect } from "react";
+import { useSearchParams } from "react-router-dom";
 
 // components
 import {
@@ -22,13 +23,17 @@ import { backendAPI, loadGameState } from "@utils";
 function Home() {
   const dispatch = useContext(GlobalDispatchContext);
   const { screenManager } = useContext(GlobalStateContext);
+
+  const [searchParams] = useSearchParams();
+  const forceRefreshInventory = searchParams.get("forceRefreshInventory") === "true";
+
   const [loading, setLoading] = useState(true);
 
   useEffect(() => {
     const fetchGameState = async () => {
       try {
         setLoading(true);
-        await loadGameState(dispatch);
+        await loadGameState(dispatch, forceRefreshInventory);
       } catch (error) {
         console.error("error in loadGameState action");
       } finally {

client/src/utils/loadGameState.js

@@ -1,9 +1,9 @@
 import { backendAPI, getErrorMessage } from "@utils";
 import { LOAD_GAME_STATE, SCREEN_MANAGER, SET_ERROR } from "@context/types";
 
-export const loadGameState = async (dispatch) => {
+export const loadGameState = async (dispatch, forceRefreshInventory) => {
   try {
-    const result = await backendAPI?.post("/race/game-state");
+    const result = await backendAPI?.post("/race/game-state", { forceRefreshInventory });
     if (result?.data?.success) {
       const {
         checkpointsCompleted,

server/controllers/handleLoadGameState.js

@@ -12,6 +12,7 @@ export const handleLoadGameState = async (req, res) => {
   try {
     const credentials = getCredentials(req.query);
     const { profileId, urlSlug, sceneDropId } = credentials;
+    const forceRefresh = req.body?.forceRefreshInventory === true;
     const now = Date.now();
 
     const world = await World.create(urlSlug, { credentials });
@@ -70,7 +71,7 @@ export const handleLoadGameState = async (req, res) => {
     const { visitor, visitorProgress, visitorInventory } = await getVisitor(credentials, true);
     let { checkpoints, startTimestamp } = visitorProgress;
 
-    const { badges } = await getInventoryItems(credentials);
+    const { badges } = await getInventoryItems(credentials, { forceRefresh });
 
     return res.json({
       checkpointsCompleted: checkpoints,

server/utils/badges/awardBadge.js

@@ -1,13 +1,11 @@
-import { Ecosystem } from "../topiaInit.js";
+import { getCachedInventoryItems } from "../inventoryCache.js";
 
 export const awardBadge = async ({ credentials, visitor, visitorInventory, badgeName, redisObj, profileId }) => {
   try {
     if (visitorInventory[badgeName]) return { success: true };
 
-    const ecosystem = await Ecosystem.create({ credentials });
-    await ecosystem.fetchInventoryItems();
-
-    const inventoryItem = ecosystem.inventoryItems?.find((item) => item.name === badgeName);
+    const inventoryItems = await getCachedInventoryItems({ credentials });
+    const inventoryItem = inventoryItems?.find((item) => item.name === badgeName);
     if (!inventoryItem) throw new Error(`Inventory item ${badgeName} not found in ecosystem`);
 
     await visitor.grantInventoryItem(inventoryItem, 1);

server/utils/badges/getInventoryItems.js

@@ -1,13 +1,11 @@
-import { Ecosystem } from "../index.js";
+import { getCachedInventoryItems } from "../inventoryCache.js";
 
-export const getInventoryItems = async (credentials) => {
+export const getInventoryItems = async (credentials, { forceRefresh = false } = {}) => {
   try {
-    const ecosystem = await Ecosystem.create({ credentials });
-    await ecosystem.fetchInventoryItems();
+    const items = await getCachedInventoryItems({ credentials, forceRefresh });
 
     const badges = {};
-
-    for (const item of ecosystem.inventoryItems) {
+    for (const item of items) {
       badges[item.name] = {
         id: item.id,
         name: item.name || "Unknown",
@@ -16,18 +14,7 @@ export const getInventoryItems = async (credentials) => {
       };
     }
 
-    // Sort items by sortOrder while keeping them as objects
-    const sortedBadges = {};
-
-    Object.values(badges)
-      .sort((a, b) => (a.sortOrder || 0) - (b.sortOrder || 0))
-      .forEach((badge) => {
-        sortedBadges[badge.name] = badge;
-      });
-
-    return {
-      badges: sortedBadges,
-    };
+    return { badges };
   } catch (error) {
     return standardizeError(error);
   }

server/utils/inventoryCache.js

@@ -0,0 +1,45 @@
+import { Ecosystem } from "./topiaInit.js";
+
+// Cache duration: 6 hours in milliseconds
+const CACHE_DURATION_MS = 6 * 60 * 60 * 1000;
+
+// In-memory cache
+let inventoryCache = null;
+
+/**
+ * Get ecosystem inventory items with caching.
+ * - Returns cached data if available and not expired.
+ * - Refreshes cache if expired or missing.
+ * - Falls back to stale cache on API failure.
+ */
+export const getCachedInventoryItems = async ({ credentials, forceRefresh = false }) => {
+  try {
+    const now = Date.now();
+    const isCacheValid = inventoryCache !== null && !forceRefresh && now - inventoryCache.timestamp < CACHE_DURATION_MS;
+
+    if (isCacheValid) {
+      return inventoryCache.items;
+    }
+
+    console.log("Fetching fresh inventory items from ecosystem");
+    const ecosystem = await Ecosystem.create({ credentials });
+    await ecosystem.fetchInventoryItems();
+
+    inventoryCache = {
+      items: [...ecosystem.inventoryItems].sort((a, b) => (a.metadata?.sortOrder ?? 0) - (b.metadata?.sortOrder ?? 0)),
+      timestamp: now,
+    };
+
+    return inventoryCache.items;
+  } catch (error) {
+    if (inventoryCache !== null) {
+      console.warn("Failed to fetch fresh inventory, using stale cache", error);
+      return inventoryCache.items;
+    }
+    throw error;
+  }
+};
+
+export const clearInventoryCache = () => {
+  inventoryCache = null;
+};