asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

docs: migrate guides to TSDoc references (#6100)

Browse Source
This commit is contained in:
Shahed Nasser
2024-01-22 18:38:35 +01:00
committed by GitHub
parent 85dad169bb
commit 4792c55226
980 changed files with 195537 additions and 160619 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/apps/docs/content/modules/price-lists/backend/override-price-selection-strategy.mdx
-295
View File
@@ -1,295 +0,0 @@
---
description: 'Learn how to override the price selection strategy. The price selection strategy is used to determine the best price based on a specific context.'
addHowToData: true
---
import ParameterTypes from "@site/src/components/ParameterTypes"
# How to Override Price Selection Strategy
In this document, you’ll learn how to override Medusa’s price selection strategy to create a custom pricing strategy.
:::note
If you’re interested in learning what a price selection strategy is and how it works, check out [this documentation](../price-selection-strategy.md) instead.
:::
## 1. Create Class
Create a TypeScript or JavaScript file in `src/strategies` of your Medusa backend project with a class that extends the `AbstractPriceSelectionStrategy` class:
```ts title="src/strategies/price.ts"
import {
AbstractPriceSelectionStrategy,
PriceSelectionContext,
PriceSelectionResult,
} from "@medusajs/medusa"
import {
TaxServiceRate,
} from "@medusajs/medusa/dist/types/tax-service"
export default class MyStrategy extends
AbstractPriceSelectionStrategy {
async calculateVariantPrice(
data: {
variantId: string;
taxRates: TaxServiceRate[];
quantity?: number
}[],
context: PriceSelectionContext
): Promise<Map<string, PriceSelectionResult>> {
throw new Error("Method not implemented.")
}
}
```
### Resolve Resources
You can resolve resources like services or repositories using [dependency injection](../../../development/fundamentals/dependency-injection.md).
For example:
```ts title="src/strategies/price.ts"
import {
AbstractPriceSelectionStrategy,
CustomerService,
PriceSelectionContext,
PriceSelectionResult,
} from "@medusajs/medusa"
import {
TaxServiceRate,
} from "@medusajs/medusa/dist/types/tax-service"
type InjectedDependencies = {
customerService: CustomerService
}
export default class MyStrategy extends
AbstractPriceSelectionStrategy {
protected customerService_: CustomerService
constructor(container: InjectedDependencies) {
super(container)
this.customerService_ = container.customerService
}
// ...
}
```
---
## 2. Implement calculateVariantPrice
In this method, you can implement your price selection strategy.
### Parameters
You can learn more about optional properties and the meaning behind every property [here](../price-selection-strategy.md#calculatevariantprice-method).
<ParameterTypes parameters={[
{
name: "data",
type: "object[]",
description: "Holds the data necessary to perform the price selection for each variant ID.",
optional: false,
children: [
{
name: "variantId",
type: "string",
description: "The ID of the variant to retrieve the prices for.",
optional: false,
},
{
name: "taxRates",
type: "object[]",
description: "The tax rates to be applied. This is only used for [Tax-Inclusive Pricing](../../taxes/inclusive-pricing.md).",
optional: false,
children: [
{
name: "rate",
type: "number | null",
description: "The tax rate",
optional: true
},
{
name: "name",
type: "string",
description: "The name of the tax rate",
optional: false
},
{
name: "code",
type: "string | null",
description: "The code of the tax rate",
optional: false
}
],
},
{
name: "quantity",
type: "number",
description: "The quantity of the variant",
optional: true
}
],
},
{
name: "context",
type: "[PriceSelectionContext](../price-selection-strategy.md#context-object)",
description: "The context of the price selection",
optional: false,
children: [
{
name: "cart_id",
type: "string",
description: "The ID of the customer’s cart. This is used when the prices are being retrieved for the variant of a line item, as it is used to determine the current region and currency code of the context.",
optional: true
},
{
name: "customer_id",
type: "string",
description: "The ID of the customer. This is used to filter out price lists for a customer group that this customer doesn’t belong to.",
optional: true
},
{
name: "region_id",
type: "string",
description: "The ID of the region the customer is using.",
optional: true
},
{
name: "quantity",
type: "number",
description: "The quantity of the item in the cart. This is used to filter out price lists that have `min_quantity` or `max_quantity` conditions set.",
optional: true
},
{
name: "currency_code",
type: "string",
description: "The currency code the customer is using.",
optional: true
},
{
name: "include_discount_prices",
type: "boolean",
description: "Whether the price list's prices should be retrieved or not.",
optional: true
},
{
name: "taxRates",
type: "object[]",
description: "The tax rates to be applied. This is only used for [Tax-Inclusive Pricing](../../taxes/inclusive-pricing.md).",
optional: false,
children: [
{
name: "rate",
type: "number | null",
description: "The tax rate",
optional: true
},
{
name: "name",
type: "string",
description: "The name of the tax rate",
optional: false
},
{
name: "code",
type: "string | null",
description: "The code of the tax rate",
optional: false
}
],
},
{
name: "ignore_cache",
type: "boolean",
description: "Whether to calculate the prices even if the value of an earlier price calculation is available in the cache.",
optional: true
},
]
}
]} />
### Returns
<ParameterTypes parameters={[
{
name: "Promise",
type: "Promise<Map<string, PriceSelectionResult>>",
description: "A map, each key is an ID of a variant, and its value is an object holding the price selection result.",
optional: false,
children: [
{
name: "PriceSelectionResult",
type: "PriceSelectionResult",
description: "The price selection result of a variant.",
optional: false,
children: [
{
name: "originalPrice",
type: "number | null",
description: "The original price of the variant which depends on the selected region or currency code in the context object. If both region ID and currency code are available in the context object, the region has higher precedence.",
optional: false
},
{
name: "originalPriceIncludesTax",
type: "boolean | null",
description: "Whether the original price includes taxes or not. This is only available for [Tax-Inclusive Pricing](../../taxes/inclusive-pricing.md).",
optional: true
},
{
name: "calculatedPrice",
type: "number | null",
description: "The lowest price among the prices of the product variant retrieved using the context object.",
optional: false
},
{
name: "calculatedPriceIncludesTax",
type: "boolean | null",
description: "Whether the calculated price includes taxes or not. This is only available for [Tax-Inclusive Pricing](../../taxes/inclusive-pricing.md).",
optional: true
},
{
name: "calculatedPriceType",
type: "enum",
description: "Either `default` if the `calculatedPrice` is the original price, or the type of the price list applied, which can be `override` or `sale`.",
optional: true
},
{
name: "prices",
type: "[MoneyAmount](../../../references/entities/classes/entities.MoneyAmount.mdx)[]",
description: "The prices of the variant retrieved using the `context` object. It can include its original price and its price lists if there are any.",
optional: false
}
],
}
],
},
]} />
---
## 3. Run Build Command
In your terminal, run the build command to transpile the files in the `src` directory into the `dist` directory:
```bash npm2yarn
npm run build
```
---
## Test it Out
Run your backend to test it out:
```bash npm2yarn
npx medusa develop
```
Then, try out your strategy using any of the [Products](https://docs.medusajs.com/api/store#products) or [Carts](https://docs.medusajs.com/api/store#carts) API Routes which include retrieving product variants and line items respectively. You should then see the prices in the response based on your implemented strategy.
www/apps/docs/content/modules/price-lists/overview.mdx
+1 -1
View File
@@ -45,7 +45,7 @@ Developers can change the default logic behind how prices are selected to be sho
},
{
type: 'link',
href: '/modules/price-lists/backend/override-price-selection-strategy',
href: '/modules/price-lists/price-selection-strategy',
label: 'Backend: Override Price Selection',
customProps: {
icon: Icons['users-solid'],
www/apps/docs/content/modules/price-lists/price-lists.md
+4 -4
View File
@@ -45,11 +45,11 @@ You can use any of the following conditions:
## How are Price Lists Applied
When a product or a line item is retrieved or manipulated on the storefront, Medusa determines its price using a Price Selection Strategy. The price selection strategy determines the best price to apply in a given [context](./price-selection-strategy.md#context-object). Part of determining the price depends on the price list.
When a product or a line item is retrieved or manipulated on the storefront, Medusa determines its price using a Price Selection Strategy. The price selection strategy determines the best price to apply in a given context. Part of determining the price depends on the price list.
:::info
This section explains how the price selection strategy uses price lists when it determines the price of a product variant. If you want full details on how the price selection strategy works, check out this documentation instead.
This section explains how the [price selection strategy](../../references/price_selection/interfaces/price_selection.IPriceSelectionStrategy.mdx) uses price lists when it determines the price of a product variant. If you want full details on how the price selection strategy works, check out [this documentation](../../references/price_selection/interfaces/price_selection.IPriceSelectionStrategy.mdx) instead.
:::
@@ -59,7 +59,7 @@ When the strategy calculates the prices of a product variant, it retrieves both
The original price depends on the selected region or currency code in the current context, where the region has higher precedence.
The calculated price is the lowest price among all retrieved prices. Retrieved prices can include the original price and the price lists that can be applied. Prices are retrieved based on the [context](./price-selection-strategy.md#context-object).
The calculated price is the lowest price among all retrieved prices. Retrieved prices can include the original price and the price lists that can be applied. Prices are retrieved based on the provided context, such as region ID or currency code.
In the [Get Product](https://docs.medusajs.com/api/store#products_getproductsproduct) and [List Product](https://docs.medusajs.com/api/store#products_getproducts) API Routes, you must pass either the `region_id` or `currency_code` to retrieve the correct prices, as they are part of the price selection strategy context.
@@ -87,5 +87,5 @@ Since the line item belongs to a cart, there’s no need to pass the `region_id`
## See Also
- [Price Selection Strategy Overview](./price-selection-strategy.md)
- [Price Selection Strategy](../../references/price_selection/classes/price_selection.AbstractPriceSelectionStrategy.mdx)
- [Manage price lists using the admin APIs](./admin/manage-price-lists.mdx)
www/apps/docs/content/modules/price-lists/price-selection-strategy.md
-72
View File
@@ -1,72 +0,0 @@
---
description: 'Learn what the price selection strategy is in the Medusa backend. The price selection strategy retrieves the best price for a product variant for a specific context.'
---
# Price Selection Strategy
In this document, you’ll learn what a price selection strategy is.
:::note
If you’re interested to learn how to override the price selection strategy, check out [this documentation](./backend/override-price-selection-strategy.mdx) instead.
:::
## What's a Price Selection Strategy
Medusa provides many features and different ways to control the price of a product variant. This includes price lists and their different conditions, products’ original prices, and taxes.
Medusa uses the `PriceSelectionStrategy` class to retrieve the best price for a product variant for a specific context. This strategy is used whenever products and line items are retrieved or manipulated on the storefront.
---
## PriceSelectionStrategy Overview
The `PriceSelectionStrategy` class extends the `AbstractPriceSelectionStrategy` class. Its main method is the `calculateVariantPrice`.
### calculateVariantPrice Method
Medusa uses this method to retrieve one or more product variants' prices. This method is used when retrieving product variants or their associated line items. It's also used when retrieving other entities that product variants and line items belong to, such as products and carts respectively.
This method accepts two parameters:
1. The first parameter is an array of objects, each object having the following properties:
1. `variantId`: a string indicating the ID of the variant to calculate the price for.
2. `quantity`: an optional number indicating the quantity of the variant.
2. A [context](#context-object) object.
The method retrieves all the available prices of the variant based on the conditions in the context object.
It returns an object with the following properties:
1. `originalPrice`: The original price of the variant which depends on the selected region or currency code in the context object. If both region ID and currency code are available in the context object, the region has higher precedence.
2. `originalPriceIncludesTax`: A boolean value indicating whether the original price includes taxes or not. This is only available for [Tax-Inclusive Pricing](../taxes/inclusive-pricing.md).
3. `calculatedPrice`: The lowest price among the prices of the product variant retrieved using the context object.
4. `calculatedPriceIncludesTax`: A boolean value indicating whether the calculated price includes taxes or not. This is only available for [Tax-Inclusive Pricing](../taxes/inclusive-pricing.md).
5. `calculatedPriceType`: Either `default` if the `calculatedPrice` is the original price, or the type of the price list applied.
6. `prices`: an array of all the prices of the variant retrieved using the context object. It can include its original price and its price lists if there are any.
:::info
You can learn more about price lists and how they’re used in [this documentation](./price-lists.md).
:::
### Context Object
The context that is passed to the `calculateVariantPrice` method is an object that has the following optional properties:
- `cart_id`: A string indicating the ID of the customer’s cart. This is used when the prices are being retrieved for the variant of a line item, as it is used to determine the current region and currency code of the context.
- `customer_id`: A string indicating the ID of the customer. This is used to filter out price lists for a customer group that this customer doesn’t belong to.
- `quantity`: A number indicating the quantity of the item in the cart. This is used to filter out price lists that have `min_quantity` or `max_quantity` conditions set.
- `region_id`: A string indicating the ID of the region the customer is using.
- `currency_code`: A string indicating the currency code the customer is using.
- `include_discount_prices`: A boolean value indicating whether price list prices should be retrieved or not.
- `tax_rates`: An array of objects indicating the tax rates to be applied. This is only used for [Tax-Inclusive Pricing](../taxes/inclusive-pricing.md).
- `ignore_cache`: a boolean value indicating whether to calculate the prices even if the value of an earlier price calculation is available in the cache.
---
## See Also
- [Override the Price Selection Strategy](./backend/override-price-selection-strategy.mdx)