feat(billing): implement promo usage reservation and rollback mechanism in billing logic

Dobrunia · Dobrunia · commit be4f3b2d419a · 2026-06-14T01:44:30.000+03:00
diff --git a/src/billing/cloudpayments.ts b/src/billing/cloudpayments.ts
@@ -163,6 +163,13 @@ export default class CloudPaymentsWebhooks {
     const recurrentPaymentSettings = data.cloudPayments?.recurrent;
     let promoPricing;
 
+    /**
+     * Record promo usage before applying paid benefits.
+     *
+     * /pay runs after CloudPayments has accepted the charge, but workspace plan
+     * must not be changed if promo usage cannot be stored. Otherwise a transient
+     * DB/limit error would grant a discounted plan without consuming the promo.
+     */
     if (data.promo && !data.isCardLinkOperation) {
       try {
         const promoCodeService = new PromoCodeService(context.factories);
@@ -301,6 +308,36 @@ export default class CloudPaymentsWebhooks {
       return;
     }
 
+    if (data.promo && !data.isCardLinkOperation) {
+      try {
+        const promoCodeService = new PromoCodeService(req.context.factories);
+        const promoPricing = await promoCodeService.getPricingForPromoCodeId(
+          data.promo.id,
+          data.userId,
+          data.workspaceId,
+          tariffPlan
+        );
+
+        await promoCodeService.createUsage({
+          promoCode: promoPricing.promoCode,
+          userId: data.userId,
+          workspaceId: workspace._id,
+          planId: tariffPlan._id,
+          benefitType: promoPricing.benefitType,
+          originalAmount: promoPricing.originalAmount,
+          finalAmount: promoPricing.finalAmount,
+          discountAmount: promoPricing.discountAmount,
+          utm: data.promo.utm,
+        });
+      } catch (e) {
+        const error = e as Error;
+
+        this.sendError(res, PayCodes.SUCCESS, `[Billing / Pay] Failed to record promo usage: ${error.toString()}`, body);
+
+        return;
+      }
+    }
+
     try {
       await businessOperation.setStatus(BusinessOperationStatus.Confirmed);
 
@@ -334,34 +371,6 @@ export default class CloudPaymentsWebhooks {
       return;
     }
 
-    if (data.promo && !data.isCardLinkOperation) {
-      try {
-        const promoCodeService = new PromoCodeService(req.context.factories);
-        const promoPricing = await promoCodeService.getPricingForPromoCodeId(
-          data.promo.id,
-          data.userId,
-          data.workspaceId,
-          tariffPlan
-        );
-
-        await promoCodeService.createUsage({
-          promoCode: promoPricing.promoCode,
-          userId: data.userId,
-          workspaceId: workspace._id,
-          planId: tariffPlan._id,
-          benefitType: promoPricing.benefitType,
-          originalAmount: promoPricing.originalAmount,
-          finalAmount: promoPricing.finalAmount,
-          discountAmount: promoPricing.discountAmount,
-          utm: data.promo.utm,
-        });
-      } catch (e) {
-        const error = e as Error;
-
-        console.error(`[Billing / Pay] Failed to record promo usage: ${error.toString()}`, body);
-      }
-    }
-
     // let accountId = workspace.accountId;
 
     /*
@@ -824,10 +833,29 @@ status: ${body.Status}`
      */
     if (body.Data) {
       const parsedData = JSON.parse(body.Data || '{}') as WebhookData;
+      const checksumData = checksumService.parseAndVerifyChecksum(parsedData.checksum);
+
+      /**
+       * Treat checksum as the source of truth for billing intent.
+       *
+       * Widget Data is client-controlled, so it must not override signed fields like
+       * workspaceId, tariffPlanId, userId, shouldSaveCard, or promo id. Only
+       * CloudPayments recurrent settings are accepted from Data because they are
+       * validated separately against server-side pricing in /check.
+       */
+      if ('isCardLinkOperation' in checksumData) {
+        return {
+          ...checksumData,
+          tariffPlanId: '',
+          shouldSaveCard: false,
+          ...(parsedData.cloudPayments ? { cloudPayments: parsedData.cloudPayments } : {}),
+        };
+      }
 
       return {
-        ...checksumService.parseAndVerifyChecksum(parsedData.checksum),
-        ...parsedData,
+        ...checksumData,
+        ...(parsedData.cloudPayments ? { cloudPayments: parsedData.cloudPayments } : {}),
+        isCardLinkOperation: false,
       };
     }
 
diff --git a/src/models/promoCodeUsagesFactory.ts b/src/models/promoCodeUsagesFactory.ts
@@ -98,28 +98,39 @@ export default class PromoCodeUsagesFactory extends AbstractModelFactory<PromoCo
     return new PromoCodeUsageModel(usage);
   }
 
+  /**
+   * Deletes usage by id.
+   *
+   * Used only as compensation when promo benefit application fails after usage reservation.
+   *
+   * @param usageId - promo usage id
+   */
+  public async deleteById(usageId: ObjectId): Promise<void> {
+    await this.collection.deleteOne({
+      _id: usageId,
+    });
+  }
+
   /**
    * Ensures promo usage indexes exist before queries.
    *
    * MongoDB createIndex is idempotent: after API restart it reuses an existing index
    * with the same keys/options and does not throw if the index is already present.
    */
   private async ensureIndexesOnce(): Promise<void> {
-    if (!this.indexesPromise) {
-      this.indexesPromise = Promise.all([
-        this.collection.createIndex({ promoCodeId: 1 }),
-        this.collection.createIndex({
-          promoCodeId: 1,
-          userId: 1,
-        }, { unique: true }),
-        this.collection.createIndex({
-          promoCodeId: 1,
-          workspaceId: 1,
-        }, { unique: true }),
-        this.collection.createIndex({ workspaceId: 1 }),
-        this.collection.createIndex({ userId: 1 }),
-      ]).then(() => undefined);
-    }
+    this.indexesPromise ??= Promise.all([
+      this.collection.createIndex({ promoCodeId: 1 }),
+      this.collection.createIndex({
+        promoCodeId: 1,
+        userId: 1,
+      }, { unique: true }),
+      this.collection.createIndex({
+        promoCodeId: 1,
+        workspaceId: 1,
+      }, { unique: true }),
+      this.collection.createIndex({ workspaceId: 1 }),
+      this.collection.createIndex({ userId: 1 }),
+    ]).then(() => undefined);
 
     await this.indexesPromise;
   }
diff --git a/src/services/promoCodeService.ts b/src/services/promoCodeService.ts
@@ -5,6 +5,7 @@ import {
 } from '@hawk.so/types';
 import PlanModel from '../models/plan';
 import PromoCodeModel from '../models/promoCode';
+import PromoCodeUsageModel from '../models/promoCodeUsage';
 import WorkspaceModel from '../models/workspace';
 import { ContextFactories } from '../types/graphql';
 import type { Utm } from '@hawk.so/types';
@@ -498,10 +499,13 @@ export default class PromoCodeService {
     try {
       const now = new Date();
 
-      await workspace.updatePlanHistory(workspace.tariffPlanId.toString(), now, userId);
-      await workspace.updateLastChargeDate(now);
-      await workspace.changePlan(plan._id);
-      await this.createUsage({
+      /**
+       * Reserve usage before granting the plan.
+       *
+       * This makes promo usage a precondition for the benefit: if limits are exhausted
+       * or the insert fails, workspace state is not changed.
+       */
+      const usage = await this.createUsage({
         promoCode,
         userId,
         workspaceId: workspace._id,
@@ -510,6 +514,20 @@ export default class PromoCodeService {
         utm,
       });
 
+      try {
+        await workspace.updatePlanHistory(workspace.tariffPlanId.toString(), now, userId);
+        await workspace.updateLastChargeDate(now);
+        await workspace.changePlan(plan._id);
+      } catch (error) {
+        try {
+          await this.factories.promoCodeUsagesFactory.deleteById(usage._id);
+        } catch (rollbackError) {
+          console.error('Failed to rollback promo usage after grant_plan apply failure', rollbackError);
+        }
+
+        throw error;
+      }
+
       return plan;
     } catch (error) {
       if (error instanceof PromoCodeError) {
@@ -521,9 +539,13 @@ export default class PromoCodeService {
   }
 
   /**
-   * Creates usage after successful payment.
+   * Creates usage after successful payment or before immediate grant_plan apply.
+   *
+   * Unique indexes on promoCodeId + userId/workspaceId make this method the durable
+   * reservation point. Callers should grant the promo benefit only after it succeeds.
    *
    * @param params - usage creation params
+   * @returns created promo usage
    */
   public async createUsage(params: {
     promoCode: PromoCodeModel;
@@ -535,11 +557,11 @@ export default class PromoCodeService {
     finalAmount?: number;
     discountAmount?: number;
     utm?: PromoCodeUtm;
-  }): Promise<void> {
+  }): Promise<PromoCodeUsageModel> {
     await this.validateUsageLimits(params.promoCode, params.userId, params.workspaceId);
 
     try {
-      await this.factories.promoCodeUsagesFactory.create({
+      return await this.factories.promoCodeUsagesFactory.create({
         promoCodeId: params.promoCode._id,
         userId: params.userId,
         workspaceId: params.workspaceId,
diff --git a/test/billing/cloudpayments.test.ts b/test/billing/cloudpayments.test.ts
@@ -0,0 +1,86 @@
+import '../../src/env-test';
+
+jest.mock('cloudpayments', () => ({
+  ClientService: jest.fn().mockImplementation(() => ({
+    getReceiptApi: jest.fn().mockReturnValue({}),
+    getClientApi: jest.fn().mockReturnValue({}),
+  })),
+  ReceiptTypes: {
+    Income: 'Income',
+  },
+  TaxationSystem: {
+    Common: 'Common',
+  },
+}));
+
+jest.mock('../../src/mongo', () => ({
+  databases: {
+    hawk: {
+      collection: jest.fn().mockReturnValue({}),
+    },
+  },
+}));
+
+import { ObjectId } from 'mongodb';
+import CloudPaymentsWebhooks from '../../src/billing/cloudpayments';
+import checksumService from '../../src/utils/checksumService';
+
+process.env.JWT_SECRET_BILLING_CHECKSUM = 'checksum_secret';
+
+describe('CloudPaymentsWebhooks', () => {
+  describe('getDataFromRequest()', () => {
+    it('should trust checksum fields over unsigned widget Data fields', async () => {
+      const promoId = new ObjectId().toString();
+      const unsignedPromoId = new ObjectId().toString();
+      const checksum = await checksumService.generateChecksum({
+        workspaceId: 'signed-workspace',
+        userId: 'signed-user',
+        tariffPlanId: 'signed-plan',
+        shouldSaveCard: false,
+        nextPaymentDate: new Date().toISOString(),
+        promo: {
+          id: promoId,
+        },
+      });
+      const webhooks = new CloudPaymentsWebhooks() as any;
+
+      const data = await webhooks.getDataFromRequest({
+        body: {
+          Data: JSON.stringify({
+            checksum,
+            workspaceId: 'unsigned-workspace',
+            userId: 'unsigned-user',
+            tariffPlanId: 'unsigned-plan',
+            shouldSaveCard: true,
+            promo: {
+              id: unsignedPromoId,
+            },
+            cloudPayments: {
+              recurrent: {
+                interval: 'Month',
+                period: 1,
+              },
+            },
+          }),
+        },
+      });
+
+      expect(data).toMatchObject({
+        workspaceId: 'signed-workspace',
+        userId: 'signed-user',
+        tariffPlanId: 'signed-plan',
+        shouldSaveCard: false,
+        promo: {
+          id: promoId,
+        },
+        cloudPayments: {
+          recurrent: {
+            interval: 'Month',
+            period: 1,
+          },
+        },
+        isCardLinkOperation: false,
+      });
+    });
+  });
+});
diff --git a/test/services/promoCodeService.test.ts b/test/services/promoCodeService.test.ts
