orion/app/modules/billing/schemas/billing.py

# app/modules/billing/schemas/billing.py
"""
Pydantic schemas for billing and subscription operations.

Used for admin subscription management and merchant-level billing.
"""

from datetime import datetime

from pydantic import BaseModel, ConfigDict, Field, field_validator


# ============================================================================
# Subscription Tier Schemas
# ============================================================================


class TierFeatureLimitEntry(BaseModel):
    """Feature limit entry for tier management."""

    feature_code: str
    limit_value: int | None = Field(None, description="None = unlimited for quantitative, ignored for binary")
    enabled: bool = True


class SubscriptionTierBase(BaseModel):
    """Base schema for subscription tier."""

    code: str = Field(..., min_length=1, max_length=30)
    name: str = Field(..., min_length=1, max_length=100)
    description: str | None = None
    price_monthly_cents: int = Field(..., ge=0)
    price_annual_cents: int | None = Field(None, ge=0)
    stripe_product_id: str | None = None
    stripe_price_monthly_id: str | None = None
    stripe_price_annual_id: str | None = None
    display_order: int = 0
    is_active: bool = True
    is_public: bool = True
    platform_id: int | None = None


class SubscriptionTierCreate(SubscriptionTierBase):
    """Schema for creating a subscription tier."""

    feature_limits: list[TierFeatureLimitEntry] = Field(default_factory=list)


class SubscriptionTierUpdate(BaseModel):
    """Schema for updating a subscription tier."""

    name: str | None = None
    description: str | None = None
    price_monthly_cents: int | None = Field(None, ge=0)
    price_annual_cents: int | None = Field(None, ge=0)
    stripe_product_id: str | None = None
    stripe_price_monthly_id: str | None = None
    stripe_price_annual_id: str | None = None
    display_order: int | None = None
    is_active: bool | None = None
    is_public: bool | None = None
    feature_limits: list[TierFeatureLimitEntry] | None = None


class SubscriptionTierResponse(BaseModel):
    """Schema for subscription tier response."""

    model_config = ConfigDict(from_attributes=True)

    id: int
    code: str
    name: str
    description: str | None = None
    price_monthly_cents: int
    price_annual_cents: int | None = None
    platform_id: int | None = None
    platform_name: str | None = None
    stripe_product_id: str | None = None
    stripe_price_monthly_id: str | None = None
    stripe_price_annual_id: str | None = None
    display_order: int
    is_active: bool
    is_public: bool
    feature_codes: list[str] = Field(default_factory=list)
    created_at: datetime
    updated_at: datetime

    @property
    def price_monthly_display(self) -> str:
        """Format monthly price for display."""
        return f"€{self.price_monthly_cents / 100:.2f}"

    @property
    def price_annual_display(self) -> str | None:
        """Format annual price for display."""
        if self.price_annual_cents is None:
            return None
        return f"€{self.price_annual_cents / 100:.2f}"


class SubscriptionTierListResponse(BaseModel):
    """Response for listing subscription tiers."""

    tiers: list[SubscriptionTierResponse]
    total: int


# ============================================================================
# Merchant Subscription Schemas (Admin View)
# ============================================================================


class MerchantSubscriptionAdminResponse(BaseModel):
    """Merchant subscription response for admin views."""

    model_config = ConfigDict(from_attributes=True)

    id: int
    merchant_id: int
    platform_id: int
    tier: str | None = None

    status: str
    is_annual: bool
    period_start: datetime
    period_end: datetime
    trial_ends_at: datetime | None = None

    stripe_customer_id: str | None = None
    stripe_subscription_id: str | None = None

    cancelled_at: datetime | None = None
    cancellation_reason: str | None = None

    payment_retry_count: int = 0
    last_payment_error: str | None = None

    created_at: datetime
    updated_at: datetime

    @field_validator("tier", mode="before")
    @classmethod
    def extract_tier_code(cls, v):
        """Convert SubscriptionTier ORM object to its code string."""
        if v is not None and hasattr(v, "code"):
            return v.code
        return v


class MerchantSubscriptionWithMerchant(MerchantSubscriptionAdminResponse):
    """Subscription response with merchant info."""

    merchant_name: str = ""
    platform_name: str = ""
    tier_name: str | None = None


class MerchantSubscriptionListResponse(BaseModel):
    """Response for listing merchant subscriptions."""

    subscriptions: list[MerchantSubscriptionWithMerchant]
    total: int
    page: int
    per_page: int
    pages: int


class MerchantSubscriptionAdminCreate(BaseModel):
    """Schema for admin creating a merchant subscription."""

    merchant_id: int
    platform_id: int
    tier_code: str = "essential"
    status: str = "trial"
    trial_days: int = 14
    is_annual: bool = False


class MerchantSubscriptionAdminUpdate(BaseModel):
    """Schema for admin updating a merchant subscription."""

    tier_code: str | None = None
    status: str | None = None
    trial_ends_at: datetime | None = None
    cancellation_reason: str | None = None


# ============================================================================
# Merchant Feature Override Schemas
# ============================================================================


class MerchantFeatureOverrideEntry(BaseModel):
    """Feature override for a specific merchant."""

    feature_code: str
    limit_value: int | None = None
    is_enabled: bool = True
    reason: str | None = None


class MerchantFeatureOverrideResponse(BaseModel):
    """Response for merchant feature override."""

    model_config = ConfigDict(from_attributes=True)

    id: int
    merchant_id: int
    platform_id: int
    feature_code: str
    limit_value: int | None = None
    is_enabled: bool
    reason: str | None = None
    created_at: datetime
    updated_at: datetime


# ============================================================================
# Billing History Schemas
# ============================================================================


class BillingHistoryResponse(BaseModel):
    """Schema for billing history entry."""

    model_config = ConfigDict(from_attributes=True)

    id: int
    store_id: int | None = None
    merchant_id: int | None = None
    stripe_invoice_id: str | None = None
    invoice_number: str | None = None
    invoice_date: datetime
    due_date: datetime | None = None

    # Amounts
    subtotal_cents: int
    tax_cents: int
    total_cents: int
    amount_paid_cents: int
    currency: str = "EUR"

    # Status
    status: str

    # URLs
    invoice_pdf_url: str | None = None
    hosted_invoice_url: str | None = None

    # Description
    description: str | None = None

    # Timestamps
    created_at: datetime

    @property
    def total_display(self) -> str:
        """Format total for display."""
        return f"€{self.total_cents / 100:.2f}"


class BillingHistoryWithMerchant(BillingHistoryResponse):
    """Billing history with merchant info."""

    merchant_name: str = ""


class BillingHistoryListResponse(BaseModel):
    """Response for listing billing history."""

    invoices: list[BillingHistoryResponse]
    total: int
    page: int
    per_page: int
    pages: int


# ============================================================================
# Checkout & Portal Schemas
# ============================================================================


class CheckoutRequest(BaseModel):
    """Request for creating checkout session."""

    tier_code: str
    is_annual: bool = False


class CheckoutResponse(BaseModel):
    """Response with checkout session URL."""

    checkout_url: str
    session_id: str


class PortalSessionResponse(BaseModel):
    """Response with customer portal URL."""

    portal_url: str


# ============================================================================
# Subscription Stats Schemas
# ============================================================================


class SubscriptionStatsResponse(BaseModel):
    """Subscription statistics for admin dashboard."""

    total_subscriptions: int
    active_count: int
    trial_count: int
    past_due_count: int
    cancelled_count: int
    expired_count: int

    # By tier
    tier_distribution: dict[str, int]

    # Revenue
    mrr_cents: int  # Monthly recurring revenue
    arr_cents: int  # Annual recurring revenue

    @property
    def mrr_display(self) -> str:
        """Format MRR for display."""
        return f"€{self.mrr_cents / 100:,.2f}"

    @property
    def arr_display(self) -> str:
        """Format ARR for display."""
        return f"€{self.arr_cents / 100:,.2f}"


# ============================================================================
# Feature Catalog Schemas
# ============================================================================


class FeatureDeclarationResponse(BaseModel):
    """Feature declaration for admin display."""

    code: str
    name_key: str
    description_key: str
    category: str
    feature_type: str
    scope: str
    default_limit: int | None = None
    unit_key: str | None = None
    is_per_period: bool = False
    ui_icon: str | None = None
    display_order: int = 0


class FeatureCatalogResponse(BaseModel):
    """All discovered features grouped by category."""

    features: dict[str, list[FeatureDeclarationResponse]]
    total_count: int