fragment-headless-sdk 2.3.3 → 2.4.1

package/dist/components/Announcement/CountdownTimer.d.ts

@@ -2,4 +2,4 @@ import React from "react";
 import { IAnnouncementContent } from "../../types";
 export default function CountdownTimer({ content, }: {
     content: IAnnouncementContent;
-}): React.JSX.Element;
+}): React.JSX.Element | null;

package/dist/components/Announcement/CountdownTimer.js

@@ -7,6 +7,7 @@ export default function CountdownTimer({ content, }) {
         minutes: "00",
         seconds: "00",
     });
+    const [isEnded, setIsEnded] = useState(false);
     useEffect(() => {
         if (!content.counterEndDate)
             return;
@@ -21,6 +22,7 @@ export default function CountdownTimer({ content, }) {
             const minutes = String(Math.floor((diff / (1000 * 60)) % 60)).padStart(2, "0");
             const seconds = String(Math.floor((diff / 1000) % 60)).padStart(2, "0");
             setTimeLeft({ days, hours, minutes, seconds });
+            setIsEnded(diff === 0);
         };
         updateTimer();
         const interval = setInterval(updateTimer, 1000);
@@ -50,6 +52,8 @@ export default function CountdownTimer({ content, }) {
         color: colors.textColor,
     }, styling, "countdownSeparator");
     const separatorAttributes = mergeSlotAttributes(styling, "countdownSeparator");
+    if (isEnded)
+        return null;
     const renderBlock = (value, label) => (React.createElement("div", { className: blockClass, style: blockStyle, ...(blockAttributes ?? {}) },
         React.createElement("div", { className: "flex gap-1" }, value.split("").map((digit, i) => (React.createElement("span", { key: i, className: digitClass, style: digitStyle, ...(digitAttributes ?? {}) }, digit)))),
         React.createElement("span", { className: labelClass, style: labelStyle, ...(labelAttributes ?? {}) }, label)));

package/dist/components/Hero/DesktopHero.d.ts

@@ -9,6 +9,8 @@ interface HeroViewProps {
     typography: ReturnType<typeof resolveHeroTypography>;
     position: "left" | "center" | "right";
     height: string;
+    buttonSpacing?: string;
+    contentSpacing?: string;
 }
-export default function DesktopHero({ buttonHref, content, colors, contentWidthClass, typography, position, height, }: HeroViewProps): React.JSX.Element;
+export default function DesktopHero({ buttonHref, content, colors, contentWidthClass, typography, position, height, buttonSpacing, contentSpacing, }: HeroViewProps): React.JSX.Element;
 export {};

package/dist/components/Hero/DesktopHero.js

@@ -2,7 +2,8 @@ import React from "react";
 import { SectionType } from "../../constants";
 import { fireClickMetric } from "../../utils";
 import { DEFAULT_CONTENT_WIDTH_CLASS, joinClassNames, renderText, } from "../../utils/hero-resolvers";
-export default function DesktopHero({ buttonHref, content, colors, contentWidthClass, typography, position, height, }) {
+import HeroCountdownTimer from "./HeroCountdownTimer";
+export default function DesktopHero({ buttonHref, content, colors, contentWidthClass, typography, position, height, buttonSpacing, contentSpacing, }) {
     const getPositionClasses = () => {
         switch (position) {
             case "center":
@@ -22,12 +23,11 @@ export default function DesktopHero({ buttonHref, content, colors, contentWidthC
         /* Image Background */
         content?.imageUrl && (React.createElement("img", { src: content.imageUrl, alt: content.title || "Hero", className: "absolute inset-0 z-0 object-cover w-full h-full" }))),
         React.createElement("div", { className: `relative z-10 mx-auto flex h-full max-w-screen-xl flex-col justify-center px-10 ${getPositionClasses()} xl:px-4` },
-            React.createElement("div", { className: joinClassNames("max-w-full", contentWidthClass || DEFAULT_CONTENT_WIDTH_CLASS) },
+            React.createElement("div", { className: joinClassNames("max-w-full flex flex-col", contentSpacing ?? "gap-4", contentWidthClass || DEFAULT_CONTENT_WIDTH_CLASS) },
                 renderText({
                     fontSize: typography.title.fontSize,
                     lineHeight: typography.title.lineHeight,
                     text: content?.title,
-                    className: "mt-4",
                     color: colors.title,
                     font: typography.title.font,
                 }),
@@ -35,12 +35,12 @@ export default function DesktopHero({ buttonHref, content, colors, contentWidthC
                     fontSize: typography.description.fontSize,
                     lineHeight: typography.description.lineHeight,
                     text: content?.description,
-                    className: "mt-4",
                     color: colors.text,
                     font: typography.description.font,
                 }),
-                content?.buttonLink && content?.buttonText && (React.createElement("a", { href: buttonHref, onClick: handleClick, className: "no-underline" },
-                    React.createElement("div", { className: "mt-6 inline-block rounded-md px-8 py-2 text-2xl font-semibold drop-shadow-lg transition-all duration-200 hover:opacity-90", style: {
+                content?.showCountdown && content?.counterEndDate && (React.createElement(HeroCountdownTimer, { content: content })),
+                content?.buttonLink && content?.buttonText && (React.createElement("a", { href: buttonHref, onClick: handleClick, className: joinClassNames("no-underline", buttonSpacing) },
+                    React.createElement("div", { className: "inline-block rounded-md px-8 py-2 text-2xl font-semibold drop-shadow-lg transition-all duration-200 hover:opacity-90", style: {
                             color: colors.buttonText,
                             backgroundColor: colors.buttonBackground,
                         } }, content.buttonText)))))));

package/dist/components/Hero/HeroCountdownTimer.d.ts

@@ -0,0 +1,5 @@
+import React from "react";
+import { IHeroContent } from "../../types/hero";
+export default function HeroCountdownTimer({ content, }: {
+    content: IHeroContent;
+}): React.JSX.Element | null;

package/dist/components/Hero/HeroCountdownTimer.js

@@ -0,0 +1,69 @@
+import React, { useEffect, useState } from "react";
+import { mergeSlotAttributes, mergeSlotClasses, mergeSlotStyles, } from "../../utils";
+import { resolveHeroCountdownColors } from "../../utils/hero-resolvers";
+export default function HeroCountdownTimer({ content, }) {
+    const [timeLeft, setTimeLeft] = useState({
+        days: "00",
+        hours: "00",
+        minutes: "00",
+        seconds: "00",
+    });
+    const [isEnded, setIsEnded] = useState(false);
+    useEffect(() => {
+        if (!content.counterEndDate)
+            return;
+        const updateTimer = () => {
+            const now = new Date().getTime();
+            const target = content.counterEndDate
+                ? new Date(content.counterEndDate).getTime()
+                : 0;
+            const diff = Math.max(0, target - now);
+            const days = String(Math.floor(diff / (1000 * 60 * 60 * 24))).padStart(2, "0");
+            const hours = String(Math.floor((diff / (1000 * 60 * 60)) % 24)).padStart(2, "0");
+            const minutes = String(Math.floor((diff / (1000 * 60)) % 60)).padStart(2, "0");
+            const seconds = String(Math.floor((diff / 1000) % 60)).padStart(2, "0");
+            setTimeLeft({ days, hours, minutes, seconds });
+            setIsEnded(diff === 0);
+        };
+        updateTimer();
+        const interval = setInterval(updateTimer, 1000);
+        return () => clearInterval(interval);
+    }, [content.counterEndDate]);
+    const styling = content.styling;
+    const containerClass = mergeSlotClasses("flex items-center justify-start gap-2 py-2 w-fit", styling, "countdownContainer");
+    const containerStyle = mergeSlotStyles(undefined, styling, "countdownContainer");
+    const containerAttributes = mergeSlotAttributes(styling, "countdownContainer");
+    const blockClass = mergeSlotClasses("flex flex-col items-center", styling, "countdownBlock");
+    const blockStyle = mergeSlotStyles(undefined, styling, "countdownBlock");
+    const blockAttributes = mergeSlotAttributes(styling, "countdownBlock");
+    const colors = resolveHeroCountdownColors(content);
+    const digitClass = mergeSlotClasses("text-[1.65rem] font-semibold flex items-center justify-center leading-snug rounded px-1.5 drop-shadow-md", styling, "countdownDigit");
+    const digitStyle = mergeSlotStyles({
+        color: colors.digitColor,
+        backgroundColor: colors.digitBackgroundColor,
+    }, styling, "countdownDigit");
+    const digitAttributes = mergeSlotAttributes(styling, "countdownDigit");
+    const labelClass = mergeSlotClasses("mt-1.5 text-base font-medium leading-tight", styling, "countdownLabel");
+    const labelStyle = mergeSlotStyles({
+        color: colors.textColor,
+    }, styling, "countdownLabel");
+    const labelAttributes = mergeSlotAttributes(styling, "countdownLabel");
+    const separatorClass = mergeSlotClasses("text-[1.65rem] font-semibold -mt-4", styling, "countdownSeparator");
+    const separatorStyle = mergeSlotStyles({
+        color: colors.textColor,
+    }, styling, "countdownSeparator");
+    const separatorAttributes = mergeSlotAttributes(styling, "countdownSeparator");
+    if (isEnded)
+        return null;
+    const renderBlock = (value, label) => (React.createElement("div", { className: blockClass, style: blockStyle, ...(blockAttributes ?? {}) },
+        React.createElement("div", { className: "flex gap-2" }, value.split("").map((digit, i) => (React.createElement("span", { key: i, className: digitClass, style: digitStyle, ...(digitAttributes ?? {}) }, digit)))),
+        React.createElement("span", { className: labelClass, style: labelStyle, ...(labelAttributes ?? {}) }, label)));
+    return (React.createElement("div", { className: containerClass, style: containerStyle, ...(containerAttributes ?? {}) },
+        renderBlock(timeLeft.days, "Days"),
+        React.createElement("span", { className: separatorClass, style: separatorStyle, ...(separatorAttributes ?? {}) }, ":"),
+        renderBlock(timeLeft.hours, "Hours"),
+        React.createElement("span", { className: separatorClass, style: separatorStyle, ...(separatorAttributes ?? {}) }, ":"),
+        renderBlock(timeLeft.minutes, "Mins"),
+        React.createElement("span", { className: separatorClass, style: separatorStyle, ...(separatorAttributes ?? {}) }, ":"),
+        renderBlock(timeLeft.seconds, "Secs")));
+}

package/dist/components/Hero/MobileHero.d.ts

@@ -6,6 +6,8 @@ interface MobileHeroProps {
     content: IHeroContent;
     colors: ReturnType<typeof resolveHeroColors>;
     typography: ReturnType<typeof resolveHeroTypography>;
+    buttonSpacing?: string;
+    contentSpacing?: string;
 }
-export default function MobileHero({ buttonHref, content, colors, typography, }: MobileHeroProps): React.JSX.Element;
+export default function MobileHero({ buttonHref, content, colors, typography, buttonSpacing, contentSpacing, }: MobileHeroProps): React.JSX.Element;
 export {};

package/dist/components/Hero/MobileHero.js

@@ -2,11 +2,12 @@ import React from "react";
 import { SectionType } from "../../constants";
 import { fireClickMetric } from "../../utils";
 import { renderText, } from "../../utils/hero-resolvers";
-export default function MobileHero({ buttonHref, content, colors, typography, }) {
+import HeroCountdownTimer from "./HeroCountdownTimer";
+export default function MobileHero({ buttonHref, content, colors, typography, buttonSpacing, contentSpacing, }) {
     const handleClick = React.useCallback(() => {
         fireClickMetric(content.measurementId, content.sectionType || SectionType.HeroBanner, content.sectionId);
     }, [content.measurementId, content.sectionType, content.sectionId]);
-    return (React.createElement("div", { className: "relative z-10 mx-auto gap-4 flex max-w-screen-md flex-col items-center justify-center py-6 text-center", style: { backgroundColor: colors.background } },
+    return (React.createElement("div", { className: `relative z-10 mx-auto flex max-w-screen-md flex-col items-center justify-center py-6 text-center ${contentSpacing ?? "gap-4"}`, style: { backgroundColor: colors.background } },
         renderText({
             fontSize: typography.title.fontSize,
             lineHeight: typography.title.lineHeight,
@@ -23,12 +24,13 @@ export default function MobileHero({ buttonHref, content, colors, typography, })
             fontSize: typography.description.fontSize,
             lineHeight: typography.description.lineHeight,
             text: content?.description,
-            className: "px-4 drop-shadow-lg text-center mt-4",
+            className: "px-4 drop-shadow-lg text-center",
             color: colors.text,
             font: typography.description.font,
         }),
-        content?.buttonLink && content?.buttonText && (React.createElement("a", { href: buttonHref, onClick: handleClick, className: "no-underline" },
-            React.createElement("div", { className: "mb-2 rounded-md px-6 py-2 text-lg font-semibold drop-shadow-lg transition-all duration-200 hover:opacity-90", style: {
+        content?.showCountdown && content?.counterEndDate && (React.createElement(HeroCountdownTimer, { content: content })),
+        content?.buttonLink && content?.buttonText && (React.createElement("a", { href: buttonHref, onClick: handleClick, className: `no-underline ${buttonSpacing ?? ""}`.trim() },
+            React.createElement("div", { className: "rounded-md px-6 py-2 text-lg font-semibold drop-shadow-lg transition-all duration-200 hover:opacity-90", style: {
                     color: colors.buttonText,
                     backgroundColor: colors.buttonBackground,
                 } }, content.buttonText)))));

package/dist/components/Hero/index.js

@@ -2,7 +2,7 @@
 import React, { useEffect, useRef } from "react";
 import { SectionType } from "../../constants";
 import { fireImpressionWhenVisible, } from "../../utils";
-import { resolveContentWidthClass, resolveHeight, resolveHeroColors, resolveHeroTypography, resolvePosition, } from "../../utils/hero-resolvers";
+import { resolveContentWidthClass, resolveHeight, resolveHeroColors, resolveHeroTypography, resolvePosition, resolveButtonSpacing, resolveContentSpacing, } from "../../utils/hero-resolvers";
 import DesktopHero from "./DesktopHero";
 import MobileHero from "./MobileHero";
 export default function Hero({ content }) {
@@ -20,9 +20,11 @@ export default function Hero({ content }) {
     const typography = resolveHeroTypography(content);
     const position = resolvePosition(content);
     const height = resolveHeight(content);
+    const buttonSpacing = resolveButtonSpacing(content);
+    const contentSpacing = resolveContentSpacing(content);
     return (React.createElement("div", { className: "bg-black", ref: ref, style: { backgroundColor: colors.background } },
         React.createElement("div", { className: "hidden lg:block" },
-            React.createElement(DesktopHero, { content: content, buttonHref: buttonHref, colors: colors, contentWidthClass: contentWidthClass, typography: typography, position: position, height: height })),
+            React.createElement(DesktopHero, { content: content, buttonHref: buttonHref, colors: colors, contentWidthClass: contentWidthClass, typography: typography, position: position, height: height, buttonSpacing: buttonSpacing, contentSpacing: contentSpacing })),
         React.createElement("div", { className: "block lg:hidden" },
-            React.createElement(MobileHero, { content: content, buttonHref: buttonHref, colors: colors, typography: typography }))));
+            React.createElement(MobileHero, { content: content, buttonHref: buttonHref, colors: colors, typography: typography, buttonSpacing: buttonSpacing, contentSpacing: contentSpacing }))));
 }

package/dist/constants/hero.d.ts

@@ -1,6 +1,7 @@
 export declare enum HeroType {
     Static = "static",
-    Video = "video"
+    Video = "video",
+    Countdown = "countdown"
 }
 export declare const heroTypes: {
     label: string;

package/dist/constants/hero.js

@@ -2,6 +2,7 @@ export var HeroType;
 (function (HeroType) {
     HeroType["Static"] = "static";
     HeroType["Video"] = "video";
+    HeroType["Countdown"] = "countdown";
 })(HeroType || (HeroType = {}));
 export const heroTypes = [
     { label: "Static Image", value: HeroType.Static },

package/dist/types/announcement.d.ts

@@ -22,6 +22,7 @@ export interface IAnnouncement {
     name: string;
     status: AnnouncementStatus;
     content: IAnnouncementContent | null;
+    page_order: number | null;
     active_duration_seconds: number | null;
     active_start_date: string | null;
     active_end_date: string | null;

package/dist/types/hero.d.ts

@@ -13,6 +13,8 @@ export interface IHeroContent {
     imageUrl: string;
     mobileImageUrl: string;
     videoUrl?: string;
+    counterEndDate?: string;
+    showCountdown?: boolean;
     measurementId?: string;
     sectionId?: string;
     sectionType?: SectionType;
@@ -24,6 +26,7 @@ export interface IHero {
     name: string;
     type: HeroType;
     page: ShopPage["handle"] | null;
+    page_order: number | null;
     status: HeroStatus;
     content: IHeroContent | null;
     active_duration_seconds: number | null;

package/dist/utils/hero-resolvers.d.ts

@@ -1,5 +1,6 @@
 import React from "react";
 import { IHeroContent } from "../types";
+import { CountdownResolvedColors } from "./announcement-resolvers";
 export interface HeroResolvedColors {
     title: string;
     text: string;
@@ -51,7 +52,10 @@ export declare function resolveHeroColors(content: IHeroContent): HeroResolvedCo
 export declare function resolveContentWidthClass(content: IHeroContent): string;
 export declare function resolvePosition(content: IHeroContent): "left" | "center" | "right";
 export declare function resolveHeight(content: IHeroContent): string;
+export declare function resolveButtonSpacing(content: IHeroContent): string;
+export declare function resolveContentSpacing(content: IHeroContent): string;
 export declare function resolveHeroTypography(content: IHeroContent): HeroTypographySettings;
+export declare function resolveHeroCountdownColors(content: IHeroContent): CountdownResolvedColors;
 export declare function renderText({ fontSize, lineHeight, text, className, color, font, }: {
     fontSize: string;
     lineHeight: string;

package/dist/utils/hero-resolvers.js

@@ -1,4 +1,5 @@
 import React from "react";
+import { resolveToken } from "./styling";
 export const DEFAULT_COLORS = {
     title: "#ffffff",
     text: "#ffffff",
@@ -70,6 +71,24 @@ export function resolveHeight(content) {
     }
     return DEFAULT_HEIGHT_CLASS;
 }
+const DEFAULT_BUTTON_SPACING = "mt-4";
+export function resolveButtonSpacing(content) {
+    const layout = content?.styling?.tokens?.layout ?? {};
+    const raw = layout.buttonSpacing;
+    if (typeof raw === "string" && raw.trim().length > 0) {
+        return raw.trim();
+    }
+    return DEFAULT_BUTTON_SPACING;
+}
+const DEFAULT_CONTENT_SPACING = "gap-4";
+export function resolveContentSpacing(content) {
+    const layout = content?.styling?.tokens?.layout ?? {};
+    const raw = layout.contentSpacing;
+    if (typeof raw === "string" && raw.trim().length > 0) {
+        return raw.trim();
+    }
+    return DEFAULT_CONTENT_SPACING;
+}
 export function resolveHeroTypography(content) {
     const typography = content?.styling?.tokens?.typography;
     return {
@@ -88,6 +107,22 @@ export function resolveHeroTypography(content) {
         },
     };
 }
+const DEFAULT_HERO_COUNTDOWN_COLORS = {
+    digitColor: "#ffffff",
+    digitBackgroundColor: "#000000",
+    textColor: "#ffffff",
+};
+export function resolveHeroCountdownColors(content) {
+    const styling = content.styling;
+    const digitColor = resolveToken(styling, "counterDigitColor");
+    const digitBackgroundColor = resolveToken(styling, "counterDigitBackgroundColor");
+    const textColor = resolveToken(styling, "counterTextColor", digitColor);
+    return {
+        digitColor: fallbackColor(digitColor, DEFAULT_HERO_COUNTDOWN_COLORS.digitColor),
+        digitBackgroundColor: fallbackColor(digitBackgroundColor, DEFAULT_HERO_COUNTDOWN_COLORS.digitBackgroundColor),
+        textColor: fallbackColor(textColor, DEFAULT_HERO_COUNTDOWN_COLORS.textColor),
+    };
+}
 export function renderText({ fontSize, lineHeight, text, className, color, font, }) {
     if (!text || text.trim().length === 0) {
         return null;

package/dist/utils/styling.js

@@ -18,6 +18,10 @@ const KNOWN_ANNOUNCEMENT_SLOTS = [
     "countdownItem",
     "countdownLabel",
     "countdownValue",
+    "countdownContainer",
+    "countdownBlock",
+    "countdownDigit",
+    "countdownSeparator",
 ];
 const KNOWN_HERO_SLOTS = [
     "root",
@@ -43,7 +47,11 @@ const KNOWN_HERO_SLOTS = [
     "mobileDescription",
     "button",
     "desktopButton",
-    "mobileButton",
+    "mobileButton", "countdownContainer",
+    "countdownBlock",
+    "countdownDigit",
+    "countdownLabel",
+    "countdownSeparator",
 ];
 const ALL_KNOWN_SLOTS = [...KNOWN_ANNOUNCEMENT_SLOTS, ...KNOWN_HERO_SLOTS];
 function getCacheKey(base, slots, extra) {

package/docs/CHANGELOG.md

@@ -7,15 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### [Unreleased]
 
+### [2.4.1] - 2026-04-10
+
+#### Added
+
+- **`IHero.page_order`** – New `page_order: number | null` field on `IHero`. Consumers can use this to sort hero banners by their merchant-defined display order.
+
+### [2.4.0] - 2026-03-08
+
+#### Added
+
+- **Hero countdown option** – Hero content supports optional countdown via `content.showCountdown` and `content.counterEndDate`. New `HeroCountdownTimer` component is used by Desktop/Mobile Hero when countdown is enabled.
+- **Button spacing** – Hero resolvers support `buttonSpacing` for configurable CTA spacing (`hero.ts`, `hero-resolvers.ts`).
+- **Content spacing** – Hero resolvers support `contentSpacing` for configurable gap between title, description, countdown, and button (`hero-resolvers.ts`); UI options in the app mirror this.
+- **Countdown color tokens** – Hero countdown supports `counterDigitColor`, `counterDigitBackgroundColor`, and `counterTextColor` via `content.styling.tokens.colors`; resolved by `resolveHeroCountdownColors()` in `hero-resolvers.ts`.
+
+#### Changed
+
+- **Hero types** – Countdown is no longer a separate hero type in the display list; countdown is shown when `content.showCountdown && content.counterEndDate` are set.
+- **IHeroContent** – Added `showCountdown?: boolean`; countdown rendering is gated on this and `counterEndDate` in both DesktopHero and MobileHero.
+
 ### [2.3.3] - 2026-03-07
 
 #### Changed
 
-- **`fetchResource` default caching** – Environment-aware defaults for better performance and freshness:
-  - **Next.js production**: Defaults to `force-cache` with 60-second revalidation and resource-type cache tags (`fragment-hero-banners`, `fragment-announcements`) so responses are cached at the edge while staying reasonably fresh.
-  - **Next.js development / non–Next.js**: Defaults to `cache: "default"` with no revalidation.
-- User-provided `cacheOptions` still override these defaults.
-- **Request deduplication**: Cache keys now normalize `status` to `"enabled"` when omitted, so identical requests are deduplicated consistently.
+- **`fetchResource` authentication** – API key is now sent as a `?apiKey=` URL query parameter instead of an `Authorization: Bearer` header, enabling Vercel's Edge Network (and other CDNs) to cache responses. No call-site changes required. Requires the Fragment app to be on a matching version; mismatched deployments will receive a 401.
 
 ### [2.3.2] - 2026-02-27
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fragment-headless-sdk",
-  "version": "2.3.3",
+  "version": "2.4.1",
   "description": "Official SDK for Fragment-Shopify CMS: React components, TypeScript types, and utilities for headless Shopify storefronts.",
   "license": "MIT",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/sevenbrand/fragment-monorepo.git",
+    "url": "https://github.com/sevenbrand/fragment-monorepo.git",
     "directory": "packages/sdk"
   },
   "homepage": "https://github.com/sevenbrand/fragment-monorepo/tree/main/packages/sdk#readme",

package/readme.md

@@ -4,7 +4,7 @@ The official SDK for integrating with Fragment-Shopify CMS. Provides React compo
 
 ## ✨ What's New
 
-**v2.3.3** – `fetchResource` uses environment-aware default caching: Next.js production defaults to 60s revalidation and resource-type cache tags; development and non–Next.js use `cache: "default"`. Request deduplication normalizes `status` for consistent cache keys.
+**v2.4.1** – `IHero` now includes a `page_order: number | null` field. Use this to sort hero banners by their merchant-defined display order; when all values are `null` the recommended behaviour is to randomize.
 
 > See [CHANGELOG.md](./docs/CHANGELOG.md) for full release history