Merge pull request #697 from sparrowapp-dev/development

release: Admin Panel Changes

Author: Mithesh54

package.json

@@ -145,6 +145,6 @@
   },
   "packageManager": "[email protected]",
   "optionalDependencies": {
-    "@sparrowapp-dev/stripe-billing": "^1.1.7"
+    "@sparrowapp-dev/stripe-billing": "^1.1.9"
   }
 }

pnpm-lock.yaml

@@ -12,8 +12,10 @@ import { PaymentEmailService } from "./services/payment-email.service";
 import { PaymentEmailHelper } from "./helpers/payment-email.helper";
 import { StripeWebhookHelper } from "./helpers/stripe-webhook.helper";
 import { StripeCustomerService } from "./services/stripe-customer.service";
+import { LicenseManagementService } from "./services/license-management.service";
 import { EmailService } from "@src/modules/common/services/email.service";
 import { AdminHubsRepository } from "@src/modules/user-admin/repositories/user-admin.hubs.repository";
+import { TeamRepository } from "@src/modules/identity/repositories/team.repository";
 
 // Try to import the Stripe module, but don't crash if it's not available
 let StripeModule: any;
@@ -46,6 +48,8 @@ export class BillingModule {
       PaymentEmailService,
       PaymentEmailHelper,
       StripeCustomerService,
+      LicenseManagementService,
+      TeamRepository,
       EmailService,
       AdminHubsRepository,
     ];
@@ -59,6 +63,7 @@ export class BillingModule {
       PaymentEmailService,
       PaymentEmailHelper,
       StripeCustomerService,
+      LicenseManagementService,
       BillingAuditService,
       ...(StripeModule ? [StripeModule] : []),
     ];

src/modules/billing/billing.module.ts

@@ -603,8 +603,8 @@ export class PaymentEmailHelper {
       updatePaymentUrl: `${process.env.FRONTEND_URL || "https://app.sparrowapp.dev"}/billing/${metadata.hubId}`,
       // Include seat data for action required email logic
       totalSeats: team.licenses?.totalSeats || 0,
-      usedSeats: team.licenses?.usedSeats || 0,
-      availableSeats: team.licenses?.availableSeats || 0,
+      usedSeats: team?.users?.length || 0,
+      invitedSeats: team?.invites?.length || 0,
     };
   }
 

src/modules/billing/helpers/payment-email.helper.ts

@@ -332,8 +332,8 @@ export class StripeWebhookHelper {
       const teamWithUpcomingInvoice =
         await this.stripeSubscriptionRepo.findTeamById(upcomingMetadata.hubId);
 
-      // Send upcoming payment email notification
       if (teamWithUpcomingInvoice) {
+        // Send upcoming payment email notification
         try {
           await this.paymentEmailHelper.sendUpcomingPaymentEmail(
             event.data.object,

src/modules/billing/helpers/stripe-webhook.helper.ts

@@ -2,6 +2,7 @@ import { Injectable, Inject } from "@nestjs/common";
 import { Collections } from "@src/modules/common/enum/database.collection.enum";
 import {
   BillingType,
+  PaymentProvider,
   SubscriptionStatus,
 } from "@src/modules/common/enum/billing.enum";
 import { Db, ObjectId, UpdateResult } from "mongodb";
@@ -183,4 +184,48 @@ export class StripeSubscriptionRepository {
       throw error;
     }
   }
+
+  /**
+   * Find teams with subscriptions ending in the given time window
+   * @param start Start datetime (e.g., now)
+   * @param end End datetime (e.g., now + 12 hours)
+   * @returns Array of team documents with subscriptions ending in range
+   */
+  async findTeamsWithSubscriptionsEndingInRange(
+    start: Date,
+    end: Date,
+  ): Promise<any[]> {
+    try {
+      return await this.db
+        .collection(Collections.TEAM)
+        .find({
+          $and: [
+            {
+              "billing.current_period_end": {
+                $gte: start,
+                $lte: end,
+              },
+            },
+            {
+              "billing.status": SubscriptionStatus.ACTIVE,
+            },
+            {
+              "plan.name": { $ne: PlanName.COMMUNITY },
+            },
+            {
+              "billing.paymentProviders": {
+                $elemMatch: {
+                  provider: PaymentProvider.STRIPE,
+                  subscriptionId: { $exists: true, $ne: null },
+                },
+              },
+            },
+          ],
+        })
+        .toArray();
+    } catch (error) {
+      console.error("Error fetching teams with expiring subscriptions:", error);
+      throw error;
+    }
+  }
 }

src/modules/billing/repositories/stripe-subscription.repository.ts

@@ -4,6 +4,8 @@ import {
   BillingEventType,
   BillingEntityType,
   BillingTransactionType,
+  BillingActorType,
+  BillingSource,
 } from "@src/modules/common/enum/billing.enum";
 import { PlanName } from "@src/modules/common/enum/plan.enum";
 import {
@@ -521,4 +523,72 @@ export class BillingAuditService {
 
     return changes;
   }
+
+  /**
+   * Record a license change event (seats reserved, freed, or optimized)
+   */
+  async recordLicenseChange(
+    entityId: string,
+    eventType:
+      | BillingEventType.SEAT_RESERVED_BY_USER_ADDITION
+      | BillingEventType.SEAT_RELEASED_BY_USER_REMOVAL
+      | BillingEventType.SEATS_CLEANED_UP_AS_UNUSED,
+    previousLicense: any,
+    newLicense: any,
+    context: {
+      actor: { type: BillingActorType; name: string };
+      source: BillingSource;
+      externalId?: string;
+      reason?: string;
+    },
+    metadata?: Record<string, any>,
+  ): Promise<string> {
+    // Calculate license changes
+    const changes = this.calculateLicenseChanges(previousLicense, newLicense);
+
+    if (changes.length === 0) {
+      console.warn("No license changes detected, skipping audit log");
+      return "";
+    }
+
+    return await this.recordBillingEvent({
+      eventType,
+      entityType: BillingEntityType.HUB,
+      entityId,
+      changes,
+      context,
+      metadata,
+    });
+  }
+
+  /**
+   * Calculate changes between license states
+   */
+  private calculateLicenseChanges(
+    previousLicense: any,
+    newLicense: any,
+  ): Array<{ field: string; previousValue: any; newValue: any }> {
+    const changes: Array<{
+      field: string;
+      previousValue: any;
+      newValue: any;
+    }> = [];
+
+    const licenseFields = ["totalSeats", "usedSeats", "availableSeats"];
+
+    for (const field of licenseFields) {
+      const previousValue = previousLicense?.[field];
+      const newValue = newLicense?.[field];
+
+      if (previousValue !== newValue) {
+        changes.push({
+          field,
+          previousValue: previousValue || null,
+          newValue: newValue || null,
+        });
+      }
+    }
+
+    return changes;
+  }
 }

src/modules/billing/services/billing-audit.service.ts

@@ -0,0 +1,136 @@
+import { Injectable } from "@nestjs/common";
+import { ObjectId } from "mongodb";
+import { LicensesDto } from "@src/modules/common/models/licenses.model";
+import { TeamRepository } from "@src/modules/identity/repositories/team.repository";
+import { BillingAuditService } from "./billing-audit.service";
+import {
+  BillingEventType,
+  BillingActorType,
+  BillingSource,
+} from "@src/modules/common/enum/billing.enum";
+
+/**
+ * License Management Service
+ * Centralized service for handling license tracking across teams
+ */
+@Injectable()
+export class LicenseManagementService {
+  constructor(
+    private readonly teamRepository: TeamRepository,
+    private readonly billingAuditService: BillingAuditService,
+  ) {}
+
+  /**
+   * Log license changes for audit purposes
+   * @param teamId - The team ID
+   * @param eventType - The type of license event
+   * @param context - Additional context for the event
+   */
+  private async logLicenseChange(
+    teamId: string,
+    eventType:
+      | BillingEventType.SEAT_RESERVED_BY_USER_ADDITION
+      | BillingEventType.SEAT_RELEASED_BY_USER_REMOVAL
+      | BillingEventType.SEATS_CLEANED_UP_AS_UNUSED,
+    context: string,
+    previousLicense?: LicensesDto,
+    newLicense?: LicensesDto,
+  ): Promise<void> {
+    try {
+      if (!previousLicense || !newLicense) return;
+
+      await this.billingAuditService.recordLicenseChange(
+        teamId,
+        eventType,
+        previousLicense,
+        newLicense,
+        {
+          actor: { type: BillingActorType.SYSTEM, name: "License Management" },
+          source: BillingSource.API_CALL,
+          reason: context,
+        },
+        {
+          context,
+          timestamp: new Date(),
+        },
+      );
+    } catch (error) {
+      console.error("Error logging license change:", error);
+      // Don't throw to avoid breaking main operation
+    }
+  }
+
+  /**
+   * Updates license tracking for a team
+   * @param teamId - The team ID to update licenses for
+   */
+  async updateLicenseTracking(teamId: string): Promise<void> {
+    try {
+      const team = await this.teamRepository.findTeamByTeamId(
+        new ObjectId(teamId),
+      );
+
+      if (!team) {
+        console.warn(`Team not found for license tracking: ${teamId}`);
+        return;
+      }
+
+      // Store previous license state for audit
+      const previousLicense: LicensesDto = team.licenses || {
+        totalSeats: Number(team.licenses?.totalSeats || 1),
+        usedSeats: Number(team.licenses?.usedSeats || 0),
+        availableSeats: Number(team.licenses?.availableSeats || 1),
+        lastUpdated: new Date(),
+      };
+
+      // Calculate current active users and pending invites
+      const currentActiveUsers = team.users?.length || 0;
+      const currentPendingInvites =
+        team.invites?.filter((invite: any) => !invite.isAccepted).length || 0;
+      const totalCurrentUsage = currentActiveUsers + currentPendingInvites;
+
+      // Use provided seats or get from existing licenses/billing
+      const totalSeats = team.licenses?.totalSeats || team.billing?.seats || 1;
+
+      const licenseData: LicensesDto = {
+        totalSeats: Number(totalSeats),
+        usedSeats: Number(totalCurrentUsage),
+        availableSeats: Number(totalSeats) - Number(totalCurrentUsage),
+        lastUpdated: new Date(),
+      };
+
+      // Update team with license data
+      await this.teamRepository.updateTeamById(new ObjectId(teamId), {
+        licenses: licenseData,
+      });
+
+      // Log license change audit event - determine event type based on usage change
+      const previousUsedSeats = previousLicense.usedSeats || 0;
+      const newUsedSeats = licenseData.usedSeats;
+
+      if (newUsedSeats > previousUsedSeats) {
+        // Users were added - seats reserved
+        await this.logLicenseChange(
+          teamId,
+          BillingEventType.SEAT_RESERVED_BY_USER_ADDITION,
+          "User added to team - seat reserved",
+          previousLicense,
+          licenseData,
+        );
+      } else if (newUsedSeats < previousUsedSeats) {
+        // Users were removed - seats freed
+        await this.logLicenseChange(
+          teamId,
+          BillingEventType.SEAT_RELEASED_BY_USER_REMOVAL,
+          "User removed from team - seat freed",
+          previousLicense,
+          licenseData,
+        );
+      }
+      // If no change in used seats, no audit event needed
+    } catch (error) {
+      console.error("Error updating license tracking:", error);
+      // Don't throw error to avoid breaking the main operation
+    }
+  }
+}