@evenicanpm/storefront-core 1.0.2 → 1.0.4

package/docs.tsconfig.json

@@ -0,0 +1,35 @@
+{
+  "compilerOptions": {
+    "target": "ES6",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "sourceMap": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "outDir": "./dist",
+    "jsx": "preserve",
+    "baseUrl": "./",
+    "paths": {
+      "@/lib/*": ["src/lib/*"],
+      "@/api-manager/*": ["src/api-manager/*"],
+      "@/auth/*": ["src/auth/*"],
+      "@/_components/*": ["src/components/_components/*"],
+      "@/components/*": ["src/components/*"],
+      "@/cms/*": ["src/cms/*"],
+      "@/schemas/*": ["src/api-manager/schemas/*"],
+      "@/services/*": ["src/api-manager/services/*"],
+      "@/hooks/*": ["src/hooks/*"],
+      "@config": ["src/config"]
+    }
+  },
+  "include": [
+    "src/components-v2/product-dimensions",
+    "src/components-v2/product-quantity-buttons",
+    "src/components-v2/products-view",
+    "src/components-v2/search-bar",
+    "src/components-v2/section"
+  ]
+}

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@evenicanpm/storefront-core",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Core module for D365/e4 Headless Storefront",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "docs": "typedoc"
   },
   "exports": {
     ".": "./index.js",
@@ -31,7 +32,9 @@
     "@tanstack/react-query": "^5.76.1",
     "next": "^15.2.1",
     "next-auth": "^4.24.11",
+    "object-mapper": "^6.2.0",
     "typescript": "^5.8.3",
-    "object-mapper": "^6.2.0"
+    "typedoc": "^0.28.9",
+    "typedoc-plugin-merge-module": "^7.0.0"
   }
 }

package/src/api-manager/README.md

@@ -1,38 +1,46 @@
-# Api Manager Package
+# Api Manager
 
 - All data fetching will originate from this layer
-- Eg. a server action will call the ApiManager to interact with external systems, api, etc.
 
-# Folders
+## User Guide
 
-## Datasources
+### 1. Setup the Api Manager config file
 
-- Datasource interface implementations - api manager loads multiple of these and then switches between
+1. Add a `@api-manager-config` webpack alias in your storefront next.config.js
 
-## Schemas
+```js
+"@api-manager-config": path.resolve(
+  process.cwd(),
+  "api-manager.config.ts",
+)
+```
 
-- input/output types for all datasource
-- D365 is base type, all other datasources should translate to this model
+2. Create a JS file that exports the config object as the default.
+3. Storefront-core will read this alias when creating api manager.
 
-## Core
+### 2. Add a new method to the `ApiManager`
 
-- Base classes and interfaces
+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.`
 
-## Lib
+## Folder Structure
 
-- Utilities and helpers that instantiate api manager etc.
+### Datasources
+
+- External API's
 
-## Services
+### Schemas
 
-- layer on top of react-query
-- a series of hooks used for react client components
+- input/output types for all datasource
+- D365 is base type, all other datasources should translate to this model
 
-# Guide
+### Lib
 
-## Add a new method to the `ApiManager`
+- Utilities and helpers that instantiate api manager etc.
 
-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.`
+### Services
+
+- React-query **cache** layer

package/src/api-manager/datasources/e4/{e4-address.datasource.ts → address/e4-address.datasource.ts}

@@ -1,4 +1,4 @@
-import getGraphqlClient from "../../lib/get-graphql-client";
+import getGraphqlClient from "../../../lib/get-graphql-client";
 import {
   Address,
   GetDeliveryOptionsInput,
@@ -9,9 +9,9 @@ import {
   DeliveryOption,
   StateProvinceInfo,
 } from "@msdyn365-commerce/retail-proxy";
-import { Shipping } from "./graphqlRequestSdk";
-import * as translator from "./e4.translator";
-import { addressMap } from "./e4.remaps";
+import { Shipping } from "../graphqlRequestSdk";
+import * as addressTranslator from "./e4-address.translator";
+import { addressMap } from "./e4-address.remaps";
 import { merge } from "object-mapper";
 
 const address = {
@@ -22,12 +22,12 @@ const address = {
       throw new Error("Error getting countries");
     }
 
-    return translator.countriesTransformValidate(data?.countries ?? []);
+    return addressTranslator.countriesTransformValidate(data?.countries ?? []);
   },
   async getStates(input: GetStatesInput): Promise<StateProvinceInfo[]> {
     const e4Api = await getGraphqlClient();
     const { data, errors } = await e4Api.e4Country({
-      id: (await translator.getCountryId(input?.countryId || "")) ?? "",
+      id: (await addressTranslator.getCountryId(input?.countryId || "")) ?? "",
     });
     if (errors) {
       throw new Error("Error getting states");
@@ -40,7 +40,7 @@ const address = {
       isoAlpha3Code: "",
       state: [],
     };
-    const result = translator.countryTransformValidate(countryData);
+    const result = addressTranslator.countryTransformValidate(countryData);
     return Array.isArray(result) ? result : [];
   },
   async getDeliveryOptions(
@@ -56,13 +56,13 @@ const address = {
       throw new Error("Error getting shipping methods");
     }
 
-    return translator.deliveryOptionsTransformValidate(
+    return addressTranslator.deliveryOptionsTransformValidate(
       (data?.shippingbyCarrier as Shipping[]) ?? [],
     ) as DeliveryOption[];
   },
   async createAddress(address: Address): Promise<Address> {
     const e4Api = await getGraphqlClient(true);
-    const e4Address = await translator.addressTransform(address);
+    const e4Address = await addressTranslator.addressTransform(address);
     const { data, errors } = await e4Api.e4AddressCreate({
       address: e4Address,
     });
@@ -79,7 +79,7 @@ const address = {
   },
   async updateAddress(address: Address): Promise<Address> {
     const e4Api = await getGraphqlClient(true);
-    const e4Address = await translator.addressTransform(address);
+    const e4Address = await addressTranslator.addressTransform(address);
     const { data, errors } = await e4Api.e4AddressUpdate({
       address: e4Address,
     });

package/src/api-manager/datasources/e4/address/e4-address.remaps.ts

@@ -0,0 +1,70 @@
+/**
+ * Maps E4 API responses to the D365 data structure.
+ *
+ * This file uses the `object-mapper` library to transform
+ * API responses into a format compatible with D365.
+ *
+ * https://github.com/wankdanker/node-object-mapper
+ *
+ */
+import { Address as E4Address } from "../graphqlRequestSdk";
+import { Address } from "@msdyn365-commerce/retail-proxy";
+
+export const addressMap = {
+  "[].id": [
+    { key: "[].Id" },
+    {
+      key: "[].RecordId",
+      transform: (id: string) => {
+        if (id !== null) return parseInt(id);
+      },
+    },
+  ],
+  "[].name": "[].Name",
+  "[].isPrimary": "[].IsPrimary",
+  "[].addressType.id": {
+    key: "[].AddressTypeValue",
+    transform: (id: string) => {
+      if (id !== null) return parseInt(id);
+    },
+  },
+  "[].address1": "[].Street",
+  "[].city": "[].City",
+  "[].stateName": "[].State",
+  "[].countryName": "[].ThreeLetterISORegionName",
+  "[].postalCode": "[].ZipCode",
+  "[].phoneNumber": "[].Phone",
+  "[].address2": {
+    key: "[].FullAddress",
+    transform: (_val: string, _src: E4Address[], dest: Address) => {
+      return `${dest?.Street}, ${dest?.City} ${dest?.State} ${dest?.ZipCode}, ${dest?.ThreeLetterISORegionName}`;
+    },
+  },
+};
+
+export const addressReverseMap = {
+  Name: "name",
+  Street: "address1",
+  City: "city",
+  ZipCode: "postalCode",
+  Phone: "phoneNumber",
+  Id: "id",
+};
+
+export const countriesMap = {
+  isoAlpha3Code: "CountryRegionId",
+  isoAlpha2Code: "ISOCode",
+  name: "ShortName",
+};
+
+export const countryMap = {
+  "state[].code": "[].StateId",
+  "state[].name": "[].StateName",
+  isoAlpha3Code: "[].CountryRegionId",
+};
+
+export const deliveryOptionsMap = {
+  id: ["Code", "RecordId"],
+  name: "Description",
+  total: "TotalChargeAmount",
+};

package/src/api-manager/datasources/e4/address/e4-address.translator.ts

@@ -0,0 +1,98 @@
+import getGraphqlClient from "../../../lib/get-graphql-client";
+import { AddressInput, Country, Shipping } from "../graphqlRequestSdk";
+import { Address } from "@/api-manager/schemas/address.schema";
+import { merge } from "object-mapper";
+import {
+  addressReverseMap,
+  countriesMap,
+  countryMap,
+  deliveryOptionsMap,
+} from "./e4-address.remaps";
+
+/**
+ * Transforms the Address schema to e4 API address
+ */
+export const addressTransform = async (address: Address) => {
+  const countryId = await getCountryId(address?.ThreeLetterISORegionName ?? "");
+  const stateId = await getStateId(address?.State ?? "", countryId ?? "");
+
+  const formattedAddress: AddressInput = merge(address, addressReverseMap);
+  formattedAddress.firstName = "";
+  formattedAddress.lastName = "";
+  formattedAddress.address2 = "";
+  formattedAddress.stateId = stateId;
+  formattedAddress.countryId = countryId;
+  formattedAddress.addressTypeId = 1; // We only create and update shipping addresses.
+
+  return formattedAddress;
+};
+
+const countriesCache = new Map<string, Country[]>();
+const countryCache = new Map<string, Country>();
+
+/**
+ * For d365 country id and value are 'USA' but for e4 it is '80175021088166' and 'USA'.
+ * So use countryId, to map the codes back to ids before API calls.
+ */
+export const getCountryId = async (code: string) => {
+  const cacheKey = "countries";
+  let countries: Country[] = [];
+
+  if (countriesCache.has(cacheKey)) {
+    countries = countriesCache.get(cacheKey) ?? countries;
+  } else {
+    const e4Api = await getGraphqlClient();
+    const { data } = await e4Api.e4CountryList();
+    countriesCache.set(cacheKey, data?.countries as Country[]);
+    countries = data?.countries as Country[];
+  }
+  const country = countries.find(
+    (c: { isoAlpha3Code: string }) => c?.isoAlpha3Code === code,
+  );
+
+  return country?.id;
+};
+
+const getStateId = async (stateCode: string, countryId: string) => {
+  const cacheKey = `states-${countryId}`;
+  let country: Country = {
+    id: "",
+    isoAlpha2Code: "",
+    isoAlpha3Code: "",
+    name: "",
+  };
+
+  if (countryCache.has(cacheKey)) {
+    country = countryCache.get(cacheKey) ?? country;
+  } else {
+    const e4Api = await getGraphqlClient();
+    const { data } = await e4Api.e4Country({ id: countryId });
+    country = data?.country as Country;
+    countryCache.set(cacheKey, country);
+  }
+
+  const state = country?.state?.find((s) => s?.code === stateCode);
+
+  return state?.id;
+};
+
+export const countriesTransformValidate = (countries: Country[]) => {
+  if (Array.isArray(countries) && countries.length) {
+    return countries.map((country) => merge(country, countriesMap));
+  }
+  return [];
+};
+
+export const countryTransformValidate = (country: Country) => {
+  if (country?.state && country?.state.length) {
+    return merge(country, countryMap);
+  }
+  return [];
+};
+
+export const deliveryOptionsTransformValidate = (options: Shipping[]) => {
+  if (Array.isArray(options) && options.length) {
+    return options.map((option) => merge(option, deliveryOptionsMap));
+  }
+  return [];
+};

package/src/api-manager/datasources/e4/{e4-cart.datasource.ts → cart/e4-cart.datasource.ts}

@@ -1,7 +1,8 @@
-import getGraphqlClient from "../../lib/get-graphql-client";
-import * as cartSchema from "../../schemas/cart.schema";
-import { Cart } from "../../schemas/cart.schema";
-import * as translator from "./e4.translator";
+import getGraphqlClient from "../../../lib/get-graphql-client";
+import * as cartSchema from "../../../schemas/cart.schema";
+import { Cart } from "../../../schemas/cart.schema";
+import * as cartTranslator from "./e4-cart.translator";
+import * as addressTranslator from "../address/e4-address.translator";
 
 import {
   CardPaymentAcceptPoint,
@@ -9,8 +10,8 @@ import {
   LineDeliverySpecification,
   ProductWarehouseInventoryInformation,
 } from "@msdyn365-commerce/retail-proxy";
-import { CartApi } from "../../types/Datasource";
-import { Cart as E4Cart } from "./graphqlRequestSdk";
+import { CartApi } from "../../../types/Datasource";
+import { Cart as E4Cart } from "../graphqlRequestSdk";
 import { SalesOrder } from "@/api-manager/schemas/order.schema";
 
 const cart: CartApi = {
@@ -24,7 +25,7 @@ const cart: CartApi = {
       throw new Error("Error reading cart");
     }
 
-    const transformedData = translator.cartTransformValidate(
+    const transformedData = cartTranslator.cartTransformValidate(
       data?.cart as E4Cart,
     );
     return transformedData;
@@ -47,7 +48,7 @@ const cart: CartApi = {
       throw new Error("Error adding to cart");
     }
 
-    const transformedData = translator.cartTransformValidate(
+    const transformedData = cartTranslator.cartTransformValidate(
       data?.addToCart?.cart as E4Cart,
     );
     return transformedData;
@@ -73,7 +74,7 @@ const cart: CartApi = {
     if (cart.ShippingAddress) {
       const address = cart.ShippingAddress;
       const createAddress = await e4Api.e4CreateCartAddress({
-        address: await translator.addressTransform(address),
+        address: await addressTranslator.addressTransform(address),
       });
 
       if (createAddress.errors) {
@@ -89,7 +90,7 @@ const cart: CartApi = {
       throw new Error("Error getting cart information");
     }
 
-    const transformedData = translator.cartTransformValidate(
+    const transformedData = cartTranslator.cartTransformValidate(
       data?.cart as E4Cart,
     );
     return transformedData;
@@ -118,7 +119,7 @@ const cart: CartApi = {
       cart = data.updateCartLine;
     }
 
-    const transformedData = translator.cartTransformValidate(
+    const transformedData = cartTranslator.cartTransformValidate(
       cart?.cart as E4Cart,
     );
     return transformedData;
@@ -142,7 +143,7 @@ const cart: CartApi = {
       throw new Error("Error updating cart");
     }
 
-    const transformedData = translator.cartTransformValidate(
+    const transformedData = cartTranslator.cartTransformValidate(
       data?.deleteCartLine?.cart as E4Cart,
     );
     return transformedData;
@@ -157,7 +158,7 @@ const cart: CartApi = {
       throw new Error("Error reading cart");
     }
 
-    const transformedData = translator.cartTransformValidate(
+    const transformedData = cartTranslator.cartTransformValidate(
       data?.cart as E4Cart,
     );
     return transformedData;
@@ -192,7 +193,7 @@ const cart: CartApi = {
       );
     }
 
-    return translator.cartTransformValidate(
+    return cartTranslator.cartTransformValidate(
       data?.setOrderShipping?.cart as E4Cart,
     );
   },
@@ -244,11 +245,11 @@ const cart: CartApi = {
       SalesLines: [],
     };
   },
-  getCartLinesInventory: function(
+  getCartLinesInventory: function (
     _input: cartSchema.InventorySearchCartLinesCriteriaInput,
   ): Promise<ProductWarehouseInventoryInformation> {
     throw new Error("Function not implemented.");
   },
 };
 
-export { cart };
+export default cart;

package/src/api-manager/datasources/e4/cart/e4-cart.remaps.ts

@@ -0,0 +1,94 @@
+/**
+ * Maps E4 API responses to the D365 data structure.
+ *
+ * This file uses the `object-mapper` library to transform
+ * API responses into a format compatible with D365.
+ *
+ * https://github.com/wankdanker/node-object-mapper
+ *
+ */
+import {
+  Address,
+  Product as DynProduct,
+} from "@msdyn365-commerce/retail-proxy";
+import { Product, CartLine, Address as E4Address } from "../graphqlRequestSdk";
+import { merge } from "object-mapper";
+import { productMap } from "../product/e4-product.remaps";
+import { addressMap } from "../address/e4-address.remaps";
+
+/* CART REMAPS */
+export const cartLineMap = {
+  "[].product": {
+    key: "[].Product?",
+    transform: (product: Product) => {
+      // If cart is empty, prevents CartLines[] from having entries
+      if (!product) return;
+
+      // For some reason transform is run multiple times. This prevents merge from running multiple times and overwriting translation.
+      const translated = merge(product, productMap) as DynProduct & {
+        ProductTypeValue?: number;
+      };
+      if (!translated.RecordId) return product;
+      translated.ProductTypeValue = 4; // default for now. Type = Standalone
+      return translated;
+    },
+  },
+  "[].id": "[].LineId",
+  "[].product.id": {
+    key: "[].ProductId",
+    transform: (id: string) => {
+      if (id !== null) return parseInt(id);
+    },
+  },
+  "[].product.code": "[].ItemId",
+  "[].product.name": "[].Product.Name",
+  "[].quantity": "[].Quantity",
+  "[].price": [
+    { key: "[].Price", default: 0 },
+    { key: "[].Product.Price", default: 0 },
+    { key: "[].Product.BasePrice", default: 0 },
+    { key: "[].Product.AdjustedPrice", default: 0 },
+  ],
+  "[].amount": [{ key: "[].TotalAmount" }, { key: "[].NetPrice" }],
+  "[].uom.name": {
+    key: "[].UnitOfMeasureSymbol",
+    transform: (name: string) => {
+      if (name !== null) {
+        if (name === "Each") return "ea";
+        return name;
+      }
+    },
+  },
+  "[].product.productType": {
+    key: "[].Product.ProductTypeValue",
+    default: 4,
+  },
+};
+
+export const cartMap = {
+  id: "Id",
+  itemCount: "TotalItems",
+
+  lines: {
+    key: "CartLines",
+    transform: (lines: CartLine[]) => {
+      if (lines.length === 0) return [];
+      return merge(lines, cartLineMap);
+    },
+  },
+
+  subtotal: "SubtotalAmountWithoutTax",
+  freightTotal: "ShippingChargeAmount",
+  taxTotal: "TaxAmount",
+  total: "TotalAmount",
+  email: "ReceiptEmail",
+
+  addresses: {
+    key: "ShippingAddress",
+    transform: (addresses: E4Address[]) => {
+      if (addresses.length === 0) return undefined;
+      const translated = merge(addresses, addressMap) as Address[];
+      return translated[addresses.length - 1];
+    },
+  },
+};

package/src/api-manager/datasources/e4/cart/e4-cart.translator.ts

@@ -0,0 +1,23 @@
+import { extendedCartSchema, Cart } from "@/api-manager/schemas/cart.schema";
+import { Cart as E4Cart } from "../graphqlRequestSdk";
+import { cartMap } from "./e4-cart.remaps";
+import { merge } from "object-mapper";
+
+/**
+ * Transforms the E4 AddToCart response to a Cart retail-proxy object
+ * Add parameters to transform model as needed
+ *
+ * @param data the E4 Cart object
+ * @returns the transformed cart object
+ */
+export const cartTransformValidate = (cart: E4Cart): Cart => {
+  if (!(cart && cart?.id)) throw new Error("Not a valid cart");
+  const transformedData = merge(cart, cartMap);
+  try {
+    extendedCartSchema.parse(transformedData);
+  } catch (e) {
+    console.warn("Cart data does not match retail-proxy schema", e);
+  }
+
+  return transformedData as Cart;
+};

package/src/api-manager/datasources/e4/categories/e4-categories.datasource.ts

@@ -0,0 +1,38 @@
+import getGraphqlClient from "@/api-manager/lib/get-graphql-client";
+import { CategoryHierarchy } from "@/lib/category-helpers";
+import { CategoryApi } from "@/api-manager/types/Datasource";
+import { Category as E4Category } from "../graphqlRequestSdk";
+import * as categoryTranslator from "./e4-categories.translator";
+
+const categories: CategoryApi = {
+  async getCategories(): Promise<CategoryHierarchy[]> {
+    const e4Api = await getGraphqlClient();
+    const { data: rawApiResult, errors } = await e4Api.categories();
+
+    if (errors) {
+      console.error(
+        "GraphQL errors reading categories (in categories.getCategories):",
+        errors,
+      );
+      throw new Error("Error getting categories");
+    }
+
+    const rawCategoryArray = rawApiResult?.categories?.category;
+
+    if (!Array.isArray(rawCategoryArray)) {
+      console.warn(
+        "Categories data at expected path not found or not an array in categories.getCategories:",
+        rawApiResult,
+      );
+      return [];
+    }
+
+    const transformedHierarchicalData =
+      categoryTranslator.categoryTransformValidate(
+        rawApiResult?.categories?.category as E4Category[],
+      );
+    return transformedHierarchicalData;
+  },
+};
+
+export default categories;