@scayle/storefront-core 8.8.0 → 8.10.0

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

@@ -1,4 +1,46 @@
-import type { PromotionsParams, PromotionsResponseData } from '../../types';
-export declare const getPromotions: (params: Omit<PromotionsParams, "ids"> | undefined, context: import("../../types").RpcContext) => Promise<Response | PromotionsResponseData>;
-export declare const getCurrentPromotions: (params: Omit<PromotionsParams, "ids" | "activeAt"> | undefined, context: import("../../types").RpcContext) => Promise<Response | PromotionsResponseData>;
-export declare const getPromotionsByIds: (ids: string[], context: import("../../types").RpcContext) => Promise<Response | PromotionsResponseData>;
+import type { PromotionsParams, PromotionsResponseData, RpcContext } from '../../types';
+/**
+ * Retrieves promotions based on provided parameters.
+ *
+ * This function uses the Storefront cache (`cached()`) with a `getPromotions` key prefix to improve performance.
+ * Cached entries are returned if found; otherwise, data is fetched and cached.
+ *
+ * @param params The parameters for retrieving promotions.
+ * @param params.pagination Pagination settings.
+ * @param params.pagination.page Page number.
+ * @param params.pagination.perPage Number of items per page.
+ * @param context The RPC context.
+ *
+ * @returns A Promise that resolves with the promotion data.
+ * It will return an `ErrorResponse` if the The Storefront API request fails.
+ */
+export declare const getPromotions: (params: Omit<PromotionsParams, "ids"> | undefined, context: RpcContext) => Promise<Response | PromotionsResponseData>;
+/**
+ * Retrieves currently active promotions.
+ *
+ * This function uses the Storefront cache (`cached()`) with a `getPromotions` key prefix to improve performance.
+ * Cached entries are returned if found; otherwise, data is fetched and cached.
+ *
+ * @param params The parameters for retrieving promotions.
+ * @param params.pagination Pagination settings.
+ * @param params.pagination.page Page number.
+ * @param params.pagination.perPage Number of items per page.
+ * @param context The RPC context.
+ *
+ * @returns A Promise that resolves with the current promotion data.
+ * It will return an `ErrorResponse` if the The Storefront API request fails.
+ */
+export declare const getCurrentPromotions: (params: Omit<PromotionsParams, "ids" | "activeAt"> | undefined, context: RpcContext) => Promise<Response | PromotionsResponseData>;
+/**
+ * Retrieves promotions by their IDs.
+ *
+ * This function uses the Storefront cache (`cached()`) with a `getByIds-promotions` key prefix to improve performance.
+ * Cached entries are returned if found; otherwise, data is fetched and cached.
+ *
+ * @param ids An array of promotion IDs.
+ * @param context The RPC context.
+ *
+ * @returns A Promise that resolves with the promotion data.
+ * It will return an `ErrorResponse` if the The Storefront API request fails.
+ */
+export declare const getPromotionsByIds: (ids: string[], context: RpcContext) => Promise<Response | PromotionsResponseData>;

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

@@ -1,25 +1,30 @@
 import type { SearchEntity, SearchV2ResolveEndpointParameters, SearchV2SuggestionsEndpointParameters, SearchV2SuggestionsEndpointResponseData } from '../../types/sapi/search';
+import type { RpcContext } from '../../types';
 /**
  * Fetches search suggestions for a given term.
  *
- * @param option - The parameters for the request.
- * @param option.term - The term to search for.
- * @param option.with - An object describing which data the returned suggestions should contain.
- * @param option.categoryId - The category ID to search within.
- * @param context - The rpc context associated with the request.
+ * @param option The parameters for the request.
+ * @param option.term The term to search for.
+ * @param option.with An object describing which data the returned suggestions should contain.
+ * @param option.categoryId The category ID to search within.
+ * @param context The RPC context.
  *
  * @returns A promise that resolves to a list of search suggestions.
+ * It will return an `ErrorResponse` if the request fails.
  */
-export declare const getSearchSuggestions: ({ term, with: _with, categoryId }: SearchV2SuggestionsEndpointParameters, { sapiClient, withParams }: import("../../types").RpcContext) => Promise<Response | SearchV2SuggestionsEndpointResponseData>;
+export declare const getSearchSuggestions: ({ term, with: _with, categoryId }: SearchV2SuggestionsEndpointParameters, context: RpcContext) => Promise<Response | SearchV2SuggestionsEndpointResponseData>;
 /**
  * Resolves a search query and returns the resolved entity.
  *
- * @param option - The parameters for the search query.
- * @param option.term - The search query to resolve.
- * @param option.with - An object describing which data the returned result should contain.
- * @param option.categoryId - The category ID for which the search should be performed.
- * @param context - The rpc context associated with the request.
+ * This function uses the Storefront cache (`cached()`) with a `resolve-${term}` key prefix to improve performance.
+ * Cached entries are returned if found; otherwise, data is fetched and cached.
+ *
+ * @param option The parameters for the search query.
+ * @param option.term The search query to resolve.
+ * @param option.with An object describing which data the returned result should contain.
+ * @param option.categoryId The category ID for which the search should be performed.
+ * @param context The RPC context.
  *
  * @returns A promise that resolves to the resolved entity or null if no entity is found.
  */
-export declare const resolveSearch: ({ term, with: _with, categoryId }: SearchV2ResolveEndpointParameters, { cached, sapiClient, withParams }: import("../../types").RpcContext) => Promise<SearchEntity | null>;
+export declare const resolveSearch: ({ term, with: _with, categoryId }: SearchV2ResolveEndpointParameters, context: RpcContext) => Promise<SearchEntity | null>;

package/dist/rpc/methods/search.mjs

@@ -1,5 +1,6 @@
 import { mapSAPIFetchErrorToResponse } from "../../utils/sapi.mjs";
-export const getSearchSuggestions = async function getSearchSuggestions2({ term, with: _with, categoryId }, { sapiClient, withParams }) {
+export const getSearchSuggestions = async function getSearchSuggestions2({ term, with: _with, categoryId }, context) {
+  const { sapiClient, withParams } = context;
   return await mapSAPIFetchErrorToResponse(sapiClient.searchv2.suggestions)(
     term,
     {
@@ -8,7 +9,8 @@ export const getSearchSuggestions = async function getSearchSuggestions2({ term,
     }
   );
 };
-export const resolveSearch = async function resolveSearch2({ term, with: _with, categoryId }, { cached, sapiClient, withParams }) {
+export const resolveSearch = async function resolveSearch2({ term, with: _with, categoryId }, context) {
+  const { cached, sapiClient, withParams } = context;
   const resolvedEntity = await cached(sapiClient.searchv2.resolve, {
     cacheKeyPrefix: `resolve-${term}`
   })(term, {

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

@@ -1,20 +1,82 @@
 import type { Optional } from 'utility-types';
 import type { GuestRequest, LoginRequest, Oauth, RegisterRequest, RpcContext, RpcContextWithSession, ShopUser, UpdatePasswordByHashRequest } from '../../types';
 import { ErrorResponse } from '../../errors';
+/**
+ * Handles the post-login logic, including fetching user data, updating tokens,
+ * merging baskets and wishlists, and creating a user-bound session.
+ *
+ * @param context The RPC context with session information.
+ * @param tokens The OAuth tokens.
+ *
+ * @returns The result of the post login operation. It will return
+ * an `ErrorResponse` if fetching the user or merging baskets/wishlists fails.
+ */
 export declare function postLogin(context: RpcContextWithSession, tokens: Oauth): Promise<(ShopUser & ErrorResponse) | undefined>;
+/**
+ * Handles OAuth login requests.
+ *
+ * @param login The login request data. Includes `email` and `password` keys.
+ * @param context The RPC context.
+ *
+ * @returns A Response object indicating the login status. It will return
+ * an `ErrorResponse` if login fails.
+ */
 export declare const oauthLogin: (login: Optional<LoginRequest, "shop_id">, context: RpcContext) => Promise<Response>;
+/**
+ * Handles OAuth user registration requests.
+ *
+ * @param register The registration request data.
+ * @param context The RPC context.
+ *
+ * @returns A Response object indicating the registration status. It will return
+ * an `ErrorResponse` if registration fails.
+ */
 export declare const oauthRegister: (register: Optional<RegisterRequest, "shop_id">, context: RpcContext) => Promise<Response>;
+/**
+ * Handles OAuth guest login requests.
+ *
+ * @param guest The guest login request data.
+ * @param context The RPC context.
+ *
+ * @returns A Response object indicating the login status. It will return
+ * an `ErrorResponse` if guest login fails.
+ */
 export declare const oauthGuestLogin: (guest: Optional<GuestRequest, "shop_id">, context: RpcContext) => Promise<Response>;
+/**
+ * Refreshes the access token using the refresh token.
+ *
+ * @param context The RPC context.
+ *
+ * @returns An object indicating the success status of the refresh operation.
+ *  It will return an `ErrorResponse` if refreshing the token fails.
+ */
 export declare const refreshAccessToken: (context: RpcContext) => Promise<Response | {
     success: true;
 } | {
     success: false;
 }>;
+/**
+ * Revokes the current access token and destroys the session.
+ *
+ * @param context The RPC context.
+ *
+ * @returns An object indicating the result of the revocation.
+ * It will return an `ErrorResponse` if revoking the token fails.
+ */
 export declare const oauthRevokeToken: (context: RpcContext) => Promise<Response | {
     result: true;
 } | {
     result: false;
 }>;
+/**
+ * Sends a password reset email to the specified email address.
+ *
+ * @param email The email address for password reset. Includes email key.
+ * @param context The RPC context.
+ *
+ * @returns An object indicating the success status of the operation.
+ * It will return an `ErrorResponse` if sending the password reset email fails.
+ */
 export declare const oauthForgetPassword: ({ email }: {
     email: string;
 }, context: RpcContext) => Promise<Response | {
@@ -22,4 +84,13 @@ export declare const oauthForgetPassword: ({ email }: {
 } | {
     success: false;
 }>;
+/**
+ * Updates the password using a password hash.
+ *
+ * @param passwordHash The password hash data.
+ * @param context The RPC context.
+ *
+ * @returns A Response object indicating the status of the password update.
+ * It will return an `ErrorResponse` if updating the password fails.
+ */
 export declare const updatePasswordByHash: (passwordHash: Optional<UpdatePasswordByHashRequest, "shop_id">, context: RpcContext) => Promise<Response>;

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 { RpcContext } from '../../types';
+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;
 }
-export declare const getVariantById: ({ ids, include, pricePromotionKey }: FetchVariantsParams, context: RpcContext) => Promise<Response | VariantDetail[]>;
+/**
+ * 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/variants.mjs

@@ -1,11 +1,10 @@
 import { mapSAPIFetchErrorToResponse } from "../../utils/sapi.mjs";
-import { getCampaignKey } from "./campaign.mjs";
 const defaultWith = {
   attributes: "all"
 };
 export const getVariantById = async function getVariantById2({ ids, include = defaultWith, pricePromotionKey = "default" }, context) {
   const { sapiClient, cached, withParams } = context;
-  const campaignKey = await getCampaignKey(context);
+  const campaignKey = await context.callRpc?.("getCampaignKey");
   const resolvedWith = include ?? withParams?.variant ?? defaultWith;
   return await cached(
     mapSAPIFetchErrorToResponse(sapiClient.variants.getByIds),

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

@@ -1,13 +1,48 @@
 import type { Wishlist } from '@scayle/storefront-api';
-import type { RpcContext, WishlistWithOptions } from '../../types';
-export declare const getWishlist: (options: WishlistWithOptions | undefined, context: RpcContext) => Promise<Response | Wishlist>;
-export declare const addItemToWishlist: (options: {
+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;
-}, context: RpcContext) => Promise<Wishlist | Response>;
-export declare const removeItemFromWishlist: (options: {
+}, 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;
-}, context: RpcContext) => Promise<Response | Wishlist>;
-export declare const clearWishlist: (context: RpcContext) => Promise<Response | Wishlist>;
+}, Wishlist>;
+export declare const clearWishlist: RpcHandler<Wishlist>;

package/dist/rpc/methods/wishlist.mjs

@@ -7,7 +7,6 @@ import {
 import { unwrap } from "../../utils/response.mjs";
 import { ErrorResponse } from "../../errors/index.mjs";
 import { mapSAPIFetchErrorToResponse } from "../../utils/sapi.mjs";
-import { getCampaignKey } from "./campaign.mjs";
 function getWithParams(params, context) {
   return params.with ?? context.withParams?.wishlist ?? MIN_WITH_PARAMS_WISHLIST;
 }
@@ -20,7 +19,7 @@ export const getWishlist = async function getWishlist2(options, context) {
     );
   }
   const { sapiClient, wishlistKey } = context;
-  const campaignKey = await getCampaignKey(context);
+  const campaignKey = await context.callRpc?.("getCampaignKey");
   const resolvedWith = getWithParams({ with: options }, context);
   return await mapSAPIFetchErrorToResponse(sapiClient.wishlist.get)(
     wishlistKey,
@@ -40,7 +39,7 @@ export const addItemToWishlist = async function addItemToWishlist2(options, cont
     );
   }
   const { sapiClient, wishlistKey } = context;
-  const campaignKey = await getCampaignKey(context);
+  const campaignKey = await context.callRpc?.("getCampaignKey");
   const { productId, variantId } = options;
   const resolvedWith = getWithParams(options, context);
   const pricePromotionKey = resolvedWith?.pricePromotionKey ?? "";
@@ -77,7 +76,7 @@ export const removeItemFromWishlist = async function removeItemFromWishlist2(opt
     );
   }
   const { sapiClient, wishlistKey } = context;
-  const campaignKey = await getCampaignKey(context);
+  const campaignKey = await context.callRpc?.("getCampaignKey");
   const resolvedWith = getWithParams(options, context);
   return await mapSAPIFetchErrorToResponse(sapiClient.wishlist.deleteItem)(
     wishlistKey,

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.