api_utils_converse_v2/models/data/database/payment.py

"""

    AUTHOR:

        Khushal P Soonderji

    DATE:

        Saturday, 7th Dec., 2024.

    OBJECTIVE:

        To define how payment transactions will be stored in the database.

    REFERENCES:

        N/A

    DOWNLOADS:

        N/A

"""


#   *****************************************************************************************************************
#  *****                                                                                                          ****
# ***                                                   IMPORT                                                      ***
#  *****                                                                                                          ****
#   *****************************************************************************************************************


# To make sibling directories accessible for imports:
import sys
sys.path.append(".")
sys.path.append("..")

# For making data behaviour_models:
from pydantic import BaseModel, Field, field_validator, PastDatetime, AwareDatetime
from typing import Optional, Literal, Union

# My utils:
from utils_v2.string import regex
from utils_v2.date_time import date_time

# To work with MongoDB:
from bson.objectid import ObjectId

# To work with date and time:
import datetime

# To work with currencies:
import pycountry


#   *****************************************************************************************************************
#  *****                                                                                                          ****
# ***                                           MACROS / ONE-TIME INIT                                              ***
#  *****                                                                                                          ****
#   *****************************************************************************************************************


# --- Nothing Yet


#   *****************************************************************************************************************
#  *****                                                                                                          ****
# ***                                                VARIABLES                                                      ***
#  *****                                                                                                          ****
#   *****************************************************************************************************************


# --- Nothing Yet


#   *****************************************************************************************************************
#  *****                                                                                                          ****
# ***                                                  FUNCTIONS                                                    ***
#  *****                                                                                                          ****
#   *****************************************************************************************************************


class CorePaymentModel(BaseModel):

    version: str = Field(
        description = "a hint about the version no. of this message",
        min_length = 1,
        frozen = True,
        default = "1.0.0"
    )

    paymentStatus: Literal["requested", "paid", "rejected"] = Field(
        description = "the status of the payment request to see what stage of the process we are in",
        frozen = False,
        default = "requested"
    )

    requestTs: AwareDatetime = Field(
        description = "the time (utc) at which the payment request was initiated",
        frozen = True,
        default_factory = lambda: date_time.get_current_utc_date_time(as_string = False)
    )

    responseTs: AwareDatetime | None = Field(
        description = "the time (utc) at which the payer responded to the payment request",
        frozen = False,
        default = None
    )

    tokenId: ObjectId = Field(
        description = "the id of the auth token that is associated with this payment",
        frozen = True
    )

    amount: float | int = Field(
        description = "the amount of money being requested"
    )

    currencyCode: str = Field(
        description = "the three-letter ISO 4217 code to identify the currency",
        frozen = True,
        examples = ["INR", "USD", "KES"]
    )

    metadata: dict = Field(
        description = "any arbitrary amount of data to identify the user and payment details",
        frozen = True
    )

    client: Literal["razorpay", "safaricomMPesaExpress"] = Field(
        description = "the third-part client that was used",
        frozen = True
    )

    clientPaymentReferenceId: int | str = Field(
        description = "the reference id given by the third-party client",
        frozen = False,
        default = None
    )

    clientPaymentRequestHttpCode: int | str = Field(
        description = "the http code the third-party client returned when you requested the payment",
        frozen = False,
        default = None
    )

    clientPaymentRequestJSON: str | int = Field(
        description = "how the third-party client responded when you requested the payment",
        frozen = False,
        default = None
    )

    clientPaymentResponseHttpCode: int | str = Field(
        description = "the http code the third-party client returned when your user responded to the payment request",
        frozen = False,
        default = None
    )

    clientPaymentResponseJSON: str | int | None = Field(
        description = "how the third-party client responded when your user responded to the payment request",
        frozen = False,
        default = None
    )

    # ┏┓    ┏•
    # ┃ ┏┓┏┓╋┓┏┓
    # ┗┛┗┛┛┗┛┗┗┫
    #          ┛

    class Config:
        extra = "allow"
        arbitrary_types_allowed = True

    # ┓┏  ┓• ┓   •
    # ┃┃┏┓┃┓┏┫┏┓╋┓┏┓┏┓
    # ┗┛┗┻┗┗┗┻┗┻┗┗┗┛┛┗

    @field_validator("requestTs", "responseTs", mode = "before")
    def parse_date_time(cls, value):
        return date_time.parse_date_time(input_value = value, timezone = date_time.TIMEZONE_UTC)

    @field_validator("tokenId", mode = "before")
    def parse_oid(cls, value):
        try: value = ObjectId(value)
        except: pass
        return value

    @field_validator("currencyCode", mode = "before")
    def validate_currency(cls, value):
        currency = pycountry.currencies.get(alpha_3 = value)
        if currency is None: raise ValueError("invalid currency code, please use iso 4217 standard")
        return value


#   *****************************************************************************************************************
#  *****                                                                                                          ****
# ***                                               MAIN PROGRAM                                                    ***
#  *****                                                                                                          ****
#   *****************************************************************************************************************


if __name__ == "__main__":

    from utils_v2.string import json

    payment = CorePaymentModel(
        paymentStatus = "requested",
        tokenId = "67519cf3a7804fcbc6f12452",
        amount = 1.00,
        currencyCode = "INR",
        metadata = {
            "userId": 1,
            "name": "My Test"
        },
        client = "safaricomMPesaExpress"
    )

    print("PAYMENT TXN. MODEL:", json.to_string(payment.model_dump(), default = str))