@vepler/schools-types/api/common.d.ts

TypeScript type definitions for Vepler Schools Service

/**
 * Common API Types
 *
 * Common type definitions shared across multiple API endpoints.
 */
/**
 * Base API response interface
 */
export interface BaseApiResponse {
    /**
     * Indicates if the API request was successful
     */
    success: boolean;
    /**
     * Optional message (error message when success=false)
     */
    message?: string;
}
/**
 * API response for array data types
 * The result is guaranteed to be an array (empty array in case of error, never null)
 */
export interface ArrayApiResponse<T extends any[]> extends BaseApiResponse {
    /**
     * The array response payload (never null, empty array in case of error)
     */
    result: T;
}
/**
 * API response for object/scalar data types
 * The result may be null in case of error
 */
export interface ObjectApiResponse<T> extends BaseApiResponse {
    /**
     * The object/scalar response payload (may be null in case of error)
     */
    result: T | null;
}
/**
 * General API response type (backward compatibility)
 * Use ArrayApiResponse or ObjectApiResponse for more specific typing when possible
 */
export type ApiResponse<T> = T extends any[] ? ArrayApiResponse<T> : ObjectApiResponse<T>;
/**
 * Pagination metadata for API responses
 */
export interface PaginationMeta {
    /**
     * Total number of items available
     */
    total: number;
    /**
     * Total number of pages available
     */
    pages: number;
    /**
     * Current page number
     */
    currentPage: number;
    /**
     * Number of items per page
     */
    pageSize: number;
}
/**
 * Common pagination parameters used across multiple endpoints
 */
export interface PaginationParams {
    /**
     * Page number for pagination
     * @minimum 1
     * @default 1
     */
    page?: number;
    /**
     * Number of results per page
     * @minimum 1
     * @maximum 100
     * @default 20
     */
    limit?: number;
}
/**
 * Common geographic coordinates format
 * Used for location-based queries
 */
export interface Coordinates {
    /**
     * Longitude component
     * @minimum -180
     * @maximum 180
     */
    longitude: number;
    /**
     * Latitude component
     * @minimum -90
     * @maximum 90
     */
    latitude: number;
}
/**
 * Common geographic bounding box format
 * Used for area-based queries
 */
export interface BoundingBox {
    /**
     * Minimum longitude
     * @minimum -180
     * @maximum 180
     */
    minLongitude: number;
    /**
     * Minimum latitude
     * @minimum -90
     * @maximum 90
     */
    minLatitude: number;
    /**
     * Maximum longitude
     * @minimum -180
     * @maximum 180
     */
    maxLongitude: number;
    /**
     * Maximum latitude
     * @minimum -90
     * @maximum 90
     */
    maxLatitude: number;
}
/**
 * Area filter types - defines the structure of geographic area filters
 * Used for all area-based filtering operations
 */
export interface AreaFilter {
    /** Type of area filter */
    type: 'point' | 'polygon' | 'multipolygon' | 'bbox' | 'entity';
    /** Radius in meters (required for point type) */
    radius?: number;
    /**
     * Coordinates array:
     * - For point: [longitude, latitude]
     * - For polygon: array of [longitude, latitude] pairs
     * - For multipolygon: array of polygon arrays
     * - For bbox: [minLon, minLat, maxLon, maxLat]
     */
    coordinates?: number[] | number[][] | number[][][];
    /** Type of geographic entity (required for entity type) */
    entityType?: string;
    /** Array of entity IDs (required for entity type) */
    ids?: string[];
}