/**
 * @fileoverview Pagination types for the DeepSource MCP Server
 * This module defines interfaces for pagination parameters and responses.
 */

/**
 * Relay-style pagination information
 * Contains information about whether there are more pages and cursors for navigating between pages.
 * @public
 */
export interface PageInfo {
  /** Whether there are more items after the current page */
  hasNextPage: boolean;
  /** Whether there are more items before the current page */
  hasPreviousPage: boolean;
  /** Cursor for the first item in the current page, used for backward pagination */
  startCursor?: string;
  /** Cursor for the last item in the current page, used for forward pagination */
  endCursor?: string;
}

/**
 * Parameters for paginating through API results
 * Supports both legacy offset-based pagination and Relay-style cursor-based pagination.
 * @public
 */
export interface PaginationParams {
  /** Legacy pagination: Number of items to skip */
  offset?: number;
  /** Relay-style pagination: Number of items to return after the 'after' cursor */
  first?: number;
  /** Relay-style pagination: Cursor to fetch records after this cursor */
  after?: string;
  /** Relay-style pagination: Cursor to fetch records before this cursor */
  before?: string;
  /** Relay-style pagination: Number of items to return before the 'before' cursor */
  last?: number;
  /** Alias for 'first' - Number of items per page (for user convenience) */
  page_size?: number;
  /** Maximum number of pages to fetch (prevents runaway pagination) */
  max_pages?: number;
}

/**
 * Metadata about the pagination state
 * Provides detailed information about the current pagination operation
 * @public
 */
export interface PaginationMetadata {
  /** Whether there are more pages available */
  has_more_pages: boolean;
  /** Cursor to fetch the next page (if available) */
  next_cursor?: string;
  /** Cursor to fetch the previous page (if available) */
  previous_cursor?: string;
  /** Total number of items across all pages (if known) */
  total_count?: number;
  /** Number of items in the current page */
  page_size: number;
  /** Number of pages fetched so far (for multi-page operations) */
  pages_fetched?: number;
  /** Whether the max_pages limit was reached */
  limit_reached?: boolean;
}

/**
 * Generic response structure containing paginated results
 * @public
 * @template T - The type of items in the response
 */
export interface PaginatedResponse<T> {
  /** Array of items in the current page */
  items: T[];
  /** Pagination information for navigating between pages */
  pageInfo: PageInfo;
  /** Total number of items across all pages */
  totalCount: number;
}

/**
 * Paginated response with enhanced metadata for MCP tool responses
 * This extends the standard response with user-friendly pagination info
 * @public
 * @template T - The type of items in the response
 */
export interface PaginatedResponseWithMetadata<T> extends PaginatedResponse<T> {
  /** User-friendly pagination metadata (in addition to pageInfo) */
  pagination?: PaginationMetadata;
}

/**
 * Options for multi-page fetching operations
 * @public
 */
export interface MultiPageOptions {
  /** Maximum number of pages to fetch (default: 10) */
  maxPages?: number;
  /** Page size for each request (default: 50) */
  pageSize?: number;
  /** Whether to fetch all pages regardless of maxPages (use with caution) */
  fetchAll?: boolean;
  /** Callback for progress updates during multi-page fetching */
  onProgress?: (pagesFetched: number, itemsFetched: number) => void;
}

/**
 * Result from a multi-page fetch operation
 * @public
 * @template T - The type of items in the response
 */
export interface MultiPageResult<T> {
  /** All items fetched across all pages */
  items: T[];
  /** Number of pages that were fetched */
  pagesFetched: number;
  /** Whether there are still more pages available */
  hasMore: boolean;
  /** The last cursor position (for resuming later) */
  lastCursor?: string;
  /** Total count if available from the API */
  totalCount?: number;
}