test(billing): add unit tests for createPaymentIntent function

- 9 new tests with Stripe API mocking via mockModule
- Tests correct parameter passing (amount, customer, payment method, description)
- Verifies currency=usd, off_session=true, confirm=true settings
- Tests idempotency key passing for safe retries
- Tests metadata passing and error propagation
- Total: 51 tests for auto-topup-helpers (was 42, now 51)

Author: brandonkachen

packages/billing/src/__tests__/auto-topup-helpers.test.ts

@@ -5,6 +5,7 @@ import {
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
 
 import {
+  createPaymentIntent,
   fetchPaymentMethods,
   filterValidPaymentMethods,
   findValidPaymentMethod,
@@ -233,6 +234,228 @@ describe('auto-topup-helpers', () => {
     })
   })
 
+  describe('createPaymentIntent', () => {
+    let mockPaymentIntentsCreate: {
+      calls: Array<{ params: any; options: any }>
+      create: (params: any, options?: any) => Promise<any>
+      mockResponse: any
+      mockError: Error | null
+    }
+
+    function createMockPaymentIntentsCreate(options?: {
+      response?: any
+      error?: Error
+    }) {
+      const calls: Array<{ params: any; options: any }> = []
+      const mockResponse = options?.response ?? {
+        id: 'pi_test_123',
+        status: 'succeeded',
+        amount: 1000,
+        currency: 'usd',
+      }
+      const mockError = options?.error ?? null
+
+      return {
+        calls,
+        mockResponse,
+        mockError,
+        create: async (params: any, opts?: any) => {
+          calls.push({ params, options: opts })
+          if (mockError) {
+            throw mockError
+          }
+          return mockResponse
+        },
+      }
+    }
+
+    beforeEach(async () => {
+      mockPaymentIntentsCreate = createMockPaymentIntentsCreate()
+      await mockModule('@codebuff/internal/util/stripe', () => ({
+        stripeServer: {
+          paymentIntents: mockPaymentIntentsCreate,
+        },
+      }))
+    })
+
+    afterEach(() => {
+      clearMockedModules()
+    })
+
+    it('should create a payment intent with correct parameters', async () => {
+      const params = {
+        amountInCents: 5000,
+        stripeCustomerId: 'cus_123',
+        paymentMethodId: 'pm_card_123',
+        description: 'Auto top-up for user',
+        idempotencyKey: 'idem_key_123',
+        metadata: { userId: 'user_123', type: 'auto_topup' },
+      }
+
+      await createPaymentIntent(params)
+
+      expect(mockPaymentIntentsCreate.calls).toHaveLength(1)
+      const call = mockPaymentIntentsCreate.calls[0]
+
+      expect(call.params).toEqual({
+        amount: 5000,
+        currency: 'usd',
+        customer: 'cus_123',
+        payment_method: 'pm_card_123',
+        off_session: true,
+        confirm: true,
+        description: 'Auto top-up for user',
+        metadata: { userId: 'user_123', type: 'auto_topup' },
+      })
+      expect(call.options).toEqual({ idempotencyKey: 'idem_key_123' })
+    })
+
+    it('should return the payment intent from Stripe', async () => {
+      const expectedResponse = {
+        id: 'pi_custom_123',
+        status: 'succeeded',
+        amount: 10000,
+        currency: 'usd',
+        customer: 'cus_456',
+      } as Stripe.PaymentIntent
+
+      mockPaymentIntentsCreate = createMockPaymentIntentsCreate({
+        response: expectedResponse,
+      })
+      await mockModule('@codebuff/internal/util/stripe', () => ({
+        stripeServer: {
+          paymentIntents: mockPaymentIntentsCreate,
+        },
+      }))
+
+      const result = await createPaymentIntent({
+        amountInCents: 10000,
+        stripeCustomerId: 'cus_456',
+        paymentMethodId: 'pm_card_456',
+        description: 'Test payment',
+        idempotencyKey: 'idem_456',
+        metadata: {},
+      })
+
+      expect(result.id).toBe('pi_custom_123')
+      expect(result.status).toBe('succeeded')
+      expect(result.amount).toBe(10000)
+    })
+
+    it('should always set currency to usd', async () => {
+      await createPaymentIntent({
+        amountInCents: 1000,
+        stripeCustomerId: 'cus_test',
+        paymentMethodId: 'pm_test',
+        description: 'Test',
+        idempotencyKey: 'idem_test',
+        metadata: {},
+      })
+
+      expect(mockPaymentIntentsCreate.calls[0].params.currency).toBe('usd')
+    })
+
+    it('should always set off_session to true for auto-topup', async () => {
+      await createPaymentIntent({
+        amountInCents: 1000,
+        stripeCustomerId: 'cus_test',
+        paymentMethodId: 'pm_test',
+        description: 'Test',
+        idempotencyKey: 'idem_test',
+        metadata: {},
+      })
+
+      expect(mockPaymentIntentsCreate.calls[0].params.off_session).toBe(true)
+    })
+
+    it('should always set confirm to true to immediately charge', async () => {
+      await createPaymentIntent({
+        amountInCents: 1000,
+        stripeCustomerId: 'cus_test',
+        paymentMethodId: 'pm_test',
+        description: 'Test',
+        idempotencyKey: 'idem_test',
+        metadata: {},
+      })
+
+      expect(mockPaymentIntentsCreate.calls[0].params.confirm).toBe(true)
+    })
+
+    it('should pass idempotency key in options for safe retries', async () => {
+      const idempotencyKey = 'unique_idem_key_789'
+
+      await createPaymentIntent({
+        amountInCents: 1000,
+        stripeCustomerId: 'cus_test',
+        paymentMethodId: 'pm_test',
+        description: 'Test',
+        idempotencyKey,
+        metadata: {},
+      })
+
+      expect(mockPaymentIntentsCreate.calls[0].options.idempotencyKey).toBe(
+        idempotencyKey,
+      )
+    })
+
+    it('should pass metadata to Stripe', async () => {
+      const metadata = {
+        userId: 'user_123',
+        organizationId: 'org_456',
+        type: 'auto_topup',
+        trigger: 'low_balance',
+      }
+
+      await createPaymentIntent({
+        amountInCents: 1000,
+        stripeCustomerId: 'cus_test',
+        paymentMethodId: 'pm_test',
+        description: 'Test',
+        idempotencyKey: 'idem_test',
+        metadata,
+      })
+
+      expect(mockPaymentIntentsCreate.calls[0].params.metadata).toEqual(metadata)
+    })
+
+    it('should propagate Stripe errors', async () => {
+      const stripeError = new Error('Card declined')
+
+      mockPaymentIntentsCreate = createMockPaymentIntentsCreate({
+        error: stripeError,
+      })
+      await mockModule('@codebuff/internal/util/stripe', () => ({
+        stripeServer: {
+          paymentIntents: mockPaymentIntentsCreate,
+        },
+      }))
+
+      await expect(
+        createPaymentIntent({
+          amountInCents: 1000,
+          stripeCustomerId: 'cus_test',
+          paymentMethodId: 'pm_declined',
+          description: 'Test',
+          idempotencyKey: 'idem_test',
+          metadata: {},
+        }),
+      ).rejects.toThrow('Card declined')
+    })
+
+    it('should handle empty metadata', async () => {
+      await createPaymentIntent({
+        amountInCents: 1000,
+        stripeCustomerId: 'cus_test',
+        paymentMethodId: 'pm_test',
+        description: 'Test',
+        idempotencyKey: 'idem_test',
+        metadata: {},
+      })
+
+      expect(mockPaymentIntentsCreate.calls[0].params.metadata).toEqual({})
+    })
+  })
+
   describe('isValidPaymentMethod', () => {
     describe('card payment methods', () => {
       it('should return true for card with future expiration date', () => {