@hawk.so/types 0.6.0-rc.2 → 0.6.2

package/build/index.d.ts

@@ -19,6 +19,8 @@ export * from './src/dbScheme/notificationsChannelSettings';
 export * from './src/dbScheme/membership';
 export * from './src/dbScheme/userProjectsLastVisit';
 export * from './src/dbScheme/plan';
+export * from './src/dbScheme/promoCode';
+export * from './src/dbScheme/promoCodeUsage';
 export * from './src/dbScheme/project';
 export * from './src/dbScheme/projectNotificationsRule';
 export * from './src/dbScheme/release';

package/build/index.js

@@ -35,6 +35,8 @@ __exportStar(require("./src/dbScheme/notificationsChannelSettings"), exports);
 __exportStar(require("./src/dbScheme/membership"), exports);
 __exportStar(require("./src/dbScheme/userProjectsLastVisit"), exports);
 __exportStar(require("./src/dbScheme/plan"), exports);
+__exportStar(require("./src/dbScheme/promoCode"), exports);
+__exportStar(require("./src/dbScheme/promoCodeUsage"), exports);
 __exportStar(require("./src/dbScheme/project"), exports);
 __exportStar(require("./src/dbScheme/projectNotificationsRule"), exports);
 __exportStar(require("./src/dbScheme/release"), exports);

package/build/src/dbScheme/promoCode.d.ts

@@ -0,0 +1,133 @@
+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
+ */
+export interface PromoCodeDBScheme {
+    /**
+     * Promo code id
+     */
+    _id: ObjectId;
+    /**
+     * Promo code value entered by user.
+     * Normalized: trim + uppercase. Allowed: A-Z, 0-9, "-", "_". Must be unique
+     * @example HAWK-2026
+     */
+    value: string;
+    /**
+     * What this promo code grants
+     */
+    benefit: PromoCodeBenefit;
+    /**
+     * Maximum total successful usages count.
+     * If not set — no global limit
+     * @example 100
+     */
+    limit?: number;
+    /**
+     * Date after which promo code cannot be used.
+     * If not set — no expiration
+     * @example 2026-12-31T23:59:59.000Z
+     */
+    expiresAt?: Date;
+    /**
+     * Date when promo code was created
+     * @example 2026-06-10T12:00:00.000Z
+     */
+    createdAt: Date;
+    /**
+     * Date when promo code was updated
+     * @example 2026-06-10T12:00:00.000Z
+     */
+    updatedAt: Date;
+    /**
+     * User or system id that created promo code
+     * @example 507f1f77bcf86cd799439013
+     */
+    createdBy: string;
+}

package/build/src/dbScheme/promoCode.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/src/dbScheme/promoCodeUsage.d.ts

@@ -0,0 +1,73 @@
+import type { ObjectId } from 'bson';
+import type { PromoCodeBenefitType } from './promoCode.ts';
+/**
+ * Promo code usage representation in DataBase
+ */
+export interface PromoCodeUsageDBScheme {
+    /**
+     * Promo code usage id
+     */
+    _id: ObjectId;
+    /**
+     * Applied promo code id
+     */
+    promoCodeId: ObjectId;
+    /**
+     * User who applied promo code
+     */
+    userId: string;
+    /**
+     * Workspace where promo code was applied
+     */
+    workspaceId: ObjectId;
+    /**
+     * Plan to which promo was applied or which was granted
+     */
+    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
+     */
+    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
+     */
+    appliedAt: Date;
+}

package/build/src/dbScheme/promoCodeUsage.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/index.ts

@@ -24,6 +24,8 @@ export * from './src/dbScheme/notificationsChannelSettings';
 export * from './src/dbScheme/membership';
 export * from './src/dbScheme/userProjectsLastVisit';
 export * from './src/dbScheme/plan';
+export * from './src/dbScheme/promoCode';
+export * from './src/dbScheme/promoCodeUsage';
 export * from './src/dbScheme/project';
 export * from './src/dbScheme/projectNotificationsRule';
 export * from './src/dbScheme/release';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hawk.so/types",
-  "version": "0.6.0-rc.2",
+  "version": "0.6.2",
   "description": "TypeScript definitions for Hawk",
   "types": "build/index.d.ts",
   "main": "build/index.js",

package/src/dbScheme/promoCode.ts

@@ -0,0 +1,164 @@
+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
+ */
+export interface PromoCodeDBScheme {
+  /**
+   * Promo code id
+   */
+  _id: ObjectId;
+
+  /**
+   * Promo code value entered by user.
+   * Normalized: trim + uppercase. Allowed: A-Z, 0-9, "-", "_". Must be unique
+   * @example HAWK-2026
+   */
+  value: string;
+
+  /**
+   * What this promo code grants
+   */
+  benefit: PromoCodeBenefit;
+
+  /**
+   * Maximum total successful usages count.
+   * If not set — no global limit
+   * @example 100
+   */
+  limit?: number;
+
+  /**
+   * Date after which promo code cannot be used.
+   * If not set — no expiration
+   * @example 2026-12-31T23:59:59.000Z
+   */
+  expiresAt?: Date;
+
+  /**
+   * Date when promo code was created
+   * @example 2026-06-10T12:00:00.000Z
+   */
+  createdAt: Date;
+
+  /**
+   * Date when promo code was updated
+   * @example 2026-06-10T12:00:00.000Z
+   */
+  updatedAt: Date;
+
+  /**
+   * User or system id that created promo code
+   * @example 507f1f77bcf86cd799439013
+   */
+  createdBy: string;
+}

package/src/dbScheme/promoCodeUsage.ts

@@ -0,0 +1,88 @@
+import type { ObjectId } from 'bson';
+import type { PromoCodeBenefitType } from './promoCode.ts';
+
+/**
+ * Promo code usage representation in DataBase
+ */
+export interface PromoCodeUsageDBScheme {
+  /**
+   * Promo code usage id
+   */
+  _id: ObjectId;
+
+  /**
+   * Applied promo code id
+   */
+  promoCodeId: ObjectId;
+
+  /**
+   * User who applied promo code
+   */
+  userId: string;
+
+  /**
+   * Workspace where promo code was applied
+   */
+  workspaceId: ObjectId;
+
+  /**
+   * Plan to which promo was applied or which was granted
+   */
+  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
+   */
+  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
+   */
+  appliedAt: Date;
+}