🛍️ DealsHub - Your Ultimate eBay Deals Finder

Find the best deals on eBay with AI-powered search, real-time price tracking, and intelligent recommendations.

🔗 Live Demo: https://ebay-store.vercel.app

---

🏥 Repo Health

Overall health: 76/100 — Last updated: 2026-04-06

Dimension	Progress	Score	Weight
📝 README Quality	█████████░		20%
🔥 Commit Activity	██████████		20%
🌿 Repo Freshness	██████████		15%
📚 Documentation	███░░░░░░░		15%
⚙️ CI/CD Setup	██████░░░░		15%
🎯 Issue Response	██████████		10%
⭐ Community Signal	█░░░░░░░░░		5%

---

✨ Features

Core Features

• 🔍 Smart Search - AI-powered product search across eBay with autocomplete
• 💰 Live eBay Products - Real-time product data via eBay Browse API with OAuth 2.0
• 🤖 AI Chatbot - Personalized shopping recommendations
• 🎯 Deal of the Day - Curated daily deals with countdown timers
• ⭐ Favorites System - Save and track your favorite products
• 📧 Newsletter - Subscribe for exclusive deals and updates
• 🔔 Price Alerts - Get notified when prices drop
• 🔄 Recently Viewed - Track your browsing history
• 🎨 Product Comparison - Compare multiple products side-by-side
• 💸 Affiliate Tracking - eBay Partner Network integration for commission tracking

Technical Features

• ⚡ ISR (Incremental Static Regeneration) - Lightning-fast page loads with fresh content
• 🖼️ Image Optimization - AVIF/WebP with blur placeholders (zero layout shift)
• 🌙 Dark Mode - Beautiful UI with seamless light/dark theme switching
• 🎨 Responsive Design - Perfect on mobile, tablet, and desktop
• ♿ Accessibility - WCAG 2.1 AA compliant
• 📊 Analytics - Vercel Analytics & Speed Insights integrated
• 🔒 Security Middleware - Rate limiting, input validation, secure headers
• 🧪 Comprehensive Testing - 65%+ test coverage with Jest
• 🔄 24-Hour Product Caching - Optimized API usage with automatic refresh
• ✅ GitHub Actions CI - Automated lint, test, and build checks on every push/PR
• 📅 Daily Rotating Keywords - Fresh product variety every day

---

🚀 Quick Start

Prerequisites

• Node.js 20.x or higher
• npm 10.x or higher
• eBay Developer Account - Sign up here
• eBay Partner Network Account - Sign up here

Installation

# Clone the repository
git clone https://github.com/SamoTech/ebay-store.git
cd ebay-store

# Install dependencies
npm install

# Copy environment variables
cp .env.example .env.local

# Configure your eBay API credentials (see below)

# Start development server
npm run dev

Open http://localhost:3000 in your browser.

Environment Variables Setup

1. Get eBay Browse API Credentials (OAuth 2.0)

1. Visit eBay Developer Portal
2. Create a Production Application Keyset
3. Copy your Client ID and Client Secret

2. Get eBay Partner Network Campaign ID

1. Visit eBay Partner Network
2. Create a campaign and get your Campaign ID
3. This is used for affiliate commission tracking

3. Configure .env.local

# ═══════════════════════════════════════════════════════════
# eBay Browse API (OAuth 2.0) - REQUIRED for Live Products
# ═══════════════════════════════════════════════════════════
EBAY_CLIENT_ID=your_production_client_id
EBAY_CLIENT_SECRET=your_production_client_secret

# ═══════════════════════════════════════════════════════════
# eBay Partner Network - REQUIRED for Affiliate Tracking
# ═══════════════════════════════════════════════════════════
EBAY_CAMPAIGN_ID=your_campaign_id

# eBay API Configuration (Advanced - Optional)
EBAY_MARKETPLACE_ID=EBAY_US
EBAY_OAUTH_SCOPE=https://api.ebay.com/oauth/api_scope

# Other Services (Optional but Recommended)
GROQ_API_KEY=gsk_your_groq_api_key_here
WEB3FORMS_ACCESS_KEY=your_web3forms_access_key_here
NEXT_PUBLIC_GA_ID=G-XXXXXXXXXX

Important Notes:

• ❌ Do NOT use the old Finding API credentials (EBAY_APP_ID, EBAY_CERT_ID, EBAY_DEV_ID)
• ✅ Use OAuth 2.0 credentials (EBAY_CLIENT_ID, EBAY_CLIENT_SECRET) for Browse API
• 🔒 Never commit .env.local to version control

Verify eBay API Setup

npm run dev
# Visit http://localhost:3000/api/health

See SETUP_GUIDE.md for detailed configuration and troubleshooting.

---

📁 Project Structure

ebay-store/
├── app/                      # Next.js 16 App Router
├── components/              # React components (19 total)
├── contexts/                # React contexts (5 total)
├── lib/                     # Utilities & business logic
├── __tests__/              # Test suites (65%+ coverage)
├── agents/                 # AI Agent system documentation
├── docs/                   # Documentation (15+ files)
└── public/                 # Static assets

See full structure in docs/.

---

🔧 Tech Stack

Frontend

• Next.js 16 - React framework with App Router & ISR
• React 19 - UI library with Server Components
• TypeScript 5 - Type-safe development
• Tailwind CSS 4 - Utility-first styling

Backend & APIs

• Next.js API Routes - Serverless API endpoints
• eBay Browse API (OAuth 2.0) - Live product data & search
• eBay Partner Network - Affiliate link generation
• Groq AI - Chatbot intelligence

Testing & Quality

• Jest 29 + React Testing Library
• Coverage: 65%+ (Unit + Integration tests)

DevOps

• Vercel - Hosting & deployment
• GitHub Actions - CI pipeline

---

📚 Documentation

• Setup Guide - Detailed installation instructions
• API Documentation - All API endpoints
• Component Library - Component props & usage
• Testing Guide - How to write & run tests
• Performance Guide - ISR, caching, optimization
• Accessibility Checklist - WCAG 2.1 compliance

---

🧪 Testing

npm test                 # Run all tests
npm run test:watch       # Watch mode
npm run test:coverage    # Coverage report

Current Coverage: 65%+ ✅

---

⚡ Performance

Metric	Score
Performance	100/100
Accessibility	95/100
Best Practices	100/100
SEO	100/100

---

🚀 Deployment

See DEPLOYMENT_COMPLETE.md for detailed instructions.

---

🛡️ Security

• ✅ No exposed secrets — all API keys server-side only
• ✅ Rate limiting on all product APIs
• ✅ Input sanitization & validation
• ✅ Security headers via middleware
• ✅ OAuth 2.0 for eBay API access

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Write tests, ensure they pass: npm test
4. Commit: git commit -m 'Add amazing feature'
5. Push & open a Pull Request

See CONTRIBUTING.md for full guidelines.

---

📄 License

MIT License — see LICENSE file for details.

---

👨‍💻 Author

Ossama Hashim (SamoTech)

• 🌐 GitHub: @SamoTech
• 📧 Email: samo.hossam@gmail.com
• 📍 Location: Cairo, Egypt

---

Made with ❤️ using Next.js 16, React 19, and AI Agent System

Live Demo • Documentation • GitHub