bunkr-api 0.1.0__py3-none-any.whl

bunkr_api/core/db.py

@@ -0,0 +1,353 @@
+import sqlite3
+import time
+from contextlib import closing, contextmanager
+
+# Internal package imports
+from ..config import DB_PATH
+from ..utils.formatting import extract_expiry_from_url
+
+
+class DatabaseManager:
+    def __init__(self, db_path: str = DB_PATH):
+        self.db_path = db_path
+        self._init_db()
+
+    def _get_connection(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self.db_path, timeout=5.0)
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA foreign_keys = ON;")
+        return conn
+
+    @contextmanager
+    def connection(self):
+        conn = self._get_connection()
+        try:
+            with conn:
+                yield conn
+        finally:
+            conn.close()
+
+    def _init_db(self):
+        """Initializes tables and handles schema migrations."""
+        with closing(self._get_connection()) as conn:
+            conn.execute("PRAGMA journal_mode = WAL;")
+            with conn:
+                conn.execute("""
+                    CREATE TABLE IF NOT EXISTS albums (
+                        id INTEGER PRIMARY KEY AUTOINCREMENT,
+                        album_id_str TEXT UNIQUE,
+                        title TEXT NOT NULL,
+                        search_term TEXT,
+                        global_index INTEGER,
+                        aggregate_size TEXT DEFAULT '0 MB',
+                        file_count INTEGER DEFAULT 0,
+                        is_staged INTEGER DEFAULT 0,
+                        created_at INTEGER NOT NULL,
+                        updated_at INTEGER NOT NULL
+                    );
+                """)
+                conn.execute("""
+                    CREATE TABLE IF NOT EXISTS assets (
+                        id INTEGER PRIMARY KEY AUTOINCREMENT,
+                        album_id INTEGER NOT NULL,
+                        track_number INTEGER,
+                        true_file_id INTEGER,
+                        title TEXT NOT NULL,
+                        original_filename TEXT,
+                        raw_size_bytes INTEGER DEFAULT 0,
+                        source_url TEXT UNIQUE,
+                        signed_cdn_url TEXT,
+                        token_expiry_timestamp INTEGER,
+                        is_staged INTEGER DEFAULT 0,
+                        download_status TEXT CHECK(
+                            download_status IN ('PENDING', 'DOWNLOADING', 'COMPLETED', 'FAILED')
+                        ) DEFAULT 'PENDING',
+                        local_file_path TEXT,
+                        error_message TEXT,
+                        FOREIGN KEY (album_id) REFERENCES albums(id) ON DELETE CASCADE
+                    );
+                """)
+                conn.execute(
+                    "CREATE TABLE IF NOT EXISTS system_config (config_key TEXT PRIMARY KEY, config_value TEXT NOT NULL, description TEXT);"
+                )
+
+                # Performance Indexing
+                conn.execute(
+                    "CREATE INDEX IF NOT EXISTS idx_assets_expiry ON assets(token_expiry_timestamp);"
+                )
+                conn.execute("CREATE INDEX IF NOT EXISTS idx_assets_album_id ON assets(album_id);")
+
+                # Seed Defaults
+                conn.execute("""
+                    INSERT OR IGNORE INTO system_config (config_key, config_value, description)
+                    VALUES 
+                        ('max_workers', '4', 'Default concurrency worker thread limit'),
+                        ('token_buffer_seconds', '600', 'Force token refresh lookahead window'),
+                        ('minter_poll_interval_seconds', '60', 'Polling interval for the background minter')
+                """)
+
+    def get_config_val(self, key: str, default: str) -> str:
+        with closing(self._get_connection()) as conn:
+            row = conn.execute(
+                "SELECT config_value FROM system_config WHERE config_key = ?;", (key,)
+            ).fetchone()
+            return row["config_value"] if row else default
+
+    def register_album_from_json(self, data: dict) -> tuple[int, int, int]:
+        """
+        Registers/syncs an album and its files.
+
+        Identity is keyed on the album's stable Bunkr slug (album_slug), not on
+        title + search-result position — result position shifts between scrapes
+        (pagination/sort/new uploads), which previously caused re-scrapes of the
+        same album to register as a brand new album with zero attached files.
+
+        Legacy JSON imports that predate album_slug fall back to the old
+        title+index identity, since there's nothing more stable to key on.
+
+        Returns (album_id, new_file_count, updated_file_count) so callers can
+        give the user real feedback instead of a blind "success" message.
+        """
+        album_meta = data.get("selected_album", {})
+        search_term = data.get("search_term", "N/A")
+        files_found = data.get("files_found", [])
+
+        album_title = album_meta.get("title", "Unknown Album")
+        global_idx = album_meta.get("album_index_number", 0)
+        album_slug = album_meta.get("album_slug")
+
+        if album_slug:
+            album_id_str = f"slug_{album_slug}".lower()
+        else:
+            # Legacy fallback (old JSON exports without a slug) — best effort only.
+            album_id_str = f"{album_title}_{global_idx}".lower().replace(" ", "_")
+
+        now = int(time.time())
+
+        with closing(self._get_connection()) as conn:
+            with conn:
+                cursor = conn.execute(
+                    """
+                    INSERT INTO albums (album_id_str, title, search_term, global_index, aggregate_size, file_count, created_at, updated_at)
+                    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                    ON CONFLICT(album_id_str) DO UPDATE SET
+                        updated_at = excluded.updated_at,
+                        aggregate_size = excluded.aggregate_size,
+                        file_count = excluded.file_count
+                    RETURNING id;
+                """,
+                    (
+                        album_id_str,
+                        album_title,
+                        search_term,
+                        global_idx,
+                        album_meta.get("aggregate_size", 0),
+                        len(files_found),
+                        now,
+                        now,
+                    ),
+                )
+                album_id = cursor.fetchone()["id"]
+
+                # Pre-compute rows and check which source_urls already exist so we
+                # can report real new-vs-updated counts (INSERT...ON CONFLICT alone
+                # can't tell you which branch it took).
+                prepared_rows = []
+                source_urls = []
+                for idx, file_rec in enumerate(files_found, start=1):
+                    cdn_url = file_rec.get("signed_cdn_url")
+                    expiry_ts = extract_expiry_from_url(cdn_url)
+                    true_file_id = file_rec.get("true_file_id") or file_rec.get("slug_id")
+                    source_url = file_rec.get("href", cdn_url)
+                    prepared_rows.append(
+                        (idx, file_rec, cdn_url, expiry_ts, true_file_id, source_url)
+                    )
+                    source_urls.append(source_url)
+
+                existing_urls = set()
+                if source_urls:
+                    placeholders = ",".join("?" for _ in source_urls)
+                    existing_urls = {
+                        row["source_url"]
+                        for row in conn.execute(
+                            f"SELECT source_url FROM assets WHERE source_url IN ({placeholders});",
+                            source_urls,
+                        ).fetchall()
+                    }
+
+                new_count = 0
+                updated_count = 0
+                for idx, file_rec, cdn_url, expiry_ts, true_file_id, source_url in prepared_rows:
+                    if source_url in existing_urls:
+                        updated_count += 1
+                    else:
+                        new_count += 1
+
+                    conn.execute(
+                        """
+                        INSERT INTO assets (
+                            album_id, track_number, true_file_id, title, original_filename, 
+                            raw_size_bytes, source_url, signed_cdn_url, token_expiry_timestamp
+                        )
+                        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                        ON CONFLICT(source_url) DO UPDATE SET
+                            album_id = excluded.album_id,
+                            track_number = excluded.track_number,
+                            true_file_id = excluded.true_file_id,
+                            title = excluded.title,
+                            original_filename = excluded.original_filename,
+                            raw_size_bytes = excluded.raw_size_bytes,
+                            signed_cdn_url = excluded.signed_cdn_url,
+                            token_expiry_timestamp = excluded.token_expiry_timestamp
+                    """,
+                        (
+                            album_id,
+                            idx,
+                            true_file_id,
+                            file_rec.get("title", f"Track {idx}"),
+                            file_rec.get("original", f"file_{idx}"),
+                            file_rec.get("size", 0),
+                            source_url,
+                            cdn_url,
+                            expiry_ts,
+                        ),
+                    )
+
+            return album_id, new_count, updated_count
+
+    def get_all_albums(self) -> list[sqlite3.Row]:
+        """Returns every album, plus a per-album total_assets/completed_assets
+        count so callers can show a '[COMPLETED]' badge without an extra
+        query per album. All original `albums` columns are still present.
+        """
+        with closing(self._get_connection()) as conn:
+            return conn.execute("""
+                SELECT al.*,
+                       COUNT(a.id) AS total_assets,
+                       SUM(CASE WHEN a.download_status = 'COMPLETED' THEN 1 ELSE 0 END) AS completed_assets
+                FROM albums al
+                LEFT JOIN assets a ON a.album_id = al.id
+                GROUP BY al.id
+                ORDER BY al.updated_at DESC;
+            """).fetchall()
+
+    def get_album(self, album_id: int) -> sqlite3.Row | None:
+        """Returns a single album's row, or None if no such album exists."""
+        with closing(self._get_connection()) as conn:
+            return conn.execute("SELECT * FROM albums WHERE id = ?;", (album_id,)).fetchone()
+
+    def delete_album(self, album_id: int) -> bool:
+        """Deletes an album and all its assets (cascades via the assets
+        table's ON DELETE CASCADE foreign key — foreign_keys is enabled on
+        every connection in _get_connection()).
+
+        Returns True if a row was actually deleted, False if no album with
+        that id existed.
+        """
+        with closing(self._get_connection()) as conn, conn:
+            cursor = conn.execute("DELETE FROM albums WHERE id = ?;", (album_id,))
+            return cursor.rowcount > 0
+
+    def get_staged_assets(self) -> list[sqlite3.Row]:
+        """Returns every asset flagged as staged, joined with its parent
+        album's title.
+
+        Filters on the asset-level flag only. The album-level is_staged
+        flag is a display convenience (shows a '[STAGED]' badge in the
+        catalog for an album with any staged items) — it is deliberately
+        NOT used to gate which assets get downloaded here. Staging a whole
+        album sets both flags at once (see toggle_staging), but downloads
+        only ever clear the asset-level flag as each file finishes, so
+        joining on the album-level flag here would keep resurfacing
+        already-completed files for as long as any sibling asset in that
+        album remains staged.
+        """
+        with closing(self._get_connection()) as conn:
+            return conn.execute("""
+                SELECT a.*, al.title AS album_title FROM assets a
+                LEFT JOIN albums al ON a.album_id = al.id
+                WHERE a.is_staged = 1
+                ORDER BY a.album_id, a.track_number ASC;
+            """).fetchall()
+
+    def sync_album_staged_flag(self, album_id: int):
+        """Clears an album's is_staged badge once none of its assets are
+        still staged. Call this after an asset's is_staged flag is cleared
+        (e.g. on download completion) so the catalog's '[STAGED]' display
+        doesn't keep showing an album as staged after every file in it is
+        actually done.
+        """
+        with closing(self._get_connection()) as conn, conn:
+            remaining = conn.execute(
+                "SELECT COUNT(*) AS c FROM assets WHERE album_id = ? AND is_staged = 1", (album_id,)
+            ).fetchone()["c"]
+            if remaining == 0:
+                conn.execute("UPDATE albums SET is_staged = 0 WHERE id = ?;", (album_id,))
+
+    def get_failed_assets(self) -> list[sqlite3.Row]:
+        """Returns every asset currently marked FAILED, joined with its
+        parent album's title.
+        """
+        with closing(self._get_connection()) as conn:
+            return conn.execute("""
+                SELECT a.*, al.title AS album_title FROM assets a
+                LEFT JOIN albums al ON a.album_id = al.id
+                WHERE a.download_status = 'FAILED'
+                ORDER BY a.album_id, a.track_number ASC;
+            """).fetchall()
+
+    def get_album_assets(self, album_id: int) -> list[sqlite3.Row]:
+        with closing(self._get_connection()) as conn:
+            return conn.execute(
+                "SELECT * FROM assets WHERE album_id = ? ORDER BY track_number ASC;", (album_id,)
+            ).fetchall()
+
+    def update_asset_url(self, asset_id: int, new_cdn_url: str):
+        expiry_ts = extract_expiry_from_url(new_cdn_url)
+        with closing(self._get_connection()) as conn, conn:
+            conn.execute(
+                "UPDATE assets SET signed_cdn_url = ?, token_expiry_timestamp = ? WHERE id = ?",
+                (new_cdn_url, expiry_ts, asset_id),
+            )
+
+    def update_download_status(
+        self, asset_id: int, status: str, local_path: str | None = None, error: str | None = None
+    ):
+        with closing(self._get_connection()) as conn, conn:
+            conn.execute(
+                "UPDATE assets SET download_status = ?, local_file_path = ?, error_message = ? WHERE id = ?",
+                (status, local_path, error, asset_id),
+            )
+
+    def get_needs_refresh(self, album_id: int | None = None) -> list[sqlite3.Row]:
+        lookahead = int(self.get_config_val("token_buffer_seconds", "600"))
+        now_with_buffer = int(time.time()) + lookahead
+        with closing(self._get_connection()) as conn:
+            if album_id is not None:
+                return conn.execute(
+                    "SELECT * FROM assets WHERE album_id = ? AND (token_expiry_timestamp IS NULL OR token_expiry_timestamp <= ?);",
+                    (album_id, now_with_buffer),
+                ).fetchall()
+            return conn.execute(
+                "SELECT * FROM assets WHERE token_expiry_timestamp IS NULL OR token_expiry_timestamp <= ?;",
+                (now_with_buffer,),
+            ).fetchall()
+
+    def get_valid_url(self, asset_id: int) -> str:
+        with closing(self._get_connection()) as conn:
+            asset = conn.execute("SELECT * FROM assets WHERE id = ?;", (asset_id,)).fetchone()
+        if not asset:
+            return ""
+        lookahead = int(self.get_config_val("token_buffer_seconds", "600"))
+        if (
+            asset["signed_cdn_url"]
+            and asset["token_expiry_timestamp"]
+            and asset["token_expiry_timestamp"] > (time.time() + lookahead)
+        ):
+            return asset["signed_cdn_url"]
+        from .tokens import mint_now
+
+        file_id = str(asset["true_file_id"]) if asset["true_file_id"] else asset["source_url"]
+        fresh_url = mint_now(file_id)
+        self.update_asset_url(asset_id, fresh_url)
+        return fresh_url

bunkr_api/core/scraper.py

@@ -0,0 +1,310 @@
+import argparse
+import asyncio
+import json
+import re
+import sys
+import urllib.parse
+from pathlib import Path
+
+from bs4 import BeautifulSoup
+from rich.console import Console
+
+from ..config import (
+    DEFAULT_JSON_DIR,
+    DEFAULT_OUTPUT_DIR,
+    HEADERS,
+    SEARCH_MODES,
+    VALID_COUNTS,
+)
+from ..utils.formatting import slugify_filename
+from ..utils.http import execute_request_with_retry_async
+
+console = Console()
+
+class ScraperEngine:
+    def __init__(self, db):
+        """
+        Initializes the scraper engine with a shared database instance.
+        """
+        self.db = db
+
+    def _safe_int(self, val):
+        """Helper to prevent ValueError crashes during parsing of sizes or counts."""
+        if isinstance(val, int):
+            return val
+        if not val:
+            return 0
+        try:
+            clean_val = re.sub(r'[^\d]', '', str(val))
+            return int(clean_val) if clean_val else 0
+        except Exception:
+            return 0
+
+    def standardize_top_url(self, url: str) -> str:
+        """Converts specific /v/ and /i/ redirect configurations to /f/."""
+        return re.sub(r'/(v|i)/', '/f/', url)
+
+    def parse_albums(self, html):
+        """Extract album information and file counts from search results page."""
+        soup = BeautifulSoup(html, 'html.parser')
+        albums = []
+        
+        for card in soup.find_all('a', href=True):
+            href = card.get('href', '')
+            
+            if re.search(r'/a/[\w-]+', href):
+                title_tag = card.find('h3')
+                title = title_tag.get_text(strip=True) if title_tag else card.get_text(strip=True)
+                
+                file_count = None
+                span_tags = card.find_all('span')
+                for span in span_tags:
+                    span_text = span.get_text(strip=True)
+                    if 'file' in span_text.lower():
+                        file_count = span_text
+                        break
+                
+                if title:
+                    albums.append({
+                        'title': title,
+                        'url': href if href.startswith('http') else 'https://bunkr.cr' + href,
+                        'file_count': file_count if file_count else "0 files"
+                    })
+        
+        seen = set()
+        unique_albums = []
+        for album in albums:
+            if album['url'] not in seen:
+                unique_albums.append(album)
+                seen.add(album['url'])
+        
+        return unique_albums
+
+    def parse_top_items(self, html, category):
+        """Extract and isolate trending listings for the 'Trending' CLI feature."""
+        soup = BeautifulSoup(html, 'html.parser')
+        items = []
+        prefix_map = {"albums": "a", "videos": "v", "files": "f", "images": "i"}
+        target_prefix = prefix_map.get(category, "f")
+        
+        for card in soup.find_all('a', href=True):
+            href = card.get('href', '')
+            if re.search(rf'/{target_prefix}/[\w-]+', href):
+                title_tag = card.find('h3') or card.find('p')
+                title = title_tag.get_text(strip=True) if title_tag else card.get_text(strip=True)
+                full_url = href if href.startswith('http') else 'https://bunkr.cr' + href
+                
+                if category in ["videos", "images"]:
+                    full_url = self.standardize_top_url(full_url)
+                
+                file_count = "1 file"
+                for span in card.find_all('span'):
+                    if 'file' in span.get_text(strip=True).lower():
+                        file_count = span.get_text(strip=True)
+                        break
+                if title:
+                    items.append({'title': title, 'url': full_url, 'file_count': file_count})
+        seen = set()
+        return [x for x in items if not (x['url'] in seen or seen.add(x['url']))]
+
+    def extract_page_metadata(self, soup):
+        """Parses total global pages from the HTML pagination section of a search results page."""
+        footer_div = soup.find('div', class_='text-xs text-[var(--text-soft)] mono')
+        if footer_div:
+            text = footer_div.get_text(strip=True)
+            match = re.search(r'Page\s+\d+\s+of\s+(\d+)', text, re.IGNORECASE)
+            if match:
+                return match.group(1)
+
+        top_span = soup.find('span', class_='text-[var(--text)]')
+        if top_span:
+            parent_text = top_span.parent.get_text(strip=True) if top_span.parent else ""
+            match = re.search(r'page\s+\d+\s+of\s+(\d+)', parent_text, re.IGNORECASE)
+            if match:
+                return match.group(1)
+
+        return "Unknown"
+
+    def parse_album_header_metadata(self, soup):
+        """Extract full album size and total files from the visitors paragraph."""
+        album_size = None
+        total_files = None
+        
+        size_el = soup.select_one(".visitors .font-semibold")
+        if size_el:
+            text = size_el.get_text(strip=True)
+            size_match = re.search(r'\((.*?)\)', text)
+            if size_match:
+                album_size = size_match.group(1)
+            
+            files_match = re.search(r'\)\s*(.*)', text)
+            if files_match:
+                total_files = files_match.group(1).strip()
+                
+        return album_size, total_files
+
+    def extract_advanced_album_files(self, html_content: str) -> list:
+        """RESTORED: Exact regex and logic to handle 'slug' vs 'name' vs 'original'."""
+        match = re.search(r'window\.albumFiles\s*=\s*\[(.*?)\];', html_content, re.DOTALL)
+        if not match:
+            return []
+            
+        array_content = match.group(1)
+        object_strings = re.findall(r'\{([^}]+)\}', array_content, re.DOTALL)
+        parsed_files = []
+        
+        for obj_str in object_strings:
+            file_meta = {}
+            matches = re.findall(r'(\w+):\s*(?:"([^"]*)"|(\d+))', obj_str)
+            
+            for key, str_val, num_val in matches:
+                if num_val:
+                    file_meta[key] = int(num_val)
+                else:
+                    file_meta[key] = str_val
+                    
+            if file_meta:
+                slug = file_meta.get('slug') or file_meta.get('name')
+                display_name = file_meta.get('original') or file_meta.get('name', 'Unknown Title')
+
+                parsed_files.append({
+                    'true_file_id': file_meta.get('id'),
+                    'slug_id': file_meta.get('id'), 
+                    'href': f"https://bunkr.cr/f/{urllib.parse.quote(str(slug))}" if slug else None,
+                    'title': display_name,
+                    'original': display_name,
+                    'size': self._safe_int(file_meta.get('size', 0)),
+                    **{k: v for k, v in file_meta.items() if k not in ['id', 'name', 'slug', 'original', 'size']}
+                })
+                
+        return parsed_files
+
+    async def scrape_album(self, session, url, search_term, album_number_index=0, save_json=False, output_dir=None):
+        """Deep resolution of an album with original informative console logging."""
+        parsed_url = urllib.parse.urlparse(url)
+        params = dict(urllib.parse.parse_qsl(parsed_url.query))
+        params['advanced'] = '1'
+        optimized_url = urllib.parse.urlunparse(
+            parsed_url._replace(query=urllib.parse.urlencode(params))
+        )
+        
+        console.print("\n[bold yellow][*][/bold yellow] Navigating optimized album view ")
+        
+        res = await execute_request_with_retry_async(session, optimized_url, headers=HEADERS)
+        soup = BeautifulSoup(res.text, 'html.parser')
+        
+        album_title = (
+            re.sub(r'\s*[\|\-]\s*Bunkr\s*$', '', soup.title.string, flags=re.IGNORECASE)
+            if soup.title else "Unknown Album"
+        )
+        
+        console.print(f"\n[bold green][+][/bold green] Selected: #[bold yellow]{album_number_index}[/bold yellow] - [bold white]{album_title}[/bold white]")
+
+        album_size, total_files = self.parse_album_header_metadata(soup)
+        final_files = self.extract_advanced_album_files(res.text)
+        
+        if album_size and total_files:
+            console.print(f"[bold green][+][/bold green] Album Info -> Aggregate Size: [bold yellow]{album_size}[/bold yellow] | Count: [bold yellow]{total_files}[/bold yellow]")
+        
+        console.print(f"[bold green][+][/bold green] Deep resolution complete. Pulled [bold cyan]{len(final_files)}[/bold cyan] accurate item profiles instantly.")
+
+        for i, f_rec in enumerate(final_files[:10], start=1):
+            raw_size = f_rec.get('size', 0)
+            size_mb = round(raw_size / (1024*1024), 2)
+            size_str = f" ({size_mb} MB)" if raw_size else ""
+            console.print(f"  {i}. {f_rec['title']}{size_str} [[italic green]True[/italic green] ID: {f_rec['true_file_id']}]")
+
+        # Stable identity for this album, independent of its position in any
+        # given search results page (which shifts between scrapes and previously
+        # caused re-scrapes to register as phantom duplicate albums).
+        slug_match = re.search(r'/a/([\w-]+)', url)
+        album_slug = slug_match.group(1) if slug_match else None
+
+        data = {
+            'search_term': search_term or "N/A",
+            'selected_album': {
+                'title': album_title.strip(),
+                'album_index_number': album_number_index,
+                'album_slug': album_slug,
+                'album_url': url,
+                'aggregate_size': album_size if album_size else "0 MB",
+                'clean_file_count': total_files if total_files else f"{len(final_files)} files"
+            },
+            'files_found': final_files
+        }
+        
+        if save_json:
+            # Determine correct output directory
+            save_path = Path(output_dir) if output_dir else DEFAULT_OUTPUT_DIR
+            save_path.mkdir(parents=True, exist_ok=True)
+            
+            output_filename = save_path / f"{slugify_filename(album_number_index, album_title)}.json"
+            try:
+                payload = json.dumps(data, indent=2, ensure_ascii=False)
+                await asyncio.to_thread(output_filename.write_text, payload, encoding="utf-8")
+                console.print(f"[bold green][+][/bold green] Enriched results saved out to [bold white]{output_filename}[/bold white]")
+            except (OSError, TypeError, ValueError) as e:
+                console.print(f"[red][!] JSON Backup Failed: {e}[/red]")
+
+        console.print("[bold yellow][*][/bold yellow] Syncing records with Database Manager...")
+        album_id, new_count, updated_count = self.db.register_album_from_json(data)
+
+        if new_count and updated_count:
+            console.print(
+                f"[bold green][+][/bold green] Synced Album ID [bold yellow]#{album_id}[/bold yellow] — "
+                f"[bold cyan]{new_count}[/bold cyan] new file(s), [bold cyan]{updated_count}[/bold cyan] refreshed."
+            )
+        elif new_count:
+            console.print(
+                f"[bold green][+][/bold green] Registered Album ID [bold yellow]#{album_id}[/bold yellow] with "
+                f"[bold cyan]{new_count}[/bold cyan] file(s)."
+            )
+        else:
+            console.print(
+                f"[bold green][+][/bold green] Album ID [bold yellow]#{album_id}[/bold yellow] already up to date "
+                f"— [bold cyan]{updated_count}[/bold cyan] file(s) refreshed, no new files found."
+            )
+
+        return album_id
+
+def main():
+    """Standalone CLI entry point for bunkr-scrape command."""
+    parser = argparse.ArgumentParser(
+        prog="bunkr-scrape",
+        description="Bunkr Standalone Scraper CLI"
+    )
+    parser.add_argument("search", nargs="?", default=None, help="The search query")
+    parser.add_argument("-m", "--mode", choices=list(SEARCH_MODES.keys()), help="Search mode")
+    parser.add_argument("-p", "--per", type=int, choices=VALID_COUNTS, help="No. of results per page")
+    parser.add_argument("-s", "--sort", choices=["latest", "oldest", "mostfiles"], help="Sort by")
+    parser.add_argument("-t", "--top", nargs="?", const="prompt", help="Trending category")
+    parser.add_argument("--save-json", action="store_true", help="Save backup JSON")
+    parser.add_argument("-o", "--output", type=str, default=str(DEFAULT_JSON_DIR), help="Output directory for a JSON metadata")
+    
+    args = parser.parse_args()
+
+    url_mode = SEARCH_MODES.get(args.mode) if args.mode else None
+    
+    from ..cli import run_scrape_interactive, run_top_engine_interactive
+
+    async def _run():
+        if args.top:
+            await run_top_engine_interactive(
+                category_seed=args.top if args.top != "prompt" else None,
+                save_json_seed=args.save_json,
+                output_dir_seed=args.output
+            )
+        else:
+            await run_scrape_interactive(
+                search_seed=args.search, 
+                mode_seed=url_mode, 
+                per_seed=args.per, 
+                sort_seed=args.sort,
+                save_json_seed=args.save_json,
+                output_dir_seed=args.output
+            )
+
+    try:
+        asyncio.run(_run())
+    except KeyboardInterrupt:
+        sys.exit(0)