Metadata-Version: 2.4
Name: tirikchilik
Version: 0.2.0
Summary: An unofficial Python wrapper for Tirikchilik API.
Home-page: https://github.com/Diyarbekoralbaev/tirikchilik
Author: Diyarbek Oralbaev
Author-email: diyarbekdev@gmail.com
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
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 :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests~=2.32.3
Requires-Dist: urllib3~=2.2.3
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary


# Tirikchilik

[![PyPI version](https://img.shields.io/pypi/v/tirikchilik)](https://pypi.org/project/tirikchilik/)
[![Python Versions](https://img.shields.io/pypi/pyversions/tirikchilik.svg)](https://pypi.org/project/tirikchilik/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
![Downloads](https://img.shields.io/pypi/dm/tirikchilik)
<p align="center">
  <a href="https://tirikchilik.uz/araltech">
    <img src="https://camo.githubusercontent.com/ed28339e5a5786534715b1c0c885271437761fc91af84d5dc5bbc2c71e307a02/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f546972696b6368696c696b2d6666646430303f7374796c653d666f722d7468652d6261646765" alt="Donate with Tirikchilik">
  </a>
</p>

Tirikchilik is an unofficial Python library for interacting with the Tirikchilik payment API. It supports **Click** and **Uzum** payment systems with typed response objects and full IDE autocompletion.

**Note:** This is an unofficial API wrapper and is not affiliated with or endorsed by Tirikchilik. Use at your own risk.

## Table of Contents
1. [Features](#features)
2. [Installation](#installation)
3. [Quick Start](#quick-start)
4. [Payment Systems](#payment-systems)
5. [API Reference](#api-reference)
6. [Response Objects](#response-objects)
7. [Error Handling](#error-handling)
8. [Dependencies](#dependencies)
9. [Contributing](#contributing)
10. [Support](#support)
11. [License](#license)

## Features
- **Multiple payment systems**: Choose between Click and Uzum at payment creation time.
- **Typed response objects**: `PaymentResponse` and `StatusResponse` with named attributes — no more guessing dict keys.
- **Custom return URL**: Redirect users to your site after Click payment completion.
- **Automatic project ID retrieval**: Just provide your project name, the library resolves the ID.
- **Robust error handling**: Custom exceptions with `code`, `message`, and `description` attributes.
- **Retry mechanism**: Automatically retries on 5xx errors (3 retries with exponential backoff).
- **Connection pooling**: Up to 10 pooled HTTP connections.

## Installation

```bash
pip install tirikchilik
```

## Quick Start

```python
from tirikchilik import Tirikchilik

client = Tirikchilik("MyProject")

# Create a payment (amount in tiyin: 1000000 = 10,000 UZS)
payment = client.create_payment(
    amount=1000000,
    donater="John Doe",
    notes="Donation for Project X",
)

print(payment.pay_id)            # "055ef757-3ca0-45b4-9f3e-a54d86c6ddac"
print(payment.checkout_url)      # "https://my.click.uz/services/pay?..."
print(payment.donate_amount)     # 950000
print(payment.commission_amount) # 50000
print(payment.total_amount)      # 1000000

# Check payment status
status = client.get_payment_status(payment.pay_id)
print(status.status)    # "Paid" or "Draft"
print(status.is_paid)   # True / False
print(status.is_draft)  # True / False
```

## Payment Systems

Choose a payment provider with the `payment_system` parameter:

### Click (default)

```python
payment = client.create_payment(
    amount=1000000,
    donater="John Doe",
    notes="Donation",
    payment_system="click",
)
# payment.checkout_url → "https://my.click.uz/services/pay?..."
```

### Uzum

```python
payment = client.create_payment(
    amount=526316,
    donater="John Doe",
    notes="Donation",
    payment_system="uzum",
)
# payment.checkout_url → "https://www.apelsin.uz/open-service?..."
```

### Custom return URL (Click only)

```python
payment = client.create_payment(
    amount=500000,
    donater="John Doe",
    notes="Donation",
    payment_system="click",
    return_url="https://mysite.com/payment/success",
)
# The checkout_url will contain your return_url
```

## API Reference

### `Tirikchilik(project_name: str)`

Initialize a client. Automatically resolves the project name to a project ID.

- `project_name` — Your project name on tirikchilik.uz.

Raises `UserNotFoundError` if the project name is not found.

---

### `create_payment(amount, donater, notes, payment_system="click", return_url=None)`

Create a new payment.

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `amount` | `int` | Yes | — | Amount in tiyin (1 UZS = 100 tiyin). E.g. `1000000` = 10,000 UZS. |
| `donater` | `str` | Yes | — | Name of the person making the payment. |
| `notes` | `str` | Yes | — | Notes or description for the payment. |
| `payment_system` | `str` | No | `"click"` | Payment provider: `"click"` or `"uzum"`. |
| `return_url` | `str` | No | `None` | Redirect URL after payment (Click only). |

**Returns** a [`PaymentResponse`](#paymentresponse) object.

---

### `get_payment_status(payment_id)`

Get the status of a payment.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `payment_id` | `str` | Yes | The `pay_id` from `PaymentResponse`. |

**Returns** a [`StatusResponse`](#statusresponse) object.

## Response Objects

### `PaymentResponse`

Returned by `create_payment()`.

| Attribute | Type | Description |
|---|---|---|
| `pay_id` | `str` | Unique payment identifier (UUID). |
| `checkout_url` | `str` | URL to redirect the user to complete payment. |
| `donate_amount` | `int` | Net amount after commission (in tiyin). |
| `commission_amount` | `int` | Commission amount (in tiyin). |
| `total_amount` | `int` | Total amount charged (in tiyin). |
| `raw` | `dict` | The original API response dictionary. |

### `StatusResponse`

Returned by `get_payment_status()`.

| Attribute | Type | Description |
|---|---|---|
| `status` | `str` | Payment status string (e.g. `"Paid"`, `"Draft"`). |
| `is_paid` | `bool` | `True` if the payment has been completed. |
| `is_draft` | `bool` | `True` if the payment has not been paid yet. |
| `raw` | `dict` | The original API response dictionary. |

## Error Handling

```python
from tirikchilik import Tirikchilik, PaymentNotFoundError, UserNotFoundError, PaymentError

client = Tirikchilik("MyProject")

try:
    payment = client.create_payment(
        amount=1000000,
        donater="John Doe",
        notes="Test",
    )
except PaymentNotFoundError as e:
    print(f"Payment not found: {e}")
except UserNotFoundError as e:
    print(f"User/project not found: {e}")
except PaymentError as e:
    print(f"Payment error: {e}")
```

| Exception | Description |
|---|---|
| `PaymentError` | Base exception for all payment-related errors. |
| `PaymentNotFoundError` | Raised when the specified payment ID is not found. |
| `UserNotFoundError` | Raised when the project name cannot be resolved. |

All exceptions have `code`, `message`, and `description` attributes.

## Dependencies

- [requests](https://pypi.org/project/requests/) (~2.32.3)
- [urllib3](https://pypi.org/project/urllib3/) (~2.2.3)

Automatically installed with `pip install tirikchilik`.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## Support

If you like this project, please consider supporting it by making a donation:
<p align="center">
  <a href="https://tirikchilik.uz/araltech">
    <img src="https://camo.githubusercontent.com/ed28339e5a5786534715b1c0c885271437761fc91af84d5dc5bbc2c71e307a02/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f546972696b6368696c696b2d6666646430303f7374796c653d666f722d7468652d6261646765" alt="Donate with Tirikchilik">
  </a>
</p>

## License

This project is licensed under the MIT License - see the [LICENSE](https://github.com/Diyarbekoralbaev/tirikchilik/LICENSE)
file for details.

## Disclaimer

This is an unofficial API wrapper for Tirikchilik. It is not affiliated with, endorsed, or supported by Tirikchilik. Use
this library at your own risk. The authors and contributors are not responsible for any misuse or damage caused by this
software.
