@scayle/storefront-core/CHANGELOG.md

Collection of essential utilities to work with the Storefront API

# @scayle/storefront-core

## 8.61.2

No changes in this release.

## 8.61.1

No changes in this release.

## 8.61.0

### Minor Changes

- **[RPC]** `defineRpcHandler` now accepts an optional `method` option (`'GET' | 'POST' | 'PUT' | 'DELETE'`) to declare the HTTP method for the handler. Defaults to `'POST'`, so existing handlers behave exactly as before. 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.

  User- and session-specific RPCs (`getBasket`, `getUser`, `fetchUser`, `getWishlist`, `getAccessToken`, `getCheckoutToken`, `getOrderById`, `getCheckoutDataByCbd`, `getShopUserAddress`) intentionally stay on `POST` so their responses are never eligible for CDN or browser caching.

  ```ts
  import { defineRpcHandler, type RpcContext } from '@scayle/storefront-core'

  // Safe, public read — eligible for CDN/browser caching
  export const getNavigation = defineRpcHandler(
    async (context: RpcContext) => {
      /* ... */
    },
    { method: 'GET' },
  )

  // User-specific / Mutation — uses POST to prevent cache leakage
  export const getBasket = defineRpcHandler(
    async (context: RpcContext) => {
      /* ... */
    },
    // method defaults to 'POST'
  )
  ```

### Patch Changes

- Updated dependency `@scayle/storefront-api@workspace:*` to `@scayle/storefront-api@catalog:`
- Updated dependency `@scayle/unstorage-scayle-kv-driver@workspace:*` to `@scayle/unstorage-scayle-kv-driver@catalog:`

## 8.60.1

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/unstorage-scayle-kv-driver@2.1.1

## 8.60.0

### Minor Changes

- All packages now require Node.js 22 or later, in line with the current Node.js LTS release schedule. See the [Node.js release schedule](https://nodejs.org/en/about/previous-releases#release-schedule) for details.

  If your project is still running an older Node.js version, now is a good time to upgrade to Node.js 22 at minimum, or ideally Node.js 24, for the latest security patches and stability improvements.

## 8.59.7

### Patch Changes

- Updated dependency `slugify@^1.6.6` to `slugify@^1.6.8`

**Dependencies**

- Updated dependency to @scayle/unstorage-scayle-kv-driver@2.0.11
- Updated dependency to @scayle/storefront-api@18.22.0

## 8.59.6

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.22.0

## 8.59.5

## 8.59.4

### Patch Changes

- Fixed error handling in `oauthRegister` and other OAuth-related RPC methods to properly propagate HTTP status codes like 409 Conflict instead of converting them to 500 Internal Server Error.

  The `convertErrorForRpcCall` function now correctly handles `OAuthRequestError` instances that wrap `FetchError` objects. Previously, when OAuth API errors occurred (such as attempting to register with an existing email), the error handling only checked for direct `FetchError` instances, causing wrapped errors to fall through to a generic 500 error response. Now the function extracts the underlying `FetchError` from `OAuthRequestError` instances, ensuring that the correct HTTP status codes are returned to the frontend.

## 8.59.3

## 8.59.2

### Patch Changes

- Deprecated the `slugify` and `getProductPath` functions in `productHelpers.ts` due to compatibility issues with Nuxt 4.

  To maintain compatibility with Nuxt 4, these functions have been deprecated. Developers should migrate to using `useRouteHelpers().slugify()` instead. Additionally, the `slugify` package must be added as a direct dependency in your Storefront Application.

  **Migration:**

  ```ts
  import baseSlugify from 'slugify'

  const slugify = (url: string | undefined): string => {
    return baseSlugify(url ?? '', {
      lower: true,
      remove: /[*+~.()'"!:@/#?]/g,
    })
  }

  const localePath = useLocalePath()

  const getProductDetailRoute = (
    id: number,
    name?: string,
    locale?: Locale,
  ): string => {
    return localePath(
      {
        name: 'p-productName-id',
        params: {
          productName: slugify(name),
          id: `${id}`,
        },
      },
      locale,
    )
  }
  ```

## 8.59.1

### Patch Changes

- Fixed import compatibility issue with the `slugify` package in `productHelpers.ts` to support both ESM and CommonJS module formats.

  The import was changed from a default import to a namespace import with a fallback, ensuring the `baseSlugify` function works correctly across different module systems and build configurations.

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.21.0
- Updated dependency to @scayle/unstorage-scayle-kv-driver@2.0.10

## 8.59.0

### Minor Changes

- Added type exports for similar products functionality by re-exporting `SimilarProductsEndpointParameters` and `SimilarProductsEndpointResponseData` from `@scayle/storefront-api`. These types enable type-safe usage of similar products endpoints throughout the storefront core.

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.21.0

## 8.58.0

## 8.57.3

## 8.57.2

### Patch Changes

- Updated dependency `hookable@^5.5.3` to `hookable@catalog:`
- Updated dependency `jose@^6.0.8` to `jose@catalog:`
- Updated dependency `ufo@^1.5.3` to `ufo@catalog:`
- Updated dependency `uncrypto@^0.1.3` to `uncrypto@catalog:`
- Updated dependency `utility-types@^3.11.0` to `utility-types@catalog:`
- This is an internal change only. The packages now use the PNPM catalog feature to ensure dependencies use the identical version across packages.

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.20.1
- Updated dependency to @scayle/unstorage-scayle-kv-driver@2.0.10

## 8.57.1

## 8.57.0

### Minor Changes

- **\[Navigation\]** Exported Navigation V2 API types to provide TypeScript support for the new navigation endpoints.

  The following types are now available from `@scayle/storefront-core`:
  - `GetNavigationV2Parameters` - Parameters for fetching navigation trees via the V2 API
  - `NavigationV2AllEndpointResponseData` - Response type for fetching all navigation trees
  - `NavigationV2ByReferenceEndpointResponseData` - Response type for fetching a navigation tree by reference key

  These types enable full TypeScript support when working with the Navigation V2 API, which uses reference keys instead of numeric IDs for more flexible navigation management.

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.20.0

## 8.56.0

### Minor Changes

- Added support for custom session data in the RPC context type definitions.

  The `ContextWithSession` interface now includes a `sessionCustomData` property (which may be `undefined`) to read custom session data and an `updateSessionCustomData` method to update it.
  The `ContextWithoutSession` interface has been updated accordingly to maintain type consistency.
  The `SessionCustomData` interface can be augmented using TypeScript module augmentation to provide type safety for custom session properties.

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.19.0
- Updated dependency to @scayle/unstorage-scayle-kv-driver@2.0.9

## 8.55.0

### Minor Changes

- Updated the type of the `removeItemFromBasket` RPC to accurately reflect that error responses can be returned if removing an item from the basket fails (these error responses were already being returned before; only the type was updated). Additionally, the `clearBasket` RPC now removes items sequentially to avoid conflicts between basket updates and returns an error response if any items in the basket could not be removed.

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.19.0

## 8.54.0

### Minor Changes

- The `getCheckoutToken` RPC was updated to refresh the access token only when it was about to expire within 30 minutes. This change reduced unnecessary access token generation and minimized the risk of using outdated or revoked tokens.

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.18.1
- Updated dependency to @scayle/unstorage-scayle-kv-driver@2.0.9

## 8.53.3

## 8.53.2

## 8.53.1

### Patch Changes

- Updated `fetchAllFiltersForCategory`, `getFilters`, `getProductsCount`, and `getProductsByCategory` RPC methods to support `includeSoldOut`, `includeSellableForFree`, and `orFiltersOperator` parameters. These parameters are now correctly passed to the Storefront API client, ensuring consistent filtering behavior.

**Dependencies**

- Updated dependency to @scayle/unstorage-scayle-kv-driver@2.0.9
- Updated dependency to @scayle/storefront-api@18.18.1

## 8.53.0

### Minor Changes

- Added support for promotions on order items by introducing the `OrderItemPromotion` interface and extending the `OrderItem` type with an optional `promotions` field.

  This enables developers to access promotion information (`id`, `name`, and `version`) directly from order items, improving visibility into which promotions were applied to each item in an order.
  Additionally, the `appliedReductions` array within the order item price now includes an optional `id` field, allowing for better tracking and identification of specific discount reductions.

  For further details, see the [Order API](https://scayle.dev/en/api-guides/storefront-api/resources/orders).

## 8.52.0

### Minor Changes

- Extended the `OrderItem` type to support `'promotion'` as a valid category in `appliedReductions`, enabling proper type checking for promotion-based discounts in order items.

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.18.1
- Updated dependency to @scayle/unstorage-scayle-kv-driver@2.0.8

## 8.51.0

### Minor Changes

- Added an email hash (`emailHash`) property to the user object returned by the `fetchUser` RPC method.

  The `emailHash` property is automatically included in all user objects returned by the RPCs.
  The email hash is calculated server-side using SHA256 and is automatically included when a user has an email address.
  This can be used e.g., for compliant user tracking and analytics without exposing sensitive email information.

## 8.50.0

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/unstorage-scayle-kv-driver@2.0.8

## 8.49.0

### Minor Changes

- Exported the `sha256` utility function as part of the public API.

  This function provides a convenient way to calculate SHA256 hashes of strings using the Web Crypto API, returning hexadecimal strings.
  Developers can now use this utility directly instead of implementing their own hashing logic or importing external cryptographic libraries.

  Example:

  ```ts
  import { sha256 } from '@scayle/storefront-core'

  const hash = await sha256('hello')
  console.log(hash) // '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824'
  ```

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.18.1
- Updated dependency to @scayle/unstorage-scayle-kv-driver@2.0.7

## 8.48.1

### Patch Changes

- Export `SmartSortingKey` constant containing all predefined smart sorting keys for intelligent product sorting. Smart sorting keys provide advanced sorting algorithms that consider multiple factors like discounts, inventory levels, sales performance, and recency to optimize product listings.

  Available keys:
  - `SmartSortingKey.SALES_PUSH` - Promotes items with highest discounts and oldest inventory
  - `SmartSortingKey.NEW_ARRIVALS` - Prioritizes recently added products with good availability
  - `SmartSortingKey.BALANCED_OFFERINGS` - Balances recency, availability, discounts, and sales data
  - `SmartSortingKey.INVENTORY_OPTIMIZATION` - Optimizes inventory turnover for high stock products
  - `SmartSortingKey.LUXURY_PROMOTION` - Highlights high-value luxury items with discounts
  - `SmartSortingKey.STOCK_COVERAGE` - Ensures broad variant availability across products
  - `SmartSortingKey.TOPSELLER` - Prioritizes products with strong sales performance
  - `SmartSortingKey.REVENUE_MAX` - Maximizes revenue by prioritizing high revenue products
  - `SmartSortingKey.RECENTLY_POPULAR` - Favors products with high recent sales performance

  These keys can be used with the `sortingKey` parameter in product queries and are intended to be used with descending sort order to return most relevant results first.

  For further information on smart product sorting and how to use smart sorting keys, visit: https://scayle.dev/en/core-documentation/the-basics/products/product-sorting

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.18.1

## 8.48.0

## 8.47.0

### Minor Changes

- Enhanced basket RPC methods to support order custom data functionality.

  All basket RPC methods now integrate with the `getOrderCustomData` RPC method to fetch and include order custom data in SAPI requests.
  This enables developers to attach order-specific custom metadata, business rules, or additional context to orders throughout the basket lifecycle.
  The existing `orderCustomData` parameter is deprecated and will be removed in the next major version.
  For now, both parameters are supported and merged together, where attributes from the parameter take precedence.

  On default, this RPC returns an empty object but can be overridden by the developer to return a custom object.

  Example `getOrderCustomData` RPC:

  ```typescript
  export const getOrderCustomData: RpcHandler<Record<string, unknown>> =
    defineRpcHandler<Record<string, unknown>>(async (context: RpcContext) => {
      return {
        customer: {
          groups: context.user?.groups,
        },
      }
    })
  ```

  For further information, please refer to the [Overriding Core RPC Methods](https://scayle.dev/en/core-documentation/storefront-guide/storefront-application/technical-foundation/rpc-methods?sourceText=RPC%2520Methods#overriding-core-rpc-methods).

- Updated all basket RPC methods to pass the customer access token to the SAPI client, enabling the `X-Customer-Token` header for promotion validation.

  The customer access token is now automatically included in basket requests when available.
  If the token has expired, it will be omitted from the request to prevent validation errors.

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/unstorage-scayle-kv-driver@2.0.7
- Updated dependency to @scayle/storefront-api@18.18.0

## 8.46.0

### Minor Changes

- Added `getAttributeValuesByGroupId` function to the `attributeHelpers` helper for retrieving attribute values by their numeric attribute group ID.

  This function allows you to retrieve attribute values filtered by a specific attribute group ID, providing a more targeted approach when working with grouped product attributes.
  The existing `getAttributeValues` function has been renamed to `getAttributeValuesByName` to better differentiate between the two lookup methods.

  ### Usage Examples

  Both functions return an array of values for consistency, making them safe to use in iterations. For single-select attributes, the value is wrapped in an array. For multi-select attributes, the array is returned directly.

  #### Looking up by name (existing, now renamed):

  ```typescript
  import { getAttributeValuesByName } from '@scayle/storefront-core'

  // Single-select attribute
  const sizes = getAttributeValuesByName(product.attributes, 'size')
  // Returns: [{ id: 1, label: 'M', value: 'medium' }]

  // Multi-select attribute
  const colors = getAttributeValuesByName(product.attributes, 'color')
  // Returns: [{ id: 1, label: 'Red' }, { id: 2, label: 'Blue' }]

  // Non-existent attribute
  const missing = getAttributeValuesByName(product.attributes, 'doesNotExist')
  // Returns: []
  ```

  #### Looking up by group ID (new):

  ```typescript
  import { getAttributeValuesByGroupId } from '@scayle/storefront-core'

  // Look up attribute by its numeric ID from the SCAYLE API
  const promotionValues = getAttributeValuesByGroupId(product.attributes, 42)
  // Returns: [{ id: 123, label: 'Summer Sale', value: 'summer-2024' }]

  // Non-existent attribute group
  const missing = getAttributeValuesByGroupId(product.attributes, 9999)
  // Returns: []
  ```

  ### When to Use Each Function
  - **`getAttributeValuesByName`**: Use when you know the attribute name key (e.g., 'color', 'size'). This is the most common use case in application code.
  - **`getAttributeValuesByGroupId`**: Use when you have the numeric attribute group ID from the SCAYLE API, such as when processing API configurations, handling dynamic attribute mappings, or working with attribute group references.

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.17.0

## 8.45.1

### Patch Changes

- Updated SCAYLE Resource Center references

**Dependencies**

- Updated dependency to @scayle/unstorage-scayle-kv-driver@2.0.6
- Updated dependency to @scayle/storefront-api@18.16.1

## 8.45.0

## 8.44.2

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/unstorage-scayle-kv-driver@2.0.5
- Updated dependency to @scayle/storefront-api@18.16.0

## 8.44.1

## 8.44.0

### Minor Changes

- Export `unwrap`, `generateBasketKey`, `generateWishlistKey` and `UnstorageCache`.

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/unstorage-scayle-kv-driver@2.0.4

## 8.43.4

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.16.0

## 8.43.3

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/unstorage-scayle-kv-driver@2.0.3
- Updated dependency to @scayle/storefront-api@18.15.0

## 8.43.2

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/unstorage-scayle-kv-driver@2.0.2

## 8.43.1

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/unstorage-scayle-kv-driver@2.0.1

## 8.43.0

### Minor Changes

- Added an export of the new promotion type `ComboDealEffect`

  This type is also included in the `PromotionEffectType` type and can be used to check if the promotion is of type `ComboDealEffect`.

  Example:

  ```ts
  const isComboDealType = (
    promotion?: Promotion | null,
  ): promotion is Promotion<ComboDealEffect> => {
    return promotion?.effect?.type === PromotionEffectType.COMBO_DEAL
  }
  ```

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.15.0

## 8.42.2

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/unstorage-scayle-kv-driver@2.0.0

## 8.42.1

### Patch Changes

- Increased the default cache timeout to 1000ms to reduce cases of prematurely skipping the cache.

## 8.42.0

### Minor Changes

- Added `promotions` field to `BasketItem` type to support multiple promotions per basket item.

  The `promotions` field is an array of `BasketItemPromotion` objects.
  With the introduction of the new `promotions` array field, the `promotion` field is now deprecated.

  Before:

  ```json
  "promotion": {
      "id": "123",
      "name": "Promotion 1",
      "isActive": true,
  }
  ```

  After:

  ```json
  "promotions": [{
      "id": "123",
      "name": "Promotion 1",
      "isActive": true,
  }]
  ```

  For more details, see the [Storefront API documentation](https://scayle.dev/en/api-guides/storefront-api/resources/baskets/get-a-basket).

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.14.0

## 8.41.4

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/unstorage-scayle-kv-driver@1.1.0
- Updated dependency to @scayle/storefront-api@18.13.1

## 8.41.3

### Patch Changes

- Fixed the case where a `postLogin` function was inadvertently registered as an RPC method.

**Dependencies**

- Updated dependency to @scayle/unstorage-scayle-kv-driver@1.0.4

## 8.41.2

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.13.1

## 8.41.1

### Patch Changes

- Improved logging around cache errors to provide more details.

## 8.41.0

### Minor Changes

- Introduce a new `updatePromotions` RPC method to wrap the Storefront API "Bulk update promotions" endpoint.
  This allows to update all promotions applied to basket's items in a single API call.
  For more details, see the [Storefront API documentation](https://scayle.dev/en/api-guides/storefront-api/resources/baskets/bulk-update-promotions).

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.13.0

## 8.40.0

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.12.0
- Updated dependency to @scayle/unstorage-scayle-kv-driver@1.0.3

## 8.39.1

### Patch Changes

- Added `'token'` and `'code'` to the list of default `blacklistedKeys`. This will more proactively redact server logs to prevent leaked data.

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.12.0
- Updated dependency to @scayle/unstorage-scayle-kv-driver@1.0.3

## 8.39.0

### Patch Changes

- Use a custom error type for OAuth API errors to improve troubleshooting OAuth errors.

## 8.38.4

## 8.38.3

### Patch Changes

- Refactored internals of `getOrderDataByCbd`. This change has no noticable impact.

## 8.38.2

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.12.0
- Updated dependency to @scayle/unstorage-scayle-kv-driver@1.0.3

## 8.38.1

### Patch Changes

- Resolved an issue where `Pagination` was not exported correctly as a `type`.

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.12.0
- Updated dependency to @scayle/unstorage-scayle-kv-driver@1.0.3

## 8.38.0

### Minor Changes

- Refined the `ContextWithoutSession` type to accurately represent actual data: `wishlistKey`, `basketKey`, and `sessionId` are now typed as `string` instead of `undefined`, since even logged-out users have these values set.
- Made `getCheckoutToken` callable by logged-in and not logged-in users. When called by a not logged-in user, the RPC returns only the `checkoutJWT`. For logged-in users, it continues to return both the `checkoutJWT` and a refreshed `accessToken` as before.

## 8.37.0

### Minor Changes

- The `where` parameter for the `getProductsByCategory` and `getProductsCount` RPCs was extended to include the previously missing options `sellableAt`, `hasCampaignReduction`, and `containsSearch`.

### Patch Changes

- Added missing export of the RPC `getCampaign`

## 8.36.0

### Minor Changes

- Created a new RPC method `getCampaign` to retrieve the first active campaign.

  More details can be found in the official SCAYLE Resource Center under [API Guides / Storefront API / Campaigns / List Campaigns](https://scayle.dev/en/api-guides/storefront-api/resources/campaigns/list-campaigns).

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.11.0

## 8.35.0

### Minor Changes

- Removed optional key `fbook` from `ShopUser` interface
- Renamed incorrectly formatted function `getBackurlFromBreadcrumbs` to `getBackURLFromBreadcrumbs`

### Patch Changes

- Renamed interface incorrectly named `IdenfitierFilterItemWithValues` to `IdentifierFilterItemWithValues`

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.10.0

## 8.34.1

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.9.0
- Updated dependency to @scayle/unstorage-scayle-kv-driver@1.0.2

## 8.34.0

### Minor Changes

- Added export of `Pagination` type.
- **Breaking:** Improved type safety of the `mergeBaskets` RPC method. The method now returns the correct type `Promise<BasketResponse<Product, Variant> | AddManyItemsBasketResponse<Product, Variant> | undefined>` instead of `any`.

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.9.0
- Updated dependency to @scayle/unstorage-scayle-kv-driver@1.0.2

## 8.33.2

### Patch Changes

- Updated dependency `@scayle/storefront-api@18.9.0` to `@scayle/storefront-api@workspace:*`
- Updated dependency `@scayle/unstorage-scayle-kv-driver@1.0.2` to `@scayle/unstorage-scayle-kv-driver@workspace:*`

## 8.33.1

### Patch Changes

- Updated dependency `@scayle/storefront-api@18.9.0` to `@scayle/storefront-api@workspace:*`
- Updated dependency `@scayle/unstorage-scayle-kv-driver@1.0.2` to `@scayle/unstorage-scayle-kv-driver@workspace:*`

## 8.33.0

### Minor Changes

- Added test factories for order and all related types.

  It is now possible to build orders with factory functions for testing purposes.
  This will reduce the amount of boilerplate code needed to create test data.

## 8.32.1

## 8.32.0

### Minor Changes

- Added `minReduction` and `maxReduction` filter parameters to the `FetchProductsCountParams.where` type and updated the `getProductsCount` RPC method to accept and handle these new reduction-based filtering conditions.

### Patch Changes

- Fixed the `getFilters` RPC method to properly apply `minReduction` and `maxReduction` filter parameters when fetching product counts.

## 8.31.0

### Minor Changes

- Added `minReduction` and `maxReduction` filter parameters to `FetchProductsByCategoryParams.where` and `FetchFiltersParams.where` types, and updated the `getProductsByCategory` and `getFilters` RPC methods to accept and handle these new reduction-based filtering conditions.

  ```ts
  const { data } = useRpc('getFilters', 'getFiltersKey', () => ({
    where: {
      minReduction: 10,
      maxReduction: 20,
    },
  }))

  const { data } = useRpc(
    'getProductsByCategory',
    'getProductsByCategoryKey',
    () => ({
      where: {
        minReduction: 10,
        maxReduction: 20,
      },
    }),
  )
  ```

## 8.30.3

No changes in this release.

## 8.30.2

### Patch Changes

- Fixed an incorrect internal import for category related RPC methods. This should resolve potential type issues.

## 8.30.1

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/unstorage-scayle-kv-driver@1.0.2

## 8.30.0

### Minor Changes

- Added `defineRpcHandler` utility function that enhances RPC handlers with type-safe metadata for improved registration and invocation of RPC handlers. While defining RPC handlers without this utility remains supported, its usage is recommended and may become mandatory in a future major release.

  Existing RPC handlers can be easily migrated to use `defineRpcHandler` by passing the existing handler to `defineRpcHandler`.

  ```ts
  export const existingHandlerWithoutParams = async (_context: RpcContext) => {
    return 'existing handler'
  }

  export const existingHandlerWithParams = async (
    { name }: { name: string },
    _context: RpcContext,
  ) => {
    return name
  }

  // will become

  export const existingHandlerWithoutParams = defineRpcHandler(
    async (_context: RpcContext) => {
      return 'existing handler'
    },
  )
  export const existingHandlerWithParams = defineRpcHandler(
    async ({ name }: { name: string }, _context: RpcContext) => {
      return name
    },
  )
  ```

### Patch Changes

- Removed unused `Awaited` and `PromiseReturnType` types.

## 8.29.0

### Minor Changes

- Added an `includeProductSorting` boolean parameter to all category RPC method endpoints (`getRootCategories`, `getCategoryByPath`, `getCategoriesByPath`, `getCategoryById`, `getCategoryTree`).
  This flag allows consumers to retrieve product sorting data, including the `smartSortingKey` and `customSortingKey` properties.
  Developers can leverage this data to seamlessly apply smart sorting keys on the product listing page by passing those parameters when fetching products.
- Added an optional `hideEmptyCategories` parameter to `getCategoryTree`. When enabled, the product count for each category is retrieved, and categories (including their children) without any products are removed. Enabling this option may increase response times, especially for large category trees.

  ```ts
  import { rpcMethods } from '@scayle/storefront-core'

  rpcMethods.getCategoryTree({ hideEmptyCategories: true }, rpcContext)
  ```

  or

  ```ts
  import { useCategoryTree } from '#storefront/composables'

  const { data: rootCategories, status } = useCategoryTree(
    {
      params: {
        hideEmptyCategories: true,
      },
    },
    'category-navigation-tree',
  )
  ```

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.9.0

## 8.28.7

### Patch Changes

- Fixed the return type of `flattenFieldSet` to reflect the flattened field set.

## 8.28.6

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/unstorage-scayle-kv-driver@1.0.1

## 8.28.5

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/unstorage-scayle-kv-driver@1.0.0

## 8.28.4

No changes in this release.

## 8.28.3

No changes in this release.

## 8.28.2

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.8.0

## 8.28.1

No changes in this release.

## 8.28.0

### Minor Changes

- Introduced the `getCategoryTree` RPC for retrieving the complete category tree.

## 8.27.0

### Minor Changes

- Added a new `getApplicablePromotionsByCode` RPC method which can be used to fetch applicable promotions for a basket.

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.7.0

## 8.26.2

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.6.1

## 8.26.1

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.6.0

## 8.26.0

No changes in this release.

## 8.25.6

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.5.0

## 8.25.5

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.4.0

## 8.25.4

No changes in this release.

## 8.25.3

### Patch Changes

- Expose `MemberRole`, `FilterValuesEndpointParameters` and `GetRedirectsEndpointParameters` type

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.3.1

## 8.25.2

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/unstorage-scayle-kv-driver@0.1.2

## 8.25.1

No changes in this release.

## 8.25.0

### Patch Changes

- **\[Code Style\]** Refactored brands and navigation tree RPCs to avoid destructuring the RPC context within function signatures

## 8.24.1

No changes in this release.

## 8.24.0

No changes in this release.

## 8.23.0

### Minor Changes

- Deprecated attribute group specific utilities `getFlattenedVariantCrosssellings` and
  `getFlattenedMaterialComposition`.

  These functions should be a part of the Storefront Application.

## 8.22.0

### Minor Changes

- Allow passing `authUrlParameters` to the `getExternalIdpRedirect` RPC method. This parameter is an optional `Record<string, string>`. Values provided here will be processed by the Auth service and appended to the final redirect URL.
- Exported the `ShopCountryCustomData` interface.

## 8.21.0

### Minor Changes

- Expose the following filter types from `storefront-api`:
  - `FilterItemWithValues`
  - `BooleanFilterItemWithValues`
  - `RangeFilterItemWithValues`
  - `IdentifierFilterItemWithValues`
  - `AttributesFilterValue`

## 8.20.1

### Patch Changes

- Re-exported `BasketKey` and `ApplicablePromotion` from `@scayle/storefront-api`

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.3.0

## 8.20.0

### Minor Changes

- Include additional client information to Auth API requests to improve security.
- Add `originalIp` to the RPCContext which represents the IP address of the request without considering the `x-forwarded-for` header.

### Patch Changes

- **\[Basket\]** Pass `campaignKey` to SAPI when updating an basket item using the `updateBasketItem` RPC.

## 8.19.1

### Patch Changes

- Fix `getCategoriesByPath` RPC to return 404 for non-existing categories.

## 8.19.0

## 8.18.0

### Minor Changes

- Update RPC methods to use explicit typing. This is an internal change to enable Typescript's `isolatedDeclarations` option. It will not impact regular usage of RPC methods, however if you are importing one of the functions directly, the explicit rather than inferred type will be used.

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.2.2

## 8.17.1

### Patch Changes

- Ensure that the `getAttribute` helper function can handle multi-value attributes.

## 8.17.0

### Minor Changes

- Fix return type of `RpcMethodCall` to reflect that it returns a `Promise<TResult>` instead of `TResult`. This change emphasizes that `callRpc` in `RpcContext` is indeed an asynchronous operation.

### Patch Changes

- Ensure that `pricePromotionKey` set in the right place when calling the deletion wishlist item operation of SAPI.

## 8.16.0

## 8.15.1

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.2.1

## 8.15.0

### Minor Changes

- Filter out orders from `user.orderSummary` that are not associated with the current shop ID.

## 8.14.4

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.2.0

## 8.14.3

### Patch Changes

- Export the `BasketItemUpdateData` type.

## 8.14.2

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.1.1

## 8.14.1

### Patch Changes

- Update `getUniqueItemsFromOrder` and `getItemQuantityFromOrder` to accept order
  `Product` and `Variant` generics to ensure correct types. Moreover, both methods
  are deprecated as they should be handled within Storefront project itself.

## 8.14.0

### Minor Changes

- Expose `PackageDeliveryStatus` type. This new type clearly defines the allowed values for a package's delivery status. This improves code clarity and helps prevent typos. It's used to replace the inline string literal types in the `ListOfPackages` type.
- Refactor the `Order` and `OrderItem` interfaces to be generic, allowing them to accept custom `Product` and `Variant` types. This allows to strongly type the `product` and `variant` data within orders and order items, leading to better type checking and potentially fewer runtime errors. This allows for compile-time checks and autocompletion when working with product and variant properties of `OrderItem` and items property of `Order`.

## 8.13.0

### Minor Changes

- Expose `OrderStatus` and `OrderItem` interfaces from `order` types.
- Enhance the `OrderSummary` component by integrating the `OrderStatus` type
  from the order `Order` interface. This update provides a more accurate and
  detailed representation of the order status for users.
- Enhance order `detailedStatus` code type for `billing`, `order` and `shipping` properties and
  expose `OrderStatusCode`, `BillingStatusCode` and `ShippingStatusCode`.

### Patch Changes

- Added `fishery@>=2.2.3` as `peerDependencies`.

## 8.12.3

### Patch Changes

- Fix typo introduced in 8.12.2.

## 8.12.2

### Patch Changes

- Use `CentAmount` in the Order type to avoid nominal type errors.

## 8.12.1

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/unstorage-scayle-kv-driver@0.1.1

## 8.12.0

### Minor Changes

- Expose `CategoryFilter` from `storefront-core`.

## 8.11.3

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.1.0

## 8.11.2

### Patch Changes

- Updated dependency `jose@^5.6.3` to `jose@^6.0.8`

## 8.11.1

### Patch Changes

- Added dependency `@scayle/unstorage-scayle-kv-driver@0.0.1`

**Dependencies**

- Updated dependency to @scayle/unstorage-scayle-kv-driver@0.1.0

## 8.11.0

### Minor Changes

- Remove check in `getOrderById` RPC whether an order exists in `context.user.orderSummary`. The order summary defaults to including only the 50 most recent entries. This fix ensures orders beyond this limit can be accessed.

## 8.10.0

### Minor Changes

- Simplified exported `Order` interface by relying directly on primitive types instead of having multiple intermediate types that resolve to primitives.

  The following formerly exported intermediate types have been replaces by primitive types:
  - resolving to `string` now
    - `TimestampOfOrderConfirmation`
    - `CharacterCurrencyCode`
    - `UniqueIdentifierOfTheState`
    - `NameOfTheState`
    - `UniqueIdentifierOfTheState1`
    - `NameOfTheState1`
    - `UniqueIdentifierOfTheState2`
    - `NameOfTheState2`
    - `TimestampOfOrderInvoice`
    - `CharacterCurrencyCode1`
    - `UniqueIdentifierOfTheItem`
    - `TimestampOfItemCreation`
    - `TimestampOfLastItemUpdate`
    - `CarrierShippingTheItem`
    - `LatestExpectedDeliveryDate`
    - `EarliestExpectedDeliveryDate`
    - `ShipmentKeyOfTheItem`
    - `TimestampOfOrderCreation`
    - `TimestampOfLastOrderUpdate`
  - resolving to `number` now
    - `ThisFieldRepresentsTheAdditionalFeesExcludingTheTaxes`
    - `ThisFieldRepresentsTheAdditionalFeesIncludingTheTaxes`
    - `TheIncludedVATAmount`
    - `TheIncludedVATRateInPercentAsIntegerRepresentation`
    - `ThisFieldRepresentsTheDiscountAmountIncludingTheTaxes`
    - `AbsoluteValueOfTheAppliedTax`
    - `UniqueNumericIdentifierOfTheItem`
    - `AvailableQuantityInTheWarehouse`
    - `ThisFieldRepresentsTheDiscountAmountIncludingTheTaxes1`
    - `AbsoluteValueOfTheAppliedTax1`
    - `RelativeValueOfTheAppliedTax`
    - `UndiscountedItemPriceExcludingTaxes`
    - `UndiscountedItemPriceIncludingTaxes`
    - `ItemPriceExcludingTaxes1`
    - `ItemPriceIncludingTaxes1`
    - `ReferenceByWhichThePackageIsIdentified`
    - `ItemPriceExcludingTaxes`
    - `ItemPriceIncludingTaxes`
    - `NumberOfInstallmentsChosenByTheCustomerForTheOrder`
  - resolving to `boolean` now
    - `TheReturnShipmentHasBeenTriggeredByCCI`
    - `WhetherThePaymentMethodIsAGiftCard`
    - `IfTrueTheCustomerElectedToHaveADelayInPaymentCapture`
  - resolving to `null | number` now
    - `PickingWarehouseId`
    - `WarehousePackageReference`
  - resolving to `null | string` now
    - `ReturnIdentCodeOfTheItem`

  The interface `ThisFieldHoldsDetailsAboutTheIncludedVATTax` has been removed and `amount: number` and `rate: number` have been directly specified under `Order.cost.appliedFees.tax.vat: {amount: number, rate: number}`.
  Additionally we have introduce the types `OrderAddressRecipientGender` and `OrderAddressRecipientType`, as well as the interfaces `OrderAddress` and `OrderForwardingAddress`.

## 8.9.0

### Minor Changes

- Extend `RpcContext` with an `rpcCall` property. This is a utility function that can be used within RPC methods to invoke another RPC method.

## 8.8.0

### Minor Changes

- Deprecate `RpcContext.campaignKey`. The `getCampaignKey` RPC should be used instead.

To get the default campaign key, you can call the RPC method:

```typescript
// Before
async function rpcMethod(context) {
  const campaignKey = { context }
  // ...
}
// After
async function rpcMethod(context) {
  const campaignKey = await context.callRpc?.('getCampaignKey')
  // ...
}
```

To override the default campaign key, override the getCampaignKey RPC with your own implementation.
See [Overriding core RPC Methods](https://scayle.dev/en/core-documentation/storefront-guide/storefront-application/technical-foundation/rpc-methods#overriding-core-rpc-methods) for more.

## 8.7.1

### Patch Changes

- Introduced JSDoc comments to provide additional contextual descriptions and hints.

## 8.7.0

### Minor Changes

- **\[Testing\]** Create and expose externally `userFactory`

### Patch Changes

- The `domain` property on `RpcContext` is optional

## 8.6.1

### Patch Changes

- Remove duplicated export of `PromotionEffectType`. It was previously defined within `@scayle/storefront-core` and reexported from `@scayle/storefront-api`. Now only the the object literal and type from `@scayle/storefront-api` are exported.

## 8.6.0

### Minor Changes

- Reexport `ExistingItemHandling`,`AddToBasketFailureKind`,`UpdateBasketItemFailureKind`,`AddToWishlistFailureKind`,`PromotionEffectType` and `FilterTypes` from `@scayle/storefront-api`, instead of redefining them in `@scayle/storefront-core`
- Remove `package.json` and `server` exports.
- The CommonJS export format will be removed in this version. All exports are provided through ES Modules (`import`/`export`) exclusively

  This change will primarily affect users who are currently using the CommonJS format of this package. To update your code, you should replace `require` statements with `import` statements and update your build tooling if necessary.

  ```TypeScript
  const { ... } = require('@scayle/storefront-core')

  // will become

  import { ... } from '@scayle/storefront-core'
  ```

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@18.0.0

## 8.5.0

### Minor Changes

- The CommonJS export format will be removed in this version. All exports are provided through ES Modules (`import`/`export`) exclusively

  This change will primarily affect users who are currently using the CommonJS format of this package. To update your code, you should replace `require` statements with `import` statements and update your build tooling if necessary.

  ```TypeScript
  const { ... } = require('@scayle/storefront-core')

  // will become

  import { ... } from '@scayle/storefront-core'
  ```

## 8.4.0

### Minor Changes

- [Types] - Extend `Gender` type with `n` option

## 8.3.2

### Patch Changes

- Types: Explicitly type the return of `resolveSearch`

## 8.3.1

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@17.18.0

## 8.3.0

### Minor Changes

- [Basket] Add support to update existing basket items using the `updateBasketItem` RPC.

## 8.2.2

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@17.17.0

## 8.2.1

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@17.16.0

## 8.2.0

### Minor Changes

- [Performance] Remove the 'autobinding' of the methods on the `Cached` instance. Instead the `execute` method only is bound when constructing the `RpcContext`. This simplifies the code and improves the performance of the `bootstrap` function. This change is internal to `storefront-core` and the API of `RpcContext` is unchanged.

## 8.1.5

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@17.15.0

## 8.1.4

### Patch Changes

- Fixed misspelling of interface `BasketItemDisplayDataItem` to `BasketItemDisplayDataItem`

**Dependencies**

- Updated dependency to @scayle/storefront-api@17.14.1

## 8.1.3

### Patch Changes

**Dependencies**

- Updated dependency to @scayle/storefront-api@17.14.0

## 8.1.2

### Patch Changes

- **RPC Methods:** When propagating the status code from a SAPI error, only include the statusCode and statusText. Previously the headers and body were included as well which could cause content decoding issues.

## 8.1.1

### Patch Changes

- Make the `sort` parameter optional for the `FetchProductsByCategoryParams`

## 8.1.0

### Minor Changes

- **RPC Methods:** Propagate SAPI response codes through RPC methods. This addresses an issue introduced in Storefront Core v8 where specific status codes were incorrectly reported as generic 500 errors. The following RPC methods are impacted:
  - `getBrands`
  - `getBrandById`
  - `getCategoryByPath`
  - `getCategoryById`
  - `getProductById`
  - `getProductsByIds`
  - `getProductsByReferenceKeys`
  - `getPromotions`
  - `getCurrentPromotions`
  - `getPromotionsByIds`
  - `getSearchSuggestions`
  - `getShopConfiguration`
  - `getVariantById`
  - `getWishlist`
  - `removeItemFromWishlist`

## 8.0.0

### Major Changes

- **\[💥 BREAKING\]** The `getBadgeLabel` helper function has been removed, giving you more control over badge label display.
  - **Note:** This change doesn't affect projects using SCAYLE Storefront Boilerplate v1.0 or later.
  - For applications based on older versions or using `getBadgeLabel`, you can refer to the previous implementation below:

    ```ts
    const BadgeLabel = {
      NEW: 'new',
      SOLD_OUT: 'sold_out',
      ONLINE_EXCLUSIVE: 'online_exclusive',
      SUSTAINABLE: 'sustainable',
      PREMIUM: 'premium',
      DEFAULT: '',
    } as const

    type BadgeLabelParamsKeys =
      | 'isNew'
      | 'isSoldOut'
      | 'isOnlineOnly'
      | 'isSustainable'
      | 'isPremium'
    type BadgeLabelParams = Partial<Record<BadgeLabelParamsKeys, boolean>>

    const getBadgeLabel = (params: BadgeLabelParams = {}): string => {
      if (!params) {
        return BadgeLabel.DEFAULT
      }
      const { isNew, isSoldOut, isOnlineOnly, isSustainable, isPremium } =
        params

      if (isNew) {
        return BadgeLabel.NEW
      } else if (isSoldOut) {
        return BadgeLabel.SOLD_OUT
      } else if (isOnlineOnly) {
        return BadgeLabel.ONLINE_EXCLUSIVE
      } else if (isSustainable) {
        return BadgeLabel.SUSTAINABLE
      } else if (isPremium) {
        return BadgeLabel.PREMIUM
      } else {
        return BadgeLabel.DEFAULT
      }
    }
    ```

- **\[💥 BREAKING\]** We've standardized our configuration to use `sapi` (Storefront API) throughout the codebase, replacing the deprecated `bapi` keyword. This change improves clarity and consistency by removing the `initBapi` function, replacing the `bapiClient` property with `sapiClient` within the `RPCContext`, and updating all code references accordingly. `BapiConfig` is not exported anymore and has been superseded by `SapiConfig`.
  - **NOTE:** These changes impact your environment variables used for deployments. Please check your infrastructure and deployment setup and adapt accordingly!
  - _Previous `bapi` Configuration in `nuxt.config.ts`_

    ```ts
    export default {
      // ...
      runtimeConfig: {
        // ...
        storefront: {
          // ...
          bapi: {
            host: '...',
            token: '...',
          },
          // ...
        },
        // ...
      },
      // ...
    }
    ```

  - _Legacy Environment Variables:_

    ```env
    NUXT_STOREFRONT_BAPI_HOST='...'
    NUXT_STOREFRONT_BAPI_TOKEN='...'
    ```

  - _Current `sapi` Configuration in `nuxt.config.ts`_

    ```ts
    export default {
      // ...
      runtimeConfig: {
        // ...
        storefront: {
          // ...
          sapi: {
            host: '...',
            token: '...',
          },
          // ...
        },
        // ...
      },
      // ...
    }
    ```

  - _New Environment Variables:_

    ```env
    NUXT_STOREFRONT_SAPI_HOST='...'
    NUXT_STOREFRONT_SAPI_TOKEN='...'
    ```

- **\[💥 BREAKING\]** We've streamlined cache management by replacing the outdated `AY_CACHE_DISABLED` environment variable. Now, you can effortlessly control caching using either the `NUXT_STOREFRONT_CACHE_ENABLED` environment variable or the `storefront.cache.enabled` option within your `nuxt.config.ts` file, providing a more user-friendly experience.
- **\[💥 BREAKING\]** This release removes the `RedisCache` provider. We now use `UnstorageCache` which also supports Redis as a backing store.
- **\[💥 BREAKING\]** To improve security and streamline token management, we've updated how you access user `accessToken`. Instead of directly accessing the `storefrontAccessToken` field on the `UserAuthentication` interface, you'll now use the dedicated `getAccessToken` RPC. This change ensures a more secure and controlled method for handling sensitive user data within your application.
  - _Previous Usage of `user.authentication.storefrontAccessToken`:_

    ```ts
    const { data, fetching, fetch, error, status } = useUser(
      'getUser',
      // ...
    )
    data.value.user.authentication.storefrontAccessToken
    ```

  - _Current Usage of dedicated `getAccessToken` RPC method:_

    ```ts
    const { data: accessToken } = useRpc(
      'getAccessToken',
      // ...
    )
    ```

- **\[💥 BREAKING\]** We've enhanced security for basket and wishlist keys by switching the default hashing algorithm from MD5 to the more robust SHA256.
  - _Overriding default `hashAlgorithm` in `nuxt.config.ts`:_

    ```ts
    export default defineNuxtConfig({
      // ...
      runtimeConfig: {
        // ...
        storefront: {
          // ...
          appKeys: {
            // ...
            hashAlgorithm: HashAlgorithm.MD5, // HashAlgorithm.SHA256
          },
          // ...
        },
        // ...
      },
      // ...
    })
    ```

- **\[💥 BREAKING\]** The attribute `loginShopId` is removed from the `ShopUser` interface as the shop now uses session cookies.
- **\[💥 BREAKING\]** We're streamlining the search experience as we transition to SCAYLE Search v2, focusing on a category-centric approach. To achieve this, we're consolidating search functionality. This means we're replacing the `searchProducts` RPC method with `getSearchSuggestions`, which provides both product suggestions (triggered by product IDs) and category suggestions (triggered by category-like terms, leading to filtered category pages).
  - _Previous Usage of `searchProducts` RPC method:_

    ```ts
    const getSearchSuggestionsRpc = useRpcCall('searchProducts')

    data.value = await searchProducts({
      term: String(searchQuery.value),
      ...params,
    })
    ```

  - _Current Usage of `getSearchSuggestions` RPC method:_

    ```ts
    const getSearchSuggestionsRpc = useRpcCall('getSearchSuggestions')

    data.value = await getSearchSuggestionsRpc({
      term: String(searchQuery.value),
      ...params,
    })
    ```

- **\[💥 BREAKING\]** Improved basket updating: Adding an item to your basket with a reduced quantity will now correctly update the basket contents.
- **\[💥 BREAKING\]** The methods `getBasket`, `removeItemFromBasket`, `addItemsToBasket`, and `addItemToBasket` have been updated. Instead of returning the basket object directly, the basket will now be accessible as a property within the response body. Furthermore, errors oc