izteamslots 1.1.0

package/backend/file_logger.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import json
+import threading
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from . import PROJECT_ROOT
+
+
+def _timestamp() -> str:
+    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+
+def _safe_title(value: str) -> str:
+    cleaned = "".join(ch if ch.isalnum() or ch in {"-", "_"} else "_" for ch in value.strip().lower())
+    while "__" in cleaned:
+        cleaned = cleaned.replace("__", "_")
+    return cleaned.strip("_") or "job"
+
+
+class FileLogger:
+    def __init__(self, root: Path | None = None) -> None:
+        self.root = root or (PROJECT_ROOT / "logs")
+        self.jobs_dir = self.root / "jobs"
+        self.app_log = self.root / "app.log"
+        self._lock = threading.Lock()
+        self.jobs_dir.mkdir(parents=True, exist_ok=True)
+
+    def _append(self, path: Path, lines: list[str]) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with self._lock:
+            with path.open("a", encoding="utf-8") as fh:
+                for line in lines:
+                    fh.write(line.rstrip("\n") + "\n")
+
+    def info(self, message: str) -> None:
+        self._append(self.app_log, [f"[{_timestamp()}] INFO  {message}"])
+
+    def error(self, message: str, traceback_text: str | None = None) -> None:
+        lines = [f"[{_timestamp()}] ERROR {message}"]
+        if traceback_text:
+            lines.extend(traceback_text.rstrip().splitlines())
+        self._append(self.app_log, lines)
+
+    def create_job_logger(self, job_id: str, title: str) -> "JobFileLogger":
+        stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+        filename = f"{stamp}-{job_id[:8]}-{_safe_title(title)}.log"
+        path = self.jobs_dir / filename
+        rel_path = path.relative_to(PROJECT_ROOT).as_posix()
+        logger = JobFileLogger(path=path, rel_path=rel_path, title=title, root_logger=self)
+        logger.log(f"JOB START: {title}")
+        self.info(f"Job created: {title} [{job_id}] -> {rel_path}")
+        return logger
+
+
+@dataclass
+class JobFileLogger:
+    path: Path
+    rel_path: str
+    title: str
+    root_logger: FileLogger
+
+    def log(self, message: str) -> None:
+        self.root_logger._append(self.path, [f"[{_timestamp()}] {message}"])
+
+    def progress(self, current: int, total: int, message: str | None = None) -> None:
+        suffix = f" {message}" if message else ""
+        self.log(f"PROGRESS {current}/{total}{suffix}")
+
+    def done(self, result: Any) -> None:
+        rendered = json.dumps(result, ensure_ascii=False, default=str) if result is not None else "null"
+        self.log(f"JOB DONE: {rendered}")
+
+    def error(self, message: str, traceback_text: str | None = None) -> None:
+        lines = [f"[{_timestamp()}] JOB ERROR: {message}"]
+        if traceback_text:
+            lines.extend(traceback_text.rstrip().splitlines())
+        self.root_logger._append(self.path, lines)
+        self.root_logger.error(f"{self.title}: {message}", traceback_text=traceback_text)

package/backend/jobs.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import threading
+import traceback
+import uuid
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from .file_logger import FileLogger, JobFileLogger
+
+EmitFunc = Callable[[str, dict[str, Any]], None]
+
+
+@dataclass
+class JobContext:
+    job_id: str
+    _emit: EmitFunc
+    _logger: JobFileLogger
+
+    def log(self, message: str) -> None:
+        rendered = str(message)
+        self._logger.log(rendered)
+        self._emit(
+            "job.log",
+            {
+                "job_id": self.job_id,
+                "message": rendered,
+            },
+        )
+
+    def progress(self, current: int, total: int, message: str | None = None) -> None:
+        self._logger.progress(current, total, message)
+        payload: dict[str, Any] = {
+            "job_id": self.job_id,
+            "current": current,
+            "total": total,
+        }
+        if message:
+            payload["message"] = message
+        self._emit("job.progress", payload)
+
+
+class JobManager:
+    def __init__(self, emit: EmitFunc, file_logger: FileLogger | None = None) -> None:
+        self._emit = emit
+        self._file_logger = file_logger or FileLogger()
+
+    def start(self, title: str, handler: Callable[[JobContext], Any]) -> str:
+        job_id = uuid.uuid4().hex
+        job_logger = self._file_logger.create_job_logger(job_id, title)
+        self._emit("job.started", {"job_id": job_id, "title": title, "log_path": job_logger.rel_path})
+
+        def runner() -> None:
+            ctx = JobContext(job_id=job_id, _emit=self._emit, _logger=job_logger)
+            try:
+                result = handler(ctx)
+                job_logger.done(result)
+                self._emit("job.done", {"job_id": job_id, "result": result, "log_path": job_logger.rel_path})
+            except Exception as e:
+                message = str(e)
+                if len(message) > 1200:
+                    message = message[:1200] + "…"
+                tb = traceback.format_exc()
+                job_logger.error(message, traceback_text=tb)
+                self._emit(
+                    "job.error",
+                    {
+                        "job_id": job_id,
+                        "error": message,
+                        "traceback": tb,
+                        "log_path": job_logger.rel_path,
+                    },
+                )
+
+        thread = threading.Thread(target=runner, daemon=True)
+        thread.start()
+        return job_id

package/backend/mail/__init__.py

@@ -0,0 +1,98 @@
+"""Pluggable mail provider system.
+
+Usage::
+
+    from backend.mail import create_provider, Mailbox
+
+    provider = create_provider()          # generic/default: "trickads"
+    mailbox = provider.generate()         # create disposable mailbox
+    inbox = provider.inbox(mailbox)       # fetch messages
+    provider.close()
+
+    slot_provider = create_slot_provider()  # slots default: "boomlify"
+
+Select provider via env var or name::
+
+    MAIL_PROVIDER=imap IMAP_HOST=imap.example.com python app.py
+
+    provider = create_provider("imap", host="imap.example.com")
+
+Available providers:
+    trickads - trickadsagencyltd.com temp mail (generic/default)
+    boomlify - Boomlify temp mail API (slots default)
+    imap     - any IMAP server (env: IMAP_HOST, IMAP_PORT, IMAP_SSL)
+
+Custom providers:
+    Subclass ``MailProvider`` from ``backend.mail.base`` and implement
+    ``generate()`` and ``inbox()``.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from .base import Inbox, Mail, MailAuthError, Mailbox, MailError, MailProvider, MailServiceUnavailable
+
+__all__ = [
+    "Inbox",
+    "Mail",
+    "MailAuthError",
+    "MailError",
+    "MailProvider",
+    "MailServiceUnavailable",
+    "Mailbox",
+    "create_provider",
+    "create_provider_for_mailbox",
+    "create_slot_provider",
+]
+
+_BUILTIN_PROVIDERS = ("boomlify", "trickads", "imap")
+
+
+def create_provider(name: str | None = None, **kwargs: Any) -> MailProvider:
+    """Create a mail provider instance by name.
+
+    Args:
+        name: Provider name. Defaults to ``MAIL_PROVIDER`` env var,
+              then falls back to ``"trickads"``.
+        **kwargs: Passed to provider constructor.
+    """
+    provider_name = name or os.environ.get("MAIL_PROVIDER", "trickads")
+
+    if provider_name == "boomlify":
+        from .boomlify import BoomlifyProvider
+        return BoomlifyProvider(**kwargs)
+
+    if provider_name == "trickads":
+        from .trickads import TrickAdsProvider
+        return TrickAdsProvider(**kwargs)
+
+    if provider_name == "imap":
+        from .imap import IMAPProvider
+        return IMAPProvider(**kwargs)
+
+    raise ValueError(
+        f"Unknown mail provider: {provider_name!r}. "
+        f"Available: {', '.join(_BUILTIN_PROVIDERS)}"
+    )
+
+
+def create_slot_provider(name: str | None = None, **kwargs: Any) -> MailProvider:
+    """Create provider for worker/slot mailboxes.
+
+    Defaults to ``SLOT_MAIL_PROVIDER``, then falls back to ``"boomlify"``.
+    """
+    provider_name = name or os.environ.get("SLOT_MAIL_PROVIDER", "boomlify")
+    return create_provider(provider_name, **kwargs)
+
+
+def create_provider_for_mailbox(mailbox: Mailbox, **kwargs: Any) -> MailProvider:
+    """Pick provider based on stored mailbox credentials.
+
+    Boomlify mailboxes store their email id inside ``Mailbox.password`` as
+    ``boomlify:<uuid>``. Everything else falls back to the generic provider.
+    """
+    password = mailbox.password.strip()
+    if password.startswith("boomlify:"):
+        return create_provider("boomlify", **kwargs)
+    return create_provider(**kwargs)

package/backend/mail/base.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+class MailError(Exception):
+    """Base exception for all mail provider errors."""
+
+
+class MailAuthError(MailError):
+    """Authentication failed (wrong password, expired token, etc.)."""
+
+
+class MailServiceUnavailable(MailError):
+    """Mail service is temporarily unavailable."""
+
+
+@dataclass(frozen=True, slots=True)
+class Mailbox:
+    """Credentials for a single mailbox."""
+    email: str
+    password: str
+
+
+@dataclass(frozen=True, slots=True)
+class Mail:
+    """A single email message."""
+    id: str
+    sender: str
+    subject: str
+    body: str
+    date: str
+
+
+@dataclass(frozen=True, slots=True)
+class Inbox:
+    """Inbox contents for a mailbox."""
+    email: str
+    messages: list[Mail]
+
+
+class MailProvider(ABC):
+    """Abstract base class for mail providers.
+
+    To create a custom provider, subclass this and implement
+    ``generate()`` and ``inbox()``.
+
+    Minimal example::
+
+        from backend.mail.base import MailProvider, Mailbox, Inbox
+
+        class MyProvider(MailProvider):
+            name = "my_provider"
+
+            def generate(self) -> Mailbox:
+                # create a new disposable mailbox
+                ...
+
+            def inbox(self, mailbox: Mailbox) -> Inbox:
+                # fetch messages for the mailbox
+                ...
+    """
+
+    name: str = "base"
+
+    @abstractmethod
+    def generate(self) -> Mailbox:
+        """Create a new disposable mailbox.
+
+        Returns a ``Mailbox`` with email and password (or token)
+        that can later be passed to ``inbox()``.
+        """
+
+    @abstractmethod
+    def inbox(self, mailbox: Mailbox) -> Inbox:
+        """Fetch current messages for a mailbox."""
+
+    def close(self) -> None:
+        """Release resources (HTTP sessions, connections, etc.)."""
+
+    def __enter__(self) -> MailProvider:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

package/backend/mail/boomlify.py

@@ -0,0 +1,178 @@
+"""Mail provider: Boomlify Temp Mail API."""
+from __future__ import annotations
+
+import os
+from typing import Any
+from urllib.parse import urlencode
+
+import requests
+
+from .base import (
+    Inbox,
+    Mail,
+    MailAuthError,
+    Mailbox,
+    MailError,
+    MailProvider,
+    MailServiceUnavailable,
+)
+
+DEFAULT_BASE_URL = "https://v1.boomlify.com"
+DEFAULT_TIME = "permanent"
+
+
+def _unwrap_payload(data: Any) -> Any:
+    if isinstance(data, dict):
+        for key in ("data", "result", "email", "message", "messages"):
+            value = data.get(key)
+            if value is not None:
+                return value
+    return data
+
+
+def _as_dict(value: Any) -> dict[str, Any]:
+    return value if isinstance(value, dict) else {}
+
+
+def _as_list(value: Any) -> list[Any]:
+    return value if isinstance(value, list) else []
+
+
+def _pick_first_str(obj: dict[str, Any], keys: tuple[str, ...]) -> str:
+    for key in keys:
+        value = obj.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return ""
+
+
+class BoomlifyProvider(MailProvider):
+    """Temporary email via Boomlify API."""
+
+    name = "boomlify"
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        mailbox_time: str | None = None,
+        domain: str | None = None,
+        session: requests.Session | None = None,
+        **_kwargs: Any,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("BOOMLIFY_API_KEY", "").strip()
+        if not self.api_key:
+            raise MailAuthError("BOOMLIFY_API_KEY is required for Boomlify mail provider")
+
+        self.base_url = (base_url or os.environ.get("BOOMLIFY_BASE_URL", DEFAULT_BASE_URL)).rstrip("/")
+        self.mailbox_time = mailbox_time or os.environ.get("BOOMLIFY_TIME", DEFAULT_TIME)
+        self.domain = domain or os.environ.get("BOOMLIFY_DOMAIN", "").strip()
+        self._external = session is not None
+        self._session = session or requests.Session()
+        self._session.headers.update({
+            "X-API-Key": self.api_key,
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": "izTeamSlots/1.0",
+        })
+
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+        query: dict[str, Any] | None = None,
+    ) -> Any:
+        url = f"{self.base_url}{endpoint}"
+        if query:
+            clean_query = {k: v for k, v in query.items() if v is not None and v != ""}
+            if clean_query:
+                url = f"{url}?{urlencode(clean_query)}"
+
+        try:
+            resp = self._session.request(method, url, json=json_body, timeout=30)
+        except requests.RequestException as e:
+            raise MailServiceUnavailable(f"Connection error: {e}") from e
+
+        try:
+            data = resp.json()
+        except ValueError:
+            data = {"error": resp.text.strip()[:500]}
+
+        if resp.status_code in (401, 403):
+            raise MailAuthError(f"[{resp.status_code}] {data}")
+        if resp.status_code in (429, 500, 502, 503, 504):
+            raise MailServiceUnavailable(f"[{resp.status_code}] {data}")
+        if resp.status_code >= 400:
+            raise MailError(f"[{resp.status_code}] {data}")
+        return data
+
+    def _extract_mailbox_id(self, mailbox: Mailbox) -> str:
+        password = mailbox.password.strip()
+        if password.startswith("boomlify:"):
+            return password.split(":", 1)[1].strip()
+        if password:
+            return password
+        raise MailError(
+            f"Mailbox {mailbox.email} does not contain Boomlify mailbox id. "
+            "Expected Mailbox.password to store the Boomlify email id."
+        )
+
+    def generate(self) -> Mailbox:
+        payload: dict[str, Any] = {"time": self.mailbox_time}
+        if self.domain:
+            payload["domain"] = self.domain
+
+        raw = self._request("POST", "/api/v1/emails/create", json_body=payload)
+        email_data = _as_dict(_unwrap_payload(raw))
+        email = _pick_first_str(email_data, ("email", "address"))
+        email_id = _pick_first_str(email_data, ("id", "email_id", "uuid"))
+
+        if not email or not email_id:
+            raise MailError(f"Unexpected Boomlify create response: {raw}")
+
+        return Mailbox(email=email, password=f"boomlify:{email_id}")
+
+    def inbox(self, mailbox: Mailbox) -> Inbox:
+        email_id = self._extract_mailbox_id(mailbox)
+        raw = self._request(
+            "GET",
+            f"/api/v1/emails/{email_id}/messages",
+            query={"limit": 100, "offset": 0},
+        )
+
+        messages_raw: list[Any] = []
+        if isinstance(raw, dict):
+            messages_raw = _as_list(raw.get("messages")) or _as_list(raw.get("items"))
+        if not messages_raw:
+            payload = _unwrap_payload(raw)
+            messages_raw = _as_list(payload)
+
+        messages: list[Mail] = []
+        for item in messages_raw:
+            msg = _as_dict(item)
+            sender_value = msg.get("from")
+            sender = _pick_first_str(msg, ("from_email", "from_name"))
+            if not sender:
+                if isinstance(sender_value, dict):
+                    sender = _pick_first_str(sender_value, ("email", "address", "name"))
+                elif isinstance(sender_value, str):
+                    sender = sender_value.strip()
+
+            body = _pick_first_str(msg, ("body_html", "html", "body_text", "body", "text", "content"))
+            messages.append(
+                Mail(
+                    id=_pick_first_str(msg, ("id", "message_id", "uuid")) or body[:32],
+                    sender=sender,
+                    subject=_pick_first_str(msg, ("subject", "title")),
+                    body=body,
+                    date=_pick_first_str(msg, ("date", "created_at", "received_at", "timestamp")),
+                )
+            )
+
+        return Inbox(email=mailbox.email, messages=messages)
+
+    def close(self) -> None:
+        if not self._external:
+            self._session.close()