Medios-Macina/Provider/telegram.py

from __future__ import annotations

import asyncio
import re
import shutil
import sys
import time
import threading
from pathlib import Path
from typing import Any, Dict, Optional, Sequence, Tuple
from urllib.parse import urlparse

from ProviderCore.base import Provider, SearchResult


_TELEGRAM_DEFAULT_TIMESTAMP_STEM_RE = re.compile(
	r"^(?P<prefix>photo|video|document|audio|voice|animation)_(?P<date>\d{4}-\d{2}-\d{2})_(?P<time>\d{2}-\d{2}-\d{2})(?: \(\d+\))?$",
	flags=re.IGNORECASE,
)


def _unique_path(path: Path) -> Path:
	try:
		if not path.exists():
			return path
	except Exception:
		return path

	stem = path.stem
	suffix = path.suffix
	parent = path.parent
	for i in range(1, 10_000):
		candidate = parent / f"{stem} ({i}){suffix}"
		try:
			if not candidate.exists():
				return candidate
		except Exception:
			return candidate
	return parent / f"{stem} (copy){suffix}"


def _maybe_strip_telegram_timestamped_default_filename(*, downloaded_path: Path) -> Path:
	"""Normalize Telethon's default timestamped names.

	Examples:
	- photo_2025-12-27_02-58-09.jpg -> photo.jpg
	"""
	try:
		stem = downloaded_path.stem
		suffix = downloaded_path.suffix
	except Exception:
		return downloaded_path

	if not suffix:
		return downloaded_path

	m = _TELEGRAM_DEFAULT_TIMESTAMP_STEM_RE.fullmatch(str(stem))
	if not m:
		return downloaded_path

	prefix = str(m.group("prefix") or "").strip().lower()
	if not prefix:
		return downloaded_path

	new_candidate = downloaded_path.with_name(f"{prefix}{suffix}")
	if new_candidate == downloaded_path:
		return downloaded_path

	new_path = _unique_path(new_candidate)
	try:
		if downloaded_path.exists():
			try:
				downloaded_path.rename(new_path)
				return new_path
			except Exception:
				shutil.move(str(downloaded_path), str(new_path))
				return new_path
	except Exception:
		return downloaded_path

	return downloaded_path


def _looks_like_telegram_message_url(url: str) -> bool:
	try:
		parsed = urlparse(str(url))
	except Exception:
		return False
	host = (parsed.hostname or "").lower().strip()
	if host in {"t.me", "telegram.me"}:
		return True
	if host.endswith(".t.me"):
		return True
	return False


def _parse_telegram_message_url(url: str) -> Tuple[str, int]:
	"""Parse a Telegram message URL into (entity, message_id).

	Supported:
	- https://t.me/<username>/<msg_id>
	- https://t.me/s/<username>/<msg_id>
	- https://t.me/c/<internal_channel_id>/<msg_id>
	"""
	parsed = urlparse(str(url))
	path = (parsed.path or "").strip("/")
	if not path:
		raise ValueError(f"Invalid Telegram URL: {url}")

	parts = [p for p in path.split("/") if p]
	if not parts:
		raise ValueError(f"Invalid Telegram URL: {url}")

	# Strip preview prefix
	if parts and parts[0].lower() == "s":
		parts = parts[1:]

	if len(parts) < 2:
		raise ValueError(f"Invalid Telegram URL (expected /<chat>/<msg>): {url}")

	chat = parts[0]
	msg_raw = parts[1]

	# t.me/c/<id>/<msg>
	if chat.lower() == "c":
		if len(parts) < 3:
			raise ValueError(f"Invalid Telegram /c/ URL: {url}")
		chat = f"c:{parts[1]}"
		msg_raw = parts[2]

	m = re.fullmatch(r"\d+", str(msg_raw).strip())
	if not m:
		raise ValueError(f"Invalid Telegram message id in URL: {url}")

	return str(chat), int(msg_raw)


class Telegram(Provider):
	"""Telegram provider using Telethon.

	Config:
	[provider=telegram]
	app_id=
	api_hash=
	"""

	def __init__(self, config: Optional[Dict[str, Any]] = None):
		super().__init__(config)
		telegram_conf = self.config.get("provider", {}).get("telegram", {}) if isinstance(self.config, dict) else {}
		self._app_id = telegram_conf.get("app_id")
		self._api_hash = telegram_conf.get("api_hash")
		self._bot_token = telegram_conf.get("bot_token")
		self._last_login_error: Optional[str] = None
		# Telethon downloads are chunked; larger parts mean fewer round-trips.
		# Telethon typically expects 4..1024 KB and divisible by 4.
		self._part_size_kb = telegram_conf.get("part_size_kb")
		if self._part_size_kb is None:
			self._part_size_kb = telegram_conf.get("chunk_kb")
		if self._part_size_kb is None:
			self._part_size_kb = telegram_conf.get("download_part_kb")

	def _has_running_event_loop(self) -> bool:
		try:
			asyncio.get_running_loop()
			return True
		except RuntimeError:
			return False
		except Exception:
			return False

	def _run_async_blocking(self, coro):
		"""Run an awaitable to completion using a fresh event loop.

		If an event loop is already running in this thread (common in REPL/TUI),
		runs the coroutine in a worker thread with its own loop.
		"""
		result: Dict[str, Any] = {}
		err: Dict[str, Any] = {}

		def _runner() -> None:
			loop = asyncio.new_event_loop()
			try:
				asyncio.set_event_loop(loop)
				result["value"] = loop.run_until_complete(coro)
			except BaseException as exc:
				# Ensure we don't leave Telethon tasks pending when the user hits Ctrl+C.
				err["error"] = exc
				try:
					try:
						pending = asyncio.all_tasks(loop)  # py3.8+
					except TypeError:
						pending = asyncio.all_tasks()  # type: ignore
					pending = [t for t in pending if t is not None and not t.done()]
					for t in pending:
						try:
							t.cancel()
						except Exception:
							pass
					if pending:
						loop.run_until_complete(asyncio.gather(*pending, return_exceptions=True))
					try:
						loop.run_until_complete(loop.shutdown_asyncgens())
					except Exception:
						pass
				except Exception:
					pass
			finally:
				try:
					loop.close()
				except Exception:
					pass

		if self._has_running_event_loop():
			th = threading.Thread(target=_runner, daemon=True)
			th.start()
			th.join()
		else:
			_runner()

		if "error" in err:
			raise err["error"]
		return result.get("value")

	def _stdin_is_interactive(self) -> bool:
		"""Best-effort check for whether we can safely prompt the user.

		Some environments (e.g. prompt_toolkit) may wrap `sys.stdin` such that
		`sys.stdin.isatty()` is False even though interactive prompting works.
		"""
		try:
			streams = [sys.stdin, getattr(sys, "__stdin__", None)]
			for stream in streams:
				if stream is None:
					continue
				isatty = getattr(stream, "isatty", None)
				if callable(isatty) and bool(isatty()):
					return True
		except Exception:
			return False
		return False

	def _legacy_session_base_path(self) -> Path:
		# Older versions stored sessions under Log/medeia_macina.
		root = Path(__file__).resolve().parents[1]
		return root / "Log" / "medeia_macina" / "telegram"

	def _migrate_legacy_session_if_needed(self) -> None:
		"""If a legacy Telethon session exists, copy it to the new root location."""
		try:
			new_base = self._session_base_path()
			new_session = Path(str(new_base) + ".session")
			if new_session.is_file():
				return

			legacy_base = self._legacy_session_base_path()
			legacy_session = Path(str(legacy_base) + ".session")
			if not legacy_session.is_file():
				return

			for suffix in (".session", ".session-journal", ".session-wal", ".session-shm"):
				src = Path(str(legacy_base) + suffix)
				dst = Path(str(new_base) + suffix)
				try:
					if src.is_file() and not dst.exists():
						shutil.copy2(str(src), str(dst))
				except Exception:
					continue
		except Exception:
			return

	def _session_file_path(self) -> Path:
		self._migrate_legacy_session_if_needed()
		base = self._session_base_path()
		return Path(str(base) + ".session")

	def _has_session(self) -> bool:
		self._migrate_legacy_session_if_needed()
		try:
			return self._session_file_path().is_file()
		except Exception:
			return False

	def _session_is_authorized(self) -> bool:
		"""Return True if the current session file represents an authorized login.

		This must never prompt.
		"""
		self._migrate_legacy_session_if_needed()
		if not self._has_session():
			return False
		try:
			from telethon import TelegramClient
		except Exception:
			return False
		try:
			app_id, api_hash = self._credentials()
		except Exception:
			return False

		session_base = self._session_base_path()

		async def _check_async() -> bool:
			client = TelegramClient(str(session_base), app_id, api_hash)
			try:
				await client.connect()
				return bool(await client.is_user_authorized())
			finally:
				try:
					await client.disconnect()
				except Exception:
					pass

		try:
			return bool(self._run_async_blocking(_check_async()))
		except Exception:
			return False

	def _ensure_session_interactive(self) -> bool:
		"""Best-effort interactive auth to create a Telethon session file.

		Returns True if a session exists and is authorized after the attempt.
		"""
		self._last_login_error = None
		if self._session_is_authorized():
			return True

		# Never prompt in non-interactive contexts.
		if not self._stdin_is_interactive():
			self._last_login_error = "stdin is not interactive"
			return False

		try:
			from telethon import TelegramClient
		except Exception as exc:
			self._last_login_error = f"Telethon not available: {exc}"
			return False

		try:
			app_id, api_hash = self._credentials()
		except Exception:
			return False

		try:
			sys.stderr.write("[telegram] No session found; login required.\n")
			sys.stderr.write("[telegram] Choose login method: 1) phone  2) bot token\n")
			sys.stderr.write("[telegram] Enter 1 or 2: ")
			sys.stderr.flush()
			choice = ""
			try:
				choice = str(input()).strip().lower()
			except EOFError:
				choice = ""

			use_bot = choice in {"2", "b", "bot", "token"}
			bot_token = ""
			if use_bot:
				sys.stderr.write("[telegram] Bot token: ")
				sys.stderr.flush()
				try:
					bot_token = str(input()).strip()
				except EOFError:
					bot_token = ""
				if not bot_token:
					self._last_login_error = "bot token was empty"
					return False
				self._bot_token = bot_token
			else:
				sys.stderr.write("[telegram] Phone login selected (Telethon will prompt for phone + code).\n")
				sys.stderr.flush()

			session_base = self._session_base_path()

			async def _auth_async() -> None:
				client = TelegramClient(str(session_base), app_id, api_hash)
				try:
					if use_bot:
						await client.start(bot_token=bot_token)
					else:
						await client.start()
				finally:
					try:
						await client.disconnect()
					except Exception:
						pass

			def _run_in_new_loop() -> None:
				loop = asyncio.new_event_loop()
				try:
					asyncio.set_event_loop(loop)
					loop.run_until_complete(_auth_async())
				finally:
					try:
						loop.close()
					except Exception:
						pass

			# If some framework is already running an event loop in this thread,
			# do the auth flow in a worker thread with its own loop.
			try:
				self._ensure_event_loop()
				main_loop = asyncio.get_event_loop()
				loop_running = bool(getattr(main_loop, "is_running", lambda: False)())
			except Exception:
				loop_running = False

			if loop_running:
				err: list[str] = []
				def _worker() -> None:
					try:
						_run_in_new_loop()
					except Exception as exc:
						err.append(str(exc))
				th = threading.Thread(target=_worker, daemon=True)
				th.start()
				th.join()
				if err:
					self._last_login_error = err[0]
					return False
			else:
				try:
					_run_in_new_loop()
				except Exception as exc:
					self._last_login_error = str(exc)
					return False
		finally:
			try:
				sys.stderr.write("\n")
				sys.stderr.flush()
			except Exception:
				pass

		ok = self._has_session()
		if not ok:
			if not self._last_login_error:
				self._last_login_error = "session was not created"
			return False

		if not self._session_is_authorized():
			if not self._last_login_error:
				self._last_login_error = "session exists but is not authorized"
			return False
		return True

	def _ensure_session_with_bot_token(self, bot_token: str) -> bool:
		"""Create a Telethon session using a bot token without prompting.

		Returns True if a session exists and is authorized after the attempt.
		"""
		self._last_login_error = None
		if self._session_is_authorized():
			return True
		bot_token = str(bot_token or "").strip()
		if not bot_token:
			return False
		try:
			from telethon import TelegramClient
		except Exception as exc:
			self._last_login_error = f"Telethon not available: {exc}"
			return False
		try:
			app_id, api_hash = self._credentials()
		except Exception as exc:
			self._last_login_error = str(exc)
			return False

		session_base = self._session_base_path()

		async def _auth_async() -> None:
			client = TelegramClient(str(session_base), app_id, api_hash)
			try:
				await client.start(bot_token=bot_token)
			finally:
				try:
					await client.disconnect()
				except Exception:
					pass

		try:
			self._run_async_blocking(_auth_async())
		except Exception as exc:
			self._last_login_error = str(exc)
			return False

		if not self._has_session():
			self._last_login_error = "bot login did not create a session"
			return False
		if not self._session_is_authorized():
			self._last_login_error = "bot session exists but is not authorized"
			return False
		return True

	def _resolve_part_size_kb(self, file_size: Optional[int]) -> int:
		# Default: bias to max throughput.
		val = self._part_size_kb
		try:
			if val not in (None, ""):
				ps = int(str(val).strip())
			else:
				ps = 1024
		except Exception:
			ps = 1024

		# Clamp to Telethon-safe range.
		if ps < 4:
			ps = 4
		if ps > 1024:
			ps = 1024
		# Must be divisible by 4.
		ps = int(ps / 4) * 4
		if ps <= 0:
			ps = 64

		# For very small files, reduce overhead a bit (still divisible by 4).
		try:
			if file_size is not None and int(file_size) > 0:
				if int(file_size) < 2 * 1024 * 1024:
					ps = min(ps, 256)
				elif int(file_size) < 10 * 1024 * 1024:
					ps = min(ps, 512)
		except Exception:
			pass
		return ps

	def validate(self) -> bool:
		"""Return True when Telegram can be used in the current context.

		Important behavior: `validate()` must be side-effect free (no prompts).
		Session creation happens on first use.
		"""
		try:
			__import__("telethon")
		except Exception:
			return False

		try:
			app_id = int(self._app_id) if self._app_id not in (None, "") else None
		except Exception:
			app_id = None
		api_hash = str(self._api_hash).strip() if self._api_hash not in (None, "") else ""
		if not bool(app_id and api_hash):
			return False

		# Consider the provider "available" when configured.
		# Authentication/session creation is handled on first use.
		return True

	def ensure_session(self, *, prompt: bool = False) -> bool:
		"""Ensure a Telethon session exists.

		- If an authorized session already exists: returns True.
		- If a bot token is configured: tries to create a session without prompting.
		- If `prompt=True`: attempts interactive login.
		"""
		# Treat "session exists" as insufficient; we need authorization.
		if self._session_is_authorized():
			return True
		bot_token = str(self._bot_token or "").strip()
		if bot_token:
			return bool(self._ensure_session_with_bot_token(bot_token) and self._session_is_authorized())
		if prompt:
			return bool(self._ensure_session_interactive() and self._session_is_authorized())
		return False

	def list_chats(self, *, limit: int = 200) -> list[Dict[str, Any]]:
		"""List dialogs/chats available to the authenticated account.

		Returns a list of dicts with keys: id, title, username, type.
		"""
		# Do not prompt implicitly.
		if not self.ensure_session(prompt=False):
			return []

		try:
			from telethon import TelegramClient
			from telethon.tl.types import Channel, Chat, User
		except Exception:
			return []

		try:
			app_id, api_hash = self._credentials()
		except Exception:
			return []

		session_base = self._session_base_path()

		async def _list_async() -> list[Dict[str, Any]]:
			client = TelegramClient(str(session_base), app_id, api_hash)
			rows: list[Dict[str, Any]] = []
			try:
				await client.connect()
				if not bool(await client.is_user_authorized()):
					return []

				try:
					dialogs = await client.get_dialogs(limit=int(limit))
				except TypeError:
					dialogs = await client.get_dialogs()

				for d in (dialogs or []):
					entity = getattr(d, "entity", None)
					title = ""
					username = ""
					chat_id = None
					kind = ""
					try:
						title = str(getattr(d, "name", "") or "").strip()
					except Exception:
						title = ""

					try:
						if entity is not None:
							maybe_id = getattr(entity, "id", None)
							if maybe_id is not None:
								chat_id = int(maybe_id)
							maybe_username = getattr(entity, "username", None)
							if isinstance(maybe_username, str):
								username = maybe_username.strip()
					except Exception:
						pass

					try:
						if not title and entity is not None:
							for attr in ("title", "first_name", "last_name"):
								v = getattr(entity, attr, None)
								if isinstance(v, str) and v.strip():
									title = v.strip()
									break
					except Exception:
						pass

					try:
						if isinstance(entity, Channel):
							if bool(getattr(entity, "broadcast", False)):
								kind = "channel"
							elif bool(getattr(entity, "megagroup", False)):
								kind = "group"
							else:
								kind = "channel"
						elif isinstance(entity, Chat):
							kind = "group"
						elif isinstance(entity, User):
							kind = "user"
						else:
							kind = type(entity).__name__.lower() if entity is not None else "unknown"
					except Exception:
						kind = "unknown"

					rows.append({"id": chat_id, "title": title, "username": username, "type": kind})
				return rows
			finally:
				try:
					await client.disconnect()
				except Exception:
					pass

		try:
			rows = self._run_async_blocking(_list_async())
		except Exception:
			rows = []

		# Sort for stable display.
		try:
			rows.sort(key=lambda r: (str(r.get("type") or ""), str(r.get("title") or "")))
		except Exception:
			pass
		return rows

	def send_files_to_chats(
		self,
		*,
		chat_ids: Sequence[int],
		usernames: Sequence[str],
		files: Optional[Sequence[Dict[str, Any]]] = None,
		file_paths: Optional[Sequence[str]] = None,
	) -> None:
		"""Send local file(s) to one or more chats.

		This must never prompt. Requires an authorized session (run: .telegram -login).
		Uses Rich ProgressBar for upload progress.
		"""
		# Never prompt implicitly.
		if not self.ensure_session(prompt=False):
			raise Exception("Telegram login required. Run: .telegram -login")

		try:
			from telethon import TelegramClient
			from telethon.tl.types import DocumentAttributeFilename
		except Exception as exc:
			raise Exception(f"Telethon not available: {exc}")

		try:
			from SYS.progress import print_progress, print_final_progress
		except Exception:
			print_progress = None  # type: ignore
			print_final_progress = None  # type: ignore

		try:
			app_id, api_hash = self._credentials()
		except Exception as exc:
			raise Exception(str(exc))

		# Back-compat: allow callers to pass `file_paths=`.
		if files is None:
			files = [{"path": str(p), "title": ""} for p in (file_paths or [])]

		def _sanitize_filename(text: str) -> str:
			# Windows-safe plus generally safe for Telegram.
			name = str(text or "").strip()
			if not name:
				return "file"
			name = name.replace("\x00", " ")
			# Strip characters illegal on Windows filenames.
			name = re.sub(r'[<>:"/\\|?*]', " ", name)
			# Collapse whitespace.
			name = re.sub(r"\s+", " ", name).strip(" .")
			if not name:
				return "file"
			# Keep it reasonable.
			if len(name) > 120:
				name = name[:120].rstrip(" .")
			return name or "file"

		# Normalize and validate file paths + titles.
		jobs: list[Dict[str, Any]] = []
		seen_paths: set[str] = set()
		for f in (files or []):
			try:
				path_text = str((f or {}).get("path") or "").strip()
			except Exception:
				path_text = ""
			if not path_text:
				continue
			path_obj = Path(path_text).expanduser()
			if not path_obj.exists():
				raise Exception(f"File not found: {path_obj}")
			key = str(path_obj).lower()
			if key in seen_paths:
				continue
			seen_paths.add(key)
			title_text = ""
			try:
				title_text = str((f or {}).get("title") or "").strip()
			except Exception:
				title_text = ""
			jobs.append({"path": str(path_obj), "title": title_text})

		if not jobs:
			raise Exception("No files to send")

		session_base = self._session_base_path()
		ids = [int(x) for x in (chat_ids or []) if x is not None]
		try:
			ids = list(dict.fromkeys(ids))
		except Exception:
			pass
		uns = [str(u or "").strip() for u in (usernames or []) if str(u or "").strip()]
		try:
			uns = list(dict.fromkeys([u.strip().lower() for u in uns if u.strip()]))
		except Exception:
			pass
		# Prefer IDs when available; avoid sending twice when both id and username exist.
		if ids:
			uns = []
		if not ids and not uns:
			raise Exception("No chat selected")

		async def _send_async() -> None:
			client = TelegramClient(str(session_base), app_id, api_hash)
			try:
				await client.connect()
				if not bool(await client.is_user_authorized()):
					raise Exception("Telegram session is not authorized. Run: .telegram -login")

				# Resolve entities: prefer IDs. Only fall back to usernames when IDs are absent.
				entities: list[Any] = []
				if ids:
					for cid in ids:
						try:
							e = await client.get_input_entity(int(cid))
							entities.append(e)
						except Exception:
							continue
				else:
					seen_u: set[str] = set()
					for u in uns:
						key = str(u).strip().lower()
						if not key or key in seen_u:
							continue
						seen_u.add(key)
						try:
							e = await client.get_input_entity(str(u))
							entities.append(e)
						except Exception:
							continue

				if not entities:
					raise Exception("Unable to resolve selected chat(s)")

				for entity in entities:
					for job in jobs:
						try:
							p = str(job.get("path") or "").strip()
							if not p:
								continue
							path_obj = Path(p)
							file_size = None
							try:
								file_size = int(path_obj.stat().st_size)
							except Exception:
								file_size = None
							ps = self._resolve_part_size_kb(file_size)

							title_raw = str(job.get("title") or "").strip()
							fallback = path_obj.stem
							base = _sanitize_filename(title_raw) if title_raw else _sanitize_filename(fallback)
							ext = path_obj.suffix
							send_name = f"{base}{ext}" if ext else base

							attributes = [DocumentAttributeFilename(send_name)]

							def _progress(sent: int, total: int) -> None:
								if print_progress is None:
									return
								try:
									print_progress(send_name, int(sent or 0), int(total or 0))
								except Exception:
									return

							# Start the progress UI immediately (even if Telethon delays the first callback).
							if print_progress is not None:
								try:
									print_progress(send_name, 0, int(file_size or 0))
								except Exception:
									pass

							try:
								await client.send_file(
									entity,
									str(path_obj),
									part_size_kb=ps,
									progress_callback=_progress,
									attributes=attributes,
								)
							finally:
								if print_final_progress is not None:
									try:
										print_final_progress(send_name, int(file_size or 0), 0.0)
									except Exception:
										pass
						except Exception as exc:
							raise Exception(str(exc))
			finally:
				try:
					await client.disconnect()
				except Exception:
					pass

		self._run_async_blocking(_send_async())

	def _session_base_path(self) -> Path:
		# Store session alongside cookies.txt at repo root.
		# Telethon uses this as base name and writes "<base>.session".
		root = Path(__file__).resolve().parents[1]
		return root / "telegram"

	def _credentials(self) -> Tuple[int, str]:
		raw_app_id = self._app_id
		if raw_app_id in (None, ""):
			raise Exception("Telegram app_id missing")
		try:
			app_id = int(str(raw_app_id).strip())
		except Exception:
			raise Exception("Telegram app_id invalid")
		api_hash = str(self._api_hash or "").strip()
		if not api_hash:
			raise Exception("Telegram api_hash missing")
		return app_id, api_hash

	def _ensure_event_loop(self) -> None:
		"""Telethon sync wrapper requires an event loop to exist in this thread."""
		try:
			asyncio.get_event_loop()
		except RuntimeError:
			loop = asyncio.new_event_loop()
			asyncio.set_event_loop(loop)

	def _download_message_media_sync(self, *, url: str, output_dir: Path) -> Tuple[Path, Dict[str, Any]]:
		# Ensure we have an authorized session before attempting API calls.
		# Never prompt during downloads.
		if not self.ensure_session(prompt=False):
			raise Exception("Telegram login required. Run: .telegram -login")

		try:
			from telethon import TelegramClient, errors
			from telethon.tl.types import PeerChannel
		except Exception as exc:
			raise Exception(f"Telethon not available: {exc}")

		try:
			output_dir.mkdir(parents=True, exist_ok=True)
		except Exception:
			pass

		app_id, api_hash = self._credentials()
		session_base = self._session_base_path()
		chat, message_id = _parse_telegram_message_url(url)

		async def _download_async() -> Tuple[Path, Dict[str, Any]]:
			client = TelegramClient(str(session_base), app_id, api_hash)
			try:
				await client.connect()
				if not bool(await client.is_user_authorized()):
					raise Exception("Telegram session is not authorized. Run: .telegram -login")

				if chat.startswith("c:"):
					channel_id = int(chat.split(":", 1)[1])
					entity = PeerChannel(channel_id)
				else:
					entity = chat
					if isinstance(entity, str) and entity and not entity.startswith("@"): 
						entity = "@" + entity

				messages = await client.get_messages(entity, ids=[message_id])
				message = None
				if isinstance(messages, (list, tuple)):
					message = messages[0] if messages else None
				else:
					try:
						message = messages[0]  # type: ignore[index]
					except Exception:
						message = None
				if not message:
					raise Exception("Telegram message not found")
				if not getattr(message, "media", None):
					raise Exception("Telegram message has no media")

				chat_title = ""
				chat_username = ""
				chat_id = None
				try:
					chat_obj = getattr(message, "chat", None)
					if chat_obj is not None:
						maybe_title = getattr(chat_obj, "title", None)
						maybe_username = getattr(chat_obj, "username", None)
						maybe_id = getattr(chat_obj, "id", None)
						if isinstance(maybe_title, str):
							chat_title = maybe_title.strip()
						if isinstance(maybe_username, str):
							chat_username = maybe_username.strip()
						if maybe_id is not None:
							chat_id = int(maybe_id)
				except Exception:
					pass

				caption = ""
				try:
					maybe_caption = getattr(message, "message", None)
					if isinstance(maybe_caption, str):
						caption = maybe_caption.strip()
				except Exception:
					pass

				msg_id = None
				msg_date = None
				try:
					msg_id = int(getattr(message, "id", 0) or 0)
				except Exception:
					msg_id = None
				try:
					msg_date = getattr(message, "date", None)
				except Exception:
					msg_date = None

				file_name = ""
				file_mime = ""
				file_size = None
				try:
					file_obj = getattr(message, "file", None)
					maybe_name = getattr(file_obj, "name", None)
					maybe_mime = getattr(file_obj, "mime_type", None)
					maybe_size = getattr(file_obj, "size", None)
					if isinstance(maybe_name, str):
						file_name = maybe_name.strip()
					if isinstance(maybe_mime, str):
						file_mime = maybe_mime.strip()
					if maybe_size is not None:
						file_size = int(maybe_size)
				except Exception:
					pass

				from models import ProgressBar
				progress_bar = ProgressBar()
				last_print = {"t": 0.0}
				def _progress(current: int, total: int) -> None:
					now = time.monotonic()
					if now - float(last_print.get("t", 0.0)) < 0.25 and current < total:
						return
					last_print["t"] = now
					progress_bar.update(downloaded=int(current), total=int(total), label="telegram", file=sys.stderr)

				part_kb = self._resolve_part_size_kb(file_size)
				try:
					downloaded = await client.download_media(
						message,
						file=str(output_dir),
						progress_callback=_progress,
						part_size_kb=part_kb,
					)
				except TypeError:
					downloaded = await client.download_media(message, file=str(output_dir), progress_callback=_progress)
				progress_bar.finish()
				if not downloaded:
					raise Exception("Telegram download returned no file")
				downloaded_path = Path(str(downloaded))

				# Telethon's default media filenames include timestamps (e.g. photo_YYYY-MM-DD_HH-MM-SS.jpg).
				# Strip those timestamps ONLY when Telegram didn't provide an explicit filename.
				if not file_name:
					downloaded_path = _maybe_strip_telegram_timestamped_default_filename(
						downloaded_path=downloaded_path,
					)

				date_iso = None
				try:
					if msg_date is not None and hasattr(msg_date, "isoformat"):
						date_iso = msg_date.isoformat()  # type: ignore[union-attr]
				except Exception:
					date_iso = None

				info: Dict[str, Any] = {
					"provider": "telegram",
					"source_url": url,
					"chat": {
						"key": chat,
						"title": chat_title,
						"username": chat_username,
						"id": chat_id,
					},
					"message": {
						"id": msg_id,
						"date": date_iso,
						"caption": caption,
					},
					"file": {
						"name": file_name,
						"mime_type": file_mime,
						"size": file_size,
						"downloaded_path": str(downloaded_path),
					},
				}
				return downloaded_path, info
			except errors.RPCError as exc:
				raise Exception(f"Telegram RPC error: {exc}")
			finally:
				try:
					await client.disconnect()
				except Exception:
					pass

		return self._run_async_blocking(_download_async())

	def download_url(self, url: str, output_dir: Path) -> Tuple[Path, Dict[str, Any]]:
		"""Download a Telegram message URL and return (path, metadata)."""
		if not _looks_like_telegram_message_url(url):
			raise ValueError("Not a Telegram URL")
		return self._download_message_media_sync(url=url, output_dir=output_dir)

	def download(self, result: SearchResult, output_dir: Path) -> Optional[Path]:
		url = str(getattr(result, "path", "") or "")
		if not url:
			return None
		if not _looks_like_telegram_message_url(url):
			return None

		path, _info = self._download_message_media_sync(url=url, output_dir=output_dir)
		return path