(20250102) Testing receipt-add with structured metadata.

models/api/finstitutions/payments/request.py

@@ -41,13 +41,6 @@ from typing import Optional, Literal, Union, List, Any
 
 # My utils:
 from utils_v2.string import regex
-from utils_v2.date_time import date_time
-
-# Models:
-from models.core.payment import CorePaymentModel, PaymentMetadata
-
-# To work with date and time:
-import datetime
 
 # To work with MongoDB:
 from bson.objectid import ObjectId
@@ -108,6 +101,52 @@ class PGPaymentRequestHeaders(BaseModel):
 # ---------------------------------------------------------------------------------------------------------------------
 
 
+class PaymentRequestMetadata(BaseModel):
+
+    """
+    These are things that the UI will send you, and you must use them as-is for adding receipts. Their internal workings
+    and use-cases are not known and are not of this code's direct concern except that you must ensure that these details
+    get delivered through the mechanism of adding receipts.
+    """
+
+    idUser: int | None = Field(frozen = False, default = None, validate_default = True)
+    idClient: int = Field(frozen = True)
+    inAccount: int = Field(frozen = True)
+    reference: str | None = Field(frozen = True, default = None, validate_default = True)
+    againstReference: str | None = Field(frozen = True, default = None, validate_default = True)
+    documentUrl: str | None = Field(frozen = False, default = None, validate_default = True)
+
+    # ┏┓    ┏•
+    # ┃ ┏┓┏┓╋┓┏┓
+    # ┗┛┗┛┛┗┛┗┗┫
+    #          ┛
+
+    class Config:
+        extra = "allow"
+
+    # ┓┏  ┓• ┓   •
+    # ┃┃┏┓┃┓┏┫┏┓╋┓┏┓┏┓
+    # ┗┛┗┻┗┗┗┻┗┻┗┗┗┛┛┗
+
+    @field_validator("reference")
+    def validate_reference(cls, value):
+        if not value: value = "On Account"
+        return value
+
+    @field_validator("againstReference")
+    def validate_against_reference(cls, value):
+        if not value: value = None
+        return value
+
+    @field_validator("documentUrl")
+    def validate_document_url(cls, value):
+        if not value: value = None
+        return value
+
+
+# ---------------------------------------------------------------------------------------------------------------------
+
+
 class PGPaymentRequestData(BaseModel):
 
     tokenKey: ObjectId = Field(
@@ -159,7 +198,7 @@ class PGPaymentRequestData(BaseModel):
         frozen = True
     )
 
-    metadata: PaymentMetadata = Field(
+    metadata: PaymentRequestMetadata = Field(
         description = "any extra information about this payment",
         frozen = True
     )

models/core/payment.py

@@ -142,8 +142,9 @@ class PaymentMetadata(BaseModel):
     get delivered through the mechanism of adding receipts.
     """
 
-    idClient: int = Field(frozen = True)
-    inAccount: int = Field(frozen = True)
+    idUser: int | None = Field(frozen = True, default = None, validate_default = True)
+    idClient: int | None = Field(frozen = True, default = None, validate_default = True)
+    inAccount: int | None = Field(frozen = True, default = None, validate_default = True)
     reference: str | None = Field(frozen = True, default = None, validate_default = True)
     againstReference: str | None = Field(frozen = True, default = None, validate_default = True)
     documentUrl: str | None = Field(frozen = False, default = None, validate_default = True)
@@ -314,7 +315,7 @@ class CorePaymentModel(BaseModel):
         examples = ["INR", "USD", "KES"]
     )
 
-    metadata: dict | None = Field(
+    metadata: PaymentMetadata = Field(
         description = "any arbitrary amount of data to identify the user and payment details",
         frozen = True
     )