usethatapp 2.1.0__tar.gz → 2.3.0__tar.gz

{usethatapp-2.1.0 → usethatapp-2.3.0}/CHANGELOG.md

@@ -4,6 +4,124 @@ All notable changes to this project are documented in this file. This project ad
 [Semantic Versioning](https://semver.org/) and follows a clear, machine- and human-readable
 format inspired by "Keep a Changelog".
 
+## [Unreleased]
+
+## [2.3.0] - 2026-10-29
+
+### Added
+
+- `Entitlement.is_trial` and `LicenseState.is_trial`: true while the user is in a free
+  trial of a paid plan (entitled, nothing charged yet; `period_end` is the conversion
+  date). Explicit so integrations never string-match `status == "trialing"`. Both are
+  trailing fields with a `False` default, so positional construction and servers that
+  predate the field keep working.
+
+## [2.2.0] - 2026-08-25
+
+### Fixed (pre-release code review)
+
+- The nine annotations the pre-release commits left untyped (most
+  visibly `UtaServerError.__init__`'s `retry_after`, which a
+  downstream strict type checker saw as `Any`) are restored —
+  `mypy --strict` is green again, as `py.typed` promises.
+
+- `Entitlement.product_id` now carries the same
+  fall-back-to-`product_public_id` parsing as `LicenseState.product_id`,
+  so the alias contract ("gate on either field") holds in both
+  verification modes — previously only the License Key API parser had
+  the fallback.
+- `configure(client_secret_path=…)` now outranks an environment
+  `UTA_CLIENT_SECRET`: secret-pair precedence is decided per layer
+  (overrides → Django settings → environment), not per key.
+- `configure()` rejects wrong-typed values with a `UtaConfigError`
+  naming the option (e.g. a scopes *list* gets "join scope names with
+  spaces") instead of silently `str()`-coercing them into corrupt
+  values that surfaced later as opaque OAuth errors.
+- A malformed `Retry-After` header containing Unicode digit-property
+  characters (e.g. `²`) no longer escapes as an uncaught `ValueError`
+  from a 429 — it degrades to `retry_after=None`.
+- `userinfo()` and the token endpoint now speak the same 429/5xx
+  contract as every other endpoint: 429 raises retriable
+  `UtaServerError` with `retry_after` (a throttled token refresh is no
+  longer a `UtaTokenError`, which read as "log the user out"), and
+  their error messages cap quoted bodies like everywhere else.
+- The ~200-character error-body cap now applies to JSON bodies too —
+  a multi-kilobyte JSON error (DRF validation map, debug-mode 500) was
+  previously quoted whole — and the truncation suffix reports the
+  amount actually cut.
+- `timeout=0.0` (a fail-fast probe, expressible since the `float`
+  widening) is respected instead of being replaced by the configured
+  default in `get_entitlement`, `get_entitlement_async`, and the
+  License Key API calls.
+- The `UtaServiceNotEnabledError` message points at the manage page on
+  `https://www.usethatapp.com` — not the resolved `api_url`, which a
+  `configure(api_url=…)` override can aim at a host with no manage UI.
+- README: the error table names the add-on by its current public name
+  (Hosted sign-in), documents the 429 → `UtaServerError` +
+  `retry_after` mapping, and the `product_id` guidance matches the
+  post-cutover alias contract everywhere.
+
+### Added
+
+- `LicenseState.product_id` — an equal-valued alias of
+  `product_public_id` (the platform's post-cutover `prod_…` pair, the
+  same contract as the entitlement endpoint), with a parser fallback
+  against servers that predate the cutover.
+
+- **License Key API** (server-side, bring-your-own-auth MoR
+  verification): `validate_license_key(key)`, `get_order(ref)` for the
+  `uta_order` checkout handback, and `regenerate_license_key(license_id)`
+  as the compromise kill switch — all authenticated with your app's
+  client credentials (`UTA_CLIENT_SECRET` required; `UTA_REDIRECT_URI`
+  is no longer needed unless you use the OIDC login flow). New
+  `LicenseState` dataclass and typed errors: `UtaNotFoundError` (with
+  `.code`), `UtaOrderProcessingError`, `UtaLicenseCanceledError`.
+- `config.load()` no longer requires `UTA_REDIRECT_URI`; `begin_login()`
+  raises `UtaConfigError` if it is missing — keys-mode integrations
+  never redirect a browser.
+
+- `UtaServiceNotEnabledError` (subclass of `UtaPermissionError`), raised
+  when the entitlement endpoint returns `403 service_not_enabled`: the
+  app's developer has not enabled the Hosted sign-in add-on. The
+  previous behavior mislabeled this case as a missing `entitlements`
+  scope; the new error says the actual fix (enable the add-on on the
+  app's manage page). Existing `except UtaPermissionError` blocks catch
+  it unchanged.
+
+- In-code configuration: `configure(api_url=…, issuer=…, …)`,
+  `load_config()`, and `reset_config()` are now exported from the
+  package root, alongside `UtaConfig` and the `DEFAULT_API_URL` /
+  `DEFAULT_ISSUER` / `DEFAULT_SCOPES` constants — parity with the
+  JavaScript SDK's `configure()` / `loadConfig()` / `resetConfig()`.
+  Overrides win over Django settings and environment variables, and a
+  non-production `api_url` can now be corrected at runtime instead of
+  only through the process environment.
+
+- `UtaServerError.retry_after` — the server's `Retry-After` header in
+  seconds on a 429 (`None` otherwise), so backoff loops can use the
+  interval the platform actually sent instead of guessing. Matches the
+  JavaScript SDK's `retryAfter`.
+
+### Fixed
+
+- `UtaNotFoundError`, `UtaOrderProcessingError`, and
+  `UtaLicenseCanceledError` are now exported from the package root —
+  they were defined and documented but not importable as
+  `from usethatapp import …`.
+- The `UtaServiceNotEnabledError` message named the add-on by its
+  retired public name ("Auth & Entitlement") and hardcoded
+  `usethatapp.com`; it now says "Hosted sign-in" and points at the
+  configured `UTA_API_URL` host.
+- A `429` from the entitlement endpoint now raises `UtaServerError`
+  (the retry-with-backoff class, matching the License Key API and the
+  documented error table) instead of the base `UtaError`.
+- Non-JSON error bodies (HTML error pages) are collapsed and capped at
+  ~200 characters when quoted into exception messages, instead of
+  inlining the entire page.
+- `get_entitlement(timeout=)` and `get_entitlement_async(timeout=)` are
+  typed `Optional[float]`, matching every other function (they were
+  `Optional[int]`, failing strict type checks on e.g. `timeout=2.5`).
+
 ## [2.1.0] - 2026-08-11
 
 Thin, dependency-free support for selling your app from your own website

{usethatapp-2.1.0/usethatapp.egg-info → usethatapp-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usethatapp
-Version: 2.1.0
+Version: 2.3.0
 Summary: Python SDK for usethatapp.com — OpenID Connect login and live license entitlement queries.
 Author-email: UseThatApp <support@usethatapp.com>
 License-Expression: MIT
@@ -106,13 +106,15 @@ from usethatapp import (
     get_prices,         # () -> AppPrices      (anonymous public API)
     get_prices_async,
     UtaSession,         # sub, access_token, refresh_token, id_token, expires_at, ...
-    Entitlement,        # entitled, version, product_id, product_public_id, status, ...
+    Entitlement,        # entitled, version, product_id, product_public_id, status, is_trial, ...
     AppInfo,            # client_id, name, tagline, listing_mode, url, marketplace_url
     Price,              # public_id, product_id, product_name, amount, currency, ...
     AppPrices,          # client_id, app_name, has_free_tier, prices
     # errors:
     UtaError, UtaConfigError, UtaDiscoveryError, UtaAuthError,
-    UtaTokenError, UtaPermissionError, UtaServerError,
+    UtaTokenError, UtaPermissionError, UtaServiceNotEnabledError,
+    UtaNotFoundError, UtaOrderProcessingError, UtaLicenseCanceledError,
+    UtaServerError,
 )
 ```
 
@@ -152,14 +154,50 @@ are documentation only — nothing framework-specific ships in the package.
 
 `get_entitlement` maps status codes to typed exceptions:
 
-| Status | Exception            | Meaning                                       |
-|--------|----------------------|-----------------------------------------------|
-| 401    | `UtaTokenError`      | Access token invalid/expired — re-auth/refresh.|
-| 403    | `UtaPermissionError` | Token lacks the `entitlements` scope.         |
-| 400    | `UtaError`           | Client not linked to an app (misconfig).      |
-| 5xx    | `UtaServerError`     | Retriable with backoff.                       |
+| Status | Exception                                     | Meaning                                       |
+|--------|-----------------------------------------------|-----------------------------------------------|
+| 401    | `UtaTokenError`                               | Access token invalid/expired — re-auth/refresh.|
+| 403 (`insufficient_scope`)   | `UtaPermissionError`            | Token lacks the `entitlements` scope.         |
+| 403 (`service_not_enabled`)  | `UtaServiceNotEnabledError`     | The Hosted sign-in add-on is switched off for this app. No retry, refresh, or re-consent will help — enable it on the app's manage page at www.usethatapp.com (Integration panel). |
+| 400    | `UtaError`                                    | Client not linked to an app (misconfig).      |
+| 429    | `UtaServerError`                              | Rate limited — back off; `e.retry_after` carries the server's `Retry-After` seconds (or `None`). |
+| 5xx    | `UtaServerError`                              | Retriable with backoff; `e.retry_after` when the server sent one. |
 
 All inherit from `UtaError` — catch that for a single `except` clause.
+`UtaServiceNotEnabledError` subclasses `UtaPermissionError`, so existing
+`except UtaPermissionError` blocks keep working unchanged.
+
+## License Key API — bring your own auth
+
+If you keep your own auth (Auth0, Clerk, homegrown) and use UseThatApp
+purely as merchant of record, skip the OIDC flow entirely and verify
+purchases with license keys. Server-side only; set `UTA_CLIENT_SECRET`
+(`UTA_REDIRECT_URI` is not needed for this mode).
+
+```python
+from usethatapp import get_order, regenerate_license_key, validate_license_key
+
+# 1) The buyer returns from checkout with ?uta_order=... — exchange it
+#    for their key and link it to YOUR signed-in user. No email matching.
+order = get_order(request.GET["uta_order"])   # raises UtaOrderProcessingError → retry briefly
+your_db.save(user=current_user, license_key=order.license_key,
+             license_id=order.license_id)
+
+# 2) Any time you need the truth (app start, feature gate, cron):
+state = validate_license_key(stored_key)      # LicenseState
+if state.entitled: ...                        # cache against state.period_end
+# state.is_trial: in a free trial — entitled, nothing charged yet, and
+# period_end is the conversion date. Show a banner; gate nothing extra.
+# canceled purchases return entitled=False, status="canceled" — an
+# answer, not an exception. UtaNotFoundError means a key that was
+# never issued for your app.
+
+# 3) Compromised key? Rotate it — the old key dies instantly:
+state = regenerate_license_key(license_id)    # state.license_key is the new key
+```
+
+Buyers can always re-view their key on their UseThatApp management
+page, so "I lost my key" needs no support ticket and no rotation.
 
 ## Purchase links & pricing
 
@@ -200,9 +238,10 @@ for price in pricing.prices:
 `Price.amount` is a decimal **string** (e.g. `"10.00"`) — parse with
 `decimal.Decimal` if you need arithmetic. `Price.product_id` is the
 opaque `prod_…` identifier to gate features on after purchase — compare
-it against **`Entitlement.product_public_id`** (`Entitlement.product_id`
-still carries the legacy UUID until the platform's identifier cutover,
-after which both fields carry the same `prod_…` value).
+it against `Entitlement.product_id` or `Entitlement.product_public_id`:
+since the platform's identifier cutover they are a permanent
+equal-valued alias pair carrying the same `prod_…` value, so gate on
+either.
 
 Notes: UseThatApp is the **merchant of record** (checkout, tax, refunds
 are handled for you). Purchases are currently **US-only**. External

{usethatapp-2.1.0 → usethatapp-2.3.0}/README.md

@@ -73,13 +73,15 @@ from usethatapp import (
     get_prices,         # () -> AppPrices      (anonymous public API)
     get_prices_async,
     UtaSession,         # sub, access_token, refresh_token, id_token, expires_at, ...
-    Entitlement,        # entitled, version, product_id, product_public_id, status, ...
+    Entitlement,        # entitled, version, product_id, product_public_id, status, is_trial, ...
     AppInfo,            # client_id, name, tagline, listing_mode, url, marketplace_url
     Price,              # public_id, product_id, product_name, amount, currency, ...
     AppPrices,          # client_id, app_name, has_free_tier, prices
     # errors:
     UtaError, UtaConfigError, UtaDiscoveryError, UtaAuthError,
-    UtaTokenError, UtaPermissionError, UtaServerError,
+    UtaTokenError, UtaPermissionError, UtaServiceNotEnabledError,
+    UtaNotFoundError, UtaOrderProcessingError, UtaLicenseCanceledError,
+    UtaServerError,
 )
 ```
 
@@ -119,14 +121,50 @@ are documentation only — nothing framework-specific ships in the package.
 
 `get_entitlement` maps status codes to typed exceptions:
 
-| Status | Exception            | Meaning                                       |
-|--------|----------------------|-----------------------------------------------|
-| 401    | `UtaTokenError`      | Access token invalid/expired — re-auth/refresh.|
-| 403    | `UtaPermissionError` | Token lacks the `entitlements` scope.         |
-| 400    | `UtaError`           | Client not linked to an app (misconfig).      |
-| 5xx    | `UtaServerError`     | Retriable with backoff.                       |
+| Status | Exception                                     | Meaning                                       |
+|--------|-----------------------------------------------|-----------------------------------------------|
+| 401    | `UtaTokenError`                               | Access token invalid/expired — re-auth/refresh.|
+| 403 (`insufficient_scope`)   | `UtaPermissionError`            | Token lacks the `entitlements` scope.         |
+| 403 (`service_not_enabled`)  | `UtaServiceNotEnabledError`     | The Hosted sign-in add-on is switched off for this app. No retry, refresh, or re-consent will help — enable it on the app's manage page at www.usethatapp.com (Integration panel). |
+| 400    | `UtaError`                                    | Client not linked to an app (misconfig).      |
+| 429    | `UtaServerError`                              | Rate limited — back off; `e.retry_after` carries the server's `Retry-After` seconds (or `None`). |
+| 5xx    | `UtaServerError`                              | Retriable with backoff; `e.retry_after` when the server sent one. |
 
 All inherit from `UtaError` — catch that for a single `except` clause.
+`UtaServiceNotEnabledError` subclasses `UtaPermissionError`, so existing
+`except UtaPermissionError` blocks keep working unchanged.
+
+## License Key API — bring your own auth
+
+If you keep your own auth (Auth0, Clerk, homegrown) and use UseThatApp
+purely as merchant of record, skip the OIDC flow entirely and verify
+purchases with license keys. Server-side only; set `UTA_CLIENT_SECRET`
+(`UTA_REDIRECT_URI` is not needed for this mode).
+
+```python
+from usethatapp import get_order, regenerate_license_key, validate_license_key
+
+# 1) The buyer returns from checkout with ?uta_order=... — exchange it
+#    for their key and link it to YOUR signed-in user. No email matching.
+order = get_order(request.GET["uta_order"])   # raises UtaOrderProcessingError → retry briefly
+your_db.save(user=current_user, license_key=order.license_key,
+             license_id=order.license_id)
+
+# 2) Any time you need the truth (app start, feature gate, cron):
+state = validate_license_key(stored_key)      # LicenseState
+if state.entitled: ...                        # cache against state.period_end
+# state.is_trial: in a free trial — entitled, nothing charged yet, and
+# period_end is the conversion date. Show a banner; gate nothing extra.
+# canceled purchases return entitled=False, status="canceled" — an
+# answer, not an exception. UtaNotFoundError means a key that was
+# never issued for your app.
+
+# 3) Compromised key? Rotate it — the old key dies instantly:
+state = regenerate_license_key(license_id)    # state.license_key is the new key
+```
+
+Buyers can always re-view their key on their UseThatApp management
+page, so "I lost my key" needs no support ticket and no rotation.
 
 ## Purchase links & pricing
 
@@ -167,9 +205,10 @@ for price in pricing.prices:
 `Price.amount` is a decimal **string** (e.g. `"10.00"`) — parse with
 `decimal.Decimal` if you need arithmetic. `Price.product_id` is the
 opaque `prod_…` identifier to gate features on after purchase — compare
-it against **`Entitlement.product_public_id`** (`Entitlement.product_id`
-still carries the legacy UUID until the platform's identifier cutover,
-after which both fields carry the same `prod_…` value).
+it against `Entitlement.product_id` or `Entitlement.product_public_id`:
+since the platform's identifier cutover they are a permanent
+equal-valued alias pair carrying the same `prod_…` value, so gate on
+either.
 
 Notes: UseThatApp is the **merchant of record** (checkout, tax, refunds
 are handled for you). Purchases are currently **US-only**. External

{usethatapp-2.1.0 → usethatapp-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "usethatapp"
-version = "2.1.0"
+version = "2.3.0"
 description = "Python SDK for usethatapp.com — OpenID Connect login and live license entitlement queries."
 readme = { file = "README.md", content-type = "text/markdown" }
 authors = [{ name = "UseThatApp", email = "support@usethatapp.com"}]

{usethatapp-2.1.0 → usethatapp-2.3.0}/tests/conftest.py

@@ -71,10 +71,15 @@ def configure_env(monkeypatch):
     monkeypatch.setenv("UTA_CLOCK_SKEW_SECONDS", "60")
     # Drop any inherited secret-path var so tests are hermetic.
     monkeypatch.delenv("UTA_CLIENT_SECRET_PATH", raising=False)
-    uta_config.reset_cache()
+    # reset_config(), not reset_cache(): the process-global _overrides
+    # dict must be cleared too, or one test's configure() call leaks
+    # into every later test — and since overrides outrank monkeypatched
+    # env vars, the leak surfaces as unrelated respx "no route matched"
+    # failures (code review finding 7).
+    uta_config.reset_config()
     uta_discovery.reset_cache()
     yield
-    uta_config.reset_cache()
+    uta_config.reset_config()
     uta_discovery.reset_cache()
 
 

{usethatapp-2.1.0 → usethatapp-2.3.0}/tests/test_client.py

@@ -6,6 +6,8 @@ from urllib.parse import parse_qs, urlparse
 import httpx
 import pytest
 
+import json
+
 from usethatapp import (
     begin_login,
     complete_login,
@@ -19,6 +21,7 @@ from usethatapp.errors import (
     UtaAuthError,
     UtaError,
     UtaPermissionError,
+    UtaServiceNotEnabledError,
     UtaServerError,
     UtaTokenError,
 )
@@ -145,9 +148,23 @@ def test_get_entitlement_licensed(oidc_routes):
     assert ent.entitled and ent.version == "Pro" and ent.product_id == "p-1"
     assert ent.product_public_id == "prod_abc123"
     assert ent.status == "active" and ent.is_free is False
+    assert ent.is_trial is False
     assert ent.period_end == "2026-07-01"
 
 
+def test_get_entitlement_trialing(oidc_routes):
+    oidc_routes.get(API_URL + "/licensing/entitlement/").mock(
+        return_value=httpx.Response(200, json={
+            "entitled": True, "version": "Pro", "product_id": "prod_abc",
+            "product_public_id": "prod_abc", "status": "trialing",
+            "is_free": False, "is_trial": True, "period_end": "2026-11-11",
+        })
+    )
+    ent = get_entitlement("at-123")
+    assert ent.entitled and ent.is_trial and ent.status == "trialing"
+    assert ent.period_end == "2026-11-11"
+
+
 def test_get_entitlement_free(oidc_routes):
     oidc_routes.get(API_URL + "/licensing/entitlement/").mock(
         return_value=httpx.Response(200, json={
@@ -172,6 +189,44 @@ def test_get_entitlement_status_mapping(oidc_routes, status, exc):
         get_entitlement("at-123")
 
 
+def test_get_entitlement_service_not_enabled(oidc_routes):
+    """A 403 whose body says service_not_enabled is the developer's to
+    fix (enable the add-on) — it must NOT be reported as a scope
+    problem, but must stay catchable as UtaPermissionError."""
+    oidc_routes.get(API_URL + "/licensing/entitlement/").mock(
+        return_value=httpx.Response(403, json={
+            "error": "service_not_enabled",
+            "error_description": "The developer has not enabled the "
+                                 "entitlement service for this app.",
+        })
+    )
+    with pytest.raises(UtaServiceNotEnabledError, match="Hosted sign-in") as exc_info:
+        get_entitlement("at-123")
+    assert issubclass(UtaServiceNotEnabledError, UtaPermissionError)
+    # Glassbox F-10: the message names the CURRENT public feature name.
+    # Code review finding 10 (reversing F-10's host half): the manage
+    # hub lives on the production dashboard host — the configured
+    # api_url may be a dev stack or gateway with no manage UI, so the
+    # message must NOT point there.
+    message = str(exc_info.value)
+    assert "Auth & Entitlement" not in message
+    assert "https://www.usethatapp.com" in message
+    assert API_URL not in message
+
+
+def test_get_entitlement_scope_403_still_permission_error(oidc_routes):
+    """The pre-existing 403 (insufficient_scope) keeps its exact class —
+    not the new subclass — so callers can tell the two apart."""
+    oidc_routes.get(API_URL + "/licensing/entitlement/").mock(
+        return_value=httpx.Response(403, json={
+            "error": "insufficient_scope", "scope": "entitlements",
+        })
+    )
+    with pytest.raises(UtaPermissionError) as excinfo:
+        get_entitlement("at-123")
+    assert type(excinfo.value) is UtaPermissionError
+
+
 @pytest.mark.asyncio
 async def test_get_entitlement_async(oidc_routes):
     oidc_routes.get(API_URL + "/licensing/entitlement/").mock(
@@ -251,3 +306,162 @@ def test_logout_url(oidc_routes):
     assert q["id_token_hint"] == ["idt"]
     assert q["post_logout_redirect_uri"] == ["https://app.test.example/bye"]
     assert q["client_id"] == [CLIENT_ID]
+
+
+def test_get_entitlement_429_maps_to_server_error(oidc_routes):
+    """Glassbox F-04: a throttle answer is transient — it must land in
+    UtaServerError (the retry-with-backoff class), not the base class."""
+    oidc_routes.get(API_URL + "/licensing/entitlement/").mock(
+        return_value=httpx.Response(
+            429, json={"error": "rate_limited"}, headers={"Retry-After": "60"}
+        )
+    )
+    with pytest.raises(UtaServerError, match="rate limited"):
+        get_entitlement("at-123")
+
+
+def test_snippet_caps_every_body_shape():
+    """Glassbox F-11 + code review finding 5: ALL bodies are collapsed
+    and capped — JSON gets no exemption, because a DRF validation map or
+    debug-mode JSON 500 can carry a multi-kilobyte traceback (the
+    log-flooding the cap exists to stop). Short bodies pass whole."""
+    from usethatapp.client import _snippet
+
+    json_body = '{"error": "unknown_key"}'
+    assert _snippet(json_body) == json_body
+
+    html = "<!DOCTYPE html>\n<html>\n" + ("<p>filler</p>\n" * 200) + "</html>"
+    out = _snippet(html)
+    assert len(out) < 260
+    assert "\n" not in out
+    assert "truncated" in out
+
+    big_json = json.dumps({"detail": "Traceback (most recent call last)" * 200})
+    out = _snippet(big_json)
+    assert len(out) < 260
+    assert "truncated" in out
+
+
+def test_non_json_error_body_is_not_inlined_whole(oidc_routes):
+    html_page = "<!DOCTYPE html><html>" + "x" * 5000 + "</html>"
+    oidc_routes.get(API_URL + "/licensing/entitlement/").mock(
+        return_value=httpx.Response(500, text=html_page)
+    )
+    with pytest.raises(UtaServerError) as exc_info:
+        get_entitlement("at-123")
+    assert len(str(exc_info.value)) < 400
+
+
+def test_429_surfaces_retry_after_on_the_exception(oidc_routes):
+    """Quiver J-05: the server's backoff hint must reach the caller —
+    documented, sent, and previously discarded one layer below them."""
+    oidc_routes.get(API_URL + "/licensing/entitlement/").mock(
+        return_value=httpx.Response(
+            429, json={"error": "rate_limited"}, headers={"Retry-After": "60"}
+        )
+    )
+    with pytest.raises(UtaServerError) as exc_info:
+        get_entitlement("at-123")
+    assert exc_info.value.retry_after == 60
+
+
+def test_retry_after_is_none_when_absent(oidc_routes):
+    oidc_routes.get(API_URL + "/licensing/entitlement/").mock(
+        return_value=httpx.Response(503, text="unavailable")
+    )
+    with pytest.raises(UtaServerError) as exc_info:
+        get_entitlement("at-123")
+    assert exc_info.value.retry_after is None
+
+
+def test_retry_after_http_date_form_is_none(oidc_routes):
+    # RFC 9110 allows an HTTP-date; we only surface the seconds form.
+    oidc_routes.get(API_URL + "/licensing/entitlement/").mock(
+        return_value=httpx.Response(
+            429, json={"error": "rate_limited"},
+            headers={"Retry-After": "Sat, 23 Aug 2026 02:00:00 GMT"},
+        )
+    )
+    with pytest.raises(UtaServerError) as exc_info:
+        get_entitlement("at-123")
+    assert exc_info.value.retry_after is None
+
+
+def test_entitlement_product_id_falls_back_to_public_id(oidc_routes):
+    """Code review finding 1: the alias promise in types.py ("gate on
+    either field") must hold against a server that predates the
+    identifier cutover — same fallback the LicenseState parser has."""
+    oidc_routes.get(API_URL + "/licensing/entitlement/").mock(
+        return_value=httpx.Response(200, json={
+            "entitled": True,
+            "version": "Pro",
+            "status": "active",
+            "product_public_id": "prod_abc123",
+            # no product_id field at all
+        })
+    )
+    ent = get_entitlement("at-123")
+    assert ent.product_id == "prod_abc123"
+    assert ent.product_id == ent.product_public_id
+
+
+def test_unicode_digit_retry_after_does_not_crash(oidc_routes):
+    """Code review finding 3 (reproduced): '²'.isdigit() is True but
+    int('²') raises — a malformed Retry-After must degrade to None, not
+    turn a 429 into an uncaught ValueError."""
+    oidc_routes.get(API_URL + "/licensing/entitlement/").mock(
+        # As the wire delivers it: the latin-1 byte 0xB2, which httpx
+        # decodes to '²' on read.
+        return_value=httpx.Response(
+            429, text="slow down", headers=[(b"Retry-After", b"\xb2")]
+        )
+    )
+    with pytest.raises(UtaServerError) as exc_info:
+        get_entitlement("at-123")
+    assert exc_info.value.retry_after is None
+
+
+def test_userinfo_429_is_retriable_with_retry_after(oidc_routes):
+    """Code review finding 4: the backoff loop this release invites must
+    work when the same rate limiter throttles userinfo during login."""
+    oidc_routes.get(METADATA["userinfo_endpoint"]).mock(
+        return_value=httpx.Response(
+            429, text="rate limited", headers={"Retry-After": "30"}
+        )
+    )
+    with pytest.raises(UtaServerError) as exc_info:
+        userinfo("at-123")
+    assert exc_info.value.retry_after == 30
+
+
+def test_token_endpoint_429_is_not_a_credential_failure(oidc_routes):
+    """Code review finding 4: a throttled token refresh is retriable
+    server pushback — surfacing it as UtaTokenError makes callers log
+    the user out instead of backing off."""
+    oidc_routes.post(METADATA["token_endpoint"]).mock(
+        return_value=httpx.Response(
+            429, text="rate limited", headers={"Retry-After": "15"}
+        )
+    )
+    with pytest.raises(UtaServerError) as exc_info:
+        refresh("rt-123")
+    assert exc_info.value.retry_after == 15
+
+
+def test_timeout_zero_is_respected(oidc_routes, monkeypatch):
+    """Code review finding 8: timeout=0.0 — expressible since the float
+    widening — is a fail-fast probe, not falsy noise to be replaced by
+    the configured default."""
+    seen = {}
+    real_get = httpx.get
+
+    def spying_get(url, **kwargs):
+        seen["timeout"] = kwargs.get("timeout")
+        return real_get(url, **kwargs)
+
+    monkeypatch.setattr(httpx, "get", spying_get)
+    oidc_routes.get(API_URL + "/licensing/entitlement/").mock(
+        return_value=httpx.Response(200, json={"entitled": False})
+    )
+    get_entitlement("at-123", timeout=0.0)
+    assert seen["timeout"] == 0.0