Metadata-Version: 2.3
Name: tgateway
Version: 0.1.0
Summary: TGateway: the simplest way to work with a Telegram Gateway API
Project-URL: Homepage, https://tgateway.deusdeveloper.com/latest/
Project-URL: Documentation, https://tgateway.deusdeveloper.com/latest/getting-started/
Project-URL: Tracker, https://github.com/deus-developer/tgateway/issues
Project-URL: Source, https://github.com/deus-developer/tgateway
Project-URL: Telegram, https://t.me/tgateway
Author-email: Artem Ukolov <deusdeveloper@yandex.com>
License-File: LICENSE
Keywords: auth,sms,telegram,verify
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: AsyncIO
Classifier: Framework :: Pydantic
Classifier: Framework :: Pydantic :: 2
Classifier: Framework :: aiohttp
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: aiohttp>=3.7.0
Requires-Dist: pydantic>=2.0
Provides-Extra: cli
Requires-Dist: typer>=0.7.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: bandit==1.7.10; extra == 'dev'
Requires-Dist: codespell==2.3.0; extra == 'dev'
Requires-Dist: mypy==1.11.2; extra == 'dev'
Requires-Dist: pre-commit==4.0.0; extra == 'dev'
Requires-Dist: ruff==0.6.9; extra == 'dev'
Requires-Dist: semgrep==1.90.0; extra == 'dev'
Requires-Dist: typer>=0.7.0; extra == 'dev'
Provides-Extra: lint
Requires-Dist: bandit==1.7.10; extra == 'lint'
Requires-Dist: codespell==2.3.0; extra == 'lint'
Requires-Dist: mypy==1.11.2; extra == 'lint'
Requires-Dist: ruff==0.6.9; extra == 'lint'
Requires-Dist: semgrep==1.90.0; extra == 'lint'
Requires-Dist: typer>=0.7.0; extra == 'lint'
Provides-Extra: optionals
Requires-Dist: typer>=0.7.0; extra == 'optionals'
Provides-Extra: types
Requires-Dist: mypy==1.11.2; extra == 'types'
Requires-Dist: typer>=0.7.0; extra == 'types'
Description-Content-Type: text/markdown

# Telegram Gateway Python SDK

![Python](https://img.shields.io/badge/Python-3.9%2B-blue)
![License](https://img.shields.io/github/license/deus-developer/tgateway)
![Build Status](https://img.shields.io/github/actions/workflow/status/deus-developer/tgateway/release_pypi.yaml)

Telegram Gateway Python SDK is a lightweight and asynchronous client library designed to interface with the [Telegram Gateway API](https://core.telegram.org/gateway).

## ✨ Features

- **Send Verification Messages**: Deliver verification codes to users' phone numbers.
- **Check Delivery Status**: Verify the status of sent messages and handle callbacks.
- **Revoke Verification**: Invalidate previously sent verification messages.
- **Integrity Validation**: Ensure authenticity of incoming reports using signature validation.
- **Easy to Use**: Designed with simplicity and usability in mind.
- **Fully Asynchronous**: Built on `asyncio` for high-performance integration.

## 🏗️ Installation

Install the SDK using pip:

```bash
pip install tgateway
```

## 📚 Usage

Here's a basic example to get started with the `TelegramGateway` client:

### Check a send verification message ability

```python
import asyncio
from tgateway import TelegramGateway

async def main():
    async with TelegramGateway(access_token="<access-token>") as gateway:
        result = await gateway.check_send_ability(
            phone_number="+1234567890",
        )

        print(f"Verification ability: {result}")

asyncio.run(main())
```

### Send a verification message

```python
import asyncio
from tgateway import TelegramGateway

async def main():
    async with TelegramGateway(access_token="<access-token>") as gateway:
        result = await gateway.send_verification_message(
            phone_number="+1234567890",
            code_length=6
        )

        print(f"Verification message sent: {result}")

asyncio.run(main())
```

### Check the Status of a Verification Request

```python
import asyncio
from tgateway import TelegramGateway

async def main():
    async with TelegramGateway(access_token="<access-token>") as gateway:
        result = await gateway.check_verification_status(request_id="<request-id>")

        print(f"Verification status: {result}")

asyncio.run(main())
```

### Revoke a Verification Message

```python
import asyncio
from tgateway import TelegramGateway

async def main():
    async with TelegramGateway(access_token="<access-token>") as gateway:
        result = await gateway.revoke_verification_message(request_id="<request-id>")

        print(f"Verification revoked: {result}")

asyncio.run(main())
```

### Validate Incoming Delivery Reports

To confirm the origin and integrity of incoming reports, you can use the `validate_report_integrity` method provided by the SDK:

```python
import asyncio
from tgateway import TelegramGateway


async def main():
    async with TelegramGateway(access_token="<access-token>") as gateway:
        try:
            gateway.validate_report_integrity(
                timestamp=123456789,  # Timestamp from header
                signature="report_signature",  # Signature from header
                body=b'{}'  # Body of the report as bytes
            )
            print("Report integrity validated successfully.")
        except Exception as e:
            print(f"Validation failed: {e}")

asyncio.run(main())
```

## 🏛️ Project Structure

The project is structured for ease of use and maintainability:

```
tgateway/
├── client.py                    # Main client class.
├── constants.py                 # Constants used throughout the SDK.
├── enums.py                     # Enum definitions for API statuses.
├── exceptions.py                # Custom exception classes.
├── integrity.py                 # Integrity validation utilities.
├── methods.py                   # Implementation of Telegram Gateway API methods.
├── types.py                     # Type definitions for API responses.
```

## 🧪 Testing

Currently, the project does not have test cases but this is planned for future releases. Contributions to add tests are welcome!

## 🔗 Important Links
- **Telegram Gateway Overview**: [Telegram Gateway Overview](https://core.telegram.org/gateway)
- **API Reference**: [Gateway API Reference](https://core.telegram.org/gateway/api)
- **Verification Tutorial**: [Verification Tutorial](https://core.telegram.org/gateway/verification-tutorial)
- **Manage Your Account**: [Gateway Account](https://gateway.telegram.org/account)
- **Terms of Service**: [Gateway Terms of Service](https://telegram.org/tos/gateway)

## 📃 License

This project is licensed under the [Apache License](LICENSE).

## 🤝 Contributing

Contributions are welcome! If you'd like to contribute, please fork the repository and submit a pull request. For major changes, open an issue first to discuss what you would like to change.

1. Fork the repository.
2. Create your feature branch: `git checkout -b feature/my-new-feature`.
3. Commit your changes: `git commit -m 'Add some feature'`.
4. Push to the branch: `git push origin feature/my-new-feature`.
5. Open a pull request.

## 💬 Contact

For questions, support, or just to connect, please reach out to the project maintainers:

- **Email**: [deusdeveloper@yandex.com](mailto:deusdeveloper@yandex.com)
- **Telegram**: [@DeusDeveloper](https://t.me/DeusDeveloper)
- **Chat**: [@tgateway](https://t.me/tgateway)
- **GitHub Issues**: [GitHub Repository](https://github.com/deus-developer/tgateway/issues)

---

Enjoy using the Telegram Gateway Python SDK! 🎉
