Function migrateUnusedCredits

packages/billing/src/subscription.ts:717–817

(params: {
  tx: DbTransaction
  userId: string
  subscriptionId: string
  expiresAt: Date
  logger: Logger
})

 * balance zeroed.
 */
export async function migrateUnusedCredits(params: {
  tx: DbTransaction
  userId: string
  subscriptionId: string
  expiresAt: Date
  logger: Logger
}): Promise<void> {
  const { tx, userId, subscriptionId, expiresAt, logger } = params
  const now = new Date()

  const unusedGrants = await tx
    .select()
    .from(schema.creditLedger)
    .where(
      and(
        eq(schema.creditLedger.user_id, userId),
        gt(schema.creditLedger.balance, 0),
        ne(schema.creditLedger.type, 'subscription'),
        isNull(schema.creditLedger.org_id),
        gt(schema.creditLedger.expires_at, now),
        lte(schema.creditLedger.expires_at, expiresAt),
      ),
    )

  const totalUnused = unusedGrants.reduce(
    (sum, grant) => sum + grant.balance,
    0,
  )

  // Deterministic ID ensures idempotency — duplicate webhook deliveries
  // will hit onConflictDoNothing and the handleSubscribe caller checks
  // for this operation_id before running.
  const operationId = `subscribe-migrate-${subscriptionId}`

  if (totalUnused === 0) {
    // Still insert the marker for idempotency so handleSubscribe's check
    // short-circuits on duplicate webhook deliveries.
    await tx
      .insert(schema.creditLedger)
      .values({
        operation_id: operationId,
        user_id: userId,
        type: 'free',
        principal: 0,
        balance: 0,
        priority: GRANT_PRIORITIES.free,
        expires_at: expiresAt,
        description: 'Migrated credits from subscription transition',
      })
      .onConflictDoNothing({ target: schema.creditLedger.operation_id })
    logger.debug({ userId }, 'No unused credits to migrate')
    return
  }

  // Zero out old grants
  for (const grant of unusedGrants) {
    await tx
      .update(schema.creditLedger)