@scayle/storefront-core 8.46.0 → 8.47.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @scayle/storefront-core
 
+## 8.47.0
+
+### Minor Changes
+
+- Enhanced basket RPC methods to support order custom data functionality.
+
+  All basket RPC methods now integrate with the `getOrderCustomData` RPC method to fetch and include order custom data in SAPI requests.
+  This enables developers to attach order-specific custom metadata, business rules, or additional context to orders throughout the basket lifecycle.
+  The existing `orderCustomData` parameter is deprecated and will be removed in the next major version.
+  For now, both parameters are supported and merged together, where attributes from the parameter take precedence.
+
+  On default, this RPC returns an empty object but can be overridden by the developer to return a custom object.
+
+  Example `getOrderCustomData` RPC:
+
+  ```typescript
+  export const getOrderCustomData: RpcHandler<Record<string, unknown>> =
+    defineRpcHandler<Record<string, unknown>>(async (context: RpcContext) => {
+      return {
+        customer: {
+          groups: context.user?.groups,
+        },
+      }
+    })
+  ```
+
+  For further information, please refer to the [Overriding Core RPC Methods](https://scayle.dev/en/core-documentation/storefront-guide/storefront-application/technical-foundation/rpc-methods?sourceText=RPC%2520Methods#overriding-core-rpc-methods).
+
+- Updated all basket RPC methods to pass the customer access token to the SAPI client, enabling the `X-Customer-Token` header for promotion validation.
+
+  The customer access token is now automatically included in basket requests when available.
+  If the token has expired, it will be omitted from the request to prevent validation errors.
+
+### Patch Changes
+
+**Dependencies**
+
+- Updated dependency to @scayle/unstorage-scayle-kv-driver@2.0.7
+- Updated dependency to @scayle/storefront-api@18.18.0
+
 ## 8.46.0
 
 ### Minor Changes

package/dist/rpc/methods/basket/basket.d.ts

@@ -15,7 +15,7 @@ import { mergeBaskets as mergeBasketFunction } from '../../../utils/user';
  * @param params.existingItemHandling How to handle existing items, default to `'AddQuantityToExisting'`.
  * @param params.itemGroup The item group.
  * @param params.with withParams for basket.
- * @param params.orderCustomData Custom data for order.
+ * @param params.orderCustomData @deprecated - will be removed in the next major version. Use `getOrderCustomData` RPC method instead.
  * @param context The RPC context.
  *
  * @returns The updated basket, potentially with errors. It will return
@@ -36,7 +36,7 @@ export declare const addItemToBasket: RpcHandler<AddOrUpdateItemType & {
  * @param params.items An array of items to add.
  * @param params.existingItemHandling How to handle existing items.
  * @param params.with withParams for basket.
- * @param params.orderCustomData Order custom data.
+ * @param params.orderCustomData @deprecated - will be removed in the next major version. Use `getOrderCustomData` RPC method instead.
  * @param context The RPC context.
  *
  * @returns The updated basket, potentially with errors. It will return
@@ -55,7 +55,7 @@ export declare const addItemsToBasket: RpcHandler<{
  * Retrieves the current basket.
  *
  * @param options The options for retrieving the basket.
- * @param options.orderCustomData Custom data for the order.
+ * @param options.orderCustomData @deprecated - will be removed in the next major version. Use `getOrderCustomData` RPC method instead.
  * @param context The RPC context.
  *
  * @returns The basket data. It will return an `ErrorResponse` alternatively
@@ -72,7 +72,7 @@ export declare const getBasket: RpcHandler<BasketWithOptions & {
  * @param options The options for removing the item.
  * @param options.itemKey The key of the item to remove.
  * @param options.with withParams for basket.
- * @param options.orderCustomData Custom data for the order.
+ * @param options.orderCustomData @deprecated - will be removed in the next major version. Use `getOrderCustomData` RPC method instead.
  * @param context The RPC context.
  *
  * @returns The updated basket. It will return an `ErrorResponse` alternatively
@@ -101,7 +101,7 @@ export declare const clearBasket: RpcHandler<boolean>;
  * @param params.fromBasketKey The key of the source basket.
  * @param params.toBasketKey The key of the target basket.
  * @param params.with withParams for basket.
- * @param params.orderCustomData Custom data for the order.
+ * @param params.orderCustomData @deprecated - will be removed in the next major version. Use `getOrderCustomData` RPC method instead.
  * @param context The RPC context.
  *
  * @returns The new merged basket as result of the merge operation.
@@ -135,6 +135,7 @@ export interface UpdateBasketItemRequestParameter {
      * An object describing which data the returned basket should contain.
      */
     with?: BasketWithOptions;
+    orderCustomData?: Record<string, unknown>;
 }
 /**
  * Applies the provided update data to a specific item in a basket.
@@ -143,6 +144,7 @@ export interface UpdateBasketItemRequestParameter {
  * @param params.basketItemKey The key of the item to be updated.
  * @param params.update The update data that should be applied to the basket item.
  * @param params.with An object describing which data the returned basket should contain.
+ * @param params.orderCustomData Custom data for the order.
  * @param context The RPC context.
  *
  * @returns A promise that resolves with the updated basket.

package/dist/rpc/methods/basket/basket.mjs

@@ -6,9 +6,16 @@ import {
   HttpStatusMessage,
   MIN_WITH_PARAMS_BASKET
 } from "../../../constants/index.mjs";
-import { mergeBaskets as mergeBasketFunction } from "../../../utils/user.mjs";
+import {
+  mergeBaskets as mergeBasketFunction,
+  getValidatedAccessToken
+} from "../../../utils/user.mjs";
 import { unwrap } from "../../../utils/response.mjs";
-import { defineRpcHandler, wasAddedWithReducedQuantity } from "../../../utils/index.mjs";
+import {
+  defineRpcHandler,
+  mergeOrderCustomData,
+  wasAddedWithReducedQuantity
+} from "../../../utils/index.mjs";
 import { mapSAPIFetchErrorToResponse } from "../../../utils/sapi.mjs";
 const SAPI_ERROR_NAME = "SAPI ERROR";
 function getWithParams(params, context) {
@@ -35,6 +42,7 @@ export const addItemToBasket = defineRpcHandler(async ({
   }
   const { sapiClient, basketKey } = context;
   const campaignKey = await context.callRpc?.("getCampaignKey");
+  const _orderCustomData = await context.callRpc?.("getOrderCustomData");
   const resolvedWith = getWithParams(
     { with: _with },
     context
@@ -60,7 +68,8 @@ export const addItemToBasket = defineRpcHandler(async ({
     ],
     {
       skipAvailabilityCheck: false,
-      orderCustomData
+      orderCustomData: mergeOrderCustomData(_orderCustomData, orderCustomData),
+      customerToken: getValidatedAccessToken(context.accessToken) ?? void 0
     },
     {
       existingItemHandling
@@ -97,6 +106,7 @@ export const addItemsToBasket = defineRpcHandler(async (params, context) => {
   }
   const { sapiClient, basketKey } = context;
   const campaignKey = await context.callRpc?.("getCampaignKey");
+  const _orderCustomData = await context.callRpc?.("getOrderCustomData");
   const resolvedWith = getWithParams(params, context);
   const itemsToBeAddedOrUpdated = params.items.map((item) => ({
     variantId: item.variantId,
@@ -119,7 +129,11 @@ export const addItemsToBasket = defineRpcHandler(async (params, context) => {
     {
       skipAvailabilityCheck: false,
       includeItemsWithoutProductData: resolvedWith?.includeItemsWithoutProductData,
-      orderCustomData: params.orderCustomData
+      orderCustomData: mergeOrderCustomData(
+        _orderCustomData,
+        params.orderCustomData
+      ),
+      customerToken: getValidatedAccessToken(context.accessToken) ?? void 0
     },
     {
       existingItemHandling: params.existingItemHandling || ExistingItemHandling.ADD_QUANTITY_TO_EXISTING
@@ -159,6 +173,7 @@ export const getBasket = defineRpcHandler(async (options, context) => {
   }
   const { sapiClient, basketKey } = context;
   const campaignKey = await context.callRpc?.("getCampaignKey");
+  const _orderCustomData = await context.callRpc?.("getOrderCustomData");
   const resolvedWith = getWithParams(
     { with: options },
     context
@@ -167,7 +182,11 @@ export const getBasket = defineRpcHandler(async (options, context) => {
     with: resolvedWith,
     campaignKey,
     includeItemsWithoutProductData: resolvedWith.includeItemsWithoutProductData,
-    orderCustomData: options?.orderCustomData
+    orderCustomData: mergeOrderCustomData(
+      _orderCustomData,
+      options?.orderCustomData
+    ),
+    customerToken: getValidatedAccessToken(context.accessToken) ?? void 0
   });
   if (response.type === "failure") {
     const { statusCode, message } = parseBasketError(response);
@@ -192,6 +211,7 @@ export const removeItemFromBasket = defineRpcHandler(async (options, context) =>
   }
   const { sapiClient, basketKey } = context;
   const campaignKey = await context.callRpc?.("getCampaignKey");
+  const _orderCustomData = await context.callRpc?.("getOrderCustomData");
   const resolvedWith = getWithParams(options, context);
   const basket = await sapiClient.basket.deleteItem(
     basketKey,
@@ -200,7 +220,11 @@ export const removeItemFromBasket = defineRpcHandler(async (options, context) =>
       with: resolvedWith,
       campaignKey,
       includeItemsWithoutProductData: resolvedWith?.includeItemsWithoutProductData,
-      orderCustomData: options.orderCustomData
+      orderCustomData: mergeOrderCustomData(
+        _orderCustomData,
+        options.orderCustomData
+      ),
+      customerToken: getValidatedAccessToken(context.accessToken) ?? void 0
     }
   );
   return { basket };
@@ -226,14 +250,18 @@ export const mergeBaskets = defineRpcHandler(async ({ fromBasketKey, toBasketKey
     { with: _with },
     context
   );
+  const _orderCustomData = await context.callRpc?.("getOrderCustomData");
   return await mergeBasketFunction(
     fromBasketKey,
     toBasketKey,
-    { ...resolvedWith, orderCustomData },
+    {
+      ...resolvedWith,
+      orderCustomData: mergeOrderCustomData(_orderCustomData, orderCustomData)
+    },
     context
   );
 });
-export const updateBasketItem = defineRpcHandler(async ({ basketItemKey, update, with: _with }, context) => {
+export const updateBasketItem = defineRpcHandler(async ({ basketItemKey, update, with: _with, orderCustomData }, context) => {
   if (!hasSession(context)) {
     return new ErrorResponse(
       HttpStatusCode.BAD_REQUEST,
@@ -248,11 +276,18 @@ export const updateBasketItem = defineRpcHandler(async ({ basketItemKey, update,
   );
   const { quantity, ...updateParams } = update;
   const campaignKey = update.campaignKey ?? await context.callRpc?.("getCampaignKey");
+  const _orderCustomData = await context.callRpc?.("getOrderCustomData");
   const result = await sapiClient.basket.updateItem(
     basketKey,
     basketItemKey,
     quantity,
-    { ...updateParams, campaignKey, with: resolvedWith }
+    {
+      ...updateParams,
+      campaignKey,
+      with: resolvedWith,
+      orderCustomData: mergeOrderCustomData(_orderCustomData, orderCustomData),
+      customerToken: getValidatedAccessToken(context.accessToken) ?? void 0
+    }
   );
   if (result.type === "success") {
     return { basket: result.basket };
@@ -287,12 +322,18 @@ export const getApplicablePromotionsByCode = defineRpcHandler(async ({ promotion
     context
   );
   const campaignKey = await context.callRpc?.("getCampaignKey");
+  const orderCustomData = await context.callRpc?.("getOrderCustomData");
   const result = await mapSAPIFetchErrorToResponse(
     sapiClient.basket.getApplicablePromotionsByCode
   )(
     basketKey,
     promotionCode,
-    { campaignKey, with: resolvedWith }
+    {
+      campaignKey,
+      with: resolvedWith,
+      orderCustomData,
+      customerToken: getValidatedAccessToken(context.accessToken) ?? void 0
+    }
   );
   if (result instanceof Response || result.type === "failure") {
     context.log.info("Getting applicable promotion codes failed", {
@@ -318,6 +359,7 @@ export const updatePromotions = defineRpcHandler(async (params, context) => {
   }
   const { basketKey, sapiClient } = context;
   const campaignKey = params.campaignKey ?? await context.callRpc?.("getCampaignKey");
+  const orderCustomData = await context.callRpc?.("getOrderCustomData");
   const resolvedWith = getWithParams(
     { with: params.with },
     context
@@ -329,7 +371,9 @@ export const updatePromotions = defineRpcHandler(async (params, context) => {
     {
       ...params,
       campaignKey,
-      with: resolvedWith
+      with: resolvedWith,
+      orderCustomData,
+      customerToken: getValidatedAccessToken(context.accessToken) ?? void 0
     }
   );
   if (result instanceof Response || result.type === "failure") {

package/dist/rpc/methods/checkout/checkout.d.ts

@@ -45,6 +45,8 @@ interface CheckoutJwtPayload {
  * @param jwtPayload The payload for the JWT. Provides checkout-related data to embed within the token.
  * @param context The RPC context.
  *
+ * @see https://scayle.dev/en/core-documentation/storefront/checkout-guide/implementation/webcomponent#jwt-attribute
+ *
  * @returns An object containing the access token and checkout JWT.
  * It will return an `ErrorResponse` if no session is found, no access token is present.
  */

package/dist/rpc/methods/checkout/checkout.mjs

@@ -26,14 +26,18 @@ export const getCheckoutToken = defineRpcHandler(async (jwtPayload = {}, context
   const now = /* @__PURE__ */ new Date();
   const { voucher, customData, preferredCollectionPoint, carrier } = jwtPayload;
   const campaignKey = await context.callRpc?.("getCampaignKey");
+  const orderCustomData = await context.callRpc?.("getOrderCustomData");
   const checkoutJwt = await new SignJWT({
     voucher,
-    customData,
     preferredCollectionPoint,
     carrier,
     basketId: context.basketKey,
-    campaignKey
-  }).setIssuedAt(now).setNotBefore(now).setExpirationTime("1h").setIssuer(`${"@scayle/storefront-core"}@${"8.46.0"}`).setProtectedHeader({ alg: "HS256", typ: "JWT" }).sign(secret);
+    campaignKey,
+    customData: {
+      ...customData,
+      ...orderCustomData
+    }
+  }).setIssuedAt(now).setNotBefore(now).setExpirationTime("1h").setIssuer(`${"@scayle/storefront-core"}@${"8.47.0"}`).setProtectedHeader({ alg: "HS256", typ: "JWT" }).sign(secret);
   return {
     accessToken: refreshedAccessToken,
     checkoutJwt

package/dist/rpc/methods/checkout/order.d.ts

@@ -14,3 +14,4 @@ import type { Order, RpcHandler } from '../../../types';
 export declare const getOrderById: RpcHandler<{
     orderId: number;
 }, Order>;
+export declare const getOrderCustomData: RpcHandler<Record<string, unknown>>;

package/dist/rpc/methods/checkout/order.mjs

@@ -51,3 +51,6 @@ export const getOrderById = defineRpcHandler(async ({ orderId }, context) => {
     );
   }
 });
+export const getOrderCustomData = defineRpcHandler(async () => {
+  return {};
+});

package/dist/utils/basket.d.ts

@@ -23,3 +23,44 @@ import type { AddOrUpdateItemError } from '@scayle/storefront-api';
  * ```
  */
 export declare const wasAddedWithReducedQuantity: (errors?: AddOrUpdateItemError[]) => boolean;
+/**
+ * Merges the two orderCustomData objects when both RPC and parameter values are provided.
+ * If an attribute exists in both, the parameter value takes precedence.
+ *
+ * @param orderCustomDataRpc The order custom data from the RPC context.
+ * @param orderCustomDataParam The order custom data from the parameter.
+ *
+ * @example
+ * ```typescript
+ * const orderCustomDataRpc = {
+ *   orderId: '1',
+ * }
+ * const orderCustomDataParam = {
+ *   orderId: '2',
+ * }
+ * const mergedOrderCustomData = mergeOrderCustomData(orderCustomDataRpc, orderCustomDataParam) // { orderId: '2' }
+ *
+ * const orderCustomDataRpc = {
+ *   orderId: '1',
+ * }
+ * const orderCustomDataParam = undefined
+ * const mergedOrderCustomData = mergeOrderCustomData(orderCustomDataRpc, orderCustomDataParam) // { orderId: '1' }
+ *
+ * const orderCustomDataRpc = undefined
+ * const orderCustomDataParam = {
+ *   orderId: '2',
+ * }
+ * const mergedOrderCustomData = mergeOrderCustomData(orderCustomDataRpc, orderCustomDataParam) // { orderId: '2' }
+ *
+ * const orderCustomDataRpc = {
+ *   orderId: '1',
+ * }
+ * const orderCustomDataParam = {
+ *   orderName: 'Order 2',
+ * }
+ * const mergedOrderCustomData = mergeOrderCustomData(orderCustomDataRpc, orderCustomDataParam) // { orderId: '1', orderName: 'Order 2' }
+ * ```
+ *
+ * @returns The merged order custom data.
+ */
+export declare const mergeOrderCustomData: (orderCustomDataRpc?: Record<string, unknown>, orderCustomDataParam?: Record<string, unknown>) => Record<string, unknown>;

package/dist/utils/basket.mjs

@@ -10,3 +10,12 @@ export const wasAddedWithReducedQuantity = (errors) => {
     (error) => error.operation === "add" && error.kind === AddToBasketFailureKind.ITEM_ADDED_WITH_REDUCED_QUANTITY || error.operation === "update" && error.kind === UpdateBasketItemFailureKind.ITEM_ADDED_WITH_REDUCED_QUANTITY
   );
 };
+export const mergeOrderCustomData = (orderCustomDataRpc, orderCustomDataParam) => {
+  if (!orderCustomDataParam) {
+    return orderCustomDataRpc ?? {};
+  }
+  if (!orderCustomDataRpc) {
+    return orderCustomDataParam ?? {};
+  }
+  return { ...orderCustomDataRpc, ...orderCustomDataParam };
+};

package/dist/utils/user.d.ts

@@ -1,5 +1,13 @@
 import type { BasketResponse, AddManyItemsBasketResponse } from '@scayle/storefront-api';
 import type { BasketWithOptions, Product, RpcContext, Variant } from '../types';
+/**
+ * Checks if the access token is expired.
+ *
+ * @param accessToken The access token to validate.
+ *
+ * @returns The validated access token or undefined if the access token is not present or expired.
+ */
+export declare const getValidatedAccessToken: (accessToken?: string) => string | undefined;
 /**
  * Merges two baskets. Adds the items from the `fromBasketKey` basket to the `toBasketKey` basket
  * and then clears the `fromBasketKey` basket. Handles existing items by adding quantities.

package/dist/utils/user.mjs

@@ -1,11 +1,23 @@
 import { ExistingItemHandling } from "@scayle/storefront-api";
+import { decodeJwt } from "jose";
+export const getValidatedAccessToken = (accessToken) => {
+  if (!accessToken) {
+    return;
+  }
+  const payload = decodeJwt(accessToken);
+  if (!payload.exp || payload.exp < Date.now() / 1e3) {
+    return;
+  }
+  return accessToken;
+};
 export const mergeBaskets = async (fromBasketKey, toBasketKey, withOptions, context) => {
   const { sapiClient } = context;
   const campaignKey = await context.callRpc?.("getCampaignKey");
   const fromOriginBasket = await sapiClient.basket.get(fromBasketKey, {
     with: withOptions,
     campaignKey,
-    orderCustomData: withOptions.orderCustomData
+    orderCustomData: withOptions.orderCustomData,
+    customerToken: getValidatedAccessToken(context.accessToken) ?? void 0
   });
   context.log.debug(`Merging basket ${fromBasketKey} to ${toBasketKey}`);
   if (fromBasketKey === toBasketKey) {
@@ -31,7 +43,8 @@ export const mergeBaskets = async (fromBasketKey, toBasketKey, withOptions, cont
         with: withOptions,
         campaignKey,
         includeItemsWithoutProductData: withOptions?.includeItemsWithoutProductData,
-        orderCustomData: withOptions.orderCustomData
+        orderCustomData: withOptions.orderCustomData,
+        customerToken: getValidatedAccessToken(context.accessToken) ?? void 0
       },
       {
         existingItemHandling: ExistingItemHandling.ADD_QUANTITY_TO_EXISTING

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scayle/storefront-core",
-  "version": "8.46.0",
+  "version": "8.47.0",
   "description": "Collection of essential utilities to work with the Storefront API",
   "author": "SCAYLE Commerce Engine",
   "license": "MIT",
@@ -48,12 +48,12 @@
     "ufo": "^1.5.3",
     "uncrypto": "^0.1.3",
     "utility-types": "^3.11.0",
-    "@scayle/storefront-api": "18.17.0",
-    "@scayle/unstorage-scayle-kv-driver": "2.0.6"
+    "@scayle/storefront-api": "18.18.0",
+    "@scayle/unstorage-scayle-kv-driver": "2.0.7"
   },
   "devDependencies": {
     "@types/crypto-js": "4.2.2",
-    "@types/node": "22.18.12",
+    "@types/node": "22.18.13",
     "@types/webpack-env": "1.18.8",
     "@vitest/coverage-v8": "3.2.4",
     "dprint": "0.50.2",
@@ -66,11 +66,11 @@
     "unbuild": "3.6.1",
     "unstorage": "1.17.1",
     "vitest": "3.2.4",
-    "@scayle/vitest-config-storefront": "1.0.0",
-    "@scayle/eslint-config-storefront": "4.7.10"
+    "@scayle/eslint-config-storefront": "4.7.11",
+    "@scayle/vitest-config-storefront": "1.0.0"
   },
   "volta": {
-    "node": "22.20.0"
+    "node": "22.21.0"
   },
   "scripts": {
     "clean": "rimraf ./dist",