gitea-admin/gh-christianlouis-docuelevate
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(subscriptions): add subscription change management with upgrade/downgrade scheduling

Browse Source 
- Add subscription_change_pending_tier and subscription_change_pending_date fields to UserProfile
- Create migration 019_add_subscription_change_pending
- Add apply_pending_subscription_changes(), request_subscription_change(), cancel_pending_subscription_change() utilities
- Add POST /api/subscriptions/change and DELETE /api/subscriptions/change endpoints
- Update GET /api/subscriptions/my to apply pending changes and return pending change info
- Update subscription view to apply pending changes and pass period_start + pending info
- Update subscription.html: per-tier action buttons (upgrade/downgrade/cancel), pending-change banner, period start date
- Add Celery daily task apply_pending_subscription_changes_all at 00:05 UTC
- Add 19 new tests covering all new utility functions and API endpoints

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
2026-03-07 20:14:12 +00:00
parent 0599cf86b3
commit 231f983429
9 changed files with 1074 additions and 59 deletions
Download Patch File Download Diff File Expand all files Collapse all files
app/api/subscriptions.py
+127 -5
View File
@@ -1,9 +1,11 @@
"""API endpoints for subscription tiers and usage statistics.
Public endpoints:
GET /api/subscriptions/tiers — list all available plans
GET /api/subscriptions/my — current user's plan + usage (auth required)
GET /api/subscriptions/platform — platform-wide stats (admin only)
GET /api/subscriptions/tiers — list all available plans
GET /api/subscriptions/my — current user's plan + usage (auth required)
POST /api/subscriptions/change — request a plan change (auth required)
DELETE /api/subscriptions/change — cancel a pending plan change (auth required)
GET /api/subscriptions/platform — platform-wide stats (admin only)
"""
import logging
@@ -11,6 +13,7 @@ from datetime import datetime, timezone
from typing import Annotated, Any
from fastapi import APIRouter, Depends, HTTPException, Request, status
from pydantic import BaseModel
from sqlalchemy import func
from sqlalchemy.orm import Session
@@ -19,10 +22,14 @@ from app.database import get_db
from app.utils.subscription import (
TIER_ORDER,
TIERS,
SubscriptionChangeError,
apply_pending_subscription_changes,
cancel_pending_subscription_change,
get_all_tiers,
get_tier,
get_user_tier_id,
get_user_usage,
request_subscription_change,
)
logger = logging.getLogger(__name__)
@@ -33,6 +40,37 @@ DbSession = Annotated[Session, Depends(get_db)]
AdminUser = Annotated[dict, Depends(_require_admin)]
# ---------------------------------------------------------------------------
# Request / response models
# ---------------------------------------------------------------------------
class SubscriptionChangeRequest(BaseModel):
"""Request body for a subscription plan change."""
plan_id: str
billing_cycle: str = "monthly" # "monthly" | "yearly"
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
def _get_owner_id(request: Request) -> str:
"""Extract the authenticated user's owner_id from the session."""
user = request.session.get("user") or {}
return user.get("username") or user.get("email") or user.get("sub") or ""
def _require_authenticated(request: Request) -> str:
"""Return the owner_id or raise 401."""
owner_id = _get_owner_id(request)
if not owner_id:
raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Authentication required")
return owner_id
# ---------------------------------------------------------------------------
# Endpoints
# ---------------------------------------------------------------------------
@@ -50,8 +88,12 @@ def list_tiers() -> dict[str, Any]:
@router.get("/my", summary="Get current user's subscription and usage")
def my_subscription(request: Request, db: DbSession) -> dict[str, Any]:
"""Return the authenticated user's subscription tier and current usage counts."""
"""Return the authenticated user's subscription tier and current usage counts.
Also applies any pending subscription changes that have become due.
"""
from app.config import settings
from app.models import UserProfile
user = request.session.get("user")
@@ -67,18 +109,98 @@ def my_subscription(request: Request, db: DbSession) -> dict[str, Any]:
raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Authentication required")
owner_id: str = user.get("username") or user.get("email") or user.get("sub") or ""
# Apply any pending change that has become due
apply_pending_subscription_changes(db, owner_id)
tier_id = get_user_tier_id(db, owner_id)
tier = get_tier(tier_id)
tier = get_tier(tier_id, db)
usage = get_user_usage(db, owner_id)
profile = db.query(UserProfile).filter(UserProfile.user_id == owner_id).first()
pending_tier_id: str | None = profile.subscription_change_pending_tier if profile else None
pending_date: str | None = (
profile.subscription_change_pending_date.isoformat()
if profile and profile.subscription_change_pending_date
else None
)
period_start: str | None = (
profile.subscription_period_start.isoformat() if profile and profile.subscription_period_start else None
)
return {
"multi_user_mode": True,
"owner_id": owner_id,
"tier": tier,
"usage": usage,
"period_start": period_start,
"pending_change": (
{
"tier_id": pending_tier_id,
"tier": get_tier(pending_tier_id, db),
"effective_date": pending_date,
}
if pending_tier_id
else None
),
}
@router.post("/change", summary="Request a subscription plan change", status_code=status.HTTP_200_OK)
def change_subscription(request: Request, body: SubscriptionChangeRequest, db: DbSession) -> dict[str, Any]:
"""Request a subscription tier change.
**Upgrades** (moving to a higher-ranked plan) take effect immediately.
**Downgrades** (moving to a lower-ranked plan) are scheduled for the end
of the current billing period to prevent gaming. The user keeps their
current plan benefits until the scheduled date.
Requesting the currently active tier while a downgrade is pending cancels
that pending change.
"""
from app.config import settings
if not settings.multi_user_enabled:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Subscription management is not available in single-user mode.",
)
owner_id = _require_authenticated(request)
try:
result = request_subscription_change(db, owner_id, body.plan_id, body.billing_cycle)
except SubscriptionChangeError as exc:
raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc)) from exc
return result
@router.delete("/change", summary="Cancel a pending subscription change", status_code=status.HTTP_200_OK)
def cancel_subscription_change(request: Request, db: DbSession) -> dict[str, Any]:
"""Cancel a scheduled future subscription change.
Only downgrades can be pending; upgrades always take effect immediately.
Returns 404 when there is no pending change to cancel.
"""
from app.config import settings
if not settings.multi_user_enabled:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Subscription management is not available in single-user mode.",
)
owner_id = _require_authenticated(request)
cancelled = cancel_pending_subscription_change(db, owner_id)
if not cancelled:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="No pending subscription change found.")
return {"cancelled": True, "message": "Your pending subscription change has been cancelled."}
@router.get("/platform", summary="Platform-wide usage statistics (admin only)")
def platform_stats(request: Request, db: DbSession, _admin: AdminUser) -> dict[str, Any]:
"""Return aggregate statistics across all users and tiers (admin only)."""