/**
 * @fileoverview Service wrapping the Gutendex catalog API (gutendex.com/books/).
 * Provides search, single-book lookup, and popularity browse with retry, timeout,
 * and in-process response caching (1-hour TTL).
 * @module services/gutendex/gutendex-service
 */
import type { Context } from '@cyanheads/mcp-ts-core';
import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
import type { StorageService } from '@cyanheads/mcp-ts-core/storage';
import type { ServerConfig } from '../../config/server-config.js';
import { type Book, type SearchParams } from './types.js';
export declare class GutendexService {
    private readonly baseUrl;
    constructor(_config: AppConfig, _storage: StorageService, serverConfig: ServerConfig);
    /** Build a Gutendex query URL from search parameters. */
    private buildSearchUrl;
    /** Fetch and parse a raw Gutendex page, with cache. */
    private fetchPage;
    /** Search books by the given parameters. Returns normalized books + count + pagination. */
    searchBooks(params: SearchParams, ctx: Context): Promise<{
        books: Book[];
        totalCount: number;
        hasMore: boolean;
        page: number;
    }>;
    /**
     * Read one book from the local catalog mirror, or `null` when the mirror cannot
     * answer — not ready, does not hold the ID, or unreadable.
     *
     * A miss is deliberately indistinguishable from a cold mirror: both mean "ask the
     * upstream". The mirror is a daily snapshot, so a book published or revised since
     * the last harvest is legitimately absent, and treating that as `not_found` would
     * turn a staleness window into a wrong answer.
     *
     * A mirror fault is downgraded to a miss rather than propagated. The mirror is an
     * availability optimization layered under a working live path; a corrupt database
     * or a missing file should cost latency, never correctness.
     */
    private mirrorBook;
    /**
     * Fetch a single book by Gutenberg ID. Serves from the local mirror when it holds
     * the record, and falls through to the live catalog otherwise. Throws not_found if
     * the live lookup 404s.
     */
    getBook(id: number, ctx: Context): Promise<Book>;
}
export declare function initGutendexService(config: AppConfig, storage: StorageService, serverConfig: ServerConfig): void;
export declare function getGutendexService(): GutendexService;
//# sourceMappingURL=gutendex-service.d.ts.map