belvo.resources.links

  1import warnings
  2from typing import Dict, List, Optional, Union
  3
  4from belvo.enums import AccessMode
  5from belvo.resources.base import Resource
  6
  7
  8class Links(Resource):
  9    endpoint = "/api/links/"
 10
 11    def create(
 12        self,
 13        institution: str,
 14        username: str,
 15        password: str,
 16        *,
 17        username2: str = None,
 18        username3: str = None,
 19        password2: str = None,
 20        token: str = None,
 21        save_data: bool = True,
 22        raise_exception: bool = False,
 23        access_mode: Optional[AccessMode] = None,
 24        username_type: str = None,
 25        external_id: str = None,
 26    ) -> Union[List[Dict], Dict]:
 27        """Register a new Link
 28
 29        Register a new link with your Belvo account. For in-depth information for all the request parameters, please see our [Links API documentation](https://developers.belvo.com/reference/registerlink).
 30
 31        <div style="background-color:#f4f6f8; border-left: 6px solid #0663F9;padding: 12px;margin-left: 25px; border-radius: 4px; margin-right: 25px">
 32        <strong>Info:</strong> We really recommend using our Connect Widget to create links. It'll save you a lot of headaches!.
 33        </div>
 34
 35
 36        Args:
 37            institution (str): The Belvo name for the institution.
 38            username (str): The end-user's username used to log in to the institution.
 39            password (str): The end-user's password used to log in to the institution.
 40            username2 (str, optional): The end-user's second username used to log in to the institution. Defaults to None.
 41            username3 (str, optional): The end-user's third username used to log in to the institution. Defaults to None.
 42            password2 (str, optional): The end-user's second password used to log in to the institution. Defaults to None.
 43            token (str, optional): The MFA token required by the bank to log in. We do not recommend sending the authentication token in the same request as registering the user. See our Handling multi-factor authentication article for more information and best practices. Defaults to None.
 44            save_data (bool, optional): Indicates whether or not to persist the data in Belvo. Defaults to `True`.
 45            raise_exception (bool, optional): Indicates whether to raise an exception or return the API error. Defaults to `False`.
 46            access_mode (Optional[AccessMode], optional): The type of link to create. Defaults to None.
 47            username_type (str, optional): Type of document to be used as a username. Defaults to None.
 48            external_id (str, optional): An additional identifier for the link, provided by you, to store in the Belvo database. Defaults to None.
 49
 50        Returns:
 51            Union[List[Dict], Dict]: For more information on the response from the API, see our [Links API documentation](https://developers.belvo.com/reference/registerlink).
 52        """
 53
 54        data = {
 55            "institution": institution,
 56            "username": username,
 57            "password": password,
 58            "save_data": save_data,
 59            "access_mode": access_mode and access_mode.value,
 60            "username2": username2,
 61            "username3": username3,
 62            "password2": password2,
 63            "token": token,
 64            "username_type": username_type,
 65            "external_id": external_id,
 66        }
 67
 68        clean_data = {key: value for key, value in data.items() if value}
 69
 70        return self.session.post(self.endpoint, data=clean_data, raise_exception=raise_exception)
 71
 72    def update(
 73        self,
 74        link: str,
 75        *,
 76        password: str = None,
 77        password2: str = None,
 78        token: str = None,
 79        save_data: bool = True,
 80        raise_exception: bool = False,
 81        username_type: str = None,
 82    ) -> Union[List[Dict], Dict]:
 83        """Update a link's credentials
 84
 85        Update the credentials of a specific link. If the successfully updated link is a recurrent one, we automatically trigger an update of the link. If we find fresh data, you'll receive historical update webhooks.
 86
 87        Args:
 88            link (str): The link.id you want to update.
 89            password (str): The end-user's password used to log in to the institution.
 90            password2 (str, optional): The end-user's second password used to log in to the institution. Defaults to None.
 91            token (str, optional): The MFA token required by the bank to log in. We do not recommend sending the authentication token in the same request as registering the user. See our Handling multi-factor authentication article for more information and best practices. Defaults to None.
 92            save_data (bool, optional): Indicates whether or not to persist the data in Belvo. Defaults to `True`.
 93            raise_exception (bool, optional): Indicates whether to raise an exception or return the API error. Defaults to `False`.
 94            username_type (str, optional): Type of document to be used as a username. Defaults to None.
 95
 96        Returns:
 97            Union[List[Dict], Dict]: For more information on the response from the API, see our [Links API documentation](https://developers.belvo.com/reference/patchlinks).
 98        """
 99
100        data = {
101            "password": password,
102            "save_data": save_data,
103            "password2": password2,
104            "token": token,
105            "username_type": username_type,
106        }
107
108        clean_data = {key: value for key, value in data.items() if value}
109
110        return self.session.put(
111            self.endpoint, id=link, data=clean_data, raise_exception=raise_exception
112        )
113
114    def token(
115        self, link: str, scopes: str, *, widget: dict = None, raise_exception: bool = False
116    ) -> Union[List[Dict], Dict]:
117        from belvo.resources import WidgetToken
118
119        warnings.warn(
120            "Please make use of `client.WidgetToken.create(link=<link:uuid>)` "
121            "to request a link scoped token instead.",
122            DeprecationWarning,
123        )
124
125        token = WidgetToken(self.session)
126        return token.create(
127            scopes=scopes, link=link, widget=widget, raise_exception=raise_exception
128        )
129
130    def patch(
131        self, link: str, *, access_mode: Optional[AccessMode] = None, raise_exception: bool = False
132    ) -> Union[List[Dict], Dict]:
133        """Update a link's access_mode
134
135        Args:
136            link (str): The `link.id` you want to update the `access_mode` for (UUID).
137            access_mode (Optional[AccessMode], optional): The new `access_mode` you want to assign to the link. Can be either `single` or `recurrent`. Defaults to None.
138            raise_exception (bool, optional): Indicates whether to raise an exception or return the API error. Defaults to `False`.
139
140        Returns:
141            Dict: The details of the object.
142        """
143        data = {"access_mode": access_mode and access_mode.value}
144        return self.session.patch(
145            f"{self.endpoint}{link}/", data=data, raise_exception=raise_exception
146        )