holiday-travel-app/TERMINAL_USAGE_GUIDE.md

# Holiday Travel App - Terminal Usage Guide

This guide shows you how to use the Holiday Travel App **entirely from the terminal** using PowerShell commands (no web browser needed).

## Prerequisites

Make sure the development server is running:
```powershell
cd "d:\Projects\Dev\Holiday Travel App"
npm run dev
```

The server will be available at `http://localhost:4000`

---

## Example 1: Basic Caribbean Search

Search for flights from Ottawa to Caribbean destinations for a holiday trip:

```powershell
# Create the search criteria
$searchData = @{
    origin = "YOW"
    destinations = @("CUN", "PUJ", "MBJ")  # Cancun, Punta Cana, Montego Bay
    startDate = "2025-12-15"
    endDate = "2026-01-15"
    tripLengthMin = 5
    tripLengthMax = 9
    budget = 1000
    currency = "CAD"
    nonStopOnly = $false
    sources = @("Deals", "Skyscanner", "GoogleFlights", "AirCanada")
} | ConvertTo-Json -Depth 3

# Send the request
$response = Invoke-RestMethod -Uri "http://localhost:4000/api/search" -Method POST -Body $searchData -ContentType "application/json"

# View all results
$response.results

# View just the first 5 results
$response.results | Select-Object -First 5 | Format-Table title, source, price, nights
```

---

## Example 2: Budget-Friendly European Search

Looking for cheap flights to Europe with non-stop preference:

```powershell
$euroSearch = @{
    origin = "YYZ"  # Toronto
    destinations = @("LHR", "CDG", "FCO", "BCN")  # London, Paris, Rome, Barcelona
    startDate = "2026-06-01"
    endDate = "2026-07-15"
    tripLengthMin = 7
    tripLengthMax = 14
    budget = 800
    currency = "CAD"
    nonStopOnly = $true
    sources = @("Deals", "Skyscanner", "GoogleFlights", "AirCanada")
} | ConvertTo-Json -Depth 3

$euroResults = Invoke-RestMethod -Uri "http://localhost:4000/api/search" -Method POST -Body $euroSearch -ContentType "application/json"

# Show only deals under $750
$euroResults.results | Where-Object { $_.price -lt 750 } | Format-Table
```

---

## Example 3: Quick Weekend Getaway

Short trips, flexible on destinations:

```powershell
$weekendSearch = @{
    origin = "YUL"  # Montreal
    destinations = @("NYC", "BOS", "YYZ", "YOW")  # New York, Boston, Toronto, Ottawa
    startDate = "2025-11-15"
    endDate = "2025-12-15"
    tripLengthMin = 2
    tripLengthMax = 4
    currency = "CAD"
    nonStopOnly = $false
    sources = @("Skyscanner", "GoogleFlights", "AirCanada")
} | ConvertTo-Json -Depth 3

$weekendResults = Invoke-RestMethod -Uri "http://localhost:4000/api/search" -Method POST -Body $weekendSearch -ContentType "application/json"

# Display results grouped by destination
$weekendResults.results | Group-Object destination | Format-Table Count, Name
```

---

## Example 4: Deal Sites Only (No Link Generation)

Only fetch from curated deal sites like YOWDeals, YYZDeals, etc.:

```powershell
$dealsOnly = @{
    origin = "YVR"  # Vancouver
    destinations = @("HNL", "LAX", "SEA")  # Hawaii, LA, Seattle
    startDate = "2026-02-01"
    endDate = "2026-03-31"
    tripLengthMin = 5
    tripLengthMax = 10
    sources = @("Deals")  # Only deal sites
} | ConvertTo-Json -Depth 3

$dealsResults = Invoke-RestMethod -Uri "http://localhost:4000/api/search" -Method POST -Body $dealsOnly -ContentType "application/json"

$dealsResults.results | Format-List
```

---

## Example 5: Export Results to CSV

Save search results to a CSV file for further analysis:

```powershell
$searchData = @{
    origin = "YYC"  # Calgary
    destinations = @("LAX", "LAS", "PHX")
    startDate = "2026-01-15"
    endDate = "2026-02-28"
    tripLengthMin = 5
    tripLengthMax = 7
    budget = 600
    currency = "CAD"
    sources = @("Skyscanner", "GoogleFlights")
} | ConvertTo-Json -Depth 3

$results = Invoke-RestMethod -Uri "http://localhost:4000/api/search" -Method POST -Body $searchData -ContentType "application/json"

# Export to CSV
$results.results | Export-Csv -Path "travel_deals_$(Get-Date -Format 'yyyy-MM-dd').csv" -NoTypeInformation

Write-Host "Results exported to travel_deals_$(Get-Date -Format 'yyyy-MM-dd').csv"
```

---

## Example 6: Filter and Sort Results

Advanced filtering and sorting:

```powershell
$searchData = @{
    origin = "YOW"
    destinations = @("MCO", "FLL", "TPA")  # Orlando, Fort Lauderdale, Tampa
    startDate = "2026-03-01"
    endDate = "2026-04-15"
    tripLengthMin = 6
    tripLengthMax = 9
    currency = "CAD"
    sources = @("Deals", "Skyscanner", "GoogleFlights", "AirCanada")
} | ConvertTo-Json -Depth 3

$results = Invoke-RestMethod -Uri "http://localhost:4000/api/search" -Method POST -Body $searchData -ContentType "application/json"

# Filter: Only show results with prices
$withPrices = $results.results | Where-Object { $null -ne $_.price }

# Sort by price (cheapest first)
$sortedByPrice = $withPrices | Sort-Object price

# Display top 10 cheapest
$sortedByPrice | Select-Object -First 10 | Format-Table title, price, currency, nights, source
```

---

## Example 7: Compare Multiple Sources

Get results and compare which source provides the most deals:

```powershell
$compareSearch = @{
    origin = "YEG"  # Edmonton
    destinations = @("YVR", "YYC", "YWG")
    startDate = "2025-12-01"
    endDate = "2026-01-31"
    tripLengthMin = 3
    tripLengthMax = 5
    sources = @("Skyscanner", "GoogleFlights", "AirCanada")
} | ConvertTo-Json -Depth 3

$compareResults = Invoke-RestMethod -Uri "http://localhost:4000/api/search" -Method POST -Body $compareSearch -ContentType "application/json"

# Count results by source
$compareResults.results | Group-Object source | Select-Object Name, Count | Sort-Object Count -Descending
```

---

## Example 8: Use with cURL (Alternative to PowerShell)

If you prefer using `curl` in PowerShell:

```powershell
curl.exe -X POST "http://localhost:4000/api/search" `
  -H "Content-Type: application/json" `
  -d '{
    "origin": "YOW",
    "destinations": ["CUN", "PUJ"],
    "startDate": "2025-12-20",
    "endDate": "2026-01-10",
    "tripLengthMin": 7,
    "tripLengthMax": 10,
    "budget": 900,
    "currency": "CAD",
    "sources": ["Deals", "Skyscanner"]
  }'
```

---

## Understanding the Response

The API returns JSON with this structure:

```json
{
  "results": [
    {
      "id": "unique-id",
      "title": "Ottawa → Cancun (7 nights)",
      "source": "Skyscanner Link",
      "link": "https://www.skyscanner.ca/...",
      "price": 685,
      "currency": "CAD",
      "startDate": "2025-12-20",
      "endDate": "2025-12-27",
      "nights": 7,
      "origin": "YOW",
      "destination": "CUN",
      "stops": null,
      "score": 9815
    }
  ]
}
```

---

## Available Airport Codes (Examples)

- **Canada**: YOW (Ottawa), YYZ (Toronto), YUL (Montreal), YVR (Vancouver), YYC (Calgary), YEG (Edmonton)
- **USA**: NYC (New York), LAX (Los Angeles), MIA (Miami), ORD (Chicago), SEA (Seattle)
- **Caribbean**: CUN (Cancun), PUJ (Punta Cana), MBJ (Montego Bay), NAS (Nassau)
- **Europe**: LHR (London), CDG (Paris), FCO (Rome), BCN (Barcelona), AMS (Amsterdam)

---

## Troubleshooting

**Server not responding?**
```powershell
# Check if server is running
Get-Process -Name node -ErrorAction SilentlyContinue

# Restart the server if needed
cd "d:\Projects\Dev\Holiday Travel App"
npm run dev
```

**Invalid date format?**
- Dates must be in `YYYY-MM-DD` format (e.g., "2025-12-31")

**No results returned?**
- Try removing budget constraints
- Set `nonStopOnly` to `$false`
- Expand the date range
- Add more destination options

---

## Tips for Best Results

1. **Multiple Destinations**: Add 3-5 destination codes for more options
2. **Flexible Dates**: Wider date ranges (30-60 days) yield more results
3. **Trip Length Range**: Use a range (e.g., 5-9 nights) instead of exact days
4. **Mix Sources**: Enable all sources for comprehensive results
5. **Budget Buffer**: Set budget 10-15% higher than your actual limit
6. **Off-Peak Travel**: Search for shoulder seasons for better deals

---

## Automation Example

Create a scheduled task to search daily and email results:

```powershell
# search_and_notify.ps1
$searchData = @{
    origin = "YOW"
    destinations = @("CUN", "PUJ", "MBJ")
    startDate = "2026-01-15"
    endDate = "2026-02-28"
    tripLengthMin = 7
    tripLengthMax = 10
    budget = 800
    currency = "CAD"
    sources = @("Deals")
} | ConvertTo-Json -Depth 3

$results = Invoke-RestMethod -Uri "http://localhost:4000/api/search" -Method POST -Body $searchData -ContentType "application/json"

# Get deals under $750
$goodDeals = $results.results | Where-Object { $_.price -lt 750 }

if ($goodDeals.Count -gt 0) {
    $goodDeals | Export-Csv -Path "good_deals.csv" -NoTypeInformation
    Write-Host "Found $($goodDeals.Count) deals under $750!"
    # Add email notification here if needed
}
```

Run with Task Scheduler:
```powershell
$trigger = New-ScheduledTaskTrigger -Daily -At 9am
$action = New-ScheduledTaskAction -Execute "PowerShell.exe" -Argument "-File C:\path\to\search_and_notify.ps1"
Register-ScheduledTask -TaskName "DailyTravelDeals" -Trigger $trigger -Action $action
```

---

## Docker Usage

If using Docker instead of local dev server:

```powershell
# Build and run
docker compose up -d

# Then use the same API calls as above
$searchData = @{ ... } | ConvertTo-Json -Depth 3
$response = Invoke-RestMethod -Uri "http://localhost:4000/api/search" -Method POST -Body $searchData -ContentType "application/json"
```

---

Enjoy finding your next holiday deal from the command line! 🏖️✈️