YurMail 0.1.0__py3-none-any.whl

YurMail/LLM/__init__.py

@@ -0,0 +1,4 @@
+from .client import OpenAIDraftClient
+from .types import DraftResult
+
+__all__ = ["OpenAIDraftClient", "DraftResult"]

YurMail/LLM/client.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from openai import AsyncOpenAI
+
+from .prompts import build_draft_prompt
+from .types import DraftResult
+
+
+class OpenAIDraftClient:
+    """
+    Small async client for generating email drafts with OpenAI.
+    """
+
+    def __init__(self, api_key: str | None = None, model: str = "gpt-5.4-mini"):
+        self._client = AsyncOpenAI(api_key=api_key)
+        self._model = model
+
+    async def test_connection(self, message: str) -> str:
+        """
+        Simple helper to verify that the LLM connection works.
+        """
+        response = await self._client.responses.create(
+            model=self._model,
+            input=message,
+        )
+        return response.output_text.strip()
+
+    async def generate_draft(
+        self,
+        purpose: str,
+        recipient_name: str | None = None,
+        tone: str = "professional",
+        context: str | None = None,
+        language: str = "es",
+    ) -> DraftResult:
+        """
+        Generate an email draft and return structured subject/body output.
+        """
+        prompt = build_draft_prompt(
+            purpose=purpose,
+            recipient_name=recipient_name,
+            tone=tone,
+            context=context,
+            language=language,
+        )
+
+        response = await self._client.responses.create(
+            model=self._model,
+            input=prompt,
+        )
+
+        text = response.output_text.strip()
+        subject, body = self._parse_subject_and_body(text)
+
+        return DraftResult(subject=subject, body=body, raw=text)
+
+    @staticmethod
+    def _parse_subject_and_body(text: str) -> tuple[str, str]:
+        """
+        Parse a response of the form:
+
+        SUBJECT: ...
+        BODY: ...
+        """
+        subject = ""
+        body = text
+
+        if "SUBJECT:" in text and "BODY:" in text:
+            before, after = text.split("BODY:", 1)
+            subject = before.replace("SUBJECT:", "").strip()
+            body = after.strip()
+
+        return subject, body

YurMail/LLM/prompts.py

@@ -0,0 +1,46 @@
+def build_draft_prompt(
+    purpose: str,
+    recipient_name: str | None = None,
+    tone: str = "professional",
+    context: str | None = None,
+    language: str = "es",
+) -> str:
+    """
+    Build a prompt for generating an email draft.
+
+    Parameters
+    ----------
+    purpose:
+        Main objective of the email.
+    recipient_name:
+        Optional recipient name.
+    tone:
+        Desired writing tone.
+    context:
+        Extra context or constraints.
+    language:
+        Output language, e.g. "es" or "en".
+    """
+    recipient_text = recipient_name or "destinatario"
+    context_text = context or "Sin contexto adicional."
+
+    return f"""
+Redacta un correo electrónico en {language}.
+
+Objetivo: {purpose}
+Destinatario: {recipient_text}
+Tono: {tone}
+Contexto adicional: {context_text}
+
+Instrucciones:
+- Escribe un asunto claro y profesional.
+- Escribe un cuerpo de correo natural, bien redactado y coherente.
+- No inventes hechos que no aparezcan en el contexto.
+- Mantén el tono solicitado.
+- Si falta información, redacta de forma prudente y general.
+
+Devuelve tu respuesta estrictamente en este formato:
+
+SUBJECT: ...
+BODY: ...
+""".strip()

YurMail/LLM/types.py

@@ -0,0 +1,7 @@
+from dataclasses import dataclass
+
+@dataclass
+class DraftResult:
+    subject: str
+    body: str
+    raw: str

YurMail/__init__.py

@@ -0,0 +1,61 @@
+from .authentication_microsoft import GraphAuthManager, OAuthCallbackResult
+from .mail import (
+    GraphMailClient, GraphAPIError,
+    Message, MailAddress, UserProfile, Draft,
+    attachment_from_bytes,
+    MailTemplate, TemplateRegistry,
+    TemplateMissingVariableError, TemplateNotFoundError,
+    TEMPLATE_RECORDATORIO, TEMPLATE_SEGUIMIENTO, TEMPLATE_REPORTE, text_to_html,
+)
+from .LLM import OpenAIDraftClient, DraftResult
+from .scheduler import (
+    Scheduler,
+    AbstractScheduleStore,
+    InMemoryStore,
+    JsonFileStore,
+    ScheduledEmail,
+    ScheduleStatus,
+    SchedulerResult,
+    TriggerType,
+    EmailBuilder,
+)
+
+__version__ = "0.3.0"
+
+__all__ = [
+    # Auth
+    "GraphAuthManager",
+    "OAuthCallbackResult",
+    # Mail cliente
+    "GraphMailClient",
+    "GraphAPIError",
+    # Modelos
+    "Message",
+    "MailAddress",
+    "UserProfile",
+    "Draft",
+    # Adjuntos
+    "attachment_from_bytes",
+    # Templates
+    "MailTemplate",
+    "TemplateRegistry",
+    "TemplateMissingVariableError",
+    "TemplateNotFoundError",
+    "TEMPLATE_RECORDATORIO",
+    "TEMPLATE_SEGUIMIENTO",
+    "TEMPLATE_REPORTE",
+    "text_to_html",
+    # LLM
+    "OpenAIDraftClient",
+    "DraftResult",
+    # Scheduler
+    "Scheduler",
+    "AbstractScheduleStore",
+    "InMemoryStore",
+    "JsonFileStore",
+    "ScheduledEmail",
+    "ScheduleStatus",
+    "SchedulerResult",
+    "TriggerType",
+    "EmailBuilder",
+]

YurMail/authentication_microsoft/__init__.py

@@ -0,0 +1,3 @@
+from .authentication import GraphAuthManager, OAuthCallbackResult
+ 
+__all__ = ["GraphAuthManager", "OAuthCallbackResult"]

YurMail/authentication_microsoft/authentication.py

@@ -0,0 +1,260 @@
+import asyncio
+import base64
+import hashlib
+import secrets
+import webbrowser
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlencode, urlparse
+
+import aiohttp
+from aiohttp import web
+
+
+@dataclass
+class OAuthCallbackResult:
+    code: str | None = None
+    state: str | None = None
+    error: str | None = None
+    error_description: str | None = None
+
+
+class GraphAuthManager:
+    """
+    Handle Microsoft OAuth 2.0 Authorization Code Flow with PKCE
+    for a local/public client.
+
+    Parameters
+  
+    client_id:
+        Application (client) ID from Microsoft Entra app registration.
+    tenant:
+        Usually "common", "organizations"
+    redirect_uri:
+        Must exactly match a registered redirect URI, e.g.
+        "http://localhost:8765/callback".
+    scopes:
+        List of scopes such as:
+        ["offline_access", "User.Read", "Mail.Send"]
+    """
+
+    def __init__(self, client_id, tenant, redirect_uri, scopes):
+        self.client_id = client_id
+        self.tenant = tenant
+        self.redirect_uri = redirect_uri
+        self.scopes = scopes
+
+        self._authorize_endpoint = (
+            f"https://login.microsoftonline.com/{self.tenant}/oauth2/v2.0/authorize"
+        )
+        self._token_endpoint = (
+            f"https://login.microsoftonline.com/{self.tenant}/oauth2/v2.0/token"
+        )
+
+        parsed = urlparse(self.redirect_uri)
+        if parsed.scheme not in {"http", "https"}:
+            raise ValueError("redirect_uri must start with http:// or https://")
+        if not parsed.hostname:
+            raise ValueError("redirect_uri must include a hostname")
+        if not parsed.port:
+            raise ValueError(
+                "redirect_uri must include an explicit port for the local callback server"
+            )
+
+        self._redirect_host = parsed.hostname
+        self._redirect_port = parsed.port
+        self._redirect_path = parsed.path or "/"
+
+        self._last_state: str | None = None
+        self._last_code_verifier: str | None = None
+        self._last_token_response: dict[str, Any] | None = None
+
+    @staticmethod
+    def _generate_state() -> str:
+        """Generate a random state value for CSRF protection."""
+        return secrets.token_urlsafe(32)
+
+    @staticmethod
+    def _generate_code_verifier() -> str:
+        """
+        Generate a PKCE code verifier.
+        RFC 7636 allows 43-128 chars; urlsafe token is convenient here.
+        """
+        verifier = secrets.token_urlsafe(64)
+        return verifier[:128]
+
+    @staticmethod
+    def _generate_code_challenge(code_verifier: str) -> str:
+        """Generate the PKCE S256 code challenge from a verifier."""
+        digest = hashlib.sha256(code_verifier.encode("ascii")).digest()
+        return base64.urlsafe_b64encode(digest).decode("ascii").rstrip("=")
+
+
+    def build_authorization_url(self, state: str) -> str:
+        """
+        Build the Microsoft authorization URL.
+
+        This implementation uses PKCE for a public/local client.
+        """
+        code_verifier = self._generate_code_verifier()
+        code_challenge = self._generate_code_challenge(code_verifier)
+
+        self._last_state = state
+        self._last_code_verifier = code_verifier
+
+        params = {
+            "client_id": self.client_id,
+            "response_type": "code",
+            "redirect_uri": self.redirect_uri,
+            "response_mode": "query",
+            "scope": " ".join(self.scopes),
+            "state": state,
+            "code_challenge": code_challenge,
+            "code_challenge_method": "S256",
+        }
+        return f"{self._authorize_endpoint}?{urlencode(params)}"
+
+    def _build_callback_app(
+        self,
+        result: OAuthCallbackResult,
+        stop_event: asyncio.Event,
+    ) -> web.Application:
+        """
+        Construye una app aiohttp de un solo endpoint para capturar
+        el redirect de Microsoft.
+
+        `stop_event` se activa una vez que se recibe la respuesta,
+        permitiendo que `login()` detenga el servidor limpiamente.
+        """
+        expected_path = self._redirect_path
+
+        async def callback_handler(request: web.Request) -> web.Response:
+            if request.path != expected_path:
+                raise web.HTTPNotFound()
+
+            result.code = request.query.get("code")
+            result.state = request.query.get("state")
+            result.error = request.query.get("error")
+            result.error_description = request.query.get("error_description")
+
+            stop_event.set()
+
+            return web.Response(
+                content_type="text/html",
+                text="""
+                <html>
+                    <body style="font-family: Arial, sans-serif; margin: 2rem;">
+                        <h2>Autenticacion completada</h2>
+                        <p>Ya puedes cerrar esta ventana y volver a la terminal.</p>
+                    </body>
+                </html>
+                """,
+            )
+
+        app = web.Application()
+        app.router.add_get(expected_path, callback_handler)
+        # Captura también requests inesperados (e.g. favicon) sin crashear.
+        app.router.add_get("/{tail:.*}", lambda r: web.Response(status=204))
+        return app
+
+    async def login(self) -> dict:
+        """
+        Complete the interactive login flow.
+
+        Steps:
+        1. Generate state
+        2. Build authorization URL with PKCE
+        3. Start local aiohttp callback server
+        4. Open browser
+        5. Wait for redirect with authorization code
+        6. Exchange code for tokens
+        7. Shut down callback server
+        """
+        state = self._generate_state()
+        auth_url = self.build_authorization_url(state)
+
+        stop_event = asyncio.Event()
+        result = OAuthCallbackResult()
+        app = self._build_callback_app(result, stop_event)
+
+        runner = web.AppRunner(app)
+        await runner.setup()
+
+        site = web.TCPSite(runner, self._redirect_host, self._redirect_port)
+        await site.start()
+
+        webbrowser.open(auth_url)
+
+        try:
+            await asyncio.wait_for(stop_event.wait(), timeout=300)
+        except asyncio.TimeoutError:
+            raise TimeoutError("Timed out waiting for OAuth callback")
+        finally:
+            await runner.cleanup()
+
+        if result.error:
+            raise RuntimeError(
+                f"Authorization failed: {result.error} - {result.error_description}"
+            )
+
+        if not result.code:
+            raise RuntimeError("No authorization code received in callback")
+
+        if result.state != self._last_state:
+            raise RuntimeError("State mismatch in OAuth callback")
+
+        return await self.exchange_code_for_token(result.code)
+
+
+    async def exchange_code_for_token(self, code: str) -> dict:
+        """
+        Exchange an authorization code for tokens.
+
+        Uses PKCE code_verifier instead of a client secret.
+        Migrado a aiohttp para no mezclar requests síncronos con asyncio.
+        """
+        if not self._last_code_verifier:
+            raise RuntimeError(
+                "No PKCE code verifier available. Call build_authorization_url() first."
+            )
+
+        data = {
+            "client_id": self.client_id,
+            "grant_type": "authorization_code",
+            "code": code,
+            "redirect_uri": self.redirect_uri,
+            "scope": " ".join(self.scopes),
+            "code_verifier": self._last_code_verifier,
+        }
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                self._token_endpoint, data=data, timeout=aiohttp.ClientTimeout(total=30)
+            ) as response:
+                response.raise_for_status()
+                token_data = await response.json()
+
+        self._last_token_response = token_data
+        return token_data
+
+    async def refresh_access_token(self, refresh_token: str) -> dict:
+        """
+        Use a refresh token to get a new token set.
+        Migrado a aiohttp para consistencia async.
+        """
+        data = {
+            "client_id": self.client_id,
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+            "scope": " ".join(self.scopes),
+        }
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                self._token_endpoint, data=data, timeout=aiohttp.ClientTimeout(total=30)
+            ) as response:
+                response.raise_for_status()
+                token_data = await response.json()
+
+        self._last_token_response = token_data
+        return token_data

YurMail/mail/__init__.py

@@ -0,0 +1,28 @@
+from .client import (
+    GraphMailClient, GraphAPIError,
+    Message, MailAddress, UserProfile, Draft,
+    attachment_from_bytes,
+)
+from .templates import (
+    MailTemplate, TemplateRegistry,
+    TemplateMissingVariableError, TemplateNotFoundError,
+    TEMPLATE_RECORDATORIO, TEMPLATE_SEGUIMIENTO, TEMPLATE_REPORTE, text_to_html,
+)
+ 
+__all__ = [
+    "GraphMailClient",
+    "GraphAPIError",
+    "Message",
+    "MailAddress",
+    "UserProfile",
+    "Draft",
+    "attachment_from_bytes",
+    "MailTemplate",
+    "TemplateRegistry",
+    "TemplateMissingVariableError",
+    "TemplateNotFoundError",
+    "TEMPLATE_RECORDATORIO",
+    "TEMPLATE_SEGUIMIENTO",
+    "TEMPLATE_REPORTE",
+    "text_to_html",
+]