@xexr/blog-platform 1.0.6 → 1.0.8

package/dist/lib/sitemap.ts

@@ -0,0 +1,719 @@
+/**
+ * Next.js-compatible sitemap generation utilities for blog platform integration.
+ *
+ * These utilities generate sitemap entries that follow Next.js MetadataRoute.Sitemap
+ * conventions, allowing seamless integration with existing Next.js applications.
+ *
+ * @example Integration with existing Next.js sitemap:
+ * ```typescript
+ * // app/sitemap.ts
+ * import { generateBlogSitemapEntries } from '@xexr/blog-platform';
+ * import type { MetadataRoute } from 'next';
+ *
+ * export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+ *   // Your existing routes
+ *   const staticRoutes = [
+ *     { url: 'https://yoursite.com', lastModified: new Date(), priority: 1 },
+ *     { url: 'https://yoursite.com/about', lastModified: new Date(), priority: 0.8 }
+ *   ];
+ *
+ *   // Blog platform entries
+ *   const blogEntries = await generateBlogSitemapEntries(blogConfig);
+ *
+ *   return [...staticRoutes, ...blogEntries];
+ * }
+ * ```
+ */
+
+import type { PublishedArticle, PublishedSite, PublishedAuthor } from '../types/contracts';
+import { generateCanonicalUrl, normalizeDomain, type CanonicalUrlOptions } from './seo';
+
+/**
+ * Configuration options for sitemap generation.
+ */
+export interface SitemapOptions {
+  /** Canonical URL configuration */
+  canonical?: CanonicalUrlOptions;
+
+  /** Whether to include author pages in sitemap */
+  includeAuthorPages?: boolean;
+
+  /** Whether to include pagination pages in sitemap */
+  includePaginationPages?: boolean;
+
+  /** Number of articles per page for pagination calculation */
+  articlesPerPage?: number;
+
+  /** Maximum number of sitemap entries (defaults to 50,000 per Google guidelines) */
+  maxEntries?: number;
+
+  /** Change frequency for different page types */
+  changeFrequency?: {
+    /** Change frequency for blog home page */
+    homePage?: SitemapChangeFreq;
+    /** Change frequency for article pages */
+    articles?: SitemapChangeFreq;
+    /** Change frequency for author pages */
+    authorPages?: SitemapChangeFreq;
+    /** Change frequency for pagination pages */
+    paginationPages?: SitemapChangeFreq;
+  };
+
+  /** Priority values for different page types */
+  priority?: {
+    /** Priority for blog home page (0.0-1.0) */
+    homePage?: number;
+    /** Priority for article pages (0.0-1.0) */
+    articles?: number;
+    /** Priority for author pages (0.0-1.0) */
+    authorPages?: number;
+    /** Priority for pagination pages (0.0-1.0) */
+    paginationPages?: number;
+  };
+}
+
+/**
+ * Valid sitemap change frequency values as per XML sitemap standard.
+ */
+export type SitemapChangeFreq =
+  | 'always'
+  | 'hourly'
+  | 'daily'
+  | 'weekly'
+  | 'monthly'
+  | 'yearly'
+  | 'never';
+
+/**
+ * Next.js MetadataRoute.Sitemap compatible entry.
+ * This matches the expected format for Next.js sitemap generation.
+ */
+export interface NextjsSitemapEntry {
+  /** The URL of the page */
+  url: string;
+
+  /** Last modification date */
+  lastModified?: string | Date;
+
+  /** Change frequency hint for search engines */
+  changeFrequency?: SitemapChangeFreq;
+
+  /** Priority relative to other URLs on the site (0.0-1.0) */
+  priority?: number;
+
+  /** Alternate language versions (for i18n) */
+  alternates?: {
+    languages?: Record<string, string>;
+  };
+}
+
+/**
+ * Legacy XML sitemap entry format (for backward compatibility).
+ * @deprecated Use NextjsSitemapEntry for new implementations
+ */
+export interface SitemapEntry {
+  /** The URL of the page */
+  loc: string;
+
+  /** Last modification date as ISO 8601 string */
+  lastmod?: string;
+
+  /** Change frequency hint for search engines */
+  changefreq?: SitemapChangeFreq;
+
+  /** Priority relative to other URLs on the site (0.0-1.0) */
+  priority?: number;
+}
+
+/**
+ * Complete sitemap data structure.
+ */
+export interface SitemapData {
+  /** All URL entries in the sitemap */
+  entries: SitemapEntry[];
+
+  /** Total number of entries */
+  totalEntries: number;
+
+  /** Whether the sitemap was truncated due to size limits */
+  truncated: boolean;
+
+  /** Generation timestamp */
+  generatedAt: string;
+
+  /** Base URL used for canonical URL generation */
+  baseUrl: string;
+}
+
+/**
+ * Generates Next.js-compatible sitemap entries for blog platform integration.
+ *
+ * @param site - The published site information
+ * @param articles - Array of published articles
+ * @param authors - Array of published authors (optional)
+ * @param options - Sitemap generation options
+ * @returns Array of Next.js MetadataRoute.Sitemap compatible entries
+ *
+ * @example
+ * ```typescript
+ * // In your Next.js app/sitemap.ts file:
+ * import { generateBlogSitemapEntries } from '@xexr/blog-platform';
+ * import type { MetadataRoute } from 'next';
+ *
+ * export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
+ *   const blogEntries = await generateBlogSitemapEntries(site, articles, authors, {
+ *     includeAuthorPages: true,
+ *     includePaginationPages: true,
+ *     changeFrequency: { articles: 'monthly' }
+ *   });
+ *
+ *   return [
+ *     // Your existing site routes
+ *     { url: 'https://yoursite.com', lastModified: new Date(), priority: 1 },
+ *     { url: 'https://yoursite.com/about', lastModified: new Date() },
+ *     // Blog entries
+ *     ...blogEntries
+ *   ];
+ * }
+ * ```
+ */
+export async function generateBlogSitemapEntries(
+  site: PublishedSite,
+  articles: readonly PublishedArticle[],
+  authors: readonly PublishedAuthor[] = [],
+  options: SitemapOptions = {}
+): Promise<NextjsSitemapEntry[]> {
+  const {
+    includeAuthorPages = true,
+    includePaginationPages = true,
+    articlesPerPage = 10,
+    maxEntries = 50000,
+    changeFrequency = {},
+    priority = {},
+  } = options;
+
+  const entries: NextjsSitemapEntry[] = [];
+  const baseUrl = normalizeDomain(
+    options.canonical?.domain ?? site.domain,
+    options.canonical?.forceHttps ?? true
+  );
+
+  const pathPrefix = options.canonical?.pathPrefix ?? '/blog';
+
+  // Add blog home page
+  entries.push({
+    url: `${baseUrl}${pathPrefix}`,
+    lastModified: getLatestModificationDate(articles),
+    changeFrequency: changeFrequency.homePage ?? 'daily',
+    priority: priority.homePage ?? 1.0,
+  });
+
+  // Add individual article pages
+  articles.forEach(article => {
+    if (entries.length >= maxEntries) return;
+
+    const articleUrl = generateCanonicalUrl(article, options.canonical);
+    entries.push({
+      url: articleUrl,
+      lastModified: article.updatedAt,
+      changeFrequency: changeFrequency.articles ?? 'monthly',
+      priority: priority.articles ?? 0.8,
+    });
+  });
+
+  // Add author pages if enabled
+  if (includeAuthorPages) {
+    authors.forEach(author => {
+      if (entries.length >= maxEntries) return;
+
+      const authorUrl = `${baseUrl}${pathPrefix}/authors/${author.slug}`;
+
+      // Find the latest article by this author for lastModified
+      const authorArticles = articles.filter(article =>
+        article.author?.id === author.id
+      );
+      const latestAuthorMod = getLatestModificationDate(authorArticles);
+
+      entries.push({
+        url: authorUrl,
+        lastModified: latestAuthorMod,
+        changeFrequency: changeFrequency.authorPages ?? 'weekly',
+        priority: priority.authorPages ?? 0.6,
+      });
+    });
+  }
+
+  // Add pagination pages if enabled
+  if (includePaginationPages && articles.length > articlesPerPage) {
+    const totalPages = Math.ceil(articles.length / articlesPerPage);
+
+    for (let page = 2; page <= totalPages; page++) {
+      if (entries.length >= maxEntries) break;
+
+      entries.push({
+        url: `${baseUrl}${pathPrefix}?page=${page}`,
+        lastModified: getLatestModificationDate(articles),
+        changeFrequency: changeFrequency.paginationPages ?? 'daily',
+        priority: priority.paginationPages ?? 0.5,
+      });
+    }
+  }
+
+  return entries;
+}
+
+/**
+ * Legacy sitemap generation for backward compatibility.
+ * @deprecated Use generateBlogSitemapEntries for Next.js integration
+ *
+ * @param site - The published site information
+ * @param articles - Array of published articles
+ * @param authors - Array of published authors (optional)
+ * @param options - Sitemap generation options
+ * @returns Complete sitemap data
+ */
+export function generateSitemap(
+  site: PublishedSite,
+  articles: readonly PublishedArticle[],
+  authors: readonly PublishedAuthor[] = [],
+  options: SitemapOptions = {}
+): SitemapData {
+  const {
+    includeAuthorPages = true,
+    includePaginationPages = true,
+    articlesPerPage = 10,
+    maxEntries = 50000,
+    changeFrequency = {},
+    priority = {},
+  } = options;
+
+  const entries: SitemapEntry[] = [];
+  const baseUrl = normalizeDomain(
+    options.canonical?.domain ?? site.domain,
+    options.canonical?.forceHttps ?? true
+  );
+
+  const pathPrefix = options.canonical?.pathPrefix ?? '/blog';
+  const generatedAt = new Date().toISOString();
+
+  // Calculate total potential entries to determine if truncation will occur
+  let potentialEntries = 1; // Home page
+  potentialEntries += articles.length; // Article pages
+  if (includeAuthorPages) {
+    potentialEntries += authors.length; // Author pages
+  }
+  if (includePaginationPages && articles.length > articlesPerPage) {
+    const totalPages = Math.ceil(articles.length / articlesPerPage);
+    potentialEntries += totalPages - 1; // Pagination pages (excluding page 1 which is home)
+  }
+
+  const willTruncate = potentialEntries > maxEntries;
+
+  // Add blog home page
+  entries.push({
+    loc: `${baseUrl}${pathPrefix}`,
+    lastmod: getLatestModificationDate(articles),
+    changefreq: changeFrequency.homePage ?? 'daily',
+    priority: priority.homePage ?? 1.0,
+  });
+
+  // Add individual article pages
+  articles.forEach(article => {
+    if (entries.length >= maxEntries) return;
+
+    const articleUrl = generateCanonicalUrl(article, options.canonical);
+    entries.push({
+      loc: articleUrl,
+      lastmod: article.updatedAt,
+      changefreq: changeFrequency.articles ?? 'monthly',
+      priority: priority.articles ?? 0.8,
+    });
+  });
+
+  // Add author pages if enabled
+  if (includeAuthorPages) {
+    authors.forEach(author => {
+      if (entries.length >= maxEntries) return;
+
+      const authorUrl = `${baseUrl}${pathPrefix}/authors/${author.slug}`;
+
+      // Find the latest article by this author for lastmod
+      const authorArticles = articles.filter(article =>
+        article.author?.id === author.id
+      );
+      const latestAuthorMod = getLatestModificationDate(authorArticles);
+
+      entries.push({
+        loc: authorUrl,
+        lastmod: latestAuthorMod,
+        changefreq: changeFrequency.authorPages ?? 'weekly',
+        priority: priority.authorPages ?? 0.6,
+      });
+    });
+  }
+
+  // Add pagination pages if enabled
+  if (includePaginationPages && articles.length > articlesPerPage) {
+    const totalPages = Math.ceil(articles.length / articlesPerPage);
+
+    for (let page = 2; page <= totalPages; page++) {
+      if (entries.length >= maxEntries) break;
+
+      entries.push({
+        loc: `${baseUrl}${pathPrefix}?page=${page}`,
+        lastmod: getLatestModificationDate(articles),
+        changefreq: changeFrequency.paginationPages ?? 'daily',
+        priority: priority.paginationPages ?? 0.5,
+      });
+    }
+  }
+
+  return {
+    entries,
+    totalEntries: entries.length,
+    truncated: willTruncate,
+    generatedAt,
+    baseUrl,
+  };
+}
+
+/**
+ * Converts sitemap data to XML format.
+ *
+ * @param sitemapData - The sitemap data to convert
+ * @returns XML string in sitemap format
+ *
+ * @example
+ * ```typescript
+ * const sitemap = generateSitemap(site, articles);
+ * const xmlString = sitemapToXml(sitemap);
+ * // Use in API route response
+ * ```
+ */
+export function sitemapToXml(sitemapData: SitemapData): string {
+  const xmlHeader = '<?xml version="1.0" encoding="UTF-8"?>';
+  const urlsetOpen = '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">';
+  const urlsetClose = '</urlset>';
+
+  const urlEntries = sitemapData.entries.map(entry => {
+    const elements: string[] = [];
+
+    elements.push(`  <url>`);
+    elements.push(`    <loc>${escapeXml(entry.loc)}</loc>`);
+
+    if (entry.lastmod) {
+      elements.push(`    <lastmod>${escapeXml(entry.lastmod)}</lastmod>`);
+    }
+
+    if (entry.changefreq) {
+      elements.push(`    <changefreq>${escapeXml(entry.changefreq)}</changefreq>`);
+    }
+
+    if (entry.priority !== undefined) {
+      elements.push(`    <priority>${entry.priority.toFixed(1)}</priority>`);
+    }
+
+    elements.push(`  </url>`);
+
+    return elements.join('\n');
+  });
+
+  return [
+    xmlHeader,
+    urlsetOpen,
+    ...urlEntries,
+    urlsetClose,
+  ].join('\n');
+}
+
+/**
+ * Generates a sitemap index for large blogs that need multiple sitemaps.
+ *
+ * @param sitemaps - Array of sitemap information
+ * @param baseUrl - Base URL for the site
+ * @returns XML string for sitemap index
+ *
+ * @example
+ * ```typescript
+ * const sitemapIndex = generateSitemapIndex([
+ *   { url: 'https://example.com/sitemap-articles.xml', lastmod: '2023-01-01T00:00:00Z' },
+ *   { url: 'https://example.com/sitemap-authors.xml', lastmod: '2023-01-01T00:00:00Z' }
+ * ], 'https://example.com');
+ * ```
+ */
+export function generateSitemapIndex(
+  sitemaps: readonly { url: string; lastmod?: string }[],
+  _baseUrl: string
+): string {
+  const xmlHeader = '<?xml version="1.0" encoding="UTF-8"?>';
+  const indexOpen = '<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">';
+  const indexClose = '</sitemapindex>';
+
+  const sitemapEntries = sitemaps.map(sitemap => {
+    const elements: string[] = [];
+
+    elements.push(`  <sitemap>`);
+    elements.push(`    <loc>${escapeXml(sitemap.url)}</loc>`);
+
+    if (sitemap.lastmod) {
+      elements.push(`    <lastmod>${escapeXml(sitemap.lastmod)}</lastmod>`);
+    }
+
+    elements.push(`  </sitemap>`);
+
+    return elements.join('\n');
+  });
+
+  return [
+    xmlHeader,
+    indexOpen,
+    ...sitemapEntries,
+    indexClose,
+  ].join('\n');
+}
+
+/**
+ * Validates sitemap data for compliance with search engine guidelines.
+ *
+ * @param sitemapData - The sitemap data to validate
+ * @returns Validation results with errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const sitemap = generateSitemap(site, articles);
+ * const validation = validateSitemap(sitemap);
+ *
+ * if (validation.errors.length > 0) {
+ *   console.error('Sitemap errors:', validation.errors);
+ * }
+ * ```
+ */
+export function validateSitemap(sitemapData: SitemapData): {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+} {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // Check entry count
+  if (sitemapData.entries.length === 0) {
+    errors.push('Sitemap must contain at least one URL');
+  } else if (sitemapData.entries.length > 50000) {
+    errors.push('Sitemap contains more than 50,000 URLs (Google limit)');
+  }
+
+  // Check for truncation
+  if (sitemapData.truncated) {
+    warnings.push('Sitemap was truncated due to size limits');
+  }
+
+  // Validate individual entries
+  sitemapData.entries.forEach((entry, index) => {
+    // Validate URL format
+    try {
+      new URL(entry.loc);
+    } catch {
+      errors.push(`Invalid URL at entry ${index + 1}: ${entry.loc}`);
+    }
+
+    // Validate priority range
+    if (entry.priority !== undefined && (entry.priority < 0 || entry.priority > 1)) {
+      errors.push(`Invalid priority at entry ${index + 1}: must be between 0.0 and 1.0`);
+    }
+
+    // Validate lastmod format
+    if (entry.lastmod && !isValidISODate(entry.lastmod)) {
+      errors.push(`Invalid lastmod date at entry ${index + 1}: ${entry.lastmod}`);
+    }
+
+    // Check URL length (Google limit is 2048 characters)
+    if (entry.loc.length > 2048) {
+      warnings.push(`URL at entry ${index + 1} exceeds 2048 character limit`);
+    }
+  });
+
+  // Check for duplicate URLs
+  const urlCounts = new Map<string, number>();
+  sitemapData.entries.forEach(entry => {
+    const count = urlCounts.get(entry.loc) ?? 0;
+    urlCounts.set(entry.loc, count + 1);
+  });
+
+  urlCounts.forEach((count, url) => {
+    if (count > 1) {
+      errors.push(`Duplicate URL found: ${url} (appears ${count} times)`);
+    }
+  });
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Gets the latest modification date from an array of articles.
+ */
+function getLatestModificationDate(articles: readonly PublishedArticle[]): string {
+  if (articles.length === 0) {
+    return new Date().toISOString();
+  }
+
+  const latestDate = articles.reduce((latest, article) => {
+    const articleDate = new Date(article.updatedAt);
+    return articleDate > latest ? articleDate : latest;
+  }, new Date(articles[0]!.updatedAt));
+
+  return latestDate.toISOString();
+}
+
+/**
+ * Creates a separate sitemap specifically for blog content.
+ * Useful for large sites that need to split sitemaps by content type.
+ *
+ * @param site - The published site information
+ * @param articles - Array of published articles
+ * @param authors - Array of published authors (optional)
+ * @param options - Sitemap generation options
+ * @returns Next.js sitemap function
+ *
+ * @example
+ * ```typescript
+ * // app/blog-sitemap/route.ts - separate blog sitemap endpoint
+ * import { createBlogSitemapRoute } from '@xexr/blog-platform';
+ *
+ * export const GET = createBlogSitemapRoute(site, articles, authors, {
+ *   includeAuthorPages: true,
+ *   articlesPerPage: 20
+ * });
+ * ```
+ */
+export function createBlogSitemapRoute(
+  site: PublishedSite,
+  articles: readonly PublishedArticle[],
+  authors: readonly PublishedAuthor[] = [],
+  options: SitemapOptions = {}
+) {
+  return async function GET() {
+    const entries = await generateBlogSitemapEntries(site, articles, authors, options);
+
+    // Convert to Next.js sitemap format and return as XML
+    const xmlEntries = entries.map(entry => ({
+      loc: entry.url,
+      lastmod: typeof entry.lastModified === 'string'
+        ? entry.lastModified
+        : entry.lastModified?.toISOString(),
+      changefreq: entry.changeFrequency,
+      priority: entry.priority,
+    }));
+
+    const sitemapData = {
+      entries: xmlEntries,
+      totalEntries: xmlEntries.length,
+      truncated: false,
+      generatedAt: new Date().toISOString(),
+      baseUrl: normalizeDomain(
+        options.canonical?.domain ?? site.domain,
+        options.canonical?.forceHttps ?? true
+      ),
+    };
+
+    const xml = sitemapToXml(sitemapData);
+
+    return new Response(xml, {
+      headers: {
+        'Content-Type': 'application/xml',
+        'Cache-Control': 'public, max-age=3600, s-maxage=3600',
+      },
+    });
+  };
+}
+
+/**
+ * Configuration interface for blog data fetching.
+ * Used to fetch blog data for sitemap generation.
+ */
+export interface BlogSitemapConfig {
+  /** Function to fetch site data */
+  getSite: () => Promise<PublishedSite>;
+
+  /** Function to fetch published articles */
+  getArticles: () => Promise<readonly PublishedArticle[]>;
+
+  /** Function to fetch authors (optional) */
+  getAuthors?: () => Promise<readonly PublishedAuthor[]>;
+
+  /** Sitemap generation options */
+  options?: SitemapOptions;
+}
+
+/**
+ * Higher-order function that creates a Next.js sitemap function with data fetching.
+ * Ideal for dynamic blog content that needs to be fetched at sitemap generation time.
+ *
+ * @param config - Configuration for fetching blog data
+ * @returns Next.js sitemap function
+ *
+ * @example
+ * ```typescript
+ * // app/sitemap.ts
+ * import { createDynamicBlogSitemap } from '@xexr/blog-platform';
+ * import { getBlogData } from './lib/blog';
+ *
+ * export default createDynamicBlogSitemap({
+ *   getSite: () => getBlogData().site,
+ *   getArticles: () => getBlogData().articles,
+ *   getAuthors: () => getBlogData().authors,
+ *   options: {
+ *     includeAuthorPages: true,
+ *     changeFrequency: { articles: 'weekly' }
+ *   }
+ * });
+ * ```
+ */
+export function createDynamicBlogSitemap(config: BlogSitemapConfig) {
+  return async function sitemap(): Promise<NextjsSitemapEntry[]> {
+    const site = await config.getSite();
+    const articles = await config.getArticles();
+    const authors = config.getAuthors ? await config.getAuthors() : [];
+
+    return generateBlogSitemapEntries(site, articles, authors, config.options);
+  };
+}
+
+/**
+ * Escapes special XML characters for safe inclusion in XML content.
+ */
+function escapeXml(text: string): string {
+  const xmlEscapes: Record<string, string> = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#x27;',
+  };
+
+  return text.replace(/[&<>"']/g, char => xmlEscapes[char] ?? char);
+}
+
+/**
+ * Validates if a string is a valid ISO 8601 date.
+ */
+function isValidISODate(dateString: string): boolean {
+  try {
+    const date = new Date(dateString);
+    const isoString = date.toISOString();
+
+    // Handle both formats: with and without milliseconds
+    // 2023-01-01T00:00:00.000Z and 2023-01-01T00:00:00Z are both valid
+    const normalizedInput = dateString.endsWith('Z') && !dateString.includes('.')
+      ? dateString.replace('Z', '.000Z')
+      : dateString;
+
+    return isoString === normalizedInput && !isNaN(date.getTime());
+  } catch {
+    return false;
+  }
+}