/**
 * Core types for the content source plugin system.
 *
 * This module defines the interfaces that all content sources must implement,
 * enabling a plugin architecture where different source types (web, GitHub,
 * local markdown) can be added without modifying core code.
 */
import type { Chunk } from '../chunking/types.js';
/**
 * Shared context passed to all content sources.
 * Contains global settings that apply regardless of source type.
 */
export interface SourceContext {
    /** Site identifier (e.g., "docs", "marketing") */
    site: string;
    /** Site base URL */
    siteUrl: string;
    /** Default guide name (can be overridden per-source) */
    guide?: string;
    /** Default version (can be overridden per-source) */
    version?: string;
    /** Whether this is the latest/current version */
    isLatest?: boolean;
    /** Show detailed progress */
    verbose?: boolean;
    /** Maximum pages/files to process (for preview runs) */
    maxPages?: number;
    /** API credentials for LLM/vision processing */
    credentials?: {
        accountId: string;
        apiToken: string;
    };
}
/**
 * Processing statistics from a content source.
 */
export interface SourceStats {
    /** Number of files/pages successfully processed */
    filesProcessed: number;
    /** Number of files/pages skipped (errors, empty, filtered) */
    filesSkipped: number;
    /** Total chunks generated */
    chunksGenerated: number;
    /** Number of images processed (if image processing enabled) */
    imagesProcessed?: number;
}
/**
 * Result from processing a content source.
 */
export interface SourceResult {
    /** Generated chunks ready for embedding */
    chunks: Chunk[];
    /** Processing statistics */
    stats: SourceStats;
}
/**
 * Base configuration shared by all source types.
 * Extend this interface for source-specific configuration.
 */
export interface BaseSourceConfig {
    /** Source type discriminator (e.g., 'web', 'github', 'markdown') */
    type: string;
    /** Custom category mappings (path pattern -> category name) */
    categories?: Record<string, string>;
    /** Guide name override for this source */
    guide?: string;
}
/**
 * Core interface that all content sources must implement.
 *
 * This enables the plugin system - each source type provides its own
 * implementation of fetching, processing, and chunking content.
 *
 * @typeParam TConfig - Source-specific configuration type extending BaseSourceConfig
 *
 * @example
 * ```typescript
 * class WebSource implements ContentSource<WebSourceConfig> {
 *   readonly type = 'web';
 *   readonly name = 'Web (Sitemap)';
 *
 *   async process(config: WebSourceConfig, context: SourceContext): Promise<SourceResult> {
 *     // Fetch pages from sitemap, extract content, create chunks
 *   }
 *
 *   validateConfig(config: unknown): WebSourceConfig {
 *     return WebSourceConfigSchema.parse(config);
 *   }
 * }
 * ```
 */
export interface ContentSource<TConfig extends BaseSourceConfig = BaseSourceConfig> {
    /**
     * Unique identifier for this source type.
     * Used for registration and config matching (e.g., 'web', 'github', 'markdown').
     */
    readonly type: string;
    /**
     * Human-readable name for logging and error messages.
     */
    readonly name: string;
    /**
     * Process the source and return chunks ready for embedding.
     *
     * All fetching, content extraction, and chunking happens within this method.
     * The implementation should handle errors gracefully and report them in stats.
     *
     * @param config - Validated source-specific configuration
     * @param context - Shared processing context (credentials, options, etc.)
     * @returns Chunks and processing statistics
     */
    process(config: TConfig, context: SourceContext): Promise<SourceResult>;
    /**
     * Validate and transform raw configuration into typed configuration.
     *
     * Should throw descriptive errors for invalid configuration.
     * Typically implemented using Zod schema validation.
     *
     * @param config - Raw configuration object from config file or CLI
     * @returns Validated and typed configuration
     * @throws Error if configuration is invalid
     */
    validateConfig(config: unknown): TConfig;
}
/**
 * Factory function type for creating content source instances.
 */
export type SourceFactory<T extends BaseSourceConfig = BaseSourceConfig> = () => ContentSource<T>;
//# sourceMappingURL=types.d.ts.map