lamen 0.3.0a1__tar.gz

lamen-0.3.0a1/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: lamen
+Version: 0.3.0a1
+Summary: Official Python SDK for Lamen
+Author: Lamen
+Author-email: dev@lamen.dev
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: httpx (>=0.25)
+Requires-Dist: pydantic[email] (>=2.0)
+Description-Content-Type: text/markdown
+
+# Lamen Python SDK
+
+🚧 Alpha Release
+
+The Lamen Python SDK is currently in active development and may change between versions.
+
+It is suitable for controlled testing and internal integrations, but is NOT yet recommended for general public production use.
+
+If you are integrating Lamen infrastructure, create an account at https://www.lamen.dev and join the community via the Support section in the dashboard.
+
+---
+
+## Overview
+
+The Lamen Python SDK is a backend / machine-to-machine client for interacting with Lamen infrastructure services.
+
+It provides API-key-authenticated access to:
+
+• Messaging — send events, direct send, register device identities, register email identities, manage web tokens  
+• Storage — presigned upload, confirm upload, download URL, list objects, folders, privacy, delete  
+• Streaming / CDN — signed streaming and playback URLs  
+• Athena — ingest logic and analytics events  
+• Geocoding — structured location search  
+
+---
+
+## Authentication
+
+All operations require a valid Lamen API key.
+
+Authentication is handled automatically using the `x-api-key` header.
+
+Example:
+
+from lamen import Lamen
+
+lamen = Lamen(api_key="lam_sk_live_...")
+
+---
+
+## Quick Start (Sync)
+
+from lamen import Lamen
+
+lamen = Lamen(api_key="lam_sk_live_...")
+
+response = lamen.messaging.post_event(
+    event="user_signed_up",
+    external_user_id="user_123",
+)
+
+print(response)
+
+---
+
+## Quick Start (Async)
+
+import asyncio
+from datetime import datetime, timezone
+from lamen import AsyncLamen
+
+async def main():
+    async with AsyncLamen(api_key="lam_sk_live_...") as lamen:
+        await lamen.athena.ingest_event(
+            external_user_id="user_123",
+            event_name="signed_up",
+            occurred_at=datetime.now(timezone.utc),
+            properties={"plan": "free"},
+            idempotency_key="athena:signed_up:user_123:2026-02-01",
+        )
+
+asyncio.run(main())
+
+---
+
+## Example: Storage Upload Flow
+
+from lamen import Lamen
+
+lamen = Lamen(api_key="lam_sk_live_...")
+
+upload = lamen.storage.create_upload_url(
+    filename="image.jpg",
+    content_type="image/jpeg",
+    size_bytes=1024,
+)
+
+print(upload.uploadUrl)
+
+# Upload the file to upload.uploadUrl using your HTTP client
+
+confirmed = lamen.storage.confirm_upload(object_id=upload.object_id)
+
+print(confirmed)
+
+---
+
+## Example: Streaming URL
+
+stream = lamen.stream.get_stream_url(
+    object_id="your-object-uuid",
+    expiry_in_seconds=3600,
+)
+
+print(stream.url)
+
+---
+
+## Error Handling
+
+The SDK raises typed exceptions:
+
+AuthenticationError  
+BillingError  
+ValidationError  
+RateLimitError  
+TimeoutError  
+NetworkError  
+ApiError  
+
+Example:
+
+from lamen import ValidationError
+
+try:
+    lamen.messaging.post_event(event="")
+except ValidationError as e:
+    print("Invalid request:", e)
+
+---
+
+## Retries & Idempotency
+
+Retries are automatically enabled for transient failures:
+
+408, 409, 425, 429, and 5xx responses.
+
+For POST, PATCH, and PUT requests, retries are only enabled if an idempotency_key is provided.
+
+Example:
+
+from datetime import datetime, timezone
+
+lamen.athena.ingest_event(
+    external_user_id="user_123",
+    event_name="purchase",
+    occurred_at=datetime.now(timezone.utc),
+    idempotency_key="purchase:user_123:1234",
+)
+
+---
+
+## Status
+
+Current version: BETA Testing.
+
+Breaking changes may occur before version 1.0.0.
+
+---
+
+## License
+
+Proprietary — © Lamen
+

lamen-0.3.0a1/README.md

@@ -0,0 +1,163 @@
+# Lamen Python SDK
+
+🚧 Alpha Release
+
+The Lamen Python SDK is currently in active development and may change between versions.
+
+It is suitable for controlled testing and internal integrations, but is NOT yet recommended for general public production use.
+
+If you are integrating Lamen infrastructure, create an account at https://www.lamen.dev and join the community via the Support section in the dashboard.
+
+---
+
+## Overview
+
+The Lamen Python SDK is a backend / machine-to-machine client for interacting with Lamen infrastructure services.
+
+It provides API-key-authenticated access to:
+
+• Messaging — send events, direct send, register device identities, register email identities, manage web tokens  
+• Storage — presigned upload, confirm upload, download URL, list objects, folders, privacy, delete  
+• Streaming / CDN — signed streaming and playback URLs  
+• Athena — ingest logic and analytics events  
+• Geocoding — structured location search  
+
+---
+
+## Authentication
+
+All operations require a valid Lamen API key.
+
+Authentication is handled automatically using the `x-api-key` header.
+
+Example:
+
+from lamen import Lamen
+
+lamen = Lamen(api_key="lam_sk_live_...")
+
+---
+
+## Quick Start (Sync)
+
+from lamen import Lamen
+
+lamen = Lamen(api_key="lam_sk_live_...")
+
+response = lamen.messaging.post_event(
+    event="user_signed_up",
+    external_user_id="user_123",
+)
+
+print(response)
+
+---
+
+## Quick Start (Async)
+
+import asyncio
+from datetime import datetime, timezone
+from lamen import AsyncLamen
+
+async def main():
+    async with AsyncLamen(api_key="lam_sk_live_...") as lamen:
+        await lamen.athena.ingest_event(
+            external_user_id="user_123",
+            event_name="signed_up",
+            occurred_at=datetime.now(timezone.utc),
+            properties={"plan": "free"},
+            idempotency_key="athena:signed_up:user_123:2026-02-01",
+        )
+
+asyncio.run(main())
+
+---
+
+## Example: Storage Upload Flow
+
+from lamen import Lamen
+
+lamen = Lamen(api_key="lam_sk_live_...")
+
+upload = lamen.storage.create_upload_url(
+    filename="image.jpg",
+    content_type="image/jpeg",
+    size_bytes=1024,
+)
+
+print(upload.uploadUrl)
+
+# Upload the file to upload.uploadUrl using your HTTP client
+
+confirmed = lamen.storage.confirm_upload(object_id=upload.object_id)
+
+print(confirmed)
+
+---
+
+## Example: Streaming URL
+
+stream = lamen.stream.get_stream_url(
+    object_id="your-object-uuid",
+    expiry_in_seconds=3600,
+)
+
+print(stream.url)
+
+---
+
+## Error Handling
+
+The SDK raises typed exceptions:
+
+AuthenticationError  
+BillingError  
+ValidationError  
+RateLimitError  
+TimeoutError  
+NetworkError  
+ApiError  
+
+Example:
+
+from lamen import ValidationError
+
+try:
+    lamen.messaging.post_event(event="")
+except ValidationError as e:
+    print("Invalid request:", e)
+
+---
+
+## Retries & Idempotency
+
+Retries are automatically enabled for transient failures:
+
+408, 409, 425, 429, and 5xx responses.
+
+For POST, PATCH, and PUT requests, retries are only enabled if an idempotency_key is provided.
+
+Example:
+
+from datetime import datetime, timezone
+
+lamen.athena.ingest_event(
+    external_user_id="user_123",
+    event_name="purchase",
+    occurred_at=datetime.now(timezone.utc),
+    idempotency_key="purchase:user_123:1234",
+)
+
+---
+
+## Status
+
+Current version: BETA Testing.
+
+Breaking changes may occur before version 1.0.0.
+
+---
+
+## License
+
+Proprietary — © Lamen

lamen-0.3.0a1/lamen/__init__.py

@@ -0,0 +1,26 @@
+from .client import Lamen, AsyncLamen
+from .errors import (
+    ApiError,
+    AuthenticationError,
+    BillingError,
+    NetworkError,
+    RateLimitError,
+    TimeoutError,
+    ValidationError,
+)
+from ._version import __version__
+
+
+__all__ = [
+    "Lamen",
+    "AsyncLamen",
+    "__version__",
+    "ApiError",
+    "AuthenticationError",
+    "BillingError",
+    "NetworkError",
+    "RateLimitError",
+    "TimeoutError",
+    "ValidationError",
+]
+

lamen-0.3.0a1/lamen/_version.py

@@ -0,0 +1 @@
+__version__ = "0.3.0a1"

lamen-0.3.0a1/lamen/athena.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Dict, Optional
+from .http import HttpClient, AsyncHttpClient
+from .types import AthenaLogicEventIngest, AthenaIngestResponse
+
+
+class AthenaClient:
+    """Athena ingest (API key): POST /athena/api/events"""
+
+    def __init__(self, http: HttpClient):
+        self._http = http
+
+    def ingest_event(
+        self,
+        *,
+        external_user_id: str,
+        event_name: str,
+        occurred_at: datetime,
+        properties: Optional[Dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> AthenaIngestResponse:
+        payload = AthenaLogicEventIngest(
+            external_user_id=external_user_id,
+            event_name=event_name,
+            occurred_at=occurred_at,
+            properties=properties,
+            idempotency_key=idempotency_key,
+        )
+        data = self._http.post("/athena/api/events", json=payload.model_dump())
+        return AthenaIngestResponse.model_validate(data)
+
+
+class AsyncAthenaClient:
+    def __init__(self, http: AsyncHttpClient):
+        self._http = http
+
+    async def ingest_event(
+        self,
+        *,
+        external_user_id: str,
+        event_name: str,
+        occurred_at: datetime,
+        properties: Optional[Dict[str, Any]] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> AthenaIngestResponse:
+        payload = AthenaLogicEventIngest(
+            external_user_id=external_user_id,
+            event_name=event_name,
+            occurred_at=occurred_at,
+            properties=properties,
+            idempotency_key=idempotency_key,
+        )
+        data = await self._http.post("/athena/api/events", json=payload.model_dump())
+        return AthenaIngestResponse.model_validate(data)

lamen-0.3.0a1/lamen/client.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from .http import DEFAULT_BASE_URL, DEFAULT_TIMEOUT_S, HttpClient, AsyncHttpClient, RetryConfig
+from .storage import StorageClient, AsyncStorageClient
+from .stream import StreamClient, AsyncStreamClient
+from .athena import AthenaClient, AsyncAthenaClient
+from .messaging import MessagingClient, AsyncMessagingClient
+from .geocoding import GeocodeClient, AsyncGeocodeClient
+from ._version import __version__
+
+
+class Lamen:
+    """Top-level SDK client (sync)."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout_s: float = DEFAULT_TIMEOUT_S,
+        user_agent: str = f"lamen-python/{__version__}",
+        retry: RetryConfig | None = None,
+    ):
+        self._http = HttpClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout_s=timeout_s,
+            user_agent=user_agent,
+            retry=retry,
+        )
+
+        self.storage = StorageClient(self._http)
+        self.stream = StreamClient(self._http)
+        self.athena = AthenaClient(self._http)
+        self.messaging = MessagingClient(self._http)
+        self.geocode = GeocodeClient(self._http)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Lamen":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+
+class AsyncLamen:
+    """Top-level SDK client (async)."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout_s: float = DEFAULT_TIMEOUT_S,
+        user_agent: str = f"lamen-python/{__version__}",
+        retry: RetryConfig | None = None,
+    ):
+        self._http = AsyncHttpClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout_s=timeout_s,
+            user_agent=user_agent,
+            retry=retry,
+        )
+
+        self.storage = AsyncStorageClient(self._http)
+        self.stream = AsyncStreamClient(self._http)
+        self.athena = AsyncAthenaClient(self._http)
+        self.messaging = AsyncMessagingClient(self._http)
+        self.geocode = AsyncGeocodeClient(self._http) 
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncLamen":
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.aclose()

lamen-0.3.0a1/lamen/errors.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+class LamenError(Exception):
+    """Base exception for the SDK."""
+
+
+@dataclass
+class ApiError(LamenError):
+    status_code: int
+    message: str
+    method: str
+    path: str
+    response_json: Optional[dict] = None
+    request_id: Optional[str] = None
+
+    def __str__(self) -> str:
+        rid = f" request_id={self.request_id}" if self.request_id else ""
+        return f"ApiError({self.status_code}) {self.method} {self.path}: {self.message}{rid}"
+
+
+class AuthenticationError(LamenError):
+    pass
+
+
+class BillingError(LamenError):
+    pass
+
+
+class ValidationError(LamenError):
+    pass
+
+
+class RateLimitError(LamenError):
+    pass
+
+
+class TimeoutError(LamenError):
+    pass
+
+
+class NetworkError(LamenError):
+    pass

lamen-0.3.0a1/lamen/geocoding.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+from typing import Any, Dict, List, Optional
+
+from .http import HttpClient, AsyncHttpClient
+from .types import GeocodeResult
+import json
+import logging
+
+class GeocodeClient:
+    """Geocoding client (sync)."""
+
+    def __init__(self, http: HttpClient, *, logger: logging.Logger | None = None):
+        self._http = http
+        self._logger = logger or logging.getLogger("lamen.geocode")
+
+    def search(
+        self,
+        *,
+        query: str,
+        limit: int = 10,
+        country: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        if not query or not query.strip():
+            raise ValueError("Query cannot be empty")
+
+        params: Dict[str, Any] = {
+            "q": query,
+            "limit": limit,
+        }
+        if country:
+            params["country"] = country
+
+        data = self._http.get("/geocode/search", params=params)
+
+        if isinstance(data, dict) and "value" in data:
+            data = data["value"]
+
+        if isinstance(data, str):
+            data = json.loads(data)
+
+        if not isinstance(data, list):
+            raise ValueError("Unexpected geocode response shape")
+
+        # Now it MUST be a list of dicts
+        return [GeocodeResult(**item) for item in data]
+
+
+class AsyncGeocodeClient:
+    """Geocoding client (async)."""
+
+    def __init__(self, http: AsyncHttpClient, *, logger: logging.Logger | None = None):
+        self._http = http
+        self._logger = logger or logging.getLogger("lamen.geocode")
+
+    async def search(
+        self,
+        *,
+        query: str,
+        limit: int = 10,
+        country: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        if not query or not query.strip():
+            raise ValueError("Query cannot be empty")
+
+        params: Dict[str, Any] = {
+            "q": query,
+            "limit": limit,
+        }
+        if country:
+            params["country"] = country
+
+        data = await self._http.get("/geocode/search", params=params)
+
+        #  If Redis-wrapped
+        if isinstance(data, dict) and "value" in data:
+            data = data["value"]
+
+        #  If JSON string
+        if isinstance(data, str):
+            data = json.loads(data)
+
+        if not isinstance(data, list):
+            raise ValueError("Unexpected geocode response shape")
+
+        # Now it MUST be a list of dicts
+        return [GeocodeResult(**item) for item in data]
+