chore: general TSDoc updates (#13742)

packages/core/types/src/http/campaign/admin/payloads.ts

@@ -35,6 +35,7 @@ export interface AdminCreateCampaign {
     /**
      * The budget's type. `spend` means the limit is set on the total amount discounted by the campaign's promotions;
      * `usage` means the limit is set on the total number of times the campaign's promotions can be used.
+     * `use_by_attribute` means the limit is set for a specific condition, such as per customer.
      */
     type?: CampaignBudgetTypeValues
     /**
@@ -49,7 +50,13 @@ export interface AdminCreateCampaign {
      */
     limit?: number | null
     /**
-     * The budget's attribute.
+     * The attribute that the budget limit is applied to. By default,
+     * the budget is applied globally. If the type is `use_by_attribute`, this field indicates the 
+     * attribute the budget is tracked by. For example, `customer_id` means the budget is tracked per customer.
+     *
+     * @example
+     * customer_id
+     * @since 2.11.0
      */
     attribute?: string | null
   } | null

packages/core/types/src/http/campaign/admin/responses.ts

@@ -64,7 +64,13 @@ export interface AdminCampaign {
      */
     used: number
     /**
-     * The budget's attribute if type is `use_by_attribute`.
+     * The attribute that the budget limit is applied to. By default,
+     * the budget is applied globally. If the type is `use_by_attribute`, this field indicates the 
+     * attribute the budget is tracked by. For example, `customer_id` means the budget is tracked per customer.
+     *
+     * @example
+     * customer_id
+     * @since 2.11.0
      */
     attribute: string
   }

packages/core/types/src/http/shipping-option/admin/payloads.ts

@@ -153,6 +153,8 @@ interface AdminCreateShippingOptionBase {
   rules?: AdminCreateShippingOptionRule[]
   /**
    * Custom key-value pairs that can be added to the shipping option.
+   * 
+   * @since 2.11.0
    */
   metadata?: Record<string, unknown>
 }
@@ -285,6 +287,8 @@ export interface AdminUpdateShippingOption {
   rules?: (AdminUpdateShippingOptionRule | AdminCreateShippingOptionRule)[]
   /**
    * Custom key-value pairs that can be added to the shipping option.
+   * 
+   * @since 2.11.0
    */
   metadata?: Record<string, unknown>
 }

packages/core/types/src/promotion/common/campaign-budget.ts

@@ -24,8 +24,8 @@ export interface CampaignBudgetDTO {
    *
    * - `spend` indicates that the budget is limited by the amount discounted by the promotions in the associated campaign.
    * - `usage` indicates that the budget is limited by the number of times the promotions of the associated campaign have been used.
-   * - `use_by_attribute` indicates that the budget is limited by the number of times the promotions of the associated campaign have been used by a specific attribute value.
-   * - `spend_by_attribute` indicates that the budget is limited by the amount discounted by the promotions in the associated campaign by a specific attribute value.
+   * - `use_by_attribute` indicates that the budget is limited by the number of times the promotions of the associated campaign have been used by a specific attribute value (for example, per customer)
+   * - `spend_by_attribute` indicates that the budget is limited by the amount discounted by the promotions in the associated campaign by a specific attribute value (for example, per customer)
    *
    */
   type?: CampaignBudgetTypeValues
@@ -50,12 +50,22 @@ export interface CampaignBudgetDTO {
   currency_code?: string
 
   /**
-   * The attribute of the campaign budget.
+   * The attribute that the budget limit is applied to. By default,
+   * the budget is applied globally. If the type is `use_by_attribute`, this field indicates the 
+   * attribute the budget is tracked by. For example, `customer_id` means the budget is tracked per customer.
+   * 
+   * @example
+   * customer_id
+   * @since 2.11.0
    */
   attribute?: string
 
   /**
-   * The usages of the campaign budget.
+   * The usages of the campaign budget. This is only set if the
+   * budget's type is `use_by_attribute` or `spend_by_attribute`.
+   * Each usage tracks the budget usage for a specific attribute value.
+   * 
+   * @since 2.11.0
    */
   usages?: CampaignBudgetUsageDTO[]
 }

packages/core/types/src/promotion/common/campaing-budget-usage.ts

@@ -12,7 +12,10 @@ export type CampaignBudgetUsageContext = {
   customer_email: string | null
 }
 /**
- * Record of promotion usage as part of a campaign
+ * Record of promotion usage as part of a campaign whose budget type
+ * is `use_by_attribute` or `spend_by_attribute`.
+ * 
+ * @since 2.11.0
  */
 export interface CampaignBudgetUsageDTO {
   /**
@@ -21,14 +24,14 @@ export interface CampaignBudgetUsageDTO {
   id: string
   /**
    * The value of the attribute that the promotion was used by.
-   * e.g. if budget campaign is defined on `email` as a useage attribute,
-   * `attribute_value` could contains email addresses
+   * For example, if the budget campaign's attribute is `customer_id`,',
+   * this value will be the ID of the customer that used the promotion.
    */
   attribute_value: string
   /**
    * The amount of times the promotion was used or
-   * the amount of money discounted by the promotion.
-   * Depends on the CampaignBudget type.
+   * the amount of money discounted by the promotion,
+   * depending on the campaign budget's type.
    */
   used: number
   /**

packages/core/types/src/promotion/common/compute-actions.ts

@@ -244,6 +244,8 @@ export interface ComputeActionContext extends Record<string, unknown> {
 
   /**
    * The cart's email
+   * 
+   * @since 2.11.0
    */
   email?: string
 

packages/core/types/src/promotion/mutations.ts

@@ -25,7 +25,13 @@ export interface CreateCampaignBudgetDTO {
   currency_code?: string | null
 
   /**
-   * The attribute by which the campaign budget usage is limited.
+   * The attribute that the budget limit is applied to. By default,
+   * the budget is applied globally. If the type is `use_by_attribute`, this field indicates the 
+   * attribute the budget is tracked by. For example, `customer_id` means the budget is tracked per customer.
+   * 
+   * @example
+   * customer_id
+   * @since 2.11.0
    */
   attribute?: string | null
 }