feat(ussd): support app test/live modes, UUID ids, and app-scoped simulate

Align the USSD module with API v1:

- Apps now have test/live modes. create_app returns id (UUID), mode,
  test_secret (ussk_test_), live_secret (ussk_live_), is_live, active
  instead of a single secret.
- Add set_mode(id, mode) and rotate_secret(id, mode).
- App and extension ids are UUID strings across all methods.
- simulate now targets an app: simulate(app_id:, session_id:, msisdn:,
  input: "", new_session: false, service_code: nil). service_code is
  sent only when given; not-owned apps return 422 unknown_app.
- Extension rentals draw from the dedicated USSD balance; underfunded
  rentals return 402 insufficient_ussd_balance.
- Add Hellio::ExtensionRequiredError (402) and map responses by error
  slug (extension_required, insufficient_ussd_balance) before status.
- Update README, CHANGELOG, and specs; bump version to 1.2.0.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

Author: Albert A. Ninyeh

CHANGELOG.md

@@ -3,6 +3,31 @@
 All notable changes to `hellio-messaging` are documented here.
 This project follows [Semantic Versioning](https://semver.org).
 
+## [1.2.0] - 2026-07-07
+
+### Added
+- USSD apps now have test/live modes:
+  - `create_app` responses return `id` (UUID string), `name`, `callback_url`,
+    `mode` ("test" for new apps), `test_secret` ("ussk_test_..."), `live_secret`
+    ("ussk_live_..."), `is_live`, and `active` instead of a single `secret`.
+  - `set_mode(id, mode)` switches an app between "test" and "live".
+  - `rotate_secret(id, mode)` rotates the secret for one mode.
+- `Hellio::ExtensionRequiredError` (402), raised when switching an app to "live"
+  before a USSD extension is purchased (slug "extension_required").
+- Error mapping now resolves a few responses by their `error` slug before the
+  HTTP status, covering "extension_required" and "insufficient_ussd_balance".
+
+### Changed
+- USSD app and extension ids are UUID strings (were integers).
+- `simulate` now targets an app: `simulate(app_id:, session_id:, msisdn:,
+  input: "", new_session: false, service_code: nil)`. `service_code` is sent
+  only when given and defaults server-side to the shared short code. Simulation
+  is always sandboxed (no charge, no extension). A not-owned app returns 422
+  ("unknown_app").
+- Extension rentals draw from the dedicated USSD balance; an underfunded rental
+  now returns 402 with slug "insufficient_ussd_balance" (still
+  `Hellio::InsufficientBalanceError`).
+
 ## [1.1.0] - 2026-07-07
 
 ### Added

README.md

@@ -104,47 +104,70 @@ before the request is sent.
 
 ## USSD
 
-USSD endpoints live under `client.ussd`. Rent an extension (the short code
-subscribers dial), point it at an app whose `callback_url` Hellio calls on each
-session step, and simulate the flow before going live.
+USSD endpoints live under `client.ussd`. Build an app whose `callback_url`
+Hellio calls on each session step, simulate the flow while still in test mode,
+rent an extension (the short code subscribers dial), then switch the app to
+live.
+
+Apps have two modes, `"test"` and `"live"`. A new app starts in `"test"` and
+carries both a `test_secret` (prefix `ussk_test_`) and a `live_secret` (prefix
+`ussk_live_`); `mode`/`is_live` say which one is active. App and extension ids
+are UUID strings.
 
 ```ruby
 # Pricing and availability
 client.ussd.pricing                 # short code, session prices, extension prices
 client.ussd.availability("100")     # {"data" => {"code" => "100", "valid" => true, "available" => true, "monthly_price" => "50.00"}}
 
-# Apps - Hellio POSTs each session step to callback_url
+# Apps - Hellio POSTs each session step to callback_url. New apps start in test mode.
 app = client.ussd.create_app(name: "Airtime", callback_url: "https://your-app.com/ussd")
+app_id = app["data"]["id"]          # UUID string
+app["data"]["mode"]                 # "test"
+app["data"]["test_secret"]          # "ussk_test_..."
 client.ussd.apps
-client.ussd.update_app(app["data"]["id"], active: false)
-client.ussd.delete_app(app["data"]["id"])
+client.ussd.update_app(app_id, active: false)
+
+# Rotate a secret for one mode (test or live)
+client.ussd.rotate_secret(app_id, "test")
 
-# Extensions - the code subscribers dial (raises on conflict / low balance)
+# Simulate a session - always sandboxed (no charge, no extension).
+# new_session: true on the first step, then reuse the same session_id.
+# service_code is optional and defaults to the shared short code.
+client.ussd.simulate(app_id: app_id, session_id: "sess-1",
+                     msisdn: "233241234567", new_session: true)
+client.ussd.simulate(app_id: app_id, session_id: "sess-1",
+                     msisdn: "233241234567", input: "1")
+
+# Extensions - the code subscribers dial, paid from the dedicated USSD balance
 client.ussd.extensions
-client.ussd.rent_extension("100", app_id: app["data"]["id"])
-client.ussd.release_extension(42)
+ext = client.ussd.rent_extension("100", app_id: app_id)
+
+# Go live once an extension is purchased
+client.ussd.set_mode(app_id, "live")
 
 # Sessions
 client.ussd.sessions(status: "ended")
-client.ussd.session(1024)
+client.ussd.session("6f1c...")      # UUID string
 
-# Simulate a session - new_session: true on the first step, then reuse session_id
-first = client.ussd.simulate(msisdn: "233241234567", service_code: "*920*100#", new_session: true)
-client.ussd.simulate(msisdn: "233241234567", service_code: "*920*100#",
-                     session_id: first["data"]["session_id"], input: "1")
+client.ussd.release_extension(ext["data"]["id"])
+client.ussd.delete_app(app_id)
 ```
 
-Renting an extension that is no longer available raises
-`Hellio::ConflictError` (409); an insufficient balance raises
-`Hellio::InsufficientBalanceError` (402).
+Renting an extension that is no longer available raises `Hellio::ConflictError`
+(409); an underfunded USSD balance raises `Hellio::InsufficientBalanceError`
+(402, slug `insufficient_ussd_balance`). The USSD balance is dedicated, separate
+from SMS credit and the main wallet. Switching an app to live before an
+extension is purchased raises `Hellio::ExtensionRequiredError` (402, slug
+`extension_required`).
 
 ### Handling the inbound callback
 
 When a subscriber uses your extension, Hellio POSTs a JSON body
 (`sessionId`, `msisdn`, `serviceCode`, `input`, `sequence`, `mode`) to your
 app's `callback_url`, signed with an `X-Hellio-Signature` header set to
-`HMAC-SHA256(rawBody, app.secret)`. Verify it, then reply with `message` and
-`action` (`"continue"` or `"end"`).
+`HMAC-SHA256(rawBody, secret)` where `secret` is the app's secret for the mode
+that raised the call (`test_secret` in test mode, `live_secret` in live mode).
+Verify it, then reply with `message` and `action` (`"continue"` or `"end"`).
 
 ```ruby
 require "openssl"
@@ -171,6 +194,7 @@ exposes field-level details through `#errors`.
 |---|---|
 | `Hellio::InvalidApiTokenError` | 401 |
 | `Hellio::InsufficientBalanceError` | 402 |
+| `Hellio::ExtensionRequiredError` | 402 (slug `extension_required`) |
 | `Hellio::ConflictError` | 409 |
 | `Hellio::ValidationError` (`#errors`) | 422 |
 | `Hellio::RateLimitError` | 429 |

lib/hellio/client.rb

@@ -16,6 +16,13 @@ class Client
     DEFAULT_BASE_URL = "https://api.helliomessaging.com/v1"
     DEFAULT_TIMEOUT = 30
 
+    # Some responses share an HTTP status but mean different things, so a few are
+    # mapped to a typed error by their response "error" slug before the status.
+    SLUG_ERRORS = {
+      "extension_required" => ExtensionRequiredError,
+      "insufficient_ussd_balance" => InsufficientBalanceError
+    }.freeze
+
     attr_reader :base_url, :timeout, :default_sender
 
     # token          - API token (falls back to HELLIO_API_TOKEN).
@@ -176,7 +183,8 @@ def delete_webhook(id)
     #
     #   client.ussd.pricing
     #   client.ussd.rent_extension("100")
-    #   client.ussd.simulate(msisdn: "233241234567", service_code: "*920*100#", new_session: true)
+    #   client.ussd.simulate(app_id: app_id, session_id: "sess-1",
+    #                        msisdn: "233241234567", new_session: true)
     #
     def ussd
       @ussd ||= Ussd.new(self)
@@ -250,7 +258,10 @@ def error_for(status, data)
           "Hellio API request failed."
         end
 
+      slug = data["error"] if data.is_a?(Hash) && data["error"].is_a?(String)
+
       error_class =
+        SLUG_ERRORS[slug] ||
         case status
         when 401 then InvalidApiTokenError
         when 402 then InsufficientBalanceError

lib/hellio/errors.rb

@@ -24,9 +24,15 @@ def errors
   # 401: the API token is missing, malformed, or revoked.
   class InvalidApiTokenError < Error; end
 
-  # 402: the account balance is too low to complete the request.
+  # 402: the account balance is too low to complete the request. For USSD
+  # extension rentals this is the dedicated USSD balance ("insufficient_ussd_balance"),
+  # which is separate from SMS credit and the main wallet.
   class InsufficientBalanceError < Error; end
 
+  # 402: switching a USSD app to "live" needs a purchased USSD extension first
+  # ("extension_required"). Buy an extension, then retry the mode switch.
+  class ExtensionRequiredError < Error; end
+
   # 409: the request conflicts with the current state of a resource, e.g. renting
   # a USSD extension that is no longer available ("extension_unavailable").
   class ConflictError < Error; end

lib/hellio/ussd.rb

@@ -6,11 +6,21 @@ module Hellio
   # session), rented extensions (the short codes subscribers dial), sessions, and
   # a simulator for exercising an app's callback without a live dial.
   #
+  # Apps carry two modes, "test" and "live". A new app starts in "test" and
+  # exposes both a `test_secret` (prefix "ussk_test_") and a `live_secret`
+  # (prefix "ussk_live_"); `mode`/`is_live` say which one is active. Switching an
+  # app to "live" requires a purchased USSD extension. Extension rentals draw
+  # from a dedicated USSD balance, separate from SMS credit and the main wallet.
+  #
   # Requests are routed through the owning client, so responses are decoded to a
   # Hash with string keys (payloads under "data") and non-2xx responses raise the
   # same typed Hellio::Error subclasses. A rented-out extension returns 409
-  # (Hellio::ConflictError) and an underfunded account returns 402
-  # (Hellio::InsufficientBalanceError).
+  # (Hellio::ConflictError), an underfunded USSD balance returns 402
+  # (Hellio::InsufficientBalanceError, slug "insufficient_ussd_balance"), and
+  # going live before an extension is purchased returns 402
+  # (Hellio::ExtensionRequiredError, slug "extension_required").
+  #
+  # App and extension ids are UUID strings.
   class Ussd
     def initialize(client)
       @client = client
@@ -37,14 +47,18 @@ def apps
     end
 
     # Create a USSD app. `callback_url` is where Hellio POSTs each session step.
+    # The returned "data" includes the app `id` (UUID string), `name`,
+    # `callback_url`, `mode` ("test" by default), `test_secret` ("ussk_test_..."),
+    # `live_secret` ("ussk_live_..."), `is_live`, and `active`.
     def create_app(name:, callback_url:)
       post("ussd/apps", compact(
         "name" => name,
         "callback_url" => callback_url
       ))
     end
 
-    # Update a USSD app. Pass only the fields you want to change.
+    # Update a USSD app (`id` is a UUID string). Pass only the fields you want to
+    # change.
     def update_app(id, name: nil, callback_url: nil, active: nil)
       put("ussd/apps/#{id}", compact(
         "name" => name,
@@ -53,7 +67,21 @@ def update_app(id, name: nil, callback_url: nil, active: nil)
       ))
     end
 
-    # Delete a USSD app by id.
+    # Switch a USSD app's mode (`id` is a UUID string; `mode` is "test" or
+    # "live"). Returns the app. Switching to "live" before a USSD extension is
+    # purchased raises Hellio::ExtensionRequiredError (402).
+    def set_mode(id, mode)
+      post("ussd/apps/#{id}/mode", "mode" => mode)
+    end
+
+    # Rotate a USSD app's secret for one mode (`id` is a UUID string; `mode` is
+    # "test" or "live"). Returns the app with the freshly rotated secret. The old
+    # secret for that mode stops working immediately.
+    def rotate_secret(id, mode)
+      post("ussd/apps/#{id}/rotate-secret", "mode" => mode)
+    end
+
+    # Delete a USSD app by id (UUID string).
     def delete_app(id)
       delete("ussd/apps/#{id}")
     end
@@ -65,17 +93,19 @@ def extensions
       get("ussd/extensions")
     end
 
-    # Rent an extension by code, optionally attaching it to an app. Raises
+    # Rent an extension by code, optionally attaching it to an app (`app_id` is a
+    # UUID string). Rentals draw from the dedicated USSD balance. Raises
     # Hellio::ConflictError (409) if the code is no longer available and
-    # Hellio::InsufficientBalanceError (402) if the balance is too low.
+    # Hellio::InsufficientBalanceError (402, slug "insufficient_ussd_balance") if
+    # the USSD balance is too low.
     def rent_extension(code, app_id: nil)
       post("ussd/extensions", compact(
         "code" => code,
         "app_id" => app_id
       ))
     end
 
-    # Release a rented extension by id.
+    # Release a rented extension by id (UUID string).
     def release_extension(id)
       delete("ussd/extensions/#{id}")
     end
@@ -87,24 +117,29 @@ def sessions(status: nil)
       get("ussd/sessions", compact("status" => status))
     end
 
-    # Fetch a single session by id.
+    # Fetch a single session by id (UUID string).
     def session(id)
       get("ussd/sessions/#{id}")
     end
 
     # -------------------------------------------------------------- Simulator
 
-    # Simulate a USSD step against an app's callback. Pass `new_session: true`
-    # for the first step (dialing the code) and the returned `session_id` on
-    # follow-up steps. Returns the app's reply plus the `action` ("continue" or
+    # Simulate a USSD step against an app's callback. `app_id` (UUID string) is
+    # the app to drive. Pass `new_session: true` for the first step (dialing the
+    # code) and reuse the same `session_id` on follow-up steps. `service_code` is
+    # optional and defaults server-side to the shared short code; pass it only to
+    # override. Simulation is always sandboxed (no charge, no extension needed).
+    # A not-owned `app_id` raises Hellio::ValidationError (422, slug
+    # "unknown_app"). Returns the app's reply plus the `action` ("continue" or
     # "end").
-    def simulate(msisdn:, service_code:, input: nil, session_id: nil, new_session: nil)
+    def simulate(app_id:, session_id:, msisdn:, input: "", new_session: false, service_code: nil)
       post("ussd/simulate", compact(
+        "app_id" => app_id,
         "session_id" => session_id,
         "msisdn" => msisdn,
-        "service_code" => service_code,
         "input" => input,
-        "new_session" => new_session
+        "new_session" => new_session,
+        "service_code" => service_code
       ))
     end
 

lib/hellio/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Hellio
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end