feat(api): limit contacts by plan

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: AchoArnold

api/docs/docs.go

@@ -363,6 +363,12 @@ const docTemplate = `{
                             "$ref": "#/definitions/responses.Unauthorized"
                         }
                     },
+                    "402": {
+                        "description": "Payment Required",
+                        "schema": {
+                            "$ref": "#/definitions/responses.PaymentRequired"
+                        }
+                    },
                     "422": {
                         "description": "Unprocessable Entity",
                         "schema": {
@@ -424,6 +430,12 @@ const docTemplate = `{
                             "$ref": "#/definitions/responses.Unauthorized"
                         }
                     },
+                    "402": {
+                        "description": "Payment Required",
+                        "schema": {
+                            "$ref": "#/definitions/responses.PaymentRequired"
+                        }
+                    },
                     "422": {
                         "description": "Unprocessable Entity",
                         "schema": {

api/docs/swagger.json

@@ -360,6 +360,12 @@
                             "$ref": "#/definitions/responses.Unauthorized"
                         }
                     },
+                    "402": {
+                        "description": "Payment Required",
+                        "schema": {
+                            "$ref": "#/definitions/responses.PaymentRequired"
+                        }
+                    },
                     "422": {
                         "description": "Unprocessable Entity",
                         "schema": {
@@ -421,6 +427,12 @@
                             "$ref": "#/definitions/responses.Unauthorized"
                         }
                     },
+                    "402": {
+                        "description": "Payment Required",
+                        "schema": {
+                            "$ref": "#/definitions/responses.PaymentRequired"
+                        }
+                    },
                     "422": {
                         "description": "Unprocessable Entity",
                         "schema": {

api/docs/swagger.yaml

@@ -1963,6 +1963,10 @@ paths:
           description: Unauthorized
           schema:
             $ref: '#/definitions/responses.Unauthorized'
+        "402":
+          description: Payment Required
+          schema:
+            $ref: '#/definitions/responses.PaymentRequired'
         "422":
           description: Unprocessable Entity
           schema:
@@ -2094,6 +2098,10 @@ paths:
           description: Unauthorized
           schema:
             $ref: '#/definitions/responses.Unauthorized'
+        "402":
+          description: Payment Required
+          schema:
+            $ref: '#/definitions/responses.PaymentRequired'
         "422":
           description: Unprocessable Entity
           schema:

api/pkg/di/container.go

@@ -720,6 +720,7 @@ func (container *Container) ContactHandler() (h *handlers.ContactHandler) {
 		container.Tracer(),
 		container.ContactHandlerValidator(),
 		container.ContactService(),
+		container.EntitlementService(),
 	)
 }
 

api/pkg/entities/contact.go

@@ -10,6 +10,9 @@ import (
 	"github.com/lib/pq"
 )
 
+// EntityNameContact is the entitlement entity name for contacts.
+const EntityNameContact = "Contact"
+
 // ContactProperties is a free-form key/value map persisted as a jsonb column.
 type ContactProperties map[string]string
 

api/pkg/handlers/contact_handler.go

@@ -1,8 +1,10 @@
 package handlers
 
 import (
+	"context"
 	"fmt"
 
+	"github.com/NdoleStudio/httpsms/pkg/entities"
 	"github.com/NdoleStudio/httpsms/pkg/repositories"
 	"github.com/NdoleStudio/httpsms/pkg/requests"
 	"github.com/NdoleStudio/httpsms/pkg/services"
@@ -17,10 +19,11 @@ import (
 // ContactHandler handles contact http requests.
 type ContactHandler struct {
 	handler
-	logger    telemetry.Logger
-	tracer    telemetry.Tracer
-	validator *validators.ContactHandlerValidator
-	service   *services.ContactService
+	logger             telemetry.Logger
+	tracer             telemetry.Tracer
+	validator          *validators.ContactHandlerValidator
+	service            *services.ContactService
+	entitlementService *services.EntitlementService
 }
 
 // NewContactHandler creates a new ContactHandler.
@@ -29,12 +32,14 @@ func NewContactHandler(
 	tracer telemetry.Tracer,
 	validator *validators.ContactHandlerValidator,
 	service *services.ContactService,
+	entitlementService *services.EntitlementService,
 ) (h *ContactHandler) {
 	return &ContactHandler{
-		logger:    logger.WithService(fmt.Sprintf("%T", h)),
-		tracer:    tracer,
-		validator: validator,
-		service:   service,
+		logger:             logger.WithService(fmt.Sprintf("%T", h)),
+		tracer:             tracer,
+		validator:          validator,
+		service:            service,
+		entitlementService: entitlementService,
 	}
 }
 
@@ -107,6 +112,7 @@ func (h *ContactHandler) Index(c fiber.Ctx) error {
 // @Success      201 	{object}	responses.ContactsResponse
 // @Failure      400	{object}	responses.BadRequest
 // @Failure 	 401    {object}	responses.Unauthorized
+// @Failure 	 402	{object}	responses.PaymentRequired
 // @Failure      422	{object}	responses.UnprocessableEntity
 // @Failure      500	{object}	responses.InternalServerError
 // @Router       /contacts [post]
@@ -128,6 +134,15 @@ func (h *ContactHandler) Store(c fiber.Ctx) error {
 
 	userID := h.userIDFomContext(c)
 	contacts := sanitized.ToContacts(userID)
+	result, err := h.checkCreateEntitlement(ctx, userID, len(contacts))
+	if err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot check contact entitlement for user [%s]", userID))
+		return h.responseInternalServerError(c)
+	}
+	if !result.Allowed {
+		return h.responsePaymentRequired(c, result.Message)
+	}
+
 	if err := h.service.CreateMany(ctx, userID, contacts); err != nil {
 		ctxLogger.Error(stacktrace.Propagatef(err, "cannot create [%d] contacts for user [%s]", len(contacts), userID))
 		return h.responseInternalServerError(c)
@@ -147,6 +162,7 @@ func (h *ContactHandler) Store(c fiber.Ctx) error {
 // @Success      201 	{object}	responses.ContactsResponse
 // @Failure      400	{object}	responses.BadRequest
 // @Failure 	 401    {object}	responses.Unauthorized
+// @Failure 	 402	{object}	responses.PaymentRequired
 // @Failure      422	{object}	responses.UnprocessableEntity
 // @Failure      500	{object}	responses.InternalServerError
 // @Router       /contacts/upload [post]
@@ -171,6 +187,15 @@ func (h *ContactHandler) Upload(c fiber.Ctx) error {
 	// build the persistable records directly without re-sanitizing.
 	request := requests.ContactStoreRequest{Contacts: items}
 	contacts := request.ToContacts(userID)
+	result, err := h.checkCreateEntitlement(ctx, userID, len(contacts))
+	if err != nil {
+		ctxLogger.Error(stacktrace.Propagatef(err, "cannot check contact entitlement for user [%s]", userID))
+		return h.responseInternalServerError(c)
+	}
+	if !result.Allowed {
+		return h.responsePaymentRequired(c, result.Message)
+	}
+
 	if err = h.service.CreateMany(ctx, userID, contacts); err != nil {
 		ctxLogger.Error(stacktrace.Propagatef(err, "cannot import [%d] contacts for user [%s]", len(contacts), userID))
 		return h.responseInternalServerError(c)
@@ -281,3 +306,14 @@ func (h *ContactHandler) Delete(c fiber.Ctx) error {
 
 	return h.responseNoContent(c, "contact deleted successfully")
 }
+
+func (h *ContactHandler) checkCreateEntitlement(
+	ctx context.Context,
+	userID entities.UserID,
+	additionalCount int,
+) (*services.EntitlementCheckResult, error) {
+	return h.entitlementService.CheckAdditional(ctx, userID, entities.EntityNameContact, additionalCount, func() (int, error) {
+		count, err := h.service.Count(ctx, userID, repositories.IndexParams{})
+		return int(count), err
+	})
+}

api/pkg/handlers/contact_handler_test.go

@@ -150,12 +150,35 @@ func (r *contactHandlerFakeRepo) snapshot() ([][]*entities.Contact, []*entities.
 
 const contactHandlerTestUserID = entities.UserID("user-id")
 
+type contactHandlerEntitlementUserRepo struct {
+	repositories.UserRepository
+	subscriptionName entities.SubscriptionName
+}
+
+func (repository *contactHandlerEntitlementUserRepo) Load(_ context.Context, userID entities.UserID) (*entities.User, error) {
+	return &entities.User{ID: userID, SubscriptionName: repository.subscriptionName}, nil
+}
+
 func newContactHandlerTestApp(repo repositories.ContactRepository) *fiber.App {
+	return newContactHandlerTestAppWithEntitlements(repo, false, entities.SubscriptionNameFree)
+}
+
+func newContactHandlerTestAppWithEntitlements(
+	repo repositories.ContactRepository,
+	entitlementsEnabled bool,
+	subscriptionName entities.SubscriptionName,
+) *fiber.App {
 	logger := &messageThreadHandlerNoopLogger{}
 	tracer := telemetry.NewOtelLogger("test", logger)
 	appCache := cache.NewMemoryCache(tracer, ttlCache.New(time.Minute, time.Minute))
 	service := services.NewContactService(logger, tracer, repo, appCache)
-	handler := NewContactHandler(logger, tracer, validators.NewContactHandlerValidator(logger, tracer), service)
+	entitlementService := services.NewEntitlementService(
+		logger,
+		tracer,
+		entitlementsEnabled,
+		&contactHandlerEntitlementUserRepo{subscriptionName: subscriptionName},
+	)
+	handler := NewContactHandler(logger, tracer, validators.NewContactHandlerValidator(logger, tracer), service, entitlementService)
 
 	app := fiber.New()
 	app.Use(func(c fiber.Ctx) error {
@@ -222,6 +245,41 @@ func TestContactHandler_Store_CreatesManyContactsFromObjectShape(t *testing.T) {
 	assert.Equal(t, "Bob", stored[0][1].Name)
 }
 
+func TestContactHandler_Store_RejectsBatchExceedingContactLimit(t *testing.T) {
+	repo := &contactHandlerFakeRepo{countResult: 199}
+	app := newContactHandlerTestAppWithEntitlements(repo, true, entities.SubscriptionNameFree)
+
+	body := `{"contacts":[
+		{"name":"Alice","phone_numbers":["+18005550199"]},
+		{"name":"Bob","phone_numbers":["+18005550100"]}
+	]}`
+	req := httptest.NewRequest(http.MethodPost, "/v1/contacts", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusPaymentRequired, resp.StatusCode)
+
+	stored, _, _, _ := repo.snapshot()
+	assert.Empty(t, stored)
+}
+
+func TestContactHandler_Store_DisabledEntitlementsDoNotLimitContacts(t *testing.T) {
+	repo := &contactHandlerFakeRepo{countResult: 200}
+	app := newContactHandlerTestAppWithEntitlements(repo, false, entities.SubscriptionNameFree)
+
+	body := `[{"name":"Alice","phone_numbers":["+18005550199"]}]`
+	req := httptest.NewRequest(http.MethodPost, "/v1/contacts", bytes.NewBufferString(body))
+	req.Header.Set("Content-Type", "application/json")
+
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusCreated, resp.StatusCode)
+
+	stored, _, _, _ := repo.snapshot()
+	require.Len(t, stored, 1)
+}
+
 func TestContactHandler_Store_ValidationError_ReturnsUnprocessableEntity(t *testing.T) {
 	repo := &contactHandlerFakeRepo{}
 	app := newContactHandlerTestApp(repo)
@@ -289,6 +347,23 @@ func TestContactHandler_Upload_CSVSuccess(t *testing.T) {
 	}
 }
 
+func TestContactHandler_Upload_RejectsBatchExceedingContactLimit(t *testing.T) {
+	repo := &contactHandlerFakeRepo{countResult: 199}
+	app := newContactHandlerTestAppWithEntitlements(repo, true, entities.SubscriptionNameFree)
+
+	csv := "Name,Emails,PhoneNumbers\nAlice,alice@example.com,+18005550199\nBob,,+18005550100\n"
+	body, contentType := buildContactCSVUpload(t, "contacts.csv", "text/csv", csv)
+	req := httptest.NewRequest(http.MethodPost, "/v1/contacts/upload", body)
+	req.Header.Set("Content-Type", contentType)
+
+	resp, err := app.Test(req, fiber.TestConfig{Timeout: time.Second})
+	require.NoError(t, err)
+	require.Equal(t, http.StatusPaymentRequired, resp.StatusCode)
+
+	stored, _, _, _ := repo.snapshot()
+	assert.Empty(t, stored)
+}
+
 func TestContactHandler_Upload_NonCSVFile_ReturnsUnprocessableEntity(t *testing.T) {
 	repo := &contactHandlerFakeRepo{}
 	app := newContactHandlerTestApp(repo)

api/pkg/services/entitlement_service.go

@@ -62,6 +62,18 @@ func (service *EntitlementService) Check(
 	userID entities.UserID,
 	entityName string,
 	countFunc func() (int, error),
+) (*EntitlementCheckResult, error) {
+	return service.CheckAdditional(ctx, userID, entityName, 1, countFunc)
+}
+
+// CheckAdditional verifies if the user can create additionalCount instances of
+// the given entity without exceeding their subscription plan limit.
+func (service *EntitlementService) CheckAdditional(
+	ctx context.Context,
+	userID entities.UserID,
+	entityName string,
+	additionalCount int,
+	countFunc func() (int, error),
 ) (*EntitlementCheckResult, error) {
 	ctx, span := service.tracer.Start(ctx)
 	defer span.End()
@@ -70,8 +82,8 @@ func (service *EntitlementService) Check(
 		return &EntitlementCheckResult{Allowed: true}, nil
 	}
 
-	limits, exists := entityLimits[entityName]
-	if !exists {
+	limits, hasConfiguredLimits := entityLimits[entityName]
+	if !hasConfiguredLimits && entityName != entities.EntityNameContact {
 		return &EntitlementCheckResult{Allowed: true}, nil
 	}
 
@@ -83,9 +95,13 @@ func (service *EntitlementService) Check(
 		)
 	}
 
-	limit, hasLimit := limits[user.SubscriptionName]
-	if !hasLimit || limit == 0 {
-		return &EntitlementCheckResult{Allowed: true}, nil
+	limit := int(user.SubscriptionName.Limit())
+	if entityName != entities.EntityNameContact {
+		var hasLimit bool
+		limit, hasLimit = limits[user.SubscriptionName]
+		if !hasLimit || limit == 0 {
+			return &EntitlementCheckResult{Allowed: true}, nil
+		}
 	}
 
 	currentCount, err := countFunc()
@@ -96,11 +112,11 @@ func (service *EntitlementService) Check(
 		)
 	}
 
-	if currentCount >= limit {
+	if currentCount+additionalCount > limit {
 		return &EntitlementCheckResult{
 			Allowed: false,
 			Message: fmt.Sprintf(
-				"Upgrade to a paid plan to create more than [%d] %s. Visit https://httpsms.com/pricing for details.",
+				"Upgrade your plan to create more than [%d] %s. Visit https://httpsms.com/pricing for details.",
 				limit,
 				formatEntityName(entityName, true),
 			),