invonetwork 2.2.0__tar.gz → 2.3.0__tar.gz

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

@@ -3,6 +3,24 @@
 All notable changes to this project are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0] - 2026-07-07
+
+### Added
+
+**Claim-time phone-share approval.** The backend closed a security gap: claiming a phone-routed
+transfer now authorizes the collecting identity against the receiver phone before crediting, so
+`claim_transfer` / `claim_currency` can now raise the phone-share `409
+PHONE_SHARE_APPROVAL_REQUIRED` (previously only registration/mint did). `is_phone_share_approval_required`
+already classifies it — no consumer code must change — but:
+
+- New **`InvoError.phone_share_last4`** surfaces the `phone_last4` from the 409 body for the UI.
+- `is_phone_share_approval_required` docs + the claim method docstrings + README now spell out
+  the claim-time path: **not a failure** — the money is held and the phone owner is texted; show
+  `err.message`, then re-issue the same claim once approved (succeeds idempotently); on
+  denial/expiry the sender is refunded.
+
+Additive, no breaking changes; affects all rails' claim paths.
+
 ## [2.2.0] - 2026-07-07
 
 ### Changed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: invonetwork
-Version: 2.2.0
+Version: 2.3.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
@@ -50,14 +50,12 @@ server-side counterpart to the [INVO JS/Web SDK](https://www.npmjs.com/package/@
 same endpoints, same field mappings, and the same webhook HMAC scheme, so both hit the
 same live backend interchangeably.
 
-> **Status:** `2.1.1` — stable, published on PyPI (`pip install invonetwork`). The backend it
+> **Status:** `2.3.0` — stable, published on PyPI (`pip install invonetwork`). The backend it
 > 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** 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.
+> Recent highlights: **2.2.0** reconciled with the backend (`mint_player_token` is a session
+> mint — `player_phone` optional; send-by-phone-alone; email-only `get_player_balance`);
+> **2.3.0** surfaces the claim-time phone-share `409` on `claim_transfer`/`claim_currency`
+> (+ `err.phone_share_last4`). Full history in the [CHANGELOG](CHANGELOG.md).
 > Canonical partner reference: **https://docs.invo.network**.
 
 ## Highlights
@@ -592,7 +590,7 @@ Classifiers:
 | `.is_receiver_not_enrolled` | recipient has no passkey → switch to claim-code entry |
 | `.is_insufficient_balance` | item purchase failed (400); `required_amount` + `current_balance` on `.body` |
 | `.is_duplicate_request` | idempotency-keyed request was a duplicate (409) |
-| `.is_phone_share_approval_required` | claim needs phone-share approval before it can complete (409) → run the phone-share OTP handshake |
+| `.is_phone_share_approval_required` | phone needs owner approval — at register/mint **or** at `claim_transfer`/`claim_currency` (contested receiver phone). Not a failure: money held, phone owner texted. Show `.message` (+ `.phone_share_last4`), re-issue the same claim after approval; sender refunded on denial/expiry |
 | `.is_phone_share_already_approved` | the phone-share (phone, requesting_email) pair was already approved |
 | `.retry_after` | seconds to back off on a 429 throttle |
 | `.is_enrollment_authorization_required` | first-enrollment needs the OTP grant |

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

@@ -5,14 +5,12 @@ server-side counterpart to the [INVO JS/Web SDK](https://www.npmjs.com/package/@
 same endpoints, same field mappings, and the same webhook HMAC scheme, so both hit the
 same live backend interchangeably.
 
-> **Status:** `2.1.1` — stable, published on PyPI (`pip install invonetwork`). The backend it
+> **Status:** `2.3.0` — stable, published on PyPI (`pip install invonetwork`). The backend it
 > 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** 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.
+> Recent highlights: **2.2.0** reconciled with the backend (`mint_player_token` is a session
+> mint — `player_phone` optional; send-by-phone-alone; email-only `get_player_balance`);
+> **2.3.0** surfaces the claim-time phone-share `409` on `claim_transfer`/`claim_currency`
+> (+ `err.phone_share_last4`). Full history in the [CHANGELOG](CHANGELOG.md).
 > Canonical partner reference: **https://docs.invo.network**.
 
 ## Highlights
@@ -547,7 +545,7 @@ Classifiers:
 | `.is_receiver_not_enrolled` | recipient has no passkey → switch to claim-code entry |
 | `.is_insufficient_balance` | item purchase failed (400); `required_amount` + `current_balance` on `.body` |
 | `.is_duplicate_request` | idempotency-keyed request was a duplicate (409) |
-| `.is_phone_share_approval_required` | claim needs phone-share approval before it can complete (409) → run the phone-share OTP handshake |
+| `.is_phone_share_approval_required` | phone needs owner approval — at register/mint **or** at `claim_transfer`/`claim_currency` (contested receiver phone). Not a failure: money held, phone owner texted. Show `.message` (+ `.phone_share_last4`), re-issue the same claim after approval; sender refunded on denial/expiry |
 | `.is_phone_share_already_approved` | the phone-share (phone, requesting_email) pair was already approved |
 | `.retry_after` | seconds to back off on a 429 throttle |
 | `.is_enrollment_authorization_required` | first-enrollment needs the OTP grant |

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "invonetwork"
-version = "2.2.0"
+version = "2.3.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.2.0 → invonetwork-2.3.0}/src/invonetwork/errors.py

@@ -120,12 +120,14 @@ class InvoError(Exception):
     def is_phone_share_approval_required(self) -> bool:
         """True if the call needs phone-share approval before it can complete (409).
 
-        Raised by registration/token-mint and by claims when the phone already belongs to
-        another INVO account (same person, new email -- expected, not a failure). The phone
-        holder gets a consent SMS; show "pending approval", then re-issue the identical call
-        once approved (poll ``phone_share_status``, or use ``phone_share_initiate`` /
-        ``phone_share_approve`` for the OTP fallback). ``phone_share_approval_id`` carries
-        the id from the 409 body.
+        Raised by registration/token-mint AND by ``claim_transfer`` / ``claim_currency`` when
+        the receiver phone is contested (the collecting identity isn't yet authorized for it).
+        NOT a failure -- the money is held and the phone owner is texted to approve. Show
+        ``err.message`` verbatim (``phone_share_last4`` names the phone), then RE-ISSUE the same
+        claim once approved (it then succeeds idempotently); on denial/expiry the sender is
+        refunded. (``phone_share_approval_id`` carries the id when the 409 came from the
+        OTP-handshake path; ``phone_share_initiate`` / ``phone_share_approve`` /
+        ``phone_share_status`` drive that fallback.)
         """
         return self.code == "PHONE_SHARE_APPROVAL_REQUIRED"
 
@@ -135,6 +137,12 @@ class InvoError(Exception):
         v = self._body_object().get("approval_id")
         return v if isinstance(v, str) and v else None
 
+    @property
+    def phone_share_last4(self) -> Optional[str]:
+        """Last 4 digits of the phone that must approve (``phone_last4``), for the UI message."""
+        v = self._body_object().get("phone_last4")
+        return v if isinstance(v, str) and v else None
+
     @property
     def is_phone_share_already_approved(self) -> bool:
         """True if the phone-share (phone, requesting_email) pair was already approved."""

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

@@ -50,7 +50,7 @@ from .types import (
 
 __all__ = ["InvoServer"]
 
-DEFAULT_USER_AGENT = "invonetwork-python-sdk/2.2.0 (+https://invo.network)"
+DEFAULT_USER_AGENT = "invonetwork-python-sdk/2.3.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."""
 
@@ -1019,6 +1019,11 @@ class InvoServer:
         ``target_player_id``. Errors surface via :class:`InvoError` (404 unknown code, 403
         phone mismatch, 400 not-claimable/expired/wrong-value, 409
         ``err.is_phone_share_approval_required``, ...).
+
+        The 409 ``is_phone_share_approval_required`` is NOT a failure: the receiver phone is
+        contested, so the money is held and the phone owner is texted to approve. Show
+        ``err.message`` (``err.phone_share_last4`` names the phone), then RE-ISSUE this same
+        claim once approved (it succeeds idempotently); on denial/expiry the sender is refunded.
         """
         body: Dict[str, Any] = {
             "claim_code": claim_code,

{invonetwork-2.2.0 → invonetwork-2.3.0}/tests/test_claim.py

@@ -13,6 +13,32 @@ def _server(responder):
     return make_server(transport, max_retries=0), calls
 
 
+def test_claim_surfaces_claim_time_phone_share_409():
+    # contested receiver phone -> money held, phone owner texted; not a failure
+    server, _ = _server(
+        lambda r, i: fake_response(
+            409,
+            {
+                "status": "approval_required",
+                "code": "PHONE_SHARE_APPROVAL_REQUIRED",
+                "message": "One more step to collect. We've texted the phone on file to confirm.",
+                "phone_last4": "6789",
+                "retry_after_approval": True,
+            },
+        )
+    )
+    with pytest.raises(InvoError) as ei:
+        server.claim_currency(
+            claim_code="CLAIM-9",
+            receiver_player_name="R",
+            receiver_player_email="r@x.com",
+            receiver_player_phone="+15555550111",
+        )
+    assert ei.value.is_phone_share_approval_required
+    assert "One more step" in ei.value.message
+    assert ei.value.phone_share_last4 == "6789"
+
+
 def test_claim_transfer_maps_body_and_success_result():
     server, calls = _server(
         lambda r, i: fake_response(