parksapi: Instructions file for Claude Code

CLAUDE.md

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

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 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 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.

No hardcoded URLs or secrets — use empty string defaults ('') and configure via .env.

@cache (src/cache.ts)

SQLite-backed caching with TTL support. Database: ./cache.sqlite (override with CACHE_DB_PATH).

Lifetime from the environment: {CLASSNAME}_{METHODNAME}_CACHESECONDS (or {PREFIX}_{METHODNAME}_CACHESECONDS for a registered prefix) replaces ttlSeconds here and cacheSeconds on @http at call time. EUROPAPARK_FETCHSEASONS_CACHESECONDS=600 polls the seasons every 10 minutes instead of 6 hours; 0 stops caching. A callback lifetime is not replaced.

Cache key collisions in base classes: When multiple parks share a base class, use getCacheKeyPrefix() to prevent collisions:

getCacheKeyPrefix(): string {
  return `attractionsio:${this.parkId}`;
}
// Keys become: attractionsio:1:ClassName:methodName:[args]