Feature: POST /public/interest endpoint for lead capture

forgejo_admin commented

2026-03-27 07:48:59 +00:00

Owner

Type

Feature

Lineage

Dependency for westside-app#115 (teams page lead gen). Product direction from Lucas 2026-03-27.

Repo

forgejo_admin/basketball-api

User Story

As a parent visiting the teams page
I want to submit my child's info via an interest form (no login required)
So that Coach Marcus can follow up about tryouts and late onboarding

Context

The westside-landing teams page will have a low-friction interest form (Player Name, Age/Grade, Parent Email, Parent Phone, Program preference). This needs a public API endpoint that:

Stores the lead in a new interest_leads table
Sends an email notification to westsidebasketball@gmail.com via gmail-sdk
Returns success to the client

This is a public endpoint — no Keycloak auth required. Same pattern as GET /public/teams.

File Targets

Files the agent should modify:

src/basketball_api/models.py — add InterestLead model
src/basketball_api/routes/public.py — add POST /public/interest endpoint + Pydantic schemas
New Alembic migration — interest_leads table

Files the agent should NOT touch:

src/basketball_api/routes/register.py — existing registration flow, separate concern
Any admin routes — admin view for leads is a separate ticket

Acceptance Criteria

POST /public/interest accepts: player_name, age_grade, parent_email, parent_phone, program (kings/queens)
Stores lead in interest_leads table with tenant_id=1, created_at timestamp
Sends formatted email notification to westsidebasketball@gmail.com
Returns 201 with confirmation message
Input validation: email format, required fields, phone format lenient
Rate limiting or duplicate check on email (optional, nice-to-have)

Test Expectations

Unit test: valid submission → 201 + DB record created
Unit test: missing required field → 422
Unit test: invalid email → 422
Integration: email notification sent (mock gmail-sdk in tests)

Constraints

No authentication required (public endpoint)
Multi-tenant: hardcode tenant_id=1 for now (same as GET /public/teams)
Email via gmail-sdk (existing dependency in this repo)
Alembic migration required — do NOT use raw SQL

Checklist

PR opened
Tests pass
No unrelated changes

westside-app#115 (frontend consumer)
project-westside-basketball
story:WS-S17 — parent registers child online

### Type Feature ### Lineage Dependency for westside-app#115 (teams page lead gen). Product direction from Lucas 2026-03-27. ### Repo `forgejo_admin/basketball-api` ### User Story As a parent visiting the teams page I want to submit my child's info via an interest form (no login required) So that Coach Marcus can follow up about tryouts and late onboarding ### Context The westside-landing teams page will have a low-friction interest form (Player Name, Age/Grade, Parent Email, Parent Phone, Program preference). This needs a public API endpoint that: 1. Stores the lead in a new `interest_leads` table 2. Sends an email notification to westsidebasketball@gmail.com via gmail-sdk 3. Returns success to the client This is a public endpoint — no Keycloak auth required. Same pattern as `GET /public/teams`. ### File Targets Files the agent should modify: - `src/basketball_api/models.py` — add `InterestLead` model - `src/basketball_api/routes/public.py` — add `POST /public/interest` endpoint + Pydantic schemas - New Alembic migration — `interest_leads` table Files the agent should NOT touch: - `src/basketball_api/routes/register.py` — existing registration flow, separate concern - Any admin routes — admin view for leads is a separate ticket ### Acceptance Criteria - [ ] `POST /public/interest` accepts: player_name, age_grade, parent_email, parent_phone, program (kings/queens) - [ ] Stores lead in `interest_leads` table with tenant_id=1, created_at timestamp - [ ] Sends formatted email notification to westsidebasketball@gmail.com - [ ] Returns 201 with confirmation message - [ ] Input validation: email format, required fields, phone format lenient - [ ] Rate limiting or duplicate check on email (optional, nice-to-have) ### Test Expectations - [ ] Unit test: valid submission → 201 + DB record created - [ ] Unit test: missing required field → 422 - [ ] Unit test: invalid email → 422 - [ ] Integration: email notification sent (mock gmail-sdk in tests) ### Constraints - No authentication required (public endpoint) - Multi-tenant: hardcode tenant_id=1 for now (same as GET /public/teams) - Email via gmail-sdk (existing dependency in this repo) - Alembic migration required — do NOT use raw SQL ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - westside-app#115 (frontend consumer) - `project-westside-basketball` - `story:WS-S17` — parent registers child online