# 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
