invonetwork 2.1.2__tar.gz → 2.2.0__tar.gz

{invonetwork-2.1.2 → invonetwork-2.2.0}/CHANGELOG.md

@@ -3,6 +3,35 @@
 All notable changes to this project are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.0] - 2026-07-07
+
+### Changed
+
+**Backend reconciliation** — an audit of the SDK against the live backend surfaced three places
+the SDK didn't match reality. All changes are backward-compatible (relaxing required inputs /
+adding surface); no working call breaks.
+
+- **`mint_player_token` no longer requires `player_phone`.** `/api/sdk/player-token` is a
+  session-token mint for an **existing** player (looked up by email), not a registration call —
+  it reads only `player_email` and ignores `player_phone`. The 2.0.0 hard E.164 requirement was
+  a bug: it could **block a valid token mint for an existing email-only player**. `player_phone`
+  is now optional (keyword) and validated only if provided. Phone stays enforced on the money
+  calls and at player creation.
+- **Send by phone alone.** `receiver_player_email` (send) and `target_player_email` (transfer)
+  are now **optional** keyword args — send to a recipient's phone; they supply their email at
+  claim (claim still requires it).
+- **`get_player_balance` is by email only.** There is no by-id balance route; passing
+  `player_id` now raises a clear `INVALID_INPUT` pointing to the browser `getBalance()` or
+  `player_email`, instead of hitting a 404.
+- **New `InvoError.is_user_verification_required`** for the `WEBAUTHN_UV_REQUIRED` (401) approve
+  failure.
+- `iterate_item_purchase_history` reads the backend's `total_count` pagination key (was `total`;
+  behavior unchanged — the short-page guard already terminated the loop).
+
+**Migration:** none required. If you passed `player_phone` to `mint_player_token` it still works;
+you can now omit it. Replace any `get_player_balance(player_id=…)` with an email lookup or the
+browser `getBalance()`.
+
 ## [2.1.2] - 2026-07-07
 
 ### Added / Changed

{invonetwork-2.1.2 → invonetwork-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: invonetwork
-Version: 2.1.2
+Version: 2.2.0
 Summary: INVO Python server SDK -- currency purchase, item purchase, sends/transfers, and webhook verification for partner platforms.
 Project-URL: Homepage, https://docs.invo.network
 Project-URL: Documentation, https://docs.invo.network
@@ -54,8 +54,10 @@ same live backend interchangeably.
 > wraps is **live** on sandbox + production, so you can build and test against sandbox today.
 > **Since 2.0.0 (breaking):** `mint_player_token` requires `player_phone` (E.164) — see the
 > [CHANGELOG](CHANGELOG.md) migration note. **2.1.0 adds** the passkey-recovery relay
-> (`recovery_begin`/`recovery_complete`); **2.1.1** is a security/correctness hardening patch;
-> **2.1.2** surfaces `expires_in_seconds` on `create_checkout`.
+> (`recovery_begin`/`recovery_complete`); **2.1.1** security hardening; **2.1.2** `expires_in_seconds`
+> on `create_checkout`. **2.2.0** reconciles with the backend: `mint_player_token` no longer
+> requires `player_phone` (it's a session mint, not registration), send-by-phone-alone, and
+> `get_player_balance` is email-only.
 > Canonical partner reference: **https://docs.invo.network**.
 
 ## Highlights
@@ -166,37 +168,29 @@ INVO integrations split across two trust boundaries. This package is the **serve
 The **game secret authenticates every call here and must never reach a browser.** Mint a
 short-lived player token server-side with `mint_player_token` and hand *that* to the browser SDK.
 
-### Player registration (email + phone, required)
+### Player token (session mint for an existing player)
 
-`mint_player_token` is the player **registration** call, and it requires **both**
-`player_email` and `player_phone`:
+`mint_player_token` mints a short-lived, game-scoped **session token** for a player who
+**already exists** on your game — it is *not* a registration call. The backend looks the player
+up by `player_email` and returns a token for their existing identity (or `404` if unknown). It
+only needs `player_email`:
 
 ```python
-token = server.mint_player_token(
-    player_email="player@example.com",
-    player_phone="+15555550100",  # REQUIRED -- E.164: leading "+", country code, digits only
-)
+token = server.mint_player_token(player_email="player@example.com")
 ```
 
-Why phone is not optional on the INVO network:
-
-- **Identity is derived from email + phone together.** Registering email-only and adding the
-  phone later **changes the identity and forces device re-enrollment** — collect the phone in
-  your enrollment UI *before* the first mint.
-- **Incoming cross-game transfers are matched by phone.** An account without a phone can never
-  see money sent to it.
-- **The account-linking consent SMS is triggered by phone.** Without one, the "add this email
-  to your account?" flow can't run.
-- **Format is E.164** (`+15555550100`) — the SDK rejects anything else before it reaches the
-  wire. Don't send national/local formats.
-
-**Same person, new email, same phone is expected and supported.** When the phone already
-belongs to another INVO account, the mint raises an `InvoError` with
-`is_phone_share_approval_required` (409) — this is **not a failure**: INVO sent the phone
-holder a consent SMS. Show the player a "pending approval" state, then re-issue the same mint
-once approved. Poll `phone_share_status(phone=..., email=...)`, or use
-`phone_share_initiate` / `phone_share_approve` (the error's `phone_share_approval_id` carries
-the id) for the in-app OTP fallback.
+`player_phone` is **optional** here (validated as E.164 only if you pass it, and ignored by this
+endpoint) — an existing email-only player still mints a token.
+
+**Where phone actually matters.** A player's INVO identity encodes their phone, and cross-game
+money routing keys off it — but that's enforced on the money calls, not the token mint:
+
+- **`initiate_send` / `initiate_transfer`** require the **sender's** phone (E.164), and take the
+  **recipient's** phone. You can send by the recipient's **phone alone** — they supply their
+  email when they claim.
+- An account with no phone can't receive cross-game money or take part in the account-linking
+  consent SMS, so make sure players have a phone at **creation / enrollment** (in your own
+  player system), before they transact.
 
 ### Not in this SDK (by design): the browser WebAuthn ceremonies
 
@@ -246,8 +240,9 @@ INVO enables each flow for your tenant in the [console](#get-your-account--game-
 
 - **Store the game secret server-side** (env var / secret manager) and expose a small endpoint
   that calls `mint_player_token` so your front-end can fetch/refresh a player token.
-- **Collect a phone number (E.164) in your enrollment flow** — `mint_player_token` requires it
-  alongside the email (see [Player registration](#player-registration-email--phone-required)).
+- **Make sure players have a phone (E.164) at creation/enrollment** — it's required on the money
+  calls (`initiate_send`/`initiate_transfer`) and for cross-game receive, though not on the token
+  mint itself (see [Player token](#player-token-session-mint-for-an-existing-player)).
 - **Set your webhook signing secret** and verify every delivery with `verify_webhook` — grant
   currency/items off webhooks, not synchronous responses.
 - **For currency purchase:** hosted checkout works out of the box; ask INVO to enable the
@@ -394,7 +389,8 @@ for row in server.iterate_item_purchase_history(player_email="p@example.com"):
 
 ```python
 result = server.get_player_balance(player_email="p@example.com")
-# or: server.get_player_balance(player_id=12345)
+# Lookup is by EMAIL only — there is no by-id balance route (player_id is a per-game internal
+# id). For a client-side read, use the browser InvoClient.getBalance() (identity from the token).
 for b in result.balances:
     print(b.currency_name, b.available_balance, b.total_balance)
 ```
@@ -624,7 +620,7 @@ Construct: `InvoServer(game_secret, base_url, *, timeout=30, max_retries=2, retr
 
 | Method | Returns |
 |---|---|
-| `mint_player_token(player_email, player_phone)` | `PlayerToken(token, expires_at, identity_id, raw)` — **both required**; `player_phone` must be E.164 (see [Player registration](#player-registration-email--phone-required)) |
+| `mint_player_token(player_email, player_phone?)` | `PlayerToken(token, expires_at, identity_id, raw)` — session mint for an **existing** player (404 if unknown); `player_phone` optional/validated-if-present (see [Player token](#player-token-session-mint-for-an-existing-player)) |
 | `initiate_send(...)` | `InitiateResult(transaction_id, verification_method, guardian_approval, raw)` |
 | `initiate_transfer(...)` | `InitiateResult` |
 | `create_checkout(player_email, usd_amount, rail?, success_url?, cancel_url?, metadata?)` | `CreateCheckoutResult(session_id, checkout_url, expires_at, expires_in_seconds, raw)` |
@@ -635,7 +631,7 @@ Construct: `InvoServer(game_secret, base_url, *, timeout=30, max_retries=2, retr
 | `get_item_purchase_history(player_email, limit?, offset?)` | `ItemHistoryResult(history, pagination, raw)` |
 | `get_item_order_details(order_id? \| transaction_id? \| client_request_id?)` | `OrderDetailsResult` |
 | `iterate_item_purchase_history(player_email, page_size?)` | generator of history rows (`dict`) |
-| `get_player_balance(player_email? \| player_id?)` | `PlayerBalanceResult(player, balances, summary, raw)` |
+| `get_player_balance(player_email)` | `PlayerBalanceResult(player, balances, summary, raw)` — **by email only** (no by-id route; use browser `InvoClient.getBalance()` client-side) |
 | `get_inbound_pending(player_email? \| player_phone?)` | `InboundPendingResult(inbound_pending, raw)` |
 | `get_linked_identities(player_email? \| player_phone?)` | `LinkedIdentitiesResult(wallet_user_id, primary_email, primary_phone, is_minor, emails, not_found, raw)` — **server-only (PII)** |
 | `verify_sms_transfer(transaction_id, sms_pin)` / `verify_sms_send(...)` | `SmsVerifyResult` — complete the SMS-PIN path when `verification_method == "sms"` |

{invonetwork-2.1.2 → invonetwork-2.2.0}/README.md

@@ -9,8 +9,10 @@ same live backend interchangeably.
 > wraps is **live** on sandbox + production, so you can build and test against sandbox today.
 > **Since 2.0.0 (breaking):** `mint_player_token` requires `player_phone` (E.164) — see the
 > [CHANGELOG](CHANGELOG.md) migration note. **2.1.0 adds** the passkey-recovery relay
-> (`recovery_begin`/`recovery_complete`); **2.1.1** is a security/correctness hardening patch;
-> **2.1.2** surfaces `expires_in_seconds` on `create_checkout`.
+> (`recovery_begin`/`recovery_complete`); **2.1.1** security hardening; **2.1.2** `expires_in_seconds`
+> on `create_checkout`. **2.2.0** reconciles with the backend: `mint_player_token` no longer
+> requires `player_phone` (it's a session mint, not registration), send-by-phone-alone, and
+> `get_player_balance` is email-only.
 > Canonical partner reference: **https://docs.invo.network**.
 
 ## Highlights
@@ -121,37 +123,29 @@ INVO integrations split across two trust boundaries. This package is the **serve
 The **game secret authenticates every call here and must never reach a browser.** Mint a
 short-lived player token server-side with `mint_player_token` and hand *that* to the browser SDK.
 
-### Player registration (email + phone, required)
+### Player token (session mint for an existing player)
 
-`mint_player_token` is the player **registration** call, and it requires **both**
-`player_email` and `player_phone`:
+`mint_player_token` mints a short-lived, game-scoped **session token** for a player who
+**already exists** on your game — it is *not* a registration call. The backend looks the player
+up by `player_email` and returns a token for their existing identity (or `404` if unknown). It
+only needs `player_email`:
 
 ```python
-token = server.mint_player_token(
-    player_email="player@example.com",
-    player_phone="+15555550100",  # REQUIRED -- E.164: leading "+", country code, digits only
-)
+token = server.mint_player_token(player_email="player@example.com")
 ```
 
-Why phone is not optional on the INVO network:
-
-- **Identity is derived from email + phone together.** Registering email-only and adding the
-  phone later **changes the identity and forces device re-enrollment** — collect the phone in
-  your enrollment UI *before* the first mint.
-- **Incoming cross-game transfers are matched by phone.** An account without a phone can never
-  see money sent to it.
-- **The account-linking consent SMS is triggered by phone.** Without one, the "add this email
-  to your account?" flow can't run.
-- **Format is E.164** (`+15555550100`) — the SDK rejects anything else before it reaches the
-  wire. Don't send national/local formats.
-
-**Same person, new email, same phone is expected and supported.** When the phone already
-belongs to another INVO account, the mint raises an `InvoError` with
-`is_phone_share_approval_required` (409) — this is **not a failure**: INVO sent the phone
-holder a consent SMS. Show the player a "pending approval" state, then re-issue the same mint
-once approved. Poll `phone_share_status(phone=..., email=...)`, or use
-`phone_share_initiate` / `phone_share_approve` (the error's `phone_share_approval_id` carries
-the id) for the in-app OTP fallback.
+`player_phone` is **optional** here (validated as E.164 only if you pass it, and ignored by this
+endpoint) — an existing email-only player still mints a token.
+
+**Where phone actually matters.** A player's INVO identity encodes their phone, and cross-game
+money routing keys off it — but that's enforced on the money calls, not the token mint:
+
+- **`initiate_send` / `initiate_transfer`** require the **sender's** phone (E.164), and take the
+  **recipient's** phone. You can send by the recipient's **phone alone** — they supply their
+  email when they claim.
+- An account with no phone can't receive cross-game money or take part in the account-linking
+  consent SMS, so make sure players have a phone at **creation / enrollment** (in your own
+  player system), before they transact.
 
 ### Not in this SDK (by design): the browser WebAuthn ceremonies
 
@@ -201,8 +195,9 @@ INVO enables each flow for your tenant in the [console](#get-your-account--game-
 
 - **Store the game secret server-side** (env var / secret manager) and expose a small endpoint
   that calls `mint_player_token` so your front-end can fetch/refresh a player token.
-- **Collect a phone number (E.164) in your enrollment flow** — `mint_player_token` requires it
-  alongside the email (see [Player registration](#player-registration-email--phone-required)).
+- **Make sure players have a phone (E.164) at creation/enrollment** — it's required on the money
+  calls (`initiate_send`/`initiate_transfer`) and for cross-game receive, though not on the token
+  mint itself (see [Player token](#player-token-session-mint-for-an-existing-player)).
 - **Set your webhook signing secret** and verify every delivery with `verify_webhook` — grant
   currency/items off webhooks, not synchronous responses.
 - **For currency purchase:** hosted checkout works out of the box; ask INVO to enable the
@@ -349,7 +344,8 @@ for row in server.iterate_item_purchase_history(player_email="p@example.com"):
 
 ```python
 result = server.get_player_balance(player_email="p@example.com")
-# or: server.get_player_balance(player_id=12345)
+# Lookup is by EMAIL only — there is no by-id balance route (player_id is a per-game internal
+# id). For a client-side read, use the browser InvoClient.getBalance() (identity from the token).
 for b in result.balances:
     print(b.currency_name, b.available_balance, b.total_balance)
 ```
@@ -579,7 +575,7 @@ Construct: `InvoServer(game_secret, base_url, *, timeout=30, max_retries=2, retr
 
 | Method | Returns |
 |---|---|
-| `mint_player_token(player_email, player_phone)` | `PlayerToken(token, expires_at, identity_id, raw)` — **both required**; `player_phone` must be E.164 (see [Player registration](#player-registration-email--phone-required)) |
+| `mint_player_token(player_email, player_phone?)` | `PlayerToken(token, expires_at, identity_id, raw)` — session mint for an **existing** player (404 if unknown); `player_phone` optional/validated-if-present (see [Player token](#player-token-session-mint-for-an-existing-player)) |
 | `initiate_send(...)` | `InitiateResult(transaction_id, verification_method, guardian_approval, raw)` |
 | `initiate_transfer(...)` | `InitiateResult` |
 | `create_checkout(player_email, usd_amount, rail?, success_url?, cancel_url?, metadata?)` | `CreateCheckoutResult(session_id, checkout_url, expires_at, expires_in_seconds, raw)` |
@@ -590,7 +586,7 @@ Construct: `InvoServer(game_secret, base_url, *, timeout=30, max_retries=2, retr
 | `get_item_purchase_history(player_email, limit?, offset?)` | `ItemHistoryResult(history, pagination, raw)` |
 | `get_item_order_details(order_id? \| transaction_id? \| client_request_id?)` | `OrderDetailsResult` |
 | `iterate_item_purchase_history(player_email, page_size?)` | generator of history rows (`dict`) |
-| `get_player_balance(player_email? \| player_id?)` | `PlayerBalanceResult(player, balances, summary, raw)` |
+| `get_player_balance(player_email)` | `PlayerBalanceResult(player, balances, summary, raw)` — **by email only** (no by-id route; use browser `InvoClient.getBalance()` client-side) |
 | `get_inbound_pending(player_email? \| player_phone?)` | `InboundPendingResult(inbound_pending, raw)` |
 | `get_linked_identities(player_email? \| player_phone?)` | `LinkedIdentitiesResult(wallet_user_id, primary_email, primary_phone, is_minor, emails, not_found, raw)` — **server-only (PII)** |
 | `verify_sms_transfer(transaction_id, sms_pin)` / `verify_sms_send(...)` | `SmsVerifyResult` — complete the SMS-PIN path when `verification_method == "sms"` |

{invonetwork-2.1.2 → invonetwork-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "invonetwork"
-version = "2.1.2"
+version = "2.2.0"
 description = "INVO Python server SDK -- currency purchase, item purchase, sends/transfers, and webhook verification for partner platforms."
 readme = "README.md"
 requires-python = ">=3.9"

{invonetwork-2.1.2 → invonetwork-2.2.0}/src/invonetwork/errors.py

@@ -85,6 +85,15 @@ class InvoError(Exception):
         """True if enrollment needs the OTP-grant flow (``enrollmentBegin``/``enrollmentVerify``)."""
         return self.code == "ENROLLMENT_REQUIRES_AUTHORIZATION"
 
+    @property
+    def is_user_verification_required(self) -> bool:
+        """True if a passkey approve/confirm was rejected for lacking user verification.
+
+        ``WEBAUTHN_UV_REQUIRED`` (401) -- re-run the ceremony requiring UV (biometric/PIN); the
+        backend treats a UV-satisfied assertion as the signed step-up.
+        """
+        return self.code == "WEBAUTHN_UV_REQUIRED"
+
     @property
     def is_enrollment_proof_required(self) -> bool:
         """True if enrolling is blocked because another method exists -- use device link."""

{invonetwork-2.1.2 → invonetwork-2.2.0}/src/invonetwork/server.py

@@ -50,7 +50,7 @@ from .types import (
 
 __all__ = ["InvoServer"]
 
-DEFAULT_USER_AGENT = "invonetwork-python-sdk/2.1.2 (+https://invo.network)"
+DEFAULT_USER_AGENT = "invonetwork-python-sdk/2.2.0 (+https://invo.network)"
 """Explicit, non-blocked UA. The backend 403-blocks UAs matching nikto|sqlmap|
 python-urllib|scanner|bot|^$, so we never use urllib's default UA."""
 
@@ -409,32 +409,33 @@ class InvoServer:
 
     # ---- Token ----
 
-    def mint_player_token(self, *, player_email: str, player_phone: str) -> PlayerToken:
+    def mint_player_token(
+        self, *, player_email: str, player_phone: Optional[str] = None
+    ) -> PlayerToken:
         """Mint a short-lived, game-scoped player token to hand to the browser client.
 
-        This is the player REGISTRATION call: the network identity is derived from
-        ``email + phone`` TOGETHER, so both are required. Registering email-only and
-        attaching the phone later changes the identity and forces device re-enrollment --
-        collect the phone before the first mint. ``player_phone`` must be E.164
-        (e.g. ``"+15555550100"``); incoming cross-game transfers and the account-linking
-        consent SMS are both matched by phone, so an account without one can't receive
-        either.
-
-        If the phone already belongs to another INVO account (same person, new email),
-        this raises an :class:`InvoError` with ``is_phone_share_approval_required`` --
-        NOT a failure: the phone holder was sent a consent SMS. Surface "pending
-        approval" to the user, then re-issue the same call once approved (poll
-        ``phone_share_status``, or use ``phone_share_initiate`` / ``phone_share_approve``
-        for the in-app OTP fallback).
+        This is a SESSION-TOKEN mint for a player who ALREADY EXISTS on the game -- not a
+        registration call. The backend looks the player up by ``player_email`` and returns a
+        token for their existing identity; if no such player exists it responds 404. The
+        network identity (which encodes the player's phone) is established at player creation
+        and on the money-routing calls, so phone is NOT required or read here.
+
+        ``player_phone`` is optional and only validated (E.164) if you pass it -- the backend
+        ignores it on this endpoint, so an existing email-only player can still mint a token.
+        Phone is enforced where it matters: ``initiate_send`` / ``initiate_transfer`` (the
+        sender's phone, and the recipient's when known) and at player creation.
 
         Idempotent: safe to retry (re-minting just issues a fresh token).
         """
         if not _is_present(player_email):
             raise _invalid_input("playerEmail", player_email, "is required")
-        _assert_e164(player_phone, "playerPhone")
+        body: Dict[str, Any] = {"player_email": player_email}
+        if player_phone is not None:
+            _assert_e164(player_phone, "playerPhone")  # validate only if provided
+            body["player_phone"] = player_phone
         raw = self._http.post(
             "/api/sdk/player-token",
-            {"player_email": player_email, "player_phone": player_phone},
+            body,
             self._auth,
             idempotent=True,
         )
@@ -454,29 +455,30 @@ class InvoServer:
         sender_player_name: str,
         sender_player_email: str,
         sender_player_phone: str,
-        receiver_player_email: str,
         receiver_player_phone: str,
         receiving_game_id: Any,
         amount: Money,
+        receiver_player_email: Optional[str] = None,
     ) -> InitiateResult:
         """Initiate a cross-game currency SEND. Inspect ``result.verification_method``.
 
-        Idempotent on ``client_request_id`` (the backend dedupes), so it is safe to retry.
+        You can send by the recipient's PHONE alone -- ``receiver_player_email`` is optional
+        (they supply their own email when they claim). Idempotent on ``client_request_id``
+        (the backend dedupes), so it is safe to retry.
         """
+        body: Dict[str, Any] = {
+            "client_request_id": client_request_id,
+            "sender_player_name": sender_player_name,
+            "sender_player_email": sender_player_email,
+            "sender_player_phone": sender_player_phone,
+            "receiver_player_phone": receiver_player_phone,
+            "receiving_game_id": receiving_game_id,
+            "amount": amount,
+        }
+        if receiver_player_email is not None:
+            body["receiver_player_email"] = receiver_player_email
         raw = self._http.post(
-            "/api/currency-sends/initiate-send",
-            {
-                "client_request_id": client_request_id,
-                "sender_player_name": sender_player_name,
-                "sender_player_email": sender_player_email,
-                "sender_player_phone": sender_player_phone,
-                "receiver_player_email": receiver_player_email,
-                "receiver_player_phone": receiver_player_phone,
-                "receiving_game_id": receiving_game_id,
-                "amount": amount,
-            },
-            self._auth,
-            idempotent=True,
+            "/api/currency-sends/initiate-send", body, self._auth, idempotent=True
         )
         return self._to_initiate_result(raw)
 
@@ -487,29 +489,30 @@ class InvoServer:
         source_player_name: str,
         source_player_email: str,
         source_player_phone: str,
-        target_player_email: str,
         target_player_phone: str,
         target_game_id: Any,
         amount: Money,
+        target_player_email: Optional[str] = None,
     ) -> InitiateResult:
         """Initiate a cross-game TRANSFER. Inspect ``result.verification_method``.
 
-        Idempotent on ``client_request_id`` (the backend dedupes), so it is safe to retry.
+        You can transfer by the recipient's PHONE alone -- ``target_player_email`` is optional
+        (they supply their own email when they claim). Idempotent on ``client_request_id``
+        (the backend dedupes), so it is safe to retry.
         """
+        body: Dict[str, Any] = {
+            "client_request_id": client_request_id,
+            "source_player_name": source_player_name,
+            "source_player_email": source_player_email,
+            "source_player_phone": source_player_phone,
+            "target_player_phone": target_player_phone,
+            "target_game_id": target_game_id,
+            "amount": amount,
+        }
+        if target_player_email is not None:
+            body["target_player_email"] = target_player_email
         raw = self._http.post(
-            "/api/transfers/initiate-transfer",
-            {
-                "client_request_id": client_request_id,
-                "source_player_name": source_player_name,
-                "source_player_email": source_player_email,
-                "source_player_phone": source_player_phone,
-                "target_player_email": target_player_email,
-                "target_player_phone": target_player_phone,
-                "target_game_id": target_game_id,
-                "amount": amount,
-            },
-            self._auth,
-            idempotent=True,
+            "/api/transfers/initiate-transfer", body, self._auth, idempotent=True
         )
         return self._to_initiate_result(raw)
 
@@ -831,9 +834,10 @@ class InvoServer:
             if len(page.history) < size:
                 return  # last (short) page
             # Guard against a backend that ignores `offset` and returns full pages forever:
-            # stop once we've yielded the reported total. Coerce like JS `Number(total)`
-            # so a string total (e.g. "100") still trips the guard.
-            total = page.pagination.get("total")
+            # stop once we've yielded the reported total. The backend key is ``total_count``
+            # (``total`` kept as a fallback). Coerce like JS ``Number()`` so a string total
+            # (e.g. "100") still trips the guard.
+            total = page.pagination.get("total_count", page.pagination.get("total"))
             try:
                 total_num = float(total) if total is not None else None
             except (TypeError, ValueError):
@@ -847,14 +851,25 @@ class InvoServer:
     def get_player_balance(
         self, *, player_email: Optional[str] = None, player_id: Any = None
     ) -> PlayerBalanceResult:
-        """Read a player's currency balances, by email or player id (game-secret)."""
-        if player_id is not None and str(player_id).strip():
-            path = f"/api/player-balances/player/{quote(str(player_id), safe='')}"
-        elif _is_present(player_email):
+        """Read a player's currency balances by EMAIL (game-secret).
+
+        Lookup is by email only -- there is no by-id balance route on the backend
+        (``player_id`` is a per-game internal id), so passing ``player_id`` raises. For a
+        client-side read use the browser ``InvoClient.getBalance()`` (identity from the token).
+        """
+        if _is_present(player_email):
             path = f"/api/player-balances/player/by-email/{quote(player_email, safe='')}"  # type: ignore[arg-type]
+        elif player_id is not None and str(player_id).strip():
+            raise InvoError(
+                "get_player_balance is by player_email only -- there is no by-id balance "
+                "route. Use the browser InvoClient.getBalance() (player token), or pass "
+                "player_email here.",
+                code="INVALID_INPUT",
+                status=0,
+            )
         else:
             raise InvoError(
-                "get_player_balance requires a player_email or player_id.",
+                "get_player_balance requires a player_email.",
                 code="INVALID_INPUT",
                 status=0,
             )

{invonetwork-2.1.2 → invonetwork-2.2.0}/tests/test_balance_identities.py

@@ -46,11 +46,13 @@ class TestPlayerBalance:
         assert b.available_balance == "1250.00"
         assert b.total_balance == "1250.00"
 
-    def test_by_player_id_uses_the_id_path(self):
+    def test_by_player_id_is_rejected(self):
+        # there is no by-id balance route on the backend -> clear error, no network call
         server, calls = _server(lambda r, i: fake_response(200, {"balances": []}))
-        r = server.get_player_balance(player_id=12345)
-        assert calls[0].url == f"{BASE}/api/player-balances/player/12345"
-        assert r.balances == []
+        with pytest.raises(InvoError) as ei:
+            server.get_player_balance(player_id=12345)
+        assert ei.value.code == "INVALID_INPUT"
+        assert len(calls) == 0
 
     def test_requires_email_or_id(self):
         server, calls = _server(lambda r, i: fake_response(200, {}))

{invonetwork-2.1.2 → invonetwork-2.2.0}/tests/test_reads.py

@@ -99,15 +99,25 @@ class TestLightValidation:
 
     @pytest.mark.parametrize(
         "player_phone",
-        ["", "  ", "5555550100", "(555) 555-0100", "+0123", "+1 555 555 0100", None],
+        ["", "  ", "5555550100", "(555) 555-0100", "+0123", "+1 555 555 0100"],
     )
-    def test_mint_requires_e164_phone(self, player_phone):
+    def test_mint_validates_e164_phone_when_provided(self, player_phone):
+        # a provided-but-malformed phone still throws...
         server, calls = _server(lambda r, i: fake_response(200, {}))
         with pytest.raises(InvoError) as ei:
             server.mint_player_token(player_email="p@x.com", player_phone=player_phone)
         assert ei.value.code == "INVALID_INPUT"
         assert len(calls) == 0
 
+    def test_mint_email_only_omits_phone(self):
+        # ...but phone is optional: an existing email-only player mints, no player_phone sent
+        server, calls = _server(
+            lambda r, i: fake_response(200, {"token": "t", "expires_at": "e", "identity_id": "id"})
+        )
+        r = server.mint_player_token(player_email="p@x.com")
+        assert r.token == "t"
+        assert calls[0].body == {"player_email": "p@x.com"}
+
     def test_create_checkout_requires_email(self):
         server, calls = _server(lambda r, i: fake_response(200, {}))
         with pytest.raises(InvoError) as ei:

{invonetwork-2.1.2 → invonetwork-2.2.0}/tests/test_server.py

@@ -72,6 +72,22 @@ class TestRequestMapping:
         assert r.transaction_id == "txn_1"
         assert r.verification_method == "in_app"
 
+    def test_initiate_send_by_phone_alone_omits_receiver_email(self):
+        transport, calls = mock_transport(
+            lambda r, i: fake_response(201, {"transaction_id": "txn_p", "verification_method": "sms"})
+        )
+        make_server(transport).initiate_send(
+            client_request_id="req_p",
+            sender_player_name="S",
+            sender_player_email="s@x.com",
+            sender_player_phone="+15555550100",
+            receiver_player_phone="+15555550111",  # no receiver_player_email
+            receiving_game_id=1,
+            amount="5",
+        )
+        assert calls[0].body["receiver_player_phone"] == "+15555550111"
+        assert "receiver_player_email" not in calls[0].body
+
     def test_initiate_transfer_maps_body(self):
         transport, calls = mock_transport(
             lambda r, i: fake_response(201, {"transaction_id": "txn_2", "verification_method": "sms"})