open-alex-wrapper 0.1.0

package/dist/client-CLRZTPFv.d.cts

@@ -0,0 +1,1266 @@
+/**
+ * Optional response caching.
+ *
+ * A tiny dependency-free LRU with per-entry TTL, plus a {@link CacheStore}
+ * interface so callers can plug in Redis, a file cache, etc. Caching is
+ * opt-in (`cache: true` or a custom store) and only ever applies to GETs.
+ */
+interface CacheStore {
+    get(key: string): unknown | undefined | Promise<unknown | undefined>;
+    set(key: string, value: unknown, ttlMs: number): void | Promise<void>;
+    delete?(key: string): void | Promise<void>;
+    clear?(): void | Promise<void>;
+}
+/** In-memory LRU cache with TTL eviction. */
+declare class LRUCache implements CacheStore {
+    private readonly maxEntries;
+    private readonly map;
+    constructor(maxEntries?: number);
+    get(key: string): unknown | undefined;
+    set(key: string, value: unknown, ttlMs: number): void;
+    delete(key: string): void;
+    clear(): void;
+    get size(): number;
+}
+
+/**
+ * Budget-aware adaptive throttle.
+ *
+ * Paces requests to a target rate (default 10/s) and *automatically slows down
+ * as the daily budget runs low* — so a long extraction glides to the limit
+ * instead of slamming into a 429/402. A `minRemainingUsd` floor hard-stops
+ * before the budget is fully exhausted.
+ *
+ * The clock is injectable so pacing is deterministically testable.
+ */
+interface ResolvedThrottle {
+    /** Target requests/second (spacing = 1000 / rps). */
+    maxRequestsPerSecond: number;
+    /** Throw {@link BudgetExceededError} once remaining budget drops below this. */
+    minRemainingUsd?: number;
+}
+interface ThrottleState {
+    remainingUsd: number;
+    dailyLimitUsd: number;
+}
+interface Clock {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+declare const REAL_CLOCK: Clock;
+declare class Throttle {
+    private readonly opts;
+    private readonly clock;
+    private nextAllowedAt;
+    constructor(opts: ResolvedThrottle, clock?: Clock);
+    /**
+     * Wait until the next request is allowed to start. Enforces the target rate
+     * and multiplies spacing when the remaining budget fraction is low.
+     */
+    gate(state: ThrottleState): Promise<void>;
+}
+
+/**
+ * Client configuration and default resolution.
+ */
+
+interface ThrottleOptions {
+    /** Target requests/second. Default 10. */
+    maxRequestsPerSecond?: number;
+    /** Hard-stop (throws BudgetExceededError) once remaining USD drops below this. */
+    minRemainingUsd?: number;
+}
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+interface RetryPolicy {
+    /** Max retry attempts after the first try (default 5). */
+    maxRetries: number;
+    /** Base backoff delay in ms (default 500). */
+    baseDelayMs: number;
+    /** Ceiling on any single backoff delay (default 20_000). */
+    maxDelayMs: number;
+    /** Status codes that trigger a retry (default 429, 500, 502, 503, 504). */
+    retryOnStatus: number[];
+}
+interface OpenAlexConfig {
+    /**
+     * OpenAlex API key. Required by OpenAlex for all requests since Feb 2026.
+     * Falls back to `process.env.OPENALEX_API_KEY`.
+     */
+    apiKey?: string;
+    /**
+     * Contact email for the "polite pool". Sent as `mailto` and in User-Agent.
+     * Falls back to `process.env.OPENALEX_MAILTO`.
+     */
+    mailto?: string;
+    /** API base URL. Default `https://api.openalex.org`. */
+    baseUrl?: string;
+    /** Extra User-Agent identifier for your app. */
+    userAgent?: string;
+    /** Per-request timeout in ms. Default 60_000. */
+    timeoutMs?: number;
+    /** Retry/backoff behaviour. */
+    retry?: Partial<RetryPolicy>;
+    /** Max concurrent in-flight requests. Default 8. */
+    concurrency?: number;
+    /**
+     * Soft daily budget in USD. When set, any call (or estimated extraction)
+     * that would cross it throws `BudgetExceededError` *before* spending.
+     */
+    dailyBudgetUsd?: number;
+    /** Called when spend crosses 80% / 100% of `dailyBudgetUsd`. */
+    onBudgetWarning?: (info: {
+        spentUsd: number;
+        limitUsd: number;
+        ratio: number;
+    }) => void;
+    /** `true` for the built-in LRU, or a custom {@link CacheStore}. GET-only. */
+    cache?: boolean | CacheStore;
+    /** Cache TTL in ms. Default 300_000 (5 min). */
+    cacheTtlMs?: number;
+    /**
+     * Budget-aware adaptive throttle. `true` = 10 req/s with auto-slowdown near
+     * the daily budget; or fine-tune with {@link ThrottleOptions}.
+     */
+    throttle?: boolean | ThrottleOptions;
+    /** Inject a custom fetch (used for testing / proxies). Default global fetch. */
+    fetch?: FetchLike;
+    /** Optional logger. Default: no-op. */
+    logger?: Logger;
+}
+interface ResolvedConfig {
+    apiKey?: string;
+    mailto?: string;
+    baseUrl: string;
+    userAgent: string;
+    timeoutMs: number;
+    retry: RetryPolicy;
+    concurrency: number;
+    dailyBudgetUsd?: number;
+    onBudgetWarning?: (info: {
+        spentUsd: number;
+        limitUsd: number;
+        ratio: number;
+    }) => void;
+    cache?: CacheStore;
+    cacheTtlMs: number;
+    throttle?: ResolvedThrottle;
+    fetch: FetchLike;
+    logger: Logger;
+}
+declare function resolveConfig(config?: OpenAlexConfig): ResolvedConfig;
+
+/**
+ * Cost & budget awareness.
+ *
+ * OpenAlex moved to usage-based pricing in Feb 2026. This module models that
+ * pricing so the SDK can (a) *estimate the dollar cost of an extraction before
+ * you run it* and (b) *track live, authoritative spend* from response headers.
+ *
+ * Prices (USD), per the OpenAlex pricing announcement:
+ *   - single entity lookup .......... $0        (unlimited)
+ *   - list / filter ................. $0.0001 / call   (1 credit)
+ *   - search ........................ $0.001  / call
+ *   - PDF / XML full-text download .. $0.01   / call
+ *
+ * Free daily allowance: $1.00/day with an API key, $0.10/day without one.
+ *
+ * OpenAlex reports usage on every response via `x-ratelimit-*` headers
+ * (confirmed against a live response):
+ *   x-ratelimit-cost-usd            cost of this request
+ *   x-ratelimit-remaining-usd       USD left in today's budget
+ *   x-ratelimit-limit-usd           today's USD budget
+ *   x-ratelimit-credits-used        credits this request cost
+ *   x-ratelimit-remaining           credits left today
+ *   x-ratelimit-limit               daily credit limit
+ *   x-ratelimit-prepaid-remaining-usd  prepaid balance (beyond the free tier)
+ *   x-ratelimit-reset               seconds until the budget resets
+ * {@link UsageTracker} prefers these authoritative values and falls back to
+ * the pricing model above when headers are absent.
+ */
+type RequestType = 'get' | 'list' | 'search' | 'download' | 'autocomplete';
+/** USD price per API call, keyed by request type (fallback when no headers). */
+declare const PRICING_USD: Record<RequestType, number>;
+declare const FREE_DAILY_USD_WITH_KEY = 1;
+declare const FREE_DAILY_USD_WITHOUT_KEY = 0.1;
+/** Documented free-tier daily caps (informational). */
+declare const FREE_TIER_LIMITS: {
+    readonly singleLookupCalls: number;
+    readonly listCalls: 10000;
+    readonly listResults: 1000000;
+    readonly searchCalls: 1000;
+    readonly searchResults: 100000;
+    readonly downloadCalls: 100;
+};
+/** Basic (page-number) paging can only reach the first 10,000 results. */
+declare const BASIC_PAGING_MAX_RESULTS = 10000;
+/** Estimated cost of a bulk extraction, produced *before* running it. */
+interface CostEstimate {
+    requestType: RequestType;
+    /** `meta.count` — total results matching the query. */
+    matchingResults: number;
+    /** How many of those you can actually page through with this strategy. */
+    fetchableResults: number;
+    perPage: number;
+    /** Page-fetch calls needed to walk `fetchableResults`. */
+    pageCalls: number;
+    /** USD for the page fetches. */
+    pagesCostUsd: number;
+    /** The single cheap count probe already spent to produce this estimate. */
+    probeCostUsd: number;
+    /** `pagesCostUsd + probeCostUsd`. */
+    totalCostUsd: number;
+    /** True when basic paging clipped the result set at 10k. */
+    cappedByBasicPaging: boolean;
+    note?: string;
+}
+interface EstimateInput {
+    count: number;
+    requestType: RequestType;
+    perPage?: number;
+    strategy?: 'basic' | 'cursor';
+}
+/** Pure cost math: given a result `count`, project the extraction cost. */
+declare function estimateExtractionCost(input: EstimateInput): CostEstimate;
+/** OpenAlex accepts per_page in [1, 200]. */
+declare function clampPerPage(n: number): number;
+interface UsageByType {
+    calls: number;
+    results: number;
+    estimatedCostUsd: number;
+}
+interface UsageSnapshot {
+    totalCalls: number;
+    /** Spend estimated from the pricing model. */
+    estimatedSpentUsd: number;
+    /** Authoritative spend today (limit − remaining), from headers, if seen. */
+    reportedSpentUsd: number | null;
+    /** Authoritative remaining budget today, from headers, if seen. */
+    reportedRemainingUsd: number | null;
+    /** Prepaid balance beyond the free tier, from headers, if seen. */
+    prepaidRemainingUsd: number | null;
+    /** Credits remaining today, from headers, if seen. */
+    creditsRemaining: number | null;
+    /** Seconds until the daily budget resets, from headers, if seen. */
+    resetSeconds: number | null;
+    /** Cost of the most recent request (USD), from headers, if seen. */
+    lastRequestCostUsd: number | null;
+    dailyLimitUsd: number;
+    /** Best available spend = reported, else estimated. */
+    spentUsd: number;
+    /** Best available remaining = reported, else limit − spent. */
+    remainingUsd: number;
+    byType: Record<RequestType, UsageByType>;
+    hasApiKey: boolean;
+}
+type Headerish = Headers | Map<string, string> | Record<string, string | string[] | undefined> | undefined;
+interface ParsedUsageHeaders {
+    costUsd?: number;
+    costRequiredUsd?: number;
+    remainingUsd?: number;
+    limitUsd?: number;
+    prepaidRemainingUsd?: number;
+    creditsUsed?: number;
+    creditsRemaining?: number;
+    creditsLimit?: number;
+    resetSeconds?: number;
+    raw: Record<string, string>;
+}
+/** Extract OpenAlex `x-ratelimit-*` usage headers into structured numbers. */
+declare function parseUsageHeaders(headers: Headerish): ParsedUsageHeaders;
+/**
+ * Accumulates spend across a client session.
+ *
+ * When OpenAlex sends `x-ratelimit-*` headers, the tracker reports authoritative
+ * spend/remaining/limit straight from them; otherwise it falls back to the
+ * pricing model.
+ */
+declare class UsageTracker {
+    private readonly hasApiKey;
+    private readonly dailyBudgetUsd?;
+    private byType;
+    private estimatedSpentUsd;
+    private reportedRemainingUsd;
+    private reportedLimitUsd;
+    private prepaidRemainingUsd;
+    private creditsRemaining;
+    private resetSeconds;
+    private lastRequestCostUsd;
+    private lastRawUsageHeaders;
+    constructor(hasApiKey: boolean, dailyBudgetUsd?: number | undefined);
+    /** The daily allowance in effect: OpenAlex-reported, else soft cap, else free tier. */
+    get dailyLimitUsd(): number;
+    /** Authoritative spend today if headers seen (limit − remaining), else estimate. */
+    get spentUsd(): number;
+    get remainingUsd(): number;
+    /** Record one completed request. Called by the HTTP layer. */
+    record(type: RequestType, opts?: {
+        results?: number;
+        headers?: Headerish;
+    }): void;
+    /**
+     * Throw {@link BudgetExceededError} if spending `additionalUsd` more would
+     * cross the soft cap. Only enforced when `dailyBudgetUsd` was configured.
+     */
+    assertWithinBudget(additionalUsd: number): void;
+    /** Immutable point-in-time view of usage. */
+    snapshot(): UsageSnapshot;
+    /** The last set of raw `x-ratelimit-*` headers OpenAlex sent (for debugging). */
+    get lastUsageHeaders(): Record<string, string>;
+    /** Human-readable multi-line budget report. */
+    report(): string;
+    reset(): void;
+}
+
+/**
+ * Low-level HTTP transport.
+ *
+ * Responsibilities:
+ *   - build request URLs (api_key + mailto injection, safe encoding)
+ *   - bound concurrency with a {@link Semaphore}
+ *   - retry with exponential backoff + jitter, honouring `Retry-After`
+ *   - per-request timeout via `AbortController`
+ *   - optional GET response caching
+ *   - record spend/usage into the {@link UsageTracker}
+ *   - normalize failures into the typed error hierarchy
+ */
+
+interface RequestOptions {
+    /** Path after the base URL, e.g. `works` or `works/W123`. Not encoded by caller. */
+    path: string;
+    /** Already-serialized OpenAlex query params (correct param names). */
+    params?: Record<string, string | undefined>;
+    /** Cost classification for budgeting. */
+    requestType: RequestType;
+    /** Bypass the response cache for this call. */
+    noCache?: boolean;
+    /** Extra fetch signal to compose with the internal timeout signal. */
+    signal?: AbortSignal;
+}
+interface HttpResponse<T> {
+    data: T;
+    status: number;
+    headers: Headers;
+    url: string;
+    cached: boolean;
+}
+declare class HttpClient {
+    readonly config: ResolvedConfig;
+    readonly usage: UsageTracker;
+    private readonly semaphore;
+    private readonly firedWarnings;
+    private readonly throttle?;
+    constructor(config: ResolvedConfig, usage: UsageTracker);
+    private gateThrottle;
+    /** Build the full request URL plus a redacted variant (api_key hidden). */
+    buildUrl(path: string, params?: Record<string, string | undefined>): {
+        url: string;
+        redacted: string;
+    };
+    /** Cache key excludes api_key so a shared cache isn't keyed to a secret. */
+    private cacheKey;
+    request<T>(opts: RequestOptions): Promise<HttpResponse<T>>;
+    private fetchWithRetry;
+    /** Shared GET-with-retry core: returns the ok `Response` or throws typed. */
+    private sendWithRetry;
+    /** Append api_key + mailto to any absolute URL (for the content host, etc.). */
+    authorizeUrl(rawUrl: string): {
+        url: string;
+        redacted: string;
+    };
+    /**
+     * Download a binary resource (e.g. a full-text PDF/XML from the content host).
+     * Budget-asserted and usage-recorded like any other request.
+     */
+    download(opts: {
+        url: string;
+        redacted?: string;
+        requestType: RequestType;
+        dest?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        bytes?: Uint8Array;
+        path?: string;
+        status: number;
+        headers: Headers;
+        contentType?: string;
+    }>;
+    private shouldRetry;
+    private backoff;
+    private maybeWarnBudget;
+}
+
+/**
+ * Shared response shapes returned by OpenAlex list/group endpoints.
+ *
+ * Entity interfaces (see `./entities`) are intentionally "open" (they carry an
+ * index signature) so that new fields added by OpenAlex never break typing —
+ * the raw payload is always reachable.
+ */
+/** The `meta` block attached to every list response. */
+interface Meta {
+    count: number;
+    db_response_time_ms: number;
+    page: number | null;
+    per_page: number;
+    /** Present only when cursor paging is active. `null` marks the last page. */
+    next_cursor?: string | null;
+    /** Present only when `groupBy` is active. */
+    groups_count?: number | null;
+    [key: string]: unknown;
+}
+/** A paged list response: `{ meta, results }` (+ optional `group_by`). */
+interface ListResult<T> {
+    meta: Meta;
+    results: T[];
+    group_by?: GroupResult[];
+}
+/** One bucket from a `group_by` aggregation. */
+interface GroupResult {
+    key: string;
+    key_display_name: string;
+    count: number;
+}
+/** Response from any `group_by` query: `{ meta, group_by }`. */
+interface GroupByResult {
+    meta: Meta;
+    group_by: GroupResult[];
+}
+/** One suggestion from an autocomplete endpoint. */
+interface AutocompleteResult {
+    id: string;
+    display_name: string;
+    hint?: string;
+    cited_by_count?: number;
+    works_count?: number;
+    entity_type?: string;
+    external_id?: string | null;
+    [key: string]: unknown;
+}
+/** The eight queryable OpenAlex entity types. */
+type EntityType = 'works' | 'authors' | 'sources' | 'institutions' | 'topics' | 'keywords' | 'publishers' | 'funders';
+/** Anything with an OpenAlex `id`; the common shape every entity shares. */
+interface OpenAlexEntity {
+    id: string;
+    display_name?: string;
+    [key: string]: unknown;
+}
+
+/**
+ * The narrow interface a QueryBuilder / paginator needs to execute requests,
+ * without depending on the concrete client. `EntityEndpoint` implements it.
+ */
+
+interface FetchListOptions {
+    requestType?: RequestType;
+    noCache?: boolean;
+    signal?: AbortSignal;
+}
+interface EntityRunner<T> {
+    readonly entityType: EntityType;
+    readonly logger: Logger;
+    /** Default concurrency to use for parallel paging when the caller doesn't specify. */
+    readonly defaultConcurrency: number;
+    fetchList(params: Record<string, string | undefined>, opts?: FetchListOptions): Promise<ListResult<T>>;
+}
+
+/**
+ * Resumable extraction checkpoints.
+ *
+ * A long cursor-paged extraction can persist its position after every page, so
+ * if it crashes, hits a rate limit, or you Ctrl-C it, the next run resumes from
+ * the last saved cursor instead of starting over — which also means you never
+ * re-pay for pages you already fetched.
+ */
+interface CheckpointState {
+    /** The next cursor to fetch (`null` once the extraction has finished). */
+    cursor: string | null;
+    /** How many items had been emitted when this state was saved. */
+    emitted: number;
+}
+interface Checkpoint {
+    load(): CheckpointState | undefined;
+    save(state: CheckpointState): void;
+    clear(): void;
+}
+/** A file-backed {@link Checkpoint} (JSON on disk, synchronous). */
+declare class FileCheckpoint implements Checkpoint {
+    private readonly path;
+    constructor(path: string);
+    load(): CheckpointState | undefined;
+    save(state: CheckpointState): void;
+    clear(): void;
+}
+/** An in-memory {@link Checkpoint} (useful for tests or custom persistence). */
+declare class MemoryCheckpoint implements Checkpoint {
+    private state;
+    load(): CheckpointState | undefined;
+    save(state: CheckpointState): void;
+    clear(): void;
+}
+
+/**
+ * Pagination strategies as async generators.
+ *
+ *   - cursor paging  → unlimited depth, sequential (the safe default for `.all()`)
+ *   - basic paging   → first 10k results, sequential or parallel
+ *
+ * Parallel basic paging fires every page request up front; the HTTP layer's
+ * semaphore caps how many are actually in flight, and pages are yielded in
+ * order. It's the fast path for the very common "≤10k results" case.
+ */
+
+interface ProgressInfo {
+    /** Items emitted so far (cumulative, includes any resumed count). */
+    emitted: number;
+    /** Pages fetched so far in this run. */
+    page: number;
+    /** Total matching results (`meta.count`), when known. */
+    total: number | null;
+}
+interface StreamOptions {
+    /** Results per page (1–200). Default 200 for max throughput. */
+    perPage?: number;
+    /** Stop after collecting this many items. */
+    maxResults?: number;
+    /** Stop after this many page requests. */
+    maxPages?: number;
+    /**
+     * 'cursor' (unlimited, sequential), 'basic' (≤10k), or 'auto'.
+     * 'auto' picks basic when `parallel` is set, else cursor.
+     */
+    strategy?: 'auto' | 'cursor' | 'basic';
+    /** Use parallel basic paging (fast; capped at 10k results). */
+    parallel?: boolean;
+    signal?: AbortSignal;
+    /** Cost classification passed through to the tracker. */
+    requestType?: RequestType;
+    /** Called once per page with cumulative progress. */
+    onProgress?: (info: ProgressInfo) => void;
+    /**
+     * Persist cursor position after every page so the extraction can resume
+     * after a crash/interrupt. Forces cursor paging. Cleared on completion.
+     */
+    resume?: Checkpoint;
+}
+/** Yield full pages (`ListResult`) according to the chosen strategy. */
+declare function streamPages<T>(runner: EntityRunner<T>, baseParams: Record<string, string | undefined>, opts?: StreamOptions): AsyncGenerator<ListResult<T>>;
+/** Yield individual entities, flattening pages, honouring `maxResults`. */
+declare function streamItems<T>(runner: EntityRunner<T>, baseParams: Record<string, string | undefined>, opts?: StreamOptions): AsyncGenerator<T>;
+declare function cursorPages<T>(runner: EntityRunner<T>, baseParams: Record<string, string | undefined>, opts: StreamOptions): AsyncGenerator<ListResult<T>>;
+declare function sequentialBasicPages<T>(runner: EntityRunner<T>, baseParams: Record<string, string | undefined>, opts: StreamOptions): AsyncGenerator<ListResult<T>>;
+declare function parallelBasicPages<T>(runner: EntityRunner<T>, baseParams: Record<string, string | undefined>, opts: StreamOptions): AsyncGenerator<ListResult<T>>;
+
+type FilterScalar = string | number | boolean;
+type FilterValue = FilterScalar | FilterScalar[];
+type Filters = Record<string, FilterValue>;
+/**
+ * Filter input with per-entity key autocomplete. Known keys (from the generated
+ * `*FilterKey` unions) are suggested in your IDE, while any string is still
+ * accepted — so new OpenAlex fields never break compilation.
+ */
+type FilterInput<F extends string = string> = {
+    [K in F]?: FilterValue;
+} & {
+    [key: string]: FilterValue;
+};
+/** Negate a filter value → `!value`. */
+declare const not: (v: FilterScalar) => string;
+/** Greater-than range filter → `>value`. */
+declare const gt: (v: FilterScalar) => string;
+/** Less-than range filter → `<value`. */
+declare const lt: (v: FilterScalar) => string;
+/** OR several values for one key (also expressible as a plain array). */
+declare const or: (...values: FilterScalar[]) => FilterScalar[];
+type SortSpec = string | string[] | Record<string, 'asc' | 'desc'>;
+interface QueryState {
+    filters: Filters;
+    search?: string;
+    sort?: string;
+    select?: string[];
+    perPage?: number;
+    sampleN?: number;
+    seed?: number;
+    groupBy?: string;
+    extra: Record<string, string>;
+}
+declare class QueryBuilder<T, F extends string = string> {
+    private readonly runner;
+    private readonly state;
+    constructor(runner: EntityRunner<T>, state?: QueryState);
+    /** The entity type this query targets (e.g. 'works'). */
+    get entityType(): EntityType;
+    private clone;
+    /** Merge filters. Array values are OR'd; use `not`/`gt`/`lt` helpers. */
+    filter(filters: FilterInput<F>): QueryBuilder<T, F>;
+    /** Full-text relevance search across the entity's default searchable fields. */
+    search(term: string): QueryBuilder<T, F>;
+    /** Search within a specific field, e.g. `.searchField('title', 'crispr')`. */
+    searchField(field: string, term: string): QueryBuilder<T, F>;
+    sort(spec: SortSpec): QueryBuilder<T, F>;
+    /** Trim the response to specific fields (cheaper, faster payloads). */
+    select(fields: string | string[]): QueryBuilder<T, F>;
+    /** Random sample of `n` results (optionally deterministic via `seed`). */
+    sample(n: number, seed?: number): QueryBuilder<T, F>;
+    seed(seed: number): QueryBuilder<T, F>;
+    perPage(n: number): QueryBuilder<T, F>;
+    /** Aggregate counts by a field (or two comma-separated fields). */
+    groupBy(field: string | string[]): QueryBuilder<T, F>;
+    /** Escape hatch: set any raw query parameter (advanced/semantic search, …). */
+    param(key: string, value: string | number | boolean): QueryBuilder<T, F>;
+    /** The OpenAlex query params this builder will send (no paging keys). */
+    toParams(): Record<string, string | undefined>;
+    private get requestType();
+    /** Fetch a single page. */
+    get(opts?: {
+        perPage?: number;
+        page?: number;
+    }): Promise<ListResult<T>>;
+    /** Fetch just the first matching entity, or `null`. */
+    first(): Promise<T | null>;
+    /** Total number of matching results (one cheap probe call). */
+    count(): Promise<number>;
+    /** Async-iterate every matching page. */
+    paginate(opts?: StreamOptions): AsyncGenerator<ListResult<T>>;
+    /** Async-iterate every matching entity across all pages. */
+    all(opts?: StreamOptions): AsyncGenerator<T>;
+    /** Collect all matching entities into an array (respecting `maxResults`). */
+    toArray(opts?: StreamOptions): Promise<T[]>;
+    /**
+     * Stream all results using the cost-optimal strategy: one cheap count, then
+     * parallel basic paging when ≤10k results (fastest) or cursor streaming above.
+     */
+    streamOptimized(opts?: StreamOptions): AsyncGenerator<T>;
+    /** Run a `group_by` aggregation and return the buckets. */
+    groups(field?: string | string[]): Promise<GroupResult[]>;
+    /** Estimate the dollar cost of extracting *all* matching results. */
+    estimateCost(opts?: {
+        perPage?: number;
+        strategy?: 'basic' | 'cursor';
+    }): Promise<CostEstimate>;
+    /** Stream all matching results to a file (JSONL / CSV / JSON). */
+    export(path: string, opts?: StreamOptions & {
+        format?: 'jsonl' | 'csv' | 'json';
+        flatten?: boolean;
+    }): Promise<{
+        path: string;
+        count: number;
+    }>;
+    private streamOpts;
+}
+declare function serializeFilters(filters: Filters): string | undefined;
+
+/**
+ * Per-entity endpoint. One instance per entity type (`client.works`, …).
+ *
+ * Implements {@link EntityRunner} so a {@link QueryBuilder} can execute through
+ * it, and exposes convenience proxies so simple calls stay terse:
+ *   await client.works.get('10.7717/peerj.4375')
+ *   await client.authors.filter({ ... }).sort({ cited_by_count: 'desc' }).toArray()
+ */
+
+interface GetOptions {
+    select?: string | string[];
+    noCache?: boolean;
+}
+declare class EntityEndpoint<T, F extends string = string> implements EntityRunner<T> {
+    protected readonly http: HttpClient;
+    readonly entityType: EntityType;
+    constructor(http: HttpClient, entityType: EntityType);
+    get logger(): Logger;
+    get defaultConcurrency(): number;
+    /** Low-level list fetch used by the query builder & paginators. */
+    fetchList(params: Record<string, string | undefined>, opts?: FetchListOptions): Promise<ListResult<T>>;
+    /** Start a fresh query. */
+    query(): QueryBuilder<T, F>;
+    filter(filters: FilterInput<F>): QueryBuilder<T, F>;
+    search(term: string): QueryBuilder<T, F>;
+    searchField(field: string, term: string): QueryBuilder<T, F>;
+    sort(spec: SortSpec): QueryBuilder<T, F>;
+    select(fields: string | string[]): QueryBuilder<T, F>;
+    sample(n: number, seed?: number): QueryBuilder<T, F>;
+    groupBy(field: string | string[]): QueryBuilder<T, F>;
+    perPage(n: number): QueryBuilder<T, F>;
+    param(key: string, value: string | number | boolean): QueryBuilder<T, F>;
+    count(): Promise<number>;
+    all(opts?: StreamOptions): AsyncGenerator<T>;
+    paginate(opts?: StreamOptions): AsyncGenerator<ListResult<T>>;
+    toArray(opts?: StreamOptions): Promise<T[]>;
+    groups(field: string | string[]): Promise<GroupResult[]>;
+    estimateCost(opts?: {
+        perPage?: number;
+        strategy?: 'basic' | 'cursor';
+    }): Promise<CostEstimate>;
+    export(path: string, opts?: StreamOptions & {
+        format?: 'jsonl' | 'csv' | 'json';
+        flatten?: boolean;
+    }): Promise<{
+        path: string;
+        count: number;
+    }>;
+    /**
+     * Fetch one entity by any supported ID: OpenAlex ID, DOI, ORCID, ROR, ISSN,
+     * Wikidata QID, PMID, MAG, or a full URL (all normalized automatically).
+     */
+    get(id: string, opts?: GetOptions): Promise<T>;
+    /**
+     * Fetch many entities by OpenAlex ID in as few calls as possible, batching
+     * into `ids.openalex` OR-filters (default 50 per request) run in parallel.
+     * Order is not guaranteed. For mixed external IDs, call {@link get} per ID.
+     */
+    getMany(ids: string[], opts?: {
+        select?: string | string[];
+        chunkSize?: number;
+    }): Promise<T[]>;
+    /** A single random entity (optionally trimmed with `select`). */
+    random(opts?: {
+        select?: string | string[];
+    }): Promise<T>;
+    /** Typeahead suggestions for this entity type. */
+    autocomplete(q: string): Promise<AutocompleteResult[]>;
+}
+
+/**
+ * Typed interfaces for OpenAlex entities.
+ *
+ * These cover the fields developers reach for most often. Every interface
+ * carries an index signature (`[key: string]: unknown`), so:
+ *   - fields not modelled here are still accessible (just untyped), and
+ *   - responses trimmed with `.select(...)` remain assignable.
+ * The full untouched payload is always available — nothing is dropped.
+ */
+interface DehydratedEntity {
+    id: string;
+    display_name: string;
+    [key: string]: unknown;
+}
+interface CountsByYear {
+    year: number;
+    works_count?: number;
+    cited_by_count?: number;
+    oa_works_count?: number;
+}
+interface Ids {
+    openalex?: string;
+    doi?: string;
+    mag?: string;
+    orcid?: string;
+    ror?: string;
+    issn_l?: string;
+    issn?: string[];
+    wikidata?: string;
+    wikipedia?: string;
+    [key: string]: unknown;
+}
+interface Authorship {
+    author_position?: 'first' | 'middle' | 'last';
+    author?: DehydratedEntity;
+    institutions?: DehydratedEntity[];
+    countries?: string[];
+    is_corresponding?: boolean;
+    raw_author_name?: string;
+    raw_affiliation_strings?: string[];
+    [key: string]: unknown;
+}
+interface Location {
+    is_oa?: boolean;
+    landing_page_url?: string | null;
+    pdf_url?: string | null;
+    source?: DehydratedEntity | null;
+    license?: string | null;
+    version?: string | null;
+    [key: string]: unknown;
+}
+interface OpenAccess {
+    is_oa?: boolean;
+    oa_status?: 'gold' | 'green' | 'hybrid' | 'bronze' | 'closed' | string;
+    oa_url?: string | null;
+    any_repository_has_fulltext?: boolean;
+    [key: string]: unknown;
+}
+interface Work {
+    id: string;
+    doi?: string | null;
+    title?: string | null;
+    display_name?: string | null;
+    publication_year?: number;
+    publication_date?: string;
+    ids?: Ids;
+    language?: string | null;
+    type?: string;
+    type_crossref?: string;
+    authorships?: Authorship[];
+    primary_location?: Location | null;
+    best_oa_location?: Location | null;
+    locations?: Location[];
+    open_access?: OpenAccess;
+    cited_by_count?: number;
+    cited_by_api_url?: string;
+    referenced_works?: string[];
+    referenced_works_count?: number;
+    related_works?: string[];
+    counts_by_year?: CountsByYear[];
+    topics?: DehydratedEntity[];
+    keywords?: {
+        id?: string;
+        display_name?: string;
+        score?: number;
+    }[];
+    concepts?: DehydratedEntity[];
+    abstract_inverted_index?: Record<string, number[]> | null;
+    is_retracted?: boolean;
+    is_paratext?: boolean;
+    updated_date?: string;
+    created_date?: string;
+    [key: string]: unknown;
+}
+interface Author {
+    id: string;
+    orcid?: string | null;
+    display_name?: string;
+    display_name_alternatives?: string[];
+    works_count?: number;
+    cited_by_count?: number;
+    ids?: Ids;
+    affiliations?: {
+        institution?: DehydratedEntity;
+        years?: number[];
+    }[];
+    last_known_institutions?: DehydratedEntity[];
+    topics?: DehydratedEntity[];
+    summary_stats?: SummaryStats;
+    counts_by_year?: CountsByYear[];
+    works_api_url?: string;
+    updated_date?: string;
+    created_date?: string;
+    [key: string]: unknown;
+}
+interface SummaryStats {
+    '2yr_mean_citedness'?: number;
+    h_index?: number;
+    i10_index?: number;
+    [key: string]: unknown;
+}
+interface Source {
+    id: string;
+    issn_l?: string | null;
+    issn?: string[] | null;
+    display_name?: string;
+    host_organization?: string | null;
+    host_organization_name?: string | null;
+    type?: string;
+    is_oa?: boolean;
+    is_in_doaj?: boolean;
+    works_count?: number;
+    cited_by_count?: number;
+    summary_stats?: SummaryStats;
+    ids?: Ids;
+    counts_by_year?: CountsByYear[];
+    works_api_url?: string;
+    updated_date?: string;
+    created_date?: string;
+    [key: string]: unknown;
+}
+interface Institution {
+    id: string;
+    ror?: string;
+    display_name?: string;
+    country_code?: string | null;
+    type?: string;
+    homepage_url?: string | null;
+    works_count?: number;
+    cited_by_count?: number;
+    summary_stats?: SummaryStats;
+    ids?: Ids;
+    geo?: {
+        city?: string;
+        region?: string | null;
+        country_code?: string;
+        country?: string;
+        latitude?: number;
+        longitude?: number;
+    };
+    associated_institutions?: DehydratedEntity[];
+    counts_by_year?: CountsByYear[];
+    works_api_url?: string;
+    updated_date?: string;
+    created_date?: string;
+    [key: string]: unknown;
+}
+interface Topic {
+    id: string;
+    display_name?: string;
+    description?: string;
+    keywords?: string[];
+    works_count?: number;
+    cited_by_count?: number;
+    subfield?: DehydratedEntity;
+    field?: DehydratedEntity;
+    domain?: DehydratedEntity;
+    ids?: Ids;
+    updated_date?: string;
+    created_date?: string;
+    [key: string]: unknown;
+}
+interface Keyword {
+    id: string;
+    display_name?: string;
+    works_count?: number;
+    cited_by_count?: number;
+    updated_date?: string;
+    created_date?: string;
+    [key: string]: unknown;
+}
+interface Publisher {
+    id: string;
+    display_name?: string;
+    alternate_titles?: string[];
+    hierarchy_level?: number;
+    parent_publisher?: DehydratedEntity | string | null;
+    country_codes?: string[];
+    works_count?: number;
+    cited_by_count?: number;
+    summary_stats?: SummaryStats;
+    ids?: Ids;
+    counts_by_year?: CountsByYear[];
+    sources_api_url?: string;
+    updated_date?: string;
+    created_date?: string;
+    [key: string]: unknown;
+}
+interface Funder {
+    id: string;
+    display_name?: string;
+    alternate_titles?: string[];
+    country_code?: string | null;
+    description?: string | null;
+    homepage_url?: string | null;
+    grants_count?: number;
+    works_count?: number;
+    cited_by_count?: number;
+    summary_stats?: SummaryStats;
+    ids?: Ids;
+    counts_by_year?: CountsByYear[];
+    updated_date?: string;
+    created_date?: string;
+    [key: string]: unknown;
+}
+/** Maps an entity-type string to its interface. */
+interface EntityTypeMap {
+    works: Work;
+    authors: Author;
+    sources: Source;
+    institutions: Institution;
+    topics: Topic;
+    keywords: Keyword;
+    publishers: Publisher;
+    funders: Funder;
+}
+
+type WorksFilterKey = "abstract.search" | "abstract.search.exact" | "apc_list.currency" | "apc_list.provenance" | "apc_list.value" | "apc_list.value_usd" | "apc_paid.currency" | "apc_paid.provenance" | "apc_paid.value" | "apc_paid.value_usd" | "author.id" | "author.orcid" | "authors_count" | "authorships.affiliations.institution_ids" | "authorships.author.id" | "authorships.author.orcid" | "authorships.countries" | "authorships.institutions.continent" | "authorships.institutions.country_code" | "authorships.institutions.id" | "authorships.institutions.is_global_south" | "authorships.institutions.lineage" | "authorships.institutions.ror" | "authorships.institutions.type" | "authorships.is_corresponding" | "authorships.raw_orcid" | "awards.doi" | "awards.funder_award_id" | "awards.funder_display_name" | "awards.funder_id" | "awards.id" | "best_oa_location.is_accepted" | "best_oa_location.is_oa" | "best_oa_location.is_published" | "best_oa_location.landing_page_url" | "best_oa_location.license" | "best_oa_location.license_id" | "best_oa_location.raw_type" | "best_oa_location.source.host_organization" | "best_oa_location.source.host_organization_lineage" | "best_oa_location.source.id" | "best_oa_location.source.is_in_doaj" | "best_oa_location.source.is_oa" | "best_oa_location.source.issn" | "best_oa_location.source.type" | "best_oa_location.version" | "best_open_version" | "biblio.first_page" | "biblio.issue" | "biblio.last_page" | "biblio.volume" | "citation_normalized_percentile.is_in_top_10_percent" | "citation_normalized_percentile.is_in_top_1_percent" | "citation_normalized_percentile.value" | "cited_by" | "cited_by_count" | "cited_by_percentile_year.max" | "cited_by_percentile_year.min" | "cites" | "collection" | "concept.id" | "concepts.id" | "concepts.wikidata" | "concepts_count" | "corresponding_author_ids" | "corresponding_institution_ids" | "countries_distinct_count" | "created_date" | "datasets" | "default.search" | "default.search.exact" | "display_name" | "display_name.search" | "display_name.search.exact" | "doi" | "doi_starts_with" | "from_created_date" | "from_publication_date" | "fulltext.search" | "fulltext.search.exact" | "fulltext_origin" | "funders.id" | "fwci" | "has_abstract" | "has_content.grobid_xml" | "has_content.pdf" | "has_doi" | "has_embeddings" | "has_fulltext" | "has_oa_accepted_or_published_version" | "has_oa_submitted_version" | "has_old_authors" | "has_orcid" | "has_pdf_url" | "has_pmcid" | "has_pmid" | "has_raw_affiliation_strings" | "has_references" | "ids.mag" | "ids.openalex" | "ids.pmcid" | "ids.pmid" | "indexed_in" | "institution.id" | "institution_assertions.country_code" | "institution_assertions.id" | "institution_assertions.lineage" | "institution_assertions.ror" | "institution_assertions.type" | "institutions.continent" | "institutions.country_code" | "institutions.id" | "institutions.is_global_south" | "institutions.ror" | "institutions.type" | "institutions_distinct_count" | "is_corresponding" | "is_oa" | "is_paratext" | "is_retracted" | "is_xpac" | "journal" | "keyword.search" | "keywords.id" | "language" | "locations.is_accepted" | "locations.is_oa" | "locations.is_published" | "locations.landing_page_url" | "locations.license" | "locations.license_id" | "locations.raw_type" | "locations.source.has_issn" | "locations.source.host_institution_lineage" | "locations.source.host_organization" | "locations.source.host_organization_lineage" | "locations.source.id" | "locations.source.is_core" | "locations.source.is_in_doaj" | "locations.source.is_oa" | "locations.source.issn" | "locations.source.publisher_lineage" | "locations.source.type" | "locations.version" | "locations_count" | "mag" | "mag_only" | "oa_status" | "open_access.any_repository_has_fulltext" | "open_access.is_oa" | "open_access.oa_status" | "openalex" | "openalex_id" | "pmcid" | "pmid" | "primary_location.is_accepted" | "primary_location.is_oa" | "primary_location.is_published" | "primary_location.landing_page_url" | "primary_location.license" | "primary_location.license_id" | "primary_location.raw_type" | "primary_location.source.has_issn" | "primary_location.source.host_institution_lineage" | "primary_location.source.host_organization" | "primary_location.source.host_organization_lineage" | "primary_location.source.id" | "primary_location.source.is_core" | "primary_location.source.is_in_doaj" | "primary_location.source.is_oa" | "primary_location.source.issn" | "primary_location.source.publisher_lineage" | "primary_location.source.type" | "primary_location.version" | "primary_topic.domain.id" | "primary_topic.field.id" | "primary_topic.id" | "primary_topic.subfield.id" | "publication_date" | "publication_year" | "raw_affiliation_strings" | "raw_affiliation_strings.search" | "raw_author_name.search" | "referenced_works" | "referenced_works_count" | "related_to" | "repository" | "semantic.search" | "sustainable_development_goals.id" | "sustainable_development_goals.score" | "title.search" | "title.search.exact" | "title_and_abstract.search" | "title_and_abstract.search.exact" | "to_created_date" | "to_publication_date" | "to_updated_date" | "topics.domain.id" | "topics.field.id" | "topics.id" | "topics.subfield.id" | "topics_count" | "type" | "type_crossref" | "updated_date" | "version";
+type AuthorsFilterKey = "affiliations.institution.country_code" | "affiliations.institution.id" | "affiliations.institution.lineage" | "affiliations.institution.ror" | "affiliations.institution.type" | "block_key" | "cited_by_count" | "collection" | "concept.id" | "concepts.id" | "default.search" | "display_name" | "display_name.search" | "from_created_date" | "has_orcid" | "id" | "ids.openalex" | "last_known_authorships.institutions.lineage" | "last_known_institutions.continent" | "last_known_institutions.country_code" | "last_known_institutions.id" | "last_known_institutions.is_global_south" | "last_known_institutions.lineage" | "last_known_institutions.ror" | "last_known_institutions.type" | "openalex" | "openalex_id" | "orcid" | "parsed_longest_name.first" | "parsed_longest_name.last" | "parsed_longest_name.middle" | "parsed_longest_name.suffix" | "scopus" | "summary_stats.2yr_mean_citedness" | "summary_stats.h_index" | "summary_stats.i10_index" | "text.search" | "to_created_date" | "to_updated_date" | "topic_share.id" | "topics.id" | "works_count" | "x_concepts.id";
+type SourcesFilterKey = "apc_prices.currency" | "apc_prices.price" | "apc_usd" | "cited_by_count" | "collection" | "concept.id" | "concepts.id" | "continent" | "country_code" | "default.search" | "display_name" | "display_name.search" | "first_publication_year" | "from_created_date" | "has_issn" | "host_organization" | "host_organization.id" | "host_organization_lineage" | "ids.mag" | "ids.openalex" | "is_core" | "is_global_south" | "is_high_oa_rate" | "is_high_oa_rate_since_year" | "is_in_doaj" | "is_in_doaj_since_year" | "is_in_jstage" | "is_in_jstage_since_year" | "is_oa" | "is_ojs" | "is_preprint_repository" | "issn" | "issn_l" | "last_publication_year" | "oa_flip_year" | "openalex" | "openalex_id" | "summary_stats.2yr_mean_citedness" | "summary_stats.h_index" | "summary_stats.i10_index" | "text.search" | "to_created_date" | "to_updated_date" | "topic_share.id" | "topics.id" | "type" | "works_count" | "x_concepts.id";
+type InstitutionsFilterKey = "cited_by_count" | "collection" | "concept.id" | "concepts.id" | "continent" | "country_code" | "default.search" | "display_name" | "display_name.search" | "from_created_date" | "has_ror" | "id" | "ids.openalex" | "is_global_south" | "is_super_system" | "lineage" | "openalex" | "openalex_id" | "repositories.host_organization" | "repositories.host_organization_lineage" | "repositories.id" | "roles.id" | "ror" | "status" | "summary_stats.2yr_mean_citedness" | "summary_stats.h_index" | "summary_stats.i10_index" | "text.search" | "topic_share.id" | "topics.id" | "type" | "works_count" | "x_concepts.id";
+type TopicsFilterKey = "cited_by_count" | "collection" | "default.search" | "description.search" | "display_name" | "display_name.search" | "domain.id" | "field.id" | "from_created_date" | "id" | "ids.openalex" | "keywords.search" | "openalex" | "subfield.id" | "text.search" | "works_count";
+type KeywordsFilterKey = "cited_by_count" | "collection" | "default.search" | "display_name" | "display_name.search" | "from_created_date" | "id" | "text.search" | "works_count";
+type PublishersFilterKey = "cited_by_count" | "collection" | "continent" | "country_codes" | "default.search" | "display_name" | "display_name.search" | "from_created_date" | "hierarchy_level" | "ids.openalex" | "ids.ror" | "ids.wikidata" | "lineage" | "openalex" | "openalex_id" | "parent_publisher" | "roles.id" | "ror" | "summary_stats.2yr_mean_citedness" | "summary_stats.h_index" | "summary_stats.i10_index" | "text.search" | "wikidata" | "works_count";
+type FundersFilterKey = "awards_count" | "cited_by_count" | "collection" | "continent" | "country_code" | "default.search" | "description.search" | "display_name" | "display_name.search" | "from_created_date" | "ids.crossref" | "ids.doi" | "ids.openalex" | "ids.ror" | "ids.wikidata" | "is_global_south" | "openalex" | "openalex_id" | "roles.id" | "ror" | "summary_stats.2yr_mean_citedness" | "summary_stats.h_index" | "summary_stats.i10_index" | "text.search" | "wikidata" | "works_count";
+/** Maps an entity type to its filter-key union. */
+interface EntityFilterKeyMap {
+    works: WorksFilterKey;
+    authors: AuthorsFilterKey;
+    sources: SourcesFilterKey;
+    institutions: InstitutionsFilterKey;
+    topics: TopicsFilterKey;
+    keywords: KeywordsFilterKey;
+    publishers: PublishersFilterKey;
+    funders: FundersFilterKey;
+}
+
+/**
+ * Works endpoint with citation-graph helpers layered on top of the generic
+ * {@link EntityEndpoint}. Each helper returns a composable {@link QueryBuilder},
+ * so you can chain `.select()`, `.filter()`, `.all()`, `.export()`, etc.
+ */
+
+/** Public host that serves cached full-text (PDF / TEI-XML) for OA works. */
+declare const CONTENT_BASE_URL = "https://content.openalex.org";
+type FulltextFormat = 'pdf' | 'xml';
+declare class WorksEndpoint extends EntityEndpoint<Work, WorksFilterKey> {
+    constructor(http: HttpClient);
+    /** Works that **cite** the given work (incoming citations). */
+    citedBy(workId: string): QueryBuilder<Work, WorksFilterKey>;
+    /** Works the given work **cites** — its references (outgoing citations). */
+    references(workId: string): QueryBuilder<Work, WorksFilterKey>;
+    /** Works OpenAlex considers related to the given work. */
+    related(workId: string): QueryBuilder<Work, WorksFilterKey>;
+    /** Only works that have a downloadable cached PDF. */
+    withPdf(): QueryBuilder<Work, WorksFilterKey>;
+    /** Only works that have a downloadable TEI-XML (Grobid) parse. */
+    withXml(): QueryBuilder<Work, WorksFilterKey>;
+    /** The content-host URL for a work's full text (api_key redacted). */
+    fulltextUrl(workId: string, format?: FulltextFormat): string;
+    /**
+     * Download a work's cached full text (PDF or TEI-XML). Costs $0.01/call and
+     * is budget-tracked. Pass `dest` to stream to a file, otherwise get bytes.
+     */
+    downloadFulltext(workId: string, opts?: {
+        format?: FulltextFormat;
+        dest?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        bytes?: Uint8Array;
+        path?: string;
+        contentType?: string;
+    }>;
+    private rawFulltextUrl;
+    /**
+     * One-hop citation neighbourhood: the work plus its references and citers.
+     * Bounded by `limit` on each side to keep the cost predictable.
+     */
+    citationGraph(workId: string, opts?: {
+        limit?: number;
+        select?: string[];
+    }): Promise<{
+        seed: Work;
+        references: Work[];
+        citedBy: Work[];
+    }>;
+}
+
+/**
+ * Snapshot / bulk-data bridge — the "$0 extract-all-data" path.
+ *
+ * OpenAlex publishes the *entire* dataset as a free, public S3 snapshot
+ * (gzipped JSON Lines, no credentials needed). For large extractions this is
+ * far cheaper than the metered API: e.g. all Works = 510M records / 665 GB at
+ * $0, versus paying $0.0001/list-call to crawl them.
+ *
+ * This module lets you:
+ *   - read the snapshot manifests (per-entity or combined) over HTTPS,
+ *   - compare the API cost of an extraction against the free snapshot,
+ *   - generate the exact `aws s3 sync` command, and
+ *   - stream entities straight from the public bucket in-process (gunzip +
+ *     NDJSON), with an optional client-side filter — zero dependencies.
+ *
+ * Paths/schema verified live (2026-07-25) against openalex.s3.amazonaws.com.
+ */
+
+type SnapshotFormat = 'jsonl' | 'parquet';
+/** Default public HTTPS endpoint for the OpenAlex S3 bucket. */
+declare const SNAPSHOT_BASE_URL = "https://openalex.s3.amazonaws.com";
+declare const SNAPSHOT_S3_URI = "s3://openalex";
+interface SnapshotFileEntry {
+    /** Original `s3://openalex/...` URL from the manifest. */
+    s3Url: string;
+    /** HTTPS URL for credential-free download. */
+    httpsUrl: string;
+    contentLength: number;
+    recordCount: number;
+}
+interface SnapshotManifest {
+    entity: string;
+    format: string;
+    date?: string;
+    recordCount: number;
+    contentLength: number;
+    files: SnapshotFileEntry[];
+}
+interface EntityTotals {
+    entity: string;
+    recordCount: number;
+    contentLength: number;
+}
+interface SnapshotPlan {
+    entity: string;
+    /** Results your filtered query would return from the API. */
+    apiResults: number;
+    apiCalls: number;
+    apiCostUsd: number;
+    /** The snapshot is always free. */
+    snapshotCostUsd: 0;
+    /** Total records in the entity's snapshot, when known. */
+    snapshotRecords?: number;
+    /** Compressed bytes of the entity's snapshot, when known. */
+    snapshotBytes?: number;
+    awsCommand: string;
+    recommendation: 'api' | 'snapshot';
+    rationale: string;
+}
+interface SnapshotClientOptions {
+    /** Override the HTTPS base (e.g. a mirror or region host). */
+    baseUrl?: string;
+    /** 'jsonl' (default, streamable in-process) or 'parquet'. */
+    format?: SnapshotFormat;
+    /** Inject a fetch (defaults to global fetch / the client's fetch). */
+    fetch?: FetchLike;
+}
+interface StreamSnapshotOptions<T> {
+    /** Keep only entities matching this predicate. */
+    filter?: (entity: T) => boolean;
+    /** Only read the first N part files (useful for sampling/testing). */
+    maxParts?: number;
+    /** Stop after emitting this many records. */
+    maxRecords?: number;
+    /** Start from this part index (for manual resume). */
+    startPart?: number;
+    /** Called after each part file completes. */
+    onPart?: (info: {
+        index: number;
+        total: number;
+        url: string;
+        records: number;
+    }) => void;
+    signal?: AbortSignal;
+}
+declare class SnapshotClient {
+    readonly baseUrl: string;
+    readonly format: SnapshotFormat;
+    private readonly fetchImpl;
+    constructor(opts?: SnapshotClientOptions);
+    /** Convert an `s3://openalex/KEY` URL to a public HTTPS URL. */
+    s3ToHttps(s3Url: string): string;
+    manifestUrl(entity: string): string;
+    combinedManifestUrl(): string;
+    /** `aws s3 sync` command to download the whole snapshot or one entity. */
+    awsSyncCommand(entity?: string, dest?: string): string;
+    /** Fetch and normalize an entity's manifest. */
+    manifest(entity: string): Promise<SnapshotManifest>;
+    /** Per-entity totals from the combined manifest (no per-file list). */
+    totals(): Promise<EntityTotals[]>;
+    /** Totals for a single entity (cheap-ish: reads combined manifest). */
+    entityTotals(entity: string): Promise<EntityTotals | undefined>;
+    /**
+     * Compare a filtered API extraction against downloading the whole snapshot.
+     * Pass the {@link CostEstimate} from `query.estimateCost()` plus the entity.
+     */
+    plan(apiEstimate: CostEstimate, entity: string, opts?: {
+        fetchTotals?: boolean;
+        dest?: string;
+    }): Promise<SnapshotPlan>;
+    /**
+     * Stream entities straight from the public snapshot (gunzip + NDJSON), at $0.
+     * Reads the manifest, then each gzipped part over HTTPS.
+     */
+    stream<T = Record<string, unknown>>(entity: string, opts?: StreamSnapshotOptions<T>): AsyncGenerator<T>;
+    private toFileEntry;
+    private getJson;
+}
+/**
+ * Stream newline-delimited JSON out of a gzipped HTTPS resource, without
+ * buffering the whole file. Uses web streams (`DecompressionStream`) — no deps.
+ */
+declare function streamGzippedNdjson<T>(fetchImpl: FetchLike, url: string, signal?: AbortSignal): AsyncGenerator<T>;
+
+/**
+ * Cost-optimal extraction planner.
+ *
+ * Given a query, it counts once and recommends how to extract cheapest/fastest:
+ *   - per-page 200 (fewest calls),
+ *   - parallel basic paging when ≤10k results (fastest), else cursor streaming,
+ *   - and, when the API bill would be high, the free snapshot instead.
+ */
+
+type ExtractionStrategy = 'parallel-basic' | 'cursor' | 'snapshot';
+interface ExtractionPlan {
+    entity: string;
+    matchingResults: number;
+    requestType: RequestType;
+    recommendedPerPage: number;
+    recommendedStrategy: ExtractionStrategy;
+    estimate: CostEstimate;
+    useSnapshot: boolean;
+    snapshotAwsCommand?: string;
+    rationale: string;
+}
+interface PlanOptions {
+    perPage?: number;
+    /** Recommend the snapshot when the API extraction would cost ≥ this (USD). Default 1. */
+    snapshotThresholdUsd?: number;
+}
+declare function planExtraction(snapshot: SnapshotClient, query: QueryBuilder<unknown>, opts?: PlanOptions): Promise<ExtractionPlan>;
+
+/**
+ * N-grams for a Work — the fulltext n-gram frequencies OpenAlex exposes for
+ * many works (when available).
+ */
+
+interface NgramEntry {
+    ngram: string;
+    ngram_count: number;
+    ngram_tokens: number;
+    term_frequency: number;
+}
+interface NgramsResponse {
+    meta: {
+        count: number;
+        doi?: string | null;
+        [key: string]: unknown;
+    };
+    ngrams: NgramEntry[];
+}
+/** Fetch the n-grams for a single Work (by any supported ID). */
+declare function fetchNgrams(http: HttpClient, workId: string): Promise<NgramsResponse>;
+/**
+ * Reconstruct readable abstract text from a Work's `abstract_inverted_index`.
+ * Returns `null` when the index is absent (common for closed works).
+ */
+declare function decodeAbstract(invertedIndex: Record<string, number[]> | null | undefined): string | null;
+
+/**
+ * The main entry point: `new OpenAlexClient({ apiKey })`.
+ *
+ * Exposes one {@link EntityEndpoint} per entity type plus a shared
+ * {@link UsageTracker} so budget/spend is visible across every call the client
+ * makes.
+ */
+
+declare class OpenAlexClient {
+    readonly config: ResolvedConfig;
+    readonly http: HttpClient;
+    /** Live spend/budget tracker, updated from every response. */
+    readonly usage: UsageTracker;
+    /** Free bulk-data snapshot bridge (manifest, cost comparison, streaming). */
+    readonly snapshot: SnapshotClient;
+    readonly works: WorksEndpoint;
+    readonly authors: EntityEndpoint<Author, AuthorsFilterKey>;
+    readonly sources: EntityEndpoint<Source, SourcesFilterKey>;
+    readonly institutions: EntityEndpoint<Institution, InstitutionsFilterKey>;
+    readonly topics: EntityEndpoint<Topic, TopicsFilterKey>;
+    readonly keywords: EntityEndpoint<Keyword, KeywordsFilterKey>;
+    readonly publishers: EntityEndpoint<Publisher, PublishersFilterKey>;
+    readonly funders: EntityEndpoint<Funder, FundersFilterKey>;
+    constructor(config?: OpenAlexConfig);
+    /** Cross-entity typeahead. Optionally scope with `entityType`. */
+    autocomplete(q: string, entityType?: 'works' | 'authors' | 'sources' | 'institutions' | 'topics' | 'keywords' | 'publishers' | 'funders'): Promise<AutocompleteResult[]>;
+    /** N-grams for a Work. */
+    ngrams(workId: string): Promise<NgramsResponse>;
+    /**
+     * Decide API vs free snapshot for a query: estimates the API cost, then
+     * compares against downloading the whole entity's snapshot ($0).
+     */
+    snapshotPlan(query: QueryBuilder<unknown>): Promise<SnapshotPlan>;
+    /**
+     * Cost-optimal plan for extracting a query: recommends per-page, cursor-vs-
+     * parallel strategy, and whether the free snapshot beats the API.
+     */
+    planExtraction(query: QueryBuilder<unknown>, opts?: PlanOptions): Promise<ExtractionPlan>;
+    /** Escape hatch: issue a raw GET against any path with any params. */
+    request<T = unknown>(path: string, params?: Record<string, string | undefined>, opts?: {
+        requestType?: RequestType;
+        noCache?: boolean;
+    }): Promise<T>;
+    /** Point-in-time usage snapshot. */
+    usageSnapshot(): UsageSnapshot;
+    /** Human-readable spend/budget report. */
+    usageReport(): string;
+    /** Reset the session usage counters (does not affect OpenAlex's daily total). */
+    resetUsage(): void;
+}
+
+export { PRICING_USD as $, type Author as A, BASIC_PAGING_MAX_RESULTS as B, CONTENT_BASE_URL as C, type DehydratedEntity as D, EntityEndpoint as E, FREE_DAILY_USD_WITHOUT_KEY as F, type FundersFilterKey as G, type GetOptions as H, type GroupByResult as I, type GroupResult as J, type Ids as K, type Institution as L, type InstitutionsFilterKey as M, type Keyword as N, OpenAlexClient as O, type KeywordsFilterKey as P, LRUCache as Q, type ListResult as R, type Location as S, type Logger as T, MemoryCheckpoint as U, type Meta as V, type NgramEntry as W, type NgramsResponse as X, type OpenAccess as Y, type OpenAlexConfig as Z, type OpenAlexEntity as _, type AuthorsFilterKey as a, type ParsedUsageHeaders as a0, type PlanOptions as a1, type ProgressInfo as a2, type Publisher as a3, type PublishersFilterKey as a4, QueryBuilder as a5, REAL_CLOCK as a6, type RequestType as a7, type ResolvedConfig as a8, type ResolvedThrottle as a9, clampPerPage as aA, cursorPages as aB, decodeAbstract as aC, estimateExtractionCost as aD, fetchNgrams as aE, gt as aF, lt as aG, not as aH, or as aI, parallelBasicPages as aJ, parseUsageHeaders as aK, planExtraction as aL, resolveConfig as aM, sequentialBasicPages as aN, serializeFilters as aO, streamGzippedNdjson as aP, streamItems as aQ, streamPages as aR, type RetryPolicy as aa, SNAPSHOT_BASE_URL as ab, SNAPSHOT_S3_URI as ac, SnapshotClient as ad, type SnapshotClientOptions as ae, type SnapshotFileEntry as af, type SnapshotFormat as ag, type SnapshotManifest as ah, type SnapshotPlan as ai, type SortSpec as aj, type Source as ak, type SourcesFilterKey as al, type StreamOptions as am, type StreamSnapshotOptions as an, type SummaryStats as ao, Throttle as ap, type ThrottleOptions as aq, type ThrottleState as ar, type Topic as as, type TopicsFilterKey as at, type UsageByType as au, type UsageSnapshot as av, UsageTracker as aw, type Work as ax, WorksEndpoint as ay, type WorksFilterKey as az, type Authorship as b, type AutocompleteResult as c, type CacheStore as d, type Checkpoint as e, type CheckpointState as f, type Clock as g, type CostEstimate as h, type CountsByYear as i, type EntityFilterKeyMap as j, type EntityTotals as k, type EntityType as l, type EntityTypeMap as m, type EstimateInput as n, type ExtractionPlan as o, type ExtractionStrategy as p, FREE_DAILY_USD_WITH_KEY as q, FREE_TIER_LIMITS as r, type FetchLike as s, FileCheckpoint as t, type FilterInput as u, type FilterScalar as v, type FilterValue as w, type Filters as x, type FulltextFormat as y, type Funder as z };