fragment-headless-sdk 2.1.1 → 2.1.3

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

@@ -1,6 +1,7 @@
 import React from "react";
 import { IAnnouncementContent } from "../../types";
-export default function AnnouncementButton({ content, buttonHref, }: {
+export default function AnnouncementButton({ content, buttonHref, clickHref, }: {
     content: IAnnouncementContent;
     buttonHref?: string;
+    clickHref?: string;
 }): React.JSX.Element | null;

package/dist/components/Announcement/AnnouncementButton.js

@@ -1,17 +1,13 @@
 import React from "react";
 import { ButtonType } from "../../constants";
-import { mergeSlotAttributes, mergeSlotClasses, mergeSlotStyles, resolveToken, resolveTokenByCategory, } from "../../utils";
-export default function AnnouncementButton({ content, buttonHref, }) {
+import { fireClickMetric, mergeSlotAttributes, mergeSlotClasses, mergeSlotStyles, resolveToken, resolveTokenByCategory, } from "../../utils";
+export default function AnnouncementButton({ content, buttonHref, clickHref, }) {
     // Don’t render if no button or explicitly None
     if (!content?.buttonText || content.buttonType === ButtonType.None)
         return null;
     // If we weren’t given a usable href, don’t render a broken link
     if (!buttonHref)
         return null;
-    // Decide if link should open in a new tab.
-    // If you already have a boolean like `content.buttonLink` meaning "open in new tab",
-    // keep using it; otherwise you can add one later.
-    const openInNewTab = Boolean(content.buttonLink);
     const styling = content.styling;
     const baseTextColor = resolveTokenByCategory(styling, "colors", "text") ||
         resolveToken(styling, "textColor");
@@ -37,7 +33,10 @@ export default function AnnouncementButton({ content, buttonHref, }) {
     if (attributes && "aria-label" in attributes) {
         delete attributes["aria-label"];
     }
-    return (React.createElement("a", { href: buttonHref, className: className, style: style, ...(openInNewTab
-            ? { target: "_blank", rel: "noopener noreferrer" }
-            : {}), ...(attributes ?? {}), "aria-label": ariaLabel }, content.buttonText));
+    const handleClick = React.useCallback(() => {
+        if (!clickHref)
+            return;
+        fireClickMetric(clickHref);
+    }, [clickHref]);
+    return (React.createElement("a", { href: buttonHref, className: className, style: style, onClick: handleClick, ...(attributes ?? {}), "aria-label": ariaLabel }, content.buttonText));
 }

package/dist/components/Announcement/index.js

@@ -2,6 +2,7 @@ import React, { useEffect, useRef } from "react";
 import { AnnouncementType, ButtonType } from "../../constants";
 import { buildClickUrl, fireImpressionWhenVisible, getThemeClasses, mergeSlotAttributes, mergeSlotClasses, mergeSlotStyles, resolveToken, resolveTokenByCategory, } from "../../utils";
 import AnnouncementButton from "./AnnouncementButton";
+import { AnnouncementStyles } from "./AnnouncementStyles";
 import CountdownTimer from "./CountdownTimer";
 export default function Announcement({ content, type, handleClose, }) {
     const ref = useRef(null);
@@ -10,7 +11,8 @@ export default function Announcement({ content, type, handleClose, }) {
             fireImpressionWhenVisible(ref.current, content.impressionUrl);
         }
     }, [content?.impressionUrl]);
-    const signedButtonHref = content?.buttonLink && content?.clickUrlBase
+    const buttonHref = content?.buttonLink || undefined;
+    const clickTrackingHref = content?.buttonLink && content?.clickUrlBase
         ? buildClickUrl(content.clickUrlBase, content.buttonLink)
         : undefined;
     if (!content)
@@ -54,6 +56,7 @@ export default function Announcement({ content, type, handleClose, }) {
     const closeButtonStyle = mergeSlotStyles({ color: closeButtonColor }, styling, "closeButton");
     const closeButtonAttributes = mergeSlotAttributes(styling, "closeButton");
     return (React.createElement("div", { ref: ref, className: rootClass, style: rootStyle, ...(rootAttributes ?? {}) },
+        React.createElement(AnnouncementStyles, null),
         React.createElement("div", { className: innerClass, style: innerStyle, ...(innerAttributes ?? {}) },
             type === AnnouncementType.Marquee ? (React.createElement("div", { className: marqueeContainerClass, style: marqueeContainerStyle, ...(marqueeContainerAttributes ?? {}) },
                 React.createElement("div", { className: marqueeTextWrapperClass, style: marqueeTextWrapperStyle, ...(marqueeTextWrapperAttributes ?? {}) },
@@ -61,12 +64,12 @@ export default function Announcement({ content, type, handleClose, }) {
                         React.createElement("div", { className: marqueeContentClass, style: marqueeContentStyle, ...(marqueeContentAttributes ?? {}), dangerouslySetInnerHTML: {
                                 __html: content.announcementHtml || "",
                             } }))),
-                content.buttonText && content.buttonType !== ButtonType.None && (React.createElement(AnnouncementButton, { content: content, buttonHref: signedButtonHref })))) : (React.createElement("div", { className: contentRowClass, style: contentRowStyle, ...(contentRowAttributes ?? {}) },
+                content.buttonText && content.buttonType !== ButtonType.None && (React.createElement(AnnouncementButton, { content: content, buttonHref: buttonHref, clickHref: clickTrackingHref })))) : (React.createElement("div", { className: contentRowClass, style: contentRowStyle, ...(contentRowAttributes ?? {}) },
                 React.createElement("div", { className: announcementTextClass, style: announcementTextStyle, ...(announcementTextAttributes ?? {}) },
                     React.createElement("div", { dangerouslySetInnerHTML: {
                             __html: content.announcementHtml || "",
                         } })),
                 type === AnnouncementType.Countdown ? (React.createElement(CountdownTimer, { content: content })) : (content.buttonText &&
-                    content.buttonType !== ButtonType.None && (React.createElement(AnnouncementButton, { content: content, buttonHref: signedButtonHref || content.buttonLink || "#" }))))),
+                    content.buttonType !== ButtonType.None && (React.createElement(AnnouncementButton, { content: content, buttonHref: buttonHref, clickHref: clickTrackingHref }))))),
             React.createElement("div", { onClick: handleClose, className: closeButtonClass, style: closeButtonStyle, ...(closeButtonAttributes ?? {}) }, "\u00D7"))));
 }

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

@@ -3,6 +3,7 @@ import { IHeroContent } from "../../types";
 import { resolveHeroColors, resolveHeroTypography } from "../../utils/hero-resolvers";
 interface HeroViewProps {
     buttonHref?: string;
+    clickHref?: string;
     content: IHeroContent;
     colors: ReturnType<typeof resolveHeroColors>;
     contentWidthClass: string;
@@ -10,5 +11,5 @@ interface HeroViewProps {
     position: "left" | "center" | "right";
     height: string;
 }
-export default function DesktopHero({ buttonHref, content, colors, contentWidthClass, typography, position, height, }: HeroViewProps): React.JSX.Element;
+export default function DesktopHero({ buttonHref, clickHref, content, colors, contentWidthClass, typography, position, height, }: HeroViewProps): React.JSX.Element;
 export {};

package/dist/components/Hero/DesktopHero.js

@@ -1,6 +1,7 @@
 import React from "react";
+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, }) {
+export default function DesktopHero({ buttonHref, clickHref, content, colors, contentWidthClass, typography, position, height, }) {
     const getPositionClasses = () => {
         switch (position) {
             case "center":
@@ -12,6 +13,11 @@ export default function DesktopHero({ buttonHref, content, colors, contentWidthC
                 return "items-start text-left";
         }
     };
+    const handleClick = React.useCallback(() => {
+        if (!clickHref)
+            return;
+        fireClickMetric(clickHref);
+    }, [clickHref]);
     return (React.createElement("div", { className: `relative ${height} gap-4 w-full`, style: { backgroundColor: colors.background } },
         content?.videoUrl ? (React.createElement("video", { src: content.videoUrl, autoPlay: true, muted: true, loop: true, playsInline: true, className: "absolute inset-0 z-0 object-cover w-full h-full" })) : (
         /* Image Background */
@@ -22,6 +28,7 @@ export default function DesktopHero({ buttonHref, content, colors, contentWidthC
                     fontSize: typography.title.fontSize,
                     lineHeight: typography.title.lineHeight,
                     text: content?.title,
+                    className: "mt-4",
                     color: colors.title,
                     font: typography.title.font,
                 }),
@@ -33,7 +40,7 @@ export default function DesktopHero({ buttonHref, content, colors, contentWidthC
                     color: colors.text,
                     font: typography.description.font,
                 }),
-                content?.buttonLink && content?.buttonText && (React.createElement("a", { href: buttonHref, target: "_blank", rel: "noopener noreferrer", className: "no-underline" },
+                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: {
                             color: colors.buttonText,
                             backgroundColor: colors.buttonBackground,

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

@@ -3,9 +3,10 @@ import { IHeroContent } from "../../types";
 import { resolveHeroColors, resolveHeroTypography } from "../../utils/hero-resolvers";
 interface MobileHeroProps {
     buttonHref?: string;
+    clickHref?: string;
     content: IHeroContent;
     colors: ReturnType<typeof resolveHeroColors>;
     typography: ReturnType<typeof resolveHeroTypography>;
 }
-export default function MobileHero({ buttonHref, content, colors, typography, }: MobileHeroProps): React.JSX.Element;
+export default function MobileHero({ buttonHref, clickHref, content, colors, typography, }: MobileHeroProps): React.JSX.Element;
 export {};

package/dist/components/Hero/MobileHero.js

@@ -1,22 +1,19 @@
 import React from "react";
-import { ensureSafeColor } from "../../utils/color";
+import { fireClickMetric } from "../../utils";
 import { renderText, } from "../../utils/hero-resolvers";
-export default function MobileHero({ buttonHref, content, colors, typography, }) {
-    const safeTitleColor = ensureSafeColor(colors.title, "#ffffff");
-    const safeTextColor = ensureSafeColor(colors.text, "#ffffff");
-    const titleFontSize = typography.title.fontSize === "text-5xl"
-        ? "text-3xl"
-        : typography.title.fontSize;
-    const descriptionFontSize = typography.description.fontSize === "text-3xl"
-        ? "text-lg"
-        : typography.description.fontSize;
+export default function MobileHero({ buttonHref, clickHref, content, colors, typography, }) {
+    const handleClick = React.useCallback(() => {
+        if (!clickHref)
+            return;
+        fireClickMetric(clickHref);
+    }, [clickHref]);
     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 } },
         renderText({
-            fontSize: titleFontSize,
+            fontSize: typography.title.fontSize,
             lineHeight: typography.title.lineHeight,
             text: content?.title,
-            className: "px-4 drop-shadow-xl text-center font-bold",
-            color: safeTitleColor,
+            className: "px-4 drop-shadow-xl text-center",
+            color: colors.title,
             font: typography.title.font,
         }),
         content?.videoUrl ? (React.createElement("div", { className: "w-full" },
@@ -24,14 +21,14 @@ export default function MobileHero({ buttonHref, content, colors, typography, })
             React.createElement("img", { src: content.mobileImageUrl, alt: content.title || "Hero", className: "h-full w-full object-cover" }))) : content?.imageUrl ? (React.createElement("div", { className: "w-full" },
             React.createElement("img", { src: content.imageUrl, alt: content.title || "Hero", className: "h-full w-full object-cover" }))) : null,
         renderText({
-            fontSize: descriptionFontSize,
+            fontSize: typography.description.fontSize,
             lineHeight: typography.description.lineHeight,
             text: content?.description,
             className: "px-4 drop-shadow-lg text-center mt-4",
-            color: safeTextColor,
+            color: colors.text,
             font: typography.description.font,
         }),
-        content?.buttonLink && content?.buttonText && (React.createElement("a", { href: buttonHref, target: "_blank", rel: "noopener noreferrer", className: "no-underline" },
+        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: {
                     color: colors.buttonText,
                     backgroundColor: colors.buttonBackground,

package/dist/components/Hero/index.js

@@ -1,5 +1,5 @@
 import React, { useEffect, useRef } from "react";
-import { buildClickUrl, fireImpressionWhenVisible } from "../../utils";
+import { buildClickUrl, fireImpressionWhenVisible, } from "../../utils";
 import { resolveContentWidthClass, resolveHeight, resolveHeroColors, resolveHeroTypography, resolvePosition, } from "../../utils/hero-resolvers";
 import DesktopHero from "./DesktopHero";
 import MobileHero from "./MobileHero";
@@ -10,7 +10,8 @@ export default function Hero({ content }) {
             fireImpressionWhenVisible(ref.current, content.impressionUrl);
         }
     }, [content?.impressionUrl]);
-    const signedButtonHref = content?.buttonLink && content?.clickUrlBase
+    const buttonHref = content?.buttonLink || undefined;
+    const clickTrackingHref = content?.buttonLink && content?.clickUrlBase
         ? buildClickUrl(content.clickUrlBase, content.buttonLink)
         : undefined;
     if (!content)
@@ -22,7 +23,7 @@ export default function Hero({ content }) {
     const height = resolveHeight(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: signedButtonHref, colors: colors, contentWidthClass: contentWidthClass, typography: typography, position: position, height: height })),
+            React.createElement(DesktopHero, { content: content, buttonHref: buttonHref, clickHref: clickTrackingHref, colors: colors, contentWidthClass: contentWidthClass, typography: typography, position: position, height: height })),
         React.createElement("div", { className: "block lg:hidden" },
-            React.createElement(MobileHero, { content: content, buttonHref: signedButtonHref, colors: colors, typography: typography }))));
+            React.createElement(MobileHero, { content: content, buttonHref: buttonHref, clickHref: clickTrackingHref, colors: colors, typography: typography }))));
 }

package/dist/utils/fetch-resource.d.ts

@@ -1,7 +1,4 @@
-export declare enum ResourceType {
-    HeroBanners = "hero-banners",
-    Announcements = "announcements"
-}
+export declare const ENABLE_REQUEST_DEDUPLICATION = true;
 export type ListParams = {
     status?: "enabled" | "disabled";
     page?: number;
@@ -9,10 +6,14 @@ export type ListParams = {
     search?: string;
     pageFilter?: string;
 };
+export declare enum ResourceType {
+    HeroBanners = "hero-banners",
+    Announcements = "announcements"
+}
 export type CacheOptions = {
-    /** Request cache mode (default: 'no-store' for fresh data) */
+    /** Request cache mode (default: 'force-cache' with 60s revalidation) */
     cache?: RequestCache;
-    /** Next.js revalidation time in seconds (default: 0 for always fresh) */
+    /** Next.js revalidation time in seconds (default: 60) */
     revalidate?: number | false;
     /** Next.js cache tags for selective invalidation */
     tags?: string[];
@@ -23,7 +24,7 @@ type FetchResourceParams = {
     type: ResourceType;
     params?: ListParams;
     fetchImpl?: typeof fetch;
-    /** Cache configuration (defaults to no caching for fresh data) */
+    /** Cache configuration (defaults to force-cache with 60s revalidation) */
     cacheOptions?: CacheOptions;
 };
 /** Lists resources with optional filters (parity with client.list) */

package/dist/utils/fetch-resource.js

@@ -1,8 +1,30 @@
+// Simple anti-spam: prevent identical concurrent requests
+export const ENABLE_REQUEST_DEDUPLICATION = true;
 export var ResourceType;
 (function (ResourceType) {
     ResourceType["HeroBanners"] = "hero-banners";
     ResourceType["Announcements"] = "announcements";
 })(ResourceType || (ResourceType = {}));
+// Simple request deduplication to prevent identical concurrent requests
+const pendingRequests = new Map();
+/**
+ * Generates a cache key for request deduplication
+ * Normalizes params to include default status for consistent key generation
+ */
+function generateRequestKey(baseUrl, type, params) {
+    // Normalize params with defaults (same as performRequest does)
+    const normalizedParams = {
+        ...params,
+        status: params.status ?? "enabled", // Include default status
+    };
+    const sortedParams = Object.keys(normalizedParams)
+        .sort()
+        .reduce((acc, key) => {
+        acc[key] = normalizedParams[key];
+        return acc;
+    }, {});
+    return `${baseUrl}:${type}:${JSON.stringify(sortedParams)}`;
+}
 /**
  * Detects if running in Next.js environment
  */
@@ -20,10 +42,10 @@ function getDefaultCacheConfig(type) {
     const isNextJS = isNextJSEnvironment();
     const isDev = process?.env?.NODE_ENV === "development";
     if (isNextJS && !isDev) {
-        // In Next.js production, default to no caching for fresh data
+        // In Next.js production, default to caching with 60 second revalidation
         return {
-            cache: "no-store",
-            revalidate: 0,
+            cache: "force-cache",
+            revalidate: 60,
             tags: [`fragment-${type}`],
         };
     }
@@ -38,6 +60,50 @@ export async function fetchResource({ baseUrl, apiKey, type, params = {}, fetchI
         console.warn("❌ Missing EXTERNAL_API_URL or FRAGMENT_API_KEY");
         return [];
     }
+    // Generate key for request deduplication
+    const requestKey = generateRequestKey(baseUrl, type, params);
+    // Request deduplication - check if identical request is already in flight
+    if (ENABLE_REQUEST_DEDUPLICATION) {
+        const existingRequest = pendingRequests.get(requestKey);
+        if (existingRequest) {
+            console.log(`🔄 Deduplicating request for ${type}`);
+            try {
+                return await existingRequest;
+            }
+            catch (err) {
+                // If the existing request failed, we'll try again below
+                pendingRequests.delete(requestKey);
+            }
+        }
+    }
+    // Create the actual request promise
+    const requestPromise = performRequest({
+        baseUrl,
+        apiKey,
+        type,
+        params,
+        fetchImpl,
+        cacheOptions,
+    });
+    // Store the promise for deduplication
+    if (ENABLE_REQUEST_DEDUPLICATION) {
+        pendingRequests.set(requestKey, requestPromise);
+    }
+    try {
+        const result = await requestPromise;
+        return result;
+    }
+    finally {
+        // Clean up the pending request
+        if (ENABLE_REQUEST_DEDUPLICATION) {
+            pendingRequests.delete(requestKey);
+        }
+    }
+}
+/**
+ * Performs the actual HTTP request (separated for cleaner code organization)
+ */
+async function performRequest({ baseUrl, apiKey, type, params = {}, fetchImpl, cacheOptions, }) {
     try {
         const f = fetchImpl ?? fetch;
         const base = baseUrl.replace(/\/+$/, "");
@@ -47,8 +113,8 @@ export async function fetchResource({ baseUrl, apiKey, type, params = {}, fetchI
         const limit = Math.min(100, Math.max(1, params.limit ?? 25));
         url.searchParams.set("pageNum", String(page));
         url.searchParams.set("limit", String(limit));
-        if (params.status)
-            url.searchParams.set("status", params.status);
+        // Default to "enabled" status if not specified
+        url.searchParams.set("status", params.status ?? "enabled");
         if (params.pageFilter)
             url.searchParams.set("page", params.pageFilter);
         if (params.search)
@@ -64,9 +130,6 @@ export async function fetchResource({ baseUrl, apiKey, type, params = {}, fetchI
             headers: {
                 Authorization: `Bearer ${apiKey}`,
                 "Content-Type": "application/json",
-                // Add cache-busting headers for better cache control
-                "Cache-Control": "no-cache, no-store, must-revalidate",
-                Pragma: "no-cache",
             },
             cache: finalCacheOptions.cache,
         };

package/dist/utils/index.d.ts

@@ -1,5 +1,4 @@
 export * from "./cache";
-export * from "./color";
 export * from "./fetch-resource";
 export * from "./hero-resolvers";
 export * from "./metrics";

package/dist/utils/index.js

@@ -1,5 +1,4 @@
 export * from "./cache";
-export * from "./color";
 export * from "./fetch-resource";
 export * from "./hero-resolvers";
 export * from "./metrics";

package/dist/utils/metrics.d.ts

@@ -1,3 +1,4 @@
 export declare function toBase64Url(input: string): string;
 export declare function buildClickUrl(clickUrlBase: string, targetHref: string): string;
+export declare function fireClickMetric(clickUrl: string): void;
 export declare function fireImpressionWhenVisible(el: HTMLElement, pixelUrl: string): void;

package/dist/utils/metrics.js

@@ -9,11 +9,42 @@ function appendQuery(url, key, value) {
     const sep = url.includes("?") ? "&" : "?";
     return `${url}${sep}${key}=${value}`;
 }
-// Build the final redirect URL the CTA should use
+// Build the tracking URL that encodes the final destination for metrics
 export function buildClickUrl(clickUrlBase, targetHref) {
     const u = encodeURIComponent(toBase64Url(targetHref));
     return appendQuery(clickUrlBase, "u", u);
 }
+// Fire the click tracking URL without relying on a redirect
+// Default to GET so legacy tracking endpoints continue to accept the request
+export function fireClickMetric(clickUrl) {
+    if (typeof window === "undefined")
+        return;
+    if (!clickUrl)
+        return;
+    try {
+        if (typeof fetch === "function") {
+            fetch(clickUrl, {
+                method: "GET",
+                mode: "no-cors",
+                keepalive: true,
+            }).catch(() => {
+                /* no-op */
+            });
+            return;
+        }
+    }
+    catch {
+        // swallow and fall back to <img>
+    }
+    try {
+        const img = new Image();
+        img.referrerPolicy = "strict-origin-when-cross-origin";
+        img.src = clickUrl;
+    }
+    catch {
+        // nothing else we can do
+    }
+}
 // --- View tracking (once per element) ---
 const seenEls = typeof WeakSet !== "undefined" ? new WeakSet() : null;
 export function fireImpressionWhenVisible(el, pixelUrl) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fragment-headless-sdk",
-  "version": "2.1.1",
+  "version": "2.1.3",
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/readme.md

@@ -2,7 +2,27 @@
 
 The official SDK for integrating with Fragment-Shopify CMS. Provides React components, TypeScript types, and utilities for rendering published sections in headless Shopify storefronts.
 
-## ✨ What's New in v2.1.0
+## ✨ What's New in v2.1.3
+
+⚡ **Request Deduplication** - Intelligent request deduplication prevents identical concurrent API calls  
+🚀 **Enhanced Caching** - Improved caching strategy with 60-second revalidation for better performance  
+🔧 **Optimized Fetching** - Consistent parameter handling and smarter cache key generation  
+🛡️ **Anti-Spam Protection** - Built-in protection against redundant API requests
+
+### Previous Release (v2.1.2)
+
+📚 **Enhanced Documentation** - Comprehensive documentation updates highlighting new click tracking features  
+📖 **Better Examples** - Improved usage examples and feature descriptions  
+🎯 **Feature Highlights** - Clear documentation of the enhanced click tracking system
+
+### Previous Release (v2.1.1)
+
+🎯 **Enhanced Click Tracking System** - Improved click tracking architecture with better user experience  
+⚡ **Direct Navigation** - Users go directly to destinations without redirect delays  
+🔗 **Separated Tracking** - Button destinations and click tracking are now handled separately  
+🛠️ **Better Performance** - Non-blocking click tracking that doesn't delay navigation
+
+### Previous Release (v2.1.0)
 
 🎨 **Enhanced Hero Styling System** - New hero resolvers utility with advanced typography, positioning, and layout controls  
 🔤 **Advanced Typography** - Built-in font family support with granular control over sizes and line heights  
@@ -41,6 +61,7 @@ Fragment-Shopify App (CMS) → API Endpoint → fragment-headless-sdk (Consumer)
 - ✅ **TypeScript Support**: Full type definitions for all components and data structures
 - ✅ **Multiple Announcement Types**: Standard, marquee, and countdown announcement variants
 - ✅ **Hero Sections**: Desktop/mobile responsive hero components with video support
+- ✅ **Advanced Click Tracking**: Separated tracking and navigation for optimal user experience
 
 ### Advanced Styling System (v2.0+)
 
@@ -62,6 +83,24 @@ Fragment-Shopify App (CMS) → API Endpoint → fragment-headless-sdk (Consumer)
 - 📝 **Type Safety**: Enhanced TypeScript interfaces for all styling options
 - 🔄 **Backward Compatible**: Works seamlessly with existing Hero implementations
 
+### Request Deduplication & Performance System (v2.1.3+)
+
+- ⚡ **Smart Deduplication**: Prevents identical concurrent API requests automatically
+- 🚀 **Optimized Caching**: 60-second cache revalidation for optimal performance vs freshness
+- 🔧 **Consistent Parameters**: Normalized parameter handling ensures reliable cache keys
+- 🛡️ **Anti-Spam Protection**: Built-in protection against redundant API calls
+- 📊 **Performance Monitoring**: Console logging for deduplication events and debugging
+- 🔄 **Graceful Fallback**: Failed requests retry automatically without affecting user experience
+
+### Enhanced Click Tracking System (v2.1.1+)
+
+- 🎯 **Separated Concerns**: Button destinations and click tracking handled independently
+- ⚡ **Direct Navigation**: Users go directly to destinations without redirect delays
+- 🔗 **Advanced Tracking**: `fireClickMetric()` function with fetch API and image fallback
+- 🛠️ **Non-Blocking**: Click tracking doesn't delay user navigation
+- 🌐 **Cross-Browser**: Works across all modern browsers with appropriate fallbacks
+- 🔄 **Graceful Degradation**: Tracking fails silently without affecting user experience
+
 ---
 
 ## 📦 Installation
@@ -160,11 +199,20 @@ const heroBanners = await fetchResource({
   type: ResourceType.HeroBanners,
 });
 
-// Fetch announcements
+// Fetch announcements with optional parameters
 const announcements = await fetchResource({
   baseUrl: process.env.EXTERNAL_API_URL,
   apiKey: process.env.FRAGMENT_API_KEY,
   type: ResourceType.Announcements,
+  params: {
+    status: "enabled", // Only fetch enabled announcements
+    limit: 10, // Limit to 10 items
+    search: "sale", // Search for announcements containing "sale"
+  },
+  cacheOptions: {
+    revalidate: 30, // Custom 30-second cache revalidation
+    tags: ["announcements"], // Custom cache tags
+  },
 });
 ```
 
@@ -627,13 +675,30 @@ const advancedHeroContent = {
 
 ### `fetchResource<T>(params)`
 
-Fetches sections from your Fragment-Shopify app.
+Fetches sections from your Fragment-Shopify app with intelligent request deduplication and caching.
 
 **Parameters:**
 
 - `baseUrl: string` - URL of your Fragment-Shopify app
 - `apiKey: string` - Fragment API key (format: `keyId:secret`)
 - `type: ResourceType` - Type of resource to fetch
+- `params?: ListParams` - Optional filtering and pagination parameters
+- `fetchImpl?: typeof fetch` - Optional custom fetch implementation
+- `cacheOptions?: CacheOptions` - Optional cache configuration
+
+**ListParams Options:**
+
+- `status?: "enabled" | "disabled"` - Filter by status (defaults to "enabled")
+- `page?: number` - Page number for pagination (defaults to 1)
+- `limit?: number` - Items per page (defaults to 25, max 100)
+- `search?: string` - Search query for filtering
+- `pageFilter?: string` - Filter by page path (e.g., "/collections/sale")
+
+**CacheOptions:**
+
+- `cache?: RequestCache` - Request cache mode (defaults to "force-cache")
+- `revalidate?: number | false` - Next.js revalidation time in seconds (defaults to 60)
+- `tags?: string[]` - Next.js cache tags for selective invalidation
 
 **ResourceType Options:**
 
@@ -642,6 +707,13 @@ Fetches sections from your Fragment-Shopify app.
 
 **Returns:** `Promise<T[]>` - Array of fetched resources
 
+**Performance Features:**
+
+- **Request Deduplication**: Identical concurrent requests are automatically deduplicated
+- **Smart Caching**: 60-second cache revalidation balances performance and freshness
+- **Parameter Normalization**: Consistent cache key generation for reliable deduplication
+- **Error Handling**: Graceful fallbacks with automatic retry on failed requests
+
 ---
 
 ## 🧩 Components

package/dist/utils/color.d.ts

@@ -1,2 +0,0 @@
-export declare function isDarkColor(color: string | undefined | null): boolean;
-export declare function ensureSafeColor(color: string | undefined | null, fallback: string): string;

package/dist/utils/color.js

@@ -1,67 +0,0 @@
-const HEX_COLOR_REGEX = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
-const RGB_COLOR_REGEX = /^rgba?\s*\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})(?:\s*,\s*(\d*\.?\d+))?\s*\)$/i;
-function hexToRgb(color) {
-    if (!HEX_COLOR_REGEX.test(color)) {
-        return null;
-    }
-    let hex = color.slice(1);
-    if (hex.length === 3) {
-        hex = hex
-            .split("")
-            .map((char) => char + char)
-            .join("");
-    }
-    const bigint = parseInt(hex, 16);
-    return {
-        r: (bigint >> 16) & 255,
-        g: (bigint >> 8) & 255,
-        b: bigint & 255,
-    };
-}
-function rgbStringToRgb(color) {
-    const match = color.match(RGB_COLOR_REGEX);
-    if (!match) {
-        return null;
-    }
-    const [, r, g, b] = match;
-    const red = Number(r);
-    const green = Number(g);
-    const blue = Number(b);
-    if ([red, green, blue].some((value) => Number.isNaN(value))) {
-        return null;
-    }
-    return { r: red, g: green, b: blue };
-}
-function normalizeColor(color) {
-    if (!color) {
-        return null;
-    }
-    const trimmed = color.trim();
-    return hexToRgb(trimmed) ?? rgbStringToRgb(trimmed);
-}
-function getRelativeLuminance(rgb) {
-    const transform = (value) => {
-        const channel = value / 255;
-        if (channel <= 0.03928) {
-            return channel / 12.92;
-        }
-        return Math.pow((channel + 0.055) / 1.055, 2.4);
-    };
-    const r = transform(rgb.r);
-    const g = transform(rgb.g);
-    const b = transform(rgb.b);
-    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
-}
-export function isDarkColor(color) {
-    const rgb = normalizeColor(color);
-    if (!rgb) {
-        return false;
-    }
-    return getRelativeLuminance(rgb) < 0.5;
-}
-export function ensureSafeColor(color, fallback) {
-    if (!color) {
-        return fallback;
-    }
-    return isDarkColor(color) ? fallback : color;
-}