From 70964b2b3d023509e4584ed333891b16deb30b9c Mon Sep 17 00:00:00 2001 From: Dobrunia Kostrigin <48620984+Dobrunia@users.noreply.github.com> Date: Thu, 11 Jun 2026 13:12:32 +0300 Subject: [PATCH 1/5] feat(types): expand promo code and usage schemas with detailed benefit types and properties --- src/dbScheme/promoCode.ts | 124 +++++++++++++++++++++++++++++++-- src/dbScheme/promoCodeUsage.ts | 48 ++++++------- 2 files changed, 140 insertions(+), 32 deletions(-) diff --git a/src/dbScheme/promoCode.ts b/src/dbScheme/promoCode.ts index 9bcf430..86e4042 100644 --- a/src/dbScheme/promoCode.ts +++ b/src/dbScheme/promoCode.ts @@ -1,5 +1,114 @@ import type { ObjectId } from 'bson'; +/** + * Promo code benefit type + */ +export type PromoCodeBenefitType = + | 'grant_plan' + | 'percent_discount' + | 'amount_discount' + | 'fixed_price'; + +/** + * Grant plan benefit — assigns a tariff to workspace immediately + */ +export interface GrantPlanPromoCodeBenefit { + /** + * Benefit type + */ + type: 'grant_plan'; + + /** + * Tariff plan to grant to workspace + */ + planId: ObjectId; +} + +/** + * Percent discount benefit + */ +export interface PercentDiscountPromoCodeBenefit { + /** + * Benefit type + */ + type: 'percent_discount'; + + /** + * Discount size in percent. Greater than 0, maximum 100 + * @example 20 + */ + percent: number; + + /** + * Plan ids this promo can be applied to. + * If not set or empty — applicable to any available plan + */ + applicablePlanIds?: ObjectId[]; + + /** + * Minimum final price after discount. + * If not set — defaults to 1 + */ + minFinalPrice?: number; +} + +/** + * Fixed amount discount benefit + */ +export interface AmountDiscountPromoCodeBenefit { + /** + * Benefit type + */ + type: 'amount_discount'; + + /** + * Discount size in money. Must be greater than 0 + */ + amount: number; + + /** + * Plan ids this promo can be applied to. + * If not set or empty — applicable to any available plan + */ + applicablePlanIds?: ObjectId[]; + + /** + * Minimum final price after discount. + * If not set — defaults to 1 + */ + minFinalPrice?: number; +} + +/** + * Fixed price benefit + */ +export interface FixedPricePromoCodeBenefit { + /** + * Benefit type + */ + type: 'fixed_price'; + + /** + * Final tariff price after promo is applied + */ + amount: number; + + /** + * Plan ids this promo can be applied to. + * If not set or empty — applicable to any available plan + */ + applicablePlanIds?: ObjectId[]; +} + +/** + * Promo code benefit union + */ +export type PromoCodeBenefit = + | GrantPlanPromoCodeBenefit + | PercentDiscountPromoCodeBenefit + | AmountDiscountPromoCodeBenefit + | FixedPricePromoCodeBenefit; + /** * Promo code representation in DataBase */ @@ -10,24 +119,27 @@ export interface PromoCodeDBScheme { _id: ObjectId; /** - * Normalized promo code value + * Promo code value entered by user. + * Normalized: trim + uppercase. Allowed: A-Z, 0-9, "-", "_". Must be unique * @example HAWK-2026 */ - code: string; + value: string; /** - * Tariff plan assigned by this promo code + * What this promo code grants */ - planId: ObjectId; + benefit: PromoCodeBenefit; /** - * Maximum total usages count + * Maximum total successful usages count. + * If not set — no global limit * @example 100 */ limit?: number; /** - * Date after which promo code cannot be used + * Date after which promo code cannot be used. + * If not set — no expiration * @example 2026-12-31T23:59:59.000Z */ expiresAt?: Date; diff --git a/src/dbScheme/promoCodeUsage.ts b/src/dbScheme/promoCodeUsage.ts index 4a014dc..1ea6694 100644 --- a/src/dbScheme/promoCodeUsage.ts +++ b/src/dbScheme/promoCodeUsage.ts @@ -1,4 +1,5 @@ import type { ObjectId } from 'bson'; +import type { PromoCodeBenefitType } from './promoCode'; /** * Promo code usage representation in DataBase @@ -25,38 +26,33 @@ export interface PromoCodeUsageDBScheme { workspaceId: ObjectId; /** - * Date when promo code was applied - * @example 2026-06-10T12:30:00.000Z + * Plan to which promo was applied or which was granted */ - appliedAt: Date; + planId?: ObjectId; /** - * UTM parameters captured when promo code was applied. Used for analytics purposes + * Benefit type at the moment of application */ - utm?: { - /** - * UTM source - identifies which site sent the traffic - */ - source?: string; + benefitType: PromoCodeBenefitType; - /** - * UTM medium - identifies what type of link was used - */ - medium?: string; + /** + * Plan price before promo, for discount promos + */ + originalAmount?: number; - /** - * UTM campaign - identifies a specific product promotion or strategic campaign - */ - campaign?: string; + /** + * Final price after promo, for discount promos + */ + finalAmount?: number; - /** - * UTM content - identifies what specifically was clicked to bring the user to the site - */ - content?: string; + /** + * Actual discount amount in money, for discount promos + */ + discountAmount?: number; - /** - * UTM term - identifies search terms - */ - term?: string; - }; + /** + * Date when promo code was successfully applied + * @example 2026-06-10T12:30:00.000Z + */ + appliedAt: Date; } From 56a8c59602c212b5ebc77b7f4b9abe9bb62cf169 Mon Sep 17 00:00:00 2001 From: Dobrunia Kostrigin <48620984+Dobrunia@users.noreply.github.com> Date: Thu, 11 Jun 2026 13:15:02 +0300 Subject: [PATCH 2/5] add utm --- src/dbScheme/promoCodeUsage.ts | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/src/dbScheme/promoCodeUsage.ts b/src/dbScheme/promoCodeUsage.ts index 1ea6694..f0f91e5 100644 --- a/src/dbScheme/promoCodeUsage.ts +++ b/src/dbScheme/promoCodeUsage.ts @@ -50,6 +50,36 @@ export interface PromoCodeUsageDBScheme { */ discountAmount?: number; + /** + * UTM parameters captured when promo code was applied. Used for analytics purposes + */ + utm?: { + /** + * UTM source - identifies which site sent the traffic + */ + source?: string; + + /** + * UTM medium - identifies what type of link was used + */ + medium?: string; + + /** + * UTM campaign - identifies a specific product promotion or strategic campaign + */ + campaign?: string; + + /** + * UTM content - identifies what specifically was clicked to bring the user to the site + */ + content?: string; + + /** + * UTM term - identifies search terms + */ + term?: string; + }; + /** * Date when promo code was successfully applied * @example 2026-06-10T12:30:00.000Z From 44280658ad1f24fc25321b798d5ece3609bb64a6 Mon Sep 17 00:00:00 2001 From: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 11 Jun 2026 10:15:45 +0000 Subject: [PATCH 3/5] Bump version up to 0.6.2 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index b719a5e..22d0efc 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@hawk.so/types", - "version": "0.6.1", + "version": "0.6.2", "description": "TypeScript definitions for Hawk", "types": "build/index.d.ts", "main": "build/index.js", From b6c7ecc612a2bcbc8b7bc2b66062d1e34bf530ba Mon Sep 17 00:00:00 2001 From: Dobrunia Kostrigin <48620984+Dobrunia@users.noreply.github.com> Date: Thu, 11 Jun 2026 13:18:11 +0300 Subject: [PATCH 4/5] fix --- src/dbScheme/promoCode.ts | 6 +++--- src/dbScheme/promoCodeUsage.ts | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/dbScheme/promoCode.ts b/src/dbScheme/promoCode.ts index 86e4042..275a033 100644 --- a/src/dbScheme/promoCode.ts +++ b/src/dbScheme/promoCode.ts @@ -1,7 +1,7 @@ import type { ObjectId } from 'bson'; /** - * Promo code benefit type + * Defines what a promo code grants to the user or workspace */ export type PromoCodeBenefitType = | 'grant_plan' @@ -25,7 +25,7 @@ export interface GrantPlanPromoCodeBenefit { } /** - * Percent discount benefit + * Reduces plan price by a percentage when purchasing a tariff */ export interface PercentDiscountPromoCodeBenefit { /** @@ -80,7 +80,7 @@ export interface AmountDiscountPromoCodeBenefit { } /** - * Fixed price benefit + * Sets a fixed final price for selected plans when purchasing a tariff */ export interface FixedPricePromoCodeBenefit { /** diff --git a/src/dbScheme/promoCodeUsage.ts b/src/dbScheme/promoCodeUsage.ts index f0f91e5..fb9f63d 100644 --- a/src/dbScheme/promoCodeUsage.ts +++ b/src/dbScheme/promoCodeUsage.ts @@ -1,5 +1,5 @@ import type { ObjectId } from 'bson'; -import type { PromoCodeBenefitType } from './promoCode'; +import type { PromoCodeBenefitType } from './promoCode.ts'; /** * Promo code usage representation in DataBase From 217a5b42aa08e2ae32d1e279df35db487883e997 Mon Sep 17 00:00:00 2001 From: github-actions <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 11 Jun 2026 10:18:39 +0000 Subject: [PATCH 5/5] Lint and build --- build/src/dbScheme/promoCode.d.ts | 101 +++++++++++++++++++++++-- build/src/dbScheme/promoCodeUsage.d.ts | 27 ++++++- 2 files changed, 119 insertions(+), 9 deletions(-) diff --git a/build/src/dbScheme/promoCode.d.ts b/build/src/dbScheme/promoCode.d.ts index d27d068..11dec1f 100644 --- a/build/src/dbScheme/promoCode.d.ts +++ b/build/src/dbScheme/promoCode.d.ts @@ -1,4 +1,90 @@ import type { ObjectId } from 'bson'; +/** + * Defines what a promo code grants to the user or workspace + */ +export type PromoCodeBenefitType = 'grant_plan' | 'percent_discount' | 'amount_discount' | 'fixed_price'; +/** + * Grant plan benefit — assigns a tariff to workspace immediately + */ +export interface GrantPlanPromoCodeBenefit { + /** + * Benefit type + */ + type: 'grant_plan'; + /** + * Tariff plan to grant to workspace + */ + planId: ObjectId; +} +/** + * Reduces plan price by a percentage when purchasing a tariff + */ +export interface PercentDiscountPromoCodeBenefit { + /** + * Benefit type + */ + type: 'percent_discount'; + /** + * Discount size in percent. Greater than 0, maximum 100 + * @example 20 + */ + percent: number; + /** + * Plan ids this promo can be applied to. + * If not set or empty — applicable to any available plan + */ + applicablePlanIds?: ObjectId[]; + /** + * Minimum final price after discount. + * If not set — defaults to 1 + */ + minFinalPrice?: number; +} +/** + * Fixed amount discount benefit + */ +export interface AmountDiscountPromoCodeBenefit { + /** + * Benefit type + */ + type: 'amount_discount'; + /** + * Discount size in money. Must be greater than 0 + */ + amount: number; + /** + * Plan ids this promo can be applied to. + * If not set or empty — applicable to any available plan + */ + applicablePlanIds?: ObjectId[]; + /** + * Minimum final price after discount. + * If not set — defaults to 1 + */ + minFinalPrice?: number; +} +/** + * Sets a fixed final price for selected plans when purchasing a tariff + */ +export interface FixedPricePromoCodeBenefit { + /** + * Benefit type + */ + type: 'fixed_price'; + /** + * Final tariff price after promo is applied + */ + amount: number; + /** + * Plan ids this promo can be applied to. + * If not set or empty — applicable to any available plan + */ + applicablePlanIds?: ObjectId[]; +} +/** + * Promo code benefit union + */ +export type PromoCodeBenefit = GrantPlanPromoCodeBenefit | PercentDiscountPromoCodeBenefit | AmountDiscountPromoCodeBenefit | FixedPricePromoCodeBenefit; /** * Promo code representation in DataBase */ @@ -8,21 +94,24 @@ export interface PromoCodeDBScheme { */ _id: ObjectId; /** - * Normalized promo code value + * Promo code value entered by user. + * Normalized: trim + uppercase. Allowed: A-Z, 0-9, "-", "_". Must be unique * @example HAWK-2026 */ - code: string; + value: string; /** - * Tariff plan assigned by this promo code + * What this promo code grants */ - planId: ObjectId; + benefit: PromoCodeBenefit; /** - * Maximum total usages count + * Maximum total successful usages count. + * If not set — no global limit * @example 100 */ limit?: number; /** - * Date after which promo code cannot be used + * Date after which promo code cannot be used. + * If not set — no expiration * @example 2026-12-31T23:59:59.000Z */ expiresAt?: Date; diff --git a/build/src/dbScheme/promoCodeUsage.d.ts b/build/src/dbScheme/promoCodeUsage.d.ts index fdaf2c9..a460f2d 100644 --- a/build/src/dbScheme/promoCodeUsage.d.ts +++ b/build/src/dbScheme/promoCodeUsage.d.ts @@ -1,4 +1,5 @@ import type { ObjectId } from 'bson'; +import type { PromoCodeBenefitType } from './promoCode.ts'; /** * Promo code usage representation in DataBase */ @@ -20,10 +21,25 @@ export interface PromoCodeUsageDBScheme { */ workspaceId: ObjectId; /** - * Date when promo code was applied - * @example 2026-06-10T12:30:00.000Z + * Plan to which promo was applied or which was granted */ - appliedAt: Date; + planId?: ObjectId; + /** + * Benefit type at the moment of application + */ + benefitType: PromoCodeBenefitType; + /** + * Plan price before promo, for discount promos + */ + originalAmount?: number; + /** + * Final price after promo, for discount promos + */ + finalAmount?: number; + /** + * Actual discount amount in money, for discount promos + */ + discountAmount?: number; /** * UTM parameters captured when promo code was applied. Used for analytics purposes */ @@ -49,4 +65,9 @@ export interface PromoCodeUsageDBScheme { */ term?: string; }; + /** + * Date when promo code was successfully applied + * @example 2026-06-10T12:30:00.000Z + */ + appliedAt: Date; }