pal-e-docs

Review: Win/lose email notifications via Gmail

review-832-2026-04-05 Doc

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Board item #832 — Forgejo issue forgejo_admin/twitch-2k-wager#60

Template Completeness

  • [x] Type — Feature
  • [x] Lineage
  • [x] Repo
  • [x] User Story
  • [x] Context
  • [x] Prerequisites
  • [x] File Targets
  • [x] Acceptance Criteria
  • [x] Test Expectations
  • [x] Constraints
  • [x] Checklist
  • [x] Related
All template sections present and populated.

Traceability

  • [x] story:winner-payout label — present on board item
  • [ ] story note MISSING — project-twitch-2k-wager has empty TOC, no user-stories section. [SCOPE] Create user story entries on project-twitch-2k-wager user-stories section.
  • [x] arch:dataflow-twitch-2k-wager label — present on board item
  • [ ] arch note MISSING — search for "dataflow-twitch-2k-wager" returned zero results in pal-e-docs. [SCOPE] Create architecture note arch-dataflow-twitch-2k-wager for the dataflow component.
  • [x] Forgejo issue — forgejo_admin/twitch-2k-wager#60, open

File Targets

  • [x] src/lib/email.ts — verified: sendWinnerEmail() and sendLoserEmail() stubs exist (lines 178, 197). sendEmail() has TODO at line 156 for Gmail OAuth transport. HTML templates already built.
  • [x] src/routes/api/admin/result/+server.ts — verified: does NOT currently import or call email functions. handleChallengerWin() (line 109) and handleMarcusWin() (line 181) are the correct integration points.
  • [x] K8s secret twitch-2k-wager-secrets — verified: exists in pal-e-deployments overlays (dev + prod). No Gmail env vars present yet.
Targets are specific and actionable.

Repo Placement

OK. Issue filed on forgejo_admin/twitch-2k-wager, primary code changes target same repo. K8s secret lives in pal-e-deployments but is an ops prerequisite (manual step by Lucas), not agent code work. Single-repo ticket is appropriate.

Dependencies

  • [ ] Gmail account creation — pending (Lucas manual step). ~/secrets/playme2k/ exists but contains only Stripe and Twitch credentials, no Gmail tokens.
  • [ ] OAuth app in Google Cloud Console — pending (Lucas manual step)
  • [ ] OAuth tokens stored in ~/secrets/playme2k/ — pending
  • [ ] K8s secret updated with Gmail credentials — pending
  • [x] email.ts stubs — satisfied (code exists)
  • [x] result endpoint — satisfied (code exists, ready for integration)
All 4 prerequisites are manual human tasks. Agent cannot execute until Lucas completes them. This is correctly documented in the issue.

Acceptance Criteria

  • [x] "Winner gets email with payout claim link" — testable once Gmail is wired
  • [x] "Loser gets email with receipt/thanks" — testable once Gmail is wired
  • [x] "Emails send via Gmail OAuth (dedicated PlayMe2K account)" — testable
  • [x] "Test emails to draneylucas@gmail.com verified on phone" — testable, follows feedback_test_email_address convention
ISSUE: The ticket says "wire up gmail-sdk" but gmail-sdk-ldraney is a Python package (used in basketball-api). This is a SvelteKit/TypeScript project with no JS equivalent. The ticket must specify the actual Node.js Gmail API approach (e.g., googleapis npm package or direct REST with OAuth2 bearer tokens). Without this, an agent will waste time looking for a nonexistent JS package.

Blast Radius

  • 2 files modified in twitch-2k-wager repo
  • Email is per-project per convention (feedback_email_architecture) — no shared email service affected
  • basketball-api uses completely different stack (Python + gmail-sdk-ldraney) — no cross-contamination
  • Rollback: revert PR + set EMAIL_ENABLED=false. Straightforward.

Decomposition Assessment

Apply the three-thing limit and five-minute rule:
  • 2 file targets in 1 repo — under threshold
  • 4 acceptance criteria — under threshold
  • Estimated agent work: ~3-4 minutes (wire OAuth transport in email.ts, add email calls to result endpoint)
  • No independent subtasks that need parallelization
No decomposition needed.

Recommendation

  • [BODY] Replace "gmail-sdk" references in Context and Constraints sections with the actual Node.js approach. gmail-sdk-ldraney is Python-only. Specify googleapis npm package or direct Gmail REST API with OAuth2 bearer tokens.
  • [SCOPE] Create user-stories section on project-twitch-2k-wager with winner-payout story entry.
  • [SCOPE] Create architecture note arch-dataflow-twitch-2k-wager for the dataflow component.