@xexr/blog-platform 1.0.7 → 1.0.9

package/dist/lib/sitemap.ts

@@ -0,0 +1,738 @@
+/**
+ * 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";
+import { buildAuthorPath } from "./urls";
+
+/**
+ * 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}${buildAuthorPath(pathPrefix, 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}${buildAuthorPath(pathPrefix, 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;
+  }
+}