lumera 0.4.6__py3-none-any.whl → 0.9.4__py3-none-any.whl

lumera/storage.py

@@ -0,0 +1,270 @@
+"""
+Storage operations for uploading and managing files.
+
+Files are automatically namespaced by the current automation run:
+    /agent_runs/{run_id}/{path}
+
+This prevents collisions between different runs while allowing logical
+organization within a run.
+
+Available functions:
+    upload()       - Upload bytes/string content to storage
+    upload_file()  - Upload a local file to storage
+    download_url() - Get download URL for an uploaded file
+    list_files()   - List files uploaded in current run
+
+Environment requirements:
+    LUMERA_RUN_ID  - Set automatically when running in automation context
+    LUMERA_TOKEN   - API authentication token
+
+Example:
+    >>> from lumera import storage
+    >>> result = storage.upload("exports/report.csv", csv_data, content_type="text/csv")
+    >>> print(result["url"])
+"""
+
+__all__ = ["upload", "upload_file", "download_url", "list_files", "UploadResult"]
+
+import mimetypes
+import os
+import pathlib
+from typing import Any, Required, TypedDict
+
+import requests
+
+from ._utils import API_BASE, get_lumera_token
+
+
+class UploadResult(TypedDict, total=False):
+    """Result of file upload.
+
+    Required fields (always present):
+        url: Public download URL
+        path: Relative path within run namespace
+        size: File size in bytes
+        content_type: MIME type
+
+    Optional fields:
+        object_key: Storage object key (platform implementation detail)
+    """
+
+    url: Required[str]  # Public download URL (always present)
+    path: Required[str]  # Relative path within run namespace (always present)
+    size: Required[int]  # File size in bytes (always present)
+    content_type: Required[str]  # MIME type (always present)
+    object_key: str  # Storage object key (optional, platform detail)
+
+
+def upload(
+    path: str,
+    content: bytes | str,
+    *,
+    content_type: str,
+    metadata: dict[str, Any] | None = None,  # noqa: ARG001 - Reserved for future use
+) -> UploadResult:
+    """Upload content to storage.
+
+    Files are automatically namespaced by the current automation run.
+    Storage location: /agent_runs/{run_id}/{path}
+
+    Args:
+        path: Relative path within this run's namespace (e.g., "exports/daily.csv")
+              Can include subfolders for organization
+        content: File content as bytes or string (strings will be encoded as UTF-8)
+        content_type: MIME type (e.g., "text/csv", "application/json")
+        metadata: Optional searchable metadata (reserved for future use)
+
+    Returns:
+        Upload result with URL and metadata
+
+    Raises:
+        ValueError: If path or content_type is empty
+        RuntimeError: If LUMERA_RUN_ID environment variable is not set
+        requests.HTTPError: If upload fails
+
+    Example:
+        >>> result = storage.upload(
+        ...     path="exports/report.csv",
+        ...     content=csv_data.encode("utf-8"),
+        ...     content_type="text/csv"
+        ... )
+        >>> print(result["url"])
+        https://storage.lumerahq.com/download/abc123
+    """
+    if not path or not path.strip():
+        raise ValueError("path is required and cannot be empty")
+    if not content_type or not content_type.strip():
+        raise ValueError("content_type is required and cannot be empty")
+
+    # Get current run ID from environment
+    run_id = os.getenv("LUMERA_RUN_ID", "").strip()
+    if not run_id:
+        raise RuntimeError(
+            "LUMERA_RUN_ID environment variable not set. "
+            "This function must be called from within an automation run."
+        )
+
+    # Convert string content to bytes
+    if isinstance(content, str):
+        content = content.encode("utf-8")
+
+    filename = os.path.basename(path)
+    size = len(content)
+
+    token = get_lumera_token()
+    headers = {"Authorization": f"token {token}", "Content-Type": "application/json"}
+
+    # Request presigned upload URL
+    resp = requests.post(
+        f"{API_BASE}/automation-runs/{run_id}/files/upload-url",
+        json={"filename": filename, "content_type": content_type, "size": size},
+        headers=headers,
+        timeout=30,
+    )
+    resp.raise_for_status()
+    data = resp.json()
+
+    upload_url = data["upload_url"]
+
+    # Upload content to presigned URL
+    put_resp = requests.put(
+        upload_url, data=content, headers={"Content-Type": content_type}, timeout=300
+    )
+    put_resp.raise_for_status()
+
+    # Construct result
+    result: UploadResult = {
+        "url": data.get("download_url", ""),
+        "object_key": data.get("object_name", ""),
+        "path": path,
+        "size": size,
+        "content_type": content_type,
+    }
+
+    return result
+
+
+def upload_file(
+    path: str,
+    file_path: str,
+    *,
+    content_type: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> UploadResult:
+    """Upload a file from disk.
+
+    Args:
+        path: Relative path in run namespace (e.g., "exports/report.pdf")
+        file_path: Local file path to upload
+        content_type: MIME type (auto-detected from extension if not provided)
+        metadata: Optional searchable metadata (reserved for future use)
+
+    Returns:
+        Upload result with URL and metadata
+
+    Raises:
+        FileNotFoundError: If file_path doesn't exist
+        ValueError: If path is empty
+
+    Example:
+        >>> result = storage.upload_file(
+        ...     path="exports/report.pdf",
+        ...     file_path="/tmp/generated_report.pdf"
+        ... )
+    """
+    file_path_obj = pathlib.Path(file_path).expanduser().resolve()
+    if not file_path_obj.is_file():
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    # Auto-detect content type if not provided
+    if not content_type:
+        content_type = mimetypes.guess_type(file_path)[0] or "application/octet-stream"
+
+    # Read file content
+    with open(file_path_obj, "rb") as f:
+        content = f.read()
+
+    return upload(path, content, content_type=content_type, metadata=metadata)
+
+
+def download_url(path: str) -> str:
+    """Get download URL for a file uploaded in this run.
+
+    Args:
+        path: Relative path within this run (same as used in upload)
+
+    Returns:
+        Download URL
+
+    Raises:
+        RuntimeError: If LUMERA_RUN_ID not set
+        requests.HTTPError: If file doesn't exist
+
+    Example:
+        >>> url = storage.download_url("exports/report.csv")
+    """
+    run_id = os.getenv("LUMERA_RUN_ID", "").strip()
+    if not run_id:
+        raise RuntimeError(
+            "LUMERA_RUN_ID environment variable not set. "
+            "This function must be called from within an automation run."
+        )
+
+    filename = os.path.basename(path)
+    token = get_lumera_token()
+    headers = {"Authorization": f"token {token}"}
+
+    resp = requests.get(
+        f"{API_BASE}/automation-runs/{run_id}/files/download-url",
+        params={"name": filename},
+        headers=headers,
+        timeout=30,
+    )
+    resp.raise_for_status()
+
+    data = resp.json()
+    return data.get("download_url", "")
+
+
+def list_files(prefix: str | None = None) -> list[dict[str, Any]]:
+    """List files uploaded in this run.
+
+    Args:
+        prefix: Optional path prefix filter (e.g., "exports/")
+
+    Returns:
+        List of file metadata dicts with keys:
+        - name: filename
+        - size: size in bytes
+        - content_type: MIME type
+        - created: creation timestamp
+
+    Raises:
+        RuntimeError: If LUMERA_RUN_ID not set
+
+    Example:
+        >>> files = storage.list_files(prefix="exports/")
+        >>> for file in files:
+        ...     print(file["name"], file["size"])
+    """
+    run_id = os.getenv("LUMERA_RUN_ID", "").strip()
+    if not run_id:
+        raise RuntimeError(
+            "LUMERA_RUN_ID environment variable not set. "
+            "This function must be called from within an automation run."
+        )
+
+    token = get_lumera_token()
+    headers = {"Authorization": f"token {token}"}
+
+    resp = requests.get(f"{API_BASE}/automation-runs/{run_id}/files", headers=headers, timeout=30)
+    resp.raise_for_status()
+
+    data = resp.json()
+    files = data.get("files", [])
+
+    # Filter by prefix if provided
+    if prefix:
+        files = [f for f in files if f.get("name", "").startswith(prefix)]
+
+    return files

lumera/webhooks.py

@@ -0,0 +1,304 @@
+"""
+Webhook endpoint management for Lumera.
+
+This module provides functions for managing webhook endpoints that receive
+external events from third-party services (Stripe, GitHub, etc.).
+
+Functions:
+    create()    - Create a new webhook endpoint
+    list()      - List all webhook endpoints
+    get()       - Get endpoint by external_id
+    update()    - Update an existing endpoint
+    delete()    - Delete an endpoint
+    url()       - Get the public webhook URL for an endpoint
+
+Example:
+    >>> from lumera import webhooks
+    >>>
+    >>> # Create a webhook endpoint
+    >>> endpoint = webhooks.create(
+    ...     name="Stripe Events",
+    ...     external_id="stripe-events",
+    ...     description="Receives Stripe payment webhooks"
+    ... )
+    >>>
+    >>> # Get the public URL to configure in Stripe
+    >>> webhook_url = webhooks.url("stripe-events")
+    >>> print(webhook_url)
+    https://app.lumerahq.com/webhooks/rec_abc123/stripe-events
+    >>>
+    >>> # List all endpoints
+    >>> for ep in webhooks.list():
+    ...     print(ep["name"], ep["external_id"])
+
+External ID Format:
+    The external_id is used as the URL slug and must follow these rules:
+    - 3-50 characters
+    - Lowercase alphanumeric and hyphens only
+    - Must start with a letter
+    - Cannot end with a hyphen
+    - No consecutive hyphens
+
+    Valid examples: "stripe-events", "github-webhooks", "acme-orders"
+    Invalid examples: "1-start", "end-", "double--hyphen"
+"""
+
+import os
+from typing import Any
+
+__all__ = [
+    "create",
+    "list",
+    "get",
+    "update",
+    "delete",
+    "url",
+]
+
+from ._utils import API_BASE, LumeraAPIError, _api_request
+
+# Collection name for webhook endpoints
+_COLLECTION = "lm_webhook_endpoints"
+
+
+def create(
+    name: str,
+    external_id: str,
+    *,
+    description: str | None = None,
+) -> dict[str, Any]:
+    """Create a new webhook endpoint.
+
+    Args:
+        name: Human-readable name for the endpoint (e.g., "Stripe Events")
+        external_id: URL-safe identifier used in the webhook URL.
+            Must be 3-50 chars, lowercase alphanumeric with hyphens,
+            start with a letter. Example: "stripe-events"
+        description: Optional description of what this webhook receives
+
+    Returns:
+        Created endpoint record with id, external_id, name, etc.
+
+    Raises:
+        ValueError: If name or external_id is empty
+        LumeraAPIError: If external_id format is invalid or already exists
+
+    Example:
+        >>> endpoint = webhooks.create(
+        ...     name="Stripe Events",
+        ...     external_id="stripe-events",
+        ...     description="Payment and subscription events from Stripe"
+        ... )
+        >>> print(endpoint["id"])
+    """
+    name = (name or "").strip()
+    external_id = (external_id or "").strip()
+
+    if not name:
+        raise ValueError("name is required")
+    if not external_id:
+        raise ValueError("external_id is required")
+
+    payload: dict[str, Any] = {
+        "name": name,
+        "external_id": external_id,
+    }
+    if description is not None:
+        payload["description"] = description.strip()
+
+    result = _api_request("POST", f"collections/{_COLLECTION}/records", json_body=payload)
+    if not isinstance(result, dict):
+        raise RuntimeError("unexpected response payload")
+    return result
+
+
+def list(
+    *,
+    per_page: int = 100,
+    page: int = 1,
+) -> list[dict[str, Any]]:
+    """List all webhook endpoints.
+
+    Args:
+        per_page: Number of results per page (default 100, max 500)
+        page: Page number, 1-indexed (default 1)
+
+    Returns:
+        List of endpoint records
+
+    Example:
+        >>> endpoints = webhooks.list()
+        >>> for ep in endpoints:
+        ...     print(f"{ep['name']}: {ep['external_id']}")
+    """
+    params: dict[str, Any] = {
+        "perPage": per_page,
+        "page": page,
+        "sort": "-created",
+    }
+
+    result = _api_request("GET", f"collections/{_COLLECTION}/records", params=params)
+    if not isinstance(result, dict):
+        return []
+    return result.get("items", [])
+
+
+def get(external_id: str) -> dict[str, Any]:
+    """Get a webhook endpoint by its external_id.
+
+    Args:
+        external_id: The external_id of the endpoint (e.g., "stripe-events")
+
+    Returns:
+        Endpoint record
+
+    Raises:
+        ValueError: If external_id is empty
+        LumeraAPIError: If endpoint not found (404)
+
+    Example:
+        >>> endpoint = webhooks.get("stripe-events")
+        >>> print(endpoint["name"])
+        Stripe Events
+    """
+    external_id = (external_id or "").strip()
+    if not external_id:
+        raise ValueError("external_id is required")
+
+    import json
+
+    params = {"filter": json.dumps({"external_id": external_id}), "perPage": 1}
+    result = _api_request("GET", f"collections/{_COLLECTION}/records", params=params)
+
+    if not isinstance(result, dict):
+        raise LumeraAPIError(
+            404, "endpoint not found", url=f"collections/{_COLLECTION}/records", payload=None
+        )
+
+    items = result.get("items", [])
+    if not items:
+        raise LumeraAPIError(
+            404,
+            f"webhook endpoint '{external_id}' not found",
+            url=f"collections/{_COLLECTION}/records",
+            payload=None,
+        )
+
+    return items[0]
+
+
+def update(
+    external_id: str,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> dict[str, Any]:
+    """Update a webhook endpoint.
+
+    Args:
+        external_id: The external_id of the endpoint to update
+        name: New name (optional)
+        description: New description (optional)
+
+    Returns:
+        Updated endpoint record
+
+    Raises:
+        ValueError: If external_id is empty or no fields to update
+        LumeraAPIError: If endpoint not found
+
+    Example:
+        >>> endpoint = webhooks.update(
+        ...     "stripe-events",
+        ...     description="Updated: Now includes refund events"
+        ... )
+    """
+    external_id = (external_id or "").strip()
+    if not external_id:
+        raise ValueError("external_id is required")
+
+    # First, find the endpoint to get its record ID
+    endpoint = get(external_id)
+    record_id = endpoint["id"]
+
+    payload: dict[str, Any] = {}
+    if name is not None:
+        payload["name"] = name.strip()
+    if description is not None:
+        payload["description"] = description.strip()
+
+    if not payload:
+        raise ValueError("at least one field (name or description) must be provided")
+
+    result = _api_request(
+        "PATCH", f"collections/{_COLLECTION}/records/{record_id}", json_body=payload
+    )
+    if not isinstance(result, dict):
+        raise RuntimeError("unexpected response payload")
+    return result
+
+
+def delete(external_id: str) -> None:
+    """Delete a webhook endpoint.
+
+    Args:
+        external_id: The external_id of the endpoint to delete
+
+    Raises:
+        ValueError: If external_id is empty
+        LumeraAPIError: If endpoint not found
+
+    Example:
+        >>> webhooks.delete("old-stripe-endpoint")
+    """
+    external_id = (external_id or "").strip()
+    if not external_id:
+        raise ValueError("external_id is required")
+
+    # First, find the endpoint to get its record ID
+    endpoint = get(external_id)
+    record_id = endpoint["id"]
+
+    _api_request("DELETE", f"collections/{_COLLECTION}/records/{record_id}")
+
+
+def url(external_id: str) -> str:
+    """Get the public webhook URL for an endpoint.
+
+    This returns the full URL that external services should send webhooks to.
+    The URL format is: https://{base}/webhooks/{company_id}/{external_id}
+
+    Args:
+        external_id: The external_id of the endpoint
+
+    Returns:
+        Full public webhook URL
+
+    Raises:
+        ValueError: If external_id is empty
+        RuntimeError: If COMPANY_ID environment variable is not set
+
+    Example:
+        >>> url = webhooks.url("stripe-events")
+        >>> print(url)
+        https://app.lumerahq.com/webhooks/rec_abc123/stripe-events
+
+        # Use this URL when configuring webhooks in Stripe, GitHub, etc.
+    """
+    external_id = (external_id or "").strip()
+    if not external_id:
+        raise ValueError("external_id is required")
+
+    company_id = os.getenv("COMPANY_ID", "").strip()
+    if not company_id:
+        raise RuntimeError(
+            "COMPANY_ID environment variable not set. "
+            "This is required to construct the webhook URL."
+        )
+
+    # API_BASE is like "https://app.lumerahq.com/api" - we need the base without /api
+    base_url = API_BASE.rstrip("/")
+    if base_url.endswith("/api"):
+        base_url = base_url[:-4]
+
+    return f"{base_url}/webhooks/{company_id}/{external_id}"

lumera-0.9.4.dist-info/METADATA

@@ -0,0 +1,37 @@
+Metadata-Version: 2.4
+Name: lumera
+Version: 0.9.4
+Summary: SDK for building on Lumera platform
+Requires-Python: >=3.11
+Requires-Dist: requests
+Requires-Dist: python-dotenv
+Requires-Dist: google-api-python-client==2.173.0
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Provides-Extra: full
+Requires-Dist: airtable-python-wrapper==0.15.3; extra == "full"
+Requires-Dist: boto3==1.39.3; extra == "full"
+Requires-Dist: google-api-python-client==2.173.0; extra == "full"
+Requires-Dist: gspread==6.2.1; extra == "full"
+Requires-Dist: hubspot-api-client==12.0.0; extra == "full"
+Requires-Dist: ipykernel; extra == "full"
+Requires-Dist: jupyter-client; extra == "full"
+Requires-Dist: matplotlib==3.10.3; extra == "full"
+Requires-Dist: notion-client==2.4.0; extra == "full"
+Requires-Dist: numpy==2.3.0; extra == "full"
+Requires-Dist: office365-rest-python-client; extra == "full"
+Requires-Dist: openai<3.0.0,>=2.15.0; extra == "full"
+Requires-Dist: openai-agents<1.0.0,>=0.6.5; extra == "full"
+Requires-Dist: openpyxl==3.1.5; extra == "full"
+Requires-Dist: pandas==2.3.0; extra == "full"
+Requires-Dist: pdfplumber; extra == "full"
+Requires-Dist: pydantic<3.0.0,>=2.12.3; extra == "full"
+Requires-Dist: PyGithub==2.6.1; extra == "full"
+Requires-Dist: python-dotenv==1.1.0; extra == "full"
+Requires-Dist: pyzmq; extra == "full"
+Requires-Dist: simple-salesforce==1.12.6; extra == "full"
+Requires-Dist: slack_sdk==3.35.0; extra == "full"
+Requires-Dist: tabulate; extra == "full"
+Requires-Dist: xlsxwriter==3.2.5; extra == "full"
+Requires-Dist: requests==2.32.4; extra == "full"

lumera-0.9.4.dist-info/RECORD

@@ -0,0 +1,17 @@
+lumera/__init__.py,sha256=D5DZoc9mqx--byMpf2wqXjq3Mussf4lZpY2bxZJa2q0,2535
+lumera/_utils.py,sha256=Gr3WRaU6MI-jpx3e5OMxAkVYYQmkUXg2J56Sy7AuEGE,24443
+lumera/automations.py,sha256=UKKtgmsYWIzJvMnIf0K5ywXCtgIu8kb9DmsAX_upubM,27397
+lumera/exceptions.py,sha256=bNsx4iYaroAAGsYxErfELC2B5ZJ3w5lVa1kKdIx5s9g,2173
+lumera/google.py,sha256=zpWW1qSlzLZY5Ip7cGAzrv9sJrQf3JBKH2ODc1cCM_E,1130
+lumera/llm.py,sha256=pUTZK7t3GTK0vfxMI1PJgJwNendyuiJc5MB1pUj2vxE,14412
+lumera/locks.py,sha256=8l_qxb8nrxge7YJ-ApUTJ5MeYpIdxDeEa94Eim9O-YM,6806
+lumera/pb.py,sha256=YdGM303LOLBtILIjpECQRtVdKASC0xLDWKWJheWpSEo,20133
+lumera/sdk.py,sha256=wKAj9cu6Rx8qXF7TU2H4EH4JjD1bXYQksHGG1a9YyrQ,33718
+lumera/storage.py,sha256=b0W6JNSGfmhJIcmK3vrATXAwxIr_bfrj-hPuQRVLTYU,8206
+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.4.dist-info/METADATA,sha256=vRfNdrbIgnrTHGHjrVPpImGOMZF3ftwDjeZeRq6R4u0,1611
+lumera-0.9.4.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+lumera-0.9.4.dist-info/top_level.txt,sha256=HgfK4XQkpMTnM2E5iWM4kB711FnYqUY9dglzib3pWlE,7
+lumera-0.9.4.dist-info/RECORD,,

{lumera-0.4.6.dist-info → lumera-0.9.4.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

lumera-0.4.6.dist-info/METADATA

@@ -1,11 +0,0 @@
-Metadata-Version: 2.4
-Name: lumera
-Version: 0.4.6
-Summary: Lumera Agent SDK for API interaction and dynamic UI generation.
-Requires-Python: >=3.8
-Requires-Dist: requests
-Requires-Dist: python-dotenv
-Requires-Dist: google-api-python-client==2.173.0
-Provides-Extra: dev
-Requires-Dist: ruff; extra == "dev"
-Requires-Dist: pytest; extra == "dev"

lumera-0.4.6.dist-info/RECORD

@@ -1,7 +0,0 @@
-lumera/__init__.py,sha256=HiyCIR0Qq1MVxUZVSgcz9xUk_6TZKNAy1cw0v7RlSWg,536
-lumera/google.py,sha256=1_xk1oyy6a6seieYbrHNWS3My06b-th_j2xWHQ9-NKs,10183
-lumera/sdk.py,sha256=LAi7ohXR0D6SlfVH5gMcywa-E4KtN05ZK92RwYcyQdU,14663
-lumera-0.4.6.dist-info/METADATA,sha256=UG1HtYKbhRQe49frc3F52gHOMpQRLevLcOMWdwgQH4o,342
-lumera-0.4.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-lumera-0.4.6.dist-info/top_level.txt,sha256=HgfK4XQkpMTnM2E5iWM4kB711FnYqUY9dglzib3pWlE,7
-lumera-0.4.6.dist-info/RECORD,,