firewalla-mcp-server
Version:
Model Context Protocol (MCP) server for Firewalla MSP API - Provides real-time network monitoring, security analysis, and firewall management through 28 specialized tools compatible with any MCP client
224 lines • 8.43 kB
TypeScript
/**
* Universal pagination utilities for cursor-based and offset-based pagination
* Provides consistent pagination interface across all MCP tools
*
* This module combines functionality from the original pagination.ts and pagination-manager.ts
* to provide a unified, comprehensive pagination solution.
*/
/**
* Type for any object that can be paginated
*/
export type Paginatable = Record<string, unknown> | object;
/**
* Pagination configuration interface
*/
export interface PaginationConfig {
/** Maximum page size allowed */
maxPageSize: number;
/** Default page size if not specified */
defaultPageSize: number;
/** Whether to use cursor-based pagination (preferred) */
useCursor: boolean;
/** Whether to use offset-based pagination (legacy) */
useOffset: boolean;
/** Whether to calculate total count (performance impact) */
includeTotalCount: boolean;
}
/**
* Pagination parameters from user input
*/
export interface PaginationParams {
/** Requested page size/limit */
limit?: number;
/** Cursor for cursor-based pagination */
cursor?: string;
/** Offset for offset-based pagination (deprecated) */
offset?: number;
/** Whether to include total count in response */
include_total_count?: boolean;
}
/**
* Cursor data structure for cursor-based pagination
*/
export interface CursorData {
offset: number;
page_size: number;
total_items?: number;
sort_by?: string;
sort_order?: 'asc' | 'desc';
}
/**
* Paginated result interface
*/
export interface PaginatedResult<T> {
results: T[];
next_cursor?: string;
total_count: number;
page_size: number;
has_more: boolean;
}
/**
* Standardized pagination response format
*/
export interface PaginationResponse {
/** Current page size */
limit: number;
/** Number of items in current page */
count: number;
/** Total count if requested and available */
total?: number;
/** Whether there are more pages available */
has_more: boolean;
/** Cursor for next page (preferred) */
next_cursor?: string | null;
/** Offset for next page (deprecated) */
offset?: number;
/** Current page number (for offset-based pagination) */
page?: number;
/** Additional pagination metadata */
metadata?: {
pages_traversed?: number;
estimated_total?: number;
warning?: string;
};
}
/**
* Update pagination configuration at runtime
*/
export declare function updatePaginationConfig(newConfig: Partial<PaginationConfig>): void;
/**
* Get current pagination configuration
*/
export declare function getPaginationConfig(): PaginationConfig;
/**
* Get default page size with validation
*/
export declare function getDefaultPageSize(requestedSize?: number): number;
/**
* Encodes a `CursorData` object into a base64 string for use as a pagination cursor.
*
* @param data - The cursor data to encode
* @returns The base64-encoded string representing the cursor
* @throws If the cursor data cannot be serialized or encoded
*/
export declare function encodeCursor(data: CursorData): string;
/**
* Decodes a base64-encoded cursor string into a validated `CursorData` object.
*
* Throws an error if the cursor is not valid base64, cannot be parsed as JSON, or does not contain required pagination fields.
*
* @param cursor - The base64-encoded cursor string to decode
* @returns The decoded and validated cursor data
*/
export declare function decodeCursor(cursor: string): CursorData;
/**
* Performs client-side cursor-based pagination and optional sorting on an array of items.
*
* Decodes the provided cursor to determine the current offset and page size, sorts the array by the specified field and order if requested, and returns a paginated result with metadata and a next cursor if more items remain.
*
* @param items - The array of items to paginate
* @param cursor - Optional base64-encoded cursor string indicating the current pagination state
* @param page_size - Number of items per page (default: configured DEFAULT_PAGE_SIZE or 100)
* @param sort_by - Optional field name to sort by
* @param sort_order - Sort order, either 'asc' or 'desc' (default is 'asc')
* @returns A paginated result containing the current page of items, pagination metadata, and a next cursor if more items are available
*/
export declare function paginateArray<T extends object>(items: T[], cursor?: string, page_size?: number, sort_by?: string, sort_order?: 'asc' | 'desc'): PaginatedResult<T>;
/**
* Fetches all items using the provided data fetcher and returns a paginated result based on the given cursor, page size, and sorting options.
*
* @param dataFetcher - A function that asynchronously retrieves all items to be paginated
* @param cursor - An optional base64-encoded cursor string representing the current pagination state
* @param page_size - The number of items per page (default: configured DEFAULT_PAGE_SIZE or 100)
* @param sort_by - Optional field name to sort the items by
* @param sort_order - Sort order, either 'asc' or 'desc' (default is 'asc')
* @returns A paginated result containing the current page of items, pagination metadata, and next cursor if more items remain
* @throws If data fetching or pagination fails
*/
export declare function createPaginatedResponse<T extends object>(dataFetcher: () => Promise<T[]>, cursor?: string, page_size?: number, sort_by?: string, sort_order?: 'asc' | 'desc'): Promise<PaginatedResult<T>>;
/**
* Formats a paginated result into a standardized response object for MCP tools.
*
* @param paginatedResult - The paginated data and metadata to include in the response
* @param query - The original query string associated with the request
* @param execution_time_ms - The time taken to execute the query, in milliseconds
* @returns An object containing the current page of results, counts, pagination metadata, the original query, and execution time
*/
export declare function formatPaginationResponse<T>(paginatedResult: PaginatedResult<T>, query: string, execution_time_ms: number): {
results: T[];
count: number;
total_count: number;
next_cursor?: string;
has_more: boolean;
query: string;
execution_time_ms: number;
};
/**
* Pagination manager for consistent pagination handling
*/
export declare class PaginationManager {
private config;
constructor(config?: Partial<PaginationConfig>);
/**
* Normalize pagination parameters from user input
*/
normalizePaginationParams(params: PaginationParams): {
limit: number;
cursor?: string;
offset: number;
includeTotalCount: boolean;
warnings: string[];
};
/**
* Create standardized pagination response
*/
createPaginationResponse(results: any[], params: PaginationParams, apiResponse?: any): PaginationResponse;
/**
* Extract pagination information from API response
*/
extractPaginationFromApiResponse(apiResponse: any): {
hasMore: boolean;
nextCursor?: string | null;
total?: number;
count?: number;
};
/**
* Get configuration for specific tool types
*/
static getConfigForTool(toolName: string): Partial<PaginationConfig>;
/**
* Create pagination manager for specific tool
*/
static forTool(toolName: string): PaginationManager;
}
/**
* Global pagination manager with default configuration
*/
export declare const globalPaginationManager: PaginationManager;
/**
* Convenience function for creating standardized pagination responses
*/
export declare function createStandardPaginationResponse(results: any[], params: PaginationParams, apiResponse?: any, toolName?: string): PaginationResponse;
/**
* Validate pagination parameters
*/
export declare function validatePaginationParams(params: PaginationParams, toolName?: string): {
isValid: boolean;
errors: string[];
warnings: string[];
normalized: ReturnType<PaginationManager['normalizePaginationParams']>;
};
/**
* Migration utility for converting offset-based to cursor-based pagination
*/
export declare function convertOffsetToCursorParams(params: {
limit?: number;
offset?: number;
sort_by?: string;
sort_order?: 'asc' | 'desc';
}): {
limit?: number;
cursor?: string;
warnings: string[];
};
//# sourceMappingURL=pagination.d.ts.map