/**
 * Pagination infrastructure for MCP tool responses.
 *
 * Provides cursor-based pagination with server-side page size clamping
 * to keep responses within LLM context budgets (~5 KB per response).
 */
/**
 * Page size defaults and maximums for each paginated resource type.
 */
export declare const PAGE_SIZE_DEFAULTS: {
    readonly OBJECT_LIST: {
        readonly default: 25;
        readonly max: 50;
    };
    readonly FIELD_LIST: {
        readonly default: 25;
        readonly max: 50;
    };
    readonly RELATIONSHIP_LIST: {
        readonly default: 10;
        readonly max: 25;
    };
    readonly NAMESPACE_LIST: {
        readonly default: 10;
        readonly max: 25;
    };
    readonly RECORD_TYPE_LIST: {
        readonly default: 10;
        readonly max: 25;
    };
};
/**
 * Metadata included in every paginated response envelope.
 */
export type PaginationMetadata = {
    /** Number of items returned in this page */
    readonly returned: number;
    /** Total number of items across all pages */
    readonly total: number;
    /** Whether more items are available */
    readonly hasMore: boolean;
    /** Opaque cursor to pass for the next page (undefined on last page) */
    readonly nextCursor?: string;
    /** Items per page used for this response */
    readonly pageSize: number;
    /** Human-readable pagination status message */
    readonly message: string;
};
/**
 * Encodes a numeric offset into an opaque base64 cursor string.
 *
 * @param offset - The zero-based offset to encode
 * @returns Opaque cursor string
 */
export declare function encodeCursor(offset: number): string;
/**
 * Decodes an opaque cursor string back to a numeric offset.
 *
 * Returns 0 for undefined or empty cursors (start from beginning).
 * Throws for malformed cursors to prevent silent pagination loops.
 *
 * @param cursor - Opaque cursor string from a previous response
 * @returns The decoded offset, or 0 if cursor is undefined/empty
 * @throws Error if the cursor is present but malformed
 */
export declare function decodeCursor(cursor: string | undefined): number;
/**
 * Clamps a requested page size to within [1, max], defaulting if undefined.
 *
 * @param requested - The page size requested by the client (may be undefined)
 * @param defaultSize - Default page size when not specified
 * @param maxSize - Maximum allowed page size
 * @returns Clamped page size
 */
export declare function clampPageSize(requested: number | undefined, defaultSize: number, maxSize: number): number;
/**
 * Input parameters for creating pagination metadata.
 */
type PaginationMetadataInput = {
    /** Current offset (start of this page) */
    readonly offset: number;
    /** Page size used for this response */
    readonly pageSize: number;
    /** Total number of items across all pages */
    readonly totalItems: number;
    /** Actual number of items returned in this page */
    readonly returnedItems: number;
};
/**
 * Creates pagination metadata for a response envelope.
 *
 * @param input - Pagination parameters
 * @returns Pagination metadata with cursor and status message
 */
export declare function createPaginationMetadata(input: PaginationMetadataInput): PaginationMetadata;
export {};