expand promo code and usage schemas

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;

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

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",

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;

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