/** Encodes a stable sort key into an opaque base64url cursor token. */
export declare function encodeCursor(key: string): string;
/** Decodes an opaque cursor token back to the sort key it encodes.
 *  Throws `CrtrError` with code `'invalid_cursor'` on malformed input. */
export declare function decodeCursor(token: string): string;
export interface PaginateResult<T> {
    items: T[];
    next_cursor: string | null;
    total: number | null;
}
export interface PaginateOpts<T> {
    /** Default page size when `params.limit` is absent. */
    defaultLimit: number;
    /** Hard cap; `params.limit` is clamped to [1, maxLimit]. */
    maxLimit: number;
    /** Returns the stable sort key for an item. Must match the sort order of the
     *  input array — ascending by this key. */
    keyOf: (item: T) => string;
    /** 'count' → compute and return `total`; 'omit' → return `null`. */
    total: 'count' | 'omit';
}
/**
 * Returns one page of items from a pre-sorted list, with a stable opaque
 * cursor for resumption.
 *
 * @param allItemsSortedAscByKey - Full dataset, sorted ascending by `keyOf`.
 * @param params - Agent-supplied `{ limit?, cursor? }` from stdin.
 * @param opts - Caller-supplied configuration (limits, key extractor, total).
 */
export declare function paginate<T>(allItemsSortedAscByKey: T[], params: {
    limit?: number;
    cursor?: string;
}, opts: PaginateOpts<T>): PaginateResult<T>;