@djangocfg/seo 2.1.50

package/src/types/index.ts

@@ -0,0 +1,222 @@
+/**
+ * @djangocfg/seo - Types
+ * Shared types for SEO module
+ */
+
+// ============================================
+// Google Search Console Types
+// ============================================
+
+export type IndexingVerdict =
+  | 'PASS'
+  | 'PARTIAL'
+  | 'FAIL'
+  | 'NEUTRAL'
+  | 'VERDICT_UNSPECIFIED';
+
+export type CoverageState =
+  | 'SUBMITTED_AND_INDEXED'
+  | 'DUPLICATE_WITHOUT_USER_SELECTED_CANONICAL'
+  | 'DUPLICATE_GOOGLE_CHOSE_DIFFERENT_CANONICAL'
+  | 'NOT_INDEXED'
+  | 'URL_NOT_FOUND'
+  | 'CRAWLED_CURRENTLY_NOT_INDEXED'
+  | 'DISCOVERED_CURRENTLY_NOT_INDEXED'
+  | 'BLOCKED_DUE_TO_UNAUTHORIZED_REQUEST'
+  | 'BLOCKED_BY_ROBOTS_TXT'
+  | 'INDEXED_NOT_SUBMITTED_IN_SITEMAP'
+  | 'COVERAGE_STATE_UNSPECIFIED';
+
+export type IndexingState =
+  | 'INDEXING_ALLOWED'
+  | 'BLOCKED_BY_META_TAG'
+  | 'BLOCKED_BY_HTTP_HEADER'
+  | 'BLOCKED_BY_ROBOTS_TXT'
+  | 'INDEXING_STATE_UNSPECIFIED';
+
+export type RobotsTxtState =
+  | 'ALLOWED'
+  | 'DISALLOWED'
+  | 'ROBOTS_TXT_STATE_UNSPECIFIED';
+
+export type PageFetchState =
+  | 'SUCCESSFUL'
+  | 'SOFT_404'
+  | 'BLOCKED_ROBOTS_TXT'
+  | 'NOT_FOUND'
+  | 'ACCESS_DENIED'
+  | 'SERVER_ERROR'
+  | 'REDIRECT_ERROR'
+  | 'ACCESS_FORBIDDEN'
+  | 'BLOCKED_4XX'
+  | 'INTERNAL_CRAWL_ERROR'
+  | 'INVALID_URL'
+  | 'PAGE_FETCH_STATE_UNSPECIFIED';
+
+export interface UrlInspectionResult {
+  url: string;
+  inspectionResultLink?: string;
+  indexStatusResult: {
+    verdict: IndexingVerdict;
+    coverageState: CoverageState;
+    indexingState: IndexingState;
+    robotsTxtState: RobotsTxtState;
+    pageFetchState: PageFetchState;
+    lastCrawlTime?: string;
+    crawledAs?: 'DESKTOP' | 'MOBILE';
+    googleCanonical?: string;
+    userCanonical?: string;
+    sitemap?: string[];
+    referringUrls?: string[];
+  };
+  mobileUsabilityResult?: {
+    verdict: IndexingVerdict;
+    issues?: Array<{
+      issueType: string;
+      message: string;
+    }>;
+  };
+  richResultsResult?: {
+    verdict: IndexingVerdict;
+    detectedItems?: Array<{
+      richResultType: string;
+      items?: Array<{
+        name: string;
+        issues?: Array<{
+          issueMessage: string;
+          severity: 'ERROR' | 'WARNING';
+        }>;
+      }>;
+    }>;
+  };
+}
+
+// ============================================
+// SEO Issue Types
+// ============================================
+
+export type IssueSeverity = 'critical' | 'error' | 'warning' | 'info';
+
+export type IssueCategory =
+  | 'indexing'
+  | 'crawling'
+  | 'content'
+  | 'technical'
+  | 'mobile'
+  | 'performance'
+  | 'structured-data'
+  | 'security';
+
+export interface SeoIssue {
+  id: string;
+  url: string;
+  category: IssueCategory;
+  severity: IssueSeverity;
+  title: string;
+  description: string;
+  recommendation: string;
+  detectedAt: string;
+  metadata?: Record<string, unknown>;
+}
+
+// ============================================
+// Crawler Types
+// ============================================
+
+export interface CrawlResult {
+  url: string;
+  statusCode: number;
+  contentType?: string;
+  title?: string;
+  metaDescription?: string;
+  metaRobots?: string;
+  canonicalUrl?: string;
+  h1?: string[];
+  h2?: string[];
+  links: {
+    internal: string[];
+    external: string[];
+  };
+  images: Array<{
+    src: string;
+    alt?: string;
+    hasAlt: boolean;
+  }>;
+  loadTime: number;
+  /** Time to first byte (ms) */
+  ttfb?: number;
+  contentLength?: number;
+  errors: string[];
+  warnings: string[];
+  crawledAt: string;
+}
+
+export interface CrawlerConfig {
+  maxPages?: number;
+  maxDepth?: number;
+  concurrency?: number;
+  timeout?: number;
+  userAgent?: string;
+  respectRobotsTxt?: boolean;
+  includePatterns?: string[];
+  excludePatterns?: string[];
+}
+
+// ============================================
+// Report Types
+// ============================================
+
+export interface SeoReport {
+  id: string;
+  siteUrl: string;
+  generatedAt: string;
+  summary: ReportSummary;
+  issues: SeoIssue[];
+  urlInspections: UrlInspectionResult[];
+  crawlResults: CrawlResult[];
+  recommendations: Recommendation[];
+}
+
+export interface ReportSummary {
+  totalUrls: number;
+  indexedUrls: number;
+  notIndexedUrls: number;
+  issuesByCategory: Record<IssueCategory, number>;
+  issuesBySeverity: Record<IssueSeverity, number>;
+  healthScore: number; // 0-100
+}
+
+export interface Recommendation {
+  priority: 1 | 2 | 3 | 4 | 5;
+  category: IssueCategory;
+  title: string;
+  description: string;
+  affectedUrls: string[];
+  estimatedImpact: 'high' | 'medium' | 'low';
+  actionItems: string[];
+}
+
+// ============================================
+// Configuration Types
+// ============================================
+
+export interface GoogleConsoleConfig {
+  serviceAccountPath?: string;
+  serviceAccountJson?: {
+    client_email: string;
+    private_key: string;
+    project_id?: string;
+  };
+  siteUrl: string;
+  /** GSC property format: 'sc-domain:example.com' or 'https://example.com'. Auto-detected if not provided. */
+  gscSiteUrl?: string;
+}
+
+export interface SeoModuleConfig {
+  googleConsole?: GoogleConsoleConfig;
+  crawler?: CrawlerConfig;
+  reports?: {
+    outputDir: string;
+    formats: ('json' | 'markdown')[];
+  };
+}

package/src/utils/index.ts

@@ -0,0 +1,154 @@
+/**
+ * @djangocfg/seo - Utilities
+ * Shared utility functions
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+
+/**
+ * Load URLs from a file (one URL per line)
+ */
+export function loadUrlsFromFile(filePath: string): string[] {
+  if (!existsSync(filePath)) {
+    throw new Error(`File not found: ${filePath}`);
+  }
+
+  const content = readFileSync(filePath, 'utf-8');
+  return content
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith('#'));
+}
+
+/**
+ * Extract URLs from sitemap XML content
+ */
+export function extractUrlsFromSitemap(xmlContent: string): string[] {
+  const urls: string[] = [];
+  const locRegex = /<loc>([^<]+)<\/loc>/g;
+  let match;
+
+  while ((match = locRegex.exec(xmlContent)) !== null) {
+    if (match[1]) {
+      urls.push(match[1].trim());
+    }
+  }
+
+  return urls;
+}
+
+/**
+ * Normalize URL for comparison
+ */
+export function normalizeUrl(url: string, baseUrl?: string): string {
+  try {
+    const parsed = new URL(url, baseUrl);
+    parsed.hash = '';
+    // Remove trailing slash
+    if (parsed.pathname.endsWith('/') && parsed.pathname !== '/') {
+      parsed.pathname = parsed.pathname.slice(0, -1);
+    }
+    return parsed.href;
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * Check if URL belongs to the same domain
+ */
+export function isSameDomain(url: string, baseUrl: string): boolean {
+  try {
+    const urlHost = new URL(url).hostname;
+    const baseHost = new URL(baseUrl).hostname;
+    return urlHost === baseHost;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Format bytes to human readable string
+ */
+export function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B';
+
+  const units = ['B', 'KB', 'MB', 'GB'];
+  const k = 1024;
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${units[i]}`;
+}
+
+/**
+ * Format milliseconds to human readable string
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${Math.floor(ms / 60000)}m ${Math.round((ms % 60000) / 1000)}s`;
+}
+
+/**
+ * Simple hash function for generating IDs
+ */
+export function hash(str: string): string {
+  let h = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    h = (h << 5) - h + char;
+    h = h & h;
+  }
+  return Math.abs(h).toString(36);
+}
+
+/**
+ * Chunk array into smaller arrays
+ */
+export function chunk<T>(array: T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let i = 0; i < array.length; i += size) {
+    chunks.push(array.slice(i, i + size));
+  }
+  return chunks;
+}
+
+/**
+ * Sleep for a given number of milliseconds
+ */
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Retry a function with exponential backoff
+ */
+export async function retry<T>(
+  fn: () => Promise<T>,
+  options: {
+    retries?: number;
+    minTimeout?: number;
+    maxTimeout?: number;
+    factor?: number;
+  } = {}
+): Promise<T> {
+  const { retries = 3, minTimeout = 1000, maxTimeout = 30000, factor = 2 } = options;
+
+  let lastError: Error | undefined;
+  let timeout = minTimeout;
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error as Error;
+
+      if (attempt < retries) {
+        await sleep(timeout);
+        timeout = Math.min(timeout * factor, maxTimeout);
+      }
+    }
+  }
+
+  throw lastError;
+}