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; } 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", diff --git a/src/dbScheme/promoCode.ts b/src/dbScheme/promoCode.ts index 9bcf430..275a033 100644 --- a/src/dbScheme/promoCode.ts +++ b/src/dbScheme/promoCode.ts @@ -1,5 +1,114 @@ 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 */ @@ -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..fb9f63d 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.ts'; /** * Promo code usage representation in DataBase @@ -25,10 +26,29 @@ 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 @@ -59,4 +79,10 @@ export interface PromoCodeUsageDBScheme { */ term?: string; }; + + /** + * Date when promo code was successfully applied + * @example 2026-06-10T12:30:00.000Z + */ + appliedAt: Date; }