← back to Wine Finder

README.md

275 lines

# Red Thunder Wine Tracker

A secure, luxury-themed Wine Pricing Tracker web platform for viewing and analyzing wine prices from K&L Wine Merchants and other sources.

## Features

- **Wine Search**: Search wines by name with real-time scraping from K&L Wine Merchants
- **Quick Access**: Instant search buttons for FOXEN and NAVARRO wineries
- **Price Tracking**: Automatic logging of all wine prices to Google Sheets
- **Historical Analytics**: View price trends over time with interactive charts
- **Price Spike Alerts**: Automatic detection of rapid price increases (>20% by default)
- **Slack Notifications**: Real-time alerts sent to Slack when price spikes are detected
- **Secure Authentication**: Password-protected access to the platform
- **Luxury UI**: Maximalist design inspired by Saks Fifth Avenue (black & white theme)

## Prerequisites

- Node.js (v16 or higher)
- Google Cloud account with Sheets API enabled
- Slack workspace with webhook access
- Ubuntu server with port 9222 available

## Installation

### 1. Clone and Install Dependencies

```bash
cd /root/WebsitesMisc/WineFinder
npm install
```

### 2. Set Up Google Sheets API

#### Create a Google Cloud Project

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable the Google Sheets API:
   - Navigate to "APIs & Services" → "Library"
   - Search for "Google Sheets API"
   - Click "Enable"

#### Create a Service Account

1. Go to "APIs & Services" → "Credentials"
2. Click "Create Credentials" → "Service Account"
3. Fill in the service account details
4. Click "Create and Continue"
5. Grant the service account appropriate roles (optional)
6. Click "Done"

#### Generate Service Account Key

1. Click on the created service account
2. Go to the "Keys" tab
3. Click "Add Key" → "Create New Key"
4. Choose "JSON" format
5. Download the JSON file
6. Save it as `google-credentials.json` in the project root directory

#### Share the Google Sheet

1. Create a new Google Sheet named "Red Thunder Wine Tracker"
2. Note the Sheet ID from the URL:
   `https://docs.google.com/spreadsheets/d/SHEET_ID_HERE/edit`
3. Open the JSON credentials file and find the `client_email` field
4. Share your Google Sheet with this email address (give it "Editor" access)

### 3. Set Up Slack Webhook

#### Create a Slack App

1. Go to [Slack API](https://api.slack.com/apps)
2. Click "Create New App" → "From scratch"
3. Name your app (e.g., "Red Thunder Wine Tracker")
4. Select your workspace (designerwallc-hyg8426.slack.com)

#### Enable Incoming Webhooks

1. In your app settings, go to "Incoming Webhooks"
2. Toggle "Activate Incoming Webhooks" to ON
3. Click "Add New Webhook to Workspace"
4. Select the channel where you want alerts (e.g., #wine-alerts)
5. Click "Allow"
6. Copy the Webhook URL (starts with `https://hooks.slack.com/services/...`)

### 4. Configure Environment Variables

Create a `.env` file in the project root:

```bash
cp .env.example .env
```

Edit the `.env` file with your actual credentials:

```env
PORT=9222
NODE_ENV=production

ADMIN_USER=admin
ADMIN_PASS=2025
SESSION_SECRET=your-random-secret-key-here

GOOGLE_SHEET_ID=your-google-sheet-id-here
GOOGLE_APPLICATION_CREDENTIALS=./google-credentials.json

SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

PRICE_SPIKE_THRESHOLD=20
```

**Important**: Never commit the `.env` file or `google-credentials.json` to version control!

### 5. Configure Firewall

Open port 9222 on your server:

```bash
# For UFW (Ubuntu Firewall)
sudo ufw allow 9222/tcp

# Verify
sudo ufw status
```

## Running the Application

### Development Mode

```bash
npm run dev
```

### Production Mode

```bash
npm start
```

The application will start on port 9222. You can access it at:

```
http://your-server-ip:9222
```

## Usage

### Login

1. Navigate to `http://your-server-ip:9222`
2. Enter credentials:
   - Username: `admin` (or as configured in .env)
   - Password: `2025` (or as configured in .env)

### Search for Wines

1. **Manual Search**: Type a wine name in the search box and click "SEARCH"
2. **Quick Search**: Click "FOXEN" or "NAVARRO" buttons for instant results

### View Results

- Results are displayed in a luxury-themed table
- Sort by: Name, Price (Low/High), or Rating
- Click "VIEW PRICE HISTORY" to see price trends over time
- Click "VIEW ON SITE" to open the wine listing on K&L

### Price Alerts

- Automatic detection when prices increase >20% (configurable)
- Alerts displayed at the top of the page with a red border
- Slack notifications sent automatically to configured channel

### Price History Charts

- Click "VIEW PRICE HISTORY" on any wine
- Interactive chart shows price changes over time
- Data sourced from Google Sheets historical logs

## Architecture

### Backend (Node.js + Express)

- `server.js` - Main application server
- `routes/auth.js` - Authentication endpoints
- `routes/scraper.js` - Wine search and scraping endpoints
- `routes/history.js` - Historical data endpoints
- `services/klWineScraper.js` - K&L Wine Merchants scraper
- `services/googleSheets.js` - Google Sheets integration
- `services/slackNotifier.js` - Slack webhook integration

### Frontend

- `public/login.html` - Login page
- `public/index.html` - Main application
- `public/css/` - Stylesheets (luxury black & white theme)
- `public/js/` - Client-side JavaScript

### Data Storage

- **Google Sheets**: "Red Thunder Wine Tracker" sheet
- Columns: Timestamp, Wine Name, Vintage, Price, Rating, Source, Availability, URL, Search Query

## Security Features

- **Authentication**: Session-based login required for all pages
- **Input Sanitization**: All user inputs are sanitized to prevent XSS/injection
- **Helmet.js**: HTTP security headers
- **Rate Limiting**: 100 requests per 15 minutes per IP
- **Environment Variables**: Sensitive credentials stored securely
- **HTTPS Ready**: CSP headers configured for secure deployment

## API Endpoints

### Authentication
- `POST /auth/login` - Login with username/password
- `GET /auth/status` - Check authentication status
- `GET /logout` - Logout and destroy session

### Wine Search
- `POST /api/scraper/search` - Search wines by query
- `GET /api/scraper/foxen` - Quick search for FOXEN
- `GET /api/scraper/navarro` - Quick search for NAVARRO

### History
- `GET /api/history/wine?name=WINE_NAME` - Get price history for a wine

## Troubleshooting

### Google Sheets Not Working

1. Verify the service account email has access to the sheet
2. Check that the `GOOGLE_SHEET_ID` is correct in `.env`
3. Ensure `google-credentials.json` is in the project root
4. Check server logs for Google API errors

### Slack Notifications Not Sending

1. Verify the webhook URL is correct in `.env`
2. Check that the Slack app is added to the channel
3. Test the webhook URL with curl:
   ```bash
   curl -X POST -H 'Content-type: application/json' --data '{"text":"Test"}' YOUR_WEBHOOK_URL
   ```

### Cannot Access the Site

1. Check that the server is running: `ps aux | grep node`
2. Verify port 9222 is open: `sudo ufw status`
3. Check server logs for errors
4. Ensure you're using the correct IP address

### Scraper Not Finding Wines

1. K&L Wine Merchants may have changed their HTML structure
2. Check the `services/klWineScraper.js` file and update selectors if needed
3. Verify your server can access klwines.com (not blocked by firewall)

## Future Enhancements

- Add more wine retailers (Wine.com, Vivino, etc.)
- Implement user-defined price alerts
- Add wine favorites/watchlist
- Export data to CSV/PDF
- Email notifications in addition to Slack
- Mobile app version

## Support

For issues or questions, contact Steve Abrams at steve@designerwallcoverings.com

## License

Private/Internal Use Only