texto-sdk 1.0.0__tar.gz

texto_sdk-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,23 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: pip install build pytest responses
+      - run: pip install -e .
+      - run: pytest
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

texto_sdk-1.0.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.coverage
+.env
+.DS_Store

texto_sdk-1.0.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to `texto-sdk` are documented here. This project follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-01-01
+
+### Added
+
+- First public release.
+- Client covering messaging, inbox, opt-outs, credits, accounts, users, access,
+  API keys, numbers, webhooks and reporting.
+- Typed exceptions, timeouts, and automatic retries for idempotent requests.
+- HMAC-SHA256 webhook signature verification helpers.

texto_sdk-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Floop Pty Ltd trading as Texto
+
+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.

texto_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.5
+Name: texto-sdk
+Version: 1.0.0
+Summary: Official Python SDK for the Texto SMS API
+Project-URL: Homepage, https://texto.com.au
+Project-URL: Documentation, https://texto.com.au/developers
+Project-URL: Source, https://github.com/textosms/texto-python
+Project-URL: Changelog, https://github.com/textosms/texto-python/blob/main/CHANGELOG.md
+Author-email: "Texto (Floop Pty Ltd)" <support@texto.com.au>
+License: MIT
+License-File: LICENSE
+Keywords: australia,messaging,sms,texto
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.25
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: responses>=0.23; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Texto SMS — Python SDK
+
+Official Python SDK for the [Texto](https://texto.com.au) SMS API. Send SMS to
+Australian and New Zealand numbers, read replies, and manage sub-accounts,
+numbers, credits, API keys, webhooks and reporting.
+
+## Install
+
+```bash
+pip install texto-sdk
+```
+
+Requires Python 3.8 or newer.
+
+## Quick start
+
+```python
+import os
+from texto import Texto
+
+texto = Texto(api_key=os.environ["TEXTO_API_KEY"])
+
+result = texto.send(to="+61400000000", message="Your booking is confirmed for 2pm.")
+print(result["message_id"], result["credits_used"])
+```
+
+## Configuration
+
+```python
+texto = Texto(
+    api_key="txt_...",
+    timeout=30.0,      # seconds
+    max_retries=2,     # retries for idempotent requests
+)
+```
+
+`base_url` can be overridden, but only to point tests at a mock server or a
+corporate proxy. The production API is always `https://api.texto.com.au`.
+
+## Sending
+
+```python
+texto.send(
+    to="0400000000",
+    message="Hi Sam, your order has shipped.",
+    sender="TEXTO",        # optional dedicated number or approved Sender ID
+    link_tracking=True,     # optional per-message override
+    campaign="Shipping",    # optional campaign name
+)
+
+texto.send_batch(
+    message="Hi {name}, your appointment is {time}.",
+    recipients=[
+        {"phone": "0400000001", "merge_data": {"name": "Sam", "time": "2pm"}},
+        {"phone": "0400000002", "merge_data": {"name": "Alex", "time": "3pm"}},
+    ],
+)
+
+payload = texto.get_message(result["message_id"])
+print(payload["delivery_receipt"])
+```
+
+## Replies and opt-outs
+
+```python
+inbox = texto.inbox(limit=50)
+optouts = texto.optouts()
+```
+
+## Credits, accounts and numbers
+
+```python
+texto.balance()
+texto.list_accounts()
+sub = texto.create_account(business_name="Acme Pty Ltd", email="ops@acme.com.au")
+texto.allocate_credits(sub["account_id"], 500)
+texto.available_numbers(country="AU")
+texto.purchase_number(label="Support line")
+```
+
+Account, team and group endpoints require account hierarchy to be enabled on
+your Texto account.
+
+## Reporting
+
+```python
+texto.report(from_="2026-01-01", to="2026-01-31", direction="outbound")
+texto.group_report(from_="2026-01-01")
+```
+
+## Webhooks
+
+```python
+from flask import Flask, request
+from texto import parse_webhook_event, is_inbound_event
+
+app = Flask(__name__)
+
+@app.post("/texto-webhook")
+def texto_webhook():
+    event = parse_webhook_event(
+        request.get_data(),                      # raw body, not re-serialised
+        request.headers.get("X-Texto-Signature"),
+        os.environ["TEXTO_WEBHOOK_SECRET"],
+    )
+    if is_inbound_event(event):
+        print("Reply from", event["from"], event["body"])
+    else:
+        print("Delivery status", event["delivery_receipt"])
+    return "", 200
+```
+
+## Errors
+
+```python
+from texto import TextoInsufficientCreditsError, TextoRateLimitError
+
+try:
+    texto.send(to="0400000000", message="Hi")
+except TextoInsufficientCreditsError as err:
+    print("Top up:", err.credits_required)
+except TextoRateLimitError as err:
+    print("Retry after", err.retry_after)
+```
+
+Every API error subclasses `TextoApiError` with `status`, `code` and `body`.
+Network failures and timeouts raise `TextoConnectionError`.
+
+## Support
+
+- API reference: https://texto.com.au/developers
+- Email: support@texto.com.au
+
+## License
+
+MIT © Floop Pty Ltd trading as Texto

texto_sdk-1.0.0/README.md

@@ -0,0 +1,136 @@
+# Texto SMS — Python SDK
+
+Official Python SDK for the [Texto](https://texto.com.au) SMS API. Send SMS to
+Australian and New Zealand numbers, read replies, and manage sub-accounts,
+numbers, credits, API keys, webhooks and reporting.
+
+## Install
+
+```bash
+pip install texto-sdk
+```
+
+Requires Python 3.8 or newer.
+
+## Quick start
+
+```python
+import os
+from texto import Texto
+
+texto = Texto(api_key=os.environ["TEXTO_API_KEY"])
+
+result = texto.send(to="+61400000000", message="Your booking is confirmed for 2pm.")
+print(result["message_id"], result["credits_used"])
+```
+
+## Configuration
+
+```python
+texto = Texto(
+    api_key="txt_...",
+    timeout=30.0,      # seconds
+    max_retries=2,     # retries for idempotent requests
+)
+```
+
+`base_url` can be overridden, but only to point tests at a mock server or a
+corporate proxy. The production API is always `https://api.texto.com.au`.
+
+## Sending
+
+```python
+texto.send(
+    to="0400000000",
+    message="Hi Sam, your order has shipped.",
+    sender="TEXTO",        # optional dedicated number or approved Sender ID
+    link_tracking=True,     # optional per-message override
+    campaign="Shipping",    # optional campaign name
+)
+
+texto.send_batch(
+    message="Hi {name}, your appointment is {time}.",
+    recipients=[
+        {"phone": "0400000001", "merge_data": {"name": "Sam", "time": "2pm"}},
+        {"phone": "0400000002", "merge_data": {"name": "Alex", "time": "3pm"}},
+    ],
+)
+
+payload = texto.get_message(result["message_id"])
+print(payload["delivery_receipt"])
+```
+
+## Replies and opt-outs
+
+```python
+inbox = texto.inbox(limit=50)
+optouts = texto.optouts()
+```
+
+## Credits, accounts and numbers
+
+```python
+texto.balance()
+texto.list_accounts()
+sub = texto.create_account(business_name="Acme Pty Ltd", email="ops@acme.com.au")
+texto.allocate_credits(sub["account_id"], 500)
+texto.available_numbers(country="AU")
+texto.purchase_number(label="Support line")
+```
+
+Account, team and group endpoints require account hierarchy to be enabled on
+your Texto account.
+
+## Reporting
+
+```python
+texto.report(from_="2026-01-01", to="2026-01-31", direction="outbound")
+texto.group_report(from_="2026-01-01")
+```
+
+## Webhooks
+
+```python
+from flask import Flask, request
+from texto import parse_webhook_event, is_inbound_event
+
+app = Flask(__name__)
+
+@app.post("/texto-webhook")
+def texto_webhook():
+    event = parse_webhook_event(
+        request.get_data(),                      # raw body, not re-serialised
+        request.headers.get("X-Texto-Signature"),
+        os.environ["TEXTO_WEBHOOK_SECRET"],
+    )
+    if is_inbound_event(event):
+        print("Reply from", event["from"], event["body"])
+    else:
+        print("Delivery status", event["delivery_receipt"])
+    return "", 200
+```
+
+## Errors
+
+```python
+from texto import TextoInsufficientCreditsError, TextoRateLimitError
+
+try:
+    texto.send(to="0400000000", message="Hi")
+except TextoInsufficientCreditsError as err:
+    print("Top up:", err.credits_required)
+except TextoRateLimitError as err:
+    print("Retry after", err.retry_after)
+```
+
+Every API error subclasses `TextoApiError` with `status`, `code` and `body`.
+Network failures and timeouts raise `TextoConnectionError`.
+
+## Support
+
+- API reference: https://texto.com.au/developers
+- Email: support@texto.com.au
+
+## License
+
+MIT © Floop Pty Ltd trading as Texto

texto_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "texto-sdk"
+version = "1.0.0"
+description = "Official Python SDK for the Texto SMS API"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Texto (Floop Pty Ltd)", email = "support@texto.com.au" }]
+keywords = ["sms", "texto", "messaging", "australia"]
+dependencies = ["requests>=2.25"]
+
+[project.urls]
+Homepage = "https://texto.com.au"
+Documentation = "https://texto.com.au/developers"
+Source = "https://github.com/textosms/texto-python"
+Changelog = "https://github.com/textosms/texto-python/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "responses>=0.23"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["texto"]

texto_sdk-1.0.0/tests/test_client.py

@@ -0,0 +1,86 @@
+import hashlib
+import hmac
+import json
+
+import pytest
+import responses
+
+from texto import (
+    Texto,
+    TextoAuthenticationError,
+    TextoInsufficientCreditsError,
+    verify_webhook_signature,
+)
+
+BASE = "https://api.texto.com.au"
+
+
+@responses.activate
+def test_send_uses_bearer_auth_and_snake_case_body():
+    responses.add(responses.POST, f"{BASE}/send", json={"message_id": "m1", "credits_used": 1})
+    texto = Texto(api_key="txt_test")
+
+    result = texto.send(to="+61400000000", message="Hello", link_tracking=True)
+
+    assert result["message_id"] == "m1"
+    request = responses.calls[0].request
+    assert request.headers["Authorization"] == "Bearer txt_test"
+    assert json.loads(request.body) == {
+        "to": "+61400000000",
+        "message": "Hello",
+        "link_tracking": True,
+    }
+
+
+@responses.activate
+def test_report_filters_become_query_params():
+    responses.add(responses.GET, f"{BASE}/report", json={"summary": {}})
+    Texto(api_key="txt_test").report(from_="2026-01-01", direction="outbound")
+
+    url = responses.calls[0].request.url
+    assert "from=2026-01-01" in url and "direction=outbound" in url
+
+
+@responses.activate
+def test_authentication_error():
+    responses.add(responses.GET, f"{BASE}/balance", json={"error": "Invalid API key"}, status=401)
+    with pytest.raises(TextoAuthenticationError):
+        Texto(api_key="txt_test").balance()
+
+
+@responses.activate
+def test_insufficient_credits_exposes_details():
+    responses.add(
+        responses.POST,
+        f"{BASE}/send",
+        json={"error": "Insufficient credits", "credits_required": 5, "credits_available": 1},
+        status=402,
+    )
+    with pytest.raises(TextoInsufficientCreditsError) as exc:
+        Texto(api_key="txt_test").send(to="0400000000", message="hi")
+    assert exc.value.credits_required == 5
+
+
+@responses.activate
+def test_retries_retryable_get():
+    responses.add(responses.GET, f"{BASE}/balance", json={"error": "boom"}, status=503)
+    responses.add(responses.GET, f"{BASE}/balance", json={"credits": 10})
+
+    assert Texto(api_key="txt_test", max_retries=1).balance() == 10
+    assert len(responses.calls) == 2
+
+
+@responses.activate
+def test_does_not_retry_post():
+    responses.add(responses.POST, f"{BASE}/send", json={"error": "boom"}, status=503)
+    with pytest.raises(Exception):
+        Texto(api_key="txt_test").send(to="0400000000", message="hi")
+    assert len(responses.calls) == 1
+
+
+def test_webhook_signature():
+    body = json.dumps({"event": "message.inbound"})
+    sig = "sha256=" + hmac.new(b"secret", body.encode(), hashlib.sha256).hexdigest()
+    assert verify_webhook_signature(body, sig, "secret") is True
+    assert verify_webhook_signature(body, sig, "other") is False
+    assert verify_webhook_signature(body, None, "secret") is False

texto_sdk-1.0.0/texto/__init__.py

@@ -0,0 +1,36 @@
+"""Official Python SDK for the Texto SMS API."""
+
+from .client import Texto
+from .errors import (
+    TextoApiError,
+    TextoAuthenticationError,
+    TextoConnectionError,
+    TextoError,
+    TextoInsufficientCreditsError,
+    TextoInvalidRequestError,
+    TextoNotFoundError,
+    TextoPermissionError,
+    TextoRateLimitError,
+    TextoServerError,
+)
+from .webhooks import is_inbound_event, parse_webhook_event, verify_webhook_signature
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "Texto",
+    "TextoError",
+    "TextoApiError",
+    "TextoAuthenticationError",
+    "TextoPermissionError",
+    "TextoInvalidRequestError",
+    "TextoInsufficientCreditsError",
+    "TextoNotFoundError",
+    "TextoRateLimitError",
+    "TextoServerError",
+    "TextoConnectionError",
+    "verify_webhook_signature",
+    "parse_webhook_event",
+    "is_inbound_event",
+    "__version__",
+]

texto_sdk-1.0.0/texto/client.py

@@ -0,0 +1,455 @@
+"""Client for the Texto SMS API."""
+
+import time
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+import requests
+
+from .errors import TextoConnectionError, error_from_response
+
+DEFAULT_BASE_URL = "https://api.texto.com.au"
+RETRYABLE_STATUSES = {408, 409, 429, 500, 502, 503, 504}
+VERSION = "1.0.0"
+
+JSON = Dict[str, Any]
+
+
+def _clean(data: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in data.items() if v is not None}
+
+
+class Texto:
+    """Client for the Texto SMS API.
+
+    >>> texto = Texto(api_key="txt_...")
+    >>> texto.send(to="+61400000000", message="Hello")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        """
+        :param api_key: Your Texto API key, beginning ``txt_``.
+        :param base_url: Only override to point at a mock server or corporate
+            proxy during testing. Production is always the Texto API.
+        """
+        if not api_key:
+            raise ValueError("A Texto API key is required.")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.session = session or requests.Session()
+
+    # ── transport ───────────────────────────────────────────────────
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        json_body: Optional[Any] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        """Perform a raw request. Exposed for endpoints not yet wrapped."""
+        url = self.base_url + path
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": f"texto-python/{VERSION}",
+        }
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        idempotent = method in ("GET", "PUT", "DELETE") or idempotency_key
+        retries = self.max_retries if idempotent else 0
+
+        last_error: Optional[Exception] = None
+        for attempt in range(retries + 1):
+            if attempt:
+                time.sleep(min(2**attempt * 0.25, 4.0))
+            try:
+                response = self.session.request(
+                    method,
+                    url,
+                    params=_clean(params or {}) or None,
+                    json=json_body,
+                    headers=headers,
+                    timeout=self.timeout,
+                )
+            except requests.RequestException as exc:
+                last_error = TextoConnectionError(f"Request to {path} failed: {exc}")
+                if attempt < retries:
+                    continue
+                raise last_error from exc
+
+            try:
+                body = response.json() if response.content else None
+            except ValueError:
+                body = {"error": response.text}
+
+            if response.ok:
+                return body
+
+            if response.status_code in RETRYABLE_STATUSES and attempt < retries:
+                last_error = error_from_response(response.status_code, body)
+                continue
+
+            retry_after = response.headers.get("Retry-After")
+            raise error_from_response(
+                response.status_code,
+                body,
+                response.headers.get("X-Request-Id"),
+                float(retry_after) if retry_after and retry_after.isdigit() else None,
+            )
+
+        raise last_error or TextoConnectionError(f"Request to {path} failed")
+
+    # ── status ──────────────────────────────────────────────────────
+
+    def status(self) -> JSON:
+        """Public health check. Does not consume credits."""
+        return self.request("GET", "/status")
+
+    # ── messaging ───────────────────────────────────────────────────
+
+    def send(
+        self,
+        to: str,
+        message: str,
+        sender: Optional[str] = None,
+        link_tracking: Optional[bool] = None,
+        campaign: Optional[str] = None,
+    ) -> JSON:
+        """Send a single SMS."""
+        return self.request(
+            "POST",
+            "/send",
+            json_body=_clean(
+                {
+                    "to": to,
+                    "message": message,
+                    "sender": sender,
+                    "link_tracking": link_tracking,
+                    "campaign": campaign,
+                }
+            ),
+        )
+
+    def send_batch(
+        self,
+        recipients: Sequence[Union[str, Dict[str, Any]]],
+        message: str,
+        sender: Optional[str] = None,
+        link_tracking: Optional[bool] = None,
+        campaign: Optional[str] = None,
+    ) -> JSON:
+        """Send one message to up to 1,000 recipients, with optional merge data."""
+        return self.request(
+            "POST",
+            "/send-batch",
+            json_body=_clean(
+                {
+                    "recipients": list(recipients),
+                    "message": message,
+                    "sender": sender,
+                    "link_tracking": link_tracking,
+                    "campaign": campaign,
+                }
+            ),
+        )
+
+    def get_message(self, message_id: str) -> JSON:
+        """Fetch a message and its delivery receipt by id or idempotency key."""
+        return self.request("GET", f"/message/{message_id}")
+
+    def get_campaign(self, campaign_id: str, limit: Optional[int] = None, offset: Optional[int] = None) -> JSON:
+        """Fetch a campaign with its per-message results."""
+        return self.request("GET", f"/campaign/{campaign_id}", params={"limit": limit, "offset": offset})
+
+    # ── inbox and opt-outs ──────────────────────────────────────────
+
+    def inbox(
+        self,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+        from_: Optional[str] = None,
+        date_from: Optional[str] = None,
+        date_to: Optional[str] = None,
+    ) -> JSON:
+        """List inbound (reply) messages."""
+        return self.request(
+            "GET",
+            "/inbox",
+            params={
+                "limit": limit,
+                "offset": offset,
+                "from": from_,
+                "date_from": date_from,
+                "date_to": date_to,
+            },
+        )
+
+    def optouts(self) -> List[JSON]:
+        """List numbers that have opted out, including global opt-outs."""
+        return self.request("GET", "/optouts")["optouts"]
+
+    # ── credits ─────────────────────────────────────────────────────
+
+    def balance(self) -> int:
+        """Current credit balance for the calling account."""
+        return self.request("GET", "/balance")["credits"]
+
+    def account_balance(self, account_id: str) -> int:
+        """Credit balance for a sub-account."""
+        return self.request("GET", f"/account/{account_id}/balance")["credits"]
+
+    def allocate_credits(self, account_id: str, amount: int) -> JSON:
+        """Move credits from the calling account down to a sub-account."""
+        return self.request("POST", f"/account/{account_id}/credits/allocate", json_body={"amount": amount})
+
+    def recall_credits(self, account_id: str, amount: int) -> JSON:
+        """Pull credits back from a sub-account."""
+        return self.request("POST", f"/account/{account_id}/credits/recall", json_body={"amount": amount})
+
+    # ── accounts ────────────────────────────────────────────────────
+
+    def list_accounts(self) -> List[JSON]:
+        """List the calling account and its sub-accounts."""
+        return self.request("GET", "/accounts")["accounts"]
+
+    def create_account(
+        self,
+        business_name: str,
+        email: Optional[str] = None,
+        daily_limit: Optional[int] = None,
+        managed_by_parent: Optional[bool] = None,
+        team_access_from_parent: Optional[bool] = None,
+        optout_exempt: Optional[bool] = None,
+        seed_credits: Optional[int] = None,
+        inherit_parent_senders: Optional[bool] = None,
+    ) -> JSON:
+        """Create a sub-account. ``email`` is required unless managed by parent."""
+        return self.request(
+            "POST",
+            "/accounts",
+            json_body=_clean(
+                {
+                    "business_name": business_name,
+                    "email": email,
+                    "daily_limit": daily_limit,
+                    "managed_by_parent": managed_by_parent,
+                    "team_access_from_parent": team_access_from_parent,
+                    "optout_exempt": optout_exempt,
+                    "seed_credits": seed_credits,
+                    "inherit_parent_senders": inherit_parent_senders,
+                }
+            ),
+        )
+
+    def get_account(self, account_id: str) -> JSON:
+        """Fetch full detail for an account."""
+        return self.request("GET", f"/account/{account_id}")["account"]
+
+    def update_account(
+        self,
+        account_id: str,
+        business_name: Optional[str] = None,
+        daily_limit: Optional[int] = None,
+        optout_exempt: Optional[bool] = None,
+        team_access_from_parent: Optional[bool] = None,
+        inherit_parent_senders: Optional[bool] = None,
+    ) -> JSON:
+        """Update a sub-account."""
+        return self.request(
+            "PATCH",
+            f"/account/{account_id}",
+            json_body=_clean(
+                {
+                    "business_name": business_name,
+                    "daily_limit": daily_limit,
+                    "optout_exempt": optout_exempt,
+                    "team_access_from_parent": team_access_from_parent,
+                    "inherit_parent_senders": inherit_parent_senders,
+                }
+            ),
+        )
+
+    def delete_account(self, account_id: str) -> JSON:
+        """Schedule a sub-account for deletion."""
+        return self.request("DELETE", f"/account/{account_id}")
+
+    # ── users and access ────────────────────────────────────────────
+
+    def list_team(self) -> List[JSON]:
+        """Team members on the calling account."""
+        return self.request("GET", "/team")["users"]
+
+    def list_account_users(self, account_id: str) -> List[JSON]:
+        """Team members on a specific account, including inherited ones."""
+        return self.request("GET", f"/account/{account_id}/users")["users"]
+
+    def invite_user(
+        self,
+        account_id: str,
+        email: str,
+        name: Optional[str] = None,
+        can_send: Optional[bool] = None,
+        can_billing: Optional[bool] = None,
+    ) -> JSON:
+        """Invite a person to an account."""
+        return self.request(
+            "POST",
+            f"/account/{account_id}/users",
+            json_body=_clean({"email": email, "name": name, "can_send": can_send, "can_billing": can_billing}),
+        )
+
+    def remove_user(self, account_id: str, member_id: str) -> JSON:
+        """Remove a team member using the row id from the users list."""
+        return self.request("DELETE", f"/account/{account_id}/users/{member_id}")
+
+    def get_access(self, account_id: str) -> JSON:
+        """Read parent-management and inherited-team settings."""
+        return self.request("GET", f"/account/{account_id}/access")
+
+    def set_access(
+        self,
+        account_id: str,
+        managed_by_parent: Optional[bool] = None,
+        team_access_from_parent: Optional[bool] = None,
+    ) -> JSON:
+        """Update parent-management and inherited-team settings."""
+        return self.request(
+            "PUT",
+            f"/account/{account_id}/access",
+            json_body=_clean(
+                {
+                    "managed_by_parent": managed_by_parent,
+                    "team_access_from_parent": team_access_from_parent,
+                }
+            ),
+        )
+
+    # ── API keys ────────────────────────────────────────────────────
+
+    def list_keys(self, account_id: str) -> List[JSON]:
+        """List API keys on an account. Key values are never returned."""
+        return self.request("GET", f"/account/{account_id}/keys")["keys"]
+
+    def create_key(self, account_id: str, name: str) -> JSON:
+        """Create an API key. The full value is returned once — store it securely."""
+        return self.request("POST", f"/account/{account_id}/key", json_body={"name": name})
+
+    def revoke_key(self, account_id: str, key_id: str) -> JSON:
+        """Revoke an API key."""
+        return self.request("DELETE", f"/account/{account_id}/key/{key_id}")
+
+    # ── numbers ─────────────────────────────────────────────────────
+
+    def list_numbers(self) -> List[JSON]:
+        """Numbers owned by the calling account."""
+        return self.request("GET", "/numbers")["numbers"]
+
+    def list_group_numbers(self) -> List[JSON]:
+        """Numbers across the calling account and all its sub-accounts."""
+        return self.request("GET", "/numbers/group")["numbers"]
+
+    def list_account_numbers(self, account_id: str) -> List[JSON]:
+        """Numbers assigned to a specific account."""
+        return self.request("GET", f"/account/{account_id}/numbers")["numbers"]
+
+    def available_numbers(
+        self,
+        country: Optional[str] = None,
+        limit: Optional[int] = None,
+        offset: Optional[int] = None,
+    ) -> JSON:
+        """Numbers currently available to purchase."""
+        return self.request("GET", "/numbers/available", params={"country": country, "limit": limit, "offset": offset})
+
+    def purchase_number(
+        self,
+        number: Optional[str] = None,
+        label: Optional[str] = None,
+        country: Optional[str] = None,
+    ) -> JSON:
+        """Purchase a dedicated number. Charges the card saved on the account."""
+        return self.request(
+            "POST",
+            "/numbers/purchase",
+            json_body=_clean({"number": number, "label": label, "country": country}),
+        )
+
+    def assign_numbers(self, account_id: str, numbers: Union[str, Sequence[str]]) -> JSON:
+        """Assign parent-owned numbers to a sub-account."""
+        return self.request("POST", f"/account/{account_id}/numbers/assign", json_body={"numbers": numbers})
+
+    def recall_numbers(self, account_id: str, numbers: Union[str, Sequence[str]]) -> JSON:
+        """Recall numbers from a sub-account."""
+        return self.request("POST", f"/account/{account_id}/numbers/recall", json_body={"numbers": numbers})
+
+    # ── webhooks ────────────────────────────────────────────────────
+
+    def get_webhooks(self) -> JSON:
+        """Read the configured delivery receipt and inbound webhooks."""
+        return self.request("GET", "/webhooks")
+
+    def set_delivery_webhook(self, url: str, enabled: Optional[bool] = None) -> JSON:
+        """Create or update the delivery receipt webhook."""
+        return self.request("PUT", "/webhooks/delivery", json_body=_clean({"url": url, "enabled": enabled}))[
+            "delivery_receipt"
+        ]
+
+    def set_inbound_webhook(self, url: str, enabled: Optional[bool] = None) -> JSON:
+        """Create or update the inbound message webhook."""
+        return self.request("PUT", "/webhooks/inbound", json_body=_clean({"url": url, "enabled": enabled}))["inbound"]
+
+    def rotate_delivery_secret(self) -> str:
+        """Rotate the delivery receipt signing secret. Returned once."""
+        return self.request("POST", "/webhooks/delivery")["secret"]
+
+    def rotate_inbound_secret(self) -> str:
+        """Rotate the inbound signing secret. Returned once."""
+        return self.request("POST", "/webhooks/inbound")["secret"]
+
+    # ── reporting ───────────────────────────────────────────────────
+
+    def report(
+        self,
+        from_: Optional[str] = None,
+        to: Optional[str] = None,
+        direction: Optional[str] = None,
+        status: Optional[str] = None,
+        country: Optional[str] = None,
+        campaign_id: Optional[str] = None,
+        keyword: Optional[str] = None,
+        number: Optional[str] = None,
+    ) -> JSON:
+        """Report for the calling account."""
+        return self.request("GET", "/report", params=self._report_params(locals()))
+
+    def account_report(self, account_id: str, **filters: Any) -> JSON:
+        """Report for a specific account in the hierarchy."""
+        return self.request("GET", f"/account/{account_id}/report", params=self._report_params(filters))
+
+    def group_report(self, from_: Optional[str] = None, to: Optional[str] = None) -> JSON:
+        """Report across the calling account and all its sub-accounts."""
+        return self.request("GET", "/report/group", params={"from": from_, "to": to})
+
+    @staticmethod
+    def _report_params(values: Dict[str, Any]) -> Dict[str, Any]:
+        return {
+            "from": values.get("from_"),
+            "to": values.get("to"),
+            "direction": values.get("direction"),
+            "status": values.get("status"),
+            "country": values.get("country"),
+            "campaign_id": values.get("campaign_id"),
+            "keyword": values.get("keyword"),
+            "number": values.get("number"),
+        }

texto_sdk-1.0.0/texto/errors.py

@@ -0,0 +1,97 @@
+"""Exception types raised by the Texto SDK."""
+
+from typing import Any, Optional
+
+
+class TextoError(Exception):
+    """Base class for every error raised by the Texto SDK."""
+
+
+class TextoApiError(TextoError):
+    """Raised when the API returns a non-2xx response."""
+
+    def __init__(
+        self,
+        message: str,
+        status: int,
+        body: Any = None,
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.body = body
+        self.code = code
+        self.request_id = request_id
+
+
+class TextoAuthenticationError(TextoApiError):
+    """The API key is missing, invalid or revoked (401)."""
+
+
+class TextoPermissionError(TextoApiError):
+    """The account lacks access or the request was blocked (403)."""
+
+
+class TextoInvalidRequestError(TextoApiError):
+    """The request was rejected as invalid (400, 405, 409)."""
+
+
+class TextoInsufficientCreditsError(TextoApiError):
+    """The account has too few credits, or a card problem occurred (402)."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        body = self.body if isinstance(self.body, dict) else {}
+        self.credits_required = body.get("credits_required")
+        self.credits_available = body.get("credits_available")
+
+
+class TextoNotFoundError(TextoApiError):
+    """The resource does not exist (404)."""
+
+
+class TextoRateLimitError(TextoApiError):
+    """The API is rate limiting the caller (429)."""
+
+    def __init__(self, *args: Any, retry_after: Optional[float] = None, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.retry_after = retry_after
+
+
+class TextoServerError(TextoApiError):
+    """The API returned a 5xx response."""
+
+
+class TextoConnectionError(TextoError):
+    """The request could not be completed (network failure or timeout)."""
+
+
+def error_from_response(
+    status: int,
+    body: Any,
+    request_id: Optional[str] = None,
+    retry_after: Optional[float] = None,
+) -> TextoApiError:
+    record = body if isinstance(body, dict) else {}
+    message = record.get("error") or f"Texto API request failed with status {status}"
+    if not isinstance(message, str):
+        message = f"Texto API request failed with status {status}"
+    code = record.get("code") if isinstance(record.get("code"), str) else None
+
+    kwargs = {"status": status, "body": body, "code": code, "request_id": request_id}
+
+    if status == 401:
+        return TextoAuthenticationError(message, **kwargs)
+    if status == 402:
+        return TextoInsufficientCreditsError(message, **kwargs)
+    if status == 403:
+        return TextoPermissionError(message, **kwargs)
+    if status == 404:
+        return TextoNotFoundError(message, **kwargs)
+    if status == 429:
+        return TextoRateLimitError(message, retry_after=retry_after, **kwargs)
+    if status >= 500:
+        return TextoServerError(message, **kwargs)
+    return TextoInvalidRequestError(message, **kwargs)

texto_sdk-1.0.0/texto/webhooks.py

@@ -0,0 +1,44 @@
+"""Helpers for verifying and parsing Texto webhooks."""
+
+import hashlib
+import hmac
+import json
+from typing import Any, Dict, Optional, Union
+
+
+def verify_webhook_signature(
+    payload: Union[str, bytes],
+    signature: Optional[str],
+    secret: str,
+) -> bool:
+    """Verify the ``X-Texto-Signature`` header against the raw request body.
+
+    :param payload: Raw request body exactly as received (do not re-serialise).
+    :param signature: Value of the ``X-Texto-Signature`` header, e.g. ``sha256=abc...``.
+    :param secret: Signing secret shown when you rotated the webhook secret.
+    """
+    if not signature or not secret:
+        return False
+    provided = signature[7:] if signature.startswith("sha256=") else signature
+    raw = payload.encode("utf-8") if isinstance(payload, str) else payload
+    expected = hmac.new(secret.encode("utf-8"), raw, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(provided, expected)
+
+
+def parse_webhook_event(
+    payload: Union[str, bytes],
+    signature: Optional[str],
+    secret: Optional[str],
+) -> Dict[str, Any]:
+    """Verify (when a secret is supplied) and decode a webhook body.
+
+    Raises ``ValueError`` when the signature does not match.
+    """
+    if secret and not verify_webhook_signature(payload, signature, secret):
+        raise ValueError("Texto webhook signature verification failed")
+    return json.loads(payload)
+
+
+def is_inbound_event(event: Dict[str, Any]) -> bool:
+    """Return True when the event is an inbound (reply) message webhook."""
+    return event.get("event") == "message.inbound"