✨ webserver API: get payment invoice link (#4870)

Author: pcrespov

packages/postgres-database/src/simcore_postgres_database/migration/versions/7777d181dc1f_new_invoice_url_column_in_payments_.py

@@ -0,0 +1,29 @@
+"""new invoice_url column in payments_transaction table
+
+Revision ID: 7777d181dc1f
+Revises: 542e6ee8a8ea
+Create Date: 2023-10-16 16:19:26.657533+00:00
+
+"""
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "7777d181dc1f"
+down_revision = "542e6ee8a8ea"
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column(
+        "payments_transactions", sa.Column("invoice_url", sa.String(), nullable=True)
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column("payments_transactions", "invoice_url")
+    # ### end Alembic commands ###

packages/postgres-database/src/simcore_postgres_database/models/payments_transactions.py

@@ -83,6 +83,12 @@ class PaymentTransactionState(str, enum.Enum):
         nullable=True,
         doc="Extra comment on this payment (optional)",
     ),
+    sa.Column(
+        "invoice_url",
+        sa.String,
+        nullable=True,
+        doc="Link to invoice of this transaction. Available when completed",
+    ),
     #
     # States
     #

packages/postgres-database/src/simcore_postgres_database/utils_payments.py

@@ -1,7 +1,8 @@
 import datetime
+import logging
 from dataclasses import dataclass
 from decimal import Decimal
-from typing import TypeAlias
+from typing import Final, TypeAlias
 
 import sqlalchemy as sa
 from aiopg.sa.connection import SAConnection
@@ -10,11 +11,16 @@
 from . import errors
 from .models.payments_transactions import PaymentTransactionState, payments_transactions
 
-PaymentID: TypeAlias = str
+_logger = logging.getLogger(__name__)
+
 
+PaymentID: TypeAlias = str
 PaymentTransactionRow: TypeAlias = RowProxy
 
 
+UNSET: Final[str] = "__UNSET__"
+
+
 @dataclass
 class PaymentFailure:
     payment_id: str
@@ -75,6 +81,7 @@ async def update_payment_transaction_state(
     payment_id: str,
     completion_state: PaymentTransactionState,
     state_message: str | None = None,
+    invoice_url: str | None = UNSET,
 ) -> PaymentTransactionRow | PaymentNotFound | PaymentAlreadyAcked:
     """ACKs payment by updating state with SUCCESS, ..."""
     if completion_state == PaymentTransactionState.PENDING:
@@ -85,6 +92,17 @@ async def update_payment_transaction_state(
     if state_message:
         optional["state_message"] = state_message
 
+    if completion_state == PaymentTransactionState.SUCCESS and invoice_url is None:
+        _logger.warning(
+            "Payment %s completed as %s without invoice (%s)",
+            payment_id,
+            state_message,
+            f"{invoice_url=}",
+        )
+
+    if invoice_url != UNSET:
+        optional["invoice_url"] = invoice_url
+
     async with connection.begin():
         row = await (
             await connection.execute(

packages/postgres-database/tests/test_models_payments_transactions.py

@@ -3,16 +3,15 @@
 # pylint: disable=unused-variable
 # pylint: disable=too-many-arguments
 
-import datetime
 import decimal
 from collections.abc import Callable
-from typing import Any
 
 import pytest
 import sqlalchemy as sa
 from aiopg.sa.connection import SAConnection
 from aiopg.sa.result import RowProxy
-from pytest_simcore.helpers.rawdata_fakers import FAKE
+from faker import Faker
+from pytest_simcore.helpers.rawdata_fakers import random_payment_transaction, utcnow
 from simcore_postgres_database.models.payments_transactions import (
     PaymentTransactionState,
     payments_transactions,
@@ -27,32 +26,6 @@
 )
 
 
-def utcnow() -> datetime.datetime:
-    return datetime.datetime.now(tz=datetime.timezone.utc)
-
-
-def random_payment_transaction(
-    **overrides,
-) -> dict[str, Any]:
-    """Generates Metadata + concept/info (excludes state)"""
-    data = {
-        "payment_id": FAKE.uuid4(),
-        "price_dollars": "123456.78",
-        "osparc_credits": "123456.78",
-        "product_name": "osparc",
-        "user_id": FAKE.pyint(),
-        "user_email": FAKE.email().lower(),
-        "wallet_id": 1,
-        "comment": "Free starting credits",
-        "initiated_at": utcnow(),
-    }
-    # state is not added on purpose
-    assert set(data.keys()).issubset({c.name for c in payments_transactions.columns})
-
-    data.update(overrides)
-    return data
-
-
 async def test_numerics_precission_and_scale(connection: SAConnection):
     # https://docs.sqlalchemy.org/en/20/core/type_basics.html#sqlalchemy.types.Numeric
     # precision: This parameter specifies the total number of digits that can be stored, both before and after the decimal point.
@@ -117,6 +90,13 @@ async def test_init_transaction_sets_it_as_pending(
     }
 
 
+@pytest.fixture
+def invoice_url(faker: Faker, expected_state: PaymentTransactionState) -> str | None:
+    if expected_state == PaymentTransactionState.SUCCESS:
+        return faker.url()
+    return None
+
+
 @pytest.mark.parametrize(
     "expected_state,expected_message",
     [
@@ -137,6 +117,7 @@ async def test_complete_transaction(
     payment_id: str,
     expected_state: PaymentTransactionState,
     expected_message: str | None,
+    invoice_url: str | None,
 ):
     await init_transaction(payment_id)
 
@@ -145,6 +126,7 @@ async def test_complete_transaction(
         payment_id=payment_id,
         completion_state=expected_state,
         state_message=expected_message,
+        invoice_url=invoice_url,
     )
 
     assert isinstance(payment_row, PaymentTransactionRow)

packages/pytest-simcore/src/pytest_simcore/helpers/rawdata_fakers.py

@@ -205,3 +205,30 @@ def random_payment_method(
 
     data.update(overrides)
     return data
+
+
+def random_payment_transaction(
+    **overrides,
+) -> dict[str, Any]:
+    """Generates Metadata + concept/info (excludes state)"""
+    from simcore_postgres_database.models.payments_transactions import (
+        payments_transactions,
+    )
+
+    # initiated
+    data = {
+        "payment_id": FAKE.uuid4(),
+        "price_dollars": "123456.78",
+        "osparc_credits": "123456.78",
+        "product_name": "osparc",
+        "user_id": FAKE.pyint(),
+        "user_email": FAKE.email().lower(),
+        "wallet_id": 1,
+        "comment": "Free starting credits",
+        "initiated_at": utcnow(),
+    }
+    # state is not added on purpose
+    assert set(data.keys()).issubset({c.name for c in payments_transactions.columns})
+
+    data.update(overrides)
+    return data