docs: update billing knowledge with comprehensive DI testing documentation

Replaced outdated "Mock database module directly" guidance with:
- Complete table of all DI interfaces and injectable dependencies
- Code examples showing how to use deps parameters
- Testing best practices for billing functions
- Example test demonstrating the DI pattern

This helps future developers understand how to properly test billing functions using the DI patterns established in this PR.

Author: brandonkachen

packages/billing/src/billing.knowledge.md

@@ -62,6 +62,84 @@ Triggers when:
 - Amount >= 500 credits (minimum)
 - If debt exists: amount = max(configured amount, debt amount)
 
-## Testing
-
-Mock database module directly, not getOrderedActiveGrants. Pass explicit 'now' parameter to control grant expiration.
+## Testing with Dependency Injection
+
+All billing functions support dependency injection (DI) via optional `deps` parameters, enabling comprehensive unit testing without mocking modules.
+
+### DI Patterns
+
+Each function accepts an optional `deps` object with injectable dependencies:
+
+```typescript
+// Example: Testing consumeCreditsAndAddAgentStep
+await consumeCreditsAndAddAgentStep({
+  messageId: 'test-msg',
+  userId: 'user-1',
+  // ... other params
+  deps: {
+    withSerializableTransaction: mockTransaction,
+    trackEvent: vi.fn(),
+    reportPurchasedCreditsToStripe: vi.fn(),
+  },
+})
+```
+
+### Available DI Interfaces
+
+| Function | Deps Interface | Injectable Dependencies |
+|----------|----------------|------------------------|
+| `consumeCreditsAndAddAgentStep` | `ConsumeCreditsAndAddAgentStepDeps` | `withSerializableTransaction`, `trackEvent`, `reportPurchasedCreditsToStripe` |
+| `calculateUsageThisCycle` | `CalculateUsageThisCycleDeps` | `db` |
+| `validateAutoTopupStatus` | `ValidateAutoTopupStatusDeps` | `db`, `stripeServer` |
+| `checkAndTriggerAutoTopup` | `CheckAndTriggerAutoTopupDeps` | `db`, `stripeServer`, `calculateUsageAndBalanceFn`, `validateAutoTopupStatusFn`, `processAndGrantCreditFn` |
+| `checkAndTriggerOrgAutoTopup` | `CheckAndTriggerOrgAutoTopupDeps` | `db`, `stripeServer`, `calculateOrganizationUsageAndBalanceFn`, `grantOrganizationCreditsFn` |
+| `reportPurchasedCreditsToStripe` | `ReportPurchasedCreditsToStripeDeps` | `db`, `stripeServer`, `shouldAttemptStripeMetering` |
+| `getPreviousFreeGrantAmount` | `GetPreviousFreeGrantAmountDeps` | `db` |
+| `calculateTotalReferralBonus` | `CalculateTotalReferralBonusDeps` | `db` |
+| `processAndGrantCredit` | `ProcessAndGrantCreditDeps` | `grantCreditFn`, `logSyncFailure` |
+| `syncOrganizationBillingCycle` | `SyncOrganizationBillingCycleDeps` | `db`, `stripeServer` |
+| `findOrganizationForRepository` | `FindOrganizationForRepositoryDeps` | `db` |
+| `consumeOrganizationCredits` | `ConsumeOrgCreditsDeps` | `withSerializableTransaction`, `trackEvent`, `reportToStripe` |
+| `grantOrganizationCredits` | `GrantOrgCreditsDeps` | `db`, `transaction` |
+
+### Functions with `conn` Parameter
+
+Some functions accept a `conn` parameter for transaction context:
+
+- `getOrderedActiveGrants({ userId, now, conn })` - Pass `tx` inside transactions
+- `getOrderedActiveOrganizationGrants({ organizationId, now, conn })` - Same pattern
+- `calculateUsageAndBalance({ ..., conn })` - Pass transaction for consistent reads
+
+### Testing Best Practices
+
+1. **Use `createMockBillingDb()`** from `@codebuff/common/testing/mock-db` for database mocking
+2. **Pass explicit `now` parameter** to control grant expiration in tests
+3. **Mock Stripe** by injecting a mock `stripeServer` via deps
+4. **Use `vi.fn()`** for tracking function calls (analytics, Stripe reporting)
+
+### Example Test
+
+```typescript
+import { createMockBillingDb } from '@codebuff/common/testing/mock-db'
+import { checkAndTriggerAutoTopup } from '@codebuff/billing/auto-topup'
+
+test('triggers auto-topup when balance is low', async () => {
+  const mockDb = createMockBillingDb()
+  const mockStripe = { paymentMethods: { list: vi.fn() }, ... }
+  const mockCalculateBalance = vi.fn().mockResolvedValue({
+    balance: { totalRemaining: 100, totalDebt: 0 }
+  })
+
+  await checkAndTriggerAutoTopup({
+    userId: 'user-1',
+    logger: mockLogger,
+    deps: {
+      db: mockDb,
+      stripeServer: mockStripe,
+      calculateUsageAndBalanceFn: mockCalculateBalance,
+    },
+  })
+
+  expect(mockCalculateBalance).toHaveBeenCalled()
+})
+```