monkeybrain-runtime 1.0.0__py3-none-any.whl

services/orders/models/invoices.py

@@ -0,0 +1,415 @@
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from bson import ObjectId
+from pydantic import BaseModel, ConfigDict, EmailStr, Field
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class InvoiceStatus(str, Enum):
+    DRAFT = "draft"
+    PENDING = "pending"
+    SENT = "sent"
+    VIEWED = "viewed"
+    PAID = "paid"
+    PARTIALLY_PAID = "partially_paid"
+    OVERDUE = "overdue"
+    CANCELLED = "cancelled"
+    REFUNDED = "refunded"
+
+
+class RecurringFrequency(str, Enum):
+    DAILY = "daily"
+    WEEKLY = "weekly"
+    MONTHLY = "monthly"
+    QUARTERLY = "quarterly"
+    YEARLY = "yearly"
+
+
+class SendStatus(str, Enum):
+    QUEUED = "queued"
+    SENT = "sent"
+    DELIVERED = "delivered"
+    OPENED = "opened"
+    CLICKED = "clicked"
+    DOWNLOADED = "downloaded"
+    FAILED = "failed"
+
+
+class NoteType(str, Enum):
+    INTERNAL = "internal"
+    CUSTOMER = "customer"
+    TERMS = "terms"
+    PAYMENT_INSTRUCTIONS = "payment_instructions"
+
+
+class SourceType(str, Enum):
+    MANUAL = "manual"
+    QUOTE = "quote"
+    ESTIMATE = "estimate"
+    SALES_ORDER = "sales_order"
+    RECURRING = "recurring"
+    BULK_IMPORT = "bulk_import"
+
+
+class TaxDetail(BaseModel):
+    rate: Optional[str] = None
+    amount: Optional[str] = None
+
+    model_config = ConfigDict(extra="allow")
+
+
+class Seller(BaseModel):
+    name: Optional[str] = None
+    address: Optional[str] = None
+    gstin_uin: Optional[str] = None
+    gstin: Optional[str] = None
+    state_name: Optional[str] = None
+    state_code: Optional[str] = None
+    email: Optional[EmailStr] = None
+    phone: Optional[str] = None
+
+    model_config = ConfigDict(extra="allow")
+
+
+class Buyer(BaseModel):
+    name: Optional[str] = None
+    address: Optional[str] = None
+    gstin_uin: Optional[str] = None
+    gstin: Optional[str] = None
+    state_name: Optional[str] = None
+    state_code: Optional[str] = None
+    email: Optional[EmailStr] = None
+    phone: Optional[str] = None
+    customer_id: Optional[str] = None
+
+    model_config = ConfigDict(extra="allow")
+
+
+class InvoiceDetails(BaseModel):
+    invoice_no: Optional[str] = None
+    date: Optional[str] = None
+    due_date: Optional[str] = None
+    payment_terms: Optional[str] = None
+    ack_no: Optional[str] = None
+    ack_date: Optional[str] = None
+    irn: Optional[str] = None
+    challan_no: Optional[str] = None
+    challan_date: Optional[str] = None
+    reverse_charge: Optional[str] = None
+    lr_no: Optional[str] = None
+    transport: Optional[str] = None
+    transport_id: Optional[str] = None
+    vehicle_number: Optional[str] = None
+    po_number: Optional[str] = None
+
+    model_config = ConfigDict(extra="allow")
+
+
+class InvoiceItem(BaseModel):
+    sl_no: Optional[str] = None
+    si_no: Optional[str] = None
+    product_id: Optional[str] = None
+    description: Optional[str] = None
+    hsn_sac: Optional[str] = None
+    quantity: Optional[str] = None
+    rate: Optional[str] = None
+    per: Optional[str] = None
+    discount: Optional[str] = None
+    taxable_value: Optional[str] = None
+    amount: Optional[str] = None
+    cgst: Optional[TaxDetail | Dict[str, Any]] = None
+    sgst: Optional[TaxDetail | Dict[str, Any]] = None
+    igst: Optional[TaxDetail | Dict[str, Any]] = None
+    total: Optional[str] = None
+
+    model_config = ConfigDict(extra="allow")
+
+
+class InvoiceTotal(BaseModel):
+    taxable_value: Optional[str] = None
+    cgst_amount: Optional[str] = None
+    sgst_amount: Optional[str] = None
+    igst_amount: Optional[str] = None
+    total_tax_amount: Optional[str] = None
+    grand_total: Optional[str] = None
+    total_amount: Optional[str] = None
+    total_quantity: Optional[str] = None
+    amount_paid: Optional[str] = "0"
+    balance_due: Optional[str] = None
+
+    model_config = ConfigDict(extra="allow")
+
+
+class BankDetails(BaseModel):
+    bank_name: Optional[str] = None
+    branch_name: Optional[str] = None
+    account_number: Optional[str] = None
+    ifsc: Optional[str] = None
+
+    model_config = ConfigDict(extra="allow")
+
+
+class InvoiceAttachment(BaseModel):
+    id: Optional[str] = None
+    file_name: str
+    file_url: str
+    file_type: Optional[str] = None
+    file_size: Optional[int] = None
+    category: Optional[str] = None
+    uploaded_at: datetime = Field(default_factory=utc_now)
+    uploaded_by: Optional[str] = None
+
+
+class InvoiceNote(BaseModel):
+    note_type: NoteType
+    content: str
+    created_at: datetime = Field(default_factory=utc_now)
+    created_by: Optional[str] = None
+    updated_at: Optional[datetime] = None
+
+
+class InvoiceVersion(BaseModel):
+    version: int
+    data_snapshot: Dict[str, Any]
+    changes_summary: Optional[str] = None
+    created_at: datetime = Field(default_factory=utc_now)
+    created_by: Optional[str] = None
+    reason: Optional[str] = None
+
+
+class InvoiceSendLog(BaseModel):
+    sent_at: datetime = Field(default_factory=utc_now)
+    to: List[EmailStr]
+    cc: List[EmailStr] = Field(default_factory=list)
+    bcc: List[EmailStr] = Field(default_factory=list)
+    status: SendStatus
+    provider_response: Optional[Dict[str, Any]] = None
+    opened_at: Optional[datetime] = None
+    clicked_at: Optional[datetime] = None
+    downloaded_at: Optional[datetime] = None
+    delivery_confirmed_at: Optional[datetime] = None
+    error_message: Optional[str] = None
+    sent_by: Optional[str] = None
+
+
+class ScheduledSend(BaseModel):
+    scheduled_for: datetime
+    timezone: str = "UTC"
+    to: List[EmailStr]
+    cc: List[EmailStr] = Field(default_factory=list)
+    bcc: List[EmailStr] = Field(default_factory=list)
+    status: str = "queued"
+    created_at: datetime = Field(default_factory=utc_now)
+    sent_at: Optional[datetime] = None
+    cancelled_at: Optional[datetime] = None
+
+
+class InvoiceShareLink(BaseModel):
+    token: str
+    expires_at: Optional[datetime] = None
+    password_protected: bool = False
+    password_hash: Optional[str] = None
+    view_count: int = 0
+    last_accessed_at: Optional[datetime] = None
+    created_at: datetime = Field(default_factory=utc_now)
+    created_by: Optional[str] = None
+    is_active: bool = True
+
+
+class RecurringInvoiceConfig(BaseModel):
+    frequency: RecurringFrequency
+    start_date: datetime
+    end_date: Optional[datetime] = None
+    occurrences: Optional[int] = None
+    occurrences_completed: int = 0
+    auto_send: bool = True
+    auto_apply_payment_terms: bool = True
+    paused: bool = False
+    last_generated_at: Optional[datetime] = None
+    next_generation_date: Optional[datetime] = None
+    notify_before_generation: bool = True
+    notification_days_before: int = 3
+    allow_preview: bool = True
+    allow_edit_before_send: bool = True
+
+
+class SourceReference(BaseModel):
+    source_type: SourceType
+    source_id: Optional[str] = None
+    source_number: Optional[str] = None
+    conversion_date: Optional[datetime] = None
+    converted_by: Optional[str] = None
+
+
+class BulkImportInfo(BaseModel):
+    batch_id: str
+    import_date: datetime = Field(default_factory=utc_now)
+    source_file: str
+    row_number: Optional[int] = None
+    validation_errors: List[str] = Field(default_factory=list)
+
+
+class CustomerPortalAccess(BaseModel):
+    enabled: bool = True
+    customer_user_id: Optional[str] = None
+    last_login: Optional[datetime] = None
+    login_count: int = 0
+
+
+class InvoiceTrackingEvent(BaseModel):
+    event_type: str
+    timestamp: datetime = Field(default_factory=utc_now)
+    user_agent: Optional[str] = None
+    ip_address: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+
+class Invoice(BaseModel):
+    id: Optional[str] = None
+    seller: Optional[Seller] = None
+    buyer: Optional[Buyer] = None
+    invoice_details: Optional[InvoiceDetails] = None
+    items: List[InvoiceItem] = Field(default_factory=list)
+    total: Optional[InvoiceTotal] = None
+    bank_details: Optional[BankDetails] = None
+    amount_in_words: Optional[str] = None
+    tax_amount_in_words: Optional[str] = None
+    declaration: Optional[str] = None
+    status: InvoiceStatus = InvoiceStatus.DRAFT
+    source_reference: Optional[SourceReference] = None
+    bulk_import_info: Optional[BulkImportInfo] = None
+    attachments: List[InvoiceAttachment] = Field(default_factory=list)
+    notes: List[InvoiceNote] = Field(default_factory=list)
+    versions: List[InvoiceVersion] = Field(default_factory=list)
+    current_version: int = 1
+    send_logs: List[InvoiceSendLog] = Field(default_factory=list)
+    scheduled_sends: List[ScheduledSend] = Field(default_factory=list)
+    share_links: List[InvoiceShareLink] = Field(default_factory=list)
+    tracking_events: List[InvoiceTrackingEvent] = Field(default_factory=list)
+    recurring: Optional[RecurringInvoiceConfig] = None
+    parent_recurring_invoice_id: Optional[str] = None
+    customer_portal_access: Optional[CustomerPortalAccess] = None
+    created_at: datetime = Field(default_factory=utc_now)
+    updated_at: datetime = Field(default_factory=utc_now)
+    sent_at: Optional[datetime] = None
+    paid_at: Optional[datetime] = None
+    created_by: Optional[str] = None
+    updated_by: Optional[str] = None
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+        extra="allow",
+        json_encoders={ObjectId: str, datetime: lambda value: value.isoformat()},
+    )
+
+
+class InvoiceCreate(BaseModel):
+    seller: Optional[Seller] = None
+    buyer: Optional[Buyer] = None
+    invoice_details: Optional[InvoiceDetails] = None
+    items: List[InvoiceItem] = Field(default_factory=list)
+    total: Optional[InvoiceTotal] = None
+    bank_details: Optional[BankDetails] = None
+    amount_in_words: Optional[str] = None
+    tax_amount_in_words: Optional[str] = None
+    declaration: Optional[str] = None
+    status: InvoiceStatus = InvoiceStatus.DRAFT
+    source_reference: Optional[SourceReference] = None
+    recurring: Optional[RecurringInvoiceConfig] = None
+    notes: List[InvoiceNote] = Field(default_factory=list)
+    attachments: List[InvoiceAttachment] = Field(default_factory=list)
+    created_by: Optional[str] = None
+
+    model_config = ConfigDict(extra="allow")
+
+
+class InvoiceUpdate(BaseModel):
+    seller: Optional[Seller] = None
+    buyer: Optional[Buyer] = None
+    invoice_details: Optional[InvoiceDetails] = None
+    items: Optional[List[InvoiceItem]] = None
+    total: Optional[InvoiceTotal] = None
+    bank_details: Optional[BankDetails] = None
+    amount_in_words: Optional[str] = None
+    tax_amount_in_words: Optional[str] = None
+    declaration: Optional[str] = None
+    status: Optional[InvoiceStatus] = None
+    attachments: Optional[List[InvoiceAttachment]] = None
+    notes: Optional[List[InvoiceNote]] = None
+    recurring: Optional[RecurringInvoiceConfig] = None
+    updated_by: Optional[str] = None
+
+    model_config = ConfigDict(extra="allow")
+
+
+class BulkSendRequest(BaseModel):
+    invoice_ids: List[str]
+    to: Optional[List[EmailStr]] = None
+    cc: List[EmailStr] = Field(default_factory=list)
+    bcc: List[EmailStr] = Field(default_factory=list)
+    schedule_for: Optional[datetime] = None
+    timezone: str = "UTC"
+
+
+class ShareLinkRequest(BaseModel):
+    invoice_id: str
+    expires_in_days: Optional[int] = 30
+    password_protected: bool = False
+    password: Optional[str] = None
+
+
+class ScheduledSendRequest(BaseModel):
+    invoice_id: str
+    scheduled_for: datetime
+    timezone: str = "UTC"
+    to: List[EmailStr]
+    cc: List[EmailStr] = Field(default_factory=list)
+    bcc: List[EmailStr] = Field(default_factory=list)
+
+
+class BulkInvoiceRow(BaseModel):
+    seller_name: Optional[str] = None
+    buyer_name: Optional[str] = None
+    buyer_email: Optional[EmailStr] = None
+    invoice_date: Optional[str] = None
+    due_date: Optional[str] = None
+    items: List[Dict[str, Any]]
+    total_amount: Optional[str] = None
+
+
+class BulkCreateRequest(BaseModel):
+    batch_id: str
+    invoices: List[BulkInvoiceRow]
+    validate_only: bool = False
+    auto_send: bool = False
+
+
+class ConvertToInvoiceRequest(BaseModel):
+    source_type: SourceType
+    source_id: str
+    invoice_date: Optional[str] = None
+    due_date: Optional[str] = None
+    auto_send: bool = False
+    override_data: Optional[Dict[str, Any]] = None
+
+
+class VersionRestoreRequest(BaseModel):
+    invoice_id: str
+    version: int
+    reason: Optional[str] = None
+
+
+class InvoiceResponse(Invoice):
+    model_config = ConfigDict(from_attributes=True, extra="allow")
+
+
+class PaginatedInvoiceResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: List[InvoiceResponse]

services/orders/models/order_customer_metrics.py

@@ -0,0 +1,78 @@
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class CustomerOrderMetrics(BaseModel):
+    order_id: str = Field(..., description="Unique identifier for the order", example="ORD123456")
+    returns_exchanges_requested: Optional[int] = Field(None, description="Number of items requested for return or exchange", example=5)
+    backordered_items: Optional[int] = Field(None, description="Number of items that were backordered in the order", example=2)
+    shipping_tracking_number: Optional[str] = Field(None, description="Tracking number provided by the shipping carrier", example="12999AA10123456784")
+    order_fulfillment_location: Optional[str] = Field(None, description="Location from which the order was fulfilled, for example Warehouse A", example="Warehouse B")
+    customs_clearance_status: Optional[str] = Field(None, description="Customs status for international shipments, if applicable", example="Cleared")
+    order_handling_time: Optional[int] = Field(None, description="Time taken to handle and prepare the order before shipment in days", example=1)
+    shipping_status: Optional[str] = Field(None, description="Current status of the order's shipment, for example In Transit, Delivered, or Pending", example="In Transit")
+    order_delivery_time: Optional[int] = Field(None, description="Time taken for the order to be delivered from shipment in days", example=3)
+    customer_feedback_score: Optional[int] = Field(None, description="Customer rating or feedback score for the order experience from 1-10", example=8)
+    order_quality_rating: Optional[int] = Field(None, description="Rating based on the quality of the received items from 1-5", example=4)
+    failed_delivery_attempts: Optional[int] = Field(None, description="Number of failed delivery attempts for the order", example=1)
+    damage_defect_rate: Optional[float] = Field(None, description="Percentage of orders with damage or defects reported by the customer", example=2.0)
+    order_resolution_time: Optional[int] = Field(None, description="Time taken to resolve any issues in days", example=1)
+    customer_service_interaction_count: Optional[int] = Field(None, description="Number of customer service interactions for the order", example=2)
+    order_accuracy_rate: Optional[float] = Field(None, description="Percentage of orders that were fulfilled correctly", example=98.0)
+    late_shipment_rate: Optional[float] = Field(None, description="Percentage of orders shipped later than the expected date", example=4.0)
+    customer_loyalty_index: Optional[float] = Field(None, description="A score indicating the likelihood of the customer returning", example=85.0)
+    order_fulfillment_time: Optional[int] = Field(None, description="Total time taken to process an order from placement to delivery in days", example=10)
+    lead_time_variability: Optional[str] = Field(None, description="Consistency of lead times for fulfilling orders", example="±2 days")
+    cycle_time_for_time_sensitive_orders: Optional[int] = Field(None, description="Time taken to process and fulfill priority orders in days", example=5)
+    missed_priority_order_rate: Optional[float] = Field(None, description="Percentage of priority orders not fulfilled within the expected timeframe", example=3.0)
+    backlogged_order_rate: Optional[float] = Field(None, description="Percentage of orders delivered after the promised deadline", example=4.0)
+    critical_path_completion_rate: Optional[float] = Field(None, description="Percentage of critical path tasks completed on time", example=95.0)
+    order_cycle_time: Optional[int] = Field(None, description="Time from order placement to delivery in days", example=12)
+    order_fill_rate: Optional[float] = Field(None, description="Percentage of customer orders fully fulfilled on the first attempt", example=99.0)
+    perfect_order_rate: Optional[float] = Field(None, description="Percentage of orders delivered without issues", example=96.0)
+
+
+class CustomerOrderMetricsCreate(CustomerOrderMetrics):
+    pass
+
+
+class CustomerOrderMetricsUpdate(BaseModel):
+    returns_exchanges_requested: Optional[int] = None
+    backordered_items: Optional[int] = None
+    shipping_tracking_number: Optional[str] = None
+    order_fulfillment_location: Optional[str] = None
+    customs_clearance_status: Optional[str] = None
+    order_handling_time: Optional[int] = None
+    shipping_status: Optional[str] = None
+    order_delivery_time: Optional[int] = None
+    customer_feedback_score: Optional[int] = None
+    order_quality_rating: Optional[int] = None
+    failed_delivery_attempts: Optional[int] = None
+    damage_defect_rate: Optional[float] = None
+    order_resolution_time: Optional[int] = None
+    customer_service_interaction_count: Optional[int] = None
+    order_accuracy_rate: Optional[float] = None
+    late_shipment_rate: Optional[float] = None
+    customer_loyalty_index: Optional[float] = None
+    order_fulfillment_time: Optional[int] = None
+    lead_time_variability: Optional[str] = None
+    cycle_time_for_time_sensitive_orders: Optional[int] = None
+    missed_priority_order_rate: Optional[float] = None
+    backlogged_order_rate: Optional[float] = None
+    critical_path_completion_rate: Optional[float] = None
+    order_cycle_time: Optional[int] = None
+    order_fill_rate: Optional[float] = None
+    perfect_order_rate: Optional[float] = None
+
+
+class CustomerOrderMetricsResponse(CustomerOrderMetrics):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedCustomerOrderMetricsResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[CustomerOrderMetricsResponse]

services/orders/models/order_details.py

@@ -0,0 +1,46 @@
+from datetime import datetime, timezone
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+def datetime_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class OrderDetailsModel(BaseModel):
+    order_id: str = Field(..., description="Unique identifier for the order")
+    order_date: datetime = Field(default_factory=datetime_now)
+    order_status: str = Field(
+        ...,
+        description="Current status of the order, for example Pending, Shipped, Delivered, or Canceled",
+    )
+    order_type: str = Field(..., description="Type of order, for example Standard, Rush, or Backorder")
+    priority_level: Optional[str] = Field(None, description="Priority level of the order, for example High, Medium, or Low")
+    shipping_method: Optional[str] = Field(None, description="Shipping method used for the order, for example Ground or Air Freight")
+    payment_method: str = Field(..., description="Method used to pay for the order, for example Credit Card or Bank Transfer")
+
+
+class OrderDetailsCreate(OrderDetailsModel):
+    pass
+
+
+class OrderDetailsUpdate(BaseModel):
+    order_date: Optional[datetime] = None
+    order_status: Optional[str] = None
+    order_type: Optional[str] = None
+    priority_level: Optional[str] = None
+    shipping_method: Optional[str] = None
+    payment_method: Optional[str] = None
+
+
+class OrderDetailsResponse(OrderDetailsModel):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedOrderDetailsResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[OrderDetailsResponse]

services/orders/models/order_metadata.py

@@ -0,0 +1,60 @@
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class OrderMetadata(BaseModel):
+    order_id: Optional[str] = Field(None, description="Unique identifier for the order", example="ORD123456")
+    customer_segment: Optional[str] = Field(None, description="Segment of the customer, for example Retail, Wholesale, or VIP", example="VIP")
+    sales_region: Optional[str] = Field(None, description="Region where the sale occurred, for example North America, Europe, or Asia", example="North America")
+    salesperson: Optional[str] = Field(None, description="Name or ID of the salesperson responsible for the sale", example="Jane Smith")
+    sales_channel: Optional[str] = Field(None, description="The channel through which the sale occurred, for example Online, In-Store, or Distributor", example="Online")
+    customs_declaration_id: Optional[str] = Field(None, description="Customs declaration ID for the shipment", example="CD-98765432")
+    total_sales_value: Optional[float] = Field(None, gt=0, description="Total revenue generated from the product", example=200.0)
+    discount_applied: Optional[float] = Field(0.0, ge=0, description="Total discount applied to the product", example=20.0)
+    net_sales_value: Optional[float] = Field(None, gt=0, description="Revenue after discounts", example=180.0)
+    tax_amount: Optional[float] = Field(0.0, ge=0, description="Tax amount applied to the product", example=18.0)
+    shipping_charges: Optional[float] = Field(0.0, ge=0, description="Shipping charges for the product, if applicable", example=5.0)
+    total_revenue: Optional[float] = Field(None, gt=0, description="Total revenue including tax and shipping charges", example=203.0)
+    commission_rate: Optional[float] = Field(0.0, ge=0, le=100, description="Commission rate as a percentage", example=5.0)
+    commission_amount: Optional[float] = Field(0.0, ge=0, description="Total commission earned for the product", example=10.0)
+    promo_code_used: Optional[bool] = Field(False, description="Indicates whether a promo code was applied", example=True)
+    promo_code_value: Optional[float] = Field(0.0, ge=0, description="Value of the promo code discount", example=10.0)
+    upsell_or_cross_sell: Optional[str] = Field(None, description="Indicates if the product was part of an upsell or cross-sell strategy", example="Upsell")
+    refund_amount: Optional[float] = Field(0.0, ge=0, description="Refund amount issued for the product, if applicable", example=50.0)
+
+
+class OrderMetadataCreate(OrderMetadata):
+    pass
+
+
+class OrderMetadataUpdate(BaseModel):
+    customer_segment: Optional[str] = None
+    sales_region: Optional[str] = None
+    salesperson: Optional[str] = None
+    sales_channel: Optional[str] = None
+    customs_declaration_id: Optional[str] = None
+    total_sales_value: Optional[float] = Field(None, gt=0)
+    discount_applied: Optional[float] = Field(None, ge=0)
+    net_sales_value: Optional[float] = Field(None, gt=0)
+    tax_amount: Optional[float] = Field(None, ge=0)
+    shipping_charges: Optional[float] = Field(None, ge=0)
+    total_revenue: Optional[float] = Field(None, gt=0)
+    commission_rate: Optional[float] = Field(None, ge=0, le=100)
+    commission_amount: Optional[float] = Field(None, ge=0)
+    promo_code_used: Optional[bool] = None
+    promo_code_value: Optional[float] = Field(None, ge=0)
+    upsell_or_cross_sell: Optional[str] = None
+    refund_amount: Optional[float] = Field(None, ge=0)
+
+
+class OrderMetadataResponse(OrderMetadata):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedOrderMetadataResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[OrderMetadataResponse]

services/orders/models/order_payment_metadata.py

@@ -0,0 +1,63 @@
+from datetime import datetime, timezone
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+def datetime_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class OrderPaymentMetadata(BaseModel):
+    order_id: str = Field(..., description="Unique identifier for the order")
+    order_payment_status: Optional[str] = Field(None, description="Current payment status of the order", example="Paid")
+    payment_method: Optional[str] = Field(None, description="Method used by the customer to pay for the order", example="Credit Card")
+    payment_terms: Optional[str] = Field(None, description="Payment terms agreed upon with the customer", example="Net 30")
+    order_payment_due_date: Optional[datetime] = Field(None, description="Date by which payment is due for the order", example="2025-01-20")
+    payment_received_date: Optional[datetime] = Field(None, description="Actual date the payment was received", example="2025-01-15")
+    payment_amount: Optional[float] = Field(None, description="Total amount paid by the customer for the order", example=1200.0)
+    outstanding_payment_amount: Optional[float] = Field(None, description="Remaining balance to be paid on the order", example=0.0)
+    payment_overdue_amount: Optional[float] = Field(None, description="Total amount that is overdue for payment", example=150.0)
+    early_payment_discount: Optional[bool] = Field(None, description="Indicates whether an early payment discount has been applied", example=True)
+    late_payment_penalty: Optional[bool] = Field(None, description="Indicates whether a late payment penalty has been applied", example=True)
+    credit_limit_utilization: Optional[float] = Field(None, description="Percentage of the customer's available credit limit utilized", example=80.0)
+    customer_payment_history: Optional[str] = Field(None, description="Summary of historical payment behavior", example="Consistently Early")
+    payment_dispute_status: Optional[str] = Field(None, description="Indicates whether there is any payment dispute", example="Resolved")
+    payment_risk_rating: Optional[str] = Field(None, description="Risk level associated with the payment", example="Low")
+    payment_processing_time: Optional[int] = Field(None, description="Time taken for payment to be processed and received in days", example=3)
+    payment_approval_status: Optional[str] = Field(None, description="Status of payment approval", example="Approved")
+
+
+class OrderPaymentMetadataCreate(OrderPaymentMetadata):
+    pass
+
+
+class OrderPaymentMetadataUpdate(BaseModel):
+    order_payment_status: Optional[str] = None
+    payment_method: Optional[str] = None
+    payment_terms: Optional[str] = None
+    order_payment_due_date: Optional[datetime] = None
+    payment_received_date: Optional[datetime] = None
+    payment_amount: Optional[float] = None
+    outstanding_payment_amount: Optional[float] = None
+    payment_overdue_amount: Optional[float] = None
+    early_payment_discount: Optional[bool] = None
+    late_payment_penalty: Optional[bool] = None
+    credit_limit_utilization: Optional[float] = None
+    customer_payment_history: Optional[str] = None
+    payment_dispute_status: Optional[str] = None
+    payment_risk_rating: Optional[str] = None
+    payment_processing_time: Optional[int] = None
+    payment_approval_status: Optional[str] = None
+
+
+class OrderPaymentMetadataResponse(OrderPaymentMetadata):
+    class Config:
+        from_attributes = True
+
+
+class PaginatedOrderPaymentMetadataResponse(BaseModel):
+    total: int
+    page: int
+    page_size: int
+    results: list[OrderPaymentMetadataResponse]