feat(billing): implement promo code functionality by Dobrunia · Pull Request #657 · codex-team/hawk.api.nodejs

Dobrunia · 2026-06-12T11:48:42Z

feat(billing): implement promo code functionality and update related types

…types

github-actions · 2026-06-12T11:48:55Z

Thanks for adding a description — the PR is now marked as Ready for Review.

neSpecc · 2026-06-12T16:10:58Z

+  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;


lets wrap it with "promo" property. Also, maybe promo.id is enough?

…ability

…tructure

…a structure

neSpecc · 2026-06-13T15:54:09Z

+  benefitType: PaymentPromoBenefitType;
+
+  /**
+   * Plan price before promo
+   */
+  originalAmount: number;
+
+  /**
+   * Final price after promo
+   */
+  finalAmount: number;
+
+  /**
+   * Actual discount amount
+   */
+  discountAmount: number;
+
+  /**
+   * UTM parameters captured when promo was applied
+   */
+  utm?: Utm;


we can't rely on these data, because it can be changed by user. It's better to pass just promo.id and resolve these values from the db

neSpecc · 2026-06-13T16:02:03Z

     */
-    const isRightAmount = +body.Amount === plan.monthlyCharge || recurrentPaymentSettings?.startDate;
+    const expectedAmount = data.promo?.finalAmount ?? plan.monthlyCharge;
+    const isRightAmount = +body.Amount === expectedAmount || (!data.promo?.finalAmount && recurrentPaymentSettings?.startDate);


explain cases in jsdoc

neSpecc · 2026-06-13T16:06:43Z

+   */
+  private async ensureIndexesOnce(): Promise<void> {
+    if (!this.indexesPromise) {
+      this.indexesPromise = this.collection.createIndex({ value: 1 }, { unique: true }).then(() => undefined);


what if api will be restarted? will it ry to create another index and get an error?

neSpecc · 2026-06-13T16:10:21Z


  Mutation: {
+    /**
+     * Preview discount promo or immediately apply grant_plan promo.


explain what is preview

neSpecc · 2026-06-13T16:12:43Z

+
+      const member = await workspace.getMemberInfo(user.id);
+
+      if (!member || !('isAdmin' in member) || !member.isAdmin) {


access rights check could be done via "@requireAdmin" directive on GraphQL scheme

neSpecc · 2026-06-13T16:16:32Z

        throw new UserInputError('Wrong checksum data');
      }

+      const planPaymentAmount = paymentData.promo?.finalAmount ?? plan.monthlyCharge;


its better to compute final amount on the fly based on plan.monthlyCharge and promo code value.
User can change any value passed from frontend. So we can rely only on promo code id.

neSpecc · 2026-06-13T16:18:58Z

+ *
+ * @param plan - tariff plan
+ */
+function isPlanAvailable(plan: PlanModel): boolean {


naming is not clear enough. maybe isPlanAvailableForPurchase?

neSpecc · 2026-06-13T16:21:27Z

+  /**
+   * Factories used by promo code service.
+   */
+  private readonly factories: ContextFactories;


I'm not sure PromoCodeService should be places to utils folder since it depends on context and makes db requests.

Maybe /services/?

neSpecc · 2026-06-13T16:22:42Z

+   * @param userId - user id
+   * @param workspaceId - workspace id
+   */
+  public async preview(value: string, userId: string, workspaceId: string): Promise<PromoCodePreviewResult> {


are use sure it should be done on API side? Maybe it can be calculated on frontend?

neSpecc · 2026-06-13T16:25:24Z

+    expect(normalizePromoCodeValue(' promo_2026 ')).toBe('PROMO_2026');
+  });
+
+  it('calculates percent discount with min final price', () => {


add describe section explaining which method are you testing

describe('calculatePromoCodePlanPrice()', () => { it('should <do something> when <case you are testing>', () => { // ... }) })

Copilot

Pull request overview

This PR adds end-to-end promo code support to the billing flow, including GraphQL APIs for preview/apply, payment checksum propagation, CloudPayments webhook validation, and persistence for promo code definitions/usages (backed by updated @hawk.so/types).

Changes:

Introduces PromoCodeService (pricing/validation/apply + usage recording) and new promo code MongoDB models/factories.
Extends billing GraphQL schema/resolvers to preview/apply promos and attach promo data to payment checksums + webhook processing.
Updates UTM handling/types to use the shared Utm type and threads promo UTM through billing.

Reviewed changes

Copilot reviewed 22 out of 23 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
yarn.lock	Updates lockfile for `@hawk.so/types` bump.
package.json	Bumps app version and updates `@hawk.so/types` to `^0.6.3`.
src/utils/promoCodeService.ts	Implements promo code validation/pricing/apply + usage recording.
src/utils/utm/utm.ts	Tightens typing and returns `Utm` from UTM validation.
src/utils/checksumService.ts	Adds optional `promo` payload to billing checksums.
src/types/graphql.ts	Extends `ContextFactories` with promo factories.
src/typeDefs/billing.ts	Adds promo inputs/types and `previewPromoCode` mutation + composePayment promo response.
src/resolvers/user.ts	Switches signup UTM typing to shared `Utm`.
src/resolvers/billingNew.ts	Adds promo support in `composePayment`, `payWithCard` amount, and new `previewPromoCode` mutation.
src/models/usersFactory.ts	Switches UTM typing in user creation to shared `Utm`.
src/models/user.ts	Switches stored user UTM typing to shared `Utm`.
src/models/promoCodeUsagesFactory.ts	Adds promo usage collection access + limit-enforcing indexes.
src/models/promoCodeUsage.ts	Adds promo usage model.
src/models/promoCodesFactory.ts	Adds promo codes collection access + unique value index.
src/models/promoCode.ts	Adds promo code settings model.
src/index.ts	Wires promo factories into request context.
src/billing/types/paymentData.ts	Adds `PaymentPromoData` to payment payload typing.
src/billing/cloudpayments.ts	Validates promo data/amounts in `/check`, records usage in `/pay`, and updates receipt amount.
test/utils/promoCodeService.test.ts	Adds unit tests for promo service behavior.
test/sso/saml/controller.test.ts	Updates mocked factories to include promo factories.
test/resolvers/project.test.ts	Updates mocked factories to include promo factories.
test/resolvers/billingNew.test.ts	Updates mocked factories to include promo factories.
test/integrations/github-routes.test.ts	Updates mocked factories to include promo factories.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+      await workspace.updatePlanHistory(workspace.tariffPlanId.toString(), now, userId);
+      await workspace.updateLastChargeDate(now);
+      await workspace.changePlan(plan._id);
+      await this.createUsage({
+        promoCode,


+      if (data.promo && !data.isCardLinkOperation) {
+        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: data.promo.benefitType,
+          originalAmount: data.promo.originalAmount,
+          finalAmount: data.promo.finalAmount,
+          discountAmount: data.promo.discountAmount,
+          utm: data.promo.utm,
+        });
+      }


+      if (promoCode && !isCardLinkOperation) {
+        try {
+          const promoCodeService = new PromoCodeService(factories);
+          const pricing = await promoCodeService.getPricingForPlan(promoCode, user.id, workspace._id.toString(), plan);
+
+          paymentAmount = pricing.finalAmount;
+          paymentPromo = buildPaymentPromoData(pricing, promoUtm);


+    async previewPromoCode(
+      _obj: undefined,
+      { input }: PreviewPromoCodeArgs,
+      { user, factories }: ResolverContextWithUser
+    ): Promise<PromoCodePreviewResult & { applied: boolean }> {


…data references

…o code index handling

…in billing logic

…ne promo code application and workspace unblocking

…ount based on promo validity

…move unused utils

… promo code processing

… billingNew resolver

…sm in billing logic

…itialization logic

…in CloudPayments integration

…o codes and usages factories

neSpecc · 2026-06-15T14:10:45Z

should be covered by tests

Copilot

Pull request overview

Copilot reviewed 27 out of 28 changed files in this pull request and generated 4 comments.

      telegram
        .sendMessage(`👀 [Billing / Compose payment]

 card link operation: ${isCardLinkOperation}
-amount: ${+plan.monthlyCharge} RUB
+amount: ${+paymentAmount} RUB
 last charge date: ${workspace.lastChargeDate?.toISOString()}


+    case 'percent_discount': {
+      const minFinalPrice = benefit.minFinalPrice ?? DEFAULT_MIN_FINAL_PRICE;
+      const discountAmount = Math.floor(originalAmount * benefit.percent / 100);
+      const finalAmount = Math.max(originalAmount - discountAmount, minFinalPrice);


+    case 'amount_discount': {
+      const minFinalPrice = benefit.minFinalPrice ?? DEFAULT_MIN_FINAL_PRICE;
+      const finalAmount = Math.max(originalAmount - benefit.amount, minFinalPrice);


+    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;


…c to improve clarity and remove deprecated methods

…e related types and logic for clarity

…r improved readability and maintainability

Copilot

Pull request overview

Copilot reviewed 28 out of 29 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

src/billing/cloudpayments.ts:209

The amount validation now compares against expectedAmount (discounted when a promo is applied), but the error message still says it must equal the plan monthly charge. This is misleading when promos are used and makes troubleshooting harder.

    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);

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


+  switch (benefit.type) {
+    case 'percent_discount':
+      if (typeof benefit.percent !== 'number' || benefit.percent <= 0 || benefit.percent > 100) {
+        throw new PromoCodeError(PromoCodeErrorCode.Invalid, 'Percent discount is invalid');
+      }
+
+      return;


 card link operation: ${isCardLinkOperation}
-amount: ${+plan.monthlyCharge} RUB
+amount: ${+paymentAmount} RUB
 last charge date: ${workspace.lastChargeDate?.toISOString()}


…d usages for consistency

…ocks and utility functions for improved clarity and functionality

neSpecc · 2026-06-15T17:33:17Z

      return;
    }

+    if (


Does recurrent payment go through the "check" method?

Will data.promo be passed in case of recurrent payment?

Write clear jsdoc for this case

it should be covered by tests and tested manually

neSpecc · 2026-06-15T17:41:33Z

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


I think createUsage() should accept promoId, and resolve promoPricing internally.

neSpecc · 2026-06-15T17:43:32Z

+      /**
+       * 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 } : {}),
+        };
+      }


I can't understand this change. Why it was added?

neSpecc · 2026-06-15T17:46:35Z

          name: plan.name,
          monthlyCharge: plan.monthlyCharge,
        },
+        chargeAmount: isCardLinkOperation ? AMOUNT_FOR_CARD_VALIDATION : paymentAmount,


explain this change

neSpecc · 2026-06-15T17:46:59Z

+            benefitType: pricing.benefitType,
+            originalAmount: pricing.originalAmount,
+            finalAmount: pricing.finalAmount,
+            discountAmount: pricing.discountAmount,


why it is needed in composePayment?

neSpecc · 2026-06-15T17:49:07Z

+      let planPaymentAmount = plan.monthlyCharge;
+
+      if (paymentData.promo?.id) {
+        try {
+          const pricing = await new PromoCodeService(factories).getPricingForPromoCodeId(
+            paymentData.promo.id,
+            user.id,
+            paymentData.workspaceId,
+            plan
+          );
+
+          planPaymentAmount = pricing.finalAmount;
+        } catch (error) {
+          throwPromoCodeGraphQLError(error);
+        }
+      }
+


I'm not sure payWithCard is still used. And if it is used, probably, it won't accept promo-code. So this code is probably redundant

neSpecc · 2026-06-15T17:50:55Z

+    promoCodeUsagesCollection = accountsDb.collection<Omit<PromoCodeUsageDBScheme, '_id'>>('promoCodeUsages');
+  });
+
+  beforeEach(async () => {


explain what is happening here or separate to methods.

neSpecc · 2026-06-15T17:52:36Z

+      });
+
+      expect(apiResponse.data.code).toBe(CheckCodes.SUCCESS);
+      expect(createdBusinessOperation?.status).toBe(BusinessOperationStatus.Pending);


why business operation is pending?

neSpecc · 2026-06-15T17:52:58Z

+      expect(createdBusinessOperation?.status).toBe(BusinessOperationStatus.Pending);
+    });
+
+    it('should reject full plan amount when promo expects discounted charge', async () => {


what does it mean "reject full plan amount" ?

neSpecc · 2026-06-15T17:53:32Z

+  }
+
+  describe('/billing/check', () => {
+    it('should accept discounted amount when promo is valid', async () => {


wrap promo-related tests to another describe section

feat(billing): implement promo code functionality and update related …

9d1f51a

…types

github-actions Bot marked this pull request as ready for review June 12, 2026 11:48

github-actions Bot and others added 3 commits June 12, 2026 11:49

Bump version up to 1.5.4

d03e093

utm

fb4e419

chore: update @hawk.so/types to version 0.6.3

e85c91e

neSpecc reviewed Jun 12, 2026

View reviewed changes

Dobrunia added 5 commits June 12, 2026 20:43

fix

0aa6738

feat(promoCode): enhance discount logic and add tests for plan applic…

72a6e60

…ability

feat(billing): refactor promo code handling and update payment data s…

377fa6f

…tructure

lint fix

e926076

feat(billing): introduce PaymentPromoBenefitType and update promo dat…

4c25dc0

…a structure

neSpecc reviewed Jun 13, 2026

View reviewed changes

neSpecc requested a review from Copilot June 13, 2026 16:26

Copilot started reviewing on behalf of neSpecc June 13, 2026 16:26 View session

Copilot AI reviewed Jun 13, 2026

View reviewed changes

Dobrunia added 12 commits June 14, 2026 01:11

refactor(billing): streamline promo code handling and update payment …

515a9e8

…data references

refactor(billing): enhance payment amount validation and improve prom…

94001e8

…o code index handling

feat(billing): enhance promo code validation and extend admin checks …

5b2f68a

…in billing logic

feat(billing): implement previewOrApplyPromoCode function to streamli…

0b74706

…ne promo code application and workspace unblocking

refactor(billing): update promo code handling to calculate payment am…

1197be9

…ount based on promo validity

refactor(billing): move PromoCodeService to services directory and re…

210de9f

…move unused utils

fix(billing): improve error handling in workspace billing updates and…

cad0777

… promo code processing

feat(billing): add tests for promo code application and validation in…

2f8e5b5

… billingNew resolver

feat(billing): implement promo usage reservation and rollback mechani…

be4f3b2

…sm in billing logic

refactor(billing): simplify promo code retrieval and improve index in…

f5b405f

…itialization logic

feat(billing): enhance promo validation and payment processing logic …

10f578e

…in CloudPayments integration

refactor(billing): remove unused index initialization logic from prom…

7945cdb

…o codes and usages factories

neSpecc requested a review from Copilot June 15, 2026 14:08

Copilot started reviewing on behalf of neSpecc June 15, 2026 14:08 View session

neSpecc reviewed Jun 15, 2026

View reviewed changes

Comment thread src/services/promoCodeService.ts

neSpecc Jun 15, 2026

Copy link
Copy Markdown

Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should be covered by tests

Copilot AI reviewed Jun 15, 2026

View reviewed changes

Dobrunia added 3 commits June 15, 2026 17:52

refactor(billing): rename and restructure promo code application logi…

d782e2b

…c to improve clarity and remove deprecated methods

refactor(billing): rename applyPromoCode to verifyPromoCode and updat…

e9ed561

…e related types and logic for clarity

refactor(billing): streamline promo code pricing calculation logic fo…

b0ef27a

…r improved readability and maintainability

neSpecc requested a review from Copilot June 15, 2026 16:19

Copilot started reviewing on behalf of neSpecc June 15, 2026 16:20 View session

Copilot AI reviewed Jun 15, 2026

View reviewed changes

Dobrunia added 2 commits June 15, 2026 19:50

refactor(migrations): update index dropping syntax for promo codes an…

627f8fb

…d usages for consistency

refactor(billing): enhance CloudPayments test suite with additional m…

cf31f71

…ocks and utility functions for improved clarity and functionality

neSpecc reviewed Jun 15, 2026

View reviewed changes


		const member = await workspace.getMemberInfo(user.id);

		if (!member \|\| !('isAdmin' in member) \|\| !member.isAdmin) {

                     return;
                   }
+                  if (

Conversation

Dobrunia commented Jun 12, 2026

Uh oh!

github-actions Bot commented Jun 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants