chore(js-sdk,types): add tsdocs for admin JS SDK methods [4/n] (#9745)

Add TSDocs to admin JS SDK from notification to payment

[4/n]

packages/core/js-sdk/src/admin/notification.ts

@@ -14,6 +14,39 @@ export class Notification {
     this.client = client
   }
 
+  /**
+   * This method retrieves a notification's details. It sends a request to the 
+   * [Get Notification](https://docs.medusajs.com/api/admin#notifications_getnotificationsid)
+   * API route.
+   * 
+   * @param id - The notification's ID.
+   * @param query - Configure the fields to retrieve in the notification.
+   * @param headers - Headers to pass in the request
+   * @returns The notification's details.
+   * 
+   * @example
+   * To retrieve a notification by its ID:
+   * 
+   * ```ts
+   * sdk.admin.notification.retrieve("notif_123")
+   * .then(({ notification }) => {
+   *   console.log(notification)
+   * })
+   * ```
+   * 
+   * To specify the fields and relations to retrieve:
+   * 
+   * ```ts
+   * sdk.admin.notification.retrieve("notif_123", {
+   *   fields: "id,to"
+   * })
+   * .then(({ notification }) => {
+   *   console.log(notification)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async retrieve(
     id: string,
     query?: HttpTypes.AdminNotificationParams,
@@ -29,6 +62,53 @@ export class Notification {
     )
   }
 
+  /**
+   * This method retrieves a paginated list of notifications. It sends a request to the 
+   * [List Notifications](https://docs.medusajs.com/api/admin#notifications_getnotifications)
+   * API route.
+   * 
+   * @param query - Filters and pagination configurations.
+   * @param headers - Headers to pass in the request.
+   * @returns The paginated list of notifications.
+   * 
+   * @example
+   * To retrieve the list of notifications:
+   * 
+   * ```ts
+   * sdk.admin.notification.list()
+   * .then(({ notifications, count, limit, offset }) => {
+   *   console.log(notifications)
+   * })
+   * ```
+   * 
+   * To configure the pagination, pass the `limit` and `offset` query parameters.
+   * 
+   * For example, to retrieve only 10 items and skip 10 items:
+   * 
+   * ```ts
+   * sdk.admin.notification.list({
+   *   limit: 10,
+   *   offset: 10
+   * })
+   * .then(({ notifications, count, limit, offset }) => {
+   *   console.log(notifications)
+   * })
+   * ```
+   * 
+   * Using the `fields` query parameter, you can specify the fields and relations to retrieve
+   * in each notification:
+   * 
+   * ```ts
+   * sdk.admin.notification.list({
+   *   fields: "id,to"
+   * })
+   * .then(({ notifications, count, limit, offset }) => {
+   *   console.log(notifications)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async list(
     query?: HttpTypes.AdminNotificationListParams,
     headers?: ClientHeaders

packages/core/js-sdk/src/admin/order-edit.ts

@@ -14,12 +14,30 @@ export class OrderEdit {
     this.client = client
   }
 
+  /**
+   * This method creates an order edit request. It sends a HTTP request to the
+   * [Create Order Edit](https://docs.medusajs.com/api/admin#order-edits_postorderedits)
+   * API route.
+   * 
+   * @param body - The order edit's details.
+   * @param query - Configure the fields to retrieve in the order edit.
+   * @param headers - Headers to pass in the request.
+   * @returns The order edit's details.
+   * 
+   * @example
+   * sdk.admin.orderEdit.initiateRequest({
+   *   order_id: "order_123"
+   * })
+   * .then(({ order_change }) => {
+   *   console.log(order_change)
+   * })
+   */
   async initiateRequest(
     body: HttpTypes.AdminInitiateOrderEditRequest,
     query?: HttpTypes.SelectParams,
     headers?: ClientHeaders
   ) {
-    return await this.client.fetch<HttpTypes.AdminOrderEditPreviewResponse>(
+    return await this.client.fetch<HttpTypes.AdminOrderEditResponse>(
       `/admin/order-edits`,
       {
         method: "POST",
@@ -30,6 +48,22 @@ export class OrderEdit {
     )
   }
 
+  /**
+   * This method changes an order edit to requested. It sends a request to the
+   * [Request Order Edit](https://docs.medusajs.com/api/admin#order-edits_postordereditsidrequest)
+   * API route.
+   * 
+   * @param id - The order edit's ID.
+   * @param query - Configure the fields to retrieve in the order preview.
+   * @param headers - Headers to pass in the request.
+   * @returns The order preview's details.
+   * 
+   * @example
+   * sdk.admin.orderEdit.request("ordch_123")
+   * .then(({ order_preview }) => {
+   *   console.log(order_preview)
+   * })
+   */
   async request(
     id: string,
     query?: HttpTypes.SelectParams,
@@ -45,6 +79,22 @@ export class OrderEdit {
     )
   }
 
+  /**
+   * This method confirms an order edit and applies it on the order. It sends a request
+   * to the [Confirm Order Edit](https://docs.medusajs.com/api/admin#order-edits_postordereditsidconfirm)
+   * API route.
+   * 
+   * @param id - The order edit's ID.
+   * @param query - Configure the fields to retrieve in the order preview.
+   * @param headers - Headers to pass in the request.
+   * @returns The order preview's details.
+   * 
+   * @example
+   * sdk.admin.orderEdit.confirm("ordch_123")
+   * .then(({ order_preview }) => {
+   *   console.log(order_preview)
+   * })
+   */
   async confirm(
     id: string,
     query?: HttpTypes.SelectParams,
@@ -60,6 +110,22 @@ export class OrderEdit {
     )
   }
 
+  /**
+   * This method cancels a requested order edit. It sends a request to the
+   * [Cancel Order Edit](https://docs.medusajs.com/api/admin#order-edits_deleteordereditsid)
+   * API route.
+   * 
+   * @param id - The order edit's ID.
+   * @param query - Query parameters
+   * @param headers - Headers to pass in the request.
+   * @returns The deletion's details.
+   * 
+   * @example
+   * sdk.admin.orderEdit.cancelRequest("ordch_123")
+   * .then(({ deleted }) => {
+   *   console.log(deleted)
+   * })
+   */
   async cancelRequest(
     id: string,
     query?: HttpTypes.SelectParams,
@@ -75,6 +141,31 @@ export class OrderEdit {
     )
   }
 
+  /**
+   * This method adds items to an order edit. These items will have the action `ITEM_ADD`.
+   * 
+   * The method sends a request to the [Add Items](https://docs.medusajs.com/api/admin#order-edits_postordereditsiditems)
+   * API route.
+   * 
+   * @param id - The order edit's ID.
+   * @param body - The items to add.
+   * @param query - Configure the fields to retrieve in the order preview.
+   * @param headers - Headers to pass in the request.
+   * @returns The order preview's details.
+   * 
+   * @example
+   * sdk.admin.orderEdit.addItems("ordch_123", {
+   *   items: [
+   *     {
+   *       variant_id: "variant_123",
+   *       quantity: 1
+   *     }
+   *   ]
+   * })
+   * .then(({ order_preview }) => {
+   *   console.log(order_preview)
+   * })
+   */
   async addItems(
     id: string,
     body: HttpTypes.AdminAddOrderEditItems,
@@ -92,6 +183,30 @@ export class OrderEdit {
     )
   }
 
+  /**
+   * This method updates the quantity and other details of an item in an order. It sends a request to the
+   * [Update Item Quantity](https://docs.medusajs.com/api/admin#order-edits_postordereditsiditemsitemitem_id)
+   * API route.
+   * 
+   * @param id - The order edit's ID.
+   * @param itemId - The item's ID in the order.
+   * @param body - The data to edit in the item.
+   * @param query - Configure the fields to retrieve in the order preview.
+   * @param headers - Headers to pass in the request.
+   * @returns The order preview's details.
+   * 
+   * @example
+   * sdk.admin.orderEdit.updateOriginalItem(
+   *   "ordch_123", 
+   *   "orli_123",
+   *   {
+   *     quantity: 1
+   *   }
+   * )
+   * .then(({ order_preview }) => {
+   *   console.log(order_preview)
+   * })
+   */
   async updateOriginalItem(
     id: string,
     itemId: string,
@@ -110,6 +225,35 @@ export class OrderEdit {
     )
   }
 
+  /**
+   * This method updates an added item in the order edit by the ID of the item's `ITEM_ADD` action.
+   * 
+   * Every item has an `actions` property, whose value is an array of actions. 
+   * You can check the action's name using its `action` property, and use the value of the `id` property.
+   * 
+   * It sends a request
+   * to the [Update Item](https://docs.medusajs.com/api/admin#order-edits_postordereditsiditemsaction_id)
+   * API route.
+   * 
+   * @param id - The order edit's ID.
+   * @param actionId - The id of the new item's `ITEM_ADD` action.
+   * @param body - The data to update.
+   * @param query - Configure the fields to retrieve in the order preview.
+   * @param headers - Headers to pass in the request.
+   * @returns The order preview's details.
+   * 
+   * @example
+   * sdk.admin.orderEdit.updateAddedItem(
+   *   "ordch_123", 
+   *   "orli_123",
+   *   {
+   *     quantity: 1
+   *   }
+   * )
+   * .then(({ order_preview }) => {
+   *   console.log(order_preview)
+   * })
+   */
   async updateAddedItem(
     id: string,
     actionId: string,
@@ -128,6 +272,27 @@ export class OrderEdit {
     )
   }
 
+  /**
+   * This method removes an added item in the order edit by the ID of the item's `ITEM_ADD` action.
+   * 
+   * Every item has an `actions` property, whose value is an array of actions. 
+   * You can check the action's name using its `action` property, and use the value of the `id` property.
+   * 
+   * @param id - The order edit's ID.
+   * @param actionId - The id of the new item's `ITEM_ADD` action.
+   * @param query - Configure the fields to retrieve in the order preview.
+   * @param headers - Headers to pass in the request.
+   * @returns The order preview's details.
+   * 
+   * @example
+   * sdk.admin.orderEdit.removeAddedItem(
+   *   "ordch_123", 
+   *   "orli_123",
+   * )
+   * .then(({ order_preview }) => {
+   *   console.log(order_preview)
+   * })
+   */
   async removeAddedItem(
     id: string,
     actionId: string,

packages/core/js-sdk/src/admin/order.ts

@@ -21,8 +21,41 @@ export class Order {
     this.client = client
   }
 
+  /**
+   * This method retrieves an order by its ID. It sends a request to the 
+   * [Get Order](https://docs.medusajs.com/api/admin#orders_getordersid)
+   * API route.
+   * 
+   * @param id - The order's ID.
+   * @param query - Configure the fields to retrieve in the order.
+   * @param headers - Headers to pass in the request
+   * @returns The order's details.
+   * 
+   * @example
+   * To retrieve an order by its ID:
+   * 
+   * ```ts
+   * sdk.admin.order.retrieve("order_123")
+   * .then(({ order }) => {
+   *   console.log(order)
+   * })
+   * ```
+   * 
+   * To specify the fields and relations to retrieve:
+   * 
+   * ```ts
+   * sdk.admin.order.retrieve("order_123", {
+   *   fields: "id,*items"
+   * })
+   * .then(({ order }) => {
+   *   console.log(order)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async retrieve(id: string, query?: SelectParams, headers?: ClientHeaders) {
-    return await this.client.fetch<{ order: HttpTypes.AdminOrder }>(
+    return await this.client.fetch<HttpTypes.AdminOrderResponse>(
       `/admin/orders/${id}`,
       {
         query,
@@ -31,6 +64,21 @@ export class Order {
     )
   }
 
+  /**
+   * This method retrieves the preview of an order based on its last associated change. It sends a request to the 
+   * [Get Order Preview](https://docs.medusajs.com/api/admin#orders_getordersidpreview) API route.
+   * 
+   * @param id - The order's ID.
+   * @param query - Query parameters.
+   * @param headers - Headers to pass in the request
+   * @returns The order preview's details.
+   * 
+   * @example
+   * sdk.admin.order.retrievePreview("order_123")
+   * .then(({ order }) => {
+   *   console.log(order)
+   * })
+   */
   async retrievePreview(
     id: string,
     query?: HttpTypes.AdminOrderFilters,
@@ -45,20 +93,81 @@ export class Order {
     )
   }
 
+  /**
+   * This method retrieves a paginated list of orders. It sends a request to the 
+   * [List Orders](https://docs.medusajs.com/api/admin#orders_getorders) API route.
+   * 
+   * @param queryParams - Filters and pagination configurations.
+   * @param headers - Headers to pass in the request.
+   * @returns The paginated list of orders.
+   * 
+   * @example
+   * To retrieve the list of orders:
+   * 
+   * ```ts
+   * sdk.admin.order.list()
+   * .then(({ orders, count, limit, offset }) => {
+   *   console.log(orders)
+   * })
+   * ```
+   * 
+   * To configure the pagination, pass the `limit` and `offset` query parameters.
+   * 
+   * For example, to retrieve only 10 items and skip 10 items:
+   * 
+   * ```ts
+   * sdk.admin.order.list({
+   *   limit: 10,
+   *   offset: 10
+   * })
+   * .then(({ orders, count, limit, offset }) => {
+   *   console.log(orders)
+   * })
+   * ```
+   * 
+   * Using the `fields` query parameter, you can specify the fields and relations to retrieve
+   * in each order:
+   * 
+   * ```ts
+   * sdk.admin.order.list({
+   *   fields: "id,*items"
+   * })
+   * .then(({ orders, count, limit, offset }) => {
+   *   console.log(orders)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async list(
-    queryParams?: FindParams & HttpTypes.AdminOrderFilters,
+    queryParams?: HttpTypes.AdminOrderFilters,
     headers?: ClientHeaders
   ) {
     return await this.client.fetch<
-      PaginatedResponse<{ orders: HttpTypes.AdminOrder[] }>
+      HttpTypes.AdminOrderListResponse
     >(`/admin/orders`, {
       query: queryParams,
       headers,
     })
   }
 
+  /**
+   * This method cancels an order. It sends a request to the
+   * [Cancel Order](https://docs.medusajs.com/api/admin#orders_postordersidcancel)
+   * API route.
+   * 
+   * @param id - The order's ID.
+   * @param headers - Headers to pass in the request.
+   * @returns The order's details.
+   * 
+   * @example
+   * sdk.admin.order.cancel("order_123")
+   * .then(({ order }) => {
+   *   console.log(order)
+   * })
+   */
   async cancel(id: string, headers?: ClientHeaders) {
-    return await this.client.fetch<{ order: HttpTypes.AdminOrder }>(
+    return await this.client.fetch<HttpTypes.AdminOrderResponse>(
       `/admin/orders/${id}/cancel`,
       {
         method: "POST",
@@ -67,13 +176,37 @@ export class Order {
     )
   }
 
+  /**
+   * This method creates a fulfillment for an order. It sends a request to the
+   * [Create Fulfillment](https://docs.medusajs.com/api/admin#orders_postordersidfulfillments)
+   * API route.
+   * 
+   * @param id - The order's ID.
+   * @param body - The fulfillment's details.
+   * @param query - Configure the fields to retrieve in the order.
+   * @param headers - Headers to pass in the request
+   * @returns The order's details.
+   * 
+   * @example
+   * sdk.admin.order.createFulfillment("order_123", {
+   *   items: [
+   *     {
+   *       id: "orli_123",
+   *       quantity: 1
+   *     }
+   *   ]
+   * })
+   * .then(({ order }) => {
+   *   console.log(order)
+   * })
+   */
   async createFulfillment(
     id: string,
     body: HttpTypes.AdminCreateOrderFulfillment,
     query?: SelectParams,
     headers?: ClientHeaders
   ) {
-    return await this.client.fetch<{ order: HttpTypes.AdminOrder }>(
+    return await this.client.fetch<HttpTypes.AdminOrderResponse>(
       `/admin/orders/${id}/fulfillments`,
       {
         method: "POST",
@@ -84,13 +217,36 @@ export class Order {
     )
   }
 
+  /**
+   * This method cancels an order's fulfillment. It sends a request to the
+   * [Cancel Fulfillment](https://docs.medusajs.com/api/admin#orders_postordersidfulfillmentsfulfillment_idcancel)
+   * API route.
+   * 
+   * @param id - The order's ID.
+   * @param fulfillmentId - The ID of the fulfillment to cancel.
+   * @param body - The cancelation's details.
+   * @param headers - Headers to pass in the request
+   * @returns The order's details.
+   * 
+   * @example
+   * sdk.admin.order.cancelFulfillment(
+   *   "order_123",
+   *   "ful_123",
+   *   {
+   *     no_notification: false
+   *   }
+   * )
+   * .then(({ order }) => {
+   *   console.log(order)
+   * })
+   */
   async cancelFulfillment(
     id: string,
     fulfillmentId: string,
     body: HttpTypes.AdminCancelOrderFulfillment,
     headers?: ClientHeaders
   ) {
-    return await this.client.fetch<{ order: HttpTypes.AdminOrder }>(
+    return await this.client.fetch<HttpTypes.AdminOrderResponse>(
       `/admin/orders/${id}/fulfillments/${fulfillmentId}/cancel`,
       {
         method: "POST",
@@ -100,6 +256,35 @@ export class Order {
     )
   }
 
+  /**
+   * This method creates a shipment for an order's fulfillment. It sends a request to the
+   * [Create Shipment](https://docs.medusajs.com/api/admin#orders_postordersidfulfillmentsfulfillment_idshipments)
+   * API route.
+   * 
+   * @param id - The order's ID.
+   * @param fulfillmentId - The ID of the fulfillment.
+   * @param body - The shipment's details.
+   * @param query - Configure the fields to retrieve in the order.
+   * @param headers - Headers to pass in the request
+   * @returns The order's details.
+   * 
+   * @example
+   * sdk.admin.order.createShipment(
+   *   "order_123",
+   *   "ful_123",
+   *   {
+   *     items: [
+   *       {
+   *         id: "fulit_123",
+   *         quantity: 1
+   *       }
+   *     ]
+   *   }
+   * )
+   * .then(({ order }) => {
+   *   console.log(order)
+   * })
+   */
   async createShipment(
     id: string,
     fulfillmentId: string,
@@ -107,7 +292,7 @@ export class Order {
     query?: SelectParams,
     headers?: ClientHeaders
   ) {
-    return await this.client.fetch<{ order: HttpTypes.AdminOrder }>(
+    return await this.client.fetch<HttpTypes.AdminOrderResponse>(
       `/admin/orders/${id}/fulfillments/${fulfillmentId}/shipments`,
       {
         method: "POST",
@@ -118,6 +303,28 @@ export class Order {
     )
   }
 
+  /**
+   * This method marks an order's fulfillment as delivered. It sends a request to the
+   * [Mark Delivered ](https://docs.medusajs.com/api/admin#orders_postordersidfulfillmentsfulfillment_idmarkasdelivered)
+   * API route.
+   * 
+   * @param id - The order's ID.
+   * @param fulfillmentId - The fulfillment's ID.
+   * @param body - The delivery details.
+   * @param query - Configure the fields to retrieve in the order.
+   * @param headers - Headers to pass in the request
+   * @returns The order's details.
+   * 
+   * @example
+   * sdk.admin.order.markAsDelivered(
+   *   "order_123",
+   *   "ful_123",
+   *   {}
+   * )
+   * .then(({ order }) => {
+   *   console.log(order)
+   * })
+   */
   async markAsDelivered(
     id: string,
     fulfillmentId: string,
@@ -125,7 +332,7 @@ export class Order {
     query?: SelectParams,
     headers?: ClientHeaders
   ) {
-    return await this.client.fetch<{ order: HttpTypes.AdminOrder }>(
+    return await this.client.fetch<HttpTypes.AdminOrderResponse>(
       `/admin/orders/${id}/fulfillments/${fulfillmentId}/mark-as-delivered`,
       {
         method: "POST",
@@ -136,6 +343,23 @@ export class Order {
     )
   }
 
+  /**
+   * This method retrieves a list of changes made on an order, including returns, exchanges, etc...
+   * 
+   * This method sends a request to the [List Changes](https://docs.medusajs.com/api/admin#orders_getordersidchanges)
+   * API route.
+   * 
+   * @param id - The order's ID.
+   * @param queryParams - Configure the fields to retrieve in each order change.
+   * @param headers - Headers to pass in the request
+   * @returns The list of order changes.
+   * 
+   * @example
+   * sdk.admin.order.listChanges("order_123")
+   * .then(({ order_changes }) => {
+   *   console.log(order_changes)
+   * })
+   */
   async listChanges(
     id: string,
     queryParams?: FindParams & HttpTypes.AdminOrderChangesFilters,
@@ -149,13 +373,29 @@ export class Order {
     })
   }
 
+  /**
+   * This method retrieves the order's line items. It sends a request to the
+   * [List Line Items](https://docs.medusajs.com/api/admin#orders_getordersidlineitems)
+   * API routes.
+   * 
+   * @param id - The order's ID.
+   * @param queryParams - Configure the fields to retrieve in each line item.
+   * @param headers - Headers to pass in the request
+   * @returns The list of line items.
+   * 
+   * @example
+   * sdk.admin.order.listLineItems("order_123")
+   * .then(({ order_items }) => {
+   *   console.log(order_items)
+   * })
+   */
   async listLineItems(
     id: string,
     queryParams?: FindParams & HttpTypes.AdminOrderItemsFilters,
     headers?: ClientHeaders
   ) {
     return await this.client.fetch<
-      PaginatedResponse<HttpTypes.AdminOrderLineItemsListResponse>
+      HttpTypes.AdminOrderLineItemsListResponse
     >(`/admin/orders/${id}/line-items`, {
       query: queryParams,
       headers,

packages/core/js-sdk/src/admin/payment-collection.ts

@@ -14,6 +14,24 @@ export class PaymentCollection {
     this.client = client
   }
 
+  /**
+   * This method creates a payment collection. It sends a request to the
+   * [Create Payment Collection](https://docs.medusajs.com/api/admin#payment-collections_postpaymentcollections)
+   * API route.
+   * 
+   * @param body - The details of the payment collection to create.
+   * @param query - Configure the fields to retrieve in the payment collection.
+   * @param headers - Headers to pass in the request
+   * @returns The payment collection's details.
+   * 
+   * @example
+   * sdk.admin.paymentCollection.create({
+   *   order_id: "order_123"
+   * })
+   * .then(({ payment_collection }) => {
+   *   console.log(payment_collection)
+   * })
+   */
   async create(
     body: HttpTypes.AdminCreatePaymentCollection,
     query?: SelectParams,
@@ -30,6 +48,21 @@ export class PaymentCollection {
     )
   }
 
+  /**
+   * This method deletes a payment collection. It sends a request to the
+   * [Delete Payment Collection](https://docs.medusajs.com/api/admin#payment-collections_deletepaymentcollectionsid)
+   * API route.
+   * 
+   * @param id - The payment collection's ID.
+   * @param headers - Headers to pass in the request
+   * @returns The deletion's details.
+   * 
+   * @example
+   * sdk.admin.paymentCollection.delete("paycol_123")
+   * .then(({ deleted }) => {
+   *   console.log(deleted)
+   * })
+   */
   async delete(id: string, headers?: ClientHeaders) {
     return await this.client.fetch<HttpTypes.AdminDeletePaymentCollectionResponse>(
       `/admin/payment-collections/${id}`,
@@ -40,6 +73,28 @@ export class PaymentCollection {
     )
   }
 
+  /**
+   * This method marks a payment collection as paid. It sends a request to the 
+   * [Mark as Paid](https://docs.medusajs.com/api/admin#payment-collections_postpaymentcollectionsidmarkaspaid)
+   * API route.
+   * 
+   * The API route creates and authorizes a payment session, then capture its payment, 
+   * using the manual payment provider.
+   * 
+   * @param id - The payment collection to mark as paid.
+   * @param body - The details to mark the payment collection as paid.
+   * @param query - Configure the fields to retrieve in the payment collection.
+   * @param headers - Headers to pass in the request.
+   * @returns The payment collection's details.
+   * 
+   * @example
+   * sdk.admin.paymentCollection.markAsPaid("paycol_123", {
+   *   order_id: "order_123"
+   * })
+   * .then(({ payment_collection }) => {
+   *   console.log(payment_collection)
+   * })
+   */
   async markAsPaid(
     id: string,
     body: HttpTypes.AdminMarkPaymentCollectionAsPaid,

packages/core/js-sdk/src/admin/payment.ts

@@ -14,6 +14,52 @@ export class Payment {
     this.client = client
   }
 
+  /**
+   * This method retrieves a paginated list of payments. It sends a request to the 
+   * [List Payments](https://docs.medusajs.com/api/admin#payments_getpayments) API route.
+   * 
+   * @param query  - Filters and pagination configurations.
+   * @param headers - Headers to pass in the request.
+   * @returns The paginated list of payments.
+   * 
+   * @example
+   * To retrieve the list of payments:
+   * 
+   * ```ts
+   * sdk.admin.payment.list()
+   * .then(({ payments, count, limit, offset }) => {
+   *   console.log(payments)
+   * })
+   * ```
+   * 
+   * To configure the pagination, pass the `limit` and `offset` query parameters.
+   * 
+   * For example, to retrieve only 10 items and skip 10 items:
+   * 
+   * ```ts
+   * sdk.admin.payment.list({
+   *   limit: 10,
+   *   offset: 10
+   * })
+   * .then(({ payments, count, limit, offset }) => {
+   *   console.log(payments)
+   * })
+   * ```
+   * 
+   * Using the `fields` query parameter, you can specify the fields and relations to retrieve
+   * in each payment:
+   * 
+   * ```ts
+   * sdk.admin.payment.list({
+   *   fields: "id,*payment_collection"
+   * })
+   * .then(({ payments, count, limit, offset }) => {
+   *   console.log(payments)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async list(query?: HttpTypes.AdminPaymentFilters, headers?: ClientHeaders) {
     return await this.client.fetch<HttpTypes.AdminPaymentsResponse>(
       `/admin/payments`,
@@ -24,6 +70,52 @@ export class Payment {
     )
   }
 
+  /**
+   * This method retrieves a paginated list of payment providers. It sends a request to the 
+   * [List Payment Providers](https://docs.medusajs.com/api/admin#payments_getpaymentspaymentproviders) API route.
+   * 
+   * @param query - Filters and pagination configurations.
+   * @param headers - Headers to pass in the request.
+   * @returns The paginated list of payment providers.
+   * 
+   * @example
+   * To retrieve the list of payment providers:
+   * 
+   * ```ts
+   * sdk.admin.payment.listPaymentProviders()
+   * .then(({ payment_providers, count, limit, offset }) => {
+   *   console.log(payment_providers)
+   * })
+   * ```
+   * 
+   * To configure the pagination, pass the `limit` and `offset` query parameters.
+   * 
+   * For example, to retrieve only 10 items and skip 10 items:
+   * 
+   * ```ts
+   * sdk.admin.payment.listPaymentProviders({
+   *   limit: 10,
+   *   offset: 10
+   * })
+   * .then(({ payment_providers, count, limit, offset }) => {
+   *   console.log(payment_providers)
+   * })
+   * ```
+   * 
+   * Using the `fields` query parameter, you can specify the fields and relations to retrieve
+   * in each payment provider:
+   * 
+   * ```ts
+   * sdk.admin.payment.listPaymentProviders({
+   *   fields: "id,is_enabled"
+   * })
+   * .then(({ payment_providers, count, limit, offset }) => {
+   *   console.log(payment_providers)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async listPaymentProviders(
     query?: HttpTypes.AdminGetPaymentProvidersParams,
     headers?: ClientHeaders
@@ -37,9 +129,42 @@ export class Payment {
     )
   }
 
+  /**
+   * This method retrieves a payment's details. It sends a request to the 
+   * [Get Payment](https://docs.medusajs.com/api/admin#payments_getpaymentsid)
+   * API route.
+   * 
+   * @param id - The payment's ID.
+   * @param query - Configure the fields to retrieve in the payment.
+   * @param headers - Headers to pass in the request
+   * @returns The payment's details.
+   * 
+   * @example
+   * To retrieve a payment by its ID:
+   * 
+   * ```ts
+   * sdk.admin.payment.retrieve("pay_123")
+   * .then(({ payment }) => {
+   *   console.log(payment)
+   * })
+   * ```
+   * 
+   * To specify the fields and relations to retrieve:
+   * 
+   * ```ts
+   * sdk.admin.payment.retrieve("pay_123", {
+   *   fields: "id,*payment_collection"
+   * })
+   * .then(({ payment }) => {
+   *   console.log(payment)
+   * })
+   * ```
+   * 
+   * Learn more about the `fields` property in the [API reference](https://docs.medusajs.com/api/store#select-fields-and-relations).
+   */
   async retrieve(
     id: string,
-    query?: HttpTypes.AdminPaymentFilters,
+    query?: SelectParams,
     headers?: ClientHeaders
   ) {
     return await this.client.fetch<HttpTypes.AdminPaymentResponse>(
@@ -51,6 +176,24 @@ export class Payment {
     )
   }
 
+  /**
+   * This method captures a payment. It sends a request to the
+   * [Capture Payment](https://docs.medusajs.com/api/admin#payments_postpaymentsidcapture) API route.
+   * 
+   * The API route uses the `capturePayment` method of the payment provider associated with the payment's collection.
+   * 
+   * @param id - The payment's ID.
+   * @param body - The capture's details.
+   * @param query - Configure the fields to retrieve in the payment.
+   * @param headers - Headers to pass in the request
+   * @returns The payment's details.
+   * 
+   * @example
+   * sdk.admin.payment.capture("paycol_123", {})
+   * .then(({ payment }) => {
+   *   console.log(payment)
+   * })
+   */
   async capture(
     id: string,
     body: HttpTypes.AdminCapturePayment,
@@ -68,6 +211,24 @@ export class Payment {
     )
   }
 
+  /**
+   * This method refunds a payment. It sends a request to the
+   * [Refund Payment](https://docs.medusajs.com/api/admin#payments_postpaymentsidrefund) API route.
+   * 
+   * The API route uses the `refundPayment` method of the payment provider associated with the payment's collection.
+   * 
+   * @param id - The payment's ID.
+   * @param body - The refund's details.
+   * @param query - Configure the fields to retrieve in the payment.
+   * @param headers - Headers to pass in the request
+   * @returns The payment's details.
+   * 
+   * @example
+   * sdk.admin.payment.refund("paycol_123", {})
+   * .then(({ payment }) => {
+   *   console.log(payment)
+   * })
+   */
   async refund(
     id: string,
     body: HttpTypes.AdminRefundPayment,

packages/core/types/src/http/notification/admin/entities.ts

@@ -1,15 +1,67 @@
 export interface AdminNotification {
+  /**
+   * The notification's ID.
+   */
   id: string
+  /**
+   * The identifier the notification is sent to.
+   * For example, an email, phone number, or username.
+   */
   to: string
+  /**
+   * The channel to send the notification through.
+   * 
+   * @example
+   * email
+   */
   channel: string
+  /**
+   * A template ID to use for the notification's content.
+   * 
+   * For example, the ID of a template in SendGrid.
+   */
   template: string
+  /**
+   * Data to pass to the template.
+   */
   data?: Record<string, unknown> | null
+  /**
+   * What triggered this notification.
+   * 
+   * @example
+   * order.created
+   */
   trigger_type?: string | null
+  /**
+   * The ID of the associated resource. for example, if the notification was triggered 
+   * because an order was created, this would be the ID of the order.
+   */
   resource_id?: string | null
+  /**
+   * The type of the resource that triggered the notification.
+   * 
+   * @example
+   * order
+   */
   resource_type?: string | null
+  /**
+   * The ID of the user or customer that received the notification.
+   */
   receiver_id?: string | null
+  /**
+   * The ID of the original notification if this is a resend of it.
+   */
   original_notification_id?: string | null
+  /**
+   * The ID of the notification in an external or third-party system.
+   */
   external_id?: string | null
+  /**
+   * The ID of the notification provider used.
+   */
   provider_id: string
+  /**
+   * The date the notification was created.
+   */
   created_at: string
 }

packages/core/types/src/http/notification/admin/queries.ts

@@ -4,8 +4,17 @@ import { FindParams, SelectParams } from "../../common"
 export interface AdminNotificationListParams
   extends BaseFilterable<AdminNotificationListParams>,
     FindParams {
+  /**
+   * Query or keywords to search the notification's searchable fields.
+   */
   q?: string
+  /**
+   * Filter by notification ID(s).
+   */
   id?: string | string[]
+  /**
+   * Filter by channel(s).
+   */
   channel?: string | string[]
 }
 

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

@@ -2,10 +2,16 @@ import { PaginatedResponse } from "../../common"
 import { AdminNotification } from "./entities"
 
 export interface AdminNotificationResponse {
+  /**
+   * The notification's details.
+   */
   notification: AdminNotification
 }
 
 export interface AdminNotificationListResponse
   extends PaginatedResponse<{
+    /**
+     * The list of notifications.
+     */
     notifications: AdminNotification[]
   }> {}

packages/core/types/src/http/order-edit/admin/payloads.ts

@@ -1,22 +1,61 @@
 export interface AdminInitiateOrderEditRequest {
+  /**
+   * The ID of the order to create the edit for.
+   */
   order_id: string
+  /**
+   * The order edit's description.
+   */
   description?: string
+  /**
+   * An internal note viewed by admin users only.
+   */
   internal_note?: string
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, unknown>
 }
 
 export interface AdminAddOrderEditItems {
+  /**
+   * The details of the items to add.
+   */
   items: {
+    /**
+     * The ID of the product variant to add.
+     */
     variant_id: string
+    /**
+     * The item's quantity.
+     */
     quantity: number
+    /**
+     * A custom price to use for the item.
+     */
     unit_price?: number
+    /**
+     * An internal note viewed by admin users only.
+     */
     internal_note?: string
+    /**
+     * Whether the variant can be added even if it's out of stock.
+     */
     allow_backorder?: boolean
+    /**
+     * Key-value pairs of custom data.
+     */
     metadata?: Record<string, unknown>
   }[]
 }
 
 export interface AdminUpdateOrderEditItem {
+  /**
+   * The item's quantity.
+   */
   quantity?: number
+  /**
+   * An internal note viewed by admin users only.
+   */
   internal_note?: string | null
 }

packages/core/types/src/http/order-edit/admin/responses.ts

@@ -2,10 +2,16 @@ import { DeleteResponse } from "../../common"
 import { AdminOrderChange, AdminOrderPreview } from "../../order/admin"
 
 export interface AdminOrderEditPreviewResponse {
+  /**
+   * A preview of the order when the edit is applied.
+   */
   order_preview: AdminOrderPreview
 }
 
 export interface AdminOrderEditResponse {
+  /**
+   * The order edit's details.
+   */
   order_change: AdminOrderChange
 }
 

packages/core/types/src/http/order/admin/entities.ts

@@ -17,13 +17,37 @@ import {
 } from "../common"
 
 export interface AdminOrder extends Omit<BaseOrder, "items"> {
+  /**
+   * The order's payment collections.
+   */
   payment_collections: AdminPaymentCollection[]
+  /**
+   * The order's fulfillments.
+   */
   fulfillments?: AdminOrderFulfillment[]
+  /**
+   * The associated sales channel's details.
+   */
   sales_channel?: AdminSalesChannel
+  /**
+   * The details of the customer that placed the order.
+   */
   customer?: AdminCustomer
+  /**
+   * The order's shipping address.
+   */
   shipping_address?: AdminOrderAddress | null
+  /**
+   * The order's billing address.
+   */
   billing_address?: AdminOrderAddress | null
+  /**
+   * The order's items.
+   */
   items: AdminOrderLineItem[]
+  /**
+   * The order's shipping methods.
+   */
   shipping_methods: AdminOrderShippingMethod[]
 }
 
@@ -54,19 +78,6 @@ export interface AdminOrderChange
   actions: AdminOrderChangeAction[]
 }
 
-export interface AdminOrderItem {
-  order_id: string
-  item_id: string
-  version: number
-  history: {
-    version: {
-      from: number
-      to: number
-    }
-  }
-  item: AdminOrderLineItem
-}
-
 export interface AdminOrderChangeAction
   extends Omit<BaseOrderChangeAction, "order_change" | "order"> {
   /**
@@ -82,25 +93,58 @@ export interface AdminOrderChangeAction
 export interface AdminOrderFulfillment extends BaseOrderFulfillment {}
 
 export interface AdminOrderItem {
+  /**
+   * The ID of the order that the item belongs to.
+   */
   order_id: string
+  /**
+   * The ID of the associated line item.
+   */
   item_id: string
+  /**
+   * The order version that the item belongs to.
+   */
   version: number
+  /**
+   * The item's history details.
+   */
   history: {
+    /**
+     * The item's version details.
+     */
     version: {
+      /**
+       * The version it was added in.
+       */
       from: number
+      /**
+       * The version it's still available in.
+       */
       to: number
     }
   }
+  /**
+   * The associated line item's details.
+   */
   item: AdminOrderLineItem
 }
 
 export interface AdminOrderLineItem
   extends Omit<BaseOrderLineItem, "variant" | "product"> {
+  /**
+   * The associated variant's details.
+   */
   variant?: AdminProductVariant
+  /**
+   * The associated product's details.
+   */
   product?: AdminProduct
 }
 
 export interface AdminOrderAddress extends BaseOrderAddress {
+  /**
+   * The address's country.
+   */
   country?: AdminRegionCountry
 }
 

packages/core/types/src/http/order/admin/payload.ts

@@ -1,22 +1,77 @@
 export interface AdminCreateOrderFulfillment {
-  items: { id: string; quantity: number }[]
+  /**
+   * The items to add to the fulfillment.
+   */
+  items: {
+    /**
+     * The order item's ID.
+     */ 
+    id: string; 
+    /**
+     * The quantity to fulfill.
+     */
+    quantity: number
+  }[]
+  /**
+   * The ID of the stock location
+   * to fulfill the items from.
+   */
   location_id?: string
+  /**
+   * Whether to notify the customer about this change.
+   */
   no_notification?: boolean
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, any>
 }
 
 export interface AdminCreateOrderShipment {
-  items: { id: string; quantity: number }[]
+  /**
+   * The fulfillment items to create a shipment for.
+   */
+  items: {
+    /**
+     * The item's ID.
+     */ 
+    id: string; 
+    /**
+     * The quantity to ship.
+     */
+    quantity: number
+  }[]
+  /**
+   * The shipment's labels.
+   */
   labels?: {
+    /**
+     * The label's tracking number.
+     */
     tracking_number: string
+    /**
+     * The label's tracking URL.
+     */
     tracking_url: string
+    /**
+     * The label's URL.
+     */
     label_url: string
   }[]
+  /**
+   * Whether to notify the customer about this change.
+   */
   no_notification?: boolean
+  /**
+   * Key-value pairs of custom data.
+   */
   metadata?: Record<string, any>
 }
 
 export interface AdminCancelOrderFulfillment {
+  /**
+   * Whether to notify the customer about this change.
+   */
   no_notification?: boolean
 }
 

packages/core/types/src/http/order/admin/queries.ts

@@ -4,21 +4,56 @@ import { FindParams } from "../../common"
 import { BaseOrderChangesFilters, BaseOrderFilters } from "../common"
 
 export interface AdminOrderFilters extends FindParams, BaseOrderFilters {
+  /**
+   * Filter by order ID(s).
+   */
   id?: string[] | string
+  /**
+   * Filter by sales channel IDs to retrieve their associated orders.
+   */
   sales_channel_id?: string[]
+  /**
+   * Filter by fulfillment statuses.
+   */
   fulfillment_status?: FulfillmentStatus[]
+  /**
+   * Filter by payment statuses.
+   */
   payment_status?: PaymentStatus[]
+  /**
+   * Filter by region IDs to retrieve their associated orders.
+   */
   region_id?: string[] | string
+  /**
+   * Filter by customer IDs to retrieve their associated orders.
+   */
   customer_id?: string[] | string
+  /**
+   * Query or keywords to filter the order's searchable fields.
+   */
   q?: string
+  /**
+   * Apply filters on the fulfillment's creation date.
+   */
   created_at?: OperatorMap<string>
+  /**
+   * Apply filters on the fulfillment's update date.
+   */
   updated_at?: OperatorMap<string>
 }
 
 export interface AdminOrderItemsFilters extends FindParams {
+  /**
+   * Filter by order item ID(s).
+   */
   id?: string[] | string
+  /**
+   * Filter by the associated line item ID(s).
+   */
   item_id?: string[] | string
-  order_id?: string[] | string
+  /**
+   * Filter by order version(s).
+   */
   version?: number[] | number
 }
 

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

@@ -7,22 +7,37 @@ import {
 } from "./entities"
 
 export interface AdminOrderResponse {
+  /**
+   * The order's details.
+   */
   order: AdminOrder
 }
 
 export interface AdminOrderChangesResponse {
+  /**
+   * The list of order changes.
+   */
   order_changes: AdminOrderChange[]
 }
 
 export type AdminOrderListResponse = PaginatedResponse<{
+  /**
+   * The list of orders.
+   */
   orders: AdminOrder[]
 }>
 
 export type AdminOrderLineItemsListResponse = {
+  /**
+   * The list of order items.
+   */
   order_items: AdminOrderItem[]
 }
 
 export interface AdminOrderPreviewResponse {
+  /**
+   * A preview of the order if the latest change, such as exchange, return, edit, or claim is applied on it.
+   */
   order: AdminOrderPreview
 }
 

packages/core/types/src/http/order/common.ts

@@ -1,5 +1,5 @@
 import { BaseFilterable, OperatorMap } from "../../dal"
-import { ChangeActionType, OrderChangeStatus } from "../../order"
+import { ChangeActionType, OrderChangeStatus, OrderStatus } from "../../order"
 import { BaseClaim } from "../claim/common"
 import { FindParams } from "../common"
 import { BaseExchange } from "../exchange/common"
@@ -914,14 +914,29 @@ export interface BaseOrder {
 export interface BaseOrderFilters
   extends FindParams,
     BaseFilterable<BaseOrderFilters> {
+  /**
+   * Filter by order ID(s).
+   */
   id?: string[] | string | OperatorMap<string | string[]>
-  status?: string[] | string | OperatorMap<string | string[]>
+  /**
+   * Filter by status(es).
+   */
+  status?: OrderStatus[] | OrderStatus | OperatorMap<OrderStatus | OrderStatus[]>
 }
 
 export interface BaseOrderChangesFilters
   extends BaseFilterable<BaseOrderChangesFilters> {
+  /**
+   * Filter by order change ID(s).
+   */
   id?: string[] | string | OperatorMap<string | string[]>
+  /**
+   * Filter by status(es).
+   */
   status?: string[] | string | OperatorMap<string | string[]>
+  /**
+   * Filter by order change type, such as `return`, `exchange`, `edit`, or `claim`.
+   */
   change_type?: string[] | string | OperatorMap<string | string[]>
 }
 

packages/core/types/src/http/payment/admin/entities.ts

@@ -8,20 +8,44 @@ import {
 } from "../common"
 
 export interface AdminPaymentProvider extends BasePaymentProvider {
+  /**
+   * Whether the payment provider is enabled.
+   */
   is_enabled: boolean
 }
 
 export interface AdminPayment extends BasePayment {
+  /**
+   * The associated refunds.
+   */
   refunds?: AdminRefund[]
+  /**
+   * The payment collection this payment belongs to.
+   */
   payment_collection?: AdminPaymentCollection
+  /**
+   * The associated payment session.
+   */
   payment_session?: AdminPaymentSession
 }
 export interface AdminPaymentCollection extends BasePaymentCollection {
+  /**
+   * The associated payments.
+   */
   payments?: AdminPayment[]
+  /**
+   * The associated payment sessions.
+   */
   payment_sessions?: AdminPaymentSession[]
+  /**
+   * The associated payment providers.
+   */
   payment_providers: AdminPaymentProvider[]
 }
 export interface AdminPaymentSession extends BasePaymentSession {
+  /**
+   * The payment collection this payment session belongs to.
+   */
   payment_collection?: AdminPaymentCollection
 }
 export interface AdminRefund extends BaseRefund {}

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

@@ -1,10 +1,24 @@
 export interface AdminCapturePayment {
+  /**
+   * Custom amount to capture. If not specified, the
+   * payment's amount is captured.
+   */
   amount?: number
 }
 
 export interface AdminRefundPayment {
+  /**
+   * Custom amount to refund. If not specified, the
+   * payment's amount is refunded.
+   */
   amount?: number
+  /**
+   * The ID of the refund's reason.
+   */
   refund_reason_id?: string | null
+  /**
+   * A note to attach to the refund.
+   */
   note?: string | null
 }
 
@@ -14,7 +28,14 @@ export interface AdminCreateRefundReason {
 }
 
 export interface AdminCreatePaymentCollection {
+  /**
+   * The ID of the order this payment collection belongs to.
+   */
   order_id: string
+  /**
+   * The payment collection's amount. If not specified, 
+   * the order's total is used as the amount instead.
+   */
   amount?: number
 }
 

packages/core/types/src/http/payment/admin/queries.ts

@@ -18,10 +18,25 @@ export interface AdminPaymentCollectionFilters
 export interface AdminPaymentSessionFilters extends BasePaymentSessionFilters {}
 
 export interface AdminPaymentFilters extends FindParams, BasePaymentFilters {
+  /**
+   * Query or keywords to search the payment's searchable fields.
+   */
   q?: string
+  /**
+   * Filter by IDs of associated payment sessions to retrieve their payments.
+   */
   payment_session_id?: string | string[]
+  /**
+   * Apply filters on the payment's creation date.
+   */
   created_at?: OperatorMap<string>
+  /**
+   * Apply filters on the payment's update date.
+   */
   updated_at?: OperatorMap<string>
+  /**
+   * Apply filters on the payment's deleted date.
+   */
   deleted_at?: OperatorMap<string>
 }
 
@@ -35,8 +50,12 @@ export interface RefundReasonFilters
 export interface AdminGetPaymentProvidersParams
   extends FindParams,
     BaseFilterable<AdminGetPaymentProvidersParams> {
+  /**
+   * Filter by payment provider ID(s).
+   */
   id?: string | string[]
+  /**
+   * Whether the payment provider is enabled.
+   */
   is_enabled?: boolean
-  $and?: AdminGetPaymentProvidersParams[]
-  $or?: AdminGetPaymentProvidersParams[]
 }

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

@@ -8,6 +8,9 @@ import {
 } from "./entities"
 
 export interface AdminPaymentCollectionResponse {
+  /**
+   * The payment collection's details.
+   */
   payment_collection: AdminPaymentCollection
 }
 
@@ -19,10 +22,16 @@ export interface AdminPaymentCollectionsResponse {
 }
 
 export interface AdminPaymentResponse {
+  /**
+   * The payment's details.
+   */
   payment: AdminPayment
 }
 
 export type AdminPaymentsResponse = PaginatedResponse<{
+  /**
+   * The list of payments.
+   */
   payments: AdminPayment[]
 }>
 
@@ -43,6 +52,9 @@ export type RefundReasonsResponse = PaginatedResponse<{
 }>
 
 export type AdminPaymentProviderListResponse = PaginatedResponse<{
+  /**
+   * The list of payment providers.
+   */
   payment_providers: AdminPaymentProvider[]
 }>
 

packages/core/types/src/http/payment/common.ts

@@ -472,5 +472,8 @@ export interface BasePaymentProviderFilters
 }
 
 export interface BasePaymentFilters extends BaseFilterable<BasePaymentFilters> {
+  /**
+   * Filter by payment ID(s).
+   */
   id?: string | string[]
 }