@momentumcms/plugins-seo 0.4.0

package/src/lib/analysis/seo-analysis.types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * SEO Analysis Result Types
+ *
+ * Types for the SEO scoring engine results.
+ */
+export interface SeoAnalysisResult {
+    /** Overall score (0-100) */
+    score: number;
+    /** Overall grade: 'good' (70+), 'warning' (40-69), 'poor' (0-39) */
+    grade: 'good' | 'warning' | 'poor';
+    /** Individual rule results */
+    rules: SeoRuleResult[];
+    /** ISO timestamp of when analysis was performed */
+    analyzedAt: string;
+    /** Collection slug */
+    collection: string;
+    /** Document ID */
+    documentId: string;
+    /** Focus keyword used for analysis */
+    focusKeyword?: string;
+}
+export interface SeoRuleResult {
+    /** Rule identifier */
+    id: string;
+    /** Rule display name */
+    name: string;
+    /** Score for this rule (0-100) */
+    score: number;
+    /** Weight in total score */
+    weight: number;
+    /** Human-readable recommendation (null if passing) */
+    recommendation: string | null;
+}
+/**
+ * Structured meta tags returned by the meta tag API.
+ */
+export interface MetaTags {
+    /** The page title */
+    title: string;
+    /** Meta tags (name or property based) */
+    meta: Array<{
+        name?: string;
+        property?: string;
+        content: string;
+    }>;
+    /** Link tags (canonical, etc.) */
+    link: Array<{
+        rel: string;
+        href: string;
+    }>;
+    /** Script tags (JSON-LD) */
+    script: Array<{
+        type: string;
+        innerHTML: string;
+    }>;
+}

package/src/lib/analysis/seo-analyzer.d.ts

@@ -0,0 +1,36 @@
+/**
+ * SEO Analysis Engine
+ *
+ * Scoring engine with built-in rules for SEO content quality assessment.
+ */
+import type { SeoScoringRule, SeoScoringContext, SeoAnalysisConfig } from '../seo-config.types';
+import type { SeoAnalysisResult } from './seo-analysis.types';
+/**
+ * Strip HTML tags and return plain text.
+ */
+export declare function extractTextContent(doc: Record<string, unknown>): string;
+/**
+ * Extract headings from HTML content in document fields.
+ */
+export declare function extractHeadings(doc: Record<string, unknown>): Array<{
+    level: number;
+    text: string;
+}>;
+export declare function createTitleLengthRule(config?: SeoAnalysisConfig): SeoScoringRule;
+export declare function createDescriptionLengthRule(config?: SeoAnalysisConfig): SeoScoringRule;
+export declare function createKeywordInTitleRule(): SeoScoringRule;
+export declare function createKeywordInDescriptionRule(): SeoScoringRule;
+export declare function createKeywordDensityRule(config?: SeoAnalysisConfig): SeoScoringRule;
+export declare function createHeadingStructureRule(): SeoScoringRule;
+export declare function createOgDataRule(): SeoScoringRule;
+export declare function createCanonicalUrlRule(): SeoScoringRule;
+export declare function createContentLengthRule(): SeoScoringRule;
+export declare function createNoIndexWarningRule(): SeoScoringRule;
+/**
+ * Build the default set of scoring rules.
+ */
+export declare function buildDefaultRules(config?: SeoAnalysisConfig): SeoScoringRule[];
+/**
+ * Run SEO analysis on a document.
+ */
+export declare function analyzeSeo(context: SeoScoringContext, rules: SeoScoringRule[]): Omit<SeoAnalysisResult, 'analyzedAt' | 'collection' | 'documentId' | 'focusKeyword'>;

package/src/lib/dashboard/seo-analysis-handler.d.ts

@@ -0,0 +1,18 @@
+/**
+ * SEO Analysis Dashboard Handler
+ *
+ * Read-only Express endpoint for the admin dashboard to fetch
+ * SEO analysis data. Requires admin authentication.
+ *
+ * The seo-analysis collection is `managed: true` (no auto-generated
+ * REST routes), so this handler provides the only HTTP read path.
+ */
+import type { Router } from 'express';
+import type { MomentumAPI } from '@momentumcms/plugins/core';
+export interface DashboardHandlerOptions {
+    getApi: () => MomentumAPI | null;
+}
+/**
+ * Creates an Express router for the SEO dashboard read endpoint.
+ */
+export declare function createDashboardRouter(options: DashboardHandlerOptions): Router;

package/src/lib/meta/meta-builder.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Meta Tag Builder
+ *
+ * Builds structured meta tag data from SEO field data.
+ * Includes Open Graph, Twitter Card, canonical, and JSON-LD support.
+ */
+import type { SeoFieldData } from '../seo-config.types';
+import type { MetaTags } from '../analysis/seo-analysis.types';
+/**
+ * Build structured meta tags from document SEO data.
+ *
+ * Falls back through: ogTitle → metaTitle → doc title field
+ */
+export declare function buildMetaTags(doc: Record<string, unknown>, seo: SeoFieldData, _siteUrl?: string): MetaTags;

package/src/lib/meta/meta-handler.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Meta Tag API Express Handler
+ *
+ * Serves JSON meta tags at /meta/:collection/:id.
+ */
+import type { Router } from 'express';
+import type { MomentumAPI } from '@momentumcms/plugins/core';
+export interface MetaHandlerOptions {
+    getApi: () => MomentumAPI | null;
+    siteUrl?: string;
+    seoCollections: string[];
+}
+/**
+ * Creates an Express router for the meta tag API.
+ */
+export declare function createMetaRouter(options: MetaHandlerOptions): Router;

package/src/lib/robots/robots-handler.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Robots.txt Express Handler
+ *
+ * Serves robots.txt based on plugin configuration.
+ * When `getApi` is provided, reads settings from the seo-settings
+ * managed collection; falls back to the static config.
+ */
+import type { Router } from 'express';
+import type { RobotsConfig } from '../seo-config.types';
+import type { MomentumAPI } from '@momentumcms/plugins/core';
+export { generateRobotsTxt } from './robots-txt-generator';
+export interface RobotsHandlerOptions {
+    siteUrl: string;
+    config: RobotsConfig;
+    /** When provided, robots.txt is read from the seo-settings collection. */
+    getApi?: () => MomentumAPI | null;
+}
+/**
+ * Creates an Express router for the robots.txt endpoint.
+ *
+ * Returns `{ router, clearCache }` so the plugin can invalidate the
+ * cached response when settings change.
+ */
+export declare function createRobotsRouter(options: RobotsHandlerOptions): {
+    router: Router;
+    clearCache: () => void;
+};

package/src/lib/robots/robots-txt-generator.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Robots.txt Generator (browser-safe)
+ *
+ * Pure function to generate robots.txt content from configuration.
+ * Separated from robots-handler.ts to avoid pulling Express into
+ * the browser bundle (admin pages import this for the live preview).
+ */
+import type { RobotsConfig } from '../seo-config.types';
+/**
+ * Generate robots.txt content from configuration.
+ */
+export declare function generateRobotsTxt(siteUrl: string, config: RobotsConfig): string;

package/src/lib/seo-admin-routes.d.ts

@@ -0,0 +1,3 @@
+import type { PluginAdminRouteDescriptor } from '@momentumcms/core';
+
+export declare const seoAdminRoutes: PluginAdminRouteDescriptor[];

package/src/lib/seo-config.types.d.ts

@@ -0,0 +1,174 @@
+/**
+ * SEO Plugin Configuration Types
+ *
+ * All configuration interfaces for the Momentum CMS SEO plugin.
+ */
+/**
+ * SEO Plugin Configuration.
+ *
+ * @example
+ * ```typescript
+ * seoPlugin({
+ *   collections: ['posts', 'pages'],
+ *   siteUrl: 'https://example.com',
+ *   analysis: { titleLength: { min: 40, max: 65 } },
+ *   sitemap: { defaultPriority: 0.7 },
+ *   robots: { crawlDelay: 1 },
+ * })
+ * ```
+ */
+export interface SeoPluginConfig {
+    /** Enable/disable the SEO plugin. @default true */
+    enabled?: boolean;
+    /**
+     * Collection slugs to inject SEO fields into.
+     * Pass `'*'` to inject into all collections (except managed and internal).
+     */
+    collections: string[] | '*';
+    /**
+     * Collections to exclude from SEO field injection.
+     * Only effective when `collections` is `'*'`.
+     */
+    excludeCollections?: string[];
+    /**
+     * Base URL for the site (used in sitemaps, canonical URLs, Open Graph).
+     * e.g., `'https://example.com'`
+     */
+    siteUrl?: string;
+    /**
+     * SEO analysis configuration.
+     * - `true` (default): enable with default settings
+     * - `false`: disable analysis
+     * - object: custom thresholds and rules
+     */
+    analysis?: boolean | SeoAnalysisConfig;
+    /**
+     * Sitemap generation configuration.
+     * - `true` (default): enable with default settings
+     * - `false`: disable sitemap endpoint
+     * - object: custom sitemap settings
+     */
+    sitemap?: boolean | SitemapConfig;
+    /**
+     * Robots.txt configuration.
+     * - `true` (default): enable with default settings
+     * - `false`: disable robots.txt endpoint
+     * - object: custom robots.txt rules
+     */
+    robots?: boolean | RobotsConfig;
+    /**
+     * Meta tag API configuration.
+     * - `true` (default): enable
+     * - `false`: disable
+     */
+    metaApi?: boolean;
+    /**
+     * Admin dashboard configuration.
+     * - `true` (default): enable built-in dashboard
+     * - `false`: disable
+     * - object: override loadComponent and/or group
+     */
+    adminDashboard?: boolean | {
+        loadComponent?: unknown;
+        group?: string;
+    };
+}
+export interface SeoAnalysisConfig {
+    /** Run analysis asynchronously after save. @default true */
+    async?: boolean;
+    /** Custom scoring rules to add or override defaults */
+    rules?: SeoScoringRule[];
+    /** Title length thresholds */
+    titleLength?: {
+        min: number;
+        max: number;
+    };
+    /** Meta description length thresholds */
+    descriptionLength?: {
+        min: number;
+        max: number;
+    };
+    /** Target keyword density range (percentage) */
+    keywordDensity?: {
+        min: number;
+        max: number;
+    };
+    /** Collections to exclude from analysis */
+    excludeCollections?: string[];
+}
+export interface SeoScoringRule {
+    /** Unique rule identifier */
+    id: string;
+    /** Rule display name */
+    name: string;
+    /** Weight (0-100) in the total score */
+    weight: number;
+    /** Scoring function returning 0-100 */
+    score: (context: SeoScoringContext) => number;
+    /** Human-readable recommendation when score is low */
+    recommendation: (context: SeoScoringContext) => string | null;
+}
+export interface SeoScoringContext {
+    /** The SEO group field data */
+    seo: SeoFieldData;
+    /** The full document data */
+    doc: Record<string, unknown>;
+    /** The collection slug */
+    collection: string;
+    /** Extracted plain text from rich text fields */
+    textContent: string;
+    /** Extracted headings from rich text content */
+    headings: Array<{
+        level: number;
+        text: string;
+    }>;
+}
+export interface SeoFieldData {
+    metaTitle?: string;
+    metaDescription?: string;
+    canonicalUrl?: string;
+    focusKeyword?: string;
+    ogTitle?: string;
+    ogDescription?: string;
+    ogImage?: string | Record<string, unknown>;
+    ogType?: string;
+    twitterCard?: string;
+    noIndex?: boolean;
+    noFollow?: boolean;
+    excludeFromSitemap?: boolean;
+    structuredData?: unknown;
+}
+export type SitemapChangeFreq = 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+export interface SitemapConfig {
+    /** Collections to include (default: all with SEO fields) */
+    includeCollections?: string[];
+    /** Collections to exclude */
+    excludeCollections?: string[];
+    /** Default priority for sitemap entries (0.0-1.0). @default 0.5 */
+    defaultPriority?: number;
+    /** Per-collection priority overrides */
+    priorities?: Record<string, number>;
+    /** Default change frequency. @default 'weekly' */
+    defaultChangeFreq?: SitemapChangeFreq;
+    /** Per-collection change frequency overrides */
+    changeFreqs?: Record<string, SitemapChangeFreq>;
+    /** Cache TTL in milliseconds. @default 300000 (5 minutes) */
+    cacheTtl?: number;
+    /** Maximum URLs per sitemap file (for sitemap index). @default 50000 */
+    maxUrlsPerSitemap?: number;
+    /** Custom URL builder per collection */
+    urlBuilder?: (collection: string, doc: Record<string, unknown>) => string | null;
+}
+export interface RobotsConfig {
+    /** User-agent rules */
+    rules?: RobotsRule[];
+    /** Additional sitemap URLs to include */
+    additionalSitemaps?: string[];
+    /** Crawl delay in seconds */
+    crawlDelay?: number;
+}
+export interface RobotsRule {
+    userAgent: string;
+    allow?: string[];
+    disallow?: string[];
+}

package/src/lib/seo-field-injector.d.ts

@@ -0,0 +1,27 @@
+/**
+ * SEO Field Injector
+ *
+ * Browser-safe — no server-side imports.
+ * Injects SEO fields as a named tab into targeted collections.
+ * Must be idempotent — called during both config generation and server init.
+ */
+import type { CollectionConfig } from '@momentumcms/core';
+export interface SeoFieldInjectorOptions {
+    collections: string[] | '*';
+    excludeCollections?: string[];
+}
+/**
+ * Inject SEO fields as a named tab into targeted collections.
+ *
+ * - If the collection already has a top-level `tabs()` field, the SEO tab
+ *   is appended to its tabs array.
+ * - Otherwise, all existing fields are wrapped in an unnamed "Content" tab
+ *   and the SEO tab is added alongside it.
+ *
+ * Data model is unchanged: a named tab `{ name: 'seo' }` stores data
+ * at `doc.seo.*` — identical to the previous `group('seo', ...)`.
+ *
+ * @param collections - Mutable collections array
+ * @param options - Which collections to target
+ */
+export declare function injectSeoFields(collections: CollectionConfig[], options: SeoFieldInjectorOptions): void;

package/src/lib/seo-fields.d.ts

@@ -0,0 +1,21 @@
+/**
+ * SEO Field Definitions
+ *
+ * Browser-safe — no server-side imports.
+ * Creates the SEO fields that get injected into collections,
+ * either as a group field or as a named tab config.
+ */
+import type { Field, GroupField, TabConfig } from '@momentumcms/core';
+/**
+ * Return the raw SEO fields shared by both group and tab config.
+ */
+export declare function getSeoFields(): Field[];
+/**
+ * Create the `seo` group field injected into collections.
+ */
+export declare function createSeoGroupField(): GroupField;
+/**
+ * Create a named tab config for SEO fields.
+ * Named tabs store data under `doc.seo.*` — same shape as `group('seo', ...)`.
+ */
+export declare function createSeoTabConfig(): TabConfig;

package/src/lib/seo-plugin.d.ts

@@ -0,0 +1,29 @@
+/**
+ * SEO Plugin
+ *
+ * A Momentum CMS plugin for SEO field injection, content analysis,
+ * sitemap generation, robots.txt, and meta tag API.
+ *
+ * @example
+ * ```typescript
+ * import { seoPlugin } from '@momentumcms/plugins/seo';
+ *
+ * export default defineMomentumConfig({
+ *   plugins: [
+ *     seoPlugin({
+ *       collections: ['posts', 'pages'],
+ *       siteUrl: 'https://example.com',
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+import type { MomentumPlugin } from '@momentumcms/plugins/core';
+import type { SeoPluginConfig } from './seo-config.types';
+/**
+ * Creates an SEO plugin.
+ *
+ * @param config - SEO plugin configuration
+ * @returns Plugin instance
+ */
+export declare function seoPlugin(config: SeoPluginConfig): MomentumPlugin;

package/src/lib/seo-utils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared SEO Utility Functions
+ *
+ * Common helpers used across multiple SEO plugin modules.
+ */
+import type { CollectionConfig } from '@momentumcms/core';
+import type { SeoFieldData } from './seo-config.types';
+/**
+ * Check if a collection already has SEO fields — either as a top-level
+ * `group('seo', ...)` or as a named `seo` tab inside a `tabs()` field.
+ */
+export declare function hasSeoField(collection: CollectionConfig): boolean;
+/**
+ * Extract SEO field data from a document's `seo` property.
+ * Returns an empty object if the seo field is missing or malformed.
+ */
+export declare function extractSeoFieldData(doc: Record<string, unknown>): SeoFieldData;
+/**
+ * Compute SEO grade from a numeric score.
+ */
+export declare function computeGrade(score: number): 'good' | 'warning' | 'poor';

package/src/lib/settings/seo-settings-collection.d.ts

@@ -0,0 +1,9 @@
+/**
+ * SEO Settings Collection (Singleton)
+ *
+ * Stores site-wide SEO configuration: robots.txt rules, crawl delay,
+ * additional sitemaps, and future global SEO settings.
+ * One document per site (upsert by querying for the singleton).
+ * Hidden from sidebar — managed via the Robots Settings admin page.
+ */
+export declare const SeoSettings: import("@momentumcms/core").CollectionConfig;

package/src/lib/settings/seo-settings-handler.d.ts

@@ -0,0 +1,21 @@
+/**
+ * SEO Settings Express Handler
+ *
+ * GET/PUT endpoint for the site-wide SEO settings singleton.
+ * Requires admin authentication. The seo-settings collection is
+ * `managed: true`, so this handler provides the only HTTP path.
+ */
+import type { Router } from 'express';
+import type { MomentumAPI } from '@momentumcms/plugins/core';
+import type { RobotsConfig } from '../seo-config.types';
+export interface SeoSettingsHandlerOptions {
+    getApi: () => MomentumAPI | null;
+    /** Static robots config from plugin init — used as defaults. */
+    defaultRobotsConfig?: RobotsConfig;
+    /** Called when settings are saved — invalidate caches. */
+    onSettingsChanged?: () => void;
+}
+/**
+ * Creates an Express router for SEO settings CRUD (singleton).
+ */
+export declare function createSeoSettingsRouter(options: SeoSettingsHandlerOptions): Router;

package/src/lib/sitemap/sitemap-cache.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Simple in-memory TTL cache for sitemap XML.
+ */
+export declare class SitemapCache {
+    private readonly store;
+    private readonly defaultTtl;
+    constructor(defaultTtl?: number);
+    get(key: string): string | null;
+    set(key: string, value: string, ttl?: number): void;
+    invalidate(key: string): void;
+    clear(): void;
+}

package/src/lib/sitemap/sitemap-generator.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Sitemap XML Generator
+ *
+ * Pure functions that build XML sitemap and sitemap index strings.
+ */
+import type { SitemapChangeFreq } from '../seo-config.types';
+export interface SitemapEntry {
+    loc: string;
+    lastmod?: string;
+    changefreq?: SitemapChangeFreq;
+    priority?: number;
+}
+/**
+ * Generate an XML sitemap from a list of URL entries.
+ */
+export declare function generateSitemap(entries: SitemapEntry[]): string;
+/**
+ * Generate a sitemap index pointing to multiple sitemap files.
+ */
+export declare function generateSitemapIndex(sitemapUrls: string[]): string;

package/src/lib/sitemap/sitemap-handler.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Sitemap Express Handler
+ *
+ * Serves XML sitemaps at /sitemap.xml with in-memory caching.
+ * Reads per-collection settings from the seo-sitemap-settings collection
+ * and per-document exclusions from the SEO field group.
+ */
+import type { Router } from 'express';
+import type { MomentumAPI } from '@momentumcms/plugins/core';
+import type { SitemapConfig } from '../seo-config.types';
+import { SitemapCache } from './sitemap-cache';
+export interface SitemapHandlerOptions {
+    getApi: () => MomentumAPI | null;
+    siteUrl: string;
+    config: SitemapConfig;
+    seoCollections: string[];
+}
+/**
+ * Creates an Express router for the sitemap endpoint.
+ */
+export declare function createSitemapRouter(options: SitemapHandlerOptions): {
+    router: Router;
+    clearCache: () => void;
+};
+/**
+ * Expose cache for shutdown cleanup.
+ */
+export { SitemapCache };

package/src/lib/sitemap/sitemap-settings-collection.d.ts

@@ -0,0 +1,7 @@
+/**
+ * SEO Sitemap Settings Collection
+ *
+ * Stores per-collection sitemap configuration (include/exclude, priority, change frequency).
+ * Hidden from sidebar — managed via the Sitemap Settings admin page.
+ */
+export declare const SeoSitemapSettings: import("@momentumcms/core").CollectionConfig;

package/src/lib/sitemap/sitemap-settings-handler.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Sitemap Settings Express Handler
+ *
+ * CRUD endpoint for per-collection sitemap configuration.
+ * Requires admin authentication. The seo-sitemap-settings collection
+ * is `managed: true`, so this handler provides the only HTTP path.
+ */
+import type { Router } from 'express';
+import type { MomentumAPI } from '@momentumcms/plugins/core';
+export interface SitemapSettingsHandlerOptions {
+    getApi: () => MomentumAPI | null;
+    seoCollections: string[];
+    onSettingsChanged?: () => void;
+}
+/**
+ * Creates an Express router for sitemap settings CRUD.
+ */
+export declare function createSitemapSettingsRouter(options: SitemapSettingsHandlerOptions): Router;