import type { FrontMcpLogger } from '../../common';
import type { SkillContent } from '../../common/interfaces';
import type { SkillMetadata } from '../../common/metadata';
import type { SkillStorageProvider, SkillSearchOptions, SkillSearchResult, SkillLoadResult, SkillListOptions, SkillListResult } from '../skill-storage.interface';
import type { SkillSyncState, SkillSyncStateStore, SyncResult } from '../sync/sync-state.interface';
/**
 * Operating mode for external skill providers.
 *
 * - 'read-only': Skills are fetched from external storage, no local writes
 * - 'persistent': Local skills are synced to external storage with SHA-based change detection
 */
export type ExternalSkillMode = 'read-only' | 'persistent';
/**
 * Options for creating an external skill provider.
 */
export interface ExternalSkillProviderOptions {
    /**
     * Operating mode for the provider.
     * @see ExternalSkillMode
     */
    mode: ExternalSkillMode;
    /**
     * Store for persisting sync state.
     * Required for persistent mode, optional for read-only.
     */
    syncStateStore?: SkillSyncStateStore;
    /**
     * Logger instance for diagnostic output.
     */
    logger?: FrontMcpLogger;
    /**
     * Default number of search results.
     * @default 10
     */
    defaultTopK?: number;
    /**
     * Default minimum similarity threshold.
     * @default 0.1
     */
    defaultMinScore?: number;
}
/**
 * Options for skill search in external storage.
 */
export interface ExternalSkillSearchOptions extends SkillSearchOptions {
    /**
     * Include metadata like embeddings in results.
     */
    includeMetadata?: boolean;
}
/**
 * Options for listing skills from external storage.
 */
export interface ExternalSkillListOptions extends SkillListOptions {
    /**
     * Cursor for pagination (provider-specific).
     */
    cursor?: string;
}
/**
 * Abstract base class for external skill storage providers.
 *
 * Provides two operating modes:
 *
 * **Read-Only Mode:**
 * - All search/load operations fetch from external storage
 * - No local persistence or modification
 * - Use case: Pull skills from a shared skill repository
 *
 * **Persistent Mode:**
 * - Local skills are synced to external storage
 * - SHA-based change detection minimizes writes
 * - Tracks sync state to detect added/updated/removed skills
 * - Use case: Publish local skills to external vector DB
 *
 * @example Implementing a REST API provider
 * ```typescript
 * class RestSkillProvider extends ExternalSkillProviderBase {
 *   constructor(private apiUrl: string, options: ExternalSkillProviderOptions) {
 *     super(options);
 *   }
 *
 *   protected async fetchSkill(skillId: string): Promise<SkillContent | null> {
 *     const response = await fetch(`${this.apiUrl}/skills/${skillId}`);
 *     if (!response.ok) return null;
 *     return response.json();
 *   }
 *
 *   // ... implement other abstract methods
 * }
 * ```
 */
export declare abstract class ExternalSkillProviderBase implements SkillStorageProvider {
    readonly type: "external";
    /** Operating mode */
    protected readonly mode: ExternalSkillMode;
    /** Current sync state (loaded from store on init) */
    protected syncState: SkillSyncState | null;
    /** Store for persisting sync state */
    protected readonly syncStateStore?: SkillSyncStateStore;
    /** Logger instance */
    protected readonly logger?: FrontMcpLogger;
    /** Default search result count */
    protected readonly defaultTopK: number;
    /** Default minimum similarity threshold */
    protected readonly defaultMinScore: number;
    /** Whether the provider has been initialized */
    private initialized;
    constructor(options: ExternalSkillProviderOptions);
    /**
     * Fetch a single skill from external storage.
     *
     * @param skillId - The skill identifier
     * @returns The skill content or null if not found
     */
    protected abstract fetchSkill(skillId: string): Promise<SkillContent | null>;
    /**
     * Fetch multiple skills from external storage.
     *
     * @param options - List options (pagination, filtering)
     * @returns Array of skill content
     */
    protected abstract fetchSkills(options?: ExternalSkillListOptions): Promise<SkillContent[]>;
    /**
     * Search for skills in external storage.
     *
     * @param query - Search query string
     * @param options - Search options
     * @returns Array of search results with scores
     */
    protected abstract searchExternal(query: string, options?: ExternalSkillSearchOptions): Promise<SkillSearchResult[]>;
    /**
     * Add or update a skill in external storage.
     *
     * @param skill - The skill content to upsert
     */
    protected abstract upsertSkill(skill: SkillContent): Promise<void>;
    /**
     * Delete a skill from external storage.
     *
     * @param skillId - The skill identifier to delete
     */
    protected abstract deleteSkill(skillId: string): Promise<void>;
    /**
     * Get the total count of skills in external storage.
     *
     * @param options - Filter options
     */
    protected abstract countExternal(options?: {
        tags?: string[];
        includeHidden?: boolean;
    }): Promise<number>;
    /**
     * Check if a skill exists in external storage.
     *
     * @param skillId - The skill identifier
     */
    protected abstract existsExternal(skillId: string): Promise<boolean>;
    /**
     * Initialize the provider.
     * Loads sync state for persistent mode.
     */
    initialize(): Promise<void>;
    /**
     * Search for skills.
     * Delegates to the abstract searchExternal method.
     */
    search(query: string, options?: SkillSearchOptions): Promise<SkillSearchResult[]>;
    /**
     * Load a skill by ID.
     * Fetches from external storage and constructs a SkillLoadResult.
     */
    load(skillId: string): Promise<SkillLoadResult | null>;
    /**
     * List skills with pagination.
     */
    list(options?: SkillListOptions): Promise<SkillListResult>;
    /**
     * Check if a skill exists.
     */
    exists(skillId: string): Promise<boolean>;
    /**
     * Count skills.
     */
    count(options?: {
        tags?: string[];
        includeHidden?: boolean;
    }): Promise<number>;
    /**
     * Dispose of resources.
     */
    dispose(): Promise<void>;
    /**
     * Sync local skills to external storage.
     *
     * This method:
     * 1. Loads previous sync state
     * 2. Computes SHA-256 hash for each local skill
     * 3. Compares hashes to detect changes
     * 4. Upserts new/changed skills
     * 5. Deletes skills no longer present locally
     * 6. Saves updated sync state
     *
     * @param localSkills - Array of local skill content to sync
     * @returns Sync result with added/updated/unchanged/removed counts
     * @throws Error if called in read-only mode
     *
     * @example
     * ```typescript
     * const result = await provider.syncSkills(localSkills);
     * console.log(`Synced: ${result.added.length} added, ${result.updated.length} updated`);
     * ```
     */
    syncSkills(localSkills: SkillContent[]): Promise<SyncResult>;
    /**
     * Get the current sync state.
     * Returns null if in read-only mode or never synced.
     * Returns a deep copy to prevent external mutation.
     */
    getSyncState(): SkillSyncState | null;
    /**
     * Clear the sync state.
     * Forces a full re-sync on next syncSkills call.
     */
    clearSyncState(): Promise<void>;
    /**
     * Check if the provider is operating in read-only mode.
     */
    isReadOnly(): boolean;
    /**
     * Check if the provider is operating in persistent mode.
     */
    isPersistent(): boolean;
    /**
     * Convert SkillContent to SkillMetadata.
     * Override in subclasses if additional metadata is available.
     */
    protected skillToMetadata(skill: SkillContent): SkillMetadata;
}
//# sourceMappingURL=external-skill.provider.d.ts.map