API Reference
Complete API documentation for m-seo.
Table of Contents
- Core API - createSEO(), SeoEngine
- CMS Integration API - CMSPlugins (NEW v1.1.1)
- AI Content Analysis API - AIContentAnalysis (NEW v1.1.1)
- Framework Adapters - React, Vue, Next.js, Express
- Utilities - UrlManager, Sitemap, Robots
CMS Integration API (NEW v1.1.1)
CMSPlugins
Multi-platform CMS integration for WordPress, Ghost, Drupal, Joomla, Contentful, and Strapi.
Constructor
import { CMSPlugins, CMSConfig } from "m-seo";
interface CMSConfig {
platform:
| "wordpress"
| "ghost"
| "drupal"
| "joomla"
| "contentful"
| "strapi"
| "custom";
baseUrl: string;
credentials?: {
username?: string;
password?: string;
apiKey?: string;
token?: string;
};
options?: {
cacheEnabled?: boolean;
cacheTTL?: number; // milliseconds
rateLimitPerMinute?: number;
timeout?: number;
};
}
const cms = new CMSPlugins(config);Methods
fetchContent()
async fetchContent(options: { id: string; type?: string }): Promise<CMSContent>
interface CMSContent {
id: string;
title: string;
content: string;
excerpt?: string;
author?: string;
publishedDate?: string;
modifiedDate?: string;
featuredImage?: string;
categories?: string[];
tags?: string[];
metadata?: Record<string, any>;
}generateSeoData()
async generateSeoData(config: CMSConfig, content: CMSContent): Promise<SeoData>
interface SeoData {
title: string;
description: string;
keywords: string[];
canonical?: string;
ogImage?: string;
structuredData?: object;
}batchProcess()
async batchProcess(options: BatchOptions): Promise<BatchResult[]>
interface BatchOptions {
operations: BatchOperation[];
config: CMSConfig;
maxConcurrency?: number;
}
interface BatchOperation {
type: "fetch" | "generate-seo" | "sync";
id?: string;
content?: CMSContent;
seo?: SeoData;
}exportContent()
async exportContent(
contents: CMSContent[],
options: { format: "json" | "csv" | "xml" | "markdown" }
): Promise<string>importContent()
async importContent(
data: string,
format: "json" | "csv" | "xml" | "markdown",
config: CMSConfig
): Promise<CMSContent[]>AI Content Analysis API (NEW v1.1.1)
AIContentAnalysis
AI-powered content analysis for SEO optimization.
analyzeContent()
static async analyzeContent(
content: string,
config: AIContentConfig
): Promise<AdvancedContentAnalysisResult>
interface AIContentConfig {
provider: "openai" | "claude" | "huggingface";
apiKey: string;
model?: string;
enableReadability?: boolean;
enableSentiment?: boolean;
enableToneAnalysis?: boolean;
enableKeywordAnalysis?: boolean;
enablePlagiarismCheck?: boolean;
targetKeywords?: string[];
language?: string;
}
interface AdvancedContentAnalysisResult {
scores: ContentQualityMetrics;
readability: ReadabilityScores;
sentiment: SentimentAnalysis;
tone: ToneAnalysis;
keywords: KeywordAnalysis[];
recommendations: SEORecommendation[];
plagiarism?: PlagiarismResult;
metadata: {
analyzedAt: string;
wordCount: number;
characterCount: number;
sentenceCount: number;
paragraphCount: number;
};
}Readability Scores
interface ReadabilityScores {
fleschReadingEase: number; // 0-100, higher is easier
gunningFog: number; // Grade level
smog: number; // Grade level
colemanLiau: number; // Grade level
automatedReadability: number; // Grade level
daleChall: number; // Grade level
grade: string; // "Easy", "Medium", "Hard"
readingTime: number; // minutes
}Sentiment & Tone
interface SentimentAnalysis {
type: "positive" | "negative" | "neutral" | "mixed";
score: number; // -1 to 1
confidence: number; // 0 to 1
emotions?: {
joy?: number;
sadness?: number;
anger?: number;
fear?: number;
surprise?: number;
};
}
interface ToneAnalysis {
primary: string; // "professional", "casual", "formal", etc.
secondary?: string[];
confidence: number;
attributes: {
formality: number; // 0-1
complexity: number;
enthusiasm: number;
};
}Keyword Analysis
interface KeywordAnalysis {
word: string;
frequency: number;
density: number; // percentage
prominence: number; // 0-1
relevance: number; // 0-100
context: string[];
}Batch Analysis
static async batchAnalyze(options: {
requests: BatchAnalysisRequest[];
globalConfig?: Partial<AIContentConfig>;
maxConcurrency?: number;
}): Promise<BatchAnalysisResult[]>
interface BatchAnalysisRequest {
content: string;
config?: Partial<AIContentConfig>;
}Export Analysis
static async exportAnalysis(
result: AdvancedContentAnalysisResult,
options: ExportOptions
): Promise<string>
interface ExportOptions {
format: "json" | "markdown" | "html" | "pdf";
includeCharts?: boolean;
includeSuggestions?: boolean;
includeHistory?: boolean;
}Image Optimization API (NEW v1.1.1)
ImageOptimizer
Optimize images for SEO and performance with AI-powered features.
analyzeImage()
static async analyzeImage(src: string, alt?: string): Promise<ImageAnalysisResult>
interface ImageAnalysisResult {
src: string;
originalFormat: string;
originalSize: { width: number; height: number; fileSize: number };
aspectRatio: string;
hasAlt: boolean;
altText: string;
altQuality: number; // 0-100
altScore: number; // 0-100
isOptimized: boolean;
canBeOptimized: boolean;
potentialSavings: number; // bytes
format: string;
recommendations: string[];
}optimizeImage()
static async optimizeImage(config: ImageOptimizationConfig): Promise<OptimizedImage>
interface ImageOptimizationConfig {
src: string;
alt?: string;
title?: string;
format?: 'webp' | 'avif' | 'jpeg' | 'png' | 'auto';
quality?: number; // 1-100
maxWidth?: number;
maxHeight?: number;
responsive?: boolean;
breakpoints?: number[]; // [320, 640, 768, 1024, 1280, 1536]
sizes?: string; // "(max-width: 768px) 100vw, 50vw"
loading?: 'lazy' | 'eager' | 'auto';
fetchPriority?: 'high' | 'low' | 'auto';
decoding?: 'async' | 'sync' | 'auto';
generateAlt?: boolean; // AI-generated alt text
altLanguage?: string;
keywords?: string[];
}
interface OptimizedImage {
src: string;
srcset?: string;
sizes?: string;
alt: string;
loading: string;
html: string; // Complete <picture> or <img> tag
}Video SEO API (NEW v1.1.1)
VideoSeo
Optimize video content for search engines.
optimizeVideo()
static optimizeVideo(config: VideoSeoConfig, pageUrl: string): VideoOptimizationResult
interface VideoSeoConfig {
name: string;
description: string;
thumbnailUrl: string;
uploadDate: string; // ISO 8601 date
duration: string; // ISO 8601 duration (PT1H30M)
contentUrl?: string;
embedUrl?: string;
transcript?: string;
captions?: Array<{ language: string; url: string }>;
category?: string;
tags?: string[];
rating?: number; // 1-5
viewCount?: number;
familyFriendly?: boolean;
requiresSubscription?: boolean;
videoQuality?: 'hd' | 'sd';
width?: number;
height?: number;
publisher?: { name: string; logo: string };
}
interface VideoOptimizationResult {
schema: VideoSchemaMarkup; // JSON-LD object
schemaJson: string; // JSON-LD as string
sitemapEntry: string; // XML sitemap entry
embedCode: string; // Optimized iframe code
recommendations: string[];
seoScore: number; // 0-100
}generateVideoSitemap()
static generateVideoSitemap(videos: VideoSeoConfig[]): string
// Returns complete XML video sitemapSocial Preview API (NEW v1.1.1)
SocialPreviewGenerator
Generate and validate social media preview cards.
generatePreview()
static generatePreview(
platform: 'facebook' | 'twitter' | 'linkedin' | 'pinterest',
config: SocialPreviewConfig
): SocialPreviewResult
interface SocialPreviewConfig {
og?: OpenGraphData;
twitter?: TwitterCardData;
}
interface OpenGraphData {
title: string;
description: string;
image: string;
url: string;
type?: 'website' | 'article' | 'video' | 'music' | 'book' | 'profile';
siteName?: string;
locale?: string;
imageWidth?: number;
imageHeight?: number;
}
interface TwitterCardData {
card: 'summary' | 'summary_large_image' | 'app' | 'player';
site?: string; // @username
creator?: string; // @username
title?: string;
description?: string;
image?: string;
}
interface SocialPreviewResult {
platform: string;
title: string;
description: string;
image: string;
url: string;
preview: string; // HTML preview render
validation: PreviewValidation;
meta: {
titleLength: number;
descriptionLength: number;
imageAspectRatio?: string;
imageDimensions?: { width: number; height: number };
};
}
interface PreviewValidation {
isValid: boolean;
errors: string[];
warnings: string[];
suggestions: string[];
requiredTags: string[];
optionalTags: string[];
score: number; // 0-100
}validatePreview()
static validatePreview(
platform: string,
data: { og?: Partial<OpenGraphData>; twitter?: Partial<TwitterCardData> }
): PreviewValidationgenerateMetaTags()
static generateMetaTags(config: SocialPreviewConfig): string
// Returns complete Open Graph and Twitter Card meta tags as HTML stringCore API
createSEO()
Simple API - Quick way to generate SEO tags.
function createSEO(options: SimpleSeoOptions): SeoResult;
interface SimpleSeoOptions {
title: string;
description: string;
image?: string;
url?: string;
keywords?: string[];
siteName?: string;
locale?: string;
type?: "website" | "article" | "product";
}
interface SeoResult {
html: string; // HTML meta tags as string
jsonLd: object; // JSON-LD structured data
metaTags: MetaTag[]; // Array of meta tag objects
linkTags: LinkTag[]; // Array of link tag objects
title: string; // Page title
description: string; // Meta description
openGraph: object; // Open Graph data
}Example:
import { createSEO } from "m-seo";
const seo = createSEO({
title: "My Page",
description: "Page description",
image: "https://example.com/og.jpg",
url: "https://example.com/page",
keywords: ["seo", "web"],
siteName: "My Site",
locale: "en_US",
type: "article",
});
console.log(seo.html); // HTML string
console.log(seo.jsonLd); // JSON-LD object
console.log(seo.metaTags); // Meta tag arraySeoEngine
Advanced API - Full control over SEO configuration.
Constructor
class SeoEngine {
constructor(config: SeoConfig);
}
interface SeoConfig {
title: string;
description: string;
keywords?: string[];
canonical?: string;
ogImage?: string;
ogType?: string;
ogUrl?: string;
twitterCard?: "summary" | "summary_large_image" | "app" | "player";
twitterSite?: string;
twitterCreator?: string;
author?: string;
siteName?: string;
locale?: string;
alternateLocales?: string[];
themeColor?: string;
robots?: string;
viewport?: string;
appleMobileWebAppCapable?: boolean;
appleMobileWebAppTitle?: string;
}Example:
import { SeoEngine } from "m-seo";
const seo = new SeoEngine({
title: "Blog Post Title",
description: "An amazing blog post",
keywords: ["blog", "tech", "web"],
canonical: "https://example.com/blog/post",
ogImage: "https://example.com/images/og.jpg",
ogType: "article",
twitterCard: "summary_large_image",
author: "John Doe",
siteName: "My Blog",
locale: "en_US",
themeColor: "#3490dc",
robots: "index, follow",
});Methods
generateMetaTags()
Generate array of meta tag objects.
generateMetaTags(): MetaTag[]
interface MetaTag {
name?: string;
property?: string;
content: string;
httpEquiv?: string;
}Example:
const metaTags = seo.generateMetaTags();
// [
// { name: 'description', content: 'An amazing blog post' },
// { property: 'og:title', content: 'Blog Post Title' },
// { name: 'twitter:card', content: 'summary_large_image' },
// ...
// ]generateLinkTags()
Generate array of link tag objects.
generateLinkTags(): LinkTag[]
interface LinkTag {
rel: string;
href: string;
hreflang?: string;
}Example:
const linkTags = seo.generateLinkTags();
// [
// { rel: 'canonical', href: 'https://example.com/blog/post' }
// ]toHtmlString()
Generate complete HTML string with all tags.
toHtmlString(): stringExample:
const html = seo.toHtmlString();
// <title>Blog Post Title</title>
// <meta name="description" content="An amazing blog post">
// <meta property="og:title" content="Blog Post Title">
// ...updateConfig()
Update SEO configuration.
updateConfig(newConfig: Partial<SeoConfig>): voidExample:
seo.updateConfig({
title: "Updated Title",
description: "Updated description",
});getConfig()
Get current configuration.
getConfig(): SeoConfigExample:
const config = seo.getConfig();
console.log(config.title); // 'Blog Post Title'Static: setDefaults()
Set global default configuration.
static setDefaults(defaults: Partial<SeoConfig>): voidExample:
SeoEngine.setDefaults({
siteName: "My Website",
locale: "en_US",
author: "John Doe",
themeColor: "#3490dc",
});
// All new instances inherit these defaults
const seo = new SeoEngine({
title: "Page",
description: "Description",
// siteName, locale, author, themeColor are inherited
});SitemapGenerator
Generate XML sitemaps.
Constructor
class SitemapGenerator {
constructor(options?: SitemapOptions);
}
interface SitemapOptions {
hostname: string;
defaultChangefreq?:
| "always"
| "hourly"
| "daily"
| "weekly"
| "monthly"
| "yearly"
| "never";
defaultPriority?: number; // 0.0 to 1.0
}Methods
addUrl()
Add a URL to the sitemap.
addUrl(url: SitemapUrl): void
interface SitemapUrl {
loc: string; // URL path
lastmod?: Date | string; // Last modified date
changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
priority?: number; // 0.0 to 1.0
alternates?: AlternateUrl[]; // Alternate language URLs
}
interface AlternateUrl {
hreflang: string;
href: string;
}Example:
import { SitemapGenerator } from "m-seo";
const sitemap = new SitemapGenerator({
hostname: "https://example.com",
defaultChangefreq: "weekly",
defaultPriority: 0.5,
});
sitemap.addUrl({
loc: "/",
lastmod: new Date(),
changefreq: "daily",
priority: 1.0,
});
sitemap.addUrl({
loc: "/blog/post-1",
lastmod: "2025-01-15",
changefreq: "monthly",
priority: 0.8,
alternates: [
{ hreflang: "en", href: "https://example.com/en/blog/post-1" },
{ hreflang: "es", href: "https://example.com/es/blog/post-1" },
],
});toXml()
Generate sitemap as XML string.
toXml(): stringExample:
const xml = sitemap.toXml();
console.log(xml);
// <?xml version="1.0" encoding="UTF-8"?>
// <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
// <url>
// <loc>https://example.com/</loc>
// <lastmod>2025-01-15</lastmod>
// <changefreq>daily</changefreq>
// <priority>1.0</priority>
// </url>
// ...
// </urlset>toJson()
Get sitemap URLs as JSON array.
toJson(): SitemapUrl[]clear()
Remove all URLs from sitemap.
clear(): voidRobotsManager
Manage robots.txt content.
Constructor
class RobotsManager {
constructor();
}Methods
addRule()
Add a robot rule.
addRule(rule: RobotRule): void
interface RobotRule {
userAgent: string;
allow?: string[];
disallow?: string[];
crawlDelay?: number;
}Example:
import { RobotsManager } from "m-seo";
const robots = new RobotsManager();
robots.addRule({
userAgent: "Googlebot",
allow: ["/public"],
disallow: ["/admin", "/private"],
crawlDelay: 10,
});
robots.addRule({
userAgent: "*",
allow: ["/"],
disallow: ["/admin"],
});allowAll()
Allow all bots to crawl everything.
allowAll(): RobotsManagerExample:
robots.allowAll();
// User-agent: *
// Allow: /disallowAll()
Block all bots from crawling.
disallowAll(): RobotsManagerExample:
robots.disallowAll();
// User-agent: *
// Disallow: /setSitemap()
Add sitemap URL.
setSitemap(url: string): RobotsManagerExample:
robots.setSitemap("https://example.com/sitemap.xml");setHost()
Set preferred host.
setHost(host: string): RobotsManagerExample:
robots.setHost("https://example.com");toString()
Generate robots.txt content.
toString(): stringExample:
const content = robots.toString();
console.log(content);
// User-agent: Googlebot
// Allow: /public
// Disallow: /admin
// Disallow: /private
// Crawl-delay: 10
//
// User-agent: *
// Allow: /
// Disallow: /admin
//
// Sitemap: https://example.com/sitemap.xml
// Host: https://example.comStructuredDataManager
Manage Schema.org JSON-LD structured data.
Constructor
class StructuredDataManager {
constructor();
}Methods
addSchema()
Add custom schema.
addSchema(schema: object): voidExample:
import { StructuredDataManager } from "m-seo";
const sd = new StructuredDataManager();
sd.addSchema({
"@context": "https://schema.org",
"@type": "Organization",
name: "My Company",
url: "https://example.com",
logo: "https://example.com/logo.png",
});addWebsite()
Add WebSite schema.
addWebsite(data: WebsiteSchema): void
interface WebsiteSchema {
name: string;
url: string;
description?: string;
inLanguage?: string;
potentialAction?: object;
}addOrganization()
Add Organization schema.
addOrganization(data: OrganizationSchema): void
interface OrganizationSchema {
name: string;
url: string;
logo?: string;
description?: string;
contactPoint?: object;
sameAs?: string[];
}addArticle()
Add BlogPosting/Article schema.
addArticle(data: ArticleSchema): void
interface ArticleSchema {
headline: string;
datePublished: string;
dateModified?: string;
author: { name: string } | { '@type': 'Person', name: string };
image?: string;
publisher?: object;
}addBreadcrumb()
Add BreadcrumbList schema.
addBreadcrumb(items: BreadcrumbItem[]): void
interface BreadcrumbItem {
name: string;
url: string;
}Example:
sd.addBreadcrumb([
{ name: "Home", url: "https://example.com" },
{ name: "Blog", url: "https://example.com/blog" },
{ name: "Post", url: "https://example.com/blog/post" },
]);toHtmlScript()
Generate <script> tag with JSON-LD.
toHtmlScript(): stringExample:
const script = sd.toHtmlScript();
// <script type="application/ld+json">
// {"@context":"https://schema.org","@type":"Organization",...}
// </script>toJson()
Get all schemas as array.
toJson(): object[]clear()
Remove all schemas.
clear(): voidReact Adapter API
useSeo()
React hook for setting SEO tags.
function useSeo(options: SeoConfig): void;Example:
import { useSeo } from "m-seo/adapters/ReactSPAAdapter";
function HomePage() {
useSeo({
title: "Home - My App",
description: "Welcome to my app",
canonical: "https://example.com",
ogImage: "https://example.com/og.jpg",
});
return <h1>Home</h1>;
}useStructuredData()
React hook for adding JSON-LD structured data.
function useStructuredData(schema: object): void;Example:
import { useStructuredData } from "m-seo/adapters/ReactSPAAdapter";
function BlogPost({ post }) {
useStructuredData({
"@context": "https://schema.org",
"@type": "BlogPosting",
headline: post.title,
datePublished: post.date,
author: { "@type": "Person", name: post.author },
});
return <article>...</article>;
}useBreadcrumbs()
React hook for breadcrumb navigation.
function useBreadcrumbs(items: BreadcrumbItem[]): void;Example:
import { useBreadcrumbs } from "m-seo/adapters/ReactSPAAdapter";
function ProductPage() {
useBreadcrumbs([
{ name: "Home", url: "/" },
{ name: "Products", url: "/products" },
{ name: "Product Name", url: "/products/123" },
]);
return <div>Product Details</div>;
}SeoHead Component
React component for SEO tags.
function SeoHead(props: SeoConfig): JSX.Element;Example:
import { SeoHead } from "m-seo/adapters/ReactSPAAdapter";
function Page() {
return (
<div>
<SeoHead
title="Page Title"
description="Page description"
ogImage="https://example.com/og.jpg"
/>
<h1>Content</h1>
</div>
);
}JsonLd Component
React component for JSON-LD structured data.
function JsonLd(props: { data: object }): JSX.Element;Example:
import { JsonLd } from "m-seo/adapters/ReactSPAAdapter";
function Product({ product }) {
return (
<div>
<JsonLd
data={{
"@type": "Product",
name: product.name,
offers: {
"@type": "Offer",
price: product.price,
priceCurrency: "USD",
},
}}
/>
<h1>{product.name}</h1>
</div>
);
}Express Adapter API
ExpressAdapter()
Express middleware for SEO.
function ExpressAdapter(options: ExpressAdapterOptions): Middleware;
interface ExpressAdapterOptions {
defaults?: Partial<SeoConfig>;
sitemapRoute?: string;
robotsRoute?: string;
}Example:
const express = require("express");
const { ExpressAdapter } = require("m-seo/adapters/ExpressAdapter");
const app = express();
app.use(
ExpressAdapter({
defaults: {
siteName: "My Site",
locale: "en_US",
themeColor: "#3490dc",
},
sitemapRoute: "/sitemap.xml",
robotsRoute: "/robots.txt",
})
);TypeScript Types
All types are exported from the main package:
import type {
SeoConfig,
MetaTag,
LinkTag,
SitemapUrl,
RobotRule,
BreadcrumbItem,
SimpleSeoOptions,
SeoResult,
} from "m-seo";Next Steps
- See Examples - Real-world usage patterns
- Read FAQ - Common questions
- View Project Structure - Code organization