@evenicanpm/storefront-core 2.1.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@evenicanpm/storefront-core",
-	"version": "2.1.0",
+	"version": "2.3.0",
 	"description": "Core module for D365/e4 Headless Storefront",
 	"type": "module",
 	"scripts": {
@@ -16,7 +16,9 @@
 	"author": "Evenica",
 	"license": "ISC",
 	"dependencies": {
-		"@evenicanpm/ui": "^2.0.0"
+		"@evenicanpm/cms": "^2.3.0",
+		"@evenicanpm/ui": "^2.0.0",
+		"strapi-sdk-js": "^3.0.0"
 	},
 	"devDependencies": {
 		"@storybook/addon-docs": "^9.1.6",
@@ -31,14 +33,17 @@
 	},
 	"peerDependencies": {
 		"@msdyn365-commerce/retail-proxy": "9.50",
+		"@opentelemetry/api": "^1.9.1",
+		"@strapi/blocks-react-renderer": "^1.0.1",
 		"@tanstack/react-query": "^5.76.1",
+		"better-auth": "*",
 		"graphql": "^16.11.0",
 		"graphql-request": "^7.1.2",
 		"jsonwebtoken": "^9.0.2",
 		"lodash": "^4.17.21",
 		"next": "^15.2.1",
-		"next-auth": "^4.24.11",
 		"object-mapper": "^6.2.0",
+		"set-cookie-parser": "^2.7.1",
 		"typedoc": "^0.28.9",
 		"typedoc-plugin-merge-modules": "^7.0.0",
 		"typescript": "^5.8.3",
@@ -49,5 +54,5 @@
 			"esbuild": "0.19.11"
 		}
 	},
-	"gitHead": "8227589295d3d63586f9b26fff8d643b070989b3"
+	"gitHead": "72bf1aeb02a3d96c587706c0d91606698e38ff6a"
 }

package/src/api-manager/README.md

@@ -1,46 +1,71 @@
 # Api Manager
 
-- All data fetching will originate from this layer
+All data fetching originates from this layer. `createApiManager()` selects the active datasource and applies any project-level overrides before returning it.
 
-## User Guide
+## Selecting a Primary Datasource
 
-### 1. Setup the Api Manager config file
+Set the `API_MANAGER_PRIMARY` environment variable to control which datasource is used. Defaults to `"e4"` when unset.
 
-1. Add a `@api-manager-config` webpack alias in your storefront next.config.js
-
-```js
-"@api-manager-config": path.resolve(
-  process.cwd(),
-  "api-manager.config.ts",
-)
+```env
+API_MANAGER_PRIMARY=e4   # default
+API_MANAGER_PRIMARY=d365
 ```
 
-2. Create a JS file that exports the config object as the default.
-3. Storefront-core will read this alias when creating api manager.
+## Project-Level Overrides
+
+Projects can override individual methods on any datasource entity without replacing the entire datasource. This allows mixing custom logic with the default implementation.
+
+### How it works
+
+`createApiManager()` loads `src/extensions/api-manager-overrides/overrides.datasource.ts` via webpack's `require.context` (using the `@storefront` alias). Any methods exported from that file are merged on top of the selected datasource's entity methods.
+
+### Setup
+
+Create or edit `src/extensions/api-manager-overrides/overrides.datasource.ts` in your storefront project:
 
-### 2. Add a new method to the `ApiManager`
+```ts
+import type { SecondaryDatasource } from "@evenicanpm/storefront-core/src/api-manager/types/Datasource";
 
-1. If the entity does not have a `entity.model.ts` file in `src/app/data-access/models`, add one and create schemas for input types eg. `addToCartInput`
-2. Add usecase to `data-access/Datasource.ts` interface
-3. Add the same usecase to `data-access/ApiManager.ts` class methods
-4. Finally, add method to the relevant data source, eg. `/src/app/data-access/datasources/E4.datasource.ts`
-5. You are now able to call the method from the `ApiManager.`
+const Overrides: SecondaryDatasource = {
+  categories: {
+    getCategories: async () => {
+      // custom implementation — replaces only this method
+      return myCustomCategories();
+    },
+  },
+};
+
+export default Overrides;
+```
+
+### Rules
+
+- Only the methods you define in `Overrides` are replaced. All other methods continue to use the primary datasource.
+- You can override methods on any core entity: `user`, `session`, `cart`, `product`, `categories`, `order`, `address`, `organization`, `invoice`.
+- You can also add entirely new non-core entities by including them in the `Overrides` object.
+- The file must use `export default` — named exports are ignored.
 
 ## Folder Structure
 
-### Datasources
+### `datasources/`
+
+Implementations for each supported backend (`e4`, `d365`).
+
+### `types/`
 
-- External API's
+- `Datasource` — abstract base class; defines the shape all datasources must implement.
+- `PrimaryDatasource` — alias for `Datasource`; all methods required.
+- `SecondaryDatasource` — `Partial<Datasource>`; use this type for override objects.
+- `DatasourceApis` — interface defining all entity API contracts.
 
-### Schemas
+### `schemas/`
 
-- input/output types for all datasource
-- D365 is base type, all other datasources should translate to this model
+Input/output types for all datasource methods. D365 types are the canonical model; other datasources translate to this shape.
 
-### Lib
+### `lib/`
 
-- Utilities and helpers that instantiate api manager etc.
+Utilities and helpers (e.g. category tree builders).
 
-### Services
+### `services/`
 
-- React-query **cache** layer
+React-query cache layer — sits above the api-manager.

package/src/api-manager/datasources/d365/d365-cart.datasource.ts

@@ -1,5 +1,35 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+
+function serializeError(error: unknown): string {
+	if (error instanceof Error) return error.message;
+	if (typeof error === "string") return error;
+	try {
+		return JSON.stringify(error, (_key, value) => {
+			if (value === null || typeof value !== "object") return value;
+			const allKeys = new Set<string>();
+			let proto = value;
+			while (proto && proto !== Object.prototype) {
+				Object.getOwnPropertyNames(proto).forEach((k) => allKeys.add(k));
+				proto = Object.getPrototypeOf(proto);
+			}
+			Object.keys(value).forEach((k) => allKeys.add(k));
+			const result: Record<string, unknown> = {};
+			for (const key of allKeys) {
+				if (key !== "constructor") {
+					try {
+						result[key] = (value as any)[key];
+					} catch {}
+				}
+			}
+			return Object.keys(result).length ? result : value;
+		});
+	} catch {
+		return String(error);
+	}
+}
+
 import { D365DatasourceBase } from "@evenicanpm/storefront-core/src/api-manager/datasources/d365/d365-base.datasource";
 import D365OrganizationDatasource from "@evenicanpm/storefront-core/src/api-manager/datasources/d365/d365-organization.datasource";
 import { D365ProductDatasource } from "@evenicanpm/storefront-core/src/api-manager/datasources/d365/d365-product.datasource";
@@ -24,6 +54,7 @@ import {
 import {
 	addCartLinesAsync,
 	addDiscountCodeAsync,
+	addInvoicesAsync,
 	checkoutAsync,
 	createCartAsync,
 	getCardPaymentAcceptPointAsync,
@@ -32,6 +63,7 @@ import {
 	removeDiscountCodesAsync,
 	retrieveCardPaymentAcceptResultAsync,
 	searchAsync,
+	setInvoiceLinePriceAsync,
 	updateAsync,
 	updateCartLinesAsync,
 	updateLineDeliverySpecificationsAsync,
@@ -54,28 +86,76 @@ import type {
 	UpdateCartInput,
 	UpdateCartLineDeliveryModeInput,
 	UpdateCartLineInput,
+	UpdateInvoiceLineInput,
 } from "@/schemas/cart.schema";
 import type { SalesOrder } from "@/schemas/order.schema";
 
 export class D365CartDatasource extends D365DatasourceBase implements CartApi {
 	async checkout(input: CheckoutInput): Promise<SalesOrder> {
-		const context = this.context;
-		const { currency, amount, tokenizedPaymentCard } = input;
-		const cartTenderLine: CartTenderLine = {
-			Currency: currency,
-			Amount: amount,
-			TenderTypeId: tokenizedPaymentCard.TenderType,
-			CardTypeId: tokenizedPaymentCard.CardTypeId,
-			TokenizedPaymentCard: tokenizedPaymentCard,
-		};
-		return await checkoutAsync(
-			context as any,
-			input.id,
-			input.receiptEmail,
-			undefined,
-			undefined,
-			[cartTenderLine],
-		);
+		const tracer = trace.getTracer("d365-cart");
+		return tracer.startActiveSpan("d365.cart.checkout", async (span) => {
+			span.setAttributes({
+				"cart.id": input.id,
+				"cart.receipt_email": input.receiptEmail ?? "",
+				"cart.currency": input.currency,
+				"cart.amount": input.amount,
+				"cart.payment_method": input.paymentMethod ?? "card",
+				"cart.tender_type":
+					input.tokenizedPaymentCard?.TenderType ?? "on-account",
+			});
+			try {
+				const context = this.context;
+				const { currency, amount, paymentMethod } = input;
+
+				let cartTenderLines: CartTenderLine[];
+				if (paymentMethod === "on-account") {
+					cartTenderLines = [
+						{
+							Currency: currency,
+							Amount: amount,
+							TenderTypeId: "4",
+						} as CartTenderLine,
+					];
+				} else {
+					const { tokenizedPaymentCard } = input;
+					if (!tokenizedPaymentCard) {
+						throw new Error(
+							"tokenizedPaymentCard is required for card payments",
+						);
+					}
+					cartTenderLines = [
+						{
+							Currency: currency,
+							Amount: amount,
+							TenderTypeId: tokenizedPaymentCard.TenderType,
+							CardTypeId: tokenizedPaymentCard.CardTypeId,
+							TokenizedPaymentCard: tokenizedPaymentCard,
+						},
+					];
+				}
+
+				const result = await checkoutAsync(
+					context as any,
+					input.id,
+					input.receiptEmail,
+					undefined,
+					undefined,
+					cartTenderLines,
+				);
+				span.setStatus({ code: SpanStatusCode.OK });
+				return result;
+			} catch (error) {
+				const message = serializeError(error);
+				span.setStatus({ code: SpanStatusCode.ERROR, message });
+				span.recordException(
+					error instanceof Error ? error : new Error(message),
+				);
+				span.setAttributes({ "error.message": message });
+				throw error;
+			} finally {
+				span.end();
+			}
+		});
 	}
 	async retrieveCardPaymentAcceptResult(
 		input: RetrieveCardPaymentAcceptResultInput,
@@ -440,6 +520,75 @@ export class D365CartDatasource extends D365DatasourceBase implements CartApi {
 		}
 		return {};
 	}
+
+	async addInvoicesToCart(
+		cart: Readonly<Cart>,
+		invoiceIds: string[],
+	): Promise<Cart> {
+		const context = this.context;
+
+		if (!cart.Version || !cart.Id) {
+			throw new Error("CartId and Version are required to add a cart line");
+		}
+
+		if (cart.Version) {
+			try {
+				const updatedCart = await addInvoicesAsync(
+					context as any,
+					cart.Id,
+					invoiceIds,
+				);
+
+				return updatedCart as Cart;
+			} catch (error) {
+				console.error("Error adding invoices to cart:", {
+					cartId: cart.Id,
+					invoiceIds,
+					error,
+				});
+				throw new Error(
+					`Unable to add invoices to cart: ${JSON.stringify(error)}`,
+				);
+			}
+		}
+		throw new Error("Cart version is required to add invoices to cart");
+	}
+
+	async setInvoiceLinePrice(input: UpdateInvoiceLineInput): Promise<Cart> {
+		const context = this.context;
+
+		if (!input.cartId || !input.cartLineId) {
+			throw new Error(
+				"CartId and CartLineId are required to set invoice line price",
+			);
+		}
+
+		if (input.cartId) {
+			try {
+				const updatedCart = await setInvoiceLinePriceAsync(
+					context as any,
+					input.cartId,
+					input.cartLineId,
+					input.price,
+					input.version,
+				);
+				return updatedCart as Cart;
+			} catch (error) {
+				console.error("Error setting invoice line price:", {
+					cartId: input.cartId,
+					cartLineId: input.cartLineId,
+					price: input.price,
+					error,
+				});
+				throw new Error(
+					`Unable to set invoice line price: ${JSON.stringify(error)}`,
+				);
+			}
+		}
+		throw new Error(
+			"CartId and CartLineId are required to set invoice line price",
+		);
+	}
 }
 
 const mergeCartWithProducts = async (

package/src/api-manager/datasources/d365/d365-invoice.datasource.ts

@@ -0,0 +1,100 @@
+import { D365DatasourceBase } from "@evenicanpm/storefront-core/src/api-manager/datasources/d365/d365-base.datasource";
+import type {
+	GetInvoicesDetailsInput,
+	GetInvoicesInput,
+	Invoice,
+	InvoiceDetails,
+	InvoiceDetailsSearchCriteria,
+	InvoiceSearchCriteria,
+} from "@evenicanpm/storefront-core/src/api-manager/schemas/invoice.schema";
+import type { InvoiceApi } from "@evenicanpm/storefront-core/src/api-manager/types/Datasource";
+import {
+	getInvoiceDetailsAsync,
+	getInvoicesAsync,
+} from "@msdyn365-commerce/retail-proxy/dist/DataActions/SalesOrdersDataActions.g";
+import type { IContext } from "@msdyn365-commerce/retail-proxy/dist/Interfaces/ICallerContext";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+
+const tracer = trace.getTracer("d365-invoice-datasource");
+
+/**
+ * Datasource for fetching invoice data from Dynamics 365. Implements the InvoiceApi interface.
+ * Uses the retail proxy's data actions to retrieve invoice information based on search criteria.
+ * Handles errors gracefully and logs them for debugging purposes.
+ */
+class D365InvoiceDatasource extends D365DatasourceBase implements InvoiceApi {
+	/**
+	 * Fetches a list of invoices based on the provided search criteria. Supports filtering by invoice IDs, customer ID, business partner ID, invoice type, and paid status.
+	 * Utilizes OpenTelemetry for tracing the execution of the method, including logging attributes and handling errors.
+	 * @param input The input containing the search criteria for fetching invoices.
+	 * @returns A promise that resolves to an array of invoices matching the search criteria.
+	 */
+	async getInvoices(input: GetInvoicesInput): Promise<Invoice[]> {
+		return tracer.startActiveSpan("d365.getInvoices", async (span) => {
+			try {
+				const context = this.context;
+
+				const invoiceSearchCriteria: InvoiceSearchCriteria = {
+					InvoiceIds: input.InvoiceSearchCriteria.InvoiceIds,
+					CustomerId: input.InvoiceSearchCriteria.CustomerId,
+					BusinessPartnerId: input.InvoiceSearchCriteria.BusinessPartnerId,
+					InvoiceTypeValues: input.InvoiceSearchCriteria.InvoiceTypeValues,
+					InvoicePaidStatusValues:
+						input.InvoiceSearchCriteria.InvoicePaidStatusValues,
+				};
+				span.setAttributes({
+					"d365.invoice.customer_id":
+						input.InvoiceSearchCriteria.CustomerId ?? "",
+					"d365.invoice.business_partner_id":
+						input.InvoiceSearchCriteria.BusinessPartnerId ?? "",
+					"d365.invoice.paid_status_filter": JSON.stringify(
+						input.InvoiceSearchCriteria.InvoicePaidStatusValues ?? [],
+					),
+				});
+
+				const invoices = await getInvoicesAsync(
+					context as unknown as IContext,
+					invoiceSearchCriteria,
+				);
+				// Retail proxy returns ObservableArray — normalize to plain array
+				const result = Array.from(invoices ?? []) as Invoice[];
+
+				span.setAttributes({ "d365.invoice.result_count": result.length });
+				span.setStatus({ code: SpanStatusCode.OK });
+				return result;
+			} catch (error) {
+				const message =
+					error instanceof Error ? error.message : JSON.stringify(error);
+				span.setStatus({ code: SpanStatusCode.ERROR, message });
+				span.recordException(
+					error instanceof Error ? error : new Error(message),
+				);
+				throw new Error(`getInvoices failed: ${message}`);
+			} finally {
+				span.end();
+			}
+		});
+	}
+
+	async getInvoiceDetails(
+		input: GetInvoicesDetailsInput,
+	): Promise<InvoiceDetails> {
+		try {
+			const context = this.context;
+			const invoiceSearchCriteria: InvoiceDetailsSearchCriteria = {
+				InvoiceId: input.InvoiceSearchCriteria.InvoiceId,
+			};
+			const invoices = await getInvoiceDetailsAsync(
+				context as unknown as IContext,
+				invoiceSearchCriteria,
+			);
+
+			return invoices;
+		} catch (error) {
+			console.error("Error fetching invoice details:", error);
+			throw error;
+		}
+	}
+}
+
+export default D365InvoiceDatasource;

package/src/api-manager/datasources/d365/d365-order.datasource.ts

@@ -1,42 +1,99 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
 import { D365DatasourceBase } from "@evenicanpm/storefront-core/src/api-manager/datasources/d365/d365-base.datasource";
 import { D365ProductDatasource } from "@evenicanpm/storefront-core/src/api-manager/datasources/d365/d365-product.datasource";
 import type {
 	GetSalesOrderDetailsInput,
+	GetSalesOrdersInput,
 	SalesOrder,
-	SalesOrderInput,
 } from "@evenicanpm/storefront-core/src/api-manager/schemas/order.schema";
 import type { OrderApi } from "@evenicanpm/storefront-core/src/api-manager/types/Datasource";
 import {
+	CustomerOrderType,
 	type SalesOrder as DynSalesOrder,
 	type ICallerContext,
+	type OrderSearchCriteria,
+	type QueryResultSettings,
 	SearchLocation,
 } from "@msdyn365-commerce/retail-proxy";
-import { getSalesOrderDetailsByTransactionIdAsync } from "@msdyn365-commerce/retail-proxy/dist/DataActions/SalesOrdersDataActions.g";
-import type { IContext } from "@msdyn365-commerce/retail-proxy/dist/Interfaces/ICallerContext";
+import { readAsync } from "@msdyn365-commerce/retail-proxy/dist/DataActions/CustomersDataActions.g";
+import {
+	getSalesOrderDetailsBySalesIdAsync,
+	getSalesOrderDetailsByTransactionIdAsync,
+	searchOrdersAsync,
+} from "@msdyn365-commerce/retail-proxy/dist/DataActions/SalesOrdersDataActions.g";
 import uniq from "lodash/uniq";
+import { getContextFromCookie } from "./utils/get-context-cookie";
 
 class D365OrderDatasource extends D365DatasourceBase implements OrderApi {
-	getSalesOrders(_input: SalesOrderInput): Promise<SalesOrder[]> {
-		throw new Error("Method not implemented.");
-	}
-	async getSalesOrderDetails(
-		input: GetSalesOrderDetailsInput,
-	): Promise<SalesOrder> {
-		const context = this.context;
-		const { transactionId } = input;
+	getSalesOrders = async (
+		input: GetSalesOrdersInput,
+	): Promise<SalesOrder[]> => {
+		const context = await getContextFromCookie();
+		const customer = await readAsync(context as any, "");
+
+		const searchCriteria: OrderSearchCriteria = {
+			...input.orderSearchCriteria,
+			OrderType: CustomerOrderType.SalesOrder,
+			CustomerAccountNumber: customer.AccountNumber,
+		};
+
+		const queryResultSettings: QueryResultSettings = {};
+		if (input.paging) queryResultSettings.Paging = input.paging;
+		if (input.sort)
+			queryResultSettings.Sorting = {
+				Columns: [input.sort],
+			};
+
+		(context as any).queryResultSettings = queryResultSettings;
+
 		try {
-			const data = await getSalesOrderDetailsByTransactionIdAsync(
-				context as unknown as IContext,
-				transactionId,
-				SearchLocation.All,
+			const searchOrdersResults = await searchOrdersAsync(
+				context as any,
+				searchCriteria,
+				null,
 			);
-			const mergedData = await mergeOrderWithProducts(data, this.context);
-			return mergedData;
+
+			return searchOrdersResults;
 		} catch (error) {
 			console.error(error);
 			throw error;
 		}
-	}
+	};
+
+	getSalesOrderDetails = async (
+		input: GetSalesOrderDetailsInput,
+	): Promise<SalesOrder> => {
+		const context = await getContextFromCookie();
+		const { transactionId, salesId } = input;
+		if (!transactionId && !salesId) throw new Error("No id provided");
+
+		let data: DynSalesOrder;
+		if (transactionId) {
+			try {
+				data = await getSalesOrderDetailsByTransactionIdAsync(
+					context as any,
+					transactionId,
+					SearchLocation.All,
+				);
+			} catch (error) {
+				console.error(error);
+				throw error;
+			}
+		} else {
+			try {
+				data = await getSalesOrderDetailsBySalesIdAsync(
+					context as any,
+					salesId,
+				);
+			} catch (error) {
+				console.error(error);
+				throw error;
+			}
+		}
+		const mergedData = await mergeOrderWithProducts(data, context);
+		return mergedData;
+	};
 }
 
 const mergeOrderWithProducts = async (

package/src/api-manager/datasources/d365/d365-product.datasource.ts

@@ -234,9 +234,27 @@ class D365ProductDatasource extends D365DatasourceBase implements ProductApi {
 			}));
 		}
 		const observableResults = await searchByCriteriaAsync(ctx, searchCriteria);
-		const results: ProductSearchResult[] = Array.from(
+		let results: ProductSearchResult[] = Array.from(
 			observableResults as Iterable<ProductSearchResult>,
 		);
+
+		// If no results found by ItemId and the values are numeric, retry by product RecordId
+		if (!results.length && input.itemIds?.length) {
+			const numericIds = input.itemIds
+				.filter((id) => /^\d+$/.test(id))
+				.map(Number);
+			if (numericIds.length) {
+				const idSearchCriteria: ProductSearchCriteria = {
+					Context: {
+						CatalogId: 0,
+						ChannelId: context.requestContext.apiSettings.channelId,
+					},
+					Ids: numericIds,
+				};
+				const idResults = await searchByCriteriaAsync(ctx, idSearchCriteria);
+				results = Array.from(idResults as Iterable<ProductSearchResult>);
+			}
+		}
 		const promises = [];
 		for (const product of results) {
 			promises.push(