# Meter Opportunities Setup Guide

## What's Been Built

I've created a complete **meter-opportunities** WordPress plugin with wave-based processing for downloading opportunities from SAM.gov (and eventually DIBBS and expiring contracts).

## File Structure

```
meter-opportunities/
├── admin/
│   ├── class-admin.php                    # Admin interface with AJAX handlers
│   ├── pages/
│   │   ├── page-dashboard.php             # Main dashboard with download controls
│   │   ├── page-settings.php              # Settings page (API keys, ES config)
│   │   └── page-sources.php               # Data source stats
│   └── js/
│       └── admin.js                       # AJAX handlers for UI interactions
├── includes/
│   ├── class-opportunities.php            # Main plugin class
│   ├── class-loader.php                   # Hook loader
│   ├── class-activator.php                # Creates indices, schedules cron jobs
│   ├── class-deactivator.php              # Cleanup on deactivation
│   ├── class-email-digest.php             # Daily email notifications
│   ├── data/
│   │   ├── class-sam-opportunities-fetcher.php  # Wave-based SAM.gov fetcher ✨
│   │   ├── class-dibbs-scraper.php        # DIBBS scraper (placeholder)
│   │   └── class-expiring-contracts.php   # Expiring contracts from meter-reports
│   └── search/
│       ├── class-elasticsearch-client.php # ES client
│       └── class-index-manager.php        # Index management
├── public/
│   └── class-public.php                   # Public-facing shortcodes
└── meter-opportunities.php                # Plugin bootstrap
```

## How to Use

### 1. Upload & Activate

1. Upload the `meter-opportunities` folder to `/wp-content/plugins/`
2. Activate the plugin in WordPress admin
3. You'll see a new **"Opportunities"** menu item

### 2. Configure Settings

Go to **Opportunities > Settings**:

- **SAM.gov API Key**: Enter your SAM.gov API key (same as the one you use for entity data)
- **Elasticsearch**: Leave blank to use meter-search settings, or configure separately
- **DIBBS**: Not yet implemented, leave blank for now

### 3. Download Opportunities

Go to **Opportunities > Dashboard**:

**Option 1: Custom Date Range**
- Select start and end dates
- Click "Download SAM Opportunities"
- Progress bar shows real-time status

**Option 2: Quick Downloads**
- "Download Today Only" - Just today's opportunities
- "Download Last 7 Days" - Initial seed for testing

**Initial Setup Recommendation:**
- Download last 30 days to seed your database
- Then run daily cron to keep it updated

## Wave/Ripple System

The SAM opportunities fetcher uses the same sophisticated wave/ripple architecture as your SAM entity downloader:

**Wave** = 30-second processing window
- Fetches as many opportunities as possible
- If time expires, saves progress and schedules next wave
- Prevents PHP timeouts

**Ripple** = Single API call (100 opportunities)
- Fetches from SAM.gov
- Indexes to Elasticsearch
- Checks wave timer
- Continues or pauses

**Progress Tracking:**
- Stored in `meter_opportunities_download_progress` option
- Tracks: offset, total_fetched, total_indexed, wave_start_time
- Dashboard shows real-time progress

## Cron Jobs

Automatically scheduled on activation:

1. `meter_opportunities_fetch_sam` - Daily at 2am (fetch yesterday's opportunities)
2. `meter_opportunities_sam_wave` - Triggered dynamically during downloads
3. `meter_opportunities_send_digests` - Daily at 6am (email notifications)
4. `meter_opportunities_cleanup` - Weekly cleanup of expired opportunities

## Dashboard Features

**Stats Overview:**
- Total opportunities count
- Active opportunities (response deadline hasn't passed)
- Closing soon (within 7 days)

**SAM.gov Download:**
- Date range picker
- Quick action buttons
- Real-time progress bar
- Status messages

**DIBBS (Coming Soon):**
- Placeholder for DIBBS scraping

**Expiring Contracts:**
- Pull from meter-reports data
- Configurable months ahead

**Elasticsearch Health:**
- Check cluster status
- Verify index connectivity

## What You Need to Do

1. **Enter SAM.gov API Key** in Settings
2. **Test with "Download Today"** to verify API connection
3. **Run initial seed** (last 30 days) to populate database
4. **Later**: Implement DIBBS scraper (requires understanding DIBBS HTML structure)
5. **Later**: Build heatmap visualization for public page

## How the Download Works

1. User clicks download button
2. AJAX call to `meter_opportunities_start_sam_download`
3. Initializes progress tracking
4. Schedules first wave with `wp_schedule_single_event`
5. Wave fires: `meter_opportunities_sam_wave` cron hook
6. Fetcher processes one wave (30 seconds max):
   - Fetch page from SAM.gov (100 opportunities)
   - Normalize data
   - Bulk index to Elasticsearch
   - Check timer
   - If time left, fetch next page
   - If time expired, save progress and schedule next wave
7. Repeat until all opportunities downloaded
8. Mark as complete

## Next Steps

- **Test the download** with today's data
- **Verify Elasticsearch indexing** is working
- **Create public-facing heatmap page** (the visualization you designed)
- **Implement DIBBS scraper** (when ready)
- **Add freemium access control** (integrate with meter-signups)

The foundation is solid and ready for you to build on!