Function ensureActiveBlockGrantCallback

packages/billing/src/subscription.ts:257–398

(params: {
  conn: DbConn
  userId: string
  subscription: SubscriptionRow
  logger: Logger
  now?: Date
})

 * All operations are serialised under an advisory lock for the user.
 */
export async function ensureActiveBlockGrantCallback(params: {
  conn: DbConn
  userId: string
  subscription: SubscriptionRow
  logger: Logger
  now?: Date
}): Promise<BlockGrantResult> {
  const { conn, userId, subscription, logger, now = new Date() } = params
  const subscriptionId = subscription.stripe_subscription_id

  // 1. Check for an existing non-expired block grant (regardless of balance)
  const existingGrants = await conn
    .select()
    .from(schema.creditLedger)
    .where(
      and(
        eq(schema.creditLedger.user_id, userId),
        eq(schema.creditLedger.type, 'subscription'),
        gt(schema.creditLedger.expires_at, now),
      ),
    )
    .orderBy(desc(schema.creditLedger.expires_at))
    .limit(1)

  if (existingGrants.length > 0) {
    const g = existingGrants[0]
    
    // Block exists with credits remaining - return it
    if (g.balance > 0) {
      return {
        grantId: g.operation_id,
        credits: g.balance,
        expiresAt: g.expires_at!,
        isNew: false,
      } satisfies BlockGrant
    }
    
    // Block exists but is exhausted - don't create a new one until it expires
    return {
      error: 'block_exhausted',
      blockUsed: g.principal,
      blockLimit: g.principal,
      resetsAt: g.expires_at!,
    } satisfies BlockExhaustedError
  }

  // 2. Resolve limits
  const limits = await getSubscriptionLimits({
    userId,
    logger,
    conn,
    tier: subscription.tier,
  })

  // 3. Check weekly limit before creating a new block
  const weekly = await getWeeklyUsage({
    userId,
    billingPeriodStart: subscription.billing_period_start,