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
@@ -101,9 +102,15 @@
   }
 
   /**
-   * Route to confirm the correctness of a user's payment
+   * Route to confirm that CloudPayments may process the payment.
    * https://developers.cloudpayments.ru/#check
    *
+   * This route handles both the first widget payment and later subscription charges.
+   * The first widget payment sends signed Data with billing intent and optional promo.
+   * Later recurrent charges may arrive without Data; in that case we resolve the
+   * workspace and current plan by SubscriptionId and validate the amount against
+   * the full plan price.
+   *
    * @param req - cloudpayments request with payment details
    * @param res - check result code
    */
@@ -141,7 +148,7 @@
 
     let workspace: WorkspaceModel;
     let member: ConfirmedMemberDBScheme;
-    let plan: PlanDBScheme;
+    let plan: PlanModel;
     let planId: string;
 
     const { workspaceId, userId, tariffPlanId } = data;
@@ -160,19 +167,81 @@
     }
 
     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;
     }
 
+    /**
+     * Validates recurrent.amount for the first subscription payment when promo is applied.
+     *
+     * CloudPayments flows:
+     * 1. First charge via widget — body.Data is present, checksum may include promo.id and
+     *    cloudPayments.recurrent.amount. Discount applies only to body.Amount (first charge).
+     *    recurrent.amount must stay equal to full plan.monthlyCharge so later renewals bill full price.
+     * 2. Monthly renewals — body.Data is absent, getDataFromRequest() resolves workspace by
+     *    SubscriptionId only, data.promo is undefined, this block is skipped, and amount must
+     *    equal plan.monthlyCharge (see isRightAmount above).
+     */
+    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 +274,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 +372,22 @@
       return;
     }
 
+    if (data.promo && !data.isCardLinkOperation) {
+      try {
+        const promoCodeService = new PromoCodeService(req.context.factories);
+
+        await promoCodeService.createUsage({
+          promoCodeId: data.promo.id,
+          userId: data.userId,
+          workspaceId: workspace._id,
+          plan: tariffPlan,
+          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 +527,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 +640,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,
@@ -563,9 +648,15 @@
   }
 
   /**
-   * Route is executed if the status of the recurring payment subscription has been changed.
+   * Route executed when a CloudPayments subscription status changes.
    * https://developers.cloudpayments.ru/#recurrent
    *
+   * This notification is about the subscription entity, not a replacement for
+   * /check or /pay transaction notifications. CloudPayments identifies which
+   * charge number this is via SuccessfulTransactionsNumber and sends the
+   * subscription Id; our transaction handlers use that Id to find the workspace.
+   * Promo data is not expected here and is not applied to subscription renewals.
+   *
    * @param req - cloudpayments request with subscription details
    * @param res - result code
    */
@@ -737,7 +828,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,
     });
@@ -751,7 +842,17 @@
   }
 
   /**
-   * Parses request body and returns data from it
+   * Parses CloudPayments request body into the signed billing intent.
+   *
+   * First widget payments include Data.checksum generated by composePayment; the
+   * checksum is the only trusted source for workspaceId, tariffPlanId, userId,
+   * shouldSaveCard, and promo id. Unsigned widget Data fields must not override it.
+   *
+   * Recurrent subscription renewals usually do not include Data. For those
+   * requests CloudPayments sends SubscriptionId and AccountId, so we restore the
+   * workspace and current plan by SubscriptionId. Because there is no signed promo
+   * in this path, data.promo is intentionally absent: promo discounts are applied
+   * only to the first widget payment, while renewals are charged at full plan price.
    *
    * @param req - request with necessary data
    */
@@ -760,15 +861,34 @@
     const body: CheckRequest | PayRequest | FailRequest = req.body;
 
     /**
-     * If Data is not presented in body means there is a recurring payment
-     * Data field is presented only in one-time payment requests or subscription initial request
+     * If Data is absent, this is a subscription renewal (or check/pay identified by SubscriptionId).
+     * Renewals do not carry promo: discount was applied only on the first widget payment.
      */
     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 +922,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 +946,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 +957,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
  */
@@ -18,7 +20,8 @@ interface RecurrentPaymentSettings {
   startDate?: string;
 
   /**
-   * Recurring payment amount.
+   * Recurring payment amount for automatic subscription renewals.
+   * Keep it equal to the full plan price even when the first widget charge uses a promo.
    */
   amount?: number;
 }
@@ -35,6 +38,23 @@ interface CloudPaymentsSettings {
   recurrent: RecurrentPaymentSettings;
 }
 
+/**
+ * Promo reference attached to the signed first payment request.
+ * Amounts are resolved on the server by promo id during check/pay.
+ * Recurrent renewals are restored by SubscriptionId and do not carry promo data.
+ */
+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 +76,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,
     };
   }