From 06096fa7dd41d5aa28332b501245df4c4550cbe4 Mon Sep 17 00:00:00 2001
From: Alex Cabal <alex@alexcabal.com>
Date: Fri, 2 May 2025 15:28:46 -0500
Subject: [PATCH] Correctly process matching donations from funds

---
 lib/Payment.php                  |  4 ++--
 lib/User.php                     | 19 ++++++++++++-------
 scripts/ingest-fa-payments       |  8 ++++----
 scripts/process-pending-payments |  2 +-
 4 files changed, 19 insertions(+), 14 deletions(-)

diff --git a/lib/Payment.php b/lib/Payment.php
index cbc2d3d1..71ae3049 100644
--- a/lib/Payment.php
+++ b/lib/Payment.php
@@ -68,7 +68,6 @@ class Payment{
 			if($this->User !== null && $this->User->Email !== null){
 				try{
 					$user = User::GetByEmail($this->User->Email);
-
 					// `User` exists, use their data.
 					$user->Name = $this->User->Name;
 					$this->User = $user;
@@ -82,8 +81,9 @@ class Payment{
 				}
 				catch(Exceptions\UserNotFoundException){
 					// User doesn't exist, create it now.
+					// Don't require an email address because we might be an anonymous `User`, or a matching donation from a fund.
 					try{
-						$this->User->Create();
+						$this->User->Create(requireEmail: false);
 					}
 					catch(Exceptions\UserExistsException | Exceptions\InvalidUserException){
 						// `User` already exists, pass.
diff --git a/lib/User.php b/lib/User.php
index 9e7309ac..ea95d644 100644
--- a/lib/User.php
+++ b/lib/User.php
@@ -189,11 +189,16 @@ class User{
 	/**
 	 * @throws Exceptions\InvalidUserException
 	 */
-	public function Validate(): void{
+	public function Validate(bool $requireEmail): void{
 		$error = new Exceptions\InvalidUserException();
 
-		if(!isset($this->Email)){
-			$error->Add(new Exceptions\EmailRequiredException());
+		if(trim($this->Email ?? '') == ''){
+			if($requireEmail){
+				$error->Add(new Exceptions\EmailRequiredException());
+			}
+			else{
+				$this->Email = null;
+			}
 		}
 		else{
 			if(filter_var($this->Email, FILTER_VALIDATE_EMAIL) === false){
@@ -238,10 +243,10 @@ class User{
 	 * @throws Exceptions\InvalidUserException
 	 * @throws Exceptions\UserExistsException
 	 */
-	public function Create(?string $password = null): void{
+	public function Create(?string $password = null, bool $requireEmail = true): void{
 		$this->GenerateUuid();
 
-		$this->Validate();
+		$this->Validate($requireEmail);
 
 		$this->Created = NOW;
 
@@ -270,8 +275,8 @@ class User{
 	 * @throws Exceptions\InvalidUserException
 	 * @throws Exceptions\UserExistsException
 	 */
-	public function Save(): void{
-		$this->Validate();
+	public function Save(bool $requireEmail = true): void{
+		$this->Validate($requireEmail);
 
 		$this->Updated = NOW;
 
diff --git a/scripts/ingest-fa-payments b/scripts/ingest-fa-payments
index 3fd565d2..8e92052b 100755
--- a/scripts/ingest-fa-payments
+++ b/scripts/ingest-fa-payments
@@ -1,6 +1,6 @@
 #!/usr/bin/php
 <?
-// Note: This script must be run as a user with a $HOME directory, otherwise Firefox won't be able to start with a profile.
+// Note: This script must be run as a user with a `$HOME` directory, otherwise Firefox won't be able to start with a profile.
 
 /**
  * FA is unreliable in the email notifications it sends. They are often missing.
@@ -50,8 +50,8 @@ $transactionIds = [];
 $today = NOW->format('n/j/Y');
 $faItemsPerPage = 20; // How many items are on a full page of FA results?
 
-// General plan: Read /tmp/last-fa-donation to see what the last transaction ID was that we processed.
-// If /tmp/last-fa-donation doesn't exist, get all transactions from today and create the file.
+// General plan: Read `/tmp/last-fa-donation` to see what the last transaction ID was that we processed.
+// If `/tmp/last-fa-donation` doesn't exist, get all transactions from today and create the file.
 
 function InsertTransaction(string $transactionId): bool{
 	$exists = Db::QueryBool('SELECT exists(
@@ -222,7 +222,7 @@ catch(Exception $ex){
 	$em->Send();
 }
 finally{
-	// `$driver` may be unintialized if we ctrl + c during Selenium initialization.
+	// `$driver` may be unintialized if we `ctrl + c` during Selenium initialization.
 	/** @phpstan-ignore nullsafe.neverNull */
 	$driver?->quit();
 }
diff --git a/scripts/process-pending-payments b/scripts/process-pending-payments
index 522a49a3..271e6cdf 100755
--- a/scripts/process-pending-payments
+++ b/scripts/process-pending-payments
@@ -89,7 +89,7 @@ try{
 				$driver->get('https://fundraising.fracturedatlas.org/admin/donations?query=' . $pendingPayment->TransactionId);
 
 				// Check if we need to log in to FA.
-				// Wait until the <body> element is visible, then check the current URL.
+				// Wait until the `<body>` element is visible, then check the current URL.
 				$driver->wait(20, 250)->until(WebDriverExpectedCondition::visibilityOfElementLocated(WebDriverBy::xpath('/html/body')));
 				if(stripos($driver->getCurrentURL(), 'auth0.com')){
 					$log->Write('Logging in to Fractured Atlas ...');