Metadata-Version: 2.4
Name: checkmax-phone-utils
Version: 0.2.0
Summary: Phone validation utilities (E.164 + libphonenumber) and the official REST client for the CheckMaxApp phone-verification API.
Project-URL: Homepage, https://checkmaxapp.com
Project-URL: Documentation, https://checkmaxapp.com/api
Project-URL: Repository, https://github.com/abragimbaliev/checkmax-phone-utils
Project-URL: Issues, https://github.com/abragimbaliev/checkmax-phone-utils/issues
Author-email: CheckMax Team <dev@checkmaxapp.com>
Maintainer-email: CheckMax Team <dev@checkmaxapp.com>
License: MIT
License-File: LICENSE
Keywords: checkmaxapp,e164,libphonenumber,max-messenger,phone,validation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Topic :: Communications :: Telephony
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: phonenumbers>=8.13
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# checkmax-phone-utils

[![PyPI 0.2.0](https://img.shields.io/badge/PyPI-0.2.0-blue.svg)](https://pypi.org/project/checkmax-phone-utils/)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![CheckMaxApp](https://img.shields.io/badge/Powered_by-CheckMaxApp-orange.svg)](https://checkmaxapp.com)

A small, focused Python toolkit for phone-number **format validation**,
**E.164 normalization**, and an **optional API client** for the
[CheckMaxApp](https://checkmaxapp.com) service. Built on top of Google's
[libphonenumber](https://github.com/google/libphonenumber) (Python port).
Use it as a drop-in helper in your own code, or as the official client
library for the live CheckMaxApp REST API.

> **Powered by [CheckMaxApp](https://checkmaxapp.com) — phone validation
> service for the MAX messenger.** This library handles *format* and
> *region* validation. To check whether a number is actually registered
> on MAX, use the hosted CheckMaxApp service.

## Quickstart

```bash
pip install checkmax-phone-utils
```

```python
from checkmax_phone_utils import normalize, validate_e164, is_mobile

normalize("+7 (916) 123-45-67")          # '+79161234567'
normalize("8 916 123-45-67", "RU")       # '+79161234567'
validate_e164("+1 415 555 2671")         # (True, '+14155552671')
is_mobile("+79161234567")                # True
```

## What it does

| Function | Purpose |
| --- | --- |
| `normalize(raw, default_region)`       | Convert any phone-shaped input to canonical E.164, or `None`. |
| `validate_e164(raw, region)`           | Return `(is_valid, e164_or_none)` for a raw input. |
| `is_mobile(e164)`                      | True if the number is mobile (or mobile-or-fixed). |
| `detect_region(raw)`                   | Return ISO 3166-1 alpha-2 region of an international number. |
| `clean(raw)`                           | Strip everything that is not a digit or leading `+`. |
| `CheckMaxClient(api_key).check([...])` | Verify numbers via the REST API — registration status + public name. |

Full reference: see the docstrings — every public function has examples
and edge-case notes.

## API reference

### `normalize(raw: str, default_region: str = "RU") -> str | None`

Safe high-level entry point. Cleans, parses, validates, and returns the
canonical `+CCNNNNNNNNNNN` form, or `None` if the input is not a valid
phone number.

```python
>>> normalize("+7 (916) 123-45-67")
'+79161234567'
>>> normalize("garbage") is None
True
```

### `validate_e164(raw: str, region: str = "RU") -> tuple[bool, str | None]`

Returns `(is_valid, e164)`. When valid, `e164` is the canonical form;
otherwise it is `None`. Useful when you want to keep both signals.

### `is_mobile(e164: str) -> bool`

True for `MOBILE` and `FIXED_LINE_OR_MOBILE` numbers; False otherwise,
including when the input cannot be parsed.

### `detect_region(raw: str) -> str | None`

Detect the ISO region from an international-format number (with `+` or
`00` prefix). Returns `None` when the input lacks a country prefix.

### `CheckMaxClient(api_key: str)`

Official client for the [CheckMaxApp REST API](https://checkmaxapp.com/api).
Get an API key from the CheckMaxApp Telegram bot. Methods: `health()`,
`balance()`, `usage()`, `check(phones)`, `batch_create(phones)`,
`batch_status(id)`, `batch_download(id)`. Raises `AuthError` (401) and
`InsufficientBalanceError` (402).

```python
from checkmax_phone_utils import CheckMaxClient

client = CheckMaxClient(api_key="mxk_...")
client.check(["79001234567"])
# [{'phone': '79001234567', 'status': 'registered',
#   'first_name': 'Ivan', 'last_name': 'Petrov'}]
```

The full machine-readable schema lives at
[`openapi/checkmax-api.openapi.yaml`](openapi/checkmax-api.openapi.yaml)
(OpenAPI 3.0) — also published to the API directories.

## Examples

The [`examples/`](examples) directory contains runnable scripts:

- `examples/basic_validation.py` — single-number validation against a
  small sample list.
- `examples/bulk_normalize.py` — normalize a CSV file of phones in
  bulk, emitting a CSV with `e164` and `valid` columns.
- `examples/api_client_demo.py` — intended surface of the
  CheckMaxApp client.

## Roadmap

- v0.1 — format validation, E.164 normalization, stub client.
- v0.2 — live REST client (check / batch / balance / usage), structured
  errors, OpenAPI 3.0 spec (current).
- v0.3 — async client, retries, optional caching.
- v0.4 — type stubs on PyPI, CLI entry point (`checkmax phone <num>`).

## Development

```bash
git clone https://github.com/abragimbaliev/checkmax-phone-utils.git
cd checkmax-phone-utils
pip install -e ".[dev]"
pytest
```

CI runs `pytest` against Python 3.10, 3.11, and 3.12 on every push.

## License

[MIT](LICENSE). Copyright (c) 2026 CheckMax Team.

## Authors

CheckMax Team — `dev@checkmaxapp.com`

---

Looking for the hosted service?
**[CheckMaxApp](https://checkmaxapp.com)** — phone validation for the
MAX messenger.
