@vsf-enterprise/unified-api-magento
5.0.0ri:link
Minor Changesri:link
FEATURE
- placeOrder unified API method: Added
placeOrder
method to the unified API for Magento.
CHANGED
- placeOrder response structure: The
placeOrder
method now returns detailed order information using theorderV2
field instead of the basicorder
field. Update your code to access order data fromresponse.data.placeOrder.orderV2
instead ofresponse.data.placeOrder.order
- magento schema updated: Updated Magento GraphQL schema from 2.4.6 to 2.4.8, which may introduce new types and fields or modify existing ones.
- magento-sdk: Is now using the
middlewareModule
from@alokai/connect/sdk
and become a Proxy SDK module to align with recent architecture changes.
Patch Changesri:link
- FIXED Aligned Unified API with Magento@2.4.8.
- Updated dependencies:
- @vsf-enterprise/magento-types@4.0.0
- @vsf-enterprise/magento-api@8.0.0
4.0.0ri:link
Major Changesri:link
- CHANGED Guarantee compatibility with
@alokai/connect
package. - CHANGED Updated the package for compatibility with Node.js 22.
Key Updates:ri:link
- Upgraded to the latest version of Node.js 22
- Updated CI pipelines to use Node.js 22 for consistency.
- Updated
.nvmrc
or.node-version
files to specify Node.js version22.14
. - Upgraded
@types/node
to version^22.13.17
for compatibility with the latest Node.js features.
Recommendations:ri:link
- Use Node.js version
22.14.0
or higher for optimal performance, security, and compatibility. - While Node.js 20 is technically supported, it is not recommended as it may cause compatibility issues with certain packages and has not been thoroughly tested.
CHANGED Replaced core dependencies with a new
@alokai/connect
package.@vue-storefront/middleware
,@vue-storefront/sdk
,vue-storefront/logger
,vue-storefront/unified-data-model
,@vue-storefront/multistore
were replaced with@alokai/connect
. The replacement preserves the same functionality and interface as the original packages. To read more about the@alokai/connect
package, please refer to the documentation.
Patch Changesri:link
- CHANGED The unified
setCartAddress
method now resolvesregion
andregion_id
from the receivedshippingAddress
argument and passes them on to Magento API. - Updated dependencies:
- @vsf-enterprise/magento-api@7.0.0
- @alokai/connect@1.0.0
- @vsf-enterprise/magento-types@3.0.0
4.0.0-rc.6ri:link
Patch Changesri:link
- CHANGED The unified
setCartAddress
method now resolvesregion
andregion_id
from the receivedshippingAddress
argument and passes them on to Magento API.
4.0.0-rc.5ri:link
Patch Changesri:link
- Updated dependencies:
- @alokai/connect@1.0.0-rc.4
- @vsf-enterprise/magento-api@7.0.0-rc.5
4.0.0-rc.4ri:link
Major Changesri:link
- CHANGED Updated the package for compatibility with Node.js 22.
Key Updates:ri:link
- Upgraded to the latest version of Node.js 22
- Updated CI pipelines to use Node.js 22 for consistency.
- Updated
.nvmrc
or.node-version
files to specify Node.js version22.14
. - Upgraded
@types/node
to version^22.13.17
for compatibility with the latest Node.js features.
Recommendations:ri:link
- Use Node.js version
22.14.0
or higher for optimal performance, security, and compatibility. - While Node.js 20 is technically supported, it is not recommended as it may cause compatibility issues with certain packages and has not been thoroughly tested.
Patch Changesri:link
- Updated dependencies:
- @vsf-enterprise/magento-types@3.0.0-rc.0
- @vsf-enterprise/magento-api@7.0.0-rc.4
- @alokai/connect@1.0.0-rc.3
4.0.0-rc.3ri:link
Patch Changesri:link
- Updated dependencies:
- @alokai/connect@1.0.0-rc.2
- @vsf-enterprise/magento-api@7.0.0-rc.3
4.0.0-rc.2ri:link
Patch Changesri:link
- Updated dependencies:
- @alokai/connect@1.0.0-rc.1
- @vsf-enterprise/magento-api@7.0.0-rc.2
4.0.0-rc.1ri:link
Major Changesri:link
Update packages to work with connect rc version
Patch Changesri:link
- Updated dependencies:
- @vsf-enterprise/magento-api@7.0.0-rc.1
- @alokai/connect@1.0.0-rc.0
4.0.0-rc.0ri:link
Major Changesri:link
Replace legacy packages with a connect package
3.0.1ri:link
Patch Changesri:link
- CHANGED - update @vsf-enterprise/sdk package to 3.4.1
3.0.0ri:link
Major Changesri:link
Update the middleware to 5.1.0
2.1.2ri:link
Patch Changesri:link
- FIXED: Added the missing utils: slugify, maybe, graphqlTypeGuardFactory
2.1.1ri:link
Patch Changesri:link
- FIXED Re-export unified-data-model methods after accidental removal.
2.1.0ri:link
Minor Changesri:link
- ADDED: Refactored
NormalizerContext
to be an interface. Now you can use declaration merging to extend theNormalizerContext
typings when you're usingassignToNormalizerContext
function.
import {
assignToNormalizerContext,
getNormalizers,
} from "@vue-storefront/unified-api-<integration>";
declare module "@vue-storefront/unified-api-<integration>" {
interface NormalizerContext {
sku?: string;
}
}
async function getProduct(context, args) {
const product = await context.api.getProduct({ id: productId.id });
const { normalizeProduct } = getNormalizers(context);
assignToNormalizerContext(context, {
sku: product.sku,
});
return normalizeProduct(product);
}
Patch Changesri:link
- ADDED re-export SfContract from unified-data-model
2.0.1ri:link
Patch Changesri:link
- FIXED order normalizer will no longer throw error if there are no products in the order
- FIXED: Types used in API methods are now available at dedicated export from this package -
@vsf-enterprise/unified-api-magento/ecommerceTypes
. Also types used by normalizers are grouped together and exported:import { NormalizerTypes } from "@vsf-enterpise/unified-api-magento"
. All helpers used by API methods are also available to import directly from package.
2.0.0ri:link
Major Changesri:link
- BREAKING Updated peerDependencies:
@vue-storefront/middleware
version to^4.0.0
.@vsf-enterprise/magento-api
version to^5.0.0
.@vsf-enterprise/magento-types
version to^2.0.0
.
Make sure this versions are used in your project.
{
...
"dependencies": {
- "@vsf-enterprise/magento-api": "3.x.x",
+ "@vsf-enterprise/magento-api": "5.0.0",
- "@vsf-enterprise/magento-types": "1.x.x",
+ "@vsf-enterprise/magento-types": "2.0.0",
- "@vue-storefront/middleware": "3.x.x",
+ "@vue-storefront/middleware": "4.2.0"
}
}
1.0.1ri:link
Patch Changesri:link
- CHANGED Upgrade
@vue-storefront/magento-api
to thev.3.1.1
and@vue-storefront/magento-types
to thev.1.2.0
.
1.0.0ri:link
Major Changesri:link
The version v1.0.0
of @vsf-enterprise/unified-api-[commerce]
packages brings the following changes:
- ✨ Simplified the extension initialization
- 🛠️ A new
addCustomFields
API which simplifies adding custom fields to the normalizers - ⚠️ Deprecation of the
unifiedSdk
- 🔄 Redefined a way to add custom methods
- 🔍 New utilities such as
defineNormalizer
which allow you to override the normalizer with the inferred typed of the raw data
Migrationri:link
If you are interested in migrating to the new version, check the Migration guide page.
Simplified the extension initializationri:link
There is no need to pass the generics to the createUnifiedExtension
, nor to pass the default normalizers and methods. Now all of them are built into the extension.
In examples, we are using sapcc package. Remember to replace it with the name of the commerce you are using.
- import {
- Config,
- Context,
- createUnifiedExtension,
- methods,
- normalizers,
- } from "@vsf-enterprise/unified-api-sapcc";
+ import { createUnifiedExtension } from "@vsf-enterprise/unified-api-sapcc";
- export const unifiedApiExtension = createUnifiedExtension<Context, Config>()({
- normalizers,
- apiMethods: {
- ...apiMethods,
- },
+ export const unifiedApiExtension = createUnifiedExtension({
+ normalizers: {
+ addCustomFields: [{}],
+ },
config: {
...
},
});
addCustomFields
APIri:link
The addCustomFields
API allows you to add custom fields to the normalizers. The defineNormalizers
utility have been removed and replaced with this API.
Before:
import { normalizers as normalizersSAP, defineNormalizers } from "@vsf-enterprise/unified-api-sapcc";
const normalizersSAP = defineNormalizers<typeof normalizersSAP>()({
...normalizersSAP,
normalizeProductCatalogItem: (rawProduct) => ({
...normalizersSAP.normalizeProductCatalogItem(product, context),
description: rawProduct.description,
}),
});
export const unifiedApiExtension = createUnifiedExtension<Context, Config>()({
normalizers,
apiMethods: {
...apiMethods,
},
config: {
...
}
});
Now:
export const unifiedApiExtension = createUnifiedExtension({
normalizers: {
addCustomFields: [
{
normalizeProductCatalogItem: (context, rawProduct) => ({
description: rawProduct.description,
}),
},
],
},
config: {
...
},
});
addCustomFields
is an array, so you can easily split the custom fields into separate files or import the custom fields from other packages.
import { customFields } from "@example/module";
import { productCustomFields, cartCustomFields } from "./customFields";
export const unifiedApiExtension = createUnifiedExtension({
normalizers: {
addCustomFields: [
productCustomFields,
cartCustomFields,
customFields,
],
},
config: {
...
},
});
If you want to override the default normalizers, you can use the override
key:
import { normalizers } from "@vsf-enterprise/unified-api-sapcc";
export const unifiedApiExtension = createUnifiedExtension({
normalizers: {
override: {
normalizeProductCatalogItem: (context, rawProduct) => ({
// to call the default normalizer
...normalizers.normalizeProductCatalogItem(context, rawProduct),
name: `${rawProduct.name} - ${rawProduct.sku}`,
}),
},
},
config: {
...
},
});
Deprecation of the unifiedSdk
ri:link
The @vsf-enterprise/unified-sdk
package has been deprecated. Now the same functionality can be achieved by using the @vue-storefront/sdk
.
- import { unifiedModule } from '@vsf-enterprise/unified-sdk';
import { CreateSdkOptions, createSdk } from '@vue-storefront/next';
- import { UnifiedApiExtension } from 'storefront-middleware/middleware.config';
+ import { UnifiedEndpoints } from 'storefront-middleware/middleware.config';
-export const { getSdk } = createSdk(options, ({ buildModule, middlewareUrl, getRequestHeaders }) => ({
+export const { getSdk } = createSdk(options, ({ buildModule, middlewareUrl, getRequestHeaders, middlewareModule }) => ({
- unified: buildModule(unifiedModule<UnifiedApiExtension>, {
+ unified: buildModule(middlewareModule<UnifiedEndpoints>, {
apiUrl: `${middlewareUrl}/commerce`,
- requestOptions: {
- headers: () => getRequestHeaders() as Record<string, string>,
+ defaultRequestConfig: {
+ headers: getRequestHeaders(),
},
}),
The middlewareModule
can be used with any other extension, not only the Unified. It requires an endpoints type to be passed as a generic. An endpoint is just a record containing names of the methods and its contract:
export type MyEndpoints = {
getProduct: (params: { id: string }) => Promise<Product>;
};
Redefined a way to add custom methodsri:link
Thanks to the middlewareModule
you can now add custom methods to the SDK, by just implementing a new extension to the middleware.
import type { ContextualizedEndpoints, SAPIntegrationContext } from "@vsf-enterprise/sapcc-api"
export const customMethodsExtension = {
name: "customMethods",
extendApiMethods: {
getProduct: async (context, params: { id: string }) => {
// your implementation
},
},
} satisfies ApiClientExtension<ContextualizedEndpoints, SAPIntegrationContext>;
// the Endpoints type can be written manually, or inferred from the extension
export type CustomMethodsEndpoints = WithoutContext<CustomMethodsExtension["extendApiMethods"]>;
export const config = {
location: "@vsf-enterprise/sapcc-api/server",
configuration: {
...
},
extensions: (extensions: ApiClientExtension[]) => [
...extensions,
unifiedApiExtension,
// register your extension in extensions array
customMethodsExtension,
],
} satisfies Integration<MiddlewareConfig>;
Then you can use it on the Storefront side, in the sdk.config.ts
file add the new module:
unified: buildModule(middlewareModule<UnifiedEndpoints>, {
apiUrl: `${middlewareUrl}/commerce`,
defaultRequestConfig: {
headers: getRequestHeaders(),
},
}),
+ customExtension: buildModule(middlewareModule<CustomMethodsEndpoints>, {
+ apiUrl: `${middlewareUrl}/commerce`,
+ defaultRequestConfig: {
+ headers: getRequestHeaders(),
+ },
+ }),
cms: buildModule(contentfulModule, {
apiUrl: `${middlewareUrl}/cntf`,
}),
You can now call the new method in the application:
sdk.customMethods.getProduct({ id: "123" });
This change is important in terms of the createUnifiedExtension
API. Our goal is to make a clear separation between the Unified Methods, which are shared across all supported eCommerce backends, and your custom methods. This approach should help you in the future if you will decide to migrate to another eCommerce.
Now you you should implement every non-Unified Method in a separate extension.
export const unifiedApiExtension = createUnifiedExtension<Context, Config>()({
apiMethods: {
...apiMethods,
- customMethod: async (context, params) => {...}
},
})
export const customMethodsExtension = {
name: "customMethods",
extendApiMethods: {
getProduct: async (context, params: { id: string }) => {
// your implementation
},
+ customMethod: async (context, params) => {...}
},
} satisfies ApiClientExtension<ContextualizedEndpoints, SAPIntegrationContext>;
If you want to override the Unified Method, you can use the override
key:
export const unifiedApiExtension = createUnifiedExtension({
apiMethods: {
override: {
getProduct: async (context, params) => {
// your implementation
},
},
},
});
Please remember that in this case, the parameters and return type of the method should be the same as in the Unified Method.
New utilitiesri:link
defineNormalizer
ri:link
You can split the override normalizer entries into separate variables. To get proper typings, you can use the defineNormalizer
utility.
import { normalizers, defineNormalizer } from "@vsf-enterprise/unified-api-sapcc";
const normalizeProductCatalogItem = defineNormalizer.normalizeProductCatalogItem((context, rawProduct) => ({
// to call the default normalizer
...normalizers.normalizeProductCatalogItem(context, rawProduct),
name: `${rawProduct.name} - ${rawProduct.sku}`,
}));
export const unifiedApiExtension = createUnifiedExtension({
normalizers: {
override: {
normalizeProductCatalogItem,
},
},
config: {
...
},
});
defineAddCustomFields
ri:link
Similarly, you can use the defineAddCustomFields
utility to split the custom fields into separate variables.
import { defineAddCustomFields } from "@vsf-enterprise/unified-api-sapcc";
const productCustomFields = defineAddCustomFields({
normalizeProductCatalogItem: (context, rawProduct) => ({
description: rawProduct.description,
}),
});
export const unifiedApiExtension = createUnifiedExtension({
normalizers: {
addCustomFields: [productCustomFields],
},
config: {
...
},
});
Patch Changesri:link
- ADDED
beforeCall
hook to Unified Extension, which set thedefaultCurrency
forvsf-locale
, whenvsf-locale
is empty. - ADDED export
getNormalizers
from package
1.0.0-rc.1ri:link
Patch Changesri:link
- ADDED export
getNormalizers
from package
1.0.0-rc.0ri:link
Major Changesri:link
First draft of v1.0.0
Patch Changesri:link
- ADDED
beforeCall
hook to Unified Extension, which set thedefaultCurrency
forvsf-locale
, whenvsf-locale
is empty.
0.3.4ri:link
Patch Changesri:link
- FIXED After
registerCustomer
, if the guest cart is not empty, it will be set as the customer cart. Previously a new, empty, cart was created for the customer every time they registered. - CHANGED
loginCustomer
returns 403, when customer is already logged in.
0.3.3ri:link
Patch Changesri:link
- FIXED Category facets calculation. To use it, it is required to have at least v2.5 of Magento.
0.3.2ri:link
Patch Changesri:link
- FIXED - Create Customer Address handles
titleCode
field.
0.3.1ri:link
Patch Changesri:link
- ADDED
beforeCall
hook to Unified Extension, which set thedefaultCurrency
forvsf-locale
, whenvsf-locale
is empty.
0.3.0ri:link
Minor Changesri:link
- ADDED
defineNormalizer
utility which helps in overriding the normalizers. It should be used only when you want to override the default normalizers. If you want to add custom fields, you should still declare the normalizer within thedefineNormalizers
.
import {
defineNormalizer,
normalizers as normalizersMagento,
defineNormalizers,
} from "@vsf-enterprise/unified-api-magento";
const customNormalizeProduct = defineNormalizer.normalizeProduct((rawProduct, ctx) => {
// your implementation goes here, no custom fields
});
const normalizers = defineNormalizers<typeof normalizersMagento>()({
...normalizersMagento,
normalizeProduct: customNormalizeProduct,
normalizeCart: (cart, context) => ({
...normalizersMagento.normalizeCart(cart, context),
// still use inline normalizer to add custom fields
version: cart.version,
}),
});
- ADDED
normalizers
toNormalizerContext
. You can now access the other normalizers from the context. This is useful when you want to reuse the existing normalizers in your custom normalizer.
const customNormalizeProduct = defineNormalizer.normalizeProduct((rawProduct, ctx) => {
// ctx.normalizers.normalizeMoney is now available
});
Patch Changesri:link
- FIXED Normalizers such as
normalizeMoney
can be now overridden globally. This is useful when you want to change the way the money is represented accross the whole Unified extension.
0.2.0ri:link
Minor Changesri:link
- ADDED accept passing categories' slug as id in
getCategory
method andsearchProducts
. If passed field will be an uuid, it will be considered as id, otherwise as slug.
0.1.1ri:link
Patch Changesri:link
- 3d8183e: FIXED Cart line item display correct
ConfigurableCartItem
attributes.
FIXEDsearchProducts()
method default sorting.
FIXEDgetProductDetails()
method responsecategories
displays related hierarchical data.
0.1.0ri:link
Minor Changesri:link
- 156465c: ADDED
@vsf-enterprise/unified-api-magento
integration for Adobe Commerce (Magento 2).
Features:- Implemented core functionality for Unified-Data-Model
- Unified Methods
- Normalizers
UDM extension import:import { createUnifiedExtension } from "@vsf-enterprise/unified-api-magento"
UDM model types import:import { SfCategory, GetCategory } from "@vsf-enterprise/unified-api-magento"
- Implemented core functionality for Unified-Data-Model
0.0.3ri:link
Patch Changesri:link
- c88a173: Internal release
0.0.2ri:link
Patch Changesri:link
- 1f52ffa: Update dependencies