Metadata-Version: 2.4
Name: pyTelegramOIDC
Version: 1.0.0
Summary: Async Python library for Telegram OpenID Connect (OIDC) login
Home-page: https://github.com/S1qwy/pyTelegramOIDC
Author: S1qwy
Author-email: s1qwy@internet.ru
Classifier: Programming Language :: Python :: 3
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Classifier: Topic :: Internet :: WWW/HTTP :: Session
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.0
Requires-Dist: PyJWT[crypto]>=2.8.0
Requires-Dist: pydantic>=2.0.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# pyTelegramOIDC

![PyPI - Version](https://img.shields.io/pypi/v/pyTelegramOIDC?color=blue&logo=pypi&logoColor=white)
![Python Versions](https://img.shields.io/pypi/pyversions/pyTelegramOIDC?logo=python&logoColor=white)
![License](https://img.shields.io/github/license/S1qwy/pyTelegramOIDC?color=green)

**pyTelegramOIDC** — is a modern, fully asynchronous Python library for integrating the official [Telegram Login (OpenID Connect)](https://core.telegram.org/bots/telegram-login) into your web applications.

It strictly follows standard OIDC specifications, supports PKCE (Proof Key for Code Exchange), and natively extracts all user data (including phone numbers) directly from cryptographically signed ID Tokens.

## Features
- **Fully Async:** Uses `httpx` for non-blocking HTTP requests.
- **Secure:** Validates JWT signatures automatically using Telegram's official JWKS keys.
- **Pydantic Models:** Strict typing for user profiles and tokens out of the box.
- **Phone Number Support:** Easily extract requested user phone numbers.

## Installation

You can install the library via pip:

```bash
pip install pyTelegramOIDC
```
*Note: Although you install it via `pyTelegramOIDC`, the module is imported as `teleoidc` (similar to how `pyTelegramBotAPI` is imported as `telebot`).*

## Quickstart (JS Widget Flow)

If you are using the official [Telegram JS Popup Widget](https://core.telegram.org/bots/telegram-login), your frontend will receive an `id_token`. Use `teleoidc` to validate it and get the user's data safely.

```python
from teleoidc import TelegramAsyncOIDCClient

# 1. Initialize the client
client = TelegramAsyncOIDCClient(
    client_id="YOUR_BOT_ID",        # From @BotFather
    client_secret="YOUR_BOT_SECRET", # From @BotFather
    redirect_uri="https://yoursite.com/auth/callback"
)

# 2. Validate the token received from the frontend
id_token = "eyJhbGciOiJSUzI1NiIs..." # Token from Telegram JS

try:
    user = client.validate_id_token(id_token)
    
    print(f"Logged in as: {user.name} (@{user.preferred_username})")
    print(f"Telegram ID: {user.id}")
    
    if user.phone_number:
        print(f"Phone: {user.phone_number}")

except Exception as e:
    print(f"Invalid token: {e}")
```

## Manual OAuth2 Redirect Flow
If you are doing a full backend redirect instead of the JS widget, `pyTelegramOIDC` provides native methods to generate auth links and exchange codes for tokens (`get_auth_request` and `exchange_code_for_token`).

## License
MIT License
