docs: enhance how references are generated (#5805)
* adjusted configurations * enhancements to tool and configurations * change reference in docs * fixed issue in workflows reference * added project name * more optimizations * fix context error * added a types reference * resolved missing types * fix reference reflection types not having children * add an expand url parameter * added new option to the README * added details about new option
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
a418e6cebc
commit
892d737c1f
4358 files changed
+947876
-534760
No files matched your search
@@ -26,13 +26,13 @@ A cart is represented by the `Cart` entity. Some of the `Cart` entity’s attrib
|
||||
- `completed_at`: the date the cart was completed. A completed cart means that it has been used for its main purpose. For example, if the cart is used to place an order, then a completed cart means that the order was placed.
|
||||
- `payment_authorized_at`: the date a payment was authorized.
|
||||
|
||||
There are other important attributes discussed in later sections. Check out the [full Cart entity in the entities reference](../../references/entities/classes/Cart.mdx).
|
||||
There are other important attributes discussed in later sections. Check out the [full Cart entity in the entities reference](../../references/entities/classes/entities.Cart.mdx).
|
||||
|
||||
---
|
||||
|
||||
## Cart Totals Calculation
|
||||
|
||||
By default, the `Cart` entity doesn’t hold any details regarding the totals. These are computed and added to the cart instance using the `CartService`'s [decorateTotals method](../../references/services/classes/CartService.mdx#decoratetotals). There's also a dedicated method in the `CartService`, [retrieveWithTotals](../../references/services/classes/CartService.mdx#retrieveWithTotals), attaching the totals automatically. It is recommended to use this method by default when you need to retrieve the cart.
|
||||
By default, the `Cart` entity doesn’t hold any details regarding the totals. These are computed and added to the cart instance using the `CartService`'s [decorateTotals method](../../references/services/classes/services.CartService.mdx#decoratetotals). There's also a dedicated method in the `CartService`, [retrieveWithTotals](../../references/services/classes/services.CartService.mdx#retrieveWithTotals), attaching the totals automatically. It is recommended to use this method by default when you need to retrieve the cart.
|
||||
|
||||
The cart’s totals are calculated based on the content and context of the cart. This includes the selected region, whether tax-inclusive pricing is enabled, the chosen shipping methods, and more.
|
||||
|
||||
@@ -83,11 +83,11 @@ You can learn how to override the cart completion strategy [here](./backend/cart
|
||||
|
||||
The process is implemented as follows:
|
||||
|
||||
1. When the idempotency key’s recovery point is set to `started`, the tax lines are created for the items in the cart. This is done using the `CartService`'s [createTaxLines method](../../references/services/classes/CartService.mdx#createtaxlines). If that is completed with no errors, the recovery point is set to `tax_lines_created` and the process continues.
|
||||
2. When the idempotency key’s recovery point is set to `tax_lines_created`, the payment is authorized using the `CartService`'s method [authorizePayment](../../references/services/classes/CartService.mdx#authorizepayment). If the payment requires more action or is pending authorization, then the tax lines that were created in the previous steps are deleted and the cart completion process is terminated. Once the payment is authorized, the process can be restarted.
|
||||
3. When the idempotency key’s recovery point is set to `payment_authorized`, tax lines are created again the same way as the first step. Then, the inventory of each of the items in the cart is confirmed using the `ProductVariantInventoryService`'s method [confirmInventory](../../references/services/classes/ProductVariantInventoryService.mdx#confirminventory). If an item is in stock, the quantity is reserved using the `ProductVariantInventoryService`'s method [reserveQuantity](../../references/services/classes/ProductVariantInventoryService.mdx#reservequantity). If an item is out of stock, any item reservations that were created are deleted, the payment is canceled, and an error is thrown, terminating the cart completion process. If all item quantities are confirmed to be available:
|
||||
1. If the cart belongs to a swap (the `type` attribute is set to `swap`), the swap is registered as completed using the `SwapService`'s [registerCartCompletion method](../../references/services/classes/SwapService.mdx#registercartcompletion) and the inventory item reservations are removed using the Inventory module. The process ends successfully here for a swap.
|
||||
2. If the cart belongs to an order, the order is created using the `OrderService`'s method [createFromCart](../../references/services/classes/OrderService.mdx#createfromcart). The order is then retrieved and sent in the response.
|
||||
1. When the idempotency key’s recovery point is set to `started`, the tax lines are created for the items in the cart. This is done using the `CartService`'s [createTaxLines method](../../references/services/classes/services.CartService.mdx#createtaxlines). If that is completed with no errors, the recovery point is set to `tax_lines_created` and the process continues.
|
||||
2. When the idempotency key’s recovery point is set to `tax_lines_created`, the payment is authorized using the `CartService`'s method [authorizePayment](../../references/services/classes/services.CartService.mdx#authorizepayment). If the payment requires more action or is pending authorization, then the tax lines that were created in the previous steps are deleted and the cart completion process is terminated. Once the payment is authorized, the process can be restarted.
|
||||
3. When the idempotency key’s recovery point is set to `payment_authorized`, tax lines are created again the same way as the first step. Then, the inventory of each of the items in the cart is confirmed using the `ProductVariantInventoryService`'s method [confirmInventory](../../references/services/classes/services.ProductVariantInventoryService.mdx#confirminventory). If an item is in stock, the quantity is reserved using the `ProductVariantInventoryService`'s method [reserveQuantity](../../references/services/classes/services.ProductVariantInventoryService.mdx#reservequantity). If an item is out of stock, any item reservations that were created are deleted, the payment is canceled, and an error is thrown, terminating the cart completion process. If all item quantities are confirmed to be available:
|
||||
1. If the cart belongs to a swap (the `type` attribute is set to `swap`), the swap is registered as completed using the `SwapService`'s [registerCartCompletion method](../../references/services/classes/services.SwapService.mdx#registercartcompletion) and the inventory item reservations are removed using the Inventory module. The process ends successfully here for a swap.
|
||||
2. If the cart belongs to an order, the order is created using the `OrderService`'s method [createFromCart](../../references/services/classes/services.OrderService.mdx#createfromcart). The order is then retrieved and sent in the response.
|
||||
4. Once the process detailed above is done, the idempotency key’s recovery point is set to `finished`.
|
||||
|
||||
---
|
||||
|
||||
@@ -58,7 +58,7 @@ It’s important to enable a payment processor in a region, or else the payment
|
||||
|
||||
### PaymentProvider Entity Overview
|
||||
|
||||
The [`PaymentProvider`](../../references/entities/classes/PaymentProvider.mdx) entity only has 2 attributes: `is_installed` which is a boolean value indicating whether the Payment Processor is installed; and `id` which is the unique identifier that you define in the Payment Processor service.
|
||||
The [`PaymentProvider`](../../references/entities/classes/entities.PaymentProvider.mdx) entity only has 2 attributes: `is_installed` which is a boolean value indicating whether the Payment Processor is installed; and `id` which is the unique identifier that you define in the Payment Processor service.
|
||||
|
||||
---
|
||||
|
||||
@@ -82,7 +82,7 @@ Among the Payment Sessions available only one will be selected based on the cust
|
||||
|
||||
### PaymentSession Entity Overview
|
||||
|
||||
The [`PaymentSession`](../../references/entities/classes/PaymentSession.mdx) entity belongs to a `Cart`. This is the customer‘s cart that was used for checkout which lead to the creation of the Payment Session.
|
||||
The [`PaymentSession`](../../references/entities/classes/entities.PaymentSession.mdx) entity belongs to a `Cart`. This is the customer‘s cart that was used for checkout which lead to the creation of the Payment Session.
|
||||
|
||||
The `PaymentSession` instance also belongs to a `PaymentProvider` instance. This is the Payment Processor that was used to create the Payment Session and that controls it for further actions like authorizing the payment.
|
||||
|
||||
@@ -116,7 +116,7 @@ When the store operator then chooses to capture the order from the Medusa Admin,
|
||||
|
||||
### Payment Entity Overview
|
||||
|
||||
The [`Payment`](../../references/entities/classes/Payment.mdx) entity belongs to the `Cart` that it was originally created from when the customer’s payment was authorized. It also belongs to an `Order` once it’s placed. Additionally, it belongs to a `PaymentProvider` which is the payment processor that the customer chose on checkout.
|
||||
The [`Payment`](../../references/entities/classes/entities.Payment.mdx) entity belongs to the `Cart` that it was originally created from when the customer’s payment was authorized. It also belongs to an `Order` once it’s placed. Additionally, it belongs to a `PaymentProvider` which is the payment processor that the customer chose on checkout.
|
||||
|
||||
In case a `Swap` is created for an order, `Payment` will be associated with that swap to handle payment operations related to it.
|
||||
|
||||
|
||||
@@ -49,7 +49,7 @@ Once the Fulfillment Provider is added to the backend, the store operator will b
|
||||
|
||||
### FulfillmentProvider Entity Overview
|
||||
|
||||
The [`FulfillmentProvider`](../../references/entities/classes/FulfillmentProvider.mdx) entity only has 2 attributes: `is_installed` to indicate if the fulfillment provider is installed and its value is a boolean; and `id` which is the unique identifier that you define in the Fulfillment Provider Service.
|
||||
The [`FulfillmentProvider`](../../references/entities/classes/entities.FulfillmentProvider.mdx) entity only has 2 attributes: `is_installed` to indicate if the fulfillment provider is installed and its value is a boolean; and `id` which is the unique identifier that you define in the Fulfillment Provider Service.
|
||||
|
||||
---
|
||||
|
||||
@@ -73,7 +73,7 @@ For example, shipping heavy items might be more expensive than others, which wou
|
||||
|
||||
### ShippingProfile Entity Overview
|
||||
|
||||
The [`ShippingProfile`](../../references/entities/classes/ShippingProfile.mdx) entity can have a set of `Product` instances. These would be the products the shipping profile is providing shipping options for.
|
||||
The [`ShippingProfile`](../../references/entities/classes/entities.ShippingProfile.mdx) entity can have a set of `Product` instances. These would be the products the shipping profile is providing shipping options for.
|
||||
|
||||
The `ShippingProfile` has a `type` attribute that can be `default`, `gift_card`, or `custom`.
|
||||
|
||||
@@ -101,7 +101,7 @@ Think of a shipping option as a template defined by the admin that indicates wha
|
||||
|
||||
### ShippingOption Entity Overview
|
||||
|
||||
The [`ShippingOption`](../../references/entities/classes/ShippingOption.mdx) entity belongs to the `ShippingProfile` entity.
|
||||
The [`ShippingOption`](../../references/entities/classes/entities.ShippingOption.mdx) entity belongs to the `ShippingProfile` entity.
|
||||
|
||||
The `ShippingOption` entity also belongs to a `FulfillmentProvider`. This can be either a custom third-party provider or one of Medusa’s default fulfillment providers.
|
||||
|
||||
@@ -139,7 +139,7 @@ This separation allows for developers to implement the custom integration with t
|
||||
|
||||
A lot of the shipping method’s attributes are similar to the shipping option’s attribute.
|
||||
|
||||
The [`ShippingMethod`](../../references/entities/classes/ShippingMethod.mdx) entity belongs to a `ShippingOption`.
|
||||
The [`ShippingMethod`](../../references/entities/classes/entities.ShippingMethod.mdx) entity belongs to a `ShippingOption`.
|
||||
|
||||
Similar to the `data` attribute explained for the `ShippingOption` entity, a `ShippingMethod` has a similar `data` attribute that includes all the data to be sent to the fulfillment provider when fulfilling the order.
|
||||
|
||||
@@ -153,5 +153,5 @@ The `ShippingMethod` instance holds a `price` attribute, which will either b
|
||||
|
||||
## See Also
|
||||
|
||||
- [Create a Fulfillment Provider](../../references/fulfillment/classes/AbstractFulfillmentService.mdx)
|
||||
- [Create a Fulfillment Provider](../../references/fulfillment/classes/fulfillment.AbstractFulfillmentService.mdx)
|
||||
- [Available shipping plugins](https://github.com/medusajs/medusa/tree/master/packages)
|
||||
Reference in new issue
Block a user