Add USSD support (client.ussd) and bump to 1.1.0

Adds a USSD resource under the client.ussd namespace covering the full
API contract: pricing, availability, apps (list/create/update/delete),
extensions (list/rent/release), sessions (list/get), and simulate.

Also adds a ConflictError (409) for extension_unavailable, a _put helper
for the app update endpoint, and an error-message fallback to the response
body's error field. Includes tests mirroring the existing suite and a
README USSD section with the inbound callback contract.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Albert A. Ninyeh

CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-07-07
+
+### Added
+- USSD support via the `client.ussd` namespace: `pricing`, `availability`,
+  `apps`, `create_app`, `update_app`, `delete_app`, `extensions`,
+  `rent_extension`, `release_extension`, `sessions`, `session`, and `simulate`.
+- `ConflictError` (409), raised when renting an extension that is no longer
+  available (`extension_unavailable`).
+
+### Changed
+- Error messages now fall back to the response body's `error` field when no
+  `message` is present.
+
 ## [1.0.0] - 2026-07-05
 
 ### Added

README.md

@@ -6,8 +6,9 @@
 [![License](https://img.shields.io/pypi/l/helliomessaging.svg)](LICENSE)
 
 Python client for the [Hellio Messaging](https://helliomessaging.com) API v1:
-**SMS**, **OTP** (SMS / email / voice), **Voice broadcasts**, **Number Lookup (HLR)**,
-**Email Verification**, and **Webhooks**. Fully type-hinted and synchronous.
+**SMS**, **OTP** (SMS / email / voice), **Voice broadcasts**, **USSD**,
+**Number Lookup (HLR)**, **Email Verification**, and **Webhooks**. Fully
+type-hinted and synchronous.
 
 ## Install
 ```bash
@@ -90,6 +91,81 @@ client.webhooks()
 client.delete_webhook(1)
 ```
 
+## USSD
+USSD lives under the `client.ussd` namespace. Needs a token with the `ussd`
+ability. You rent an **extension** (a short-code suffix, e.g. `*920*100#`), point
+it at a USSD **app** whose `callback_url` Hellio calls on every step, and can
+inspect **sessions** or `simulate` a step without dialling the real code. List
+endpoints are cursor-paginated (`data` array + `meta.next_cursor`).
+
+```python
+from hellio import Hellio
+
+client = Hellio(token="your-token-here")
+
+# Pricing and availability
+client.ussd.pricing()                      # session prices per network + extension rents
+client.ussd.availability(100)              # {'data': {'valid': True, 'available': True, 'monthly_price': '50.00'}}
+
+# Apps (the callback endpoints Hellio POSTs session steps to)
+client.ussd.apps()                         # list (pass cursor="..." for the next page)
+app = client.ussd.create_app("Airtime Top-up", "https://your-app.com/ussd")
+app_id = app["data"]["id"]
+client.ussd.update_app(app_id, name="Airtime", active=True)
+client.ussd.delete_app(app_id)
+
+# Extensions (short-code suffixes you rent and bind to an app)
+client.ussd.extensions()
+ext = client.ussd.rent_extension(100, app_id=app_id)
+client.ussd.release_extension(ext["data"]["id"])
+
+# Sessions
+client.ussd.sessions(status="ended")       # optional status filter
+client.ussd.session("sess_ref_123")
+
+# Simulate a subscriber step against your callback (no real dialling)
+client.ussd.simulate(
+    msisdn="233241234567",
+    service_code="*920*100#",
+    user_input="1",
+    new_session=True,
+)
+# -> {'data': {'message': 'Welcome...', 'action': 'continue', 'continue': True}}
+```
+
+Renting an extension that has just been taken raises `ConflictError` (409); an
+empty balance raises `InsufficientBalanceError` (402):
+
+```python
+from hellio import ConflictError, InsufficientBalanceError
+
+try:
+    client.ussd.rent_extension(100)
+except ConflictError:
+    ...  # someone else rented it first; try another code
+except InsufficientBalanceError:
+    ...  # top up
+```
+
+### Inbound callback
+When a subscriber uses your extension, Hellio POSTs
+`{ sessionId, msisdn, serviceCode, input, sequence, mode }` to the app's
+`callback_url`, signed with an `X-Hellio-Signature` header
+(`HMAC-SHA256(rawBody, app.secret)`). Verify the signature, then return
+`{ message, action }` where `action` is `"continue"` or `"end"`:
+
+```python
+import hashlib
+import hmac
+
+def handle_ussd(raw_body: bytes, signature: str, secret: str) -> dict:
+    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected, signature):
+        raise ValueError("bad signature")
+    # ... branch on the parsed payload ...
+    return {"message": "Welcome to Airtime Top-up", "action": "continue"}
+```
+
 ## Error handling
 Non-2xx responses raise typed exceptions (all extend `HellioError`). Each error
 carries `message`, `status_code`, and `response` (the parsed body); validation
@@ -99,6 +175,7 @@ errors also expose `errors`.
 |---|---|
 | `InvalidApiTokenError` | 401 |
 | `InsufficientBalanceError` | 402 |
+| `ConflictError` | 409 |
 | `ValidationError` (`.errors`) | 422 |
 | `RateLimitError` | 429 |
 | `HellioError` | other |

pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "helliomessaging"
-version = "1.0.0"
-description = "Official Python SDK for the Hellio Messaging API (SMS, OTP, Voice, Number Lookup, Email Verification, Webhooks)."
+version = "1.1.0"
+description = "Official Python SDK for the Hellio Messaging API (SMS, OTP, Voice, USSD, Number Lookup, Email Verification, Webhooks)."
 readme = "README.md"
 requires-python = ">=3.9"
 license = { text = "MIT" }
 authors = [{ name = "Albert Ninyeh", email = "eaglesecurity0@gmail.com" }]
-keywords = ["hellio", "sms", "otp", "voice", "messaging", "hlr", "email-verification"]
+keywords = ["hellio", "sms", "otp", "voice", "ussd", "messaging", "hlr", "email-verification"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",

src/hellio/__init__.py

@@ -10,21 +10,25 @@
 
 from .client import Hellio
 from .errors import (
+    ConflictError,
     HellioError,
     InsufficientBalanceError,
     InvalidApiTokenError,
     RateLimitError,
     ServiceUnavailableError,
     ValidationError,
 )
+from .ussd import Ussd
 
-__version__ = "0.1.0"
+__version__ = "1.1.0"
 
 __all__ = [
     "Hellio",
+    "Ussd",
     "HellioError",
     "InvalidApiTokenError",
     "InsufficientBalanceError",
+    "ConflictError",
     "ValidationError",
     "RateLimitError",
     "ServiceUnavailableError",

src/hellio/client.py

@@ -13,13 +13,15 @@
 import httpx
 
 from .errors import (
+    ConflictError,
     HellioError,
     InsufficientBalanceError,
     InvalidApiTokenError,
     RateLimitError,
     ServiceUnavailableError,
     ValidationError,
 )
+from .ussd import Ussd
 
 Recipients = Union[str, Sequence[str]]
 
@@ -68,6 +70,9 @@ def __init__(
             },
         )
 
+        #: USSD endpoints (pricing, apps, extensions, sessions, simulate).
+        self.ussd = Ussd(self)
+
     # ---------------------------------------------------------------- lifecycle
 
     def close(self) -> None:
@@ -279,6 +284,11 @@ def _post(
     ) -> Dict[str, Any]:
         return self._request("POST", path, json=body)
 
+    def _put(
+        self, path: str, body: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        return self._request("PUT", path, json=body)
+
     def _delete(self, path: str) -> Dict[str, Any]:
         return self._request("DELETE", path)
 
@@ -303,12 +313,15 @@ def _request(
             return data
 
         message = data.get("message")
+        if not isinstance(message, str) or not message:
+            message = data.get("error")
         if not isinstance(message, str) or not message:
             message = "Hellio API request failed."
 
         error_class = {
             401: InvalidApiTokenError,
             402: InsufficientBalanceError,
+            409: ConflictError,
             422: ValidationError,
             429: RateLimitError,
             503: ServiceUnavailableError,

src/hellio/errors.py

@@ -45,6 +45,11 @@ class InsufficientBalanceError(HellioError):
     """Raised on HTTP 402. The account balance is too low for the request."""
 
 
+class ConflictError(HellioError):
+    """Raised on HTTP 409. The request conflicts with the current state, e.g. a
+    USSD extension that is no longer available to rent (``extension_unavailable``)."""
+
+
 class ValidationError(HellioError):
     """Raised on HTTP 422. One or more request fields failed validation."""
 
@@ -62,6 +67,7 @@ class ServiceUnavailableError(HellioError):
     "HellioError",
     "InvalidApiTokenError",
     "InsufficientBalanceError",
+    "ConflictError",
     "ValidationError",
     "RateLimitError",
     "ServiceUnavailableError",