lumera 0.9.8__py3-none-any.whl → 0.10.0__py3-none-any.whl

lumera/__init__.py

@@ -13,7 +13,7 @@ except PackageNotFoundError:
     __version__ = "unknown"  # Not installed (e.g., running from source)
 
 # Import new modules (as modules, not individual functions)
-from . import automations, exceptions, integrations, llm, locks, pb, storage, webhooks
+from . import automations, email, exceptions, integrations, llm, locks, pb, storage, webhooks
 from ._utils import (
     LumeraAPIError,
     RecordNotUniqueError,
@@ -102,6 +102,7 @@ __all__ = [
     "LockHeldError",
     # New modules (use as lumera.pb, lumera.storage, etc.)
     "automations",
+    "email",
     "pb",
     "storage",
     "llm",

lumera/automations.py

@@ -57,18 +57,76 @@ __all__ = [
     "create",
     "update",
     "upsert",
-    # Log streaming and download
+    # Log functions
     "stream_logs",
+    "get_logs",
     "get_log_download_url",
     # Classes
     "Run",
     "Automation",
+    "LogsResponse",
 ]
 
 from ._utils import LumeraAPIError, _api_request
 from .sdk import get_automation_run as _get_automation_run
 from .sdk import run_automation as _run_automation
 
+# ============================================================================
+# LogsResponse Class
+# ============================================================================
+
+
+class LogsResponse:
+    """Response from fetching automation run logs.
+
+    Attributes:
+        data: Raw log content as a string (NDJSON format).
+        offset: Byte offset where this chunk starts.
+        size: Number of bytes in this chunk.
+        total_size: Total size of the log file.
+        has_more: True if there are more logs after this chunk.
+        source: Where logs came from ("live" or "archived").
+        truncated: True if logs were truncated at storage time (>50MB).
+    """
+
+    def __init__(self, data: dict[str, Any]) -> None:
+        self._data = data
+
+    @property
+    def data(self) -> str:
+        return self._data.get("data", "")
+
+    @property
+    def offset(self) -> int:
+        return self._data.get("offset", 0)
+
+    @property
+    def size(self) -> int:
+        return self._data.get("size", 0)
+
+    @property
+    def total_size(self) -> int:
+        return self._data.get("total_size", 0)
+
+    @property
+    def has_more(self) -> bool:
+        return self._data.get("has_more", False)
+
+    @property
+    def source(self) -> str:
+        return self._data.get("source", "")
+
+    @property
+    def truncated(self) -> bool:
+        return self._data.get("truncated", False)
+
+    def __repr__(self) -> str:
+        return (
+            f"LogsResponse(offset={self.offset}, size={self.size}, "
+            f"total_size={self.total_size}, has_more={self.has_more})"
+        )
+
+
 # ============================================================================
 # Run Class
 # ============================================================================
@@ -246,6 +304,66 @@ class Run:
             raise ValueError("Cannot get log URL without run id")
         return get_log_download_url(self.id)
 
+    def logs(
+        self,
+        *,
+        offset: int = 0,
+        limit: int = 1024 * 1024,
+        all: bool = False,
+    ) -> LogsResponse:
+        """Fetch logs for this run.
+
+        Works for both live (running) and archived (completed) runs.
+        Returns raw log data as a string (NDJSON format).
+
+        Args:
+            offset: Byte offset to start from. Negative values read from end
+                    (e.g., -1048576 = last 1MB).
+            limit: Maximum bytes to return (default 1MB).
+            all: If True, fetch all logs at once. Returns 400 if logs > 10MB.
+
+        Returns:
+            A LogsResponse object with data, offset, size, total_size, has_more,
+            source ("live" or "archived"), and truncated flag.
+
+        Raises:
+            ValueError: If the run has no ID.
+            LumeraAPIError: If logs are not available or request fails.
+
+        Example:
+            >>> run = automations.get_run("run_id")
+            >>> resp = run.logs()
+            >>> print(resp.data)  # Raw NDJSON log content
+            >>> while resp.has_more:
+            ...     resp = run.logs(offset=resp.offset + resp.size)
+            ...     print(resp.data)
+        """
+        if not self.id:
+            raise ValueError("Cannot fetch logs without run id")
+        return get_logs(self.id, offset=offset, limit=limit, all=all)
+
+    def stream_logs(self, *, timeout: float = 30) -> Iterator[str]:
+        """Stream logs from this run.
+
+        Works for both live (running) and archived (completed) runs.
+        For live runs, streams in real-time as logs are produced.
+        For archived runs, streams the entire log from S3.
+
+        Args:
+            timeout: HTTP connection timeout in seconds.
+
+        Yields:
+            Log lines as strings (raw NDJSON lines).
+
+        Example:
+            >>> run = automations.run("automation_id", inputs={})
+            >>> for line in run.stream_logs():
+            ...     print(line)
+        """
+        if not self.id:
+            raise ValueError("Cannot stream logs without run id")
+        return stream_logs(self.id, timeout=timeout)
+
     def to_dict(self) -> dict[str, Any]:
         """Return the underlying data dict."""
         return self._data.copy()
@@ -795,17 +913,19 @@ def delete(automation_id: str) -> None:
 
 
 def stream_logs(run_id: str, *, timeout: float = 30) -> Iterator[str]:
-    """Stream live logs from a running automation.
+    """Stream logs from an automation run.
 
+    Works for both live (running) and archived (completed) runs.
     Connects to the server-sent events endpoint and yields log lines
-    as they arrive. Stops when the run completes.
+    as they arrive. For live runs, streams in real-time. For archived
+    runs, streams the entire log from storage.
 
     Args:
         run_id: The run ID to stream logs from.
         timeout: HTTP connection timeout in seconds.
 
     Yields:
-        Log lines as strings.
+        Log lines as strings (raw NDJSON lines).
 
     Example:
         >>> for line in automations.stream_logs("run_id"):
@@ -825,7 +945,7 @@ def stream_logs(run_id: str, *, timeout: float = 30) -> Iterator[str]:
     if not token:
         raise ValueError("LUMERA_TOKEN environment variable is required")
 
-    url = f"{base_url}/automation-runs/{run_id}/logs/live"
+    url = f"{base_url}/automation-runs/{run_id}/logs?stream=true"
     headers = {
         "Authorization": f"token {token}",
         "Accept": "text/event-stream",
@@ -902,3 +1022,51 @@ def get_log_download_url(run_id: str) -> str:
     if isinstance(result, dict) and "url" in result:
         return result["url"]
     raise RuntimeError("Unexpected response: no download URL returned")
+
+
+def get_logs(
+    run_id: str,
+    *,
+    offset: int = 0,
+    limit: int = 1024 * 1024,
+    all: bool = False,
+) -> LogsResponse:
+    """Fetch logs for an automation run.
+
+    Works for both live (running) and archived (completed) runs.
+    Returns raw log data as a string (NDJSON format).
+
+    Args:
+        run_id: The run ID to get logs for.
+        offset: Byte offset to start from. Negative values read from end
+                (e.g., -1048576 = last 1MB).
+        limit: Maximum bytes to return (default 1MB).
+        all: If True, fetch all logs at once. Returns 400 if logs > 10MB.
+
+    Returns:
+        A LogsResponse object with data, offset, size, total_size, has_more,
+        source ("live" or "archived"), and truncated flag.
+
+    Raises:
+        ValueError: If run_id is empty.
+        LumeraAPIError: If logs are not available or request fails.
+
+    Example:
+        >>> resp = automations.get_logs("run_id")
+        >>> print(resp.data)  # Raw NDJSON log content
+        >>> while resp.has_more:
+        ...     resp = automations.get_logs("run_id", offset=resp.offset + resp.size)
+        ...     print(resp.data)
+    """
+    run_id = run_id.strip()
+    if not run_id:
+        raise ValueError("run_id is required")
+
+    params: dict[str, Any] = {"offset": offset, "limit": limit}
+    if all:
+        params["all"] = "true"
+
+    result = _api_request("GET", f"automation-runs/{run_id}/logs", params=params)
+    if isinstance(result, dict):
+        return LogsResponse(result)
+    raise RuntimeError("Unexpected response from logs endpoint")

lumera/email.py

@@ -0,0 +1,156 @@
+"""
+Email sending for Lumera automations.
+
+Send transactional emails through the Lumera platform using AWS SES infrastructure.
+Emails are logged to the lm_email_logs collection for auditing and debugging.
+
+Functions:
+    send()  - Send an email with HTML/text content
+
+Example:
+    >>> from lumera import email
+    >>>
+    >>> # Send a simple email
+    >>> result = email.send(
+    ...     to="user@example.com",
+    ...     subject="Welcome to Lumera!",
+    ...     body_html="<h1>Hello!</h1><p>Welcome aboard.</p>"
+    ... )
+    >>> print(result.message_id)
+    >>>
+    >>> # Send to multiple recipients with plain text fallback
+    >>> result = email.send(
+    ...     to=["alice@example.com", "bob@example.com"],
+    ...     subject="Team Update",
+    ...     body_html="<h1>Update</h1><p>See details below.</p>",
+    ...     body_text="Update\\n\\nSee details below.",
+    ...     tags={"type": "notification", "team": "engineering"}
+    ... )
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._utils import _api_request, LumeraAPIError
+
+__all__ = [
+    "send",
+    "SendResult",
+]
+
+
+class SendResult:
+    """Result of sending an email.
+
+    Attributes:
+        message_id: The unique identifier from AWS SES for the sent email.
+        log_id: The PocketBase record ID in lm_email_logs for auditing.
+    """
+
+    def __init__(self, data: dict[str, Any]):
+        self.message_id: str = data.get("message_id", "")
+        self.log_id: str = data.get("log_id", "")
+        self._raw = data
+
+    def __repr__(self) -> str:
+        return f"SendResult(message_id={self.message_id!r}, log_id={self.log_id!r})"
+
+
+def send(
+    to: list[str] | str,
+    subject: str,
+    *,
+    body_html: str | None = None,
+    body_text: str | None = None,
+    cc: list[str] | str | None = None,
+    bcc: list[str] | str | None = None,
+    from_address: str | None = None,
+    from_name: str | None = None,
+    reply_to: str | None = None,
+    tags: dict[str, str] | None = None,
+) -> SendResult:
+    """Send an email.
+
+    At least one of body_html or body_text must be provided. If only body_html
+    is provided, a plain text version will be auto-generated.
+
+    Args:
+        to: Recipient email address(es). Can be a single string or list.
+        subject: Email subject line.
+        body_html: HTML body content (optional if body_text provided).
+        body_text: Plain text body content (optional, auto-generated from HTML).
+        cc: CC recipient(s) (optional).
+        bcc: BCC recipient(s) (optional).
+        from_address: Sender email address (optional, uses platform default).
+        from_name: Sender display name (optional, uses platform default).
+        reply_to: Reply-to address (optional).
+        tags: Custom key-value pairs for tracking/filtering in logs (optional).
+
+    Returns:
+        SendResult with message_id and log_id.
+
+    Raises:
+        ValueError: If required fields are missing or invalid.
+        LumeraAPIError: If the API request fails.
+
+    Example:
+        >>> # Simple email
+        >>> result = email.send(
+        ...     to="user@example.com",
+        ...     subject="Password Reset",
+        ...     body_html="<p>Click <a href='...'>here</a> to reset.</p>"
+        ... )
+        >>>
+        >>> # Email with all options
+        >>> result = email.send(
+        ...     to=["alice@example.com", "bob@example.com"],
+        ...     subject="Monthly Report",
+        ...     body_html="<h1>Report</h1><p>See attached.</p>",
+        ...     body_text="Report\\n\\nSee attached.",
+        ...     cc="manager@example.com",
+        ...     reply_to="reports@example.com",
+        ...     tags={"report_type": "monthly", "department": "sales"}
+        ... )
+    """
+    # Normalize to lists
+    to_list = [to] if isinstance(to, str) else list(to) if to else []
+    cc_list = [cc] if isinstance(cc, str) else (list(cc) if cc else None)
+    bcc_list = [bcc] if isinstance(bcc, str) else (list(bcc) if bcc else None)
+
+    # Validate
+    if not to_list:
+        raise ValueError("at least one recipient is required")
+    if not subject or not subject.strip():
+        raise ValueError("subject is required")
+    if not body_html and not body_text:
+        raise ValueError("at least one of body_html or body_text is required")
+
+    # Build payload
+    payload: dict[str, Any] = {
+        "to": to_list,
+        "subject": subject.strip(),
+    }
+
+    if body_html:
+        payload["body_html"] = body_html
+    if body_text:
+        payload["body_text"] = body_text
+    if cc_list:
+        payload["cc"] = cc_list
+    if bcc_list:
+        payload["bcc"] = bcc_list
+    if from_address:
+        payload["from"] = from_address.strip()
+    if from_name:
+        payload["from_name"] = from_name.strip()
+    if reply_to:
+        payload["reply_to"] = reply_to.strip()
+    if tags:
+        payload["tags"] = tags
+
+    result = _api_request("POST", "email/send", json_body=payload)
+    if not isinstance(result, dict):
+        raise RuntimeError("unexpected response from email/send")
+
+    return SendResult(result)

{lumera-0.9.8.dist-info → lumera-0.10.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lumera
-Version: 0.9.8
+Version: 0.10.0
 Summary: SDK for building on Lumera platform
 Requires-Python: >=3.11
 Requires-Dist: requests

{lumera-0.9.8.dist-info → lumera-0.10.0.dist-info}/RECORD

@@ -1,6 +1,7 @@
-lumera/__init__.py,sha256=nIEzrBMFoW6-xJ5L5CQrq6feDJUH119Vttm-L8Si6aE,2667
+lumera/__init__.py,sha256=5FlY5dSJ1WNM4ko7wgmcajO8G2voBGn4S19E91_WdqE,2687
 lumera/_utils.py,sha256=b-l3Ebh4n2pC-9T5mR6h4hPf_Wl48VDlHES0pLo1zKE,25766
-lumera/automations.py,sha256=UKKtgmsYWIzJvMnIf0K5ywXCtgIu8kb9DmsAX_upubM,27397
+lumera/automations.py,sha256=KPP_rD7WKmBs865jiKoonZJjdTno-FSAU7hajPFyqs0,32851
+lumera/email.py,sha256=lk8KUsRw1ZvxgM0FPQXH-jVKUQA5f0zLv88jlc3IWlA,5056
 lumera/exceptions.py,sha256=bNsx4iYaroAAGsYxErfELC2B5ZJ3w5lVa1kKdIx5s9g,2173
 lumera/files.py,sha256=xMJmLTSaQQDttM3AMmpOWc6soh4lvCCKBreV0fXWHQw,3159
 lumera/google.py,sha256=zpWW1qSlzLZY5Ip7cGAzrv9sJrQf3JBKH2ODc1cCM_E,1130
@@ -12,7 +13,7 @@ lumera/storage.py,sha256=fWkscTvKDzQ-5tsfA1lREO2qgtjJ4Yvxj3hvYNLKiW0,10527
 lumera/webhooks.py,sha256=L_Q5YHBJKQNpv7G9Nq0QqlGMRch6x9ptlwu1xD2qwUc,8661
 lumera/integrations/__init__.py,sha256=LnJmAnFB_p3YMKyeGVdDP4LYlJ85XFNQFAxGo6zF7CI,937
 lumera/integrations/google.py,sha256=QkbBbbDh3I_OToPDFqcivU6sWy2UieHBxZ_TPv5rqK0,11862
-lumera-0.9.8.dist-info/METADATA,sha256=rAooBJr5-_9xpam1ctyqqB7C9jNpcXdf-KmzBuj8iGw,1611
-lumera-0.9.8.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-lumera-0.9.8.dist-info/top_level.txt,sha256=HgfK4XQkpMTnM2E5iWM4kB711FnYqUY9dglzib3pWlE,7
-lumera-0.9.8.dist-info/RECORD,,
+lumera-0.10.0.dist-info/METADATA,sha256=uWvSDuD868zVICFyVUppHMIrWe6A-JKeyxFRurjxieU,1612
+lumera-0.10.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+lumera-0.10.0.dist-info/top_level.txt,sha256=HgfK4XQkpMTnM2E5iWM4kB711FnYqUY9dglzib3pWlE,7
+lumera-0.10.0.dist-info/RECORD,,