smstunnel 1.0.0__tar.gz

smstunnel-1.0.0/.gitignore

@@ -0,0 +1,17 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+# Never commit keys
+.env
+*.key.json
+local-test-key.json

smstunnel-1.0.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to `smstunnel` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
+
+## [1.0.0] - 2026-11-01
+
+### Added
+
+- `smstunnel.Client` with `send_sms()`, `send_verification_code()`, `get_message_status()`,
+  `get_received_messages()`, `get_devices()` and `get_usage()`, and `smstunnel.AsyncClient` with the same methods
+  as coroutines.
+- Typed, read-only responses: `SendResult`, `MessageStatus`, `ReceivedMessages` / `ReceivedMessage`,
+  `DeviceList` / `Device`, `Usage`. Times are timezone-aware `datetime` objects.
+- Exceptions: `ApiError` with the HTTP status, SMSTunnel's error code and message, and the subclasses
+  `AuthenticationError` (401), `PermissionDeniedError` (403) and `RateLimitError` (429, with `retry_after`);
+  `TransportError` when SMSTunnel cannot be reached. All extend `SmsTunnelError`.
+- A standard-library transport (no dependencies, never follows redirects), and optional httpx transports
+  (`pip install "smstunnel[httpx]"`).

smstunnel-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NARBOWEB SRL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

smstunnel-1.0.0/PKG-INFO

@@ -0,0 +1,377 @@
+Metadata-Version: 2.5
+Name: smstunnel
+Version: 1.0.0
+Summary: Python client for SMSTunnel: send texts from your own apps through your own Android phone, from your own number.
+Project-URL: Homepage, https://smstunnel.io
+Project-URL: Documentation, https://github.com/narcisbodea/smstunnel-python#readme
+Project-URL: Source, https://github.com/narcisbodea/smstunnel-python
+Project-URL: Issues, https://github.com/narcisbodea/smstunnel-python/issues
+Project-URL: Changelog, https://github.com/narcisbodea/smstunnel-python/blob/main/CHANGELOG.md
+Author-email: Narcis Bodea <contact@narboweb.ro>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: 2fa,android,otp,sms,smstunnel,text message,verification code
+Classifier: Development Status :: 5 - Production/Stable
+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.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 :: 3.15
+Classifier: Topic :: Communications :: Telephony
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.27; extra == 'httpx'
+Description-Content-Type: text/markdown
+
+# SMSTunnel for Python
+
+`smstunnel`: a small Python client for **[SMSTunnel](https://smstunnel.io)**. Send texts from your own Python apps through **your own Android phone**, from **your own number**.
+
+Your app hands the text to your SMSTunnel account and your phone sends it from its own SIM, so recipients see a number they know and can reply to. The phone is linked to your account when you sign in to the SMSTunnel app (or scan the QR code from your dashboard), and you can cut an app off at any time by deleting its API key in your dashboard.
+
+Your phone needs the SMSTunnel app from Google Play:
+
+<a href="https://play.google.com/store/apps/details?id=io.smstunnel.app"><img src="https://smstunnel.io/google-play-badge.png" alt="Get it on Google Play" height="56"></a>
+
+## Requirements
+
+- Python 3.10 or newer
+- No dependencies. [httpx](https://www.python-httpx.org) is optional (see [Your own HTTP client](#your-own-http-client)).
+
+## Installation
+
+```bash
+pip install smstunnel
+```
+
+## Get an API key
+
+1. Install the [SMSTunnel app from Google Play](https://play.google.com/store/apps/details?id=io.smstunnel.app) on your Android phone and sign in. Sign in at [smstunnel.io](https://smstunnel.io) on your computer with the same account: the phone appears under **Phones** (you can also link it with the QR code from **Phones → Add phone**).
+2. In your [SMSTunnel dashboard](https://dashboard.smstunnel.io/apps), open **Apps** → **Add an app** and create its key. The key can send texts and look up whether they went out (`sms:send` and `sms:read`).
+3. Reading received texts only works with a key you have explicitly allowed to (**Can also read received texts**, the `sms:inbox` permission, a separate opt-in per key). Syncing received texts is off by default in the app; when you turn it on, only texts that arrive from then on are synced, and the phone's existing messages are never read.
+
+Keep the key out of your code: put it in an environment variable such as `SMSTUNNEL_API_KEY`.
+
+## Usage
+
+```python
+import os
+import smstunnel
+
+client = smstunnel.Client(os.environ["SMSTUNNEL_API_KEY"])  # sk_live_...
+
+result = client.send_sms("+14155550123", "Your order #1042 has shipped.")
+
+print(result.message_id)  # keep it to look up the status later
+```
+
+### Send a text
+
+```python
+result = client.send_sms(
+    "+14155550123",               # international format
+    "See you at 10:30.",          # up to 1600 characters
+    device_id=None,               # a phone id from get_devices(), or None to let SMSTunnel pick one of yours
+    default_country_code=None,    # e.g. "+40": completes numbers given without + or 00
+)
+
+result.message_id  # str
+result.queued      # True when the phone was offline: it sends the text as soon as it is back
+result.branded     # True when the text carries a short SMSTunnel signature (plans with a free quota)
+result.remaining   # today's quota left, e.g. {"clean": 95, "total": "unlimited"} (-1 means no limit)
+```
+
+One call sends one text to one number. To text several people, call `send_sms()` once for each.
+
+### Send a sign-in or verification code
+
+```python
+client.send_verification_code("+14155550123", "Your sign-in code is 482913")
+```
+
+The text must contain the code, 4 to 10 digits standing on their own (for example `482913` or `123-456`); SMSTunnel refuses it otherwise. Codes count against a separate quota, and the text can be up to 320 characters.
+
+### Look up a status
+
+Needs a key with `sms:read`.
+
+```python
+from smstunnel import MessageStatus
+
+status = client.get_message_status(result.message_id)
+
+status.status           # "pending", "sent", "delivered" or "failed"
+status.delivery_status  # the same, or "unconfirmed": handed to the SIM but the phone got no confirmation
+status.sent_at          # a datetime (UTC), or None
+status.error_message    # why it failed, or None
+status.is_final         # True once it will not change any more
+
+if status.status == MessageStatus.FAILED:
+    ...
+```
+
+### Read received texts
+
+Needs a key you allowed to read received texts (`sms:inbox`) and syncing turned on in the app.
+
+```python
+from datetime import datetime, timedelta, timezone
+
+page = client.get_received_messages(
+    limit=20,                                            # at most 100
+    page=1,
+    since=datetime.now(timezone.utc) - timedelta(days=1),  # or an ISO 8601 string
+    phone="+14155550123",                                # only from this sender
+    device_id=None,                                      # only this phone
+)
+
+for text in page:
+    print(text.sender, text.message)  # text.received_at, text.device_name, ...
+
+page.total     # all texts that match, on every page
+page.has_more  # ask for the next page
+```
+
+### Your phones and your usage
+
+```python
+for phone in client.get_devices():
+    print(phone.name, "online" if phone.is_online else "offline")  # phone.id, phone.last_seen_at
+
+usage = client.get_usage()
+usage.plan       # e.g. "pro"
+usage.usage      # {"smsClean": 15, "smsBranded": 0, "twoFaClean": 4}
+usage.remaining  # {"smsClean": "unlimited", "twoFaClean": 96}
+```
+
+Every response object is a read-only dataclass with a `raw` field, the whole answer, for fields this version does not map yet. The package ships type hints (`py.typed`).
+
+### Async
+
+`smstunnel.AsyncClient` has the same methods, as coroutines:
+
+```python
+import asyncio
+import os
+
+import smstunnel
+
+
+async def main() -> None:
+    async with smstunnel.AsyncClient(os.environ["SMSTUNNEL_API_KEY"]) as client:
+        await client.send_sms("+14155550123", "Your table is ready.")
+
+
+asyncio.run(main())
+```
+
+It sends through httpx when httpx is installed (`pip install "smstunnel[httpx]"`); otherwise it runs the standard-library transport in a worker thread.
+
+## Errors
+
+Every call raises a `smstunnel.SmsTunnelError` when it does not go through:
+
+| Exception | When |
+| --- | --- |
+| `AuthenticationError` (401) | The API key is wrong, was deleted, or its account is suspended. |
+| `PermissionDeniedError` (403) | The key lacks a permission (`error_code` is `PERMISSION_REQUIRED`, `permission` names it, e.g. `sms:inbox`), or the plan does not include the feature. |
+| `RateLimitError` (429) | Too many requests. `retry_after` gives the seconds to wait, when SMSTunnel says. |
+| `ApiError` | Any other error answer: 400 (a number it cannot read, a verification text without a code), 404 (no such message), 5xx. The three above extend it. |
+| `TransportError` | SMSTunnel could not be reached (DNS, TLS, timeout). |
+
+```python
+import logging
+import time
+
+from smstunnel import ApiError, RateLimitError, TransportError
+
+try:
+    client.send_sms("+14155550123", "Your table is ready.")
+except RateLimitError as error:
+    time.sleep(error.retry_after or 30)  # then try again
+except ApiError as error:
+    logging.warning("SMSTunnel %s %s: %s", error.status_code, error.error_code or "-", error.message)
+except TransportError:
+    ...  # network problem: try again later
+```
+
+`message` (also `str(error)`) is SMSTunnel's own explanation, `status_code` the HTTP status, `body` the decoded answer. An empty number or text raises `ValueError` before anything is sent.
+
+## Django
+
+Read the key from the environment in `settings.py`:
+
+```python
+# settings.py
+import os
+
+SMSTUNNEL_API_KEY = os.environ.get("SMSTUNNEL_API_KEY", "")
+```
+
+Make one client for the whole app, and send once the order is saved:
+
+```python
+# shop/sms.py
+from functools import cache
+
+import smstunnel
+from django.conf import settings
+
+
+@cache
+def sms() -> smstunnel.Client:
+    return smstunnel.Client(settings.SMSTUNNEL_API_KEY)
+```
+
+```python
+# shop/views.py
+import logging
+
+from django.db import transaction
+from django.shortcuts import get_object_or_404, redirect
+
+from smstunnel import SmsTunnelError
+
+from .models import Order
+from .sms import sms
+
+log = logging.getLogger(__name__)
+
+
+def text_customer(order: Order) -> None:
+    try:
+        sms().send_sms(order.phone, f"Your order #{order.pk} has shipped.")
+    except SmsTunnelError:
+        log.exception("The shipping text for order %s did not go out", order.pk)
+
+
+def mark_shipped(request, pk):
+    order = get_object_or_404(Order, pk=pk)
+    order.status = "shipped"
+    order.save()
+    transaction.on_commit(lambda: text_customer(order))
+    return redirect("order-detail", pk=pk)
+```
+
+To keep requests fast, you can call `text_customer()` from a background task (Celery, RQ, Django's tasks) instead.
+
+## Flask
+
+```python
+import os
+
+from flask import Flask, abort, request
+from smstunnel import Client, SmsTunnelError
+
+app = Flask(__name__)
+app.config["SMSTUNNEL_API_KEY"] = os.environ["SMSTUNNEL_API_KEY"]
+sms = Client(app.config["SMSTUNNEL_API_KEY"])
+
+
+@app.post("/appointments/<int:appointment_id>/remind")
+def remind(appointment_id: int):
+    phone = request.form.get("phone", "")
+    if not phone.startswith("+"):
+        abort(400, "Give the number in international format, e.g. +14155550123.")
+    try:
+        result = sms.send_sms(phone, "Reminder: your appointment is tomorrow at 10:30.")
+    except SmsTunnelError as error:
+        app.logger.warning("SMSTunnel: %s", error)
+        return {"sent": False}, 502
+    return {"sent": True, "messageId": result.message_id}
+```
+
+## Your own HTTP client
+
+The default transport uses only the standard library (`urllib.request`), a 30-second timeout and never follows redirects, so the API key is never sent to another address. It uses the proxy from the `HTTPS_PROXY` environment variable. Change the timeout, or trust your own certificate authority:
+
+```python
+import ssl
+
+from smstunnel import Client
+from smstunnel.transport import UrllibTransport
+
+client = Client(api_key, timeout=10, transport=UrllibTransport(ssl_context=ssl.create_default_context(cafile="ca.pem")))
+```
+
+Or send through httpx, so SMSTunnel calls share your app's HTTP setup:
+
+```python
+import httpx
+from smstunnel import AsyncClient, Client
+from smstunnel.transport import AsyncHttpxTransport, HttpxTransport
+
+client = Client(api_key, transport=HttpxTransport(httpx.Client(proxy="http://proxy.internal:3128")))
+async_client = AsyncClient(api_key, transport=AsyncHttpxTransport(httpx.AsyncClient()))
+```
+
+In your own tests, give the client an object with a `send(request) -> HttpResponse` method (see `smstunnel.transport.Transport`) to answer without a network, or mock `smstunnel.Client`.
+
+`Client(api_key, "https://your-own-host")` points the client at a self-hosted SMSTunnel; the default is `https://smstunnel.io`.
+
+## Notes and limits
+
+- **Rate limit**: sending allows 30 requests a minute.
+- **Length**: up to 1600 characters (10 joined SMS); verification codes up to 320.
+- **Numbers**: use the international format (`+14155550123`). For local numbers, pass `default_country_code`: it always takes precedence (`+49`, `49` and `0049` all work).
+- **Offline phone**: the text waits on your account (`queued` is `True`) and goes out when the phone is back online.
+
+## Build it with an AI assistant
+
+Paste this into Claude, ChatGPT, Cursor or Copilot, and replace the part in brackets. Never paste your real API key into a prompt.
+
+```text
+I want my Python app to send texts with SMSTunnel. SMSTunnel sends each text from my own Android phone, from my own number: the phone runs the SMSTunnel app and is linked to my SMSTunnel account.
+
+Use the SMSTunnel package: `pip install smstunnel`, then `client = smstunnel.Client(os.environ["SMSTUNNEL_API_KEY"])`.
+API facts:
+- client.send_sms(to, message, device_id=None, default_country_code=None) calls POST https://smstunnel.io/api/v1/sms/send with the header X-API-Key and the JSON body {"to", "message", "deviceId"?, "defaultCountryCode"?}. It returns message_id and queued.
+- One recipient per call. To text several people, call it once per number.
+- client.send_verification_code(...) (POST /api/v1/sms/send-2fa) is only for sign-in codes: the text must contain a code of 4 to 10 digits standing on its own (e.g. 482913 or 123-456), at most 320 characters; it uses a separate quota.
+- Numbers in international format (+14155550123). default_country_code (e.g. "+40") completes numbers written without + or 00.
+- Limits: 30 send requests a minute, 1600 characters a text.
+- Errors: 401 AuthenticationError (bad key), 403 PermissionDeniedError (missing permission or plan; error_code such as PERMISSION_REQUIRED), 429 RateLimitError (retry_after seconds), other 4xx/5xx ApiError, TransportError when SMSTunnel can't be reached.
+- If the phone is offline, the text waits on the account (queued is True) and goes out when the phone is back.
+
+What I want: [describe what should send a text, to whom, and when]
+
+Rules:
+- Read the API key from an environment variable or the platform's secret store. Never put it in source code, in the repository or in client-side code.
+- Validate phone numbers before sending, and handle every error above: log it clearly, don't retry 401/403, wait and retry 429.
+- Only send texts people expect (alerts to myself, reminders, sign-in codes, order updates).
+```
+
+## Responsible use
+
+Send only texts that people expect from you: alerts to yourself, appointment reminders, sign-in codes, order updates. Unsolicited messages from a personal SIM break most carriers' terms of service. Please make sure your usage complies with your carrier's terms and with local regulations (in the EU, that includes GDPR and ePrivacy rules on electronic communications).
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e . --group dev   # pip 25.1 or newer
+pytest                         # unit tests
+ruff check . && ruff format --check .
+mypy                           # strict
+```
+
+The end-to-end tests run only against a test server, never production. They read the server address and a test key from a JSON file (`{"serverUrl": "http://127.0.0.1:3101", "apiKey": "...", "deviceId": "..."}`) and, when `SMSTUNNEL_E2E_MONGO_URL` is set, check each text in the server's database:
+
+```bash
+pip install --group e2e
+SMSTUNNEL_E2E_KEY_FILE=/path/to/test-key.json SMSTUNNEL_E2E_MONGO_URL=mongodb://127.0.0.1:27018/smstunnel_app_dev pytest tests/e2e
+```
+
+## Changelog
+
+See [CHANGELOG.md](https://github.com/narcisbodea/smstunnel-python/blob/main/CHANGELOG.md).
+
+## License
+
+MIT, © NARBOWEB SRL. See [LICENSE](https://github.com/narcisbodea/smstunnel-python/blob/main/LICENSE).