spatialflow 0.1.0__py3-none-any.whl

spatialflow/jobs.py

@@ -0,0 +1,204 @@
+"""
+Async job polling helpers for SpatialFlow SDK.
+
+Provides utilities for polling long-running jobs like file uploads.
+"""
+
+import asyncio
+from typing import Any, Callable, Dict, Optional, TypeVar
+
+from .exceptions import SpatialFlowError, TimeoutError
+
+T = TypeVar("T")
+
+
+class JobTimeoutError(TimeoutError):
+    """Raised when a job polling operation times out."""
+
+    def __init__(self, job_id: str, timeout: float, last_status: Optional[str] = None):
+        self.job_id = job_id
+        self.timeout = timeout
+        self.last_status = last_status
+        message = f"Job {job_id} did not complete within {timeout} seconds"
+        if last_status:
+            message += f" (last status: {last_status})"
+        super().__init__(message)
+
+
+class JobFailedError(SpatialFlowError):
+    """Raised when a polled job fails."""
+
+    def __init__(
+        self,
+        job_id: str,
+        error_message: Optional[str] = None,
+        results: Optional[Dict[str, Any]] = None,
+    ):
+        self.job_id = job_id
+        self.error_message = error_message
+        self.results = results
+        message = f"Job {job_id} failed"
+        if error_message:
+            message += f": {error_message}"
+        super().__init__(message)
+
+
+class JobResult:
+    """Result of a completed job."""
+
+    def __init__(
+        self,
+        job_id: str,
+        status: str,
+        created_count: int = 0,
+        failed_count: int = 0,
+        total_features: int = 0,
+        results: Optional[Dict[str, Any]] = None,
+        duration: Optional[float] = None,
+        raw_response: Optional[Any] = None,
+    ):
+        self.job_id = job_id
+        self.status = status
+        self.created_count = created_count
+        self.failed_count = failed_count
+        self.total_features = total_features
+        self.results = results or {}
+        self.duration = duration
+        self.raw_response = raw_response
+
+    @property
+    def created_geofences(self) -> list:
+        """List of created geofence info (id, name)."""
+        return self.results.get("created_geofences", [])
+
+    @property
+    def errors(self) -> list:
+        """List of errors that occurred during processing."""
+        return self.results.get("errors", [])
+
+    @property
+    def warnings(self) -> list:
+        """List of warnings from processing."""
+        return self.results.get("warnings", [])
+
+    def __repr__(self) -> str:
+        return (
+            f"JobResult(job_id={self.job_id!r}, status={self.status!r}, "
+            f"created={self.created_count}, failed={self.failed_count})"
+        )
+
+
+async def poll_job(
+    fetch_status: Callable[[], Any],
+    *,
+    timeout: float = 300,
+    poll_interval: float = 2.0,
+    terminal_statuses: tuple = ("completed", "failed"),
+    on_status: Optional[Callable[[str, Any], None]] = None,
+    extract_job_id: Optional[Callable[[Any], str]] = None,
+    extract_status: Optional[Callable[[Any], str]] = None,
+) -> JobResult:
+    """
+    Poll a job until it reaches a terminal status.
+
+    Args:
+        fetch_status: Async function that fetches the current job status.
+                     Should return a response object with status information.
+        timeout: Maximum time to wait in seconds. Default: 300 (5 minutes).
+        poll_interval: Time between polls in seconds. Default: 2.0.
+        terminal_statuses: Tuple of statuses that indicate the job is done.
+                          Default: ("completed", "failed").
+        on_status: Optional callback called on each poll with (status, response).
+        extract_job_id: Function to extract job_id from response.
+                       Default: looks for job_id attribute or dict key.
+        extract_status: Function to extract status from response.
+                       Default: looks for status attribute or dict key.
+
+    Returns:
+        JobResult with the final job state.
+
+    Raises:
+        JobTimeoutError: If the job doesn't complete within the timeout.
+        JobFailedError: If the job fails.
+
+    Example:
+        >>> async def get_status():
+        ...     return await client.geofences.apps_geofences_api_get_upload_job_status(
+        ...         job_id=job_id
+        ...     )
+        ...
+        >>> result = await poll_job(get_status, timeout=120)
+        >>> print(f"Created {result.created_count} geofences")
+    """
+    extract_job_id = extract_job_id or _default_extract_job_id
+    extract_status = extract_status or _default_extract_status
+
+    elapsed = 0.0
+    last_status: Optional[str] = None
+    last_response: Optional[Any] = None
+
+    while elapsed < timeout:
+        response = await fetch_status()
+        last_response = response
+        status = extract_status(response)
+        last_status = status
+
+        if on_status:
+            on_status(status, response)
+
+        if status in terminal_statuses:
+            job_id = extract_job_id(response)
+            return _build_job_result(job_id, status, response)
+
+        await asyncio.sleep(poll_interval)
+        elapsed += poll_interval
+
+    # Timeout
+    job_id = extract_job_id(last_response) if last_response else "unknown"
+    raise JobTimeoutError(job_id, timeout, last_status)
+
+
+def _default_extract_job_id(response: Any) -> str:
+    """Extract job_id from response."""
+    if hasattr(response, "job_id"):
+        return str(response.job_id)
+    if isinstance(response, dict):
+        return str(response.get("job_id", "unknown"))
+    return "unknown"
+
+
+def _default_extract_status(response: Any) -> str:
+    """Extract status from response."""
+    if hasattr(response, "status"):
+        return str(response.status)
+    if isinstance(response, dict):
+        return str(response.get("status", "unknown"))
+    return "unknown"
+
+
+def _build_job_result(job_id: str, status: str, response: Any) -> JobResult:
+    """Build a JobResult from the response."""
+    # Handle both object attributes and dict access
+    def get_field(name: str, default: Any = None) -> Any:
+        if hasattr(response, name):
+            return getattr(response, name)
+        if isinstance(response, dict):
+            return response.get(name, default)
+        return default
+
+    # Check for failure
+    if status == "failed":
+        error_message = get_field("error_message")
+        results = get_field("results")
+        raise JobFailedError(job_id, error_message, results)
+
+    return JobResult(
+        job_id=job_id,
+        status=status,
+        created_count=get_field("created_count", 0),
+        failed_count=get_field("failed_count", 0),
+        total_features=get_field("total_features", 0),
+        results=get_field("results"),
+        duration=get_field("duration"),
+        raw_response=response,
+    )

spatialflow/pagination.py

@@ -0,0 +1,142 @@
+"""
+Pagination helpers for SpatialFlow SDK.
+
+Provides async iterators for paginated API responses.
+"""
+
+from typing import TypeVar, Generic, AsyncIterator, Callable, Awaitable, Any, List
+
+T = TypeVar("T")
+
+
+class PaginatedResponse(Generic[T]):
+    """
+    A paginated response with helper methods for navigation.
+
+    Attributes:
+        items: The items in the current page
+        count: Total number of items across all pages
+        next_url: URL for the next page (if any)
+        previous_url: URL for the previous page (if any)
+    """
+
+    def __init__(
+        self,
+        items: List[T],
+        count: int,
+        next_url: str | None = None,
+        previous_url: str | None = None,
+    ):
+        self.items = items
+        self.count = count
+        self.next_url = next_url
+        self.previous_url = previous_url
+
+    @property
+    def has_more(self) -> bool:
+        """Returns True if there are more pages available."""
+        return self.next_url is not None
+
+    def __iter__(self):
+        """Iterate over items in the current page."""
+        return iter(self.items)
+
+    def __len__(self) -> int:
+        """Number of items in the current page."""
+        return len(self.items)
+
+
+class AsyncPaginator(Generic[T]):
+    """
+    Async iterator for paginated API responses.
+
+    Automatically fetches subsequent pages as you iterate.
+
+    Example:
+        >>> async for geofence in client.geofences.list_all():
+        ...     print(geofence.name)
+    """
+
+    def __init__(
+        self,
+        fetch_page: Callable[[int, int], Awaitable[Any]],
+        extract_items: Callable[[Any], List[T]],
+        extract_count: Callable[[Any], int],
+        extract_next: Callable[[Any], str | None],
+        limit: int = 100,
+    ):
+        """
+        Initialize the paginator.
+
+        Args:
+            fetch_page: Async function that fetches a page (offset, limit) -> response
+            extract_items: Function to extract items list from response
+            extract_count: Function to extract total count from response
+            extract_next: Function to extract next page URL from response
+            limit: Number of items per page
+        """
+        self._fetch_page = fetch_page
+        self._extract_items = extract_items
+        self._extract_count = extract_count
+        self._extract_next = extract_next
+        self._limit = limit
+        self._offset = 0
+        self._exhausted = False
+        self._total_count: int | None = None
+
+    async def __aiter__(self) -> AsyncIterator[T]:
+        """Async iterate over all items across all pages."""
+        while not self._exhausted:
+            response = await self._fetch_page(self._offset, self._limit)
+            items = self._extract_items(response)
+            self._total_count = self._extract_count(response)
+            next_url = self._extract_next(response)
+
+            for item in items:
+                yield item
+
+            if next_url is None or len(items) < self._limit:
+                self._exhausted = True
+            else:
+                self._offset += self._limit
+
+    @property
+    def total_count(self) -> int | None:
+        """
+        Total count of items (available after first page is fetched).
+        """
+        return self._total_count
+
+
+def paginate(
+    fetch_page: Callable[[int, int], Awaitable[Any]],
+    limit: int = 100,
+) -> AsyncPaginator:
+    """
+    Create a paginator for a list endpoint.
+
+    This is a convenience function for the common case where the response
+    has 'results', 'count', and 'next' fields.
+
+    Args:
+        fetch_page: Async function that takes (offset, limit) and returns response
+        limit: Number of items per page (default 100)
+
+    Returns:
+        AsyncPaginator that yields items from all pages
+
+    Example:
+        >>> async def fetch(offset, limit):
+        ...     return await client.geofences.apps_geofences_api_list_geofences(
+        ...         offset=offset, limit=limit
+        ...     )
+        >>> async for geofence in paginate(fetch):
+        ...     print(geofence.name)
+    """
+    return AsyncPaginator(
+        fetch_page=fetch_page,
+        extract_items=lambda r: r.results if hasattr(r, "results") else [],
+        extract_count=lambda r: r.count if hasattr(r, "count") else 0,
+        extract_next=lambda r: r.next if hasattr(r, "next") else None,
+        limit=limit,
+    )

spatialflow/uploads.py

@@ -0,0 +1,166 @@
+"""
+File upload helpers for SpatialFlow SDK.
+
+Provides utilities for uploading files (GeoJSON, KML, GPX) and processing them.
+"""
+
+import os
+from pathlib import Path
+from typing import Any, Callable, Optional, Union
+
+import aiohttp
+
+from .jobs import JobResult, poll_job
+
+
+async def upload_geofences(
+    client: Any,
+    file_path: Union[str, Path],
+    *,
+    group_name: Optional[str] = None,
+    timeout: float = 300,
+    poll_interval: float = 2.0,
+    on_status: Optional[Callable[[str, Any], None]] = None,
+) -> JobResult:
+    """
+    Upload a geofence file and wait for processing to complete.
+
+    This is a convenience method that:
+    1. Requests a presigned upload URL
+    2. Uploads the file to S3
+    3. Starts the geofence import job
+    4. Polls until completion
+
+    Args:
+        client: SpatialFlow client instance.
+        file_path: Path to the file to upload (GeoJSON, KML, or GPX).
+        group_name: Optional name for the geofence group.
+        timeout: Maximum time to wait for processing in seconds. Default: 300.
+        poll_interval: Time between status polls in seconds. Default: 2.0.
+        on_status: Optional callback called on each poll with (status, response).
+
+    Returns:
+        JobResult with the final job state including created geofences.
+
+    Raises:
+        FileNotFoundError: If the file doesn't exist.
+        ValueError: If the file type is not supported.
+        JobTimeoutError: If processing doesn't complete within timeout.
+        JobFailedError: If the import job fails.
+
+    Example:
+        >>> result = await upload_geofences(
+        ...     client,
+        ...     "boundaries.geojson",
+        ...     group_name="my-region",
+        ...     timeout=120,
+        ... )
+        >>> print(f"Created {result.created_count} geofences")
+    """
+    file_path = Path(file_path)
+
+    if not file_path.exists():
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    # Get file info
+    filename = file_path.name
+    file_size = file_path.stat().st_size
+
+    # Determine content type
+    ext = file_path.suffix.lower()
+    content_types = {
+        ".geojson": "application/geo+json",
+        ".json": "application/json",
+        ".kml": "application/vnd.google-earth.kml+xml",
+        ".gpx": "application/gpx+xml",
+    }
+
+    if ext not in content_types:
+        raise ValueError(
+            f"Unsupported file type: {ext}. "
+            f"Supported types: {', '.join(content_types.keys())}"
+        )
+
+    content_type = content_types[ext]
+
+    # Step 1: Get presigned upload URL
+    presigned_response = await client.storage.apps_storage_api_create_presigned_url(
+        presigned_url_request={
+            "file_type": "geofences",
+            "filename": filename,
+            "file_size": file_size,
+        }
+    )
+
+    # Extract from response (handle both direct and axios-style responses)
+    presigned_data = _extract_data(presigned_response)
+    upload_url = presigned_data.get("upload_url")
+    file_id = presigned_data.get("file_id")
+
+    if not upload_url:
+        raise ValueError(
+            "Failed to get presigned upload URL from storage API. "
+            "Response missing 'upload_url' field."
+        )
+    if not file_id:
+        raise ValueError(
+            "Failed to get file ID from storage API. "
+            "Response missing 'file_id' field."
+        )
+
+    # Step 2: Upload file to S3
+    # Note: For large files, consider using aiohttp's streaming upload.
+    # This implementation reads the entire file into memory for simplicity.
+    async with aiohttp.ClientSession() as session:
+        with open(file_path, "rb") as f:
+            file_content = f.read()
+
+        async with session.put(
+            upload_url,
+            data=file_content,
+            headers={"Content-Type": content_type},
+        ) as resp:
+            if resp.status not in (200, 204):
+                text = await resp.text()
+                raise ValueError(f"Failed to upload file to S3: {resp.status} - {text}")
+
+    # Step 3: Start the geofence import job
+    upload_request = {"file_id": file_id}
+    if group_name:
+        upload_request["group_name"] = group_name
+
+    job_response = await client.geofences.apps_geofences_api_upload_geofences_async(
+        upload_geofences_request=upload_request
+    )
+
+    job_data = _extract_data(job_response)
+    job_id = job_data.get("job_id")
+
+    if not job_id:
+        raise ValueError(
+            "Failed to start upload job. Response missing 'job_id' field."
+        )
+
+    # Step 4: Poll for completion
+    async def fetch_status():
+        return await client.geofences.apps_geofences_api_get_upload_job_status(
+            job_id=job_id
+        )
+
+    return await poll_job(
+        fetch_status,
+        timeout=timeout,
+        poll_interval=poll_interval,
+        on_status=on_status,
+    )
+
+
+def _extract_data(response: Any) -> dict:
+    """Extract data from response, handling axios-style responses."""
+    if hasattr(response, "data"):
+        return response.data if isinstance(response.data, dict) else response.data.__dict__
+    if isinstance(response, dict):
+        return response
+    if hasattr(response, "__dict__"):
+        return response.__dict__
+    return {}

spatialflow/webhooks.py

@@ -0,0 +1,126 @@
+"""
+Webhook signature verification for SpatialFlow SDK.
+
+Provides HMAC-SHA256 signature verification for webhook payloads.
+"""
+
+import hashlib
+import hmac
+import time
+from typing import Union
+
+from .exceptions import SpatialFlowError
+
+
+class WebhookSignatureError(SpatialFlowError):
+    """Raised when webhook signature verification fails."""
+
+    pass
+
+
+def verify_webhook_signature(
+    payload: Union[str, bytes],
+    signature: str,
+    secret: str,
+    tolerance: int = 300,
+) -> dict:
+    """
+    Verify a webhook signature and return the parsed payload.
+
+    SpatialFlow webhooks include an HMAC-SHA256 signature in the
+    `X-SF-Signature` header. This function verifies that signature
+    and optionally checks the timestamp to prevent replay attacks.
+
+    Args:
+        payload: The raw webhook payload (request body as string or bytes)
+        signature: The signature from X-SF-Signature header
+        secret: Your webhook signing secret
+        tolerance: Maximum age of the webhook in seconds (default 300 = 5 minutes).
+                   Set to 0 to disable timestamp checking.
+
+    Returns:
+        The parsed webhook payload as a dict
+
+    Raises:
+        WebhookSignatureError: If signature is invalid or timestamp is too old
+
+    Example:
+        >>> from spatialflow import verify_webhook_signature
+        >>>
+        >>> # In your webhook handler (e.g., Flask/FastAPI)
+        >>> @app.post("/webhook")
+        >>> async def handle_webhook(request):
+        ...     payload = await request.body()
+        ...     signature = request.headers.get("X-SF-Signature")
+        ...
+        ...     try:
+        ...         event = verify_webhook_signature(
+        ...             payload=payload,
+        ...             signature=signature,
+        ...             secret=WEBHOOK_SECRET,
+        ...         )
+        ...         # Process the verified event
+        ...         print(f"Event type: {event['type']}")
+        ...         return {"status": "ok"}
+        ...     except WebhookSignatureError as e:
+        ...         return {"error": str(e)}, 400
+    """
+    import json
+
+    # Normalize payload to bytes
+    if isinstance(payload, str):
+        payload_bytes = payload.encode("utf-8")
+    else:
+        payload_bytes = payload
+
+    # Parse the signature header
+    # Format: t=<timestamp>,v1=<signature>
+    try:
+        parts = dict(part.split("=", 1) for part in signature.split(","))
+        timestamp_str = parts.get("t")
+        sig_hash = parts.get("v1")
+
+        if not timestamp_str or not sig_hash:
+            raise WebhookSignatureError(
+                "Invalid signature format. Expected: t=<timestamp>,v1=<signature>"
+            )
+
+        timestamp = int(timestamp_str)
+    except (ValueError, AttributeError) as e:
+        raise WebhookSignatureError(f"Failed to parse signature header: {e}")
+
+    # Check timestamp tolerance (replay attack prevention)
+    if tolerance > 0:
+        now = int(time.time())
+        age = now - timestamp
+        if age > tolerance:
+            raise WebhookSignatureError(
+                f"Webhook timestamp too old: {age}s (tolerance: {tolerance}s)"
+            )
+        if age < -tolerance:
+            raise WebhookSignatureError(
+                f"Webhook timestamp in future: {-age}s (tolerance: {tolerance}s)"
+            )
+
+    # Compute expected signature
+    # The signed payload is: timestamp.payload
+    signed_payload = f"{timestamp}.".encode("utf-8") + payload_bytes
+    expected_sig = hmac.new(
+        secret.encode("utf-8"),
+        signed_payload,
+        hashlib.sha256,
+    ).hexdigest()
+
+    # Constant-time comparison to prevent timing attacks
+    if not hmac.compare_digest(expected_sig, sig_hash):
+        raise WebhookSignatureError("Signature verification failed")
+
+    # Parse and return the payload
+    try:
+        return json.loads(payload_bytes.decode("utf-8"))
+    except json.JSONDecodeError as e:
+        raise WebhookSignatureError(f"Failed to parse webhook payload as JSON: {e}")
+
+
+# Convenience alias
+verify_signature = verify_webhook_signature