refactor(billing): DRY up auto-topup logic (Commit 3.1)

- Extract shared helpers to auto-topup-helpers.ts:
  - fetchPaymentMethods() - fetches card + link payment methods
  - findValidPaymentMethod() - validates payment methods (expiration check)
  - createPaymentIntent() - creates Stripe payment intent with idempotency
  - getOrSetDefaultPaymentMethod() - gets/sets default payment method
- Reduce duplication between user and org auto-topup flows
- All 81 billing tests pass

Author: brandonkachen

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

@@ -0,0 +1,152 @@
+import { stripeServer } from '@codebuff/internal/util/stripe'
+
+import type { Logger } from '@codebuff/common/types/contracts/logger'
+import type Stripe from 'stripe'
+
+/**
+ * Fetches both card and link payment methods for a Stripe customer.
+ */
+export async function fetchPaymentMethods(
+  stripeCustomerId: string,
+): Promise<Stripe.PaymentMethod[]> {
+  const [cardPaymentMethods, linkPaymentMethods] = await Promise.all([
+    stripeServer.paymentMethods.list({
+      customer: stripeCustomerId,
+      type: 'card',
+    }),
+    stripeServer.paymentMethods.list({
+      customer: stripeCustomerId,
+      type: 'link',
+    }),
+  ])
+
+  return [...cardPaymentMethods.data, ...linkPaymentMethods.data]
+}
+
+/**
+ * Finds the first valid (non-expired) payment method from a list.
+ * Cards are checked for expiration, link methods are always valid.
+ */
+export function findValidPaymentMethod(
+  paymentMethods: Stripe.PaymentMethod[],
+): Stripe.PaymentMethod | undefined {
+  return paymentMethods.find((pm) => {
+    if (pm.type === 'card') {
+      return (
+        pm.card?.exp_year &&
+        pm.card.exp_month &&
+        new Date(pm.card.exp_year, pm.card.exp_month - 1) > new Date()
+      )
+    }
+    if (pm.type === 'link') {
+      return true
+    }
+    return false
+  })
+}
+
+export interface PaymentIntentParams {
+  amountInCents: number
+  stripeCustomerId: string
+  paymentMethodId: string
+  description: string
+  idempotencyKey: string
+  metadata: Record<string, string>
+}
+
+/**
+ * Creates a Stripe payment intent with idempotency key for safe retries.
+ */
+export async function createPaymentIntent(
+  params: PaymentIntentParams,
+): Promise<Stripe.PaymentIntent> {
+  const {
+    amountInCents,
+    stripeCustomerId,
+    paymentMethodId,
+    description,
+    idempotencyKey,
+    metadata,
+  } = params
+
+  return stripeServer.paymentIntents.create(
+    {
+      amount: amountInCents,
+      currency: 'usd',
+      customer: stripeCustomerId,
+      payment_method: paymentMethodId,
+      off_session: true,
+      confirm: true,
+      description,
+      metadata,
+    },
+    {
+      idempotencyKey,
+    },
+  )
+}
+
+/**
+ * Gets the default payment method for a customer, or selects and sets the first available one.
+ * Returns the payment method ID to use.
+ */
+export async function getOrSetDefaultPaymentMethod(params: {
+  stripeCustomerId: string
+  paymentMethods: Stripe.PaymentMethod[]
+  logger: Logger
+  logContext: Record<string, unknown>
+}): Promise<string> {
+  const { stripeCustomerId, paymentMethods, logger, logContext } = params
+
+  // Get the customer to check for default payment method
+  const customer = await stripeServer.customers.retrieve(stripeCustomerId)
+
+  // Check if there's already a default payment method
+  if (
+    customer &&
+    !customer.deleted &&
+    customer.invoice_settings?.default_payment_method
+  ) {
+    const defaultPaymentMethodId =
+      typeof customer.invoice_settings.default_payment_method === 'string'
+        ? customer.invoice_settings.default_payment_method
+        : customer.invoice_settings.default_payment_method.id
+
+    // Verify the default payment method is still valid and available
+    const isDefaultValid = paymentMethods.some(
+      (pm) => pm.id === defaultPaymentMethodId,
+    )
+
+    if (isDefaultValid) {
+      logger.debug(
+        { ...logContext, paymentMethodId: defaultPaymentMethodId },
+        'Using existing default payment method',
+      )
+      return defaultPaymentMethodId
+    }
+  }
+
+  // Use the first available and set it as default
+  const firstPaymentMethod = paymentMethods[0]
+  const paymentMethodToUse = firstPaymentMethod.id
+
+  try {
+    await stripeServer.customers.update(stripeCustomerId, {
+      invoice_settings: {
+        default_payment_method: paymentMethodToUse,
+      },
+    })
+
+    logger.info(
+      { ...logContext, paymentMethodId: paymentMethodToUse },
+      'Set first available payment method as default',
+    )
+  } catch (error) {
+    logger.warn(
+      { ...logContext, paymentMethodId: paymentMethodToUse, error },
+      'Failed to set default payment method, but will proceed with payment',
+    )
+  }
+
+  return paymentMethodToUse
+}