velocity-python 0.0.233__tar.gz → 0.0.236__tar.gz

{velocity_python-0.0.233/src/velocity_python.egg-info → velocity_python-0.0.236}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.0.233
+Version: 0.0.236
 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.233 → velocity_python-0.0.236}/pyproject.toml

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

{velocity_python-0.0.233 → velocity_python-0.0.236}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.0.233"
+__version__ = version = "0.0.236"
 
 from . import aws
 from . import db

velocity_python-0.0.236/src/velocity/app/validators/__init__.py

@@ -0,0 +1 @@
+"""velocity.app.validators — domain validators for shared application entities."""

velocity_python-0.0.236/src/velocity/app/validators/formbuilder_template.py

@@ -0,0 +1,204 @@
+"""Pure-Python validator for form_builder_template dicts.
+
+Authoritative location: velocity.app.validators.formbuilder_template
+
+Called by:
+  - BackOffice before_write hook (rwx/form_builder_template.py)
+  - BackOffice CLI: scripts/validate_formbuilder_templates.py
+  - DonateMain CLI: scripts/formbuilder_validator.py (shim — imports from here)
+  - Tests: velocity-python/tests/app/validators/test_formbuilder_template.py
+           BackOffice.demo/tests/backend/test_form_builder_template_hook.py
+           DonateMain.demo/tests/backend/test_formbuilder_validators.py
+
+No external dependencies — only the stdlib so it runs everywhere the test suite runs.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List
+
+# --------------------------------------------------------------------------- #
+# Helpers
+# --------------------------------------------------------------------------- #
+
+_EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+# Also accept RFC 5322 display-name format: "Label <user@example.com>"
+_EMAIL_DISPLAY_RE = re.compile(r"<[^@\s>]+@[^@\s>]+\.[^@\s>]+>$")
+_URL_RE = re.compile(r"^https?://", re.IGNORECASE)
+
+# Braintree: descriptor must be <= 22 characters, NAME*TEXT format.
+_BT_DESCRIPTOR_MAX_LEN = 22
+
+
+def _str_val(fb: Dict[str, Any], key: str) -> str:
+    """Return the stripped string value for a key, or '' when None/missing."""
+    v = fb.get(key)
+    return v.strip() if isinstance(v, str) else ""
+
+
+# --------------------------------------------------------------------------- #
+# Public API
+# --------------------------------------------------------------------------- #
+
+Issue = Dict[str, str]  # {field, severity, message}
+
+
+def validate_formbuilder_template(fb: Dict[str, Any]) -> List[Issue]:
+    """Validate a form_builder_template dict for known configuration problems.
+
+    Returns a list of issue dicts::
+
+        [{"field": "...", "severity": "error"|"warning", "message": "..."}]
+
+    An empty list means no issues were found.
+
+    Severities:
+      error   – will cause a runtime crash or silent payment failure.
+      warning – likely produces a broken/confusing user experience.
+    """
+    issues: List[Issue] = []
+
+    def error(field: str, message: str) -> None:
+        issues.append({"field": field, "severity": "error", "message": message})
+
+    def warning(field: str, message: str) -> None:
+        issues.append({"field": field, "severity": "warning", "message": message})
+
+    # ---------------------------------------------------------------------- #
+    # Identity
+    # ---------------------------------------------------------------------- #
+    if not _str_val(fb, "client"):
+        error("client", "client is required; KeyError will crash the handler")
+
+    if not _str_val(fb, "campaign"):
+        error("campaign", "campaign is required; KeyError will crash the handler")
+
+    if not _str_val(fb, "url_slug"):
+        error("url_slug", "url_slug is required; template will not be routable")
+
+    # ---------------------------------------------------------------------- #
+    # Receipt email fields
+    # (used with direct key access: fb["receipt_from_address"] etc.)
+    # ---------------------------------------------------------------------- #
+    from_addr = _str_val(fb, "receipt_from_address")
+    if not from_addr:
+        error(
+            "receipt_from_address",
+            "receipt_from_address is empty; donation receipt emails will fail to send",
+        )
+    elif not _EMAIL_RE.match(from_addr) and not _EMAIL_DISPLAY_RE.search(from_addr):
+        error(
+            "receipt_from_address",
+            f"receipt_from_address '{from_addr}' is not a valid email address",
+        )
+
+    if not _str_val(fb, "receipt_subject"):
+        warning(
+            "receipt_subject",
+            "receipt_subject is empty; donation receipt email subject will be blank",
+        )
+
+    if not _str_val(fb, "receipt_body_text"):
+        error(
+            "receipt_body_text",
+            "receipt_body_text is empty; donation receipt emails will have no content",
+        )
+
+    # ---------------------------------------------------------------------- #
+    # Braintree transaction descriptor
+    # Rules: <= 22 chars, should contain '*', ASCII printable only.
+    # ---------------------------------------------------------------------- #
+    descriptor = _str_val(fb, "descriptor")
+    if descriptor:
+        if len(descriptor) > _BT_DESCRIPTOR_MAX_LEN:
+            error(
+                "descriptor",
+                f"descriptor is {len(descriptor)} chars (max {_BT_DESCRIPTOR_MAX_LEN}); "
+                "Braintree will reject the transaction",
+            )
+        if "*" not in descriptor:
+            warning(
+                "descriptor",
+                f"descriptor '{descriptor}' should follow 'NAME*TEXT' format for Braintree",
+            )
+        bad_chars = [c for c in descriptor if not (32 <= ord(c) <= 126)]
+        if bad_chars:
+            error(
+                "descriptor",
+                f"descriptor contains non-ASCII/non-printable characters: {bad_chars!r}",
+            )
+
+    # ---------------------------------------------------------------------- #
+    # Content — at least one active donation or metric must be configured
+    # ---------------------------------------------------------------------- #
+    has_content = _has_donation_content(fb) or _has_metric_content(fb)
+    if not has_content:
+        warning(
+            "donations/metrics",
+            "template has no donation amounts or metrics configured; the form will be empty",
+        )
+
+    # ---------------------------------------------------------------------- #
+    # Share URL (used in confirmation email)
+    # ---------------------------------------------------------------------- #
+    share_url = _str_val(fb, "share_url")
+    if share_url and not _URL_RE.match(share_url):
+        warning(
+            "share_url",
+            f"share_url '{share_url}' does not look like a valid URL (expected https://...)",
+        )
+
+    # ---------------------------------------------------------------------- #
+    # Confirmation page text
+    # ---------------------------------------------------------------------- #
+    if not _str_val(fb, "confirmation_header_text"):
+        warning(
+            "confirmation_header_text",
+            "confirmation_header_text is empty; the thank-you page header will be blank",
+        )
+
+    return issues
+
+
+# --------------------------------------------------------------------------- #
+# Internal helpers
+# --------------------------------------------------------------------------- #
+
+
+def _has_donation_content(fb: Dict[str, Any]) -> bool:
+    """Return True if at least one visible donation is configured."""
+    donations = fb.get("donations")
+    if isinstance(donations, dict):
+        for key, item in donations.items():
+            hide_key = f"donation_{key}_hide_donation_from_ui"
+            if fb.get(hide_key):
+                continue
+            if isinstance(item, dict) and item.get("label"):
+                return True
+    # Legacy numbered fields
+    for i in range(1, 10):
+        if fb.get(f"donation_{i}_hide_donation_from_ui"):
+            continue
+        if _str_val(fb, f"donation_{i}_label") or fb.get(f"donation_{i}_values"):
+            return True
+    return False
+
+
+def _has_metric_content(fb: Dict[str, Any]) -> bool:
+    """Return True if at least one visible metric is configured."""
+    metrics = fb.get("metrics")
+    if isinstance(metrics, dict):
+        for key, item in metrics.items():
+            hide_key = f"{key}_hide_donation_from_ui"
+            if fb.get(hide_key):
+                continue
+            if isinstance(item, dict) and item.get("label"):
+                return True
+    # Legacy numbered fields
+    for i in range(1, 10):
+        if fb.get(f"metric_{i}_hide_donation_from_ui"):
+            continue
+        if _str_val(fb, f"metric_{i}_label") or fb.get(f"metric_{i}_values"):
+            return True
+    return False

{velocity_python-0.0.233 → velocity_python-0.0.236}/src/velocity/payment/__init__.py

@@ -55,6 +55,11 @@ from .profiles import (
     upsert_payment_profile,
 )
 from .demo_profiles import resolve_demo_charge_cards, get_card_lookup_id
+from .charge_rules import (
+    should_charge_immediately,
+    is_below_immediate_charge_minimum,
+    is_above_immediate_charge_maximum,
+)
 
 __all__ = [
     # Base classes
@@ -83,6 +88,9 @@ __all__ = [
     "upsert_payment_profile",
     "resolve_demo_charge_cards",
     "get_card_lookup_id",
+    "should_charge_immediately",
+    "is_below_immediate_charge_minimum",
+    "is_above_immediate_charge_maximum",
 ]
 
 __version__ = "1.0.0"

velocity_python-0.0.236/src/velocity/payment/charge_rules.py

@@ -0,0 +1,39 @@
+"""Shared immediate-charge validation helpers for payment flows."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def should_charge_immediately(total_charge_amount: Any) -> bool:
+    """Return True when an immediate payment should be submitted to a processor."""
+    if total_charge_amount in (None, ""):
+        return False
+    try:
+        return float(total_charge_amount) > 0
+    except (TypeError, ValueError):
+        return False
+
+
+def is_below_immediate_charge_minimum(
+    total_charge_amount: Any, minimum_donation_amount: Any
+) -> bool:
+    """Return True only when an actual immediate charge exists and is below the minimum."""
+    if not should_charge_immediately(total_charge_amount):
+        return False
+    try:
+        return float(total_charge_amount) < float(minimum_donation_amount)
+    except (TypeError, ValueError):
+        return False
+
+
+def is_above_immediate_charge_maximum(
+    total_charge_amount: Any, maximum_donation_amount: Any
+) -> bool:
+    """Return True only when an actual immediate charge exists and is above the maximum."""
+    if not should_charge_immediately(total_charge_amount):
+        return False
+    try:
+        return float(total_charge_amount) > float(maximum_donation_amount)
+    except (TypeError, ValueError):
+        return False

{velocity_python-0.0.233 → velocity_python-0.0.236/src/velocity_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.0.233
+Version: 0.0.236
 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.233 → velocity_python-0.0.236}/src/velocity_python.egg-info/SOURCES.txt

@@ -12,6 +12,8 @@ src/velocity/app/tests/__init__.py
 src/velocity/app/tests/test_email_processing.py
 src/velocity/app/tests/test_payment_profile_sorting.py
 src/velocity/app/tests/test_spreadsheet_functions.py
+src/velocity/app/validators/__init__.py
+src/velocity/app/validators/formbuilder_template.py
 src/velocity/aws/__init__.py
 src/velocity/aws/amplify.py
 src/velocity/aws/amplify_build.py
@@ -133,6 +135,7 @@ src/velocity/payment/__init__.py
 src/velocity/payment/authorizenet_adapter.py
 src/velocity/payment/base_adapter.py
 src/velocity/payment/braintree_adapter.py
+src/velocity/payment/charge_rules.py
 src/velocity/payment/demo_profiles.py
 src/velocity/payment/profiles.py
 src/velocity/payment/router.py
@@ -144,6 +147,7 @@ src/velocity_python.egg-info/requires.txt
 src/velocity_python.egg-info/top_level.txt
 tests/test_amplify_build.py
 tests/test_decorators.py
+tests/test_formbuilder_template_validator.py
 tests/test_iconv_money_to_cents.py
 tests/test_lambda_handler.py
 tests/test_lambda_handler_auth.py

velocity_python-0.0.236/tests/test_formbuilder_template_validator.py

@@ -0,0 +1,240 @@
+"""Unit tests for velocity.app.validators.formbuilder_template.
+
+These tests are the canonical regression suite for the shared validator.
+Consumer-project tests (DonateMain, BackOffice) import from this module via
+velocity so their suites should stay in sync.
+
+Runs entirely offline — no database or network access required.
+
+  python -m pytest tests/test_formbuilder_template_validator.py -v
+"""
+
+from __future__ import annotations
+
+import unittest
+
+from velocity.app.validators.formbuilder_template import validate_formbuilder_template
+
+
+# --------------------------------------------------------------------------- #
+# Helpers
+# --------------------------------------------------------------------------- #
+
+
+def _make_valid_fb(**overrides) -> dict:
+    """Return the minimal template dict that passes all validations."""
+    base = {
+        "client": "TestClient",
+        "campaign": "test_campaign",
+        "url_slug": "/test/campaign",
+        "receipt_from_address": "noreply@example.com",
+        "receipt_subject": "Thank you for your donation",
+        "receipt_body_text": "<p>Dear {first_name}, thank you for donating!</p>",
+        "descriptor": "CaringCent*TEST",
+        "confirmation_header_text": "Thank you!",
+        "share_url": "https://donate.example.org/campaign",
+        "donations": {
+            "d1": {"label": "Give $25", "values": {"$25": "25"}},
+        },
+    }
+    base.update(overrides)
+    return base
+
+
+def _errors(issues, field=None):
+    return [
+        i
+        for i in issues
+        if i["severity"] == "error" and (field is None or i["field"] == field)
+    ]
+
+
+def _warnings(issues, field=None):
+    return [
+        i
+        for i in issues
+        if i["severity"] == "warning" and (field is None or i["field"] == field)
+    ]
+
+
+# --------------------------------------------------------------------------- #
+# Baseline
+# --------------------------------------------------------------------------- #
+
+
+class ValidTemplatePassesTests(unittest.TestCase):
+
+    def test_valid_template_has_no_issues(self):
+        issues = validate_formbuilder_template(_make_valid_fb())
+        self.assertEqual(issues, [], f"Unexpected issues: {issues}")
+
+    def test_returns_a_list(self):
+        result = validate_formbuilder_template(_make_valid_fb())
+        self.assertIsInstance(result, list)
+
+
+# --------------------------------------------------------------------------- #
+# Identity fields
+# --------------------------------------------------------------------------- #
+
+
+class IdentityFieldTests(unittest.TestCase):
+
+    def test_missing_client_is_error(self):
+        self.assertTrue(_errors(validate_formbuilder_template(_make_valid_fb(client="")), "client"))
+
+    def test_none_client_is_error(self):
+        self.assertTrue(_errors(validate_formbuilder_template(_make_valid_fb(client=None)), "client"))
+
+    def test_missing_campaign_is_error(self):
+        self.assertTrue(_errors(validate_formbuilder_template(_make_valid_fb(campaign="")), "campaign"))
+
+    def test_missing_url_slug_is_error(self):
+        fb = _make_valid_fb()
+        del fb["url_slug"]
+        self.assertTrue(_errors(validate_formbuilder_template(fb), "url_slug"))
+
+    def test_none_url_slug_is_error(self):
+        self.assertTrue(_errors(validate_formbuilder_template(_make_valid_fb(url_slug=None)), "url_slug"))
+
+
+# --------------------------------------------------------------------------- #
+# Receipt email fields
+# --------------------------------------------------------------------------- #
+
+
+class ReceiptEmailFieldTests(unittest.TestCase):
+
+    def test_empty_from_address_is_error(self):
+        self.assertTrue(_errors(validate_formbuilder_template(
+            _make_valid_fb(receipt_from_address="")), "receipt_from_address"))
+
+    def test_none_from_address_is_error(self):
+        self.assertTrue(_errors(validate_formbuilder_template(
+            _make_valid_fb(receipt_from_address=None)), "receipt_from_address"))
+
+    def test_invalid_from_address_is_error(self):
+        self.assertTrue(_errors(validate_formbuilder_template(
+            _make_valid_fb(receipt_from_address="not-an-email")), "receipt_from_address"))
+
+    def test_display_name_format_passes(self):
+        """'Display Name <user@example.com>' is RFC 5322 valid and used in practice."""
+        issues = validate_formbuilder_template(
+            _make_valid_fb(receipt_from_address="Tigers Athletics <noreply@example.com>"))
+        self.assertFalse(_errors(issues, "receipt_from_address"))
+
+    def test_empty_subject_is_warning(self):
+        self.assertTrue(_warnings(validate_formbuilder_template(
+            _make_valid_fb(receipt_subject="")), "receipt_subject"))
+
+    def test_empty_body_is_error(self):
+        self.assertTrue(_errors(validate_formbuilder_template(
+            _make_valid_fb(receipt_body_text="")), "receipt_body_text"))
+
+
+# --------------------------------------------------------------------------- #
+# Braintree descriptor
+# --------------------------------------------------------------------------- #
+
+
+class DescriptorTests(unittest.TestCase):
+
+    def test_valid_descriptor_passes(self):
+        issues = validate_formbuilder_template(_make_valid_fb())
+        self.assertFalse(_errors(issues, "descriptor"))
+        self.assertFalse(_warnings(issues, "descriptor"))
+
+    def test_omitted_descriptor_passes(self):
+        fb = _make_valid_fb()
+        del fb["descriptor"]
+        issues = validate_formbuilder_template(fb)
+        self.assertFalse(_errors(issues, "descriptor"))
+
+    def test_descriptor_too_long_is_error(self):
+        self.assertTrue(_errors(validate_formbuilder_template(
+            _make_valid_fb(descriptor="A" * 23)), "descriptor"))
+
+    def test_descriptor_exactly_22_chars_passes(self):
+        issues = validate_formbuilder_template(_make_valid_fb(descriptor="CaringCent*EXACTLY22CH"))
+        self.assertFalse(_errors(issues, "descriptor"))
+
+    def test_descriptor_without_asterisk_is_warning(self):
+        fb = _make_valid_fb(descriptor="CaringCentNOASTERISK")
+        issues = validate_formbuilder_template(fb)
+        self.assertTrue(_warnings(issues, "descriptor"))
+
+    def test_descriptor_with_non_ascii_is_error(self):
+        self.assertTrue(_errors(validate_formbuilder_template(
+            _make_valid_fb(descriptor="CaringCent*\x80TEST")), "descriptor"))
+
+
+# --------------------------------------------------------------------------- #
+# Content — donations / metrics
+# --------------------------------------------------------------------------- #
+
+
+class ContentConfigurationTests(unittest.TestCase):
+
+    def test_no_donations_no_metrics_is_warning(self):
+        fb = _make_valid_fb()
+        del fb["donations"]
+        self.assertTrue(_warnings(validate_formbuilder_template(fb), "donations/metrics"))
+
+    def test_modern_donations_dict_counts_as_content(self):
+        issues = validate_formbuilder_template(_make_valid_fb())
+        self.assertFalse(_warnings(issues, "donations/metrics"))
+
+    def test_hidden_donation_does_not_count_as_content(self):
+        fb = _make_valid_fb()
+        fb["donations"] = {"d1": {"label": "Hidden", "values": {}}}
+        fb["donation_d1_hide_donation_from_ui"] = True
+        issues = validate_formbuilder_template(fb)
+        self.assertTrue(_warnings(issues, "donations/metrics"))
+
+    def test_legacy_numbered_donation_fields_count_as_content(self):
+        fb = _make_valid_fb()
+        del fb["donations"]
+        fb["donation_1_label"] = "Give $25"
+        issues = validate_formbuilder_template(fb)
+        self.assertFalse(_warnings(issues, "donations/metrics"))
+
+
+# --------------------------------------------------------------------------- #
+# Share URL
+# --------------------------------------------------------------------------- #
+
+
+class ShareUrlTests(unittest.TestCase):
+
+    def test_missing_share_url_is_ok(self):
+        fb = _make_valid_fb()
+        del fb["share_url"]
+        self.assertFalse(_warnings(validate_formbuilder_template(fb), "share_url"))
+
+    def test_valid_https_url_passes(self):
+        issues = validate_formbuilder_template(_make_valid_fb())
+        self.assertFalse(_warnings(issues, "share_url"))
+
+    def test_non_url_share_url_is_warning(self):
+        self.assertTrue(_warnings(validate_formbuilder_template(
+            _make_valid_fb(share_url="not-a-url")), "share_url"))
+
+
+# --------------------------------------------------------------------------- #
+# Confirmation page text
+# --------------------------------------------------------------------------- #
+
+
+class ConfirmationTextTests(unittest.TestCase):
+
+    def test_empty_confirmation_header_is_warning(self):
+        self.assertTrue(_warnings(validate_formbuilder_template(
+            _make_valid_fb(confirmation_header_text="")), "confirmation_header_text"))
+
+    def test_valid_confirmation_header_passes(self):
+        issues = validate_formbuilder_template(_make_valid_fb())
+        self.assertFalse(_warnings(issues, "confirmation_header_text"))
+
+
+if __name__ == "__main__":
+    unittest.main()