feat(core-flows,dashboard,js-sdk,promotion,medusa,types,utils): limit promotion usage per customer (#13451)

**What**
- implement promotion usage limits per customer/email
- fix registering spend usage over the limit
- fix type errors in promotion module tests

**How**
- introduce a new type of campaign budget that can be defined by an attribute such as customer id or email
- add `CampaignBudgetUsage` entity to keep track of the number of uses per attribute value
- update `registerUsage` and `computeActions` in the promotion module to work with the new type
- update `core-flows` to pass context needed for usage calculation to the promotion module

**Breaking**
- registering promotion usage now throws (and cart complete fails) if the budget limit is exceeded or if the cart completion would result in a breached limit

---

CLOSES CORE-1172
CLOSES CORE-1173
CLOSES CORE-1174
CLOSES CORE-1175


Co-authored-by: Adrien de Peretti <25098370+adrien2p@users.noreply.github.com>

packages/modules/promotion/src/utils/compute-actions/usage.ts

@@ -1,6 +1,9 @@
 import {
   BigNumberInput,
   CampaignBudgetExceededAction,
+  CampaignBudgetUsageContext,
+  CampaignBudgetUsageDTO,
+  ComputeActionContext,
   InferEntityType,
   PromotionDTO,
 } from "@medusajs/framework/types"
@@ -11,9 +14,20 @@ import {
 } from "@medusajs/framework/utils"
 import { Promotion } from "@models"
 
+/**
+ * Compute the action for a budget exceeded.
+ * @param promotion - the promotion being applied
+ * @param amount - amount can be:
+ *  1. discounted amount in case of spend budget
+ *  2. number of times the promotion has been used in case of usage budget
+ *  3. number of times the promotion has been used by a specific attribute value in case of use_by_attribute budget
+ * @param attributeUsage - the attribute usage in case of use_by_attribute budget
+ * @returns the exceeded action if the budget is exceeded, otherwise undefined
+ */
 export function computeActionForBudgetExceeded(
   promotion: PromotionDTO | InferEntityType<typeof Promotion>,
-  amount: BigNumberInput
+  amount: BigNumberInput,
+  attributeUsage?: CampaignBudgetUsageDTO
 ): CampaignBudgetExceededAction | void {
   const campaignBudget = promotion.campaign?.budget
 
@@ -21,7 +35,17 @@ export function computeActionForBudgetExceeded(
     return
   }
 
-  const campaignBudgetUsed = campaignBudget.used ?? 0
+  if (
+    campaignBudget.type === CampaignBudgetType.USE_BY_ATTRIBUTE &&
+    !attributeUsage
+  ) {
+    return
+  }
+
+  const campaignBudgetUsed = attributeUsage
+    ? attributeUsage.used
+    : campaignBudget.used ?? 0
+
   const totalUsed =
     campaignBudget.type === CampaignBudgetType.SPEND
       ? MathBN.add(campaignBudgetUsed, amount)
@@ -34,3 +58,16 @@ export function computeActionForBudgetExceeded(
     }
   }
 }
+
+export function getBudgetUsageContextFromComputeActionContext(
+  computeActionContext: ComputeActionContext
+): CampaignBudgetUsageContext {
+  return {
+    customer_id:
+      computeActionContext.customer_id ??
+      (computeActionContext.customer as any)?.id ??
+      null,
+    customer_email:
+      (computeActionContext.email as string | undefined | null) ?? null,
+  }
+}