Initial commit: bunkr_dl album downloaderHEADmaster

Single-file Python script that downloads Bunkr albums and search
results. Supports the current Bunkr layout (relative /f/ links,
dl.<domain>/file/<id> pages, _001_v2 metadata API and signed CDN
URLs), follows paginated albums, resumes partial downloads and
takes an -o/--output override for the base folder.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 77 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7c78d57
--- /dev/null
+++ b/README.md
@@ -0,0 +1,77 @@
+# bunkr_dl
+
+Download every file of a Bunkr album, or of every album found by a Bunkr
+search, from the command line.
+
+- Follows paginated albums (`?page=N`, 100 files per page).
+- Saves files under their original names.
+- Resumes partially downloaded files when run again against the same folder.
+- Works with any Bunkr mirror domain, since links are resolved relative to the
+  URL you pass.
+
+## Requirements
+
+Python 3 with:
+
+- `requests`
+- `beautifulsoup4`
+- `lxml`
+
+## Usage
+
+```
+bunkr_dl [-h] [-o DIR] url
+```
+
+| Option             | Meaning                                              |
+|--------------------|------------------------------------------------------|
+| `url`              | Album URL (`https://<domain>/a/<id>`) or search URL (containing `?search=`) |
+| `-o, --output DIR` | Base download folder (default: `/data/bunkr`)        |
+| `-h, --help`       | Show help and exit                                   |
+
+The default folder is set by `DEFAULT_OUTPUT` near the top of the script.
+
+Examples:
+
+```
+bunkr_dl https://bunkr.cr/a/XXXXXXXX
+bunkr_dl -o ~/Downloads https://bunkr.cr/a/XXXXXXXX
+bunkr_dl 'https://bunkr.cr/?search=some%20name'
+```
+
+Quote search URLs so the shell leaves `?` and `&` alone.
+
+### Where files go
+
+- Album: `OUTPUT/<album title>/`. If that folder already exists, a ` - 2`,
+  ` - 3`, ... suffix is added.
+- Search: `OUTPUT/<Search Terms>/<album title>/`, one subfolder per album found.
+
+## How it works
+
+1. Album page: collect the `/f/<slug>` file links, following `?page=N` until a
+   page adds nothing new.
+2. File page: find the `https://dl.<domain>/file/<id>` download link.
+3. POST the id to `/api/_001_v2` on that host to get the storage path and
+   original file name.
+4. Ask `https://glb-apisign.cdn.cr/sign` for a token and download the signed
+   CDN URL.
+
+Bunkr changes domains and page layout often. When the script reports no media,
+check these steps against the live pages first.
+
+## License
+
+Copyright (C) 2025-2026 Danilo M. <danix@danix.xyz>
+
+This program is free software; you can redistribute it and/or modify it under
+the terms of the GNU General Public License version 2 as published by the Free
+Software Foundation. See [LICENSE](LICENSE) for the full text.
+
+## Development Approach
+
+This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.
+
+All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.
+
+The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.