@xexr/blog-platform 1.0.6 → 1.0.8

package/dist/lib/seo.ts

@@ -0,0 +1,295 @@
+/**
+ * SEO utilities for canonical URL generation and validation.
+ *
+ * These utilities ensure proper canonical URL structure for SEO optimization,
+ * preventing duplicate content issues and improving search engine indexing.
+ */
+
+import type { PublishedArticle, PublishedSite } from '../types/contracts';
+
+/**
+ * Configuration options for canonical URL generation.
+ */
+export interface CanonicalUrlOptions {
+  /** Whether to force HTTPS protocol (default: true) */
+  forceHttps?: boolean;
+
+  /** Whether to remove trailing slashes (default: true) */
+  removeTrailingSlash?: boolean;
+
+  /** Custom domain override (uses site.domain if not provided) */
+  domain?: string;
+
+  /** Custom path prefix (default: '/blog') */
+  pathPrefix?: string;
+}
+
+/**
+ * Normalizes a domain by ensuring proper protocol and removing trailing slashes.
+ *
+ * @param domain - The domain to normalize
+ * @param forceHttps - Whether to force HTTPS protocol
+ * @returns The normalized domain
+ *
+ * @example
+ * ```typescript
+ * normalizeDomain('example.com') // 'https://example.com'
+ * normalizeDomain('http://example.com/') // 'https://example.com'
+ * normalizeDomain('https://example.com', false) // 'https://example.com'
+ * ```
+ */
+export function normalizeDomain(domain: string, forceHttps = true): string {
+  let normalized = domain.trim();
+
+  // Remove trailing slashes
+  normalized = normalized.replace(/\/+$/, '');
+
+  // Add protocol if missing
+  if (!/^https?:\/\//.exec(normalized)) {
+    normalized = `${forceHttps ? 'https' : 'http'}://${normalized}`;
+  }
+
+  // Force HTTPS if requested
+  if (forceHttps && normalized.startsWith('http://')) {
+    normalized = normalized.replace('http://', 'https://');
+  }
+
+  return normalized;
+}
+
+/**
+ * Validates and normalizes a slug for URL usage.
+ *
+ * @param slug - The slug to validate and normalize
+ * @returns The normalized slug
+ * @throws Error if slug is invalid
+ *
+ * @example
+ * ```typescript
+ * normalizeSlug('hello-world') // 'hello-world'
+ * normalizeSlug('Hello World!') // throws Error
+ * normalizeSlug('hello--world') // 'hello-world'
+ * ```
+ */
+export function normalizeSlug(slug: string): string {
+  const trimmed = slug.trim();
+
+  if (!trimmed) {
+    throw new Error('Slug cannot be empty');
+  }
+
+  // Check if slug contains only valid characters
+  if (!/^[a-z0-9-]+$/.test(trimmed)) {
+    throw new Error('Slug can only contain lowercase letters, numbers, and hyphens');
+  }
+
+  // Remove multiple consecutive hyphens
+  const normalized = trimmed.replace(/-+/g, '-');
+
+  // Remove leading/trailing hyphens
+  const clean = normalized.replace(/^-+|-+$/g, '');
+
+  if (!clean) {
+    throw new Error('Slug cannot consist only of hyphens');
+  }
+
+  return clean;
+}
+
+/**
+ * Generates a canonical URL for an article.
+ *
+ * @param article - The published article
+ * @param options - Configuration options for URL generation
+ * @returns The canonical URL
+ * @throws Error if article or site data is invalid
+ *
+ * @example
+ * ```typescript
+ * const article = {
+ *   slug: 'hello-world',
+ *   site: { domain: 'example.com' },
+ *   // ... other fields
+ * };
+ *
+ * generateCanonicalUrl(article)
+ * // 'https://example.com/blog/hello-world'
+ *
+ * generateCanonicalUrl(article, { pathPrefix: '/posts' })
+ * // 'https://example.com/posts/hello-world'
+ * ```
+ */
+export function generateCanonicalUrl(
+  article: PublishedArticle,
+  options: CanonicalUrlOptions = {}
+): string {
+  const {
+    forceHttps = true,
+    removeTrailingSlash = true,
+    domain = article.site.domain,
+    pathPrefix = '/blog'
+  } = options;
+
+  if (!domain) {
+    throw new Error('Domain is required for canonical URL generation');
+  }
+
+  if (!article.slug) {
+    throw new Error('Article slug is required for canonical URL generation');
+  }
+
+  // Validate and normalize inputs
+  const normalizedDomain = normalizeDomain(domain, forceHttps);
+  const normalizedSlug = normalizeSlug(article.slug);
+
+  // Ensure path prefix starts with '/' and doesn't end with '/'
+  const cleanPrefix = pathPrefix
+    .replace(/^(?!\/)/, '/') // Add leading slash if missing
+    .replace(/\/+$/, ''); // Remove trailing slashes
+
+  // Construct the canonical URL
+  let canonicalUrl = `${normalizedDomain}${cleanPrefix}/${normalizedSlug}`;
+
+  // Remove trailing slash if requested
+  if (removeTrailingSlash) {
+    canonicalUrl = canonicalUrl.replace(/\/+$/, '');
+  }
+
+  return canonicalUrl;
+}
+
+/**
+ * Generates a canonical URL for an article from site and slug data.
+ * Useful when you don't have a full PublishedArticle object.
+ *
+ * @param site - The published site
+ * @param slug - The article slug
+ * @param options - Configuration options for URL generation
+ * @returns The canonical URL
+ *
+ * @example
+ * ```typescript
+ * const site = { domain: 'example.com', ... };
+ * generateCanonicalUrlFromSlug(site, 'hello-world')
+ * // 'https://example.com/blog/hello-world'
+ * ```
+ */
+export function generateCanonicalUrlFromSlug(
+  site: PublishedSite,
+  slug: string,
+  options: CanonicalUrlOptions = {}
+): string {
+  return generateCanonicalUrl(
+    {
+      slug,
+      site,
+      // Minimal required fields for canonical URL generation
+      id: '',
+      title: '',
+      excerpt: '',
+      content: '',
+      readingSeconds: 0,
+      wordCount: 0,
+      publishedAt: '',
+      updatedAt: '',
+      author: null,
+      meta: { keywords: [] },
+      version: 1
+    },
+    options
+  );
+}
+
+/**
+ * Validates if a URL is a valid canonical URL format.
+ *
+ * @param url - The URL to validate
+ * @returns True if the URL is valid for canonical use
+ *
+ * @example
+ * ```typescript
+ * isValidCanonicalUrl('https://example.com/blog/hello-world') // true
+ * isValidCanonicalUrl('http://example.com/blog/hello-world') // true
+ * isValidCanonicalUrl('example.com/blog/hello-world') // false (missing protocol)
+ * isValidCanonicalUrl('https://example.com/blog/hello world') // false (spaces)
+ * ```
+ */
+export function isValidCanonicalUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+
+    // Must be HTTP or HTTPS
+    if (!['http:', 'https:'].includes(parsed.protocol)) {
+      return false;
+    }
+
+    // Must have a valid hostname (not empty or just slashes)
+    if (!parsed.hostname || parsed.hostname.length === 0) {
+      return false;
+    }
+
+    // Check for URLs with empty hostname like 'https:///path'
+    if (/^https?:\/\/\//.exec(url) && !/^https?:\/\/[^\/]/.exec(url)) {
+      return false;
+    }
+
+    // Path should not contain unencoded spaces or other problematic characters
+    // Check the original URL string since URL constructor auto-encodes
+    if (url.includes(' ')) {
+      return false;
+    }
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Extracts the base URL (protocol + hostname + port) from a canonical URL.
+ *
+ * @param canonicalUrl - The canonical URL
+ * @returns The base URL
+ *
+ * @example
+ * ```typescript
+ * getBaseUrl('https://example.com/blog/hello-world') // 'https://example.com'
+ * getBaseUrl('https://blog.example.com:8080/posts/test') // 'https://blog.example.com:8080'
+ * ```
+ */
+export function getBaseUrl(canonicalUrl: string): string {
+  try {
+    const parsed = new URL(canonicalUrl);
+    return `${parsed.protocol}//${parsed.host}`;
+  } catch {
+    throw new Error('Invalid canonical URL provided');
+  }
+}
+
+/**
+ * Updates an article's canonical URL in its meta field.
+ *
+ * @param article - The article to update
+ * @param options - Configuration options for URL generation
+ * @returns A new article object with updated canonical URL
+ *
+ * @example
+ * ```typescript
+ * const updatedArticle = updateArticleCanonicalUrl(article);
+ * console.log(updatedArticle.meta.canonicalUrl); // Generated canonical URL
+ * ```
+ */
+export function updateArticleCanonicalUrl(
+  article: PublishedArticle,
+  options: CanonicalUrlOptions = {}
+): PublishedArticle {
+  const canonicalUrl = generateCanonicalUrl(article, options);
+
+  return {
+    ...article,
+    meta: {
+      ...article.meta,
+      canonicalUrl
+    }
+  };
+}