From c73de3e246bbbc01be950b8a9ef82d47b096754d Mon Sep 17 00:00:00 2001
From: Wojciech Sikora <wsikora@vuestorefront.io>
Date: Fri, 15 Mar 2024 13:22:02 +0100
Subject: [PATCH 01/17] update getting started

---
 .../4.sdk/2.getting-started/1.index.md        | 193 ++++++++++--------
 .../4.sdk/3.advanced/1.middleware-module.md   |  25 +++
 ...ending-module.md => 2.extending-module.md} |   0
 .../4.sdk/3.advanced/3.custom-modules.md      |  14 ++
 4 files changed, 142 insertions(+), 90 deletions(-)
 create mode 100644 docs/content/4.sdk/3.advanced/1.middleware-module.md
 rename docs/content/4.sdk/3.advanced/{extending-module.md => 2.extending-module.md} (100%)
 create mode 100644 docs/content/4.sdk/3.advanced/3.custom-modules.md

diff --git a/docs/content/4.sdk/2.getting-started/1.index.md b/docs/content/4.sdk/2.getting-started/1.index.md
index 23d6a1fc3c..30dfb2c4c9 100644
--- a/docs/content/4.sdk/2.getting-started/1.index.md
+++ b/docs/content/4.sdk/2.getting-started/1.index.md
@@ -1,8 +1,8 @@
-# Getting Started 
+# Getting Started
 
-If you're setting your Vue Storefront application from scratch, you'll need to configure the SDK Core to create a type-safe SDK that communicates with your [Server Middleware](/middleware).
+If you're setting your Vue Storefront application from scratch, you'll need to configure a type-safe SDK that communicates with your [Server Middleware](/middleware).
 
-There are various ways to configure the SDK, depending on your chosen framework. For Next.js and Nuxt, you can use the `@vue-storefront/next` and `@vue-storefront/nuxt` modules respectively. If you're looking for framework agnostic experience, you can use the `@vue-storefront/core` module.
+There are various ways to configure the SDK, depending on your chosen framework. For Next.js and Nuxt, you can use the `@vue-storefront/next` and `@vue-storefront/nuxt` packages respectively. If you're looking for framework agnostic experience, you can use the `@vue-storefront/sdk` package.
 
 ::tabs{:titles='["Next.js", "Nuxt", "Other"]' class="mt-8"}
 
@@ -27,21 +27,20 @@ npm install --save-dev @vue-storefront/next
 
 To use SDK in our application, we need to initialize it first. To do so, follow these steps:
 
-1. Create SDK Config file - `sdk.config.ts` in root directory of your project. 
+1. Create an `sdk` directory in the root of your project.
+
+1. Create SDK Config file - `sdk.config.ts` in the `sdk` directory.
 
 ::info
-It is not necessary to name the file `sdk.config.ts` specifically or to keep it in the root of your project, but it is recommended to keep it consistent with the rest of the Vue Storefront project.
+It is not necessary to name the file `sdk.config.ts` specifically or to keep it in the `sdk` directory, but it is recommended to keep it consistent with the rest of the Vue Storefront project.
 ::
 
-2. Create the SDK configuration by importing the `createSdk` function from the Next.js SDK and the modules you want to use.
+2. Create the SDK configuration by importing the `createSdk` function from the Next.js SDK and using the `middlewareModule` it provides. You should also import other modules you want to use.
 
 ```ts[sdk.config.ts]
-import { sapccModule } from '@vsf-enterprise/sapcc-sdk';
-import {
-  contentfulModule,
-  ContentfulModuleType,
-} from "@vsf-enterprise/contentful-sdk";
+import { contentfulModule } from "@vsf-enterprise/contentful-sdk";
 import { CreateSdkOptions, createSdk } from "@vue-storefront/next";
+import { UnifiedEndpoints } from "storefront-middleware/types";
 
 const options: CreateSdkOptions = {
    middleware: {
@@ -49,13 +48,16 @@ const options: CreateSdkOptions = {
    }
 };
 
-export const { getSdk, createSdkContext } = createSdk(
+export const { getSdk } = createSdk(
   options,
-  ({ buildModule, middlewareUrl, getRequestHeaders }) => ({
-    commerce: buildModule(sapccModule, {
+  ({ buildModule, middlewareUrl, middlewareModule, getRequestHeaders }) => ({
+    commerce: buildModule(middlewareModule<UnifiedEndpoints>, {
       apiUrl: middlewareUrl + "/commerce",
+      defaultRequestConfig: {
+        headers: getRequestHeaders(),
+      },
     }),
-    cms: buildModule<ContentfulModuleType>(contentfulModule, {
+    cms: buildModule(contentfulModule, {
       apiUrl: middlewareUrl + "/cms",
     }),
   }),
@@ -65,6 +67,7 @@ export const { getSdk, createSdkContext } = createSdk(
 Let's break down the code above:
 
 - The `createSdk` function expects
+
   - base SDK options including the middleware and (optionally) the multistore configuration as a first argument,
   - and a factory function for the SDK configuration as a second argument. Those factory function receives a context, useful for creating the SDK configuration.
 
@@ -72,21 +75,21 @@ Let's break down the code above:
 
 - The `middlewareUrl` is the URL of the middleware instance.
 
-- The `getRequestHeaders` function is used to retrieve the Cookie header with cookie values.
+- The `middlewareModule` is an SDK module that ensures communication with the Server Middleware. It takes the `UnifiedEndpoints` type as a generic parameter. The `UnifiedEndpoints` type is a type that represents the endpoints of the Server Middleware.
 
-- The `createSdk` function returns
-  - the `getSdk` function, which is used to create the new SDK instance,
-  - and the `createSdkContext` function, which is used to create the SDK context, to share the same SDK instance on the Client side.
+- The `getRequestHeaders` function is used to retrieve the `Cookie` header with cookie values.
+
+- The `createSdk` function returns the `getSdk` function, which is used to retreive the new SDK instance.
 
 ## Registering the SDK
 
-Once you have initialized the SDK, you can register it in your application. 
+Once you have initialized the SDK, you can register it in your application.
 
 Vue Storefront SDK can be used in two ways:
 
-- **getSdk** - returns the SDK instance, which can be used to call the SDK methods directly. This is useful for server-side rendering, as it allows you to call the SDK methods directly in your application.
+- `getSdk` - returns the SDK instance, which can be used to call the SDK methods directly. This is useful for server-side rendering, as it allows you to call the SDK methods directly in your application.
 
-- **createSdkContext** - returns the SDK context, which can be used to share the same SDK instance on the Client side. This is useful for client-side rendering, as it allows you to share the same SDK instance across your application.
+- `createSdkContext` - returns the SDK context, which can be used to share the same SDK instance on the Client side. This is useful for client-side rendering, as it allows you to share the same SDK instance across your application.
 
 ### getSdk
 
@@ -95,27 +98,34 @@ Vue Storefront SDK can be used in two ways:
 Below is an example of how you can use `getSdk` in your application:
 
 ```ts
-import { getSdk } from "../sdk.config";
+import { getSdk } from "@/sdk/sdk.config";
 
 const sdk = getSdk();
 ```
 
 ### createSdkContext
 
-For client-side rendering, you can use `createSdkContext`. In order to use it, you'll need to create a new file in your application, for example `hooks/sdk.ts`:
+For client-side rendering, you can use `createSdkContext`. To use it, you'll need to create a new file in your application, for example `sdk/SdkProvider.tsx`:
 
 ```ts
 import { createSdkContext } from "@vue-storefront/next/client";
-import { getSdk } from "../sdk.config";
+import { getSdk } from "@/sdk/sdk.config";
 
 export const [SdkProvider, useSdk] = createSdkContext(getSdk());
 ```
 
+To achieve easier importing, you can also create an `index.ts` file in the `sdk` directory:
+
+```ts [sdk/index.tsx]
+export * from "./SdkProvider";
+export * from "./sdk.config";
+```
+
 Once you have created the SDK context, you can register it in your application. For example, if you're using the Pages Router, you can register it in `pages/_app.tsx`:
 
 ```tsx
 import type { AppProps } from "next/app";
-import { SdkProvider } from "../hooks";
+import { SdkProvider } from "@/sdk";
 
 export default function App({ Component, pageProps }: AppProps) {
   return (
@@ -128,7 +138,7 @@ export default function App({ Component, pageProps }: AppProps) {
 
 If you're using the App Router, you can register it in `app/layout.tsx`:
 
-```tsx[app/layout.tsx]
+```tsx [app/layout.tsx]
 import { ReactNode } from "react";
 import { Providers } from "./providers";
 
@@ -143,11 +153,11 @@ export default function RootLayout({ children }: { children: ReactNode }) {
 }
 ```
 
-```tsx[app/providers.tsx]
+```tsx [app/providers.tsx]
 "use client";
 
 import { ReactNode } from "react";
-import { SdkProvider } from "../hooks";
+import { SdkProvider } from "@/sdk";
 
 export function Providers({ children }: { children: ReactNode }) {
   return <SdkProvider>{children}</SdkProvider>;
@@ -163,8 +173,9 @@ Don't be alarmed if you see a `use client` directive in the `app/providers.tsx`
 Once you have registered the SDK in your application, you can start using it. Here's an example of how you can use the SAP Commerce Cloud SDK module in your application:
 
 ::code-group
-```tsx[Pages Router]
-import { getSdk } from "../sdk.config";
+
+```tsx [Pages Router]
+import { getSdk } from "@/sdk";
 
 export function getServersideProps() {
   const sdk = getSdk();
@@ -177,16 +188,18 @@ export function getServersideProps() {
   };
 }
 ```
-```tsx[App Router]
-import { getSdk } from "../sdk.config";
+
+```tsx [App Router]
+import { getSdk } from "@/sdk";
 
 const sdk = getSdk();
 
 const { products } = await sdk.commerce.searchProduct();
 ```
-```tsx[Client Side Rendering]
+
+```tsx [Client Side Rendering]
 import { useEffect, useState } from "react";
-import { useSdk } from "../hooks";
+import { useSdk } from "@/sdk";
 
 export function ClientComponentUsingSDK() {
   const sdk = useSdk();
@@ -195,8 +208,8 @@ export function ClientComponentUsingSDK() {
   useEffect(() => {
     const fetchCart = async () => {
       const newCart = await sdk.commerce.getCart({
-        cartId: '<cart_id>',
-        fields: 'code,guid,user(FULL)'
+        cartId: "<cart_id>",
+        fields: "code,guid,user(FULL)",
       });
       setCart(newCart);
     };
@@ -205,6 +218,7 @@ export function ClientComponentUsingSDK() {
   }, []);
 }
 ```
+
 ::
 
 Code above is just an example of how you can use the SDK in your application. For more information about the avaialble methods, please refer to the respective [Integration's documentation](https://docs.vuestorefront.io/integrations).
@@ -215,7 +229,7 @@ That's it! You can now use VueStorefront SDK Module in your Next.js app ✨
 
 ## Installation
 
-To get started with the SDK within Next.js, first you have to install and configure the `@vue-storefront/nuxt` module. 
+To get started with the SDK within Next.js, first you have to install and configure the `@vue-storefront/nuxt` module.
 
 1. In the root of your Storefront project run:
 
@@ -232,7 +246,7 @@ npm install --save-dev @vue-storefront/nuxt
 
 2. Add `@vue-storefront/nuxt` to the `modules` section of `nuxt.config.ts`
 
-```ts[nuxt.config.ts]
+```ts [nuxt.config.ts]
 export default defineNuxtConfig({
   modules: ["@vue-storefront/nuxt"],
 });
@@ -242,13 +256,13 @@ export default defineNuxtConfig({
 
 To configure the module, use `vsf` key in the Nuxt configuration object and provide necessary information such as the Middleware instance address:
 
-```ts[nuxt.config.ts]
+```ts [nuxt.config.ts]
 export default defineNuxtConfig({
   modules: ["@vue-storefront/nuxt"],
   vsf: {
     middleware: {
-      apiUrl: "http://localhost:4000"
-    }
+      apiUrl: "http://localhost:4000",
+    },
   },
 });
 ```
@@ -257,7 +271,7 @@ export default defineNuxtConfig({
 
 To use SDK in our application, we need to initialize it first. To do so, follow these steps:
 
-Create SDK Config file - `sdk.config.ts` in root directory of your project. 
+Create SDK Config file - `sdk.config.ts` in root directory of your project.
 
 ::info
 For Nuxt framework it's necessary to name the file `sdk.config.ts` and keep it in the root of your project.
@@ -265,22 +279,22 @@ For Nuxt framework it's necessary to name the file `sdk.config.ts` and keep it i
 
 You should import all other SDK configuration components. See the example below illustrating the SDK configuration with SAP Commerce Cloud and Contentful modules.
 
-```ts[sdk.config.ts]
-import { sapccModule } from '@vsf-enterprise/sapcc-sdk';
-import {
-  contentfulModule,
-  ContentfulModuleType,
-} from "@vsf-enterprise/contentful-sdk";
+```ts [sdk.config.ts]
+import { contentfulModule } from "@vsf-enterprise/contentful-sdk";
+import { UnifiedEndpoints } from "storefront-middleware/types";
 
 export default defineSdkConfig(
-  ({ buildModule, middlewareUrl, getCookieHeader }) => ({
-    commerce: buildModule(sapccModule, {
-      apiUrl: middlewareUrl + "/commerce",
+  ({ buildModule, middlewareUrl, middlewareModule getRequestHeaders }) => ({
+    commerce: buildModule(middlewareModule<UnifiedEndpoints>, {
+      apiUrl: middlewareUrl + "/commerce", // SAP Commerce Cloud integration is available at /commerce endpoint
+      defaultRequestConfig: {
+        headers: getRequestHeaders(),
+      },
     }),
-    cms: buildModule<ContentfulModuleType>(contentfulModule, {
+    cms: buildModule(contentfulModule, {
       apiUrl: middlewareUrl + "/cms",
     }),
-  }),
+  })
 );
 ```
 
@@ -290,16 +304,15 @@ The `defineSdkConfig` function is used for intializing the SDK. The parameter fo
 
 - the `buildModule` function,
 - the middleware URL (`middlewareUrl`),
-- a function for retrieving the Cookie header with cookie values (`getCookieHeader`).
+- the `middlewareModule` - an SDK module that ensures communication with the Server Middleware. It takes the `UnifiedEndpoints` type as a generic parameter. The `UnifiedEndpoints` type is a type that represents the endpoints of the Server Middleware,
+- a function for retrieving request header, including cookie header (`getRequestHeaders`).
 
 ## Usage
 
 Once you have initialized the SDK, you can start using it. Here's an example of how you can use the SAP Commerce Cloud SDK module in your application:
 
 ```vue
-<template>
-  /* ... */
-</template>
+<template>/* ... */</template>
 
 <script setup>
 const sdk = useSdk();
@@ -321,15 +334,18 @@ That's it! You can now use VueStorefront SDK Module in your Nuxt app ✨
 To install the SDK Core, run the following command:
 
 ::code-group
+
 ```bash [npm]
+# Using npm
 npm install @vue-storefront/sdk
-```
-```bash [yarn]
+
+# Using yarn
 yarn add @vue-storefront/sdk
-```
-```bash [pnpm]
+
+# Using pnpm
 pnpm install @vue-storefront/sdk
 ```
+
 ::
 
 ## Initializing the SDK
@@ -350,29 +366,26 @@ The examples below use the SAP Commerce Cloud and Contentful SDK modules. Howeve
 
 When it comes to managing multiple SDK modules, there are two options for this:
 
-1. **Individual exports (recommended)** - initialize each integration as a separate SDK instance, allowing for better code-splitting 
+1. **Individual exports (recommended)** - initialize each integration as a separate SDK instance, allowing for better code-splitting
 2. **Single Instance** - combine multiple modules in one SDK instance
 
 ### Individual Exports
 
 ```ts [sdk.config.ts]
-import { initSDK, buildModule } from '@vue-storefront/sdk';
-import { sapccModule } from '@vsf-enterprise/sapcc-sdk';
-import {
-  contentfulModule,
-  ContentfulModuleType,
-} from "@vsf-enterprise/contentful-sdk";
-
-const { commerce } = initSDK({ 
-  commerce: buildModule(sapccModule, { 
-    apiUrl: 'http://localhost:8181/commerce' 
-  }) 
+import { initSDK, buildModule, middlewareModule } from "@vue-storefront/sdk";
+import { contentfulModule } from "@vsf-enterprise/contentful-sdk";
+import { UnifiedEndpoints } from "storefront-middleware/types";
+
+const { commerce } = initSDK({
+  commerce: buildModule(middlewareModule<UnifiedEndpoints>, {
+    apiUrl: "http://localhost:8181/commerce",
+  }),
 });
 
-const { cms } = initSDK({ 
-  cms: buildModule<ContentfulModuleType>(contentfulModule, {
-    apiUrl: 'http://localhost:8181/stripe'
-  })
+const { cms } = initSDK({
+  cms: buildModule(contentfulModule, {
+    apiUrl: "http://localhost:8181/cms",
+  }),
 });
 
 export { commerce, cms };
@@ -381,21 +394,18 @@ export { commerce, cms };
 ### Single Instance
 
 ```ts [sdk.config.ts]
-import { initSDK, buildModule } from '@vue-storefront/sdk';
-import { sapccModule } from '@vsf-enterprise/sapcc-sdk';
-import {
-  contentfulModule,
-  ContentfulModuleType,
-} from "@vsf-enterprise/contentful-sdk";
+import { initSDK, buildModule, middlewareModule } from "@vue-storefront/sdk";
+import { contentfulModule } from "@vsf-enterprise/contentful-sdk";
+import { UnifiedEndpoints } from "storefront-middleware/types";
 
 const sdkConfig = {
-  commerce: buildModule(sapccModule, { 
-    apiUrl: 'http://localhost:8181/commerce' 
+  commerce: buildModule(middlewareModule<UnifiedEndpoints>, {
+    apiUrl: "http://localhost:8181/commerce",
   }),
-  cms: buildModule<ContentfulModuleType>(contentfulModule, {
-    apiUrl: 'http://localhost:8181/cms'
-  })
-}
+  cms: buildModule(contentfulModule, {
+    apiUrl: "http://localhost:8181/cms",
+  }),
+};
 
 export const sdk = initSDK(sdkConfig);
 ```
@@ -415,16 +425,19 @@ For example, you can rename `commerce` to `sapcc` and `cms` to `contentful`. `in
 Once you have initialized the SDK, you can start using it. Here's an example of how you can use the SAP Commerce Cloud SDK module in your application:
 
 ::code-group
+
 ```ts[Individual Exports]
 import { commerce } from "../sdk.config";
 
 const { products } = await commerce.searchProduct();
 ```
+
 ```ts[Single Instance]
 import { sdk } from "../sdk.config";
 
 const { products } = await sdk.commerce.searchProduct();
 ```
+
 ::
 
 Code above is just an example of how you can use the SDK in your application. For more information about the avaialble methods, please refer to the respective [Integration's documentation](https://docs.vuestorefront.io/integrations).
diff --git a/docs/content/4.sdk/3.advanced/1.middleware-module.md b/docs/content/4.sdk/3.advanced/1.middleware-module.md
new file mode 100644
index 0000000000..9cd49cee79
--- /dev/null
+++ b/docs/content/4.sdk/3.advanced/1.middleware-module.md
@@ -0,0 +1,25 @@
+# The `middlewareModule`
+
+## Introduction
+
+## Configuration
+
+### Options
+
+###
+
+## Usage
+
+## Examples
+
+### Send a `GET` request
+
+### Add a header to each request
+
+### Add a header to single request
+
+### Replace the default HTTP client with `axios`
+
+### Add a custom error handler
+
+### Add cookies to the request during SSR
diff --git a/docs/content/4.sdk/3.advanced/extending-module.md b/docs/content/4.sdk/3.advanced/2.extending-module.md
similarity index 100%
rename from docs/content/4.sdk/3.advanced/extending-module.md
rename to docs/content/4.sdk/3.advanced/2.extending-module.md
diff --git a/docs/content/4.sdk/3.advanced/3.custom-modules.md b/docs/content/4.sdk/3.advanced/3.custom-modules.md
new file mode 100644
index 0000000000..1b496611c4
--- /dev/null
+++ b/docs/content/4.sdk/3.advanced/3.custom-modules.md
@@ -0,0 +1,14 @@
+# Custom modules
+
+::: tip When custom module is necessary?
+:::
+
+## Module
+
+## Connector
+
+## Methods
+
+## Utils
+
+## Subscribers
\ No newline at end of file

From bd569b9a6fb1264049ad5dfe28a2cfe1b81d1317 Mon Sep 17 00:00:00 2001
From: Wojciech Sikora <wsikora@vuestorefront.io>
Date: Fri, 15 Mar 2024 14:54:45 +0100
Subject: [PATCH 02/17] Add docs for middleware module

---
 .../4.sdk/2.getting-started/1.index.md        |  10 +-
 .../4.sdk/3.advanced/1.middleware-module.md   | 380 +++++++++++++++++-
 2 files changed, 384 insertions(+), 6 deletions(-)

diff --git a/docs/content/4.sdk/2.getting-started/1.index.md b/docs/content/4.sdk/2.getting-started/1.index.md
index 30dfb2c4c9..c5330e8bd5 100644
--- a/docs/content/4.sdk/2.getting-started/1.index.md
+++ b/docs/content/4.sdk/2.getting-started/1.index.md
@@ -37,15 +37,15 @@ It is not necessary to name the file `sdk.config.ts` specifically or to keep it
 
 2. Create the SDK configuration by importing the `createSdk` function from the Next.js SDK and using the `middlewareModule` it provides. You should also import other modules you want to use.
 
-```ts[sdk.config.ts]
+```ts [sdk.config.ts]
 import { contentfulModule } from "@vsf-enterprise/contentful-sdk";
 import { CreateSdkOptions, createSdk } from "@vue-storefront/next";
 import { UnifiedEndpoints } from "storefront-middleware/types";
 
 const options: CreateSdkOptions = {
-   middleware: {
-        apiUrl: "http://localhost:4000",
-   }
+  middleware: {
+    apiUrl: "http://localhost:4000",
+  },
 };
 
 export const { getSdk } = createSdk(
@@ -60,7 +60,7 @@ export const { getSdk } = createSdk(
     cms: buildModule(contentfulModule, {
       apiUrl: middlewareUrl + "/cms",
     }),
-  }),
+  })
 );
 ```
 
diff --git a/docs/content/4.sdk/3.advanced/1.middleware-module.md b/docs/content/4.sdk/3.advanced/1.middleware-module.md
index 9cd49cee79..a621b3ff27 100644
--- a/docs/content/4.sdk/3.advanced/1.middleware-module.md
+++ b/docs/content/4.sdk/3.advanced/1.middleware-module.md
@@ -2,24 +2,402 @@
 
 ## Introduction
 
+The `middlewareModule` is an SDK module that ensures communication with the [Server Middleware](/middleware).
+
+## Setup
+
+Depending on which framework you are using, you can get the `middlewareModule` in different ways. However, the setup is always the same.
+
+In Next, `middlewareModule` is available in the `createSdk` function.
+
+```ts [Nuxt]
+// sdk/sdk.config.ts
+import { CreateSdkOptions, createSdk } from "@vue-storefront/next";
+import { UnifiedEndpoints } from "storefront-middleware/types";
+
+const options: CreateSdkOptions = {
+  middleware: {
+    apiUrl: "http://localhost:4000",
+  },
+};
+
+export const { getSdk } = createSdk(
+  options,
+  ({ buildModule, middlewareUrl, middlewareModule, getRequestHeaders }) => ({
+    commerce: buildModule(middlewareModule<UnifiedEndpoints>, {
+      apiUrl: middlewareUrl + "/commerce",
+      defaultRequestConfig: {
+        headers: getRequestHeaders(),
+      },
+    }),
+  })
+);
+```
+
+In Nuxt, `middlewareModule` is available in the `defineSdkConfig` function.
+
+```ts [Nuxt]
+// sdk.config.ts
+import { UnifiedEndpoints } from "storefront-middleware/types";
+
+export default defineSdkConfig(
+  ({ buildModule, middlewareUrl, middlewareModule getRequestHeaders }) => ({
+    commerce: buildModule(middlewareModule<UnifiedEndpoints>, {
+      apiUrl: middlewareUrl + "/commerce", // SAP Commerce Cloud integration is available at /commerce endpoint
+      defaultRequestConfig: {
+        headers: getRequestHeaders(),
+      },
+    })
+  })
+);
+```
+
+You can also import it directly from the `@vue-storefront/sdk` package.
+
+```ts [Other]
+import { initSDK, buildModule, middlewareModule } from "@vue-storefront/sdk";
+import { UnifiedEndpoints } from "storefront-middleware/types";
+
+export const sdk = initSDK({
+  commerce: buildModule(middlewareModule<UnifiedEndpoints>, {
+    apiUrl: "http://localhost:8181/commerce",
+  }),
+});
+```
+
 ## Configuration
 
+### Type definition
+
+As the `middlewareModule` could be used to communicate with the Server Middleware and it's not limited to a specific backend, it requires a type definition of the endpoints.
+
+The type definition should be provided as a generic type to the `middlewareModule` function.
+
+```ts
+type Endpoints = {
+  getProduct: ({
+    id: string,
+  }) => Promise<{ id: string; title: string; description: string }>;
+};
+
+const sdk = initSDK({
+  commerce: buildModule(middlewareModule<Endpoints>, {
+    apiUrl: "http://localhost:8181/commerce",
+  }),
+});
+
+const product = await sdk.commerce.getProduct({ id: "123" });
+```
+
+In Storefront Starter, you can find the `UnifiedEndpoints` type in `storefront-middleware/types.ts` file. It's a type definition for the endpoints used in the middleware.
+
+```ts
+import { UnifiedEndpoints } from "storefront-middleware/types";
+
+export const sdk = initSDK({
+  commerce: buildModule(middlewareModule<UnifiedEndpoints>, {
+    apiUrl: "http://localhost:8181/commerce",
+  }),
+});
+
+const product = await sdk.commerce.getProduct({ id: "123" });
+```
+
+Also, you can import the `Endpoints` type from integration packages.
+
+```ts
+import { Endpoints } from "@vsf-enterprise/sapcc-api";
+
+export const sdk = initSDK({
+  commerce: buildModule(middlewareModule<Endpoints>, {
+    apiUrl: "http://localhost:8181/commerce",
+  }),
+});
+```
+
 ### Options
 
-###
+The `middlewareModule` accepts the following options:
+
+- `apiUrl` - the URL of the middleware server,
+- `ssrApiUrl` - (Optional) the URL of the middleware server during SSR,
+- `defaultRequestConfig` - (Optional) default request config for each request,
+- `httpClient` - (Optional) a custom HTTP client,
+- `errorHandler` - (Optional) a custom error handler for HTTP requests.
+
+Example configuration:
+
+```ts
+import { initSDK, buildModule, middlewareModule } from "@vue-storefront/sdk";
+import { UnifiedEndpoints } from "storefront-middleware/types";
+
+export const sdk = initSDK({
+  commerce: buildModule(middlewareModule<UnifiedEndpoints>, {
+    apiUrl: "/api/commerce",
+    ssrApiUrl: "http://localhost:8181/commerce",
+    defaultRequestConfig: {
+      headers: {
+        "X-Api-Key": "123",
+      },
+    },
+    httpClient: async (url, params, config) => {
+      // Custom HTTP client
+    },
+    errorHandler: ({ error, methodName, url, params, config, httpClient }) => {
+      // Custom error handler
+    },
+  }),
+});
+```
 
 ## Usage
 
+Once you have added the `middlewareModule` to your SDK, you can use it to make requests to the Server Middleware.
+
+```ts
+const product = await sdk.commerce.getProduct({ id: "123" });
+```
+
+Additionally, each method of this module allows you to pass a custom request configuration. To do it, you need to import `prepareConfig` helper from `@vue-storefront/sdk` package.
+
+```ts
+import { prepareConfig } from "@vue-storefront/sdk";
+
+const product = await sdk.commerce.getProduct(
+  { id: "123" },
+  prepareConfig({
+    method: "GET",
+    headers: {
+      "X-Custom-Header": "123",
+    },
+  })
+);
+```
+
 ## Examples
 
 ### Send a `GET` request
 
+By default, each request is a `POST` request. You can change it by passing a custom request configuration.
+
+```ts
+const product = await sdk.commerce.getProduct(
+  { id: "123" },
+  prepareConfig({
+    method: "GET",
+  })
+);
+```
+
+### Use a `GET` method by default
+
+You can use a `GET` method by default by passing it in the `defaultRequestConfig` option of the `middlewareModule` function.
+
+```ts
+export const sdk = initSDK({
+  commerce: buildModule(middlewareModule<UnifiedEndpoints>, {
+    apiUrl: "http://localhost:8181/commerce",
+    defaultRequestConfig: {
+      method: "GET",
+    },
+  }),
+});
+```
+
 ### Add a header to each request
 
+You can add a header to each request by passing it in the `defaultRequestConfig` option of the `middlewareModule` function.
+
+```ts
+export const sdk = initSDK({
+  commerce: buildModule(middlewareModule<UnifiedEndpoints>, {
+    apiUrl: "http://localhost:8181/commerce",
+    defaultRequestConfig: {
+      headers: {
+        "X-Api-Key": "123",
+      },
+    },
+  }),
+});
+```
+
 ### Add a header to single request
 
+You can add a header to a single request by passing it in the request configuration.
+
+```ts
+const product = await sdk.commerce.getProduct(
+  { id: "123" },
+  prepareConfig({
+    headers: {
+      "X-Custom-Header": "123",
+    },
+  })
+);
+```
+
 ### Replace the default HTTP client with `axios`
 
+By default, the SDK uses the `fetch` API.
+You can replace the default HTTP client with `axios` by passing it in the `httpClient` option of the `middlewareModule` function.
+
+There are some requirements for the custom HTTP client.
+
+1. It must be an async function accepting the following parameters:
+   - `url` - the URL of the request,
+   - `params` - the parameters of the request,
+   - `config` - the request configuration,
+2. It must include the `Access-Control-Allow-Credentials` response header (more info [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials)),
+3. It must throw an `SdkHttpError` if the request fails.
+
+```ts
+import axios from "axios";
+import { SdkHttpError } from "@vue-storefront/sdk";
+
+export const sdk = initSDK({
+  commerce: buildModule(middlewareModule<UnifiedEndpoints>, {
+    apiUrl: "http://localhost:8181/commerce",
+    httpClient: async (url, params, config) => {
+      try {
+        const { data } = await axios(url, {
+          ...config,
+          data: params,
+          withCredentials: true, // Includes the `Access-Control-Allow-Credentials` response header
+        });
+
+        return data;
+      } catch (error: any) {
+        throw new SdkHttpError({
+          statusCode: error.response?.status || 500,
+          message: error.response?.data?.message || error.message,
+          cause: error,
+        });
+      }
+    },
+  }),
+});
+```
+
+::: warning
+It's important to include the `Access-Control-Allow-Credentials` response header in the custom HTTP client. Otherwise, the cookies won't be sent with the request.
+:::
+
 ### Add a custom error handler
 
+You can add a custom error handler by passing it in the `errorHandler` option of the `middlewareModule` function.
+
+```ts
+import { SdkHttpError } from "@vue-storefront/sdk";
+import { refreshToken } from "./handlers/refreshToken"; // Custom implementation of the refresh token logic
+
+const options: Options = {
+  apiUrl: "https://api.example.com",
+  errorHandler: async ({
+    error,
+    methodName,
+    url,
+    params,
+    config,
+    httpClient,
+  }) => {
+    if (error.status === 401 && methodName !== "login") {
+      // Refresh the token
+      await refreshToken();
+      // Retry the request
+      return httpClient(url, params, config);
+    }
+
+    throw error;
+  },
+};
+```
+
 ### Add cookies to the request during SSR
+
+Normally, the cookies are sent with the request during CSR. However, during SSR, you need to pass them manually.
+
+`@vue-storefront/next` and `@vue-storefront/nuxt` provide a `getRequestHeaders` helper that returns the cookies.
+
+To use it, you need to pass the `getRequestHeaders` function to the `defaultRequestConfig` option of the `middlewareModule` function.
+
+```ts [Next]
+// sdk/sdk.config.ts
+import { createSdk } from "@vue-storefront/next";
+import { UnifiedEndpoints } from "storefront-middleware/types";
+
+const options = {
+  middleware: {
+    apiUrl: "http://localhost:4000",
+  },
+};
+
+export const { getSdk } = createSdk(
+  options,
+  ({ buildModule, middlewareUrl, middlewareModule, getRequestHeaders }) => ({
+    commerce: buildModule(middlewareModule<UnifiedEndpoints>, {
+      apiUrl: middlewareUrl + "/commerce",
+      defaultRequestConfig: {
+        headers: getRequestHeaders(),
+      },
+    }),
+  })
+);
+```
+
+```ts [Nuxt]
+// sdk.config.ts
+import { defineSdkConfig } from "@vue-storefront/nuxt";
+import { UnifiedEndpoints } from "storefront-middleware/types";
+
+export default defineSdkConfig(
+  ({ buildModule, middlewareUrl, middlewareModule, getRequestHeaders }) => ({
+    commerce: buildModule(middlewareModule<UnifiedEndpoints>, {
+      apiUrl: middlewareUrl + "/commerce",
+      defaultRequestConfig: {
+        headers: getRequestHeaders(),
+      },
+    }),
+  })
+);
+```
+
+While Nuxt ensures that cookies are sent with the request without any additional configuration, in Next, you need to pass the headers to `getSdk` function.
+
+```tsx [App Router]
+import { headers } from "next/headers";
+import { getSdk } from "@/sdk";
+
+export default async function SsrPage() {
+  const sdk = getSdk({
+    getRequestHeaders: () => headers(),
+  });
+  const product = await sdk.commerce.getProduct({ id: "123" });
+
+  return (
+    // ...
+  );
+}
+```
+
+```tsx [Pages Router]
+import { GetServerSideProps } from "next";
+import { getSdk } from "@/sdk";
+
+export default function SsrPage({ result }: any) {
+  return (
+    // ...
+  );
+}
+
+export const getServerSideProps: GetServerSideProps = async ({ req }) => {
+  const sdk = getSdk({
+    getRequestHeaders: () => req.headers,
+  });
+
+  return {
+    props: {
+      result: await sdk.commerce.getProduct({ id: "123" }),
+    },
+  };
+};
+```

From 3fb2bb7e6f6ac7b856ee78219f807b9d1b6aa747 Mon Sep 17 00:00:00 2001
From: Wojciech Sikora <wsikora@vuestorefront.io>
Date: Fri, 15 Mar 2024 15:06:14 +0100
Subject: [PATCH 03/17] extension docs - in progress

---
 .../4.sdk/3.advanced/2.extending-module.md    | 403 ++----------------
 1 file changed, 32 insertions(+), 371 deletions(-)

diff --git a/docs/content/4.sdk/3.advanced/2.extending-module.md b/docs/content/4.sdk/3.advanced/2.extending-module.md
index 1e607ce7cc..2b9680ba36 100644
--- a/docs/content/4.sdk/3.advanced/2.extending-module.md
+++ b/docs/content/4.sdk/3.advanced/2.extending-module.md
@@ -1,397 +1,58 @@
 # Extending a Module
 
-In most cases, a module exports the base set of communication methods and utilities. 
+In most cases, a module exports the base set of communication methods and utilities.
 
 However, developers might require additional functionality that the module doesn't provide.
- 
-To address this issue without requesting new features from the module's author, each module can be customized to meet the specific needs of developers.
-
-A module extension is an object that defines a custom behavior for a module. It can contain interceptors, utility methods, and subscribers. This enables developers to tailor the module to their specific needs and add new functionality.
-
-SDK Core package exports the `Extension` type that defines the structure of the module extension.
-
-Example extension looks like this:
-
-```js
-// SAPCC Example
-
-import { Extension } from '@vue-storefront/sdk';
-
-/**
- * SAPCC Extension type.
- * In this example we used `any` type for the `interceptors`, `utils`, `extend` and `override` properties, however, it's recommended to use a specific type for each of them.
- */
-interface SAPCCExtension extends Extension {
-  interceptors: any[];
-  utils: any;
-  extend: any;
-  override: any;
-  subscribers: any;
-}
 
-export const sapccExtension: SAPCCExtension = {
-  interceptors: [],
-  utils: {},
-  extend: {},
-  override: {},
-  subscribers: {}
-};
-```
-
-Let's review each of the extension properties to understand their roles and responsibilities.
+To address this issue without requesting new features from the module's author, each module can be customized to meet the specific needs of developers.
 
-## Interceptors
+## Quick start
 
-Interceptors are functions that modify the input parameters of a method or the output result of a method. 
+To extend the SDK module, add either an object or a function to the `buildModule` function parameters.
 
-### Execution order of interceptors
+```ts
+import { UnifiedEndpoints } from "storefront-middleware/types";
 
-Assume that you have the following interceptors defined for the `getProducts` method:
+// Extension as an object
 
-```js
-const extension = {
-  interceptors: [
+const sdk = initSDK({
+  commerce: buildModule(
+    middlewareModule<UnifiedEndpoints>,
     {
-      before: {
-        getProducts: (args: any) => {
-          return ["modified-args"];
-        },
-      },
-      after: {
-        getProducts: (result: any) => {
-          return `${result}-modified-result`;
-        },
-      },
-      around: {
-        getProducts: [
-          (next: any, arg1: any, arg2: any) => {
-            const result = next(arg1, arg2);
-            return result + "-around1";
-          },
-          (next: any, arg1: any, arg2: any) => {
-            const result = next(arg1, arg2);
-            return result + "-around2";
-          },
-          (next: any, arg1: any, arg2: any) => {
-            const result = next(arg1, arg2);
-            return result + "-around3";
-          },
-        ],
-      },
+      apiUrl: "http://localhost:8181/commerce",
     },
-  ],
-};
-```
-
-The execution order of interceptors will be as follows:
-* all `before` interceptors in the order they are defined
-  * `around` interceptor 1 up to next() call
-    * `around` interceptor 2 up to next() call
-      * `around` interceptor 3 up to next() call
-        * `getProducts` method
-      * `around` interceptor 3 after next() call
-    * `around` interceptor 2 after next() call
-  * `around` interceptor 1 after next() call
-* all `after` interceptors in the order they are defined
-
-`getProducts` method will be called only once.
-
-### `before` interceptors
-
-`before` interceptors allow you to define a list of interceptors that can modify the input parameters of an SDK method. 
-
-These interceptors will run before your method call and will modify the input parameters before they enter the SDK method.
-
-:::warning `before` interceptors should not change the return type of the parameter!
-
-The idea of `before` interceptors is to modify the input parameters values only. 
-It should not be used to change the contract, that may break the typing and cause unforeseen issues.
-:::
-
-```js
-// SAPCC Example
-
-export const sapccExtension: SAPCCExtension = {
-  interceptors: [
-    {
-      before: {
-        getProducts: (args: Parameters<SAPCCModuleType['connector']['getProducts']>): Parameters<SAPCCModuleType['connector']['getProducts']> => {
-          console.log(`Interceptor modifies the input of getProducts method.`)
-
-          return [{
-            id: 2
-          }]
-        }
-      }
-    }
-  ]
-}
-```
-
-### `after` interceptors
-
-`after` interceptors allow you to define a list of interceptors that can modify the output of an SDK method. 
-
-These interceptors run after your method call and modify the output result.
-
-:::warning `after` interceptors should not change the return type of the parameter!
-The idea of `after` interceptors is to modify the output value only. 
-It should not be used to change the contract, that may break the typing and cause unforeseen issues.
-:::
-
-```js
-// SAPCC Example
-
-export const sapccExtension: SAPCCExtension = {
-  interceptors: [
-    {
-      after: {
-        getProducts: (res: ReturnType<SAPCCModuleType['connector']['getProducts']>): ReturnType<SAPCCModuleType['connector']['getProducts']> => {
-          console.log(`Interceptor modifies the output of getProducts method.`)
-
-          return [{ id: res[0].id, name: 'Hello world' }]
-        }
-      }
-    }
-  ]
-}
-```
-
-### `around` interceptors
-`around` interceptors allow you to define a list of interceptors that can modify the input and output of an SDK method and have access to the original method.
-
-These interceptors run after all `before` interceptors and before all `after` interceptors.
-
-:::warning `around` interceptors should not change the return type of the parameter!
-it is up to the developer to call the original method, if it's not called, the SDK method won't be executed.
-:::
-
-```js
-// SAPCC Example
-type GetProductsFn = typeof SAPCCModuleType['connector']['getProducts'];
-
-export const sapccExtension: SAPCCExtension = {
-  interceptors: [
     {
-      around: {
-        getProducts: (next: GetProductsFn, ...args: Parameters<GetProductsFn>): ReturnType<GetProductsFn> => {
-          // Do something before the method call
-          // ...
-
-          // Call the original method, if it's not called, the SDK method won't be executed
-          const result = next(...args);
-          
-          // Do something after the method call with the result
-          result.myCustomProperty = 'Hello world';
-
-          return result;
-        }
-      }
-    }
-  ]
-}
-```
-
-## `utils`
-
-The `utils` property allows you to define methods that can be used to extend the module's functionalities. Utils should not depend on on any other components
-
-:::tip Why to use `utils` methods?
-Imagine you're creating an integration with a payment provider. 
-To initialize the payment, you need to pass a specific config, that might be hard to create for someone who is not familiar with the payment provider. 
-In this case, you can create a `utils` method that will create the config for you. 
-Such method won't be asynchronous and won't be affected by the interceptors.
-:::
-
-```js
-// SAPCC Example
-
-export const sapccExtension: SAPCCExtension = {
-  utils: {
-    buildConfig: (config: any) => {
-      return {
-        ...config,
-        paymentServiceProvider: 'SAPCC-Payments'
-      };
-    }
-  }
-};
-```
-
-Example of using `utils` method:
-
-```js
-// SAPCC Example
-
-import { sdk } from './sdk'
-
-// Using utils methods
-const sapccPaymentConfig = sdk.sapcc.utils.buildConfig(baseConfig);
-```
-
-## `extend`
-
-`extend` can be used to create a new method that is not covered by the module. 
-
-:::tip These methods are affected by interceptors
-Like the built-in SDK methods, methods in `extend` are impacted by your interceptors.
-:::
-
-The very common use case and also very basic example of using `extend` is to create a new method that is not covered by the module. In this example the `extend` attribute is configured with an object that contains a method `getProductBySku` that returns a promise.
-
-```js
-// SAPCC Example
-
-export const sapccExtension: SAPCCExtension = {
-  extend: {
-    getProductBySku: (sku: string) => {
-      return axios.get(`/products/${sku}`);
-    }
-  }
-};
-```
-
-Example of using `extend` method:
-
-```js
-// SAPCC Example
-
-import { sdk } from './sdk';
-
-// Using extend methods
-const product = await sdk.sapcc.getProductBySku('product-sku');
-```
-
-In the example below, we are using the `extend` attribute to create a new method `getProductBySkuWithLogger` that logs the used sku and then calls the original `getProductBySku` method.
-
-`buildModule` function provides the parent object that contains the original methods and optional context. You can use it to call the original method or access additional properties in the context.
-
-We pass a factory function as the third argument to the `buildModule` function. The factory function receives the options and the parent object as arguments. Parent object contains the original methods and optional context.
-
-In this example, we are also using the `customMethod` that calls an external API using the `context.client` method.
-
-```ts
-const sdkConfig = {
-  sapcc: buildModule(
-    // sapccModule is the module that we want to extend
-    sapccModule, 
-    // module options
-    { url: "some-url" }, 
-    // factory function that receives the options and the parent object as arguments
-    (options, { methods, context }) => { 
-    return {
       extend: {
-        getProductBySkuWithLogger: (sku: string) => {
-          console.log("used sku", sku);
-          return await parent.methods.getProductBySku(sku);(1);
-        },
-        customMethod: async () => {
-          return (
-            await parent.context.client(
-              "some-url-to-external-api",
-            )
-          );
+        customMethod: () => {
+          console.log("Custom method");
         },
       },
-    };
-  }),
-};
-```
-In such way you can easily extend the module with new methods and use the original methods. Also, it is up to the developer to decide if the `context` object is available and what properties it contains.
-
-:::tip
-As a rule of thumb, it's recommended to add options and client to the context object as it allows for easy implementation of custom methods.
-:::
-
-:::
-warning the `context` object is optional and might not be available in all modules. Please, check the module's documentation to see if it's available and what properties it contains. You can also check type-hinting in your IDE to see what properties are available.
-:::
-
-
-## `override`
-
-While `extend` allows you to create a new method, `override` allows you to change the behavior of the existing method.
-
-:::tip 
-These methods are affected by interceptors
-Like the built-in SDK methods, methods in `extend` are impacted by your interceptors.
-:::
-
-```js
-// SAPCC Example
-
-export const sapccExtension: SAPCCExtension = {
-  override: {
-    getProducts: (params: any) => {
-      return axios.get(`/products`, { params });
-    }
-  }
-};
-```
-
-Example of using `override` method:
-
-```js
-import { sdk } from './sdk';
-
-// Using module's method
-sdk.sapcc.getProducts({ ids: [1, 2, 3] });
-
-```
-
-## `subscribers`
-
-Subscribers are functions that are called when the specific event is emitted.
-
-Events that can be emited are:
-- `*_before` - run the function before EACH method of EACH module,
-- `*_after` - run the function after EACH method of EACH module,
-- `<module>_before` - run the function before EACH method of the specific module,
-- `<module>_after` - run the function after EACH method of the specific module,
-- `<module>_<method>_before` - run the function before the specific method of the specific module,
-- `<module>_<method>_after` - run the function after the specific method of the specific module.
-
-It implements the [publish-subscribe](https://www.enjoyalgorithms.com/blog/publisher-subscriber-pattern) pattern. 
-
-It's a great place to add some custom logic, like logging or analytics.
-
-```js
-// SAPCC Example
-
-export const sapccExtension: SAPCCExtension = {
-  subscribers: {
-    sapcc_before: () => {
-      console.log(`Before each SAPCC method do something`);
-    },
-    sapcc_after: () => {
-      console.log(`After each SAPCC method do something`);
     }
-  }
-};
-```
-
-## Using the extension
-
-To use the extension, you need to import it and pass it as the third argument to the buildModule function. In addition, you need to pass the type of the extension (SAPCCExtensionType) as the second generic argument to the buildModule function. To pass the type of the extension, you can use the typeof operator. Here's an example:
+  ),
+});
 
-```js
-// SAPCC Example
+await sdk.commerce.customMethod(); // Logs "Custom method"
 
-import { sapccModule, SAPCCModuleType } from '@vsf-enterprise/sapcc-sdk';
-import { initSDK, buildModule } from '@vue-storefront/sdk';
-import { sapccExtension, type SAPCCExtensionType } from './sapccExtension';
+// Extension as a function
 
-const sdkConfig = {
-  sapcc: buildModule<SAPCCModuleType, SAPCCExtensionType>(
-    sapccModule,
+const sdk = initSDK({
+  commerce: buildModule(
+    middlewareModule<UnifiedEndpoints>,
     {
-      apiUrl: "http://localhost:8181/sapcc",
+      apiUrl: "http://localhost:8181/commerce",
     },
-    sapccExtension
+    (extensionParams, module) => ({
+      extend: {
+        customMethod: () => {
+          console.log("Extension params: ", extensionParams);
+        },
+      },
+    }),
+    { customParam: "customValue" }
   ),
-};
+});
 
-export const sdk = initSDK<typeof sdkConfig>(sdkConfig);
+await sdk.commerce.customMethod(); // Logs "Extension params: { customParam: 'customValue' }"
 ```
 
-Now you can use the extension in your application.
+Extensions initialized as functions can be configured with the `extensionParams` and have access to the module internals.

From 0a4064e62cb676659a8c12866eb19708c883da4c Mon Sep 17 00:00:00 2001
From: Wojciech Sikora <wsikora@vuestorefront.io>
Date: Fri, 15 Mar 2024 15:50:00 +0100
Subject: [PATCH 04/17] add docs for extending a module

---
 .../4.sdk/3.advanced/2.extending-module.md    | 355 +++++++++++++++++-
 1 file changed, 353 insertions(+), 2 deletions(-)

diff --git a/docs/content/4.sdk/3.advanced/2.extending-module.md b/docs/content/4.sdk/3.advanced/2.extending-module.md
index 2b9680ba36..b56fc298f4 100644
--- a/docs/content/4.sdk/3.advanced/2.extending-module.md
+++ b/docs/content/4.sdk/3.advanced/2.extending-module.md
@@ -41,7 +41,7 @@ const sdk = initSDK({
     {
       apiUrl: "http://localhost:8181/commerce",
     },
-    (extensionParams, module) => ({
+    (extensionParams, { methods, context }) => ({
       extend: {
         customMethod: () => {
           console.log("Extension params: ", extensionParams);
@@ -55,4 +55,355 @@ const sdk = initSDK({
 await sdk.commerce.customMethod(); // Logs "Extension params: { customParam: 'customValue' }"
 ```
 
-Extensions initialized as functions can be configured with the `extensionParams` and have access to the module internals.
+Extensions initialized as functions can be configured with the `extensionParams` and have access to the module internals - `methods` and `context`.
+
+## Extension properties
+
+An example extension might look like this:
+
+```ts
+import { Extension } from "@vue-storefront/sdk";
+
+export const sapccExtension = {
+  interceptors: [],
+  utils: {},
+  extend: {},
+  override: {},
+  subscribers: {},
+};
+```
+
+Let's review each of the extension properties to understand their roles and responsibilities.
+
+### interceptors
+
+#### `before` interceptors
+
+`before` interceptors allow you to define a list of interceptors that can modify the input parameters of an SDK method.
+
+These interceptors will run before your method call and will modify the input parameters before they enter the SDK method.
+
+:::warning `before` interceptors should not change the return type of the parameter!
+
+The idea of `before` interceptors is to modify the input parameters values only.
+It should not be used to change the contract, that may break the typing and cause unforeseen issues.
+:::
+
+```ts
+import { UnifiedEndpoints } from "storefront-middleware/types";
+
+export const sapccExtension = {
+  interceptors: [
+    {
+      before: {
+        getProducts: (
+          args: Parameters<UnifiedEndpoints["getProducts"]>
+        ): Parameters<UnifiedEndpoints["getProducts"]> => {
+          console.log(`Interceptor modifies the input of getProducts method.`);
+
+          return [
+            {
+              id: 2,
+            },
+          ];
+        },
+      },
+    },
+  ],
+};
+```
+
+#### `after` interceptors
+
+`after` interceptors allow you to define a list of interceptors that can modify the output of an SDK method.
+
+These interceptors run after your method call and modify the output result.
+
+:::warning `after` interceptors should not change the return type of the parameter!
+The idea of `after` interceptors is to modify the output value only.
+It should not be used to change the contract, that may break the typing and cause unforeseen issues.
+:::
+
+```ts
+import { UnifiedEndpoints } from "storefront-middleware/types";
+
+export const sapccExtension = {
+  interceptors: [
+    {
+      after: {
+        getProducts: (
+          res: ReturnType<UnifiedEndpoints["getProducts"]>
+        ): ReturnType<UnifiedEndpoints["getProducts"]> => {
+          console.log(`Interceptor modifies the output of getProducts method.`);
+
+          return [{ id: res[0].id, name: "Hello world" }];
+        },
+      },
+    },
+  ],
+};
+```
+
+#### `around` interceptors
+
+`around` interceptors allow you to define a list of interceptors that can modify the input and output of an SDK method and have access to the original method.
+
+These interceptors run after all `before` interceptors and before all `after` interceptors.
+
+:::warning `around` interceptors should not change the return type of the parameter!
+it is up to the developer to call the original method, if it's not called, the SDK method won't be executed.
+:::
+
+```ts
+import { UnifiedEndpoints } from "storefront-middleware/types";
+
+type GetProductsFn = UnifiedEndpoints["getProducts"];
+
+export const sapccExtension = {
+  interceptors: [
+    {
+      around: {
+        getProducts: (
+          next: GetProductsFn,
+          ...args: Parameters<GetProductsFn>
+        ): ReturnType<GetProductsFn> => {
+          // Do something before the method call
+          // ...
+
+          // Call the original method, if it's not called, the SDK method won't be executed
+          const result = next(...args);
+
+          // Do something after the method call with the result
+          result.myCustomProperty = "Hello world";
+
+          return result;
+        },
+      },
+    },
+  ],
+};
+```
+
+#### Execution order of interceptors
+
+Assume that you have the following interceptors defined for the `getProducts` method:
+
+```ts
+const extension = {
+  interceptors: [
+    {
+      before: {
+        getProducts: (args: any) => {
+          return ["modified-args"];
+        },
+      },
+      after: {
+        getProducts: (result: any) => {
+          return `${result}-modified-result`;
+        },
+      },
+      around: {
+        getProducts: [
+          (next: any, arg1: any, arg2: any) => {
+            const result = next(arg1, arg2);
+            return result + "-around1";
+          },
+          (next: any, arg1: any, arg2: any) => {
+            const result = next(arg1, arg2);
+            return result + "-around2";
+          },
+          (next: any, arg1: any, arg2: any) => {
+            const result = next(arg1, arg2);
+            return result + "-around3";
+          },
+        ],
+      },
+    },
+  ],
+};
+```
+
+The execution order of interceptors will be as follows:
+
+- all `before` interceptors in the order they are defined
+  - `around` interceptor 1 up to next() call
+    - `around` interceptor 2 up to next() call
+      - `around` interceptor 3 up to next() call
+        - `getProducts` method
+      - `around` interceptor 3 after next() call
+    - `around` interceptor 2 after next() call
+  - `around` interceptor 1 after next() call
+- all `after` interceptors in the order they are defined
+
+`getProducts` method will be called only once.
+
+### `utils`
+
+The `utils` property allows you to define methods that can be used to extend the module's functionalities. Utils should not depend on any other components
+
+:::tip Why to use `utils` methods?
+Imagine you're creating an integration with a payment provider.
+To initialize the payment, you need to pass a specific config, that might be hard to create for someone who is not familiar with the payment provider.
+In this case, you can create a `utils` method that will create the config for you.
+Such method won't be asynchronous and won't be affected by the interceptors.
+:::
+
+```ts
+export const sapccExtension = {
+  utils: {
+    buildConfig: (config: any) => {
+      return {
+        ...config,
+        paymentServiceProvider: "SAPCC-Payments",
+      };
+    },
+  },
+};
+```
+
+Example of using `utils` method:
+
+```ts
+// Using utils methods
+const sapccPaymentConfig = sdk.sapcc.utils.buildConfig(baseConfig);
+```
+
+### `extend`
+
+`extend` can be used to create a new method that is not covered by the module.
+
+:::tip These methods are affected by interceptors
+Like the built-in SDK methods, methods in `extend` are impacted by your interceptors.
+:::
+
+Let's assume you want to add a custom `authenticate` method that calls an external service to authenticate the user and want to use a fallback if the service is not available.
+You can add the `authenticate` method to the `extend` property and reuse the existing `login` method as a fallback.
+
+```ts
+import { UnifiedEndpoints } from "storefront-middleware/types";
+
+const sdk = initSDK({
+  auth: buildModule(
+    middlewareModule<UnifiedEndpoints>,
+    {
+      apiUrl: "http://localhost:8181/auth",
+    },
+    (_extensionParams, { methods }) => ({
+      extend: {
+        authenticate: async (username: string, password: string) => {
+          try {
+            const response = await fetch(
+              "http://external-service/authenticate",
+              {
+                method: "POST",
+                body: JSON.stringify({ username, password }),
+              }
+            );
+
+            if (response.ok) {
+              return response.json();
+            }
+          } catch (e) {
+            console.error("External service is not available. Using fallback.");
+          }
+
+          return await methods.login(username, password);
+        },
+      },
+    })
+  ),
+});
+```
+
+You can also access the module `context`. Each module author can define its own context. `middlewareModule` provides access to module options and `requestSender` through its `context`.
+
+```ts
+import { UnifiedEndpoints } from "storefront-middleware/types";
+
+const sdk = initSDK({
+  auth: buildModule(
+    middlewareModule<UnifiedEndpoints>,
+    {
+      apiUrl: "http://localhost:8181/commerce",
+    },
+    (_extensionParams, { methods, context }) => ({
+      extend: {
+        authenticate: async (username: string, password: string) => {
+          try {
+            console.log("Base url: ": context.options.apiUrl);
+            const response = await context.requestSender("/authenticate", {
+              username,
+              password,
+            });
+
+            return response;
+          } catch (e) {
+            console.error("Auth service is not available. Using fallback.");
+          }
+
+          return await methods.login(username, password);
+        },
+      },
+    })
+  ),
+});
+```
+
+:::tip
+As a rule of thumb, it's recommended to add options and client to the context object as it allows for easy implementation of custom methods.
+:::
+
+:::
+warning the `context` object is optional and might not be available in all modules. Please, check the module's documentation to see if it's available and what properties it contains. You can also check type-hinting in your IDE to see what properties are available.
+:::
+
+## `override`
+
+While `extend` allows you to create a new method, `override` allows you to change the behavior of the existing method.
+
+:::tip
+These methods are affected by interceptors
+Like the built-in SDK methods, methods in `override` are impacted by your interceptors.
+:::
+
+```ts
+export const sapccExtension = {
+  override: {
+    getProducts: (params: any) => {
+      // Override the getProducts method
+    },
+  },
+};
+```
+
+It might be useful when you want to change the behavior of the existing method, like adding a new parameter or changing the default behavior.
+
+## `subscribers`
+
+Subscribers are functions that are called when a specific event is emitted.
+
+Events that can be emitted are:
+
+- `*_before` - run the function before EACH method of EACH module,
+- `*_after` - run the function after EACH method of EACH module,
+- `<module>_before` - run the function before EACH method of the specific module,
+- `<module>_after` - run the function after EACH method of the specific module,
+- `<module>_<method>_before` - run the function before the specific method of the specific module,
+- `<module>_<method>_after` - run the function after the specific method of the specific module.
+
+It implements the [publish-subscribe](https://www.enjoyalgorithms.com/blog/publisher-subscriber-pattern) pattern.
+
+It's a great place to add some custom logic, like logging or analytics.
+
+```ts
+export const sapccExtension = {
+  subscribers: {
+    sapcc_before: () => {
+      console.log(`Before each SAPCC method do something`);
+    },
+    sapcc_after: () => {
+      console.log(`After each SAPCC method do something`);
+    },
+  },
+};
+```

From ad22979e43554ad866188b402498187651bc6f7f Mon Sep 17 00:00:00 2001
From: Wojciech Sikora <wsikora@vuestorefront.io>
Date: Fri, 15 Mar 2024 15:51:55 +0100
Subject: [PATCH 05/17] update overview docs

---
 docs/content/4.sdk/1.index.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/content/4.sdk/1.index.md b/docs/content/4.sdk/1.index.md
index c9f91cf1ff..7e456effd4 100644
--- a/docs/content/4.sdk/1.index.md
+++ b/docs/content/4.sdk/1.index.md
@@ -27,9 +27,9 @@ By utilizing the Vue Storefront SDK, you can establish a type-safe contract betw
 The SDK has two components:
 
 1. The SDK Core - the core package, `@vue-storefront/sdk`, that initializes all modules and implements the plug-in architecture
-2. Modules - pluggable pieces of code as standalone packages that integrate into the core to add functionality (eg.: `@vsf-enterprise/sapcc-sdk`)
+2. Modules - pluggable pieces of code as standalone packages that integrate into the core to add functionality (eg.: `middlewareModule`)
 
-In most cases, these modules will come through our [Integrations](/integrations) - which contain both an SDK Module and an API Client (Middleware) - but you can also create your own modules.
+In most cases, you would use `middlewareModule` with different configurations - but you can also create your own modules.
 
 :card{to="/integrations" title="Integrations" description="See all of the available integrations that you can use with the SDK" icon="fluent:puzzle-cube-piece-20-filled"}
 

From bab20c6e5047d19a275019f07a0d0db460f1b9ad Mon Sep 17 00:00:00 2001
From: Wojciech Sikora <wsikora@vuestorefront.io>
Date: Fri, 15 Mar 2024 16:03:23 +0100
Subject: [PATCH 06/17] modify the api client guide and remove the sdk one

---
 .../2.guides/7.api-client.md}                 | 143 +++++++------
 .../5.integrations/3.custom/4.sdk-module.md   | 192 ------------------
 2 files changed, 78 insertions(+), 257 deletions(-)
 rename docs/content/{5.integrations/3.custom/3.api-client.md => 3.middleware/2.guides/7.api-client.md} (63%)
 delete mode 100644 docs/content/5.integrations/3.custom/4.sdk-module.md

diff --git a/docs/content/5.integrations/3.custom/3.api-client.md b/docs/content/3.middleware/2.guides/7.api-client.md
similarity index 63%
rename from docs/content/5.integrations/3.custom/3.api-client.md
rename to docs/content/3.middleware/2.guides/7.api-client.md
index 840ce14ecd..67736e5cdc 100644
--- a/docs/content/5.integrations/3.custom/3.api-client.md
+++ b/docs/content/3.middleware/2.guides/7.api-client.md
@@ -1,7 +1,5 @@
 # Creating an API Client
 
-
-
 The API client is used by the server middleware to create a server-to-server communication with your custom backend.
 
 ## Creating the integration client
@@ -12,7 +10,7 @@ First, you should create the `index.server.ts` file. It will be the entry point
 
 ```ts
 // index.server.ts
-import { apiClientFactory } from '@vue-storefront/middleware';
+import { apiClientFactory } from "@vue-storefront/middleware";
 
 const onCreate = (settings: any) => {
   // TODO: create a client here and return it with the integration configuration
@@ -32,7 +30,7 @@ The `onCreate` function is called when the server middleware is initialized. It
 
 The `api` object is a set of functions that will be available in the integration client.
 
-Now, let's create the client. 
+Now, let's create the client.
 
 :::tip
 In the following example we used the `axios` library to create a client. However, you can use any client that you suits your needs.
@@ -57,9 +55,9 @@ You should use the `MiddlewareConfig` interface in the `onCreate` function.
 
 ```ts
 // index.server.ts
-import { apiClientFactory } from '@vue-storefront/middleware';
-import axios from 'axios';
-import { MiddlewareConfig } from './types/config';
+import { apiClientFactory } from "@vue-storefront/middleware";
+import axios from "axios";
+import { MiddlewareConfig } from "./types/config";
 
 const buildClient = () => {
   const axiosInstance = axios.create();
@@ -87,16 +85,11 @@ The server middleware can be initialized now, but it does not contain any API fu
 
 ```ts
 // types/context/index.ts
-import { IntegrationContext } from '@vue-storefront/middleware';
-import { AxiosInstance } from 'axios';
-import { MiddlewareConfig } from '../config';
+import { IntegrationContext } from "@vue-storefront/middleware";
+import { AxiosInstance } from "axios";
+import { MiddlewareConfig } from "../config";
 
-/**
- * All available API Endpoints without first argument - `context`, because this prop is set automatically.
- */
-export type ContextualizedEndpoints = {
-  [T in keyof Endpoints]: Endpoints[T] extends (x: any, ...args: infer P) => infer R ? (...args: P) => R : never;
-};
+export type TODO = any;
 
 /**
  * Runtime integration context, which includes API client instance, settings, and endpoints that will be passed via middleware server.
@@ -105,71 +98,89 @@ export type ContextualizedEndpoints = {
 export type MyIntegrationIntegrationContext = IntegrationContext<
   AxiosInstance, // HTTP client instance
   MiddlewareConfig,
-  ContextualizedEndpoints
+  TODO
 >;
-
-/**
- * Global context of the application which includes runtime integration context.
- **/
-export interface Context {
-  // This property is named `myIntegration`, but you should use your integration name in here.
-  $myIntegration: MyIntegrationIntegrationContext;
-}
 ```
 
-The `ContextualizedEndpoints` type is a set of API functions without the `context` argument. It's necessary for the `IntegrationContext` type. It also requires the type of client used in the integration and the type of integration configuration.
+Now, you can create the first API method - an `exampleEndpoint` function.
+
+```ts
+// api/exampleEndpoint/index.ts
+import { MyIntegrationIntegrationContext, TODO } from "../../types";
+
+export const exampleEndpoint = async (
+  context: MyIntegrationIntegrationContext,
+  params: TODO
+) => {
+  console.log("exampleEndpoint has been called");
 
-The `Context` type is the global context of the application. It's used by api-client methods to access the integration client and the configuration.
+  // Example request could look like this:
+  // return await context.client.get(`example-url?id=${params.id}`);
+  return Promise.resolve({ success: true });
+};
+```
 
-Now you can add the interface for the API functions.
+You should also export the `exampleEndpoint` function in the `api/index.ts` file.
 
 ```ts
-// types/api/index.ts
-import { MyIntegrationContext } from '../config';
+// api/index.ts
+export * from "./exampleEndpoint";
+```
 
-type TODO = any;
+Then, let's create the `Endpoints` type.
 
-/**
- * Definition of all API-client methods available in {@link https://docs.vuestorefront.io/v2/advanced/context.html#context-api | context}.
- */
-export interface Endpoints {
-  /**
-   * Here you can find an example endpoint definition. Based on this example, you should define how your endpoint will look like.
-   * This description will appear in the API extractor, so try to document all endpoints added here.
-   */
-  exampleEndpoint: (context: MyIntegrationContext, params: TODO) => Promise<TODO>;
-}
+```ts
+// types/api/endpoints.ts
+import { WithoutContext } from "@vue-storefront/middleware";
+import * as api from "../../api";
+
+export type Endpoints = WithoutContext<typeof api>;
 ```
 
-Finally, you can create the `exampleEndpoint` function.
+Notice that we use the `WithoutContext` type from the `@vue-storefront/middleware` package. It's a utility type that removes the `context` parameter from the API functions.
+`context` is only used in the server middleware, so it should not be included in the final interface.
+
+Finally, let's add the `Endpoints` type to the `MyIntegrationIntegrationContext` interface.
 
 ```ts
-// api/exampleEndpoint/index.ts
-import { Endpoints } from '../../types';
+// types/context/index.ts
+import { IntegrationContext } from "@vue-storefront/middleware";
+import { AxiosInstance } from "axios";
+import { MiddlewareConfig } from "../config";
+import { Endpoints } from "../api/endpoints";
 
-export const exampleEndpoint: Endpoints['exampleEndpoint'] = async (context, params) => {
-  console.log('exampleEndpoint has been called');
+export type TODO = any;
 
-  // Example request could look like this:
-  // return await context.client.get(`example-url?id=${params.id}`);
-  return Promise.resolve({ success: true });
-};
+export type MyIntegrationIntegrationContext = IntegrationContext<
+  AxiosInstance, // HTTP client instance
+  MiddlewareConfig,
+  Endpoints
+>;
 ```
 
-You should also export the `exampleEndpoint` function in the `api/index.ts` file.
+Remember to export all the types in the `types/index.ts` file.
 
 ```ts
-// api/index.ts
-export * from './exampleEndpoint';
+// types/index.ts
+export * from "./config";
+export * from "./context";
+export * from "./api/endpoints";
+```
+
+And from `index.ts` as well.
+
+```ts
+// index.ts
+export * from "./types";
 ```
 
 To be able to call the `exampleEndpoint` function, you should add it to the `api` object in the `index.server.ts` file.
 
 ```ts
-import { apiClientFactory } from '@vue-storefront/middleware';
-import axios from 'axios';
-import * as api from './api';
-import { MiddlewareConfig } from './types/config';
+import { apiClientFactory } from "@vue-storefront/middleware";
+import axios from "axios";
+import * as api from "./api";
+import { MiddlewareConfig } from "./types/config";
 
 const buildClient = () => {
   const axiosInstance = axios.create();
@@ -207,7 +218,7 @@ This guide described the details of creating the integration, but it does not co
 module.exports = {
   integrations: {
     boilerplate: {
-      location: '@vsf-enterprise/my-integration-api/server', // This should be the path to your built index.server.js file
+      location: "@vsf-enterprise/my-integration-api/server", // This should be the path to your built index.server.js file
       configuration: {
         // Add your configuration here
       },
@@ -220,20 +231,22 @@ You can run the server middleware with this example script:
 
 ```js
 // server.js
-const { createServer } = require('@vue-storefront/middleware');
-const { integrations } = require('./middleware.config');
-const cors = require('cors');
+const { createServer } = require("@vue-storefront/middleware");
+const { integrations } = require("./middleware.config");
+const cors = require("cors");
 
 (async () => {
   const app = await createServer({ integrations });
-  const host = process.argv[2] ?? '0.0.0.0';
+  const host = process.argv[2] ?? "0.0.0.0";
   const port = process.argv[3] ?? 8181;
-  const CORS_MIDDLEWARE_NAME = 'corsMiddleware';
+  const CORS_MIDDLEWARE_NAME = "corsMiddleware";
 
-  const corsMiddleware = app._router.stack.find((middleware) => middleware.name === CORS_MIDDLEWARE_NAME);
+  const corsMiddleware = app._router.stack.find(
+    (middleware) => middleware.name === CORS_MIDDLEWARE_NAME
+  );
 
   corsMiddleware.handle = cors({
-    origin: ['http://localhost:3000'],
+    origin: ["http://localhost:3000"],
     credentials: true,
   });
 
diff --git a/docs/content/5.integrations/3.custom/4.sdk-module.md b/docs/content/5.integrations/3.custom/4.sdk-module.md
deleted file mode 100644
index 6911c55bd5..0000000000
--- a/docs/content/5.integrations/3.custom/4.sdk-module.md
+++ /dev/null
@@ -1,192 +0,0 @@
-# Creating a SDK module
-
-Each integration needs an SDK Module to allow storefronts to communicate with the API Client.
-
-## Creating the integration SDK module
-
-To start creating the SDK module, create a new folder called `sdk` in the `src` folder of your integration. This package will contain your integration SDK module.
-
-First, you should create the `index.ts` file. It will be the entry point for the SDK module. It should look like this:
-
-```ts
-// index.ts
-export const myIntegrationModule = (options: any) => ({
-  // TODO: create a module here
-});
-```
-
-Think of the `options` object as a set of configuration options for your integration. It can contain the `apiUrl` or any other information that you need to configure the module.
-
-```ts
-// types/options.ts
-
-export interface Options {
-  apiUrl: string;
-}
-```
-
-Once you have the Options interface defined, you can use it in the `index.ts` file:
-
-```ts
-// index.ts
-import { Options } from './types/options';
-
-export const myIntegrationModule = (options: Options) => ({
-  // TODO: create a module here
-});
-```
-
-Now, let's verify what `myIntegrationModule` should return. To help with that, we've created a `Module` interface that you can use and extend:
-
-```ts
-// index.ts
-import { Module } from '@vue-storefront/sdk';
-import { Options } from './types/options';
-
-interface MyIntegrationModule extends Module {}
-
-export const myIntegrationModule = (options: Options): MyIntegrationModule => ({
-  connector: {},
-  utils: {},
-  subscribers: {},
-});
-```
-
-In the example, we're going to create a connector that will call the `exampleEndpoint` prepared in the [Creating an API Client](./api-client.md) section.
-To do that, we need a connector. A connector is a set of functions that will be available in the frontend application. It's a communication layer between the frontend application and the API client.
-
-```ts
-// connector.ts
-import { Options } from './types/options';
-
-export const myIntegrationConnector = (options: Options) => {
-  return {}; // Connector methods
-};
-```
-
-A connector should return a set of methods, and each method should use a configured client to call the server middleware. In this example we're going to use `axios` to call the `exampleEndpoint`:
-
-```ts
-// client/index.ts
-import axios from './axios';
-
-const client = axios.create();
-
-export { client };
-```
-
-The client should be configured when the connector is initialized:
-
-```ts
-// connector.ts
-import { client } from './client';
-import { Options } from './types/options';
-
-export const myIntegrationConnector = (options: Options) => {
-  client.defaults.baseURL = options.apiUrl;
-  return {}; // Connector methods
-};
-```
-
-Now, let's create a method that will call the `exampleEndpoint`:
-
-```ts
-// methods/exampleMethod.ts
-import { client } from '../client';
-
-export const exampleMethod = async (params: any) => {
-  const response = await client.get('/exampleEndpoint', { params });
-  return response.data;
-};
-```
-
-Let's also export the method from `methods/index.ts` file:
-
-```ts
-// methods/index.ts
-export { exampleMethod } from './exampleMethod';
-```
-
-Now, you can import the method in the connector and return it:
-
-```ts
-// connector.ts
-import { client } from './client';
-import * as methods from './methods';
-import { Options } from './types/options';
-
-export const myIntegrationConnector = (options: Options) => {
-  client.defaults.baseURL = options.apiUrl;
-  return methods;
-};
-```
-
-The connector is ready. You can import it in the `index.ts` file and return it in the `myIntegrationModule` function:
-
-```ts
-// index.ts
-import { Module } from '@vue-storefront/sdk';
-import { myIntegrationConnector } from './connector';
-import { Options } from './types/options';
-
-interface MyIntegrationModule extends Module {
-  connector: ReturnType<typeof myIntegrationConnector>;
-}
-
-export const myIntegrationModule = (options: Options): MyIntegrationModule => ({
-  connector: myIntegrationConnector(options),
-  utils: {},
-  subscribers: {},
-});
-```
-
-Last but not least, you should also export the `client` to allow extending the module:
-
-```ts
-// index.ts
-import { Module } from '@vue-storefront/sdk';
-import { myIntegrationConnector } from './connector';
-import { Options } from './types/options';
-
-interface MyIntegrationModule extends Module {
-  connector: ReturnType<typeof myIntegrationConnector>;
-}
-
-export const myIntegrationModule = (options: Options): MyIntegrationModule => ({
-  connector: myIntegrationConnector(options),
-  utils: {},
-  subscribers: {},
-});
-
-export { client } from './client';
-```
-
-Your integration SDK module is ready to use.
-
-## Using the module
-
-:::warning Building your integration module
-This guide described the details of creating the integration module, but it does not cover the details of the building process. You can find the tools and configuration we're using by default in our integrations in our [integration boilerplate repository](https://github.com/vuestorefront/integration-boilerplate)
-:::
-
-When your integration SDK module is ready, you can use it in the front-end application. To do that, you need to import the module in the `sdk.config.ts` file:
-
-```ts
-// sdk.config.ts
-import { myIntegrationModule, MyIntegrationModule } from '@vsf-enterprise/my-integration-sdk';
-import { initSDK, buildModule } from '@vsf-enterprise/sdk';
-
-const sdkConfig = {
-  myIntegration: buildModule<MyIntegrationModule>(myIntegrationModule, {
-    apiUrl: 'http://localhost:8181/myIntegration',
-  }),
-};
-
-export const sdk = initSDK<typeof sdkConfig>(sdkConfig);
-```
-
-The `exampleMethod` is ready to be used in your components:
-
-```ts
-await sdk.myIntegration.exampleMethod({ param: 'value' });
-```

From b6b5126c65d030170a0616662107e02432e4dfb8 Mon Sep 17 00:00:00 2001
From: Wojciech Sikora <wsikora@vuestorefront.io>
Date: Fri, 15 Mar 2024 21:08:07 +0100
Subject: [PATCH 07/17] Add a guide for custom SDK modules

---
 .../4.sdk/3.advanced/3.custom-modules.md      | 162 +++++++++++++++++-
 1 file changed, 161 insertions(+), 1 deletion(-)

diff --git a/docs/content/4.sdk/3.advanced/3.custom-modules.md b/docs/content/4.sdk/3.advanced/3.custom-modules.md
index 1b496611c4..39e44ca86b 100644
--- a/docs/content/4.sdk/3.advanced/3.custom-modules.md
+++ b/docs/content/4.sdk/3.advanced/3.custom-modules.md
@@ -1,14 +1,174 @@
 # Custom modules
 
 ::: tip When custom module is necessary?
+Many times, the default `middlewareModule` is enough to handle the communication with the Server Middleware. You can achieve even custom and extended logic of the endpoints by extending the module. However, you may need to create a module that is not communicating with the Server Middleware at all. For example, you may need to create a logger module, or a module that is communicating with a third-party service directly. In this case, a custom module is the way to go.
 :::
 
 ## Module
 
+Let's start with the module itself. The module is a function that implements the `Module` interface.
+Create a new file `module.ts` and add the following code:
+
+```typescript
+import { Module } from "@vue-storefront/sdk";
+
+const loggerModule = () => {
+  return {
+    connector: {},
+    utils: {},
+    subscribers: {},
+  } satisfies Module;
+};
+```
+
+The `connector`, `utils`, and `subscribers` are the parts of the module. The `connector` is the part that is responsible for the module's methods. The `utils` are the helper functions that can be used in the module. The `subscribers` are the functions that are called when the event is emitted.
+
 ## Connector
 
+The connector is the part of the module that is responsible for the module's methods. The connector is an object that contains the methods.
+
+```typescript [module.ts]
+import { Module } from "@vue-storefront/sdk";
+
+const loggerModule = () => {
+  return {
+    connector: {
+      log: (message: string) => {
+        console.log(message);
+      },
+    },
+    utils: {},
+    subscribers: {},
+  } satisfies Module;
+};
+```
+
+You can also separate the connector into a separate file. Create a new file `connector.ts` and add the following code:
+
+```typescript [connector.ts]
+import { Connector } from "@vue-storefront/sdk";
+
+const loggerConnector = () => {
+  return {
+    log: (message: string) => {
+      console.log(message);
+    },
+  } satisfies Connector;
+};
+```
+
+Now, the logger connector is in a separate file and can be used in the module.
+
+```typescript [module.ts]
+import { Module } from "@vue-storefront/sdk";
+import { loggerConnector } from "./connector";
+
+const loggerModule = () => {
+  return {
+    connector: loggerConnector(),
+    utils: {},
+    subscribers: {},
+  } satisfies Module;
+};
+```
+
 ## Methods
 
+To keep the connector clean, you can separate the methods into a separate file. Create a new file `methods.ts` and add the following code:
+
+```typescript [methods.ts]
+export const log = (message: string) => {
+  console.log(message);
+};
+```
+
+Now, you can use the `log` method in the connector.
+
+```typescript [connector.ts]
+import { Connector } from "@vue-storefront/sdk";
+import * as methods from "./methods";
+
+const loggerConnector = () => {
+  return {
+    ...methods,
+  } satisfies Connector;
+};
+```
+
+Let's also make the methods more complex by extending their functionality. Let's assume that we want to log the message to the server as well.
+
+```typescript [methods.ts]
+export const log = (message: string) => {
+  console.log(message);
+  fetch("https://example.com/log", {
+    method: "POST",
+    body: JSON.stringify({ message }),
+  });
+};
+```
+
+Now, the `log` method is logging the message to the console and sending it to the server.
+
 ## Utils
 
-## Subscribers
\ No newline at end of file
+Utils are the helper functions that can be helpful when working with the module. For example, you can create a helper function that is adding a timestamp.
+
+```typescript [module.ts]
+import { Module } from "@vue-storefront/sdk";
+import { loggerConnector } from "./connector";
+
+const loggerModule = () => {
+  return {
+    connector: loggerConnector(),
+    utils: {
+      formatMessage: (message: string) => {
+        return `${new Date().toISOString()} - ${message}`;
+      },
+    },
+    subscribers: {},
+  } satisfies Module;
+};
+```
+
+## Subscribers
+
+Subscribers are the functions that are called when the event is emitted. For example, you can create a subscriber that is logging the message to the server.
+
+```typescript [module.ts]
+import { Module } from "@vue-storefront/sdk";
+import { loggerConnector } from "./connector";
+
+const loggerModule = () => {
+  return {
+    connector: loggerConnector(),
+    utils: {
+      formatMessage: (message: string) => {
+        return `${new Date().toISOString()} - ${message}`;
+      },
+    },
+    subscribers: {
+      "*_after": (payload) => {
+        fetch("https://example.com/log", {
+          method: "POST",
+          body: JSON.stringify(payload),
+        });
+      },
+    },
+  } satisfies Module;
+};
+```
+
+Now, the subscriber is logging the payload to the server after every method call of every SDK module.
+
+Finally, you can use the module in your application.
+
+```typescript
+import { initSdk, buildModule } from "@vue-storefront/sdk";
+import { loggerModule } from "./module";
+
+const sdk = initSdk({
+  logger: buildModule(loggerModule),
+});
+
+sdk.logger.log("Hello, World!"); // 2021-01-01T00:00:00.000Z - Hello, World!
+```

From 604f35845ea43059a221b117a24c06096364824f Mon Sep 17 00:00:00 2001
From: Wojciech Sikora <wsikora@vuestorefront.io>
Date: Fri, 15 Mar 2024 21:15:21 +0100
Subject: [PATCH 08/17] Update docs

---
 docs/content/4.sdk/2.getting-started/1.index.md   | 6 +++---
 docs/content/4.sdk/3.advanced/3.custom-modules.md | 4 +++-
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/docs/content/4.sdk/2.getting-started/1.index.md b/docs/content/4.sdk/2.getting-started/1.index.md
index c5330e8bd5..3f66d75c6c 100644
--- a/docs/content/4.sdk/2.getting-started/1.index.md
+++ b/docs/content/4.sdk/2.getting-started/1.index.md
@@ -452,10 +452,10 @@ That's it! You can now use VueStorefront SDK Module in any JavaScript app ✨
 #section-1
 :card{to="/sdk/advanced/extending-module" title="Extending the SDK" description="Learn how to customize, override, or extend any default functionality in the SDK" icon="ri:terminal-box-fill"}
 #section-2
-:card{to="/middleware" title="Middleware Docs" description="Understand more about Vue Storefront Middleware" icon="fa6-solid:layer-group"}
+:card{to="/sdk/advanced/middleware-module" title="The middlewareModule" description="Understand how to use the default SDK module" icon="fa6-solid:layer-group"}
 #section-3
-:card{to="/integrations" title="View all Integrations" description="View our ready-to-use integrations for popular e-commerce services" icon="fluent:puzzle-cube-piece-20-filled"}
+:card{to="/sdk/advanced/custom-modules" title="Create a custom SDK module" description="Create your own custom SDK module" icon="fluent:puzzle-cube-piece-20-filled"}
 #section-4
-:card{to="/integrations/custom/quick-start" title="Building Custom Integrations" description="Connect to your unique third-party services with custom integrations" icon="gridicons:customize"}
+:card{to="/integrations" title="View all Integrations" description="View our ready-to-use integrations for popular e-commerce services" icon="fluent:puzzle-cube-piece-20-filled"}
 
 ::
diff --git a/docs/content/4.sdk/3.advanced/3.custom-modules.md b/docs/content/4.sdk/3.advanced/3.custom-modules.md
index 39e44ca86b..6714e40dd8 100644
--- a/docs/content/4.sdk/3.advanced/3.custom-modules.md
+++ b/docs/content/4.sdk/3.advanced/3.custom-modules.md
@@ -1,7 +1,9 @@
 # Custom modules
 
 ::: tip When custom module is necessary?
-Many times, the default `middlewareModule` is enough to handle the communication with the Server Middleware. You can achieve even custom and extended logic of the endpoints by extending the module. However, you may need to create a module that is not communicating with the Server Middleware at all. For example, you may need to create a logger module, or a module that is communicating with a third-party service directly. In this case, a custom module is the way to go.
+Many times, the default `middlewareModule` is enough to handle the communication with the Server Middleware. You can achieve even custom and extended logic of the endpoints by [extending the module](sdk/advanced/extending-module). 
+
+However, you may need to create a module that is not communicating with the Server Middleware at all. For example, a logger module, or a module that is communicating with a third-party service directly and needs to run on the frontend. In this case, a custom module is the way to go.
 :::
 
 ## Module

From ba85354f9d9f469ebe1838849abfa499efa42c1e Mon Sep 17 00:00:00 2001
From: Wojciech Sikora <wsikora@vuestorefront.io>
Date: Fri, 15 Mar 2024 21:25:13 +0100
Subject: [PATCH 09/17] add additional example to middleware module

---
 .../4.sdk/3.advanced/1.middleware-module.md   | 34 +++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/docs/content/4.sdk/3.advanced/1.middleware-module.md b/docs/content/4.sdk/3.advanced/1.middleware-module.md
index a621b3ff27..cdb76addae 100644
--- a/docs/content/4.sdk/3.advanced/1.middleware-module.md
+++ b/docs/content/4.sdk/3.advanced/1.middleware-module.md
@@ -401,3 +401,37 @@ export const getServerSideProps: GetServerSideProps = async ({ req }) => {
   };
 };
 ```
+
+### Use the `middlewareModule` with a custom integration
+
+You can use the `middlewareModule` with a custom integration by providing a type definition of the endpoints.
+
+This example assumes that you have a custom Api Client that has been implemented as described in the [Creating an API Client](/middleware/guides/api-client) guide. It also assumes that the integration has been added to the `middleware.config.ts` and it's available at the `/custom` endpoint.
+
+First, let's export the `Endpoints` type as `CustomEndpoints` from the custom integration package. 
+That way, you won't need to install the custom integration package on the frontend and you'll avoid naming conflicts.
+
+```ts [storefront-middleware/types.ts]
+export { Endpoints as CustomEndpoints } from "custom-integration-api-client";
+
+// ...
+```
+
+Then, let's initialize the SDK with the `middlewareModule` and the `CustomEndpoints` type.
+
+```ts
+import { initSDK, buildModule, middlewareModule } from "@vue-storefront/sdk";
+import { CustomEndpoints } from "storefront-middleware/types";
+
+export const sdk = initSDK({
+  custom: buildModule(middlewareModule<CustomEndpoints>, {
+    apiUrl: "http://localhost:8181/custom",
+  }),
+});
+```
+
+Now, you can use the `custom` module to make requests to the custom integration endpoints.
+
+```ts
+const result = await sdk.custom.someMethod({ id: "123" });
+```

From 8fbea1651c643f39a10dc0db96b3deab2afa9119 Mon Sep 17 00:00:00 2001
From: Wojciech Sikora <wsikora@vuestorefront.io>
Date: Fri, 15 Mar 2024 21:30:04 +0100
Subject: [PATCH 10/17] docs: update integration quick start

---
 .../5.integrations/3.custom/2.quick-start.md  | 28 +++++++++----------
 1 file changed, 13 insertions(+), 15 deletions(-)

diff --git a/docs/content/5.integrations/3.custom/2.quick-start.md b/docs/content/5.integrations/3.custom/2.quick-start.md
index 20ad9e8b35..2e0e01f426 100644
--- a/docs/content/5.integrations/3.custom/2.quick-start.md
+++ b/docs/content/5.integrations/3.custom/2.quick-start.md
@@ -8,14 +8,14 @@ This section covers how to create an integration SDK module. If you're looking f
 
 To help you scaffold a project, you can use our CLI to generate the boilerplate for your integration SDK module. To do that, run the following command:
 
-[//]: # (//TODO: add link to the boilerplate)
-```bash 
-npx @vue-storefront/cli create integration 
+[//]: # "//TODO: add link to the boilerplate"
+
+```bash
+npx @vue-storefront/cli create integration
 ```
 
 The CLI will ask you a few questions about your integration and generate the boilerplate for you.
 
-
 ### Running the application
 
 Let's run the application and see what we've got:
@@ -31,16 +31,16 @@ If you have any issues specific to this Boilerplate, please report them on the [
 But first, let's take a look at the boilerplate structure.
 
 ### Boilerplate structure
+
 :::tip
-To make things easier, we use a lerna mono-repo to manage the boilerplate. 
-It allows us to manage dependencies and publish packages more efficiently. 
-If you're unfamiliar with lerna, please check out the [lerna documentation](https://lerna.js.org/).
+To make things easier, we use a [Turborepo](https://turbo.build/) to manage the boilerplate.
+It allows us to manage dependencies and publish packages more efficiently.
+If you're unfamiliar with Turborepo, please check out the [documentation](https://turbo.build/repo/docs).
 :::
 
 - `packages/api-client` - contains the API client for your integration. It's a set of functions that will be used to communicate with the backend API.
-- `packages/sdk` - contains the SDK module for your integration. It's a set of functions that will be used to communicate with the API client from the frontend application.
 - `playground/app` - contains an application with the SDK module and API client already integrated. It's a great place to see your integration in action.
-   You choose the type of application you want to use as a playground during the boilerplate generation process.
+  You choose the type of application you want to use as a playground during the boilerplate generation process.
 - `playground/middleware` - contains a middleware that will communicate with the api-client.
 
 ### Creating a new Endpoint
@@ -48,25 +48,23 @@ If you're unfamiliar with lerna, please check out the [lerna documentation](http
 Let's create a new endpoint in the API client.
 
 ```bash
-npx @vue-storefront/cli add endpoint getProduct
+yarn vsf add endpoint getProduct
 ```
 
 Let's check out what's been generated for us:
 
 API Client:
+
 - `packages/api-client/src/api/getProduct/index.ts` - contains the `getProduct` endpoint.
 - `packages/api-client/src/api/index.ts` - contains the `getProduct` endpoint export.
 - `packages/api-client/src/types/api/endpoints.ts` - contains the `getProduct` endpoint exported interface method.
 
-SDK:
-- `packages/sdk/src/methods/getProduct/index.ts` - contains the `getProduct` SDK method.
-- `packages/sdk/src/methods/index.ts` - contains the `getProduct` SDK method export.
-
 Playground:
+
 - `playground/app/pages/index.vue` - contains the `getProduct` endpoint usage example.
 
 :::warning
-Be sure to rebuild the application before running it. Otherwise, the endpoint won't be available:
+App should rebuild after adding a new endpoint. If it doesn't, please rebuild the project and run the app again.
 :::
 
 ```bash

From 30415e76c980acfd1a9ff7610861b6bd8305ec03 Mon Sep 17 00:00:00 2001
From: Wojciech Sikora <35867383+WojtekTheWebDev@users.noreply.github.com>
Date: Thu, 21 Mar 2024 13:55:43 +0100
Subject: [PATCH 11/17] Apply suggestions from code review

Co-authored-by: Matt Maribojoc <mmaribojoc@vuestorefront.io>
---
 docs/content/4.sdk/3.advanced/3.custom-modules.md     | 6 +++---
 docs/content/5.integrations/3.custom/2.quick-start.md | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/content/4.sdk/3.advanced/3.custom-modules.md b/docs/content/4.sdk/3.advanced/3.custom-modules.md
index 6714e40dd8..d637b00456 100644
--- a/docs/content/4.sdk/3.advanced/3.custom-modules.md
+++ b/docs/content/4.sdk/3.advanced/3.custom-modules.md
@@ -1,9 +1,9 @@
 # Custom modules
 
-::: tip When custom module is necessary?
-Many times, the default `middlewareModule` is enough to handle the communication with the Server Middleware. You can achieve even custom and extended logic of the endpoints by [extending the module](sdk/advanced/extending-module). 
+::: tip When is a custom module necessary?
+Many times, the default `middlewareModule` is enough to handle the communication with the Server Middleware. You can achieve customizing the behavior and logic of the endpoints by [extending the module](sdk/advanced/extending-module). 
 
-However, you may need to create a module that is not communicating with the Server Middleware at all. For example, a logger module, or a module that is communicating with a third-party service directly and needs to run on the frontend. In this case, a custom module is the way to go.
+However, you may need to create a module that doesn't communicate with the Server Middleware at all. For example, a logger module, or a module that is communicating with a third-party service directly and needs to run on the frontend. In this case, a custom module is the way to go.
 :::
 
 ## Module
diff --git a/docs/content/5.integrations/3.custom/2.quick-start.md b/docs/content/5.integrations/3.custom/2.quick-start.md
index 2e0e01f426..a8964125e2 100644
--- a/docs/content/5.integrations/3.custom/2.quick-start.md
+++ b/docs/content/5.integrations/3.custom/2.quick-start.md
@@ -64,7 +64,7 @@ Playground:
 - `playground/app/pages/index.vue` - contains the `getProduct` endpoint usage example.
 
 :::warning
-App should rebuild after adding a new endpoint. If it doesn't, please rebuild the project and run the app again.
+The app should rebuild after adding a new endpoint. If it doesn't, please rebuild the project and run the app again.
 :::
 
 ```bash

From 1e0a06423a7a2bca7639f417534f8462bd73d579 Mon Sep 17 00:00:00 2001
From: Wojciech Sikora <wsikora@vuestorefront.io>
Date: Thu, 21 Mar 2024 14:55:16 +0100
Subject: [PATCH 12/17] Remove context section from orchestration docs

---
 .../3.middleware/2.guides/4.orchestration.md  | 33 +------------------
 1 file changed, 1 insertion(+), 32 deletions(-)

diff --git a/docs/content/3.middleware/2.guides/4.orchestration.md b/docs/content/3.middleware/2.guides/4.orchestration.md
index b3d474aff2..dd21942ae9 100644
--- a/docs/content/3.middleware/2.guides/4.orchestration.md
+++ b/docs/content/3.middleware/2.guides/4.orchestration.md
@@ -27,7 +27,7 @@ The `getApiClient` method takes a single argument, which is the key of the api c
 
 Here's a basic example of what this might look like:
 
-```javascript
+```typescript
 export const integrations = {
   sapcc: {
     location: "@vsf-enterprise/sapcc-api/server",
@@ -204,37 +204,6 @@ import {
 } from "@vsf-enterprise/sapcc-api";
 ```
 
-### Endpoints and the `context` object
-
-Each method of the integration api client contains the `context` object as the first argument. However, the `context` is not something that is passed by the developer to the method during the call. This is because the `context` is passed automatically by the `@vue-storefront/middleware` package logic. Because of this, the `context` object should be excluded from the `Api` interface passed to the `ApiClient` type.
-
-To achieve that, the `@vue-storefront/middleware` export the interface `ContextualizedApi`, which basically removes the context from the API.
-
-### Example
-
-Let's take a look at the `sapcc` integration. The `sapcc` integration exports the following types:
-
-```typescript
-import {
-  Endpoints,
-  MiddlewareConfig,
-  AxiosInstance,
-} from "@vsf-enterprise/sapcc-api";
-import { ContextualizedApi } from "@vue-storefront/middleware";
-
-// ...
-
-const sapcc = context.getApiClient<
-  ContextualizedApi<Endpoints>,
-  MiddlewareConfig,
-  AxiosInstance
->("sapcc");
-
-// sapcc.api now is aware of the SAPCC methods that are not expecting the `context` object
-// sapcc.config is now aware of the SAPCC configuration object
-// sapcc.client is now aware of the SAPCC HTTP client object
-```
-
 :::tip Type of endpoints
 Sometimes, the `Endpoints` type is not exported by the integration. If that's the case, you can import the `XyzIntegrationContext` type from the integration package. For example, the `sapcc` integration exports the `SapccIntegrationContext` type, which contains the endpoints type as `SapccIntegrationContext['api']`. It contains also the type of the configuration object as `SapccIntegrationContext['config']` and the type of the HTTP client object as `SapccIntegrationContext['client']`. This should be applied to all integrations.
 :::

From 43365bc67d41454e8b994fada963cfd0941314fb Mon Sep 17 00:00:00 2001
From: Wojciech Sikora <wsikora@vuestorefront.io>
Date: Thu, 21 Mar 2024 15:05:31 +0100
Subject: [PATCH 13/17] apply review suggestions

---
 .../content/3.middleware/2.guides/7.api-client.md | 12 +++++++-----
 docs/content/4.sdk/3.advanced/3.custom-modules.md | 15 ++++++++-------
 2 files changed, 15 insertions(+), 12 deletions(-)

diff --git a/docs/content/3.middleware/2.guides/7.api-client.md b/docs/content/3.middleware/2.guides/7.api-client.md
index 67736e5cdc..3230ee5531 100644
--- a/docs/content/3.middleware/2.guides/7.api-client.md
+++ b/docs/content/3.middleware/2.guides/7.api-client.md
@@ -132,13 +132,15 @@ Then, let's create the `Endpoints` type.
 ```ts
 // types/api/endpoints.ts
 import { WithoutContext } from "@vue-storefront/middleware";
-import * as api from "../../api";
+import * as apiMethods from "../../api";
 
-export type Endpoints = WithoutContext<typeof api>;
+export type ApiMethods = typeof apiMethods;
+
+export type Endpoints = WithoutContext<ApiMethods>;
 ```
 
-Notice that we use the `WithoutContext` type from the `@vue-storefront/middleware` package. It's a utility type that removes the `context` parameter from the API functions.
-`context` is only used in the server middleware, so it should not be included in the final interface.
+Notice that we use the `WithoutContext` type from the `@vue-storefront/middleware` package. It's a utility type that removes the `context` parameter from the API methods.
+Server Middleware creates the `context` object based on the middleware configuration and request that has been made. The `Endpoints` interface should reflect only the available API endpoints.
 
 Finally, let's add the `Endpoints` type to the `MyIntegrationIntegrationContext` interface.
 
@@ -152,7 +154,7 @@ import { Endpoints } from "../api/endpoints";
 export type TODO = any;
 
 export type MyIntegrationIntegrationContext = IntegrationContext<
-  AxiosInstance, // HTTP client instance
+  AxiosInstance, // HTTP client instance, you should use your client type here
   MiddlewareConfig,
   Endpoints
 >;
diff --git a/docs/content/4.sdk/3.advanced/3.custom-modules.md b/docs/content/4.sdk/3.advanced/3.custom-modules.md
index d637b00456..26140e596e 100644
--- a/docs/content/4.sdk/3.advanced/3.custom-modules.md
+++ b/docs/content/4.sdk/3.advanced/3.custom-modules.md
@@ -14,7 +14,7 @@ Create a new file `module.ts` and add the following code:
 ```typescript
 import { Module } from "@vue-storefront/sdk";
 
-const loggerModule = () => {
+export const loggerModule = () => {
   return {
     connector: {},
     utils: {},
@@ -32,7 +32,7 @@ The connector is the part of the module that is responsible for the module's met
 ```typescript [module.ts]
 import { Module } from "@vue-storefront/sdk";
 
-const loggerModule = () => {
+export const loggerModule = () => {
   return {
     connector: {
       log: (message: string) => {
@@ -50,7 +50,7 @@ You can also separate the connector into a separate file. Create a new file `con
 ```typescript [connector.ts]
 import { Connector } from "@vue-storefront/sdk";
 
-const loggerConnector = () => {
+export const loggerConnector = () => {
   return {
     log: (message: string) => {
       console.log(message);
@@ -65,7 +65,7 @@ Now, the logger connector is in a separate file and can be used in the module.
 import { Module } from "@vue-storefront/sdk";
 import { loggerConnector } from "./connector";
 
-const loggerModule = () => {
+export const loggerModule = () => {
   return {
     connector: loggerConnector(),
     utils: {},
@@ -90,7 +90,7 @@ Now, you can use the `log` method in the connector.
 import { Connector } from "@vue-storefront/sdk";
 import * as methods from "./methods";
 
-const loggerConnector = () => {
+export const loggerConnector = () => {
   return {
     ...methods,
   } satisfies Connector;
@@ -119,7 +119,7 @@ Utils are the helper functions that can be helpful when working with the module.
 import { Module } from "@vue-storefront/sdk";
 import { loggerConnector } from "./connector";
 
-const loggerModule = () => {
+export const loggerModule = () => {
   return {
     connector: loggerConnector(),
     utils: {
@@ -135,12 +135,13 @@ const loggerModule = () => {
 ## Subscribers
 
 Subscribers are the functions that are called when the event is emitted. For example, you can create a subscriber that is logging the message to the server.
+You can learn more about the subscribers in the [Subscribers](/sdk/advanced/extending-module#subscribers) docs.
 
 ```typescript [module.ts]
 import { Module } from "@vue-storefront/sdk";
 import { loggerConnector } from "./connector";
 
-const loggerModule = () => {
+export const loggerModule = () => {
   return {
     connector: loggerConnector(),
     utils: {

From 118f77174f7d01f50fa57d0a3bacfc4d9ce48b94 Mon Sep 17 00:00:00 2001
From: Wojciech Sikora <wsikora@vuestorefront.io>
Date: Thu, 21 Mar 2024 15:23:59 +0100
Subject: [PATCH 14/17] Add a guide for csr cookies

---
 .../4.sdk/2.getting-started/1.index.md        | 10 +++++-
 .../2.middleware-module.md}                   | 36 ++++++++++++++++++-
 ...ending-module.md => 1.extending-module.md} |  0
 ....custom-modules.md => 2.custom-modules.md} |  0
 4 files changed, 44 insertions(+), 2 deletions(-)
 rename docs/content/4.sdk/{3.advanced/1.middleware-module.md => 2.getting-started/2.middleware-module.md} (93%)
 rename docs/content/4.sdk/3.advanced/{2.extending-module.md => 1.extending-module.md} (100%)
 rename docs/content/4.sdk/3.advanced/{3.custom-modules.md => 2.custom-modules.md} (100%)

diff --git a/docs/content/4.sdk/2.getting-started/1.index.md b/docs/content/4.sdk/2.getting-started/1.index.md
index 3f66d75c6c..9b5d4f6e6a 100644
--- a/docs/content/4.sdk/2.getting-started/1.index.md
+++ b/docs/content/4.sdk/2.getting-started/1.index.md
@@ -77,7 +77,15 @@ Let's break down the code above:
 
 - The `middlewareModule` is an SDK module that ensures communication with the Server Middleware. It takes the `UnifiedEndpoints` type as a generic parameter. The `UnifiedEndpoints` type is a type that represents the endpoints of the Server Middleware.
 
-- The `getRequestHeaders` function is used to retrieve the `Cookie` header with cookie values.
+- The `getRequestHeaders` function is used to provide the incoming headers within your requests. You can use `getRequestHeaders` to access and proxy the initial cookie headers to SDK requests during SSR. Initial headers could be provided by the [`getSdk`](#getsdk) method.
+  Check out examples there:
+  - Next Pages Router [link](https://github.com/vuestorefront/vue-storefront/tree/main/packages/storefront/packages/next/__tests__/apps/pages-router)
+  - Next App Router [link](https://github.com/vuestorefront/vue-storefront/tree/main/packages/storefront/packages/next/__tests__/apps/app-router)
+  - Nuxt app [link](https://github.com/vuestorefront/vue-storefront/tree/main/packages/storefront/packages/nuxt/__tests__/app)
+
+::info
+In the browser, `getRequestHeaders` will return an empty object.
+::
 
 - The `createSdk` function returns the `getSdk` function, which is used to retreive the new SDK instance.
 
diff --git a/docs/content/4.sdk/3.advanced/1.middleware-module.md b/docs/content/4.sdk/2.getting-started/2.middleware-module.md
similarity index 93%
rename from docs/content/4.sdk/3.advanced/1.middleware-module.md
rename to docs/content/4.sdk/2.getting-started/2.middleware-module.md
index cdb76addae..a29559b4c1 100644
--- a/docs/content/4.sdk/3.advanced/1.middleware-module.md
+++ b/docs/content/4.sdk/2.getting-started/2.middleware-module.md
@@ -402,13 +402,47 @@ export const getServerSideProps: GetServerSideProps = async ({ req }) => {
 };
 ```
 
+### Add cookies to the request during CSR
+
+Cookies are being sent with the request during Client-Side Rendering by default.
+
+However, you can always specify the headers manually by passing them to the `defaultRequestConfig` option of the `middlewareModule`...
+
+```ts
+export const sdk = initSDK({
+  commerce: buildModule(middlewareModule<UnifiedEndpoints>, {
+    apiUrl: "http://localhost:8181/commerce",
+    defaultRequestConfig: {
+      headers: {
+        Cookie: "name=value",
+      },
+    },
+  }),
+});
+```
+
+...or by passing them to the request configuration.
+
+```ts
+import { prepareConfig } from "@vue-storefront/sdk";
+
+const product = await sdk.commerce.getProduct(
+  { id: "123" },
+  prepareConfig({
+    headers: {
+      Cookie: "name=value",
+    },
+  })
+);
+```
+
 ### Use the `middlewareModule` with a custom integration
 
 You can use the `middlewareModule` with a custom integration by providing a type definition of the endpoints.
 
 This example assumes that you have a custom Api Client that has been implemented as described in the [Creating an API Client](/middleware/guides/api-client) guide. It also assumes that the integration has been added to the `middleware.config.ts` and it's available at the `/custom` endpoint.
 
-First, let's export the `Endpoints` type as `CustomEndpoints` from the custom integration package. 
+First, let's export the `Endpoints` type as `CustomEndpoints` from the custom integration package.
 That way, you won't need to install the custom integration package on the frontend and you'll avoid naming conflicts.
 
 ```ts [storefront-middleware/types.ts]
diff --git a/docs/content/4.sdk/3.advanced/2.extending-module.md b/docs/content/4.sdk/3.advanced/1.extending-module.md
similarity index 100%
rename from docs/content/4.sdk/3.advanced/2.extending-module.md
rename to docs/content/4.sdk/3.advanced/1.extending-module.md
diff --git a/docs/content/4.sdk/3.advanced/3.custom-modules.md b/docs/content/4.sdk/3.advanced/2.custom-modules.md
similarity index 100%
rename from docs/content/4.sdk/3.advanced/3.custom-modules.md
rename to docs/content/4.sdk/3.advanced/2.custom-modules.md

From c5cdd50e324347beeb737e963102ad13b03c3ceb Mon Sep 17 00:00:00 2001
From: Wojciech Sikora <wsikora@vuestorefront.io>
Date: Thu, 21 Mar 2024 15:35:21 +0100
Subject: [PATCH 15/17] use new name

---
 docs/content/4.sdk/2.getting-started/1.index.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/content/4.sdk/2.getting-started/1.index.md b/docs/content/4.sdk/2.getting-started/1.index.md
index 142e6f2304..75b23a7f8f 100644
--- a/docs/content/4.sdk/2.getting-started/1.index.md
+++ b/docs/content/4.sdk/2.getting-started/1.index.md
@@ -1,6 +1,6 @@
 # Getting Started
 
-If you're setting your Vue Storefront application from scratch, you'll need to configure a type-safe SDK that communicates with your [Server Middleware](/middleware).
+If you're setting your Alokai application from scratch, you'll need to configure a type-safe SDK that communicates with your [Server Middleware](/middleware).
 
 There are various ways to configure the SDK, depending on your chosen framework. For Next.js and Nuxt, you can use the `@vue-storefront/next` and `@vue-storefront/nuxt` packages respectively. If you're looking for framework agnostic experience, you can use the `@vue-storefront/sdk` package.
 
@@ -32,7 +32,7 @@ To use SDK in our application, we need to initialize it first. To do so, follow
 1. Create SDK Config file - `sdk.config.ts` in the `sdk` directory.
 
 ::info
-It is not necessary to name the file `sdk.config.ts` specifically or to keep it in the `sdk` directory, but it is recommended to keep it consistent with the rest of the Vue Storefront project.
+It is not necessary to name the file `sdk.config.ts` specifically or to keep it in the `sdk` directory, but it is recommended to keep it consistent with the rest of the Alokai project.
 ::
 
 2. Create the SDK configuration by importing the `createSdk` function from the Next.js SDK and using the `middlewareModule` it provides. You should also import other modules you want to use.

From 4111a9d851cc2d566dc90145a6273b6424eb967d Mon Sep 17 00:00:00 2001
From: Wojciech Sikora <wsikora@vuestorefront.io>
Date: Fri, 29 Mar 2024 18:41:48 +0100
Subject: [PATCH 16/17] update orchestration guide

---
 .../3.middleware/2.guides/4.orchestration.md  | 225 ++++++++++++------
 1 file changed, 155 insertions(+), 70 deletions(-)

diff --git a/docs/content/3.middleware/2.guides/4.orchestration.md b/docs/content/3.middleware/2.guides/4.orchestration.md
index f9b21e2e8e..3a15f4c0be 100644
--- a/docs/content/3.middleware/2.guides/4.orchestration.md
+++ b/docs/content/3.middleware/2.guides/4.orchestration.md
@@ -7,6 +7,7 @@ Optimizing server requests through data integration and orchestration is essenti
 Data orchestration allows for consolidating multiple server requests into a single endpoint, which significantly eases the burden on the frontend. This is particularly beneficial in scenarios involving numerous simultaneous server requests.
 
 ### Advantages:
+
 - **Minimized Network Traffic**: Fewer server calls lead to reduced latency and enhanced responsiveness.
 - **Simplified Frontend Architecture**: By grouping related server requests, the frontend logic becomes less complex.
 - **Uniform Data Collection**: Ensures that data fetched from different sources is consistent and provided in a standard format.
@@ -27,7 +28,7 @@ The `getApiClient` method takes a single argument, which is the key of the api c
 
 Here's a basic example of what this might look like:
 
-```typescript
+```typescript [middleware.config.ts]
 export const integrations = {
   sapcc: {
     location: "@vsf-enterprise/sapcc-api/server",
@@ -40,11 +41,11 @@ export const integrations = {
         name: "sapcc-contentful-extension",
         extendApiMethods: {
           getPDP: async (context, params: { id: string }) => {
-            const sapcc = context.getApiClient("sapcc");
-            const contentful = context.getApiClient("contentful");
+            const sapccApi = context.api; // You can access integration methods directly
+            const contentful = context.getApiClient("contentful"); // You can access other integrations using getApiClient
 
             const [product, content] = Promise.all(
-              sapcc.api.getProduct({ id: params.id }),
+              sapccApi.getProduct({ id: params.id }),
               contentful.api.getEntries({
                 content_type: "product",
                 "fields.sku": params.id,
@@ -75,63 +76,156 @@ export const integrations = {
 
 3. Aggregate Data: Once data from all required integrations is retrieved, aggregate and format it as needed.
 
-4. Return Unified Response: Send a consolidated response back to the frontend.:
+4. Return Unified Response: Send a consolidated response back to the frontend.
 
 ### Using orchestration methods in the frontend
 
-To call the orchestration endpoint, you need to send a POST request to the endpoint URL. In our example it would be `POST http://localhost:8080/sapcc/getPDP`. The request body should contain the parameters required by the endpoint.
+To call the orchestration endpoint, you can use the [middlewareModule](/sdk/getting-strated/middlewareModule).
 
-When it comes to extending the Alokai integrations like `sapcc` or `contentful`, you can use the SDK extension mechanism as described in the [Extending a Module](/sdk/advanced/extending-module) guide.
+You need to prepare the type definition for the orchestration methods. It would be necessary to pass this type to the `middlewareModule`. To do it, let's aggregate the orchestration methods in a single object:
 
-## Real-World Examples
+```typescript [storefront-middleware/middleware.config.ts]
+export const orchestrationMethods = {
+  getPDP: async (context, params: { id: string }) => {
+    const sapccApi = context.api;
+    const contentful = context.getApiClient("contentful");
 
-The examples provided demonstrate practical uses of data orchestration:
+    const [product, content] = Promise.all(
+      sapccApi.getProduct({ id: params.id }),
+      contentful.api.getEntries({
+        content_type: "product",
+        "fields.sku": params.id,
+      })
+    );
 
-### Example 1: Fetching Custom Product Properties from Legacy Systems
-
-This use case involves calling the commerce backend to fetch specific product data. Additionally, a separate call is made to a legacy custom system of the customer, to retrieve a custom product property (e.g., stock of the product). This data is used, for example, to display stock information on the product page.
-
-Example implementation might look like this:
+    return {
+      product,
+      content,
+    };
+  },
+};
 
-```typescript [middleware.config.ts]
 export const integrations = {
   sapcc: {
-    // ...
+    location: "@vsf-enterprise/sapcc-api/server",
+    configuration: {
+      // ...
+    },
     extensions: (extensions) => [
       ...extensions,
       {
-        name: "orchestration-extension",
+        name: "sapcc-contentful-extension",
         extendApiMethods: {
-          enrichedSearch: async (context, params: { productId: string }) => {
-            const sapcc = context.getApiClient("sapcc");
-            const legacyCustomSystem = context.getApiClient("legacyCustomSystem");
-
-            const prouctStock = await legacyCustomSystem.api.getProductStock({
-              productId: params.productId,
-            });
-
-            const product = await sapcc.api.getProduct({
-              { id: params.productId },
-            });
-
-            return {
-              ...product,
-              stock: productStock,
-            };
-          },
+          ...orchestrationMethods,
         },
       },
     ],
   },
-  legacyCustomSystem: {
-    // ...
+  contentful: {
+    location: "@vsf-enterprise/contentful-api/server",
+    configuration: {
+      // ...
+    },
   },
 };
 ```
 
-### Example 2: Product Slider Orchestration with Commerce Backend Data
+Then, let's use `WithoutContext` type helper to prepare the type of the endpoints created by the orchestration methods. As a good practice, it's recommended to use a separate file for the types used in the middleware configuration:
+
+```typescript [storefront-middleware/types.ts]
+import { type WithoutContext } from "@vue-storefront/middleware";
+import { orchestrationMethods } from "./middleware.config";
+
+export { type Endpoints as SapccEndpoints} from "@vsf-enterprise/sapcc-api";
+export type OrchestrationEndpoints = WithoutContext<typeof orchestrationMethods>;
+```
+
+
+Finally, pass the `OrchestrationEndpoints` type to the `middlewareModule`:
 
-In this scenario, the CMS returns a product slider component that lacks sufficient product data (or contains only product IDs). The orchestration layer enhances the product slider by adding product data from the commerce backend, ensuring a comprehensive and informative display.
+::code-group
+```typescript[Next.js]
+import { contentfulModule } from "@vsf-enterprise/contentful-sdk";
+import { CreateSdkOptions, createSdk } from "@vue-storefront/next";
+import { SapccEndpoints, OrchestrationEndpoints } from "storefront-middleware/types";
+
+const options: CreateSdkOptions = {
+  middleware: {
+    apiUrl: "http://localhost:4000",
+  },
+};
+
+export const { getSdk } = createSdk(
+  options,
+  ({ buildModule, middlewareUrl, middlewareModule, getRequestHeaders }) => ({
+    sapcc: buildModule(middlewareModule<SapccEndpoints & OrchestrationEndpoints>, {
+      apiUrl: middlewareUrl + "/sapcc",
+      defaultRequestConfig: {
+        headers: getRequestHeaders(),
+      },
+    }),
+    contentful: buildModule(contentfulModule, {
+      apiUrl: middlewareUrl + "/contentful",
+    }),
+  })
+);
+```
+
+```typescript[Nuxt.js]
+import { contentfulModule } from "@vsf-enterprise/contentful-sdk";
+import { SapccEndpoints, OrchestrationEndpoints } from "storefront-middleware/types";
+
+export default defineSdkConfig(
+  ({ buildModule, middlewareUrl, middlewareModule getRequestHeaders }) => ({
+    sapcc: buildModule(middlewareModule<SapccEndpoints & OrchestrationEndpoints>, {
+      apiUrl: middlewareUrl + "/sapcc", 
+      defaultRequestConfig: {
+        headers: getRequestHeaders(),
+      },
+    }),
+    contentful: buildModule(contentfulModule, {
+      apiUrl: middlewareUrl + "/contentful",
+    }),
+  })
+);
+```
+
+```typescript[Other]
+import { initSDK, buildModule, middlewareModule } from "@vue-storefront/sdk";
+import { contentfulModule } from "@vsf-enterprise/contentful-sdk";
+import { SapccEndpoints, OrchestrationEndpoints } from "storefront-middleware/types";
+
+const { sapcc } = initSDK({
+  sapcc: buildModule(middlewareModule<SapccEndpoints & OrchestrationEndpoints>, {
+    apiUrl: "http://localhost:8181/sapcc",
+  }),
+});
+
+const { contentful } = initSDK({
+  contentful: buildModule(contentfulModule, {
+    apiUrl: "http://localhost:8181/contentful",
+  }),
+});
+
+export { sapcc, contentful };
+```
+::
+
+Now, the SDK is aware of the orchestration methods, and you can call them as follows:
+
+```typescript
+const pdp = await sdk.sapcc.getPDP({ id: "123" });
+```
+
+## Real-World Examples
+
+The examples provided demonstrate practical uses of data orchestration:
+
+### Example 1: Fetching Custom Product Properties from Legacy Systems
+
+This use case involves calling the commerce backend to fetch specific product data. Additionally, a separate call is made to a legacy custom system of the customer, to retrieve a custom product property (e.g., stock of the product). This data is used, for example, to display stock information on the product page.
+
+Example implementation might look like this:
 
 ```typescript [middleware.config.ts]
 export const integrations = {
@@ -142,45 +236,29 @@ export const integrations = {
       {
         name: "orchestration-extension",
         extendApiMethods: {
-          getProductSlider: async (
-            context: IntegrationContext,
-            props: { entryId: string }
-          ) => {
-            const contentful: ApiClient<ContentfulEndpoints> =
-              context.getApiClient("contentful");
-            const sapcc: ApiClient<SapccEndpoints> =
-              context.getApiClient("sapcc");
-
-            const content = await contentful.api.getEntry(props.entryId);
-            const productItems = await Promise.all(
-              content.fields.items.map(async (item) => {
-                const product = await sapcc.api.getProduct({
-                  id: item.fields.productId,
-                });
-
-                return {
-                  ...item,
-                  fields: {
-                    ...item.fields,
-                    ...product,
-                  },
-                };
-              })
-            );
+          enrichedSearch: async (context, params: { productId: string }) => {
+            const sapccApi = context.api;
+            const legacyCustomSystem = context.getApiClient("legacyCustomSystem");
+
+            const [prouctStock, product] = await Promise.all([
+              legacyCustomSystem.api.getProductStock({
+                productId: params.productId,
+              }),
+              sapccApi.getProduct({
+                { id: params.productId },
+              }),
+            ]);
 
             return {
-              ...content,
-              fields: {
-                ...content.fields,
-                items: productItems,
-              },
+              ...product,
+              stock: productStock,
             };
           },
         },
       },
     ],
   },
-  contentful: {
+  legacyCustomSystem: {
     // ...
   },
 };
@@ -205,5 +283,12 @@ import {
 ```
 
 :::tip Type of endpoints
-Sometimes, the `Endpoints` type is not exported by the integration. If that's the case, you can import the `XyzIntegrationContext` type from the integration package. For example, the `sapcc` integration exports the `SapccIntegrationContext` type, which contains the endpoints type as `SapccIntegrationContext['api']`. It contains also the type of the configuration object as `SapccIntegrationContext['config']` and the type of the HTTP client object as `SapccIntegrationContext['client']`. This should be applied to all integrations.
+
+Sometimes, the `Endpoints` type is not exported by the integration. If that's the case, you can import the `XyzIntegrationContext` type from the integration package. For example, the `sapcc` integration exports the `SapccIntegrationContext` type, which contains the following:
+
+- `SapccIntegrationContext['api']` - the endpoints type
+- `SapccIntegrationContext['config']` - the configuration object type
+- `SapccIntegrationContext['client']` - the HTTP client object type
+
+This applies to all integrations.  
 :::

From 8bf757912d24f42c442b2a0eba9e658e47fd836a Mon Sep 17 00:00:00 2001
From: Wojciech Sikora <wsikora@vuestorefront.io>
Date: Fri, 29 Mar 2024 19:12:30 +0100
Subject: [PATCH 17/17] apply review suggestions

---
 docs/content/3.middleware/2.guides/7.api-client.md  | 11 ++++++-----
 docs/content/4.sdk/2.getting-started/1.index.md     |  8 ++++----
 .../4.sdk/2.getting-started/2.middleware-module.md  | 13 ++++++++++---
 docs/content/4.sdk/3.advanced/2.custom-modules.md   |  4 ++--
 4 files changed, 22 insertions(+), 14 deletions(-)

diff --git a/docs/content/3.middleware/2.guides/7.api-client.md b/docs/content/3.middleware/2.guides/7.api-client.md
index a93560c48b..a473ae2853 100644
--- a/docs/content/3.middleware/2.guides/7.api-client.md
+++ b/docs/content/3.middleware/2.guides/7.api-client.md
@@ -33,12 +33,13 @@ The `api` object is a set of functions that will be available in the integration
 Now, let's create the client.
 
 :::tip
-In the following example we used the `axios` library to create a client. However, you can use any client that you suits your needs.
+In the following example we used the `axios` library to create a client. However, you can use any client that suits your needs.
+
 :::
 
 The `buildClient` function creates an instance of the `axios` client. It's a good practice to create a separate function for creating the client, so you can easily mock it in the tests.
 
-The `onCreate` function returns accepts the integration configuration, and we recommend that you create an interface for it.
+The `onCreate` function accepts the integration configuration, and we recommend that you create an interface for it.
 
 ```ts
 // types/config/index.ts
@@ -64,11 +65,11 @@ const buildClient = () => {
   return axiosInstance;
 };
 
-const onCreate = (settings: MiddlewareConfig) => {
+const onCreate = (config: MiddlewareConfig) => {
   const client = buildClient();
 
   return {
-    config: settings,
+    config,
     client,
   };
 };
@@ -81,7 +82,7 @@ const { createApiClient } = apiClientFactory({
 export { createApiClient };
 ```
 
-The server middleware can be initialized now, but it does not contain any API functions. Before adding them, let's type the integration context. Alokai uses the `context` object to pass the integration client and the configuration to the API functions. Create a `types/context/index.ts` file and add the following code:
+Now, we can initialize the server middleware, but it does not contain any API methods. Before adding them, let's create a type for the integration context.
 
 ```ts
 // types/context/index.ts
diff --git a/docs/content/4.sdk/2.getting-started/1.index.md b/docs/content/4.sdk/2.getting-started/1.index.md
index 75b23a7f8f..5c0a9d4e8f 100644
--- a/docs/content/4.sdk/2.getting-started/1.index.md
+++ b/docs/content/4.sdk/2.getting-started/1.index.md
@@ -2,6 +2,10 @@
 
 If you're setting your Alokai application from scratch, you'll need to configure a type-safe SDK that communicates with your [Server Middleware](/middleware).
 
+:::tip
+In the examples below, we assume that you have an Alokai app with the Unified Data Model. However, the approach for non-unified Alokai applications is similar.
+:::
+
 There are various ways to configure the SDK, depending on your chosen framework. For Next.js and Nuxt, you can use the `@vue-storefront/next` and `@vue-storefront/nuxt` packages respectively. If you're looking for framework agnostic experience, you can use the `@vue-storefront/sdk` package.
 
 ::tabs{:titles='["Next.js", "Nuxt", "Other"]' class="mt-8"}
@@ -460,11 +464,7 @@ That's it! You can now use VueStorefront SDK Module in any JavaScript app ✨
 #section-1
 :card{to="/sdk/advanced/extending-module" title="Extending the SDK" description="Learn how to customize, override, or extend any default functionality in the SDK" icon="ri:terminal-box-fill"}
 #section-2
-<<<<<<< HEAD
 :card{to="/sdk/advanced/middleware-module" title="The middlewareModule" description="Understand how to use the default SDK module" icon="fa6-solid:layer-group"}
-=======
-:card{to="/middleware" title="Middleware Docs" description="Understand more about Alokai Middleware" icon="fa6-solid:layer-group"}
->>>>>>> 803cfd9a0ae0a44d624741b6c2c4cc2a5f643a3b
 #section-3
 :card{to="/sdk/advanced/custom-modules" title="Create a custom SDK module" description="Create your own custom SDK module" icon="fluent:puzzle-cube-piece-20-filled"}
 #section-4
diff --git a/docs/content/4.sdk/2.getting-started/2.middleware-module.md b/docs/content/4.sdk/2.getting-started/2.middleware-module.md
index a29559b4c1..1b61e3481d 100644
--- a/docs/content/4.sdk/2.getting-started/2.middleware-module.md
+++ b/docs/content/4.sdk/2.getting-started/2.middleware-module.md
@@ -10,7 +10,7 @@ Depending on which framework you are using, you can get the `middlewareModule` i
 
 In Next, `middlewareModule` is available in the `createSdk` function.
 
-```ts [Nuxt]
+```ts [Next]
 // sdk/sdk.config.ts
 import { CreateSdkOptions, createSdk } from "@vue-storefront/next";
 import { UnifiedEndpoints } from "storefront-middleware/types";
@@ -69,7 +69,8 @@ export const sdk = initSDK({
 
 ### Type definition
 
-As the `middlewareModule` could be used to communicate with the Server Middleware and it's not limited to a specific backend, it requires a type definition of the endpoints.
+As the `middlewareModule` is used to communicate with the Alokai Middleware and it's not limited to a specific backend, it requires a type definition of the endpoints.  
+
 
 The type definition should be provided as a generic type to the `middlewareModule` function.
 
@@ -89,7 +90,11 @@ const sdk = initSDK({
 const product = await sdk.commerce.getProduct({ id: "123" });
 ```
 
-In Storefront Starter, you can find the `UnifiedEndpoints` type in `storefront-middleware/types.ts` file. It's a type definition for the endpoints used in the middleware.
+In Alokai Storefront, you can find the `UnifiedEndpoints` type in `storefront-middleware/types.ts` file. It's a type definition for the endpoints used in the middleware.  
+
+::: tip Nuxt and Next examples
+We're using `initSDK` approach in this examples to make it more universal. However, you can use `createSdk` and `defineSdkConfig` functions in Next and Nuxt as well.
+:::
 
 ```ts
 import { UnifiedEndpoints } from "storefront-middleware/types";
@@ -149,6 +154,8 @@ export const sdk = initSDK({
   }),
 });
 ```
+Once you have added the `middlewareModule` to your SDK, you can use it to make requests to the Alokai Middleware.  
+
 
 ## Usage
 
diff --git a/docs/content/4.sdk/3.advanced/2.custom-modules.md b/docs/content/4.sdk/3.advanced/2.custom-modules.md
index 26140e596e..44d9544c95 100644
--- a/docs/content/4.sdk/3.advanced/2.custom-modules.md
+++ b/docs/content/4.sdk/3.advanced/2.custom-modules.md
@@ -9,7 +9,7 @@ However, you may need to create a module that doesn't communicate with the Serve
 ## Module
 
 Let's start with the module itself. The module is a function that implements the `Module` interface.
-Create a new file `module.ts` and add the following code:
+Frist, create a new directory `sdk/modules/logger`. Then, navigate to it and create a new file `module.ts` with the following code:
 
 ```typescript
 import { Module } from "@vue-storefront/sdk";
@@ -173,5 +173,5 @@ const sdk = initSdk({
   logger: buildModule(loggerModule),
 });
 
-sdk.logger.log("Hello, World!"); // 2021-01-01T00:00:00.000Z - Hello, World!
+sdk.utils.formatMessage(sdk.logger.log("Hello, World!")); // 2021-01-01T00:00:00.000Z - Hello, World!
 ```