docs: fix tsdocs following typedoc update + 1.20 release (#6033)

* docs: fix tsdocs following typedoc update + 1.20 release

* Fix OAS validation errors

* fixes to react-docs-generator

* fix content linting

packages/medusa/src/interfaces/file-service.ts

@@ -29,7 +29,6 @@ export interface IFileService extends TransactionBaseService {
   /**
    * upload file to fileservice from stream
    * @param fileData file metadata relevant for fileservice to create and upload the file
-   * @param fileStream readable stream of the file to upload
    * */
   getUploadStreamDescriptor(
     fileData: UploadStreamDescriptorType

packages/medusa/src/interfaces/fulfillment-service.ts

@@ -390,12 +390,21 @@ export interface FulfillmentService extends TransactionBaseService {
   ): Promise<any>
 }
 
+/**
+ * @parentIgnore activeManager_,atomicPhase_,shouldRetryTransaction_,withTransaction
+ */
 export abstract class AbstractFulfillmentService
   extends TransactionBaseService
   implements FulfillmentService
 {
+  /**
+   * @ignore
+   */
   static _isFulfillmentService = true
 
+  /**
+   * @ignore
+   */
   static isFulfillmentService(object): boolean {
     return object?.constructor?._isFulfillmentService
   }

packages/medusa/src/interfaces/price-selection-strategy.ts

@@ -8,16 +8,23 @@ export interface IPriceSelectionStrategy extends ITransactionBaseService {
   /**
    * Calculate the original and discount price for a given variant in a set of
    * circumstances described in the context.
-   * @param variantId The variant id of the variant for which to retrieve prices
-   * @param context Details relevant to determine the correct pricing of the variant
    * @return pricing details in an object containing the calculated lowest price,
    * the default price an all valid prices for the given variant
    */
   calculateVariantPrice(
     data: {
+      /**
+       * The variant id of the variant for which to retrieve prices
+       */
       variantId: string
+      /**
+       * The variant's quantity.
+       */
       quantity?: number
     }[],
+    /**
+     * Details relevant to determine the correct pricing of the variant
+     */
     context: PriceSelectionContext
   ): Promise<Map<string, PriceSelectionResult>>
 

packages/medusa/src/models/cart.ts

@@ -228,6 +228,13 @@
  *     description: The total of gift cards with taxes
  *     type: integer
  *     example: 0
+ *   sales_channels:
+ *     description: The associated sales channels.
+ *     type: array
+ *     nullable: true
+ *     x-expandable: "sales_channels"
+ *     items:
+ *       $ref: "#/components/schemas/SalesChannel"
  */
 
 import {

packages/medusa/src/models/order.ts

@@ -742,4 +742,12 @@ export class Order extends BaseEntity {
  *     externalDocs:
  *       description: "Learn about the metadata attribute, and how to delete and update it."
  *       url: "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+ *   sales_channels:
+ *     description: The associated sales channels.
+ *     type: array
+ *     nullable: true
+ *     x-expandable: "sales_channels"
+ *     x-featureFlag: "medusa_v2"
+ *     items:
+ *       $ref: "#/components/schemas/SalesChannel"
  */

packages/medusa/src/models/publishable-api-key-sales-channel.ts

@@ -30,7 +30,14 @@ export class PublishableApiKeySalesChannel extends BaseEntity {
  * required:
  *   - publishable_key_id
  *   - sales_channel_id
+ *   - created_at
+ *   - updated_at
+ *   - deleted_at
  * properties:
+ *   id:
+ *    description: The relation's ID
+ *    type: string
+ *    example: pksc_01G8X9A7ESKAJXG2H0E6F1MW7A
  *   sales_channel_id:
  *     description: The sales channel's ID
  *     type: string
@@ -39,4 +46,17 @@ export class PublishableApiKeySalesChannel extends BaseEntity {
  *     description: The publishable API key's ID
  *     type: string
  *     example: pak_01G1G5V21KADXNGH29BJMAJ4B4
+ *   created_at:
+ *     description: The date with timezone at which the resource was created.
+ *     type: string
+ *     format: date-time
+ *   updated_at:
+ *     description: The date with timezone at which the resource was updated.
+ *     type: string
+ *     format: date-time
+ *   deleted_at:
+ *     description: The date with timezone at which the resource was deleted.
+ *     nullable: true
+ *     type: string
+ *     format: date-time
  */

packages/medusa/src/models/sales-channel.ts

@@ -165,4 +165,27 @@ export class SalesChannel extends SoftDeletableEntity {
  *    externalDocs:
  *      description: "Learn about the metadata attribute, and how to delete and update it."
  *      url: "https://docs.medusajs.com/development/entities/overview#metadata-attribute"
+ *  carts:
+ *    description: The associated carts.
+ *    type: array
+ *    nullable: true
+ *    x-expandable: "carts"
+ *    x-featureFlag: "medusa_v2"
+ *    items:
+ *      $ref: "#/components/schemas/Cart"
+ *  orders:
+ *    description: The associated orders.
+ *    type: array
+ *    nullable: true
+ *    x-expandable: "orders"
+ *    x-featureFlag: "medusa_v2"
+ *    items:
+ *      $ref: "#/components/schemas/Order"
+ *  publishableKeys:
+ *    description: The associated publishable API keys.
+ *    type: array
+ *    nullable: true
+ *    x-expandable: "publishableKeys"
+ *    items:
+ *      $ref: "#/components/schemas/PublishableApiKey"
  */

packages/medusa/src/services/customer.ts

@@ -416,7 +416,6 @@ class CustomerService extends TransactionBaseService {
    * Updates the customers' billing address.
    * @param {Customer} customer - the Customer to update
    * @param {Object|string} addressOrId - the value to set the billing address to
-   * @param {Object} addrRepo - address repository
    * @return {Promise} the result of the update operation
    */
   async updateBillingAddress_(

packages/medusa/src/services/fulfillment.ts

@@ -101,10 +101,6 @@ class FulfillmentService extends TransactionBaseService {
    * Retrieves the order line items, given an array of items.
    * @param order - the order to get line items from
    * @param items - the items to get
-   * @param transformer - a function to apply to each of the items
-   *    retrieved from the order, should return a line item. If the transformer
-   *    returns an undefined value the line item will be filtered from the
-   *    returned array.
    * @return the line items generated by the transformer.
    */
   async getFulfillmentItems_(

packages/medusa/src/services/new-totals.ts

@@ -79,10 +79,8 @@ export default class NewTotalsService extends TransactionBaseService {
 
   /**
    * Calculate and return the items totals for either the legacy calculation or the new calculation
-   * @param items
-   * @param includeTax
-   * @param calculationContext
-   * @param taxRate
+   * @param items 
+   * @param param1 
    */
   async getLineItemTotals(
     items: LineItem | LineItem[],
@@ -138,17 +136,18 @@ export default class NewTotalsService extends TransactionBaseService {
 
   /**
    * Calculate and return the totals for an item
-   * @param item
-   * @param includeTax
-   * @param lineItemAllocation
-   * @param taxLines Only needed to force the usage of the specified tax lines, often in the case where the item does not hold the tax lines
-   * @param calculationContext
+   * @param item 
+   * @param param1 
+   * @returns 
    */
   protected async getLineItemTotals_(
     item: LineItem,
     {
       includeTax,
       lineItemAllocation,
+      /**
+       * Only needed to force the usage of the specified tax lines, often in the case where the item does not hold the tax lines
+       */
       taxLines,
       calculationContext,
     }: {
@@ -247,9 +246,7 @@ export default class NewTotalsService extends TransactionBaseService {
   /**
    * Calculate and return the legacy calculated totals using the tax rate
    * @param item
-   * @param taxRate
-   * @param lineItemAllocation
-   * @param calculationContext
+   * @param param1
    */
   protected async getLineItemTotalsLegacy(
     item: LineItem,
@@ -327,8 +324,7 @@ export default class NewTotalsService extends TransactionBaseService {
   /**
    * Return the amount that can be refund on a line item
    * @param lineItem
-   * @param calculationContext
-   * @param taxRate
+   * @param param1
    */
   getLineItemRefund(
     lineItem: {
@@ -396,8 +392,7 @@ export default class NewTotalsService extends TransactionBaseService {
 
   /**
    * @param lineItem
-   * @param calculationContext
-   * @param taxRate
+   * @param param1
    * @protected
    */
   protected getLineItemRefundLegacy(
@@ -440,9 +435,7 @@ export default class NewTotalsService extends TransactionBaseService {
   /**
    * Calculate and return the gift cards totals
    * @param giftCardableAmount
-   * @param giftCardTransactions
-   * @param region
-   * @param giftCards
+   * @param param1
    */
   async getGiftCardTotals(
     giftCardableAmount: number,
@@ -520,8 +513,7 @@ export default class NewTotalsService extends TransactionBaseService {
 
   /**
    * Calculate and return the gift cards totals based on their transactions
-   * @param gift_card_transactions
-   * @param region
+   * @param param0
    */
   getGiftCardTransactionsTotals({
     giftCardTransactions,
@@ -564,10 +556,7 @@ export default class NewTotalsService extends TransactionBaseService {
   /**
    * Calculate and return the shipping methods totals for either the legacy calculation or the new calculation
    * @param shippingMethods
-   * @param includeTax
-   * @param discounts
-   * @param taxRate
-   * @param calculationContext
+   * @param param1
    */
   async getShippingMethodTotals(
     shippingMethods: ShippingMethod | ShippingMethod[],
@@ -658,10 +647,7 @@ export default class NewTotalsService extends TransactionBaseService {
   /**
    * Calculate and return the shipping method totals
    * @param shippingMethod
-   * @param includeTax
-   * @param calculationContext
-   * @param taxLines
-   * @param discounts
+   * @param param1
    */
   protected async getShippingMethodTotals_(
     shippingMethod: ShippingMethod,
@@ -742,9 +728,7 @@ export default class NewTotalsService extends TransactionBaseService {
   /**
    * Calculate and return the shipping method totals legacy using the tax rate
    * @param shippingMethod
-   * @param calculationContext
-   * @param taxRate
-   * @param discounts
+   * @param param1
    */
   protected async getShippingMethodTotalsLegacy(
     shippingMethod: ShippingMethod,

packages/medusa/src/services/note.ts

@@ -69,16 +69,22 @@ class NoteService extends TransactionBaseService {
   /** Fetches all notes related to the given selector
    * @param selector - the query object for find
    * @param config - the configuration used to find the objects. contains relations, skip, and take.
-   * @param config.relations - Which relations to include in the resulting list of Notes.
-   * @param config.take - How many Notes to take in the resulting list of Notes.
-   * @param config.skip - How many Notes to skip in the resulting list of Notes.
    * @return notes related to the given search.
    */
   async list(
     selector: Selector<Note>,
     config: FindConfig<Note> = {
+      /**
+       * How many Notes to skip in the resulting list of Notes.
+       */
       skip: 0,
+      /**
+       * How many Notes to take in the resulting list of Notes.
+       */
       take: 50,
+      /**
+       * Which relations to include in the resulting list of Notes.
+       */
       relations: [],
     }
   ): Promise<Note[]> {
@@ -90,16 +96,22 @@ class NoteService extends TransactionBaseService {
   /** Fetches all notes related to the given selector
    * @param selector - the query object for find
    * @param config - the configuration used to find the objects. contains relations, skip, and take.
-   * @param config.relations - Which relations to include in the resulting list of Notes.
-   * @param config.take - How many Notes to take in the resulting list of Notes.
-   * @param config.skip - How many Notes to skip in the resulting list of Notes.
    * @return notes related to the given search.
    */
   async listAndCount(
     selector: Selector<Note>,
     config: FindConfig<Note> = {
+      /**
+       * How many Notes to skip in the resulting list of Notes.
+       */
       skip: 0,
+      /**
+       * How many Notes to take in the resulting list of Notes.
+       */
       take: 50,
+      /**
+       * Which relations to include in the resulting list of Notes.
+       */
       relations: [],
     }
   ): Promise<[Note[], number]> {

packages/medusa/src/services/product-variant-inventory.ts

@@ -249,15 +249,21 @@ class ProductVariantInventoryService extends TransactionBaseService {
 
   /**
    * Attach a variant to an inventory item
-   * @param variantId variant id
-   * @param inventoryItemId inventory item id
-   * @param requiredQuantity quantity of variant to attach
    * @returns the variant inventory item
    */
   async attachInventoryItem(
     attachments: {
+      /**
+       * variant id
+       */
       variantId: string
+      /**
+       * inventory item id
+       */
       inventoryItemId: string
+      /**
+       * quantity of variant to attach
+       */
       requiredQuantity?: number
     }[]
   ): Promise<ProductVariantInventoryItem[]>

packages/medusa/src/utils/calculate-price-tax-amount.ts

@@ -1,10 +1,8 @@
 /**
  * Return the tax amount that
+ * 
  * - is includes in the price if it is tax inclusive
  * - will be applied on to the price if it is tax exclusive
- * @param price
- * @param includesTax
- * @param taxRate
  */
 export function calculatePriceTaxAmount({
   price,