medusa-storefront-data 2.5.7 → 2.5.9

package/dist/src/server/page-input.js

@@ -5,6 +5,84 @@ import { normalizeHomepageConfig } from "./normalize-homepage-config";
 function asObject(v) {
     return v && typeof v === "object" && !Array.isArray(v) ? v : null;
 }
+function asArray(v) {
+    return Array.isArray(v) ? v : [];
+}
+/** `hero-banners.homeBanners[].slide` from medusa-plugin-dynamic-config. */
+function heroSlideRow(row) {
+    const rowObj = asObject(row);
+    if (!rowObj)
+        return null;
+    const slide = asObject(rowObj.slide) ?? rowObj;
+    const image = slide.image;
+    if (image == null || image === "")
+        return null;
+    return {
+        image,
+        title: slide.title,
+        subtitle: slide.subtitle,
+        description: slide.description,
+        buttonText: slide.buttonText ?? slide.buttonName,
+        buttonLink: slide.buttonLink,
+    };
+}
+function simplifiedConfigFromHeroBanners(response) {
+    if (!response || typeof response !== "object")
+        return null;
+    const root = asObject(response["hero-banners"]);
+    if (!root)
+        return null;
+    const desktop = asArray(root.homeBanners)
+        .map(heroSlideRow)
+        .filter((row) => row !== null);
+    const mobile = asArray(root.appBanners)
+        .map(heroSlideRow)
+        .filter((row) => row !== null);
+    if (!desktop.length && !mobile.length)
+        return null;
+    const banners = {};
+    if (desktop.length)
+        banners.desktop = desktop;
+    if (mobile.length)
+        banners.mobile = mobile;
+    return { site: { banners } };
+}
+function mergeHomepageConfigLayers(...layers) {
+    const defined = layers.filter(Boolean);
+    if (!defined.length)
+        return null;
+    if (defined.length === 1)
+        return defined[0];
+    const merged = {};
+    for (const layer of defined) {
+        const site = asObject(layer.site) ?? {};
+        const mergedSite = asObject(merged.site) ?? {};
+        const layerBanners = asObject(site.banners);
+        if (layerBanners) {
+            mergedSite.banners = {
+                ...(asObject(mergedSite.banners) ?? {}),
+                ...layerBanners,
+            };
+        }
+        for (const [key, value] of Object.entries(site)) {
+            if (key !== "banners" && value !== undefined)
+                mergedSite[key] = value;
+        }
+        if (Object.keys(mergedSite).length)
+            merged.site = mergedSite;
+        const sections = asObject(layer.sections);
+        if (sections) {
+            merged.sections = { ...(asObject(merged.sections) ?? {}), ...sections };
+        }
+        for (const [key, value] of Object.entries(layer)) {
+            if (key === "site" || key === "sections")
+                continue;
+            if (value !== undefined)
+                merged[key] = value;
+        }
+    }
+    return merged;
+}
 export const DEFAULT_PAGE_INPUT = defaultPageInputJson;
 /**
  * Merge CMS / main-project overrides onto package JSON defaults.
@@ -76,14 +154,19 @@ export function simplifiedHomepageConfigFromDynamicResponse(response) {
         ? simplified
         : null;
 }
+/** CMS-only homepage config (no package JSON defaults). */
+export function homepageConfigFromDynamicResponseNormalized(response) {
+    const legacy = response?.["homepage-config"] ?? null;
+    const fromSplit = simplifiedHomepageConfigFromDynamicResponse(response);
+    const fromHeroBanners = simplifiedConfigFromHeroBanners(response);
+    const raw = mergeHomepageConfigLayers(fromSplit, legacy, fromHeroBanners);
+    return normalizeHomepageConfig(raw);
+}
 /**
  * Build `homepage-config` from Medusa `GET /store/dynamic-config` (main project only).
- * Supports legacy `homepage-config` or split plugin keys.
+ * Supports legacy `homepage-config`, split plugin keys, and `hero-banners`.
  */
 export function homepageConfigFromDynamicResponse(response) {
-    const legacy = response?.["homepage-config"] ?? null;
-    const fromSplit = simplifiedHomepageConfigFromDynamicResponse(response);
-    const raw = fromSplit ?? legacy;
-    const normalized = normalizeHomepageConfig(raw);
+    const normalized = homepageConfigFromDynamicResponseNormalized(response);
     return mergePageInputWithDefaults(normalized);
 }

package/dist/src/server/storefront-cms.d.ts

@@ -0,0 +1,11 @@
+import "server-only";
+import type { StorefrontPageInput } from "./page-input";
+type Maybe<T> = T | null | undefined;
+/** Cached CMS merge for the storefront (fetch once per request). */
+export declare const loadStorefrontPageInput: () => Promise<StorefrontPageInput>;
+export declare function resolveStorefrontPageInput(pageInput?: Maybe<StorefrontPageInput>): Promise<StorefrontPageInput>;
+export declare function loadContactInfoFromStorefrontInput(pageInput?: Maybe<StorefrontPageInput>): Promise<import("./dynamic-config").ContactInfo | null>;
+export declare function loadContactEmailFromStorefrontInput(pageInput?: Maybe<StorefrontPageInput>): Promise<string>;
+export declare function loadHelpFaqFromStorefrontInput(pageInput?: Maybe<StorefrontPageInput>): Promise<import("./dynamic-config").HelpFaqConfig>;
+export {};
+//# sourceMappingURL=storefront-cms.d.ts.map

package/dist/src/server/storefront-cms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storefront-cms.d.ts","sourceRoot":"","sources":["../../../src/server/storefront-cms.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,CAAA;AAGpB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAOvD,KAAK,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,SAAS,CAAA;AAEpC,oEAAoE;AACpE,eAAO,MAAM,uBAAuB,QACxB,OAAO,CAAC,mBAAmB,CAItC,CAAA;AAED,wBAAsB,0BAA0B,CAC9C,SAAS,CAAC,EAAE,KAAK,CAAC,mBAAmB,CAAC,GACrC,OAAO,CAAC,mBAAmB,CAAC,CAE9B;AAED,wBAAsB,kCAAkC,CACtD,SAAS,CAAC,EAAE,KAAK,CAAC,mBAAmB,CAAC,0DAIvC;AAED,wBAAsB,mCAAmC,CACvD,SAAS,CAAC,EAAE,KAAK,CAAC,mBAAmB,CAAC,GACrC,OAAO,CAAC,MAAM,CAAC,CAGjB;AAED,wBAAsB,8BAA8B,CAClD,SAAS,CAAC,EAAE,KAAK,CAAC,mBAAmB,CAAC,qDAIvC"}

package/dist/src/server/storefront-cms.js

@@ -0,0 +1,24 @@
+import "server-only";
+import { cache } from "react";
+import { getContactInfoFromPageInput, getHelpFaqFromPageInput, } from "./dynamic-config";
+import { getDynamicConfig, homepageConfigFromDynamicResponse } from "./dynamic-config";
+/** Cached CMS merge for the storefront (fetch once per request). */
+export const loadStorefrontPageInput = cache(async () => {
+    const raw = await getDynamicConfig();
+    return homepageConfigFromDynamicResponse(raw);
+});
+export async function resolveStorefrontPageInput(pageInput) {
+    return (pageInput ?? (await loadStorefrontPageInput()));
+}
+export async function loadContactInfoFromStorefrontInput(pageInput) {
+    const resolved = await resolveStorefrontPageInput(pageInput);
+    return getContactInfoFromPageInput(resolved);
+}
+export async function loadContactEmailFromStorefrontInput(pageInput) {
+    const info = await loadContactInfoFromStorefrontInput(pageInput);
+    return info?.email ?? "";
+}
+export async function loadHelpFaqFromStorefrontInput(pageInput) {
+    const resolved = await resolveStorefrontPageInput(pageInput);
+    return getHelpFaqFromPageInput(resolved);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "medusa-storefront-data",
-  "version": "2.5.7",
+  "version": "2.5.9",
   "type": "module",
   "description": "Medusa storefront server data layer extracted from Next.js storefront",
   "license": "MIT",
@@ -17,16 +17,17 @@
   ],
   "scripts": {
     "build": "tsc",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "test": "npm run build"
   },
   "peerDependencies": {
-    "next": ">=14",
-    "react": ">=18",
     "@medusajs/js-sdk": ">=2",
     "@medusajs/types": ">=2",
     "medusa-reviews-logic": "*",
+    "medusa-services": "^1.0.0",
     "medusa-wishlist-logic": "*",
-    "medusa-services": "^1.0.0"
+    "next": ">=14",
+    "react": ">=18"
   },
   "peerDependenciesMeta": {
     "medusa-reviews-logic": {
@@ -38,13 +39,17 @@
     "server-only": "^0.0.1"
   },
   "devDependencies": {
-    "typescript": "^5.6.0",
-    "@types/react": "^18.3.0",
-    "next": "^15.0.0",
     "@medusajs/js-sdk": "^2.0.0",
     "@medusajs/types": "^2.0.0",
     "@types/node": "^22.0.0",
-    "medusa-services": "workspace:*"
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "medusa-services": "^1.2.1",
+    "medusa-ui-home-config": "^1.1.3",
+    "next": "^15.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.6.0"
   },
   "exports": {
     "./package.json": "./package.json",
@@ -53,6 +58,16 @@
       "import": "./src/server/index.ts",
       "default": "./src/server/index.ts"
     },
+    "./help/sections/helpFaq": {
+      "types": "./dist/server/help-sections/help-faq.d.ts",
+      "import": "./src/server/help-sections/help-faq.ts",
+      "default": "./src/server/help-sections/help-faq.ts"
+    },
+    "./storefront-cms": {
+      "types": "./src/server/storefront-cms.ts",
+      "import": "./src/server/storefront-cms.ts",
+      "default": "./src/server/storefront-cms.ts"
+    },
     "./home/sections/promoAnnouncements": {
       "types": "./dist/server/home-sections/promo-announcements.d.ts",
       "import": "./src/server/home-sections/promo-announcements.ts",
@@ -128,6 +143,11 @@
       "import": "./src/server/home-sections/testimonials.ts",
       "default": "./src/server/home-sections/testimonials.ts"
     },
+    "./home/sections/customerStories": {
+      "types": "./dist/server/home-sections/customer-stories.d.ts",
+      "import": "./src/server/home-sections/customer-stories.ts",
+      "default": "./src/server/home-sections/customer-stories.ts"
+    },
     "./home/sections/brandPillars": {
       "types": "./dist/server/home-sections/brand-pillars.d.ts",
       "import": "./src/server/home-sections/brand-pillars.ts",
@@ -167,16 +187,6 @@
       "types": "./dist/server/home-sections/blog-posts.d.ts",
       "import": "./src/server/home-sections/blog-posts.ts",
       "default": "./src/server/home-sections/blog-posts.ts"
-    },
-    "./help/sections/helpFaq": {
-      "types": "./dist/server/help-sections/help-faq.d.ts",
-      "import": "./src/server/help-sections/help-faq.ts",
-      "default": "./src/server/help-sections/help-faq.ts"
-    },
-    "./storefront-cms": {
-      "types": "./src/server/storefront-cms.ts",
-      "import": "./src/server/storefront-cms.ts",
-      "default": "./src/server/storefront-cms.ts"
     }
   },
   "main": "./dist/server/index.js",

package/src/server/dynamic-config.ts

@@ -9,7 +9,10 @@ import {
 } from "./homepage-section-defaults"
 import type { DynamicConfigResponse, HomepageConfig } from "./homepage-config.types"
 import { mergeSectionBlock } from "./config-merge"
-import { mergePageInputWithDefaults, resolvePageInput } from "./page-input"
+import {
+  mergePageInputWithDefaults,
+  resolvePageInput,
+} from "./page-input"
 
 export {
   DEFAULT_PAGE_INPUT,
@@ -20,7 +23,6 @@ export {
   type StorefrontPageInput,
 } from "./page-input"
 
-
 export const getDynamicConfig = cache(async (): Promise<DynamicConfigResponse | null> => {
   try {
     const publishableKey = process.env.NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY
@@ -80,6 +82,7 @@ export function getLogoFromPageInput(
 
 
 
+/** Normalized hero slide used by storefront UI (`getHomeBannersFromPageInput`). */
 export type HomepageBanner = {
   image?: string
   title?: string
@@ -131,8 +134,6 @@ export function getAppBannersFromPageInput(
   return null
 }
 
-
-
 // Legacy function for backward compatibility
 
 export function getWebsiteDescriptionFromPageInput(
@@ -504,6 +505,142 @@ export function getTestimonialsFromPageInput(
   return { title, subtitle, testimonials }
 }
 
+export type CustomerStoryItem = {
+  id: string
+  image: string
+  text: string
+  name: string
+  rating?: number
+  location?: string
+}
+
+function parseCustomerStoryRow(
+  item: unknown,
+  index: number
+): CustomerStoryItem | null {
+  if (!item || typeof item !== "object") return null
+  const row =
+    (item as Record<string, unknown>).story ??
+    (item as Record<string, unknown>).review ??
+    item
+  const r = row as Record<string, unknown>
+  const text = String(
+    r.text ?? r["review-description"] ?? r.description ?? r.quote ?? ""
+  ).trim()
+  const name = String(
+    r.name ??
+      r["review-user-name"] ??
+      r["user-name"] ??
+      r.user_name ??
+      r.author ??
+      ""
+  ).trim()
+  const image = String(
+    r.image ??
+      r["review-profile-image"] ??
+      r["profile-image"] ??
+      r.profile_image ??
+      ""
+  ).trim()
+  /** Quote + name required; image optional (admin Ratings often has no photo). */
+  if (!text || !name) return null
+  const ratingRaw = r.rating ?? r["review-rating"]
+  const rating =
+    ratingRaw != null && ratingRaw !== ""
+      ? parseFloat(String(ratingRaw))
+      : undefined
+  const location = String(r.location ?? "").trim()
+  return {
+    id: String(r.id ?? `${name.toLowerCase().replace(/[^a-z0-9]+/g, "-")}-${index + 1}`),
+    image: image || "/Logo.png",
+    text,
+    name,
+    rating: Number.isFinite(rating) ? Math.max(0, Math.min(5, rating!)) : undefined,
+    location: location || undefined,
+  }
+}
+
+function parseCustomerStoriesFromBlock(
+  block: Record<string, unknown>
+): CustomerStoryItem[] {
+  const raw =
+    block.items ??
+    block.stories ??
+    block.reviews ??
+    block["customer-stories"] ??
+    []
+  if (!Array.isArray(raw)) return []
+  return raw
+    .map((item, index) => parseCustomerStoryRow(item, index))
+    .filter((row): row is CustomerStoryItem => row !== null)
+}
+
+function parseCustomerStoriesFromRatings(ratings: unknown): CustomerStoryItem[] {
+  if (!Array.isArray(ratings)) return []
+  return ratings
+    .map((item, index) => parseCustomerStoryRow(item, index))
+    .filter((row): row is CustomerStoryItem => row !== null)
+}
+
+function getHomepageRatingsArray(
+  pageInput?: HomepageConfig | null
+): unknown[] {
+  const resolved = resolvePageInput(pageInput)
+  const fromResolved = resolved["ratings"]
+  if (Array.isArray(fromResolved) && fromResolved.length > 0) {
+    return fromResolved
+  }
+  const fromOverride = pageInput?.["ratings"]
+  if (Array.isArray(fromOverride) && fromOverride.length > 0) {
+    return fromOverride
+  }
+  return []
+}
+
+export function getCustomerStoriesFromPageInput(
+  pageInput?: HomepageConfig | null
+): {
+  title: string
+  eyebrow: string
+  items: CustomerStoryItem[]
+} {
+  const homepageConfig = resolvePageInput(pageInput)
+  const block = getMergedSectionBlock("customerStories", pageInput)
+  const copy = parseSectionCopy(block)
+  const ratingTitle = String(homepageConfig["rating-title"] ?? "").trim()
+  const title = copy.title ?? copy.name ?? ratingTitle
+  const eyebrow = copy.eyebrow ?? ""
+  const defaults = DEFAULT_HOMEPAGE_SECTIONS.customerStories as Record<string, unknown>
+
+  /** Admin "Ratings" (`homepage-config.ratings[].review`) — always before merged section defaults. */
+  const ratingsItems = parseCustomerStoriesFromRatings(
+    getHomepageRatingsArray(pageInput)
+  )
+
+  /** CMS `sections.customerStories` only (no package default stories mixed in). */
+  const cmsSectionBlock =
+    findSectionBlock(getHomepageSectionsRoot(pageInput), "customerStories") ?? {}
+  const sectionItems = parseCustomerStoriesFromBlock(cmsSectionBlock)
+
+  let items =
+    ratingsItems.length > 0
+      ? ratingsItems
+      : sectionItems.length > 0
+        ? sectionItems
+        : parseCustomerStoriesFromBlock(block)
+  if (items.length === 0) {
+    items = parseCustomerStoriesFromBlock(
+      defaults as Record<string, unknown>
+    )
+  }
+
+  return {
+    title: title || String(defaults.title ?? "Customer Stories"),
+    eyebrow: eyebrow || String(defaults.eyebrow ?? "WHAT PARENTS SAY"),
+    items,
+  }
+}
+
 
 export function getSocialLinksFromPageInput(
   pageInput?: HomepageConfig | null

package/src/server/hero-banner-priority.ts

@@ -0,0 +1,63 @@
+/** Simplified banner shape used by hero sections (not legacy kebab-case CMS keys). */
+export type HomepageBanner = {
+  image?: string
+  title?: string
+  subtitle?: string
+  description?: string
+  buttonName?: string
+  buttonLink?: string
+}
+
+export type ThemeHeroBannerFallbacks = {
+  home: HomepageBanner
+  app: HomepageBanner
+}
+
+export type HeroBannerSource = "dynamic-config" | "theme-copy" | "library-default"
+
+export type ResolvedHeroBanners = {
+  homeBanners: HomepageBanner[]
+  appBanners: HomepageBanner[]
+  homeSource: HeroBannerSource
+  appSource: HeroBannerSource
+}
+
+export function hasBannerData(
+  banner: HomepageBanner | null | undefined
+): boolean {
+  if (!banner) return false
+  return Boolean(
+    banner.image?.trim() ||
+    banner.title?.trim() ||
+    banner.subtitle?.trim() ||
+    banner.description?.trim() ||
+    banner.buttonName?.trim() ||
+    banner.buttonLink?.trim()
+  )
+}
+
+/**
+ * Whole-banner priority (not per-field):
+ * 1. dynamic-config  2. theme copy.ts  3. package library defaults
+ */
+export function pickHeroBannerBySource(
+  cms: HomepageBanner | null | undefined,
+  theme: HomepageBanner,
+  library: HomepageBanner
+): { banner: HomepageBanner; source: HeroBannerSource } {
+  if (cms && hasBannerData(cms)) {
+    return { banner: cms, source: "dynamic-config" }
+  }
+  if (hasBannerData(theme)) {
+    return { banner: theme, source: "theme-copy" }
+  }
+  return { banner: library, source: "library-default" }
+}
+
+export function resolveHeroBannerWithPriority(
+  cms: HomepageBanner | null | undefined,
+  theme: HomepageBanner,
+  library: HomepageBanner
+): HomepageBanner {
+  return pickHeroBannerBySource(cms, theme, library).banner
+}

package/src/server/home-sections/customer-stories.ts

@@ -0,0 +1,23 @@
+import "server-only"
+
+import {
+  getCustomerStoriesFromPageInput,
+  getHomeSectionsCopyFromPageInput,
+} from "../dynamic-config"
+import type { SectionLoaderOptions } from "./shared"
+
+export type CustomerStoriesSectionData = {
+  customerStories: ReturnType<typeof getCustomerStoriesFromPageInput>
+  copy: ReturnType<typeof getHomeSectionsCopyFromPageInput>["customerStories"]
+}
+
+export async function loadCustomerStoriesSectionData(
+  _countryCode: string,
+  options?: SectionLoaderOptions
+): Promise<CustomerStoriesSectionData> {
+  const pageInput = options?.pageInput ?? null
+  return {
+    customerStories: getCustomerStoriesFromPageInput(pageInput),
+    copy: getHomeSectionsCopyFromPageInput(pageInput).customerStories,
+  }
+}

package/src/server/homepage-config.types.ts

@@ -212,6 +212,22 @@ export type HomepageVideoStoriesSection = HomepageSectionCopyFields & {
   "video-stories"?: HomepageVideoStoryEntry[]
 }
 
+export type HomepageCustomerStoryItem = {
+  id?: string
+  image?: string
+  text?: string
+  name?: string
+  rating?: number | string
+  location?: string
+  story?: HomepageCustomerStoryItem
+  review?: HomepageCustomerStoryItem
+}
+
+export type HomepageCustomerStoriesSection = HomepageSectionCopyFields & {
+  items?: HomepageCustomerStoryItem[]
+  stories?: HomepageCustomerStoryItem[]
+}
+
 /** Per-section blocks under `homepage-config.sections`. */
 export type HomepageSectionsConfig = {
   promoAnnouncements?: HomepagePromoAnnouncementsSection
@@ -228,6 +244,7 @@ export type HomepageSectionsConfig = {
   themeDresses?: HomepageSectionCopyFields
   brandMarquee?: HomepageSectionCopyFields
   aboutBrand?: HomepageAboutBrandSection
+  customerStories?: HomepageCustomerStoriesSection
   testimonials?: HomepageTestimonialsSection
   brandPillars?: HomepageBrandPillarsSection
   instagramPosts?: HomepageInstagramPostsSection
@@ -457,6 +474,7 @@ export const HOMEPAGE_SECTION_IDS = [
   "themeDresses",
   "brandMarquee",
   "aboutBrand",
+  "customerStories",
   "testimonials",
   "brandPillars",
   "instagramPosts",

package/src/server/homepage-section-defaults.ts

@@ -1,4 +1,5 @@
 import helpFaqDefaults from "./help-faq-section-defaults.json"
+import { customerStoriesSectionDefaults } from "medusa-ui-home-config/sections/customerStories"
 
 /**
  * Default `homepage-config.sections` blocks.
@@ -71,6 +72,7 @@ export const DEFAULT_HOMEPAGE_SECTIONS = {
       { label: "Products", value: "3000+" },
     ],
   },
+  customerStories: customerStoriesSectionDefaults,
   testimonials: {
     title: "What Clients Talk About Us",
     description: "The Trust We've Earned",

package/src/server/page-input.ts

@@ -14,6 +14,87 @@ function asObject(v: unknown): Loose | null {
   return v && typeof v === "object" && !Array.isArray(v) ? (v as Loose) : null
 }
 
+function asArray(v: unknown): unknown[] {
+  return Array.isArray(v) ? v : []
+}
+
+/** `hero-banners.homeBanners[].slide` from medusa-plugin-dynamic-config. */
+function heroSlideRow(row: unknown): Loose | null {
+  const rowObj = asObject(row)
+  if (!rowObj) return null
+  const slide = asObject(rowObj.slide) ?? rowObj
+  const image = slide.image
+  if (image == null || image === "") return null
+  return {
+    image,
+    title: slide.title,
+    subtitle: slide.subtitle,
+    description: slide.description,
+    buttonText: slide.buttonText ?? slide.buttonName,
+    buttonLink: slide.buttonLink,
+  }
+}
+
+function simplifiedConfigFromHeroBanners(
+  response: DynamicConfigResponse | null | undefined
+): HomepageConfig | null {
+  if (!response || typeof response !== "object") return null
+  const root = asObject((response as Loose)["hero-banners"])
+  if (!root) return null
+
+  const desktop = asArray(root.homeBanners)
+    .map(heroSlideRow)
+    .filter((row): row is Loose => row !== null)
+  const mobile = asArray(root.appBanners)
+    .map(heroSlideRow)
+    .filter((row): row is Loose => row !== null)
+
+  if (!desktop.length && !mobile.length) return null
+
+  const banners: Loose = {}
+  if (desktop.length) banners.desktop = desktop
+  if (mobile.length) banners.mobile = mobile
+
+  return { site: { banners } } as HomepageConfig
+}
+
+function mergeHomepageConfigLayers(
+  ...layers: Array<HomepageConfig | null | undefined>
+): HomepageConfig | null {
+  const defined = layers.filter(Boolean) as HomepageConfig[]
+  if (!defined.length) return null
+  if (defined.length === 1) return defined[0]
+
+  const merged: Loose = {}
+  for (const layer of defined) {
+    const site = asObject((layer as Loose).site) ?? {}
+    const mergedSite = asObject(merged.site) ?? {}
+    const layerBanners = asObject(site.banners)
+    if (layerBanners) {
+      mergedSite.banners = {
+        ...(asObject(mergedSite.banners) ?? {}),
+        ...layerBanners,
+      }
+    }
+    for (const [key, value] of Object.entries(site)) {
+      if (key !== "banners" && value !== undefined) mergedSite[key] = value
+    }
+    if (Object.keys(mergedSite).length) merged.site = mergedSite
+
+    const sections = asObject((layer as Loose).sections)
+    if (sections) {
+      merged.sections = { ...(asObject(merged.sections) ?? {}), ...sections }
+    }
+
+    for (const [key, value] of Object.entries(layer as Loose)) {
+      if (key === "site" || key === "sections") continue
+      if (value !== undefined) merged[key] = value
+    }
+  }
+
+  return merged as HomepageConfig
+}
+
 /** Full `homepage-config` blob passed from the main project into pages and layout. */
 export type StorefrontPageInput = HomepageConfig
 
@@ -106,16 +187,24 @@ export function simplifiedHomepageConfigFromDynamicResponse(
     : null
 }
 
+/** CMS-only homepage config (no package JSON defaults). */
+export function homepageConfigFromDynamicResponseNormalized(
+  response: DynamicConfigResponse | null | undefined
+): HomepageConfig {
+  const legacy = response?.["homepage-config"] ?? null
+  const fromSplit = simplifiedHomepageConfigFromDynamicResponse(response)
+  const fromHeroBanners = simplifiedConfigFromHeroBanners(response)
+  const raw = mergeHomepageConfigLayers(fromSplit, legacy, fromHeroBanners)
+  return normalizeHomepageConfig(raw)
+}
+
 /**
  * Build `homepage-config` from Medusa `GET /store/dynamic-config` (main project only).
- * Supports legacy `homepage-config` or split plugin keys.
+ * Supports legacy `homepage-config`, split plugin keys, and `hero-banners`.
  */
 export function homepageConfigFromDynamicResponse(
   response: DynamicConfigResponse | null | undefined
 ): StorefrontPageInput {
-  const legacy = response?.["homepage-config"] ?? null
-  const fromSplit = simplifiedHomepageConfigFromDynamicResponse(response)
-  const raw = fromSplit ?? legacy
-  const normalized = normalizeHomepageConfig(raw)
+  const normalized = homepageConfigFromDynamicResponseNormalized(response)
   return mergePageInputWithDefaults(normalized)
 }