feat: update USSD module for API v1 test/live app modes

USSD apps now have test and live modes. create_app responses expose id
(UUID string), mode, test_secret, live_secret, is_live, and active in
place of the single secret. Add set_mode and rotate_secret, type every
app/extension id as str, and reshape simulate to take app_id.

- Add ExtensionRequiredError (402 extension_required) and slug-aware
  error mapping so 402 resolves to InsufficientBalanceError or
  ExtensionRequiredError by the response error slug.
- rent_extension now surfaces insufficient_ussd_balance (dedicated USSD
  balance) on 402.
- simulate(app_id, session_id, msisdn, input="", new_session=False,
  service_code=None): service_code sent only when set; unknown_app -> 422.
- Update README USSD lifecycle, CHANGELOG, and tests; bump to 1.2.0.

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

Author: Albert A. Ninyeh

CHANGELOG.md

@@ -4,6 +4,32 @@ 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.2.0] - 2026-07-07
+
+### Added
+- USSD apps now have **test** and **live** modes. `create_app` responses expose
+  `id` (UUID string), `mode`, `test_secret` (`ussk_test_`), `live_secret`
+  (`ussk_live_`), `is_live`, and `active` in place of the single `secret`.
+- `client.ussd.set_mode(app_id, mode)` to switch an app between `test` and
+  `live`, and `client.ussd.rotate_secret(app_id, mode)` to rotate the secret for
+  a mode.
+- `ExtensionRequiredError` (402, `extension_required`), raised when switching an
+  app to live mode before an extension has been purchased.
+
+### Changed
+- App and extension ids are UUID strings; every id parameter (`update_app`,
+  `delete_app`, `rent_extension`'s `app_id`, `release_extension`, `session`, and
+  the new methods) is now typed `str`.
+- `simulate` now takes the app to target: `simulate(app_id, session_id, msisdn,
+  input="", new_session=False, service_code=None)`. `service_code` is optional
+  and defaults to the shared short code server-side. Simulation always runs in
+  the sandbox (test mode); an app you do not own returns 422 `unknown_app`.
+- Renting an extension draws from the dedicated USSD balance; on insufficient
+  funds it now returns 402 `insufficient_ussd_balance` (mapped to
+  `InsufficientBalanceError`).
+- Error mapping now honours the response `error` slug, so 402 responses resolve
+  to `InsufficientBalanceError` or `ExtensionRequiredError` as appropriate.
+
 ## [1.1.0] - 2026-07-07
 
 ### Added

README.md

@@ -93,10 +93,19 @@ 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`).
+ability. You build a USSD **app** whose `callback_url` Hellio calls on every
+step, `simulate` it in the sandbox by `app_id`, rent an **extension** (a
+short-code suffix, e.g. `*920*100#`) from your dedicated USSD balance, then flip
+the app to **live** mode. You can also inspect **sessions**. List endpoints are
+cursor-paginated (`data` array + `meta.next_cursor`).
+
+Every app has a **test** and a **live** mode. A new app starts in `test` and
+carries two secrets, `test_secret` (`ussk_test_...`) and `live_secret`
+(`ussk_live_...`); the active one is the secret for the current `mode`.
+Simulation always runs in the sandbox (test mode): no charge, no extension
+needed. Going live requires a purchased extension, and live USSD sessions are
+billed to a dedicated USSD balance, separate from your SMS credit and main
+wallet.
 
 ```python
 from hellio import Hellio
@@ -107,51 +116,67 @@ client = Hellio(token="your-token-here")
 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)
+# 1. Create an app (starts in test mode; ids are UUID strings)
 app = client.ussd.create_app("Airtime Top-up", "https://your-app.com/ussd")
-app_id = app["data"]["id"]
+app_id = app["data"]["id"]                 # e.g. "9b1f...": a UUID string
+# app["data"] also has: mode, test_secret, live_secret, is_live, active
+client.ussd.apps()                         # list (pass cursor="..." for the next page)
 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)
+# 2. Simulate a subscriber step in the sandbox (no dialling, no charge)
+client.ussd.simulate(
+    app_id=app_id,
+    session_id="sess-1",
+    msisdn="233241234567",
+    input="1",
+    new_session=True,
+)
+# -> {'data': {'message': 'Welcome...', 'action': 'continue', 'continue': True}}
+
+# 3. Rent an extension from your USSD balance and bind it to the app
 client.ussd.extensions()
 ext = client.ussd.rent_extension(100, app_id=app_id)
-client.ussd.release_extension(ext["data"]["id"])
+
+# 4. Go live (needs a purchased extension) and rotate secrets as needed
+client.ussd.set_mode(app_id, "live")
+client.ussd.rotate_secret(app_id, "live")
 
 # 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}}
+# Teardown
+client.ussd.release_extension(ext["data"]["id"])
+client.ussd.delete_app(app_id)
 ```
 
-Renting an extension that has just been taken raises `ConflictError` (409); an
-empty balance raises `InsufficientBalanceError` (402):
+Renting an extension that has just been taken raises `ConflictError` (409); too
+low a USSD balance raises `InsufficientBalanceError` (402,
+`insufficient_ussd_balance`); switching to live before an extension is purchased
+raises `ExtensionRequiredError` (402, `extension_required`):
 
 ```python
-from hellio import ConflictError, InsufficientBalanceError
+from hellio import ConflictError, ExtensionRequiredError, InsufficientBalanceError
 
 try:
     client.ussd.rent_extension(100)
 except ConflictError:
     ...  # someone else rented it first; try another code
 except InsufficientBalanceError:
-    ...  # top up
+    ...  # top up your USSD balance
+
+try:
+    client.ussd.set_mode(app_id, "live")
+except ExtensionRequiredError:
+    ...  # rent an extension for the app first
 ```
 
 ### 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
+(`HMAC-SHA256(rawBody, secret)`, where `secret` is the app's `test_secret` or
+`live_secret` for the `mode` on the request). Verify the signature, then return
 `{ message, action }` where `action` is `"continue"` or `"end"`:
 
 ```python
@@ -174,7 +199,8 @@ errors also expose `errors`.
 | Exception | Status |
 |---|---|
 | `InvalidApiTokenError` | 401 |
-| `InsufficientBalanceError` | 402 |
+| `InsufficientBalanceError` | 402 (`insufficient_ussd_balance`) |
+| `ExtensionRequiredError` | 402 (`extension_required`) |
 | `ConflictError` | 409 |
 | `ValidationError` (`.errors`) | 422 |
 | `RateLimitError` | 429 |

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "helliomessaging"
-version = "1.1.0"
+version = "1.2.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"

src/hellio/__init__.py

@@ -11,6 +11,7 @@
 from .client import Hellio
 from .errors import (
     ConflictError,
+    ExtensionRequiredError,
     HellioError,
     InsufficientBalanceError,
     InvalidApiTokenError,
@@ -20,14 +21,15 @@
 )
 from .ussd import Ussd
 
-__version__ = "1.1.0"
+__version__ = "1.2.0"
 
 __all__ = [
     "Hellio",
     "Ussd",
     "HellioError",
     "InvalidApiTokenError",
     "InsufficientBalanceError",
+    "ExtensionRequiredError",
     "ConflictError",
     "ValidationError",
     "RateLimitError",

src/hellio/client.py

@@ -14,6 +14,7 @@
 
 from .errors import (
     ConflictError,
+    ExtensionRequiredError,
     HellioError,
     InsufficientBalanceError,
     InvalidApiTokenError,
@@ -312,20 +313,30 @@ def _request(
         if 200 <= response.status_code < 300:
             return data
 
+        slug = data.get("error")
         message = data.get("message")
         if not isinstance(message, str) or not message:
-            message = data.get("error")
+            message = slug
         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,
-        }.get(response.status_code, HellioError)
+        # Some slugs share a status code (e.g. 402 covers both an insufficient
+        # balance and a missing extension), so a slug match wins over the
+        # status-code default when present.
+        slug_errors = {
+            "insufficient_ussd_balance": InsufficientBalanceError,
+            "extension_required": ExtensionRequiredError,
+        }
+        error_class = slug_errors.get(slug) if isinstance(slug, str) else None
+        if error_class is None:
+            error_class = {
+                401: InvalidApiTokenError,
+                402: InsufficientBalanceError,
+                409: ConflictError,
+                422: ValidationError,
+                429: RateLimitError,
+                503: ServiceUnavailableError,
+            }.get(response.status_code, HellioError)
 
         raise error_class(message, response.status_code, data)
 

src/hellio/errors.py

@@ -42,7 +42,13 @@ class InvalidApiTokenError(HellioError):
 
 
 class InsufficientBalanceError(HellioError):
-    """Raised on HTTP 402. The account balance is too low for the request."""
+    """Raised on HTTP 402. A balance is too low for the request, e.g. the
+    dedicated USSD balance when renting an extension (``insufficient_ussd_balance``)."""
+
+
+class ExtensionRequiredError(HellioError):
+    """Raised on HTTP 402 (``extension_required``) when switching a USSD app to
+    live mode before an extension has been purchased for it."""
 
 
 class ConflictError(HellioError):
@@ -67,6 +73,7 @@ class ServiceUnavailableError(HellioError):
     "HellioError",
     "InvalidApiTokenError",
     "InsufficientBalanceError",
+    "ExtensionRequiredError",
     "ConflictError",
     "ValidationError",
     "RateLimitError",