lumera 0.7.3__py3-none-any.whl → 0.8.2__py3-none-any.whl

lumera/__init__.py

@@ -1,14 +1,14 @@
 """
 Lumera Agent SDK
 
-This SDK provides helpers for agents running within the Lumera Notebook environment
+This SDK provides helpers for automations running within the Lumera environment
 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, integrations, llm, locks, pb, storage, webhooks
 from ._utils import (
     LumeraAPIError,
     RecordNotUniqueError,
@@ -97,4 +97,6 @@ __all__ = [
     "llm",
     "locks",
     "exceptions",
+    "webhooks",
+    "integrations",
 ]

lumera/_utils.py

@@ -13,6 +13,7 @@ from functools import wraps as _wraps
 from typing import IO, Any, Callable, Iterable, Mapping, MutableMapping, Sequence, TypeVar
 
 import requests
+import requests.adapters
 from dotenv import load_dotenv
 
 TOKEN_ENV = "LUMERA_TOKEN"
@@ -35,6 +36,25 @@ MOUNT_ROOT = _mount_env
 
 _token_cache: dict[str, tuple[str, float]] = {}
 
+# Connection pooling for better performance
+_http_session: requests.Session | None = None
+
+
+def _get_session() -> requests.Session:
+    """Get or create a shared requests Session with connection pooling."""
+    global _http_session
+    if _http_session is None:
+        _http_session = requests.Session()
+        # Configure connection pooling
+        adapter = requests.adapters.HTTPAdapter(
+            pool_connections=10,
+            pool_maxsize=20,
+            max_retries=0,  # Don't retry automatically, let caller handle
+        )
+        _http_session.mount("https://", adapter)
+        _http_session.mount("http://", adapter)
+    return _http_session
+
 
 def get_lumera_token() -> str:
     token = os.getenv(TOKEN_ENV)
@@ -251,7 +271,8 @@ def _api_request(
         "Accept": "application/json",
     }
 
-    resp = requests.request(
+    session = _get_session()
+    resp = session.request(
         method,
         url,
         params=params,

lumera/automations.py

@@ -25,7 +25,7 @@ Example:
     >>> from lumera import automations
     >>>
     >>> # Run an automation
-    >>> run = automations.run("agent_id", inputs={"limit": 100})
+    >>> run = automations.run("automation_id", inputs={"limit": 100})
     >>> print(run.id, run.status)
     >>>
     >>> # Wait for completion
@@ -78,7 +78,7 @@ class Run:
 
     Attributes:
         id: The run ID.
-        automation_id: The automation/agent ID.
+        automation_id: The automation ID.
         status: Current status (queued, running, succeeded, failed, cancelled, timeout).
         inputs: The inputs passed to the run.
         result: The result returned by the automation (when succeeded).
@@ -329,7 +329,7 @@ def run(
     """Run an automation by ID.
 
     Args:
-        automation_id: The automation/agent ID to run.
+        automation_id: The automation ID to run.
         inputs: Input parameters (dict). Types are coerced based on input_schema.
         files: File inputs to upload (mapping of input key to file path(s)).
         external_id: Optional correlation ID for idempotency. Repeated calls
@@ -430,7 +430,7 @@ def list_runs(
         List of Run objects.
 
     Example:
-        >>> runs = automations.list_runs("agent_id", status="succeeded", limit=10)
+        >>> runs = automations.list_runs("automation_id", status="succeeded", limit=10)
         >>> for r in runs:
         ...     print(r.id, r.created, r.status)
     """
@@ -509,8 +509,8 @@ def get(automation_id: str) -> Automation:
         An Automation object.
 
     Example:
-        >>> agent = automations.get("abc123")
-        >>> print(agent.name, agent.input_schema)
+        >>> automation = automations.get("abc123")
+        >>> print(automation.name, automation.input_schema)
     """
     automation_id = automation_id.strip()
     if not automation_id:
@@ -535,8 +535,8 @@ def get_by_external_id(external_id: str) -> Automation:
         LumeraAPIError: If no automation with that external_id exists.
 
     Example:
-        >>> agent = automations.get_by_external_id("deposit_matching:step1")
-        >>> print(agent.id, agent.name)
+        >>> automation = automations.get_by_external_id("deposit_matching:step1")
+        >>> print(automation.id, automation.name)
     """
     external_id = external_id.strip()
     if not external_id:
@@ -582,7 +582,7 @@ def create(
         The created Automation object.
 
     Example:
-        >>> agent = automations.create(
+        >>> automation = automations.create(
         ...     name="My Automation",
         ...     code="def main(x): return {'result': x * 2}",
         ...     input_schema={

lumera/google.py

@@ -1,270 +1,47 @@
-import io
-import logging
-import os
-import re
-from typing import TYPE_CHECKING, Optional, Tuple
-
-# When type checking we want access to the concrete ``Resource`` class that
-# ``googleapiclient.discovery.build`` returns. Importing it unconditionally
-# would require ``googleapiclient`` to be available in every execution
-# environment – something we cannot guarantee.  By guarding the import with
-# ``TYPE_CHECKING`` we give static analysers (ruff, mypy, etc.) the
-# information they need without introducing a hard runtime dependency.
-# During static analysis we want to import ``Resource`` so that it is a known
-# name for type checkers, but we don't require this import at runtime. Guard
-# it with ``TYPE_CHECKING`` to avoid hard dependencies.
-if TYPE_CHECKING:  # pragma: no cover
-    from googleapiclient.discovery import Resource  # noqa: F401
-
-# Always ensure that the symbol ``Resource`` exists at runtime to placate static
-# analysers like ruff (F821) that inspect the AST without executing the code.
-try:  # pragma: no cover – optional runtime import
-    from googleapiclient.discovery import Resource  # type: ignore
-except ModuleNotFoundError:  # pragma: no cover – provide a stub fallback
-
-    class Resource:  # noqa: D401
-        """Stub replacement for ``googleapiclient.discovery.Resource``."""
-
-        pass
-
-
-from google.oauth2.credentials import Credentials
-from googleapiclient.discovery import build
-from googleapiclient.http import MediaFileUpload, MediaIoBaseDownload
-
-from lumera import get_access_token
-
-# Module logger
-logger = logging.getLogger(__name__)
-
-# =====================================================================================
-# Configuration
-# =====================================================================================
-
-MIME_GOOGLE_SHEET = "application/vnd.google-apps.spreadsheet"
-MIME_EXCEL = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
-
-# =====================================================================================
-# Authentication & Service Initialization
-# =====================================================================================
-
-
-def get_google_credentials() -> Credentials:
-    """
-    Retrieves a Google OAuth token from Lumera and
-    converts it into a Credentials object usable by googleapiclient.
-    """
-    logger.debug("Fetching Google access token from Lumera…")
-    access_token = get_access_token("google")
-    logger.debug("Access token received.")
-    creds = Credentials(token=access_token)
-    logger.debug("Credentials object created.")
-    return creds
-
-
-def get_sheets_service(credentials: Optional[Credentials] = None) -> 'Resource':
-    """
-    Initializes and returns the Google Sheets API service.
-
-    If no credentials are provided, this function will automatically fetch a
-    Google access token from Lumera and construct the appropriate
-    ``google.oauth2.credentials.Credentials`` instance.
-    """
-    if credentials is None:
-        logger.info("No credentials provided; fetching Google token…")
-        credentials = get_google_credentials()
-    logger.info("Google Sheets API service being initialized…")
-    return build('sheets', 'v4', credentials=credentials)
-
-
-def get_drive_service(credentials: Optional[Credentials] = None) -> 'Resource':
-    """
-    Initializes and returns the Google Drive API service.
-
-    If no credentials are provided, this function will automatically fetch a
-    Google access token from Lumera and construct the appropriate
-    ``google.oauth2.credentials.Credentials`` instance.
-    """
-    if credentials is None:
-        logger.info("No credentials provided; fetching Google token…")
-        credentials = get_google_credentials()
-    logger.info("Google Drive API service being initialized…")
-    return build('drive', 'v3', credentials=credentials)
-
-
-# =====================================================================================
-# Google Sheets & Drive Utility Functions
-# =====================================================================================
-
-
-def get_spreadsheet_and_sheet_id(
-    service: 'Resource', spreadsheet_url: str, tab_name: str
-) -> Tuple[Optional[str], Optional[int]]:
-    """
-    Given a Google Sheets URL and a tab (sheet) name, returns a tuple:
-    (spreadsheet_id, sheet_id)
-    """
-    spreadsheet_id = _extract_spreadsheet_id(spreadsheet_url)
-    if not spreadsheet_id:
-        return None, None
-
-    sheet_id = _get_sheet_id_from_name(service, spreadsheet_id, tab_name)
-    return spreadsheet_id, sheet_id
-
-
-def _extract_spreadsheet_id(spreadsheet_url: str) -> Optional[str]:
-    """Extracts the spreadsheet ID from a Google Sheets URL."""
-    logger.debug(f"Extracting spreadsheet ID from URL: {spreadsheet_url}")
-    pattern = r"/d/([a-zA-Z0-9-_]+)"
-    match = re.search(pattern, spreadsheet_url)
-    if match:
-        spreadsheet_id = match.group(1)
-        logger.debug(f"Spreadsheet ID extracted: {spreadsheet_id}")
-        return spreadsheet_id
-    logger.warning("Could not extract Spreadsheet ID.")
-    return None
-
-
-def _get_sheet_id_from_name(
-    service: 'Resource', spreadsheet_id: str, tab_name: str
-) -> Optional[int]:
-    """Uses the Google Sheets API to fetch the sheet ID corresponding to 'tab_name'."""
-    logger.debug(f"Requesting sheet metadata for spreadsheet ID: {spreadsheet_id}")
-    response = (
-        service.spreadsheets()
-        .get(spreadsheetId=spreadsheet_id, fields="sheets.properties")
-        .execute()
-    )
-    logger.debug("Metadata received. Searching for tab…")
-
-    for sheet in response.get("sheets", []):
-        properties = sheet.get("properties", {})
-        if properties.get("title") == tab_name:
-            sheet_id = properties.get("sheetId")
-            logger.debug(f"Match found for tab '{tab_name}'. Sheet ID is {sheet_id}")
-            return sheet_id
-    logger.warning(f"No sheet found with tab name '{tab_name}'.")
-    return None
-
-
-def sheet_name_from_gid(service: 'Resource', spreadsheet_id: str, gid: int) -> Optional[str]:
-    """Resolve a sheet's human-readable name (title) from its gid."""
-    logger.debug(f"Resolving sheet name from gid={gid} …")
-    meta = (
-        service.spreadsheets()
-        .get(
-            spreadsheetId=spreadsheet_id,
-            includeGridData=False,
-            fields="sheets(properties(sheetId,title))",
-        )
-        .execute()
-    )
-
-    for sheet in meta.get("sheets", []):
-        props = sheet.get("properties", {})
-        if props.get("sheetId") == gid:
-            title = props["title"]
-            logger.debug(f"Sheet gid={gid} corresponds to sheet name='{title}'.")
-            return title
-    logger.warning(f"No sheet found with gid={gid}")
-    return None
-
-
-def read_cell(service: 'Resource', spreadsheet_id: str, range_a1: str) -> Optional[str]:
-    """Fetch a single cell value (as string); returns None if empty."""
-    logger.debug(f"Reading cell '{range_a1}' …")
-    resp = (
-        service.spreadsheets()
-        .values()
-        .get(spreadsheetId=spreadsheet_id, range=range_a1, majorDimension="ROWS")
-        .execute()
-    )
-
-    values = resp.get("values", [])
-    return values[0][0] if values and values[0] else None
-
-
-# NOTE: The function performs I/O side-effects and does not return a value.
-def download_file_direct(drive_service: 'Resource', file_id: str, dest_path: str) -> None:
-    """
-    Downloads a file directly from Google Drive using files().get_media
-    without any format conversion.
-    """
-    logger.info(f"Initiating direct download for file ID: {file_id}")
-
-    request = drive_service.files().get_media(fileId=file_id)
-    fh = io.BytesIO()
-    downloader = MediaIoBaseDownload(fh, request)
-
-    done = False
-    while not done:
-        status, done = downloader.next_chunk()
-        if status:
-            logger.debug(f"Download progress: {int(status.progress() * 100)}%")
-
-    with open(dest_path, "wb") as f:
-        f.write(fh.getvalue())
-    logger.info(f"File saved to: {dest_path}")
-
-
-def upload_excel_as_google_sheet(
-    drive_service: 'Resource', local_path: str, desired_name: str
-) -> Tuple[Optional[str], Optional[str]]:
-    """
-    Uploads a local XLSX file to Google Drive, converting it to Google Sheets format.
-    Returns the file ID and web link.
-    """
-    logger.info(f"Preparing to upload '{local_path}' as Google Sheet named '{desired_name}'")
-
-    if not os.path.isfile(local_path):
-        logger.error(f"Local file not found at '{local_path}'. Aborting.")
-        return None, None
-
-    media = MediaFileUpload(local_path, mimetype=MIME_EXCEL, resumable=True)
-    file_metadata = {"name": desired_name, "mimeType": MIME_GOOGLE_SHEET}
-
-    logger.info("Initiating Google Drive upload & conversion…")
-    request = drive_service.files().create(
-        body=file_metadata, media_body=media, fields="id, webViewLink"
-    )
-
-    response = None
-    while response is None:
-        status, response = request.next_chunk()
-        if status:
-            logger.debug(f"Upload progress: {int(status.progress() * 100)}%")
-
-    file_id = response.get("id")
-    web_view_link = response.get("webViewLink")
-    logger.info(f"Upload completed. File ID: {file_id}")
-    return file_id, web_view_link
-
-
-# Remove rows from a sheet.  All parameters are 1-based (both *start_row* and
-# *end_row* are inclusive) mirroring the UI behaviour in Google Sheets.
-def delete_rows_api_call(
-    service: 'Resource',
-    spreadsheet_id: str,
-    sheet_gid: int,
-    start_row: int,
-    end_row: int,
-) -> None:
-    """Executes the API call to delete rows."""
-    logger.info(f"Deleting rows {start_row}-{end_row} (1-based inclusive)…")
-
-    body = {
-        "requests": [
-            {
-                "deleteDimension": {
-                    "range": {
-                        "sheetId": sheet_gid,
-                        "dimension": "ROWS",
-                        "startIndex": start_row - 1,  # 0-based
-                        "endIndex": end_row,  # end-exclusive
-                    }
-                }
-            }
-        ]
-    }
-    service.spreadsheets().batchUpdate(spreadsheetId=spreadsheet_id, body=body).execute()
-    logger.info("Rows deleted.")
+"""
+Backward compatibility shim for lumera.google.
+
+This module has moved to lumera.integrations.google.
+All imports are re-exported here for backward compatibility.
+
+New code should use:
+    from lumera.integrations import google
+    # or
+    from lumera.integrations.google import get_sheets_service, get_drive_service
+"""
+
+# Re-export everything from the new location
+from lumera.integrations.google import (
+    MIME_EXCEL,
+    MIME_GOOGLE_SHEET,
+    delete_rows_api_call,
+    download_file_direct,
+    get_credentials,
+    get_drive_service,
+    get_google_credentials,
+    get_sheets_service,
+    get_spreadsheet_and_sheet_id,
+    read_cell,
+    sheet_name_from_gid,
+    upload_excel_as_google_sheet,
+)
+
+__all__ = [
+    # Authentication
+    "get_credentials",
+    "get_google_credentials",
+    # Services
+    "get_sheets_service",
+    "get_drive_service",
+    # Sheets helpers
+    "get_spreadsheet_and_sheet_id",
+    "sheet_name_from_gid",
+    "read_cell",
+    "delete_rows_api_call",
+    # Drive helpers
+    "download_file_direct",
+    "upload_excel_as_google_sheet",
+    # Constants
+    "MIME_GOOGLE_SHEET",
+    "MIME_EXCEL",
+]

lumera/sdk.py

@@ -399,10 +399,10 @@ def run_automation(
     external_id: str | None = None,
     metadata: Mapping[str, Any] | None = None,
 ) -> dict[str, Any]:
-    """Create an agent run and optionally upload files for file inputs.
+    """Create an automation run and optionally upload files for file inputs.
 
     Args:
-        automation_id: The automation/agent to run. Required.
+        automation_id: The automation to run. Required.
         inputs: Inputs payload (dict or JSON string). File refs are resolved automatically.
         files: Mapping of input key -> path(s) to upload before run creation.
         status: Optional initial status (defaults to ``queued``).
@@ -463,12 +463,13 @@ def get_automation_run(
     run_id: str | None = None,
     external_id: str | None = None,
 ) -> dict[str, Any]:
-    """Fetch an agent run by id or by automation_id + external_id idempotency key.
+    """Fetch an automation run by id or by automation_id + external_id idempotency key.
 
     Args:
-        automation_id: Agent id for external_id lookup. Required when ``run_id`` is not provided.
-        run_id: Optional run id. When provided, this takes precedence over external_id lookup.
-        external_id: Optional idempotency key to look up the latest run for the agent.
+        automation_id: Automation id for external_id lookup.
+            Required when ``run_id`` is not provided.
+        run_id: Optional run id. When provided, takes precedence over external_id.
+        external_id: Optional idempotency key to look up the latest run for the automation.
 
     Raises:
         ValueError: If required identifiers are missing.
@@ -510,7 +511,7 @@ def update_automation_run(
     error: str | None = None,
     metadata: Mapping[str, Any] | None = None,
 ) -> dict[str, Any]:
-    """Update an agent run with result, status, or other fields.
+    """Update an automation run with result, status, or other fields.
 
     Args:
         run_id: The run id to update. Required.
@@ -520,7 +521,7 @@ def update_automation_run(
         metadata: Optional metadata update.
 
     Returns:
-        The updated agent run record.
+        The updated automation run record.
     """
     run_id = run_id.strip() if isinstance(run_id, str) else ""
     if not run_id:

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.7.3.dist-info → lumera-0.8.2.dist-info}/METADATA

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

lumera-0.8.2.dist-info/RECORD

@@ -0,0 +1,15 @@
+lumera/__init__.py,sha256=rOTVv9u-Wtl0ky4oPN5yF9AMRO3UOSZo-BEMwqmMoV4,2352
+lumera/_utils.py,sha256=Gr3WRaU6MI-jpx3e5OMxAkVYYQmkUXg2J56Sy7AuEGE,24443
+lumera/automations.py,sha256=8BTvq91SXBtO5PO5SKEBdKcz7JRsKl2o4bzp3VCS8_U,24813
+lumera/exceptions.py,sha256=bNsx4iYaroAAGsYxErfELC2B5ZJ3w5lVa1kKdIx5s9g,2173
+lumera/google.py,sha256=MwgPd3hNNuOj6CKmxJMYTQ7F81a_R4x0Wx19GSiOGoU,1136
+lumera/llm.py,sha256=pUTZK7t3GTK0vfxMI1PJgJwNendyuiJc5MB1pUj2vxE,14412
+lumera/locks.py,sha256=8l_qxb8nrxge7YJ-ApUTJ5MeYpIdxDeEa94Eim9O-YM,6806
+lumera/pb.py,sha256=EZABRPVbrSJ8_9Yh-BLt9cp4omkwo5r10Qs8v7wc1qc,18236
+lumera/sdk.py,sha256=EZVH1FnT7smkvFgT6QjVf4gDnVuktF1w7RZFaeTPgDE,30470
+lumera/storage.py,sha256=b0W6JNSGfmhJIcmK3vrATXAwxIr_bfrj-hPuQRVLTYU,8206
+lumera/webhooks.py,sha256=L_Q5YHBJKQNpv7G9Nq0QqlGMRch6x9ptlwu1xD2qwUc,8661
+lumera-0.8.2.dist-info/METADATA,sha256=UJHFpJG3igC8bKiDnEFYom92fzXb0d_zZ7St127aGpc,1611
+lumera-0.8.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+lumera-0.8.2.dist-info/top_level.txt,sha256=HgfK4XQkpMTnM2E5iWM4kB711FnYqUY9dglzib3pWlE,7
+lumera-0.8.2.dist-info/RECORD,,

lumera-0.7.3.dist-info/RECORD

@@ -1,14 +0,0 @@
-lumera/__init__.py,sha256=NuZgCTtxQNdj1HKltc76XIcx8kUuE4PKY7mUy5XCXiU,2296
-lumera/_utils.py,sha256=Ur4ZEf-khH3zFzX-aY4Y5uDqgYSWz9kJEkoR9WKy5yc,23727
-lumera/automations.py,sha256=ZHN4m1pIO7py_F3DkUTTDTsr3dbJy7Mly_-gXt3h31o,24780
-lumera/exceptions.py,sha256=bNsx4iYaroAAGsYxErfELC2B5ZJ3w5lVa1kKdIx5s9g,2173
-lumera/google.py,sha256=3IVNL1HaOtsTmunl0alnGFuUAkzQQRyCEA3CKjlPqO0,10183
-lumera/llm.py,sha256=pUTZK7t3GTK0vfxMI1PJgJwNendyuiJc5MB1pUj2vxE,14412
-lumera/locks.py,sha256=8l_qxb8nrxge7YJ-ApUTJ5MeYpIdxDeEa94Eim9O-YM,6806
-lumera/pb.py,sha256=EZABRPVbrSJ8_9Yh-BLt9cp4omkwo5r10Qs8v7wc1qc,18236
-lumera/sdk.py,sha256=GVu1Pe_r7qNPDJ5g7qeACAfW5w5TDOyK8LN3VvDwk0s,30446
-lumera/storage.py,sha256=b0W6JNSGfmhJIcmK3vrATXAwxIr_bfrj-hPuQRVLTYU,8206
-lumera-0.7.3.dist-info/METADATA,sha256=G0fM5Y0DkPMr6QsNOuUaUZPnpKiqpo25_hEMlB7T1yg,1611
-lumera-0.7.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-lumera-0.7.3.dist-info/top_level.txt,sha256=HgfK4XQkpMTnM2E5iWM4kB711FnYqUY9dglzib3pWlE,7
-lumera-0.7.3.dist-info/RECORD,,