@drfrost/bods-js/src/types/common.ts

JavaScript client for the UK's Bus Open Data Service (BODS) API

/**
 * Common types and interfaces used across the BODS API client
 */

/**
 * Base configuration for API requests
 */
export interface ApiConfig {
  /** The API key for accessing BODS services */
  apiKey: string;
  /** Base URL for the BODS API */
  baseUrl?: string;
  /** Request timeout in milliseconds */
  timeout?: number;
}

/**
 * Standard error response structure
 */
export interface ErrorResponse {
  detail: string;
}

/**
 * Pagination parameters for list requests
 */
export interface PaginationParams {
  /** Maximum number of records to return (max 100) */
  limit?: number;
  /** Offset for pagination */
  offset?: number;
}

/**
 * Standard paginated response structure
 */
export interface PaginatedResponse<T> {
  /** Total count of items */
  count: number;
  /** URL for next page if available */
  next: string | null;
  /** URL for previous page if available */
  previous: string | null;
  /** Array of results */
  results: T[];
}

/**
 * Date range filter parameters
 */
export interface DateRangeParams {
  /** Start date for filtering */
  startDate?: Date | string;
  /** End date for filtering */
  endDate?: Date | string;
}

/**
 * Geographic bounding box for location-based queries
 * Format: [minLongitude, minLatitude, maxLongitude, maxLatitude]
 */
export type BoundingBox = [number, number, number, number];

/**
 * Administrative area information
 */
export interface AdminArea {
  /** ATCO area code */
  atco_code: string;
  /** Area name */
  name: string;
}

/**
 * Locality information
 */
export interface Locality {
  /** Gazetteer ID */
  gazetter_id: string;
  /** Locality name */
  name: string;
}

/**
 * Data quality rating
 */
export type DataQualityRating = 'red' | 'amber' | 'green';

/**
 * Dataset status
 */
export type DatasetStatus = 'published' | 'error' | 'inactive';