@scayle/storefront-core 8.7.0 → 8.8.0

package/dist/utils/log.d.ts

@@ -1,43 +1,112 @@
+/**
+ * Represents a log level.
+ */
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Represents a single log entry.
+ */
 export interface LogEntry {
     level: LogLevel;
     space: string;
     message: string;
     data?: object;
 }
+/**
+ * A function that handles log entries.
+ *
+ * @param entry The log entry to handle.
+ */
 export type LogHandler = (entry: LogEntry) => void;
+/**
+ * Options for configuring the logger.
+ */
 export interface LogOptions {
     handler?: LogHandler;
     space: string;
 }
 /**
- * This log provides a way to log messages to a custom log handler (in a serial manner).
- * If no handler is provided, it will log to the console.
+ * A logger that provides structured logging with namespaces.
+ * Supports custom log handlers or if no handler is provided, logging to the console.
  */
 export declare class Log {
+    /**
+     * The default log instance, logging to the console with the `global` namespace.
+     */
     static readonly default: Log;
     _handler?: LogHandler;
     _space: string;
     _type: string;
+    /**
+     * Creates a new Log instance.
+     *
+     * @param options Options for the logger.
+     */
     constructor(options?: LogOptions);
+    /**
+     * Logs a debug message.
+     *
+     * @param message The debug message.
+     * @param data Optional additional data.
+     */
     debug(message: string, data?: any): void;
+    /**
+     * Logs an informational message.
+     *
+     * @param message The informational message.
+     * @param data Optional additional data.
+     */
     info(message: string, data?: any): void;
+    /**
+     * Logs a warning message.
+     *
+     * @param message The warning message.
+     * @param data Optional additional data.
+     */
     warn(message: string, data?: any): void;
+    /**
+     * Logs an error message.
+     *
+     * @param message The error message or an Error object.
+     * @param data Optional additional data.
+     */
     error(message: string | Error, data?: any): void;
+    /**
+     * Writes a log entry.
+     *
+     * @param level The log level.
+     * @param message The log message.
+     * @param data Optional additional data.
+     */
     write(level: LogLevel, message: string, data?: any): void;
     /**
-     * Create a new sub-space.
-     * All spaces are being separated by a dot. E.g. `global.api` and `global.api.getUser`
-     * @param subSpace The name of the sub-space in camel-case (e.g. `api` and `api.getUser`)
+     * Creates a new Log instance with a sub-namespace.
+     * Namespaces are separated by dots (e.g., "global.api.getUser").
+     *
+     * @param subSpace The sub-namespace to add in camel-case (e.g. `api` and `api.getUser`)
+     *
+     * @returns A new Log instance with the updated namespace.
      */
     space(subSpace: string): Log;
     /**
-     * Measure the time of a function.
+     * Measures the execution time of an asynchronous function and logs a debug message.
+     *
+     * @param message A message to include in the log output.
+     * @param func The asynchronous function to time.
+     *
+     * @returns A Promise that resolves with the result of the timed function.
      */
     time(message: string, func: () => any): Promise<any>;
     /**
-     * Attach the log to the request object: `req.$log`.
-     * This function should be called in a server middleware before storefront-core is initialized.
+     * Attaches the log instance to a request object.
+     * This is typically used in server middleware.
+     *
+     * @param req The request object.
+     * @param log The Log instance to attach.
+     *
+     * @example
+     * Log.attachToRequest(req, new Log({ space: 'myModule' }))
+     *
+     * @deprecated
      */
     static attachToRequest(req: any, log: Log): void;
 }

package/dist/utils/log.mjs

@@ -1,4 +1,7 @@
 export class Log {
+  /**
+   * The default log instance, logging to the console with the `global` namespace.
+   */
   static default = new this({
     space: "global",
     handler: consoleLogHandler
@@ -6,19 +9,48 @@ export class Log {
   _handler;
   _space;
   _type = "log";
+  /**
+   * Creates a new Log instance.
+   *
+   * @param options Options for the logger.
+   */
   constructor(options) {
     this._handler = options?.handler || Log.default._handler;
     this._space = options?.space || Log.default._space;
   }
+  /**
+   * Logs a debug message.
+   *
+   * @param message The debug message.
+   * @param data Optional additional data.
+   */
   debug(message, data) {
     this.write("debug", message, data);
   }
+  /**
+   * Logs an informational message.
+   *
+   * @param message The informational message.
+   * @param data Optional additional data.
+   */
   info(message, data) {
     this.write("info", message, data);
   }
+  /**
+   * Logs a warning message.
+   *
+   * @param message The warning message.
+   * @param data Optional additional data.
+   */
   warn(message, data) {
     this.write("warn", message, data);
   }
+  /**
+   * Logs an error message.
+   *
+   * @param message The error message or an Error object.
+   * @param data Optional additional data.
+   */
   error(message, data) {
     const error = message instanceof Error ? message : null;
     if (error) {
@@ -29,6 +61,13 @@ export class Log {
     }
     this.write("error", error?.message ?? message, data);
   }
+  /**
+   * Writes a log entry.
+   *
+   * @param level The log level.
+   * @param message The log message.
+   * @param data Optional additional data.
+   */
   write(level, message, data) {
     if (typeof data !== "undefined") {
       data = typeof data !== "object" ? { data } : data;
@@ -41,9 +80,12 @@ export class Log {
     }
   }
   /**
-   * Create a new sub-space.
-   * All spaces are being separated by a dot. E.g. `global.api` and `global.api.getUser`
-   * @param subSpace The name of the sub-space in camel-case (e.g. `api` and `api.getUser`)
+   * Creates a new Log instance with a sub-namespace.
+   * Namespaces are separated by dots (e.g., "global.api.getUser").
+   *
+   * @param subSpace The sub-namespace to add in camel-case (e.g. `api` and `api.getUser`)
+   *
+   * @returns A new Log instance with the updated namespace.
    */
   space(subSpace) {
     return new Log({
@@ -52,7 +94,12 @@ export class Log {
     });
   }
   /**
-   * Measure the time of a function.
+   * Measures the execution time of an asynchronous function and logs a debug message.
+   *
+   * @param message A message to include in the log output.
+   * @param func The asynchronous function to time.
+   *
+   * @returns A Promise that resolves with the result of the timed function.
    */
   async time(message, func) {
     const start = Date.now();
@@ -62,8 +109,16 @@ export class Log {
     return result;
   }
   /**
-   * Attach the log to the request object: `req.$log`.
-   * This function should be called in a server middleware before storefront-core is initialized.
+   * Attaches the log instance to a request object.
+   * This is typically used in server middleware.
+   *
+   * @param req The request object.
+   * @param log The Log instance to attach.
+   *
+   * @example
+   * Log.attachToRequest(req, new Log({ space: 'myModule' }))
+   *
+   * @deprecated
    */
   static attachToRequest(req, log) {
     req.$log = log;

package/dist/utils/response.d.ts

@@ -1,6 +1,11 @@
 /**
- * Unwrap a possible response into its body
- * @param res
- * @returns unwrapped response
+ * Unwraps a value that might be a `Response` object or a direct value. If it's a `Response`,
+ * it parses the JSON body and returns it; otherwise, it returns the value directly.
+ *
+ * @template T The expected type of the unwrapped value.
+ *
+ * @param res The value to unwrap, which can be a `Promise`, `Response`, or a direct value.
+ *
+ * @returns A Promise resolving to the unwrapped value.
  */
 export declare function unwrap<T>(res: Promise<Response | T> | Response | T): Promise<T>;

package/dist/utils/sapi.d.ts

@@ -1,5 +1,13 @@
 /**
- * Wrap a SAPI API function, catching any SAPI FetchErrors thrown
- * and translating them to a Response return
+ * Wraps a SAPI API function, catching SAPI FetchErrors and converting them to a structured Response.
+ * This allows handling SAPI errors in a consistent way, returning a JSON response with status information.
+ *
+ * @template T The type of the SAPI API function.
+ *
+ * @param func The SAPI API function to wrap.
+ *
+ * @returns A wrapped function that returns a Promise resolving to either the original function's result or a JSON Response representing the error.
+ *
+ * @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>;

package/dist/utils/timeout.d.ts

@@ -1,2 +1,20 @@
+/**
+ * Pauses execution for a specified number of milliseconds.
+ *
+ * @param ms The number of milliseconds to wait.
+ *
+ * @returns A Promise that resolves after the specified delay.
+ */
 export declare const wait: (ms: number) => Promise<unknown>;
+/**
+ * Wraps a promise with a timeout. Rejects the promise if it doesn't resolve within the given time.
+ *
+ * @template T The type of the promise's resolved value.
+ * @param ms The timeout duration in milliseconds.
+ * @param promise The promise to wrap.
+ *
+ * @returns A new promise that resolves or rejects based on the original promise or the timeout.
+ *
+ * @throws {Error} If the promise times out.  The error message will be "timeout".
+ */
 export declare const timeout: <T>(ms: number, promise: Promise<T>) => Promise<T>;

package/dist/utils/user.d.ts

@@ -1,4 +1,15 @@
 import type { BasketWithOptions, RpcContext } from '../types';
+/**
+ * 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.
+ *
+ * @param fromBasketKey The key of the source basket.
+ * @param toBasketKey The key of the destination basket.
+ * @param withOptions Options for retrieving basket data (including custom and order data).
+ * @param context The RPC context.
+ *
+ * @returns The merged basket.
+ */
 export declare const mergeBaskets: (fromBasketKey: string, toBasketKey: string, withOptions: BasketWithOptions & {
     orderCustomData?: Record<string, unknown>;
 }, context: RpcContext) => Promise<{
@@ -13,4 +24,15 @@ export declare const mergeBaskets: (fromBasketKey: string, toBasketKey: string,
     readonly basket: import("@scayle/storefront-api").BasketResponseData<import("@scayle/storefront-api").Product, import("@scayle/storefront-api").Variant>;
     readonly errors: import("@scayle/storefront-api").AddOrUpdateItemError[];
 } | undefined>;
+/**
+ * Merges two wishlists.  Adds the items from the `fromWishlistKey` wishlist to the `toWishlistKey` wishlist
+ * and then clears the `fromWishlistKey` wishlist.
+ *
+ * @param fromWishlistKey The key of the source wishlist.
+ * @param toWishlistKey The key of the destination wishlist.
+ * @param withOptions Options for retrieving wishlist data.
+ * @param context The RPC context.
+ *
+ * @returns Nothing (resolves when the merge operation is complete).
+ */
 export declare const mergeWishlists: (fromWishlistKey: string, toWishlistKey: string, withOptions: BasketWithOptions, context: RpcContext) => Promise<void>;

package/dist/utils/user.mjs

@@ -1,6 +1,8 @@
 import { ExistingItemHandling } from "@scayle/storefront-api";
+import { getCampaignKey } from "../rpc/methods/index.mjs";
 export const mergeBaskets = async (fromBasketKey, toBasketKey, withOptions, context) => {
-  const { sapiClient, campaignKey } = context;
+  const { sapiClient } = context;
+  const campaignKey = await getCampaignKey(context);
   const fromOriginBasket = await sapiClient.basket.get(fromBasketKey, {
     with: withOptions,
     campaignKey,
@@ -43,7 +45,8 @@ export const mergeBaskets = async (fromBasketKey, toBasketKey, withOptions, cont
   }
 };
 export const mergeWishlists = async (fromWishlistKey, toWishlistKey, withOptions, context) => {
-  const { sapiClient, campaignKey } = context;
+  const { sapiClient } = context;
+  const campaignKey = await getCampaignKey(context);
   const oldWishlist = await sapiClient.wishlist.get(fromWishlistKey, {
     with: withOptions,
     campaignKey

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scayle/storefront-core",
-  "version": "8.7.0",
+  "version": "8.8.0",
   "description": "Collection of essential utilities to work with the Storefront API",
   "author": "SCAYLE Commerce Engine",
   "license": "MIT",