@gravito/constellation 1.0.0-alpha.6 → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,821 @@
+import { Job } from '@gravito/stream';
+import { PlanetCore } from '@gravito/core';
+
+type ChangeFreq = 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+interface AlternateUrl {
+    lang: string;
+    url: string;
+}
+interface SitemapImage {
+    loc: string;
+    title?: string | undefined;
+    caption?: string | undefined;
+    geo_location?: string | undefined;
+    license?: string | undefined;
+}
+interface SitemapVideo {
+    thumbnail_loc: string;
+    title: string;
+    description: string;
+    content_loc?: string | undefined;
+    player_loc?: string | undefined;
+    duration?: number | undefined;
+    expiration_date?: Date | string | undefined;
+    rating?: number | undefined;
+    view_count?: number | undefined;
+    publication_date?: Date | string | undefined;
+    family_friendly?: 'yes' | 'no' | undefined;
+    tag?: string[] | undefined;
+    category?: string | undefined;
+    restriction?: {
+        relationship: 'allow' | 'deny';
+        countries: string[];
+    } | undefined;
+}
+interface SitemapNews {
+    publication: {
+        name: string;
+        language: string;
+    };
+    publication_date: Date | string;
+    title: string;
+    genres?: string | undefined;
+    keywords?: string[] | undefined;
+    stock_tickers?: string[] | undefined;
+}
+interface SitemapEntry {
+    url: string;
+    lastmod?: Date | string | undefined;
+    changefreq?: ChangeFreq | undefined;
+    priority?: number | undefined;
+    alternates?: AlternateUrl[] | undefined;
+    images?: SitemapImage[] | undefined;
+    videos?: SitemapVideo[] | undefined;
+    news?: SitemapNews | undefined;
+    redirect?: {
+        from: string;
+        to: string;
+        type: 301 | 302;
+        canonical?: string;
+    };
+}
+interface SitemapIndexEntry {
+    url: string;
+    lastmod?: Date | string | undefined;
+}
+interface SitemapProvider {
+    getEntries(): Promise<SitemapEntry[]> | SitemapEntry[] | AsyncIterable<SitemapEntry>;
+}
+interface SitemapStreamOptions {
+    baseUrl: string;
+    pretty?: boolean | undefined;
+}
+interface SitemapStorage {
+    write(filename: string, content: string): Promise<void>;
+    read(filename: string): Promise<string | null>;
+    exists(filename: string): Promise<boolean>;
+    getUrl(filename: string): string;
+    writeShadow?(filename: string, content: string, shadowId?: string): Promise<void>;
+    commitShadow?(shadowId: string): Promise<void>;
+    listVersions?(filename: string): Promise<string[]>;
+    switchVersion?(filename: string, version: string): Promise<void>;
+}
+interface SitemapCache {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttl?: number): Promise<void>;
+    has(key: string): Promise<boolean>;
+}
+interface SitemapLock {
+    acquire(resource: string, ttl: number): Promise<boolean>;
+    release(resource: string): Promise<void>;
+}
+interface SitemapProgress {
+    jobId: string;
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    total: number;
+    processed: number;
+    percentage: number;
+    startTime?: Date;
+    endTime?: Date;
+    error?: string;
+}
+interface SitemapProgressStorage {
+    get(jobId: string): Promise<SitemapProgress | null>;
+    set(jobId: string, progress: SitemapProgress): Promise<void>;
+    update(jobId: string, updates: Partial<SitemapProgress>): Promise<void>;
+    delete(jobId: string): Promise<void>;
+    list(limit?: number): Promise<SitemapProgress[]>;
+}
+type ChangeType = 'add' | 'update' | 'remove';
+interface SitemapChange {
+    type: ChangeType;
+    url: string;
+    entry?: SitemapEntry;
+    timestamp: Date;
+}
+interface ChangeTracker {
+    track(change: SitemapChange): Promise<void>;
+    getChanges(since?: Date): Promise<SitemapChange[]>;
+    getChangesByUrl(url: string): Promise<SitemapChange[]>;
+    clear(since?: Date): Promise<void>;
+}
+interface RedirectRule {
+    from: string;
+    to: string;
+    type: 301 | 302;
+    createdAt?: Date;
+}
+interface RedirectManager {
+    register(redirect: RedirectRule): Promise<void>;
+    registerBatch(redirects: RedirectRule[]): Promise<void>;
+    get(from: string): Promise<RedirectRule | null>;
+    getAll(): Promise<RedirectRule[]>;
+    resolve(url: string, followChains?: boolean, maxChainLength?: number): Promise<string | null>;
+}
+
+interface MemoryChangeTrackerOptions {
+    maxChanges?: number;
+}
+/**
+ * 記憶體變更追蹤器實作
+ * 適用於單一進程或開發環境
+ */
+declare class MemoryChangeTracker implements ChangeTracker {
+    private changes;
+    private maxChanges;
+    constructor(options?: MemoryChangeTrackerOptions);
+    track(change: SitemapChange): Promise<void>;
+    getChanges(since?: Date): Promise<SitemapChange[]>;
+    getChangesByUrl(url: string): Promise<SitemapChange[]>;
+    clear(since?: Date): Promise<void>;
+}
+interface RedisChangeTrackerOptions {
+    client: any;
+    keyPrefix?: string;
+    ttl?: number;
+}
+/**
+ * Redis 變更追蹤器實作
+ * 適用於分散式環境或多進程
+ */
+declare class RedisChangeTracker implements ChangeTracker {
+    private client;
+    private keyPrefix;
+    private ttl;
+    constructor(options: RedisChangeTrackerOptions);
+    private getKey;
+    private getListKey;
+    track(change: SitemapChange): Promise<void>;
+    getChanges(since?: Date): Promise<SitemapChange[]>;
+    getChangesByUrl(url: string): Promise<SitemapChange[]>;
+    clear(since?: Date): Promise<void>;
+}
+
+interface DiffResult {
+    added: SitemapEntry[];
+    updated: SitemapEntry[];
+    removed: string[];
+}
+interface DiffCalculatorOptions {
+    batchSize?: number;
+}
+/**
+ * 差異計算器
+ * 比較兩個 sitemap 狀態，計算差異
+ */
+declare class DiffCalculator {
+    private batchSize;
+    constructor(options?: DiffCalculatorOptions);
+    /**
+     * 計算兩個 sitemap 狀態的差異
+     */
+    calculate(oldEntries: SitemapEntry[], newEntries: SitemapEntry[]): DiffResult;
+    /**
+     * 批次計算差異（用於大量 URL）
+     */
+    calculateBatch(oldEntries: AsyncIterable<SitemapEntry>, newEntries: AsyncIterable<SitemapEntry>): Promise<DiffResult>;
+    /**
+     * 從變更記錄計算差異
+     */
+    calculateFromChanges(baseEntries: SitemapEntry[], changes: SitemapChange[]): DiffResult;
+    /**
+     * 檢查 entry 是否有變更
+     */
+    private hasChanged;
+}
+
+interface ShadowProcessorOptions {
+    storage: SitemapStorage;
+    mode: 'atomic' | 'versioned';
+    enabled: boolean;
+}
+interface ShadowOperation {
+    filename: string;
+    content: string;
+    shadowId?: string;
+}
+/**
+ * 影子處理器
+ * 管理影子生成流程，支援原子切換和版本化兩種模式
+ */
+declare class ShadowProcessor {
+    private options;
+    private shadowId;
+    private operations;
+    constructor(options: ShadowProcessorOptions);
+    /**
+     * 添加一個影子操作
+     */
+    addOperation(operation: ShadowOperation): Promise<void>;
+    /**
+     * 提交所有影子操作
+     */
+    commit(): Promise<void>;
+    /**
+     * 取消所有影子操作
+     */
+    rollback(): Promise<void>;
+    /**
+     * 獲取當前影子 ID
+     */
+    getShadowId(): string;
+    /**
+     * 獲取所有操作
+     */
+    getOperations(): ShadowOperation[];
+}
+
+interface SitemapGeneratorOptions extends SitemapStreamOptions {
+    storage: SitemapStorage;
+    providers: SitemapProvider[];
+    maxEntriesPerFile?: number;
+    filename?: string;
+    shadow?: {
+        enabled: boolean;
+        mode: 'atomic' | 'versioned';
+    };
+    onProgress?: (progress: {
+        processed: number;
+        total: number;
+        percentage: number;
+    }) => void;
+}
+declare class SitemapGenerator {
+    private options;
+    private shadowProcessor;
+    constructor(options: SitemapGeneratorOptions);
+    run(): Promise<void>;
+    /**
+     * 獲取影子處理器（如果啟用）
+     */
+    getShadowProcessor(): ShadowProcessor | null;
+}
+
+interface IncrementalGeneratorOptions extends SitemapGeneratorOptions {
+    changeTracker: ChangeTracker;
+    diffCalculator?: DiffCalculator;
+    autoTrack?: boolean;
+}
+/**
+ * 增量生成器
+ * 只生成變更的 URL，不重新生成整個 sitemap
+ */
+declare class IncrementalGenerator {
+    private options;
+    private changeTracker;
+    private diffCalculator;
+    private generator;
+    constructor(options: IncrementalGeneratorOptions);
+    /**
+     * 生成完整的 sitemap（首次生成）
+     */
+    generateFull(): Promise<void>;
+    /**
+     * 增量生成（只更新變更的部分）
+     */
+    generateIncremental(since?: Date): Promise<void>;
+    /**
+     * 手動追蹤變更
+     */
+    trackChange(change: SitemapChange): Promise<void>;
+    /**
+     * 獲取變更記錄
+     */
+    getChanges(since?: Date): Promise<SitemapChange[]>;
+    /**
+     * 載入基礎 entries（從現有 sitemap）
+     */
+    private loadBaseEntries;
+    /**
+     * 生成差異部分
+     */
+    private generateDiff;
+    /**
+     * 將 AsyncIterable 轉換為陣列
+     */
+    private toArray;
+}
+
+interface ProgressTrackerOptions {
+    storage: SitemapProgressStorage;
+    updateInterval?: number;
+}
+/**
+ * 進度追蹤器
+ * 追蹤 sitemap 生成進度
+ */
+declare class ProgressTracker {
+    private storage;
+    private updateInterval;
+    private currentProgress;
+    private updateTimer;
+    constructor(options: ProgressTrackerOptions);
+    /**
+     * 初始化進度追蹤
+     */
+    init(jobId: string, total: number): Promise<void>;
+    /**
+     * 更新進度
+     */
+    update(processed: number, status?: SitemapProgress['status']): Promise<void>;
+    /**
+     * 完成進度追蹤
+     */
+    complete(): Promise<void>;
+    /**
+     * 標記為失敗
+     */
+    fail(error: string): Promise<void>;
+    /**
+     * 刷新進度到儲存
+     */
+    private flush;
+    /**
+     * 停止更新計時器
+     */
+    private stop;
+    /**
+     * 獲取當前進度
+     */
+    getCurrentProgress(): SitemapProgress | null;
+}
+
+declare class SitemapIndex {
+    private options;
+    private entries;
+    constructor(options: SitemapStreamOptions);
+    add(entry: string | SitemapIndexEntry): this;
+    addAll(entries: (string | SitemapIndexEntry)[]): this;
+    toXML(): string;
+    private escape;
+}
+
+declare class SitemapStream {
+    private options;
+    private entries;
+    constructor(options: SitemapStreamOptions);
+    add(entry: string | SitemapEntry): this;
+    addAll(entries: (string | SitemapEntry)[]): this;
+    toXML(): string;
+    private renderUrl;
+    private hasImages;
+    private hasVideos;
+    private hasNews;
+    private hasAlternates;
+    private escape;
+}
+
+/**
+ * Interface representing basic structure needed to generate i18n entries.
+ * Partial of SitemapEntry because url is generated dynamically.
+ */
+type I18nSitemapEntryOptions = Omit<SitemapEntry, 'url' | 'alternates'>;
+/**
+ * Generate fully cross-referenced SitemapEntries for multiple locales.
+ *
+ * @param path The path relative to the locale prefix (e.g. '/docs/intro')
+ * @param locales List of supported locales (e.g. ['en', 'zh', 'jp'])
+ * @param baseUrl The domain root (e.g. 'https://gravito.dev'). IF provided, URLs will be absolute. If not, they remain relative paths but include the locale prefix.
+ * @param options Additional SitemapEntry options (lastmod, priority, etc.)
+ */
+declare function generateI18nEntries(path: string, locales: string[], baseUrl?: string, options?: I18nSitemapEntryOptions): SitemapEntry[];
+
+interface GenerateSitemapJobOptions {
+    generatorOptions: SitemapGeneratorOptions;
+    jobId: string;
+    progressTracker?: ProgressTracker;
+    shadowProcessor?: ShadowProcessor;
+    onProgress?: (progress: {
+        processed: number;
+        total: number;
+        percentage: number;
+    }) => void;
+    onComplete?: () => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Sitemap 生成背景任務
+ * 整合背景任務處理和進度追蹤
+ */
+declare class GenerateSitemapJob extends Job {
+    private options;
+    private generator;
+    private totalEntries;
+    private processedEntries;
+    constructor(options: GenerateSitemapJobOptions);
+    handle(): Promise<void>;
+    /**
+     * 計算總 URL 數
+     */
+    private calculateTotal;
+    /**
+     * 帶進度追蹤的生成
+     */
+    private generateWithProgress;
+}
+
+interface DynamicSitemapOptions extends SitemapStreamOptions {
+    path?: string | undefined;
+    providers: SitemapProvider[];
+    cacheSeconds?: number | undefined;
+    storage?: SitemapStorage | undefined;
+    lock?: SitemapLock | undefined;
+}
+interface StaticSitemapOptions extends SitemapStreamOptions {
+    outDir: string;
+    filename?: string | undefined;
+    providers: SitemapProvider[];
+    storage?: SitemapStorage | undefined;
+    incremental?: {
+        enabled: boolean;
+        changeTracker: ChangeTracker;
+        autoTrack?: boolean;
+    };
+    redirect?: {
+        enabled: boolean;
+        manager: RedirectManager;
+        strategy?: 'remove_old_add_new' | 'keep_relation' | 'update_url' | 'dual_mark';
+        followChains?: boolean;
+        maxChainLength?: number;
+    };
+    shadow?: {
+        enabled: boolean;
+        mode: 'atomic' | 'versioned';
+    };
+    progressStorage?: SitemapProgressStorage;
+}
+declare class OrbitSitemap {
+    private options;
+    private mode;
+    private constructor();
+    /**
+     * Create a dynamic sitemap configuration.
+     *
+     * @param options - The dynamic sitemap options.
+     * @returns An OrbitSitemap instance configured for dynamic generation.
+     */
+    static dynamic(options: DynamicSitemapOptions): OrbitSitemap;
+    /**
+     * Create a static sitemap configuration.
+     *
+     * @param options - The static sitemap options.
+     * @returns An OrbitSitemap instance configured for static generation.
+     */
+    static static(options: StaticSitemapOptions): OrbitSitemap;
+    /**
+     * Install the sitemap module into PlanetCore.
+     *
+     * @param core - The PlanetCore instance.
+     */
+    install(core: PlanetCore): void;
+    private installDynamic;
+    /**
+     * Generate the sitemap (static mode only).
+     *
+     * @returns A promise that resolves when generation is complete.
+     * @throws {Error} If called in dynamic mode.
+     */
+    generate(): Promise<void>;
+    /**
+     * Generate incremental sitemap updates (static mode only).
+     *
+     * @param since - Only include items modified since this date.
+     * @returns A promise that resolves when incremental generation is complete.
+     * @throws {Error} If called in dynamic mode, or if incremental generation is not enabled/configured.
+     */
+    generateIncremental(since?: Date): Promise<void>;
+    /**
+     * Generate sitemap asynchronously in the background (static mode only).
+     *
+     * @param options - Options for the async generation job.
+     * @returns A promise resolving to the job ID.
+     * @throws {Error} If called in dynamic mode.
+     */
+    generateAsync(options?: {
+        incremental?: boolean;
+        since?: Date;
+        onProgress?: (progress: {
+            processed: number;
+            total: number;
+            percentage: number;
+        }) => void;
+        onComplete?: () => void;
+        onError?: (error: Error) => void;
+    }): Promise<string>;
+    /**
+     * Install API endpoints for triggering and monitoring sitemap generation.
+     *
+     * @param core - The PlanetCore instance.
+     * @param basePath - The base path for the API endpoints (default: '/admin/sitemap').
+     */
+    installApiEndpoints(core: PlanetCore, basePath?: string): void;
+    /**
+     * Convert an AsyncIterable to an array.
+     */
+    private toArray;
+}
+
+interface RouteScannerOptions {
+    include?: string[] | undefined;
+    exclude?: string[] | undefined;
+    defaultChangefreq?: ChangeFreq | undefined;
+    defaultPriority?: number | undefined;
+}
+declare class RouteScanner implements SitemapProvider {
+    private router;
+    private options;
+    constructor(router: any, options?: RouteScannerOptions);
+    getEntries(): SitemapEntry[];
+    private extractRoutes;
+    private shouldInclude;
+}
+declare function routeScanner(router: any, options?: RouteScannerOptions): RouteScanner;
+
+interface AutoDetectOptions {
+    enabled: boolean;
+    timeout?: number;
+    maxConcurrent?: number;
+    cache?: boolean;
+    cacheTtl?: number;
+}
+interface DatabaseDetectOptions {
+    enabled: boolean;
+    table: string;
+    columns: {
+        from: string;
+        to: string;
+        type: string;
+    };
+    connection: any;
+}
+interface ConfigDetectOptions {
+    enabled: boolean;
+    path: string;
+    watch?: boolean;
+}
+interface RedirectDetectorOptions {
+    baseUrl: string;
+    autoDetect?: AutoDetectOptions;
+    database?: DatabaseDetectOptions;
+    config?: ConfigDetectOptions;
+}
+/**
+ * 轉址偵測器
+ * 支援多種偵測方式：自動偵測、資料庫、設定檔
+ */
+declare class RedirectDetector {
+    private options;
+    private cache;
+    constructor(options: RedirectDetectorOptions);
+    /**
+     * 偵測單一 URL 的轉址
+     */
+    detect(url: string): Promise<RedirectRule | null>;
+    /**
+     * 批次偵測轉址
+     */
+    detectBatch(urls: string[]): Promise<Map<string, RedirectRule | null>>;
+    /**
+     * 從資料庫偵測
+     */
+    private detectFromDatabase;
+    /**
+     * 從設定檔偵測
+     */
+    private detectFromConfig;
+    /**
+     * 自動偵測（透過 HTTP 請求）
+     */
+    private detectAuto;
+    /**
+     * 快取結果
+     */
+    private cacheResult;
+}
+
+type RedirectHandlingStrategy = 'remove_old_add_new' | 'keep_relation' | 'update_url' | 'dual_mark';
+interface RedirectHandlerOptions {
+    manager: RedirectManager;
+    strategy: RedirectHandlingStrategy;
+    followChains?: boolean;
+    maxChainLength?: number;
+}
+/**
+ * 轉址處理器
+ * 處理 sitemap entries 中的轉址
+ */
+declare class RedirectHandler {
+    private options;
+    constructor(options: RedirectHandlerOptions);
+    /**
+     * 處理 entries 中的轉址
+     */
+    processEntries(entries: SitemapEntry[]): Promise<SitemapEntry[]>;
+    /**
+     * 策略一：移除舊 URL，加入新 URL
+     */
+    private handleRemoveOldAddNew;
+    /**
+     * 策略二：保留關聯，使用 canonical link
+     */
+    private handleKeepRelation;
+    /**
+     * 策略三：僅更新 URL
+     */
+    private handleUpdateUrl;
+    /**
+     * 策略四：雙重標記
+     */
+    private handleDualMark;
+}
+
+interface MemoryRedirectManagerOptions {
+    maxRules?: number;
+}
+/**
+ * 記憶體轉址管理器實作
+ */
+declare class MemoryRedirectManager implements RedirectManager {
+    private rules;
+    private maxRules;
+    constructor(options?: MemoryRedirectManagerOptions);
+    register(redirect: RedirectRule): Promise<void>;
+    registerBatch(redirects: RedirectRule[]): Promise<void>;
+    get(from: string): Promise<RedirectRule | null>;
+    getAll(): Promise<RedirectRule[]>;
+    resolve(url: string, followChains?: boolean, maxChainLength?: number): Promise<string | null>;
+}
+interface RedisRedirectManagerOptions {
+    client: any;
+    keyPrefix?: string;
+    ttl?: number;
+}
+/**
+ * Redis 轉址管理器實作
+ */
+declare class RedisRedirectManager implements RedirectManager {
+    private client;
+    private keyPrefix;
+    private ttl;
+    constructor(options: RedisRedirectManagerOptions);
+    private getKey;
+    private getListKey;
+    register(redirect: RedirectRule): Promise<void>;
+    registerBatch(redirects: RedirectRule[]): Promise<void>;
+    get(from: string): Promise<RedirectRule | null>;
+    getAll(): Promise<RedirectRule[]>;
+    resolve(url: string, followChains?: boolean, maxChainLength?: number): Promise<string | null>;
+}
+
+declare class DiskSitemapStorage implements SitemapStorage {
+    private outDir;
+    private baseUrl;
+    constructor(outDir: string, baseUrl: string);
+    write(filename: string, content: string): Promise<void>;
+    read(filename: string): Promise<string | null>;
+    exists(filename: string): Promise<boolean>;
+    getUrl(filename: string): string;
+}
+
+interface GCPSitemapStorageOptions {
+    bucket: string;
+    prefix?: string;
+    baseUrl?: string;
+    shadow?: {
+        enabled: boolean;
+        mode: 'atomic' | 'versioned';
+    };
+    keyFilename?: string;
+    projectId?: string;
+}
+/**
+ * Google Cloud Storage 儲存實作
+ * 支援影子處理和版本化
+ */
+declare class GCPSitemapStorage implements SitemapStorage {
+    private bucket;
+    private prefix;
+    private baseUrl;
+    private shadowEnabled;
+    private shadowMode;
+    private storageClient;
+    private bucketInstance;
+    constructor(options: GCPSitemapStorageOptions);
+    private getStorageClient;
+    private getKey;
+    write(filename: string, content: string): Promise<void>;
+    read(filename: string): Promise<string | null>;
+    exists(filename: string): Promise<boolean>;
+    getUrl(filename: string): string;
+    writeShadow(filename: string, content: string, shadowId?: string): Promise<void>;
+    commitShadow(shadowId: string): Promise<void>;
+    listVersions(filename: string): Promise<string[]>;
+    switchVersion(filename: string, version: string): Promise<void>;
+}
+
+/**
+ * 記憶體進度儲存實作
+ * 適用於單一進程或開發環境
+ */
+declare class MemoryProgressStorage implements SitemapProgressStorage {
+    private storage;
+    get(jobId: string): Promise<SitemapProgress | null>;
+    set(jobId: string, progress: SitemapProgress): Promise<void>;
+    update(jobId: string, updates: Partial<SitemapProgress>): Promise<void>;
+    delete(jobId: string): Promise<void>;
+    list(limit?: number): Promise<SitemapProgress[]>;
+}
+
+declare class MemorySitemapStorage implements SitemapStorage {
+    private baseUrl;
+    private files;
+    constructor(baseUrl: string);
+    write(filename: string, content: string): Promise<void>;
+    read(filename: string): Promise<string | null>;
+    exists(filename: string): Promise<boolean>;
+    getUrl(filename: string): string;
+}
+
+interface RedisProgressStorageOptions {
+    client: any;
+    keyPrefix?: string;
+    ttl?: number;
+}
+/**
+ * Redis 進度儲存實作
+ * 適用於分散式環境或多進程
+ */
+declare class RedisProgressStorage implements SitemapProgressStorage {
+    private client;
+    private keyPrefix;
+    private ttl;
+    constructor(options: RedisProgressStorageOptions);
+    private getKey;
+    private getListKey;
+    get(jobId: string): Promise<SitemapProgress | null>;
+    set(jobId: string, progress: SitemapProgress): Promise<void>;
+    update(jobId: string, updates: Partial<SitemapProgress>): Promise<void>;
+    delete(jobId: string): Promise<void>;
+    list(limit?: number): Promise<SitemapProgress[]>;
+}
+
+interface S3SitemapStorageOptions {
+    bucket: string;
+    region?: string;
+    prefix?: string;
+    baseUrl?: string;
+    shadow?: {
+        enabled: boolean;
+        mode: 'atomic' | 'versioned';
+    };
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+    };
+}
+/**
+ * AWS S3 儲存實作
+ * 支援影子處理和版本化
+ */
+declare class S3SitemapStorage implements SitemapStorage {
+    private bucket;
+    private region?;
+    private prefix;
+    private baseUrl;
+    private shadowEnabled;
+    private shadowMode;
+    private s3Client;
+    constructor(options: S3SitemapStorageOptions);
+    private getS3Client;
+    private getKey;
+    write(filename: string, content: string): Promise<void>;
+    read(filename: string): Promise<string | null>;
+    exists(filename: string): Promise<boolean>;
+    getUrl(filename: string): string;
+    writeShadow(filename: string, content: string, shadowId?: string): Promise<void>;
+    commitShadow(shadowId: string): Promise<void>;
+    listVersions(filename: string): Promise<string[]>;
+    switchVersion(filename: string, version: string): Promise<void>;
+}
+
+export { type AlternateUrl, type ChangeFreq, type ChangeTracker, type ChangeType, DiffCalculator, DiskSitemapStorage, type DynamicSitemapOptions, GCPSitemapStorage, type GCPSitemapStorageOptions, GenerateSitemapJob, type GenerateSitemapJobOptions, type I18nSitemapEntryOptions, IncrementalGenerator, type IncrementalGeneratorOptions, MemoryChangeTracker, MemoryProgressStorage, MemoryRedirectManager, type MemoryRedirectManagerOptions, MemorySitemapStorage, OrbitSitemap, ProgressTracker, type ProgressTrackerOptions, RedirectDetector, type RedirectDetectorOptions, RedirectHandler, type RedirectHandlerOptions, type RedirectHandlingStrategy, type RedirectManager, type RedirectRule, RedisChangeTracker, RedisProgressStorage, type RedisProgressStorageOptions, RedisRedirectManager, type RedisRedirectManagerOptions, RouteScanner, type RouteScannerOptions, S3SitemapStorage, type S3SitemapStorageOptions, ShadowProcessor, type ShadowProcessorOptions, type SitemapCache, type SitemapChange, type SitemapEntry, SitemapGenerator, type SitemapGeneratorOptions, type SitemapImage, SitemapIndex, type SitemapIndexEntry, type SitemapLock, type SitemapNews, type SitemapProgress, type SitemapProgressStorage, type SitemapProvider, type SitemapStorage, SitemapStream, type SitemapStreamOptions, type SitemapVideo, type StaticSitemapOptions, generateI18nEntries, routeScanner };