feat: first-payment email + blast endpoint #376

Merged

forgejo_admin merged 2 commits from 369-first-payment-email-blast into main

2026-04-07 20:13:27 +00:00

forgejo_admin commented

2026-04-07 17:29:36 +00:00

Owner

Summary

Adds send_first_payment_email service function and POST /admin/email/first-payment blast endpoint for sending prorated first-month payment emails to parents of signed players after their first practice.

Changes

src/basketball_api/models.py -- Added first_payment to EmailType enum
src/basketball_api/services/email.py -- Added _calculate_prorated_fee() helper (same formula as westside-contracts: round(fee * 25/30 / 5) * 5) and send_first_payment_email() with branded HTML, plaintext fallback, and EmailLog persistence
src/basketball_api/routes/admin.py -- Added POST /admin/email/first-payment endpoint with test_email query param filter, targeting players with contract_status=signed and non-null contract_token
tests/test_first_payment_email.py -- 5 tests: proration math ($200->$165, $180->$150, None->$165), email content verification, EmailLog persistence
tests/test_first_payment_blast.py -- 3 tests: blast sends to signed players only, test_email filtering, error handling
tests/test_templated_email.py -- Updated EmailType enum value assertion to include first_payment

Test Plan

All 8 new tests pass
Full suite: 852 passed (pre-existing test_checkout.py webhook failures excluded -- unrelated to this PR)
ruff format and ruff check clean

Review Checklist

New enum value added to EmailType
Email function follows existing pattern (get_gmail_client, _brand_wrapper, EmailLog)
Blast endpoint follows jersey-reminder pattern (test_email filter, error collection)
Proration formula matches westside-contracts
No changes to checkout.py or webhooks.py
Tests cover happy path, proration math, filtering, and error handling

None.

Closes #369

## Summary Adds `send_first_payment_email` service function and `POST /admin/email/first-payment` blast endpoint for sending prorated first-month payment emails to parents of signed players after their first practice. ## Changes - **src/basketball_api/models.py** -- Added `first_payment` to `EmailType` enum - **src/basketball_api/services/email.py** -- Added `_calculate_prorated_fee()` helper (same formula as westside-contracts: `round(fee * 25/30 / 5) * 5`) and `send_first_payment_email()` with branded HTML, plaintext fallback, and EmailLog persistence - **src/basketball_api/routes/admin.py** -- Added `POST /admin/email/first-payment` endpoint with `test_email` query param filter, targeting players with `contract_status=signed` and non-null `contract_token` - **tests/test_first_payment_email.py** -- 5 tests: proration math ($200->$165, $180->$150, None->$165), email content verification, EmailLog persistence - **tests/test_first_payment_blast.py** -- 3 tests: blast sends to signed players only, test_email filtering, error handling - **tests/test_templated_email.py** -- Updated EmailType enum value assertion to include `first_payment` ## Test Plan - All 8 new tests pass - Full suite: 852 passed (pre-existing `test_checkout.py` webhook failures excluded -- unrelated to this PR) - `ruff format` and `ruff check` clean ## Review Checklist - [x] New enum value added to EmailType - [x] Email function follows existing pattern (get_gmail_client, _brand_wrapper, EmailLog) - [x] Blast endpoint follows jersey-reminder pattern (test_email filter, error collection) - [x] Proration formula matches westside-contracts - [x] No changes to checkout.py or webhooks.py - [x] Tests cover happy path, proration math, filtering, and error handling ## Related Notes None. ## Related Closes #369

forgejo_admin added 1 commit

2026-04-07 17:29:36 +00:00

feat: add send_first_payment_email + POST /admin/email/first-payment blast endpoint

ci/woodpecker/pr/woodpecker Pipeline failed

Details

40eee1cac5

Post-practice first-payment email with prorated fee calculation (same formula
as westside-contracts) and branded HTML. Blast endpoint targets signed players
with contract tokens, supports test_email filtering.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

forgejo_admin commented

2026-04-07 17:30:14 +00:00

Author

Owner

QA Review -- PR #376

Summary

Adds send_first_payment_email service function, _calculate_prorated_fee helper, and POST /admin/email/first-payment blast endpoint. 6 files changed, 520 additions.

Findings

No blocking issues.

Positive observations:

Email function follows the established pattern exactly (get_gmail_client, _brand_wrapper, EmailLog, db.commit) -- consistent with send_profile_reminder_email and others
Blast endpoint follows jersey-reminder pattern (tenant lookup, test_email filter, error collection, continue-on-failure)
Proration formula matches westside-contracts: round(fee * 25/30 / 5) * 5
checkout_url correctly uses settings.frontend_url (matching checkout.py patterns), not settings.base_url
Tests cover: proration math (3 cases), email content verification, EmailLog persistence, blast filtering (signed-only + no-token exclusion), test_email filter, error handling
Enum value test in test_templated_email.py updated
ruff clean per PR description

Nits (non-blocking):

Subject line hardcodes "April" -- will need updating for future months, but acceptable for current use case
No DB migration for the new enum value -- Postgres string enums may need an ALTER TYPE if the column uses a native enum. Verify the EmailType column uses a string-backed enum or that an Alembic migration exists separately.

Test Results (per PR)

8 new tests: all pass
Full suite: 852 passed (pre-existing test_checkout.py failures excluded)

VERDICT: APPROVED

## QA Review -- PR #376 ### Summary Adds `send_first_payment_email` service function, `_calculate_prorated_fee` helper, and `POST /admin/email/first-payment` blast endpoint. 6 files changed, 520 additions. ### Findings **No blocking issues.** **Positive observations:** - Email function follows the established pattern exactly (get_gmail_client, _brand_wrapper, EmailLog, db.commit) -- consistent with send_profile_reminder_email and others - Blast endpoint follows jersey-reminder pattern (tenant lookup, test_email filter, error collection, continue-on-failure) - Proration formula matches westside-contracts: `round(fee * 25/30 / 5) * 5` - checkout_url correctly uses `settings.frontend_url` (matching checkout.py patterns), not `settings.base_url` - Tests cover: proration math (3 cases), email content verification, EmailLog persistence, blast filtering (signed-only + no-token exclusion), test_email filter, error handling - Enum value test in test_templated_email.py updated - ruff clean per PR description **Nits (non-blocking):** - Subject line hardcodes "April" -- will need updating for future months, but acceptable for current use case - No DB migration for the new enum value -- Postgres string enums may need an ALTER TYPE if the column uses a native enum. Verify the EmailType column uses a string-backed enum or that an Alembic migration exists separately. ### Test Results (per PR) - 8 new tests: all pass - Full suite: 852 passed (pre-existing test_checkout.py failures excluded) **VERDICT: APPROVED**

forgejo_admin added 1 commit

2026-04-07 17:31:33 +00:00

fix: use base_url not frontend_url for checkout redirect link

ci/woodpecker/pr/woodpecker Pipeline failed

Details

b0423fda6a

The /checkout/first-payment endpoint lives on basketball-api (the API),
not westside-app (the frontend). Using frontend_url would send parents
to a 404.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>