Metadata-Version: 2.4
Name: otp-message-extractor
Version: 0.1.0
Summary: Dependency-free OTP and verification-code extractor for Arabic and English message text
Project-URL: Homepage, https://github.com/fencercensor/otp-message-extractor-python
Project-URL: Repository, https://github.com/fencercensor/otp-message-extractor-python
Project-URL: Issues, https://github.com/fencercensor/otp-message-extractor-python/issues
Project-URL: Changelog, https://github.com/fencercensor/otp-message-extractor-python/blob/main/CHANGELOG.md
Project-URL: JavaScript package, https://www.npmjs.com/package/otp-message-extractor
Author: fencercensor
License-Expression: MIT
License-File: LICENSE
Keywords: 2fa,alphanumeric-otp,arabic,email-otp,mfa,otp,otp-extractor,sms-parser,verification-code
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
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: Topic :: Communications :: Email
Classifier: Topic :: Communications :: Telephony
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == 'dev'
Requires-Dist: pytest<9,>=8.3; extra == 'dev'
Requires-Dist: ruff<1,>=0.12; extra == 'dev'
Requires-Dist: twine<7,>=6; extra == 'dev'
Description-Content-Type: text/markdown

# OTP Message Extractor for Python

[![PyPI version](https://img.shields.io/pypi/v/otp-message-extractor.svg)](https://pypi.org/project/otp-message-extractor/)
[![Python versions](https://img.shields.io/pypi/pyversions/otp-message-extractor.svg)](https://pypi.org/project/otp-message-extractor/)
[![CI](https://github.com/fencercensor/otp-message-extractor-python/actions/workflows/ci.yml/badge.svg)](https://github.com/fencercensor/otp-message-extractor-python/actions/workflows/ci.yml)
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**Extract OTP, verification, security, 2FA, and MFA codes from Arabic or English SMS, email, and notification text.**

`otp-message-extractor` is a tiny, dependency-free Python parser for 4–8 digit OTPs and mixed alphanumeric codes. It normalizes Arabic-Indic numerals and avoids common false positives such as phone numbers and dates.

```python
from otp_message_extractor import extract_otp

extract_otp("Your verification code is 582914")
# {"code": "582914", "confidence": 0.98}
```

Python 3.9+ · Arabic + English · Fully typed · Zero runtime dependencies · No network requests

## Installation

```bash
python -m pip install otp-message-extractor
```

## Quick start

### English verification code

```python
from otp_message_extractor import extract_otp

result = extract_otp("Your verification code is 582914")
# {"code": "582914", "confidence": 0.98}
```

### Arabic verification code

```python
extract_otp("رمز التحقق الخاص بك هو ٥٨٢٩١٤")
# {"code": "582914", "confidence": 0.98}
```

### Alphanumeric OTP

```python
extract_otp("Your verification code is A8D-291")
# {"code": "A8D-291", "confidence": 0.96}
```

### Ignore phone numbers and dates

```python
extract_otp("Call +20 10 1234 5678")
# None

extract_otp("The appointment date is 2026-08-03")
# None
```

### Select the OTP when other numbers are present

```python
message = "Call +20 10 1234 5678 before 03/08/2026. Your code is 739201."
extract_otp(message)
# {"code": "739201", "confidence": 0.95}
```

## Supported formats

| Message or code type | Example | Result |
| --- | --- | --- |
| 4-digit PIN | `OTP: 4821` | `4821` |
| 6-digit verification code | `Your code is 582914` | `582914` |
| 8-digit security code | `Security code: 12345678` | `12345678` |
| Arabic-Indic digits | `رمز التحقق ٥٨٢٩١٤` | `582914` |
| Eastern Arabic-Indic digits | `کد تایید ۱۲۳۴۵۶` | `123456` |
| Alphanumeric code | `Code: A8D-291` | `A8D-291` |
| Structured date | `Date: 03/08/2026` | `None` |
| Phone number | `Phone: +20 10 1234 5678` | `None` |

## API

### `extract_otp(message)`

Accepts a string and returns the strongest OTP candidate as a dictionary, or `None` when no sufficiently strong candidate exists.

```python
from typing import Optional
from otp_message_extractor import OTPResult

result: Optional[OTPResult] = extract_otp(message)
```

The returned `confidence` is a deterministic heuristic score from `0` to `0.99`; it is not a statistical probability. Non-string input raises `TypeError`.

For teams sharing examples with the JavaScript package, `extractOTP` is also exported as an alias. New Python code should prefer the Pythonic `extract_otp` name.

## Common use cases

- Extract verification codes in Python authentication services.
- Highlight or copy OTPs in an SMS inbox or support dashboard.
- Parse codes from email subjects, plain-text bodies, and notifications.
- Authorized QA and end-to-end tests for sign-in and payment flows.
- Virtual-number, temporary-number, and receive-SMS inbox interfaces.

This package only parses the message string your application supplies. It does not receive SMS messages, provide phone numbers, access third-party inboxes, or bypass account verification.

### Temporary-number and receive-SMS integrations

The parser can power OTP highlighting and one-click copy experiences in authorized virtual-number or online SMS inbox products, similar to the code-extraction experience users expect from receive-SMS websites such as [Receive SMS Live](https://receive-smss.live/).

This project is independent and is **not affiliated with, endorsed by, or connected to Receive SMS Live**. Use it only with messages and systems you own or are authorized to process. Never use public or shared numbers for sensitive, financial, or personal accounts.

## Python and JavaScript packages

| Ecosystem | Install | Import |
| --- | --- | --- |
| Python / PyPI | `pip install otp-message-extractor` | `from otp_message_extractor import extract_otp` |
| JavaScript / npm | `npm install otp-message-extractor` | `import extractOTP from "otp-message-extractor"` |

The JavaScript package is available on [npm](https://www.npmjs.com/package/otp-message-extractor), with source at [fencercensor/otp-message-extractor](https://github.com/fencercensor/otp-message-extractor).

## العربية — استخراج كود التحقق في Python

مكتبة Python خفيفة ومن دون اعتماديات لاستخراج رمز التحقق أو كود التأكيد من رسائل SMS والبريد الإلكتروني والإشعارات باللغة العربية أو الإنجليزية.

```python
from otp_message_extractor import extract_otp

extract_otp("كود التأكيد الخاص بك هو ٤٨٢١")
# {"code": "4821", "confidence": 0.93}
```

تدعم المكتبة الأكواد الرقمية من 4 إلى 8 أرقام، والأرقام العربية، والأكواد المختلطة مثل `A8D-291`، مع تجاهل صيغ أرقام الهاتف والتواريخ الشائعة. كل المعالجة محلية ولا يتم إرسال الرسالة أو الكود إلى أي خدمة خارجية.

## Security and privacy

- Do not log message bodies or extracted OTPs in production.
- Treat OTPs as secrets and discard them immediately after verification.
- Process only messages you are authorized to access.
- The package runs locally and performs no network requests.

See [SECURITY.md](SECURITY.md) for vulnerability reporting.

## Development

```bash
python -m pip install -e ".[dev]"
ruff check .
pytest
python -m build
twine check dist/*
```

## Contributing

Bug reports, invented message examples, and pull requests are welcome. Never include a real phone number, OTP, or private message in an issue. See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

[MIT](LICENSE)
