@gravito/constellation 2.0.0 → 3.0.1

package/dist/index.d.cts

@@ -1,144 +1,507 @@
 import { Job } from '@gravito/stream';
-import { PlanetCore } from '@gravito/core';
+import { GravitoOrbit, PlanetCore } from '@gravito/core';
 
+/**
+ * Supported change frequency values for sitemap entries.
+ *
+ * @public
+ * @since 3.0.0
+ */
 type ChangeFreq = 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+/**
+ * Represents an alternate language or regional version of a URL.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface AlternateUrl {
+    /** The language code (e.g., 'en', 'zh-TW') or 'x-default'. */
     lang: string;
+    /** The full URL of the alternate version. */
     url: string;
 }
+/**
+ * Image metadata for a sitemap entry.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface SitemapImage {
+    /** The full URL of the image. */
     loc: string;
+    /** The title of the image. */
     title?: string | undefined;
+    /** A caption for the image. */
     caption?: string | undefined;
+    /** The geographic location of the image. */
     geo_location?: string | undefined;
+    /** A URL to the license for the image. */
     license?: string | undefined;
 }
+/**
+ * Video metadata for a sitemap entry.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface SitemapVideo {
+    /** The URL of the video thumbnail. */
     thumbnail_loc: string;
+    /** The title of the video. */
     title: string;
+    /** A description of the video. */
     description: string;
+    /** The URL of the actual video file. */
     content_loc?: string | undefined;
+    /** The URL of the video player. */
     player_loc?: string | undefined;
+    /** Duration of the video in seconds. */
     duration?: number | undefined;
+    /** When the video will no longer be available. */
     expiration_date?: Date | string | undefined;
+    /** Rating of the video (0.0 to 5.0). */
     rating?: number | undefined;
+    /** Number of times the video has been viewed. */
     view_count?: number | undefined;
+    /** When the video was first published. */
     publication_date?: Date | string | undefined;
+    /** Whether the video is suitable for children. */
     family_friendly?: 'yes' | 'no' | undefined;
+    /** Tags associated with the video. */
     tag?: string[] | undefined;
+    /** The category of the video. */
     category?: string | undefined;
+    /** Regional restrictions for the video. */
     restriction?: {
         relationship: 'allow' | 'deny';
         countries: string[];
     } | undefined;
 }
+/**
+ * News metadata for a sitemap entry.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface SitemapNews {
+    /** The publication that the news article belongs to. */
     publication: {
+        /** Name of the news publication. */
         name: string;
+        /** Language of the news publication (ISO 639 code). */
         language: string;
     };
+    /** The publication date of the news article. */
     publication_date: Date | string;
+    /** The title of the news article. */
     title: string;
+    /** Genres of the news article (e.g., 'PressRelease', 'Blog'). */
     genres?: string | undefined;
+    /** Keywords for the news article. */
     keywords?: string[] | undefined;
+    /** Stock tickers for the news article. */
     stock_tickers?: string[] | undefined;
 }
+/**
+ * Represents a single URL entry in an XML sitemap.
+ *
+ * Supports standard sitemap properties as well as Google-specific extensions
+ * for images, videos, and news.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface SitemapEntry {
+    /** The full URL of the page including protocol and domain. */
     url: string;
+    /** The date of last modification of the page. */
     lastmod?: Date | string | undefined;
+    /** How frequently the page is likely to change. */
     changefreq?: ChangeFreq | undefined;
+    /** The priority of this URL relative to other URLs on your site (0.0 to 1.0). @default 0.5 */
     priority?: number | undefined;
+    /** Alternate language or regional versions of this URL (i18n). */
     alternates?: AlternateUrl[] | undefined;
+    /** Image information associated with this URL. */
     images?: SitemapImage[] | undefined;
+    /** Video information associated with this URL. */
     videos?: SitemapVideo[] | undefined;
+    /** News-specific information for this URL. */
     news?: SitemapNews | undefined;
+    /** Optional redirect metadata for SEO and tracking purposes. */
     redirect?: {
+        /** The source URL path that redirects to this entry. */
         from: string;
+        /** The destination URL path. */
         to: string;
+        /** The HTTP redirect status code. */
         type: 301 | 302;
+        /** The preferred canonical URL for this page. */
         canonical?: string;
     };
 }
+/**
+ * Represents an entry in a sitemap index file.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface SitemapIndexEntry {
+    /** URL of the sub-sitemap file. */
     url: string;
+    /** Last modification time of the sub-sitemap. */
     lastmod?: Date | string | undefined;
 }
+/**
+ * A provider responsible for yielding sitemap entries.
+ *
+ * Providers can be implemented to scan databases, file systems, or
+ * external APIs to discover content that should be included in the sitemap.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface SitemapProvider {
+    /**
+     * Generates a collection of sitemap entries.
+     *
+     * @returns An array, a promise of an array, or an async iterable of sitemap entries.
+     */
     getEntries(): Promise<SitemapEntry[]> | SitemapEntry[] | AsyncIterable<SitemapEntry>;
 }
+/**
+ * Configuration for the sitemap XML generation stream.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface SitemapStreamOptions {
+    /** Base domain used to normalize relative URLs. */
     baseUrl: string;
+    /** Whether to output formatted and indented XML. @default false */
     pretty?: boolean | undefined;
 }
+/**
+ * Persistence layer for storing generated sitemap files.
+ *
+ * Supports atomic deployments via "shadow" areas and provides hooks for
+ * version management and rollbacks.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface SitemapStorage {
+    /**
+     * Write sitemap content to the storage backend.
+     *
+     * @param filename - The destination filename.
+     * @param content - The raw XML content.
+     */
     write(filename: string, content: string): Promise<void>;
+    /**
+     * Read sitemap content from the storage backend.
+     *
+     * @param filename - The filename to read.
+     * @returns The XML content as a string, or null if not found.
+     */
     read(filename: string): Promise<string | null>;
+    /**
+     * Check if a sitemap file exists in storage.
+     *
+     * @param filename - The filename to check.
+     * @returns True if the file exists, false otherwise.
+     */
     exists(filename: string): Promise<boolean>;
+    /**
+     * Get the public URL for a given sitemap filename.
+     *
+     * @param filename - The sitemap filename.
+     * @returns The full public URL.
+     */
     getUrl(filename: string): string;
+    /**
+     * Write content to a non-public staging area for atomic deployment.
+     *
+     * @param filename - The target filename.
+     * @param content - The XML content.
+     * @param shadowId - Optional session identifier.
+     */
     writeShadow?(filename: string, content: string, shadowId?: string): Promise<void>;
+    /**
+     * Commit all staged files in a shadow session to production.
+     *
+     * @param shadowId - The identifier of the session to commit.
+     */
     commitShadow?(shadowId: string): Promise<void>;
+    /**
+     * List available archived versions of a specific sitemap.
+     *
+     * @param filename - The sitemap filename.
+     * @returns An array of version identifiers.
+     */
     listVersions?(filename: string): Promise<string[]>;
+    /**
+     * Revert a sitemap to a previously archived version.
+     *
+     * @param filename - The sitemap filename.
+     * @param version - The version identifier to switch to.
+     */
     switchVersion?(filename: string, version: string): Promise<void>;
 }
+/**
+ * Cache interface for storing frequently accessed sitemap fragments.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface SitemapCache {
+    /**
+     * Retrieve a cached XML fragment.
+     *
+     * @param key - The cache key.
+     * @returns The cached XML string, or null if miss.
+     */
     get(key: string): Promise<string | null>;
+    /**
+     * Store an XML fragment in the cache.
+     *
+     * @param key - The cache key.
+     * @param value - The XML content to cache.
+     * @param ttl - Optional time-to-live in seconds.
+     */
     set(key: string, value: string, ttl?: number): Promise<void>;
+    /**
+     * Check if a specific fragment is currently cached.
+     *
+     * @param key - The cache key.
+     * @returns True if hit, false otherwise.
+     */
     has(key: string): Promise<boolean>;
 }
+/**
+ * Distributed lock interface to prevent concurrent sitemap generation.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface SitemapLock {
+    /**
+     * Attempt to acquire a lock on a resource.
+     *
+     * @param resource - Identifier for the resource to lock.
+     * @param ttl - Lock expiration time in milliseconds.
+     * @returns True if the lock was acquired, false otherwise.
+     */
     acquire(resource: string, ttl: number): Promise<boolean>;
+    /**
+     * Release a previously held lock.
+     *
+     * @param resource - Identifier for the resource to unlock.
+     */
     release(resource: string): Promise<void>;
 }
+/**
+ * Progress tracking data for large-scale sitemap generation jobs.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface SitemapProgress {
+    /** Unique identifier for the generation job. */
     jobId: string;
+    /** Current state of the generation process. */
     status: 'pending' | 'processing' | 'completed' | 'failed';
+    /** Total number of URLs to be processed. */
     total: number;
+    /** Number of URLs already processed. */
     processed: number;
+    /** Completion percentage (0 to 100). */
     percentage: number;
+    /** Timestamp when the job was started. */
     startTime?: Date;
+    /** Timestamp when the job was finished or failed. */
     endTime?: Date;
+    /** Error message if the status is 'failed'. */
     error?: string;
 }
+/**
+ * Interface for persisting and retrieving sitemap job progress.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface SitemapProgressStorage {
+    /**
+     * Retrieve progress for a specific generation job.
+     *
+     * @param jobId - The job identifier.
+     */
     get(jobId: string): Promise<SitemapProgress | null>;
+    /**
+     * Initialize or overwrite a progress record.
+     *
+     * @param jobId - The job identifier.
+     * @param progress - The initial progress state.
+     */
     set(jobId: string, progress: SitemapProgress): Promise<void>;
+    /**
+     * Update specific fields of an existing progress record.
+     *
+     * @param jobId - The job identifier.
+     * @param updates - Object containing fields to update.
+     */
     update(jobId: string, updates: Partial<SitemapProgress>): Promise<void>;
+    /**
+     * Delete a progress record from storage.
+     *
+     * @param jobId - The job identifier.
+     */
     delete(jobId: string): Promise<void>;
+    /**
+     * List recent sitemap generation jobs.
+     *
+     * @param limit - Maximum number of records to return. @default 100
+     * @returns An array of progress records.
+     */
     list(limit?: number): Promise<SitemapProgress[]>;
 }
+/**
+ * The nature of a structural change detected in the site.
+ *
+ * @public
+ * @since 3.0.0
+ */
 type ChangeType = 'add' | 'update' | 'remove';
+/**
+ * Represents a single structural change detected in the site.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface SitemapChange {
+    /** The nature of the change (add, update, or remove). */
     type: ChangeType;
+    /** The target URL that was affected. */
     url: string;
+    /** The sitemap entry representation of the URL (for additions and updates). */
     entry?: SitemapEntry;
+    /** When the change was detected. */
     timestamp: Date;
 }
+/**
+ * Interface for tracking and querying site structure changes over time.
+ *
+ * Change trackers are used by the `IncrementalGenerator` to perform
+ * partial sitemap updates.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface ChangeTracker {
+    /**
+     * Record a new site structure change.
+     *
+     * @param change - The change event to record.
+     */
     track(change: SitemapChange): Promise<void>;
+    /**
+     * Retrieve all changes recorded since a specific time.
+     *
+     * @param since - Optional start date for the query.
+     * @returns An array of change events.
+     */
     getChanges(since?: Date): Promise<SitemapChange[]>;
+    /**
+     * Retrieve the full change history for a specific URL.
+     *
+     * @param url - The URL to query history for.
+     * @returns An array of change events.
+     */
     getChangesByUrl(url: string): Promise<SitemapChange[]>;
+    /**
+     * Purge old change records from storage.
+     *
+     * @param since - If provided, only records older than this date will be cleared.
+     */
     clear(since?: Date): Promise<void>;
 }
+/**
+ * Defines a 301 or 302 redirect rule managed by Constellation.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface RedirectRule {
+    /** The incoming URL path or glob pattern. */
     from: string;
+    /** The destination URL path or absolute URL. */
     to: string;
+    /** The HTTP status code (301 for permanent, 302 for temporary). */
     type: 301 | 302;
+    /** Timestamp when the redirect rule was created. */
     createdAt?: Date;
 }
+/**
+ * Manager for registering and resolving redirect rules.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface RedirectManager {
+    /**
+     * Register a single redirect rule.
+     *
+     * @param redirect - The redirect rule to add.
+     */
     register(redirect: RedirectRule): Promise<void>;
+    /**
+     * Register multiple redirect rules at once.
+     *
+     * @param redirects - An array of redirect rules.
+     */
     registerBatch(redirects: RedirectRule[]): Promise<void>;
+    /**
+     * Retrieve a specific redirect rule by its source path.
+     *
+     * @param from - The source path.
+     * @returns The redirect rule, or null if not found.
+     */
     get(from: string): Promise<RedirectRule | null>;
+    /**
+     * Retrieve all registered redirect rules.
+     *
+     * @returns An array of all redirect rules.
+     */
     getAll(): Promise<RedirectRule[]>;
+    /**
+     * Resolve a URL through the redirect table.
+     *
+     * @param url - The URL to resolve.
+     * @param followChains - Whether to recursively resolve if redirects point to other redirects.
+     * @param maxChainLength - Maximum depth for chain resolution to prevent infinite loops.
+     * @returns The final destination URL, or null if no redirect matches.
+     */
     resolve(url: string, followChains?: boolean, maxChainLength?: number): Promise<string | null>;
 }
 
+/**
+ * Options for configuring the `MemoryChangeTracker`.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface MemoryChangeTrackerOptions {
+    /** Maximum number of changes to keep in memory. @default 100000 */
     maxChanges?: number;
 }
 /**
- * 記憶體變更追蹤器實作
- * 適用於單一進程或開發環境
+ * MemoryChangeTracker is a simple, in-memory implementation of the `ChangeTracker`.
+ *
+ * It is suitable for single-process applications or development environments where
+ * persistence of change history across restarts is not required.
+ *
+ * @public
+ * @since 3.0.0
  */
 declare class MemoryChangeTracker implements ChangeTracker {
     private changes;
@@ -149,14 +512,29 @@ declare class MemoryChangeTracker implements ChangeTracker {
     getChangesByUrl(url: string): Promise<SitemapChange[]>;
     clear(since?: Date): Promise<void>;
 }
+/**
+ * Options for configuring the `RedisChangeTracker`.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface RedisChangeTrackerOptions {
+    /** The Redis client instance. */
     client: any;
+    /** Prefix for Redis keys to avoid collisions. @default 'sitemap:changes:' */
     keyPrefix?: string;
+    /** Time-to-live for change records in seconds. @default 604800 (7 days) */
     ttl?: number;
 }
 /**
- * Redis 變更追蹤器實作
- * 適用於分散式環境或多進程
+ * RedisChangeTracker provides a distributed implementation of the `ChangeTracker`.
+ *
+ * It uses Redis to store change records, making it suitable for multi-process
+ * or distributed environments where multiple instances of Gravito need to
+ * share change history.
+ *
+ * @public
+ * @since 3.0.0
  */
 declare class RedisChangeTracker implements ChangeTracker {
     private client;
@@ -171,17 +549,39 @@ declare class RedisChangeTracker implements ChangeTracker {
     clear(since?: Date): Promise<void>;
 }
 
+/**
+ * Result of a sitemap difference calculation.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface DiffResult {
+    /** Entries that are present in the new set but not in the old one. */
     added: SitemapEntry[];
+    /** Entries that are present in both sets but have different metadata. */
     updated: SitemapEntry[];
+    /** URLs that were present in the old set but are missing from the new one. */
     removed: string[];
 }
+/**
+ * Options for configuring the `DiffCalculator`.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface DiffCalculatorOptions {
+    /** Batch size for processing large datasets. @default 10000 */
     batchSize?: number;
 }
 /**
- * 差異計算器
- * 比較兩個 sitemap 狀態，計算差異
+ * DiffCalculator compares two sets of sitemap entries to identify changes.
+ *
+ * It is used for incremental sitemap generation, allowing the system to
+ * update only the parts of the sitemap that have actually changed (added,
+ * updated, or removed).
+ *
+ * @public
+ * @since 3.0.0
  */
 declare class DiffCalculator {
     private batchSize;
@@ -204,19 +604,47 @@ declare class DiffCalculator {
     private hasChanged;
 }
 
+/**
+ * Options for configuring the `ShadowProcessor`.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface ShadowProcessorOptions {
+    /** The storage backend used for writing files. */
     storage: SitemapStorage;
+    /**
+     * Deployment mode:
+     * - `atomic`: All files are swapped at once when committed.
+     * - `versioned`: Each file is committed individually, potentially creating a new version.
+     */
     mode: 'atomic' | 'versioned';
+    /** Whether shadow processing is enabled. */
     enabled: boolean;
 }
+/**
+ * Represents a single file write operation within a shadow session.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface ShadowOperation {
+    /** The destination filename. */
     filename: string;
+    /** The file content to be written. */
     content: string;
+    /** Optional unique identifier for the shadow session. */
     shadowId?: string;
 }
 /**
- * 影子處理器
- * 管理影子生成流程，支援原子切換和版本化兩種模式
+ * ShadowProcessor manages the staging and atomic deployment of generated files.
+ *
+ * It allows files to be written to a "shadow" location before being "committed"
+ * (swapped) to their final destination, ensuring zero-downtime and atomic updates
+ * for sitemaps and indexes.
+ *
+ * @public
+ * @since 3.0.0
  */
 declare class ShadowProcessor {
     private options;
@@ -245,21 +673,55 @@ declare class ShadowProcessor {
     getOperations(): ShadowOperation[];
 }
 
+/**
+ * Options for configuring the `SitemapGenerator`.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface SitemapGeneratorOptions extends SitemapStreamOptions {
+    /** The storage backend where the sitemap files will be written. */
     storage: SitemapStorage;
+    /** An array of providers that supply the entries to be included in the sitemap. */
     providers: SitemapProvider[];
+    /** Maximum number of entries per individual sitemap file. @default 50000 */
     maxEntriesPerFile?: number;
+    /** The name of the main sitemap or sitemap index file. @default 'sitemap.xml' */
     filename?: string;
+    /** Configuration for staging files before atomic deployment. */
     shadow?: {
+        /** Whether shadow processing is enabled. */
         enabled: boolean;
+        /** Deployment mode: 'atomic' or 'versioned'. */
         mode: 'atomic' | 'versioned';
     };
+    /** Optional callback to track generation progress. */
     onProgress?: (progress: {
         processed: number;
         total: number;
         percentage: number;
     }) => void;
 }
+/**
+ * SitemapGenerator is the primary orchestrator for creating sitemaps in Gravito.
+ *
+ * It coordinates multiple `SitemapProvider`s, handles file sharding when
+ * URL limits are reached, and uses a `ShadowProcessor` for atomic deployments.
+ * It automatically generates a sitemap index if multiple files are produced.
+ *
+ * @example
+ * ```typescript
+ * const generator = new SitemapGenerator({
+ *   baseUrl: 'https://example.com',
+ *   storage: new DiskSitemapStorage('./public'),
+ *   providers: [new RouteScanner()]
+ * });
+ * await generator.run();
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class SitemapGenerator {
     private options;
     private shadowProcessor;
@@ -271,14 +733,31 @@ declare class SitemapGenerator {
     getShadowProcessor(): ShadowProcessor | null;
 }
 
+/**
+ * Options for configuring the `IncrementalGenerator`.
+ *
+ * Extends `SitemapGeneratorOptions` to include change tracking and difference
+ * calculation components.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface IncrementalGeneratorOptions extends SitemapGeneratorOptions {
+    /** The change tracker used to store and retrieve sitemap changes. */
     changeTracker: ChangeTracker;
+    /** Optional difference calculator. Defaults to a new `DiffCalculator` instance. */
     diffCalculator?: DiffCalculator;
+    /** Whether to automatically track changes during full generation. @default true */
     autoTrack?: boolean;
 }
 /**
- * 增量生成器
- * 只生成變更的 URL，不重新生成整個 sitemap
+ * IncrementalGenerator optimizes sitemap updates by processing only changed URLs.
+ *
+ * Instead of regenerating the entire sitemap from scratch, it uses a `ChangeTracker`
+ * to identify new, updated, or removed URLs and updates the sitemap incrementally.
+ *
+ * @public
+ * @since 3.0.0
  */
 declare class IncrementalGenerator {
     private options;
@@ -316,13 +795,26 @@ declare class IncrementalGenerator {
     private toArray;
 }
 
+/**
+ * Options for configuring the `ProgressTracker`.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface ProgressTrackerOptions {
+    /** The storage backend used to persist progress information. */
     storage: SitemapProgressStorage;
+    /** Update interval in milliseconds. @default 1000 */
     updateInterval?: number;
 }
 /**
- * 進度追蹤器
- * 追蹤 sitemap 生成進度
+ * ProgressTracker monitors and persists the progress of sitemap generation jobs.
+ *
+ * It provides methods to initialize, update, and complete progress tracking,
+ * ensuring that long-running generation tasks can be monitored via the storage backend.
+ *
+ * @public
+ * @since 3.0.0
  */
 declare class ProgressTracker {
     private storage;
@@ -360,6 +852,23 @@ declare class ProgressTracker {
     getCurrentProgress(): SitemapProgress | null;
 }
 
+/**
+ * SitemapIndex handles the generation of sitemap index files.
+ *
+ * A sitemap index is used when a site has multiple sitemap files, usually
+ * because the number of URLs exceeds the 50,000 limit per sitemap.
+ *
+ * @example
+ * ```typescript
+ * const index = new SitemapIndex({ baseUrl: 'https://example.com' });
+ * index.add('sitemap-posts.xml');
+ * index.add({ url: 'sitemap-pages.xml', lastmod: new Date() });
+ * const xml = index.toXML();
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class SitemapIndex {
     private options;
     private entries;
@@ -370,6 +879,26 @@ declare class SitemapIndex {
     private escape;
 }
 
+/**
+ * SitemapStream handles the low-level generation of sitemap XML content.
+ *
+ * It supports standard sitemap tags as well as Google-specific extensions for
+ * images, videos, news, and internationalization (i18n) via `xhtml:link`.
+ *
+ * @example
+ * ```typescript
+ * const stream = new SitemapStream({ baseUrl: 'https://example.com' });
+ * stream.add({
+ *   url: '/contact',
+ *   changefreq: 'monthly',
+ *   priority: 0.5
+ * });
+ * const xml = stream.toXML();
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class SitemapStream {
     private options;
     private entries;
@@ -400,22 +929,41 @@ type I18nSitemapEntryOptions = Omit<SitemapEntry, 'url' | 'alternates'>;
  */
 declare function generateI18nEntries(path: string, locales: string[], baseUrl?: string, options?: I18nSitemapEntryOptions): SitemapEntry[];
 
+/**
+ * Options for configuring the `GenerateSitemapJob`.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface GenerateSitemapJobOptions {
+    /** Options for the underlying sitemap generator. */
     generatorOptions: SitemapGeneratorOptions;
+    /** Unique identifier for the generation job. */
     jobId: string;
+    /** Optional progress tracker to monitor execution state. */
     progressTracker?: ProgressTracker;
+    /** Optional shadow processor for atomic deployments. */
     shadowProcessor?: ShadowProcessor;
+    /** Optional callback triggered during progress updates. */
     onProgress?: (progress: {
         processed: number;
         total: number;
         percentage: number;
     }) => void;
+    /** Optional callback triggered when the job completes successfully. */
     onComplete?: () => void;
+    /** Optional callback triggered when the job encounters an error. */
     onError?: (error: Error) => void;
 }
 /**
- * Sitemap 生成背景任務
- * 整合背景任務處理和進度追蹤
+ * GenerateSitemapJob is a background task for processing large-scale sitemaps.
+ *
+ * It integrates with Gravito's `stream` module to provide asynchronous,
+ * observable sitemap generation with real-time progress tracking and
+ * atomic deployment support.
+ *
+ * @public
+ * @since 3.0.0
  */
 declare class GenerateSitemapJob extends Job {
     private options;
@@ -434,37 +982,110 @@ declare class GenerateSitemapJob extends Job {
     private generateWithProgress;
 }
 
+/**
+ * Configuration for a dynamically generated sitemap that is built upon request.
+ *
+ * Useful for small to medium sites where fresh data is critical. Dynamic sitemaps
+ * are generated on-the-fly and can be cached at the HTTP level.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface DynamicSitemapOptions extends SitemapStreamOptions {
+    /** The URL path where the sitemap will be exposed. @default '/sitemap.xml' */
     path?: string | undefined;
+    /** List of sitemap entry providers to scan for content. */
     providers: SitemapProvider[];
+    /** Cache duration in seconds for the HTTP response. @default undefined (no-cache) */
     cacheSeconds?: number | undefined;
+    /** Persistence backend for cached XML files. Defaults to MemorySitemapStorage. */
     storage?: SitemapStorage | undefined;
+    /** Optional distributed lock to prevent "cache stampede" during heavy generation. */
     lock?: SitemapLock | undefined;
 }
+/**
+ * Configuration for a statically pre-generated sitemap.
+ *
+ * Recommended for large sites or high-traffic applications. Static sitemaps
+ * are built (usually as part of a build process) and served as static files.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface StaticSitemapOptions extends SitemapStreamOptions {
+    /** Local directory where generated XML files will be saved. */
     outDir: string;
+    /** The name of the root sitemap file. @default 'sitemap.xml' */
     filename?: string | undefined;
+    /** List of sitemap entry providers to scan for content. */
     providers: SitemapProvider[];
+    /** Custom storage backend. Defaults to DiskSitemapStorage using `outDir`. */
     storage?: SitemapStorage | undefined;
+    /** Optional incremental generation settings to only update changed URLs. */
     incremental?: {
+        /** Whether to enable incremental builds. */
         enabled: boolean;
+        /** Backend for tracking structural site changes. */
         changeTracker: ChangeTracker;
+        /** Whether to automatically record new changes during scan. @default false */
         autoTrack?: boolean;
     };
+    /** Optional SEO redirect orchestration settings. */
     redirect?: {
+        /** Whether to automatically handle 301/302 redirects found in sitemap. */
         enabled: boolean;
+        /** Backend for managing and resolving redirect rules. */
         manager: RedirectManager;
+        /** Strategy for resolving conflicting or chained redirects. @default 'remove_old_add_new' */
         strategy?: 'remove_old_add_new' | 'keep_relation' | 'update_url' | 'dual_mark';
+        /** Whether to resolve redirect chains into a single jump. @default false */
         followChains?: boolean;
+        /** Maximum number of redirect jumps to follow. @default 5 */
         maxChainLength?: number;
     };
+    /** Deployment settings for atomic sitemap updates via shadow staging. */
     shadow?: {
+        /** Whether to enable "shadow" (atomic staging) mode. */
         enabled: boolean;
+        /** The update strategy: 'atomic' (full swap) or 'versioned' (archived). @default 'atomic' */
         mode: 'atomic' | 'versioned';
     };
+    /** Persistence backend for long-running job progress tracking. */
     progressStorage?: SitemapProgressStorage;
 }
-declare class OrbitSitemap {
+/**
+ * OrbitSitemap is the enterprise SEO orchestration module for Gravito.
+ *
+ * It provides advanced sitemap generation supporting large-scale indexing,
+ * automatic 301/302 redirect handling, and atomic sitemap deployments.
+ *
+ * It can operate in two modes:
+ * 1. **Dynamic**: Sitemaps are generated on-the-fly and cached.
+ * 2. **Static**: Sitemaps are pre-built (e.g., during CI/CD) and served from disk or cloud storage.
+ *
+ * @example Dynamic Mode
+ * ```typescript
+ * const sitemap = OrbitSitemap.dynamic({
+ *   baseUrl: 'https://example.com',
+ *   providers: [new PostSitemapProvider()]
+ * });
+ * core.addOrbit(sitemap);
+ * ```
+ *
+ * @example Static Mode
+ * ```typescript
+ * const sitemap = OrbitSitemap.static({
+ *   baseUrl: 'https://example.com',
+ *   outDir: './public',
+ *   shadow: { enabled: true, mode: 'atomic' }
+ * });
+ * await sitemap.generate();
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
+declare class OrbitSitemap implements GravitoOrbit {
     private options;
     private mode;
     private constructor();
@@ -535,53 +1156,149 @@ declare class OrbitSitemap {
     private toArray;
 }
 
+/**
+ * Options for configuring the `RouteScanner`.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface RouteScannerOptions {
+    /** Glob patterns of routes to explicitly include. */
     include?: string[] | undefined;
+    /** Glob patterns of routes to exclude from the sitemap. */
     exclude?: string[] | undefined;
+    /** Default change frequency for scanned routes. @default 'weekly' */
     defaultChangefreq?: ChangeFreq | undefined;
+    /** Default priority for scanned routes (0.0 to 1.0). @default 0.5 */
     defaultPriority?: number | undefined;
 }
+/**
+ * RouteScanner automatically discovers static GET routes from the Gravito router.
+ *
+ * It filters out routes with parameters (e.g., /user/:id) and non-GET routes
+ * by default, ensuring that only crawlable pages are included in the sitemap.
+ *
+ * @example
+ * ```typescript
+ * const scanner = new RouteScanner(app.router, {
+ *   exclude: ['/admin/*', '/internal/*']
+ * });
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class RouteScanner implements SitemapProvider {
     private router;
     private options;
     constructor(router: any, options?: RouteScannerOptions);
+    /**
+     * Scan the router and return discovered entries.
+     *
+     * @returns An array of sitemap entries.
+     */
     getEntries(): SitemapEntry[];
     private extractRoutes;
     private shouldInclude;
 }
+/**
+ * Functional factory for creating a `RouteScanner`.
+ *
+ * @param router - The Gravito router instance.
+ * @param options - Optional scanner configuration.
+ * @returns A new RouteScanner instance.
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare function routeScanner(router: any, options?: RouteScannerOptions): RouteScanner;
 
+/**
+ * Options for automatic redirect detection via HTTP probes.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface AutoDetectOptions {
+    /** Whether automatic HTTP detection is enabled. */
     enabled: boolean;
+    /** HTTP request timeout in milliseconds. @default 5000 */
     timeout?: number;
+    /** Maximum number of concurrent HTTP probes. @default 10 */
     maxConcurrent?: number;
+    /** Whether to cache detection results in memory. @default false */
     cache?: boolean;
+    /** Cache time-to-live in seconds. @default 3600 */
     cacheTtl?: number;
 }
+/**
+ * Options for redirect detection from a database table.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface DatabaseDetectOptions {
+    /** Whether database detection is enabled. */
     enabled: boolean;
+    /** The name of the table containing redirect rules. */
     table: string;
+    /** Column mapping for the redirect table. */
     columns: {
         from: string;
         to: string;
         type: string;
     };
+    /** Database connection instance (e.g., Knex, Atlas). */
     connection: any;
 }
+/**
+ * Options for redirect detection from a static configuration file.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface ConfigDetectOptions {
+    /** Whether configuration file detection is enabled. */
     enabled: boolean;
+    /** Path to the JSON configuration file. */
     path: string;
+    /** Whether to watch the file for changes. @default false */
     watch?: boolean;
 }
+/**
+ * Options for configuring the `RedirectDetector`.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface RedirectDetectorOptions {
+    /** The base URL of the site being scanned. */
     baseUrl: string;
+    /** Configuration for automatic HTTP probing. */
     autoDetect?: AutoDetectOptions;
+    /** Configuration for database-driven detection. */
     database?: DatabaseDetectOptions;
+    /** Configuration for file-driven detection. */
     config?: ConfigDetectOptions;
 }
 /**
- * 轉址偵測器
- * 支援多種偵測方式：自動偵測、資料庫、設定檔
+ * RedirectDetector identifies 301 and 302 redirects for URLs.
+ *
+ * It supports multiple detection strategies including database lookups,
+ * static configuration files, and live HTTP probing. This ensures that
+ * sitemaps always point to final destination URLs, improving SEO efficiency.
+ *
+ * @example
+ * ```typescript
+ * const detector = new RedirectDetector({
+ *   baseUrl: 'https://example.com',
+ *   autoDetect: { enabled: true }
+ * });
+ * const rule = await detector.detect('/old-path');
+ * ```
+ *
+ * @public
+ * @since 3.0.0
  */
 declare class RedirectDetector {
     private options;
@@ -613,16 +1330,45 @@ declare class RedirectDetector {
     private cacheResult;
 }
 
-type RedirectHandlingStrategy = 'remove_old_add_new' | 'keep_relation' | 'update_url' | 'dual_mark';
+/**
+ * Strategies for handling URLs that have redirects in the sitemap.
+ *
+ * @public
+ * @since 3.0.0
+ */
+type RedirectHandlingStrategy = 
+/** Replace the old URL with the final destination URL. (Default) */
+'remove_old_add_new'
+/** Keep the old URL in the sitemap but mark the final destination as canonical. */
+ | 'keep_relation'
+/** Silently update the URL to the destination without extra metadata. */
+ | 'update_url'
+/** Include both the original and destination URLs in the sitemap. */
+ | 'dual_mark';
+/**
+ * Options for configuring the `RedirectHandler`.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface RedirectHandlerOptions {
+    /** The redirect manager used to resolve rules. */
     manager: RedirectManager;
+    /** The strategy to use when a redirect is found. */
     strategy: RedirectHandlingStrategy;
+    /** Whether to follow redirect chains to the final destination. @default false */
     followChains?: boolean;
+    /** Maximum number of redirect jumps to follow. @default 5 */
     maxChainLength?: number;
 }
 /**
- * 轉址處理器
- * 處理 sitemap entries 中的轉址
+ * RedirectHandler processes sitemap entries to ensure they handle 301/302 redirects correctly.
+ *
+ * It uses a `RedirectManager` to resolve final destinations and applies one of
+ * the supported `RedirectHandlingStrategy` options to the entry list.
+ *
+ * @public
+ * @since 3.0.0
  */
 declare class RedirectHandler {
     private options;
@@ -649,11 +1395,24 @@ declare class RedirectHandler {
     private handleDualMark;
 }
 
+/**
+ * Options for configuring the `MemoryRedirectManager`.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface MemoryRedirectManagerOptions {
+    /** Maximum number of rules to keep in memory. @default 100000 */
     maxRules?: number;
 }
 /**
- * 記憶體轉址管理器實作
+ * MemoryRedirectManager is a fast, in-memory implementation of the `RedirectManager`.
+ *
+ * It is suitable for development environments or small sites where redirect
+ * rules do not need to persist across application restarts.
+ *
+ * @public
+ * @since 3.0.0
  */
 declare class MemoryRedirectManager implements RedirectManager {
     private rules;
@@ -665,13 +1424,29 @@ declare class MemoryRedirectManager implements RedirectManager {
     getAll(): Promise<RedirectRule[]>;
     resolve(url: string, followChains?: boolean, maxChainLength?: number): Promise<string | null>;
 }
+/**
+ * Options for configuring the `RedisRedirectManager`.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface RedisRedirectManagerOptions {
+    /** The Redis client instance. */
     client: any;
+    /** Prefix for Redis keys to avoid collisions. @default 'sitemap:redirects:' */
     keyPrefix?: string;
+    /** Time-to-live for redirect rules in seconds. If not set, rules are permanent. */
     ttl?: number;
 }
 /**
- * Redis 轉址管理器實作
+ * RedisRedirectManager provides a persistent, distributed implementation of the `RedirectManager`.
+ *
+ * It uses Redis to store redirect rules, making it suitable for production
+ * environments where multiple application instances need to share the same
+ * redirect configuration.
+ *
+ * @public
+ * @since 3.0.0
  */
 declare class RedisRedirectManager implements RedirectManager {
     private client;
@@ -687,6 +1462,22 @@ declare class RedisRedirectManager implements RedirectManager {
     resolve(url: string, followChains?: boolean, maxChainLength?: number): Promise<string | null>;
 }
 
+/**
+ * DiskSitemapStorage persists sitemap files to the local file system.
+ *
+ * It is the default storage backend for single-server Gravito deployments.
+ * It automatically handles directory creation and ensures filenames are sanitized
+ * to prevent path traversal attacks.
+ *
+ * @example
+ * ```typescript
+ * const storage = new DiskSitemapStorage('./public/sitemaps', 'https://example.com/sitemaps');
+ * await storage.write('sitemap.xml', '...');
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class DiskSitemapStorage implements SitemapStorage {
     private outDir;
     private baseUrl;
@@ -697,20 +1488,48 @@ declare class DiskSitemapStorage implements SitemapStorage {
     getUrl(filename: string): string;
 }
 
+/**
+ * Options for configuring the `GCPSitemapStorage`.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface GCPSitemapStorageOptions {
+    /** The Google Cloud Storage bucket name. */
     bucket: string;
+    /** Optional prefix (folder path) within the bucket. */
     prefix?: string;
+    /** Optional base URL for resolving sitemap locations. Defaults to the standard GCS public URL. */
     baseUrl?: string;
+    /** Configuration for staging files before atomic deployment. */
     shadow?: {
+        /** Whether shadow processing is enabled. */
         enabled: boolean;
+        /** Deployment mode: 'atomic' or 'versioned'. */
         mode: 'atomic' | 'versioned';
     };
+    /** Path to the service account key file. */
     keyFilename?: string;
+    /** The Google Cloud Project ID. */
     projectId?: string;
 }
 /**
- * Google Cloud Storage 儲存實作
- * 支援影子處理和版本化
+ * GCPSitemapStorage persists sitemap files to Google Cloud Storage.
+ *
+ * It supports atomic deployments via shadow processing and file versioning,
+ * allowing for reliable updates in high-traffic cloud environments.
+ *
+ * @example
+ * ```typescript
+ * const storage = new GCPSitemapStorage({
+ *   bucket: 'my-sitemaps',
+ *   prefix: 'prod/',
+ *   shadow: { enabled: true, mode: 'atomic' }
+ * });
+ * ```
+ *
+ * @public
+ * @since 3.0.0
  */
 declare class GCPSitemapStorage implements SitemapStorage {
     private bucket;
@@ -746,6 +1565,21 @@ declare class MemoryProgressStorage implements SitemapProgressStorage {
     list(limit?: number): Promise<SitemapProgress[]>;
 }
 
+/**
+ * MemorySitemapStorage is a non-persistent, in-memory storage backend for sitemaps.
+ *
+ * It is primarily used for testing or for applications where sitemaps are
+ * generated on-the-fly and served directly from memory.
+ *
+ * @example
+ * ```typescript
+ * const storage = new MemorySitemapStorage('https://example.com');
+ * await storage.write('sitemap.xml', '...');
+ * ```
+ *
+ * @public
+ * @since 3.0.0
+ */
 declare class MemorySitemapStorage implements SitemapStorage {
     private baseUrl;
     private files;
@@ -756,14 +1590,28 @@ declare class MemorySitemapStorage implements SitemapStorage {
     getUrl(filename: string): string;
 }
 
+/**
+ * Options for configuring the `RedisProgressStorage`.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface RedisProgressStorageOptions {
+    /** The Redis client instance. */
     client: any;
+    /** Prefix for Redis keys to avoid collisions. @default 'sitemap:progress:' */
     keyPrefix?: string;
+    /** Time-to-live for progress records in seconds. @default 86400 (24 hours) */
     ttl?: number;
 }
 /**
- * Redis 進度儲存實作
- * 適用於分散式環境或多進程
+ * RedisProgressStorage persists sitemap generation progress to Redis.
+ *
+ * It is designed for multi-process or distributed environments where progress
+ * needs to be tracked across multiple worker instances.
+ *
+ * @public
+ * @since 3.0.0
  */
 declare class RedisProgressStorage implements SitemapProgressStorage {
     private client;
@@ -779,23 +1627,51 @@ declare class RedisProgressStorage implements SitemapProgressStorage {
     list(limit?: number): Promise<SitemapProgress[]>;
 }
 
+/**
+ * Options for configuring the `S3SitemapStorage`.
+ *
+ * @public
+ * @since 3.0.0
+ */
 interface S3SitemapStorageOptions {
+    /** The AWS S3 bucket name. */
     bucket: string;
+    /** The AWS region where the bucket is located. @default 'us-east-1' */
     region?: string;
+    /** Optional prefix (folder path) within the bucket. */
     prefix?: string;
+    /** Optional base URL for resolving sitemap locations. Defaults to standard S3 URL. */
     baseUrl?: string;
+    /** Configuration for staging files before atomic deployment. */
     shadow?: {
+        /** Whether shadow processing is enabled. */
         enabled: boolean;
+        /** Deployment mode: 'atomic' or 'versioned'. */
         mode: 'atomic' | 'versioned';
     };
+    /** Optional AWS credentials. If not provided, the SDK will use environment defaults. */
     credentials?: {
         accessKeyId: string;
         secretAccessKey: string;
     };
 }
 /**
- * AWS S3 儲存實作
- * 支援影子處理和版本化
+ * S3SitemapStorage persists sitemap files to AWS S3.
+ *
+ * It provides robust cloud storage with support for shadow processing
+ * and file versioning, ensuring safe and atomic sitemap updates.
+ *
+ * @example
+ * ```typescript
+ * const storage = new S3SitemapStorage({
+ *   bucket: 'my-sitemaps',
+ *   region: 'ap-northeast-1',
+ *   shadow: { enabled: true, mode: 'atomic' }
+ * });
+ * ```
+ *
+ * @public
+ * @since 3.0.0
  */
 declare class S3SitemapStorage implements SitemapStorage {
     private bucket;