@vepler/schools-types/api/endpoints/metrics.d.ts

TypeScript type definitions for Vepler Schools Service

/**
 * Metrics Endpoint Types
 *
 * Type definitions for the /metrics API endpoint.
 * This file contains both request and response types.
 */
import { Period, CohortType, PriorAttainment, PupilCharacteristic } from '../../models/metric';
import { ObjectApiResponse } from '../common';
import { MetricProfile } from './metrics-geographic';
/**
 * Input parameters for the /metrics GET endpoint
 */
export interface MetricsQueryParams {
    /**
     * Comma-separated list of school IDs to query metrics for
     * @required
     * @example "123,456,789"
     */
    schoolIds: string;
    /**
     * Comma-separated list of academic year IDs
     * @example "GB_2022-2023,GB_2021-2022"
     * @description If not provided, metrics from the latest academic year will be returned
     */
    academicYears?: string;
    /**
     * Comma-separated list of specific metric codes to query
     * @example "PTRWM_EXP,READPROG,ATT8SCR"
     * @description Mutually exclusive with profile
     */
    metricCodes?: string;
    /**
     * Pre-defined profile(s) of metrics to return
     * @enum ["ks2", "ks4", "ks5", "pupil", "finance", "ofsted"]
     * @description Mutually exclusive with metricCodes. Can be a comma-separated list of profiles.
     * @example "ks2,ks4,pupil"
     */
    profile?: string;
    /**
     * Student cohort type for filtering metrics
     * @enum ["all", "disadvantaged", "boys", "girls", "eal", "senSupport", "ehcp"]
     */
    cohortType?: CohortType;
    /**
     * Reporting period type
     * @enum ["annual", "termly", "monthly"]
     */
    period?: Period;
    /**
     * Period number (e.g., term 1, 2, 3 or month 1-12)
     * @description Required when period is 'termly' or 'monthly'
     */
    periodNumber?: number;
    /**
     * Include metric definitions metadata in response
     * @default false
     */
    includeMetadata?: boolean;
    /**
     * Prior attainment filter
     * @enum ["low", "medium", "high"]
     */
    priorAttainment?: PriorAttainment;
    /**
     * Pupil characteristic filter
     * @enum ["fsm", "eal", "sen", "none"]
     */
    pupilCharacteristic?: PupilCharacteristic;
}
/**
 * Metric data item in response
 */
export interface MetricDataItem {
    /**
     * School database ID
     */
    schoolId: number;
    /**
     * School name
     */
    schoolName: string;
    /**
     * School URN (Unique Reference Number)
     */
    schoolURN: number;
    /**
     * Academic year ID (e.g., "GB_2022-2023")
     */
    academicYear: string;
    /**
     * Academic year name (e.g., "2022-2023")
     */
    academicYearName: string;
    /**
     * Metric code identifier
     */
    metricCode: string;
    /**
     * The actual metric value
     */
    value: string;
    /**
     * Student cohort type
     */
    cohortType: CohortType;
    /**
     * Reporting period type
     */
    period: Period;
    /**
     * Period number (e.g., term 1, 2, 3 or month 1-12)
     */
    periodNumber: number | null;
    /**
     * Additional contextual factors
     */
    contextualFactors?: {
        priorAttainment?: string | null;
        pupilCharacteristic?: string | null;
    } | null;
    /**
     * Confidence interval for statistical values
     */
    confidence?: {
        lower?: number;
        upper?: number;
    } | null;
    /**
     * Optional metric metadata (included when includeMetadata=true)
     */
    metadata?: {
        category: string;
        subcategory: string;
        dataType: string;
        description: string;
        rangeMin?: number;
        rangeMax?: number;
        nationalAverage?: number;
        isHigherBetter?: boolean;
        units?: string;
        decimalPlaces?: number;
    };
}
/**
 * Options for querying metrics from schools
 */
export interface MetricsQueryOptions {
    /**
     * Array of school IDs to query metrics for
     */
    schoolIds: number[];
    /**
     * Array of academic year IDs (e.g., "GB_2022-2023")
     * @optional If not provided, metrics from the latest academic year will be returned automatically
     * If multiple years are specified, all matching metrics will be returned
     */
    academicYears?: string[];
    /**
     * Array of specific metric codes to query
     * Mutually exclusive with profile
     */
    metricCodes?: string[];
    /**
     * Pre-defined profile(s) of metrics to return
     * Mutually exclusive with metricCodes
     * Can be a single profile or an array of profiles
     */
    profile?: MetricProfile | MetricProfile[];
    /**
     * Student cohort type for filtering metrics
     * Only applied if explicitly specified
     */
    cohortType?: CohortType;
    /**
     * Reporting period type
     * Only applied if explicitly specified
     */
    period?: Period;
    /**
     * Period number (e.g., term 1, 2, 3 or month 1-12)
     * Required when period is specified and is 'termly' or 'monthly'
     */
    periodNumber?: number | null;
    /**
     * Include metric definitions metadata in response
     * @default false
     */
    includeMetadata?: boolean;
    /**
     * Maximum number of metrics to return
     * @default 50
     */
    limit?: number;
    /**
     * Number of metrics to skip (for pagination)
     * @default 0
     */
    offset?: number;
    /**
     * Prior attainment filter
     */
    priorAttainment?: PriorAttainment;
    /**
     * Pupil characteristic filter
     */
    pupilCharacteristic?: PupilCharacteristic;
}
/**
 * Response data structure for metrics endpoint
 */
export interface MetricsResponseData {
    /**
     * Array of metric data items
     */
    metrics: MetricDataItem[];
    /**
     * Metadata about the response
     */
    meta: {
        /**
         * Total number of metrics matching the query
         */
        total: number;
    };
}
/**
 * Complete response for the /metrics GET endpoint
 * This returns an object with an array of metrics, guaranteed to have empty arrays in error cases
 */
export type MetricsResponse = ObjectApiResponse<MetricsResponseData>;