/**
 * Pagination helpers for GTM API v2 list endpoints.
 *
 * GTM list endpoints return a `nextPageToken` when more results exist. These
 * helpers transparently follow every page so callers receive the complete set
 * by default, while still allowing callers to bound the work via `maxPages`.
 */
import { z } from 'zod';
/** Default safety ceiling on the number of pages fetched in a single call. */
export declare const DEFAULT_MAX_PAGES = 50;
/**
 * Reusable Zod fields for paginated list tools. Merge into a tool input
 * schema with `.extend(paginationFields)`. Both fields are optional, so
 * existing callers keep working unchanged — by default every page is fetched.
 */
export declare const paginationFields: {
    pageToken: z.ZodOptional<z.ZodString>;
    maxPages: z.ZodOptional<z.ZodNumber>;
};
export interface PaginationOptions {
    /** Optional starting page token. */
    pageToken?: string;
    /**
     * Maximum number of pages to fetch. Defaults to a safe upper bound to avoid
     * unbounded loops against very large accounts. Set higher if needed.
     */
    maxPages?: number;
}
export interface PaginatedResult<T> {
    items: T[];
    /** Number of pages actually fetched. */
    pagesFetched: number;
    /**
     * Set when there were more pages than `maxPages` allowed. Callers can pass
     * this back as `pageToken` to continue, or raise `maxPages`.
     */
    nextPageToken?: string;
    /** True when at least one additional page remained unfetched. */
    truncated: boolean;
}
/**
 * Follow GTM pagination across pages and accumulate the extracted items.
 *
 * @param fetchPage  Calls the GTM list endpoint for a given page token and
 *                   returns the raw response data (the `.data` of the gaxios
 *                   response).
 * @param extract    Pulls the array of items out of a page's response data.
 * @param options    Optional starting token and page ceiling.
 */
export declare function paginate<TData, TItem>(fetchPage: (pageToken?: string) => Promise<TData>, extract: (data: TData) => TItem[] | undefined, options?: PaginationOptions): Promise<PaginatedResult<TItem>>;
/** Where a list was read from. Carried back so an answer can say WHERE it looked. */
export interface ListScope {
    accountId?: string;
    containerId?: string;
    workspaceId?: string;
    propertyId?: string;
}
/**
 * Shape a paginated result into the standard list-tool response body. Keeps
 * the existing `{ <key>: [...], count }` shape and only adds pagination
 * metadata (`nextPageToken`, `truncated`) when the result was actually
 * truncated, so non-truncated responses are unchanged from before.
 *
 * `scope` echoes the ids the list was read from. An empty list is the case that
 * needs it: "there are no tags in your selected workspace" is unfalsifiable
 * without knowing which workspace that was, and a container can hold several.
 * Returning the ids means an answer can name them instead of the user having to
 * trust that the right one was read.
 */
export declare function buildListResult<T>(key: string, result: PaginatedResult<T>, scope?: ListScope): Record<string, unknown>;
//# sourceMappingURL=pagination.d.ts.map