docs: generate medusa-react reference (#6004)

* add new plugin for better organization

* added handling in theme for mutations and query types

* added tsdoc to hooks

* added tsdocs to utility functions

* added tsdoc to providers

* generated reference

* general fixes for generated reference

* generated api reference specs + general fixes

* add missing import react

* split utilities into different directories

* added overview page

* added link to customer authentication section

* fix lint errors

* added changeset

* fix readme

* fixed build error

* added expand fields + other sections to overview

* updated what's new section

* general refactoring

* remove unnecessary query field

* fix links

* added ignoreApi option

packages/medusa-js/src/resources/admin/draft-orders.ts

@@ -87,7 +87,7 @@ class AdminDraftOrdersResource extends BaseResource {
   }
 
   /**
-   * Delete a Draft Order
+   * Delete a Draft Order.
    * @param {string} id - The ID of the draft order.
    * @param {Record<string, any>} customHeaders - Custom headers to attach to the request.
    * @returns {ResponsePromise<AdminDraftOrdersDeleteRes>} Resolves to the deletion operation details.

packages/medusa-js/src/resources/admin/gift-cards.ts

@@ -23,7 +23,7 @@ import BaseResource from "../base"
  */
 class AdminGiftCardsResource extends BaseResource {
   /**
-   * Create a gift card that can redeemed by its unique code. The Gift Card is only valid within `1` region.
+   * Create a gift card that can redeemed by its unique code. The Gift Card is only valid within one region.
    * @param {AdminPostGiftCardsReq} payload - The gift card to be created.
    * @param {Record<string, any>} customHeaders - Custom headers to attach to the request.
    * @returns {ResponsePromise<AdminGiftCardsRes>} Resolves to the gift card's details.

packages/medusa-js/src/resources/admin/inventory-item.ts

@@ -162,15 +162,6 @@ class AdminInventoryItemsResource extends BaseResource {
    * @returns {ResponsePromise<AdminInventoryItemsListWithVariantsAndLocationLevelsRes>} The list of inventory items with pagination fields.
    * 
    * @example
-   * import Medusa from "@medusajs/medusa-js"
-   * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
-   * // must be previously logged in or use api token
-   * medusa.admin.inventoryItems.list()
-   * .then(({ inventory_items, count, offset, limit }) => {
-   *   console.log(inventory_items.length);
-   * })
-   * 
-   * @example
    * To list inventory items:
    * 
    * ```ts

packages/medusa-js/src/resources/admin/orders.ts

@@ -34,7 +34,7 @@ import BaseResource from "../base"
  */
 class AdminOrdersResource extends BaseResource {
   /**
-   * Update and order's details.
+   * Update an order's details.
    * @param {string} id - The order's ID.
    * @param {AdminPostOrdersOrderReq} payload - The attributes to update in the order.
    * @param {Record<string, any>} customHeaders - Custom headers to attach to the request.
@@ -248,7 +248,7 @@ class AdminOrdersResource extends BaseResource {
 
   /**
    * Create a Fulfillment of an Order using the fulfillment provider, and change the order's fulfillment status to either `partially_fulfilled` or `fulfilled`, depending on
- *  whether all the items were fulfilled.
+   * whether all the items were fulfilled.
    * @param {string} id - The ID of the order that the fulfillment belongs to.
    * @param {AdminPostOrdersOrderFulfillmentsReq} payload - The fulfillment to be created.
    * @param {Record<string, any>} customHeaders - Custom headers to attach to the request.
@@ -513,7 +513,7 @@ class AdminOrdersResource extends BaseResource {
    *   ]
    * })
    * .then(({ order }) => {
-   *   console.log(order.id);
+   *   console.log(order.swaps);
    * })
    */
   createSwap(
@@ -642,7 +642,7 @@ class AdminOrdersResource extends BaseResource {
    * @param {string} id - The order's ID.
    * @param {AdminPostOrdersOrderClaimsReq} payload - The claim to be created.
    * @param {Record<string, any>} customHeaders - Custom headers to attach to the request.
-   * @returns {ResponsePromise<AdminOrdersRes>} Resolves to the order's details. You can access the swap under the `claims` property.
+   * @returns {ResponsePromise<AdminOrdersRes>} Resolves to the order's details. You can access the claim under the `claims` property.
    * 
    * @example
    * import Medusa from "@medusajs/medusa-js"
@@ -701,7 +701,7 @@ class AdminOrdersResource extends BaseResource {
    * @param {string} claimId - The claim's ID.
    * @param {AdminPostOrdersOrderClaimsClaimReq} payload - The attributes to update in the claim.
    * @param {Record<string, any>} customHeaders - Custom headers to attach to the request.
-   * @returns {ResponsePromise<AdminOrdersRes>} Resolves to the order's details. You can access the swap under the `claims` property.
+   * @returns {ResponsePromise<AdminOrdersRes>} Resolves to the order's details. You can access the claims under the `claims` property.
    * 
    * @example
    * import Medusa from "@medusajs/medusa-js"

packages/medusa-js/src/resources/admin/payments.ts

@@ -79,16 +79,17 @@ class AdminPaymentsResource extends BaseResource {
    * @returns {ResponsePromise<AdminRefundRes>} Resolves to the refund's details.
    * 
    * @example
+   * import { RefundReason } from "@medusajs/medusa";
    * import Medusa from "@medusajs/medusa-js"
    * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
    * // must be previously logged in or use api token
    * medusa.admin.payments.refundPayment(paymentId, {
    *   amount: 1000,
-   *   reason: "return",
+   *   reason: RefundReason.RETURN,
    *   note: "Do not like it",
    * })
-   * .then(({ payment }) => {
-   *   console.log(payment.id);
+   * .then(({ refund }) => {
+   *   console.log(refund.amount);
    * })
    */
   refundPayment(

packages/medusa-js/src/resources/admin/publishable-api-keys.ts

@@ -33,8 +33,6 @@ class AdminPublishableApiKeyResource extends BaseResource {
   /**
    * Retrieve a publishable API key's details.
    * @param {string} id - The ID of the publishable API key.
-   * @privateRemarks The query parameter serves no purpose, so will leave this without a description until it's removed/fixed.
-   * @param {Record<string, any>} query
    * @param {Record<string, any>} customHeaders - Custom headers to attach to the request.
    * @returns {ResponsePromise<AdminPublishableApiKeysRes>} Resolves to the publishable API key's details.
    *

packages/medusa-js/src/resources/admin/returns.ts

@@ -22,7 +22,7 @@ import BaseResource from "../base"
  */
 class AdminReturnsResource extends BaseResource {
   /**
-   * Registers a return as canceled. The return can be associated with an order, claim, or swap.
+   * Register a return as canceled. The return can be associated with an order, claim, or swap.
    * @param {string} id - The return's ID. 
    * @param {Record<string, any>} customHeaders - Custom headers to attach to the request.
    * @returns {ResponsePromise<AdminReturnsCancelRes>} Resolves to the details of the order associated with the return. If the return is associated with a claim or a swap, then it'll be the order

packages/medusa-js/src/resources/admin/sales-channels.ts

@@ -251,7 +251,9 @@ class AdminSalesChannelsResource extends BaseResource {
   }
 
   /**
-   * Associate a stock location with a sales channel.
+   * Associate a stock location with a sales channel. It requires the 
+   * [@medusajs/stock-location](https://docs.medusajs.com/modules/multiwarehouse/install-modules#stock-location-module) module to be installed in
+   * your Medusa backend.
    * @param {string} salesChannelId - The sales channel's ID. 
    * @param {AdminPostSalesChannelsChannelStockLocationsReq} payload - The stock location to associate with the sales channel.
    * @param {Record<string, any>} customHeaders - Custom headers to attach to the request.

packages/medusa-js/src/resources/admin/shipping-profiles.ts

@@ -27,11 +27,13 @@ class AdminShippingProfilesResource extends BaseResource {
    * @returns {ResponsePromise<AdminShippingProfilesRes>} Resolves to the shipping profile's details.
    * 
    * @example
+   * import { ShippingProfileType } from "@medusajs/medusa"
    * import Medusa from "@medusajs/medusa-js"
    * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
    * // must be previously logged in or use api token
    * medusa.admin.shippingProfiles.create({
-   *   name: "Large Products"
+   *   name: "Large Products",
+   *   type: ShippingProfileType.DEFAULT
    * })
    * .then(({ shipping_profile }) => {
    *   console.log(shipping_profile.id);

packages/medusa-js/src/resources/admin/tax-rates.ts

@@ -110,7 +110,7 @@ class AdminTaxRatesResource extends BaseResource {
    * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
    * // must be previously logged in or use api token
    * medusa.admin.taxRates.list({
-   *   expand: "shipping_options"
+   *   expand: ["shipping_options"]
    * })
    * .then(({ tax_rates, limit, offset, count }) => {
    *   console.log(tax_rates.length);
@@ -124,7 +124,7 @@ class AdminTaxRatesResource extends BaseResource {
    * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
    * // must be previously logged in or use api token
    * medusa.admin.taxRates.list({
-   *   expand: "shipping_options",
+   *   expand: ["shipping_options"],
    *   limit,
    *   offset
    * })

packages/medusa-js/src/resources/admin/uploads.ts

@@ -28,8 +28,8 @@ class AdminUploadsResource extends BaseResource {
   }
 
   /**
-   * Upload a file to a public bucket or storage. The file upload is handled by the file service installed on the Medusa backend.
-   * @param {AdminCreateUploadPayload} file - The file to upload.
+   * Upload a file or multiple files to a public bucket or storage. The file upload is handled by the file service installed on the Medusa backend.
+   * @param {AdminCreateUploadPayload} file - The file(s) to upload.
    * @returns {ResponsePromise<AdminUploadsRes>} Resolves to the uploaded file details.
    * 
    * @example

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

@@ -66,8 +66,8 @@ class CartsResource extends BaseResource {
    * import Medusa from "@medusajs/medusa-js"
    * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
    * medusa.carts.complete(cartId)
-   * .then(({ cart }) => {
-   *   console.log(cart.id);
+   * .then(({ data, type }) => {
+   *   console.log(data.id, type);
    * })
    */
   complete(

packages/medusa-js/src/resources/line-items.ts

@@ -12,7 +12,7 @@ import BaseResource from "./base"
  */
 class LineItemsResource extends BaseResource {
   /**
-   * Generates a Line Item with a given Product Variant and adds it to the Cart
+   * Generate a Line Item with a given Product Variant and adds it to the Cart
    * @param {string} cart_id - The cart's ID.
    * @param {StorePostCartsCartLineItemsReq} payload - The line item to be created.
    * @param {Record<string, any>} customHeaders - Custom headers to attach to the request.

packages/medusa-js/src/resources/order-edits.ts

@@ -62,7 +62,7 @@ class OrderEditsResource extends BaseResource {
   }
 
   /**
-   * Complete an Order Edit and reflect its changes on the original order. Any additional payment required must be authorized first using the {@link PaymentCollectionsResource} routes.
+   * Complete and confirm an Order Edit and reflect its changes on the original order. Any additional payment required must be authorized first using the {@link PaymentCollectionsResource} routes.
    * @param {string} id - The ID of the order edit.
    * @param {Record<string, any>} customHeaders - Custom headers to attach to the request.
    * @returns {ResponsePromise<StoreOrderEditsRes>} Resolves to the order edit's details.

packages/medusa-js/src/resources/payment-collections.ts

@@ -103,7 +103,9 @@ class PaymentCollectionsResource extends BaseResource {
    * import Medusa from "@medusajs/medusa-js"
    * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
    * // must be previously logged in or use api token
-   * medusa.paymentCollections.authorize(paymentId)
+   * medusa.paymentCollections.authorizePaymentSessionsBatch(paymentCollectionId, {
+   *  session_ids: ["ps_123456"]
+   * })
    * .then(({ payment_collection }) => {
    *   console.log(payment_collection.id);
    * })
@@ -131,7 +133,7 @@ class PaymentCollectionsResource extends BaseResource {
    * import Medusa from "@medusajs/medusa-js"
    * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
    * // must be previously logged in or use api token
- *
+   *
    * // Total amount = 10000
    * medusa.paymentCollections.managePaymentSessionsBatch(paymentId, {
    *   sessions: [
@@ -213,7 +215,7 @@ class PaymentCollectionsResource extends BaseResource {
    * const medusa = new Medusa({ baseUrl: MEDUSA_BACKEND_URL, maxRetries: 3 })
    * medusa.paymentCollections.refreshPaymentSession(paymentCollectionId, sessionId)
    * .then(({ payment_session }) => {
-   *   console.log(payment_session.id);
+   *   console.log(payment_session.status);
    * })
    */
   refreshPaymentSession(

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

@@ -77,7 +77,7 @@ class ProductsResource extends BaseResource {
   }
 
   /**
-   * Retrieves a list of products. The products can be filtered by fields such as `id` or `q` passed in the `query` parameter. The products can also be sorted or paginated.
+   * Retrieve a list of products. The products can be filtered by fields such as `id` or `q` passed in the `query` parameter. The products can also be sorted or paginated.
    * This method can also be used to retrieve a product by its handle.
    * 
    * For accurate and correct pricing of the products based on the customer's context, it's highly recommended to pass fields such as

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

@@ -9,7 +9,7 @@ import BaseResource from "./base"
  * Regions are different countries or geographical regions that the commerce store serves customers in.
  * Customers can choose what region they're in, which can be used to change the prices shown based on the region and its currency.
  * 
- * Related Guide: [How to use regions in a storefront](https://docs.medusajs.com/modules/regions-and-currencies/storefront/use-regions)
+ * Related Guide: [How to use regions in a storefront](https://docs.medusajs.com/modules/regions-and-currencies/storefront/use-regions).
  */
 class RegionsResource extends BaseResource {
   /**

packages/medusa-js/src/typings.ts

@@ -27,7 +27,9 @@ type CreateUserRolesEnum = NoUndefined<AdminCreateUserRequest["role"]>
 // convert Enum type to union of string literals
 export type CreateUserRoles = `${CreateUserRolesEnum}`
 
-// remove enum type and replace with union type
+/**
+ * The details of the user to create.
+ */
 export type AdminCreateUserPayload =
   | Omit<AdminCreateUserRequest, "role">
   | {
@@ -38,6 +40,9 @@ type UpdateUserRolesEnum = NoUndefined<AdminUpdateUserRequest["role"]>
 
 export type UpdateUserRoles = `${UpdateUserRolesEnum}`
 
+/**
+ * The details to update of the user.
+ */
 export type AdminUpdateUserPayload = Omit<AdminUpdateUserRequest, "role"> & {
   role?: UpdateUserRoles
 }
@@ -48,4 +53,7 @@ export type AdminPostInvitesPayload = Omit<AdminPostInvitesReq, "role"> & {
   role: InviteUserRolesEnum
 }
 
+/**
+ * The file(s) to upload.
+ */
 export type AdminCreateUploadPayload = File | File[]