TypeScript Types

Core type definitions for Capyseo.

Configuration Types

CapyseoConfig

Main configuration object:

interface CapyseoConfig {
  // Rule settings
  rules?: Record<string, RuleConfig>;

  // AI configuration
  ai?: AIConfig;

  // Analysis options
  analysis?: AnalysisConfig;

  // CI/CD settings
  ci?: CIConfig;

  // Reporter settings
  reporters?: ReporterConfig;
}

RuleConfig

Configuration for individual rules:

interface RuleConfig {
  // Enable/disable rule
  enabled?: boolean;

  // Severity level
  severity?: 'error' | 'warning' | 'info';

  // Custom weight for scoring
  weight?: number;

  // Rule-specific options
  options?: Record<string, unknown>;
}

AIConfig

AI provider configuration:

interface AIConfig {
  // Enable AI features
  enabled?: boolean;

  // AI provider
  provider?: 'gemini' | 'openai' | 'anthropic' | 'ollama';

  // Model name
  model?: string;

  // API key (overrides env var)
  apiKey?: string;

  // Ollama base URL
  baseUrl?: string;

  // Cache directory
  cacheDir?: string;

  // Cache TTL in milliseconds
  cacheTTL?: number;
}

AnalysisConfig

Analysis behavior configuration:

interface AnalysisConfig {
  // File patterns to include
  include?: string[];

  // File patterns to exclude
  exclude?: string[];

  // Concurrent analysis limit
  concurrency?: number;

  // Analysis timeout (ms)
  timeout?: number;

  // Base URL for relative paths
  baseUrl?: string;
}

CIConfig

CI/CD configuration:

interface CIConfig {
  // Minimum passing score
  minScore?: number;

  // Fail on severity
  failOn?: 'error' | 'warning' | 'info' | 'none';

  // Exit codes
  exitCodes?: {
    success?: number;
    failure?: number;
    error?: number;
  };
}

Analysis Types

AnalysisResult

Result from analyzer.analyze():

interface AnalysisResult {
  // Overall score (0-100)
  score: number;

  // Per-page results
  pages: PageResult[];

  // Summary statistics
  summary: AnalysisSummary;

  // Analysis metadata
  metadata: AnalysisMetadata;
}

PageResult

Result for a single page:

interface PageResult {
  // Page URL or file path
  url: string;

  // Page score (0-100)
  score: number;

  // Issues found
  issues: SEOIssue[];

  // Page metadata
  metadata?: PageMetadata;

  // Score breakdown by category
  breakdown?: Record<string, number>;
}

SEOIssue

Individual issue found during analysis:

interface SEOIssue {
  // Rule ID that generated this issue
  ruleId: string;

  // Human-readable message
  message: string;

  // Severity level
  severity: 'error' | 'warning' | 'info';

  // How to fix (optional)
  suggestion?: string;

  // CSS selector for element (optional)
  selector?: string;

  // AI-generated suggestion (optional)
  aiSuggestion?: string;

  // Additional context (optional)
  context?: Record<string, unknown>;
}

AnalysisSummary

Summary statistics:

interface AnalysisSummary {
  // Total pages analyzed
  totalPages: number;

  // Average score across pages
  averageScore: number;

  // Issue counts by severity
  errors: number;
  warnings: number;
  info: number;

  // Total issues
  totalIssues: number;

  // Analysis duration (ms)
  duration?: number;
}

AnalysisMetadata

Analysis context information:

interface AnalysisMetadata {
  // Capyseo version
  version: string;

  // Analysis timestamp
  timestamp: string;

  // Configuration used
  config: CapyseoConfig;

  // AI provider used
  aiProvider?: string;

  // AI model used
  aiModel?: string;
}

Rule Types

SEORule

Rule definition interface:

interface SEORule {
  // Unique rule identifier
  id: string;

  // Human-readable name
  name: string;

  // Rule description
  description: string;

  // Category for grouping
  category: RuleCategory;

  // Default severity
  defaultSeverity: 'error' | 'warning' | 'info';

  // Check function
  check(context: AnalysisContext): SEOIssue[];
}

RuleCategory

Available rule categories:

type RuleCategory =
  | 'meta-tags'
  | 'images'
  | 'headings'
  | 'links'
  | 'content'
  | 'social'
  | 'structured-data'
  | 'mobile'
  | 'security'
  | 'performance'
  | 'url';

AnalysisContext

Context passed to rule check functions:

interface AnalysisContext {
  // Cheerio instance for DOM queries
  $: CheerioAPI;

  // Raw HTML content
  html: string;

  // Page URL or file path
  url: string;

  // Extracted page metadata
  metadata: PageMetadata;

  // Current configuration
  config: CapyseoConfig;
}

PageMetadata

Extracted page metadata:

interface PageMetadata {
  // Page title
  title?: string;

  // Meta description
  description?: string;

  // Canonical URL
  canonical?: string;

  // Language
  lang?: string;

  // Charset
  charset?: string;

  // Robots directive
  robots?: string;

  // Open Graph data
  openGraph?: OpenGraphData;

  // Twitter Card data
  twitterCard?: TwitterCardData;
}

Reporter Types

Reporter

Reporter interface:

interface Reporter {
  // Reporter name
  name: string;

  // Format results
  format(result: AnalysisResult): string;

  // Write to file (optional)
  write?(result: AnalysisResult, path: string): Promise<void>;
}

ReporterConfig

Reporter configuration:

interface ReporterConfig {
  // Console reporter options
  console?: {
    colors?: boolean;
    verbose?: boolean;
    quiet?: boolean;
  };

  // HTML reporter options
  html?: {
    title?: string;
    theme?: 'light' | 'dark';
    showAI?: boolean;
  };

  // JSON reporter options
  json?: {
    pretty?: boolean;
    includeMetadata?: boolean;
  };
}

AI Types

AIProvider

AI provider interface:

interface AIProvider {
  // Provider name
  name: string;

  // Generate content
  generate(prompt: string): Promise<string>;

  // Analyze image (optional)
  analyzeImage?(image: Buffer): Promise<string>;
}

AISuggestion

AI-generated suggestion:

interface AISuggestion {
  // Rule ID
  ruleId: string;

  // Original issue
  issue: SEOIssue;

  // AI suggestion text
  suggestion: string;

  // Confidence score (0-1)
  confidence?: number;
}

Event Types

AnalysisEvent

Events emitted during analysis:

type AnalysisEvent =
  | { type: 'start'; totalPages: number }
  | { type: 'page:start'; url: string }
  | { type: 'page:complete'; url: string; score: number }
  | { type: 'page:error'; url: string; error: Error }
  | { type: 'complete'; result: AnalysisResult };

ProgressCallback

Progress callback function:

type ProgressCallback = (event: AnalysisEvent) => void;

Utility Types

Severity

Severity level type:

type Severity = 'error' | 'warning' | 'info';

OutputFormat

Output format type:

type OutputFormat = 'console' | 'json' | 'sarif' | 'html' | 'csv';

DeepPartial

Utility for partial configuration:

type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
};

Usage Examples

Type-Safe Configuration

import type { CapyseoConfig } from '@capyseo/core';

const config: CapyseoConfig = {
  rules: {
    'meta-title': { severity: 'error' },
    'meta-description': { severity: 'error' },
    'image-alt': { severity: 'warning' },
  },
  ai: {
    enabled: true,
    provider: 'gemini',
  },
};

Custom Rule

import type { SEORule, AnalysisContext, SEOIssue } from '@capyseo/core';

const myRule: SEORule = {
  id: 'my-rule',
  name: 'My Rule',
  description: 'My custom rule',
  category: 'content',
  defaultSeverity: 'warning',

  check(context: AnalysisContext): SEOIssue[] {
    const { $ } = context;
    // Type-safe DOM access
    const title = $('title').text();
    return [];
  },
};

Handling Results

import type { AnalysisResult, SEOIssue } from '@capyseo/core';

function processResults(result: AnalysisResult): void {
  console.log(`Score: ${result.score}`);

  for (const page of result.pages) {
    const errors = page.issues.filter(
      (i: SEOIssue) => i.severity === 'error'
    );
    console.log(`${page.url}: ${errors.length} errors`);
  }
}

Type Exports

Import types from the main package:

import type {
  CapyseoConfig,
  RuleConfig,
  AIConfig,
  AnalysisResult,
  PageResult,
  SEOIssue,
  SEORule,
  AnalysisContext,
  Severity,
  RuleCategory,
} from '@capyseo/core';