parksapi CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

ParksAPI is a TypeScript library for fetching real-time theme park data (wait times, schedules, entities) from 75+ park implementations, serving ~118 destination entities worldwide. All park implementations live in src/parks/.

Key Requirement: Node 24+, npm 11+

Skills & Agents

Detailed implementation guides live in .claude/ — always check these before writing park code:

• .claude/skills/implementing-parks.md — Complete guide for building new park destinations: scaffold, decorators, entity mapping, live data, schedules, validation workflow, tips & tricks, and 12 reference implementations
• .claude/agents/park-ts-migrator.md — Agent for migrating JS park implementations to TypeScript

Common Commands

npm run build          # Compile TypeScript to dist/
npm run watch          # Auto-recompile on changes
npm run dev            # Test all parks via harness
npm run dev -- <id>    # Test specific park (e.g. universalorlando)
npm run dev -- --list  # List available park IDs
npm test               # Run Vitest tests
npm run test:coverage  # Coverage report
npm run health         # Health check all endpoints
npm run har -- <file>  # Analyse HAR capture

Architecture

Decorator-Based Design

@config (src/config.ts)

Automatic configuration loading. Priority: instance config > env vars > prefixed env vars > defaults.

Property decorator marks properties for config injection. @destinationController auto-applies the class-level @config — never add @config to a class that uses @destinationController.

@destinationController({category: 'MyCategory'})
export class MyPark extends Destination {
  @config apiKey: string = '';       // Reads MYPARK_APIKEY env var
  @config timeout: number = 5000;    // Reads MYPARK_TIMEOUT, coerced to number
  @config enabled: boolean = true;   // Reads MYPARK_ENABLED, coerced to boolean

  constructor(options?: DestinationConstructor) {
    super(options);
    this.addConfigPrefix('MYPARK');   // Also checks MYPARK_* env vars
  }
}