@scayle/storefront-product-detail 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @scayle/storefront-product-detail
 
+## 1.9.0
+
+### Minor Changes
+
+- **[RPC]** Updated built-in RPC methods to use `GET` for safe, cacheable reads and `PUT`/`POST`/`DELETE` for mutations, enabling CDN and browser caching for public data fetches.
+
+## 1.8.0
+
+### Minor Changes
+
+- Added the `useSimilarProducts` composable and `getSimilarProducts` RPC method to enable fetching product recommendations based on a given product ID.
+
+  The `useSimilarProducts` composable provides a convenient way to retrieve similar products with support for filtering, limiting results, and configuring product data inclusion. The underlying `getSimilarProducts` RPC method accepts a `productId` and optional configuration parameters including `with` (product data to include), `limit` (maximum number of recommendations), `where` (product search filters), `pricePromotionKey`, `campaignKey`, and `ignoreSameMasterKey` (whether to exclude products with the same master key). Results are cached for 5 minutes to improve performance.
+
+  ```ts
+  const { data, status, error } = useSimilarProducts({
+    params: {
+      productId: 123,
+      limit: 10,
+      with: { attributes: "all", images: { attributes: "all" } },
+      where: {
+        attributes: [
+          {
+            type: "attributes",
+            key: "brand",
+            values: [456],
+          },
+        ],
+      },
+      ignoreSameMasterKey: true,
+    },
+  });
+  ```
+
 ## 1.7.0
 
 ### Minor Changes
@@ -44,64 +78,64 @@
   **`sellableTimeframeStartsInFuture`:**
 
   ```ts
-  import { sellableTimeframeStartsInFuture } from '@scayle/storefront-product-detail'
+  import { sellableTimeframeStartsInFuture } from "@scayle/storefront-product-detail";
 
   // Example timeframe
   const timeframe = {
-    sellableFrom: '2099-01-01T00:00:00Z',
-    sellableTo: '2100-01-01T00:00:00Z',
-  }
+    sellableFrom: "2099-01-01T00:00:00Z",
+    sellableTo: "2100-01-01T00:00:00Z",
+  };
 
-  const inFuture = sellableTimeframeStartsInFuture(timeframe)
-  console.log(inFuture) // true if current date is before 2099-01-01
+  const inFuture = sellableTimeframeStartsInFuture(timeframe);
+  console.log(inFuture); // true if current date is before 2099-01-01
   ```
 
   **`sellableTimeframeEndsInPast`:**
 
   ```ts
-  import { sellableTimeframeEndsInPast } from '@scayle/storefront-product-detail'
+  import { sellableTimeframeEndsInPast } from "@scayle/storefront-product-detail";
 
   const timeframe = {
-    sellableFrom: '2018-01-01T00:00:00Z',
-    sellableTo: '2020-01-01T00:00:00Z',
-  }
+    sellableFrom: "2018-01-01T00:00:00Z",
+    sellableTo: "2020-01-01T00:00:00Z",
+  };
 
-  const ended = sellableTimeframeEndsInPast(timeframe)
-  console.log(ended) // true if current date is after 2020-01-01
+  const ended = sellableTimeframeEndsInPast(timeframe);
+  console.log(ended); // true if current date is after 2020-01-01
   ```
 
   **`isInSellableTimeframe`:**
 
   ```ts
-  import { isInSellableTimeframe } from '@scayle/storefront-product-detail'
+  import { isInSellableTimeframe } from "@scayle/storefront-product-detail";
 
   const timeframe = {
-    sellableFrom: '2023-01-01T00:00:00Z',
-    sellableTo: '2025-01-01T00:00:00Z',
-  }
+    sellableFrom: "2023-01-01T00:00:00Z",
+    sellableTo: "2025-01-01T00:00:00Z",
+  };
 
-  const active = isInSellableTimeframe(timeframe)
-  console.log(active) // true if current date is between 2023-01-01 and 2025-01-01
+  const active = isInSellableTimeframe(timeframe);
+  console.log(active); // true if current date is between 2023-01-01 and 2025-01-01
   ```
 
   **`useSellableTimeFrame`:**
 
   ```ts
-  import { useSellableTimeFrame } from '@scayle/storefront-product-detail'
+  import { useSellableTimeFrame } from "@scayle/storefront-product-detail";
 
   const timeframe = {
-    sellableFrom: '2023-01-01T00:00:00Z',
-    sellableTo: '2025-01-01T00:00:00Z',
-  }
+    sellableFrom: "2023-01-01T00:00:00Z",
+    sellableTo: "2025-01-01T00:00:00Z",
+  };
   const {
     isInSellableTimeframe,
     sellableTimeframeStartsInFuture,
     sellableTimeframeEndsInPast,
-  } = useSellableTimeFrame(timeframe)
+  } = useSellableTimeFrame(timeframe);
 
-  console.log(isInSellableTimeframe) // true if the timeframe is active
-  console.log(sellableTimeframeStartsInFuture) // true if the time frame starts in the future
-  console.log(sellableTimeframeEndsInPast) // true if the timeframe ended in the past
+  console.log(isInSellableTimeframe); // true if the timeframe is active
+  console.log(sellableTimeframeStartsInFuture); // true if the time frame starts in the future
+  console.log(sellableTimeframeEndsInPast); // true if the timeframe ended in the past
   ```
 
 ## 1.5.6
@@ -117,20 +151,20 @@
 
   ```ts
   // Before
-  const { data } = await useRpc('getProduct', 'my-static-product-key', {
+  const { data } = await useRpc("getProduct", "my-static-product-key", {
     productId: 123,
-  })
+  });
 
   // After
-  const productId = ref(123)
+  const productId = ref(123);
 
   // The key is now reactive. If `productId` changes, the key updates
   // to 'product-456' (for example) and triggers a new fetch.
   const { data } = await useRpc(
-    'getProduct',
+    "getProduct",
     () => `product-${productId.value}`,
-    { productId },
-  )
+    { productId }
+  );
   ```
 
 ## 1.5.5
@@ -167,15 +201,15 @@
 
   ```ts
   export default defineNuxtConfig({
-    modules: ['@scayle/storefront-product-detail'],
+    modules: ["@scayle/storefront-product-detail"],
     runtimeConfig: {
       public: {
-        'product-detail': {
+        "product-detail": {
           maxRecentlyViewedProducts: 15,
         },
       },
     },
-  })
+  });
   ```
 
 ## 1.5.0
@@ -187,15 +221,15 @@
   Example usage:
 
   ```ts
-  import { useRecentlyViewedProducts } from '#storefront-product-detail/composables'
+  import { useRecentlyViewedProducts } from "#storefront-product-detail/composables";
 
   const { products, addProduct, loadMissingProducts } =
-    useRecentlyViewedProducts()
+    useRecentlyViewedProducts();
 
   onBeforeMount(async () => {
-    addProductId(1234)
-    await loadMissingProducts()
-  })
+    addProductId(1234);
+    await loadMissingProducts();
+  });
   ```
 
 ## 1.4.2
@@ -227,46 +261,44 @@
 
   ```ts
   useProductSeoData({
-    name: 'Name',
-    brand: 'Brand',
-    productDescription: 'Description',
+    name: "Name",
+    brand: "Brand",
+    productDescription: "Description",
     variants: variants.value.map((variant) => {
       return generateProductSchema({
-        productName: 'Name',
+        productName: "Name",
         variant,
         url: `${$config.public.baseUrl}${route.fullPath}`,
         size,
-      })
+      });
     }),
     images: images.value,
     productId: product.value?.id || 0,
     color: formatColors(colors.value),
-    variesBy: variants.value.length > 1
-      ? ['https://schema.org/size']
-      : undefined,
-  })
+    variesBy:
+      variants.value.length > 1 ? ["https://schema.org/size"] : undefined,
+  });
 
   // Will become
 
   useProductSeoData({
-    name: 'Name',
-    brand: 'Brand',
-    productDescription: 'Description',
+    name: "Name",
+    brand: "Brand",
+    productDescription: "Description",
     variants: variants.value.map((variant) => {
       return generateProductSchema({
-        productName: 'Name',
+        productName: "Name",
         variant,
         url: `${$config.public.baseUrl}${route.fullPath}`,
         size,
         images: images.value[0],
-      })
+      });
     }),
     productId: product.value?.id || 0,
     color: formatColors(colors.value),
-    variesBy: variants.value.length > 1
-      ? ['https://schema.org/size']
-      : undefined,
-  })
+    variesBy:
+      variants.value.length > 1 ? ["https://schema.org/size"] : undefined,
+  });
   ```
 
 ## 1.2.0

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@scayle/storefront-product-detail",
   "configKey": "product-detail",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "compatibility": {
     "bridge": false,
     "nuxt": ">=3.13"

package/dist/module.mjs

@@ -1,7 +1,7 @@
 import { defineNuxtModule, createResolver, addImportsDir } from '@nuxt/kit';
 
 const PACKAGE_NAME = "@scayle/storefront-product-detail";
-const PACKAGE_VERSION = "1.7.0";
+const PACKAGE_VERSION = "1.9.0";
 const module$1 = defineNuxtModule({
   meta: {
     name: PACKAGE_NAME,
@@ -24,6 +24,10 @@ const module$1 = defineNuxtModule({
         source: await resolvePath("./runtime/rpc/methods/products"),
         names: ["getAllShopProductsForId"]
       });
+      customRpcs.push({
+        source: await resolvePath("./runtime/rpc/methods/recommendations"),
+        names: ["getSimilarProducts"]
+      });
     });
     nuxt.options.optimization.keyedComposables.push({
       name: "useAllShopProductsForId",

package/dist/runtime/composables/index.d.ts

@@ -2,3 +2,4 @@ export * from './useProductSeoData.js';
 export * from './useAllShopProductsForId.js';
 export * from './useRecentlyViewedProducts.js';
 export * from './useSellableTimeFrame.js';
+export * from './useSimilarProducts.js';

package/dist/runtime/composables/index.js

@@ -2,3 +2,4 @@ export * from "./useProductSeoData.js";
 export * from "./useAllShopProductsForId.js";
 export * from "./useRecentlyViewedProducts.js";
 export * from "./useSellableTimeFrame.js";
+export * from "./useSimilarProducts.js";

package/dist/runtime/composables/useSimilarProducts.d.ts

@@ -0,0 +1,26 @@
+import type { RpcMethodParameters } from '@scayle/storefront-nuxt';
+import type { NormalizedRpcResponse, UseRpcOptions, UseRpcCacheKey, KeysOf, UseRpcReturn } from '@scayle/storefront-nuxt/composables';
+import type { MaybeRefOrGetter } from 'vue';
+/**
+ * Retrieves similar products for a given product ID using the `getSimilarProducts` RPC method.
+ *
+ * This function acts as a wrapper around the `useRpc` composable,
+ * simplifying the process of fetching data. It internally calls `useRpc`
+ * with the provided parameters and options.
+ *
+ * @template DataT The type of the normalized RPC response data. Defaults to `NormalizedRpcResponse<'getSimilarProducts'>`.
+ * @template PickKeys The keys to pick from the data. Defaults to all keys of `DataT`.
+ * @template DefaultT The default value to use if data is not available. Defaults to `null`.
+ *
+ * @param params The parameters for the `getSimilarProducts` RPC method.
+ * @param params.params The parameters for the `getSimilarProducts` RPC method.
+ * @param params.options The options for the underlying `useRpc` call, controlling data handling and loading state.
+ * @param key A unique key for this RPC call. Used internally by `useRpc` for caching and state management.
+ *
+ * @returns The result of the `useRpc` call, which includes the fetched data,
+ *          loading state, and any error information.
+ */
+export declare function useSimilarProducts<DataT = NormalizedRpcResponse<'getSimilarProducts'>, PickKeys extends KeysOf<DataT> = KeysOf<DataT>, DefaultT = null>({ params, options, }?: Partial<{
+    params: MaybeRefOrGetter<RpcMethodParameters<'getSimilarProducts'>>;
+    options: UseRpcOptions<'getSimilarProducts', DataT, PickKeys, DefaultT>;
+}>, key?: UseRpcCacheKey): UseRpcReturn<'getSimilarProducts', DataT, PickKeys, DefaultT>;

package/dist/runtime/composables/useSimilarProducts.js

@@ -0,0 +1,7 @@
+import { useRpc } from "@scayle/storefront-nuxt/composables";
+export function useSimilarProducts({
+  params,
+  options
+} = {}, key = "useSimilarProducts") {
+  return useRpc("getSimilarProducts", key, params, options);
+}

package/dist/runtime/index.d.ts

@@ -1,6 +1,7 @@
 export * from './composables/useProductSeoData.js';
 export * from './composables/useAllShopProductsForId.js';
 export * from './composables/useSellableTimeFrame.js';
+export * from './composables/useSimilarProducts.js';
 export * from './utils/product.js';
 export * from './utils/attribute.js';
 export * from './utils/seo.js';

package/dist/runtime/index.js

@@ -1,6 +1,7 @@
 export * from "./composables/useProductSeoData.js";
 export * from "./composables/useAllShopProductsForId.js";
 export * from "./composables/useSellableTimeFrame.js";
+export * from "./composables/useSimilarProducts.js";
 export * from "./utils/product.js";
 export * from "./utils/attribute.js";
 export * from "./utils/seo.js";

package/dist/runtime/rpc/methods/products.js

@@ -30,4 +30,4 @@ export const getAllShopProductsForId = defineRpcHandler(async (options, context)
     // 12 hours
   })();
   return result;
-});
+}, { method: "GET" });

package/dist/runtime/rpc/methods/recommendations.d.ts

@@ -0,0 +1,26 @@
+import type { ProductWith, ProductSearchQuery, RpcHandler, Product } from '@scayle/storefront-nuxt';
+interface FetchSimilarProductsParams {
+    productId: number;
+    with?: ProductWith;
+    pricePromotionKey?: string;
+    where?: ProductSearchQuery;
+    limit?: number;
+    ignoreSameMasterKey?: boolean;
+}
+/**
+ * Retrieves similar products for a given product ID.
+ *
+ * @param options The options for retrieving similar products.
+ * @param options.productId The ID of the product to retrieve similar products for.
+ * @param options.with The 'with' parameter for including additional data.
+ * @param options.pricePromotionKey The price promotion key.
+ * @param options.where The where clause to filter the products.
+ * @params options.where.attributes The attributes to filter the products by.
+ * @param options.limit The limit of products to retrieve.
+ * @param options.ignoreSameMasterKey Whether to ignore products with the same master key.
+ * @param context The RPC context.
+ *
+ * @returns A Promise that resolves with an array of products.
+ */
+export declare const getSimilarProducts: RpcHandler<FetchSimilarProductsParams, Product[]>;
+export {};

package/dist/runtime/rpc/methods/recommendations.js

@@ -0,0 +1,38 @@
+import {
+  ErrorResponse,
+  FetchError,
+  MINUTE,
+  MIN_WITH_PARAMS_PRODUCT,
+  defineRpcHandler
+} from "@scayle/storefront-nuxt";
+export const getSimilarProducts = defineRpcHandler(async (options, context) => {
+  const { sapiClient, cached, withParams } = context;
+  const campaignKey = await context.callRpc?.("getCampaignKey");
+  const { productId, with: withParameter, ...rest } = options;
+  const fetch = async (productId2, params) => {
+    try {
+      return sapiClient.recommendations.getSimilarProducts(productId2, params);
+    } catch (e) {
+      if (e instanceof FetchError) {
+        const response = e.response;
+        return new ErrorResponse(
+          response.status,
+          response.statusText,
+          "Failed to fetch similar products"
+        );
+      }
+      throw e;
+    }
+  };
+  return await cached(
+    fetch,
+    {
+      cacheKeyPrefix: "getSimilarProducts-products",
+      ttl: 5 * MINUTE
+    }
+  )(productId, {
+    with: withParameter ?? withParams?.product ?? MIN_WITH_PARAMS_PRODUCT,
+    campaignKey,
+    ...rest
+  });
+}, { method: "GET" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scayle/storefront-product-detail",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Collection of essential composables and utilities to work with product detail",
   "author": "SCAYLE Commerce Engine",
   "license": "MIT",
@@ -24,6 +24,9 @@
     "CHANGELOG.md",
     "dist"
   ],
+  "engines": {
+    "node": ">= 22.0.0"
+  },
   "imports": {
     "#storefront-product-detail": "./dist/runtime/index.js"
   },
@@ -37,28 +40,27 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.2",
-    "@nuxt/kit": "3.20.0",
+    "@nuxt/kit": "^3.20.2",
     "@nuxt/module-builder": "1.0.2",
-    "@nuxt/schema": "3.20.0",
-    "@nuxt/test-utils": "3.23.0",
-    "@types/node": "22.19.5",
-    "@vitest/coverage-v8": "4.0.16",
-    "@vueuse/core": "14.1.0",
-    "dprint": "0.51.1",
-    "eslint-formatter-gitlab": "7.0.1",
-    "eslint": "9.39.2",
-    "happy-dom": "20.1.0",
-    "nuxt": "3.20.0",
-    "publint": "0.3.16",
+    "@nuxt/schema": "^3.20.2",
+    "@nuxt/test-utils": "4.0.0",
+    "@scayle/eslint-config-storefront": "^4.8.0",
+    "@types/node": "22.19.17",
+    "@vitest/coverage-v8": "4.1.5",
+    "@vueuse/core": "14.2.1",
+    "eslint-formatter-gitlab": "7.1.0",
+    "eslint": "10.2.1",
+    "happy-dom": "20.9.0",
+    "nuxt": "^3.20.2",
+    "publint": "0.3.18",
     "schema-dts": "1.1.5",
     "typescript": "5.9.3",
     "unbuild": "3.6.1",
-    "vitest": "4.0.16",
+    "vitest": "4.1.5",
     "vue-router": "4.6.4",
-    "vue-tsc": "3.2.2",
-    "vue": "3.5.26",
-    "@scayle/eslint-config-storefront": "4.7.20",
-    "@scayle/storefront-nuxt": "8.58.0",
+    "vue-tsc": "3.2.6",
+    "vue": "3.5.32",
+    "@scayle/storefront-nuxt": "8.61.0",
     "@scayle/vitest-config-storefront": "1.0.0"
   },
   "scripts": {
@@ -69,11 +71,6 @@
     "lint": "eslint .",
     "lint:ci": "eslint . --format gitlab",
     "lint:fix": "eslint . --fix",
-    "format": "dprint check",
-    "format:fix": "dprint fmt",
-    "test": "vitest --run",
-    "test:watch": "vitest",
-    "test:ci": "vitest --run --coverage --reporter=default --reporter=junit --outputFile=./coverage/junit.xml",
     "typecheck": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit",
     "package:lint": "publint",
     "verify-packaging": "attw --pack . --profile esm-only"