fragment-headless-sdk 2.2.1 → 2.3.1

package/dist/utils/attribution.d.ts

@@ -0,0 +1,32 @@
+import { SectionType } from '../constants';
+export interface FragmentAttribution {
+    sectionId: string;
+    sectionType: SectionType;
+    timestamp: number;
+}
+/**
+ * Store attribution data for a section click
+ * Uses sessionStorage for session-scoped attribution (last-click wins)
+ * @param sectionId - The UUID of the section
+ * @param sectionType - The type of section (announcement or hero_banner)
+ */
+export declare function setAttribution(sectionId: string, sectionType: SectionType): void;
+/**
+ * Retrieve stored attribution data
+ * @returns The stored attribution or null if none exists or data is invalid
+ */
+export declare function getAttribution(): FragmentAttribution | null;
+/**
+ * Clear stored attribution data
+ * Called after successful conversion tracking
+ */
+export declare function clearAttribution(): void;
+declare global {
+    interface Window {
+        fragmentAttribution?: {
+            get: () => FragmentAttribution | null;
+            set: (sectionId: string, sectionType: SectionType) => void;
+            clear: () => void;
+        };
+    }
+}

package/dist/utils/attribution.js

@@ -0,0 +1,89 @@
+import { SectionType } from '../constants';
+const STORAGE_KEY = 'fragment_attribution';
+/**
+ * Store attribution data for a section click
+ * Uses sessionStorage for session-scoped attribution (last-click wins)
+ * @param sectionId - The UUID of the section
+ * @param sectionType - The type of section (announcement or hero_banner)
+ */
+export function setAttribution(sectionId, sectionType) {
+    if (typeof sessionStorage === 'undefined')
+        return;
+    const attribution = {
+        sectionId,
+        sectionType,
+        timestamp: Date.now()
+    };
+    try {
+        sessionStorage.setItem(STORAGE_KEY, JSON.stringify(attribution));
+    }
+    catch (e) {
+        // Handle quota exceeded or other storage errors silently
+        console.warn('Fragment: Failed to set attribution', e);
+    }
+}
+/**
+ * Validates that parsed data matches the FragmentAttribution interface
+ */
+function isValidAttribution(data) {
+    if (!data || typeof data !== 'object')
+        return false;
+    const obj = data;
+    return (typeof obj.sectionId === 'string' &&
+        (obj.sectionType === SectionType.Announcement || obj.sectionType === SectionType.HeroBanner) &&
+        typeof obj.timestamp === 'number');
+}
+/**
+ * Retrieve stored attribution data
+ * @returns The stored attribution or null if none exists or data is invalid
+ */
+export function getAttribution() {
+    if (typeof sessionStorage === 'undefined')
+        return null;
+    try {
+        const stored = sessionStorage.getItem(STORAGE_KEY);
+        if (!stored)
+            return null;
+        const parsed = JSON.parse(stored);
+        if (!isValidAttribution(parsed)) {
+            // Invalid data - clear it and return null
+            sessionStorage.removeItem(STORAGE_KEY);
+            return null;
+        }
+        return parsed;
+    }
+    catch (e) {
+        // Handle parse errors or other issues
+        console.warn('Fragment: Failed to get attribution', e);
+        // Clear potentially corrupted data
+        try {
+            sessionStorage.removeItem(STORAGE_KEY);
+        }
+        catch {
+            // Ignore errors when clearing
+        }
+        return null;
+    }
+}
+/**
+ * Clear stored attribution data
+ * Called after successful conversion tracking
+ */
+export function clearAttribution() {
+    if (typeof sessionStorage === 'undefined')
+        return;
+    try {
+        sessionStorage.removeItem(STORAGE_KEY);
+    }
+    catch (e) {
+        console.warn('Fragment: Failed to clear attribution', e);
+    }
+}
+// Make globally accessible for Shopify theme integrations
+if (typeof window !== 'undefined') {
+    window.fragmentAttribution = {
+        get: getAttribution,
+        set: setAttribution,
+        clear: clearAttribution
+    };
+}

package/dist/utils/index.d.ts

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

package/dist/utils/index.js

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

package/dist/utils/metrics.d.ts

@@ -8,4 +8,8 @@ declare global {
         dataLayer?: unknown[];
     }
 }
+/**
+ * Fire a scroll past metric when user scrolls past a section
+ */
+export declare function fireScrollPastMetric(measurementId: string | undefined, sectionType: SectionType, sectionId: string): void;
 export declare function fireImpressionWhenVisible(el: HTMLElement, pixelUrl: string, measurementId?: string, sectionType?: SectionType, sectionId?: string): void;

package/dist/utils/metrics.js

@@ -1,4 +1,5 @@
 import { SectionType } from "../constants";
+import { setAttribution } from "./attribution";
 // --- Unicode-safe Base64URL ---
 export function toBase64Url(input) {
     // Handles emojis & non-ASCII reliably:
@@ -22,6 +23,10 @@ export function fireClickMetric(clickUrl, measurementId, sectionType, sectionId)
         return;
     if (!clickUrl)
         return;
+    // Store attribution for potential purchase/add-to-cart
+    if (sectionType && sectionId) {
+        setAttribution(sectionId, sectionType);
+    }
     // Send to GA4 first (if available)
     if (measurementId && sectionType && sectionId) {
         sendGA4Event("click", measurementId, sectionType, sectionId);
@@ -65,7 +70,7 @@ function getSectionEventName(baseEventName, sectionType) {
  * Only sends section_id parameter - event name already indicates section type.
  * This is a fire-and-forget operation that won't throw errors.
  */
-function sendGA4Event(baseEventName, measurementId, sectionType, sectionId) {
+function sendGA4Event(baseEventName, measurementId, sectionType, sectionId, additionalParams) {
     if (typeof window === "undefined")
         return;
     if (!measurementId)
@@ -76,12 +81,25 @@ function sendGA4Event(baseEventName, measurementId, sectionType, sectionId) {
         const eventName = getSectionEventName(baseEventName, sectionType);
         window.gtag("event", eventName, {
             section_id: sectionId,
+            ...additionalParams,
         });
     }
     catch {
         // Silently fail - don't break tracking if GA4 fails
     }
 }
+/**
+ * Fire a scroll past metric when user scrolls past a section
+ */
+export function fireScrollPastMetric(measurementId, sectionType, sectionId) {
+    if (typeof window === "undefined")
+        return;
+    if (!measurementId || !sectionType || !sectionId)
+        return;
+    sendGA4Event("scroll_past", measurementId, sectionType, sectionId, {
+        engagement_type: "scroll_past",
+    });
+}
 // --- View tracking (once per element) ---
 const seenEls = typeof WeakSet !== "undefined" ? new WeakSet() : null;
 export function fireImpressionWhenVisible(el, pixelUrl, measurementId, sectionType, sectionId) {
@@ -92,6 +110,7 @@ export function fireImpressionWhenVisible(el, pixelUrl, measurementId, sectionTy
     if (seenEls && seenEls.has(el))
         return; // de-dupe by element
     let fired = false;
+    let hasScrolledPast = false;
     const img = new Image();
     const fire = () => {
         if (fired)
@@ -119,6 +138,16 @@ export function fireImpressionWhenVisible(el, pixelUrl, measurementId, sectionTy
         for (const e of entries) {
             if (e.isIntersecting && e.intersectionRatio >= 0.3) {
                 fire();
+            }
+            else if (!e.isIntersecting &&
+                !hasScrolledPast &&
+                e.boundingClientRect.top < 0 &&
+                fired) {
+                // User scrolled past the section (it's above viewport and was previously visible)
+                hasScrolledPast = true;
+                if (measurementId && sectionType && sectionId) {
+                    fireScrollPastMetric(measurementId, sectionType, sectionId);
+                }
                 io.disconnect();
                 break;
             }

package/docs/CHANGELOG.md

@@ -0,0 +1,542 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+### [2.3.1] - 2026-01-25
+
+### 🔧 Technical Improvements
+
+- **Enhanced Error Handling** – Improved error handling in attribution functions
+  - Better error messages and logging
+  - Automatic cleanup of corrupted data
+  - Graceful degradation when sessionStorage is unavailable
+
+## [2.3.0] - 2026-01-25
+
+### ✨ Attribution Tracking System
+
+- **Session-Based Attribution** – New attribution tracking system for purchase/add-to-cart attribution
+  - Automatically stores attribution data when users click section buttons
+  - Uses sessionStorage for session-scoped attribution (last-click wins)
+  - Tracks section ID, section type, and timestamp for each click
+
+### 📚 Documentation
+
+- **New Attribution Section** – Added comprehensive documentation for attribution tracking
+  - Usage examples for Shopify theme integrations
+  - Programmatic access examples
+  - Use cases for purchase and add-to-cart attribution
+
+## [2.2.0] - 2025-01-18
+
+### ✨ Google Analytics 4 (GA4) Integration
+
+- **GA4 Event Tracking** – Added comprehensive Google Analytics 4 integration for section tracking
+  - Automatic `section_view` events when sections become visible
+  - Automatic `section_click` events when users interact with buttons
+  - Configurable via `measurementId`, `sectionId`, and `sectionType` fields
+  - Graceful fallback if GA4 is not available (doesn't break functionality)
+
+## [2.1.9] - 2025-12-26
+
+### ✨ Announcement Resolvers System
+
+- **New Announcement Resolvers Utility** – Added centralized color resolution system for Announcement components
+  - `resolveAnnouncementColors()` – Intelligent color resolution with guaranteed fallback values
+  - `resolveCountdownColors()` – Dedicated color resolver for countdown timer styling
+  - Supports both new format (`colors.background`) and legacy format (`bgColor`) for backward compatibility
+
+### 🔧 Component Refactoring
+
+- **Centralized Color Resolution** – Refactored all Announcement components to use the new resolver system
+  - Improved code maintainability and consistency across all announcement types
+
+### 🎨 Countdown Timer Styling Improvements
+
+- **Enhanced Layout** – Improved visual spacing and sizing
+  - Added `gap-1` between countdown digits
+  - Reduced digit font size from `text-xl` to `text-lg`
+  - Changed line height from `leading-none` to `leading-tight`
+
+### 🔧 Type System Updates
+
+- **Enhanced Type Definitions** – Updated `IAnnouncement` and `IHero` interfaces
+  - Added `active_duration_seconds`, `last_activated_at`, and `last_deactivated_at` fields
+
+### 📚 Documentation
+
+- **New Announcement Resolvers Documentation** – Added comprehensive guide for the new resolver system
+
+## [2.1.8] - 2025-12-25
+
+### ✨ Countdown Timer Styling Enhancements
+
+- **Enhanced Countdown Timer Color Tokens** – Added comprehensive color customization for countdown timers
+  - `counterDigitColor` – Customize the color of countdown digits (default: `#FFFFFF`)
+  - `counterDigitBackgroundColor` – Customize the background color of countdown digits (default: `#000000`)
+  - `counterTextColor` – Customize the color of labels and separators (default: uses `counterDigitColor`)
+- **Fixed Token Resolution** – Corrected `counterTextColor` token resolution to use proper fallback handling
+- **Documentation Updates** – Added comprehensive countdown timer styling documentation to README
+
+## [2.1.5] - 2025-12-05
+
+### 🔧 Type System Updates
+
+- **Enhanced Type Definitions** – Updated `IAnnouncement` and `IHero` interfaces to match Supabase schema
+  - Added `active_start_date: string | null` field
+  - Added `active_end_date: string | null` field
+  - Made `created_at` and `updated_at` nullable
+  - Made `page` field nullable in `IHero`
+
+### 🗑️ Breaking Changes
+
+- **Removed Theme & Variant System** – Simplified styling system by removing unused theme/variant abstractions
+  - Removed `theme` property from `IFragmentStyling`
+  - Removed `variant` property from `IFragmentStyling`
+  - Focus now exclusively on design tokens, slots, responsive design, and state-based styling
+  - Updated all documentation to reflect the simplified system
+
+## [2.1.4] - 2025-11-18
+
+### ✨ UI/UX Improvements
+
+- **Countdown Timer Enhancements** – Improved countdown timer visual design
+  - Removed background color from countdown digits for cleaner appearance
+  - Increased digit font size for better visibility
+  - Shortened label text: "Minutes" → "Mins", "Seconds" → "Secs"
+
+- **Announcement Component Updates** – Enhanced announcement functionality
+  - Countdown timers can now display alongside buttons when both are enabled
+  - Improved layout flexibility for countdown announcements with CTAs
+
+## [2.1.2] - 2025-10-30
+
+### 📚 Documentation Updates
+
+- **Enhanced README** – Updated documentation to highlight new click tracking features
+- **Feature Highlights** – Added comprehensive documentation for the enhanced click tracking system
+- **Usage Examples** – Improved examples showing the separation of button destinations and tracking
+
+## [2.1.1] - 2025-10-30
+
+### 🎯 Enhanced Click Tracking System
+
+- **Improved Click Tracking Architecture** – Separated button destinations from click tracking for better user experience
+  - `buttonHref` now contains the actual destination URL (no redirect)
+  - `clickHref` contains the tracking URL for metrics collection
+  - Users go directly to intended destinations instead of through redirects
+- **New `fireClickMetric()` Function** – Advanced click tracking without relying on redirects
+  - Uses `fetch()` with `no-cors` mode and `keepalive` for reliable tracking
+  - Falls back to Image pixel tracking for maximum compatibility
+  - Handles server-side rendering gracefully
+- **Removed Automatic New Tab Behavior** – Links no longer force `target="_blank"`
+  - Provides more natural user experience
+  - Allows developers to control link behavior explicitly
+  - Maintains accessibility with proper ARIA labels
+
+### 🛠 Technical Improvements
+
+- **Enhanced Component Props** – Both Hero and Announcement components now accept separate tracking parameters
+  - `buttonHref` for the actual destination
+  - `clickHref` for tracking metrics
+- **Better Error Handling** – Click tracking fails gracefully without affecting user experience
+- **Performance Optimized** – Non-blocking click tracking that doesn't delay navigation
+- **Cross-Browser Compatible** – Works across all modern browsers with appropriate fallbacks
+
+### 📝 Usage Examples
+
+```typescript
+// The SDK automatically handles the separation of concerns
+const heroContent = {
+  title: "Shop Now",
+  buttonText: "Get Started",
+  buttonLink: "https://example.com/products", // Direct destination
+  clickUrlBase: "https://tracking.example.com/click", // Tracking base
+  // SDK automatically creates:
+  // - buttonHref: "https://example.com/products" (direct link)
+  // - clickHref: "https://tracking.example.com/click?u=..." (tracking)
+};
+
+<Hero content={heroContent} />;
+```
+
+### ⚡ Performance Benefits
+
+- **Faster Navigation** – Users go directly to destinations without redirect delays
+- **Reliable Tracking** – Click metrics are captured even if users navigate away quickly
+- **Better SEO** – Direct links improve search engine crawling and indexing
+- **Enhanced UX** – More predictable link behavior for better user experience
+
+### 🔄 Backward Compatibility
+
+- **No Breaking Changes** – All existing implementations continue to work
+- **Automatic Upgrade** – New tracking system activates automatically when `clickUrlBase` is present
+- **Legacy Support** – Existing tracking URLs continue to function as before
+
+## [2.1.0] - 2025-10-27
+
+### 🎨 Enhanced Hero Styling System
+
+- **New Hero Resolvers Utility** – Comprehensive utility system for advanced Hero component customization
+  - `resolveHeroColors()` – Intelligent color resolution with fallback handling
+  - `resolveHeroTypography()` – Typography settings with font family, size, and line height control
+  - `resolveContentWidthClass()` – Dynamic content width management
+  - `resolvePosition()` – Content positioning (left, center, right alignment)
+  - `resolveHeight()` – Flexible height configuration
+  - `renderText()` – Unified text rendering with typography and styling support
+
+### ✨ Advanced Typography Features
+
+- **Font Family Support** – Built-in support for popular font families:
+  - Roboto, Open Sans, Lato, Montserrat, Poppins, Inter, Nunito Sans, Source Sans Pro
+  - Custom font family support through `FontKey` type system
+- **Responsive Typography** – Granular control over font sizes and line heights
+  - Separate title and description typography settings
+  - Tailwind CSS class integration for responsive design
+- **Typography Tokens** – New styling tokens for enhanced typography control:
+  - `titleFontSize`, `titleLineHeight`, `titleFont`
+  - `descriptionFontSize`, `descriptionLineHeight`, `descriptionFont`
+
+### 🏗️ Layout & Positioning Enhancements
+
+- **Content Positioning** – New positioning system for Hero content alignment
+  - Left, center, and right alignment options
+  - Responsive positioning with proper text alignment
+- **Content Width Control** – Dynamic content width management
+  - Configurable content container widths
+  - Responsive design integration
+- **Height Management** – Flexible height configuration system
+  - Custom height classes support
+  - Default height fallbacks
+
+### 🎯 Developer Experience Improvements
+
+- **Type Safety** – Enhanced TypeScript interfaces for all new features
+  - `HeroResolvedColors` interface for color resolution
+  - `HeroTypographySettings` interface for typography configuration
+  - `FontKey` type for font family validation
+- **Utility Functions** – New helper functions for common operations
+  - `joinClassNames()` – Safe CSS class concatenation
+  - `fallbackColor()` – Color value validation with fallbacks
+- **Better Defaults** – Comprehensive default values for all styling options
+  - `DEFAULT_COLORS` for color fallbacks
+  - `DEFAULT_TYPOGRAPHY` for typography defaults
+  - `FONT_FAMILY_MAP` for font family mappings
+
+### 🔄 Backward Compatibility
+
+- **Seamless Migration** – All existing Hero components continue to work without changes
+- **Progressive Enhancement** – New features are opt-in and don't affect existing implementations
+- **Legacy Support** – Existing styling approaches remain fully supported
+
+### 📝 Usage Examples
+
+```typescript
+// Enhanced Hero with new typography and positioning
+const heroContent = {
+  title: "Welcome to Our Store",
+  description: "Discover amazing products",
+  buttonText: "Shop Now",
+  buttonLink: "/products",
+  imageUrl: "https://example.com/hero.jpg",
+
+  styling: {
+    tokens: {
+      colors: {
+        title: "#ffffff",
+        text: "#f0f0f0",
+        button: "#007bff",
+        buttonText: "#ffffff",
+        background: "#1a1a1a",
+      },
+      typography: {
+        titleFont: "montserrat",
+        titleFontSize: "text-6xl",
+        titleLineHeight: "leading-tight",
+        descriptionFont: "inter",
+        descriptionFontSize: "text-xl",
+        descriptionLineHeight: "leading-relaxed",
+      },
+      layout: {
+        contentWidth: "max-w-4xl",
+        position: "center",
+        height: "min-h-screen",
+      },
+    },
+  },
+};
+```
+
+### 🛠 Technical Improvements
+
+- **Performance Optimized** – Efficient color and typography resolution
+- **Memory Efficient** – Optimized utility functions with minimal overhead
+- **Tree Shakeable** – Individual utility functions can be imported separately
+- **CSS-in-JS Ready** – Full compatibility with styled-components and emotion
+
+## [1.0.6] - 2025-10-16
+
+### 🚀 Next.js Caching Fix
+
+- **Fixed Vercel/Next.js Caching Issues** – Resolved aggressive caching that prevented fresh data from appearing in production deployments
+  - Added `cache: 'no-store'` by default for all `fetchResource()` calls
+  - Added Next.js-specific `revalidate: 0` configuration
+  - Added cache-busting headers (`Cache-Control`, `Pragma`) to prevent CDN caching
+  - Smart environment detection for Next.js vs other frameworks
+
+### ✨ New Cache Management Features
+
+- **Cache Configuration Options** – Added optional `cacheOptions` parameter to `fetchResource()`
+  - `cache`: Control request cache mode (default: 'no-store' for fresh data)
+  - `revalidate`: Next.js revalidation time in seconds (default: 0)
+  - `tags`: Next.js cache tags for selective invalidation
+- **Cache Invalidation Utilities** – New helper functions for cache management
+  - `revalidateFragmentCache()` – Invalidate all or specific Fragment caches
+  - `revalidateResourceType()` – Invalidate cache for specific resource type
+  - `revalidateAllFragmentCaches()` – Clear all Fragment-related caches
+  - `createCacheTag()` / `createCacheTags()` – Generate cache tags
+
+### 🛠 Technical Improvements
+
+- **Environment Detection** – Automatic Next.js environment detection for optimal cache settings
+- **Backward Compatibility** – All existing code continues to work without changes
+- **TypeScript Support** – Full type definitions for new cache options
+
+### 📝 Usage Examples
+
+```typescript
+// Default behavior - always fresh data (recommended)
+const announcements = await fetchResource({
+  baseUrl: process.env.FRAGMENT_BASE_URL,
+  apiKey: process.env.FRAGMENT_API_KEY,
+  type: ResourceType.Announcements,
+});
+
+// Optional: Enable caching for performance
+const cachedHeroes = await fetchResource({
+  baseUrl: process.env.FRAGMENT_BASE_URL,
+  apiKey: process.env.FRAGMENT_API_KEY,
+  type: ResourceType.HeroBanners,
+  cacheOptions: {
+    cache: "default",
+    revalidate: 300, // 5 minutes
+  },
+});
+
+// Cache invalidation (server-side only)
+import { revalidateResourceType } from "fragment-headless-sdk";
+await revalidateResourceType(ResourceType.Announcements);
+```
+
+### ⚠️ Migration Notes
+
+- **No breaking changes** – Existing code works without modification
+- **Fresh data by default** – Your database updates will now appear immediately in production
+- **Opt-in caching** – Use `cacheOptions` if you want to enable caching for performance
+
+## [1.0.5] - 2025-09-28
+
+### ✨ New Features
+
+- **Metrics Tracking** – Added built-in view and click tracking for both **Hero** and **Announcement** sections.
+  - Each resource’s `content` object now includes two server-generated fields:
+    - `impressionUrl` – 1×1 pixel URL automatically fired when the component enters the viewport.
+    - `clickUrlBase` – base redirect URL used to record button clicks before sending the user to the final destination.
+  - The SDK’s `<Hero>` and `<Announcement>` components now automatically:
+    - trigger a view pixel when visible, and
+    - wrap their CTA buttons with a signed click-tracking redirect.
+
+### 🛠 Technical Notes
+
+- The `makeSignedMetricUrls` helper was refactored to attach `impressionUrl` and `clickUrlBase` **inside the `content` object** for each item returned by the API.
+- New client-side utilities exported from `utils`:
+  - `buildClickUrl()` – safely appends the final destination (`&u=...`) to a signed `clickUrlBase`.
+  - `fireImpressionWhenVisible()` – fires a pixel only once when an element is at least 30 % visible.
+
+### ⚠️ Migration Notes
+
+- **No breaking changes.**  
+  Existing components continue to work; the new tracking is automatic when you upgrade to v1.0.5.
+- If you build custom CTAs outside the provided components, use the new helpers to track clicks and views manually.
+
+## [1.0.4] - 2025-09-27
+
+- **Types:** `IHero` now includes `views_count: number` and `clicks_count: number`.
+
+### 📝 Notes
+
+- No breaking changes..
+
+## [1.0.3] - 2025-09-21
+
+### 🎨 UI/UX Improvements
+
+- **Announcement Type Rename** - Changed `AnnouncementType.Announcement` to `AnnouncementType.Static` for better clarity
+- **Countdown Timer Styling** - Removed white background from countdown timer for cleaner appearance
+- **Layout Optimization** - Improved announcement banner layout with:
+  - Removed top/bottom padding (`py-3`) for more compact design
+  - Added 50px minimum height for consistent banner sizing
+  - Enhanced vertical centering of all content elements
+- **Timer Digit Sizing** - Made countdown timer digits smaller and more compact:
+  - Reduced digit size from 24×28px to 20×24px
+  - Changed font size from `text-xl` to `text-base`
+
+### 🔧 Technical Changes
+
+- Updated `announcementTypes` array to reflect new "Static" label
+- Improved flexbox layout for better vertical alignment
+- Maintained responsive design across all screen sizes
+
+## [1.0.2] - 2025-09-20
+
+### 🔄 Breaking Changes
+
+- **Component Naming** - Renamed `Banner` component and all related types to `Announcement`
+  - `Banner` → `Announcement`
+  - `IBannerContent` → `IAnnouncementContent`
+  - `IBanner` → `IAnnouncement`
+  - `BannerType` → `AnnouncementType`
+  - `BannerStatus` → `AnnouncementStatus`
+  - `BannerButton` → `AnnouncementButton`
+  - `BannerStyles` → `AnnouncementStyles`
+  - `bannerHtml` property → `announcementHtml`
+
+- **Resource Type Updates** - Updated resource type enums for consistency
+  - `ResourceType.HeroSections` → `ResourceType.HeroBanners`
+  - `ResourceType.Banners` → `ResourceType.Announcements`
+
+### 🔗 API Endpoint Changes
+
+- Updated API endpoints to match new naming:
+  - `/api/v1/hero-sections` → `/api/v1/hero-banners`
+  - `/api/v1/banners` → `/api/v1/announcements`
+
+### 📚 Documentation
+
+- Updated all documentation to reflect new component and type names
+- Updated README.md examples with new ResourceType values
+- Updated code examples throughout
+
+### 🛠️ Migration Guide
+
+To update your existing code:
+
+```typescript
+// Before (v1.0.1)
+import {
+  Banner,
+  BannerType,
+  IBannerContent,
+  ResourceType,
+} from "fragment-headless-sdk";
+
+const banners = await fetchResource({
+  type: ResourceType.Banners,
+});
+
+<Banner content={bannerContent} type={BannerType.Standard} />;
+
+// After (v1.0.2)
+import {
+  Announcement,
+  AnnouncementType,
+  IAnnouncementContent,
+  ResourceType,
+} from "fragment-headless-sdk";
+
+const announcements = await fetchResource({
+  type: ResourceType.Announcements,
+});
+
+<Announcement
+  content={announcementContent}
+  type={AnnouncementType.Announcement}
+/>;
+```
+
+## [1.0.1] - 2025-09-07
+
+### 🎉 Initial Release
+
+The official SDK for integrating with fragment-shopify CMS. Production-ready with full API key authentication support.
+
+### Features
+
+- **Complete TypeScript Support** - Full type definitions for all components and API responses
+- **React Components** - Pre-built Hero and Announcement components with responsive design
+- **API Integration** - Built-in utilities for fetching sections from fragment-shopify app
+- **Production Ready** - Full API key authentication with v1 endpoints
+- **Tailwind CSS** - Styled components with customizable design system
+
+### Components
+
+- **Hero Component** - Responsive hero sections with desktop/mobile layouts
+  - Support for images, videos, and call-to-action buttons
+  - Customizable content and styling
+- **Announcement Component** - Flexible announcement bars with multiple display types
+  - Standard, marquee, and countdown announcement types
+  - `AnnouncementButton` and `CountdownTimer` sub-components
+
+### API Integration
+
+- **`fetchResource()` Function** - Simple API for fetching sections
+- **API Key Authentication** - Secure authentication using `keyId:secret` format
+- **v1 Endpoints** - Production endpoints (`/api/v1/announcements`, `/api/v1/hero-banners`)
+- **Error Handling** - Comprehensive error handling and logging
+- **Type Safety** - Full TypeScript support for all API responses
+
+### Usage
+
+```tsx
+import {
+  fetchResource,
+  ResourceType,
+  Hero,
+  Announcement,
+} from "fragment-headless-sdk";
+
+// Fetch data
+const heroes = await fetchResource({
+  baseUrl: process.env.EXTERNAL_API_URL,
+  apiKey: process.env.FRAGMENT_API_KEY,
+  type: ResourceType.HeroBanners,
+});
+
+// Render components
+<Hero content={heroes[0]?.content} />;
+```
+
+### Environment Variables
+
+```bash
+EXTERNAL_API_URL=https://your-fragment-app.vercel.app
+FRAGMENT_API_KEY=bh_a1b2c3d4e5f6:your-64-char-secret
+```
+
+---
+
+## Upcoming Changes
+
+### v1.1.0 (Planned)
+
+- Enhanced error handling with specific error types
+- Support for additional section types
+- Caching and performance optimizations
+
+### v1.2.0 (Planned)
+
+- Real-time updates via webhooks
+- Advanced filtering and sorting options
+- Batch operations support
+- TypeScript strict mode compatibility
+
+---
+
+## Support
+
+- **Documentation**: [README.md](./README.md)
+- **NPM Package**: https://www.npmjs.com/package/fragment-shopify-sdk
+- **Issues**: Please report issues in the GitHub repository

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fragment-headless-sdk",
-  "version": "2.2.1",
+  "version": "2.3.1",
   "license": "MIT",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +12,8 @@
     "./styles": "./dist/styles/fragment-sdk.css"
   },
   "files": [
-    "dist"
+    "dist",
+    "docs/CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc"

package/readme.md

@@ -4,7 +4,7 @@ The official SDK for integrating with Fragment-Shopify CMS. Provides React compo
 
 ## ✨ What's New
 
-**v2.2.0** - Google Analytics 4 (GA4) integration with automatic section tracking
+**v2.3.1** - Enhanced attribution tracking with session storage and global API
 
 > See [CHANGELOG.md](./docs/CHANGELOG.md) for full release history
 
@@ -80,6 +80,15 @@ Fragment-Shopify App (CMS) → API Endpoint → fragment-headless-sdk (Consumer)
 - 🛡️ **Graceful Fallback**: Works even if GA4 is not configured (doesn't break functionality)
 - 📦 **Exported Types**: `SectionType` enum available for consumer use
 
+### Attribution Tracking System (v2.4.0+)
+
+- 🎯 **Session-Based Attribution**: Tracks which section was clicked for purchase/add-to-cart attribution
+- 💾 **SessionStorage Integration**: Uses sessionStorage for session-scoped attribution (last-click wins)
+- 🌐 **Global API Access**: Exposed as `window.fragmentAttribution` for Shopify theme integrations
+- 🔒 **Type-Safe**: Full TypeScript support with proper type definitions
+- ✅ **Data Validation**: Automatic validation and cleanup of corrupted attribution data
+- 🧹 **Auto-Cleanup**: Invalid or corrupted data is automatically cleared from storage
+
 ---
 
 ## 📦 Installation
@@ -117,7 +126,7 @@ module.exports = {
     "./components/**/*.{js,ts,jsx,tsx,mdx}",
     path.join(
       __dirname,
-      "node_modules/fragment-headless-sdk/dist/**/*.{js,ts,jsx,tsx}"
+      "node_modules/fragment-headless-sdk/dist/**/*.{js,ts,jsx,tsx}",
     ),
   ],
   theme: {
@@ -481,6 +490,105 @@ const announcementContent = {
 };
 ```
 
+## 🎯 Attribution Tracking
+
+The SDK automatically tracks which section was clicked for attribution purposes. This is useful for tracking conversions (purchases, add-to-cart) back to the original section interaction.
+
+### Automatic Attribution
+
+When a user clicks a button in a Hero or Announcement section, the SDK automatically stores attribution data in `sessionStorage`:
+
+```typescript
+// Attribution is automatically set when clicks occur
+// No additional code needed - it happens automatically!
+```
+
+### Global API (Shopify Theme Integration)
+
+For Shopify theme integrations, attribution data is exposed globally via `window.fragmentAttribution`:
+
+```javascript
+// Get current attribution data
+const attribution = window.fragmentAttribution.get();
+// Returns: { sectionId: "uuid", sectionType: "announcement" | "hero_banner", timestamp: 1234567890 }
+// Or: null if no attribution exists
+
+// Manually set attribution (usually not needed - SDK handles this automatically)
+window.fragmentAttribution.set("section-uuid", "announcement");
+
+// Clear attribution (e.g., after successful conversion tracking)
+window.fragmentAttribution.clear();
+```
+
+### Programmatic Access
+
+You can also import and use attribution functions directly:
+
+```typescript
+import { getAttribution, clearAttribution } from "fragment-headless-sdk";
+
+// Get attribution data
+const attribution = getAttribution();
+if (attribution) {
+  console.log(`User clicked section: ${attribution.sectionId}`);
+  console.log(`Section type: ${attribution.sectionType}`);
+  console.log(`Clicked at: ${new Date(attribution.timestamp)}`);
+}
+
+// Clear attribution after tracking conversion
+clearAttribution();
+```
+
+### Use Cases
+
+**Purchase Attribution:**
+
+```javascript
+// In your Shopify checkout success page
+if (window.fragmentAttribution) {
+  const attribution = window.fragmentAttribution.get();
+  if (attribution) {
+    // Track purchase back to the section click
+    // e.g., send to analytics, update database, etc.
+    trackPurchase(attribution.sectionId, attribution.sectionType);
+
+    // Clear attribution after tracking
+    window.fragmentAttribution.clear();
+  }
+}
+```
+
+**Add-to-Cart Attribution:**
+
+```javascript
+// In your add-to-cart handler
+if (window.fragmentAttribution) {
+  const attribution = window.fragmentAttribution.get();
+  if (attribution) {
+    // Track add-to-cart back to the section click
+    trackAddToCart(attribution.sectionId, attribution.sectionType);
+  }
+}
+```
+
+### Attribution Data Structure
+
+```typescript
+interface FragmentAttribution {
+  sectionId: string; // UUID of the section that was clicked
+  sectionType: SectionType; // "announcement" | "hero_banner"
+  timestamp: number; // Unix timestamp of when the click occurred
+}
+```
+
+### Features
+
+- ✅ **Session-Scoped**: Attribution data persists for the browser session only
+- ✅ **Last-Click Wins**: New clicks overwrite previous attribution data
+- ✅ **Type-Safe**: Full TypeScript support with proper type definitions
+- ✅ **Data Validation**: Automatically validates and cleans corrupted data
+- ✅ **Graceful Degradation**: Works even if sessionStorage is unavailable
+
 ## 🔑 API Key Setup
 
 Before using the SDK, you need to generate an API key from your Fragment-Shopify app: