@evenicanpm/storefront-core 1.0.0-alpha

package/README.md

@@ -0,0 +1,40 @@
+# @evenicanpm/storefront-core
+
+## Overview
+
+- this package should contain the internals of the storefront
+- the storefront should be a shell that implements all of the code in this package
+- there should be an exstensibility layer on the key components
+  - api-manager
+  - components
+  - etc
+
+## ApiManager Config
+
+- This package cannot depend on storefront, so config will live in
+  this package until we find a better/different solution for injecting the config from storefront dir
+
+## Build and Dependencies
+
+- this package is consumed and built by webpack as part of storefront build
+- it does not have it's own compile/build step
+- must have this package listed under `transpilePackages` in the storefront next.config.mjs
+- using `transpilePackages` keeps the @evenicanpm packages very lightweight and portable
+- during product dev this package is installed via local file url (symlink)
+- this means this packages dependencies are NOT installed, everything should be a peerDep
+  and then added to the storefront package.json as a dependency
+- there is a step in the `init.sh` script that will symlink the storefront node_modules to
+  the top-level of client packages - this ensures that the same versions of packages are used
+- this is required for packages such as `@tanstack/react-query` that require the same package
+  location to be used across the entire codebase
+
+## Misc
+
+- if at some point we want to start installing packages in this repo we will have to run an npm
+  install step in the `init.sh` of storefront
+
+## Next Steps
+
+- [ ] Remove dead packages from shared/studio
+- [ ] Clean up package.json in top-level client-packages
+- [ ] Clean up tests

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@evenicanpm/storefront-core",
+  "version": "1.0.0-alpha",
+  "description": "Core module for D365/e4 Headless Storefront",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./*": "./*"
+  },
+  "author": "Evenica",
+  "license": "ISC",
+  "dependencies": {
+    "@msdyn365-commerce/retail-proxy": "9.50",
+    "graphql": "^16.11.0",
+    "graphql-request": "^7.1.2",
+    "jsonwebtoken": "^9.0.2",
+    "lodash": "^4.17.21",
+    "object-mapper": "^6.2.0",
+    "zod": "^3.25.25"
+  },
+  "devDependencies": {
+    "@strapi/blocks-react-renderer": "^1.0.1",
+    "@types/jsonwebtoken": "^9.0.9",
+    "@types/lodash": "^4.17.17",
+    "@types/node": "^22.15.20",
+    "@types/object-mapper": "^6.2.2"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.76.1",
+    "next": "^15.2.1",
+    "next-auth": "^4.24.11",
+    "typescript": "^5.8.3"
+  }
+}

package/src/api-manager/README.md

@@ -0,0 +1,38 @@
+# Api Manager Package
+
+- All data fetching will originate from this layer
+- Eg. a server action will call the ApiManager to interact with external systems, api, etc.
+
+# Folders
+
+## Datasources
+
+- Datasource interface implementations - api manager loads multiple of these and then switches between
+
+## Schemas
+
+- input/output types for all datasource
+- D365 is base type, all other datasources should translate to this model
+
+## Core
+
+- Base classes and interfaces
+
+## Lib
+
+- Utilities and helpers that instantiate api manager etc.
+
+## Services
+
+- layer on top of react-query
+- a series of hooks used for react client components
+
+# Guide
+
+## Add a new method to the `ApiManager`
+
+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.`

package/src/api-manager/api-manager.config.json

@@ -0,0 +1,12 @@
+{
+  "primary": "e4",
+  "secondary": [],
+  "overrides": {},
+  "d365": {
+    "baseUrl": "https://scui1e8d9zn85030208-rs.su.retail.dynamics.com/",
+    "catalogId": 0,
+    "oun": "128",
+    "baseImageUrl": "https://images-us-prod.cms.commerce.dynamics.com/cms/api/lmrndcmtsl/imageFileData/search?fileName=/",
+    "channelId": 68719478279
+  }
+}

package/src/api-manager/datasources/README.md

@@ -0,0 +1,17 @@
+# Data Sources
+
+- Contains all data sources, translators and interfaces that are consumed by the ApiManager
+- Currently the datasource implementation is responsible for translation and validation before handing data back to the ApiManager
+
+## File Naming
+
+- `<datasourceName>.datasource.ts` is used for datasources.
+- `<datasourceName>.translator.ts` is used for translation layers.
+
+## Data Access Layer Nextjs
+
+https://nextjs.org/blog/security-nextjs-server-components-actions#data-access-layer
+
+- NextJS recommends doing auth inside the data access layer as well as on routes
+- This provides optimal data security.
+- We should extend the Datasources or the Apimanager to check auth/access during data retrieval.

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

@@ -0,0 +1,141 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { AddressApi } from "@/api-manager/types/Datasource";
+import {
+  CountryRegionInfo,
+  DeliveryOption,
+  FilterDeliveryModeOption,
+  StateProvinceInfo,
+} from "@msdyn365-commerce/retail-proxy";
+import { getDeliveryOptionsAsync } from "@msdyn365-commerce/retail-proxy/dist/DataActions/CartsDataActions.g";
+import {
+  getCountryRegionsByLanguageIdAsync,
+  getStateProvincesAsync,
+} from "@msdyn365-commerce/retail-proxy/dist/DataActions/StoreOperationsDataActions.g";
+import {
+  Address,
+  GetCountriesInput,
+  GetDeliveryOptionsInput,
+  GetStatesInput,
+} from "@/schemas/address.schema";
+import { getContextFromCookie } from "./utils/get-context-cookie";
+import {
+  readAsync,
+  updateAsync,
+} from "@msdyn365-commerce/retail-proxy/dist/DataActions/CustomersDataActions.g";
+import { D365DatasourceBase } from "./d365-base.datasource";
+class D365AddressDatasource extends D365DatasourceBase implements AddressApi {
+  async createAddress(address: Address): Promise<Address> {
+    const context = await getContextFromCookie();
+    const customer = await readAsync(context as any, "");
+    const accountNumber = customer.AccountNumber;
+
+    const prevAddresses = customer.Addresses ?? [];
+    customer.Addresses = [...prevAddresses, address as any];
+
+    const updatedCustomer = await updateAsync(context as any, {
+      ...customer,
+      AccountNumber: accountNumber,
+    });
+
+    const added = updatedCustomer.Addresses?.find((a) =>
+      prevAddresses.every((old) => old.RecordId !== a.RecordId),
+    );
+    if (!added || added.RecordId == null) {
+      throw new Error("Failed to create new address");
+    }
+
+    return {
+      ...added,
+      Id: added.RecordId.toString(),
+    };
+  }
+
+  async updateAddress(address: Address): Promise<Address> {
+    const context = await getContextFromCookie();
+    const customer = await readAsync(context as any, "");
+    customer.Addresses = customer.Addresses ?? [];
+
+    const idx = customer.Addresses.findIndex(
+      (a) => a.RecordId?.toString() === address.Id,
+    );
+    const updatedRecord = { ...(address as any) };
+
+    if (idx >= 0) {
+      customer.Addresses[idx] = {
+        ...customer.Addresses[idx],
+        ...updatedRecord,
+      };
+    } else {
+      customer.Addresses.push(updatedRecord);
+    }
+
+    const updatedCustomer = await updateAsync(context as any, customer);
+    const rec = updatedCustomer.Addresses?.find(
+      (a) => a.RecordId?.toString() === address.Id,
+    );
+    if (!rec || rec.RecordId == null) {
+      throw new Error(`Failed to update address Id=${address.Id}`);
+    }
+
+    return {
+      ...rec,
+      Id: rec.RecordId.toString(),
+    };
+  }
+
+  async deleteAddress(addressId: string): Promise<string> {
+    const context = await getContextFromCookie();
+    const customer = await readAsync(context as any, "");
+    customer.Addresses = customer.Addresses ?? [];
+
+    const rec = customer.Addresses.find(
+      (a) => a.RecordId?.toString() === addressId,
+    );
+    if (rec) {
+      rec.Deactivate = true;
+      await updateAsync(context as any, customer);
+    }
+
+    return addressId;
+  }
+
+  async getCountries(input: GetCountriesInput): Promise<CountryRegionInfo[]> {
+    const context = await getContextFromCookie();
+    const locale = input.locale ?? context.requestContext.locale;
+    if (!locale) {
+      throw new Error("Locale is required to fetch countries");
+    }
+
+    return getCountryRegionsByLanguageIdAsync(context as any, locale);
+  }
+
+  async getStates(input: GetStatesInput): Promise<StateProvinceInfo[]> {
+    const context = await getContextFromCookie();
+    if (!input.countryId) {
+      throw new Error("countryId is required to fetch states");
+    }
+
+    return getStateProvincesAsync(context as any, input.countryId);
+  }
+
+  async getDeliveryOptions(
+    input: GetDeliveryOptionsInput,
+  ): Promise<DeliveryOption[]> {
+    const context = await getContextFromCookie();
+    try {
+      return getDeliveryOptionsAsync(
+        context as any,
+        input.cartId,
+        input.shippingAddress,
+        input.cartLineIds,
+        FilterDeliveryModeOption.FilterOutNonCarrierDeliveryMode,
+        false,
+      );
+    } catch (err) {
+      console.error("getDeliveryOptions error:", err);
+      return [];
+    }
+  }
+}
+
+export default D365AddressDatasource;

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

@@ -0,0 +1,8 @@
+import { ICallerContext } from "@msdyn365-commerce/retail-proxy";
+
+export abstract class D365DatasourceBase {
+  context: ICallerContext;
+  constructor(context: ICallerContext) {
+    this.context = context;
+  }
+}

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

@@ -0,0 +1,374 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import { CartApi } from "@/api-manager/types/Datasource";
+import {
+  CartType,
+  Cart as DynCart,
+  CardPaymentAcceptPoint,
+  CardPaymentAcceptSettings,
+  CardPaymentAcceptResult,
+  // SalesOrder,
+  CartTenderLine,
+  QueryResultSettings,
+  CartSearchCriteria,
+  ICallerContext,
+  CartLine,
+} from "@msdyn365-commerce/retail-proxy";
+import {
+  addCartLinesAsync,
+  createCartAsync,
+  readAsync,
+  removeCartLinesAsync,
+  updateCartLinesAsync,
+  updateAsync,
+  addDiscountCodeAsync,
+  removeDiscountCodesAsync,
+  updateLineDeliverySpecificationsAsync,
+  getCardPaymentAcceptPointAsync,
+  retrieveCardPaymentAcceptResultAsync,
+  checkoutAsync,
+  searchAsync,
+} from "@msdyn365-commerce/retail-proxy/dist/DataActions/CartsDataActions.g";
+import {
+  ManageDiscountCodeInput,
+  AddToCartInput,
+  Cart,
+  DeleteCartLineInput,
+  UpdateCartInput,
+  UpdateCartLineInput,
+  UpdateCartLineDeliveryModeInput,
+  RemoveCartLineDeliveryModeInput,
+  GetCardPaymentAcceptPointInput,
+  RetrieveCardPaymentAcceptResultInput,
+  CheckoutInput,
+} from "@/schemas/cart.schema";
+import { uniq, omit } from "lodash";
+import { D365ProductDatasource } from "./d365-product.datasource";
+import pojo from "./utils/parse-object";
+import { getCartCookie } from "@/lib/cart-cookie-handler";
+import { SalesOrder } from "@/schemas/order.schema";
+import { D365DatasourceBase } from "./d365-base.datasource";
+
+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],
+    );
+  }
+  async retrieveCardPaymentAcceptResult(
+    input: RetrieveCardPaymentAcceptResultInput,
+  ): Promise<CardPaymentAcceptResult> {
+    const context = this.context;
+    const { cartId, resultAccessCode, settings } = input;
+    return pojo(
+      retrieveCardPaymentAcceptResultAsync(
+        context as any,
+        resultAccessCode,
+        [],
+        cartId,
+        settings,
+      ),
+    );
+  }
+  async getCardAcceptPoint(
+    input: GetCardPaymentAcceptPointInput,
+  ): Promise<CardPaymentAcceptPoint> {
+    const context = this.context;
+    const { totalAmount, hideBillingAddress, origin } = input;
+    const paymentAcceptSettings: CardPaymentAcceptSettings = {
+      AdaptorPath:
+        (typeof window !== "undefined" && `${origin}/Connectors`) || undefined,
+      CardPaymentEnabled: true,
+      CardTokenizationEnabled: true,
+      HideBillingAddress: hideBillingAddress || false,
+      HostPageOrigin: origin || "",
+      PaymentAmount: totalAmount,
+    };
+    try {
+      const data = await getCardPaymentAcceptPointAsync(
+        context as any,
+        input.cartId,
+        paymentAcceptSettings,
+      );
+
+      return pojo(data);
+    } catch (error) {
+      console.warn(error);
+      return {};
+    }
+  }
+  async updateLineDeliveryMode(
+    input: UpdateCartLineDeliveryModeInput,
+  ): Promise<Cart> {
+    const context = this.context;
+    const { cartId, cartLineDeliverySpecification } = input;
+    const cart = await updateLineDeliverySpecificationsAsync(
+      context as any,
+      cartId,
+      cartLineDeliverySpecification,
+    );
+    return await mergeCartWithProducts(cart, this.context);
+  }
+  async removeLineDeliveryMode(
+    input: RemoveCartLineDeliveryModeInput,
+  ): Promise<Cart> {
+    const context = this.context;
+    // Get Address from cart input
+    const newCart = { ...input.cart };
+    // Remove Address and ShippingMethodId from cart lines
+    newCart.CartLines?.forEach((line) => {
+      line.DeliveryMode = "";
+      line.ShippingAddress = {};
+      line.Product = undefined;
+    });
+
+    // Update cartlines to remove the delivery mode
+    const cartWithoutDeliveryMode = await updateCartLinesAsync(
+      context as any,
+      String(newCart?.Id),
+      newCart?.CartLines,
+      newCart?.Version,
+    );
+
+    //Call update cart from this class with the address.
+    return this.updateCart({
+      cart: {
+        ...cartWithoutDeliveryMode,
+        ShippingAddress: newCart.ShippingAddress,
+      },
+    });
+  }
+
+  async removeDiscountcode(input: ManageDiscountCodeInput) {
+    const context = this.context;
+    if (!input.cartId) {
+      throw new Error("CartId is required to remove a discount code");
+    }
+    const cart = await removeDiscountCodesAsync(context as any, input.cartId, [
+      input.discountCode,
+    ]);
+    return await mergeCartWithProducts(cart, this.context);
+  }
+  async addDiscountCode(input: ManageDiscountCodeInput): Promise<Cart> {
+    const context = this.context;
+    const { discountCode, cartId } = input;
+    if (!cartId) {
+      throw new Error("CartId is required to add a discount code");
+    }
+    const cart = await addDiscountCodeAsync(
+      context as any,
+      cartId,
+      discountCode,
+    );
+    return await mergeCartWithProducts(cart, this.context);
+  }
+  async updateCartLine(input: UpdateCartLineInput): Promise<Cart> {
+    const context = this.context;
+    const { cartId, cartLine, version } = input;
+    if (!version || !cartId) {
+      throw new Error("CartId and Version are required to update a cart line");
+    }
+    const cartLinesWithoutProduct = cartLine.map((line) =>
+      omit(line, "Product"),
+    );
+    const cart = await updateCartLinesAsync(
+      context as any,
+      cartId,
+      cartLinesWithoutProduct,
+      version,
+    );
+    return await mergeCartWithProducts(cart, this.context);
+  }
+  async addToCart(input: AddToCartInput): Promise<Cart> {
+    const context = this.context;
+    const { cartId, cartLine, version } = input;
+    if (!version || !cartId) {
+      throw new Error("CartId and Version are required to add a cart line");
+    }
+    const _cartLines = cartLine.map((line) => omit(line, "Product"));
+    try {
+      const updatedCart = await addCartLinesAsync(
+        context as any,
+        cartId,
+        _cartLines,
+        version,
+      );
+      return await mergeCartWithProducts(updatedCart, this.context);
+    } catch (err) {
+      console.error(err);
+      throw new Error("Error adding to cart: " + JSON.stringify(err));
+    }
+  }
+  async updateCart(input: UpdateCartInput): Promise<Cart> {
+    const context = this.context;
+    const { cart } = input;
+    if (cart.CartLines) {
+      cart.CartLines.map((cl) => omit(cl, "Product"));
+    }
+    const updatedCart = await updateAsync(context as any, <DynCart>cart);
+    return await mergeCartWithProducts(updatedCart, this.context);
+  }
+  async deleteCartLine(input: DeleteCartLineInput): Promise<Cart> {
+    const context = this.context;
+    const { cartLine, cartId } = input;
+    const cartLineIds = cartLine
+      .map((line) => line.LineId)
+      .filter((id) => id !== undefined);
+    if (!cartId) {
+      throw new Error("CartId and Version are required to delete a cart line");
+    }
+    const cart = await removeCartLinesAsync(
+      context as any,
+      cartId,
+      cartLineIds,
+    );
+    return await mergeCartWithProducts(cart, this.context);
+  }
+
+  async getCart(input: { cartId: string }): Promise<Cart> {
+    const context = this.context;
+    const id = input?.cartId ?? (await getCartCookie());
+    let cart: DynCart;
+
+    if (!id) {
+      return this.createCart(context);
+    } else {
+      cart = (await readAsync(context as any, id)) as DynCart;
+      if (!cart) {
+        return this.createCart(context);
+      }
+      return await mergeCartWithProducts(cart, this.context);
+    }
+  }
+
+  async updateCartLines(input: UpdateCartLineInput): Promise<Cart> {
+    const context = this.context;
+    const { cartId, cartLine, version } = input;
+    if (!version || !cartId) {
+      throw new Error("CartId and Version are required to update a cart line");
+    }
+    const cartLinesWithoutProduct = cartLine.map((line) =>
+      omit(line, "Product"),
+    );
+    const cart = await updateCartLinesAsync(
+      context as any,
+      cartId,
+      cartLinesWithoutProduct,
+      version,
+    );
+    await mergeCartWithProducts(cart, this.context);
+    return <Cart>cart;
+  }
+
+  /**
+   * Merges guest and user carts, only needs to be done if authenticated
+   * @returns A cart object with products attached
+   */
+  async initCart(): Promise<Cart> {
+    const context = this.context;
+    const cartId = await getCartCookie();
+
+    const isAuthenticated =
+      context.requestContext.user.isAuthenticated &&
+      !!context.requestContext.user.token;
+
+    if (isAuthenticated) {
+      // Attempt to find the user's existing cart
+      const foundCart = await this.getUsersCart(context);
+      if (foundCart) {
+        // If the cookie cart differs from the found cart, remerge lines
+        if (cartId && foundCart.Id !== cartId) {
+          // Retrieve the old (guest) cart using the provided cartId
+          const oldCart = await this.getCart({ cartId });
+          if (oldCart && oldCart.CartLines?.length > 0) {
+            const cartLines: CartLine[] =
+              oldCart.CartLines.map((line) => ({
+                Quantity: line.Quantity,
+                ProductId: line.ProductId,
+                UnitOfMeasureSymbol: line.UnitOfMeasureSymbol,
+              })) || [];
+            await this.addToCart({
+              cartId: foundCart.Id,
+              cartLine: cartLines,
+              version: foundCart.Version,
+            });
+          }
+        }
+        return mergeCartWithProducts(foundCart, this.context);
+      }
+    }
+
+    // If not authenticated or no found cart, fall back to reading/creating the cookie cart
+    return await this.getCart({ cartId: cartId || "" });
+  }
+
+  async createCart(context: ICallerContext): Promise<Cart> {
+    return (await createCartAsync(context as any, <DynCart>{
+      CartTypeValue: CartType.Checkout,
+    })) as Cart;
+  }
+
+  async getUsersCart(context: ICallerContext): Promise<DynCart | undefined> {
+    const queryResultSettings: QueryResultSettings = {
+      Paging: { Top: 1, Skip: 0 },
+      Sorting: {
+        Columns: [
+          {
+            ColumnName: "ModifiedDateTime",
+            IsDescending: true,
+          },
+        ],
+      },
+    };
+    const searchCriteria: CartSearchCriteria = {
+      CartTypeValue: CartType.Checkout,
+      IncludeAnonymous: false,
+    };
+    const ctx = { ...context } as any;
+    ctx.queryResultSettings = queryResultSettings;
+    const cartResult = await searchAsync(ctx, searchCriteria);
+    return cartResult[0];
+  }
+}
+
+const mergeCartWithProducts = async (
+  cart: DynCart,
+  context: ICallerContext,
+): Promise<Cart> => {
+  const _cart = { ...cart } as Cart;
+  if (_cart.CartLines?.length) {
+    //Get products
+    const productIds = _cart.CartLines.map((line) => line.ProductId).filter(
+      (p) => p !== undefined,
+    );
+    if (productIds.length) {
+      const productDataSource = new D365ProductDatasource(context);
+      const products = await productDataSource.getProductByIds({
+        id: uniq(productIds),
+      });
+      if (products) {
+        _cart.CartLines.forEach((line) => {
+          const product = products.find((p) => p.RecordId === line.ProductId);
+          if (product) {
+            line.Product = product;
+          }
+        });
+      }
+    }
+  }
+  return cart as Cart;
+};