import type { ApiClient, FetchResponse, HttpMethod, MaybeOptionalInit, MediaType, PathsWithMethod, RequiredKeysOf } from '@archon-research/http-client-core';
import type { DataTag, QueryClient, QueryFilters, QueryKey, SkipToken, UseMutationOptions, UseQueryOptions } from '@tanstack/react-query';
import { HttpRequestError } from './errors.js';
import { type QueryApiMiddleware } from './middleware.js';
import { type QueryApiKey } from './query-key.js';
/**
 * The shape an `openapi-typescript`-generated `paths` type has: every path maps
 * to an object carrying the HTTP methods that endpoint implements, plus the
 * path-level `parameters`. This is the constraint on `createQueryApi` and on
 * every option type below, and it is what makes `TPaths[TPath][TMethod]` legal.
 *
 * Every method is *optional* and typed `any` for two reasons that come straight
 * from the generated output. `openapi-typescript` emits absent operations as
 * `put?: never`, so a required key rejects real generated paths; and the
 * operation payload has to widen to `any`, because narrowing it makes
 * TypeScript resolve `TPaths[TPath][TMethod]` to `<payload> | undefined`, which
 * then fails `FetchResponse`'s own `Record<string | number, any>` constraint.
 * Nothing is lost by that: the operation types the api actually reports are
 * read back off the caller's own `TPaths`, never off this shape.
 *
 * What it therefore does *not* do is reject a badly typed client. If the paths
 * type behind `client` is not a paths map, inference finds no candidate for
 * `TPaths` and falls back to this constraint, so `createQueryApi` still returns
 * — as `QueryApi<QueryApiPaths>`, on which no `queryOptions` call typechecks.
 * The rejection lands on the calls rather than on the construction.
 */
export type QueryApiPaths = Record<string, {
    [TMethod in HttpMethod]?: any;
} & {
    parameters?: any;
}>;
/**
 * Methods `queryOptions` accepts: the safe, bodyless, cacheable ones. A
 * POST-backed read (`POST /search`) is deliberately out of v1 — see DESIGN.md.
 */
export type QueryApiQueryMethod = Extract<HttpMethod, 'get' | 'head'>;
/** Methods `mutationOptions` accepts. */
export type QueryApiMutationMethod = Extract<HttpMethod, 'post' | 'put' | 'patch' | 'delete'>;
/**
 * What a failed query or mutation rejects with. A request that reached the
 * server rejects with {@link HttpRequestError} (status plus parsed error body);
 * a transport failure or a middleware — response validation, for instance —
 * rejects with whatever it threw. Narrow with `isHttpRequestError` before
 * reading `status`.
 */
export type QueryApiError<TErrorBody> = HttpRequestError<TErrorBody> | Error;
type InitWithUnknowns<TInit> = TInit & {
    [key: string]: unknown;
};
type InferSelectReturnType<TData, TSelect> = TSelect extends (data: TData) => infer TSelected ? TSelected : TData;
/** Per-call options for `queryOptions`: react-query's, plus cache tags. */
export type QueryApiCallOptions<TQueryFnData, TError, TData, TKey extends QueryKey, TTag extends string> = Omit<UseQueryOptions<TQueryFnData, TError, TData, TKey>, 'queryKey' | 'queryFn'> & {
    /** Tags this endpoint belongs to, for mutation-driven invalidation. */
    tags?: readonly TTag[];
    /** Middleware appended to the instance chain for this call only. */
    middleware?: readonly QueryApiMiddleware[];
};
/**
 * A tag to invalidate on mutation success, either fixed or derived from the
 * mutation's own result and variables.
 */
export type MutationInvalidation<TTag extends string, TData, TVariables> = TTag | ((data: TData, variables: TVariables) => TTag | readonly TTag[]);
/** Per-call options for `mutationOptions`: react-query's, plus `invalidates`. */
export type QueryApiMutationCallOptions<TData, TError, TVariables, TOnMutateResult, TTag extends string> = Omit<UseMutationOptions<TData, TError, TVariables, TOnMutateResult>, 'mutationKey' | 'mutationFn'> & {
    invalidates?: readonly MutationInvalidation<TTag, TData, TVariables>[];
    /** Middleware appended to the instance chain for this call only. */
    middleware?: readonly QueryApiMiddleware[];
};
export type QueryApiKeyFn<TPaths extends QueryApiPaths, TMedia extends MediaType> = <TMethod extends QueryApiQueryMethod, TPath extends PathsWithMethod<TPaths, TMethod>, TInit extends MaybeOptionalInit<TPaths[TPath], TMethod>, TResponse extends Required<FetchResponse<TPaths[TPath][TMethod], TInit, TMedia>>>(method: TMethod, path: TPath, ...[init]: RequiredKeysOf<TInit> extends never ? [init?: InitWithUnknowns<TInit>] : [init: InitWithUnknowns<TInit>]) => NoInfer<DataTag<QueryApiKey<TMethod, TPath>, TResponse['data'], QueryApiError<TResponse['error']>>>;
export type QueryApiQueryOptionsFn<TPaths extends QueryApiPaths, TTag extends string, TMedia extends MediaType> = <TMethod extends QueryApiQueryMethod, TPath extends PathsWithMethod<TPaths, TMethod>, TInit extends MaybeOptionalInit<TPaths[TPath], TMethod>, TResponse extends Required<FetchResponse<TPaths[TPath][TMethod], TInit, TMedia>>, TOptions extends QueryApiCallOptions<TResponse['data'], QueryApiError<TResponse['error']>, InferSelectReturnType<TResponse['data'], TOptions['select']>, QueryApiKey<TMethod, TPath>, TTag>>(method: TMethod, path: TPath, ...[init, options]: RequiredKeysOf<TInit> extends never ? [init?: InitWithUnknowns<TInit>, options?: TOptions] : [init: InitWithUnknowns<TInit>, options?: TOptions]) => NoInfer<Omit<UseQueryOptions<TResponse['data'], QueryApiError<TResponse['error']>, InferSelectReturnType<TResponse['data'], TOptions['select']>, QueryApiKey<TMethod, TPath>>, 'queryKey' | 'queryFn'> & {
    queryKey: DataTag<QueryApiKey<TMethod, TPath>, TResponse['data'], QueryApiError<TResponse['error']>>;
    queryFn: Exclude<UseQueryOptions<TResponse['data'], QueryApiError<TResponse['error']>, InferSelectReturnType<TResponse['data'], TOptions['select']>, QueryApiKey<TMethod, TPath>>['queryFn'], SkipToken | undefined>;
}>;
export type QueryApiMutationOptionsFn<TPaths extends QueryApiPaths, TTag extends string, TMedia extends MediaType> = <TMethod extends QueryApiMutationMethod, TPath extends PathsWithMethod<TPaths, TMethod>, TInit extends MaybeOptionalInit<TPaths[TPath], TMethod>, TResponse extends Required<FetchResponse<TPaths[TPath][TMethod], TInit, TMedia>>, TOnMutateResult = unknown>(method: TMethod, path: TPath, options?: QueryApiMutationCallOptions<TResponse['data'], QueryApiError<TResponse['error']>, InitWithUnknowns<TInit>, TOnMutateResult, TTag>) => NoInfer<Omit<UseMutationOptions<TResponse['data'], QueryApiError<TResponse['error']>, InitWithUnknowns<TInit>, TOnMutateResult>, 'mutationKey' | 'mutationFn'> & {
    mutationKey: readonly [method: TMethod, path: TPath];
    mutationFn: NonNullable<UseMutationOptions<TResponse['data'], QueryApiError<TResponse['error']>, InitWithUnknowns<TInit>, TOnMutateResult>['mutationFn']>;
}>;
/** Instance-level configuration for {@link createQueryApi}. */
export type QueryApiOptions<TTag extends string> = {
    /**
     * The tag vocabulary. Passing it both infers `TTag` (so `tags` and
     * `invalidates` are checked against a closed set) and makes an unknown tag
     * throw at runtime, which is what catches typos from untyped call sites.
     */
    tags?: readonly TTag[];
    /** Middleware applied to every request from this instance, outermost first. */
    middleware?: readonly QueryApiMiddleware[];
};
export type QueryApi<TPaths extends QueryApiPaths, TTag extends string = string, TMedia extends MediaType = MediaType> = {
    /**
     * The derived key for an operation, for targeting `getQueryData`,
     * `setQueryData`, or `invalidateQueries` without a hand-built key factory.
     * Slice it to `[method, path]` to target every cached variant of an endpoint.
     */
    queryKey: QueryApiKeyFn<TPaths, TMedia>;
    queryOptions: QueryApiQueryOptionsFn<TPaths, TTag, TMedia>;
    mutationOptions: QueryApiMutationOptionsFn<TPaths, TTag, TMedia>;
    /** A react-query filter matching every query registered under `tag`. */
    tagFilter: (tag: TTag) => QueryFilters;
    invalidateTags: (client: QueryClient, tags: readonly TTag[]) => Promise<void>;
    /** The `${method} ${path}` tokens currently registered under `tag`. */
    taggedEndpoints: (tag: TTag) => readonly string[];
};
/**
 * Binds a TanStack Query surface to an `openapi-fetch` client.
 *
 * The generated `TPaths` type is the only endpoint definition: methods, paths,
 * params, request bodies, and response types are all read off it, and both
 * `TPaths` and the tag vocabulary are inferred from the arguments — prefer
 * `createQueryApi(client, { tags: [...] })` over passing type arguments
 * explicitly, since naming one disables inference for the rest.
 */
export declare function createQueryApi<TPaths extends QueryApiPaths, TTag extends string = string, TMedia extends MediaType = MediaType>(client: ApiClient<TPaths, TMedia>, options?: QueryApiOptions<TTag>): QueryApi<TPaths, TTag, TMedia>;
export {};