Merge branch 'main' of https://github.com/vuestorefront/vue-storefront into docs/multibrand2

Author: jagoral

.node-version

@@ -1 +1 @@
-18
+22.14.0

docs/content/cookbook/handling-custom-occ-endpoint.md

@@ -1,15 +1,36 @@
 # Handling custom OCC endpoints
 
 It is a common task to add support for a custom (non-standard) SAP OCC API endpoint not covered by the Alokai intergration.
-This guide will show you how can do it using Alokai.
+There are two ways how you can do it:
 
-## Prerequisites
+1. Generate new API client based on OpenAPI (swagger) specification.
+2. Add support for a custom endpoint manually.
 
-Before we start make sure that you are familiar with [Adding New API Methods](https://docs.alokai.com/storefront/integration-and-setup/storefront-extension#adding-new-api-methods) guide. With that guide, you would be able to
+## Generating new API client
+
+Generation of new API client allows you to add support for all custom endpoints at once. You just run a script and all the endpoints will be added to the integration.
+
+How to do this is described in the [Generated API guide](/integrations/sapcc/features/generated-api).
+
+This should be your default approach, because it is the most scalable and maintainable way.
+
+## Adding support for a custom endpoint manually
+
+If you don't want or cannot generate a new API client, you can add support for a custom endpoint manually. 
+It boils down to adding a new API method to the middleware that calls the custom endpoint. This guide shows how to do it efficiently.
+
+When to use this approach?
+
+- When for some reason you cannot generate a new API client, e.g. OpenAPI specification is not available.
+- When you are iterating fast both on the API and the front-end and you don't want to regenerate the API client for each change.
+
+### Prerequisites
+
+Before we start make sure that you are familiar with [Adding New API Methods](/unified-data-layer/integration-and-setup/creating-new-api-methods) guide. With that guide, you would be able to
 communicate with OCC API but it would require manual retrieval of context parameters (baseSiteId, userId, language,
 and currency) and preparation of authorization headers. Read on to see how to streamline that process.
 
-## Communicating with OCC API effectively
+### Communicating with OCC API effectively
 
 OCC endpoints have a given structure
 
@@ -35,74 +56,69 @@ Here's where to find the parameters:
 
 - `baseUrl` - is configured in .env file as `SAPCC_API_URI`. The api client already knows it and prepends each URL with it.
 - `baseSiteId` - is defined in the middleware configuration. That configuration is exposed to api method via context.
-- `userId` - can be found in the request cookies under [`AUTH_USER_COOKIE_NAME`](https://docs.alokai.com/integrations/sapcc/api/sapcc-api/AUTH_USER_COOKIE_NAME).
-- `language` - can be found in the request cookies under [`VSF_LOCALE_COOKIE`](https://docs.alokai.com/storefront/features/internationalization/internatialization-support).
-- `currency` - can be found in the request cookies under [`VSF_CURRENCY_COOKIE`](https://docs.alokai.com/storefront/features/internationalization/currency-switching).
-- authorization token - can be found in the request cookies under [`AUTH_USER_TOKEN_COOKIE_NAME`](https://docs.alokai.com/integrations/sapcc/api/sapcc-api/AUTH_USER_TOKEN_COOKIE_NAME)
+- `userId` - can be found in the request cookies under [`AUTH_USER_COOKIE_NAME`](/integrations/sapcc/api/sapcc-api/AUTH_USER_COOKIE_NAME).
+- `language` - can be found in the request cookies under [`VSF_LOCALE_COOKIE`](/storefront/features/internationalization/internatialization-support).
+- `currency` - can be found in the request cookies under [`VSF_CURRENCY_COOKIE`](/storefront/features/internationalization/currency-switching).
+- authorization token - can be found in the request cookies under [`AUTH_USER_TOKEN_COOKIE_NAME`](/integrations/sapcc/api/sapcc-api/AUTH_USER_TOKEN_COOKIE_NAME)
 
 You don't have to parse the cookies yourself. Alokai provides helper methods for that. Here’s a code example of how to do it:
 
-```typescript
-import {
-  SapccIntegrationContext,
-  TokenModes,
-  createRequestOptions,
-  getUserIdFromRequest,
-} from "@vsf-enterprise/sapcc-api";
-import { BaseProps, BaseUserId } from "@vsf-enterprise/sapcc-types";
+```typescript [apps/storefront-middleware/api/custom-methods/types.ts]
+import { BaseProps, BaseUserId } from '@vsf-enterprise/sapcc-types';
 
-export interface CustomEndpointProps extends BaseProps, BaseUserId {
+export interface CustomMethodArgs extends BaseProps, BaseUserId {
   customField: any;
 }
 
-export interface CustomResponse {
+export interface CustomMethodResponse {
   whatever: any;
 }
+```
+
+```typescript [apps/storefront-middleware/api/custom-methods/custom.ts]
+import { createRequestOptions, getUserIdFromRequest, TokenModes } from '@vsf-enterprise/sapcc-api';
+import { type IntegrationContext } from '../../types';
+import type { CustomMethodArgs, CustomMethodResponse } from './types';
 
-const callCustomEndpoint = async (
-  context: SapccIntegrationContext,
-  props: CustomEndpointProps
-): Promise<CustomResponse> => {
+export async function exampleCustomMethod(
+  context: IntegrationContext,
+  args: CustomMethodArgs,
+): Promise<CustomMethodResponse> {
   const { config, req, client } = context;
 
-  const userId = getUserIdFromRequest({ req, props } as any); // retrieves userID from props or cookies
+  const userId = getUserIdFromRequest({ context, props: args }); // retrieves userID from props or cookies
 
   const res = await client.get(
-    `/${config.api.baseSiteId}/users/${userId}/customEndpoint/${props.customField}`,
+    `/${config.api.baseSiteId}/users/${userId}/customEndpoint/${args.customField}`,
     createRequestOptions({
       // adds authorization headers and language & currency parameters
       context,
-      props,
+      props: args,
       tokenMode: TokenModes.CUSTOMERORAPPLICATION,
-    })
+    }),
   );
 
   return res.data;
-};
+}
+
 ```
 
 Read more about the helper methods:
 
-- [getUserIdFromRequest](https://docs.alokai.com/integrations/sapcc/api/sapcc-api/getUserIdFromRequest)
-- [createRequestOptions](https://docs.alokai.com/integrations/sapcc/api/sapcc-api/createRequestOptions)
+- [getUserIdFromRequest](/integrations/sapcc/api/sapcc-api/getUserIdFromRequest)
+- [createRequestOptions](/integrations/sapcc/api/sapcc-api/createRequestOptions)
 
-## Real life example
+### Real life example
 
-Here's an example implementation of the product interest feature. This feature is available in OCC API, but not in the middleware and SDK integration.
+Here's an example implementation of the product interest feature.
 Let's add support for it.
 
-First, you need to add a new API method in the middleware. (For simplicity, this guide shows how to do it in one file, but we recommend splitting it into multiple files to maintain cleaner code.)
+First, you need to add a new API method in the middleware.
 
-```typescript [storefront-middleware/middleware.config.ts]
-import {
-  SapccIntegrationContext,
-  TokenModes,
-  createRequestOptions,
-  getUserIdFromRequest,
-} from "@vsf-enterprise/sapcc-api";
-import { BaseProps, BaseUserId, Product } from "@vsf-enterprise/sapcc-types";
+```typescript [apps/storefront-middleware/api/custom-methods/types.ts]
+import { BaseProps, BaseUserId, Product } from '@vsf-enterprise/sapcc-types';
 
-export interface GetProductInterestsProps extends BaseProps, BaseUserId {
+export interface GetProductInterestsArgs extends BaseProps, BaseUserId {
   productCode?: string;
 }
 export interface ProductInterestEntry {
@@ -118,66 +134,61 @@ export interface UserInterestsResponse {
   results: Array<ProductInterestRelation>;
 }
 
-const getProductInterests = async (
-  context: SapccIntegrationContext,
-  props: GetProductInterestsProps
-): Promise<UserInterestsResponse> => {
-  const { config, req, client } = context;
+```
 
-  const userId = getUserIdFromRequest({ req, props } as any);
+```typescript [apps/storefront-middleware/api/custom-methods/custom.ts]
+import { createRequestOptions, getUserIdFromRequest, TokenModes } from '@vsf-enterprise/sapcc-api';
+import { type IntegrationContext } from '../../types';
+import type { GetProductInterestsArgs, UserInterestsResponse } from './types';
+
+export async function getProductInterests(
+  context: IntegrationContext,
+  args: GetProductInterestsArgs,
+): Promise<UserInterestsResponse> {
+  const { config, client } = context;
+
+  const userId = getUserIdFromRequest({ context, props: args });
 
   const requestOptions = createRequestOptions({
     context,
-    props,
+    props: args,
     tokenMode: TokenModes.CUSTOMERORAPPLICATION,
   });
 
-  const res = await client.get(
-    `/${config.api.baseSiteId}/users/${userId}/productinterests`,
-    {
-      ...requestOptions,
-      params: {
-        ...requestOptions.params,
-        productCode: props.productCode,
-      },
-    }
-  );
+  const res = await client.get(`/${config.api.baseSiteId}/users/${userId}/productinterests`, {
+    ...requestOptions,
+    params: {
+      ...requestOptions.params,
+      productCode: args.productCode,
+    },
+  });
 
   return res.data;
-};
-
-const apiMethods = methods<typeof normalizers>();
-const unifiedApiExtension = createUnifiedExtension<Context, Config>()({
-  normalizers,
-  apiMethods: {
-    ...apiMethods,
-    getProductInterests,
-  },
-  config: {
-    /* ... */
-  },
-});
+}
+```
+
+```typescript [apps/storefront-middleware/api/custom-methods/index.ts]
+export { getProductInterests } from './custom';
+export * from './types';
 ```
 
 Then, in your frontend application, you need to add a custom hook to retrieve the product interests on the front end.
 
 ```typescript [storefront-unified-nextjs/hooks/useProductInterests/useProductInterests.ts]
-import { useQuery } from "@tanstack/react-query";
-import { InferSdkArgs, useSdk } from "~/sdk";
+import { useQuery } from '@tanstack/react-query';
 
-export type GetProductInterestsArgs = InferSdkArgs<"getProductInterests">;
+import { useSdk } from '@/sdk/alokai-context';
 
-export function useProductInterests({ productCode }: GetProductInterestsArgs) {
+export function useProductInterests({ productCode }: { productCode: string }) {
   const sdk = useSdk();
 
   return useQuery({
-    queryKey: ["product interests", productCode],
     queryFn: () =>
-      sdk.unified.getProductInterests({
+      sdk.customExtension.getProductInterests({
         productCode,
       }),
-    refetchOnMount: false,
-    refetchOnWindowFocus: false,
+    queryKey: ['product interests', productCode],
   });
 }
+
 ```

docs/content/guides/1.index.md

@@ -34,15 +34,26 @@ Alokai is not a cookie-cutter solution, it is meant to be able to handle even th
 Learn how to create efficient and unified multigeo/multibrand/multivendor setups with Alokai.
 ::
 
-#section-4
-:card{to="/guides/kubernetes-probe" title="Kubernetes Probes" description="Alokai Cloud customers' middleware and frontend apps are deployed in Kubernetes. Check how Kubernetes mechanisms are used by Alokai Cloud" icon="tabler:heart-rate-monitor"}
+::
+
+## Advanced
 
-#section-5
-:card{to="/guides/best-practices" title="Best Practices" description="Check what to follow to keep your storefront in the best possible shape" icon="tabler:rosette-discount-check"}
+::card{title="Kubernetes Probes" to="/guides/kubernetes-probe" class="mb-5" icon="tabler:heart-rate-monitor"}
+#description
+Learn how to implement health check endpoints for your Alokai Cloud applications running on Kubernetes. This guide covers liveness and readiness probes implementation to ensure proper application monitoring and reliability.
+::
 
+## Best Practices
 
+::card{title="Performance" to="/guides/best-practices/performance" class="mb-5" icon="tabler:rosette-discount-check"}
+#description
+Every 100ms added to loading time costed Amazon 1% less sales. Don't let the poor performance to ruin your sales. Learn how to optimize your store for speed.
 ::
 
+::card{title="Data Fetching" icon="tabler:mobiledata" to="/guides/best-practices/data-fetching" }
+#description
+Learn how to optimize your data fetching strategy to improve performance and avoid caching errors.
+::
 
 ## Advanced
 
@@ -61,4 +72,3 @@ Every 100ms added to loading time costed Amazon 1% less sales. Don't let the poo
 ::info
 Can't find what you're looking for? Check out our [cookbook](/cookbook) for more guides and tutorials.
 ::
-

docs/content/guides/6.best-practices/1.index.md

@@ -1,5 +1,18 @@
+---
+title: Guides
+layout: default
+---
+
 # Best Practices
 
 In this guide, we have compiled a collection of best practices to help you optimize your development workflow, improve code quality, and ensure maintainability.
 
-::card{title="Data Fetching" icon="tabler:mobiledata" to="/guides/best-practices/data-fetching" }
+::card{title="Performance" to="/guides/best-practices/performance" class="mb-5" icon="tabler:rosette-discount-check"}
+#description
+Every 100ms added to loading time costed Amazon 1% less sales. Don't let the poor performance to ruin your sales. Learn how to optimize your store for speed.
+::
+
+::card{title="Data Fetching" icon="tabler:mobiledata" to="/guides/best-practices/data-fetching" }
+#description
+Learn how to optimize your data fetching strategy to improve performance and avoid caching errors.
+::

docs/content/guides/6.best-practices/2.data-fetching.md

@@ -42,7 +42,8 @@ The rule of thumb is: _always use server-side fetching except for_:
 
 Alokai architecture introduces the Middleware in between the front-end application and the APIs. This adds two additional possible routes to our diagram, but most of the traffic should go through the middleware, because:
 
-- it is cached on the CDN
+<!-- Uncomment below when CDN caching is availavble -->
+<!-- - it is cached on the CDN -->
 - it keeps your architecture simple
 - you can easily monitor middleware traffic in the console
 - enables [data federation](/middleware/guides/federation)
@@ -58,13 +59,17 @@ Fortunately, we can reject the route between the server and the API, because:
 The direct route between the browser and API should be avoided, because it:
 
 - tightly couples storefront with the API,
-- reduces performance by bypasses CDN cache.
+<!-- Uncomment below when CDN caching is availavble -->
+<!-- - reduces performance by bypassing CDN cache. -->
 
 Use direct direct browser to API calls only when communicating via middleware is not possible or requires unnecessary effort. Sample scenarios when it might be valid to communicate directly between client and API:
 
 - the communication requires extremely low latency - e.g. voice or video stream
 - communication with API is done via some SDK that requires direct client (browser) interaction - e.g. analytics or authentication services
 
+
+<!-- Uncomment below when CDN caching is availavble -->
+<!-- ## CDN Caching
 ## CDN Caching
 
 To further improve your application performance we encourage you to enable the CDN. The CDN is capable of caching responses from the server and the middleware to the browser.
@@ -73,7 +78,7 @@ To further improve your application performance we encourage you to enable the C
 
 ::info
 [Read more about caching here.](/storefront/features/cdn/making-ssr-cacheable)
-::
+:: -->
 
 ## Examples
 

docs/content/guides/3.performance/1.index.md renamed to docs/content/guides/6.best-practices/3.performance/1.index.md

@@ -0,0 +1,3 @@
+title: Performance
+sidebarRoot: true
+

docs/content/guides/3.performance/2.core-web-vitals.md renamed to docs/content/guides/6.best-practices/3.performance/2.core-web-vitals.md

@@ -0,0 +1,26 @@
+---
+title:
+layout: default
+---
+
+# Multistore
+
+On this page you'll find a set of guides that will help you to understand the fundamentals of Alokai and how different parts of our stack will help you to build your Alokai application.
+
+Below you will find a list of guides to help you get started with Alokai.
+
+::card{title="Introduction" icon="tabler:align-box-center-middle" to="/guides/multistore/introduction" }
+
+#description
+Learn what challenges the Alokai Multistore solution addresses and how it can help you solve them.
+::
+
+<br />
+
+::card{title="Tooling and concepts" icon="tabler:tools" to="/guides/multistore/tooling-and-concepts" }
+
+#description
+Learn the concepts and tools behind the Alokai Multistore solution.
+::
+
+<br />