npm package: @knowcode/imgfetch
Description: Reliable image downloader CLI that works with any website
Author: knowcode
Latest version: 0.1.0

<div align="center">
  
# 📸 @knowcode/imgfetch

### *Download images from anywhere. Even the tricky sites.*

[![npm version](https://img.shields.io/npm/v/@knowcode/imgfetch.svg)](https://www.npmjs.com/package/@knowcode/imgfetch)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/@knowcode/imgfetch.svg)](https://nodejs.org)

A powerful CLI tool that combines multiple strategies to reliably download images from any website, including those with anti-bot protection, dynamic content, and authentication requirements.

[Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [Strategies](#-strategies) • [Examples](#-examples) • [API](#-api) • [FAQ](#-faq)

</div>

---

## 🎯 Why imgfetch?

Ever tried to download an image only to get blocked by anti-bot measures? Or struggled with JavaScript-rendered content? **imgfetch** solves these problems by intelligently selecting the right approach for each URL.

```bash
# Just works™
imgfetch https://linkedin.com/in/john-doe --strategy browser -o profile.jpg
```

## ✨ Features

<table>
<tr>
<td>

### 🚀 Smart Detection
Automatically chooses the best download strategy based on URL patterns and site requirements.

</td>
<td>

### 🤖 Anti-Bot Bypass
Uses puppeteer-extra-plugin-stealth to avoid detection on protected sites.

</td>
</tr>
<tr>
<td>

### 📦 Batch Processing
Download multiple images efficiently with a single command.

</td>
<td>

### 🔄 Automatic Fallback
If one method fails, automatically tries alternative strategies.

</td>
</tr>
</table>

## 📦 Installation

### Global Installation (Recommended)
```bash
npm install -g @knowcode/imgfetch
```

### Local Installation
```bash
npm install @knowcode/imgfetch
```

### Requirements
- Node.js 16.0.0 or higher
- npm or yarn

## 🚀 Quick Start

### Basic Usage

```bash
# Download a simple image
imgfetch https://example.com/photo.jpg

# Save with custom filename
imgfetch https://example.com/photo.jpg -o my-image.jpg

# Force browser strategy for dynamic content
imgfetch https://instagram.com/p/ABC123 --strategy browser
```

### Batch Download

Create a file `urls.txt`:
```
https://example.com/image1.jpg
https://linkedin.com/in/user
https://unsplash.com/photos/abc123
```

Then run:
```bash
imgfetch batch urls.txt --output-dir ./images/
```

## 🎨 Strategies

### Direct Strategy
**Best for:** Static images, CDN links, direct URLs
```bash
imgfetch https://cdn.example.com/image.png --strategy direct
```
- ⚡ Fastest method
- 📦 Minimal resource usage
- ✅ Works with most image hosting services

### Browser Strategy (Puppeteer)
**Best for:** Social media, JavaScript-rendered content
```bash
imgfetch https://linkedin.com/in/user --strategy browser
```
- 🛡️ Bypasses anti-bot protection
- 🔍 Handles dynamic content
- 🍪 Maintains session state

### Playwright Strategy
**Best for:** Complex sites, when Puppeteer fails
```bash
imgfetch https://complex-site.com/image --strategy playwright
```
- 🌐 Cross-browser support
- 🔧 Alternative automation engine
- 🎭 Better handling of modern web apps

## 📖 Examples

### Download LinkedIn Profile Pictures
```bash
imgfetch https://linkedin.com/in/john-doe \
  --strategy browser \
  -o john-doe-profile.jpg
```

### Extract Images from Instagram Posts
```bash
imgfetch https://instagram.com/p/ABC123XYZ \
  --strategy browser \
  --timeout 45
```

### Batch Download with Mixed Sources
```bash
# Create urls.txt with various image sources
cat > urls.txt << EOF
https://pbs.twimg.com/profile_images/123/abc.jpg
https://linkedin.com/in/jane-doe
https://github.com/user.png
EOF

# Download all images
imgfetch batch urls.txt --output-dir ./profile-pics/
```

### JSON Output for Automation
```bash
# Get structured output for scripting
result=$(imgfetch https://example.com/img.jpg --json)
echo $result | jq '.path'
```

## 🧩 API Usage

### Node.js Integration

```javascript
const ImageFetcher = require('@knowcode/imgfetch');

async function downloadImage() {
  const fetcher = new ImageFetcher({
    strategy: 'auto',
    timeout: 30000
  });

  try {
    const result = await fetcher.fetch(
      'https://example.com/image.jpg',
      './output.jpg'
    );
    
    console.log('Success!', result);
    // {
    //   success: true,
    //   strategy: 'direct',
    //   path: './output.jpg',
    //   size: 245632,
    //   mimeType: 'image/jpeg'
    // }
  } catch (error) {
    console.error('Failed:', error.message);
  } finally {
    await fetcher.close();
  }
}
```

### Advanced Configuration

```javascript
const fetcher = new ImageFetcher({
  strategy: 'browser',  // Force specific strategy
  timeout: 60000,       // 60 second timeout
  retries: 5,          // Number of retry attempts
});
```

## 🎛️ Command Line Options

| Option | Short | Description | Default |
|--------|-------|-------------|---------|
| `--output` | `-o` | Output file path | Auto-generated |
| `--strategy` | `-s` | Download strategy (`auto`, `direct`, `browser`, `playwright`) | `auto` |
| `--timeout` | `-t` | Timeout in seconds | `30` |
| `--json` | | Output as JSON | `false` |
| `--quiet` | `-q` | Suppress progress output | `false` |
| `--help` | `-h` | Show help | |
| `--version` | `-V` | Show version | |

## 🔧 Configuration

### Environment Variables
```bash
# Set default timeout
export IMGFETCH_TIMEOUT=60

# Set default output directory
export IMGFETCH_OUTPUT_DIR=./downloads
```

### Custom Headers
```javascript
const fetcher = new ImageFetcher({
  headers: {
    'User-Agent': 'Custom User Agent',
    'Referer': 'https://example.com'
  }
});
```

## ❓ FAQ

### Why does it download the wrong image from some sites?
Some sites load multiple images. imgfetch tries to identify the main image, but you might need to use browser DevTools to find the specific image URL.

### Can it handle sites that require login?
Currently, imgfetch doesn't support authentication. For sites requiring login, you'll need to download images manually or use browser automation with saved cookies.

### Why is browser strategy slow?
Browser automation launches a real browser instance, which takes time. Use direct strategy when possible for better performance.

### How do I download from sites with CAPTCHA?
CAPTCHA-protected sites require manual intervention. imgfetch can't automatically solve CAPTCHAs.

## 🛠️ Troubleshooting

### "No suitable image found"
- The page might not contain images
- Try using `--strategy browser` for dynamic content
- Check if the URL requires authentication

### "All strategies failed"
- Verify the URL is accessible in a regular browser
- Check your internet connection
- Some sites may have strong anti-bot protection

### Installation Issues
```bash
# Clear npm cache
npm cache clean --force

# Install with verbose logging
npm install -g @knowcode/imgfetch --verbose
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built on [puppeteer-extra](https://github.com/berstend/puppeteer-extra) and [playwright-extra](https://github.com/berstend/puppeteer-extra)
- Uses [puppeteer-extra-plugin-stealth](https://github.com/berstend/puppeteer-extra/tree/master/packages/puppeteer-extra-plugin-stealth) for anti-detection
- Inspired by the need for reliable image downloading in web scraping projects

---

<div align="center">

Made with ❤️ by [knowcode](https://github.com/knowcode)

[Report Bug](https://github.com/knowcode/imgfetch/issues) • [Request Feature](https://github.com/knowcode/imgfetch/issues)

</div>