feat(billing): implement promo code functionality

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 { PaymentData } from './types/paymentData';
 import cloudPaymentsApi from '../utils/cloudPaymentsApi';
 import PlanModel from '../models/plan';
 import { ClientApi, ClientService, CustomerReceiptItem, ReceiptApi, ReceiptTypes, TaxationSystem } from 'cloudpayments';
+import PromoCodeService from '../utils/promoCodeService';
 
 const PENNY_MULTIPLIER = 100;
 
@@ -141,7 +142,7 @@ export default class CloudPaymentsWebhooks {
 
     let workspace: WorkspaceModel;
     let member: ConfirmedMemberDBScheme;
-    let plan: PlanDBScheme;
+    let plan: PlanModel;
     let planId: string;
 
     const { workspaceId, userId, tariffPlanId } = data;
@@ -161,11 +162,36 @@ export default class CloudPaymentsWebhooks {
 
     const recurrentPaymentSettings = data.cloudPayments?.recurrent;
 
+    if (data.promoCodeValue && !data.isCardLinkOperation) {
+      try {
+        const promoCodeService = new PromoCodeService(context.factories);
+        const promoPricing = await promoCodeService.getPricingForPlan(data.promoCodeValue, data.userId, data.workspaceId, plan);
+
+        if (
+          promoPricing.promoCode._id.toString() !== data.promoCodeId ||
+          promoPricing.finalAmount !== data.finalAmount ||
+          promoPricing.originalAmount !== data.originalAmount ||
+          promoPricing.discountAmount !== data.discountAmount
+        ) {
+          this.sendError(res, CheckCodes.WRONG_AMOUNT, '[Billing / Check] Promo code payment data does not match current promo calculation', body);
+
+          return;
+        }
+      } 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;
+      }
+    }
+
     /**
      * 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.
      */
-    const isRightAmount = +body.Amount === plan.monthlyCharge || recurrentPaymentSettings?.startDate;
+    const expectedAmount = data.finalAmount ?? plan.monthlyCharge;
+    const isRightAmount = +body.Amount === expectedAmount || (!data.finalAmount && recurrentPaymentSettings?.startDate);
 
     if (!isRightAmount) {
       this.sendError(res, CheckCodes.WRONG_AMOUNT, `[Billing / Check] Amount does not equal to plan monthly charge`, body);
@@ -295,6 +321,23 @@ export default class CloudPaymentsWebhooks {
       if (subscriptionId) {
         await workspace.setSubscriptionId(subscriptionId);
       }
+
+      if (data.promoCodeValue && !data.isCardLinkOperation && data.benefitType) {
+        const promoCodeService = new PromoCodeService(req.context.factories);
+        const promoCode = await promoCodeService.getValidPromoCode(data.promoCodeValue, data.userId, data.workspaceId);
+
+        await promoCodeService.createUsage({
+          promoCode,
+          userId: data.userId,
+          workspaceId: workspace._id,
+          planId: tariffPlan._id,
+          benefitType: data.benefitType,
+          originalAmount: data.originalAmount,
+          finalAmount: data.finalAmount,
+          discountAmount: data.discountAmount,
+          utm: data.promoUtm,
+        });
+      }
     } catch (e) {
       const error = e as Error;
 
@@ -442,7 +485,7 @@ plan monthly charge: ${data.cloudPayments?.recurrent.amount} ${body.Currency}`
          */
         const userEmail = body.IssuerBankCountry === RUSSIA_ISO_CODE ? user.email : undefined;
 
-        await this.sendReceipt(workspace, tariffPlan, userEmail);
+        await this.sendReceipt(workspace, tariffPlan, userEmail, data.finalAmount ?? tariffPlan.monthlyCharge);
 
         let messageText = '';
 
@@ -826,8 +869,9 @@ status: ${body.Status}`
    * @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 +880,9 @@ status: ${body.Status}`
     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
  */
@@ -56,6 +58,34 @@ export interface PaymentData {
    * If true, we will save user card
    */
   shouldSaveCard: boolean;
+  /**
+   * Applied promo code id
+   */
+  promoCodeId?: string;
+  /**
+   * Applied promo code value
+   */
+  promoCodeValue?: string;
+  /**
+   * Promo benefit type
+   */
+  benefitType?: 'grant_plan' | 'percent_discount' | 'amount_discount' | 'fixed_price';
+  /**
+   * Plan price before promo
+   */
+  originalAmount?: number;
+  /**
+   * Final price after promo
+   */
+  finalAmount?: number;
+  /**
+   * Actual discount amount
+   */
+  discountAmount?: number;
+  /**
+   * UTM parameters captured when promo was applied
+   */
+  promoUtm?: Utm;
   /**
    * True if this is card linking operation – charging minimal amount of money to validate card info
    */

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');
+  }
+}

src/models/promoCodeUsage.ts

@@ -0,0 +1,81 @@
+import { Collection, ObjectId } from 'mongodb';
+import AbstractModel from './abstractModel';
+import {
+  PromoCodeBenefitType,
+  PromoCodeUsageDBScheme
+} from '@hawk.so/types';
+
+/**
+ * Model representing successful promo code application.
+ */
+export default class PromoCodeUsageModel extends AbstractModel<PromoCodeUsageDBScheme> implements PromoCodeUsageDBScheme {
+  /**
+   * Promo code usage id.
+   */
+  public _id!: ObjectId;
+
+  /**
+   * Applied promo code id.
+   */
+  public promoCodeId!: ObjectId;
+
+  /**
+   * User who applied promo code.
+   */
+  public userId!: string;
+
+  /**
+   * Workspace where promo code was applied.
+   */
+  public workspaceId!: ObjectId;
+
+  /**
+   * Plan to which promo was applied.
+   */
+  public planId?: ObjectId;
+
+  /**
+   * Benefit type at application time.
+   */
+  public benefitType!: PromoCodeBenefitType;
+
+  /**
+   * Price before promo.
+   */
+  public originalAmount?: number;
+
+  /**
+   * Price after promo.
+   */
+  public finalAmount?: number;
+
+  /**
+   * Actual discount amount.
+   */
+  public discountAmount?: number;
+
+  /**
+   * UTM parameters captured on apply.
+   */
+  public utm?: PromoCodeUsageDBScheme['utm'];
+
+  /**
+   * Application date.
+   */
+  public appliedAt!: Date;
+
+  /**
+   * Model's collection.
+   */
+  protected collection: Collection<PromoCodeUsageDBScheme>;
+
+  /**
+   * Create PromoCodeUsage instance.
+   *
+   * @param usageData - usage data
+   */
+  constructor(usageData: PromoCodeUsageDBScheme) {
+    super(usageData);
+    this.collection = this.dbConnection.collection<PromoCodeUsageDBScheme>('promoCodeUsages');
+  }
+}