Metadata-Version: 2.4
Name: finnear
Version: 0.1.0
Summary: Official Python SDK for Finnear - Push notification platform for founders & developers
Project-URL: Homepage, https://finnear.app
Project-URL: Repository, https://github.com/finnear/finnear-python
License-Expression: MIT
Keywords: analytics,events,finnear,push-notifications,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Finnear Python SDK

Official Python SDK for [Finnear](https://finnear.app) - Push notification platform for founders & developers.

## Installation

```bash
pip install finnear
```

## Quick Start

```python
from finnear import Finnear, EventPayload

client = Finnear(api_key="your-api-key")

result = client.track(EventPayload(
    channel="signups",
    title="New user signed up",
    description="user@example.com",
    emoji="🙋",
    metadata={"plan": "pro"},
))

print(result.event_id)
```

## API

### `Finnear(api_key, base_url?)`

| Option     | Type  | Required | Description          |
| ---------- | ----- | -------- | -------------------- |
| `api_key`  | `str` | Yes      | Your Finnear API key |
| `base_url` | `str` | No       | Custom API base URL  |

### `client.track(event)`

Send an event to Finnear. Returns an `EventResponse` with `event_id`.

| Field         | Type             | Required | Description        |
| ------------- | ---------------- | -------- | ------------------ |
| `channel`     | `str`            | Yes      | Event channel      |
| `title`       | `str`            | Yes      | Event title        |
| `description` | `str`            | No       | Event description  |
| `emoji`       | `str`            | No       | Event emoji icon   |
| `user_id`     | `str`            | No       | Associated user ID |
| `metadata`    | `dict[str, str]` | No       | Key-value metadata |

### Error Handling

```python
from finnear import Finnear, EventPayload, AuthenticationError, ValidationError, ApiError

try:
    client.track(EventPayload(channel="signups", title="New user"))
except AuthenticationError:
    # Invalid API key (401)
    pass
except ValidationError:
    # Invalid payload (400)
    pass
except ApiError as e:
    # Other HTTP error
    print(e.status, str(e))
```

## Requirements

- Python 3.10+
- No external dependencies

## License

MIT
