usethatapp 2.0.0__tar.gz → 2.2.0__tar.gz

usethatapp-2.2.0/CHANGELOG.md

@@ -0,0 +1,335 @@
+# Changelog
+
+All notable changes to this project are documented in this file. This project adheres to
+[Semantic Versioning](https://semver.org/) and follows a clear, machine- and human-readable
+format inspired by "Keep a Changelog".
+
+## [Unreleased]
+
+## [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
+— hosted purchase links, the buyer management page, and the public
+(anonymous, CORS-enabled) app/pricing APIs — plus fixes to several
+identity-integrity and error-contract bugs in the 2.0 OIDC path.
+
+### Added
+
+- `purchase_url(price_id, *, next=, ref=, email=)` — build the hosted
+  checkout URL for a public price id (`prc_…`). Pure URL builder, no
+  network.
+- `manage_url(*, next=)` — build the buyer's subscription-management page
+  URL for your app. Pure URL builder, no network.
+- `get_app_info()` / `get_app_info_async()` → `AppInfo(client_id, name,
+  tagline, listing_mode, url, marketplace_url)`, from the anonymous
+  public apps API.
+- `get_prices()` / `get_prices_async()` → `AppPrices(client_id, app_name,
+  has_free_tier, prices)`, from the anonymous public pricing API —
+  render your pricing UI from this instead of hardcoding amounts.
+- New frozen dataclasses: `AppInfo`, `Price` (`public_id`, `product_id`,
+  `product_name`, `amount` — a decimal string, `currency`, `is_recurring`,
+  `frequency`, `buy_url`), and `AppPrices`.
+- `Entitlement.product_public_id` — the opaque public product identifier
+  (`prod_…`) matching `Price.product_id` from the pricing API. New
+  integrations should gate on it; `Entitlement.product_id` currently
+  carries a legacy UUID and will converge on the same `prod_…` value.
+
+### Changed
+
+- `refresh()` no longer sends a `scope` parameter. It previously sent the
+  full configured `UTA_SCOPES`, which is *broader* than the grant whenever
+  a login narrowed it via `begin_login(scopes=…)` — RFC 6749 §6 requires
+  the provider to reject that with `invalid_scope`, forcing a needless
+  interactive re-login. Omitting it asks for the original grant's scope.
+- `begin_login(extra_params=…)` now raises `ValueError` when `extra_params`
+  collides with a reserved OAuth parameter (`state`, `nonce`,
+  `code_challenge`, `redirect_uri`, …). Such a value previously landed in
+  the authorization URL while `flow_state` kept the internally generated
+  one, so the paired `complete_login()` always failed with a misleading
+  "state mismatch — possible CSRF" error.
+
+### Fixed
+
+- `userinfo()` returned the response body as the user's claims for any
+  status other than 401/5xx. A 403 or 400 error body (e.g.
+  `{"detail": "insufficient scope"}`) was therefore treated as a valid
+  claim set, and `refresh()`'s no-ID-token fallback turned it into a
+  `UtaSession` with `sub=""` — collapsing every affected user onto one
+  empty-string local key. 403 now raises `UtaPermissionError` and any
+  other non-2xx raises `UtaError`.
+- `refresh()` likewise accepted a 200 userinfo response with no `sub`,
+  again producing `sub=""`. It now raises `UtaTokenError`, matching what
+  `complete_login()` already did for the same case.
+- ID-token validation refetched the JWKS on *any* signature or decode
+  failure, so every malformed or forged token cost a blocking HTTPS
+  round-trip, and a network blip during that refetch surfaced
+  `UtaDiscoveryError` in place of the real validation error. The refetch
+  now happens only when the token references a `kid` that is not cached
+  (genuine key rotation).
+- `purchase_url()` validated `price_id` with `strip()` but interpolated
+  the raw value into the path, so a stray-whitespace or `/?#`-bearing id
+  produced a broken checkout link. It is now stripped and percent-encoded.
+- `get_prices()` / `get_prices_async()` raised a bare `AttributeError` when
+  a price entry was not a JSON object, escaping the documented "catch
+  `UtaError`" contract. Malformed entries now raise `UtaError`.
+- Gating guidance: the README quickstart and the `Entitlement.product_id`
+  docstring still pointed feature gating at `product_id` (a legacy UUID),
+  which locks out every paying customer. Both now point at
+  `product_public_id`.
+
+## [2.0.0] - 2026-06-21
+
+Breaking rewrite onto standard OAuth2 / OpenID Connect. usethatapp.com is
+now an OpenID Provider; the SDK is a framework-agnostic OIDC client. The
+v1 launch-envelope push + signed `get_version` pull are gone.
+
+### Removed
+
+- `get_user` / `get_user_from_request` / `get_user_from_request_async` and
+  the encrypted launch-envelope handling (`usethatapp.payloads`).
+- `get_version` / `get_version_async` and the process-local version cache.
+- `uta_launch_view` Django decorator and `usethatapp.django_helpers` — the
+  SDK no longer ships any framework-specific code.
+- `UtaUser` (and its `user_key` / `version_hint`).
+- RSA-key configuration (`UTA_PRIVATE_KEY[_PATH]`,
+  `UTA_MARKET_PUBLIC_KEY[_PATH]`) and `UTA_APP_ID`.
+- The bundled `cryptography` dependency (now pulled transitively by
+  `joserfc`).
+
+### Added
+
+- OIDC login flow:
+  - `begin_login()` → `(authorization_url, flow_state)` (authorization
+    code + PKCE; `flow_state` is a JSON-able dict you stash in the session).
+  - `complete_login(code=, state=, flow_state=)` → `UtaSession`, validating
+    `state`, exchanging the code, and verifying the ID token (signature via
+    JWKS, `iss`/`aud`/`exp`/`nonce`).
+  - `refresh(refresh_token)`, `userinfo(access_token)`, `logout_url(...)`.
+- `get_entitlement(access_token)` / `get_entitlement_async(...)` →
+  `Entitlement(entitled, version, product_id, status, is_free, period_end)`,
+  the Bearer-token replacement for `get_version`.
+- `UtaSession` (carries the pairwise pseudonymous `sub` + tokens) and
+  `Entitlement` dataclasses.
+- New config: `UTA_CLIENT_ID`, `UTA_CLIENT_SECRET[_PATH]`,
+  `UTA_REDIRECT_URI`, `UTA_ISSUER`, `UTA_SCOPES`.
+- New typed errors: `UtaDiscoveryError`, `UtaAuthError`, `UtaTokenError`,
+  `UtaPermissionError` (replacing the v1 envelope/session error set).
+
+### Changed
+
+- Runtime dependencies are now `httpx` + `joserfc`.
+- Identity is a pairwise, per-app pseudonymous `sub` — stable within your
+  app, uncorrelatable across apps. Key your user records off `sub`.
+
+## [1.0.0] - 2026-05-21
+
+Breaking rewrite for the new usethatapp.com webhook-based handoff. The browser
+iframe / `usethatapp.js` model has been retired in favor of a server-to-server
+push + pull flow.
+
+### Removed
+
+- `usethatapp.js` integration, `requestAccessLevel()` JS bridge, and all
+  iframe / `postMessage` handling.
+- `usethatapp.webapps.get_version(envelope, public_key_path, private_key_path)` —
+  the old envelope (`type`/`responseTo`/`message{contents,signature}`) is no
+  longer accepted.
+- `usethatapp.encryption` module (`Keys`, `decrypt_message`, `verify_signature`).
+  PEM key loading is now handled internally by `usethatapp.config`.
+- `uid` / `username` fields on the returned user object. The v1 envelope carries
+  only an opaque `user_key`.
+
+### Added
+
+- New top-level public API:
+  - `get_user(payload)` — verify + decrypt the launch envelope POSTed by
+    the marketplace. Framework-agnostic; takes the raw `uta_payload`
+    string or already-parsed mapping.
+  - `get_user_from_request(request)` and `get_user_from_request_async(request)`
+    — request-aware helpers that pull `uta_payload` directly out of a
+    Django / Flask / Werkzeug / Starlette request and forward to `get_user`.
+  - `get_version(user_key)` and `get_version_async(user_key)` — signed
+    server-to-server POST to `https://usethatapp.com/licensing/getversion/`,
+    returning the current product name or `None`. Honors a process-local TTL
+    cache keyed off the server's `cache_until`.
+  - `UtaUser` frozen dataclass (`user_key`, `app_id`, `issued_at`,
+    `expires_at`, `version_hint`).
+  - `uta_launch_view` Django decorator (csrf-exempt, POST-only, injects
+    `request.uta_user`).
+- Hybrid envelope crypto in `usethatapp.payloads`:
+  `RSA-OAEP-SHA256 + AES-256-GCM + RSA-PSS-SHA256`. The PSS signature now
+  covers `ek || iv || ct` (not the plaintext).
+- Typed exception hierarchy under `UtaError`: `UtaSignatureError`,
+  `UtaPayloadExpiredError`, `UtaAppMismatchError`, `UtaBadRequestError`,
+  `UtaSessionRevokedError`, `UtaUnknownSessionError`, `UtaServerError`,
+  `UtaConfigError`. Every failure mode (local validation + each HTTP status)
+  maps to a specific subclass.
+- `usethatapp.config.load()` settings resolver reading from
+  `django.conf.settings` then `os.environ`. New settings:
+  `UTA_APP_ID`, `UTA_PRIVATE_KEY`, `UTA_PRIVATE_KEY_PATH`,
+  `UTA_MARKET_PUBLIC_KEY`, `UTA_MARKET_PUBLIC_KEY_PATH`, `UTA_API_URL`,
+  `UTA_CLOCK_SKEW_SECONDS`, `UTA_REQUEST_TIMEOUT_SECONDS`. The
+  `*_PATH` variants read the PEM from a file at boot (intended for
+  hosting providers that mount secret files into the container);
+  direct values take precedence when both are set.
+- `py.typed` marker — package now ships type information.
+- `httpx` runtime dependency (sync + async HTTP).
+
+### Changed
+
+- Minimum Python is now 3.9.
+- `cryptography` constraint relaxed to `>=42`.
+
+### Migration
+
+```python
+# Before (0.x)
+from usethatapp.webapps import get_version
+version = get_version(envelope, "pub.pem", "priv.pem")
+
+# After (1.0)
+from usethatapp import get_user_from_request, get_version
+
+# In your launch view (Django shown):
+user = get_user_from_request(request)            # verifies envelope, returns UtaUser
+session["uta_user_key"] = user.user_key
+
+# Later, whenever you need the live tier:
+version = get_version(user.user_key)  # str | None
+```
+
+## [0.3.0] - 2026-04-10
+
+### Changed
+
+- Breaking change: `get_version` now accepts a full `requestAccessLevel()` envelope instead of
+  a flat message dict. The first parameter has been renamed from `message` to `envelope` and
+  must contain a `type` field (`"level"`) and a nested `message` dict with `contents` and
+  `signature`.
+- Error envelopes (`type == "error"`) are now detected and raise a `ValueError` with the
+  server's error description.
+- Envelope `type` is validated; unexpected types raise a `ValueError`.
+
+## [0.2.0] - 2026-03-29
+
+### Changed
+
+- Breaking change: renamed `get_product` -> `get_version` to better reflect the function's
+  purpose and improve clarity of the public API.
+
+## [0.1.0] - 2026-03-19
+
+### Added
+
+- Initial release: introduced `get_product` (now renamed to `get_version`) to retrieve
+  licensing or version information from signed/encrypted messages.
+
+---
+
+For more details, including commit-level history, see the project's Git repository.

usethatapp-2.2.0/MANIFEST.in

@@ -0,0 +1,4 @@
+# setuptools' sdist defaults pick up tests/test_*.py but not conftest.py or
+# the package marker, which ships a test suite that cannot be collected.
+include CHANGELOG.md
+recursive-include tests *.py

{usethatapp-2.0.0 → usethatapp-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: usethatapp
-Version: 2.0.0
+Version: 2.2.0
 Summary: Python SDK for usethatapp.com — OpenID Connect login and live license entitlement queries.
 Author-email: UseThatApp <support@usethatapp.com>
 License-Expression: MIT
@@ -99,11 +99,22 @@ from usethatapp import (
     refresh,            # (refresh_token) -> UtaSession
     userinfo,           # (access_token) -> {"sub": ...}
     logout_url,         # (id_token=, post_logout_redirect_uri=) -> str
+    purchase_url,       # (price_id, *, next=, ref=, email=) -> str  (no network)
+    manage_url,         # (*, next=) -> str                          (no network)
+    get_app_info,       # () -> AppInfo        (anonymous public API)
+    get_app_info_async,
+    get_prices,         # () -> AppPrices      (anonymous public API)
+    get_prices_async,
     UtaSession,         # sub, access_token, refresh_token, id_token, expires_at, ...
-    Entitlement,        # entitled, version, product_id, status, is_free, period_end
+    Entitlement,        # entitled, version, product_id, product_public_id, status, ...
+    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,
 )
 ```
 
@@ -129,9 +140,10 @@ session = complete_login(
 save_to_session("uta_sub", session.sub)
 save_to_session("uta_access_token", session.access_token)
 
-# 3) Anywhere you gate features:
+# 3) Anywhere you gate features. Gate on product_public_id — the opaque
+#    prod_… id that matches Price.product_id from get_prices():
 ent = get_entitlement(load_from_session("uta_access_token"))
-if ent.entitled and ent.product_id == "...":
+if ent.entitled and ent.product_public_id == "prod_...":
     ...
 ```
 
@@ -142,14 +154,97 @@ 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
+# 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
+
+usethatapp.com can sell your app **from your own website**: hosted
+checkout links, a buyer management page, and a public pricing API. The
+SDK helpers are thin — the URL builders make no network calls, and the
+two GET functions hit **anonymous** endpoints (no auth, CORS-enabled), so
+they work even on a marketing page that never logs anyone in.
+
+Gate an upgrade CTA on the entitlement, then send the user to checkout:
+
+```python
+from usethatapp import get_entitlement, manage_url, purchase_url
+
+ent = get_entitlement(load_from_session("uta_access_token"))
+if not ent.entitled:
+    # Hosted checkout. `next` must be an HTTPS URL on your registered
+    # domain (validated server-side); omit it to land on your Login URL.
+    return redirect(purchase_url("prc_...", next="https://yourapp.example/welcome"))
+
+# Existing buyers manage (or cancel) their plan on usethatapp.com:
+billing_link = manage_url(next="https://yourapp.example/account")
+```
+
+Render pricing from the live API instead of hardcoding — sellers can
+change prices anytime:
+
+```python
+from usethatapp import get_prices
+
+pricing = get_prices()          # anonymous — no token needed
+for price in pricing.prices:
+    per = f"/{price.frequency}" if price.is_recurring else " one-time"
+    print(f"{price.product_name}: {price.amount} {price.currency}{per}")
+    print(f"  buy: {price.buy_url}")   # ready-made hosted checkout link
+```
+
+`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_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
+sales is in beta — buy links return **404 until it's enabled for your
+app**. Full guide: [docs.usethatapp.com](https://docs.usethatapp.com).
 
 ## Signing out
 

{usethatapp-2.0.0 → usethatapp-2.2.0}/README.md

@@ -66,11 +66,22 @@ from usethatapp import (
     refresh,            # (refresh_token) -> UtaSession
     userinfo,           # (access_token) -> {"sub": ...}
     logout_url,         # (id_token=, post_logout_redirect_uri=) -> str
+    purchase_url,       # (price_id, *, next=, ref=, email=) -> str  (no network)
+    manage_url,         # (*, next=) -> str                          (no network)
+    get_app_info,       # () -> AppInfo        (anonymous public API)
+    get_app_info_async,
+    get_prices,         # () -> AppPrices      (anonymous public API)
+    get_prices_async,
     UtaSession,         # sub, access_token, refresh_token, id_token, expires_at, ...
-    Entitlement,        # entitled, version, product_id, status, is_free, period_end
+    Entitlement,        # entitled, version, product_id, product_public_id, status, ...
+    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,
 )
 ```
 
@@ -96,9 +107,10 @@ session = complete_login(
 save_to_session("uta_sub", session.sub)
 save_to_session("uta_access_token", session.access_token)
 
-# 3) Anywhere you gate features:
+# 3) Anywhere you gate features. Gate on product_public_id — the opaque
+#    prod_… id that matches Price.product_id from get_prices():
 ent = get_entitlement(load_from_session("uta_access_token"))
-if ent.entitled and ent.product_id == "...":
+if ent.entitled and ent.product_public_id == "prod_...":
     ...
 ```
 
@@ -109,14 +121,97 @@ 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
+# 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
+
+usethatapp.com can sell your app **from your own website**: hosted
+checkout links, a buyer management page, and a public pricing API. The
+SDK helpers are thin — the URL builders make no network calls, and the
+two GET functions hit **anonymous** endpoints (no auth, CORS-enabled), so
+they work even on a marketing page that never logs anyone in.
+
+Gate an upgrade CTA on the entitlement, then send the user to checkout:
+
+```python
+from usethatapp import get_entitlement, manage_url, purchase_url
+
+ent = get_entitlement(load_from_session("uta_access_token"))
+if not ent.entitled:
+    # Hosted checkout. `next` must be an HTTPS URL on your registered
+    # domain (validated server-side); omit it to land on your Login URL.
+    return redirect(purchase_url("prc_...", next="https://yourapp.example/welcome"))
+
+# Existing buyers manage (or cancel) their plan on usethatapp.com:
+billing_link = manage_url(next="https://yourapp.example/account")
+```
+
+Render pricing from the live API instead of hardcoding — sellers can
+change prices anytime:
+
+```python
+from usethatapp import get_prices
+
+pricing = get_prices()          # anonymous — no token needed
+for price in pricing.prices:
+    per = f"/{price.frequency}" if price.is_recurring else " one-time"
+    print(f"{price.product_name}: {price.amount} {price.currency}{per}")
+    print(f"  buy: {price.buy_url}")   # ready-made hosted checkout link
+```
+
+`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_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
+sales is in beta — buy links return **404 until it's enabled for your
+app**. Full guide: [docs.usethatapp.com](https://docs.usethatapp.com).
 
 ## Signing out
 

{usethatapp-2.0.0 → usethatapp-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "usethatapp"
-version = "2.0.0"
+version = "2.2.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"}]