Metadata-Version: 2.4
Name: littleevents
Version: 0.1.1
Summary: The official Python SDK for interacting with the Little Events API.
Author-email: Ephy Mucira <ephymucira@gmail.com>
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Dynamic: license-file

# littleevents

The official, developer-friendly Python SDK for interacting with the **Little Africa Events API**.

`littleevents` allows external businesses and organizers to seamlessly list, create, and manage events, as well as configure, disable, or enable ticket tiers on the Little Africa platform.

[![PyPI version](https://img.shields.io/pypi/v/littleevents.svg)](https://pypi.org/project/littleevents/)
[![Python versions](https://img.shields.io/pypi/pyversions/littleevents.svg)](https://pypi.org/project/littleevents/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## Key Features

- **Resource-Oriented Interface**: Natural, idiomatic usage (e.g. `client.events.list_events()`, `client.ticket_prices.create_ticket_price()`).
- **Resilient Request Pipeline**: Automatically handles HTTP retries on standard rate limits (`429`) and server errors (`5xx`) using `httpx.HTTPTransport`.
- **Zero-Overhead Serialization**: Pure Python dictionary interfaces for requests and responses—no complex validation models or Pydantic overhead.
- **Rich Error Observation**: Surfaces `LittleEventsAPIError` preserving raw upstream HTTP status codes, error structures, and validation messages.
- **Clean Sync Client**: Optimized HTTP connection pool management built on `httpx`.

---

## Installation

Install the package via `pip` from PyPI:

```bash
pip install littleevents
```

---

## Quickstart

### 1. Client Initialization

Import the client and initialize it using your Bearer API token:

```python
from littleevents import LittleEventsClient

# Initialize the client
client = LittleEventsClient(api_key="your-little-bearer-token")
```

---

### 2. Events Management

#### List Organizer Events
Retrieve all events belonging to the authenticated organizer:
```python
events_response = client.events.list_events()
print(f"Retrieved {len(events_response.get('data', []))} events.")
```

#### Create a New Event
Add a new event under your organizer account. Image dimensions must be exactly `500x500 px`:
```python
new_event_data = {
    "EventName": "Startup Neon Gala",
    "Description": "An exquisite evening celebration of tech innovators.",
    "Location": "Alchemist Bar, Westlands",
    "ContactEmail": "events@example.com",
    "ContactPhone": "+254700000000",
    "Country": "Kenya",
    "City": "Nairobi",
    "ImageUrl": "https://example.com/500x500-banner.jpg", # Exactly 500x500 px
    "EventType": "regular",
    "TestEvent": True, # Set to True for sandbox testing
    "Timings": [
        {
            "ShowID": "cb488791-3252-440c-a1de-e5324f10d8cc",
            "Label": "Main Show",
            "Start": "2026-06-01T18:00:00.000Z",
            "End": "2026-06-01T22:00:00.000Z"
        }
    ]
}

created_event = client.events.create_event(new_event_data)
```

#### Get Event Details by ID
```python
event = client.events.get_event("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
print(event["EventName"])
```

#### Update Event
Modify details of an existing event (fields are optional):
```python
client.events.update_event(
    event_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    data={"Location": "Broadwalk Mall, Westlands"}
)
```

#### Request Go Live
Submit an event for review and publication by the Little Africa team:
```python
client.events.request_go_live("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
```

---

### 3. Ticket Prices Management

#### Create Ticket Price
Attach a price tier to an existing event:
```python
ticket_payload = {
    "EventID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "PriceName": "Early Bird General",
    "Price": 1500, # In Currency denomination
    "Remaining": 100, # Total supply available
    "Currency": "KES", # "KES" or "USD"
    "MaxAttendees": 100,
    "MaxTicketsPerOrder": 5
}

client.ticket_prices.create_ticket_price(ticket_payload)
```

#### Update Ticket Price
```python
client.ticket_prices.update_ticket_price(
    price_id="f47ac10b-58cc-4372-a567-0e02b2c3d479",
    data={"Price": 1800}
)
```

#### Disable / Enable Ticket Tiers
Manage the active sales status of ticket tiers:
```python
# Terminate sales for a tier
client.ticket_prices.disable_ticket_price("f47ac10b-58cc-4372-a567-0e02b2c3d479")

# Re-enable sales for a tier
client.ticket_prices.enable_ticket_price("f47ac10b-58cc-4372-a567-0e02b2c3d479")
```

#### List Active Ticket Prices
Retrieve active ticket prices bound to a specific event:
```python
active_tickets = client.ticket_prices.list_active_ticket_prices_for_event("a1b2c3d4-e5f6-7890-abcd-ef1234567890")
```

---

## Robust Error Handling

The SDK raises standard `LittleEventsAPIError` whenever the Little Africa API responds with a non-2xx status code. This preserves the upstream message and state details:

```python
from littleevents import LittleEventsClient, LittleEventsAPIError

client = LittleEventsClient(api_key="token")

try:
    # Trigger an intentional error (e.g. invalid dimensions)
    client.events.create_event({
        "EventName": "Gala",
        "ImageUrl": "https://example.com/invalid-image.jpg" # Not 500x500 px
        # ... other missing required fields
    })
except LittleEventsAPIError as e:
    print(f"API Error Occurred! Status Code: {e.status_code}")
    print(f"Server Message: {e.message}")
    print(f"Full JSON Payload: {e.response_data}")
```

---

## License

This project is licensed under the MIT License.
