gphotos-scraper/README.md

A tool to extract public url and metadata from shared album

# gphotos-scraper

A high-performance tool to extract public URLs and metadata from Google Photos shared albums.

![Build Status](https://img.shields.io/badge/build-passing-brightgreen)
![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)
![Biome](https://img.shields.io/badge/Linting-Biome-yellow)
![License](https://img.shields.io/badge/license-MIT-green)

## 🚀 Key Features

*   **Extreme Performance**:
    *   **Parallel Processing**: Fetches photo metadata in concurrent batches using a worker pool pattern.
    *   **Keep-Alive Connections**: Reuses TCP connections via a custom `https.Agent` with compression (gzip/br).
    *   **O(1) Lookups**: Uses highly optimized data structures for instant ID resolution.
*   **Zero Bloat**:
    *   **No Cheerio**: HTML parsing is done via optimized Regex, removing heavy DOM dependencies.
    *   **Lightweight**: Minimal dependencies for maximum speed.
*   **Robust & Safe**:
    *   **Defensive Parsing**: Gracefully handles malformed responses from Google's RPC.
    *   **Anti-Hijacking**: Automatically cleans Google's security prefixes.
    *   **Type Safe**: Written in 100% TypeScript with strict typing.

## 📦 Installation

### Global CLI
```bash
npm install -g gphotos-scraper
```

### Local Module
```bash
npm install gphotos-scraper
```

## 💻 Usage

### CLI

Extract an album to a JSON file:

```bash
gphotos-scraper extract <ALBUM_URL> <OUTPUT_FILE.json>
```

**Example:**
```bash
gphotos-scraper extract https://photos.app.goo.gl/ExampleAlbumID ./data/album.json
```

### Module

Use it programmatically in your Node.js application:

```typescript
import { extractAlbum } from "gphotos-scraper";

const run = async () => {
    try {
        const album = await extractAlbum('https://photos.app.goo.gl/ExampleAlbumID');
        console.log(`Title: ${album.title}`);
        console.log(`Total Photos: ${album.photos.length}`);
        console.log(album);
    } catch (error) {
        console.error("Failed to extract album:", error);
    }
};

run();
```

### Output Format

```json
{
  "id": "ALBUM_ID",
  "title": "Album Title",
  "url": "https://photos.app.goo.gl/...",
  "photos": [
    {
      "id": "PHOTO_ID",
      "description": "Photo caption",
      "filename": "image.jpg",
      "createdAt": 1654258374000,
      "size": 93425,
      "width": 800,
      "height": 500,
      "mimeType": "image/jpeg",
      "url": "https://lh3.googleusercontent.com/..."
    }
  ]
}
```

## 🛠️ Development

This project uses **Biome** for linting and formatting.

1.  **Install dependencies**:
    ```bash
    nvm use
    npm install
    ```

2.  **Build**:
    ```bash
    npm run build
    ```

3.  **Lint & Format**:
    ```bash
    npm run lint:fix
    ```

## 📄 License

MIT