Revert "chore: move part of docs to enterprise repository (#7385)" (#7386)

This reverts commit a72218b.

Author: bartoszherba

docs/content/3.middleware/1.index.md

@@ -0,0 +1,44 @@
+---
+title: Overview
+---
+# Middleware
+
+Alokai's **Server Middleware** is an Express.js application that provides a single place for you to connect to the multiple services that you need to run your storefront.
+
+It acts as a layer between your frontend application and the various services that you need to connect to, such as a commerce backend, CMS, or payment gateway. 
+
+Our different [integrations](/integrations) add onto the middleware to provide additional API Clients specific for a certain integration that you can interact with using the [SDK](/sdk).
+
+## Features
+
+::list{type="success"}
+- Connect multiple services using different technologies and libraries
+- Create and [extend](/middleware/guides/extensions) integrations to add new capabilities or modify their behavior
+- Control of the requests sent to the integration platform and responses sent back to the Nuxt.js application
+- Securely store credentials on the server without exposing them to the end-users of your application
+- Improve site performance by moving logic to the server abd shipping less code to the browser
+::
+
+## Getting Started
+
+If you're using our storefront, the middleware is set up for you. Our storefronts come with a middleware and frontend app already configured, so you can get started right away.
+
+But if you're building your Alokai application from scratch, you'll need to set up the middleware to connect to your backend services.
+
+::grid{:columns="2"}
+#section-1
+:card{to="/middleware/guides/extensions" title="See Available Storefronts" description="Get started with one of our ready-to-customize storefronts." icon="material-symbols:storefront"}
+#section-2
+:card{to="/middleware/guides/extensions" title="Start From Scratch" description="Set up your server middleware, configure it, and more." icon="gridicons:customize"}
+::
+
+## Architecture
+
+The easiest way to explain the Server Middleware architecture is to base the explanation on the Alokai Integration context.
+
+In the container, the server application uses the integration that can communicate with the external service provider (e.g. commerce backend). The integration can be extended by the integration extensions. Middleware config is provided for both integration and its extensions.
+
+<img alt="Middleware Data Flow" src="./img/overview/architecture.svg" class="mx-auto" />
+
+
+

docs/content/3.middleware/2.guides/10.logging.md

@@ -0,0 +1,344 @@
+# Logger
+
+The middleware application provides a logger instance that automatically attaches metadata related to the scope of each call. By adding this contextual data, the logger makes it significantly easier to trace the origin of logs or errors, simplifying the debugging and monitoring process across the application.
+
+:::info
+The logger has been available since version 5.1.0. Please refer to the [middleware changelog](https://docs.alokai.com/middleware/reference/change-log#_510) for more details.
+:::
+
+## Using logger
+
+The middleware application provides access to the logger in various parts of the system, such as in extensions and integrations. This flexibility allows you to log important events, errors, and other data throughout the lifecycle of your application.
+
+In this section, we will explore how to access and use the logger in different parts of the application.
+
+The examples below demonstrate how to use the application logger to ensure that correct metadata is conveyed in the logs. To achieve that, we will use the `getLogger` function to extract the logger instance from the passed argument.
+
+:::tip
+The logger is integrated into the middleware to provide additional metadata about the scope of call with every log out of the box. In case of error, it also provides an error boundary.
+:::
+
+### Basic Logger usage
+
+To use the logger, you need to import the `getLogger` function from the middleware package. Depending on the context, you can obtain the logger from different sources, such as the `alokai` object, `context` object, or `params` object. All such cases are covered in the following examples. For this example, we will use the `context` object.
+
+```ts
+import { getLogger } from "@vue-storefront/middleware";
+
+// Assume that `context` is available in the current scope
+const logger = getLogger(context);
+logger.info("Middleware is running!");
+```
+
+Prints:
+
+```json
+{
+  "message": "Middleware is running!",
+  "timestamp": "2024-10-22T19:04:18.791Z",
+  "severity": "INFO",
+  "alokai": {
+    "context": "middleware",
+    "scope": {
+      // ...
+    }
+  }
+}
+```
+
+The provided logger has a second optional argument that allows you to include custom metadata to be attached to the JSON output.
+For example:
+
+```ts
+logger.info("I've just fetched a user!", {
+  userId: "123",
+});
+```
+
+Prints:
+
+```json
+{
+  "message": "I've just fetched a user!",
+  "timestamp": "2024-10-22T19:04:18.791Z",
+  "severity": "INFO",
+  "alokai": {
+    "context": "middleware",
+    "scope": {
+      // ...
+    }
+  },
+  "userId": "123"
+}
+```
+
+:::warning
+It's forbidden to overwrite **alokai** key within provided metadata. Any attempt will be ineffective. If you need to provide additional metadata, use a different key. **alokai** key is reserved for internal use only.
+:::
+
+### `extendApp`
+
+```ts
+import { getLogger } from "@vue-storefront/middleware";
+
+const someExtension = {
+  name: "some-extension",
+  extendApp(params) {
+    const logger = getLogger(params);
+
+    logger.info(
+      "You can call a logger inside extendApp hook, called on bootstrap of the application"
+    );
+  },
+};
+```
+
+### Hooks
+
+Logger is available in hooks factory:
+
+```ts
+import { getLogger } from "@vue-storefront/middleware";
+
+const paypalExtension = {
+  name: "sapcc-paypal-extension",
+  hooks(req, res, alokai) {
+    const logger = getLogger(alokai);
+    logger.info(
+      "You can call a logger every time a hooks factory gets invoked"
+    );
+    return {
+      // ...
+    };
+  },
+};
+```
+
+In order, to use logger in certain hooks like `beforeCall`, `beforeCreate`, `afterCall`, `afterCreate` obtain it from it's params:
+
+```ts
+import { getLogger } from "@vue-storefront/middleware";
+
+const paypalExtension = {
+  name: "sapcc-paypal-extension",
+  hooks(req, res, alokai) {
+    return {
+      beforeCall(params) {
+        const logger = getLogger(params);
+        logger.info("You can log every time a beforeCall hook gets invoked");
+        return params.args;
+      },
+      beforeCreate(params) {
+        const logger = getLogger(params);
+        logger.info("You can log every time a beforeCreate hook gets invoked");
+        return params.configuration;
+      },
+      afterCall(params) {
+        const logger = getLogger(params);
+        logger.info("You can log every time a afterCall hook gets invoked");
+        return params.response;
+      },
+      afterCreate(params) {
+        const logger = getLogger(params);
+        logger.info("You can log every time a afterCreate hook gets invoked");
+        return params.configuration;
+      },
+    };
+  },
+};
+```
+
+#### Caveat: Accessing logger via closure
+
+Consider the following snippet:
+
+```ts
+import { getLogger } from "@vue-storefront/middleware";
+
+const someExtension = {
+  name: "some-extension",
+  hooks(req, res, alokai) {
+    const hooksLogger = getLogger(alokai);
+    hooksLogger.info(
+      "You can call a logger every time a hooks factory gets invoked"
+    );
+    return {
+      beforeCall(params) {
+        // Never access via closure a logger belonging to the hooks factory:
+        hooksLogger.info("Don't do that!");
+        // Instead use own logger of every hook function:
+        const logger = getLogger(params);
+        logger.info("Do that!");
+        return params.args;
+      },
+    };
+  },
+};
+```
+
+:::warning
+Attempt of using `hooksLogger` inside `beforeCall` or other hooks via closure corrupts information about scope of call of the log. Always use logger provided in params to the hook.
+:::
+
+### extendApiMethods
+
+Inside extended api methods, obtain logger from `context` using `getLogger` function.
+
+```ts
+import { getLogger } from "@vue-storefront/middleware";
+
+const testingExtension = {
+  name: "some-extension",
+  extendApiMethods: {
+    addedCustomEndpoint(context) {
+      const logger = getLogger(context);
+      logger.info("You can log inside newly created handler!");
+      return {
+        // ...
+      };
+    },
+  },
+};
+```
+
+:::tip
+You can derive logger from context the same way if you are creating an integration.
+:::
+
+### onCreate
+
+The hook got a new parameter from which you can derive the logger with help of `getLogger` function.
+
+```ts
+import { type AlokaiContainer, getLogger } from "@vue-storefront/middleware";
+
+const onCreate = async (
+  config: Record<string, unknown> = {},
+  alokai: AlokaiContainer
+) => {
+  const logger = getLogger(alokai);
+  logger.info("You can log inside onCreate when creating a new integration");
+
+  return {
+    // ...
+  };
+};
+```
+
+## Configuration
+
+The middleware logger offers flexible configuration options to control logging behavior across the application. These options allow you to manage the verbosity and level of detail in logs based on the needs of different environments, such as development or production.
+
+### Available Configuration Options
+
+```ts
+/**
+ * Options for the logger.
+ */
+export interface LoggerOptions {
+  /**
+   * The log level aligned with RFC5424.
+   */
+  verbosity?: LogVerbosity; // (def. "info")
+
+  /**
+   * Whether to include the stack trace in the log message.
+   */
+  includeStackTrace?: boolean; // (def. true)
+}
+```
+
+#### 1. Verbosity
+
+This option sets the log verbosity level based on the [RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424) syslog standard. It defines the severity of log messages that should be recorded. Available log levels are:
+
+- **emergency**: The highest severity level, indicating a system-wide emergency.
+- **alert**: Indicates an urgent condition that requires immediate attention.
+- **critical**: Highlights critical issues that need immediate action.
+- **error**: Used to log error messages that could affect functionality.
+- **warning**: Logs warnings about potential issues that should be monitored.
+- **notice**: Records significant but non-critical events.
+- **info**: Logs general informational messages indicating normal operation.
+- **debug**: The most detailed log level, useful for tracing and debugging the application.
+
+**Example:**
+Setting the log verbosity level to `error` ensures only error messages and above (i.e., critical, alert, emergency) will be captured:
+
+```json
+{
+  "logger": {
+    "verbosity": "error"
+  }
+}
+```
+
+For a development environment, you might prefer a more verbose log level like `debug`:
+
+```json
+{
+  "logger": {
+    "verbosity": "debug"
+  }
+}
+```
+
+#### 2. includeStackTrace
+
+This option specifies whether the stack trace should be included in the log messages. If set to `true`, stack traces will be included in error messages, which can be helpful during debugging. If set to `false`, logs will be more concise.
+
+```json
+{
+  "logger": {
+    "includeStackTrace": true
+  }
+}
+```
+
+### Global configuration
+
+To configure the logger globally, add a `logger` object to the top-level configuration of the middleware. This configuration will apply to all integrations and parts of the application unless specifically overridden. Here’s an example of a global configuration where the stack trace is included in the logs, and the log level is set to `debug`:
+
+```js[middleware.config.js]
+export const config = {
+  "logger": {
+    "includeStackTrace": true,
+    "verbosity": "debug"
+  },
+  // The rest of the middleware configuration
+  "integrations": {
+    // ...
+  }
+}
+```
+
+This global logger configuration ensures that all logs, regardless of the integration or scope, will follow these settings.
+
+### Per integration configuration
+
+If you need different logging settings for specific integrations, you can configure the logger separately within each integration. The logger configuration should be added at the same level as `location` and `configuration` keys within the integration’s object.
+
+For example, here is how you would configure the logger for an integration with the key `commerce`:
+
+```js[middleware.config.js]
+export const config = {
+  "integrations": {
+    "commerce": {
+      "location": "@vsf-enterprise/sapcc-api/server",
+
+      "configuration": {
+        // Configuration of integration itself
+      }
+
+      // Configuration of the logger only for "commerce" integration
+      "logger": {
+        "includeStackTrace": true,
+        "verbosity": "debug"
+      },
+    }
+  }
+}
+```
+
+In this case, the logging configuration applies only to the `commerce` integration, overriding the global settings if they exist. The logger configuration can vary for each integration, allowing you to customize the level of logging detail based on the needs of specific integrations.
+
+This approach provides the flexibility to define global logging behavior while also giving control to fine-tune logging per integration, ensuring you capture the necessary details for debugging and monitoring in the most relevant areas.