# generated by datamodel-codegen:
#   filename:  openapi.yaml
#   timestamp: 2026-06-25T12:37:57+00:00

from __future__ import annotations

from enum import Enum
from typing import Annotated, Any

from pydantic import BaseModel, Field


class Category(BaseModel):
    id: str | None = None
    """
    Unique identifier for the category
    """
    name: str | None = None
    """
    Category display name
    """
    slug: str | None = None
    """
    URL-friendly identifier
    """


class ProductEnrichment(BaseModel):
    gender: str | None = None
    """
    Target gender (Male, Female, Unisex)
    """
    product_type: str | None = None
    """
    Targeted product type (e.g., Eastern, Western)
    """
    sizing_guide: dict[str, Any] | None = None
    """
    Category-specific sizing information
    """


class Inventory(BaseModel):
    allow_out_of_stock: bool | None = None
    available_quantity: int | None = None
    """
    Number of units available
    """
    committed_quantity: int | None = None
    in_stock: bool | None = None
    """
    Flag indicating if the product is in stock
    """
    inventory_management: str | None = None
    inventory_policy: str | None = None
    low_stock_threshold: int | None = None
    quantity: int | None = None
    """
    --- v1 compatibility fields ---
    """
    reserved_quantity: int | None = None
    track_inventory: bool | None = None


class Option(BaseModel):
    name: str | None = None
    """
    Name of the option (e.g., Size, Color)
    """
    required: bool | None = None
    """
    Whether this option is required
    """
    values: list[str] | None = None
    """
    List of available values for this option
    """


class Pricing(BaseModel):
    brand_price: float | None = None
    """
    Raw price from Shopify or seller portal — base used for commission calculation
    """
    commission_rate: float | None = None
    """
    Juno's commission rate applied to the effective brand price (constant: 0.175)
    """
    compare_at_price: float | None = None
    """
    Original price before discount
    """
    cost_price: float | None = None
    """
    Seller's own purchase/production cost — entered manually, used only for profit calculation
    """
    currency: str | None = None
    """
    Currency code (e.g., PKR)
    """
    discount_type: str | None = None
    """
    Type of discount (e.g., "fixed", "percentage")
    """
    discount_value: float | None = None
    """
    Percentage of discount
    """
    discounted: bool | None = None
    """
    Flag indicating if the product is on sale
    """
    discounted_price: float | None = None
    """
    Price after applying discount
    """
    price: float | None = None
    """
    Current selling price
    """
    seller_payout: float | None = None
    """
    Amount transferred to the brand after deducting commission from effective brand price
    """
    shipping_included: bool | None = None
    """
    Set by seller: true = brand already embedded the Rs.99 shipping buffer into their listed price
    """


class Shipping(BaseModel):
    free_shipping: bool | None = None
    """
    Flag indicating if shipping is free
    """
    handling_time: int | None = None
    requires_shipping: bool | None = None
    shipping_class: str | None = None
    shipping_methods: list[str] | None = None
    shipping_zones: list[str] | None = None
    weight: float | None = None
    """
    --- v1 compatibility fields ---
    """
    weight_unit: str | None = None


class SizingGuide(BaseModel):
    measurement_unit: str | None = None
    """
    Measurement unit (e.g., "inches", "cm")
    """
    size_chart: dict[str, dict[str, float]] | None = None
    """
    Size chart mapping size names to measurements
    """
    size_fit: str | None = None
    """
    Human-readable size & fit description
    """


class VariantInventory(BaseModel):
    allow_out_of_stock: bool | None = None
    available_quantity: int | None = None
    committed_quantity: int | None = None
    in_stock: bool | None = None
    inventory_management: str | None = None
    inventory_policy: str | None = None
    low_stock_threshold: int | None = None
    quantity: int | None = None
    reserved_quantity: int | None = None
    sku: str | None = None
    track_inventory: bool | None = None


class Variant(BaseModel):
    available: bool | None = None
    """
    Availability flag
    """
    brand_price: float | None = None
    """
    Raw brand price for this variant before the display markup is applied
    """
    id: str | None = None
    """
    Unique identifier for the variant
    """
    inventory: VariantInventory | None = None
    """
    --- v1 compatibility fields ---
    Variant inventory details
    """
    is_default: bool | None = None
    """
    Whether this is the default variant
    """
    options: dict[str, str] | None = None
    """
    Map of option names to values (e.g., {"Size": "M"})
    """
    position: int | None = None
    """
    Display order position
    """
    price: float | None = None
    """
    Specific price for this variant
    """
    sku: str | None = None
    """
    Stock Keeping Unit
    """
    title: str | None = None
    """
    Variant title
    """


class Product(BaseModel):
    body_html: str | None = None
    """
    Raw HTML description from upstream sources (e.g., Shopify body_html)
    """
    categories: list[Category] | None = None
    """
    List of categories the product belongs to
    """
    collections: list[str] | None = None
    """
    --- v1 compatibility fields ---
    Collection IDs this product belongs to
    """
    created_at: str | None = None
    """
    Timestamp when the product was created
    """
    description: str | None = None
    """
    Full product description
    """
    enrichment: ProductEnrichment | None = None
    """
    Seller-supplied enrichment metadata (sizing guide, etc.)
    """
    gender: str | None = None
    """
    Target gender (Male, Female, Unisex) — set during enrichment
    """
    handle: str | None = None
    """
    URL-friendly identifier
    """
    id: str | None = None
    """
    Unique identifier for the product
    """
    images: list[str] | None = None
    """
    List of product image URLs
    """
    inventory: Inventory | None = None
    """
    Current inventory status
    """
    is_customizable: bool | None = None
    """
    Whether the product can be customized
    """
    is_featured: bool | None = None
    """
    Flag indicating if the product is featured
    """
    is_ready_to_wear: bool | None = None
    """
    Whether the product is ready to wear off-the-rack
    """
    is_trending: bool | None = None
    """
    Flag indicating if the product is trending
    """
    options: list[Option] | None = None
    """
    Configurable options for the product
    """
    pricing: Pricing | None = None
    """
    Pricing information
    """
    product_type: str | None = None
    """
    Type of product (e.g., Eastern, Western)
    """
    published_at: str | None = None
    """
    Timestamp when the product was published
    """
    purchase_count: int | None = None
    """
    Number of times this product has been purchased
    """
    rating: float | None = None
    """
    Average user rating
    """
    raw_id: str | None = None
    """
    External identifier from source (e.g., Shopify)
    """
    return_eligibility: bool | None = None
    """
    Whether the product is eligible for returns
    """
    review_count: int | None = None
    """
    Total number of reviews
    """
    seller_city: str | None = None
    """
    City where this brand ships from — used at checkout to classify within-city vs outside-city shipments
    """
    seller_id: str | None = None
    """
    Reference to the seller/brand ID
    """
    seller_logo: str | None = None
    """
    URL to the seller's logo
    """
    seller_name: str | None = None
    """
    Name of the seller/brand
    """
    shipping_details: Shipping | None = None
    """
    Shipping and handling details
    """
    short_description: str | None = None
    """
    Short summary of the product
    """
    sizing_guide: SizingGuide | None = None
    """
    Legacy top-level sizing guide (v1 compatibility) — prefer enrichment.sizing_guide
    """
    status: str | None = None
    """
    Lifecycle status (active, draft, archived)
    """
    tags: list[str] | None = None
    """
    Keywords for search and discovery
    """
    title: str | None = None
    """
    Product display name
    """
    updated_at: str | None = None
    """
    Timestamp when the product was last updated
    """
    variants: list[Variant] | None = None
    """
    Available product variants (sizes, colors, etc.)
    """
    video_url: str | None = None
    """
    URL to product video
    """
    view_count: int | None = None
    """
    Number of times this product has been viewed
    """


class Address(BaseModel):
    address_line1: str | None = None
    """
    Primary address line
    """
    address_line2: str | None = None
    """
    Secondary address line (optional)
    """
    address_type: str | None = None
    """
    Type of location (home, office, other)
    """
    city: str | None = None
    """
    City name
    """
    country: str | None = None
    """
    Country name
    """
    created_at: str | None = None
    """
    Timestamp when the address was saved
    """
    id: str | None = None
    """
    Unique identifier for the address
    """
    instructions: str | None = None
    """
    Delivery instructions for the rider
    """
    is_default: bool | None = None
    """
    Flag indicating if this is the user's primary address
    """
    latitude: float | None = None
    """
    Precise geographical coordinates
    """
    longitude: float | None = None
    name: str | None = None
    """
    Full name of the recipient
    """
    phone_number: str | None = None
    """
    Contact phone number (+92...)
    """
    postal_code: str | None = None
    """
    Area postal code
    """
    province: str | None = None
    """
    Province or state name
    """
    updated_at: str | None = None
    """
    Timestamp of the last update
    """
    user_id: str | None = None
    """
    ID of the user who owns this address
    """


class OrderFinancials(BaseModel):
    commission: float | None = None
    """
    subtotal * rate
    """
    commission_rate: float | None = None
    """
    captured at checkout
    """
    currency: str | None = None
    """
    "PKR"
    """
    discount_amount: float | None = None
    free_shipping_applied: bool | None = None
    seller_payout: float | None = None
    """
    subtotal - commission
    """
    shipping_fee: float | None = None
    """
    this child's share
    """
    subtotal: float | None = None
    """
    sum(line_total)
    """
    total: float | None = None
    """
    subtotal + shipping - discount
    """


class OrderItem(BaseModel):
    id: str | None = None
    line_total: float | None = None
    product_id: str | None = None
    product_image: str | None = None
    product_name: str | None = None
    """
    --- new snapshot fields ---
    """
    quantity: int | None = None
    seller_sku: str | None = None
    unit_price: float | None = None
    variant_id: str | None = None
    variant_label: str | None = None
    variant_options: dict[str, str] | None = None


class ShippingAddressSnapshot(BaseModel):
    address_line1: str | None = None
    address_line2: str | None = None
    city: str | None = None
    country: str | None = None
    email: str | None = None
    full_name: str | None = None
    instructions: str | None = None
    latitude: float | None = None
    longitude: float | None = None
    phone_number: str | None = None
    postal_code: str | None = None
    province: str | None = None


class OrderStatus(Enum):
    pending = 'pending'
    confirmed = 'confirmed'
    packed = 'packed'
    handed_to_rider = 'handed_to_rider'
    at_warehouse = 'at_warehouse'
    out_for_delivery = 'out_for_delivery'
    delivered = 'delivered'
    delivery_attempted = 'delivery_attempted'
    cancelled = 'cancelled'
    returned = 'returned'


class GeoPoint(BaseModel):
    city: str | None = None
    label: str | None = None
    """
    "Lahore Warehouse"
    """
    lat: float | None = None
    lng: float | None = None


class TrackingAnchors(BaseModel):
    customer: GeoPoint | None = None
    seller: GeoPoint | None = None
    warehouse: GeoPoint | None = None
    """
    filled at at_warehouse
    """


class TrackingMilestone(BaseModel):
    label: str | None = None
    """
    e.g. "Packed by Zara Closet"
    """
    location: GeoPoint | None = None
    note: str | None = None
    occurred_at: str | None = None
    set_by: str | None = None
    """
    user_id of seller/admin
    """
    status: OrderStatus | None = None


class OrderTracking(BaseModel):
    anchors: TrackingAnchors | None = None
    """
    fixed map points
    """
    current_status: OrderStatus | None = None
    estimated_delivery: str | None = None
    polyline: str | None = None
    timeline: list[TrackingMilestone] | None = None


class Order(BaseModel):
    campaign_id: str | None = None
    """
    ID of the campaign that drove this order
    """
    created_at: str | None = None
    """
    Timestamp when the order was created
    """
    customer_email: str | None = None
    customer_name: str | None = None
    customer_phone: str | None = None
    financials: OrderFinancials | None = None
    id: str | None = None
    """
    Unique identifier for the fulfillment group
    """
    old_order_number: str | None = None
    """
    Legacy order number retained after migration for backward compatibility
    """
    order_items: list[OrderItem] | None = None
    """
    List of items to be fulfilled by this seller
    """
    order_number: str | None = None
    """
    Display number for customer support
    """
    parent_order_id: str | None = None
    """
    Reference to the main transaction ID
    """
    seller_city: str | None = None
    seller_id: str | None = None
    """
    ID of the seller responsible for this part of the order
    """
    seller_name: str | None = None
    """
    --- new snapshot fields ---
    """
    shipping_address: ShippingAddressSnapshot | None = None
    status: OrderStatus | None = None
    """
    Current fulfillment status
    """
    total: float | None = None
    """
    Final total for this specific seller
    """
    tracking: OrderTracking | None = None
    """
    Tracking information
    """
    updated_at: str | None = None
    """
    Timestamp of last update
    """
    user_id: str | None = None
    """
    ID of the customer
    """


class MeasurementProfile(BaseModel):
    bust: float | None = None
    height: float | None = None
    hip: float | None = None
    inseam_length: float | None = None
    preferred_fit: str | None = None
    shoe_size: float | None = None
    shoe_size_system: str | None = None
    shoulder: float | None = None
    updated_at: str | None = None
    waist: float | None = None
    weight: float | None = None


class NotificationPrefs(BaseModel):
    email: bool | None = None
    """
    Enable/disable email notifications
    """
    push_notification: bool | None = None
    """
    Enable/disable push notifications
    """
    sms: bool | None = None
    """
    Enable/disable SMS notifications
    """


class UserPreferences(BaseModel):
    color_preferences: list[str] | None = None
    favorite_brands: list[str] | None = None
    favorite_categories: list[str] | None = None
    preferred_sizes: dict[str, str] | None = None
    price_range_max: float | None = None
    price_range_min: float | None = None
    style_preferences: list[str] | None = None


class RecentlyViewed(BaseModel):
    product_id: str | None = None
    viewed_at: str | None = None


class User(BaseModel):
    account_status: str | None = None
    """
    Current account status (active, inactive, suspended)
    """
    apple_id: str | None = None
    """
    Apple OAuth provider user ID — empty for phone-registered users
    """
    avatar: str | None = None
    """
    User's avatar image URL
    """
    created_at: str | None = None
    """
    Timestamp when the user registered
    """
    email: str | None = None
    """
    User's email address
    """
    gender: str | None = None
    """
    User's gender
    """
    google_id: str | None = None
    """
    Google OAuth provider user ID — empty for phone-registered users
    """
    id: str | None = None
    """
    Unique identifier for the user
    """
    institute: str | None = None
    """
    User's institute/university
    """
    last_login: str | None = None
    """
    Timestamp of the user's last successful login
    """
    measurement_profile: MeasurementProfile | None = None
    """
    Body measurements for fit prediction
    """
    name: str | None = None
    """
    User's full name
    """
    notification_prefs: NotificationPrefs | None = None
    """
    User's notification settings
    """
    phone_number: str | None = None
    """
    User's phone number. Kept for legacy accounts; new accounts use email as primary identifier.
    """
    preferences: UserPreferences | None = None
    """
    User's style and shopping preferences
    """
    profile_completion: int | None = None
    """
    Percentage of profile information completed
    """
    recently_viewed: list[RecentlyViewed] | None = None
    """
    Recently viewed products
    """
    referral_code: str | None = None
    """
    Referral code for growth tracking
    """
    referred_by: str | None = None
    """
    ID of the user who referred this user
    """
    role: str | None = None
    """
    User's role (user, admin, staff)
    """
    updated_at: str | None = None
    """
    Timestamp when the profile was last updated
    """
    verification_status: str | None = None
    """
    Phone verification status (verified, unverified)
    """


class CheckoutRequest(BaseModel):
    address_id: str
    """
    ID of the saved shipping address
    """
    campaign_id: str | None = None
    """
    Optional campaign attribution
    """
    payment_method: str
    """
    Selected payment method (e.g., cod, easypaisa)
    """


class CheckoutItem(BaseModel):
    product_id: str
    quantity: Annotated[int, Field(ge=1)]
    variant_id: str


class CheckoutDirectRequest(BaseModel):
    address_id: str
    """
    ID of the saved shipping address
    """
    campaign_id: str | None = None
    """
    Optional campaign attribution
    """
    items: list[CheckoutItem]
    """
    Items snapshot from the client at checkout time
    """
    payment_method: str
    """
    Selected payment method (e.g., cod, easypaisa)
    """


class CheckoutSummaryRequest(BaseModel):
    address_id: str | None = None
    buyer_city: str | None = None
    cart_id: str | None = None


class ShippingEstimateAllocation(BaseModel):
    fee: float | None = None
    quantity: int | None = None
    seller_city: str | None = None
    seller_id: str | None = None
    seller_name: str | None = None


class EligibleOffer(BaseModel):
    code: str | None = None
    description: str | None = None
    id: str | None = None


class CheckoutSummaryResponse(BaseModel):
    breakdown: list[ShippingEstimateAllocation] | None = None
    currency: str | None = None
    discount_amount: float | None = None
    eligible_offers: list[EligibleOffer] | None = None
    free_shipping_applied: bool | None = None
    shipping_total: float | None = None
    subtotal: float | None = None
    total: float | None = None


class GuestCheckoutDetails(BaseModel):
    address_line1: str | None = None
    address_line2: str | None = None
    city: str | None = None
    country: str | None = None
    email: str | None = None
    full_name: str | None = None
    latitude: float | None = None
    longitude: float | None = None
    phone_number: str | None = None
    postal_code: str | None = None
    province: str | None = None


class GuestCheckoutDetailsRequest(BaseModel):
    address_line1: str | None = None
    address_line2: str | None = None
    city: str | None = None
    country: str | None = None
    email: str | None = None
    full_name: str | None = None
    latitude: float | None = None
    longitude: float | None = None
    phone_number: str | None = None
    postal_code: str | None = None
    province: str | None = None


class GuestCheckoutRequest(BaseModel):
    campaign_id: str | None = None
    """
    Optional campaign attribution
    """
    payment_method: str | None = None


class GuestCheckoutDirectRequest(BaseModel):
    campaign_id: str | None = None
    """
    Optional campaign attribution
    """
    customer: GuestCheckoutDetailsRequest | None = None
    items: list[CheckoutItem] | None = None
    payment_method: str | None = None


class ApiError(BaseModel):
    code: str | None = None
    detail: str | None = None
    message: str | None = None
