ns-trains

# NS Trains Skill

Check Dutch train schedules, departures, disruptions, and plan journeys using the official NS (Nederlandse Spoorwegen) API.

## Setup

### 1. Get an NS subscription key

1. Go to [NS API Portal](https://apiportal.ns.nl/)
2. Create an account and subscribe to the **Ns-App** product (free tier available)
3. Copy your **Primary Key**

### 2. Set Environment Variables

```bash
export NS_SUBSCRIPTION_KEY="your-subscription-key-here"   # preferred
# Back-compat:
export NS_API_KEY="$NS_SUBSCRIPTION_KEY"                   # legacy name still supported

# Optional: Configure commute stations for quick shortcuts
export NS_HOME_STATION="Utrecht Centraal"
export NS_WORK_STATION="Amsterdam Zuid"
```

For security, prefer injecting these env vars via your runtime secret mechanism rather than committing them anywhere. Avoid printing or sharing your subscription key.

## Quick Usage

### 🚆 Commute shortcuts
```bash
node {baseDir}/scripts/commute.mjs --to-work   # Morning: Home → Work
node {baseDir}/scripts/commute.mjs --to-home   # Evening: Work → Home
```

### Plan any journey
```bash
node {baseDir}/scripts/journey.mjs --from "Utrecht Centraal" --to "Amsterdam Zuid"
```

### Check departures from a station
```bash
node {baseDir}/scripts/departures.mjs --station "Amsterdam Centraal"
```

### Check arrivals at a station
```bash
node {baseDir}/scripts/arrivals.mjs --station "Rotterdam Centraal"
```

### Search for stations
```bash
node {baseDir}/scripts/stations.mjs amsterdam
node {baseDir}/scripts/stations.mjs --search "den haag"
```

### Check current disruptions
```bash
node {baseDir}/scripts/disruptions.mjs
node {baseDir}/scripts/disruptions.mjs --from "Utrecht" --to "Amsterdam"
```

## Natural Language

Just ask:
- "When is the next train to Amsterdam?"
- "Check trains from Utrecht to Rotterdam"
- "Any train disruptions today?"
- "Plan my commute to work"
- "What time does the train arrive?"

## Output

Returns journey options with:
- Departure/arrival times...