/**
 * @fileoverview Socrata SODA API and Discovery API client.
 * Handles dataset discovery, schema inspection, SoQL query execution, and portal listing.
 * @module services/socrata/socrata-service
 */
import type { Context } from '@cyanheads/mcp-ts-core';
import type { DatasetMetadata, DiscoveryResult, FindDatasetsOptions, PortalEntry, QueryDatasetOptions, QueryResult } from './types.js';
/** Reset the module-scope portal-count cache. Test-only. */
export declare function resetPortalCountCache(): void;
export declare class SocrataService {
    /**
     * Set to `true` once Socrata rejects the configured app token (403 invalid
     * token). While set, {@link buildHeaders} omits `X-App-Token`, so every later
     * request — and the immediate keyless retry in {@link fetchJson} — runs keyless.
     * Process-lifetime state, cleared by a restart with a corrected token. An
     * instance field (not module scope) so the singleton owns it and each
     * `new SocrataService()` in tests starts with a clean slate.
     */
    private appTokenDisabled;
    /** Build the default request headers, adding the app token unless it's disabled. */
    private buildHeaders;
    /** Fetch JSON from a URL with retry, timeout, and SODA error detection. */
    private fetchJson;
    /**
     * Search for datasets across all portals or scoped to one domain.
     * Uses the Socrata Discovery API.
     */
    findDatasets(opts: FindDatasetsOptions, ctx: Context): Promise<{
        results: DiscoveryResult[];
        totalCount: number;
    }>;
    /** Fetch full metadata and column schema for a dataset by ID. */
    getDataset(domain: string, datasetId: string, ctx: Context): Promise<DatasetMetadata>;
    /**
     * Assemble the SoQL query-string params shared by the single-page
     * ({@link queryDataset}) and paginated ({@link streamDatasetRows}) fetch paths.
     * `$limit`/`$offset` are passed explicitly so each caller controls paging.
     */
    private buildQueryParams;
    /** Execute a SoQL query against a dataset. */
    queryDataset(opts: QueryDatasetOptions, ctx: Context): Promise<QueryResult>;
    /**
     * Stream a dataset's matching rows across paginated SODA calls, bounded by a
     * hard `maxRows` safety cap. Walks `$offset` in pages of {@link SODA_PAGE_MAX}
     * until the upstream is exhausted (a short page) or the cap is reached.
     *
     * Distinct from {@link queryDataset}, whose single call bounds the inline
     * response by the caller's `limit`: this drains the wider matching set (up to
     * the cap) so a bounded copy can be staged onto a DataCanvas for SQL — the
     * canvas is a bounded subset, never literally the full result set when the
     * match exceeds the cap.
     */
    streamDatasetRows(opts: QueryDatasetOptions, maxRows: number, ctx: Context): AsyncGenerator<Record<string, unknown>>;
    /**
     * List the curated well-known Socrata portals with live dataset counts.
     * Counts come from the TTL-cached Discovery catalog lookups; a portal whose
     * count has never resolved carries `datasetCount: null` rather than failing
     * the whole listing.
     */
    listPortals(ctx: Context): Promise<PortalEntry[]>;
    /**
     * Warm the portal-count cache: one `limit=0` Discovery catalog query per
     * known domain (`resultSetSize` is the count of dataset-type assets).
     * Per-domain failures are logged and skipped — last-known-good values are
     * retained. A refresh that resolves nothing schedules a short retry instead
     * of holding an empty cache for the full TTL.
     */
    private refreshPortalCounts;
    /** Count dataset-type assets on one portal via the Discovery catalog. */
    private fetchPortalDatasetCount;
}
export declare function initSocrataService(): void;
export declare function getSocrataService(): SocrataService;
//# sourceMappingURL=socrata-service.d.ts.map