@hawk.so/types 0.6.1 → 0.6.3

package/build/index.d.ts

@@ -10,6 +10,7 @@ export * from './src/base/event/taskManagerItem';
 export * from './src/base/event/addons';
 export * from './src/base/integrations/integrationToken';
 export * from './src/base/project/ProjectTaskManager';
+export * from './src/base/utm';
 export * from './src/base/workspace/GitHubIntegration';
 export * from './src/base/user/GitHubAuthorization';
 export * from './src/dbScheme/businessOperation';

package/build/index.js

@@ -26,6 +26,7 @@ __exportStar(require("./src/base/event/taskManagerItem"), exports);
 __exportStar(require("./src/base/event/addons"), exports);
 __exportStar(require("./src/base/integrations/integrationToken"), exports);
 __exportStar(require("./src/base/project/ProjectTaskManager"), exports);
+__exportStar(require("./src/base/utm"), exports);
 __exportStar(require("./src/base/workspace/GitHubIntegration"), exports);
 __exportStar(require("./src/base/user/GitHubAuthorization"), exports);
 __exportStar(require("./src/dbScheme/businessOperation"), exports);

package/build/src/base/utm.d.ts

@@ -0,0 +1,25 @@
+/**
+ * UTM parameters captured for analytics.
+ */
+export interface 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;
+}

package/build/src/base/utm.js

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

package/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;

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

@@ -1,4 +1,6 @@
 import type { ObjectId } from 'bson';
+import type { PromoCodeBenefitType } from './promoCode.ts';
+import type { Utm } from '../base/utm.ts';
 /**
  * Promo code usage representation in DataBase
  */
@@ -20,33 +22,32 @@ 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
      */
-    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;
-    };
+    utm?: Utm;
+    /**
+     * Date when promo code was successfully applied
+     * @example 2026-06-10T12:30:00.000Z
+     */
+    appliedAt: Date;
 }

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

@@ -4,6 +4,7 @@ import type { BankCard } from './bankCard.ts';
 import type { MembershipDBScheme } from './membership.ts';
 import type { UserProjectsLastVisitDBScheme } from './userProjectsLastVisit.ts';
 import type { GitHubAuthorization } from '../base/user/GitHubAuthorization.ts';
+import type { Utm } from '../base/utm.ts';
 /**
  * Interface representing how user is stored in DB
  */
@@ -57,28 +58,7 @@ export interface UserDBScheme {
     /**
      * UTM parameters from signup - Data form where user went to sign up. 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;
-    };
+    utm?: Utm;
     /**
      * GitHub OAuth authorizations.
      * Used for user-to-server operations (e.g. Copilot assignment).

package/index.ts

@@ -14,6 +14,7 @@ export * from './src/base/event/addons';
 
 export * from './src/base/integrations/integrationToken';
 export * from './src/base/project/ProjectTaskManager';
+export * from './src/base/utm';
 export * from './src/base/workspace/GitHubIntegration';
 export * from './src/base/user/GitHubAuthorization';
 

package/package.json

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

package/src/base/utm.ts

@@ -0,0 +1,29 @@
+/**
+ * UTM parameters captured for analytics.
+ */
+export interface 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;
+}

package/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;

package/src/dbScheme/promoCodeUsage.ts

@@ -1,4 +1,6 @@
 import type { ObjectId } from 'bson';
+import type { PromoCodeBenefitType } from './promoCode.ts';
+import type { Utm } from '../base/utm.ts';
 
 /**
  * Promo code usage representation in DataBase
@@ -25,38 +27,38 @@ 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
    */
-  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;
-  };
+  utm?: Utm;
+
+  /**
+   * Date when promo code was successfully applied
+   * @example 2026-06-10T12:30:00.000Z
+   */
+  appliedAt: Date;
 }

package/src/dbScheme/user.ts

@@ -4,6 +4,7 @@ import type { BankCard } from './bankCard.ts';
 import type { MembershipDBScheme } from './membership.ts';
 import type { UserProjectsLastVisitDBScheme } from './userProjectsLastVisit.ts';
 import type { GitHubAuthorization } from '../base/user/GitHubAuthorization.ts';
+import type { Utm } from '../base/utm.ts';
 
 /**
  * Interface representing how user is stored in DB
@@ -69,32 +70,7 @@ export interface UserDBScheme {
   /**
    * UTM parameters from signup - Data form where user went to sign up. 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;
-  };
+  utm?: Utm;
 
   /**
    * GitHub OAuth authorizations.