npm package: @openpets/flights
Description: Flight search plugin for OpenCode - search for flights, compare prices, and find the best travel options
Latest version: 1.0.3

# Flights Plugin for OpenCode

A comprehensive flight search plugin that enables you to search for flights, find airport codes, and plan travel dates directly within OpenCode. This plugin uses the factory pattern and supports multiple flight search providers with automatic fallbacks.

## Features

- **Flight Search**: Search for one-way or round-trip flights between any airports
- **Real-time Pricing**: Get current flight prices from major airlines
- **Airport Lookup**: Find airport codes by city name or airport name
- **Travel Planning**: Calculate suggested travel dates based on your preferences
- **Multiple Providers**: Support for SerpAPI (Google Flights), RapidAPI, and Amadeus
- **Mock Mode**: Test the plugin without API keys using sample data

## Prerequisites

- OpenCode installed and configured
- Node.js 16+ (for running the plugin)
- API key from one of the supported providers (optional for testing)

## Supported Providers

### 1. SerpAPI (Recommended)
- **Description**: Provides Google Flights data with the best coverage and accuracy
- **Cost**: Free tier available (100 searches/month), paid plans starting at $50/month
- **Get API Key**: https://serpapi.com/
- **Best For**: Most users, best data quality and coverage

### 2. RapidAPI
- **Description**: Access to multiple flight search APIs
- **Cost**: Varies by API, free tiers available
- **Get API Key**: https://rapidapi.com/
- **Best For**: Alternative to SerpAPI, multiple API options

### 3. Amadeus
- **Description**: Professional flight search API used by travel agencies
- **Cost**: Free tier available (limited requests), paid tiers for production
- **Get API Key**: https://developers.amadeus.com/
- **Best For**: Professional applications, advanced features

## Setup

### 1. Install Dependencies

From the repository root:
```bash
pnpm install
```

### 2. Configure Environment

Copy the example environment file:
```bash
cd pets/flights
cp .env.example .env
```

Edit `.env` and add your API key:
```bash
SERPAPI_API_KEY=your_serpapi_key_here
FLIGHT_PROVIDER=serpapi
MAX_RESULTS=10
DEFAULT_CABIN_CLASS=economy
```

### 3. Configure OpenCode

Add the flights plugin to your OpenCode configuration in `opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "./pets/flights/index.ts"
  ]
}
```

## Available Tools

### 1. `search-flights`

Search for one-way or round-trip flights between airports.

**Parameters:**
- `from` (required): Departure airport code (3-letter IATA code)
- `to` (required): Arrival airport code (3-letter IATA code)
- `departureDate` (required): Departure date in YYYY-MM-DD format
- `returnDate` (optional): Return date for round-trip flights
- `adults` (optional): Number of adult passengers (default: 1)
- `children` (optional): Number of children (default: 0)
- `cabinClass` (optional): economy, premium_economy, business, or first
- `maxResults` (optional): Maximum number of results (default: 10)

**Examples:**
```bash
opencode run "search flights from LAX to JFK on 2025-01-15"
opencode run "search round trip flights from SFO to NYC departing 2025-01-15 returning 2025-01-22"
opencode run "search business class flights from LAX to LHR on 2025-03-01"
```

### 2. `search-airports`

Find airport codes by city name, airport name, or partial code.

**Parameters:**
- `query` (required): Search term (city/airport name)

**Examples:**
```bash
opencode run "find airport code for Los Angeles"
opencode run "search airports in Tokyo"
```

### 3. `calculate-travel-dates`

Calculate suggested travel dates for flexible planning.

**Parameters:**
- `daysFromNow` (optional): Days from today for departure (default: 30)
- `tripLength` (optional): Trip length in days (default: 7)

**Examples:**
```bash
opencode run "calculate travel dates 45 days from now for 10 day trip"
opencode run "suggest dates for a 5 day trip next month"
```

### 4. `get-provider-status`

Check active provider and configuration status.

**Example:**
```bash
opencode run "check provider status"
```

## Mock Mode (No API Key Required)

The plugin includes a mock provider for testing without API keys. It returns sample data for major airports and realistic flight information.

## Configuration Options

All configuration via environment variables in `.env`:

```bash
SERPAPI_API_KEY=your_key
FLIGHT_PROVIDER=serpapi
MAX_RESULTS=10
DEFAULT_CABIN_CLASS=economy
LOG_LEVEL=info
REQUEST_TIMEOUT=30000
```

## Common Use Cases

### Planning a Vacation
```bash
opencode run "calculate travel dates 30 days from now for 14 days"
opencode run "find airports in Hawaii"
opencode run "search round trip from LAX to HNL departing 2025-12-20 returning 2026-01-03"
```

### Business Travel
```bash
opencode run "search business class flights from SFO to NYC on 2025-01-15"
opencode run "find airports in New York"
```

## Troubleshooting

### "No flights found"
- Verify airport codes are valid 3-letter IATA codes
- Check dates are in YYYY-MM-DD format and in the future
- Ensure API key has available quota

### "Using mock data" warning
- No API key is configured
- Add valid API key to `.env` file

### Module resolution errors
- Ensure you're running from the openpets directory
- Check that all dependencies are installed with `pnpm install`

## Development

### Project Structure
```
pets/flights/
├── index.ts           # Main plugin implementation
├── package.json       # Plugin metadata
├── .env.example       # Environment template
├── README.md          # This file
└── reference/         # Python reference implementations
```

### Testing
```bash
npm run quickstart      # Quick test
npm run test:queries    # Test all queries
npm run test:scenarios  # Test all scenarios
```

## License

MIT

## Acknowledgments

This plugin merges functionality from:
- [flights-mcp](https://github.com/ravinahp/flights-mcp) - Duffel API integration
- [google-flights-mcp](https://github.com/fastmcp/google-flights-mcp) - Fast-flights integration