lumera 0.9.1__tar.gz → 0.9.3__tar.gz

{lumera-0.9.1 → lumera-0.9.3}/PKG-INFO

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

{lumera-0.9.1 → lumera-0.9.3}/lumera/automations.py

@@ -57,8 +57,9 @@ __all__ = [
     "create",
     "update",
     "upsert",
-    # Log streaming
+    # Log streaming and download
     "stream_logs",
+    "get_log_download_url",
     # Classes
     "Run",
     "Automation",
@@ -218,6 +219,33 @@ class Run:
             self._data = result
         return self
 
+    def get_log_download_url(self) -> str:
+        """Get a presigned URL to download the run's logs.
+
+        Logs are archived to S3 after the run completes. This method returns
+        a presigned URL that can be used to download the log file.
+
+        **Caution for coding agents:** Automation logs can be very large (up to 50MB).
+        Avoid reading entire log contents into context. Instead, download to a file
+        and use tools like `grep`, `tail`, or `head` to extract relevant portions.
+
+        Returns:
+            A presigned URL string for downloading the logs.
+
+        Raises:
+            ValueError: If the run has no ID.
+            RuntimeError: If logs are not yet available (run still in progress).
+
+        Example:
+            >>> run = automations.get_run("run_id")
+            >>> if run.is_terminal:
+            ...     url = run.get_log_download_url()
+            ...     # Download to file, then use grep/tail to inspect
+        """
+        if not self.id:
+            raise ValueError("Cannot get log URL without run id")
+        return get_log_download_url(self.id)
+
     def to_dict(self) -> dict[str, Any]:
         """Return the underlying data dict."""
         return self._data.copy()
@@ -833,3 +861,44 @@ def stream_logs(run_id: str, *, timeout: float = 30) -> Iterator[str]:
                     return
                 current_event = ""
                 current_data = ""
+
+
+def get_log_download_url(run_id: str) -> str:
+    """Get a presigned URL to download the logs for a completed run.
+
+    Logs are archived to S3 after a run completes. This function returns
+    a presigned URL that can be used to download the log file directly.
+
+    **Caution for coding agents:** Automation logs can be very large (up to 50MB).
+    Avoid reading entire log contents into context. Instead, download to a file
+    and use tools like `grep`, `tail`, or `head` to extract relevant portions.
+
+    Args:
+        run_id: The run ID to get logs for.
+
+    Returns:
+        A presigned URL string for downloading the logs.
+
+    Raises:
+        ValueError: If run_id is empty.
+        LumeraAPIError: If the run doesn't exist or logs aren't available.
+
+    Example:
+        >>> url = automations.get_log_download_url("run_abc123")
+        >>> # Download to file, then inspect with shell tools
+        >>> import subprocess
+        >>> subprocess.run(["curl", "-o", "run.log", url])
+        >>> # Use grep/tail to extract relevant parts
+    """
+    run_id = run_id.strip()
+    if not run_id:
+        raise ValueError("run_id is required")
+
+    result = _api_request(
+        "GET",
+        f"automation-runs/{run_id}/files/download-url",
+        params={"name": "run.log"},
+    )
+    if isinstance(result, dict) and "url" in result:
+        return result["url"]
+    raise RuntimeError("Unexpected response: no download URL returned")

lumera-0.9.3/lumera/integrations/__init__.py

@@ -0,0 +1,34 @@
+"""
+Lumera SDK Integrations
+
+Third-party service integrations with Lumera credential management.
+
+Each integration module provides:
+- A `get_*_client()` or `get_*_service()` function that returns an authenticated client
+- Optional helper functions for common Lumera patterns
+
+Example:
+    from lumera.integrations import google, get_access_token
+
+    # Google Sheets with Lumera-managed OAuth
+    sheets = google.get_sheets_service()
+    data = sheets.spreadsheets().values().get(...)
+
+    # Google Drive
+    drive = google.get_drive_service()
+    files = drive.files().list().execute()
+
+    # Get raw access token for any provider
+    token = get_access_token("slack")
+
+Available integrations:
+- `google` - Google APIs (Sheets, Drive)
+
+Utilities:
+- `get_access_token(provider)` - Get OAuth token for any Lumera-connected provider
+"""
+
+from .._utils import get_access_token
+from . import google
+
+__all__ = ["get_access_token", "google"]

lumera-0.9.3/lumera/integrations/google.py

@@ -0,0 +1,338 @@
+"""
+Google API Integration
+
+Provides authenticated Google API clients using Lumera-managed OAuth credentials.
+
+Example:
+    from lumera.integrations import google
+
+    # Get authenticated Sheets service
+    sheets = google.get_sheets_service()
+    data = sheets.spreadsheets().values().get(
+        spreadsheetId="...",
+        range="Sheet1!A1:D10"
+    ).execute()
+
+    # Get authenticated Drive service
+    drive = google.get_drive_service()
+    files = drive.files().list().execute()
+
+    # Share credentials between services
+    creds = google.get_credentials()
+    sheets = google.get_sheets_service(credentials=creds)
+    drive = google.get_drive_service(credentials=creds)
+"""
+
+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 .._utils 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_credentials() -> Credentials:
+    """
+    Retrieves a Google OAuth token from Lumera and
+    converts it into a Credentials object usable by googleapiclient.
+
+    Returns:
+        google.oauth2.credentials.Credentials: Authenticated credentials object.
+
+    Raises:
+        RuntimeError: If LUMERA_TOKEN is not set or token fetch fails.
+    """
+    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
+
+
+# Backward compatibility alias
+get_google_credentials = get_credentials
+
+
+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.
+
+    Args:
+        credentials: Optional pre-fetched credentials. If None, fetches from Lumera.
+
+    Returns:
+        Google Sheets API service resource.
+    """
+    if credentials is None:
+        logger.info("No credentials provided; fetching Google token…")
+        credentials = get_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.
+
+    Args:
+        credentials: Optional pre-fetched credentials. If None, fetches from Lumera.
+
+    Returns:
+        Google Drive API service resource.
+    """
+    if credentials is None:
+        logger.info("No credentials provided; fetching Google token…")
+        credentials = get_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.")
+
+
+__all__ = [
+    # Authentication
+    "get_credentials",
+    "get_google_credentials",  # backward compat alias
+    # 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-0.9.1 → lumera-0.9.3}/lumera/pb.py

@@ -48,6 +48,7 @@ Example:
     >>> deposit = pb.get("deposits", "rec_abc123")
 """
 
+import warnings
 from typing import Any, Iterator, Mapping, Sequence
 
 __all__ = [
@@ -88,9 +89,6 @@ from .sdk import (
 from .sdk import (
     bulk_upsert_records as _bulk_upsert_records,
 )
-from .sdk import (
-    create_collection as _create_collection,
-)
 from .sdk import (
     create_record as _create_record,
 )
@@ -100,6 +98,9 @@ from .sdk import (
 from .sdk import (
     delete_record as _delete_record,
 )
+from .sdk import (
+    ensure_collection as _ensure_collection,
+)
 from .sdk import (
     get_collection as _get_collection,
 )
@@ -115,9 +116,6 @@ from .sdk import (
 from .sdk import (
     list_records as _list_records,
 )
-from .sdk import (
-    update_collection as _update_collection,
-)
 from .sdk import (
     update_record as _update_record,
 )
@@ -561,62 +559,61 @@ def get_collection(name: str) -> dict[str, Any] | None:
         raise
 
 
-def create_collection(
+def ensure_collection(
     name: str,
-    schema: Sequence[dict[str, Any]],
+    schema: Sequence[dict[str, Any]] | None = None,
     *,
     indexes: Sequence[str] | None = None,
 ) -> dict[str, Any]:
-    """Create a new collection.
+    """Ensure a collection exists with the given schema (idempotent).
 
-    Args:
-        name: Collection name (must not start with '_')
-        schema: List of field definitions. Each field is a dict with:
-            - name: Field name (required)
-            - type: Field type (required): text, number, bool, date, json,
-                    relation, select, editor, lumera_file
-            - required: Whether field is required (default False)
-            - options: Type-specific options (e.g., collectionId for relations)
-        indexes: Optional list of index definitions
+    This is the recommended way to manage collections. It creates the collection
+    if it doesn't exist, or updates it if it does. Safe to call multiple times.
 
-    Returns:
-        Created collection object
+    IMPORTANT: The schema and indexes are declarative:
+    - schema: The COMPLETE list of user fields you want (replaces all existing user fields)
+    - indexes: The COMPLETE list of user indexes you want (replaces all existing user indexes)
+    - System fields (id, created, updated, etc.) are automatically managed
+    - System indexes (external_id, updated) are automatically managed
 
-    Example:
-        >>> col = pb.create_collection("deposits", [
-        ...     {"name": "amount", "type": "number", "required": True},
-        ...     {"name": "status", "type": "text"},
-        ...     {"name": "account_id", "type": "relation",
-        ...      "options": {"collectionId": "accounts"}}
-        ... ])
-    """
-    return _create_collection(name, schema=schema, indexes=indexes)
-
-
-def update_collection(
-    name: str,
-    schema: Sequence[dict[str, Any]],
-    *,
-    indexes: Sequence[str] | None = None,
-) -> dict[str, Any]:
-    """Update a collection's schema.
+    If you omit schema or indexes, existing values are preserved.
 
     Args:
-        name: Collection name
-        schema: New schema (replaces existing user fields)
-        indexes: Optional new indexes
+        name: Collection name (must not start with '_')
+        schema: List of field definitions. If provided, replaces all user fields.
+                Each field is a dict with:
+                - name: Field name (required)
+                - type: Field type (required): text, number, bool, date, json,
+                        relation, select, editor, lumera_file
+                - required: Whether field is required (default False)
+                - options: Type-specific options (e.g., collectionId for relations)
+        indexes: Optional list of user index DDL statements. If provided,
+                replaces all user indexes.
 
     Returns:
-        Updated collection object
+        Collection object with:
+        - schema: User-defined fields only (what you can modify)
+        - indexes: User-defined indexes only (what you can modify)
+        - systemInfo: Read-only system fields and indexes (automatically managed)
 
     Example:
-        >>> col = pb.update_collection("deposits", [
+        >>> # Create or update a collection
+        >>> col = pb.ensure_collection("deposits", [
         ...     {"name": "amount", "type": "number", "required": True},
         ...     {"name": "status", "type": "text"},
-        ...     {"name": "notes", "type": "text"}  # New field
+        ... ])
+        >>>
+        >>> # Add a field using copy-modify-send pattern
+        >>> col = pb.get_collection("deposits")
+        >>> col["schema"].append({"name": "notes", "type": "text"})
+        >>> pb.ensure_collection("deposits", col["schema"])
+        >>>
+        >>> # Add an index
+        >>> pb.ensure_collection("deposits", indexes=[
+        ...     "CREATE INDEX idx_status ON deposits (status)"
         ... ])
     """
-    return _update_collection(name, schema=schema, indexes=indexes)
+    return _ensure_collection(name, schema=schema, indexes=indexes)
 
 
 def delete_collection(name: str) -> None:
@@ -634,56 +631,40 @@ def delete_collection(name: str) -> None:
     _delete_collection(name)
 
 
-def ensure_collection(
+# Backwards compatibility aliases
+def create_collection(
     name: str,
     schema: Sequence[dict[str, Any]],
     *,
-    update_schema: bool = False,
     indexes: Sequence[str] | None = None,
 ) -> dict[str, Any]:
-    """Ensure a collection exists with the given schema (idempotent).
-
-    This is the recommended way to set up collections in automation scripts.
-    Safe to call multiple times - will not fail if collection already exists.
-
-    Args:
-        name: Collection name
-        schema: List of field definitions
-        update_schema: If True, update existing collection's schema.
-                      If False (default), leave existing collection unchanged.
-        indexes: Optional list of index definitions
-
-    Returns:
-        Collection object (created, updated, or existing)
-
-    Behavior:
-        - Collection doesn't exist → create it
-        - Collection exists, update_schema=False → return existing (no-op)
-        - Collection exists, update_schema=True → update schema
+    """Create a new collection.
 
-    Example:
-        >>> # Safe to run multiple times
-        >>> col = pb.ensure_collection("deposits", [
-        ...     {"name": "amount", "type": "number", "required": True},
-        ...     {"name": "status", "type": "text"},
-        ... ])
-        >>>
-        >>> # Update schema if collection exists
-        >>> col = pb.ensure_collection("deposits", [
-        ...     {"name": "amount", "type": "number", "required": True},
-        ...     {"name": "status", "type": "text"},
-        ...     {"name": "notes", "type": "text"},  # Add new field
-        ... ], update_schema=True)
+    .. deprecated::
+        Use :func:`ensure_collection` instead, which handles both create and update.
     """
-    existing = get_collection(name)
+    warnings.warn(
+        "create_collection() is deprecated, use ensure_collection() instead",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return ensure_collection(name, schema, indexes=indexes)
 
-    if existing is None:
-        # Collection doesn't exist, create it
-        return create_collection(name, schema, indexes=indexes)
 
-    if update_schema:
-        # Update existing collection's schema
-        return update_collection(name, schema, indexes=indexes)
+def update_collection(
+    name: str,
+    schema: Sequence[dict[str, Any]],
+    *,
+    indexes: Sequence[str] | None = None,
+) -> dict[str, Any]:
+    """Update a collection's schema.
 
-    # Collection exists and update_schema=False, return as-is
-    return existing
+    .. deprecated::
+        Use :func:`ensure_collection` instead, which handles both create and update.
+    """
+    warnings.warn(
+        "update_collection() is deprecated, use ensure_collection() instead",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return ensure_collection(name, schema, indexes=indexes)

{lumera-0.9.1 → lumera-0.9.3}/lumera/sdk.py

@@ -23,6 +23,7 @@ Direct usage is discouraged unless you need low-level control.
 
 import json
 import os
+import warnings
 from typing import Any, Iterable, Mapping, MutableMapping, Sequence, TypedDict
 
 import requests as _requests
@@ -179,27 +180,99 @@ def get_collection(collection_id_or_name: str) -> dict[str, Any]:
     return _api_request("GET", f"collections/{collection_id_or_name}")
 
 
-def create_collection(
+def ensure_collection(
     name: str,
     *,
     collection_type: str = "base",
-    schema: Iterable[CollectionField] | None = None,
-    indexes: Iterable[str] | None = None,
+    schema: Iterable[CollectionField] | object = _UNSET,
+    indexes: Iterable[str] | object = _UNSET,
 ) -> dict[str, Any]:
-    """Create a new PocketBase collection and return the server payload."""
+    """Ensure a collection exists with the given schema and indexes.
+
+    This is an idempotent operation - it creates the collection if it doesn't exist,
+    or updates it if it does. Safe to call multiple times with the same arguments.
+
+    The `schema` field should contain ONLY user-defined fields. System fields
+    (id, created, updated, created_by, updated_by, external_id, lm_provenance)
+    are automatically managed by Lumera and should not be included.
 
+    The `indexes` field should contain ONLY user-defined indexes. System indexes
+    (external_id unique index, updated index) are automatically managed.
+
+    Args:
+        name: Collection name. Required.
+        collection_type: Collection type, defaults to "base".
+        schema: List of field definitions. If provided, replaces all user fields.
+                If omitted, existing fields are preserved.
+        indexes: List of index DDL statements. If provided, replaces all user indexes.
+                 If omitted, existing indexes are preserved.
+
+    Returns:
+        The collection data including:
+        - schema: User-defined fields only
+        - indexes: User-defined indexes only
+        - systemInfo: Object with system-managed fields and indexes (read-only)
+
+    Example:
+        # Create or update a collection
+        coll = ensure_collection(
+            "customers",
+            schema=[
+                {"name": "title", "type": "text", "required": True},
+                {"name": "email", "type": "text"},
+            ],
+            indexes=["CREATE INDEX idx_email ON customers (email)"]
+        )
+
+        # Add a field (copy-modify-send pattern)
+        coll = get_collection("customers")
+        coll["schema"].append({"name": "phone", "type": "text"})
+        ensure_collection("customers", schema=coll["schema"])
+    """
     if not name or not name.strip():
         raise ValueError("name is required")
 
-    payload: dict[str, Any] = {"name": name.strip()}
+    name = name.strip()
+    payload: dict[str, Any] = {}
+
     if collection_type:
         payload["type"] = collection_type
-    if schema is not None:
+
+    if schema is not _UNSET:
+        if schema is None:
+            raise ValueError("schema cannot be None; provide an iterable of fields or omit")
         payload["schema"] = [dict(field) for field in schema]
-    if indexes is not None:
-        payload["indexes"] = list(indexes)
 
-    return _api_request("POST", "collections", json_body=payload)
+    if indexes is not _UNSET:
+        payload["indexes"] = list(indexes) if indexes is not None else []
+
+    return _api_request("PUT", f"collections/{name}", json_body=payload)
+
+
+# Backwards compatibility aliases
+def create_collection(
+    name: str,
+    *,
+    collection_type: str = "base",
+    schema: Iterable[CollectionField] | None = None,
+    indexes: Iterable[str] | None = None,
+) -> dict[str, Any]:
+    """Create a new PocketBase collection.
+
+    .. deprecated::
+        Use :func:`ensure_collection` instead, which handles both create and update.
+    """
+    warnings.warn(
+        "create_collection() is deprecated, use ensure_collection() instead",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return ensure_collection(
+        name,
+        collection_type=collection_type,
+        schema=schema if schema is not None else [],
+        indexes=indexes if indexes is not None else [],
+    )
 
 
 def update_collection(
@@ -210,33 +283,26 @@ def update_collection(
     schema: Iterable[CollectionField] | object = _UNSET,
     indexes: Iterable[str] | object = _UNSET,
 ) -> dict[str, Any]:
-    """Update a PocketBase collection."""
-
-    if not collection_id_or_name:
-        raise ValueError("collection_id_or_name is required")
-
-    payload: dict[str, Any] = {}
-
-    if name is not _UNSET:
-        if name is None or not str(name).strip():
-            raise ValueError("name cannot be empty")
-        payload["name"] = str(name).strip()
-
-    if collection_type is not _UNSET:
-        payload["type"] = collection_type
+    """Update a PocketBase collection.
 
-    if schema is not _UNSET:
-        if schema is None:
-            raise ValueError("schema cannot be None; provide an iterable of fields")
-        payload["schema"] = [dict(field) for field in schema]
-
-    if indexes is not _UNSET:
-        payload["indexes"] = list(indexes) if indexes is not None else []
-
-    if not payload:
-        raise ValueError("no fields provided to update")
+    .. deprecated::
+        Use :func:`ensure_collection` instead, which handles both create and update.
+        Note: The 'name' parameter for renaming is no longer supported.
+    """
+    warnings.warn(
+        "update_collection() is deprecated, use ensure_collection() instead",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    if name is not _UNSET and name != collection_id_or_name:
+        raise ValueError("Renaming collections via 'name' parameter is no longer supported")
 
-    return _api_request("PATCH", f"collections/{collection_id_or_name}", json_body=payload)
+    return ensure_collection(
+        collection_id_or_name,
+        collection_type=collection_type if collection_type is not _UNSET else "base",
+        schema=schema,
+        indexes=indexes,
+    )
 
 
 def delete_collection(collection_id_or_name: str) -> None:

{lumera-0.9.1 → lumera-0.9.3}/lumera.egg-info/PKG-INFO

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

{lumera-0.9.1 → lumera-0.9.3}/lumera.egg-info/SOURCES.txt

@@ -15,4 +15,6 @@ lumera.egg-info/SOURCES.txt
 lumera.egg-info/dependency_links.txt
 lumera.egg-info/requires.txt
 lumera.egg-info/top_level.txt
+lumera/integrations/__init__.py
+lumera/integrations/google.py
 tests/test_sdk.py

{lumera-0.9.1 → lumera-0.9.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "lumera"
-version = "0.9.1"
+version = "0.9.3"
 description = "SDK for building on Lumera platform"
 requires-python = ">=3.11"
 dependencies = [
@@ -45,8 +45,9 @@ full = [
     "requests==2.32.4",
 ]
 
-[tool.setuptools]
-packages = ["lumera"]
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["lumera*"]
 
 [tool.pytest.ini_options]
 minversion = "8.0"

{lumera-0.9.1 → lumera-0.9.3}/tests/test_sdk.py

@@ -154,14 +154,17 @@ def test_list_collections_uses_token_and_returns_payload(monkeypatch: pytest.Mon
     assert headers["Authorization"] == "token tok"
 
 
-def test_create_collection_posts_payload(monkeypatch: pytest.MonkeyPatch) -> None:
+def test_ensure_collection_uses_put(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Test that ensure_collection uses PUT method and includes schema in payload."""
     monkeypatch.setenv(sdk.TOKEN_ENV, "tok")
 
     captured: dict[str, object] = {}
 
-    def fake_request(_method: str, _url: str, **kwargs: object) -> DummyResponse:
+    def fake_request(method: str, url: str, **kwargs: object) -> DummyResponse:
+        captured["method"] = method
+        captured["url"] = url
         captured["json"] = kwargs.get("json")
-        return DummyResponse(status_code=201, json_data={"id": "new"})
+        return DummyResponse(status_code=200, json_data={"id": "new", "name": "example"})
 
     class MockSession:
         def request(self, method: str, url: str, **kwargs: object) -> DummyResponse:
@@ -172,18 +175,52 @@ def test_create_collection_posts_payload(monkeypatch: pytest.MonkeyPatch) -> Non
 
     monkeypatch.setattr(_utils, "_get_session", lambda: MockSession())
 
-    resp = create_collection(
+    resp = sdk.ensure_collection(
         "example", schema=[{"name": "field", "type": "text"}], indexes=["CREATE INDEX"]
     )
 
     assert resp["id"] == "new"
+    assert captured["method"] == "PUT"
+    assert str(captured["url"]).endswith("/collections/example")
     payload = captured["json"]
     assert isinstance(payload, dict)
-    assert payload["name"] == "example"
+    # Name is not in payload (it's in URL path)
+    assert "name" not in payload
     assert payload["schema"][0]["name"] == "field"
     assert payload["indexes"] == ["CREATE INDEX"]
 
 
+def test_create_collection_uses_ensure(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Test that create_collection (deprecated) calls ensure_collection."""
+    monkeypatch.setenv(sdk.TOKEN_ENV, "tok")
+
+    captured: dict[str, object] = {}
+
+    def fake_request(method: str, url: str, **kwargs: object) -> DummyResponse:
+        captured["method"] = method
+        captured["url"] = url
+        return DummyResponse(status_code=200, json_data={"id": "new"})
+
+    class MockSession:
+        def request(self, method: str, url: str, **kwargs: object) -> DummyResponse:
+            return fake_request(method, url, **kwargs)
+
+        def mount(self, prefix: str, adapter: object) -> None:
+            pass
+
+    monkeypatch.setattr(_utils, "_get_session", lambda: MockSession())
+
+    # Should emit deprecation warning
+    with pytest.warns(DeprecationWarning, match="create_collection.*deprecated"):
+        resp = create_collection(
+            "example", schema=[{"name": "field", "type": "text"}], indexes=["CREATE INDEX"]
+        )
+
+    assert resp["id"] == "new"
+    # Should use PUT (via ensure_collection)
+    assert captured["method"] == "PUT"
+
+
 def test_create_record_sends_json_payload(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setenv(sdk.TOKEN_ENV, "tok")