Initial commit: MyCrib API in Go

Complete rewrite of Django REST API to Go with:
- Gin web framework for HTTP routing
- GORM for database operations
- GoAdmin for admin panel
- Gorush integration for push notifications
- Redis for caching and job queues

Features implemented:
- User authentication (login, register, logout, password reset)
- Residence management (CRUD, sharing, share codes)
- Task management (CRUD, kanban board, completions)
- Contractor management (CRUD, specialties)
- Document management (CRUD, warranties)
- Notifications (preferences, push notifications)
- Subscription management (tiers, limits)

Infrastructure:
- Docker Compose for local development
- Database migrations and seed data
- Admin panel for data management

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

internal/handlers/auth_handler.go

@@ -0,0 +1,364 @@
+package handlers
+
+import (
+	"errors"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"github.com/rs/zerolog/log"
+
+	"github.com/treytartt/mycrib-api/internal/dto/requests"
+	"github.com/treytartt/mycrib-api/internal/dto/responses"
+	"github.com/treytartt/mycrib-api/internal/middleware"
+	"github.com/treytartt/mycrib-api/internal/services"
+)
+
+// AuthHandler handles authentication endpoints
+type AuthHandler struct {
+	authService  *services.AuthService
+	emailService *services.EmailService
+	cache        *services.CacheService
+}
+
+// NewAuthHandler creates a new auth handler
+func NewAuthHandler(authService *services.AuthService, emailService *services.EmailService, cache *services.CacheService) *AuthHandler {
+	return &AuthHandler{
+		authService:  authService,
+		emailService: emailService,
+		cache:        cache,
+	}
+}
+
+// Login handles POST /api/auth/login/
+func (h *AuthHandler) Login(c *gin.Context) {
+	var req requests.LoginRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, responses.ErrorResponse{
+			Error: "Invalid request body",
+			Details: map[string]string{
+				"validation": err.Error(),
+			},
+		})
+		return
+	}
+
+	response, err := h.authService.Login(&req)
+	if err != nil {
+		status := http.StatusUnauthorized
+		message := "Invalid credentials"
+
+		if errors.Is(err, services.ErrUserInactive) {
+			message = "Account is inactive"
+		}
+
+		log.Debug().Err(err).Str("identifier", req.Username).Msg("Login failed")
+		c.JSON(status, responses.ErrorResponse{Error: message})
+		return
+	}
+
+	c.JSON(http.StatusOK, response)
+}
+
+// Register handles POST /api/auth/register/
+func (h *AuthHandler) Register(c *gin.Context) {
+	var req requests.RegisterRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, responses.ErrorResponse{
+			Error: "Invalid request body",
+			Details: map[string]string{
+				"validation": err.Error(),
+			},
+		})
+		return
+	}
+
+	response, confirmationCode, err := h.authService.Register(&req)
+	if err != nil {
+		status := http.StatusBadRequest
+		message := err.Error()
+
+		if errors.Is(err, services.ErrUsernameTaken) {
+			message = "Username already taken"
+		} else if errors.Is(err, services.ErrEmailTaken) {
+			message = "Email already registered"
+		} else {
+			status = http.StatusInternalServerError
+			message = "Registration failed"
+			log.Error().Err(err).Msg("Registration failed")
+		}
+
+		c.JSON(status, responses.ErrorResponse{Error: message})
+		return
+	}
+
+	// Send welcome email with confirmation code (async)
+	if h.emailService != nil && confirmationCode != "" {
+		go func() {
+			if err := h.emailService.SendWelcomeEmail(req.Email, req.FirstName, confirmationCode); err != nil {
+				log.Error().Err(err).Str("email", req.Email).Msg("Failed to send welcome email")
+			}
+		}()
+	}
+
+	c.JSON(http.StatusCreated, response)
+}
+
+// Logout handles POST /api/auth/logout/
+func (h *AuthHandler) Logout(c *gin.Context) {
+	token := middleware.GetAuthToken(c)
+	if token == "" {
+		c.JSON(http.StatusUnauthorized, responses.ErrorResponse{Error: "Not authenticated"})
+		return
+	}
+
+	// Invalidate token in database
+	if err := h.authService.Logout(token); err != nil {
+		log.Warn().Err(err).Msg("Failed to delete token from database")
+	}
+
+	// Invalidate token in cache
+	if h.cache != nil {
+		if err := h.cache.InvalidateAuthToken(c.Request.Context(), token); err != nil {
+			log.Warn().Err(err).Msg("Failed to invalidate token in cache")
+		}
+	}
+
+	c.JSON(http.StatusOK, responses.MessageResponse{Message: "Logged out successfully"})
+}
+
+// CurrentUser handles GET /api/auth/me/
+func (h *AuthHandler) CurrentUser(c *gin.Context) {
+	user := middleware.MustGetAuthUser(c)
+	if user == nil {
+		return
+	}
+
+	response, err := h.authService.GetCurrentUser(user.ID)
+	if err != nil {
+		log.Error().Err(err).Uint("user_id", user.ID).Msg("Failed to get current user")
+		c.JSON(http.StatusInternalServerError, responses.ErrorResponse{Error: "Failed to get user"})
+		return
+	}
+
+	c.JSON(http.StatusOK, response)
+}
+
+// UpdateProfile handles PUT/PATCH /api/auth/profile/
+func (h *AuthHandler) UpdateProfile(c *gin.Context) {
+	user := middleware.MustGetAuthUser(c)
+	if user == nil {
+		return
+	}
+
+	var req requests.UpdateProfileRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, responses.ErrorResponse{
+			Error: "Invalid request body",
+			Details: map[string]string{
+				"validation": err.Error(),
+			},
+		})
+		return
+	}
+
+	response, err := h.authService.UpdateProfile(user.ID, &req)
+	if err != nil {
+		if errors.Is(err, services.ErrEmailTaken) {
+			c.JSON(http.StatusBadRequest, responses.ErrorResponse{Error: "Email already taken"})
+			return
+		}
+
+		log.Error().Err(err).Uint("user_id", user.ID).Msg("Failed to update profile")
+		c.JSON(http.StatusInternalServerError, responses.ErrorResponse{Error: "Failed to update profile"})
+		return
+	}
+
+	c.JSON(http.StatusOK, response)
+}
+
+// VerifyEmail handles POST /api/auth/verify-email/
+func (h *AuthHandler) VerifyEmail(c *gin.Context) {
+	user := middleware.MustGetAuthUser(c)
+	if user == nil {
+		return
+	}
+
+	var req requests.VerifyEmailRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, responses.ErrorResponse{
+			Error: "Invalid request body",
+			Details: map[string]string{
+				"validation": err.Error(),
+			},
+		})
+		return
+	}
+
+	err := h.authService.VerifyEmail(user.ID, req.Code)
+	if err != nil {
+		status := http.StatusBadRequest
+		message := err.Error()
+
+		if errors.Is(err, services.ErrInvalidCode) {
+			message = "Invalid verification code"
+		} else if errors.Is(err, services.ErrCodeExpired) {
+			message = "Verification code has expired"
+		} else if errors.Is(err, services.ErrAlreadyVerified) {
+			message = "Email already verified"
+		} else {
+			status = http.StatusInternalServerError
+			message = "Verification failed"
+			log.Error().Err(err).Uint("user_id", user.ID).Msg("Email verification failed")
+		}
+
+		c.JSON(status, responses.ErrorResponse{Error: message})
+		return
+	}
+
+	c.JSON(http.StatusOK, responses.VerifyEmailResponse{
+		Message:  "Email verified successfully",
+		Verified: true,
+	})
+}
+
+// ResendVerification handles POST /api/auth/resend-verification/
+func (h *AuthHandler) ResendVerification(c *gin.Context) {
+	user := middleware.MustGetAuthUser(c)
+	if user == nil {
+		return
+	}
+
+	code, err := h.authService.ResendVerificationCode(user.ID)
+	if err != nil {
+		if errors.Is(err, services.ErrAlreadyVerified) {
+			c.JSON(http.StatusBadRequest, responses.ErrorResponse{Error: "Email already verified"})
+			return
+		}
+
+		log.Error().Err(err).Uint("user_id", user.ID).Msg("Failed to resend verification")
+		c.JSON(http.StatusInternalServerError, responses.ErrorResponse{Error: "Failed to resend verification"})
+		return
+	}
+
+	// Send verification email (async)
+	if h.emailService != nil {
+		go func() {
+			if err := h.emailService.SendVerificationEmail(user.Email, user.FirstName, code); err != nil {
+				log.Error().Err(err).Str("email", user.Email).Msg("Failed to send verification email")
+			}
+		}()
+	}
+
+	c.JSON(http.StatusOK, responses.MessageResponse{Message: "Verification email sent"})
+}
+
+// ForgotPassword handles POST /api/auth/forgot-password/
+func (h *AuthHandler) ForgotPassword(c *gin.Context) {
+	var req requests.ForgotPasswordRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, responses.ErrorResponse{
+			Error: "Invalid request body",
+			Details: map[string]string{
+				"validation": err.Error(),
+			},
+		})
+		return
+	}
+
+	code, user, err := h.authService.ForgotPassword(req.Email)
+	if err != nil {
+		if errors.Is(err, services.ErrRateLimitExceeded) {
+			c.JSON(http.StatusTooManyRequests, responses.ErrorResponse{
+				Error: "Too many password reset requests. Please try again later.",
+			})
+			return
+		}
+
+		log.Error().Err(err).Str("email", req.Email).Msg("Forgot password failed")
+		// Don't reveal errors to prevent email enumeration
+	}
+
+	// Send password reset email (async) - only if user found
+	if h.emailService != nil && code != "" && user != nil {
+		go func() {
+			if err := h.emailService.SendPasswordResetEmail(user.Email, user.FirstName, code); err != nil {
+				log.Error().Err(err).Str("email", user.Email).Msg("Failed to send password reset email")
+			}
+		}()
+	}
+
+	// Always return success to prevent email enumeration
+	c.JSON(http.StatusOK, responses.ForgotPasswordResponse{
+		Message: "If an account with that email exists, a password reset code has been sent.",
+	})
+}
+
+// VerifyResetCode handles POST /api/auth/verify-reset-code/
+func (h *AuthHandler) VerifyResetCode(c *gin.Context) {
+	var req requests.VerifyResetCodeRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, responses.ErrorResponse{
+			Error: "Invalid request body",
+			Details: map[string]string{
+				"validation": err.Error(),
+			},
+		})
+		return
+	}
+
+	resetToken, err := h.authService.VerifyResetCode(req.Email, req.Code)
+	if err != nil {
+		status := http.StatusBadRequest
+		message := "Invalid verification code"
+
+		if errors.Is(err, services.ErrCodeExpired) {
+			message = "Verification code has expired"
+		} else if errors.Is(err, services.ErrRateLimitExceeded) {
+			status = http.StatusTooManyRequests
+			message = "Too many attempts. Please request a new code."
+		}
+
+		c.JSON(status, responses.ErrorResponse{Error: message})
+		return
+	}
+
+	c.JSON(http.StatusOK, responses.VerifyResetCodeResponse{
+		Message:    "Code verified successfully",
+		ResetToken: resetToken,
+	})
+}
+
+// ResetPassword handles POST /api/auth/reset-password/
+func (h *AuthHandler) ResetPassword(c *gin.Context) {
+	var req requests.ResetPasswordRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, responses.ErrorResponse{
+			Error: "Invalid request body",
+			Details: map[string]string{
+				"validation": err.Error(),
+			},
+		})
+		return
+	}
+
+	err := h.authService.ResetPassword(req.ResetToken, req.NewPassword)
+	if err != nil {
+		status := http.StatusBadRequest
+		message := "Invalid or expired reset token"
+
+		if errors.Is(err, services.ErrInvalidResetToken) {
+			message = "Invalid or expired reset token"
+		} else {
+			status = http.StatusInternalServerError
+			message = "Password reset failed"
+			log.Error().Err(err).Msg("Password reset failed")
+		}
+
+		c.JSON(status, responses.ErrorResponse{Error: message})
+		return
+	}
+
+	c.JSON(http.StatusOK, responses.ResetPasswordResponse{
+		Message: "Password reset successfully. Please log in with your new password.",
+	})
+}

internal/handlers/contractor_handler.go

@@ -0,0 +1,192 @@
+package handlers
+
+import (
+	"errors"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/treytartt/mycrib-api/internal/dto/requests"
+	"github.com/treytartt/mycrib-api/internal/middleware"
+	"github.com/treytartt/mycrib-api/internal/models"
+	"github.com/treytartt/mycrib-api/internal/services"
+)
+
+// ContractorHandler handles contractor-related HTTP requests
+type ContractorHandler struct {
+	contractorService *services.ContractorService
+}
+
+// NewContractorHandler creates a new contractor handler
+func NewContractorHandler(contractorService *services.ContractorService) *ContractorHandler {
+	return &ContractorHandler{contractorService: contractorService}
+}
+
+// ListContractors handles GET /api/contractors/
+func (h *ContractorHandler) ListContractors(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	response, err := h.contractorService.ListContractors(user.ID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, response)
+}
+
+// GetContractor handles GET /api/contractors/:id/
+func (h *ContractorHandler) GetContractor(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	contractorID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid contractor ID"})
+		return
+	}
+
+	response, err := h.contractorService.GetContractor(uint(contractorID), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrContractorNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrContractorAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, response)
+}
+
+// CreateContractor handles POST /api/contractors/
+func (h *ContractorHandler) CreateContractor(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	var req requests.CreateContractorRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	response, err := h.contractorService.CreateContractor(&req, user.ID)
+	if err != nil {
+		if errors.Is(err, services.ErrResidenceAccessDenied) {
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusCreated, response)
+}
+
+// UpdateContractor handles PUT/PATCH /api/contractors/:id/
+func (h *ContractorHandler) UpdateContractor(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	contractorID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid contractor ID"})
+		return
+	}
+
+	var req requests.UpdateContractorRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	response, err := h.contractorService.UpdateContractor(uint(contractorID), user.ID, &req)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrContractorNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrContractorAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, response)
+}
+
+// DeleteContractor handles DELETE /api/contractors/:id/
+func (h *ContractorHandler) DeleteContractor(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	contractorID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid contractor ID"})
+		return
+	}
+
+	err = h.contractorService.DeleteContractor(uint(contractorID), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrContractorNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrContractorAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "Contractor deleted successfully"})
+}
+
+// ToggleFavorite handles POST /api/contractors/:id/toggle-favorite/
+func (h *ContractorHandler) ToggleFavorite(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	contractorID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid contractor ID"})
+		return
+	}
+
+	response, err := h.contractorService.ToggleFavorite(uint(contractorID), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrContractorNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrContractorAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, response)
+}
+
+// GetContractorTasks handles GET /api/contractors/:id/tasks/
+func (h *ContractorHandler) GetContractorTasks(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	contractorID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid contractor ID"})
+		return
+	}
+
+	response, err := h.contractorService.GetContractorTasks(uint(contractorID), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrContractorNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrContractorAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, response)
+}
+
+// GetSpecialties handles GET /api/contractors/specialties/
+func (h *ContractorHandler) GetSpecialties(c *gin.Context) {
+	specialties, err := h.contractorService.GetSpecialties()
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, specialties)
+}

internal/handlers/document_handler.go

@@ -0,0 +1,193 @@
+package handlers
+
+import (
+	"errors"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/treytartt/mycrib-api/internal/dto/requests"
+	"github.com/treytartt/mycrib-api/internal/middleware"
+	"github.com/treytartt/mycrib-api/internal/models"
+	"github.com/treytartt/mycrib-api/internal/services"
+)
+
+// DocumentHandler handles document-related HTTP requests
+type DocumentHandler struct {
+	documentService *services.DocumentService
+}
+
+// NewDocumentHandler creates a new document handler
+func NewDocumentHandler(documentService *services.DocumentService) *DocumentHandler {
+	return &DocumentHandler{documentService: documentService}
+}
+
+// ListDocuments handles GET /api/documents/
+func (h *DocumentHandler) ListDocuments(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	response, err := h.documentService.ListDocuments(user.ID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, response)
+}
+
+// GetDocument handles GET /api/documents/:id/
+func (h *DocumentHandler) GetDocument(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	documentID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid document ID"})
+		return
+	}
+
+	response, err := h.documentService.GetDocument(uint(documentID), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrDocumentNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrDocumentAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, response)
+}
+
+// ListWarranties handles GET /api/documents/warranties/
+func (h *DocumentHandler) ListWarranties(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	response, err := h.documentService.ListWarranties(user.ID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, response)
+}
+
+// CreateDocument handles POST /api/documents/
+func (h *DocumentHandler) CreateDocument(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	var req requests.CreateDocumentRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	response, err := h.documentService.CreateDocument(&req, user.ID)
+	if err != nil {
+		if errors.Is(err, services.ErrResidenceAccessDenied) {
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusCreated, response)
+}
+
+// UpdateDocument handles PUT/PATCH /api/documents/:id/
+func (h *DocumentHandler) UpdateDocument(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	documentID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid document ID"})
+		return
+	}
+
+	var req requests.UpdateDocumentRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	response, err := h.documentService.UpdateDocument(uint(documentID), user.ID, &req)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrDocumentNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrDocumentAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, response)
+}
+
+// DeleteDocument handles DELETE /api/documents/:id/
+func (h *DocumentHandler) DeleteDocument(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	documentID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid document ID"})
+		return
+	}
+
+	err = h.documentService.DeleteDocument(uint(documentID), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrDocumentNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrDocumentAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "Document deleted successfully"})
+}
+
+// ActivateDocument handles POST /api/documents/:id/activate/
+func (h *DocumentHandler) ActivateDocument(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	documentID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid document ID"})
+		return
+	}
+
+	response, err := h.documentService.ActivateDocument(uint(documentID), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrDocumentNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrDocumentAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "Document activated", "document": response})
+}
+
+// DeactivateDocument handles POST /api/documents/:id/deactivate/
+func (h *DocumentHandler) DeactivateDocument(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	documentID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid document ID"})
+		return
+	}
+
+	response, err := h.documentService.DeactivateDocument(uint(documentID), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrDocumentNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrDocumentAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "Document deactivated", "document": response})
+}

internal/handlers/notification_handler.go

@@ -0,0 +1,197 @@
+package handlers
+
+import (
+	"errors"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/treytartt/mycrib-api/internal/middleware"
+	"github.com/treytartt/mycrib-api/internal/models"
+	"github.com/treytartt/mycrib-api/internal/services"
+)
+
+// NotificationHandler handles notification-related HTTP requests
+type NotificationHandler struct {
+	notificationService *services.NotificationService
+}
+
+// NewNotificationHandler creates a new notification handler
+func NewNotificationHandler(notificationService *services.NotificationService) *NotificationHandler {
+	return &NotificationHandler{notificationService: notificationService}
+}
+
+// ListNotifications handles GET /api/notifications/
+func (h *NotificationHandler) ListNotifications(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	limit := 50
+	offset := 0
+	if l := c.Query("limit"); l != "" {
+		if parsed, err := strconv.Atoi(l); err == nil && parsed > 0 {
+			limit = parsed
+		}
+	}
+	if o := c.Query("offset"); o != "" {
+		if parsed, err := strconv.Atoi(o); err == nil && parsed >= 0 {
+			offset = parsed
+		}
+	}
+
+	notifications, err := h.notificationService.GetNotifications(user.ID, limit, offset)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"count":   len(notifications),
+		"results": notifications,
+	})
+}
+
+// GetUnreadCount handles GET /api/notifications/unread-count/
+func (h *NotificationHandler) GetUnreadCount(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	count, err := h.notificationService.GetUnreadCount(user.ID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"unread_count": count})
+}
+
+// MarkAsRead handles POST /api/notifications/:id/read/
+func (h *NotificationHandler) MarkAsRead(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	notificationID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid notification ID"})
+		return
+	}
+
+	err = h.notificationService.MarkAsRead(uint(notificationID), user.ID)
+	if err != nil {
+		if errors.Is(err, services.ErrNotificationNotFound) {
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"message": "Notification marked as read"})
+}
+
+// MarkAllAsRead handles POST /api/notifications/mark-all-read/
+func (h *NotificationHandler) MarkAllAsRead(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	err := h.notificationService.MarkAllAsRead(user.ID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"message": "All notifications marked as read"})
+}
+
+// GetPreferences handles GET /api/notifications/preferences/
+func (h *NotificationHandler) GetPreferences(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	prefs, err := h.notificationService.GetPreferences(user.ID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, prefs)
+}
+
+// UpdatePreferences handles PUT/PATCH /api/notifications/preferences/
+func (h *NotificationHandler) UpdatePreferences(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	var req services.UpdatePreferencesRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	prefs, err := h.notificationService.UpdatePreferences(user.ID, &req)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, prefs)
+}
+
+// RegisterDevice handles POST /api/notifications/devices/
+func (h *NotificationHandler) RegisterDevice(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	var req services.RegisterDeviceRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	device, err := h.notificationService.RegisterDevice(user.ID, &req)
+	if err != nil {
+		if errors.Is(err, services.ErrInvalidPlatform) {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusCreated, device)
+}
+
+// ListDevices handles GET /api/notifications/devices/
+func (h *NotificationHandler) ListDevices(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	devices, err := h.notificationService.ListDevices(user.ID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, devices)
+}
+
+// DeleteDevice handles DELETE /api/notifications/devices/:id/
+func (h *NotificationHandler) DeleteDevice(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	deviceID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid device ID"})
+		return
+	}
+
+	platform := c.Query("platform")
+	if platform == "" {
+		platform = "ios" // Default to iOS
+	}
+
+	err = h.notificationService.DeleteDevice(uint(deviceID), platform, user.ID)
+	if err != nil {
+		if errors.Is(err, services.ErrInvalidPlatform) {
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"message": "Device removed"})
+}

internal/handlers/residence_handler.go

@@ -0,0 +1,288 @@
+package handlers
+
+import (
+	"errors"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/treytartt/mycrib-api/internal/dto/requests"
+	"github.com/treytartt/mycrib-api/internal/middleware"
+	"github.com/treytartt/mycrib-api/internal/models"
+	"github.com/treytartt/mycrib-api/internal/services"
+)
+
+// ResidenceHandler handles residence-related HTTP requests
+type ResidenceHandler struct {
+	residenceService *services.ResidenceService
+}
+
+// NewResidenceHandler creates a new residence handler
+func NewResidenceHandler(residenceService *services.ResidenceService) *ResidenceHandler {
+	return &ResidenceHandler{
+		residenceService: residenceService,
+	}
+}
+
+// ListResidences handles GET /api/residences/
+func (h *ResidenceHandler) ListResidences(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	response, err := h.residenceService.ListResidences(user.ID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, response)
+}
+
+// GetMyResidences handles GET /api/residences/my-residences/
+func (h *ResidenceHandler) GetMyResidences(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	response, err := h.residenceService.GetMyResidences(user.ID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, response)
+}
+
+// GetResidence handles GET /api/residences/:id/
+func (h *ResidenceHandler) GetResidence(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	residenceID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid residence ID"})
+		return
+	}
+
+	response, err := h.residenceService.GetResidence(uint(residenceID), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrResidenceNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrResidenceAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+
+	c.JSON(http.StatusOK, response)
+}
+
+// CreateResidence handles POST /api/residences/
+func (h *ResidenceHandler) CreateResidence(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	var req requests.CreateResidenceRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	response, err := h.residenceService.CreateResidence(&req, user.ID)
+	if err != nil {
+		if errors.Is(err, services.ErrPropertiesLimitReached) {
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusCreated, response)
+}
+
+// UpdateResidence handles PUT/PATCH /api/residences/:id/
+func (h *ResidenceHandler) UpdateResidence(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	residenceID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid residence ID"})
+		return
+	}
+
+	var req requests.UpdateResidenceRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	response, err := h.residenceService.UpdateResidence(uint(residenceID), user.ID, &req)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrResidenceNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrNotResidenceOwner):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+
+	c.JSON(http.StatusOK, response)
+}
+
+// DeleteResidence handles DELETE /api/residences/:id/
+func (h *ResidenceHandler) DeleteResidence(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	residenceID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid residence ID"})
+		return
+	}
+
+	err = h.residenceService.DeleteResidence(uint(residenceID), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrResidenceNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrNotResidenceOwner):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"message": "Residence deleted successfully"})
+}
+
+// GenerateShareCode handles POST /api/residences/:id/generate-share-code/
+func (h *ResidenceHandler) GenerateShareCode(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	residenceID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid residence ID"})
+		return
+	}
+
+	var req requests.GenerateShareCodeRequest
+	// Request body is optional
+	c.ShouldBindJSON(&req)
+
+	response, err := h.residenceService.GenerateShareCode(uint(residenceID), user.ID, req.ExpiresInHours)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrResidenceNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrNotResidenceOwner):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+
+	c.JSON(http.StatusOK, response)
+}
+
+// JoinWithCode handles POST /api/residences/join-with-code/
+func (h *ResidenceHandler) JoinWithCode(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	var req requests.JoinWithCodeRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	response, err := h.residenceService.JoinWithCode(req.Code, user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrShareCodeInvalid):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrShareCodeExpired):
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrUserAlreadyMember):
+			c.JSON(http.StatusConflict, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+
+	c.JSON(http.StatusOK, response)
+}
+
+// GetResidenceUsers handles GET /api/residences/:id/users/
+func (h *ResidenceHandler) GetResidenceUsers(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	residenceID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid residence ID"})
+		return
+	}
+
+	users, err := h.residenceService.GetResidenceUsers(uint(residenceID), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrResidenceNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrResidenceAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+
+	c.JSON(http.StatusOK, users)
+}
+
+// RemoveResidenceUser handles DELETE /api/residences/:id/users/:user_id/
+func (h *ResidenceHandler) RemoveResidenceUser(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	residenceID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid residence ID"})
+		return
+	}
+
+	userIDToRemove, err := strconv.ParseUint(c.Param("user_id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid user ID"})
+		return
+	}
+
+	err = h.residenceService.RemoveUser(uint(residenceID), uint(userIDToRemove), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrResidenceNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrNotResidenceOwner):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrCannotRemoveOwner):
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{"message": "User removed from residence"})
+}
+
+// GetResidenceTypes handles GET /api/residences/types/
+func (h *ResidenceHandler) GetResidenceTypes(c *gin.Context) {
+	types, err := h.residenceService.GetResidenceTypes()
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, types)
+}

internal/handlers/subscription_handler.go

@@ -0,0 +1,176 @@
+package handlers
+
+import (
+	"errors"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/treytartt/mycrib-api/internal/middleware"
+	"github.com/treytartt/mycrib-api/internal/models"
+	"github.com/treytartt/mycrib-api/internal/services"
+)
+
+// SubscriptionHandler handles subscription-related HTTP requests
+type SubscriptionHandler struct {
+	subscriptionService *services.SubscriptionService
+}
+
+// NewSubscriptionHandler creates a new subscription handler
+func NewSubscriptionHandler(subscriptionService *services.SubscriptionService) *SubscriptionHandler {
+	return &SubscriptionHandler{subscriptionService: subscriptionService}
+}
+
+// GetSubscription handles GET /api/subscription/
+func (h *SubscriptionHandler) GetSubscription(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	subscription, err := h.subscriptionService.GetSubscription(user.ID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, subscription)
+}
+
+// GetSubscriptionStatus handles GET /api/subscription/status/
+func (h *SubscriptionHandler) GetSubscriptionStatus(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	status, err := h.subscriptionService.GetSubscriptionStatus(user.ID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, status)
+}
+
+// GetUpgradeTrigger handles GET /api/subscription/upgrade-trigger/:key/
+func (h *SubscriptionHandler) GetUpgradeTrigger(c *gin.Context) {
+	key := c.Param("key")
+
+	trigger, err := h.subscriptionService.GetUpgradeTrigger(key)
+	if err != nil {
+		if errors.Is(err, services.ErrUpgradeTriggerNotFound) {
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, trigger)
+}
+
+// GetFeatureBenefits handles GET /api/subscription/features/
+func (h *SubscriptionHandler) GetFeatureBenefits(c *gin.Context) {
+	benefits, err := h.subscriptionService.GetFeatureBenefits()
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, benefits)
+}
+
+// GetPromotions handles GET /api/subscription/promotions/
+func (h *SubscriptionHandler) GetPromotions(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	promotions, err := h.subscriptionService.GetActivePromotions(user.ID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, promotions)
+}
+
+// ProcessPurchase handles POST /api/subscription/purchase/
+func (h *SubscriptionHandler) ProcessPurchase(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	var req services.ProcessPurchaseRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	var subscription *services.SubscriptionResponse
+	var err error
+
+	switch req.Platform {
+	case "ios":
+		if req.ReceiptData == "" {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "receipt_data is required for iOS"})
+			return
+		}
+		subscription, err = h.subscriptionService.ProcessApplePurchase(user.ID, req.ReceiptData)
+	case "android":
+		if req.PurchaseToken == "" {
+			c.JSON(http.StatusBadRequest, gin.H{"error": "purchase_token is required for Android"})
+			return
+		}
+		subscription, err = h.subscriptionService.ProcessGooglePurchase(user.ID, req.PurchaseToken)
+	}
+
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"message":      "Subscription upgraded successfully",
+		"subscription": subscription,
+	})
+}
+
+// CancelSubscription handles POST /api/subscription/cancel/
+func (h *SubscriptionHandler) CancelSubscription(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	subscription, err := h.subscriptionService.CancelSubscription(user.ID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"message":      "Subscription cancelled. You will retain Pro benefits until the end of your billing period.",
+		"subscription": subscription,
+	})
+}
+
+// RestoreSubscription handles POST /api/subscription/restore/
+func (h *SubscriptionHandler) RestoreSubscription(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+
+	var req services.ProcessPurchaseRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	// Same logic as ProcessPurchase - validates receipt/token and restores
+	var subscription *services.SubscriptionResponse
+	var err error
+
+	switch req.Platform {
+	case "ios":
+		subscription, err = h.subscriptionService.ProcessApplePurchase(user.ID, req.ReceiptData)
+	case "android":
+		subscription, err = h.subscriptionService.ProcessGooglePurchase(user.ID, req.PurchaseToken)
+	}
+
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+
+	c.JSON(http.StatusOK, gin.H{
+		"message":      "Subscription restored successfully",
+		"subscription": subscription,
+	})
+}

internal/handlers/task_handler.go

@@ -0,0 +1,414 @@
+package handlers
+
+import (
+	"errors"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/treytartt/mycrib-api/internal/dto/requests"
+	"github.com/treytartt/mycrib-api/internal/middleware"
+	"github.com/treytartt/mycrib-api/internal/models"
+	"github.com/treytartt/mycrib-api/internal/services"
+)
+
+// TaskHandler handles task-related HTTP requests
+type TaskHandler struct {
+	taskService *services.TaskService
+}
+
+// NewTaskHandler creates a new task handler
+func NewTaskHandler(taskService *services.TaskService) *TaskHandler {
+	return &TaskHandler{taskService: taskService}
+}
+
+// ListTasks handles GET /api/tasks/
+func (h *TaskHandler) ListTasks(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	response, err := h.taskService.ListTasks(user.ID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, response)
+}
+
+// GetTask handles GET /api/tasks/:id/
+func (h *TaskHandler) GetTask(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	taskID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid task ID"})
+		return
+	}
+
+	response, err := h.taskService.GetTask(uint(taskID), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrTaskNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrTaskAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, response)
+}
+
+// GetTasksByResidence handles GET /api/tasks/by-residence/:residence_id/
+func (h *TaskHandler) GetTasksByResidence(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	residenceID, err := strconv.ParseUint(c.Param("residence_id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid residence ID"})
+		return
+	}
+
+	daysThreshold := 30
+	if d := c.Query("days_threshold"); d != "" {
+		if parsed, err := strconv.Atoi(d); err == nil {
+			daysThreshold = parsed
+		}
+	}
+
+	response, err := h.taskService.GetTasksByResidence(uint(residenceID), user.ID, daysThreshold)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrResidenceAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, response)
+}
+
+// CreateTask handles POST /api/tasks/
+func (h *TaskHandler) CreateTask(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	var req requests.CreateTaskRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	response, err := h.taskService.CreateTask(&req, user.ID)
+	if err != nil {
+		if errors.Is(err, services.ErrResidenceAccessDenied) {
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+			return
+		}
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusCreated, response)
+}
+
+// UpdateTask handles PUT/PATCH /api/tasks/:id/
+func (h *TaskHandler) UpdateTask(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	taskID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid task ID"})
+		return
+	}
+
+	var req requests.UpdateTaskRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	response, err := h.taskService.UpdateTask(uint(taskID), user.ID, &req)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrTaskNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrTaskAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, response)
+}
+
+// DeleteTask handles DELETE /api/tasks/:id/
+func (h *TaskHandler) DeleteTask(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	taskID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid task ID"})
+		return
+	}
+
+	err = h.taskService.DeleteTask(uint(taskID), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrTaskNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrTaskAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "Task deleted successfully"})
+}
+
+// MarkInProgress handles POST /api/tasks/:id/mark-in-progress/
+func (h *TaskHandler) MarkInProgress(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	taskID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid task ID"})
+		return
+	}
+
+	response, err := h.taskService.MarkInProgress(uint(taskID), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrTaskNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrTaskAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "Task marked as in progress", "task": response})
+}
+
+// CancelTask handles POST /api/tasks/:id/cancel/
+func (h *TaskHandler) CancelTask(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	taskID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid task ID"})
+		return
+	}
+
+	response, err := h.taskService.CancelTask(uint(taskID), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrTaskNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrTaskAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrTaskAlreadyCancelled):
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "Task cancelled", "task": response})
+}
+
+// UncancelTask handles POST /api/tasks/:id/uncancel/
+func (h *TaskHandler) UncancelTask(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	taskID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid task ID"})
+		return
+	}
+
+	response, err := h.taskService.UncancelTask(uint(taskID), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrTaskNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrTaskAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "Task uncancelled", "task": response})
+}
+
+// ArchiveTask handles POST /api/tasks/:id/archive/
+func (h *TaskHandler) ArchiveTask(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	taskID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid task ID"})
+		return
+	}
+
+	response, err := h.taskService.ArchiveTask(uint(taskID), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrTaskNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrTaskAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrTaskAlreadyArchived):
+			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "Task archived", "task": response})
+}
+
+// UnarchiveTask handles POST /api/tasks/:id/unarchive/
+func (h *TaskHandler) UnarchiveTask(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	taskID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid task ID"})
+		return
+	}
+
+	response, err := h.taskService.UnarchiveTask(uint(taskID), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrTaskNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrTaskAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "Task unarchived", "task": response})
+}
+
+// === Task Completions ===
+
+// ListCompletions handles GET /api/task-completions/
+func (h *TaskHandler) ListCompletions(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	response, err := h.taskService.ListCompletions(user.ID)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, response)
+}
+
+// GetCompletion handles GET /api/task-completions/:id/
+func (h *TaskHandler) GetCompletion(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	completionID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid completion ID"})
+		return
+	}
+
+	response, err := h.taskService.GetCompletion(uint(completionID), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrCompletionNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrTaskAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, response)
+}
+
+// CreateCompletion handles POST /api/task-completions/
+func (h *TaskHandler) CreateCompletion(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	var req requests.CreateTaskCompletionRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		return
+	}
+
+	response, err := h.taskService.CreateCompletion(&req, user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrTaskNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrTaskAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusCreated, response)
+}
+
+// DeleteCompletion handles DELETE /api/task-completions/:id/
+func (h *TaskHandler) DeleteCompletion(c *gin.Context) {
+	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+	completionID, err := strconv.ParseUint(c.Param("id"), 10, 32)
+	if err != nil {
+		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid completion ID"})
+		return
+	}
+
+	err = h.taskService.DeleteCompletion(uint(completionID), user.ID)
+	if err != nil {
+		switch {
+		case errors.Is(err, services.ErrCompletionNotFound):
+			c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
+		case errors.Is(err, services.ErrTaskAccessDenied):
+			c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
+		default:
+			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		}
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "Completion deleted successfully"})
+}
+
+// === Lookups ===
+
+// GetCategories handles GET /api/tasks/categories/
+func (h *TaskHandler) GetCategories(c *gin.Context) {
+	categories, err := h.taskService.GetCategories()
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, categories)
+}
+
+// GetPriorities handles GET /api/tasks/priorities/
+func (h *TaskHandler) GetPriorities(c *gin.Context) {
+	priorities, err := h.taskService.GetPriorities()
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, priorities)
+}
+
+// GetStatuses handles GET /api/tasks/statuses/
+func (h *TaskHandler) GetStatuses(c *gin.Context) {
+	statuses, err := h.taskService.GetStatuses()
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, statuses)
+}
+
+// GetFrequencies handles GET /api/tasks/frequencies/
+func (h *TaskHandler) GetFrequencies(c *gin.Context) {
+	frequencies, err := h.taskService.GetFrequencies()
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		return
+	}
+	c.JSON(http.StatusOK, frequencies)
+}