velocity-python 0.2.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.2.0"
+__version__ = version = "0.2.1"
 
 import importlib as _importlib
 

velocity/aws/tests/test_sms.py

@@ -55,10 +55,13 @@ class TestParseInboundEvent(unittest.TestCase):
         )
         messages = parse_inbound_event(event)
         self.assertEqual(len(messages), 2)
-        self.assertEqual(messages[1].media_urls, [
-            "s3://bucket/media/one.jpg",
-            "s3://bucket/media/two.jpg",
-        ])
+        self.assertEqual(
+            messages[1].media_urls,
+            [
+                "s3://bucket/media/one.jpg",
+                "s3://bucket/media/two.jpg",
+            ],
+        )
 
     def test_bare_payload_dict(self):
         messages = parse_inbound_event(_payload())

velocity/misc/pdf.py

@@ -214,7 +214,10 @@ def page_css(page: PageOptions) -> str:
     size = _css_page_size(page)
     top, right, bottom, left = page.margins()
     parts = [f"size: {size};", f"margin: {top} {right} {bottom} {left};"]
-    for slot, text in (("bottom-right", page.footer_right), ("bottom-center", page.footer_center)):
+    for slot, text in (
+        ("bottom-right", page.footer_right),
+        ("bottom-center", page.footer_center),
+    ):
         if text:
             parts.append(
                 f"@{slot} {{ content: {_footer_content(text)}; "
@@ -258,7 +261,9 @@ _RENDERERS: Dict[str, BasePdfRenderer] = {
 }
 
 
-def register_renderer(name: str, renderer: BasePdfRenderer, *, preferred: bool = False) -> None:
+def register_renderer(
+    name: str, renderer: BasePdfRenderer, *, preferred: bool = False
+) -> None:
     """Add (or replace) a backend. ``preferred=True`` makes it the first choice
     for auto-selection."""
     key = name.strip().lower()
@@ -331,7 +336,9 @@ def html_to_pdf(
         footer_center=footer_center,
         footer_font_size=footer_font_size,
     )
-    return get_renderer(engine).render(html, page, base_url=base_url, extra_css=extra_css)
+    return get_renderer(engine).render(
+        html, page, base_url=base_url, extra_css=extra_css
+    )
 
 
 def _inject_css(html: str, css: str) -> str:

velocity/payment/__init__.py

@@ -21,6 +21,7 @@ StripeAdapter`` still works and raises ImportError when the SDK is missing;
 
 from .base_adapter import (
     OUTCOME_UNKNOWN,
+    ChargeReferenceAnomaly,
     PaymentProcessorAdapter,
     ProcessorError,
     ProcessorOutcomeUnknown,
@@ -38,6 +39,7 @@ __all__ = [
     "PaymentProcessorAdapter",
     "ProcessorError",
     "ProcessorOutcomeUnknown",
+    "ChargeReferenceAnomaly",
     "OUTCOME_UNKNOWN",
     # Adapters
     "StripeAdapter",

velocity/payment/authorizenet_adapter.py

@@ -30,11 +30,14 @@ from authorizenet import apicontractsv1, apicontrollers
 from .base_adapter import (
     PaymentProcessorAdapter,
     ProcessorError,
+    _as_utc,
     _require_amount,
     _validate_partial_amount,
+    fit_reference,
     mark_external_side_effect,
+    payment_reference,
 )
-from .money import cents_to_decimal
+from .money import cents_to_decimal, to_cents
 from .redact import normalize_card_number, scrub
 from .authorizenet_mirror import (
     build_payment_account_fields_from_authorize_account,
@@ -52,6 +55,75 @@ logger = logging.getLogger(__name__)
 logging.getLogger("authorizenet.sdk").setLevel(logging.CRITICAL + 1)
 logging.getLogger("pyxb").setLevel(logging.WARNING)
 
+#: ``order.invoiceNumber`` and the request ``refId`` are each at most 20
+#: characters (AnetApiSchema.xsd; the SDK rejects longer values).
+INVOICE_NUMBER_MAX_LENGTH = 20
+REF_ID_MAX_LENGTH = 20
+
+#: getTransactionList / getUnsettledTransactionList page size (schema max 1000).
+_PAGE_LIMIT = 1000
+#: getSettledBatchList accepts at most 31 days per request.
+_BATCH_WINDOW = timedelta(days=30)
+#: Look-back when find_charge_by_reference gets no ``since``.
+DEFAULT_REFERENCE_LOOKBACK = timedelta(days=31)
+
+#: transactionStatus values meaning "no money moved / none will": ignored by a
+#: lookup by reference. Refund statuses are skipped too (they are credits).
+_DEAD_STATUSES = frozenset(
+    {
+        "declined",
+        "voided",
+        "expired",
+        "generalError",
+        "failedReview",
+        "settlementError",
+        "communicationError",
+        "refundSettledSuccessfully",
+        "refundPendingSettlement",
+    }
+)
+#: Live but undecided (fraud review): returned with ``success=False``.
+_PENDING_STATUSES = frozenset(
+    {"FDSPendingReview", "FDSAuthorizedPendingReview", "underReview"}
+)
+#: An authOnlyTransaction not yet captured (``authorize_payment``'s result).
+_AUTHORIZED_STATUSES = frozenset({"authorizedPendingCapture"})
+
+
+def _lookup_status(transaction_status: Any) -> str:
+    """A live ``transactionStatus`` in the charge path's vocabulary.
+
+    Fraud review -> ``"Held for Review"`` (response code 4), an uncaptured
+    authOnly -> ``"authorized"`` (as ``authorize_payment`` reports it), every
+    other live status (captured, settled, approved after review...) ->
+    ``"Approved"`` (response code 1).
+    """
+    if transaction_status in _PENDING_STATUSES:
+        return RESPONSE_CODES[4]
+    if transaction_status in _AUTHORIZED_STATUSES:
+        return "authorized"
+    return RESPONSE_CODES[1]
+
+
+def _invoice_number(payment_data: Dict[str, Any]) -> Optional[str]:
+    """The ``order.invoiceNumber`` for ``payment_data``'s reference, or None.
+
+    The same value is sent as the request ``refId`` (also 20 characters).
+    """
+    reference = payment_reference(payment_data)
+    return fit_reference(reference, INVOICE_NUMBER_MAX_LENGTH) if reference else None
+
+
+def _as_list(container: Any, key: str) -> List[Dict[str, Any]]:
+    """xmltodict gives one child as a dict and several as a list."""
+    if not isinstance(container, dict):
+        return []
+    value = container.get(key)
+    if value is None:
+        return []
+    return value if isinstance(value, list) else [value]
+
+
 RESPONSE_CODES = {
     1: "Approved",
     2: "Declined",
@@ -567,7 +639,9 @@ class AuthorizeNetAdapter(PaymentProcessorAdapter):
         Pre-authorize a payment using authOnlyTransaction on a stored profile.
 
         Authorize.Net authorizations expire after 30 days. No HTTP response
-        raises ``ProcessorOutcomeUnknown`` with the side effect marked.
+        raises ``ProcessorOutcomeUnknown`` with the side effect marked. The
+        reference, when given, is sent as ``order.invoiceNumber`` and ``refId``
+        as in :meth:`charge_stored_payment_method`.
         """
         amount_cents = _require_amount(
             "authorize_net", payment_data["amount"], "amount"
@@ -584,17 +658,25 @@ class AuthorizeNetAdapter(PaymentProcessorAdapter):
             tx_request.amount = amount_dollars
             tx_request.profile = profile
 
-            if payment_data.get("client_id") or payment_data.get("description"):
+            invoice_number = _invoice_number(payment_data)
+            if (
+                payment_data.get("client_id")
+                or payment_data.get("description")
+                or invoice_number
+            ):
                 order = apicontractsv1.orderType()
-                client_id = payment_data.get("client_id", "")
-                desc = payment_data.get("description", str(client_id))
-                order.description = str(desc)[:255]
+                if invoice_number:
+                    order.invoiceNumber = invoice_number
+                if payment_data.get("client_id") or payment_data.get("description"):
+                    client_id = payment_data.get("client_id", "")
+                    desc = payment_data.get("description", str(client_id))
+                    order.description = str(desc)[:255]
                 tx_request.order = order
 
             request = apicontractsv1.createTransactionRequest()
             request.merchantAuthentication = self._merchant_auth()
             request.transactionRequest = tx_request
-            request.refId = f"ref{int(time.time() * 1000)}"
+            request.refId = invoice_number or f"ref{int(time.time() * 1000)}"
 
             controller = apicontrollers.createTransactionController(request)
         except Exception as e:
@@ -614,6 +696,7 @@ class AuthorizeNetAdapter(PaymentProcessorAdapter):
                 "customer_profile_id": payment_data.get("customer_profile_id"),
                 "payment_profile_id": payment_data.get("payment_method"),
                 "ref_id": request.refId,
+                "processor_reference": invoice_number,
             },
         )
         trans = response.get("transactionResponse", {})
@@ -649,6 +732,8 @@ class AuthorizeNetAdapter(PaymentProcessorAdapter):
             }
             if mirror_error:
                 metadata["mirror_error"] = mirror_error
+            if invoice_number:
+                metadata["processor_reference"] = invoice_number
             return {
                 "processor_transaction_id": trans.get("transId"),
                 "status": "authorized",
@@ -667,7 +752,11 @@ class AuthorizeNetAdapter(PaymentProcessorAdapter):
             "authorization_code": None,
             "expires_at": None,
             "error_message": _transaction_error_text(trans, code),
-            "metadata": {"response_code": code},
+            "metadata": (
+                {"response_code": code, "processor_reference": invoice_number}
+                if invoice_number
+                else {"response_code": code}
+            ),
         }
 
     def charge_stored_payment_method(
@@ -680,7 +769,17 @@ class AuthorizeNetAdapter(PaymentProcessorAdapter):
         and spot donations. No HTTP response raises ``ProcessorOutcomeUnknown``
         (as before, this path raises rather than returns on transport errors)
         with the side effect marked.
+
+        Authorize.Net has no idempotency keys. The stable business reference
+        (``payment_data["reference"]``, else ``["idempotency_key"]``) is sent
+        as ``order.invoiceNumber`` and as the request ``refId`` (both hashed
+        to 20 characters when longer) and returned in
+        ``metadata["processor_reference"]`` (and in the
+        ``ProcessorOutcomeUnknown`` metadata); :meth:`find_charge_by_reference`
+        finds the charge by it. Without a reference the ``refId`` stays
+        time-based.
         """
+        invoice_number = _invoice_number(payment_data)
         try:
             amount_cents = _require_amount(
                 "authorize_net", payment_data.get("amount"), "amount"
@@ -702,13 +801,16 @@ class AuthorizeNetAdapter(PaymentProcessorAdapter):
             client_id = payment_data.get("client_id", "")
             campaign = metadata.get("campaign", str(client_id))
             order_description = None
-            if client_id or campaign:
+            if client_id or campaign or invoice_number:
                 order = apicontractsv1.orderType()
+                if invoice_number:
+                    order.invoiceNumber = invoice_number
                 if client_id and campaign:
                     order_description = f"{client_id}::{campaign}"[:255]
-                else:
+                elif client_id or campaign:
                     order_description = str(client_id or campaign)[:255]
-                order.description = order_description
+                if order_description:
+                    order.description = order_description
                 tx_request.order = order
 
             # Line items
@@ -734,7 +836,7 @@ class AuthorizeNetAdapter(PaymentProcessorAdapter):
             request = apicontractsv1.createTransactionRequest()
             request.merchantAuthentication = self._merchant_auth()
             request.transactionRequest = tx_request
-            request.refId = f"ref{int(time.time() * 1000)}"
+            request.refId = invoice_number or f"ref{int(time.time() * 1000)}"
 
             controller = apicontrollers.createTransactionController(request)
         except ProcessorError:
@@ -752,7 +854,14 @@ class AuthorizeNetAdapter(PaymentProcessorAdapter):
                 "platform_fee": 0,
                 "client_amount": 0,
                 "error_message": scrub(str(e)),
-                "metadata": {"error_type": type(e).__name__},
+                "metadata": (
+                    {
+                        "error_type": type(e).__name__,
+                        "processor_reference": invoice_number,
+                    }
+                    if invoice_number
+                    else {"error_type": type(e).__name__}
+                ),
             }
 
         response = self._execute(
@@ -764,6 +873,7 @@ class AuthorizeNetAdapter(PaymentProcessorAdapter):
                 "customer_profile_id": payment_data.get("customer_profile_id"),
                 "payment_profile_id": payment_data.get("payment_method"),
                 "ref_id": request.refId,
+                "processor_reference": invoice_number,
             },
         )
         trans = response.get("transactionResponse", {})
@@ -807,6 +917,8 @@ class AuthorizeNetAdapter(PaymentProcessorAdapter):
             }
             if mirror_error:
                 result_metadata["mirror_error"] = mirror_error
+            if invoice_number:
+                result_metadata["processor_reference"] = invoice_number
             return {
                 "processor_transaction_id": trans.get("transId"),
                 "processor_charge_id": trans.get("transId"),
@@ -831,7 +943,187 @@ class AuthorizeNetAdapter(PaymentProcessorAdapter):
             "platform_fee": 0,
             "client_amount": 0,
             "error_message": _transaction_error_text(trans, code),
-            "metadata": {"response_code": code},
+            "metadata": (
+                {"response_code": code, "processor_reference": invoice_number}
+                if invoice_number
+                else {"response_code": code}
+            ),
+        }
+
+    # ========================================================================
+    # LOOKUP BY REFERENCE
+    # ========================================================================
+
+    def find_charge_by_reference(
+        self,
+        tx,
+        reference: str,
+        *,
+        amount: Optional[int] = None,
+        since: Optional[datetime] = None,
+    ) -> Optional[Dict[str, Any]]:
+        """Find the live transaction whose ``invoiceNumber`` is ``reference``.
+
+        Authorize.Net cannot search by invoice number, so this scans the
+        documented reporting lists and filters on ``invoiceNumber`` (the same
+        20-character fitting the charge applied):
+
+        * ``getUnsettledTransactionListRequest`` (status ``any``, so held
+          transactions are included), sorted by ``submitTimeUTC``, paged 1000
+          at a time;
+        * ``getSettledBatchListRequest`` from ``since`` to now (in 30-day
+          windows; the API allows 31), then ``getTransactionListRequest`` per
+          batch, sorted and paged the same way.
+
+        ``since`` bounds the scan (default: 31 days back) -- pass the attempt's
+        creation time. Each request is a Transaction Details API call, so the
+        scan costs one call per batch page. Declined, voided, expired, error
+        and refund transactions are ignored; a transaction under fraud review
+        is returned with ``success=False``. The amount is the summary's
+        ``settleAmount``. Any API error or missing response raises
+        ``ProcessorOutcomeUnknown``. Transaction Details API access must be
+        enabled for the API login.
+
+        ``status`` uses the charge path's vocabulary: ``"Approved"``,
+        ``"Held for Review"`` (fraud review, ``success=False``) or
+        ``"authorized"`` (an uncaptured authOnly); the raw value is in
+        ``metadata["transaction_status"]``. The found transaction is mirrored
+        to ``authorize_transactions`` with the charge path's writer (an
+        idempotent upsert keyed by ``remote_transid``); a mirror failure does
+        not hide the charge and sets ``metadata["mirror_error"]``.
+        """
+        reference = self._require_reference(reference)
+        invoice_number = fit_reference(reference, INVOICE_NUMBER_MAX_LENGTH)
+        now = datetime.now(timezone.utc)
+        start = _as_utc(since) or now - DEFAULT_REFERENCE_LOOKBACK
+        found: Dict[str, Dict[str, Any]] = {}
+        try:
+            for summary in self._unsettled_transactions():
+                if summary.get("invoiceNumber") == invoice_number:
+                    found.setdefault(str(summary.get("transId")), summary)
+            for batch_id in self._settled_batch_ids(start, now):
+                for summary in self._batch_transactions(batch_id):
+                    if summary.get("invoiceNumber") == invoice_number:
+                        found.setdefault(str(summary.get("transId")), summary)
+        except Exception as exc:
+            raise self._reference_lookup_failed(reference, exc) from None
+
+        matches = [
+            self._normalize_summary(summary, invoice_number)
+            for summary in found.values()
+            if summary.get("transactionStatus") not in _DEAD_STATUSES
+        ]
+        match = self._select_reference_match(reference, matches, amount)
+        if match is None:
+            return None
+        summary = match["metadata"]["transaction_summary"]
+        status = match["status"]
+        mirror_error = self._mirror_transaction(
+            tx,
+            {
+                "processor_transaction_id": match["processor_transaction_id"],
+                "amount": (
+                    cents_to_decimal(match["amount"])
+                    if match["amount"] is not None
+                    else None
+                ),
+                "status": status,
+                "remote_responsecode": 4 if status == RESPONSE_CODES[4] else 1,
+                "raw_payload": summary,
+            },
+            "find_charge_by_reference",
+        )
+        if mirror_error:
+            match["metadata"]["mirror_error"] = mirror_error
+        return match
+
+    def _paged_transactions(self, build_request, make_controller):
+        """Yield transaction summaries page by page (sorted, 1000 per page)."""
+        page = 1
+        while True:
+            request = build_request()
+            request.merchantAuthentication = self._merchant_auth()
+            sorting = apicontractsv1.TransactionListSorting()
+            sorting.orderBy = apicontractsv1.TransactionListOrderFieldEnum.submitTimeUTC
+            sorting.orderDescending = False
+            request.sorting = sorting
+            paging = apicontractsv1.Paging()
+            paging.limit = _PAGE_LIMIT
+            paging.offset = page
+            request.paging = paging
+            response = self._execute(make_controller(request))
+            items = _as_list(response.get("transactions"), "transaction")
+            yield from items
+            if len(items) < _PAGE_LIMIT:
+                return
+            page += 1
+
+    def _unsettled_transactions(self):
+        def build():
+            request = apicontractsv1.getUnsettledTransactionListRequest()
+            request.status = apicontractsv1.TransactionGroupStatusEnum.any
+            return request
+
+        return self._paged_transactions(
+            build, apicontrollers.getUnsettledTransactionListController
+        )
+
+    def _batch_transactions(self, batch_id: str):
+        def build():
+            request = apicontractsv1.getTransactionListRequest()
+            request.batchId = batch_id
+            return request
+
+        return self._paged_transactions(
+            build, apicontrollers.getTransactionListController
+        )
+
+    def _settled_batch_ids(self, start: datetime, end: datetime) -> List[str]:
+        """Settled batch ids from ``start`` to ``end``, 30 days per request."""
+        batch_ids: List[str] = []
+        window_start = start
+        while window_start < end:
+            window_end = min(window_start + _BATCH_WINDOW, end)
+            request = apicontractsv1.getSettledBatchListRequest()
+            request.merchantAuthentication = self._merchant_auth()
+            request.firstSettlementDate = window_start
+            request.lastSettlementDate = window_end
+            response = self._execute(
+                apicontrollers.getSettledBatchListController(request)
+            )
+            for batch in _as_list(response.get("batchList"), "batch"):
+                batch_id = batch.get("batchId")
+                if batch_id and batch_id not in batch_ids:
+                    batch_ids.append(batch_id)
+            window_start = window_end
+        return batch_ids
+
+    @staticmethod
+    def _normalize_summary(
+        summary: Dict[str, Any], invoice_number: str
+    ) -> Dict[str, Any]:
+        """A transactionSummaryType (as a dict) in the charge result shape."""
+        raw_status = summary.get("transactionStatus")
+        settle_amount = summary.get("settleAmount")
+        amount_cents = to_cents(str(settle_amount)) if settle_amount else None
+        return {
+            "processor_transaction_id": summary.get("transId"),
+            "processor_charge_id": summary.get("transId"),
+            "status": _lookup_status(raw_status),
+            "success": raw_status not in _PENDING_STATUSES,
+            "amount": amount_cents,
+            "currency": "usd",
+            "authorization_code": None,  # not in the summary; see get_transaction_details
+            "platform_fee": 0,
+            "client_amount": amount_cents,
+            "created_at": summary.get("submitTimeUTC"),
+            "error_message": None,
+            "metadata": {
+                "processor_reference": invoice_number,
+                "found_by_reference": True,
+                "transaction_status": raw_status,
+                "transaction_summary": summary,
+            },
         }
 
     # ========================================================================