k

ProviderCore/base.py

@@ -5,7 +5,7 @@ import re
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Sequence, Tuple
+from typing import Any, Dict, List, Optional, Sequence, Tuple, Callable
 
 
 @dataclass
@@ -62,6 +62,22 @@ class SearchResult:
         if selection_args:
             out["_selection_args"] = selection_args
 
+        try:
+            selection_action = getattr(self, "selection_action", None)
+        except Exception:
+            selection_action = None
+        if selection_action is None:
+            try:
+                fm = getattr(self, "full_metadata", None)
+                if isinstance(fm, dict):
+                    selection_action = fm.get("_selection_action") or fm.get("selection_action")
+            except Exception:
+                selection_action = None
+        if selection_action:
+            normalized = [str(x) for x in selection_action if x is not None]
+            if normalized:
+                out["_selection_action"] = normalized
+
         return out
 
 
@@ -167,6 +183,35 @@ class Provider(ABC):
 
         return None
 
+    def download_items(
+        self,
+        result: SearchResult,
+        output_dir: Path,
+        *,
+        emit: Callable[[Path, str, str, Dict[str, Any]], None],
+        progress: Any,
+        quiet_mode: bool,
+        path_from_result: Callable[[Any], Path],
+        config: Optional[Dict[str, Any]] = None,
+    ) -> int:
+        """Optional multi-item download hook (default no-op)."""
+
+        _ = result
+        _ = output_dir
+        _ = emit
+        _ = progress
+        _ = quiet_mode
+        _ = path_from_result
+        _ = config
+        return 0
+
+    def handle_url(self, url: str, *, output_dir: Optional[Path] = None) -> Tuple[bool, Optional[Path]]:
+        """Optional provider override to parse and act on URLs."""
+
+        _ = url
+        _ = output_dir
+        return False, None
+
     def upload(self, file_path: str, **kwargs: Any) -> str:
         """Upload a file and return a URL or identifier."""
         raise NotImplementedError(f"Provider '{self.name}' does not support upload")