tirdad-sdk 2.1.12__tar.gz

tirdad_sdk-2.1.12/MANIFEST.in

@@ -0,0 +1,3 @@
+# Include examples folder and all its contents
+graft examples
+include README.md

tirdad_sdk-2.1.12/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: tirdad-sdk
+Version: 2.1.12
+Summary: Python Client SDK for the Tirdad API.
+Author: Tirdad
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpcore>=1.0.9
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.11.2
+
+# Tirdad Python SDK
+
+Type-safe Python client for the Tirdad API: billing, metering, and subscription management for SaaS and usage-based products.
+
+## Requirements
+
+- **Python 3.10+**
+
+## Installation
+
+```bash
+pip install flexprice
+```
+
+With uv or poetry:
+
+```bash
+uv add flexprice
+# or
+poetry add flexprice
+```
+
+Runnable samples are in the `examples/` directory.
+
+## Environment
+
+| Variable | Required | Description |
+| -------- | -------- | ----------- |
+| `TIRDAD_API_KEY` | Yes | API key |
+| `TIRDAD_API_HOST` | Optional | Full base URL including `https://` and `/v1` (default: `https://api.tirdad.ai/v1`). No trailing slash. |
+
+**Integration tests** in [api/tests/python/test_sdk.py](../tests/python/test_sdk.py) use a different env shape; see [api/tests/README.md](../tests/README.md).
+
+## Quick start
+
+Initialize the client, create a customer, ingest an event:
+
+```python
+import os
+from flexprice import Tirdad
+
+api_key = os.getenv("TIRDAD_API_KEY", "YOUR_API_KEY")
+server_url = os.getenv(
+    "TIRDAD_API_HOST", "https://api.tirdad.ai/v1"
+)
+
+with Tirdad(server_url=server_url, api_key_auth=api_key) as client:
+    external_id = "customer-123"
+    client.customers.create_customer(
+        external_id=external_id,
+        email="user@example.com",
+        name="Example Customer",
+    )
+    result = client.events.ingest_event(
+        request={
+            "event_name": "Sample Event",
+            "external_customer_id": external_id,
+            "properties": {"source": "python_app", "environment": "test"},
+            "source": "python_app",
+        }
+    )
+    print(result)
+```
+
+## Async usage
+
+The same client supports async when used as an async context manager:
+
+```python
+import asyncio
+import os
+from flexprice import Tirdad
+
+async def main():
+    server_url = os.getenv(
+        "TIRDAD_API_HOST", "https://api.tirdad.ai/v1"
+    )
+    async with Tirdad(
+        server_url=server_url,
+        api_key_auth=os.getenv("TIRDAD_API_KEY", "YOUR_API_KEY"),
+    ) as client:
+        result = await client.events.ingest_event_async(
+            request={
+                "event_name": "Sample Event",
+                "external_customer_id": "customer-123",
+                "properties": {"source": "python_async", "environment": "test"},
+                "source": "python_async",
+            }
+        )
+        print(result)
+
+asyncio.run(main())
+```
+
+## Authentication
+
+- Pass your API key as `api_key_auth` when creating the client. The SDK sends it in the `x-api-key` header.
+- Set `TIRDAD_API_HOST` to a full URL (see [Environment](#environment)) or use the default `https://api.tirdad.ai/v1`.
+- Prefer environment variables; get keys from your [Tirdad dashboard](https://app.flexprice.io) or docs.
+
+## Error handling
+
+API errors are raised as exceptions. Catch them and inspect the response as needed:
+
+```python
+try:
+    with Tirdad(server_url="...", api_key_auth="...") as flexprice:
+        result = flexprice.events.ingest_event(request={...})
+except Exception as e:
+    print(f"Error: {e}")
+    # Inspect status code and body if available on the exception
+```
+
+See the [API docs](https://docs.flexprice.io) for error formats and status codes.
+
+## Features
+
+- Full API coverage (customers, plans, events, invoices, payments, entitlements, etc.)
+- Sync and async support
+- Type-safe request/response models (Pydantic)
+- Built-in retries and error handling
+
+For a full list of operations, see the [API reference](https://docs.flexprice.io) and the [examples](examples/) in this repo.
+
+## Troubleshooting
+
+- **Missing or invalid API key:** Ensure `api_key_auth` is set (or set `TIRDAD_API_KEY` and pass it in). Keys are for server-side use only.
+- **Wrong server URL:** Use a full URL such as `https://api.tirdad.ai/v1` (include `/v1`; no trailing slash).
+- **4xx/5xx on ingest:** Event ingest returns 202 Accepted; for errors, check request fields (`event_name`, `external_customer_id`, `properties`, `source`) against the [API docs](https://docs.flexprice.io).
+
+## Handling Webhooks
+
+Tirdad sends webhook events to your server for async updates on payments, invoices, subscriptions, wallets, and more.
+
+**Flow:**
+1. Register your endpoint URL in the Tirdad dashboard
+2. Receive `POST` with raw JSON body
+3. Read `event_type` to route
+4. Parse payload into typed model
+5. Handle business logic idempotently
+6. Return `200` quickly
+
+```python
+import json
+from flexprice.models import (
+    WebhookDtoPaymentWebhookPayload,
+    WebhookDtoSubscriptionWebhookPayload,
+    WebhookDtoInvoiceWebhookPayload,
+)
+
+def handle_webhook(raw_body: str) -> None:
+    event = json.loads(raw_body)
+
+    match event.get("event_type"):
+        case "payment.success" | "payment.failed" | "payment.updated":
+            payload = WebhookDtoPaymentWebhookPayload.model_validate(event)
+            if payload.payment:
+                print(f"payment {payload.payment.id}")
+                # TODO: update payment record
+
+        case "subscription.activated" | "subscription.cancelled" | "subscription.updated":
+            payload = WebhookDtoSubscriptionWebhookPayload.model_validate(event)
+            if payload.subscription:
+                print(f"subscription {payload.subscription.id}")
+
+        case "invoice.update.finalized" | "invoice.payment.overdue":
+            payload = WebhookDtoInvoiceWebhookPayload.model_validate(event)
+            if payload.invoice:
+                print(f"invoice {payload.invoice.id}")
+
+        case _:
+            print(f"unhandled event: {event.get('event_type')}")
+```
+
+### Event types
+
+| Category | Events |
+|---|---|
+| **Payment** | `payment.created` · `payment.updated` · `payment.success` · `payment.failed` · `payment.pending` |
+| **Invoice** | `invoice.create.drafted` · `invoice.update` · `invoice.update.finalized` · `invoice.update.payment` · `invoice.update.voided` · `invoice.payment.overdue` · `invoice.communication.triggered` |
+| **Subscription** | `subscription.created` · `subscription.draft.created` · `subscription.activated` · `subscription.updated` · `subscription.paused` · `subscription.resumed` · `subscription.cancelled` · `subscription.renewal.due` |
+| **Subscription Phase** | `subscription.phase.created` · `subscription.phase.updated` · `subscription.phase.deleted` |
+| **Customer** | `customer.created` · `customer.updated` · `customer.deleted` |
+| **Wallet** | `wallet.created` · `wallet.updated` · `wallet.terminated` · `wallet.transaction.created` · `wallet.credit_balance.dropped` · `wallet.credit_balance.recovered` · `wallet.ongoing_balance.dropped` · `wallet.ongoing_balance.recovered` |
+| **Feature / Entitlement** | `feature.created` · `feature.updated` · `feature.deleted` · `feature.wallet_balance.alert` · `entitlement.created` · `entitlement.updated` · `entitlement.deleted` |
+| **Credit Note** | `credit_note.created` · `credit_note.updated` |
+
+**Production rules:**
+- Keep handlers idempotent — Tirdad retries on non-`2xx`
+- Return `200` for unknown event types — prevents unnecessary retries
+- Do heavy processing async — respond fast, queue the work
+
+## Documentation
+
+- [Tirdad API documentation](https://docs.flexprice.io)
+- [Python SDK examples](examples/) in this repo
+- [SDK integration tests](../tests/README.md) — different `TIRDAD_API_HOST` shape for automated tests

tirdad_sdk-2.1.12/README.md

@@ -0,0 +1,197 @@
+# Tirdad Python SDK
+
+Type-safe Python client for the Tirdad API: billing, metering, and subscription management for SaaS and usage-based products.
+
+## Requirements
+
+- **Python 3.10+**
+
+## Installation
+
+```bash
+pip install flexprice
+```
+
+With uv or poetry:
+
+```bash
+uv add flexprice
+# or
+poetry add flexprice
+```
+
+Runnable samples are in the `examples/` directory.
+
+## Environment
+
+| Variable | Required | Description |
+| -------- | -------- | ----------- |
+| `TIRDAD_API_KEY` | Yes | API key |
+| `TIRDAD_API_HOST` | Optional | Full base URL including `https://` and `/v1` (default: `https://api.tirdad.ai/v1`). No trailing slash. |
+
+**Integration tests** in [api/tests/python/test_sdk.py](../tests/python/test_sdk.py) use a different env shape; see [api/tests/README.md](../tests/README.md).
+
+## Quick start
+
+Initialize the client, create a customer, ingest an event:
+
+```python
+import os
+from flexprice import Tirdad
+
+api_key = os.getenv("TIRDAD_API_KEY", "YOUR_API_KEY")
+server_url = os.getenv(
+    "TIRDAD_API_HOST", "https://api.tirdad.ai/v1"
+)
+
+with Tirdad(server_url=server_url, api_key_auth=api_key) as client:
+    external_id = "customer-123"
+    client.customers.create_customer(
+        external_id=external_id,
+        email="user@example.com",
+        name="Example Customer",
+    )
+    result = client.events.ingest_event(
+        request={
+            "event_name": "Sample Event",
+            "external_customer_id": external_id,
+            "properties": {"source": "python_app", "environment": "test"},
+            "source": "python_app",
+        }
+    )
+    print(result)
+```
+
+## Async usage
+
+The same client supports async when used as an async context manager:
+
+```python
+import asyncio
+import os
+from flexprice import Tirdad
+
+async def main():
+    server_url = os.getenv(
+        "TIRDAD_API_HOST", "https://api.tirdad.ai/v1"
+    )
+    async with Tirdad(
+        server_url=server_url,
+        api_key_auth=os.getenv("TIRDAD_API_KEY", "YOUR_API_KEY"),
+    ) as client:
+        result = await client.events.ingest_event_async(
+            request={
+                "event_name": "Sample Event",
+                "external_customer_id": "customer-123",
+                "properties": {"source": "python_async", "environment": "test"},
+                "source": "python_async",
+            }
+        )
+        print(result)
+
+asyncio.run(main())
+```
+
+## Authentication
+
+- Pass your API key as `api_key_auth` when creating the client. The SDK sends it in the `x-api-key` header.
+- Set `TIRDAD_API_HOST` to a full URL (see [Environment](#environment)) or use the default `https://api.tirdad.ai/v1`.
+- Prefer environment variables; get keys from your [Tirdad dashboard](https://app.flexprice.io) or docs.
+
+## Error handling
+
+API errors are raised as exceptions. Catch them and inspect the response as needed:
+
+```python
+try:
+    with Tirdad(server_url="...", api_key_auth="...") as flexprice:
+        result = flexprice.events.ingest_event(request={...})
+except Exception as e:
+    print(f"Error: {e}")
+    # Inspect status code and body if available on the exception
+```
+
+See the [API docs](https://docs.flexprice.io) for error formats and status codes.
+
+## Features
+
+- Full API coverage (customers, plans, events, invoices, payments, entitlements, etc.)
+- Sync and async support
+- Type-safe request/response models (Pydantic)
+- Built-in retries and error handling
+
+For a full list of operations, see the [API reference](https://docs.flexprice.io) and the [examples](examples/) in this repo.
+
+## Troubleshooting
+
+- **Missing or invalid API key:** Ensure `api_key_auth` is set (or set `TIRDAD_API_KEY` and pass it in). Keys are for server-side use only.
+- **Wrong server URL:** Use a full URL such as `https://api.tirdad.ai/v1` (include `/v1`; no trailing slash).
+- **4xx/5xx on ingest:** Event ingest returns 202 Accepted; for errors, check request fields (`event_name`, `external_customer_id`, `properties`, `source`) against the [API docs](https://docs.flexprice.io).
+
+## Handling Webhooks
+
+Tirdad sends webhook events to your server for async updates on payments, invoices, subscriptions, wallets, and more.
+
+**Flow:**
+1. Register your endpoint URL in the Tirdad dashboard
+2. Receive `POST` with raw JSON body
+3. Read `event_type` to route
+4. Parse payload into typed model
+5. Handle business logic idempotently
+6. Return `200` quickly
+
+```python
+import json
+from flexprice.models import (
+    WebhookDtoPaymentWebhookPayload,
+    WebhookDtoSubscriptionWebhookPayload,
+    WebhookDtoInvoiceWebhookPayload,
+)
+
+def handle_webhook(raw_body: str) -> None:
+    event = json.loads(raw_body)
+
+    match event.get("event_type"):
+        case "payment.success" | "payment.failed" | "payment.updated":
+            payload = WebhookDtoPaymentWebhookPayload.model_validate(event)
+            if payload.payment:
+                print(f"payment {payload.payment.id}")
+                # TODO: update payment record
+
+        case "subscription.activated" | "subscription.cancelled" | "subscription.updated":
+            payload = WebhookDtoSubscriptionWebhookPayload.model_validate(event)
+            if payload.subscription:
+                print(f"subscription {payload.subscription.id}")
+
+        case "invoice.update.finalized" | "invoice.payment.overdue":
+            payload = WebhookDtoInvoiceWebhookPayload.model_validate(event)
+            if payload.invoice:
+                print(f"invoice {payload.invoice.id}")
+
+        case _:
+            print(f"unhandled event: {event.get('event_type')}")
+```
+
+### Event types
+
+| Category | Events |
+|---|---|
+| **Payment** | `payment.created` · `payment.updated` · `payment.success` · `payment.failed` · `payment.pending` |
+| **Invoice** | `invoice.create.drafted` · `invoice.update` · `invoice.update.finalized` · `invoice.update.payment` · `invoice.update.voided` · `invoice.payment.overdue` · `invoice.communication.triggered` |
+| **Subscription** | `subscription.created` · `subscription.draft.created` · `subscription.activated` · `subscription.updated` · `subscription.paused` · `subscription.resumed` · `subscription.cancelled` · `subscription.renewal.due` |
+| **Subscription Phase** | `subscription.phase.created` · `subscription.phase.updated` · `subscription.phase.deleted` |
+| **Customer** | `customer.created` · `customer.updated` · `customer.deleted` |
+| **Wallet** | `wallet.created` · `wallet.updated` · `wallet.terminated` · `wallet.transaction.created` · `wallet.credit_balance.dropped` · `wallet.credit_balance.recovered` · `wallet.ongoing_balance.dropped` · `wallet.ongoing_balance.recovered` |
+| **Feature / Entitlement** | `feature.created` · `feature.updated` · `feature.deleted` · `feature.wallet_balance.alert` · `entitlement.created` · `entitlement.updated` · `entitlement.deleted` |
+| **Credit Note** | `credit_note.created` · `credit_note.updated` |
+
+**Production rules:**
+- Keep handlers idempotent — Tirdad retries on non-`2xx`
+- Return `200` for unknown event types — prevents unnecessary retries
+- Do heavy processing async — respond fast, queue the work
+
+## Documentation
+
+- [Tirdad API documentation](https://docs.flexprice.io)
+- [Python SDK examples](examples/) in this repo
+- [SDK integration tests](../tests/README.md) — different `TIRDAD_API_HOST` shape for automated tests

tirdad_sdk-2.1.12/examples/.env.sample

@@ -0,0 +1,3 @@
+# Full base URL including https:// and /v1; no trailing slash.
+FLEXPRICE_API_KEY=your_api_key_here
+FLEXPRICE_API_HOST=https://us.api.flexprice.io/v1

tirdad_sdk-2.1.12/examples/.gitignore

@@ -0,0 +1,2 @@
+.env
+!.env.sample

tirdad_sdk-2.1.12/examples/README.md

@@ -0,0 +1,14 @@
+# Python SDK examples
+
+1. Create a virtual environment and install dependencies:
+   ```bash
+   python -m venv venv
+   source venv/bin/activate   # Windows: venv\Scripts\activate
+   pip install -r requirements.txt
+   ```
+2. Copy `.env.sample` to `.env` and set **`TIRDAD_API_KEY`**. Optionally set **`TIRDAD_API_HOST`** to a full URL (default: `https://api.tirdad.ai/v1`).
+3. Run the sync example: `python example.py`  
+   Run the async example: `python async_event_example.py`  
+   (From the package root: `python examples/example.py` or `python examples/async_event_example.py`.)
+
+**Integration tests:** Full API flows are in [api/tests/python/test_sdk.py](../../tests/python/test_sdk.py). Install with `pip install -r requirements.txt` in `api/tests/python`; see [api/tests/README.md](../../tests/README.md).

tirdad_sdk-2.1.12/examples/async_event_example.py

@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+"""
+FlexPrice Python SDK example – async client, ingest events.
+
+Default base URL: https://us.api.flexprice.io/v1
+Override with FLEXPRICE_API_HOST (full URL). Set FLEXPRICE_API_KEY in .env or environment.
+"""
+
+import asyncio
+import logging
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from flexprice import Flexprice
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
+logger = logging.getLogger(__name__)
+
+
+async def main():
+    api_key = os.getenv("FLEXPRICE_API_KEY")
+    server_url = os.getenv(
+        "FLEXPRICE_API_HOST", "https://us.api.flexprice.io/v1"
+    )
+
+    if not api_key:
+        raise SystemExit("Set FLEXPRICE_API_KEY in .env or environment")
+
+    logger.info("Using async FlexPrice client")
+
+    async with Flexprice(
+        server_url=server_url,
+        api_key_auth=api_key,
+    ) as flexprice:
+        result = await flexprice.events.ingest_event_async(
+            request={
+                "event_name": "Sample Event",
+                "external_customer_id": "customer-async-123",
+                "properties": {"source": "python_async", "environment": "test"},
+                "source": "python_async",
+            }
+        )
+        logger.info("Event ingested: %s", result)
+
+    logger.info("Async example complete!")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())