@scayle/storefront-core 8.7.0 → 8.8.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @scayle/storefront-core
 
+## 8.8.0
+
+### Minor Changes
+
+- Deprecate `RpcContext.campaignKey`. The `getCampaignKey` RPC should be used instead.
+
+## 8.7.1
+
+### Patch Changes
+
+- Introduced JSDoc comments to provide additional contextual descriptions and hints.
+
 ## 8.7.0
 
 ### Minor Changes

package/dist/api/customer.d.ts

@@ -1,4 +1,9 @@
 import type { Gender, Order, RpcContext, ShopUser, ShopUserAddress } from '../types';
+/**
+ * Represents a paginated API response.
+ *
+ * @template EntityType The type of entities in the response.
+ */
 interface PaginatedResponse<EntityType> {
     entities: EntityType[];
     pagination: {
@@ -12,10 +17,16 @@ interface PaginatedResponse<EntityType> {
         total: number;
     };
 }
+/**
+ * Represents contact data for a customer.
+ */
 interface ContactData {
     email: string;
     phone: string;
 }
+/**
+ * Represents personal data for a customer.
+ */
 interface PersonalData {
     firstName: string;
     lastName: string;
@@ -23,6 +34,9 @@ interface PersonalData {
     gender?: Gender;
     title?: string;
 }
+/**
+ * Data required for updating a password.
+ */
 interface PasswordUpdate {
     password: string;
     newPassword: string;
@@ -35,15 +49,46 @@ interface PasswordUpdate {
  * @see https://scayle.dev/en/api-guides/customer-account-api
  */
 export declare class CustomerAPIClient {
+    /**
+     * Base URL for the Checkout API.
+     */
     baseURL: string;
+    /**
+     * RPC context containing authentication and other information.
+     */
     context: RpcContext;
+    /**
+     * Additional headers to include in requests.
+     */
     additionalHeaders: HeadersInit | undefined;
+    /**
+     * Creates a new instance of the CustomerAPIClient.
+     *
+     * @param context The RPC context.
+     */
     constructor(context: RpcContext);
+    /**
+     * Gets the headers for API requests, including authorization.
+     */
     get headers(): HeadersInit;
+    /**
+     * Sends an API request and handles potential token refresh.
+     *
+     * @param request The request function to execute.
+     * @param retry Whether to retry the request after a token refresh.
+     *
+     * @returns The parsed JSON response.
+     *
+     * @template BodyType The expected type of the response body.
+     */
     sendRequest<BodyType>(request: () => Promise<Response>, retry?: boolean): Promise<BodyType>;
     /**
      * Get the addresses for the current customer.
      *
+     * @param shopId The ID of the shop.
+     *
+     * @returns A paginated response containing the customer's addresses.
+     *
      * @see https://scayle.dev/en/api-guides/customer-account-api/resources/customer/address/list-addresses
      */
     getAddresses(shopId: number): Promise<PaginatedResponse<ShopUserAddress>>;
@@ -51,30 +96,58 @@ export declare class CustomerAPIClient {
      * Returns customer data and latest orders.
      * When not logged in, it will return `undefined`.
      *
+     * @param shopId The ID of the shop.
+     * @param accessToken  Optional access token to use for the request.
+     * @returns The customer data.
+     *
      * @see https://scayle.dev/en/api-guides/customer-account-api/resources/customer/get-customer
      */
     getMe(shopId: number, accessToken?: string): Promise<ShopUser>;
     /**
      * Retrieve a customer's order.
      *
+     * @param shopId The ID of the shop.
+     * @param orderId The ID of the order.
+     *
+     * @returns The customer's order.
+     *
      * @see https://scayle.dev/en/api-guides/customer-account-api/resources/order/get-order
      */
     getOrder(shopId: number, orderId: number): Promise<Order>;
     /**
      * Update contact details of a customer.
      *
+     * @param shopId The ID of the shop.
+     * @param data Contact data to update.
+     * @param data.email Customer's email address.
+     * @param data.phone Customer's phone number.
+     *
+     * @returns The updated customer data.
+     *
      * @see https://scayle.dev/en/api-guides/customer-account-api/resources/customer/update-contact-details
      */
     updateContactInfo(shopId: number, { email, phone }: Partial<ContactData>): Promise<ShopUser>;
     /**
      * Update customer personal data.
      *
+     * @param shopId The ID of the shop.
+     * @param payload Personal data to update.
+     *
+     * @returns The updated customer data.
+     *
      * @see https://scayle.dev/en/api-guides/customer-account-api/resources/customer/update-personal-data
      */
     updatePersonalInfo(shopId: number, payload: Partial<PersonalData>): Promise<ShopUser>;
     /**
      * Update customer password.
      *
+     * @param shopId The ID of the shop.
+     * @param data Data for updating the password.
+     * @param data.password Current password.
+     * @param data.newPassword New password.
+     *
+     * @returns The updated customer data.
+     *
      * @see https://scayle.dev/en/api-guides/customer-account-api/resources/customer/update-password
      */
     updatePassword(shopId: number, { password, newPassword }: PasswordUpdate): Promise<ShopUser>;

package/dist/api/customer.mjs

@@ -2,14 +2,31 @@ import { FetchError } from "../utils/fetch.mjs";
 import { HttpStatusCode } from "../constants/httpStatus.mjs";
 import { getOAuthClient } from "./oauth.mjs";
 export class CustomerAPIClient {
+  /**
+   * Base URL for the Checkout API.
+   */
   baseURL;
+  /**
+   * RPC context containing authentication and other information.
+   */
   context;
+  /**
+   * Additional headers to include in requests.
+   */
   additionalHeaders;
+  /**
+   * Creates a new instance of the CustomerAPIClient.
+   *
+   * @param context The RPC context.
+   */
   constructor(context) {
     this.baseURL = context.checkout.url;
     this.context = context;
     this.additionalHeaders = context.internalAccessHeader ? { "x-internal-access": context.internalAccessHeader } : {};
   }
+  /**
+   * Gets the headers for API requests, including authorization.
+   */
   get headers() {
     return {
       Authorization: `Bearer ${this.context.accessToken}`,
@@ -18,6 +35,16 @@ export class CustomerAPIClient {
       ...this.additionalHeaders
     };
   }
+  /**
+   * Sends an API request and handles potential token refresh.
+   *
+   * @param request The request function to execute.
+   * @param retry Whether to retry the request after a token refresh.
+   *
+   * @returns The parsed JSON response.
+   *
+   * @template BodyType The expected type of the response body.
+   */
   async sendRequest(request, retry = true) {
     const response = await request();
     if (response.ok) {
@@ -61,6 +88,10 @@ export class CustomerAPIClient {
   /**
    * Get the addresses for the current customer.
    *
+   * @param shopId The ID of the shop.
+   *
+   * @returns A paginated response containing the customer's addresses.
+   *
    * @see https://scayle.dev/en/api-guides/customer-account-api/resources/customer/address/list-addresses
    */
   async getAddresses(shopId) {
@@ -77,6 +108,10 @@ export class CustomerAPIClient {
    * Returns customer data and latest orders.
    * When not logged in, it will return `undefined`.
    *
+   * @param shopId The ID of the shop.
+   * @param accessToken  Optional access token to use for the request.
+   * @returns The customer data.
+   *
    * @see https://scayle.dev/en/api-guides/customer-account-api/resources/customer/get-customer
    */
   async getMe(shopId, accessToken) {
@@ -93,6 +128,11 @@ export class CustomerAPIClient {
   /**
    * Retrieve a customer's order.
    *
+   * @param shopId The ID of the shop.
+   * @param orderId The ID of the order.
+   *
+   * @returns The customer's order.
+   *
    * @see https://scayle.dev/en/api-guides/customer-account-api/resources/order/get-order
    */
   async getOrder(shopId, orderId) {
@@ -108,6 +148,13 @@ export class CustomerAPIClient {
   /**
    * Update contact details of a customer.
    *
+   * @param shopId The ID of the shop.
+   * @param data Contact data to update.
+   * @param data.email Customer's email address.
+   * @param data.phone Customer's phone number.
+   *
+   * @returns The updated customer data.
+   *
    * @see https://scayle.dev/en/api-guides/customer-account-api/resources/customer/update-contact-details
    */
   async updateContactInfo(shopId, { email, phone }) {
@@ -128,6 +175,11 @@ export class CustomerAPIClient {
   /**
    * Update customer personal data.
    *
+   * @param shopId The ID of the shop.
+   * @param payload Personal data to update.
+   *
+   * @returns The updated customer data.
+   *
    * @see https://scayle.dev/en/api-guides/customer-account-api/resources/customer/update-personal-data
    */
   async updatePersonalInfo(shopId, payload) {
@@ -145,6 +197,13 @@ export class CustomerAPIClient {
   /**
    * Update customer password.
    *
+   * @param shopId The ID of the shop.
+   * @param data Data for updating the password.
+   * @param data.password Current password.
+   * @param data.newPassword New password.
+   *
+   * @returns The updated customer data.
+   *
    * @see https://scayle.dev/en/api-guides/customer-account-api/resources/customer/update-password
    */
   async updatePassword(shopId, { password, newPassword }) {

package/dist/api/oauth.d.ts

@@ -1,12 +1,24 @@
 import type { GuestRequest, LoginRequest, Oauth, RefreshTokenRequest, RegisterRequest, SendResetPasswordEmailRequest, UpdatePasswordByHashRequest, UpdatePasswordRequest } from '../types/api/auth';
 import type { RpcContext } from '../types/api/context';
 import type { Log } from '../utils/log';
+/**
+ * Options for configuring the OAuth client.
+ */
 export interface OAuthOptions {
     clientId: string;
     clientSecret: string;
     apiHost: string;
     additionalHeaders?: HeadersInit;
 }
+/**
+ * Creates and returns an OAuthClient instance using the provided RPC context.
+ *
+ * @param context The RPC context containing OAuth configuration.
+ *
+ * @returns An instance of the OAuthClient.
+ *
+ * @throws {Error} If OAuth configuration is missing in the context.
+ */
 export declare function getOAuthClient(context: RpcContext): OAuthClient;
 /**
  * A client for interacting with the Checkout Authentication API
@@ -14,15 +26,37 @@ export declare function getOAuthClient(context: RpcContext): OAuthClient;
  * @see https://scayle.dev/en/api-guides/checkout-authentication-api
  */
 export declare class OAuthClient {
+    /**
+     * Headers for API requests.
+     */
     headers: HeadersInit;
+    /**
+     * Base URL for the API.
+     */
     baseURL: string;
+    /**
+     * Logger instance.
+     */
     logger?: Log;
+    /**
+     * OAuth client ID.
+     */
     clientId: string;
+    /**
+     * Creates a new instance of the OAuthClient.
+     *
+     * @param options OAuth client options.
+     * @param logger Optional logger instance.
+     *
+     * @throws {MissingCredentialsError} If client ID or client secret are missing.
+     */
     constructor(options: OAuthOptions, logger?: Log);
     /**
      * Register a new User and receive an access token.
      *
-     * @param payload
+     * @param payload The registration data.
+     *
+     * @returns The OAuth response containing access and refresh tokens.
      *
      * @see https://scayle.dev/en/api-guides/checkout-authentication-api/resources/oauth-client/create-new-user
      */
@@ -30,7 +64,9 @@ export declare class OAuthClient {
     /**
      * Login a User and receive an access token.
      *
-     * @param payload
+     * @param payload The login credentials, including the `shopId`.
+     *
+     * @returns The OAuth response containing access and refresh tokens.
      *
      * @see https://scayle.dev/en/api-guides/checkout-authentication-api/resources/oauth-client/log-in-users
      */
@@ -38,7 +74,9 @@ export declare class OAuthClient {
     /**
      * Login a User as a guest and receive an access token.
      *
-     * @param payload
+     * @param payload The guest login data.
+     *
+     * @returns The OAuth response containing access and refresh tokens.
      *
      * @see https://scayle.dev/en/api-guides/checkout-authentication-api/resources/oauth-client/log-in-users-as-guest
      */
@@ -46,7 +84,9 @@ export declare class OAuthClient {
     /**
      * Send a reset password email to a User.
      *
-     * @param payload
+     * @param payload The data for sending the reset password email.
+     *
+     * @returns Nothing (resolves when the request completes successfully).
      *
      * @see https://scayle.dev/en/api-guides/checkout-authentication-api/resources/oauth-client/send-password-reset-email
      */
@@ -55,7 +95,9 @@ export declare class OAuthClient {
      * Update password by using hash.
      * All older tokens of the User are also invalidated.
      *
-     * @param payload
+     * @param payload The data for updating the password by hash.
+     *
+     * @returns The new OAuth response with updated tokens.
      *
      * @see https://scayle.dev/en/api-guides/checkout-authentication-api/resources/oauth-client/update-password-by-hash
      */
@@ -63,20 +105,25 @@ export declare class OAuthClient {
     /**
      * Update password via plain string.
      *
-     * @param payload
-     * @param accessToken
+     * @param payload The data for updating the password (current and new password).
+     * @param accessToken The current access token.
+     *
+     * @returns Nothing (resolves when the request completes successfully).
      */
     updatePassword(payload: UpdatePasswordRequest, accessToken: string): Promise<void>;
     /**
      * Generate a new access token via a refresh token.
      *
-     * @param payload
+     * @param payload The refresh token request data.
+     * @returns The new OAuth response with updated access token.
      */
     refreshToken(payload: RefreshTokenRequest): Promise<Oauth>;
     /**
      * Validate a token.
      *
-     * @param accessToken
+     * @param accessToken The access token to validate.
+     *
+     * @returns Nothing (resolves if the token is valid, rejects otherwise).
      *
      * @see https://scayle.dev/en/api-guides/checkout-authentication-api/resources/bearer-auth/validate-present-token
      */
@@ -92,8 +139,9 @@ export declare class OAuthClient {
      * (_because a frontend redirect is required_) this step will be skipped and the IDP-Tokens
      * will remain valid until they expire or are revoked from IDP side.
      *
-     * @param shopId
-     * @param accessToken
+     * @param shopId The ID of the shop.
+     * @param accessToken The access token to use for authorization.
+     * @returns Nothing (resolves when the token is successfully revoked).
      *
      * @see https://scayle.dev/en/api-guides/checkout-authentication-api/resources/bearer-auth/delete-access-token-with-id
      */
@@ -101,7 +149,9 @@ export declare class OAuthClient {
     /**
      * Generate a new token based on authorization code.
      *
-     * @param code
+     * @param code The authorization code.
+     *
+     * @returns The new OAuth response.
      */
     generateToken(code: string): Promise<Oauth>;
 }

package/dist/api/oauth.mjs

@@ -23,9 +23,7 @@ export function getOAuthClient(context) {
   if (!context.oauth) {
     throw new Error("OAuth configuration is missing");
   }
-  const clientId = context.oauth.clientId;
-  const clientSecret = context.oauth.clientSecret;
-  const apiHost = context.oauth.apiHost;
+  const { clientId, clientSecret, apiHost } = context.oauth;
   const accessHeader = context.internalAccessHeader;
   return new OAuthClient({
     clientId,
@@ -35,10 +33,30 @@ export function getOAuthClient(context) {
   }, context.log);
 }
 export class OAuthClient {
+  /**
+   * Headers for API requests.
+   */
   headers;
+  /**
+   * Base URL for the API.
+   */
   baseURL;
+  /**
+   * Logger instance.
+   */
   logger;
+  /**
+   * OAuth client ID.
+   */
   clientId;
+  /**
+   * Creates a new instance of the OAuthClient.
+   *
+   * @param options OAuth client options.
+   * @param logger Optional logger instance.
+   *
+   * @throws {MissingCredentialsError} If client ID or client secret are missing.
+   */
   constructor(options, logger) {
     const { clientId, clientSecret, apiHost, additionalHeaders } = options;
     if (!clientId || !clientSecret) {
@@ -58,7 +76,9 @@ export class OAuthClient {
   /**
    * Register a new User and receive an access token.
    *
-   * @param payload
+   * @param payload The registration data.
+   *
+   * @returns The OAuth response containing access and refresh tokens.
    *
    * @see https://scayle.dev/en/api-guides/checkout-authentication-api/resources/oauth-client/create-new-user
    */
@@ -73,7 +93,9 @@ export class OAuthClient {
   /**
    * Login a User and receive an access token.
    *
-   * @param payload
+   * @param payload The login credentials, including the `shopId`.
+   *
+   * @returns The OAuth response containing access and refresh tokens.
    *
    * @see https://scayle.dev/en/api-guides/checkout-authentication-api/resources/oauth-client/log-in-users
    */
@@ -88,7 +110,9 @@ export class OAuthClient {
   /**
    * Login a User as a guest and receive an access token.
    *
-   * @param payload
+   * @param payload The guest login data.
+   *
+   * @returns The OAuth response containing access and refresh tokens.
    *
    * @see https://scayle.dev/en/api-guides/checkout-authentication-api/resources/oauth-client/log-in-users-as-guest
    */
@@ -103,7 +127,9 @@ export class OAuthClient {
   /**
    * Send a reset password email to a User.
    *
-   * @param payload
+   * @param payload The data for sending the reset password email.
+   *
+   * @returns Nothing (resolves when the request completes successfully).
    *
    * @see https://scayle.dev/en/api-guides/checkout-authentication-api/resources/oauth-client/send-password-reset-email
    */
@@ -119,7 +145,9 @@ export class OAuthClient {
    * Update password by using hash.
    * All older tokens of the User are also invalidated.
    *
-   * @param payload
+   * @param payload The data for updating the password by hash.
+   *
+   * @returns The new OAuth response with updated tokens.
    *
    * @see https://scayle.dev/en/api-guides/checkout-authentication-api/resources/oauth-client/update-password-by-hash
    */
@@ -134,8 +162,10 @@ export class OAuthClient {
   /**
    * Update password via plain string.
    *
-   * @param payload
-   * @param accessToken
+   * @param payload The data for updating the password (current and new password).
+   * @param accessToken The current access token.
+   *
+   * @returns Nothing (resolves when the request completes successfully).
    */
   async updatePassword(payload, accessToken) {
     this.logger?.debug("Updating password");
@@ -151,7 +181,8 @@ export class OAuthClient {
   /**
    * Generate a new access token via a refresh token.
    *
-   * @param payload
+   * @param payload The refresh token request data.
+   * @returns The new OAuth response with updated access token.
    */
   async refreshToken(payload) {
     this.logger?.debug("Refreshing access token");
@@ -164,7 +195,9 @@ export class OAuthClient {
   /**
    * Validate a token.
    *
-   * @param accessToken
+   * @param accessToken The access token to validate.
+   *
+   * @returns Nothing (resolves if the token is valid, rejects otherwise).
    *
    * @see https://scayle.dev/en/api-guides/checkout-authentication-api/resources/bearer-auth/validate-present-token
    */
@@ -188,8 +221,9 @@ export class OAuthClient {
    * (_because a frontend redirect is required_) this step will be skipped and the IDP-Tokens
    * will remain valid until they expire or are revoked from IDP side.
    *
-   * @param shopId
-   * @param accessToken
+   * @param shopId The ID of the shop.
+   * @param accessToken The access token to use for authorization.
+   * @returns Nothing (resolves when the token is successfully revoked).
    *
    * @see https://scayle.dev/en/api-guides/checkout-authentication-api/resources/bearer-auth/delete-access-token-with-id
    */
@@ -208,7 +242,9 @@ export class OAuthClient {
   /**
    * Generate a new token based on authorization code.
    *
-   * @param code
+   * @param code The authorization code.
+   *
+   * @returns The new OAuth response.
    */
   async generateToken(code) {
     return await fetch(`${this.baseURL}/oauth/token`, {

package/dist/cache/cache.d.ts

@@ -1,8 +1,55 @@
+/**
+ * Interface for Storefront-internal caching mechanism.
+ * Used for the `UnstorageCache` with `cached()`.
+ */
 export interface Cache {
+    /**
+     * Sets a value in the cache.
+     *
+     * @param key The key to store the value under.
+     * @param value The value to store in the cache.
+     * @param ttl Time-to-live in milliseconds.
+     * @param tags Optional array of tags to associate with the cached value.
+     *
+     * @returns A promise that resolves when the value is set.
+     */
     set: (key: string, value: any, ttl: number, tags?: string[]) => Promise<void>;
+    /**
+     * Retrieves a value from the cache.
+     *
+     * @param key The key of the cached value.
+     *
+     * @returns A promise that resolves with the cached value or rejects if not found.
+     */
     get: (key: string) => Promise<any>;
+    /**
+     * Checks if a key exists in the cache.
+     *
+     * @param key The key to check.
+     *
+     * @returns A promise that resolves with `true` if the key exists, `false` otherwise.
+     */
     has: (key: string) => Promise<boolean>;
+    /**
+     * Purges cached values associated with specific tags.
+     *
+     * @param tags An array of tags to purge.
+     *
+     * @returns A promise that resolves when the tags are purged.
+     */
     purgeTags: (tags: string[]) => Promise<void>;
+    /**
+     * Purges cached values by their keys.
+     *
+     * @param keys An array of keys to purge.
+     *
+     * @returns A promise that resolves when the keys are purged.
+     */
     purgeKeys: (keys: string[]) => Promise<void>;
+    /**
+     * Purges all cached values.
+     *
+     * @returns A promise that resolves when the cache is cleared.
+     */
     purgeAll: () => Promise<void>;
 }