Data Types and Configuration

/**
 * Core sitemap URL entry with all standard sitemap fields
 */
interface SitemapUrl {
  /** URL location (required) */
  loc: string;
  /** Last modification date */
  lastmod?: string | Date;
  /** How frequently the page is likely to change */
  changefreq?: Changefreq;
  /** Priority of this URL relative to other URLs on your site */
  priority?: 0 | 0.1 | 0.2 | 0.3 | 0.4 | 0.5 | 0.6 | 0.7 | 0.8 | 0.9 | 1;
  /** Alternative language versions of this URL */
  alternatives?: AlternativeEntry[];
  /** Google News metadata for news articles */
  news?: GoogleNewsEntry;
  /** Associated images for this URL */
  images?: ImageEntry[];
  /** Associated videos for this URL */
  videos?: VideoEntry[];
  /** Internal flag for i18n transformation */
  _i18nTransform?: boolean;
  /** Internal sitemap name reference */
  _sitemap?: string;
}

/**
 * Input type for sitemap URLs - accepts either full object or string URL
 */
type SitemapUrlInput = SitemapUrl | string;

/**
 * Strict version with all optional properties required
 */
type SitemapStrict = Required<SitemapUrl>;

/**
 * Valid change frequency values
 */
type Changefreq = 
  | 'always' 
  | 'hourly' 
  | 'daily' 
  | 'weekly' 
  | 'monthly' 
  | 'yearly' 
  | 'never';

/**
 * Internal resolved sitemap URL with computed properties
 */
interface ResolvedSitemapUrl extends Omit<SitemapUrl, 'url'>, Required<Pick<SitemapUrl, 'loc'>> {
  /** Internal unique key */
  _key: string;
  /** Parsed URL components */
  _path: ParsedURL;
  /** Relative location path */
  _relativeLoc: string;
  /** Whether URL is absolute */
  _abs: boolean;
}

/**
 * Base configuration for individual sitemaps
 */
interface SitemapDefinition {
  /** URL include patterns for filtering */
  include?: FilterInput[];
  /** URL exclude patterns for filtering */
  exclude?: FilterInput[];
  /** Whether to include global app sources */
  includeAppSources?: boolean;
  /** Sitemap filename */
  sitemapName: string;
  /** URL collection - can be static array or dynamic function */
  urls?: MaybeFunction<MaybePromise<SitemapUrlInput[]>>;
  /** Default properties applied to all URLs */
  defaults?: Omit<SitemapUrl, 'loc'>;
  /** Additional URL sources */
  sources?: SitemapSourceInput[];
  /** Enable chunking configuration */
  chunks?: boolean | number;
  /** Maximum URLs per chunk */
  chunkSize?: number;
  /** Internal route reference */
  _route?: string;
  /** Internal chunking flag */
  _isChunking?: boolean;
  /** Internal chunk size */
  _chunkSize?: number;
  /** Internal chunk count */
  _chunkCount?: number;
}

/**
 * Filter patterns for URL matching
 */
type FilterInput = string | RegExp | {
  regex: string;
};

/**
 * Value that can be a direct value or function returning the value
 */
type MaybeFunction<T> = T | (() => T);

/**
 * Value that can be synchronous or asynchronous
 */
type MaybePromise<T> = T | Promise<T>;

/**
 * Input types for URL sources
 */
type SitemapSourceInput = 
  | string 
  | [string, FetchOptions] 
  | SitemapSourceBase 
  | SitemapSourceResolved;

/**
 * Base URL source configuration
 */
interface SitemapSourceBase {
  /** Source metadata and documentation */
  context: {
    name: string;
    description?: string;
    tips?: string[];
  };
  /** Fetch configuration for remote sources */
  fetch?: string | [string, FetchOptions];
  /** Static URLs provided by this source */
  urls?: SitemapUrlInput[];
  /** Source classification */
  sourceType?: 'app' | 'user';
}

/**
 * Resolved URL source with runtime data
 */
interface SitemapSourceResolved extends Omit<SitemapSourceBase, 'urls'> {
  /** Resolved URLs (required after resolution) */
  urls: SitemapUrlInput[];
  /** Any errors encountered during resolution */
  error?: any;
  /** Time taken to resolve source in milliseconds */
  timeTakenMs?: number;
  /** Whether source resolution failed */
  _isFailure?: boolean;
}

/**
 * App source context types
 */
type AppSourceContext = 
  | 'nuxt:pages' 
  | 'nuxt:prerender' 
  | 'nuxt:route-rules' 
  | '@nuxtjs/i18n:pages' 
  | '@nuxt/content:document-driven';

/**
 * Configuration for multiple sitemaps
 */
interface MultiSitemapEntry {
  [key: string]: Partial<SitemapDefinition>;
}

/**
 * Index sitemap configuration
 */
interface IndexSitemapRemotes {
  index?: (string | SitemapIndexEntry)[];
}

/**
 * Combined multi-sitemap input type
 */
type MultiSitemapsInput = Partial<MultiSitemapEntry> & Partial<IndexSitemapRemotes>;

/**
 * Sitemap index entry
 */
interface SitemapIndexEntry {
  /** Sitemap URL */
  sitemap: string;
  /** Last modification date of the sitemap */
  lastmod?: string;
  /** Internal sitemap name reference */
  _sitemapName?: string;
}

/**
 * Image entry for sitemap image extensions
 */
interface ImageEntry {
  /** Image URL location */
  loc: string | URL;
  /** Image caption text */
  caption?: string;
  /** Geographic location of the image */
  geoLocation?: string;
  /** Image title */
  title?: string;
  /** License URL for the image */
  license?: string | URL;
}

/**
 * Video entry for sitemap video extensions
 */
interface VideoEntry {
  /** Video title (required) */
  title: string;
  /** Video thumbnail URL (required) */
  thumbnail_loc: string | URL;
  /** Video description (required) */
  description: string;
  /** Direct video content URL */
  content_loc?: string | URL;
  /** Video player page URL */
  player_loc?: string | URL;
  /** Video duration in seconds */
  duration?: number;
  /** Video expiration date */
  expiration_date?: Date | string;
  /** Video rating (0.0 to 5.0) */
  rating?: number;
  /** View count */
  view_count?: number;
  /** Publication date */
  publication_date?: Date | string;
  /** Family-friendly content flag */
  family_friendly?: 'yes' | 'no' | boolean;
  /** Geographic restrictions */
  restriction?: Restriction;
  /** Platform restrictions */
  platform?: Platform;
  /** Pricing information */
  price?: PriceEntry[];
  /** Subscription requirement */
  requires_subscription?: 'yes' | 'no' | boolean;
  /** Uploader information */
  uploader?: {
    uploader: string;
    info?: string | URL;
  };
  /** Live content indicator */
  live?: 'yes' | 'no' | boolean;
  /** Content tags */
  tag?: string | string[];
}

/**
 * Geographic restriction configuration
 */
interface Restriction {
  relationship: 'allow' | 'deny';
  restriction: string;
}

/**
 * Platform restriction configuration
 */
interface Platform {
  relationship: 'allow' | 'deny';
  platform: string;
}

/**
 * Video pricing information
 */
interface PriceEntry {
  price?: number | string;
  currency?: string;
  type?: 'rent' | 'purchase' | 'package' | 'subscription';
}

/**
 * Alternative URL entry for i18n support
 */
interface AlternativeEntry {
  /** Language/locale code (hreflang attribute) */
  hreflang: string;
  /** Alternative URL */
  href: string | URL;
}

/**
 * Google News metadata for news articles
 */
interface GoogleNewsEntry {
  /** News article title */
  title: string;
  /** Article publication date in W3C format */
  publication_date: Date | string;
  /** Publication information */
  publication: {
    /** Publication name as it appears on news.google.com */
    name: string;
    /** Publication language (ISO 639 code) */
    language: string;
  };
}

/**
 * Runtime configuration available in server context
 */
interface ModuleRuntimeConfig extends Pick<
  ModuleOptions, 
  | 'sitemapsPathPrefix' 
  | 'cacheMaxAgeSeconds' 
  | 'sitemapName' 
  | 'excludeAppSources' 
  | 'sortEntries' 
  | 'defaultSitemapsChunkSize' 
  | 'xslColumns' 
  | 'xslTips' 
  | 'debug' 
  | 'discoverImages' 
  | 'discoverVideos' 
  | 'autoLastmod' 
  | 'xsl' 
  | 'credits' 
  | 'minify'
> {
  /** Module version */
  version: string;
  /** Whether Nuxt Content document-driven mode is enabled */
  isNuxtContentDocumentDriven: boolean;
  /** Sitemap definitions and index configuration */
  sitemaps: { 
    index?: Pick<SitemapDefinition, 'sitemapName' | '_route'> & { 
      sitemaps: SitemapIndexEntry[] 
    } 
  } & Record<string, Omit<SitemapDefinition, 'urls'> & { _hasSourceChunk?: boolean }>;
  /** Auto i18n configuration */
  autoI18n?: AutoI18nConfig;
  /** Whether multiple sitemaps are enabled */
  isMultiSitemap: boolean;
  /** Whether i18n URL mapping is enabled */
  isI18nMapped: boolean;
}

/**
 * Base hook context with H3 event
 */
interface NitroBaseHook {
  event: H3Event;
}

/**
 * Context for sitemap index render hooks
 */
interface SitemapIndexRenderCtx extends NitroBaseHook {
  sitemaps: SitemapIndexEntry[];
}

/**
 * Context for individual sitemap render hooks
 */
interface SitemapRenderCtx extends NitroBaseHook {
  sitemapName: string;
  urls: ResolvedSitemapUrl[];
}

/**
 * Context for sitemap input processing hooks
 */
interface SitemapInputCtx extends NitroBaseHook {
  sitemapName: string;
  urls: SitemapUrlInput[];
}

/**
 * Context for sitemap output hooks
 */
interface SitemapOutputHookCtx extends NitroBaseHook {
  sitemapName: string;
  sitemap: string;
}

/**
 * Context for sitemap sources hooks
 */
interface SitemapSourcesHookCtx extends NitroBaseHook {
  sitemapName: string;
  sources: (SitemapSourceBase | SitemapSourceResolved)[];
}

/**
 * Auto i18n configuration for multi-language sitemaps
 */
interface AutoI18nConfig {
  /** Whether different domains are used for locales */
  differentDomains?: boolean;
  /** Locale configurations with sitemap metadata */
  locales: (LocaleObject & { 
    _sitemap: string; 
    _hreflang: string; 
  })[];
  /** Default locale code */
  defaultLocale: string;
  /** URL generation strategy */
  strategy: 'prefix' | 'prefix_except_default' | 'prefix_and_default' | 'no_prefix';
  /** Page-specific translations */
  pages?: Record<string, Record<string, string | false>>;
}

/**
 * Locale object configuration
 */
interface LocaleObject extends Record<string, any> {
  /** Locale code */
  code: string;
  /** Locale display name */
  name?: string;
  /** Text direction */
  dir?: 'ltr' | 'rtl' | 'auto';
  /** Primary domain for this locale */
  domain?: string;
  /** Multiple domains for this locale */
  domains?: string[];
  /** Default locale for specified domains */
  defaultForDomains?: string[];
  /** Language file configuration */
  file?: string | {
    path: string;
    cache?: boolean;
  };
  /** Multiple language files */
  files?: string[] | {
    path: string;
    cache?: boolean;
  }[];
  /** Whether this is a catch-all locale */
  isCatchallLocale?: boolean;
  /** @deprecated - use language instead */
  iso?: string;
  /** Language code */
  language?: string;
}

/**
 * Combined i18n integration options
 */
type I18nIntegrationOptions = NuxtI18nOptions & NuxtI18nMicro;

/**
 * Nuxt i18n micro integration
 */
interface NuxtI18nMicro {
  includeDefaultLocaleRoute?: boolean;
}

/**
 * Nitro URL resolvers for server context
 */
interface NitroUrlResolvers {
  event: H3Event;
  canonicalUrlResolver: (path: string) => string;
  relativeBaseUrlResolver: (path: string) => string;
  fixSlashes: (path: string) => string;
}

/**
 * XSL column configuration for sitemap styling
 */
interface XslColumn {
  label: string;
  width: `${string}%`;
  select?: string;
}

// Type-safe sitemap URL creation
const sitemapUrl: SitemapUrl = {
  loc: '/blog/post-1',
  lastmod: new Date(),
  changefreq: 'weekly',
  priority: 0.8,
  images: [{
    loc: '/images/blog/post-1-hero.jpg',
    caption: 'Blog post hero image',
    title: 'How to Use TypeScript'
  }],
  alternatives: [{
    hreflang: 'es',
    href: '/es/blog/post-1'
  }]
};

// Multi-sitemap configuration
const multiSitemapConfig: MultiSitemapsInput = {
  posts: {
    includeAppSources: true,
    include: ['/blog/**', '/news/**'],
    defaults: {
      changefreq: 'weekly',
      priority: 0.7
    }
  },
  pages: {
    includeAppSources: true,
    exclude: ['/blog/**', '/news/**'],
    defaults: {
      changefreq: 'monthly',
      priority: 0.5
    }
  }
};

// Source configuration with type safety
const dynamicSource: SitemapSourceBase = {
  context: {
    name: 'Product Pages',
    description: 'Dynamic product URLs from database',
    tips: ['Updates every hour', 'Includes product images']
  },
  fetch: ['/api/products-sitemap', { 
    headers: { 'Accept': 'application/json' } 
  }],
  sourceType: 'user'
};

// i18n configuration
const i18nConfig: AutoI18nConfig = {
  differentDomains: false,
  locales: [
    { 
      code: 'en', 
      _sitemap: 'en', 
      _hreflang: 'en',
      name: 'English'
    },
    { 
      code: 'es', 
      _sitemap: 'es', 
      _hreflang: 'es',
      name: 'Español'
    }
  ],
  defaultLocale: 'en',
  strategy: 'prefix_except_default'
};