pagopar 1.0.0__tar.gz

pagopar-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Alan Bogarin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pagopar-1.0.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: pagopar
+Version: 1.0.0
+Summary: Asynchronous API wrapper for Pagopar written in Python.
+Author-email: AlanBogarin <bogarin01alan@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AlanBogarin/pagopar
+Project-URL: Issues, https://github.com/AlanBogarin/pagopar/issues
+Keywords: pagopar,api,async
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp
+Requires-Dist: msgspec
+Dynamic: license-file
+
+# Pagopar
+
+Client to consume pagopar.com REST API, created based on [official documentation](https://soporte.pagopar.com/portal/es/kb).
+
+Asynchronous Python wrapper for the Pagopar API, designed for efficiency and type safety.
+
+## Installation
+
+```bash
+pip install pagopar
+```
+
+## Configuration
+
+You can configure the application by passing your credentials directly or by using environment variables.
+
+### Environment Variables
+
+Set the following environment variables:
+
+- `PAGOPAR_PRIVATE_TOKEN`
+- `PAGOPAR_PUBLIC_TOKEN`
+
+### Manual Initialization
+
+```python
+from pagopar import initialize_app
+
+app = initialize_app(
+    private_token="your_private_token",
+    public_token="your_public_token"
+)
+```
+
+## Usage Examples
+
+### Initialize Application
+
+```python
+import asyncio
+from pagopar import initialize_app, close_app
+
+# Initialize with environment variables or pass tokens here
+app = initialize_app()
+other = initialize_app(
+    private_token="other_private_token",
+    public_token="other_public_token",
+    # When needs multiple instances, set the name as a unique identifier
+    name="other-app",
+)
+
+async def main():
+    # Your logic here
+    await close_app()
+    await close_app(other)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Create a Transaction
+
+Generate a payment link for a user.
+
+```python
+import datetime
+from pagopar import checkout, enums
+
+async def create_order():
+    # Define items
+    item = checkout.Item(
+        name="Product Name",
+        description="Product Description",
+        price=150000,
+        quantity=1,
+        total_price=150000,
+        product_id=123,
+        image_url="https://example.com/image.png"
+    )
+
+    # Start transaction
+    transaction = await checkout.start_transaction(
+        commerce_order_id="ORDER-001",
+        items=[item],
+        amount=150000,
+        payment_type=enums.PaymentType.PAGO_EXPRESS,
+        max_payment_date=datetime.datetime.now() + datetime.timedelta(days=1),
+        buyer_name="John Doe",
+        buyer_email="john.doe@example.com",
+        buyer_phone="0981123456",
+        buyer_document="1234567",
+        buyer_document_type=enums.DocumentType.CI
+    )
+
+    # Get checkout URL
+    url = checkout.pagopar_checkout_url(transaction.order_id)
+    print(f"Checkout URL: {url}")
+```
+
+### Check Payment Status
+
+Validate if a payment notification is authentic.
+
+```python
+from pagopar import checkout
+
+def validate_pagopar_notification(notification_token: str, order_id: str) -> bool:
+    return checkout.check_pagopar_payment(notification_token, order_id)
+```
+
+### Get Order Details
+
+Retrieve the current status of an order.
+
+```python
+async def check_order_status(order_hash: str):
+    order = await checkout.get_order(order_hash)
+    print(f"Order Status: {'Paid' if order.paid else 'Pending'}")
+```
+
+## Modules
+
+- **checkout**: Transaction initialization, payment link generation, and order status checking.
+- **courier**: Integration with shipping providers (AEX, Mobi) and freight calculation.
+- **login**: Pagopar Login / Registration linking flow.
+- **payment**: Recurring payments and tokenized card management.
+- **subs**: Subscription notifications parsing.
+- **sync**: Product and inventory synchronization with Pagopar.

pagopar-1.0.0/README.md

@@ -0,0 +1,128 @@
+# Pagopar
+
+Client to consume pagopar.com REST API, created based on [official documentation](https://soporte.pagopar.com/portal/es/kb).
+
+Asynchronous Python wrapper for the Pagopar API, designed for efficiency and type safety.
+
+## Installation
+
+```bash
+pip install pagopar
+```
+
+## Configuration
+
+You can configure the application by passing your credentials directly or by using environment variables.
+
+### Environment Variables
+
+Set the following environment variables:
+
+- `PAGOPAR_PRIVATE_TOKEN`
+- `PAGOPAR_PUBLIC_TOKEN`
+
+### Manual Initialization
+
+```python
+from pagopar import initialize_app
+
+app = initialize_app(
+    private_token="your_private_token",
+    public_token="your_public_token"
+)
+```
+
+## Usage Examples
+
+### Initialize Application
+
+```python
+import asyncio
+from pagopar import initialize_app, close_app
+
+# Initialize with environment variables or pass tokens here
+app = initialize_app()
+other = initialize_app(
+    private_token="other_private_token",
+    public_token="other_public_token",
+    # When needs multiple instances, set the name as a unique identifier
+    name="other-app",
+)
+
+async def main():
+    # Your logic here
+    await close_app()
+    await close_app(other)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Create a Transaction
+
+Generate a payment link for a user.
+
+```python
+import datetime
+from pagopar import checkout, enums
+
+async def create_order():
+    # Define items
+    item = checkout.Item(
+        name="Product Name",
+        description="Product Description",
+        price=150000,
+        quantity=1,
+        total_price=150000,
+        product_id=123,
+        image_url="https://example.com/image.png"
+    )
+
+    # Start transaction
+    transaction = await checkout.start_transaction(
+        commerce_order_id="ORDER-001",
+        items=[item],
+        amount=150000,
+        payment_type=enums.PaymentType.PAGO_EXPRESS,
+        max_payment_date=datetime.datetime.now() + datetime.timedelta(days=1),
+        buyer_name="John Doe",
+        buyer_email="john.doe@example.com",
+        buyer_phone="0981123456",
+        buyer_document="1234567",
+        buyer_document_type=enums.DocumentType.CI
+    )
+
+    # Get checkout URL
+    url = checkout.pagopar_checkout_url(transaction.order_id)
+    print(f"Checkout URL: {url}")
+```
+
+### Check Payment Status
+
+Validate if a payment notification is authentic.
+
+```python
+from pagopar import checkout
+
+def validate_pagopar_notification(notification_token: str, order_id: str) -> bool:
+    return checkout.check_pagopar_payment(notification_token, order_id)
+```
+
+### Get Order Details
+
+Retrieve the current status of an order.
+
+```python
+async def check_order_status(order_hash: str):
+    order = await checkout.get_order(order_hash)
+    print(f"Order Status: {'Paid' if order.paid else 'Pending'}")
+```
+
+## Modules
+
+- **checkout**: Transaction initialization, payment link generation, and order status checking.
+- **courier**: Integration with shipping providers (AEX, Mobi) and freight calculation.
+- **login**: Pagopar Login / Registration linking flow.
+- **payment**: Recurring payments and tokenized card management.
+- **subs**: Subscription notifications parsing.
+- **sync**: Product and inventory synchronization with Pagopar.

pagopar-1.0.0/pagopar/__init__.py

@@ -0,0 +1,15 @@
+"""
+Pagopar API Wrapper
+===================
+
+Asynchronous Python wrapper for the Pagopar API.
+
+This library provides a simple and efficient way to interact with Pagopar services,
+including payment processing, order management, and recurring payments.
+"""
+from pagopar.app import *
+
+from pagopar import errors as errors
+from pagopar import http as http
+
+__version__ = "1.0.0"

pagopar-1.0.0/pagopar/app.py

@@ -0,0 +1,199 @@
+import os
+import threading
+
+import aiohttp
+
+from pagopar import http as _http
+
+__all__ = ("Application", "initialize_app", "get_app", "close_app")
+
+_DEFAULT_APP_NAME = "<DEFAULT>"
+_APP_LOCK = threading.Lock()
+
+_apps: dict[str, "Application"] = {}
+
+
+class Application:
+    """
+    Represents a Pagopar application configuration.
+
+    This class holds credential information and manages the underlying
+    HTTP session used for API requests.
+
+    Parameters
+    ----------
+    name : str
+        Unique identifier for this application instance.
+    private_token : str
+        Commerce private token provided by Pagopar.
+    public_token : str
+        Commerce public token provided by Pagopar.
+    proxy : str, optional
+        Proxy URL to use for network requests.
+    """
+
+    __slots__ = (
+        "_name",
+        "_private_token",
+        "_public_token",
+        "_session",
+        "_session_lock",
+        "proxy",
+    )
+
+    def __init__(
+        self,
+        name: str,
+        private_token: str,
+        public_token: str,
+        proxy: str | None
+    ) -> None:
+        self._name = name
+        self._private_token = private_token
+        self._public_token = public_token
+        self._session: aiohttp.ClientSession | None = None
+        self._session_lock = threading.Lock()
+        self.proxy = proxy
+
+    @property
+    def name(self) -> str:
+        """Application name."""
+        return self._name
+
+    @property
+    def private_token(self) -> str:
+        """Commerce private token."""
+        return self._private_token
+
+    @property
+    def public_token(self) -> str:
+        """Commerce public token."""
+        return self._public_token
+
+    @property
+    def session(self) -> aiohttp.ClientSession:
+        """
+        The aiohttp ClientSession used by this application.
+
+        The session is lazily created when first accessed.
+        """
+        with self._session_lock:
+            if not self._session or self._session.closed:
+                self._session = _http.create_session(self.proxy)
+            return self._session
+
+def initialize_app(
+    private_token: str | None = None,
+    public_token: str | None = None,
+    *,
+    proxy: str | None = None,
+    name: str = _DEFAULT_APP_NAME,
+) -> Application:
+    """
+    Initialize the Pagopar application with credentials.
+
+    If tokens are not provided, the function attempts to read them from
+    environment variables ``PAGOPAR_PRIVATE_TOKEN`` and ``PAGOPAR_PUBLIC_TOKEN``.
+
+    Parameters
+    ----------
+    private_token : str, optional
+        Commerce private token.
+    public_token : str, optional
+        Commerce public token.
+    proxy : str, optional
+        Proxy URL for API requests.
+    name : str, optional
+        Unique name for this application instance. Defaults to a global default name.
+
+    Returns
+    -------
+    Application
+        The initialized application instance.
+
+    Raises
+    ------
+    RuntimeError
+        If credentials are missing (neither provided nor found in environment).
+    ValueError
+        If an application with the same name is already initialized.
+    """
+    if private_token is None or public_token is None:
+        private_token = os.getenv("PAGOPAR_PRIVATE_TOKEN", private_token)
+        public_token = os.getenv("PAGOPAR_PUBLIC_TOKEN", public_token)
+
+    if not (private_token and public_token):
+        raise RuntimeError("Missing pagopar commerce credentials.")
+
+    with _APP_LOCK:
+        if name not in _apps:
+            app = _apps[name] = Application(
+                name,
+                private_token,
+                public_token,
+                proxy,
+            )
+            return app
+
+    if name == _DEFAULT_APP_NAME:
+        raise ValueError(
+            "The default Pagopar app already initialized. If you want to initialize "
+            "multiple applications, give a unique value to the `name` parameter."
+        )
+    raise ValueError(f"Pagopar app named {name!r} already initialized.")
+
+
+def get_app(name: str = _DEFAULT_APP_NAME) -> Application:
+    """
+    Retrieve an initialized application instance by name.
+
+    Parameters
+    ----------
+    name : str, optional
+        The name of the application to retrieve.
+
+    Returns
+    -------
+    Application
+        The requested application instance.
+
+    Raises
+    ------
+    ValueError
+        If no application with the specified name exists.
+    """
+    with _APP_LOCK:
+        if name in _apps:
+            return _apps[name]
+    raise ValueError(f"Pagopar named {name!r} not exists.")
+
+
+async def close_app(app: Application | str | None = None) -> None:
+    """
+    Close an initialized application and its associated HTTP session.
+
+    Parameters
+    ----------
+    app : Application, str, optional
+        The object or name of the application to close.
+
+    Raises
+    ------
+    ValueError
+        If no application with the specified name exists.
+    """
+    app = check_initialized_app(app)
+    with _APP_LOCK:
+        del _apps[app.name]
+    if app._session and not app._session.closed:
+        await app.session.close()
+
+
+def check_initialized_app(app: Application | str | None) -> Application:
+    if app is None:
+        return get_app()
+    if isinstance(app, str):
+        app = get_app(app)
+    elif app is not get_app(app.name):
+        raise ValueError("Application instance not initialized via the pagopar module.")
+    return app