feat(billing): add auto-ban system for users with excessive disputes

- Add extensible ban-conditions module with dispute threshold checking
- Handle charge.dispute.created webhook to evaluate ban conditions
- Send friendly email to non-banned users offering to help resolve disputes
- Update ban message to be clear and helpful (403 instead of cryptic 503)
- Add unit tests for ban-conditions module
- Fix SDK type issue exposed by User type changes

Author: brandonkachen

packages/internal/src/loops/client.ts

@@ -199,3 +199,40 @@ export async function sendBasicEmail(
     },
   })
 }
+
+/**
+ * Send a notification email when a user files a dispute.
+ * Offers to work with them to resolve the issue.
+ */
+export async function sendDisputeNotificationEmail(params: {
+  email: string
+  firstName: string
+  disputeAmount: string
+  logger: Logger
+}): Promise<SendEmailResult> {
+  const { email, firstName, disputeAmount, logger } = params
+
+  const subject = "We noticed a dispute on your account - let's resolve this together"
+  const message = `Hi ${firstName},
+
+We noticed that a dispute was filed for a ${disputeAmount} charge on your Codebuff account. We're sorry to hear you had an issue and we'd love the opportunity to make things right.
+
+If there was a problem with your experience or a charge you didn't recognize, please reach out to us directly and we'll be happy to:
+
+• Issue a full refund if appropriate
+• Help resolve any technical issues you experienced
+• Answer any questions about your billing
+
+Working with us directly is often faster than going through your bank, and it helps us improve our service for everyone.
+
+Please reply to this email or contact our support team - we're here to help!
+
+Best regards,
+The Codebuff Team`
+
+  return sendBasicEmail({
+    email,
+    data: { subject, message },
+    logger,
+  })
+}

web/src/app/api/stripe/webhook/route.ts

@@ -6,13 +6,19 @@ import {
 import db from '@codebuff/internal/db'
 import * as schema from '@codebuff/internal/db/schema'
 import { env } from '@codebuff/internal/env'
+import { sendDisputeNotificationEmail } from '@codebuff/internal/loops'
 import { stripeServer } from '@codebuff/internal/util/stripe'
 import { eq } from 'drizzle-orm'
 import { NextResponse } from 'next/server'
 
 import type { NextRequest } from 'next/server'
 import type Stripe from 'stripe'
 
+import {
+  banUser,
+  evaluateBanConditions,
+  getUserByStripeCustomerId,
+} from '@/lib/ban-conditions'
 import { getStripeCustomerId } from '@/lib/stripe-utils'
 import { logger } from '@/util/logger'
 
@@ -357,6 +363,111 @@ const webhookHandler = async (req: NextRequest): Promise<NextResponse> => {
         await handleSubscriptionEvent(event.data.object as Stripe.Subscription)
         break
       }
+      case 'charge.dispute.created': {
+        const dispute = event.data.object as Stripe.Dispute
+        const chargeId =
+          typeof dispute.charge === 'string'
+            ? dispute.charge
+            : dispute.charge?.id
+
+        if (!chargeId) {
+          logger.warn(
+            { disputeId: dispute.id },
+            'Dispute received without charge ID',
+          )
+          break
+        }
+
+        // Get the charge to find the customer
+        const charge = await stripeServer.charges.retrieve(chargeId)
+        if (!charge.customer) {
+          logger.warn(
+            { disputeId: dispute.id, chargeId },
+            'Dispute charge has no customer (guest payment)',
+          )
+          break
+        }
+
+        const customerId = getStripeCustomerId(
+          charge.customer as string | Stripe.Customer | Stripe.DeletedCustomer,
+        )
+
+        if (!customerId) {
+          logger.warn(
+            { disputeId: dispute.id, chargeId },
+            'Dispute charge has no customer',
+          )
+          break
+        }
+
+        // Look up the user
+        const user = await getUserByStripeCustomerId(customerId)
+        if (!user) {
+          logger.info(
+            { disputeId: dispute.id, customerId },
+            'Dispute received for unknown customer (may be an organization)',
+          )
+          break
+        }
+
+        // Skip if already banned
+        if (user.banned) {
+          logger.debug(
+            { disputeId: dispute.id, userId: user.id },
+            'Dispute received for already-banned user, skipping evaluation',
+          )
+          break
+        }
+
+        // Evaluate ban conditions
+        const banResult = await evaluateBanConditions({
+          userId: user.id,
+          stripeCustomerId: customerId,
+          logger,
+        })
+
+        if (banResult.shouldBan) {
+          await banUser(user.id, banResult.reason, logger)
+          logger.warn(
+            {
+              disputeId: dispute.id,
+              userId: user.id,
+              customerId,
+              reason: banResult.reason,
+            },
+            'User auto-banned due to dispute threshold',
+          )
+          // Don't send email to banned users
+        } else {
+          // Send friendly dispute notification email to non-banned users
+          const firstName = user.name?.split(' ')[0] || 'there'
+          const disputeAmount = `$${(dispute.amount / 100).toFixed(2)}`
+          const emailResult = await sendDisputeNotificationEmail({
+            email: user.email,
+            firstName,
+            disputeAmount,
+            logger,
+          })
+
+          if (emailResult.success) {
+            logger.info(
+              { disputeId: dispute.id, userId: user.id, email: user.email },
+              'Sent dispute notification email to user',
+            )
+          } else {
+            logger.warn(
+              {
+                disputeId: dispute.id,
+                userId: user.id,
+                email: user.email,
+                error: emailResult.error,
+              },
+              'Failed to send dispute notification email',
+            )
+          }
+        }
+        break
+      }
       case 'charge.refunded': {
         const charge = event.data.object as Stripe.Charge
         // Get the payment intent ID from the charge

web/src/app/api/v1/chat/completions/__tests__/completions.test.ts

@@ -354,8 +354,8 @@ describe('/api/v1/chat/completions POST endpoint', () => {
     })
   })
 
-  describe('Blocked users', () => {
-    it('returns 503 with cryptic error for blocked user IDs', async () => {
+  describe('Banned users', () => {
+    it('returns 403 with clear message for banned users', async () => {
       const req = new NextRequest(
         'http://localhost:3000/api/v1/chat/completions',
         {
@@ -380,11 +380,12 @@ describe('/api/v1/chat/completions POST endpoint', () => {
         loggerWithContext: mockLoggerWithContext,
       })
 
-      expect(response.status).toBe(503)
+      expect(response.status).toBe(403)
       const body = await response.json()
       expect(body).toEqual({
-        error: 'upstream_timeout',
-        message: 'Overloaded. Request could not be processed',
+        error: 'account_suspended',
+        message:
+          'Your account has been suspended due to billing issues. Please contact support@codebuff.com to resolve this.',
       })
     })
   })

web/src/app/api/v1/chat/completions/_post.ts

@@ -149,14 +149,20 @@ export async function postChatCompletions(params: {
 
     const userId = userInfo.id
 
-    // Check if user is banned. Return fake overloaded error to avoid revealing the block.
+    // Check if user is banned.
+    // We use a clear, helpful message rather than a cryptic error because:
+    // 1. Legitimate users banned by mistake deserve to know what's happening
+    // 2. Bad actors will figure out they're banned regardless of the message
+    // 3. Clear messaging encourages resolution (matches our dispute notification email)
+    // 4. 403 Forbidden is the correct HTTP status for "you're not allowed"
     if (userInfo.banned) {
       return NextResponse.json(
         {
-          error: 'upstream_timeout',
-          message: 'Overloaded. Request could not be processed',
+          error: 'account_suspended',
+          message:
+            'Your account has been suspended due to billing issues. Please contact support@codebuff.com to resolve this.',
         },
-        { status: 503 },
+        { status: 403 },
       )
     }