@scayle/storefront-core 8.9.0 → 8.11.0

package/dist/rpc/methods/session.mjs

@@ -186,11 +186,11 @@ export const refreshAccessToken = async (context) => {
     });
     return { success: !!tokens };
   } catch (error) {
-    const res = convertErrorForRpcCall(error, [
+    const response = convertErrorForRpcCall(error, [
       HttpStatusCode.BAD_REQUEST,
       HttpStatusCode.UNAUTHORIZED
     ]);
-    if (res && res.status === HttpStatusCode.UNAUTHORIZED) {
+    if (response && response.status === HttpStatusCode.UNAUTHORIZED) {
       context.log.debug(
         "Failed to refresh Checkout Token due to invalid refresh token. Deleting session"
       );
@@ -200,8 +200,8 @@ export const refreshAccessToken = async (context) => {
         "Failed to refresh Checkout Token for unknown reason."
       );
     }
-    if (res) {
-      return res;
+    if (response) {
+      return response;
     }
     return { success: false };
   }
@@ -234,13 +234,13 @@ export const oauthRevokeToken = async (context) => {
     }, context);
     return { result: true };
   } catch (error) {
-    const res = convertErrorForRpcCall(error, [
+    const response = convertErrorForRpcCall(error, [
       HttpStatusCode.BAD_REQUEST,
       HttpStatusCode.UNAUTHORIZED,
       HttpStatusCode.NOT_FOUND
     ]);
-    if (res) {
-      return res;
+    if (response) {
+      return response;
     }
     return { result: false };
   }
@@ -276,14 +276,14 @@ export const oauthForgetPassword = async ({ email }, context) => {
     });
     return { success: true };
   } catch (error) {
-    const res = convertErrorForRpcCall(error, [
+    const response = convertErrorForRpcCall(error, [
       HttpStatusCode.BAD_REQUEST,
       HttpStatusCode.NOT_FOUND,
       HttpStatusCode.UNAUTHORIZED,
       HttpStatusCode.FORBIDDEN
     ]);
-    if (res) {
-      return res;
+    if (response) {
+      return response;
     }
     return { success: false };
   }
@@ -309,13 +309,13 @@ export const updatePasswordByHash = async (passwordHash, context) => {
     });
     await context.createUserBoundSession();
   } catch (error) {
-    const res = convertErrorForRpcCall(error, [
+    const response = convertErrorForRpcCall(error, [
       HttpStatusCode.BAD_REQUEST,
       HttpStatusCode.UNAUTHORIZED,
       HttpStatusCode.NOT_ACCEPTABLE
     ]);
-    if (res) {
-      return res;
+    if (response) {
+      return response;
     }
     return new ErrorResponse(
       HttpStatusCode.INTERNAL_SERVER_ERROR,

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

@@ -1,4 +1,15 @@
 import type { ShopConfiguration } from '@scayle/storefront-api';
 import type { RpcContext } from '../../types';
-declare const getShopConfiguration: ({ cached, sapiClient }: RpcContext) => Promise<Response | ShopConfiguration>;
+/**
+ * Retrieves the shop configuration.
+ *
+ * This function uses the Storefront cache (`cached()`) with a `get-shopConfigurations` key prefix to improve performance.
+ * Cached entries are returned if found; otherwise, data is fetched and cached.
+ *
+ * @param context The RPC context.
+ *
+ * @returns The shop configuration. It will return an `ErrorResponse` alternatively
+ * if the Storefront API request fails.
+ */
+declare const getShopConfiguration: (context: RpcContext) => Promise<Response | ShopConfiguration>;
 export { getShopConfiguration };

package/dist/rpc/methods/shopConfiguration.mjs

@@ -1,5 +1,6 @@
 import { mapSAPIFetchErrorToResponse } from "../../utils/sapi.mjs";
-const getShopConfiguration = async function getShopConfiguration2({ cached, sapiClient }) {
+const getShopConfiguration = async function getShopConfiguration2(context) {
+  const { cached, sapiClient } = context;
   return await cached(
     mapSAPIFetchErrorToResponse(sapiClient.shopConfiguration.get),
     {

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

@@ -1,22 +1,52 @@
 import type { RpcContext, ShopUser } from '../../types';
 import { ErrorResponse } from '../../errors';
+/**
+ * Retrieves the user from the context.
+ *
+ * @param context The RPC context.
+ *
+ * @returns An object containing the user object, or undefined if not logged in.
+ */
 declare const getUser: (context: RpcContext) => {
     user: ShopUser | undefined;
 };
+/**
+ * Fetches user data using the provided access token.
+ *
+ * @param param An object containing the access token.
+ * @param param.accessToken The access token for authentication.
+ * @param context The RPC context.
+ *
+ * @returns The fetched user data. It will return an `ErrorResponse` alternatively
+ * if an error occurs during the API call.
+ */
 declare const fetchUser: ({ accessToken }: {
     accessToken?: string;
 }, context: RpcContext) => Promise<ShopUser>;
 /**
- * This function adds a way to force fetch the user from checkout.
- * In case the user is not logged in any longer the session will be destroyed and the returned user will be undefined.
- * @param context
- * @returns ShopUser
+ * Refreshes the user session and data.
+ * If the user is no longer logged in, the session is destroyed.
+ *
+ * @param context The RPC context.
+ *
+ * @returns An object containing the user object, or undefined if session is destroyed.
+ * It will return an `ErrorResponse` if no session is found or other errors occur.
  */
 declare const refreshUser: (context: RpcContext) => Promise<ErrorResponse | {
     user: undefined;
 } | {
     user: ShopUser;
 }>;
+/**
+ * Retrieves or refreshes the access token.
+ *
+ * @param param The parameter containing the flag for forced token refresh.
+ * @param param.forceTokenRefresh Whether to force a token refresh. Defaults to false.
+ * @param context The RPC context.
+ *
+ * @returns The access token. It will return an `ErrorResponse` alternatively
+ * if no session, access token, or refresh token is found.
+ */
 declare const getAccessToken: ({ forceTokenRefresh }: {
     forceTokenRefresh?: boolean;
 } | undefined, context: RpcContext) => Promise<string | ErrorResponse>;

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

@@ -1,8 +1,36 @@
 import type { ProductWith, VariantDetail } from '@scayle/storefront-api';
 import type { RpcHandler } from '../../types';
+/**
+ * Parameters for fetching variants.
+ */
 export interface FetchVariantsParams {
+    /**
+     * Array of variant IDs.
+     */
     ids: number[];
+    /**
+     * Include related data for the variant.
+     */
     include?: ProductWith;
+    /**
+     * Price promotion key.
+     */
     pricePromotionKey?: string;
 }
+/**
+ * Retrieves variant details by their IDs.
+ *
+ * This function uses the Storefront cache (`cached()`) with a `getByIds-variants` key prefix to improve performance.
+ * Cached entries are returned if found; otherwise, data is fetched and cached.
+ *
+ * @param params Parameters for fetching the variants.
+ * @param params.ids Array of variant IDs.
+ * @param params.include Include related data for the variant. Defaults to `defaultWith`.
+ * @param params.pricePromotionKey Price promotion key. Defaults to 'default'.
+ * @param context The RPC context.
+ *
+ * @returns A Promise that resolves to an array of `VariantDetail` objects.
+ *
+ * @throws Will throw an error if the SAPI request fails.
+ */
 export declare const getVariantById: RpcHandler<FetchVariantsParams, VariantDetail[]>;

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

@@ -1,11 +1,46 @@
 import type { Wishlist } from '@scayle/storefront-api';
 import type { ParamRpcHandler, RpcHandler, WishlistWithOptions } from '../../types';
+/**
+ * Retrieves the wishlist.
+ *
+ * @param options The options for retrieving the wishlist, including optional `with` parameter.
+ * @param options.with Optional parameter for specifying additional data to include in the wishlist response.
+ * @param context The RPC context.
+ *
+ * @returns The wishlist data or an `ErrorResponse` if an error occurs.
+ * It will return an `ErrorResponse` if no session is found or if fetching the wishlist fails.
+ */
 export declare const getWishlist: RpcHandler<WishlistWithOptions | undefined, Wishlist>;
+/**
+ * Adds an item to the wishlist.
+ *
+ * @param options The options for adding an item, including product/variant ID and additional data.
+ * @param options.variantId The ID of the variant to add.
+ * @param options.productId The ID of the product to add.
+ * @param options.with Optional parameter for specifying additional data to include in the wishlist response.
+ * @param context The RPC context.
+ *
+ * @returns The updated wishlist or a `Response` object indicating the error if adding fails.
+ * It will return an `ErrorResponse` if no session is found,
+ * if neither productId nor variantId are provided, or if adding to the wishlist fails.
+ */
 export declare const addItemToWishlist: ParamRpcHandler<{
     variantId?: number;
     productId?: number;
     with?: WishlistWithOptions;
 }, Wishlist | Response>;
+/**
+ * Removes an item from the wishlist.
+ *
+ * @param options Options for removing the item.
+ * @param options.itemKey The key of the item to remove.
+ * @param options.with Optional parameter for specifying additional data to include in the wishlist response.
+ *
+ * @param context The RPC context.
+ *
+ * @returns The updated wishlist data. It will return an `ErrorResponse`
+ * if no session is found or if removing the item fails.
+ */
 export declare const removeItemFromWishlist: RpcHandler<{
     itemKey: string;
     with?: WishlistWithOptions;

package/dist/test/factories/user.d.ts

@@ -1,3 +1,13 @@
 import { Factory } from 'fishery';
 import type { ShopUser } from '../../types';
+/**
+ * Factory for creating mock `ShopUser` objects for testing.
+ *
+ * @example
+ * ```typescript
+ * const user = userFactory.build() // Generates a default ShopUser object
+ * const guestUser = userFactory.build({ isGuest: true }) // Generates a guest ShopUser
+ * const multipleUsers = userFactory.buildList(5) // Generates an array of 5 ShopUser objects.
+ * ```
+ */
 export declare const userFactory: Factory<ShopUser, any, ShopUser>;

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

@@ -1,13 +1,28 @@
 import type { Gender } from '../user';
+/**
+ * Represents a pair of OAuth 2.0 access and refresh tokens.  These tokens are used for authentication and authorization within an OAuth 2.0 flow.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-1.4
+ * @see https://scayle.dev/en/checkout-guide/authentication-accounts/token-based-authentication
+ */
 export interface OAuthTokens {
     accessToken: string;
     refreshToken: string;
 }
+/**
+ * Represents a base error object providing a structured format for error responses.
+ */
 interface BaseError {
     error: string;
     message: string;
     context: Record<any, any> | null;
 }
+/**
+ * Represents a Bad Request (400) error indicating a validation failure, often caused by incorrect client input.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
+ * @see https://scayle.dev/en/api-guides/checkout-authentication-api/getting-started/errors#_400s-status-codes
+ */
 export interface BadRequestError extends BaseError {
     error: 'validation_error';
     message: 'The property ID must be an integer.';
@@ -16,16 +31,32 @@ export interface BadRequestError extends BaseError {
         context: Record<any, any>;
     };
 }
+/**
+ * Represents an Unauthorized (401) error indicating client authentication failure, typically due to invalid credentials.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6750#section-3.1
+ * @see https://scayle.dev/en/api-guides/checkout-authentication-api/getting-started/errors#unauthorized-client
+ */
 export interface UnauthorizedError extends BaseError {
     error: 'INVALID_CLIENT';
     message: 'Client authentication failed.';
     context: null;
 }
+/**
+ * Represents the request body for login.
+ *
+ * @see https://scayle.dev/en/api-guides/checkout-authentication-api/resources/oauth-client/log-in-users
+ */
 export interface LoginRequest {
     email: string;
     password: string;
     shop_id: number;
 }
+/**
+ * Represents the request body for registration.
+ *
+ * @see https://scayle.dev/en/api-guides/checkout-authentication-api/resources/oauth-client/create-new-user
+ */
 export interface RegisterRequest {
     first_name: string;
     last_name: string;
@@ -34,6 +65,11 @@ export interface RegisterRequest {
     gender: Gender;
     shop_id: number;
 }
+/**
+ * Represents the request body for guest checkout.
+ *
+ * @see https://scayle.dev/en/api-guides/checkout-authentication-api/resources/oauth-client/log-in-users-as-guest
+ */
 export interface GuestRequest {
     first_name: string;
     last_name: string;
@@ -41,31 +77,62 @@ export interface GuestRequest {
     gender: Gender;
     shop_id: number;
 }
+/**
+ * Represents the request body for sending a password reset email.
+ *
+ * @see https://scayle.dev/en/api-guides/checkout-authentication-api/resources/oauth-client/send-password-reset-email
+ */
 export interface SendResetPasswordEmailRequest {
     email: string;
     reset_url: string;
     shop_id: number;
 }
+/**
+ * Represents the request body for updating a password using a hash.
+ *
+ * @see https://scayle.dev/en/api-guides/checkout-authentication-api/resources/oauth-client/update-password-by-hash
+ */
 export interface UpdatePasswordByHashRequest {
     password: string;
     hash: string;
     shop_id: number;
 }
+/**
+ * Represents the request body for updating a password.
+ *
+ * @see https://scayle.dev/en/api-guides/checkout-authentication-api/resources/bearer-auth/update-customers-password
+ */
 export interface UpdatePasswordRequest {
     password: string;
     new_password: string;
 }
+/**
+ * Represents the request body for refreshing an OAuth 2.0 access token using a refresh token.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6749#section-6
+ */
 export interface RefreshTokenRequest {
     grant_type: 'refresh_token';
     refresh_token: string;
 }
+/**
+ * Represents a standard OAuth 2.0 access token response as defined in RFC 6750.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc6750
+ * @see https://scayle.dev/en/api-guides/checkout-authentication-api/getting-started/authentication#auth-response
+ */
 export interface Oauth {
+    /** The type of token. A `Bearer` token indicates that anyone who possesses the token can use it to access the protected resources, without further authentication. */
     token_type: 'Bearer';
+    /** The lifetime of the access token in seconds. */
     expires_in: number;
+    /** The access token string issued by the authorization server. */
     access_token: string;
+    /** A refresh token that can be used to obtain a new access token. */
     refresh_token: string;
 }
 /**
+ * Represents an IDP configuration.
  * This adds `string` so it's flexible enough to support
  * multiple IDPs since we don't know what they are.
  * More narrow type can be defined in the nuxt modules.

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

@@ -6,6 +6,9 @@ import type { AuthenticationType, ShopUser } from '../user';
 import type { BasketWithOptions, CategoryWith, ProductCategoryWith, ProductWith, SearchV2With, SearchWith, VariantWith, WishlistWithOptions } from '../';
 import type { IDPConfig, OAuthTokens } from './auth';
 import type { RpcMethodCall } from '../..';
+/**
+ * Parameters that can be included in the request context.
+ */
 export type WithParams = Partial<{
     basket: BasketWithOptions;
     wishlist: WishlistWithOptions;
@@ -16,11 +19,32 @@ export type WithParams = Partial<{
     searchV2: SearchV2With;
     variant: VariantWith;
 }>;
+/**
+ * Represents runtime configuration options.
+ */
 export interface RuntimeConfiguration {
     [key: string]: any;
 }
+/**
+ * Additional context information for RPC calls.
+ * AThis interface can be augmented to extend the `RpcContext` type and
+ * allows to adding custom properties to the RPC context.
+ *
+ * @example
+ * ```typescript
+ * // Augment AdditionalRpcContext type
+ * declare module '@scayle/storefront-core' {
+ *   interface AdditionalRpcContext {
+ *     myNewProp: string
+ *   }
+ * }
+ * ```
+ */
 export interface AdditionalRpcContext {
 }
+/**
+ * Context interface with session information.
+ */
 export interface ContextWithSession {
     wishlistKey: string;
     basketKey: string;
@@ -33,6 +57,9 @@ export interface ContextWithSession {
     updateUser: (user: ShopUser) => void;
     updateTokens: (tokens: OAuthTokens) => void;
 }
+/**
+ * Context interface without session information.
+ */
 export interface ContextWithoutSession {
     wishlistKey: undefined;
     basketKey: undefined;
@@ -45,21 +72,39 @@ export interface ContextWithoutSession {
     updateUser: undefined;
     updateTokens: undefined;
 }
+/**
+ * Information provided after a successful login.
+ */
 interface LoginInformation {
     shopId: number;
     user: ShopUser;
     authenticationType?: AuthenticationType;
     accessToken: string;
 }
+/**
+ * Information provided after a successful logout.
+ */
 interface LogoutInformation {
     shopId: number;
     user: ShopUser;
     authenticationType?: AuthenticationType;
 }
+/**
+ * Hooks for storefront events.
+ */
 export interface StorefrontHooks {
+    /**
+     * Hook called after a successful login.
+     */
     'storefront:afterLogin': (loginInfo: LoginInformation, context: RpcContext) => Promise<void> | void;
+    /**
+     * Hook called after a successful logout.
+     */
     'storefront:afterLogout': (logoutInfo: LogoutInformation, context: RpcContext) => Promise<void> | void;
 }
+/**
+ * The main RPC context interface, combining various properties.
+ */
 export type RpcContext = {
     locale: string;
     checkout: {
@@ -123,7 +168,23 @@ export type RpcContext = {
     callHookWith?: Hookable<StorefrontHooks>['callHookWith'];
     callRpc?: RpcMethodCall;
 } & AdditionalRpcContext & (ContextWithoutSession | ContextWithSession);
+/**
+ * RPC context type with guaranteed session information.
+ */
 export type RpcContextWithSession = RpcContext & ContextWithSession;
+/**
+ * Assertion function to narrow the type of `RpcContext` to `RpcContextWithSession`.
+ *
+ * @param context - The RPC context object.
+ *
+ * @throws {Error} If `context.sessionId` is not defined.
+ */
 export declare function assertSession(context: RpcContext): asserts context is RpcContextWithSession;
+/**
+ * Type guard function to check if the provided `RpcContext` has session information.
+ * @param context The RPC context object.
+ *
+ * @returns True if `context.sessionId` is defined, false otherwise.
+ */
 export declare function hasSession(context: RpcContext): context is RpcContextWithSession;
 export {};

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

@@ -1,4 +1,23 @@
 import type { RpcContext } from './context';
+/**
+ * Type for an RPC handler that accepts parameters.
+ *
+ * @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;
+/**
+ * Type for an RPC handler that does not accept parameters.
+ *
+ * @template ResponseType The type of the response.
+ */
 export type NoParamRpcHandler<ResponseType> = (context: RpcContext) => Promise<ResponseType | Response> | ResponseType | Response;
+/**
+ * Generic RPC handler type. Handles both cases with and without parameters.
+ *
+ * @template A The response type if no parameters are used, or the parameters type if parameters are used.
+ * @template B The response type if parameters are used.
+ * If `void`, no parameters are expected.
+ * This allows for defining RPC handlers that either accept parameters or not.
+ */
 export type RpcHandler<A, B = void> = B extends void ? NoParamRpcHandler<A> : ParamRpcHandler<A, B>;

package/dist/types/breadcrumb.d.ts

@@ -1,4 +1,13 @@
+/**
+ * Represents an item in a breadcrumb navigation.
+ */
 export interface BreadcrumbItem {
+    /**
+     * The displayed text for the breadcrumb item.
+     */
     value: string;
+    /**
+     * The navigation target (URL or route) for the breadcrumb item.
+     */
     to: string;
 }

package/dist/types/promises.d.ts

@@ -1,2 +1,12 @@
+/**
+ * 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>>;

package/dist/types/sapi/basket.d.ts

@@ -1,23 +1,48 @@
 import type { BasketItemDisplayData, BasketItemDisplayDataKey, BasketResponse, BasketResponseData, BasketWith, BasketItemDisplayDataItem, CreateBasketItemParameters, ItemGroup } from '@scayle/storefront-api';
+/**
+ * Represents custom data for a basket item. Corresponds to the `customData` property
+ * of `CreateBasketItemParameters`.
+ */
 export type BasketCustomData = Pick<CreateBasketItemParameters, 'customData'>;
+/**
+ * Represents display data for a basket item. Uses a partial record to allow flexibility in
+ * which display data keys are present.
+ */
 export type BasketDisplayData = Partial<Record<BasketItemDisplayDataKey, BasketItemDisplayDataItem>>;
-export type { BasketItemDisplayData, BasketItemDisplayDataItem, BasketResponseData, BasketWith, BasketResponse, ItemGroup, };
+/**
+ * Parameters for adding or updating an item in the basket.
+ */
 export interface AddOrUpdateItemType {
     variantId: number;
     quantity: number;
+    /** Display data for the item. */
     displayData?: BasketItemDisplayData;
+    /** Custom data for the item. */
     customData?: {
         [key: string | number]: any;
     };
+    /** Item group for the item. */
     itemGroup?: ItemGroup;
+    /** If the product is not in the "catalog" anymore, keep it in the basket */
     includeItemsWithoutProductData?: boolean;
     promotionId?: string | null;
 }
+/**
+ * Options for fetching a basket, extending the base `BasketWith` type.
+ */
 export interface BasketWithOptions extends BasketWith {
+    /** Key for filtering the price promotions */
     pricePromotionKey?: string;
+    /** if the product is not in the "catalog" anymore, keep it in the basket */
     includeItemsWithoutProductData?: boolean;
 }
+/**
+ * Parameters for the `useBasket` composable.
+ */
 export interface UseBasketParams {
+    /** Key for caching. */
     key?: string;
+    /** Data to include with the basket. */
     with: BasketWithOptions;
 }
+export type { BasketItemDisplayData, BasketItemDisplayDataItem, BasketResponseData, BasketWith, BasketResponse, ItemGroup, };