lumera 0.7.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

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,
@@ -34,7 +34,7 @@ from .sdk import (
     create_record,
     delete_collection,
     delete_record,
-    get_agent_run,
+    get_automation_run,
     get_collection,
     get_record,
     get_record_by_external_id,
@@ -42,8 +42,9 @@ from .sdk import (
     list_records,
     query_sql,
     replay_hook,
-    run_agent,
+    run_automation,
     save_to_lumera,
+    update_automation_run,
     update_collection,
     update_record,
     upload_lumera_file,
@@ -73,8 +74,9 @@ __all__ = [
     # Other operations
     "replay_hook",
     "query_sql",
-    "run_agent",
-    "get_agent_run",
+    "run_automation",
+    "get_automation_run",
+    "update_automation_run",
     "upload_lumera_file",
     "save_to_lumera",
     # Type definitions
@@ -95,4 +97,5 @@ __all__ = [
     "llm",
     "locks",
     "exceptions",
+    "webhooks",
 ]

lumera/_utils.py

@@ -117,10 +117,10 @@ def _utcnow_iso() -> str:
     )
 
 
-def _default_provenance(agent_id: str, run_id: str | None) -> dict[str, Any]:
+def _default_provenance(automation_id: str, run_id: str | None) -> dict[str, Any]:
     recorded_at = _utcnow_iso()
-    env_agent_id = os.getenv("LUMERA_AGENT_ID", "").strip()
-    agent_id = (agent_id or "").strip() or env_agent_id
+    env_automation_id = os.getenv("LUMERA_AUTOMATION_ID", "").strip()
+    automation_id = (automation_id or "").strip() or env_automation_id
 
     run_id = (run_id or "").strip() or os.getenv("LUMERA_RUN_ID", "").strip()
 
@@ -132,8 +132,8 @@ def _default_provenance(agent_id: str, run_id: str | None) -> dict[str, Any]:
         "recorded_at": recorded_at,
     }
 
-    if agent_id:
-        payload["agent"] = {"id": agent_id}
+    if automation_id:
+        payload["agent"] = {"id": automation_id}  # Backend still expects "agent" key
 
     if run_id:
         payload["agent_run"] = {"id": run_id}
@@ -284,7 +284,7 @@ def _ensure_mapping(payload: Mapping[str, Any] | None, *, name: str) -> dict[str
     return dict(payload)
 
 
-def _prepare_agent_inputs(
+def _prepare_automation_inputs(
     inputs: Mapping[str, Any] | str | None,
 ) -> dict[str, Any] | None:
     if inputs is None:
@@ -345,7 +345,7 @@ def _upload_file_to_presigned(upload_url: str, path: pathlib.Path, content_type:
         resp.raise_for_status()
 
 
-def _upload_agent_files(
+def _upload_automation_files(
     run_id: str | None,
     files: Mapping[str, str | os.PathLike[str] | Sequence[str | os.PathLike[str]]],
     *,
@@ -370,7 +370,7 @@ def _upload_agent_files(
             size = file_path.stat().st_size
 
             body: dict[str, Any] = {
-                "scope": "agent_run",
+                "scope": "automation_run",
                 "filename": filename,
                 "content_type": content_type,
                 "size": size,
@@ -631,7 +631,7 @@ def _upload_session_file(file_path: str, session_id: str) -> dict:
     return {"name": filename, "notebook_path": notebook_path}
 
 
-def _upload_agent_run_file(file_path: str, run_id: str) -> dict:
+def _upload_automation_run_file(file_path: str, run_id: str) -> dict:
     token = get_lumera_token()
     path = pathlib.Path(file_path).expanduser().resolve()
     if not path.is_file():
@@ -644,7 +644,7 @@ def _upload_agent_run_file(file_path: str, run_id: str) -> dict:
     headers = {"Authorization": f"token {token}", "Content-Type": "application/json"}
 
     resp = requests.post(
-        f"{API_BASE}/agent-runs/{run_id}/files/upload-url",
+        f"{API_BASE}/automation-runs/{run_id}/files/upload-url",
         json={"filename": filename, "content_type": mimetype, "size": size},
         headers=headers,
         timeout=30,
@@ -742,10 +742,10 @@ __all__ = [
     "_is_sequence",
     "_normalize_mount_path",
     "_pretty_size",
-    "_prepare_agent_inputs",
+    "_prepare_automation_inputs",
     "_record_mutation",
-    "_upload_agent_files",
-    "_upload_agent_run_file",
+    "_upload_automation_files",
+    "_upload_automation_run_file",
     "_upload_file_to_presigned",
     "_upload_document",
     "_upload_session_file",

lumera/automations.py

@@ -65,8 +65,8 @@ __all__ = [
 ]
 
 from ._utils import LumeraAPIError, _api_request
-from .sdk import get_agent_run as _get_agent_run
-from .sdk import run_agent as _run_agent
+from .sdk import get_automation_run as _get_automation_run
+from .sdk import run_automation as _run_automation
 
 # ============================================================================
 # Run Class
@@ -101,7 +101,7 @@ class Run:
 
     @property
     def automation_id(self) -> str:
-        return self._data.get("agent_id", "")
+        return self._data.get("automation_id", "")
 
     @property
     def status(self) -> str:
@@ -166,7 +166,7 @@ class Run:
         """
         if not self.id:
             raise ValueError("Cannot refresh run without id")
-        updated = _get_agent_run(run_id=self.id)
+        updated = _get_automation_run(run_id=self.id)
         self._data = updated
         return self
 
@@ -213,7 +213,7 @@ class Run:
         """
         if not self.id:
             raise ValueError("Cannot cancel run without id")
-        result = _api_request("POST", f"agent-runs/{self.id}/cancel")
+        result = _api_request("POST", f"automation-runs/{self.id}/cancel")
         if isinstance(result, dict):
             self._data = result
         return self
@@ -271,13 +271,8 @@ class Automation:
 
     @property
     def input_schema(self) -> dict[str, Any] | None:
-        raw = self._data.get("input_schema")
-        if isinstance(raw, str):
-            try:
-                return json.loads(raw)
-            except json.JSONDecodeError:
-                return None
-        return raw
+        """Return the input schema as a dict. API always returns JSON object."""
+        return self._data.get("input_schema")
 
     @property
     def status(self) -> str | None:
@@ -349,7 +344,7 @@ def run(
         >>> print(run.id, run.status)
         >>> result = run.wait(timeout=300)
     """
-    result = _run_agent(
+    result = _run_automation(
         automation_id,
         inputs=inputs,
         files=files,
@@ -408,7 +403,7 @@ def get_run(run_id: str) -> Run:
         >>> run = automations.get_run("run_abc123")
         >>> print(run.status, run.result)
     """
-    result = _get_agent_run(run_id=run_id)
+    result = _get_automation_run(run_id=run_id)
     return Run(result)
 
 
@@ -446,15 +441,15 @@ def list_runs(
         "dir": dir,
     }
     if automation_id:
-        params["agent_id"] = automation_id
+        params["automation_id"] = automation_id
     if status:
         params["status"] = status
 
-    result = _api_request("GET", "agent-runs", params=params)
+    result = _api_request("GET", "automation-runs", params=params)
     items = []
     if isinstance(result, dict):
         # API returns runs in different keys depending on context
-        items = result.get("agent_runs") or result.get("data") or []
+        items = result.get("automation_runs") or result.get("data") or []
     return [Run(item) for item in items if isinstance(item, dict)]
 
 
@@ -497,10 +492,10 @@ def list(
     if q:
         params["q"] = q
 
-    result = _api_request("GET", "agents", params=params)
+    result = _api_request("GET", "automations", params=params)
     items = []
     if isinstance(result, dict):
-        items = result.get("agents") or []
+        items = result.get("automations") or []
     return [Automation(item) for item in items if isinstance(item, dict)]
 
 
@@ -521,7 +516,7 @@ def get(automation_id: str) -> Automation:
     if not automation_id:
         raise ValueError("automation_id is required")
 
-    result = _api_request("GET", f"agents/{automation_id}")
+    result = _api_request("GET", f"automations/{automation_id}")
     if not isinstance(result, dict):
         raise RuntimeError("Unexpected response")
     return Automation(result)
@@ -547,14 +542,17 @@ def get_by_external_id(external_id: str) -> Automation:
     if not external_id:
         raise ValueError("external_id is required")
 
-    result = _api_request("GET", "agents", params={"external_id": external_id, "limit": 1})
+    result = _api_request("GET", "automations", params={"external_id": external_id, "limit": 1})
     if isinstance(result, dict):
-        items = result.get("agents") or []
+        items = result.get("automations") or []
         if items and isinstance(items[0], dict):
             return Automation(items[0])
 
     raise LumeraAPIError(
-        404, f"Automation with external_id '{external_id}' not found", url="agents", payload=None
+        404,
+        f"Automation with external_id '{external_id}' not found",
+        url="automations",
+        payload=None,
     )
 
 
@@ -565,7 +563,6 @@ def create(
     input_schema: Mapping[str, Any] | None = None,
     description: str | None = None,
     external_id: str | None = None,
-    expose_to_ai: bool = False,
     schedule: str | None = None,
     schedule_tz: str | None = None,
 ) -> Automation:
@@ -578,7 +575,6 @@ def create(
             ``function.name`` and ``function.parameters``.
         description: Human-readable description.
         external_id: Stable identifier for programmatic access.
-        expose_to_ai: If True, makes this callable as an AI tool.
         schedule: Cron expression for scheduled runs.
         schedule_tz: Timezone for schedule (e.g., "America/New_York").
 
@@ -612,14 +608,12 @@ def create(
         payload["description"] = description
     if external_id is not None:
         payload["external_id"] = external_id
-    if expose_to_ai:
-        payload["expose_to_ai"] = True
     if schedule is not None:
         payload["schedule"] = schedule
     if schedule_tz is not None:
         payload["schedule_tz"] = schedule_tz
 
-    result = _api_request("POST", "agents", json_body=payload)
+    result = _api_request("POST", "automations", json_body=payload)
     if not isinstance(result, dict):
         raise RuntimeError("Unexpected response")
     return Automation(result)
@@ -633,7 +627,6 @@ def update(
     input_schema: Mapping[str, Any] | None = None,
     description: str | None = None,
     external_id: str | None = None,
-    expose_to_ai: bool | None = None,
     schedule: str | None = None,
     schedule_tz: str | None = None,
 ) -> Automation:
@@ -646,7 +639,6 @@ def update(
         input_schema: New input schema.
         description: New description.
         external_id: New external_id.
-        expose_to_ai: Whether to expose as AI tool.
         schedule: New cron schedule (empty string to clear).
         schedule_tz: New schedule timezone.
 
@@ -671,8 +663,6 @@ def update(
         payload["description"] = description
     if external_id is not None:
         payload["external_id"] = external_id
-    if expose_to_ai is not None:
-        payload["expose_to_ai"] = expose_to_ai
     if schedule is not None:
         payload["schedule"] = schedule
     if schedule_tz is not None:
@@ -681,7 +671,7 @@ def update(
     if not payload:
         raise ValueError("At least one field to update is required")
 
-    result = _api_request("PATCH", f"agents/{automation_id}", json_body=payload)
+    result = _api_request("PATCH", f"automations/{automation_id}", json_body=payload)
     if not isinstance(result, dict):
         raise RuntimeError("Unexpected response")
     return Automation(result)
@@ -694,7 +684,6 @@ def upsert(
     code: str,
     input_schema: Mapping[str, Any] | None = None,
     description: str | None = None,
-    expose_to_ai: bool = False,
     schedule: str | None = None,
     schedule_tz: str | None = None,
 ) -> Automation:
@@ -709,7 +698,6 @@ def upsert(
         code: Python code.
         input_schema: JSON schema defining inputs.
         description: Human-readable description.
-        expose_to_ai: If True, makes this callable as an AI tool.
         schedule: Cron expression for scheduled runs.
         schedule_tz: Timezone for schedule.
 
@@ -739,7 +727,6 @@ def upsert(
             code=code,
             input_schema=input_schema,
             description=description,
-            expose_to_ai=expose_to_ai,
             schedule=schedule,
             schedule_tz=schedule_tz,
         )
@@ -753,7 +740,6 @@ def upsert(
             input_schema=input_schema,
             description=description,
             external_id=external_id,
-            expose_to_ai=expose_to_ai,
             schedule=schedule,
             schedule_tz=schedule_tz,
         )
@@ -772,7 +758,7 @@ def delete(automation_id: str) -> None:
     if not automation_id:
         raise ValueError("automation_id is required")
 
-    _api_request("DELETE", f"agents/{automation_id}")
+    _api_request("DELETE", f"automations/{automation_id}")
 
 
 # ============================================================================
@@ -811,7 +797,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}/agent-runs/{run_id}/logs/live"
+    url = f"{base_url}/automation-runs/{run_id}/logs/live"
     headers = {
         "Authorization": f"token {token}",
         "Accept": "text/event-stream",

lumera/sdk.py

@@ -51,10 +51,10 @@ from ._utils import (
     _default_provenance,
     _ensure_mapping,
     _is_sequence,
-    _prepare_agent_inputs,
+    _prepare_automation_inputs,
     _record_mutation,
-    _upload_agent_files,
-    _upload_agent_run_file,
+    _upload_automation_files,
+    _upload_automation_run_file,
     _upload_document,
     _upload_lumera_file,
     _upload_session_file,
@@ -388,8 +388,8 @@ def get_record_by_external_id(collection_id_or_name: str, external_id: str) -> d
     return first
 
 
-def run_agent(
-    agent_id: str,
+def run_automation(
+    automation_id: str,
     *,
     inputs: Mapping[str, Any] | str | None = None,
     files: Mapping[str, str | os.PathLike[str] | Sequence[str | os.PathLike[str]]] | None = None,
@@ -402,7 +402,7 @@ def run_agent(
     """Create an agent run and optionally upload files for file inputs.
 
     Args:
-        agent_id: The automation/agent to run. Required.
+        automation_id: The automation/agent 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``).
@@ -413,16 +413,18 @@ def run_agent(
         metadata: Arbitrary JSON metadata to persist with the run (e.g., callback_url).
     """
 
-    agent_id = agent_id.strip()
-    if not agent_id:
-        raise ValueError("agent_id is required")
+    automation_id = automation_id.strip()
+    if not automation_id:
+        raise ValueError("automation_id is required")
 
     run_id: str | None = None
 
-    prepared_inputs = _prepare_agent_inputs(inputs) or {}
+    prepared_inputs = _prepare_automation_inputs(inputs) or {}
 
     file_map = files or {}
-    run_id, upload_descriptors = _upload_agent_files(run_id, file_map, api_request=_api_request)
+    run_id, upload_descriptors = _upload_automation_files(
+        run_id, file_map, api_request=_api_request
+    )
 
     final_inputs = json.loads(json.dumps(prepared_inputs)) if prepared_inputs else {}
     for key, descriptors in upload_descriptors.items():
@@ -433,7 +435,7 @@ def run_agent(
 
     cleaned_status = status.strip() if isinstance(status, str) else ""
     payload: dict[str, Any] = {
-        "agent_id": agent_id,
+        "automation_id": automation_id,
         "inputs": json.dumps(final_inputs),
         "status": cleaned_status or "queued",
     }
@@ -447,24 +449,24 @@ def run_agent(
         payload["metadata"] = _ensure_mapping(metadata, name="metadata")
     payload["lm_provenance"] = _ensure_mapping(
         provenance, name="provenance"
-    ) or _default_provenance(agent_id, run_id)
+    ) or _default_provenance(automation_id, run_id)
 
-    run = _api_request("POST", "agent-runs", json_body=payload)
+    run = _api_request("POST", "automation-runs", json_body=payload)
     if not isinstance(run, dict):
         raise RuntimeError("unexpected response payload")
     return run
 
 
-def get_agent_run(
-    agent_id: str | None = None,
+def get_automation_run(
+    automation_id: str | None = None,
     *,
     run_id: str | None = None,
     external_id: str | None = None,
 ) -> dict[str, Any]:
-    """Fetch an agent run by id or by agent_id + external_id idempotency key.
+    """Fetch an agent run by id or by automation_id + external_id idempotency key.
 
     Args:
-        agent_id: Agent id for external_id lookup. Required when ``run_id`` is not provided.
+        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.
 
@@ -474,29 +476,33 @@ def get_agent_run(
     """
 
     if run_id:
-        return _api_request("GET", f"agent-runs/{run_id}")
+        return _api_request("GET", f"automation-runs/{run_id}")
 
-    agent_id = agent_id.strip() if isinstance(agent_id, str) else ""
+    automation_id = automation_id.strip() if isinstance(automation_id, str) else ""
     external_id = external_id.strip() if isinstance(external_id, str) else ""
-    if not agent_id:
-        raise ValueError("agent_id is required when run_id is not provided")
+    if not automation_id:
+        raise ValueError("automation_id is required when run_id is not provided")
     if not external_id:
         raise ValueError("external_id is required when run_id is not provided")
 
     resp = _api_request(
         "GET",
-        "agent-runs",
-        params={"agent_id": agent_id, "external_id": external_id, "limit": 1},
+        "automation-runs",
+        params={
+            "automation_id": automation_id,
+            "external_id": external_id,
+            "limit": 1,
+        },
     )
-    runs = resp.get("agent_runs") if isinstance(resp, dict) else None
+    runs = resp.get("data") if isinstance(resp, dict) else None  # Backend returns "data" key
     if runs and isinstance(runs, list) and runs and isinstance(runs[0], dict):
         return runs[0]
 
-    url = _api_url("agent-runs")
-    raise _LumeraAPIError(404, "agent run not found", url=url, payload=None)
+    url = _api_url("automation-runs")
+    raise _LumeraAPIError(404, "automation run not found", url=url, payload=None)
 
 
-def update_agent_run(
+def update_automation_run(
     run_id: str,
     *,
     result: Mapping[str, Any] | None = None,
@@ -533,7 +539,7 @@ def update_agent_run(
     if not payload:
         raise ValueError("at least one field to update is required")
 
-    response = _api_request("PATCH", f"agent-runs/{run_id}", json_body=payload)
+    response = _api_request("PATCH", f"automation-runs/{run_id}", json_body=payload)
     if not isinstance(response, dict):
         raise RuntimeError("unexpected response payload")
     return response
@@ -627,9 +633,7 @@ def bulk_update_records(
         raise ValueError("data is required")
 
     path = f"collections/{collection_id_or_name}/records/bulk/update"
-    result = _api_request(
-        "POST", path, json_body={"ids": list(record_ids), "data": dict(data)}
-    )
+    result = _api_request("POST", path, json_body={"ids": list(record_ids), "data": dict(data)})
     return result if isinstance(result, dict) else {}
 
 
@@ -652,9 +656,7 @@ def bulk_upsert_records(
         raise ValueError("records is required")
 
     path = f"collections/{collection_id_or_name}/records/bulk/upsert"
-    result = _api_request(
-        "POST", path, json_body={"records": [dict(r) for r in records]}
-    )
+    result = _api_request("POST", path, json_body={"records": [dict(r) for r in records]})
     return result if isinstance(result, dict) else {}
 
 
@@ -677,9 +679,7 @@ def bulk_insert_records(
         raise ValueError("records is required")
 
     path = f"collections/{collection_id_or_name}/records/bulk/insert"
-    result = _api_request(
-        "POST", path, json_body={"records": [dict(r) for r in records]}
-    )
+    result = _api_request("POST", path, json_body={"records": [dict(r) for r in records]})
     return result if isinstance(result, dict) else {}
 
 
@@ -912,7 +912,7 @@ def save_to_lumera(file_path: str) -> dict:
 
     run_id = os.getenv("LUMERA_RUN_ID", "").strip()
     if run_id:
-        return _upload_agent_run_file(file_path, run_id)
+        return _upload_automation_run_file(file_path, run_id)
 
     session_id = os.getenv("LUMERA_SESSION_ID", "").strip()
     if session_id:

lumera/storage.py

@@ -116,7 +116,7 @@ def upload(
 
     # Request presigned upload URL
     resp = requests.post(
-        f"{API_BASE}/agent-runs/{run_id}/files/upload-url",
+        f"{API_BASE}/automation-runs/{run_id}/files/upload-url",
         json={"filename": filename, "content_type": content_type, "size": size},
         headers=headers,
         timeout=30,
@@ -215,7 +215,7 @@ def download_url(path: str) -> str:
     headers = {"Authorization": f"token {token}"}
 
     resp = requests.get(
-        f"{API_BASE}/agent-runs/{run_id}/files/download-url",
+        f"{API_BASE}/automation-runs/{run_id}/files/download-url",
         params={"name": filename},
         headers=headers,
         timeout=30,
@@ -257,7 +257,7 @@ def list_files(prefix: str | None = None) -> list[dict[str, Any]]:
     token = get_lumera_token()
     headers = {"Authorization": f"token {token}"}
 
-    resp = requests.get(f"{API_BASE}/agent-runs/{run_id}/files", headers=headers, timeout=30)
+    resp = requests.get(f"{API_BASE}/automation-runs/{run_id}/files", headers=headers, timeout=30)
     resp.raise_for_status()
 
     data = resp.json()

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

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

lumera-0.8.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+lumera/__init__.py,sha256=waGigk2pMakKwoYDLMjKGai5kmL-2KA6hDKouWdq1Z8,2322
+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/webhooks.py,sha256=wOAhqpC6mDgi7wK1LNJEx4sGMR0ZFdCHz2y_W6R9Ajg,8576
+lumera-0.8.0.dist-info/METADATA,sha256=9vmayvlbC9SJ_w1cGEHBqXFo8PtlGimgmh5SkG69XaE,1611
+lumera-0.8.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+lumera-0.8.0.dist-info/top_level.txt,sha256=HgfK4XQkpMTnM2E5iWM4kB711FnYqUY9dglzib3pWlE,7
+lumera-0.8.0.dist-info/RECORD,,

lumera-0.7.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-lumera/__init__.py,sha256=uZMw2gAa7bVn6bOykeCP_19BP0tQquHie3teypVyCkY,2220
-lumera/_utils.py,sha256=QyAaphxXGEK8XNPO0ghKLgTOYhAxcF_j3W0T8StzjxA,23610
-lumera/automations.py,sha256=6Y2USVktrFrueTNNxn8rnBi4-2_eeFpeVbI2gB90AP8,25244
-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=XnzVtAGonhhQ2pDMtNKEOG5ZVH1sPLK-gsyTfCfBLSA,30233
-lumera/storage.py,sha256=kQQJYVRnxcpDZQ_gB2iZy6anb3hyZN7b8a_oNuE2yYE,8191
-lumera-0.7.0.dist-info/METADATA,sha256=BDmiGKUcRGZg585Gfc9Yq8cUP8myD0SA5EZXfdciC_4,1611
-lumera-0.7.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-lumera-0.7.0.dist-info/top_level.txt,sha256=HgfK4XQkpMTnM2E5iWM4kB711FnYqUY9dglzib3pWlE,7
-lumera-0.7.0.dist-info/RECORD,,