Add ExistPhone resource (#424)

* Add ExistPhone resource

* Add PhoneVerificationAssociation resource

* Update cuenca-validations to version 2.1.12 in requirements.txt

* Update version to 2.1.7 in version.py

* Refactor ExistPhone and PhoneVerificationAssociation resources to ExistPhones and PhoneVerificationAssociations

* Update version to 2.1.7 in version.py

Author: gmorales96

cuenca/__init__.py

@@ -45,6 +45,8 @@
     'TermsOfService',
     'UserTOSAgreement',
     'PostalCodes',
+    'ExistPhones',
+    'PhoneVerificationAssociations',
 ]
 
 from . import http
@@ -64,6 +66,7 @@
     CurpValidation,
     Deposit,
     Endpoint,
+    ExistPhones,
     File,
     FileBatch,
     Identity,
@@ -73,6 +76,7 @@
     LimitedWallet,
     LoginToken,
     Otp,
+    PhoneVerificationAssociations,
     Platform,
     PostalCodes,
     Questionnaires,

cuenca/resources/__init__.py

@@ -16,13 +16,15 @@
     'Endpoint',
     'File',
     'FileBatch',
+    'ExistPhones',
     'Identity',
     'IdentityEvent',
     'KYCValidation',
     'LimitedWallet',
     'LoginToken',
     'Otp',
     'Platform',
+    'PhoneVerificationAssociation',
     'Questionnaires',
     'Saving',
     'ServiceProvider',
@@ -58,6 +60,7 @@
 from .curp_validations import CurpValidation
 from .deposits import Deposit
 from .endpoints import Endpoint
+from .exist_phones import ExistPhones
 from .file_batches import FileBatch
 from .files import File
 from .identities import Identity
@@ -67,6 +70,7 @@
 from .limited_wallets import LimitedWallet
 from .login_tokens import LoginToken
 from .otps import Otp
+from .phone_verification_associations import PhoneVerificationAssociations
 from .platforms import Platform
 from .postal_codes import PostalCodes
 from .questionnaires import Questionnaires
@@ -132,6 +136,7 @@
     JwtToken,
     TermsOfService,
     UserTOSAgreement,
+    PhoneVerificationAssociations,
 ]
 for resource_cls in resource_classes:
     RESOURCES[resource_cls._resource] = resource_cls  # type: ignore

cuenca/resources/exist_phones.py

@@ -0,0 +1,12 @@
+from typing import ClassVar
+
+from pydantic_extra_types.phone_numbers import PhoneNumber
+
+from .base import Retrievable
+
+
+class ExistPhones(Retrievable):
+    _resource: ClassVar = 'exist_phones'
+
+    id: PhoneNumber
+    exist: bool

cuenca/resources/phone_verification_associations.py

@@ -0,0 +1,26 @@
+import datetime as dt
+from typing import ClassVar
+
+from cuenca_validations.types.requests import (
+    PhoneVerificationAssociationRequest,
+)
+
+from ..http import Session, session as global_session
+from .base import Creatable
+
+
+class PhoneVerificationAssociations(Creatable):
+    _resource: ClassVar = 'phone_verification_associations'
+
+    verification_id: str
+    user_id: str
+    created_at: dt.datetime
+
+    @classmethod
+    def create(
+        cls, verification_id: str, session: Session = global_session
+    ) -> 'PhoneVerificationAssociations':
+        req = PhoneVerificationAssociationRequest(
+            verification_id=verification_id
+        )
+        return cls._create(session=session, **req.model_dump())

cuenca/version.py

@@ -1,3 +1,3 @@
-__version__ = '2.1.6'
+__version__ = '2.1.7'
 CLIENT_VERSION = __version__
 API_VERSION = '2020-03-19'

requirements.txt

@@ -1,3 +1,3 @@
 requests==2.32.3
-cuenca-validations==2.1.11
+cuenca-validations==2.1.12
 pydantic-extra-types==2.10.2

tests/resources/cassettes/test_exist_phone_retrieve.yaml

@@ -0,0 +1,40 @@
+interactions:
+- request:
+    body: null
+    headers:
+      User-Agent:
+      - cuenca-python/2.1.7.dev2
+      X-Cuenca-Api-Version:
+      - '2020-03-19'
+    method: GET
+    uri: https://sandbox.cuenca.com/exist_phones/+527331256958
+  response:
+    body:
+      string: '{"id":"+527331256958","exist":true}'
+    headers:
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '35'
+      Content-Type:
+      - application/json
+      Date:
+      - Thu, 17 Jul 2025 18:34:19 GMT
+      X-Request-Time:
+      - 'value: 0.041'
+      x-amz-apigw-id:
+      - N3dG4EzACYcEofg=
+      x-amzn-Remapped-Connection:
+      - keep-alive
+      x-amzn-Remapped-Content-Length:
+      - '35'
+      x-amzn-Remapped-Date:
+      - Thu, 17 Jul 2025 18:34:19 GMT
+      x-amzn-Remapped-Server:
+      - nginx/1.28.0
+      x-amzn-RequestId:
+      - 51d8507c-c023-4b91-aa52-a6bdc499df89
+    status:
+      code: 200
+      message: OK
+version: 1

tests/resources/cassettes/test_phone_verification_association_create.yaml

@@ -0,0 +1,46 @@
+interactions:
+- request:
+    body: '{"verification_id": "VEeCjasQQWQM-Hr-odTGoKoQ"}'
+    headers:
+      Authorization:
+      - DUMMY
+      Content-Length:
+      - '47'
+      Content-Type:
+      - application/json
+      User-Agent:
+      - cuenca-python/2.1.7.dev2
+      X-Cuenca-Api-Version:
+      - '2020-03-19'
+    method: POST
+    uri: https://sandbox.cuenca.com/phone_verification_associations
+  response:
+    body:
+      string: '{"id":"PVuzCh7IsESSyGxyMdjgRY3A","verification_id":"VEeCjasQQWQM-Hr-odTGoKoQ","user_id":"USS2gTzkh_Sm2ZPZGtfNOK_Q","created_at":"2025-07-21T17:07:04.776955"}'
+    headers:
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '157'
+      Content-Type:
+      - application/json
+      Date:
+      - Mon, 21 Jul 2025 17:07:04 GMT
+      X-Request-Time:
+      - 'value: 0.487'
+      x-amz-apigw-id:
+      - OEcE3FGUCYcEvbw=
+      x-amzn-Remapped-Connection:
+      - keep-alive
+      x-amzn-Remapped-Content-Length:
+      - '157'
+      x-amzn-Remapped-Date:
+      - Mon, 21 Jul 2025 17:07:04 GMT
+      x-amzn-Remapped-Server:
+      - nginx/1.28.0
+      x-amzn-RequestId:
+      - f10e5016-1ce3-429d-9d00-027a4d018c71
+    status:
+      code: 201
+      message: Created
+version: 1

tests/resources/test_exist_phone.py

@@ -0,0 +1,11 @@
+import pytest
+
+from cuenca import ExistPhones
+
+
+@pytest.mark.vcr
+def test_exist_phone_retrieve():
+    phone_number = '+527331256958'
+    exist_phone: ExistPhones = ExistPhones.retrieve(phone_number)
+    assert exist_phone.id == phone_number
+    assert exist_phone.exist

tests/resources/test_phone_verification_association.py

@@ -0,0 +1,13 @@
+import pytest
+
+from cuenca import PhoneVerificationAssociations
+
+
+@pytest.mark.vcr
+def test_phone_verification_association_create():
+
+    phone_verification_association = PhoneVerificationAssociations.create(
+        verification_id='VEeCjasQQWQM-Hr-odTGoKoQ',
+    )
+    assert phone_verification_association.verification_id
+    assert phone_verification_association.user_id