lumera 0.7.3__tar.gz → 0.8.0__tar.gz

{lumera-0.7.3 → lumera-0.8.0}/PKG-INFO

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

{lumera-0.7.3 → lumera-0.8.0}/lumera/__init__.py

@@ -5,10 +5,10 @@ This SDK provides helpers for agents running within the Lumera Notebook environm
 to interact with the Lumera API and define dynamic user interfaces.
 """
 
-__version__ = "0.7.0"
+__version__ = "0.8.0"
 
 # Import new modules (as modules, not individual functions)
-from . import automations, exceptions, llm, locks, pb, storage
+from . import automations, exceptions, llm, locks, pb, storage, webhooks
 from ._utils import (
     LumeraAPIError,
     RecordNotUniqueError,
@@ -97,4 +97,5 @@ __all__ = [
     "llm",
     "locks",
     "exceptions",
+    "webhooks",
 ]

lumera-0.8.0/lumera/webhooks.py

@@ -0,0 +1,295 @@
+"""
+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/acme/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_api}/{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_API_NAME environment variable is not set
+
+    Example:
+        >>> url = webhooks.url("stripe-events")
+        >>> print(url)
+        https://app.lumerahq.com/webhooks/acme/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_api = os.getenv("COMPANY_API_NAME", "").strip()
+    if not company_api:
+        raise RuntimeError(
+            "COMPANY_API_NAME 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_api}/{external_id}"

{lumera-0.7.3 → lumera-0.8.0}/lumera.egg-info/PKG-INFO

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

{lumera-0.7.3 → lumera-0.8.0}/lumera.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ lumera/locks.py
 lumera/pb.py
 lumera/sdk.py
 lumera/storage.py
+lumera/webhooks.py
 lumera.egg-info/PKG-INFO
 lumera.egg-info/SOURCES.txt
 lumera.egg-info/dependency_links.txt

{lumera-0.7.3 → lumera-0.8.0}/pyproject.toml

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