/**
 * @fileoverview Aggregation tool for trend and distribution analysis via OpenAlex group_by.
 * @module mcp-server/tools/definitions/analyze-trends.tool
 */
import { z } from '@cyanheads/mcp-ts-core';
import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
export declare const analyzeTrendsTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
    entity_type: z.ZodEnum<{
        authors: "authors";
        funders: "funders";
        institutions: "institutions";
        keywords: "keywords";
        publishers: "publishers";
        sources: "sources";
        topics: "topics";
        works: "works";
    }>;
    group_by: z.ZodString;
    filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
    include_unknown: z.ZodDefault<z.ZodBoolean>;
    per_page: z.ZodDefault<z.ZodNumber>;
    order: z.ZodOptional<z.ZodEnum<{
        count: "count";
        key: "key";
    }>>;
    cursor: z.ZodOptional<z.ZodString>;
}, z.core.$strip>, z.ZodObject<{
    meta: z.ZodObject<{
        count: z.ZodNumber;
        groups_count: z.ZodNullable<z.ZodNumber>;
        next_cursor: z.ZodNullable<z.ZodString>;
    }, z.core.$strip>;
    groups: z.ZodArray<z.ZodObject<{
        key: z.ZodString;
        key_display_name: z.ZodString;
        count: z.ZodNumber;
    }, z.core.$strip>>;
}, z.core.$strip>, readonly [{
    readonly reason: "rate_limited";
    readonly code: JsonRpcErrorCode.RateLimited;
    readonly when: "OpenAlex throttled the request for exceeding its per-second ceiling (HTTP 429).";
    readonly retryable: true;
    readonly recovery: "Wait several seconds and retry; consider lowering request frequency for this caller.";
}, {
    readonly reason: "upstream_budget_exhausted";
    readonly code: JsonRpcErrorCode.RateLimited;
    readonly when: "The OpenAlex daily usage budget is spent (HTTP 429).";
    readonly retryable: false;
    readonly recovery: "The daily budget refills at midnight UTC — retrying sooner will not succeed. Set OPENALEX_API_KEY to a free key (https://openalex.org/settings/api) for a larger daily budget than anonymous access, or wait for the reset.";
}, {
    readonly reason: "upstream_timeout";
    readonly code: JsonRpcErrorCode.Timeout;
    readonly when: "OpenAlex did not respond within the request deadline.";
    readonly retryable: true;
    readonly recovery: "Retry after a short delay; if timeouts persist, narrow the request with tighter filters to reduce upstream load.";
}, {
    readonly reason: "upstream_unavailable";
    readonly code: JsonRpcErrorCode.ServiceUnavailable;
    readonly when: "OpenAlex was unreachable or unusable — HTTP 503, a connection failure, or a body that was empty, HTML, or unparseable JSON.";
    readonly retryable: true;
    readonly recovery: "Wait and retry; check https://openalex.org for service status if the outage persists.";
}, {
    readonly reason: "upstream_unauthorized";
    readonly code: JsonRpcErrorCode.Unauthorized;
    readonly when: "OpenAlex rejected the API key (HTTP 401).";
    readonly recovery: "Check that OPENALEX_API_KEY is set to a valid OpenAlex account API key (free from https://openalex.org/settings/api).";
}, {
    readonly reason: "upstream_forbidden";
    readonly code: JsonRpcErrorCode.Forbidden;
    readonly when: "OpenAlex denied access to the requested resource (HTTP 403).";
    readonly recovery: "Confirm the API key has access to this entity type or endpoint, then retry the request.";
}, {
    readonly reason: "comma_in_filter_value";
    readonly code: JsonRpcErrorCode.InvalidParams;
    readonly when: "A filter value contains a comma, which collides with the OpenAlex filter separator.";
    readonly recovery: "Use `|` for OR within a filter value (e.g. \"2020|2021\"), or use a `.search` filter or the `query` parameter for free-text phrases that contain commas.";
}, {
    readonly reason: "upstream_invalid_params";
    readonly code: JsonRpcErrorCode.InvalidParams;
    readonly when: "OpenAlex rejected an invalid group_by or filter field name (HTTP 400).";
    readonly recovery: "The upstream message names the rejected key and suggests close matches. Use openalex_describe_fields(entity_type, \"group_by\") to browse valid group_by fields, or openalex_describe_fields(entity_type, \"filter\") for filter fields.";
}, {
    readonly reason: "upstream_invalid_id_value";
    readonly code: JsonRpcErrorCode.InvalidParams;
    readonly when: "An entity-ID filter received a value that is not an OpenAlex ID — usually a name (HTTP 400).";
    readonly recovery: "Call openalex_resolve_name to turn the name into an OpenAlex ID, then filter by that ID. Entity filters such as authorships.author.id and primary_topic.id accept IDs only.";
}, {
    readonly reason: "upstream_ungroupable_group_by";
    readonly code: JsonRpcErrorCode.InvalidParams;
    readonly when: "group_by targets a raw date, float, or *.search field OpenAlex cannot aggregate (HTTP 400).";
    readonly recovery: "Group by a categorical or year field (e.g. publication_year, type, oa_status, or an integer count field) — raw date fields and *.search operators cannot be grouped. Call openalex_describe_fields(entity_type, \"group_by\") for the groupable set.";
}, {
    readonly reason: "upstream_invalid_params_other";
    readonly code: JsonRpcErrorCode.InvalidParams;
    readonly when: "OpenAlex rejected the request (HTTP 400) for a reason other than an invalid field name.";
    readonly recovery: "Read the upstream message in the error above and adjust the request — check filter operators, value formats, and the group_by field.";
}, {
    readonly reason: "upstream_validation_failed";
    readonly code: JsonRpcErrorCode.ValidationError;
    readonly when: "OpenAlex rejected the request as semantically invalid (HTTP 422).";
    readonly recovery: "Read the upstream message for the specific field, then adjust the request to satisfy validation.";
}], {
    readonly echo: z.ZodString;
    readonly totalCount: z.ZodNumber;
    readonly notice: z.ZodOptional<z.ZodString>;
    readonly budget: z.ZodOptional<z.ZodObject<{
        costUsd: z.ZodNumber;
        remainingUsd: z.ZodNumber;
        resetsInSeconds: z.ZodNumber;
        prepaidRemainingUsd: z.ZodOptional<z.ZodNumber>;
    }, z.core.$strip>>;
}>;
//# sourceMappingURL=analyze-trends.tool.d.ts.map