@scayle/storefront-core 8.28.7 → 8.30.0

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # @scayle/storefront-core
 
+## 8.30.0
+
+### Minor Changes
+
+- Added `defineRpcHandler` utility function that enhances RPC handlers with type-safe metadata for improved registration and invocation of RPC handlers. While defining RPC handlers without this utility remains supported, its usage is recommended and may become mandatory in a future major release.
+
+  Existing RPC handlers can be easily migrated to use `defineRpcHandler` by passing the existing handler to `defineRpcHandler`.
+
+  ```ts
+  export const existingHandlerWithoutParams = async (_context: RpcContext) => {
+    return 'existing handler'
+  }
+
+  export const existingHandlerWithParams = async (
+    { name }: { name: string },
+    _context: RpcContext,
+  ) => {
+    return name
+  }
+
+  // will become
+
+  export const existingHandlerWithoutParams = defineRpcHandler(
+    async (_context: RpcContext) => {
+      return 'existing handler'
+    },
+  )
+  export const existingHandlerWithParams = defineRpcHandler(
+    async ({ name }: { name: string }, _context: RpcContext) => {
+      return name
+    },
+  )
+  ```
+
+### Patch Changes
+
+- Removed unused `Awaited` and `PromiseReturnType` types.
+
+## 8.29.0
+
+### Minor Changes
+
+- Added an `includeProductSorting` boolean parameter to all category RPC method endpoints (`getRootCategories`, `getCategoryByPath`, `getCategoriesByPath`, `getCategoryById`, `getCategoryTree`).
+  This flag allows consumers to retrieve product sorting data, including the `smartSortingKey` and `customSortingKey` properties.
+  Developers can leverage this data to seamlessly apply smart sorting keys on the product listing page by passing those parameters when fetching products.
+- Added an optional `hideEmptyCategories` parameter to `getCategoryTree`. When enabled, the product count for each category is retrieved, and categories (including their children) without any products are removed. Enabling this option may increase response times, especially for large category trees.
+
+  ```ts
+  import { rpcMethods } from '@scayle/storefront-core'
+
+  rpcMethods.getCategoryTree({ hideEmptyCategories: true }, rpcContext)
+  ```
+
+  or
+
+  ```ts
+  import { useCategoryTree } from '#storefront/composables'
+
+  const { data: rootCategories, status } = useCategoryTree(
+    {
+      params: {
+        hideEmptyCategories: true,
+      },
+    },
+    'category-navigation-tree',
+  )
+  ```
+
+### Patch Changes
+
+**Dependencies**
+
+- Updated dependency to @scayle/storefront-api@18.9.0
+
 ## 8.28.7
 
 ### Patch Changes

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

@@ -7,6 +7,7 @@ import type { Category, ProductCategoryPropertyWith, RpcHandler } from '../../ty
  *
  * @param params The parameters for retrieving the root category.
  * @param params.children The number of child categories to include.
+ * @param params.includeProductSorting Whether to include the product sorting data.
  * @param params.includeHidden Whether to include hidden categories.
  * @param params.properties The properties to include for each category.
  * @param context The RPC context.
@@ -17,6 +18,7 @@ export declare const getRootCategories: RpcHandler<{
     children?: number;
     includeHidden?: true;
     properties?: ProductCategoryPropertyWith;
+    includeProductSorting?: boolean;
 }, {
     categories: Category[];
     activeNode: undefined;
@@ -30,6 +32,7 @@ export declare const getRootCategories: RpcHandler<{
  * @param params The parameters for retrieving a category by its path.
  * @param params.path The path of the category.
  * @param params.children The number of child categories to include, default to `1`.
+ * @param params.includeProductSorting Whether to include the product sorting data.
  * @param params.includeHidden Whether to include hidden categories.
  * @param params.properties The properties to include for each category.
  * @param context The RPC context.
@@ -41,6 +44,7 @@ export declare const getCategoryByPath: RpcHandler<{
     path: string;
     children?: number;
     includeHidden?: true;
+    includeProductSorting?: boolean;
     properties?: ProductCategoryPropertyWith;
 }, Category | undefined>;
 /**
@@ -52,6 +56,7 @@ export declare const getCategoryByPath: RpcHandler<{
  * @param params The parameters for retrieving multiple categories by path.
  * @param params.path The path of the categories.
  * @param params.children The number of children categories to include, default o `1`.
+ * @param params.includeProductSorting Whether to include the product sorting data.
  * @param params.includeHidden Whether to include hidden categories.
  * @param params.properties The properties to include for each category.
  * @param context The RPC context.
@@ -62,6 +67,7 @@ export declare const getCategoriesByPath: RpcHandler<{
     path: string;
     children?: number;
     includeHidden?: true;
+    includeProductSorting?: boolean;
     properties?: ProductCategoryPropertyWith;
 }, {
     categories: Category[] | Category;
@@ -76,6 +82,7 @@ export declare const getCategoriesByPath: RpcHandler<{
  * @param params The parameters for retrieving a category by ID.
  * @param params.id The category ID.
  * @param params.children The number of child categories to include.
+ * @param params.includeProductSorting Whether to include the product sorting data.
  * @param params.includeHidden Whether to include hidden categories.
  * @param params.properties The properties to include for each category.
  * @param context The RPC context.
@@ -86,10 +93,13 @@ export declare const getCategoryById: RpcHandler<{
     id: number;
     children?: number;
     includeHidden?: true;
+    includeProductSorting?: boolean;
     properties?: ProductCategoryPropertyWith;
 }, Category>;
 export declare const getCategoryTree: RpcHandler<{
     children?: number;
     includeHidden?: true;
+    includeProductSorting?: boolean;
     properties?: ProductCategoryPropertyWith;
+    hideEmptyCategories?: boolean;
 }, Category[]>;

package/dist/rpc/methods/categories.mjs

@@ -1,11 +1,11 @@
 import { splitAndRemoveEmpty } from "../../helpers/index.mjs";
 import { mapSAPIFetchErrorToResponse } from "../../utils/sapi.mjs";
-export const getRootCategories = async function getRootCategories2({ children = 1, includeHidden, properties }, context) {
+export const getRootCategories = async function getRootCategories2({ children = 1, includeHidden, properties, includeProductSorting }, context) {
   const { cached, sapiClient } = context;
   const result = await cached(sapiClient.categories.getRoots, {
     cacheKeyPrefix: "root-categories"
   })({
-    with: { children, properties },
+    with: { children, properties, includeProductSorting },
     includeHidden
   });
   return {
@@ -13,7 +13,7 @@ export const getRootCategories = async function getRootCategories2({ children =
     activeNode: void 0
   };
 };
-export const getCategoryByPath = async function getCategoryByPath2({ path, children = 1, includeHidden, properties }, context) {
+export const getCategoryByPath = async function getCategoryByPath2({ path, children = 1, includeHidden, properties, includeProductSorting }, context) {
   const { cached, sapiClient } = context;
   const sanitizedPath = splitAndRemoveEmpty(path);
   return await cached(
@@ -21,12 +21,18 @@ export const getCategoryByPath = async function getCategoryByPath2({ path, child
     {
       cacheKeyPrefix: `getByPath-category-${sanitizedPath}`
     }
-  )(sanitizedPath, { with: { children, properties }, includeHidden });
+  )(sanitizedPath, {
+    with: { children, properties, includeProductSorting },
+    includeHidden
+  });
 };
-export const getCategoriesByPath = async function getCategoriesByPath2({ path, children = 1, includeHidden, properties }, context) {
+export const getCategoriesByPath = async function getCategoriesByPath2({ path, children = 1, includeHidden, properties, includeProductSorting }, context) {
   const { cached, sapiClient } = context;
   if (path === "/") {
-    return getRootCategories({ children, includeHidden, properties }, context);
+    return getRootCategories(
+      { children, includeHidden, properties, includeProductSorting },
+      context
+    );
   }
   const sanitizedPath = splitAndRemoveEmpty(path);
   const result = await cached(
@@ -35,7 +41,7 @@ export const getCategoriesByPath = async function getCategoriesByPath2({ path, c
       cacheKeyPrefix: `getByPath-categories-${sanitizedPath}`
     }
   )(sanitizedPath, {
-    with: { children, properties },
+    with: { children, properties, includeProductSorting },
     includeHidden
   });
   if (result instanceof Response) {
@@ -49,7 +55,8 @@ export const getCategoriesByPath = async function getCategoriesByPath2({ path, c
         with: {
           children,
           parents: "all",
-          properties
+          properties,
+          includeProductSorting
         },
         includeHidden
       });
@@ -72,7 +79,7 @@ export const getCategoriesByPath = async function getCategoriesByPath2({ path, c
   }
   return { categories: tree, activeNode: result };
 };
-export const getCategoryById = async function getCategoryById2({ id, children = 1, includeHidden, properties }, context) {
+export const getCategoryById = async function getCategoryById2({ id, children = 1, includeHidden, properties, includeProductSorting }, context) {
   const { cached, sapiClient } = context;
   return await cached(
     mapSAPIFetchErrorToResponse(sapiClient.categories.getById),
@@ -83,17 +90,56 @@ export const getCategoryById = async function getCategoryById2({ id, children =
     with: {
       children,
       parents: "all",
-      properties
+      properties,
+      includeProductSorting
     },
     includeHidden
   });
 };
-export const getCategoryTree = async function getCategoryTree2({ children, includeHidden, properties }, context) {
-  const { cached, sapiClient } = context;
-  return await cached(sapiClient.categories.getRoots, {
+export const getCategoryTree = async function getCategoryTree2({
+  children,
+  includeHidden,
+  properties,
+  hideEmptyCategories,
+  includeProductSorting
+}, context) {
+  const { cached, sapiClient, callRpc } = context;
+  const categoryTree = await cached(sapiClient.categories.getRoots, {
     cacheKeyPrefix: "root-categories"
   })({
-    with: { children, properties },
+    with: { children, properties, includeProductSorting },
     includeHidden
   });
+  if (!hideEmptyCategories) {
+    return categoryTree;
+  }
+  const campaignKey = await callRpc?.("getCampaignKey");
+  const categoryProductCountTable = await cached(async () => {
+    const productCount = await sapiClient.filters.getValues("categoryids", {
+      campaignKey
+    });
+    return Object.fromEntries(
+      productCount.map(({ id, productCount: productCount2 }) => [id, productCount2])
+    );
+  }, {
+    cacheKey: `category-product-count-table-${campaignKey || "no-campaign"}`,
+    ttl: 3600
+    // 1 hour
+  })();
+  const removeEmptyCategories = (category) => {
+    if (category.children) {
+      category.children = category.children.filter(
+        (child) => categoryProductCountTable[child.id] > 0
+      );
+      category.children.forEach((child) => {
+        removeEmptyCategories(child);
+      });
+    }
+  };
+  categoryTree.forEach((category) => {
+    removeEmptyCategories(category);
+  });
+  return categoryTree.filter(
+    (category) => categoryProductCountTable[category.id] > 0
+  );
 };

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

@@ -36,7 +36,7 @@ export const getCheckoutToken = async function getCheckoutToken2(jwtPayload = {}
     carrier,
     basketId: context.basketKey,
     campaignKey
-  }).setIssuedAt(now).setNotBefore(now).setExpirationTime("1h").setIssuer(`${"@scayle/storefront-core"}@${"8.28.7"}`).setProtectedHeader({ alg: "HS256", typ: "JWT" }).sign(secret);
+  }).setIssuedAt(now).setNotBefore(now).setExpirationTime("1h").setIssuer(`${"@scayle/storefront-core"}@${"8.30.0"}`).setProtectedHeader({ alg: "HS256", typ: "JWT" }).sign(secret);
   return {
     accessToken: refreshedAccessToken,
     checkoutJwt

package/dist/types/api/rpc.d.ts

@@ -2,16 +2,24 @@ import type { RpcContext } from './context';
 /**
  * Type for an RPC handler that accepts parameters.
  *
+ * @note In the upcoming major release `rpcType` property will be mandatory.
+ *
  * @template Params The type of the parameters object.
  * @template ResponseType The type of the response.
  */
-export type ParamRpcHandler<Params extends Record<string, any>, ResponseType> = (params: Params, context: RpcContext) => Promise<(ResponseType extends undefined ? void : ResponseType) | Response> | ResponseType | Response;
+export type ParamRpcHandler<Params extends Record<string, any>, ResponseType> = ((params: Params, context: RpcContext) => Promise<(ResponseType extends undefined ? void : ResponseType) | Response> | ResponseType | Response) & {
+    rpcType?: 'WithParam';
+};
 /**
  * Type for an RPC handler that does not accept parameters.
  *
+ * @note In the upcoming major release `rpcType` property will be mandatory.
+ *
  * @template ResponseType The type of the response.
  */
-export type NoParamRpcHandler<ResponseType> = (context: RpcContext) => Promise<ResponseType | Response> | ResponseType | Response;
+export type NoParamRpcHandler<ResponseType> = ((context: RpcContext) => Promise<ResponseType | Response> | ResponseType | Response) & {
+    rpcType?: 'NoParam';
+};
 /**
  * Generic RPC handler type. Handles both cases with and without parameters.
  *

package/dist/types/index.d.ts

@@ -1,4 +1,3 @@
-export * from './promises';
 export * from './user';
 export * from './breadcrumb';
 export * from './api/rpc';

package/dist/types/index.mjs

@@ -1,4 +1,3 @@
-export * from "./promises.mjs";
 export * from "./user.mjs";
 export * from "./breadcrumb.mjs";
 export * from "./api/rpc.mjs";

package/dist/utils/index.d.ts

@@ -3,3 +3,4 @@ export * from './log';
 export * from './fetch';
 export * from './basket';
 export * from './campaign';
+export { defineRpcHandler } from './rpc';

package/dist/utils/index.mjs

@@ -3,3 +3,4 @@ export * from "./log.mjs";
 export * from "./fetch.mjs";
 export * from "./basket.mjs";
 export * from "./campaign.mjs";
+export { defineRpcHandler } from "./rpc.mjs";

package/dist/utils/rpc.d.ts

@@ -0,0 +1,27 @@
+import type { RpcMethods, RpcMethodName } from '..';
+import type { RpcContext, RpcHandler } from '../types';
+type RpcType = 'NoParam' | 'WithParam';
+/**
+ * Defines an RPC method handler.
+ *
+ * @param handler - The RPC handler function.
+ * @returns The handler itself, with correct types enforced and internal properties set.
+ */
+export declare function defineRpcHandler<Params extends Record<string, unknown>, Result = unknown>(handler: (params: Params, context: RpcContext) => Result | Promise<Result>): RpcHandler<Params, Result>;
+/**
+ * Defines an RPC method handler.
+ *
+ * @param handler - The RPC handler function.
+ * @returns The handler itself, with correct types enforced and internal properties set.
+ */
+export declare function defineRpcHandler<Result = unknown>(handler: (context: RpcContext) => Result | Promise<Result>): RpcHandler<Result>;
+/**
+ * Defines an RPC method handler.
+ *
+ * @param handler The RPC handler function.
+ * @returns The handler itself, with correct types enforced and internal properties set.
+ */
+export declare function defineRpcHandler<T extends RpcMethods[RpcMethodName]>(handler: T): T & {
+    rpcType: RpcType;
+};
+export {};

package/dist/utils/rpc.mjs

@@ -0,0 +1,5 @@
+export function defineRpcHandler(handler) {
+  const rpcType = handler.length === 1 ? "NoParam" : "WithParam";
+  const handlerWithType = Object.assign(handler, { rpcType });
+  return handlerWithType;
+}

package/dist/utils/sapi.d.ts

@@ -10,4 +10,4 @@
  *
  * @throws Re-throws any error that is not an instance of FetchError.
  */
-export declare function mapSAPIFetchErrorToResponse<T extends (...args: any) => any>(func: T): (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>> | Response>;
+export declare function mapSAPIFetchErrorToResponse<T extends (...args: any[]) => any>(func: T): (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>> | Response>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scayle/storefront-core",
-  "version": "8.28.7",
+  "version": "8.30.0",
   "description": "Collection of essential utilities to work with the Storefront API",
   "author": "SCAYLE Commerce Engine",
   "license": "MIT",
@@ -64,7 +64,7 @@
     "fishery": "^2.2.3"
   },
   "dependencies": {
-    "@scayle/storefront-api": "18.8.0",
+    "@scayle/storefront-api": "18.9.0",
     "@scayle/unstorage-scayle-kv-driver": "1.0.1",
     "crypto-js": "^4.2.0",
     "hookable": "^5.5.3",
@@ -75,14 +75,14 @@
     "utility-types": "^3.11.0"
   },
   "devDependencies": {
-    "@scayle/eslint-config-storefront": "4.5.5",
+    "@scayle/eslint-config-storefront": "4.5.6",
     "@types/crypto-js": "4.2.2",
-    "@types/node": "22.15.31",
+    "@types/node": "22.15.32",
     "@types/webpack-env": "1.18.8",
     "@vitest/coverage-v8": "3.2.3",
     "dprint": "0.50.0",
     "eslint-formatter-gitlab": "6.0.1",
-    "eslint": "9.28.0",
+    "eslint": "9.29.0",
     "fishery": "2.3.1",
     "publint": "0.2.12",
     "rimraf": "6.0.1",

package/dist/types/promises.d.ts

@@ -1,12 +0,0 @@
-/**
- * Extracts the type resolved by a promise or promise-like value.
- *
- * @template T The input type, which can be a promise-like value.
- */
-export type Awaited<T> = T extends PromiseLike<infer U> ? Awaited<U> : T;
-/**
- * Extracts the return type of a promise-returning function, after the promise resolves.
- *
- * @template T The promise-returning function type.
- */
-export type PromiseReturnType<T extends (...args: any) => Promise<any>> = Awaited<ReturnType<T>>;