Function handleSubscribe

packages/billing/src/subscription.ts:629–700

(params: {
  userId: string
  stripeSubscription: Stripe.Subscription
  logger: Logger
})

 * All operations run inside an advisory-locked transaction.
 */
export async function handleSubscribe(params: {
  userId: string
  stripeSubscription: Stripe.Subscription
  logger: Logger
}): Promise<void> {
  const { userId, stripeSubscription, logger } = params
  const newResetDate = new Date(stripeSubscription.current_period_end * 1000)

  const { result: didMigrate } = await withAdvisoryLockTransaction({
    callback: async (tx) => {
      // Idempotency: check if credits were already migrated for this subscription.
      // We use the credit_ledger instead of the subscription table because
      // handleSubscriptionUpdated may upsert the subscription row before
      // invoice.paid fires, which would cause this check to skip migration.
      const migrationOpId = `subscribe-migrate-${stripeSubscription.id}`
      const existingMigration = await tx
        .select({ operation_id: schema.creditLedger.operation_id })
        .from(schema.creditLedger)
        .where(eq(schema.creditLedger.operation_id, migrationOpId))
        .limit(1)

      if (existingMigration.length > 0) {
        logger.info(
          { userId, subscriptionId: stripeSubscription.id },
          'Credits already migrated — skipping handleSubscribe',
        )
        return false
      }

      // Move next_quota_reset to align with Stripe billing period
      await tx
        .update(schema.user)
        .set({ next_quota_reset: newResetDate })
        .where(eq(schema.user.id, userId))

      // Migrate unused credits so nothing is lost
      await migrateUnusedCredits({
        tx,
        userId,
        subscriptionId: stripeSubscription.id,
        expiresAt: newResetDate,
        logger,
      })

      return true
    },
    lockKey: `user:${userId}`,
    context: { userId, subscriptionId: stripeSubscription.id },
    logger,
  })

  if (didMigrate) {
    trackEvent({
      event: AnalyticsEvent.SUBSCRIPTION_CREATED,
      userId,
      properties: {
        subscriptionId: stripeSubscription.id,
        newResetDate: newResetDate.toISOString(),