"""Billing status constants and canonical field documentation.

Subscription: plan_slug = internal identity, stripe_price_id = Stripe billing identity.
Legacy plan_id/plan_name kept for backward compatibility; prefer plan_slug.
"""
from __future__ import annotations

# Subscription statuses (Stripe-aligned)
SUBSCRIPTION_ACTIVE = "active"
SUBSCRIPTION_TRIALING = "trialing"
SUBSCRIPTION_PAST_DUE = "past_due"
SUBSCRIPTION_CANCELED = "canceled"
SUBSCRIPTION_INCOMPLETE = "incomplete"
SUBSCRIPTION_STATUSES = frozenset({
    SUBSCRIPTION_ACTIVE,
    SUBSCRIPTION_TRIALING,
    SUBSCRIPTION_PAST_DUE,
    SUBSCRIPTION_CANCELED,
    SUBSCRIPTION_INCOMPLETE,
})

# Purchase statuses
PURCHASE_PENDING = "pending"
PURCHASE_PAID = "paid"
PURCHASE_FAILED = "failed"
PURCHASE_REFUNDED = "refunded"
PURCHASE_CANCELED = "canceled"
PURCHASE_STATUSES = frozenset({
    PURCHASE_PENDING,
    PURCHASE_PAID,
    PURCHASE_FAILED,
    PURCHASE_REFUNDED,
    PURCHASE_CANCELED,
})

# Notification statuses
NOTIFICATION_QUEUED = "queued"
NOTIFICATION_SENT = "sent"
NOTIFICATION_FAILED = "failed"
NOTIFICATION_SKIPPED_DUPLICATE = "skipped_duplicate"
NOTIFICATION_STATUSES = frozenset({
    NOTIFICATION_QUEUED,
    NOTIFICATION_SENT,
    NOTIFICATION_FAILED,
    NOTIFICATION_SKIPPED_DUPLICATE,
})

# Catalog: self-serve checkout and public pricing hide amounts for this slug (sales-led).
ENTERPRISE_PLAN_SLUG = "enterprise"

# No Stripe subscription; workspace billing flags treat this as “no payment required”.
FREE_PLAN_SLUG = "free"

# Internal staff accounts — no Stripe subscription, treated same as free for billing.
STAFF_PLAN_SLUG = "staff"

# Ledger entry types
LEDGER_PURCHASE = "purchase"
LEDGER_CONSUMPTION = "consumption"
LEDGER_ADJUSTMENT = "adjustment"
LEDGER_REFUND = "refund"
LEDGER_BONUS = "bonus"
LEDGER_EXPIRATION = "expiration"