@alphasquad/saleor-template-advance 0.1.0

package/src/lib/saleor/getSaleorApiUrl.ts

@@ -0,0 +1,25 @@
+const GRAPHQL_SUFFIX_RE = /\/graphql\/?$/i;
+
+/**
+ * Returns the Saleor GraphQL endpoint URL.
+ *
+ * This template requires `NEXT_PUBLIC_API_URL` to be set (single-tenant per deployment).
+ * We also normalize it so callers can safely pass either:
+ * - https://example.com/graphql
+ * - https://example.com/graphql/
+ * - https://example.com (we'll append /graphql/)
+ */
+export function getSaleorApiUrl(): string {
+  const raw = process.env.NEXT_PUBLIC_API_URL?.trim();
+  if (!raw) {
+    throw new Error(
+      "Missing NEXT_PUBLIC_API_URL. Set it to your Saleor GraphQL endpoint (e.g. https://.../graphql/)."
+    );
+  }
+
+  if (GRAPHQL_SUFFIX_RE.test(raw)) {
+    return raw.endsWith("/") ? raw : `${raw}/`;
+  }
+
+  return `${raw.replace(/\/+$/, "")}/graphql/`;
+}

package/src/lib/schema.ts

@@ -0,0 +1,303 @@
+/**
+ * Schema.org structured data utilities
+ * Generate JSON-LD markup for SEO
+ */
+
+interface Product {
+  id: string;
+  slug?: string;
+  name: string;
+  description?: string;
+  image?: string | string[];
+  price?: number;
+  currency?: string;
+  availability?: string;
+  sku?: string;
+  brand?: string;
+  rating?: number;
+  reviewCount?: number;
+  category?: {
+    id: string;
+    name: string;
+  };
+}
+
+interface BreadcrumbItem {
+  name: string;
+  url: string;
+}
+
+/**
+ * Generate Organization schema for homepage
+ */
+export function generateOrganizationSchema(
+  siteName: string,
+  siteUrl: string,
+  logoUrl?: string,
+  socialLinks?: string[]
+) {
+  const baseUrl = (process.env.NEXT_PUBLIC_SITE_URL || siteUrl).replace(
+    /\/$/,
+    ""
+  );
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "Organization",
+    name: siteName,
+    url: baseUrl,
+    logo: logoUrl
+      ? {
+          "@type": "ImageObject",
+          url: `${baseUrl}${logoUrl}`,
+        }
+      : undefined,
+    sameAs: socialLinks || [],
+  };
+}
+
+/**
+ * Generate WebSite schema with search action
+ */
+export function generateWebsiteSchema(
+  siteName: string,
+  siteUrl: string,
+  searchUrl?: string
+) {
+  const baseUrl = (process.env.NEXT_PUBLIC_SITE_URL || siteUrl).replace(
+    /\/$/,
+    ""
+  );
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "WebSite",
+    name: siteName,
+    url: baseUrl,
+    potentialAction: searchUrl
+      ? {
+          "@type": "SearchAction",
+          target: {
+            "@type": "EntryPoint",
+            urlTemplate: `${baseUrl}${searchUrl}?q={search_term_string}`,
+          },
+          "query-input": "required name=search_term_string",
+        }
+      : undefined,
+  };
+}
+
+/**
+ * Generate Product schema
+ */
+export function generateProductSchema(product: Product) {
+  const baseUrl = (process.env.NEXT_PUBLIC_SITE_URL || "http://localhost:3000").replace(
+    /\/$/,
+    ""
+  );
+
+  const images = Array.isArray(product.image)
+    ? product.image
+    : product.image
+    ? [product.image]
+    : [];
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "Product",
+    name: product.name,
+    description: product.description || "",
+    image: images.map((img) =>
+      img.startsWith("http") ? img : `${baseUrl}${img}`
+    ),
+    sku: product.sku || product.id,
+    category: product.category?.name,
+    offers: {
+      "@type": "Offer",
+      price: product.price?.toString() || "0",
+      priceCurrency: product.currency || "USD",
+      availability: product.availability
+        ? `https://schema.org/${product.availability}`
+        : "https://schema.org/InStock",
+      url: `${baseUrl}/product/${product.slug}`,
+    },
+    brand: product.brand
+      ? {
+          "@type": "Brand",
+          name: product.brand,
+        }
+      : undefined,
+    aggregateRating:
+      product.rating && product.reviewCount
+        ? {
+            "@type": "AggregateRating",
+            ratingValue: product.rating.toString(),
+            reviewCount: product.reviewCount.toString(),
+          }
+        : undefined,
+  };
+}
+
+/**
+ * Generate ItemList schema for product listings
+ */
+export function generateItemListSchema(products: Product[], listName: string) {
+  const baseUrl = (process.env.NEXT_PUBLIC_SITE_URL || "http://localhost:3000").replace(
+    /\/$/,
+    ""
+  );
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "ItemList",
+    name: listName,
+    numberOfItems: products.length,
+    itemListElement: products.map((product, index) => ({
+      "@type": "ListItem",
+      position: index + 1,
+      item: {
+        "@type": "Product",
+        name: product.name,
+        url: `${baseUrl}/product/${product.id}`,
+        image: Array.isArray(product.image)
+          ? product.image[0]
+          : product.image || "",
+        category: product.category?.name,
+        offers: {
+          "@type": "Offer",
+          price: product.price?.toString() || "0",
+          priceCurrency: product.currency || "USD",
+        },
+      },
+    })),
+  };
+}
+
+/**
+ * Generate BreadcrumbList schema
+ */
+export function generateBreadcrumbSchema(items: BreadcrumbItem[]) {
+  const baseUrl = (process.env.NEXT_PUBLIC_SITE_URL || "http://localhost:3000").replace(
+    /\/$/,
+    ""
+  );
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    itemListElement: items.map((item, index) => ({
+      "@type": "ListItem",
+      position: index + 1,
+      name: item.name,
+      item: item.url.startsWith("http") ? item.url : `${baseUrl}${item.url}`,
+    })),
+  };
+}
+
+/**
+ * Generate CollectionPage schema for category/collection pages
+ */
+export function generateCollectionPageSchema(
+  name: string,
+  description: string,
+  url: string
+) {
+  const baseUrl = (process.env.NEXT_PUBLIC_SITE_URL || "http://localhost:3000").replace(
+    /\/$/,
+    ""
+  );
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "CollectionPage",
+    name,
+    description,
+    url: url.startsWith("http") ? url : `${baseUrl}${url}`,
+  };
+}
+
+/**
+ * Generate WebPage schema for product category pages with ItemList
+ */
+export function generateProductCategoryPageSchema(
+  name: string,
+  description: string,
+  url: string
+) {
+  const baseUrl = (process.env.NEXT_PUBLIC_SITE_URL || "http://localhost:3000").replace(
+    /\/$/,
+    ""
+  );
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "WebPage",
+    name: `${name} - Product Category`,
+    description,
+    url: url.startsWith("http") ? url : `${baseUrl}${url}`,
+    breadcrumb: {
+      "@type": "BreadcrumbList",
+    },
+  };
+}
+
+/**
+ * Generate Blog schema for blog listing pages
+ */
+export function generateBlogSchema(
+  name: string,
+  description: string,
+  url: string
+) {
+  const baseUrl = (process.env.NEXT_PUBLIC_SITE_URL || "http://localhost:3000").replace(
+    /\/$/,
+    ""
+  );
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "Blog",
+    name,
+    description,
+    url: url.startsWith("http") ? url : `${baseUrl}${url}`,
+  };
+}
+
+/**
+ * Generate BlogPosting schema for blog posts
+ */
+export function generateBlogPostingSchema(
+  title: string,
+  description: string,
+  url: string,
+  datePublished: string,
+  dateModified?: string,
+  authorName?: string,
+  image?: string
+) {
+  const baseUrl = (process.env.NEXT_PUBLIC_SITE_URL || "http://localhost:3000").replace(
+    /\/$/,
+    ""
+  );
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "BlogPosting",
+    headline: title,
+    description,
+    url: url.startsWith("http") ? url : `${baseUrl}${url}`,
+    datePublished,
+    dateModified: dateModified || datePublished,
+    author: authorName
+      ? {
+          "@type": "Person",
+          name: authorName,
+        }
+      : undefined,
+    image: image
+      ? image.startsWith("http")
+        ? image
+        : `${baseUrl}${image}`
+      : undefined,
+  };
+}

package/src/lib/seo/extractTextFromEditorJs.ts

@@ -0,0 +1,58 @@
+function stripHtml(input: string): string {
+  return input.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
+}
+
+type EditorJsBlock =
+  | { type: "paragraph"; data?: { text?: string } }
+  | { type: "header"; data?: { text?: string } }
+  | { type: "quote"; data?: { text?: string } }
+  | { type: "list"; data?: { items?: string[] } }
+  | { type: string; data?: Record<string, unknown> };
+
+type EditorJsDoc = { blocks?: EditorJsBlock[] };
+
+/**
+ * Saleor pages/descriptions are often stored as Editor.js JSON (string).
+ * This extracts readable plaintext for meta descriptions / schema.
+ */
+export function extractTextFromEditorJs(input?: string | null): string {
+  if (!input) return "";
+
+  const trimmed = input.trim();
+  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) {
+    return stripHtml(trimmed);
+  }
+
+  try {
+    const parsed = JSON.parse(trimmed) as EditorJsDoc;
+    const blocks = Array.isArray(parsed?.blocks) ? parsed.blocks : [];
+
+    const parts: string[] = [];
+    for (const block of blocks) {
+      if (!block || typeof block !== "object") continue;
+
+      if (
+        block.type === "paragraph" ||
+        block.type === "header" ||
+        block.type === "quote"
+      ) {
+        const txt = stripHtml(String(block.data?.text || ""));
+        if (txt) parts.push(txt);
+        continue;
+      }
+
+      if (block.type === "list") {
+        const items = Array.isArray(block.data?.items) ? block.data?.items : [];
+        for (const item of items) {
+          const txt = stripHtml(String(item || ""));
+          if (txt) parts.push(txt);
+        }
+      }
+    }
+
+    return stripHtml(parts.join(" "));
+  } catch {
+    return stripHtml(trimmed);
+  }
+}
+

package/src/lib/seo/site.ts

@@ -0,0 +1,10 @@
+export function getSiteUrl(): URL {
+  const raw = process.env.NEXT_PUBLIC_SITE_URL?.trim() || "http://localhost:3000";
+  return new URL(raw.endsWith("/") ? raw : `${raw}/`);
+}
+
+export function canonicalPath(pathname: string): string {
+  if (!pathname.startsWith("/")) return `/${pathname}`;
+  return pathname;
+}
+

package/src/lib/urls/normalizeInternalUrl.ts

@@ -0,0 +1,53 @@
+export function normalizeInternalUrl(input: string): string {
+  const raw = input.trim();
+  if (!raw) return raw;
+
+  // Already relative.
+  if (raw.startsWith("/") && !raw.startsWith("//")) return raw;
+
+  // Try to interpret absolute URLs and strip the host when it matches our site.
+  try {
+    const siteRaw = process.env.NEXT_PUBLIC_SITE_URL?.trim();
+    const site = siteRaw ? new URL(siteRaw.endsWith("/") ? siteRaw : `${siteRaw}/`) : null;
+
+    const url = new URL(raw);
+
+    if (site && url.hostname === site.hostname) {
+      return `${url.pathname}${url.search}${url.hash}` || "/";
+    }
+
+    // Saleor menus often include absolute storefront URLs; in templates the domain may differ
+    // between environments (localhost vs deployed). Only strip the host for *known* internal routes.
+    const internalPrefixes = [
+      "/",
+      "/about",
+      "/contact",
+      "/products",
+      "/product",
+      "/category",
+      "/blog",
+      "/content",
+      "/request-return",
+      "/account",
+      "/privacy-policy",
+      "/shipping-returns",
+      "/terms-and-conditions",
+      "/warranty",
+      "/frequently-asked-questions",
+      "/site-map",
+      "/discounts",
+      "/core-policies",
+      "/cancellation-policy",
+      "/brands",
+      "/brand",
+    ];
+
+    if (internalPrefixes.some((p) => url.pathname === p || url.pathname.startsWith(`${p}/`))) {
+      return `${url.pathname}${url.search}${url.hash}` || "/";
+    }
+  } catch {
+    // fall through
+  }
+
+  return raw;
+}

package/src/middleware.ts

@@ -0,0 +1,134 @@
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+import { jwtDecode } from 'jwt-decode';
+import { fetchConfigurationDirect, isFeatureActive } from '@/app/utils/configurationService';
+
+type JwtPayload = { exp?: number };
+
+const AUTH_ROUTES = [
+  '/account/login',
+  '/account/register',
+  '/account/forgot-password',
+  '/account/reset-password',
+];
+
+const PROTECTED_PREFIXES = ['/account', '/orders', '/settings'];
+
+// Feature route mappings
+const FEATURE_ROUTES = {
+  '/locator': 'dealer_locator',
+} as const;
+
+export async function middleware(req: NextRequest) {
+  const { pathname } = req.nextUrl;
+
+  const normalizedPath =
+    pathname.endsWith('/') && pathname.length > 1
+      ? pathname.slice(0, -1)
+      : pathname;
+
+  // Check feature route protection first
+  const featureName = FEATURE_ROUTES[normalizedPath as keyof typeof FEATURE_ROUTES];
+  if (featureName) {
+    try {
+      const configuration = await fetchConfigurationDirect();
+      const isActive = isFeatureActive(configuration, featureName);
+      
+      if (!isActive) {
+        // Redirect to home page if feature is not active
+        const homeUrl = new URL('/', req.url);
+        const response = NextResponse.redirect(homeUrl);
+        
+        const isProd = process.env.NODE_ENV === 'production';
+        if (!isProd) {
+          response.headers.set('x-middleware-redirect', `home:feature-disabled:${featureName}`);
+        }
+        return response;
+      }
+    } catch (error) {
+      console.error('Error checking feature configuration:', error);
+      // Allow access if there's an error (fail open)
+    }
+  }
+
+  const tokenCookie = req.cookies.get('token');
+  const refreshCookie = req.cookies.get('refreshToken');
+  
+  let isTokenValid = false;
+  if (tokenCookie?.value) {
+    try {
+      const { exp } = jwtDecode<JwtPayload>(tokenCookie.value);
+      isTokenValid = !!exp && exp * 1000 > Date.now();
+    } catch {
+      isTokenValid = false;
+    }
+  }
+  
+  const isLoggedIn = !!tokenCookie && isTokenValid;
+
+  const isAuthRoute = AUTH_ROUTES.some(
+    route => normalizedPath === route || normalizedPath.startsWith(route + '/')
+  );
+
+  const isProtectedRoute =
+    PROTECTED_PREFIXES.some(
+      prefix => normalizedPath === prefix || normalizedPath.startsWith(prefix + '/')
+    ) && !isAuthRoute;
+
+  // Debug headers only in non-prod and NEVER include token value
+  const isProd = process.env.NODE_ENV === 'production';
+  const debugHeaders: Record<string, string> = {
+    'x-pathname': normalizedPath,
+    'x-has-token': tokenCookie ? '1' : '0',
+    'x-has-refresh': refreshCookie ? '1' : '0',
+    'x-is-logged-in': isLoggedIn ? '1' : '0',
+    'x-is-auth-route': isAuthRoute ? '1' : '0',
+    'x-is-protected-route': isProtectedRoute ? '1' : '0',
+  };
+
+  // If token exists but is expired, redirect to clear-cookies API which will then redirect to login
+  if (tokenCookie && !isTokenValid) {
+    const loginUrl = new URL('/api/auth/clear-cookies', req.url);
+    loginUrl.searchParams.set('redirect', '/account/login');
+    loginUrl.searchParams.set('reason', 'token-expired');
+    const response = NextResponse.redirect(loginUrl);
+    if (!isProd) {
+      response.headers.set('x-middleware-redirect', 'login:token-expired');
+      Object.entries(debugHeaders).forEach(([k, v]) => response.headers.set(k, v));
+    }
+    return response;
+  }
+
+  if (isLoggedIn && isAuthRoute) {
+    const res = NextResponse.redirect(new URL('/', req.url));
+    if (!isProd) {
+      res.headers.set('x-middleware-redirect', 'home:auth-while-logged-in');
+      Object.entries(debugHeaders).forEach(([k, v]) => res.headers.set(k, v));
+    }
+    return res;
+  }
+
+  if (!isLoggedIn && isProtectedRoute) {
+    const loginUrl = new URL('/account/login', req.url);
+    loginUrl.searchParams.set('next', normalizedPath);
+    const res = NextResponse.redirect(loginUrl);
+    if (!isProd) {
+      res.headers.set('x-middleware-redirect', 'login:protected-while-logged-out');
+      Object.entries(debugHeaders).forEach(([k, v]) => res.headers.set(k, v));
+    }
+    return res;
+  }
+
+  const res = NextResponse.next();
+  if (!isProd) {
+    res.headers.set('x-middleware-hit', '1');
+    Object.entries(debugHeaders).forEach(([k, v]) => res.headers.set(k, v));
+  }
+  return res;
+}
+
+export const config = {
+  matcher: [
+    '/((?!api|_next/static|_next/image|favicon.ico|images|manifest.webmanifest|sitemap.xml|robots.txt).*)',
+  ],
+};

package/src/sitemaps/README.md

@@ -0,0 +1,105 @@
+# Sitemap Integration
+
+Complete sitemap setup for all pages including static and dynamic content for Google, Yahoo, and Bing.
+
+## Files Structure
+
+```
+src/sitemaps/
+├── static-pages-sitemap.ts    # All static pages sitemap
+├── dynamic-pages-sitemap.ts   # Dynamic content (products, categories, etc.)
+├── sitemap-index.ts          # Configuration and search engine URLs
+└── README.md                 # This documentation
+
+src/app/
+├── sitemap.ts                # Main sitemap endpoint (combines all)
+└── sitemap-index.xml/        # Sitemap index route
+    └── route.ts
+
+public/robots.txt             # Search engine crawler instructions
+```
+
+## Available URLs
+
+- **Main Sitemap**: `http://localhost:3000/sitemap.xml`
+- **Sitemap Index**: `http://localhost:3000/sitemap-index.xml`
+- **Robots.txt**: `http://localhost:3000/robots.txt`
+
+## Current Pages in Sitemap
+
+### Static Pages (22 pages):
+- **Main Pages**: Homepage, About, Contact, Shop, Categories, Products, Blog
+- **Account Pages**: Login, Register, Password Reset, Account Dashboard, Orders, Settings, Addresses
+- **Legal Pages**: Privacy Policy, Terms & Conditions, Warranty, Shipping & Returns
+- **Support Pages**: FAQ, Store Locator
+- **E-commerce**: Cart, Checkout, Order Confirmation
+
+### Dynamic Pages (Ready for implementation):
+- **Products**: `/product/[id]` - Product detail pages
+- **Categories**: `/category/[slug]` - Category listing pages  
+- **Brands**: `/brand/[id]` - Brand pages
+- **Blog Posts**: `/blog/[slug]` - Individual blog posts
+- **Dynamic Pages**: `/[slug]` - CMS-managed pages
+
+## Google Search Console Setup
+
+1. **Add Property**: Go to [Google Search Console](https://search.google.com/search-console) and add your domain
+2. **Verify Ownership**: Follow verification steps (HTML file upload, DNS, or meta tag)
+3. **Submit Sitemaps**: 
+   - Go to "Sitemaps" in the left menu
+   - Add sitemaps:
+     - `https://yourdomain.com/sitemap.xml` (main sitemap)
+     - `https://yourdomain.com/sitemap-index.xml` (sitemap index)
+   - Click "Submit"
+
+## Other Search Engines
+
+### Bing Webmaster Tools
+1. Visit [Bing Webmaster Tools](https://www.bing.com/webmasters)
+2. Add your site and verify ownership
+3. Submit both sitemaps in "Sitemaps" section
+
+### Yahoo Search
+Yahoo uses Bing's index, so submitting to Bing covers Yahoo as well.
+
+### Manual Ping (Optional)
+Search engines can be notified directly:
+- Google: `https://www.google.com/ping?sitemap=https://yourdomain.com/sitemap.xml`
+- Bing: `https://www.bing.com/ping?sitemap=https://yourdomain.com/sitemap.xml`
+
+## Production Setup
+
+1. Update `NEXT_PUBLIC_SITE_URL` in your environment variables
+2. Update robots.txt with your actual domain
+3. Implement dynamic content fetching in `dynamic-pages-sitemap.ts`
+4. Submit sitemaps to search engines using your production URL
+
+## Adding Dynamic Content
+
+To populate dynamic pages, implement the helper functions in `dynamic-pages-sitemap.ts`:
+
+```typescript
+// Example: Connect to your GraphQL API
+export async function getProductSitemapEntries(): Promise<MetadataRoute.Sitemap> {
+  const baseUrl = process.env.NEXT_PUBLIC_SITE_URL || 'http://localhost:3000'
+  const { data } = await client.query({ query: GET_ALL_PRODUCTS })
+  
+  return data.products.map(product => ({
+    url: `${baseUrl}/product/${product.id}`,
+    lastModified: new Date(product.updatedAt),
+    changeFrequency: 'weekly' as const,
+    priority: 0.8,
+  }))
+}
+```
+
+## SEO Priority Guidelines
+
+- **Priority 1.0**: Homepage
+- **Priority 0.9**: Shop, Main category pages
+- **Priority 0.8**: About, Product pages, Category pages, Blog
+- **Priority 0.7**: Contact, Brand pages
+- **Priority 0.6**: FAQ, Blog posts, Store locator
+- **Priority 0.5**: Legal pages, Dynamic CMS pages
+- **Priority 0.4**: Account pages (login, register)
+- **Priority 0.3**: Password reset, OTP pages