lumera 0.9.7__tar.gz → 0.9.9__tar.gz

{lumera-0.9.7 → lumera-0.9.9}/PKG-INFO

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

{lumera-0.9.7 → lumera-0.9.9}/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-0.9.9/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.7 → lumera-0.9.9}/lumera/storage.py

@@ -23,7 +23,15 @@ Example:
     >>> print(result["url"])
 """
 
-__all__ = ["upload", "upload_file", "download_url", "list_files", "UploadResult"]
+__all__ = [
+    "upload",
+    "upload_file",
+    "download_url",
+    "list_files",
+    "UploadResult",
+    "get_download_url",
+    "download",
+]
 
 import mimetypes
 import os
@@ -268,3 +276,76 @@ def list_files(prefix: str | None = None) -> list[dict[str, Any]]:
         files = [f for f in files if f.get("name", "").startswith(prefix)]
 
     return files
+
+
+def get_download_url(object_key: str) -> str:
+    """Get a presigned download URL for a file by its object_key.
+
+    Use this to get download URLs for files stored in lumera_file fields on records.
+    The object_key is found in the file descriptor (e.g., record["file"]["object_key"]).
+
+    Args:
+        object_key: The storage object key from a lumera_file field descriptor
+
+    Returns:
+        Presigned download URL (valid for ~15 minutes)
+
+    Raises:
+        ValueError: If object_key is empty
+        requests.HTTPError: If the file doesn't exist or request fails
+
+    Example:
+        >>> record = pb.get("documents", "rec_123")
+        >>> url = storage.get_download_url(record["file"]["object_key"])
+        >>> # Use url to download the file
+    """
+    if not object_key or not object_key.strip():
+        raise ValueError("object_key is required and cannot be empty")
+
+    token = get_lumera_token()
+    headers = {"Authorization": f"token {token}", "Content-Type": "application/json"}
+
+    resp = requests.post(
+        f"{API_BASE}/pb/uploads/download",
+        json={"object_key": object_key.strip()},
+        headers=headers,
+        timeout=30,
+    )
+    resp.raise_for_status()
+
+    data = resp.json()
+    url = data.get("download_url")
+    if not url:
+        raise RuntimeError("uploads/download response missing download_url")
+
+    return url
+
+
+def download(object_key: str) -> bytes:
+    """Download file content by its object_key.
+
+    Use this to download files stored in lumera_file fields on records.
+    The object_key is found in the file descriptor (e.g., record["file"]["object_key"]).
+
+    Args:
+        object_key: The storage object key from a lumera_file field descriptor
+
+    Returns:
+        File content as bytes
+
+    Raises:
+        ValueError: If object_key is empty
+        requests.HTTPError: If the file doesn't exist or download fails
+
+    Example:
+        >>> record = pb.get("documents", "rec_123")
+        >>> content = storage.download(record["file"]["object_key"])
+        >>> with open("local_copy.pdf", "wb") as f:
+        ...     f.write(content)
+    """
+    url = get_download_url(object_key)
+
+    response = requests.get(url, timeout=300)
+    response.raise_for_status()
+
+    return response.content

{lumera-0.9.7 → lumera-0.9.9}/lumera.egg-info/PKG-INFO

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

{lumera-0.9.7 → lumera-0.9.9}/lumera.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ pyproject.toml
 lumera/__init__.py
 lumera/_utils.py
 lumera/automations.py
+lumera/email.py
 lumera/exceptions.py
 lumera/files.py
 lumera/google.py

{lumera-0.9.7 → lumera-0.9.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lumera"
-version = "0.9.7"
+version = "0.9.9"
 description = "SDK for building on Lumera platform"
 requires-python = ">=3.11"
 dependencies = [