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

TypeScript type definitions for Vepler Schools Service

/**
 * Metrics Time Series Endpoint Types
 *
 * Type definitions for the optimized metrics API endpoint
 * specifically designed for time series visualization.
 */
import { ObjectApiResponse } from '../common';
import { MetricProfile } from '../../models/metric-profiles';
/**
 * Time-series metric data with a flattened structure
 * where each metric is a property on the series item
 */
export interface TimeSeriesItem {
    /**
     * Time period identifier (e.g., "2023-2024")
     */
    timePeriod: string;
    /**
     * Unix timestamp in milliseconds for the time period
     */
    timestamp: number;
    /**
     * Granularity of the data point
     */
    granularity: 'annual' | 'termly' | 'monthly';
    /**
     * Dynamic properties for each metric code
     * The key is the metric code and the value is the metric value
     */
    [metricCode: string]: string | number | null;
}
/**
 * Metric definition with metadata
 */
export interface MetricDefinitionWithMetadata {
    /**
     * Unique identifier for the metric
     */
    id: number;
    /**
     * Metric code
     */
    code: string;
    /**
     * Human-readable description of the metric
     */
    description: string;
    /**
     * Category of the metric (e.g., "attendance", "attainment")
     */
    category: string;
    /**
     * Additional metadata for the metric
     */
    metadata: {
        /**
         * Minimum value in the expected range
         */
        rangeMin?: number;
        /**
         * Maximum value in the expected range
         */
        rangeMax?: number;
        /**
         * National average for comparison
         */
        nationalAverage?: number;
        /**
         * Whether higher values are better
         */
        isHigherBetter?: boolean;
        /**
         * Units for the metric (e.g., "%", "points")
         */
        units?: string;
        /**
         * Number of decimal places to display
         */
        decimalPlaces?: number;
        /**
         * Whether the metric has confidence intervals
         */
        hasConfidenceIntervals?: boolean;
    };
}
/**
 * Response metadata
 */
export interface MetricsTimeSeriesMetadata {
    /**
     * API version
     */
    version: string;
    /**
     * Timestamp when the data was generated
     */
    generatedAt: string;
    /**
     * Data quality score (0-1)
     */
    dataQuality?: number;
    /**
     * Data coverage score (0-1)
     */
    coverage?: number;
    /**
     * Cache key for the response
     */
    cacheKey?: string;
    /**
     * Error message if any
     */
    error?: string;
}
/**
 * Response data for metrics time series endpoint
 */
export interface MetricsTimeSeriesResponseData {
    /**
     * Array of time series data points
     */
    series: TimeSeriesItem[];
    /**
     * Array of metric definitions
     */
    metrics: MetricDefinitionWithMetadata[];
    /**
     * Optional metadata about the response
     */
    metadata: MetricsTimeSeriesMetadata;
}
/**
 * Options for querying time series metrics
 */
export interface MetricsTimeSeriesQueryOptions {
    /**
     * Array of academic year IDs (e.g., "2023-2024")
     * If not provided, metrics from all available academic years 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
     */
    profile?: MetricProfile | MetricProfile[];
    /**
     * Student cohort type for filtering metrics
     * Default is "all"
     */
    cohortType?: string;
    /**
     * Contextual factors for advanced filtering
     */
    contextualFactors?: {
        priorAttainment?: 'low' | 'medium' | 'high';
        pupilCharacteristic?: 'fsm' | 'eal' | 'sen' | 'none';
    };
    /**
     * Granularity of the data
     * Default is "annual"
     */
    granularity?: 'annual' | 'termly' | 'monthly';
}
/**
 * Complete response for the metrics time series endpoint
 * This returns an object with arrays for series and metrics, guaranteed to have empty arrays in error cases
 */
export type MetricsTimeSeriesResponse = ObjectApiResponse<MetricsTimeSeriesResponseData>;