From 5fc4a45b44c58f9eeadd5cca68090b631ee16f2b Mon Sep 17 00:00:00 2001
From: stuppie
Date: Thu, 24 Sep 2026 11:01:26 -0600
Subject: add UserLedgerTransactionUserPayoutCancel

---
 generalresearch/models/thl/ledger.py             | 29 ++++++++++++++++++++++++
 generalresearch/models/thl/wallet/definitions.py |  2 ++
 pyproject.toml                                   |  2 +-
 3 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/generalresearch/models/thl/ledger.py b/generalresearch/models/thl/ledger.py
index 0db457f..01066fc 100644
--- a/generalresearch/models/thl/ledger.py
+++ b/generalresearch/models/thl/ledger.py
@@ -411,6 +411,12 @@ class LedgerTransaction(BaseModel):
                 d["amount"] = credits[0].amount
             d["tsid"] = self.metadata.get("thl_session")
             return UserLedgerTransactionTaskAdjustment.model_validate(d)
+        elif d["tx_type"] == TransactionType.USER_PAYOUT_CANCEL.value:
+            assert len(credits) == 1
+            d["amount"] = credits[0].amount
+            d["payout_id"] = self.metadata["payoutevent"]
+            d["description"] = "Payout Cancelled"
+            return UserLedgerTransactionUserPayoutCancel.model_validate(d)
 
 
 class UserLedgerTransaction(BaseModel):
@@ -496,6 +502,28 @@ class UserLedgerTransactionUserPayout(UserLedgerTransaction):
         return self
 
 
+class UserLedgerTransactionUserPayoutCancel(UserLedgerTransaction):
+    tx_type: Literal[TransactionType.USER_PAYOUT_CANCEL] = Field(
+        default=TransactionType.USER_PAYOUT_CANCEL
+    )
+    description: str = Field(default="Payout Cancelled", max_length=255)
+    payout_id: UUIDStr = Field(
+        description="A unique identifier for the payout",
+        examples=["a3848e0a53d64f68a74ced5f61b6eb68"],
+    )
+
+    def create_url(self, product_id: str) -> str | None:
+        return f"https://fsb.generalresearch.com/{product_id}/cashout/{self.payout_id}/"
+
+    @model_validator(mode="after")
+    def validate_amount(self):
+        assert self.amount > 0, (
+            "In a cancelled user payout, the amount should be positive because "
+            "it is returned to the user's wallet."
+        )
+        return self
+
+
 class UserLedgerTransactionUserBonus(UserLedgerTransaction):
     model_config = ConfigDict(
         extra="forbid",
@@ -598,6 +626,7 @@ class UserLedgerTransactionAttemptCredit(UserLedgerTransaction):
 
 UserLedgerTransactionType = Annotated[
     UserLedgerTransactionUserPayout
+    | UserLedgerTransactionUserPayoutCancel
     | UserLedgerTransactionUserBonus
     | UserLedgerTransactionTaskAdjustment
     | UserLedgerTransactionTaskComplete
diff --git a/generalresearch/models/thl/wallet/definitions.py b/generalresearch/models/thl/wallet/definitions.py
index 4474745..5f18e38 100644
--- a/generalresearch/models/thl/wallet/definitions.py
+++ b/generalresearch/models/thl/wallet/definitions.py
@@ -15,6 +15,8 @@ class PayoutType(StrEnum, metaclass=ReprEnumMeta):
     PAYPAL = "PAYPAL"
     # User is paid out via a Tango Gift Card
     TANGO = "TANGO"
+    # Tremendous Gift Card
+    TREMENDOUS = "TREMENDOUS"
     # DWOLLA
     DWOLLA = "DWOLLA"
     # A payment is made to a bank account using ACH
diff --git a/pyproject.toml b/pyproject.toml
index 0f3fd89..46ab5c3 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "generalresearch"
-version = "3.5.8"
+version = "3.5.9"
 description = "Python Utilities for General Research"
 readme = "README.md"
 requires-python = ">=3.14"
-- 
cgit v1.2.3