@drfrost/bods-js/src/bods-client.ts

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

import type { ApiConfig } from './types/index.js';
import { HttpClient, TimetablesClient, FaresClient, AVLClient, DisruptionsClient } from './client/index.js';

/**
 * Main BODS (Bus Open Data Service) API Client
 * 
 * This client provides access to all BODS APIs:
 * - Timetables: Bus schedules and routes
 * - Fares: Bus fare information  
 * - AVL: Real-time vehicle locations
 * - Disruptions: Service disruption information
 * 
 * @example
 * ```typescript
 * import { BODSClient } from 'bods-js';
 * 
 * const client = new BODSClient({
 *   apiKey: 'your-api-key-here'
 * });
 * 
 * // Search for timetables
 * const timetables = await client.timetables.search({
 *   noc: ['SCMN'],
 *   status: 'published'
 * });
 * 
 * // Get real-time vehicle locations
 * const vehicles = await client.avl.getSIRIVM({
 *   operatorRef: ['SCMN']
 * });
 * 
 * // Get current service disruptions
 * const disruptions = await client.disruptions.getCurrent();
 * ```
 */
export class BODSClient {
  /** HTTP client for making API requests */
  private readonly httpClient: HttpClient;
  
  /** Timetables API client */
  public readonly timetables: TimetablesClient;
  
  /** Fares API client */
  public readonly fares: FaresClient;
  
  /** Automatic Vehicle Location API client */
  public readonly avl: AVLClient;
  
  /** Disruptions API client */
  public readonly disruptions: DisruptionsClient;

  /**
   * Create a new BODS API client
   * 
   * @param config - API configuration including API key
   * 
   * @example
   * ```typescript
   * const client = new BODSClient({
   *   apiKey: 'your-api-key-here',
   *   timeout: 30000 // optional: request timeout in milliseconds
   * });
   * ```
   */
  constructor(config: ApiConfig) {
    this.httpClient = new HttpClient(config);
    this.timetables = new TimetablesClient(this.httpClient);
    this.fares = new FaresClient(this.httpClient);
    this.avl = new AVLClient(this.httpClient);
    this.disruptions = new DisruptionsClient(this.httpClient);
  }

  /**
   * Get API client configuration info
   */
  getConfig(): Omit<ApiConfig, 'apiKey'> {
    return {
      baseUrl: this.httpClient['baseUrl'],
      timeout: this.httpClient['timeout']
    };
  }

  /**
   * Test API connectivity
   * 
   * @returns Promise resolving to true if API is accessible
   * 
   * @example
   * ```typescript
   * const isConnected = await client.testConnection();
   * if (isConnected) {
   *   console.log('API is accessible');
   * }
   * ```
   */
  async testConnection(): Promise<boolean> {
    try {
      await this.timetables.search({ limit: 1 });
      return true;
    } catch {
      return false;
    }
  }
}