Function getUserUsageData

apps/sim/lib/billing/core/usage.ts:188–340

(
  userId: string,
  executor: DbClient = db
)

 * Get comprehensive usage data for a user
 */
export async function getUserUsageData(
  userId: string,
  executor: DbClient = db
): Promise<UsageData> {
  try {
    // Write — always on the primary regardless of executor routing.
    await ensureUserStatsExists(userId)

    const [userStatsData, subscription] = await Promise.all([
      // Read-your-write: must see the row ensureUserStatsExists may have just
      // inserted, which a lagging replica can miss (this path throws on a
      // missing row). Stays on the primary deliberately.
      db
        .select()
        .from(userStats)
        .where(eq(userStats.userId, userId))
        .limit(1),
      getHighestPrioritySubscription(userId, { executor }),
    ])

    if (userStatsData.length === 0) {
      logger.error('User stats not found for userId', { userId })
      throw new Error(`User stats not found for userId: ${userId}`)
    }

    const stats = userStatsData[0]
    const orgScoped = isOrgScopedSubscription(subscription, userId)
    const billingPeriod =
      subscription?.periodStart && subscription.periodEnd
        ? { start: subscription.periodStart, end: subscription.periodEnd }
        : defaultBillingPeriod()

    let currentUsageDecimal = toDecimal(stats.currentPeriodCost)
    if (!orgScoped) {
      currentUsageDecimal = currentUsageDecimal.plus(
        await getBillingPeriodUsageCost(
          { type: 'user', id: userId },
          billingPeriod,
          undefined,
          executor
        )
      )
    }

    // For personally-scoped Pro users, include any snapshotted usage from
    // a prior org-join so the display reflects their total Pro usage.
    if (subscription && isPro(subscription.plan) && !orgScoped) {
      const snapshotUsageDecimal = toDecimal(stats.proPeriodCostSnapshot)
      if (snapshotUsageDecimal.greaterThan(0)) {
        currentUsageDecimal = currentUsageDecimal.plus(snapshotUsageDecimal)
        logger.info('Including Pro snapshot in usage display', {
          userId,
          currentPeriodCost: stats.currentPeriodCost,
          proPeriodCostSnapshot: toNumber(snapshotUsageDecimal),
          totalUsage: toNumber(currentUsageDecimal),
        })
      }
    }