// prospectus-api/src/billing/stripe.service.ts
async createCheckoutSession(userId: number, priceId: string, planId: string, customerId?: string) {
  const baseUrl = this.configService.get<string>('FRONTEND_URL') || 'http://localhost:5173';
  return this.stripe.checkout.sessions.create({
    customer: customerId,
    payment_method_types: ['card'],
    line_items: [{ price: priceId, quantity: 1 }],
    mode: 'subscription',
    success_url: `${baseUrl}/dashboard?status=success&session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${baseUrl}/dashboard?status=cancelled`,
    metadata: { userId: userId.toString(), planId },
  });
}

// prospectus-api/src/billing/billing.service.ts
async updateUserBilling(userId: number, data: {
  trialStatus?: string;
  subscriptionEndDate?: Date;
  subscriptionStatus?: string;
  planId?: string;
}) {
  if (data.planId && !this.plans[data.planId]) {
    throw new BadRequestException(`Unknown plan ID: ${data.planId}`);
  }
  return this.prisma.user.update({
    where: { id: userId },
    data: {
      trialStatus: data.trialStatus,
      subscriptionEndDate: data.subscriptionEndDate,
      subscriptionStatus: data.subscriptionStatus,
      subscriptionPlan: data.planId,
    },
  });
}

// prospectus-api/src/billing/billing.service.ts
async claimWebhookEvent(eventId: string, eventType: string, source: string): Promise<boolean> {
  try {
    await this.prisma.processedWebhookEvent.create({
      data: { id: eventId, source, eventType },
    });
    return true; // Successfully claimed — first time seeing this event
  } catch (error: any) {
    if (error.code === 'P2002') return false; // Unique constraint violation → already claimed
    throw error;
  }
}

// 1. Controller declaration is 1 line of clean metadata:
@Post('opportunity')
@RequireLimit('opportunities_yearly')
async createOpportunity(@Body() dto: CreateOpportunityDto) { ... }

// 2. LimitGuard dynamically executes the appropriate domain counter:
@Injectable()
export class LimitGuard implements CanActivate {
  async canActivate(context: ExecutionContext): Promise<boolean> {
    const limitKey = this.reflector.getAllAndOverride<keyof PlanLimit>(
      LIMIT_KEY,
      [context.getHandler(), context.getClass()],
    );
    if (!limitKey) return true;

    const { user, organization } = context.switchToHttp().getRequest();
    if (!user || user.role === 'SUPERADMIN') return true; // SuperAdmin bypass

    switch (limitKey) {
      case 'seats':
        await this.billingService.checkSeatLimit(user.id, organization.id);
        break;
      case 'opportunities_yearly':
        await this.billingService.checkYearlyOpportunityLimit(user.id, organization.id);
        break;
      case 'leads_total':
        const limits = await this.billingService.getUserLimits(user.id);
        const count = await this.prisma.contact.count({ where: { organizationId: organization.id } });
        if (count >= limits.leads_total) {
          throw new ForbiddenException(`Lead limit reached (${limits.leads_total}). Upgrade plan.`);
        }
        break;
    }
    return true;
  }
}

// prospectus-api/src/billing/cron.service.ts
@Cron(CronExpression.EVERY_DAY_AT_MIDNIGHT)
async handleTrialExpiry() {
  const now = new Date();

  // 1. Move expired trials to 'expired'
  await this.prisma.user.updateMany({
    where: { trialStatus: 'active', subscriptionEndDate: { lt: now } },
    data: { trialStatus: 'expired' },
  });

  // 2. Archive 45-day delinquent accounts
  const fortyFiveDaysAgo = new Date(Date.now() - 45 * 24 * 60 * 60 * 1000);
  await this.prisma.user.updateMany({
    where: { trialStatus: 'expired', subscriptionEndDate: { lt: fortyFiveDaysAgo } },
    data: { trialStatus: 'archived' },
  });

  // 3. Roll over 30-day minute cycles for active subscribers
  await this.resetExpiredMinutesCycles(now);

  // 4. Retry failed DID releases
  await this.retryProvisioningJobs();
}