fragment-headless-sdk 1.0.1

package/dist/components/Banner/BannerButton.d.ts

@@ -0,0 +1,5 @@
+import React from "react";
+import { IBannerContent } from "../../types";
+export default function BannerButton({ content }: {
+    content: IBannerContent;
+}): React.JSX.Element;

package/dist/components/Banner/BannerButton.js

@@ -0,0 +1,21 @@
+import React from "react";
+import { ButtonType } from "../../constants";
+export default function BannerButton({ content }) {
+    return (React.createElement("a", { href: content.buttonLink || "#", className: "whitespace-nowrap rounded-md px-3 py-2 font-medium text-base no-underline text-white hover:cursor-pointer hover:opacity-70", style: {
+            ...(content.buttonType === ButtonType.Text
+                ? {
+                    textDecoration: "underline",
+                    color: content.textColor,
+                }
+                : {
+                    backgroundColor: content.buttonColor,
+                    color: content.buttonTextColor,
+                }),
+        }, ...(content.buttonLink
+            ? { target: "_blank", rel: "noopener noreferrer" }
+            : {}), onClick: (e) => {
+            if (!content.buttonLink) {
+                e.preventDefault();
+            }
+        } }, content.buttonText));
+}

package/dist/components/Banner/BannerStyles.d.ts

@@ -0,0 +1,3 @@
+export declare function BannerStyles({ seconds }: {
+    seconds?: number;
+}): null;

package/dist/components/Banner/BannerStyles.js

@@ -0,0 +1,33 @@
+"use client";
+import { useEffect } from "react";
+export function BannerStyles({ seconds = 15 }) {
+    useEffect(() => {
+        const style = document.createElement("style");
+        style.id = "banner-styles"; // Ensure unique ID to avoid duplicates
+        style.textContent = `
+      @keyframes marquee {
+        0% {
+          transform: translateX(100%);
+        }
+        100% {
+          transform: translateX(-100%);
+        }
+      }
+
+      .animate-marquee {
+        animation: marquee ${seconds}s linear infinite;
+      }
+
+      .Polaris-Page {
+        padding-bottom: 4rem !important;
+      }
+    `;
+        if (!document.getElementById("banner-styles")) {
+            document.head.appendChild(style);
+        }
+        return () => {
+            document.getElementById("banner-styles")?.remove();
+        };
+    }, [seconds]);
+    return null;
+}

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

@@ -0,0 +1,5 @@
+import React from "react";
+import { IBannerContent } from "../../types";
+export default function CountdownTimer({ content, }: {
+    content: IBannerContent;
+}): React.JSX.Element;

package/dist/components/Banner/CountdownTimer.js

@@ -0,0 +1,42 @@
+import React, { useEffect, useState } from "react";
+export default function CountdownTimer({ content, }) {
+    const [timeLeft, setTimeLeft] = useState({
+        days: "00",
+        hours: "00",
+        minutes: "00",
+        seconds: "00",
+    });
+    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 });
+        };
+        updateTimer();
+        const interval = setInterval(updateTimer, 1000);
+        return () => clearInterval(interval);
+    }, [content.counterEndDate]);
+    const renderBlock = (value, label) => (React.createElement("div", { className: "flex flex-col items-center" },
+        React.createElement("div", { className: "flex gap-1" }, value.split("").map((digit, i) => (React.createElement("span", { key: i, className: "w-6 h-7 rounded bg-black text-white text-xl font-bold flex items-center justify-center", style: {
+                backgroundColor: content.counterBgColor || "#000000",
+                color: content.counterDigitColor || "#FFFFFF",
+            } }, digit)))),
+        React.createElement("span", { className: "mt-0.5 text-xs" }, label)));
+    return (React.createElement("div", { className: "flex items-center gap-1 bg-gray-100 rounded" },
+        renderBlock(timeLeft.days, "Days"),
+        React.createElement("span", { className: "text-xl font-semibold -mt-4" }, ":"),
+        renderBlock(timeLeft.hours, "Hours"),
+        React.createElement("span", { className: "text-xl font-semibold -mt-4" }, ":"),
+        renderBlock(timeLeft.minutes, "Minutes"),
+        React.createElement("span", { className: "text-xl font-semibold -mt-4" }, ":"),
+        renderBlock(timeLeft.seconds, "Seconds")));
+}

package/dist/components/Banner/index.d.ts

@@ -0,0 +1,8 @@
+import React from "react";
+import { BannerType } from "../../constants";
+import { IBannerContent } from "../../types";
+export default function ({ content, type, handleClose, }: {
+    content: IBannerContent;
+    type: BannerType;
+    handleClose: () => void;
+}): React.JSX.Element;

package/dist/components/Banner/index.js

@@ -0,0 +1,27 @@
+import React from "react";
+import { BannerType, ButtonType } from "../../constants";
+import BannerButton from "./BannerButton";
+import { BannerStyles } from "./BannerStyles";
+import CountdownTimer from "./CountdownTimer";
+export default function ({ content, type, handleClose, }) {
+    return (React.createElement("div", { className: "relative w-full", style: {
+            backgroundColor: content.bgColor,
+            color: content.textColor,
+        } },
+        React.createElement(BannerStyles, null),
+        React.createElement("div", { className: "relative mx-auto flex max-w-screen-xl flex-col md:flex-row items-center justify-center gap-4 px-4 py-3 text-center md:text-left" },
+            type === BannerType.Marquee ? (React.createElement("div", { className: "flex w-full flex-col md:flex-row items-center justify-between gap-2 md:gap-4 overflow-hidden md:pr-8" },
+                React.createElement("div", { className: "w-full md:flex-1 overflow-hidden" },
+                    React.createElement("div", { className: "whitespace-nowrap animate-marquee" },
+                        React.createElement("div", { className: "inline-block max-w-none text-base", dangerouslySetInnerHTML: {
+                                __html: content.bannerHtml || "",
+                            } }))),
+                content.buttonText && content.buttonType !== ButtonType.None && (React.createElement(BannerButton, { content: content })))) : (React.createElement("div", { className: "flex flex-col md:flex-row items-center justify-center gap-2 md:gap-4 w-full" },
+                React.createElement("div", { className: "max-w-none text-base font-semibold" },
+                    React.createElement("div", { dangerouslySetInnerHTML: { __html: content.bannerHtml || "" } })),
+                type === BannerType.Countdown ? (React.createElement(CountdownTimer, { content: content })) : (content.buttonText &&
+                    content.buttonType !== ButtonType.None && (React.createElement(BannerButton, { content: content }))))),
+            React.createElement("div", { onClick: handleClose, className: "absolute right-4 top-1/2 -translate-y-1/2 text-3xl leading-none cursor-pointer", style: {
+                    color: content.textColor || "#000",
+                } }, "\u00D7"))));
+}

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

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

package/dist/components/Hero/DesktopHero.js

@@ -0,0 +1,14 @@
+import React from "react";
+export default function DesktopHero({ content }) {
+    return (React.createElement("div", { className: "relative h-[400px] gap-4 w-full" },
+        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 items-start justify-center px-10 text-left xl:px-4" },
+            React.createElement("div", { className: "w-2/5" },
+                content?.title && (React.createElement("h1", { className: "text-5xl font-bold leading-tight drop-shadow-xl", style: { color: content.titleColor || "#ffffff" } }, content.title)),
+                content?.description && (React.createElement("div", { className: "mt-4 text-2xl drop-shadow-lg prose", style: { color: content.textColor || undefined }, dangerouslySetInnerHTML: { __html: content.description } })),
+                content?.buttonLink && content?.buttonText && (React.createElement("a", { href: content.buttonLink, target: "_blank", rel: "noopener noreferrer", className: "no-underline" },
+                    React.createElement("div", { className: "mt-6 rounded-md px-8 py-2 text-2xl font-semibold drop-shadow-lg transition-all duration-200 hover:bg-gray-800 inline-block", style: {
+                            color: content.buttonTextColor ?? undefined,
+                            backgroundColor: content.buttonColor ?? undefined,
+                        } }, content.buttonText)))))));
+}

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

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

package/dist/components/Hero/MobileHero.js

@@ -0,0 +1,13 @@
+import React from "react";
+export default function MobileHero({ content }) {
+    return (React.createElement("div", { className: "relative z-10 mx-auto gap-4 flex h-full max-w-screen-md flex-col items-center justify-center py-6 text-center" },
+        content?.title && (React.createElement("h1", { className: "text-3xl font-bold drop-shadow-xl px-4", style: { color: content.titleColor || undefined } }, content.title)),
+        (content?.mobileImageUrl || content?.imageUrl) && (React.createElement("div", { className: "w-full" },
+            React.createElement("img", { src: content.mobileImageUrl || content.imageUrl || "", alt: content.title || "Hero", className: "h-full w-full object-cover" }))),
+        content?.description && (React.createElement("div", { className: "px-4 text-2xl drop-shadow-lg prose", style: { color: content.textColor || undefined }, dangerouslySetInnerHTML: { __html: content.description } })),
+        content?.buttonLink && content?.buttonText && (React.createElement("a", { href: content.buttonLink, target: "_blank", rel: "noopener noreferrer", 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:bg-gray-800", style: {
+                    color: content.buttonTextColor ?? undefined,
+                    backgroundColor: content.buttonColor ?? undefined,
+                } }, content.buttonText)))));
+}

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

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

package/dist/components/Hero/index.js

@@ -0,0 +1,12 @@
+import React from "react";
+import DesktopHero from "./DesktopHero";
+import MobileHero from "./MobileHero";
+export default function Hero({ content }) {
+    if (!content)
+        return null;
+    return (React.createElement("div", { className: "bg-black" },
+        React.createElement("div", { className: "hidden lg:block" },
+            React.createElement(DesktopHero, { content: content })),
+        React.createElement("div", { className: "block lg:hidden" },
+            React.createElement(MobileHero, { content: content }))));
+}

package/dist/components/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Banner } from "./Banner";
+export { default as Hero } from "./Hero";

package/dist/components/index.js

@@ -0,0 +1,2 @@
+export { default as Banner } from "./Banner";
+export { default as Hero } from "./Hero";

package/dist/constants/banner.d.ts

@@ -0,0 +1,18 @@
+export declare enum BannerType {
+    Countdown = "countdown",
+    Announcement = "announcement",
+    Marquee = "marquee"
+}
+export declare const bannerTypes: {
+    label: string;
+    value: BannerType;
+}[];
+export declare enum BannerStatus {
+    Enabled = "enabled",
+    Disabled = "disabled"
+}
+export declare enum ButtonType {
+    None = "none",
+    Default = "default",
+    Text = "text"
+}

package/dist/constants/banner.js

@@ -0,0 +1,22 @@
+export var BannerType;
+(function (BannerType) {
+    BannerType["Countdown"] = "countdown";
+    BannerType["Announcement"] = "announcement";
+    BannerType["Marquee"] = "marquee";
+})(BannerType || (BannerType = {}));
+export const bannerTypes = [
+    { label: "Announcement Banner", value: BannerType.Announcement },
+    { label: "Countdown Timer", value: BannerType.Countdown },
+    { label: "Scrolling Text / Marquee", value: BannerType.Marquee },
+];
+export var BannerStatus;
+(function (BannerStatus) {
+    BannerStatus["Enabled"] = "enabled";
+    BannerStatus["Disabled"] = "disabled";
+})(BannerStatus || (BannerStatus = {}));
+export var ButtonType;
+(function (ButtonType) {
+    ButtonType["None"] = "none";
+    ButtonType["Default"] = "default";
+    ButtonType["Text"] = "text";
+})(ButtonType || (ButtonType = {}));

package/dist/constants/hero.d.ts

@@ -0,0 +1,12 @@
+export declare enum HeroType {
+    Static = "static",
+    Video = "video"
+}
+export declare const heroTypes: {
+    label: string;
+    value: HeroType;
+}[];
+export declare enum HeroStatus {
+    Enabled = "enabled",
+    Disabled = "disabled"
+}

package/dist/constants/hero.js

@@ -0,0 +1,14 @@
+export var HeroType;
+(function (HeroType) {
+    HeroType["Static"] = "static";
+    HeroType["Video"] = "video";
+})(HeroType || (HeroType = {}));
+export const heroTypes = [
+    { label: "Static Image", value: HeroType.Static },
+    { label: "Video Background", value: HeroType.Video },
+];
+export var HeroStatus;
+(function (HeroStatus) {
+    HeroStatus["Enabled"] = "enabled";
+    HeroStatus["Disabled"] = "disabled";
+})(HeroStatus || (HeroStatus = {}));

package/dist/constants/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./banner";
+export * from "./hero";

package/dist/constants/index.js

@@ -0,0 +1,2 @@
+export * from "./banner";
+export * from "./hero";

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./components";
+export * from "./constants";
+export * from "./types";
+export * from "./utils";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./components";
+export * from "./constants";
+export * from "./types";
+export * from "./utils";

package/dist/types/banner.d.ts

@@ -0,0 +1,28 @@
+import { BannerStatus, BannerType, ButtonType } from "../constants";
+export declare const buttonTypes: {
+    label: string;
+    value: ButtonType;
+}[];
+export interface IBannerContent {
+    buttonType: ButtonType;
+    buttonText: string;
+    buttonLink: string;
+    bgColor: string;
+    bannerHtml: string;
+    buttonColor: string;
+    buttonTextColor: string;
+    textColor: string;
+    counterEndDate?: string;
+    counterBgColor?: string;
+    counterDigitColor?: string;
+}
+export interface IBanner {
+    id: string;
+    shop: string;
+    type: BannerType;
+    name: string;
+    status: BannerStatus;
+    content: IBannerContent | null;
+    created_at: string;
+    updated_at: string;
+}

package/dist/types/banner.js

@@ -0,0 +1,6 @@
+import { ButtonType } from "../constants";
+export const buttonTypes = [
+    { label: "None", value: ButtonType.None },
+    { label: "Default Button", value: ButtonType.Default },
+    { label: "Text Link", value: ButtonType.Text },
+];

package/dist/types/hero-section.d.ts

@@ -0,0 +1,41 @@
+export declare enum HeroType {
+    Static = "static",
+    Video = "video"
+}
+export declare const heroTypes: {
+    label: string;
+    value: HeroType;
+}[];
+export declare enum HeroStatus {
+    Enabled = "enabled",
+    Disabled = "disabled"
+}
+export type ShopPage = {
+    id: string;
+    title: string;
+    handle: string;
+};
+export interface HeroContent {
+    title: string;
+    titleColor: string;
+    description: string;
+    textColor: string;
+    buttonText: string;
+    buttonLink: string;
+    buttonColor: string;
+    buttonTextColor: string;
+    imageUrl: string;
+    mobileImageUrl: string;
+    videoUrl?: string;
+}
+export interface HeroSection {
+    id: string;
+    shop: string;
+    name: string;
+    type: HeroType;
+    page: ShopPage["handle"];
+    status: HeroStatus;
+    content: HeroContent | null;
+    created_at: string;
+    updated_at: string;
+}

package/dist/types/hero.d.ts

@@ -0,0 +1,30 @@
+import { HeroStatus, HeroType } from "../constants";
+export type ShopPage = {
+    id: string;
+    title: string;
+    handle: string;
+};
+export interface IHeroContent {
+    title: string;
+    titleColor: string;
+    description: string;
+    textColor: string;
+    buttonText: string;
+    buttonLink: string;
+    buttonColor: string;
+    buttonTextColor: string;
+    imageUrl: string;
+    mobileImageUrl: string;
+    videoUrl?: string;
+}
+export interface IHero {
+    id: string;
+    shop: string;
+    name: string;
+    type: HeroType;
+    page: ShopPage["handle"];
+    status: HeroStatus;
+    content: IHeroContent | null;
+    created_at: string;
+    updated_at: string;
+}

package/dist/types/hero.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./banner";
+export * from "./hero";

package/dist/types/index.js

@@ -0,0 +1,2 @@
+export * from "./banner";
+export * from "./hero";

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

@@ -0,0 +1,11 @@
+export declare enum ResourceType {
+    HeroSections = "hero-sections",
+    Banners = "banners"
+}
+type FetchResourceParams = {
+    baseUrl: string;
+    apiKey: string;
+    type: ResourceType;
+};
+export declare function fetchResource<T>({ baseUrl, apiKey, type, }: FetchResourceParams): Promise<T[]>;
+export {};

package/dist/utils/fetch-resource.js

@@ -0,0 +1,41 @@
+export var ResourceType;
+(function (ResourceType) {
+    ResourceType["HeroSections"] = "hero-sections";
+    ResourceType["Banners"] = "banners";
+})(ResourceType || (ResourceType = {}));
+export async function fetchResource({ baseUrl, apiKey, type, }) {
+    if (!baseUrl || !apiKey) {
+        console.warn("❌ Missing EXTERNAL_API_URL or FRAGMENT_API_KEY");
+        return [];
+    }
+    try {
+        // Build the endpoint URL for the specific resource type
+        const endpoint = `${baseUrl}/api/v1/${type}`;
+        const res = await fetch(endpoint, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            },
+        });
+        if (!res.ok) {
+            throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+        }
+        const json = await res.json();
+        if (json.status === "success") {
+            // The API returns { status: "success", data: { items: [...], total, page, limit } }
+            if (json.data?.items && Array.isArray(json.data.items)) {
+                return json.data.items;
+            }
+            // Fallback for direct array response
+            if (Array.isArray(json.data)) {
+                return json.data;
+            }
+        }
+        console.error(`❌ Failed to load ${type}:`, json.message || "Unknown error");
+    }
+    catch (err) {
+        console.error(`❌ Fetch error for ${type}:`, err);
+    }
+    return [];
+}

package/dist/utils/fetchResource.d.ts

@@ -0,0 +1,2 @@
+export type ResourceType = "hero_section" | "banner";
+export declare function fetchResource<T>(baseUrl: string, shop: string, token: string, type: ResourceType): Promise<T[]>;

package/dist/utils/fetchResource.js

@@ -0,0 +1,28 @@
+export async function fetchResource(baseUrl, shop, token, type) {
+    if (!baseUrl || !shop || !token) {
+        console.warn("❌ Missing EXTERNAL_API_URL, SHOP_DOMAIN, or EXTERNAL_API_KEY");
+        return [];
+    }
+    try {
+        const res = await fetch(`${baseUrl}/?type=${type}&shop=${shop}`, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${token}`,
+            },
+        });
+        const json = await res.json();
+        if (json.status === "success") {
+            if (Array.isArray(json.data)) {
+                return json.data;
+            }
+            else if (Array.isArray(json.data?.[type])) {
+                return json.data[type];
+            }
+        }
+        console.error(`❌ Failed to load ${type}:`, json.message);
+    }
+    catch (err) {
+        console.error(`❌ Fetch error for ${type}:`, err);
+    }
+    return [];
+}

package/dist/utils/index.d.ts

@@ -0,0 +1 @@
+export * from "./fetch-resource";

package/dist/utils/index.js

@@ -0,0 +1 @@
+export * from "./fetch-resource";

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "fragment-headless-sdk",
+  "version": "1.0.1",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "react": "^19.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.2",
+    "typescript": "^5.8.3"
+  }
+}

package/readme.md

@@ -0,0 +1,404 @@
+# fragment-headless-sdk
+
+The official SDK for integrating with fragment-shopify CMS. Provides React components, TypeScript types, and utilities for rendering published sections in headless Shopify storefronts.
+
+---
+
+## 🏗️ Architecture
+
+This package works as a **consumer library** that integrates with the **fragment-shopify app**:
+
+```
+Fragment-Shopify App (CMS) → API Endpoint → fragment-shopify-sdk (Consumer) → Your Headless Site
+```
+
+- **Fragment-Shopify App**: Content management system for creating and publishing sections
+- **fragment-shopify-sdk**: This SDK - consumes and renders the published content
+- **Your App**: Next.js/React application that uses the SDK
+
+---
+
+## 🔧 Features
+
+- ✅ **Data Fetching**: Built-in utilities to fetch sections from fragment-shopify API
+- ✅ **React Components**: Pre-built Hero and Banner components with responsive design
+- ✅ **TypeScript Support**: Full type definitions for all components and data structures
+- ✅ **Tailwind Integration**: Styled with Tailwind CSS for easy customization
+- ✅ **Multiple Banner Types**: Standard, marquee, and countdown banner variants
+- ✅ **Hero Sections**: Desktop/mobile responsive hero components with video support
+
+---
+
+## 📦 Installation
+
+```bash
+# Using Yarn
+yarn add fragment-headless-sdk
+
+# Using npm
+npm install fragment-headless-sdk
+```
+
+---
+
+## 🎨 Tailwind CSS Setup
+
+Since this package uses Tailwind utility classes, your host app must be configured with Tailwind CSS.
+
+### 1. Install Tailwind
+
+```bash
+npm install -D tailwindcss postcss autoprefixer
+npx tailwindcss init -p
+```
+
+### 2. Update `tailwind.config.js`
+
+```js
+const path = require("path");
+
+module.exports = {
+  content: [
+    "./app/**/*.{js,ts,jsx,tsx,mdx}",
+    "./pages/**/*.{js,ts,jsx,tsx,mdx}",
+    "./components/**/*.{js,ts,jsx,tsx,mdx}",
+    path.join(__dirname, "node_modules/fragment-headless-sdk/dist/**/*.{js,ts,jsx,tsx}"),
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+  corePlugins: {
+    preflight: false,
+  },
+};
+```
+
+### 3. Include Tailwind in your global CSS
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Fetch Data from Fragment-Shopify
+
+```tsx
+import { fetchResource, ResourceType } from "fragment-headless-sdk";
+
+// Fetch hero sections
+const heroes = await fetchResource({
+  baseUrl: process.env.EXTERNAL_API_URL, // Your fragment-shopify app URL
+  apiKey: process.env.FRAGMENT_API_KEY, // API key from fragment-shopify (format: "keyId:secret")
+  type: ResourceType.HeroSections,
+});
+
+// Fetch banners
+const banners = await fetchResource({
+  baseUrl: process.env.EXTERNAL_API_URL,
+  apiKey: process.env.FRAGMENT_API_KEY,
+  type: ResourceType.Banners,
+});
+```
+
+### 2. Render Components
+
+```tsx
+import { Banner, Hero } from "fragment-headless-sdk";
+import { BannerType } from "fragment-headless-sdk";
+
+export default function Page() {
+  const [showBanner, setShowBanner] = useState(true);
+
+  return (
+    <>
+      {/* Hero Section */}
+      <Hero content={heroes[0]?.content} />
+
+      {/* Banner */}
+      {showBanner && banners[0] && (
+        <Banner
+          content={banners[0].content}
+          type={banners[0].type as BannerType}
+          handleClose={() => setShowBanner(false)}
+        />
+      )}
+    </>
+  );
+}
+```
+
+---
+
+## 📡 API Reference
+
+### `fetchResource<T>(params)`
+
+Fetches sections from your fragment-shopify app.
+
+**Parameters:**
+
+- `baseUrl: string` - URL of your fragment-shopify app
+- `apiKey: string` - Fragment API key (format: `keyId:secret`)
+- `type: ResourceType` - Type of resource to fetch
+
+**ResourceType Options:**
+
+- `ResourceType.HeroSections` - Fetch hero sections
+- `ResourceType.Banners` - Fetch banner sections
+
+**Returns:** `Promise<T[]>` - Array of fetched resources
+
+**Example Response:**
+
+```json
+{
+  "status": "success",
+  "data": [
+    {
+      "id": "hero-1",
+      "shop": "your-shop.myshopify.com",
+      "name": "Homepage Hero",
+      "content": {
+        "title": "Welcome to Our Store",
+        "subtitle": "Discover amazing products",
+        "description": "Shop the latest collection...",
+        "backgroundImage": "https://...",
+        "buttons": [...]
+      }
+    }
+  ]
+}
+```
+
+---
+
+## 🧩 Components
+
+### Hero Component
+
+Responsive hero section with support for images, videos, and call-to-action buttons.
+
+```tsx
+import { Hero } from "fragment-headless-sdk";
+
+<Hero content={heroContent} />;
+```
+
+**Props:**
+
+- `content: IHeroContent` - Hero configuration object
+
+**IHeroContent Interface:**
+
+```typescript
+interface IHeroContent {
+  title?: string;
+  subtitle?: string;
+  description?: string;
+  backgroundImage?: string;
+  videoUrl?: string;
+  buttons?: Array<{
+    text: string;
+    link: string;
+    style: "primary" | "secondary";
+  }>;
+  shopPage?: {
+    id: string;
+    title: string;
+    handle: string;
+  };
+}
+```
+
+### Banner Component
+
+Flexible banner component with multiple display types and countdown functionality.
+
+```tsx
+import { Banner, BannerType } from "fragment-headless-sdk";
+
+<Banner
+  content={bannerContent}
+  type={BannerType.Standard}
+  handleClose={() => setBannerVisible(false)}
+/>;
+```
+
+**Props:**
+
+- `content: IBannerContent` - Banner configuration object
+- `type: BannerType` - Display type (Standard, Marquee, Countdown)
+- `handleClose: () => void` - Function called when banner is closed
+
+**Banner Types:**
+
+- `BannerType.Standard` - Regular banner with text and button
+- `BannerType.Marquee` - Scrolling marquee banner
+- `BannerType.Countdown` - Banner with countdown timer
+
+**IBannerContent Interface:**
+
+```typescript
+interface IBannerContent {
+  bannerHtml: string;
+  bgColor: string;
+  textColor: string;
+  buttonType: ButtonType;
+  buttonText: string;
+  buttonLink: string;
+  buttonColor: string;
+  buttonTextColor: string;
+  counterEndDate?: string;
+  counterBgColor?: string;
+  counterDigitColor?: string;
+}
+```
+
+---
+
+## 🔑 API Key Setup
+
+Before using the SDK, you need to generate an API key from your fragment-shopify app:
+
+### 1. Generate API Key
+
+1. Install the Fragment app in your Shopify store
+2. Navigate to the **Configuration** section within the app
+3. Find the **"API Access"** section
+4. Click **"Generate Key"** to create your API key
+5. **Save the key securely** - it's only shown once!
+
+### 2. API Key Format
+
+The API key follows this format: `keyId:secret`
+
+Example: `bh_a1b2c3d4e5f6:your-64-char-secret-here`
+
+### 3. Key Management
+
+- Only **one active key** per shop for security
+- Keys **expire after 1 year** by default
+- You can **regenerate keys** when needed (revokes the old key)
+- Monitor key usage in the Configuration page
+
+### ✅ Ready for Production
+
+The external API is fully implemented! The fragment-shopify app now supports complete API key authentication with the v1 endpoints. Your SDK is ready to use in production.
+
+---
+
+## 🔧 Environment Variables
+
+Add these environment variables to your `.env.local`:
+
+```bash
+# Fragment-Shopify Integration
+EXTERNAL_API_URL=https://your-fragment-app.vercel.app
+FRAGMENT_API_KEY=bh_a1b2c3d4e5f6:your-64-char-secret
+```
+
+---
+
+## 🎨 Styling & Customization
+
+### Tailwind CSS Classes
+
+Components use Tailwind utility classes. You can customize styling by:
+
+1. **Overriding default styles** with your own CSS classes
+2. **Using Tailwind's configuration** to modify the design system
+3. **Applying custom colors** through the content configuration objects
+
+### Component Styling
+
+**Hero Component:**
+
+- Responsive design with `md:` breakpoints
+- Background image/video support
+- Customizable button styles through content props
+
+**Banner Component:**
+
+- Dynamic background and text colors via `content.bgColor` and `content.textColor`
+- Marquee animation with `animate-marquee` class
+- Countdown timer with customizable colors
+
+---
+
+## 🔄 Data Flow
+
+```mermaid
+graph TD
+    A[Fragment-Shopify App] --> B[API Endpoint]
+    B --> C[fetchResource()]
+    C --> D[Your React App]
+    D --> E[Hero/Banner Components]
+    E --> F[Rendered UI]
+```
+
+1. **Content Creation**: Editors create sections in fragment-shopify app
+2. **Publishing**: Sections are published and available via API
+3. **Data Fetching**: Your app calls `fetchResource()` to get section data
+4. **Component Rendering**: Pass data to Hero/Banner components
+5. **UI Display**: Components render responsive, styled sections
+
+---
+
+## 🚨 Error Handling
+
+The package includes built-in error handling:
+
+```typescript
+// fetchResource automatically handles:
+// - Missing environment variables (logs warning, returns [])
+// - API errors (logs error, returns [])
+// - Invalid response format (logs error, returns [])
+
+const sections = await fetchResource({...});
+// sections will always be an array, even on error
+```
+
+**Best Practices:**
+
+- Always check if data exists before rendering: `{sections[0] && <Hero content={sections[0].content} />}`
+- Implement fallback UI for when sections are unavailable
+- Monitor console for API warnings and errors
+
+---
+
+## 📦 Package Structure
+
+```
+fragment-headless-sdk/
+├── src/
+│   ├── components/          # React components
+│   │   ├── Banner/         # Banner component variants
+│   │   └── Hero/           # Hero component variants
+│   ├── constants/          # Enums and constants
+│   ├── types/              # TypeScript interfaces
+│   └── utils/              # Utility functions
+└── dist/                   # Compiled output
+```
+
+---
+
+## 🤝 Contributing
+
+This package is designed to work specifically with the fragment-shopify app. When adding new section types:
+
+1. Add the resource type to `ResourceType` enum
+2. Create corresponding TypeScript interfaces
+3. Build React components for rendering
+4. Update this documentation
+
+---
+
+## 📝 License
+
+MIT License - See LICENSE file for details.