# Yupoo Product Image Downloader - Chrome Extension

A powerful Manifest V3 Chrome extension that automatically downloads all product images from Yupoo-style gallery pages, organizing them by product into individual folders.

## Features

✨ **Automatic Product Detection** - Scans gallery pages to find all product cards
🖼️ **Complete Image Collection** - Downloads all images from each product's detail page
📁 **Organized Downloads** - Creates one folder per product with numbered images
🔄 **Retry Logic** - Automatically retries failed downloads
⚙️ **Concurrency Control** - Limit simultaneous downloads to avoid overwhelming the server
🔀 **Deduplication** - Prevents downloading the same image twice in a session
📋 **Progress Tracking** - Real-time updates on scanning and downloading status
🛠️ **Easy Customization** - Simple selector configuration for different website structures
✅ **Rate Limiting** - Automatic delays between requests to be respectful to servers

## Installation

### 1. Prepare the Extension

Clone or download this directory to your computer. You should have these files:
```
yupoo-downloader/
  ├── manifest.json
  ├── popup.html
  ├── popup.js
  ├── styles.css
  ├── background.js
  ├── content.js
  └── README.md
```

### 2. Load Extension in Chrome

1. Open Chrome and navigate to `chrome://extensions/`
2. Enable **Developer mode** (toggle in the top-right corner)
3. Click **"Load unpacked"**
4. Select the `yupoo-downloader` folder
5. The extension should now appear in your extensions list
6. Pin it to the toolbar for easy access (click the puzzle icon)

### 3. Grant Permissions

When you first use the extension, Chrome will ask for permissions:
- **Download files** - Needed to save images
- **Access current tab** - Needed to scan the page
- **Access all websites** - Needed to fetch product detail pages

Click "Allow" to proceed.

## Usage

### Basic Workflow

1. **Navigate to a Yupoo gallery page** with products you want to download
2. **Click the extension icon** in your toolbar
3. **Click "🔍 Scan Products"** - The extension will find all products on the current page
4. **Adjust settings** if needed:
   - Set "Max Concurrent Downloads" (1-10, default 2)
5. **Click "⬇️ Download All"** - Downloads will begin automatically
6. **Monitor progress** in the activity log and statistics
7. **Downloads save to** your browser's default download folder

### Download Structure

Images are organized like this:
```
Downloads/
  ├── 3me10101430/
  │   ├── 01.jpg
  │   ├── 02.jpg
  │   └── 03.jpg
  ├── 3mf10083295/
  │   ├── 01.jpg
  │   ├── 02.jpg
  │   ├── 03.jpg
  │   └── 04.jpg
  └── product_001/
      ├── 01.jpg
      └── 02.jpg
```

## Customization

The extension is designed to work with Yupoo and similar gallery sites, but websites vary in their HTML structure. You can customize the selectors to match your target website.

### Editing CSS Selectors

#### For Gallery Page (Finding Products)

Edit the `SELECTORS` object in **`content.js`** (around line 15):

```javascript
const SELECTORS = {
  // The container div for each product tile/card
  productCard: [
    'div.item',                    // Try these in order
    'div.product-item',
    'div.product-card',
    // Add more selectors that match your site
  ],
  
  // The link that goes to the product detail page
  productLink: [
    'a[href*="/item/"]',
    'a[href*="/product"]',
    // Add more link selectors
  ],
  
  // The visible product title/name
  productTitle: [
    '.product-name',
    '.product-title',
    'h3',
    // Add more title selectors
  ],
};
```

**How to find the right selectors:**
1. Open the website in Chrome
2. Right-click on a product card → **"Inspect"**
3. Look at the HTML structure
4. Copy the class names or tag names you see
5. Add them to the corresponding array in `content.js`

#### For Detail Page (Finding Images)

Edit the `DETAIL_PAGE_SELECTORS` object in **`background.js`** (around line 30):

```javascript
const DETAIL_PAGE_SELECTORS = {
  // Container that holds all product images
  imageContainer: [
    'div.photo-list',
    'div.details-images',
    'div.gallery',
    // Add more container selectors
  ],
  
  // Individual image elements
  imageElements: [
    'img.photo',
    'img[class*="detail"]',
    'img',  // Fallback to all images
  ],
  
  // Links to large images
  imageLinks: [
    'a[href*=".jpg"]',
    'a[href*=".png"]',
  ],
};
```

### Testing Your Selectors

1. **For gallery page:**
   - Open DevTools (F12) on a gallery page
   - Open the Console tab
   - Paste: `document.querySelectorAll('your-selector-here').length`
   - Should return > 0 if selector is correct

2. **For detail page:**
   - Open DevTools on a product detail page
   - Try: `document.querySelectorAll('img').length`
   - Should show number of images on that page

## Configuration Options

Edit the `CONFIG` object in **`background.js`** to adjust:

```javascript
const CONFIG = {
  REQUEST_DELAY: 800,           // ms between requests (lower = faster but more load on server)
  RETRY_ATTEMPTS: 3,            // How many times to retry failed downloads
  RETRY_DELAY: 2000,            // ms to wait before retrying
  MAX_CONCURRENT_DOWNLOADS: 2,  // Can be overridden in UI (1-10)
  TIMEOUT: 30000,               // ms before request times out
};
```

## Troubleshooting

### "No products found"

1. Check the URL - make sure you're on a gallery page with product links
2. Verify selectors are correct:
   - Right-click product card → Inspect
   - Check if the selector matches the HTML
   - Update `SELECTORS` in `content.js`

3. Check browser console (F12 → Console):
   - Look for error messages
   - Type: `document.querySelectorAll('your-selector').length`
   - Should be > 0

### Downloads not starting

1. Verify Chrome permissions:
   - Go to `chrome://extensions/`
   - Find "Yupoo Downloader"
   - Click "Details"
   - Check "Permissions" tab

2. Check Chrome's download settings:
   - Go to `chrome://settings/downloads`
   - Verify download location is accessible
   - Disable "Ask where to save each file" option

### Slow downloads

1. Increase `MAX_CONCURRENT_DOWNLOADS` in the popup (2-5 is usually good)
2. Decrease `REQUEST_DELAY` in `background.js` if the server allows
3. Check your internet connection

### Getting 404 errors for images

1. The image URLs might be dynamic or time-limited
2. Check detail page selector:
   - Open a product page in your browser
   - F12 → Inspect the images
   - Update `DETAIL_PAGE_SELECTORS` in `background.js`

3. The site might require headers:
   - Add custom headers to `fetchWithRetry()` in `background.js` if needed

### Extension stops working after Chrome update

1. Go to `chrome://extensions/`
2. Click "Update" or toggle off/on
3. If still broken, reload the extension:
   - Remove it
   - Reload this folder again

## How It Works

### 1. Content Script (`content.js`)
- Runs on the gallery page you're viewing
- Finds all product cards/links using CSS selectors
- Extracts product codes and detail page URLs
- Sends data to the background worker

### 2. Popup UI (`popup.html`, `popup.js`, `styles.css`)
- Shows "Scan Products" and "Download All" buttons
- Displays real-time progress
- Shows activity log
- Allows concurrency adjustment

### 3. Background Service Worker (`background.js`)
- Fetches each product's detail page
- Parses the HTML to find all images
- Downloads images using Chrome's downloads API
- Manages concurrency queue
- Handles retry logic and deduplication
- Tracks progress and errors

## Technical Details

### Manifest V3
- Uses service workers instead of background pages
- Latest Chrome extension security model
- Future-proof implementation

### Downloads API
- Uses `chrome.downloads.download()` with `filename` parameter
- Automatically creates product folders
- Works with browser's native download system

### Content Security Policy
- Safe from malicious scripts
- Follows Chrome extension best practices
- No external dependencies

### Rate Limiting
- 800ms delay between requests (configurable)
- Respects server resources
- Can be adjusted for faster downloads

## Performance Tips

1. **Reduce concurrency on slow connections** - Set to 1-2
2. **Increase concurrency on fast connections** - Set to 4-5 (but check server limits)
3. **Decrease REQUEST_DELAY for faster downloads** (but be respectful):
   - 800ms (default) = 1.25 requests/sec
   - 500ms = 2 requests/sec
   - 300ms = 3.3 requests/sec
4. **Close other Chrome tabs** to free up bandwidth
5. **Disable VPN/proxy** if it's slowing things down

## File Organization

```
popup.html              → User interface
popup.js                → UI logic and user interaction
styles.css              → Visual styling

content.js              → Page scanning (runs on website)
background.js           → Download orchestration (service worker)
manifest.json           → Extension configuration

README.md               → This file
```

## Browser Support

- Chrome 88+ (Manifest V3 support)
- Edge 88+ (also based on Chromium)
- Brave, Opera, and other Chromium-based browsers

## Known Limitations

- Does not work with infinite scroll pages (only scans initial visible products)
- Some sites with JavaScript-rendered images may not work
- Image watermarks are preserved as-is
- Login-required sites need active session

## Future Improvements

- [ ] Handle infinite scroll pages
- [ ] Support for lazy-loaded images
- [ ] Filter by product category
- [ ] Scheduling downloads
- [ ] Export metadata (product names, links)
- [ ] Resume incomplete downloads
- [ ] Image quality selection

## Legal Notice

This extension is for personal, non-commercial use only. Respect website ToS and copyright laws when downloading images. The author is not responsible for misuse.

## License

MIT License - feel free to modify and distribute

## Support

If you encounter issues:

1. Check the activity log in the popup for error messages
2. Open DevTools (F12) and check the Console tab
3. Verify CSS selectors for your target website
4. Try on a different gallery page to isolate the issue
5. Check that you have permission to download from the website

---

**Happy downloading! 📸**