velocity-python 0.0.217__tar.gz → 0.0.219__tar.gz

{velocity_python-0.0.217/src/velocity_python.egg-info → velocity_python-0.0.219}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.0.217
+Version: 0.0.219
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.0.217 → velocity_python-0.0.219}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.0.217"
+version = "0.0.219"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]

{velocity_python-0.0.217 → velocity_python-0.0.219}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.0.217"
+__version__ = version = "0.0.219"
 
 from . import aws
 from . import db

{velocity_python-0.0.217 → velocity_python-0.0.219}/src/velocity/payment/__init__.py

@@ -32,6 +32,18 @@ from .router import (
     get_processor_config,
     get_revenue_split_percentage,
     get_processor_account_id,
+    charge_stored_payment_method,
+    get_or_create_customer_profile,
+    attach_payment_method,
+    detach_payment_method,
+    delete_customer_profile,
+)
+from .profiles import (
+    normalize_payment_processor,
+    money_to_cents,
+    get_payment_profile_sources,
+    build_stripe_payment_profile,
+    upsert_payment_profile,
 )
 
 __all__ = [
@@ -46,6 +58,16 @@ __all__ = [
     "get_processor_config",
     "get_revenue_split_percentage",
     "get_processor_account_id",
+    "charge_stored_payment_method",
+    "get_or_create_customer_profile",
+    "attach_payment_method",
+    "detach_payment_method",
+    "delete_customer_profile",
+    "normalize_payment_processor",
+    "money_to_cents",
+    "get_payment_profile_sources",
+    "build_stripe_payment_profile",
+    "upsert_payment_profile",
 ]
 
 __version__ = "1.0.0"

{velocity_python-0.0.217 → velocity_python-0.0.219}/src/velocity/payment/base_adapter.py

@@ -153,6 +153,94 @@ class PaymentProcessorAdapter(ABC):
         """
         pass
 
+    @abstractmethod
+    def charge_stored_payment_method(
+        self, tx, payment_data: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Charge a previously stored payment method immediately.
+
+        This is used for vault/off-session payment flows such as saved donor cards,
+        recurring charges, and queued month transactions.
+
+        Args:
+            tx: velocity-python transaction object
+            payment_data: Dictionary containing:
+                - amount: Amount in cents (integer)
+                - currency: ISO currency code (default: 'usd')
+                - payment_method: Stored processor payment method token/ID
+                - customer_profile_id: Stored processor customer ID (optional)
+                - client_id: Internal client identifier
+                - processor_account_id: External account identifier (optional)
+                - revenue_split_percentage: Platform fee percentage (optional)
+                - metadata: Additional transaction metadata
+                - donor_email: Donor email address
+                - donor_name: Donor full name
+                - description: Transaction description (optional)
+                - descriptor: Processor descriptor object (optional)
+
+        Returns:
+            Dictionary containing:
+                - processor_transaction_id: External transaction/payment intent identifier
+                - processor_charge_id: External charge identifier when available
+                - status: Processor status string
+                - success: Boolean indicating a completed charge
+                - amount: Amount charged in cents
+                - currency: Transaction currency
+                - authorization_code: Processor authorization code when available
+                - platform_fee: Platform fee amount in cents
+                - client_amount: Net client amount in cents
+                - error_message: Error details if failed (optional)
+                - metadata: Additional processor-specific data
+        """
+        pass
+
+    def get_or_create_customer_profile(
+        self, tx, customer_data: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Get or create a vaulted customer profile for a processor.
+
+        Processors that do not support customer profiles directly may override this
+        or leave the default unsupported implementation.
+        """
+        raise ProcessorError(
+            processor=self.processor_name,
+            error_code="unsupported_operation",
+            error_message="Customer profile management is not supported by this processor.",
+        )
+
+    def attach_payment_method(
+        self,
+        tx,
+        customer_profile_id: str,
+        payment_method_id: str,
+        payment_data: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Attach a payment method to a vaulted customer profile."""
+        raise ProcessorError(
+            processor=self.processor_name,
+            error_code="unsupported_operation",
+            error_message="Payment method attachment is not supported by this processor.",
+        )
+
+    def detach_payment_method(
+        self, tx, payment_method_id: str, payment_data: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Detach a payment method from a vaulted customer profile."""
+        raise ProcessorError(
+            processor=self.processor_name,
+            error_code="unsupported_operation",
+            error_message="Payment method detachment is not supported by this processor.",
+        )
+
+    def delete_customer_profile(self, tx, customer_profile_id: str) -> Dict[str, Any]:
+        """Delete a vaulted customer profile."""
+        raise ProcessorError(
+            processor=self.processor_name,
+            error_code="unsupported_operation",
+            error_message="Customer profile deletion is not supported by this processor.",
+        )
+
     # ========================================================================
     # PAYMENT CAPTURE
     # ========================================================================

{velocity_python-0.0.217 → velocity_python-0.0.219}/src/velocity/payment/braintree_adapter.py

@@ -370,6 +370,87 @@ class BraintreeAdapter(PaymentProcessorAdapter):
                 "metadata": {"error_type": type(e).__name__},
             }
 
+    def charge_stored_payment_method(self, tx, payment_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Charge a stored Braintree payment method token immediately."""
+        try:
+            amount_cents = payment_data["amount"]
+            amount_dollars = amount_cents / 100
+            transaction_params = {
+                "payment_method_token": payment_data["payment_method"],
+                "amount": f"{amount_dollars:.2f}",
+                "options": {"submit_for_settlement": True},
+            }
+
+            descriptor = payment_data.get("descriptor")
+            if descriptor:
+                transaction_params["descriptor"] = descriptor
+
+            metadata = payment_data.get("metadata") or {}
+            if metadata:
+                transaction_params["custom_fields"] = {
+                    str(key): str(value)
+                    for key, value in metadata.items()
+                    if value is not None
+                }
+
+            result = self.gateway.transaction.sale(transaction_params)
+
+            if result.is_success:
+                transaction = result.transaction
+                charged_amount = int(float(transaction.amount) * 100)
+                return {
+                    "processor_transaction_id": transaction.id,
+                    "processor_charge_id": transaction.id,
+                    "status": transaction.status,
+                    "success": True,
+                    "amount": charged_amount,
+                    "currency": transaction.currency_iso_code.lower(),
+                    "authorization_code": transaction.processor_authorization_code,
+                    "platform_fee": 0,
+                    "client_amount": charged_amount,
+                    "error_message": None,
+                    "metadata": {
+                        "transaction": transaction,
+                    },
+                }
+
+            error_message = result.message
+            if result.transaction:
+                error_message = result.transaction.processor_response_text
+            return {
+                "processor_transaction_id": None,
+                "processor_charge_id": None,
+                "status": "failed",
+                "success": False,
+                "amount": payment_data.get("amount"),
+                "currency": payment_data.get("currency", "usd"),
+                "authorization_code": None,
+                "platform_fee": 0,
+                "client_amount": 0,
+                "error_message": error_message,
+                "metadata": {
+                    "braintree_errors": [
+                        f"{error.code}: {error.message}"
+                        for error in result.errors.deep_errors
+                    ]
+                },
+            }
+
+        except Exception as e:
+            return {
+                "processor_transaction_id": None,
+                "processor_charge_id": None,
+                "status": "failed",
+                "success": False,
+                "amount": payment_data.get("amount"),
+                "currency": payment_data.get("currency", "usd"),
+                "authorization_code": None,
+                "platform_fee": 0,
+                "client_amount": 0,
+                "error_message": str(e),
+                "metadata": {"error_type": type(e).__name__},
+            }
+
     # ========================================================================
     # PAYMENT CAPTURE
     # ========================================================================

velocity_python-0.0.219/src/velocity/payment/profiles.py

@@ -0,0 +1,71 @@
+"""Payment profile utilities shared across payment processors."""
+
+from decimal import Decimal
+
+
+PROCESSOR_PROFILE_SOURCES = {
+    "stripe": ["ST"],
+    "braintree": ["BT", "AN"],
+}
+
+
+def normalize_payment_processor(value):
+    raw = str(value or "").strip().lower()
+    if not raw or raw == "braintree":
+        return "braintree"
+    if raw == "stripe":
+        return "stripe"
+    return raw
+
+
+def money_to_cents(value):
+    amount = Decimal(str(value or 0))
+    return int((amount * Decimal("100")).quantize(Decimal("1")))
+
+
+def get_payment_profile_sources(processor_type):
+    processor = normalize_payment_processor(processor_type)
+    return list(PROCESSOR_PROFILE_SOURCES.get(processor, ["BT", "AN"]))
+
+
+def build_stripe_payment_profile(
+    customer_id, payment_method, email_address, is_default=True
+):
+    card = getattr(payment_method, "card", None)
+    billing_details = getattr(payment_method, "billing_details", None)
+    data = {
+        "src": "ST",
+        "card_type": (
+            str(getattr(card, "brand", "Stripe") or "Stripe")
+            .replace("_", " ")
+            .title()
+        ),
+        "card_number": getattr(card, "last4", None),
+        "expiration_date": (
+            f"{int(getattr(card, 'exp_year', 0)):04d}-{int(getattr(card, 'exp_month', 0)):02d}"
+            if getattr(card, "exp_year", None) and getattr(card, "exp_month", None)
+            else None
+        ),
+        "payment_profile_id": payment_method.id,
+        "customer_profile_id": customer_id,
+        "email_address": email_address,
+        "is_default": is_default,
+    }
+    name = getattr(billing_details, "name", None) if billing_details else None
+    if name:
+        parts = str(name).split()
+        if parts:
+            data["first_name"] = " ".join(parts[:-1]) or parts[0]
+            data["last_name"] = parts[-1] if len(parts) > 1 else ""
+    return data
+
+
+def upsert_payment_profile(tx, profile_data, key=None):
+    lookup_key = key or {"payment_profile_id": profile_data["payment_profile_id"]}
+    try:
+        tx.table("payment_profiles").upsert(profile_data, lookup_key)
+    except Exception:
+        data = dict(profile_data)
+        data.update(lookup_key)
+        tx.table("payment_profiles").insert(data)
+        tx.table("payment_profiles").create_index("payment_profile_id", unique=True)

{velocity_python-0.0.217 → velocity_python-0.0.219}/src/velocity/payment/router.py

@@ -15,6 +15,7 @@ from typing import Dict, Any, Optional
 from .base_adapter import PaymentProcessorAdapter
 from .stripe_adapter import StripeAdapter
 from .braintree_adapter import BraintreeAdapter
+from .profiles import money_to_cents
 
 
 def get_processor_adapter(
@@ -48,16 +49,17 @@ def get_processor_adapter(
             f"Payment processor '{processor_type}' is not enabled in feature flags"
         )
 
-    # Get processor configuration
+    return _build_adapter(processor_type)
+
+
+def _build_adapter(processor_type: str) -> PaymentProcessorAdapter:
     config = get_processor_config(processor_type)
 
-    # Instantiate appropriate adapter
     if processor_type == "stripe":
         return StripeAdapter(config)
-    elif processor_type == "braintree":
+    if processor_type == "braintree":
         return BraintreeAdapter(config)
-    else:
-        raise ValueError(f"Unsupported payment processor type: {processor_type}")
+    raise ValueError(f"Unsupported payment processor type: {processor_type}")
 
 
 def _determine_processor_type(
@@ -276,3 +278,101 @@ def get_processor_account_id(
     )
 
     return payment_account["processor_account_id"] if payment_account else None
+
+
+def charge_stored_payment_method(
+    tx,
+    client_id: str,
+    payment_profile: Dict[str, Any],
+    amount,
+    *,
+    donor_email: Optional[str] = None,
+    donor_name: Optional[str] = None,
+    description: Optional[str] = None,
+    metadata: Optional[Dict[str, Any]] = None,
+    processor_type: Optional[str] = None,
+    descriptor: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Charge a stored payment profile using the routed processor adapter."""
+    resolved_processor = processor_type or _determine_processor_type(tx, client_id)
+    if not _is_processor_enabled(tx, resolved_processor):
+        raise ValueError(
+            f"Payment processor '{resolved_processor}' is not enabled in feature flags"
+        )
+
+    adapter = _build_adapter(resolved_processor)
+    amount_cents = money_to_cents(amount)
+
+    return adapter.charge_stored_payment_method(
+        tx,
+        {
+            "amount": amount_cents,
+            "currency": "usd",
+            "payment_method": payment_profile["payment_profile_id"],
+            "customer_profile_id": payment_profile.get("customer_profile_id"),
+            "client_id": client_id,
+            "processor_account_id": get_processor_account_id(
+                tx, client_id, resolved_processor
+            ),
+            "revenue_split_percentage": get_revenue_split_percentage(tx, client_id),
+            "donor_email": donor_email,
+            "donor_name": donor_name,
+            "description": description,
+            "descriptor": descriptor,
+            "metadata": metadata or {},
+        },
+    )
+
+
+def get_or_create_customer_profile(
+    tx, processor_type: str, customer_data: Dict[str, Any]
+) -> Dict[str, Any]:
+    """Get or create a vaulted processor customer profile."""
+    if not _is_processor_enabled(tx, processor_type):
+        raise ValueError(
+            f"Payment processor '{processor_type}' is not enabled in feature flags"
+        )
+    adapter = _build_adapter(processor_type)
+    return adapter.get_or_create_customer_profile(tx, customer_data)
+
+
+def attach_payment_method(
+    tx,
+    processor_type: str,
+    customer_profile_id: str,
+    payment_method_id: str,
+    payment_data: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """Attach a payment method to a vaulted processor customer profile."""
+    if not _is_processor_enabled(tx, processor_type):
+        raise ValueError(
+            f"Payment processor '{processor_type}' is not enabled in feature flags"
+        )
+    adapter = _build_adapter(processor_type)
+    return adapter.attach_payment_method(
+        tx, customer_profile_id, payment_method_id, payment_data
+    )
+
+
+def detach_payment_method(
+    tx, processor_type: str, payment_method_id: str
+) -> Dict[str, Any]:
+    """Detach a payment method from a vaulted processor customer profile."""
+    if not _is_processor_enabled(tx, processor_type):
+        raise ValueError(
+            f"Payment processor '{processor_type}' is not enabled in feature flags"
+        )
+    adapter = _build_adapter(processor_type)
+    return adapter.detach_payment_method(tx, payment_method_id)
+
+
+def delete_customer_profile(
+    tx, processor_type: str, customer_profile_id: str
+) -> Dict[str, Any]:
+    """Delete a vaulted processor customer profile."""
+    if not _is_processor_enabled(tx, processor_type):
+        raise ValueError(
+            f"Payment processor '{processor_type}' is not enabled in feature flags"
+        )
+    adapter = _build_adapter(processor_type)
+    return adapter.delete_customer_profile(tx, customer_profile_id)

{velocity_python-0.0.217 → velocity_python-0.0.219}/src/velocity/payment/stripe_adapter.py

@@ -50,6 +50,146 @@ class StripeAdapter(PaymentProcessorAdapter):
     # ACCOUNT MANAGEMENT
     # ========================================================================
 
+    def get_or_create_customer_profile(
+        self, tx, customer_data: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Get an existing Stripe customer or create one for vaulted payment methods."""
+        try:
+            email_address = customer_data["email_address"]
+            existing = (
+                tx.table("payment_profiles")
+                .select(
+                    columns=["customer_profile_id"],
+                    where={"email_address": email_address, "src": "ST"},
+                    orderby="is_default desc, sys_id desc",
+                )
+                .one()
+            )
+            if existing and existing.get("customer_profile_id"):
+                return {
+                    "customer_profile_id": existing["customer_profile_id"],
+                    "created": False,
+                }
+
+            full_name = customer_data.get("name") or " ".join(
+                part
+                for part in [
+                    customer_data.get("first_name"),
+                    customer_data.get("last_name"),
+                ]
+                if part
+            ).strip()
+
+            customer = stripe.Customer.create(
+                email=email_address,
+                name=full_name or email_address,
+                metadata={
+                    "platform": "caringcent",
+                    "email_address": email_address,
+                    **(customer_data.get("metadata") or {}),
+                },
+            )
+            return {
+                "customer_profile_id": customer.id,
+                "created": True,
+                "customer": customer,
+            }
+        except stripe.error.StripeError as e:
+            raise ProcessorError(
+                processor="stripe",
+                error_code=e.code or "unknown",
+                error_message=str(e),
+                metadata={"email_address": customer_data.get("email_address")},
+            )
+
+    def attach_payment_method(
+        self,
+        tx,
+        customer_profile_id: str,
+        payment_method_id: str,
+        payment_data: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Attach a Stripe payment method to a customer and optionally make it default."""
+        payment_data = payment_data or {}
+        try:
+            payment_method = stripe.PaymentMethod.retrieve(payment_method_id)
+            attached_customer = getattr(payment_method, "customer", None)
+            if attached_customer and str(attached_customer) != str(customer_profile_id):
+                raise ProcessorError(
+                    processor="stripe",
+                    error_code="payment_method_attached_elsewhere",
+                    error_message="This payment method is already attached to another Stripe customer.",
+                )
+
+            if not attached_customer:
+                payment_method = stripe.PaymentMethod.attach(
+                    payment_method_id, customer=customer_profile_id
+                )
+
+            if payment_data.get("set_default", True):
+                stripe.Customer.modify(
+                    customer_profile_id,
+                    email=payment_data.get("email_address"),
+                    name=payment_data.get("name") or payment_data.get("email_address"),
+                    invoice_settings={"default_payment_method": payment_method.id},
+                )
+
+            return {
+                "customer_profile_id": customer_profile_id,
+                "payment_profile_id": payment_method.id,
+                "payment_method": payment_method,
+            }
+        except ProcessorError:
+            raise
+        except stripe.error.StripeError as e:
+            raise ProcessorError(
+                processor="stripe",
+                error_code=e.code or "unknown",
+                error_message=str(e),
+                metadata={
+                    "customer_profile_id": customer_profile_id,
+                    "payment_method_id": payment_method_id,
+                },
+            )
+
+    def detach_payment_method(
+        self, tx, payment_method_id: str, payment_data: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """Detach a Stripe payment method from any attached customer."""
+        try:
+            payment_method = stripe.PaymentMethod.retrieve(payment_method_id)
+            if getattr(payment_method, "customer", None):
+                payment_method = stripe.PaymentMethod.detach(payment_method_id)
+            return {
+                "payment_profile_id": payment_method_id,
+                "detached": True,
+                "payment_method": payment_method,
+            }
+        except stripe.error.StripeError as e:
+            raise ProcessorError(
+                processor="stripe",
+                error_code=e.code or "unknown",
+                error_message=str(e),
+                metadata={"payment_method_id": payment_method_id},
+            )
+
+    def delete_customer_profile(self, tx, customer_profile_id: str) -> Dict[str, Any]:
+        """Delete a Stripe vaulted customer."""
+        try:
+            result = stripe.Customer.delete(customer_profile_id)
+            return {
+                "customer_profile_id": customer_profile_id,
+                "deleted": bool(getattr(result, "deleted", False)),
+                "customer": result,
+            }
+        except stripe.error.StripeError as e:
+            raise ProcessorError(
+                processor="stripe",
+                error_code=e.code or "unknown",
+                error_message=str(e),
+                metadata={"customer_profile_id": customer_profile_id},
+            )
+
     def create_account(self, tx, client_data: Dict[str, Any]) -> Dict[str, Any]:
         """
         Create a Stripe Express Connected Account for a client school.
@@ -314,6 +454,90 @@ class StripeAdapter(PaymentProcessorAdapter):
                 },
             }
 
+    def charge_stored_payment_method(self, tx, payment_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Charge a stored Stripe PaymentMethod using an off-session PaymentIntent."""
+        try:
+            amount_cents = payment_data["amount"]
+            currency = payment_data.get("currency", "usd")
+            payment_method = payment_data["payment_method"]
+            customer_profile_id = payment_data.get("customer_profile_id")
+            processor_account_id = payment_data.get("processor_account_id")
+            revenue_split_percentage = payment_data.get("revenue_split_percentage", 0)
+
+            if not customer_profile_id:
+                raise ProcessorError(
+                    processor="stripe",
+                    error_code="missing_customer_profile",
+                    error_message="Stored Stripe charges require a customer_profile_id.",
+                )
+            if not processor_account_id:
+                raise ProcessorError(
+                    processor="stripe",
+                    error_code="missing_processor_account",
+                    error_message="Stripe processor account is not configured for this client.",
+                )
+
+            platform_fee_cents = self.calculate_platform_fee(
+                amount_cents, revenue_split_percentage
+            )
+
+            payment_intent = stripe.PaymentIntent.create(
+                amount=amount_cents,
+                currency=currency,
+                customer=customer_profile_id,
+                payment_method=payment_method,
+                confirm=True,
+                off_session=True,
+                application_fee_amount=platform_fee_cents,
+                transfer_data={"destination": processor_account_id},
+                description=payment_data.get("description"),
+                metadata={
+                    "client_id": str(payment_data.get("client_id")),
+                    "donor_email": payment_data.get("donor_email"),
+                    "donor_name": payment_data.get("donor_name"),
+                    "platform": "caringcent",
+                    "environment": self.environment,
+                    **(payment_data.get("metadata") or {}),
+                },
+            )
+
+            charge_id = getattr(payment_intent, "latest_charge", None)
+            return {
+                "processor_transaction_id": payment_intent.id,
+                "processor_charge_id": charge_id,
+                "status": payment_intent.status,
+                "success": payment_intent.status == "succeeded",
+                "amount": payment_intent.amount,
+                "currency": payment_intent.currency,
+                "authorization_code": payment_intent.id,
+                "platform_fee": payment_intent.application_fee_amount or platform_fee_cents,
+                "client_amount": payment_intent.amount - (payment_intent.application_fee_amount or platform_fee_cents),
+                "error_message": None,
+                "metadata": {
+                    "payment_intent": payment_intent,
+                },
+            }
+
+        except ProcessorError:
+            raise
+        except stripe.error.StripeError as e:
+            return {
+                "processor_transaction_id": None,
+                "processor_charge_id": None,
+                "status": "failed",
+                "success": False,
+                "amount": payment_data.get("amount"),
+                "currency": payment_data.get("currency", "usd"),
+                "authorization_code": None,
+                "platform_fee": 0,
+                "client_amount": 0,
+                "error_message": str(e),
+                "metadata": {
+                    "error_code": e.code,
+                    "error_type": type(e).__name__,
+                },
+            }
+
     # ========================================================================
     # PAYMENT CAPTURE
     # ========================================================================