feat(core): Implement TaxLineCalculationStrategy

Relates to #307

packages/asset-server-plugin/e2e/graphql/generated-e2e-asset-server-plugin-types.ts

@@ -1553,7 +1553,7 @@ export type ProductVariant = Node & {
     assets: Array<Asset>;
     price: Scalars['Int'];
     currencyCode: CurrencyCode;
-    /** @deprecated price is now always exluding tax */
+    /** @deprecated price now always excludes tax */
     priceIncludesTax: Scalars['Boolean'];
     priceWithTax: Scalars['Int'];
     taxRateApplied: TaxRate;
@@ -3291,6 +3291,8 @@ export enum LanguageCode {
  * by taxRate.
  */
 export type OrderTaxSummary = {
+    /** A description of this tax */
+    description: Scalars['String'];
     /** The taxRate as a percentage */
     taxRate: Scalars['Float'];
     /** The total net price or OrderItems to which this taxRate applies */

packages/common/src/generated-shop-types.ts

@@ -1765,6 +1765,8 @@ export type OrderHistoryArgs = {
  */
 export type OrderTaxSummary = {
     __typename?: 'OrderTaxSummary';
+    /** A description of this tax */
+    description: Scalars['String'];
     /** The taxRate as a percentage */
     taxRate: Scalars['Float'];
     /** The total net price or OrderItems to which this taxRate applies */
@@ -2123,7 +2125,7 @@ export type ProductVariant = Node & {
     assets: Array<Asset>;
     price: Scalars['Int'];
     currencyCode: CurrencyCode;
-    /** @deprecated price is now always exluding tax */
+    /** @deprecated price now always excludes tax */
     priceIncludesTax: Scalars['Boolean'];
     priceWithTax: Scalars['Int'];
     taxRateApplied: TaxRate;

packages/common/src/generated-types.ts

@@ -1705,7 +1705,7 @@ export type ProductVariant = Node & {
   assets: Array<Asset>;
   price: Scalars['Int'];
   currencyCode: CurrencyCode;
-  /** @deprecated price is now always exluding tax */
+  /** @deprecated price now always excludes tax */
   priceIncludesTax: Scalars['Boolean'];
   priceWithTax: Scalars['Int'];
   taxRateApplied: TaxRate;
@@ -3493,6 +3493,8 @@ export enum LanguageCode {
  */
 export type OrderTaxSummary = {
   __typename?: 'OrderTaxSummary';
+  /** A description of this tax */
+  description: Scalars['String'];
   /** The taxRate as a percentage */
   taxRate: Scalars['Float'];
   /** The total net price or OrderItems to which this taxRate applies */

packages/core/e2e/graphql/generated-e2e-admin-types.ts

@@ -1553,7 +1553,7 @@ export type ProductVariant = Node & {
     assets: Array<Asset>;
     price: Scalars['Int'];
     currencyCode: CurrencyCode;
-    /** @deprecated price is now always exluding tax */
+    /** @deprecated price now always excludes tax */
     priceIncludesTax: Scalars['Boolean'];
     priceWithTax: Scalars['Int'];
     taxRateApplied: TaxRate;
@@ -3291,6 +3291,8 @@ export enum LanguageCode {
  * by taxRate.
  */
 export type OrderTaxSummary = {
+    /** A description of this tax */
+    description: Scalars['String'];
     /** The taxRate as a percentage */
     taxRate: Scalars['Float'];
     /** The total net price or OrderItems to which this taxRate applies */

packages/core/e2e/graphql/generated-e2e-shop-types.ts

@@ -1713,6 +1713,8 @@ export type OrderHistoryArgs = {
  * by taxRate.
  */
 export type OrderTaxSummary = {
+    /** A description of this tax */
+    description: Scalars['String'];
     /** The taxRate as a percentage */
     taxRate: Scalars['Float'];
     /** The total net price or OrderItems to which this taxRate applies */
@@ -2047,7 +2049,7 @@ export type ProductVariant = Node & {
     assets: Array<Asset>;
     price: Scalars['Int'];
     currencyCode: CurrencyCode;
-    /** @deprecated price is now always exluding tax */
+    /** @deprecated price now always excludes tax */
     priceIncludesTax: Scalars['Boolean'];
     priceWithTax: Scalars['Int'];
     taxRateApplied: TaxRate;
@@ -2829,7 +2831,7 @@ export type GetActiveOrderWithPriceDataQuery = {
                     taxLines: Array<Pick<TaxLine, 'taxRate' | 'description'>>;
                 }
             >;
-            taxSummary: Array<Pick<OrderTaxSummary, 'taxRate' | 'taxBase' | 'taxTotal'>>;
+            taxSummary: Array<Pick<OrderTaxSummary, 'description' | 'taxRate' | 'taxBase' | 'taxTotal'>>;
         }
     >;
 };

packages/core/e2e/graphql/shop-definitions.ts

@@ -338,6 +338,7 @@ export const GET_ACTIVE_ORDER_WITH_PRICE_DATA = gql`
                 }
             }
             taxSummary {
+                description
                 taxRate
                 taxBase
                 taxTotal

packages/core/e2e/order-taxes.e2e-spec.ts

@@ -159,16 +159,19 @@ describe('Order taxes', () => {
 
         expect(activeOrder?.taxSummary).toEqual([
             {
+                description: 'Standard Tax Europe',
                 taxRate: 20,
                 taxBase: 200,
                 taxTotal: 40,
             },
             {
+                description: 'Reduced Tax Europe',
                 taxRate: 10,
                 taxBase: 200,
                 taxTotal: 20,
             },
             {
+                description: 'Zero Tax Europe',
                 taxRate: 0,
                 taxBase: 200,
                 taxTotal: 0,

packages/core/src/api/schema/common/order.type.graphql

@@ -59,6 +59,8 @@ A summary of the taxes being applied to this order, grouped
 by taxRate.
 """
 type OrderTaxSummary {
+    "A description of this tax"
+    description: String!
     "The taxRate as a percentage"
     taxRate: Float!
     "The total net price or OrderItems to which this taxRate applies"

packages/core/src/config/config.service.ts

@@ -87,7 +87,7 @@ export class ConfigService implements VendureConfig {
         return this.activeConfig.paymentOptions;
     }
 
-    get taxOptions(): TaxOptions {
+    get taxOptions(): Required<TaxOptions> {
         return this.activeConfig.taxOptions;
     }
 

packages/core/src/config/default-config.ts

@@ -26,6 +26,7 @@ import { defaultPromotionActions, defaultPromotionConditions } from './promotion
 import { InMemorySessionCacheStrategy } from './session-cache/in-memory-session-cache-strategy';
 import { defaultShippingCalculator } from './shipping-method/default-shipping-calculator';
 import { defaultShippingEligibilityChecker } from './shipping-method/default-shipping-eligibility-checker';
+import { DefaultTaxLineCalculationStrategy } from './tax/default-tax-line-calculation-strategy';
 import { DefaultTaxZoneStrategy } from './tax/default-tax-zone-strategy';
 import { RuntimeVendureConfig } from './vendure-config';
 
@@ -118,6 +119,7 @@ export const defaultConfig: RuntimeVendureConfig = {
     },
     taxOptions: {
         taxZoneStrategy: new DefaultTaxZoneStrategy(),
+        taxLineCalculationStrategy: new DefaultTaxLineCalculationStrategy(),
     },
     importExportOptions: {
         importAssetsDir: __dirname,

packages/core/src/config/tax/default-tax-line-calculation-strategy.ts

@@ -0,0 +1,17 @@
+import { TaxLine } from '@vendure/common/lib/generated-types';
+
+import { CalculateTaxLinesArgs, TaxLineCalculationStrategy } from './tax-line-calculation-strategy';
+
+/**
+ * @description
+ * The default {@link TaxLineCalculationStrategy} which applies a single TaxLine to the OrderItem
+ * based on the applicable {@link TaxRate}.
+ *
+ * @docsCategory tax
+ */
+export class DefaultTaxLineCalculationStrategy implements TaxLineCalculationStrategy {
+    calculate(args: CalculateTaxLinesArgs): TaxLine[] {
+        const { orderItem, applicableTaxRate } = args;
+        return [applicableTaxRate.apply(orderItem.proratedUnitPrice)];
+    }
+}

packages/core/src/config/tax/tax-line-calculation-strategy.ts

@@ -0,0 +1,47 @@
+import { TaxLine } from '@vendure/common/lib/generated-types';
+
+import { RequestContext } from '../../api/common/request-context';
+import { InjectableStrategy } from '../../common/types/injectable-strategy';
+import { OrderItem } from '../../entity/order-item/order-item.entity';
+import { OrderLine } from '../../entity/order-line/order-line.entity';
+import { Order } from '../../entity/order/order.entity';
+import { TaxRate } from '../../entity/tax-rate/tax-rate.entity';
+
+/**
+ * @description
+ * This strategy defines how the TaxLines on OrderItems are calculated. By default,
+ * the {@link DefaultTaxLineCalculationStrategy} is used, which directly applies
+ * a single TaxLine based on the applicable {@link TaxRate}.
+ *
+ * However, custom strategies may use any suitable method for calculating TaxLines.
+ * For example, a third-party tax API or a lookup of a custom tax table may be used.
+ *
+ * @docsCategory tax
+ * @docsPage TaxLineCalculationStrategy
+ * @docsWeight 0
+ */
+export interface TaxLineCalculationStrategy extends InjectableStrategy {
+    /**
+     * @description
+     * This method is called when calculating the Order prices. Since it will be called
+     * whenever an Order is modified in some way (adding/removing items, applying promotions,
+     * setting ShippingMethod etc), care should be taken so that calling the function does
+     * not adversely impact overall performance. For example, by using caching and only
+     * calling external APIs when absolutely necessary.
+     */
+    calculate(args: CalculateTaxLinesArgs): TaxLine[] | Promise<TaxLine[]>;
+}
+
+/**
+ * @description
+ *
+ * @docsCategory tax
+ * @docsPage TaxLineCalculationStrategy
+ */
+export interface CalculateTaxLinesArgs {
+    ctx: RequestContext;
+    order: Order;
+    orderLine: OrderLine;
+    orderItem: OrderItem;
+    applicableTaxRate: TaxRate;
+}

packages/core/src/config/vendure-config.ts

@@ -31,6 +31,7 @@ import { PromotionCondition } from './promotion/promotion-condition';
 import { SessionCacheStrategy } from './session-cache/session-cache-strategy';
 import { ShippingCalculator } from './shipping-method/shipping-calculator';
 import { ShippingEligibilityChecker } from './shipping-method/shipping-eligibility-checker';
+import { TaxLineCalculationStrategy } from './tax/tax-line-calculation-strategy';
 import { TaxZoneStrategy } from './tax/tax-zone-strategy';
 
 /**
@@ -599,7 +600,14 @@ export interface TaxOptions {
      *
      * @default DefaultTaxZoneStrategy
      */
-    taxZoneStrategy: TaxZoneStrategy;
+    taxZoneStrategy?: TaxZoneStrategy;
+    /**
+     * @description
+     * Defines the strategy used to calculate the TaxLines added to OrderItems.
+     *
+     * @default DefaultTaxLineCalculationStrategy
+     */
+    taxLineCalculationStrategy?: TaxLineCalculationStrategy;
 }
 
 /**
@@ -840,6 +848,7 @@ export interface RuntimeVendureConfig extends Required<VendureConfig> {
     promotionOptions: Required<PromotionOptions>;
     shippingOptions: Required<ShippingOptions>;
     workerOptions: Required<WorkerOptions>;
+    taxOptions: Required<TaxOptions>;
 }
 
 type DeepPartialSimple<T> = {