feat(auth): implement user plans and credits system with related endpoints

app/models/plan.py

@@ -0,0 +1,58 @@
+"""Plan model for user subscription plans."""
+
+from sqlalchemy import Column, Integer, String, Text
+from sqlalchemy.orm import relationship
+
+from app.database import db
+
+
+class Plan(db.Model):
+    """Plan model for user subscription plans."""
+
+    __tablename__ = "plans"
+
+    id = Column(Integer, primary_key=True)
+    code = Column(String(50), unique=True, nullable=False, index=True)
+    name = Column(String(100), nullable=False)
+    description = Column(Text)
+    credits = Column(Integer, default=0, nullable=False)
+    max_credits = Column(Integer, default=0, nullable=False)
+
+    # Relationship with users
+    users = relationship("User", back_populates="plan", lazy="dynamic")
+
+    def __repr__(self) -> str:
+        """String representation of Plan."""
+        return f"<Plan {self.code}: {self.name}>"
+
+    @classmethod
+    def find_by_code(cls, code: str) -> "Plan | None":
+        """Find plan by code."""
+        return cls.query.filter_by(code=code).first()
+
+    @classmethod
+    def get_default_plan(cls) -> "Plan":
+        """Get the default plan (free)."""
+        plan = cls.find_by_code("free")
+        if not plan:
+            raise ValueError("Default 'free' plan not found in database")
+        return plan
+
+    @classmethod
+    def get_pro_plan(cls) -> "Plan":
+        """Get the pro plan."""
+        plan = cls.find_by_code("pro")
+        if not plan:
+            raise ValueError("'pro' plan not found in database")
+        return plan
+
+    def to_dict(self) -> dict:
+        """Convert plan to dictionary."""
+        return {
+            "id": self.id,
+            "code": self.code,
+            "name": self.name,
+            "description": self.description,
+            "credits": self.credits,
+            "max_credits": self.max_credits,
+        }