feat(billing): suppress low credit warnings for auto top-up users

Add autoTopupEnabled field throughout the stack to improve UX for users
with auto top-up enabled. These users no longer see threshold warnings
at 1000/500/100 credits since their balance auto-replenishes. Warnings
only appear when truly out of credits (≤ 0).

- Add autoTopupEnabled to usage responses (API, websocket, CLI)
- Update shouldAutoShowBanner to skip warnings for auto top-up users
- Add comprehensive tests for new behavior
- Fix naming consistency (autoTopupEnabled vs autoTopUpEnabled)
- Remove unused test imports

Author: brandonkachen

backend/src/websockets/middleware.ts

@@ -402,7 +402,7 @@ protec.use(async ({ action, clientSessionId, ws, userInfo, logger }) => {
     },
   })
 
-  // Check and trigger monthly reset if needed
+  // Check and trigger monthly reset if needed (ignore the returned quotaResetDate since we use user.next_quota_reset)
   await triggerMonthlyResetAndGrant({ userId, logger })
 
   // Check if we need to trigger auto top-up and get the amount added (if any)

backend/src/websockets/websocket-action.ts

@@ -51,6 +51,7 @@ export async function genUsageResponse(params: {
       where: eq(schema.user.id, userId),
       columns: {
         next_quota_reset: true,
+        auto_topup_enabled: true,
       },
     })
 
@@ -73,6 +74,7 @@ export async function genUsageResponse(params: {
         remainingBalance: balanceDetails.totalRemaining,
         balanceBreakdown: balanceDetails.breakdown,
         next_quota_reset: user.next_quota_reset,
+        autoTopupEnabled: user.auto_topup_enabled ?? false,
       } satisfies UsageResponse
     } catch (error) {
       logger.error(

cli/src/hooks/use-usage-monitor.ts

@@ -29,12 +29,14 @@ export function useUsageMonitor() {
 
     const authToken = getAuthToken()
     const remainingBalance = usageData?.remainingBalance ?? null
+    const autoTopupEnabled = usageData?.autoTopupEnabled ?? false
 
     const decision = shouldAutoShowBanner(
       isChainInProgress,
       !!authToken,
       remainingBalance,
       lastWarnedThresholdRef.current,
+      autoTopupEnabled,
     )
 
     // Update the last warned threshold

cli/src/hooks/use-usage-query.ts

@@ -20,6 +20,7 @@ interface UsageResponse {
     paid: number
   }
   next_quota_reset: string | null
+  autoTopupEnabled?: boolean
 }
 
 interface FetchUsageParams {

cli/src/utils/__tests__/usage-banner-state.test.ts

@@ -193,6 +193,89 @@ describe('usage-banner-state', () => {
       })
     })
 
+    describe('auto top-up enabled behavior', () => {
+      test('does not auto-show for auto-top-up users above 0 credits', () => {
+        // Even at low credits, auto-top-up users shouldn't see warnings
+        const result = shouldAutoShowBanner(false, true, 50, null, true)
+        expect(result.shouldShow).toBe(false)
+        expect(result.newWarningThreshold).toBe(null)
+      })
+
+      test('does not auto-show for auto-top-up users at any positive threshold', () => {
+        // At 500 credits - would normally warn
+        let result = shouldAutoShowBanner(false, true, 499, null, true)
+        expect(result.shouldShow).toBe(false)
+
+        // At 100 credits - would normally warn
+        result = shouldAutoShowBanner(false, true, 99, null, true)
+        expect(result.shouldShow).toBe(false)
+
+        // Even at 1 credit
+        result = shouldAutoShowBanner(false, true, 1, null, true)
+        expect(result.shouldShow).toBe(false)
+      })
+
+      test('DOES auto-show for auto-top-up users when truly out (0 credits)', () => {
+        const result = shouldAutoShowBanner(false, true, 0, null, true)
+        expect(result.shouldShow).toBe(true)
+        expect(result.newWarningThreshold).toBe(100)
+      })
+
+      test('DOES auto-show for auto-top-up users when in debt (negative credits)', () => {
+        const result = shouldAutoShowBanner(false, true, -50, null, true)
+        expect(result.shouldShow).toBe(true)
+        expect(result.newWarningThreshold).toBe(100)
+      })
+
+      test('non-auto-top-up users still get warnings as normal', () => {
+        // Without auto-top-up, should warn at low credits
+        const result = shouldAutoShowBanner(false, true, 50, null, false)
+        expect(result.shouldShow).toBe(true)
+        expect(result.newWarningThreshold).toBe(100)
+      })
+
+      test('defaults autoTopUpEnabled to false when omitted', () => {
+        // When autoTopUpEnabled parameter is omitted, should behave like false
+        const result = shouldAutoShowBanner(false, true, 50, null)
+        expect(result.shouldShow).toBe(true)
+        expect(result.newWarningThreshold).toBe(100)
+      })
+    })
+
+    describe('combined scenarios', () => {
+      test('chain in progress takes precedence over auto-top-up status', () => {
+        // Even with auto-top-up disabled and low credits, chain in progress blocks showing
+        const result = shouldAutoShowBanner(true, true, 50, null, false)
+        expect(result.shouldShow).toBe(false)
+      })
+
+      test('unauthenticated takes precedence over auto-top-up status', () => {
+        // Even with auto-top-up disabled and low credits, no auth token blocks showing
+        const result = shouldAutoShowBanner(false, false, 50, null, false)
+        expect(result.shouldShow).toBe(false)
+      })
+
+      test('null balance takes precedence over auto-top-up status', () => {
+        // Even with auto-top-up disabled, null balance blocks showing
+        const result = shouldAutoShowBanner(false, true, null, null, false)
+        expect(result.shouldShow).toBe(false)
+      })
+
+      test('auto-top-up user with previous warning threshold and now at 0 credits', () => {
+        // Auto-top-up user who was previously warned at 500, now at 0 - should show
+        const result = shouldAutoShowBanner(false, true, 0, 500, true)
+        expect(result.shouldShow).toBe(true)
+        expect(result.newWarningThreshold).toBe(100)
+      })
+
+      test('auto-top-up user with healthy balance clears warning state', () => {
+        // Auto-top-up user who now has healthy balance should have cleared state
+        const result = shouldAutoShowBanner(false, true, 1500, 100, true)
+        expect(result.shouldShow).toBe(false)
+        expect(result.newWarningThreshold).toBe(null)
+      })
+    })
+
     describe('state reset behavior', () => {
       test('clears warning state when credits return to healthy', () => {
         const result = shouldAutoShowBanner(

cli/src/utils/usage-banner-state.ts

@@ -121,12 +121,14 @@ export interface AutoShowDecision {
  * - User is authenticated (hasAuthToken = true)
  * - User has credit data available (remainingBalance !== null)
  * - User crosses a new threshold (1000, 500, or 100) that hasn't been warned about yet
+ * - User does NOT have auto top-up enabled (unless truly out of credits <= 0)
  */
 export function shouldAutoShowBanner(
   isChainInProgress: boolean,
   hasAuthToken: boolean,
   remainingBalance: number | null,
   lastWarnedThreshold: number | null,
+  autoTopupEnabled: boolean = false,
 ): AutoShowDecision {
   // Don't show during active chains
   if (isChainInProgress) {
@@ -143,6 +145,12 @@ export function shouldAutoShowBanner(
     return { shouldShow: false, newWarningThreshold: lastWarnedThreshold }
   }
 
+  // For users with auto top-up enabled, only show if truly out of credits (<= 0)
+  // Auto top-up users want to "set and forget" - don't bother them with threshold warnings
+  if (autoTopupEnabled && remainingBalance > 0) {
+    return { shouldShow: false, newWarningThreshold: null }
+  }
+
   const currentThreshold = getThresholdTier(remainingBalance)
 
   // Clear warning state if user is back above all thresholds

common/src/actions.ts

@@ -154,6 +154,7 @@ export type UsageResponse = {
   balanceBreakdown?: Record<GrantType, number>
   next_quota_reset: Date | null
   autoTopupAdded?: number
+  autoTopupEnabled?: boolean
 }
 
 export type MessageCostResponse = {

common/src/types/contracts/billing.ts

@@ -14,6 +14,7 @@ export type GetUserUsageDataFn = (params: {
   }
   nextQuotaReset: string
   autoTopupTriggered?: boolean
+  autoTopupEnabled?: boolean
 }>
 
 export type ConsumeCreditsWithFallbackFn = (params: {

packages/billing/src/__tests__/grant-credits.test.ts

@@ -0,0 +1,179 @@
+import {
+  clearMockedModules,
+  mockModule,
+} from '@codebuff/common/testing/mock-modules'
+import { afterEach, describe, expect, it } from 'bun:test'
+
+import { triggerMonthlyResetAndGrant } from '../grant-credits'
+
+import type { Logger } from '@codebuff/common/types/contracts/logger'
+
+const logger: Logger = {
+  debug: () => {},
+  error: () => {},
+  info: () => {},
+  warn: () => {},
+}
+
+const futureDate = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000) // 30 days from now
+const pastDate = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000) // 30 days ago
+
+const createDbMock = (options: {
+  user: {
+    next_quota_reset: Date | null
+    auto_topup_enabled: boolean | null
+  } | null
+}) => {
+  const { user } = options
+
+  return {
+    transaction: async (callback: (tx: any) => Promise<any>) => {
+      const tx = {
+        query: {
+          user: {
+            findFirst: async () => user,
+          },
+        },
+        update: () => ({
+          set: () => ({
+            where: () => Promise.resolve(),
+          }),
+        }),
+        insert: () => ({
+          values: () => Promise.resolve(),
+        }),
+        select: () => ({
+          from: () => ({
+            where: () => ({
+              orderBy: () => ({
+                limit: () => [],
+              }),
+            }),
+            then: (cb: any) => cb([]),
+          }),
+        }),
+      }
+      return callback(tx)
+    },
+    select: () => ({
+      from: () => ({
+        where: () => ({
+          orderBy: () => ({
+            limit: () => [],
+          }),
+        }),
+      }),
+    }),
+  }
+}
+
+describe('grant-credits', () => {
+  afterEach(() => {
+    clearMockedModules()
+  })
+
+  describe('triggerMonthlyResetAndGrant', () => {
+    describe('autoTopupEnabled return value', () => {
+      it('should return autoTopupEnabled: true when user has auto_topup_enabled: true', async () => {
+        await mockModule('@codebuff/internal/db', () => ({
+          default: createDbMock({
+            user: {
+              next_quota_reset: futureDate,
+              auto_topup_enabled: true,
+            },
+          }),
+        }))
+
+        // Need to re-import after mocking
+        const { triggerMonthlyResetAndGrant: fn } = await import('../grant-credits')
+
+        const result = await fn({
+          userId: 'user-123',
+          logger,
+        })
+
+        expect(result.autoTopupEnabled).toBe(true)
+        expect(result.quotaResetDate).toEqual(futureDate)
+      })
+
+      it('should return autoTopupEnabled: false when user has auto_topup_enabled: false', async () => {
+        await mockModule('@codebuff/internal/db', () => ({
+          default: createDbMock({
+            user: {
+              next_quota_reset: futureDate,
+              auto_topup_enabled: false,
+            },
+          }),
+        }))
+
+        const { triggerMonthlyResetAndGrant: fn } = await import('../grant-credits')
+
+        const result = await fn({
+          userId: 'user-123',
+          logger,
+        })
+
+        expect(result.autoTopupEnabled).toBe(false)
+      })
+
+      it('should default autoTopupEnabled to false when user has auto_topup_enabled: null', async () => {
+        await mockModule('@codebuff/internal/db', () => ({
+          default: createDbMock({
+            user: {
+              next_quota_reset: futureDate,
+              auto_topup_enabled: null,
+            },
+          }),
+        }))
+
+        const { triggerMonthlyResetAndGrant: fn } = await import('../grant-credits')
+
+        const result = await fn({
+          userId: 'user-123',
+          logger,
+        })
+
+        expect(result.autoTopupEnabled).toBe(false)
+      })
+
+      it('should throw error when user is not found', async () => {
+        await mockModule('@codebuff/internal/db', () => ({
+          default: createDbMock({
+            user: null,
+          }),
+        }))
+
+        const { triggerMonthlyResetAndGrant: fn } = await import('../grant-credits')
+
+        await expect(
+          fn({
+            userId: 'nonexistent-user',
+            logger,
+          }),
+        ).rejects.toThrow('User nonexistent-user not found')
+      })
+    })
+
+    describe('quota reset behavior', () => {
+      it('should return existing reset date when it is in the future', async () => {
+        await mockModule('@codebuff/internal/db', () => ({
+          default: createDbMock({
+            user: {
+              next_quota_reset: futureDate,
+              auto_topup_enabled: false,
+            },
+          }),
+        }))
+
+        const { triggerMonthlyResetAndGrant: fn } = await import('../grant-credits')
+
+        const result = await fn({
+          userId: 'user-123',
+          logger,
+        })
+
+        expect(result.quotaResetDate).toEqual(futureDate)
+      })
+    })
+  })
+})