pagamio-frontend-commons-lib/lib/api/types.d.ts

Pagamio library for Frontend reusable components like the form engine and table container

import type { CustomAuthConfig, TokenManager } from '../auth';
export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
export interface ApiErrorResponse {
    error?: string;
    message?: string;
    status?: number;
    [key: string]: unknown;
}
export declare class ApiError extends Error {
    status: number;
    data?: unknown;
    constructor(message: string, status: number, data?: unknown);
}
export interface ApiClientConfig<T extends CustomAuthConfig> {
    baseURL: string;
    tokenManager?: TokenManager<T>;
    defaultHeaders?: HeadersInit;
    timeout?: number;
    retries?: number;
    retryDelay?: number;
    onRequest?: (config: RequestInit) => Promise<RequestInit> | RequestInit;
    onResponse?: <T>(response: Response, data: T) => Promise<T> | T;
    onError?: (error: ApiError) => Promise<void> | void;
    onUnauthorized?: () => Promise<void> | void;
}
export interface RequestConfig extends RequestInit {
    params?: Record<string, string>;
    timeout?: number;
    retries?: number;
    skipAuth?: boolean;
    skipRetry?: boolean;
    skipRefresh?: boolean;
    isProtected?: boolean;
    signal?: AbortSignal | null;
}
/**
 * Spring Boot style paginated response interface
 */
export interface SpringBootResponse<T> {
    content: T[];
    pageable: {
        sort: {
            empty: boolean;
            sorted: boolean;
            unsorted: boolean;
        };
        offset: number;
        pageNumber: number;
        pageSize: number;
        paged: boolean;
        unpaged: boolean;
    };
    totalElements: number;
    totalPages: number;
    last: boolean;
    size: number;
    number: number;
    sort: {
        empty: boolean;
        sorted: boolean;
        unsorted: boolean;
    };
    first: boolean;
    numberOfElements: number;
    empty: boolean;
}
/**
 * Configuration for mapping API response structure
 */
export interface ResponseMapping {
    /** Path to data array in response (e.g., 'content' or 'data.items') */
    data?: string;
    /** Path to total count (e.g., 'totalElements' or 'meta.total') */
    total?: string;
    /** Path to current page number */
    page?: string;
    /** Path to page size */
    pageSize?: string;
    /** Default values when paths are not found */
    defaultValues?: {
        data: any[];
        total: number;
        page: number;
        pageSize: number;
    };
    /** Type of response structure */
    responseType?: 'default' | 'spring-boot';
}
/**
 * Configuration for query parameter formatting
 */
export interface QueryParamConfig {
    pagination?: {
        /** Parameter name for page number (default: 'page') */
        pageParam?: string;
        /** Parameter name for page size (default: 'size') */
        sizeParam?: string;
        /** Custom transform function for pagination parameters */
        transform?: (page: number, size: number) => Record<string, string>;
    };
    sorting?: {
        /** Parameter name for sort field (default: 'sortBy') */
        sortByParam?: string;
        /** Parameter name for sort direction (default: 'sortDir') */
        sortDirParam?: string;
        /** Custom transform function for sorting parameters */
        transform?: (sortBy: string, sortDir: string) => Record<string, string>;
    };
    filtering?: {
        /** Parameter name for search query (default: 'searchQuery') */
        searchParam?: string;
        /** Format for filter parameters */
        filterFormat?: 'bracket' | 'flat' | 'prefix' | 'custom';
        /** Prefix for filter parameters when using 'prefix' format */
        filterPrefix?: string;
        /** Custom transform function for filter parameters */
        transform?: (filters: Record<string, string>) => Record<string, string>;
    };
}
/**
 * Represents a single mock configuration for an API request.
 */
export interface MockConfig {
    /**
     * The path of the API endpoint (e.g., "/dashboard/metrics").
     */
    path: string;
    /**
     * The HTTP method (e.g., "GET", "POST", "PUT", "DELETE").
     */
    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
    /**
     * The query parameters or payload expected in the request.
     * If undefined, the mock will match any request to the path and method.
     */
    params?: Record<string, any> | any[];
    /**
     * The mock response to return when the request matches.
     */
    response: any;
}
/**
 * Type for the `mockConfig` prop, which is an array of `MockConfig` objects.
 */
export type MockConfigArray = MockConfig[];