From 43a44cf426ab43bc74eb76bc6718ebd49d1de00c Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Mon, 28 Oct 2024 06:42:17 +0200 Subject: [PATCH] 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] --- .../core/js-sdk/src/admin/notification.ts | 80 ++++++ packages/core/js-sdk/src/admin/order-edit.ts | 167 +++++++++++- packages/core/js-sdk/src/admin/order.ts | 258 +++++++++++++++++- .../js-sdk/src/admin/payment-collection.ts | 55 ++++ packages/core/js-sdk/src/admin/payment.ts | 163 ++++++++++- .../src/http/notification/admin/entities.ts | 52 ++++ .../src/http/notification/admin/queries.ts | 9 + .../src/http/notification/admin/responses.ts | 6 + .../src/http/order-edit/admin/payloads.ts | 39 +++ .../src/http/order-edit/admin/responses.ts | 6 + .../types/src/http/order/admin/entities.ts | 70 ++++- .../types/src/http/order/admin/payload.ts | 59 +++- .../types/src/http/order/admin/queries.ts | 37 ++- .../types/src/http/order/admin/responses.ts | 15 + packages/core/types/src/http/order/common.ts | 19 +- .../types/src/http/payment/admin/entities.ts | 24 ++ .../types/src/http/payment/admin/payloads.ts | 21 ++ .../types/src/http/payment/admin/queries.ts | 23 +- .../types/src/http/payment/admin/responses.ts | 12 + .../core/types/src/http/payment/common.ts | 3 + 20 files changed, 1087 insertions(+), 31 deletions(-) diff --git a/packages/core/js-sdk/src/admin/notification.ts b/packages/core/js-sdk/src/admin/notification.ts index ea747bf37d..3cd2963bd5 100644 --- a/packages/core/js-sdk/src/admin/notification.ts +++ b/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 diff --git a/packages/core/js-sdk/src/admin/order-edit.ts b/packages/core/js-sdk/src/admin/order-edit.ts index 0773c36b46..a04cb18fe5 100644 --- a/packages/core/js-sdk/src/admin/order-edit.ts +++ b/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( + return await this.client.fetch( `/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, diff --git a/packages/core/js-sdk/src/admin/order.ts b/packages/core/js-sdk/src/admin/order.ts index 1b0dd4ae68..8952146b2a 100644 --- a/packages/core/js-sdk/src/admin/order.ts +++ b/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( `/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( `/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( `/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( `/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( `/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( `/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 >(`/admin/orders/${id}/line-items`, { query: queryParams, headers, diff --git a/packages/core/js-sdk/src/admin/payment-collection.ts b/packages/core/js-sdk/src/admin/payment-collection.ts index d55916aaac..605f2e96b7 100644 --- a/packages/core/js-sdk/src/admin/payment-collection.ts +++ b/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( `/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, diff --git a/packages/core/js-sdk/src/admin/payment.ts b/packages/core/js-sdk/src/admin/payment.ts index 3e8e313af6..023c340645 100644 --- a/packages/core/js-sdk/src/admin/payment.ts +++ b/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( `/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( @@ -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, diff --git a/packages/core/types/src/http/notification/admin/entities.ts b/packages/core/types/src/http/notification/admin/entities.ts index f425be154b..8e1f04bdbb 100644 --- a/packages/core/types/src/http/notification/admin/entities.ts +++ b/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 | 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 } diff --git a/packages/core/types/src/http/notification/admin/queries.ts b/packages/core/types/src/http/notification/admin/queries.ts index 2507417d20..fc894c1aa9 100644 --- a/packages/core/types/src/http/notification/admin/queries.ts +++ b/packages/core/types/src/http/notification/admin/queries.ts @@ -4,8 +4,17 @@ import { FindParams, SelectParams } from "../../common" export interface AdminNotificationListParams extends BaseFilterable, 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[] } diff --git a/packages/core/types/src/http/notification/admin/responses.ts b/packages/core/types/src/http/notification/admin/responses.ts index d3e4f4ccc1..c609df0b5d 100644 --- a/packages/core/types/src/http/notification/admin/responses.ts +++ b/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[] }> {} diff --git a/packages/core/types/src/http/order-edit/admin/payloads.ts b/packages/core/types/src/http/order-edit/admin/payloads.ts index 5242d2e95d..21534496fb 100644 --- a/packages/core/types/src/http/order-edit/admin/payloads.ts +++ b/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 } 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 }[] } export interface AdminUpdateOrderEditItem { + /** + * The item's quantity. + */ quantity?: number + /** + * An internal note viewed by admin users only. + */ internal_note?: string | null } diff --git a/packages/core/types/src/http/order-edit/admin/responses.ts b/packages/core/types/src/http/order-edit/admin/responses.ts index 5119cd2e71..9ac25b15c5 100644 --- a/packages/core/types/src/http/order-edit/admin/responses.ts +++ b/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 } diff --git a/packages/core/types/src/http/order/admin/entities.ts b/packages/core/types/src/http/order/admin/entities.ts index 0207504050..abc642b4af 100644 --- a/packages/core/types/src/http/order/admin/entities.ts +++ b/packages/core/types/src/http/order/admin/entities.ts @@ -17,13 +17,37 @@ import { } from "../common" export interface AdminOrder extends Omit { + /** + * 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 { /** @@ -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 { + /** + * 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 } diff --git a/packages/core/types/src/http/order/admin/payload.ts b/packages/core/types/src/http/order/admin/payload.ts index 3ce1d41cb9..fc1d38f962 100644 --- a/packages/core/types/src/http/order/admin/payload.ts +++ b/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 } 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 } export interface AdminCancelOrderFulfillment { + /** + * Whether to notify the customer about this change. + */ no_notification?: boolean } diff --git a/packages/core/types/src/http/order/admin/queries.ts b/packages/core/types/src/http/order/admin/queries.ts index 725f350943..9ff515ae6f 100644 --- a/packages/core/types/src/http/order/admin/queries.ts +++ b/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 + /** + * Apply filters on the fulfillment's update date. + */ updated_at?: OperatorMap } 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 } diff --git a/packages/core/types/src/http/order/admin/responses.ts b/packages/core/types/src/http/order/admin/responses.ts index dbcb8a0096..571f5f27b5 100644 --- a/packages/core/types/src/http/order/admin/responses.ts +++ b/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 } diff --git a/packages/core/types/src/http/order/common.ts b/packages/core/types/src/http/order/common.ts index b8e785a454..020b85c781 100644 --- a/packages/core/types/src/http/order/common.ts +++ b/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 { + /** + * Filter by order ID(s). + */ id?: string[] | string | OperatorMap - status?: string[] | string | OperatorMap + /** + * Filter by status(es). + */ + status?: OrderStatus[] | OrderStatus | OperatorMap } export interface BaseOrderChangesFilters extends BaseFilterable { + /** + * Filter by order change ID(s). + */ id?: string[] | string | OperatorMap + /** + * Filter by status(es). + */ status?: string[] | string | OperatorMap + /** + * Filter by order change type, such as `return`, `exchange`, `edit`, or `claim`. + */ change_type?: string[] | string | OperatorMap } diff --git a/packages/core/types/src/http/payment/admin/entities.ts b/packages/core/types/src/http/payment/admin/entities.ts index 25ef2336a4..9a4ef7e85a 100644 --- a/packages/core/types/src/http/payment/admin/entities.ts +++ b/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 {} diff --git a/packages/core/types/src/http/payment/admin/payloads.ts b/packages/core/types/src/http/payment/admin/payloads.ts index b407662567..ffa535448d 100644 --- a/packages/core/types/src/http/payment/admin/payloads.ts +++ b/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 } diff --git a/packages/core/types/src/http/payment/admin/queries.ts b/packages/core/types/src/http/payment/admin/queries.ts index 67f77f9def..fd74c4f328 100644 --- a/packages/core/types/src/http/payment/admin/queries.ts +++ b/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 + /** + * Apply filters on the payment's update date. + */ updated_at?: OperatorMap + /** + * Apply filters on the payment's deleted date. + */ deleted_at?: OperatorMap } @@ -35,8 +50,12 @@ export interface RefundReasonFilters export interface AdminGetPaymentProvidersParams extends FindParams, BaseFilterable { + /** + * Filter by payment provider ID(s). + */ id?: string | string[] + /** + * Whether the payment provider is enabled. + */ is_enabled?: boolean - $and?: AdminGetPaymentProvidersParams[] - $or?: AdminGetPaymentProvidersParams[] } diff --git a/packages/core/types/src/http/payment/admin/responses.ts b/packages/core/types/src/http/payment/admin/responses.ts index 6790ad8f97..f3c2b09a05 100644 --- a/packages/core/types/src/http/payment/admin/responses.ts +++ b/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[] }> diff --git a/packages/core/types/src/http/payment/common.ts b/packages/core/types/src/http/payment/common.ts index 35a40726d1..3e1ae5c023 100644 --- a/packages/core/types/src/http/payment/common.ts +++ b/packages/core/types/src/http/payment/common.ts @@ -472,5 +472,8 @@ export interface BasePaymentProviderFilters } export interface BasePaymentFilters extends BaseFilterable { + /** + * Filter by payment ID(s). + */ id?: string | string[] }