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

docs-util/packages/react-docs-generator/src/classes/typedoc-manager.ts

@@ -6,7 +6,7 @@ import {
   TSFunctionSignatureType,
   TypeDescriptor,
 } from "react-docgen/dist/Documentation.js"
-import { Comment } from "typedoc"
+import { Comment, ReferenceReflection, ReferenceType } from "typedoc"
 import {
   Application,
   Context,
@@ -72,6 +72,8 @@ export default class TypedocManager {
       tsconfig: this.options.tsconfigPath,
       plugin: ["typedoc-plugin-custom"],
       enableInternalResolve: true,
+      internalModule: "internal",
+      checkVariables: true,
       logLevel: this.options.verbose ? "Verbose" : "None",
     })
 
@@ -108,24 +110,35 @@ export default class TypedocManager {
     // since the component may be a child of an exported component
     // we use the reflectionPathName to retrieve the component
     // by its "reflection path"
-    const reflection = this.project?.getChildByName(
+    let reflection = this.project?.getChildByName(reflectionPathName) as
-      reflectionPathName
+      | DeclarationReflection
-    ) as DeclarationReflection
+      | ReferenceReflection
+    if (reflection && reflection instanceof ReferenceReflection) {
+      // load declaration reflection
+      reflection = reflection.getTargetReflection() as DeclarationReflection
+    }
     if (!reflection) {
       return spec
     }
 
-    // retrieve the signature of the reflection
+    const doesReflectionHaveSignature =
-    // this is helpful to retrieve the props of the component
+      reflection.type?.type === "reference" &&
-    const mappedSignature = reflection.sources?.length
+      reflection.type.reflection instanceof DeclarationReflection &&
-      ? this.getMappedSignatureFromSource(reflection.sources[0])
+      reflection.type.reflection.signatures?.length
-      : undefined
 
-    if (
+    // If the original reflection in the reference type has a signature
-      mappedSignature?.signatures[0].parameters?.length &&
+    // use that signature. Else, try to get the signature from the mapping.
-      mappedSignature.signatures[0].parameters[0].type
+    const signature = doesReflectionHaveSignature
-    ) {
+      ? (
-      const signature = mappedSignature.signatures[0]
+          (reflection.type! as ReferenceType)
+            .reflection as DeclarationReflection
+        ).signatures![0]
+      : reflection.sources?.length
+        ? this.getMappedSignatureFromSource(reflection.sources[0])
+            ?.signatures[0]
+        : undefined
+
+    if (signature?.parameters?.length && signature.parameters[0].type) {
       // get the props of the component from the
       // first parameter in the signature.
       const props = getTypeChildren({
@@ -212,7 +225,7 @@ export default class TypedocManager {
             return
           }
           spec.props![prop.name] = {
-            description: this.normalizeDescription(this.getDescription(prop)),
+            description,
             required: !prop.flags.isOptional,
             tsType: prop.type
               ? this.getTsType(prop.type)
@@ -446,8 +459,9 @@ export default class TypedocManager {
   // this is useful for the CustomResolver to check
   // if a variable is a React component.
   isReactComponent(name: string): boolean {
-    const reflection = this.getReflectionByName(name)
+    const reflection = this.getReflectionByName(name, {
-
+      hasSignature: true,
+    })
     if (
       !reflection ||
       !(reflection instanceof DeclarationReflection) ||
@@ -459,7 +473,9 @@ export default class TypedocManager {
     return reflection.signatures.some(
       (signature) =>
         signature.type?.type === "reference" &&
-        signature.type.name === "ReactNode"
+        (signature.type.name === "ReactNode" ||
+          (signature.type.name === "Element" &&
+            signature.type.package === "@types/react"))
     )
   }
 
@@ -571,11 +587,27 @@ export default class TypedocManager {
   }
 
   // Gets a reflection by its name.
-  getReflectionByName(name: string): DeclarationReflection | undefined {
+  getReflectionByName(
+    name: string,
+    options?: {
+      hasSignature?: boolean
+    }
+  ): DeclarationReflection | undefined {
     return this.project
-      ? (Object.values(this.project?.reflections || {}).find(
+      ? (Object.values(this.project?.reflections || {}).find((ref) => {
-          (ref) => ref.name === name
+          if (ref.name !== name) {
-        ) as DeclarationReflection)
+            return false
+          }
+
+          if (
+            options?.hasSignature &&
+            (!(ref instanceof DeclarationReflection) || !ref.signatures)
+          ) {
+            return false
+          }
+
+          return true
+        }) as DeclarationReflection)
       : undefined
   }
 }

docs-util/packages/typedoc-config/extended-tsconfig/tsdoc.json

@@ -45,6 +45,10 @@
     {
       "tagName": "@typeParamDefinition",
       "syntaxKind": "block"
+    },
+    {
+      "tagName": "@parentIgnore",
+      "syntaxKind": "block"
     }
   ]
 }

docs-util/packages/typedoc-config/fulfillment.js

@@ -5,4 +5,5 @@ module.exports = getConfig({
   entryPointPath: "packages/medusa/src/interfaces/fulfillment-service.ts",
   tsConfigName: "medusa.json",
   name: "fulfillment",
+  parentIgnore: true,
 })

docs-util/packages/typedoc-plugin-custom/src/index.ts

@@ -5,6 +5,7 @@ import { load as parseOasSchemaPlugin } from "./parse-oas-schema-plugin"
 import { load as apiIgnorePlugin } from "./api-ignore"
 import { load as eslintExamplePlugin } from "./eslint-example"
 import { load as signatureModifierPlugin } from "./signature-modifier"
+import { load as parentIgnorePlugin } from "./parent-ignore"
 import { GenerateNamespacePlugin } from "./generate-namespace"
 
 export function load(app: Application) {
@@ -14,6 +15,7 @@ export function load(app: Application) {
   apiIgnorePlugin(app)
   eslintExamplePlugin(app)
   signatureModifierPlugin(app)
+  parentIgnorePlugin(app)
 
   new GenerateNamespacePlugin(app)
 }

docs-util/packages/typedoc-plugin-custom/src/parent-ignore.ts

@@ -0,0 +1,47 @@
+import {
+  Application,
+  Context,
+  Converter,
+  DeclarationReflection,
+  ParameterType,
+  ReflectionKind,
+} from "typedoc"
+
+export function load(app: Application) {
+  app.options.addDeclaration({
+    name: "parentIgnore",
+    help: "Whether to ignore items with the `@parentIgnore` tag.",
+    type: ParameterType.Boolean, // The default
+    defaultValue: false,
+  })
+
+  app.converter.on(Converter.EVENT_RESOLVE_BEGIN, (context: Context) => {
+    const isParentIgnoreEnabled = app.options.getValue("parentIgnore")
+    for (const reflection of context.project.getReflectionsByKind(
+      ReflectionKind.All
+    )) {
+      if (
+        isParentIgnoreEnabled &&
+        reflection instanceof DeclarationReflection
+      ) {
+        reflection.comment?.blockTags
+          .filter((tag) => tag.tag === "@parentIgnore")
+          .forEach((tag) => {
+            const fieldNames = tag.content
+              .map((content) => content.text)
+              .join("")
+              .split(",")
+            reflection.children = reflection.children?.filter(
+              (child) => !fieldNames.includes(child.name)
+            )
+          })
+      }
+
+      if (reflection.comment) {
+        reflection.comment.blockTags = reflection.comment?.blockTags.filter(
+          (tag) => tag.tag !== "@parentIgnore"
+        )
+      }
+    }
+  })
+}

docs-util/packages/typedoc-plugin-custom/src/resolve-references-plugin.ts

@@ -32,10 +32,18 @@ export function load(app: Application) {
     defaultValue: false,
   })
 
+  app.options.addDeclaration({
+    name: "checkVariables",
+    help: "Whether to check for and add variables.",
+    type: ParameterType.Boolean,
+    defaultValue: false,
+  })
+
   let activeReflection: Reflection | undefined
   const referencedSymbols = new Map<ts.Program, Set<ts.Symbol>>()
   const symbolToActiveRefl = new Map<ts.Symbol, Reflection>()
   const knownPrograms = new Map<Reflection, ts.Program>()
+  let checkedVariableSymbols = false
 
   function discoverMissingExports(
     context: Context,
@@ -90,6 +98,48 @@ export function load(app: Application) {
     }
   )
 
+  app.converter.on(Converter.EVENT_CREATE_DECLARATION, (context: Context) => {
+    if (!app.options.getValue("checkVariables") || checkedVariableSymbols) {
+      return
+    }
+    checkedVariableSymbols = true
+
+    context.program
+      .getSourceFiles()
+      .filter((file) =>
+        app.entryPoints.some((entryPoint) => file.fileName.includes(entryPoint))
+      )
+      .forEach((file) => {
+        if ("locals" in file) {
+          const localVariables = file.locals as Map<string, ts.Symbol>
+          if (!localVariables.size) {
+            return
+          }
+
+          const internalNs = getOrCreateInternalNs({
+            context,
+            scope: context.project,
+            nameSuffix: `${Math.random() * 100}`,
+          })
+
+          if (!internalNs) {
+            return
+          }
+
+          const internalContext = context.withScope(internalNs)
+
+          for (const [, value] of localVariables) {
+            if (!value.valueDeclaration) {
+              continue
+            }
+            if (shouldConvertSymbol(value, context.checker)) {
+              internalContext.converter.convertSymbol(internalContext, value)
+            }
+          }
+        }
+      })
+  })
+
   app.converter.on(
     Converter.EVENT_RESOLVE_BEGIN,
     function onResolveBegin(context: Context) {
@@ -118,21 +168,7 @@ export function load(app: Application) {
         // Nasty hack here that will almost certainly break in future TypeDoc versions.
         context.setActiveProgram(program)
 
-        const internalModuleOption =
+        const internalNs = getOrCreateInternalNs({ context, scope: mod })
-          context.converter.application.options.getValue("internalModule")
-
-        let internalNs: DeclarationReflection | undefined = undefined
-        if (internalModuleOption) {
-          internalNs = context
-            .withScope(mod)
-            .createDeclarationReflection(
-              ReflectionKind.Module,
-              void 0,
-              void 0,
-              context.converter.application.options.getValue("internalModule")
-            )
-          context.finalizeDeclarationReflection(internalNs)
-        }
 
         const internalContext = context.withScope(internalNs || mod)
 
@@ -199,3 +235,35 @@ function shouldConvertSymbol(symbol: ts.Symbol, checker: ts.TypeChecker) {
 
   return true
 }
+
+function getOrCreateInternalNs({
+  context,
+  scope,
+  nameSuffix = "",
+}: {
+  context: Context
+  scope: Reflection
+  nameSuffix?: string
+}): DeclarationReflection | undefined {
+  const internalNsName =
+    context.converter.application.options.getValue("internalModule")
+  if (!internalNsName) {
+    return undefined
+  }
+  let internalNs = context.project.getChildByName(
+    `${internalNsName}${nameSuffix}`
+  ) as DeclarationReflection
+  if (!internalNs) {
+    internalNs = context
+      .withScope(scope)
+      .createDeclarationReflection(
+        ReflectionKind.Module,
+        void 0,
+        void 0,
+        `${internalNsName}${nameSuffix}`
+      )
+    context.finalizeDeclarationReflection(internalNs)
+  }
+
+  return internalNs
+}

docs-util/packages/types/lib/index.d.ts

@@ -205,5 +205,15 @@ export declare module "typedoc" {
      * Namespace names whose child members should have their own documents.
      */
     allReflectionsHaveOwnDocumentInNamespace: string[]
+    /**
+     * Whether to ignore items with the `@parentIgnore` tag.
+     * @defaultValue false
+     */
+    parentIgnore: boolean
+    /**
+     * Whether to check for and add variables.
+     * @defaultValue false
+     */
+    checkVariables: boolean
   }
 }

docs-util/packages/types/tsconfig.json

@@ -3,5 +3,5 @@
   "compilerOptions": {
     "rootDir": "lib",
   },
-  "include": ["lib/index.d.ts"]
+  "include": ["lib"]
 }

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

@@ -80,9 +80,7 @@ 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 param1 
-   * @param calculationContext
-   * @param taxRate
    */
   async getLineItemTotals(
     items: LineItem | LineItem[],
@@ -139,16 +137,17 @@ export default class NewTotalsService extends TransactionBaseService {
   /**
    * Calculate and return the totals for an item
    * @param item 
-   * @param includeTax
+   * @param param1 
-   * @param lineItemAllocation
+   * @returns 
-   * @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
    */
   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 param1
-   * @param lineItemAllocation
-   * @param calculationContext
    */
   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 param1
-   * @param taxRate
    */
   getLineItemRefund(
     lineItem: {
@@ -396,8 +392,7 @@ export default class NewTotalsService extends TransactionBaseService {
 
   /**
    * @param lineItem
-   * @param calculationContext
+   * @param param1
-   * @param taxRate
    * @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 param1
-   * @param region
-   * @param giftCards
    */
   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 param0
-   * @param region
    */
   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 param1
-   * @param discounts
-   * @param taxRate
-   * @param calculationContext
    */
   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 param1
-   * @param calculationContext
-   * @param taxLines
-   * @param discounts
    */
   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 param1
-   * @param taxRate
-   * @param discounts
    */
   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)

www/apps/docs/content/medusa-react/overview.mdx

@@ -412,7 +412,7 @@ import { useAdminProducts } from "medusa-react"
 
 const Products = () => {
   const { products, isLoading } = useAdminProducts({
-    expand: "collection"
+    expand: "collection",
   })
 
   return (
@@ -445,7 +445,7 @@ import { useAdminProducts } from "medusa-react"
 
 const Products = () => {
   const { products, isLoading } = useAdminProducts({
-    expand: "variants,collection"
+    expand: "variants,collection",
   })
 
   return (
@@ -478,7 +478,7 @@ import { useAdminProducts } from "medusa-react"
 
 const Products = () => {
   const { products, isLoading } = useAdminProducts({
-    expand: ""
+    expand: "",
   })
 
   return (
@@ -558,7 +558,7 @@ import { useAdminProducts } from "medusa-react"
 const Products = () => {
   const { products, isLoading } = useAdminProducts({
     fields: "title",
-    expand: ""
+    expand: "",
   })
 
   return (
@@ -654,7 +654,7 @@ import { useAdminProducts } from "medusa-react"
 const Products = () => {
   const { products, isLoading } = useAdminProducts({
     fields: "",
-    expand: ""
+    expand: "",
   })
 
   return (
@@ -698,10 +698,10 @@ const Products = () => {
     products, 
     limit,
     offset,
-    isLoading
+    isLoading,
   } = useAdminProducts({
     limit: 20,
-    offset: 0
+    offset: 0,
   })
 
   return (
@@ -736,14 +736,14 @@ For example, if the `count` is `100` and the `limit` is `50`, you can divide the
 
 The `order` field, available on hooks supporting pagination, allows you to sort the retrieved items by an attribute of that item. For example, you can sort products by their `created_at` attribute by setting `order` to `created_at`:
 
-```ts
+```tsx
 import React from "react"
 import { useAdminProducts } from "medusa-react"
 
 const Products = () => {
   const { 
     products, 
-    isLoading
+    isLoading,
   } = useAdminProducts({
     order: "created_at",
   })
@@ -768,14 +768,14 @@ export default Products
 
 By default, the sort direction will be ascending. To change it to descending, pass a dash (`-`) before the attribute name. For example:
 
-```ts
+```tsx
 import React from "react"
 import { useAdminProducts } from "medusa-react"
 
 const Products = () => {
   const { 
     products, 
-    isLoading
+    isLoading,
   } = useAdminProducts({
     order: "-created_at",
   })

www/apps/ui/src/specs/Popover/Popover.Content.json

@@ -69,14 +69,6 @@
         ]
       },
       "required": false
-    },
-    "forceMount": {
-      "description": "Used to force mounting when more control is needed. Useful when\ncontrolling animation with React animation libraries.",
-      "required": false,
-      "tsType": {
-        "name": "literal",
-        "value": "true"
-      }
     }
   }
 }

www/apps/ui/src/specs/ToastProvider/ToastProvider.json

@@ -0,0 +1,6 @@
+{
+  "description": "",
+  "methods": [],
+  "displayName": "ToastProvider",
+  "props": {}
+}