feat(billing): implement promo code functionality

migrations/20260615140000-add-promo-code-indexes.js

@@ -0,0 +1,29 @@
+/**
+ * @file Migration to add indexes for promoCodes and promoCodeUsages collections
+ */
+module.exports = {
+  async up(db) {
+    const promoCodes = db.collection('promoCodes');
+    const promoCodeUsages = db.collection('promoCodeUsages');
+
+    await promoCodes.createIndex({ value: 1 }, { unique: true });
+
+    await promoCodeUsages.createIndex({ promoCodeId: 1 });
+    await promoCodeUsages.createIndex({ promoCodeId: 1, userId: 1 }, { unique: true });
+    await promoCodeUsages.createIndex({ promoCodeId: 1, workspaceId: 1 }, { unique: true });
+    await promoCodeUsages.createIndex({ workspaceId: 1 });
+    await promoCodeUsages.createIndex({ userId: 1 });
+  },
+
+  async down(db) {
+    const promoCodes = db.collection('promoCodes');
+    const promoCodeUsages = db.collection('promoCodeUsages');
+
+    await promoCodes.dropIndex({ value: 1 });
+    await promoCodeUsages.dropIndex({ promoCodeId: 1 });
+    await promoCodeUsages.dropIndex({ promoCodeId: 1, userId: 1 });
+    await promoCodeUsages.dropIndex({ promoCodeId: 1, workspaceId: 1 });
+    await promoCodeUsages.dropIndex({ workspaceId: 1 });
+    await promoCodeUsages.dropIndex({ userId: 1 });
+  },
+};

package.json

@@ -1,6 +1,6 @@
 {
   "name": "hawk.api",
-  "version": "1.5.3",
+  "version": "1.5.4",
   "main": "index.ts",
   "license": "BUSL-1.1",
   "scripts": {
@@ -42,7 +42,7 @@
     "@graphql-tools/schema": "^8.5.1",
     "@graphql-tools/utils": "^8.9.0",
     "@hawk.so/nodejs": "^3.3.2",
-    "@hawk.so/types": "^0.5.9",
+    "@hawk.so/types": "^0.6.3",
     "@n1ru4l/json-patch-plus": "^0.2.0",
     "@node-saml/node-saml": "^5.0.1",
     "@octokit/oauth-methods": "^4.0.0",

src/billing/cloudpayments.ts

@@ -42,6 +42,7 @@
 import cloudPaymentsApi from '../utils/cloudPaymentsApi';
 import PlanModel from '../models/plan';
 import { ClientApi, ClientService, CustomerReceiptItem, ReceiptApi, ReceiptTypes, TaxationSystem } from 'cloudpayments';
+import PromoCodeService from '../services/promoCodeService';
 
 const PENNY_MULTIPLIER = 100;
 
@@ -88,7 +89,7 @@
     return router;
   }
 
   /**
    * Generates invoice id for payment
    *
    * @param tariffPlan - tariff plan to generate invoice id
@@ -141,7 +142,7 @@
 
     let workspace: WorkspaceModel;
     let member: ConfirmedMemberDBScheme;
-    let plan: PlanDBScheme;
+    let plan: PlanModel;
     let planId: string;
 
     const { workspaceId, userId, tariffPlanId } = data;
@@ -160,19 +161,70 @@
     }
 
     const recurrentPaymentSettings = data.cloudPayments?.recurrent;
+    let promoPricing;
 
     /**
-     * The amount will be considered correct if it is equal to the cost of the tariff plan.
-     * Also, the cost will be correct if it is a payment to activate the subscription.
+     * Revalidate promo before accepting payment.
+     *
+     * Amount check uses server-side pricing; usage is recorded later in /pay
+     * after workspace plan is updated successfully.
      */
-    const isRightAmount = +body.Amount === plan.monthlyCharge || recurrentPaymentSettings?.startDate;
+    if (data.promo && !data.isCardLinkOperation) {
+      try {
+        const promoCodeService = new PromoCodeService(context.factories);
+
+        promoPricing = await promoCodeService.getPricingForPromoCodeId(
+          data.promo.id,
+          data.userId,
+          data.workspaceId,
+          plan
+        );
+      } catch (e) {
+        const error = e as Error;
+
+        this.sendError(res, CheckCodes.PAYMENT_COULD_NOT_BE_ACCEPTED, `[Billing / Check] Promo code is invalid: ${error.toString()}`, body);
+
+        return;
+      }
+    }
+
+    /**
+     * Validates payment amount from CloudPayments against expected charge.
+     *
+     * expectedAmount:
+     * - with promo: final price recalculated on the server by promo id
+     * - without promo: full selected plan monthly charge
+     *
+     * isRightAmount is true when:
+     * 1) body.Amount equals expectedAmount — regular one-time payment (with or without promo)
+     * 2) no promo and recurrent.startDate is set — subscription is created with a deferred first charge;
+     *    current payment can be a card-link/auth amount (for example 1 RUB) while recurrent.amount
+     *    stores the real plan price for future charges
+     */
+    const expectedAmount = promoPricing?.finalAmount ?? plan.monthlyCharge;
+    const isRightAmount = +body.Amount === expectedAmount || (!data.promo && recurrentPaymentSettings?.startDate);
 
     if (!isRightAmount) {
       this.sendError(res, CheckCodes.WRONG_AMOUNT, `[Billing / Check] Amount does not equal to plan monthly charge`, body);
 
       return;
     }
 
+    if (
+      data.promo &&
+      recurrentPaymentSettings?.amount !== undefined &&
+      +recurrentPaymentSettings.amount !== plan.monthlyCharge
+    ) {
+      this.sendError(
+        res,
+        CheckCodes.WRONG_AMOUNT,
+        '[Billing / Check] Recurrent amount must equal full plan price when promo is applied',
+        body
+      );
+
+      return;
+    }
+
     /**
      * Create business operation about creation of subscription
      */
@@ -205,7 +257,7 @@
     telegram.sendMessage(`🤗 [Billing / Check] All checks passed successfully «${workspace.name}»`, TelegramBotURLs.Money)
       .catch(e => console.error('Error while sending message to Telegram: ' + e));
 
     HawkCatcher.send(new Error('[Billing / Check] All checks passed successfully'), body as any);
 
     res.json({
       code: CheckCodes.SUCCESS,
@@ -303,6 +355,32 @@
       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 (error) {
+        console.error('[Billing / Pay] Failed to record promo usage after plan change', error);
+      }
+    }
+
     // let accountId = workspace.accountId;
 
     /*
@@ -442,7 +520,7 @@
          */
         const userEmail = body.IssuerBankCountry === RUSSIA_ISO_CODE ? user.email : undefined;
 
-        await this.sendReceipt(workspace, tariffPlan, userEmail);
+        await this.sendReceipt(workspace, tariffPlan, userEmail, +body.Amount);
 
         let messageText = '';
 
@@ -555,7 +633,7 @@
 
     this.handleSendingToTelegramError(telegram.sendMessage(`❌ [Billing / Fail] Transaction failed for «${workspace.name}»`, TelegramBotURLs.Money));
 
     HawkCatcher.send(new Error('[Billing / Fail] Transaction failed'), body as any);
 
     res.json({
       code: FailCodes.SUCCESS,
@@ -737,7 +815,7 @@
    * @param errorText - error description
    * @param backtrace - request data and error data
    */
   private sendError(res: express.Response, errorCode: CheckCodes | PayCodes | FailCodes | RecurrentCodes, errorText: string, backtrace: { [key: string]: any }): void {
     res.json({
       code: errorCode,
     });
@@ -765,10 +843,29 @@
      */
     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,
       };
     }
 
@@ -802,7 +899,7 @@
     promise.catch(e => console.error('Error while sending message to Telegram: ' + e));
   }
 
   /**
    * Parses body and returns card data
    * @param request - request body to parse
    */
@@ -826,8 +923,9 @@
    * @param workspace - workspace for which payment is made
    * @param tariff - paid tariff plan
    * @param userMail - user email address
+   * @param amount - actual paid amount
    */
-  private async sendReceipt(workspace: WorkspaceModel, tariff: PlanModel, userMail?: string): Promise<void> {
+  private async sendReceipt(workspace: WorkspaceModel, tariff: PlanModel, userMail?: string, amount = tariff.monthlyCharge): Promise<void> {
     /**
      * A general tax that applies to all commercial activities
      * involving the production and distribution of goods and the provision of services
@@ -836,9 +934,9 @@
     const VALUE_ADDED_TAX = 0;
 
     const item: CustomerReceiptItem = {
-      amount: tariff.monthlyCharge,
+      amount,
       label: `${tariff.name} tariff plan`,
-      price: tariff.monthlyCharge,
+      price: amount,
       vat: VALUE_ADDED_TAX,
       quantity: 1,
     };

src/billing/types/paymentData.ts

@@ -1,3 +1,5 @@
+import type { Utm } from '@hawk.so/types';
+
 /**
  * Data for setting up recurring payments
  */
@@ -35,6 +37,22 @@ interface CloudPaymentsSettings {
   recurrent: RecurrentPaymentSettings;
 }
 
+/**
+ * Promo reference attached to payment request.
+ * Amounts are resolved on the server by promo id during check/pay.
+ */
+export interface PaymentPromoData {
+  /**
+   * Applied promo code id
+   */
+  id: string;
+
+  /**
+   * UTM parameters captured when promo was applied
+   */
+  utm?: Utm;
+}
+
 export interface PaymentData {
   /**
    * Data for Cloudpayments needs
@@ -56,6 +74,10 @@ export interface PaymentData {
    * If true, we will save user card
    */
   shouldSaveCard: boolean;
+  /**
+   * Applied promo code reference
+   */
+  promo?: PaymentPromoData;
   /**
    * True if this is card linking operation – charging minimal amount of money to validate card info
    */

src/directives/requireAdmin.ts

@@ -80,6 +80,14 @@ export default function requireAdminDirective(directiveName = 'requireAdmin') {
                 await checkByWorkspaceId(context, args.workspaceId);
               }
 
+              if (args.input?.workspaceId) {
+                await checkByWorkspaceId(context, args.input.workspaceId);
+              }
+
+              if (args.projectId) {
+                await checkByProjectId(context, args.projectId);
+              }
+
               if (args.input?.projectId) {
                 await checkByProjectId(context, args.input.projectId);
               }

src/index.ts

@@ -32,6 +32,8 @@ import ReleasesFactory from './models/releasesFactory';
 import RedisHelper from './redisHelper';
 import { appendSsoRoutes } from './sso';
 import { appendGitHubRoutes } from './integrations/github';
+import PromoCodesFactory from './models/promoCodesFactory';
+import PromoCodeUsagesFactory from './models/promoCodeUsagesFactory';
 
 /**
  * Option to enable playground
@@ -172,13 +174,21 @@ class HawkAPI {
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     const releasesFactory = new ReleasesFactory(mongo.databases.events!);
 
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const promoCodesFactory = new PromoCodesFactory(mongo.databases.hawk!);
+
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const promoCodeUsagesFactory = new PromoCodeUsagesFactory(mongo.databases.hawk!);
+
     return {
       usersFactory,
       workspacesFactory,
       projectsFactory,
       plansFactory,
       businessOperationsFactory,
       releasesFactory,
+      promoCodesFactory,
+      promoCodeUsagesFactory,
     };
   }
 

src/models/promoCode.ts

@@ -0,0 +1,66 @@
+import { Collection, ObjectId } from 'mongodb';
+import AbstractModel from './abstractModel';
+import {
+  PromoCodeBenefit,
+  PromoCodeDBScheme
+} from '@hawk.so/types';
+
+/**
+ * Model representing promo code settings.
+ */
+export default class PromoCodeModel extends AbstractModel<PromoCodeDBScheme> implements PromoCodeDBScheme {
+  /**
+   * Promo code id.
+   */
+  public _id!: ObjectId;
+
+  /**
+   * Normalized promo code value.
+   */
+  public value!: string;
+
+  /**
+   * Benefit granted by this promo code.
+   */
+  public benefit!: PromoCodeBenefit;
+
+  /**
+   * Maximum successful usages count.
+   */
+  public limit?: number;
+
+  /**
+   * Expiration date.
+   */
+  public expiresAt?: Date;
+
+  /**
+   * Creation date.
+   */
+  public createdAt!: Date;
+
+  /**
+   * Last update date.
+   */
+  public updatedAt!: Date;
+
+  /**
+   * Creator id.
+   */
+  public createdBy!: string;
+
+  /**
+   * Model's collection.
+   */
+  protected collection: Collection<PromoCodeDBScheme>;
+
+  /**
+   * Create PromoCode instance.
+   *
+   * @param promoCodeData - promo code data
+   */
+  constructor(promoCodeData: PromoCodeDBScheme) {
+    super(promoCodeData);
+    this.collection = this.dbConnection.collection<PromoCodeDBScheme>('promoCodes');
+  }
+}