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/design-system/ui/src/components/command-bar/command-bar.tsx

@@ -144,6 +144,9 @@ const Command = React.forwardRef<HTMLButtonElement, CommandProps>(
   (
     {
       className, 
+      /**
+       * @ignore
+       */
       type = "button", 
       /**
        * The command's label.

packages/generated/client-types/src/lib/models/Cart.ts

@@ -182,4 +182,8 @@ export interface Cart {
    * The total of gift cards with taxes
    */
   gift_card_tax_total?: number
+  /**
+   * The associated sales channels.
+   */
+  sales_channels?: Array<SalesChannel> | null
 }

packages/generated/client-types/src/lib/models/Order.ts

@@ -267,4 +267,8 @@ export interface Order {
    * An optional key-value map with additional details
    */
   metadata: Record<string, any> | null
+  /**
+   * The associated sales channels.
+   */
+  sales_channels?: Array<SalesChannel> | null
 }

packages/generated/client-types/src/lib/models/PublishableApiKeySalesChannel.ts

@@ -7,6 +7,10 @@ import { SetRelation, Merge } from "../core/ModelUtils"
  * This represents the association between the Publishable API keys and Sales Channels
  */
 export interface PublishableApiKeySalesChannel {
+  /**
+   * The relation's ID
+   */
+  id?: string
   /**
    * The sales channel's ID
    */
@@ -15,4 +19,16 @@ export interface PublishableApiKeySalesChannel {
    * The publishable API key's ID
    */
   publishable_key_id: string
+  /**
+   * The date with timezone at which the resource was created.
+   */
+  created_at: string
+  /**
+   * The date with timezone at which the resource was updated.
+   */
+  updated_at: string
+  /**
+   * The date with timezone at which the resource was deleted.
+   */
+  deleted_at: string | null
 }

packages/generated/client-types/src/lib/models/SalesChannel.ts

@@ -3,6 +3,9 @@
 /* eslint-disable */
 import { SetRelation, Merge } from "../core/ModelUtils"
 
+import type { Cart } from "./Cart"
+import type { Order } from "./Order"
+import type { PublishableApiKey } from "./PublishableApiKey"
 import type { SalesChannelLocation } from "./SalesChannelLocation"
 
 /**
@@ -45,4 +48,16 @@ export interface SalesChannel {
    * An optional key-value map with additional details
    */
   metadata?: Record<string, any> | null
+  /**
+   * The associated carts.
+   */
+  carts?: Array<Cart> | null
+  /**
+   * The associated orders.
+   */
+  orders?: Array<Order> | null
+  /**
+   * The associated publishable API keys.
+   */
+  publishableKeys?: Array<PublishableApiKey> | null
 }

packages/medusa-js/src/resources/customers.ts

@@ -35,7 +35,6 @@ class CustomerResource extends BaseResource {
    * Register a new customer. This will also automatically authenticate the customer and set their login session in the response Cookie header.
    * Subsequent requests sent with the JS client are sent with the Cookie session automatically.
    * @param {StorePostCustomersReq} payload - The details of the customer to be created.
-   * @param {string} query - Filters and pagination configurations to apply on the retrieved product collections.
    * @param {Record<string, any>} customHeaders - Custom headers to attach to the request.
    * @returns { ResponsePromise<StoreCustomersRes>} Resolves to the created customer's details.
    * 

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,

packages/oas/medusa-oas-cli/redocly/redocly-config.yaml

@@ -13,6 +13,7 @@ decorators:
         - Order
         - Payment
         - PaymentSession
+        - SalesChannel
       ClaimImage:
         - ClaimItem
       ClaimItem:
@@ -43,6 +44,7 @@ decorators:
         - Fulfillment
       GiftCard:
         - Order
+        - Region
       GiftCardTransaction:
         - GiftCard
         - Order
@@ -73,6 +75,9 @@ decorators:
         - Refund
         - Return
         - Swap
+        - SalesChannel
+        - Region
+        - LineItem
       OrderEdit:
         - Order
       OrderItemChange:
@@ -134,6 +139,10 @@ decorators:
         - Region
       TrackingLink:
         - Fulfillment
+      SalesChannel:
+        - Order
+        - Cart
+        - PublishableApiKey
 
 # Similar config to /www/docs/docusaurus.config.js > redocusaurus
 # Allows to emulate rendering of API public documentation when using `yarn redocly preview-docs openapi.yaml`

packages/workflows-sdk/src/utils/composer/helpers/step-response.ts

@@ -39,7 +39,76 @@ export class StepResponse<TOutput, TCompensateInput = TOutput> {
   /**
    * Creates a StepResponse that indicates that the step has failed and the retry mechanism should not kick in anymore.
    *
-   * @param message - An optional message to be logged. Default to `Permanent failure`.
+   * @param message - An optional message to be logged.
+   * 
+   * @example
+   * import { Product } from "@medusajs/medusa"
+   * import {
+   *   createStep,
+   *   StepResponse,
+   *   createWorkflow
+   * } from "@medusajs/workflows-sdk"
+   * 
+   * interface CreateProductInput {
+   *   title: string
+   * }
+   * 
+   * export const createProductStep = createStep(
+   *   "createProductStep",
+   *   async function (
+   *     input: CreateProductInput,
+   *     context
+   *   ) {
+   *     const productService = context.container.resolve(
+   *       "productService"
+   *     )
+   *     
+   *     try {
+   *       const product = await productService.create(input)
+   *       return new StepResponse({
+   *         product
+   *       }, {
+   *         product_id: product.id
+   *       })
+   *     } catch (e) {
+   *       return StepResponse.permanentFailure(`Couldn't create the product: ${e}`)
+   *     }
+   *   }
+   * )
+   * 
+   * interface WorkflowInput {
+   *  title: string
+   * }
+   * 
+   * const myWorkflow = createWorkflow<
+   *     WorkflowInput,
+   *     Product
+   *   >("my-workflow", (input) => {
+   *    // Everything here will be executed and resolved later
+   *    // during the execution. Including the data access.
+   * 
+   *     const product = createProductStep(input)
+   *   }
+   * )
+   * 
+   * myWorkflow()
+   *   .run({
+   *     input: {
+   *       title: "Shirt"
+   *     }
+   *   })
+   *   .then(({ errors, result }) => {
+   *     if (errors.length) {
+   *       errors.forEach((err) => {
+   *         if (typeof err.error === "object" && "message" in err.error) {
+   *           console.error(err.error.message)
+   *         } else {
+   *           console.error(err.error)
+   *         }
+   *       })
+   *     }
+   *     console.log(result)
+   *   })
    */
   static permanentFailure(message = "Permanent failure"): never {
     throw new PermanentStepFailureError(message)