@breadstone/archipel-mcp 0.0.23 → 0.0.25

package/data/packages/platform-logging/api/Class.ContextLogger.md

@@ -0,0 +1,152 @@
+---
+title: 'Class: ContextLogger'
+generated: true
+editUrl: false
+---
+# Class: ContextLogger
+
+Defined in: [ContextLogger.ts:20](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-logging/src/ContextLogger.ts#L20)
+
+Structured logger that automatically enriches log entries with the
+current request context (requestId, userId) from [RequestContextStore](Class.RequestContextStore).
+
+## Remarks
+
+This logger wraps the NestJS Logger and prepends structured
+context fields. It is intended as a drop-in replacement for direct
+`Logger` usage in services that need request-scoped correlation.
+
+## Constructors
+
+### Constructor
+
+```ts
+new ContextLogger(context?): ContextLogger;
+```
+
+Defined in: [ContextLogger.ts:29](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-logging/src/ContextLogger.ts#L29)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `context?` | `string` |
+
+#### Returns
+
+`ContextLogger`
+
+## Methods
+
+### debug()
+
+```ts
+debug(message, data?): void;
+```
+
+Defined in: [ContextLogger.ts:69](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-logging/src/ContextLogger.ts#L69)
+
+Logs at `debug` level with request context.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `message` | `string` |
+| `data?` | `Record`\<`string`, `unknown`\> |
+
+#### Returns
+
+`void`
+
+***
+
+### error()
+
+```ts
+error(message, data?): void;
+```
+
+Defined in: [ContextLogger.ts:60](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-logging/src/ContextLogger.ts#L60)
+
+Logs at `error` level with request context.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `message` | `string` |
+| `data?` | `Record`\<`string`, `unknown`\> |
+
+#### Returns
+
+`void`
+
+***
+
+### log()
+
+```ts
+log(message, data?): void;
+```
+
+Defined in: [ContextLogger.ts:42](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-logging/src/ContextLogger.ts#L42)
+
+Logs at `log` level with request context.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `message` | `string` |
+| `data?` | `Record`\<`string`, `unknown`\> |
+
+#### Returns
+
+`void`
+
+***
+
+### verbose()
+
+```ts
+verbose(message, data?): void;
+```
+
+Defined in: [ContextLogger.ts:78](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-logging/src/ContextLogger.ts#L78)
+
+Logs at `verbose` level with request context.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `message` | `string` |
+| `data?` | `Record`\<`string`, `unknown`\> |
+
+#### Returns
+
+`void`
+
+***
+
+### warn()
+
+```ts
+warn(message, data?): void;
+```
+
+Defined in: [ContextLogger.ts:51](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-logging/src/ContextLogger.ts#L51)
+
+Logs at `warn` level with request context.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `message` | `string` |
+| `data?` | `Record`\<`string`, `unknown`\> |
+
+#### Returns
+
+`void`

package/data/packages/platform-logging/api/Class.LoggerModule.md

@@ -5,9 +5,15 @@ editUrl: false
 ---
 # Class: LoggerModule
 
-Defined in: [LoggerModule.ts:35](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-logging/src/LoggerModule.ts#L35)
+Defined in: [LoggerModule.ts:44](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-logging/src/LoggerModule.ts#L44)
 
-Global logging module that configures the NestJS Logger with an application-wide log level.
+Global logging module that configures the NestJS Logger with an application-wide log level
+and provides request-scoped context propagation via [RequestIdMiddleware](Class.RequestIdMiddleware).
+
+## Remarks
+
+Apply [RequestIdMiddleware](Class.RequestIdMiddleware) in your `AppModule.configure()` to enable
+automatic `requestId` propagation to all log entries via [ContextLogger](Class.ContextLogger).
 
 ## Constructors
 

package/data/packages/platform-logging/api/Class.RequestContextStore.md

@@ -0,0 +1,90 @@
+---
+title: 'Class: RequestContextStore'
+generated: true
+editUrl: false
+---
+# Class: RequestContextStore
+
+Defined in: [RequestContextStore.ts:29](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-logging/src/RequestContextStore.ts#L29)
+
+AsyncLocalStorage-based request context store.
+
+Provides a per-request context accessible anywhere in the call stack
+without passing parameters explicitly. This is the foundation for
+structured logging with automatic `requestId` propagation.
+
+## Constructors
+
+### Constructor
+
+```ts
+new RequestContextStore(): RequestContextStore;
+```
+
+#### Returns
+
+`RequestContextStore`
+
+## Methods
+
+### get()
+
+```ts
+static get(): IRequestContext | undefined;
+```
+
+Defined in: [RequestContextStore.ts:57](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-logging/src/RequestContextStore.ts#L57)
+
+Returns the current request context, or `undefined` if called
+outside a request scope.
+
+#### Returns
+
+[`IRequestContext`](Interface.IRequestContext) \| `undefined`
+
+***
+
+### getRequestId()
+
+```ts
+static getRequestId(): string;
+```
+
+Defined in: [RequestContextStore.ts:66](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-logging/src/RequestContextStore.ts#L66)
+
+Returns the current `requestId`, or `'unknown'` if no context is active.
+
+#### Returns
+
+`string`
+
+***
+
+### run()
+
+```ts
+static run<T>(context, callback): T;
+```
+
+Defined in: [RequestContextStore.ts:47](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-logging/src/RequestContextStore.ts#L47)
+
+Runs a callback within a new request context.
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `T` |
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `context` | [`IRequestContext`](Interface.IRequestContext) | The request context to associate with the callback execution. |
+| `callback` | () => `T` | The function to execute within the context. |
+
+#### Returns
+
+`T`
+
+The return value of the callback.

package/data/packages/platform-logging/api/Class.RequestIdMiddleware.md

@@ -0,0 +1,68 @@
+---
+title: 'Class: RequestIdMiddleware'
+generated: true
+editUrl: false
+---
+# Class: RequestIdMiddleware
+
+Defined in: [RequestIdMiddleware.ts:27](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-logging/src/RequestIdMiddleware.ts#L27)
+
+NestJS middleware that extracts or generates a unique request ID
+and stores it in the [RequestContextStore](Class.RequestContextStore) via `AsyncLocalStorage`.
+
+## Remarks
+
+If the incoming request already carries a `x-request-id` header (e.g. from
+an API gateway or load balancer), the middleware reuses that value.
+Otherwise it generates a new UUID v4.
+
+The request ID is also set on the response headers for traceability.
+
+## Implements
+
+- `NestMiddleware`
+
+## Constructors
+
+### Constructor
+
+```ts
+new RequestIdMiddleware(): RequestIdMiddleware;
+```
+
+#### Returns
+
+`RequestIdMiddleware`
+
+## Methods
+
+### use()
+
+```ts
+use(
+   req, 
+   res, 
+   next): void;
+```
+
+Defined in: [RequestIdMiddleware.ts:33](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-logging/src/RequestIdMiddleware.ts#L33)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `req` | `Request` |
+| `res` | `Response` |
+| `next` | (`error?`) => `void` |
+
+#### Returns
+
+`void`
+
+#### Inherit Doc
+
+#### Implementation of
+
+```ts
+NestMiddleware.use
+```

package/data/packages/platform-logging/api/Interface.IRequestContext.md

@@ -0,0 +1,34 @@
+---
+title: 'Interface: IRequestContext'
+generated: true
+editUrl: false
+---
+# Interface: IRequestContext
+
+Defined in: [RequestContextStore.ts:12](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-logging/src/RequestContextStore.ts#L12)
+
+Shape of the per-request context stored in [RequestContextStore](Class.RequestContextStore).
+
+## Properties
+
+### requestId
+
+```ts
+readonly requestId: string;
+```
+
+Defined in: [RequestContextStore.ts:14](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-logging/src/RequestContextStore.ts#L14)
+
+Unique request correlation identifier.
+
+***
+
+### userId?
+
+```ts
+readonly optional userId?: string;
+```
+
+Defined in: [RequestContextStore.ts:17](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-logging/src/RequestContextStore.ts#L17)
+
+Optional authenticated user identifier.

package/data/packages/platform-logging/api/Variable.REQUEST_ID_HEADER.md

@@ -0,0 +1,14 @@
+---
+title: 'Variable: REQUEST\_ID\_HEADER'
+generated: true
+editUrl: false
+---
+# Variable: REQUEST\_ID\_HEADER
+
+```ts
+const REQUEST_ID_HEADER: "x-request-id" = 'x-request-id';
+```
+
+Defined in: [RequestIdMiddleware.ts:11](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-logging/src/RequestIdMiddleware.ts#L11)
+
+Header name used to propagate the request correlation ID.

package/data/packages/platform-logging/api/index.md

@@ -9,7 +9,16 @@ editUrl: false
 
 | Class | Description |
 | ------ | ------ |
-| [LoggerModule](Class.LoggerModule) | Global logging module that configures the NestJS Logger with an application-wide log level. |
+| [ContextLogger](Class.ContextLogger) | Structured logger that automatically enriches log entries with the current request context (requestId, userId) from [RequestContextStore](Class.RequestContextStore). |
+| [LoggerModule](Class.LoggerModule) | Global logging module that configures the NestJS Logger with an application-wide log level and provides request-scoped context propagation via [RequestIdMiddleware](Class.RequestIdMiddleware). |
+| [RequestContextStore](Class.RequestContextStore) | AsyncLocalStorage-based request context store. |
+| [RequestIdMiddleware](Class.RequestIdMiddleware) | NestJS middleware that extracts or generates a unique request ID and stores it in the [RequestContextStore](Class.RequestContextStore) via `AsyncLocalStorage`. |
+
+## Interfaces
+
+| Interface | Description |
+| ------ | ------ |
+| [IRequestContext](Interface.IRequestContext) | Shape of the per-request context stored in [RequestContextStore](Class.RequestContextStore). |
 
 ## Variables
 
@@ -17,3 +26,4 @@ editUrl: false
 | ------ | ------ |
 | [APP\_LOG\_LEVEL](Variable.APP_LOG_LEVEL) | Application log level (e.g. `'debug'`, `'info'`, `'warn'`, `'error'`). |
 | [PLATFORM\_LOGGING\_CONFIG\_ENTRIES](Variable.PLATFORM_LOGGING_CONFIG_ENTRIES) | All configuration entries required by `platform-logging`. |
+| [REQUEST\_ID\_HEADER](Variable.REQUEST_ID_HEADER) | Header name used to propagate the request correlation ID. |

package/data/packages/platform-logging/index.md

@@ -1,14 +1,14 @@
 ---
 title: platform-logging
-description: Configurable logging module for NestJS with log-level management.
+description: Configurable logging module for NestJS with log-level management, request context propagation, and structured logging.
 order: 6
-tags: [logging, log-level, nestjs]
+tags: [logging, log-level, nestjs, request-context, structured-logging, correlation-id]
 package: '@breadstone/archipel-platform-logging'
 ---
 
 # platform-logging
 
-Configurable logging module for NestJS applications with application-wide log-level management. Wraps the built-in NestJS `Logger` and configures it via the central `ConfigModule`.
+Configurable logging module for NestJS applications with application-wide log-level management, request-scoped context propagation, and structured logging. Wraps the built-in NestJS `Logger` and configures it via the central `ConfigModule`.
 
 **Package:** `@breadstone/archipel-platform-logging`
 
@@ -48,6 +48,75 @@ export class PaymentService {
 
 ---
 
+## Request Context Propagation
+
+### RequestIdMiddleware
+
+Extracts or generates a unique `x-request-id` per request and stores it in `AsyncLocalStorage` via `RequestContextStore`. Apply it globally:
+
+```typescript
+import { RequestIdMiddleware } from '@breadstone/archipel-platform-logging';
+
+export class AppModule implements NestModule {
+  public configure(consumer: MiddlewareConsumer): void {
+    consumer.apply(RequestIdMiddleware).forRoutes('*');
+  }
+}
+```
+
+The middleware:
+
+1. Reads the `x-request-id` header from the incoming request (if present from an API gateway or load balancer)
+2. Generates a UUID v4 if no header is found
+3. Sets the `x-request-id` header on the response
+4. Wraps the request execution in `RequestContextStore.run()` so the ID is available anywhere in the call stack
+
+### RequestContextStore
+
+`AsyncLocalStorage`-based per-request context store. Access the current request context from anywhere without passing parameters:
+
+```typescript
+import { RequestContextStore, type IRequestContext } from '@breadstone/archipel-platform-logging';
+
+// Get current context
+const context: IRequestContext | undefined = RequestContextStore.get();
+const requestId: string | undefined = RequestContextStore.getRequestId();
+
+// Run a callback within a context (used internally by middleware)
+RequestContextStore.run({ requestId: 'abc-123', userId: 'user-1' }, () => {
+  // context is available in all nested calls
+});
+```
+
+#### IRequestContext
+
+| Field       | Type     | Description                       |
+| ----------- | -------- | --------------------------------- |
+| `requestId` | `string` | Unique request correlation ID     |
+| `userId`    | `string?`| Optional authenticated user ID    |
+
+### ContextLogger
+
+Structured logger that automatically enriches every log entry with the current request context:
+
+```typescript
+import { ContextLogger } from '@breadstone/archipel-platform-logging';
+
+@Injectable()
+export class OrderService {
+  private readonly _logger = new ContextLogger(OrderService.name);
+
+  public async placeOrder(dto: CreateOrderDto): Promise<void> {
+    this._logger.log('Placing order', { orderId: dto.orderId });
+    // Output: { requestId: "abc-123", userId: "user-1", orderId: "...", message: "Placing order" }
+  }
+}
+```
+
+Methods: `log()`, `warn()`, `error()`, `debug()`, `verbose()` — all accept an optional `data` record that is merged with the request context.
+
+---
+
 ## Environment Variables
 
 | Variable        | Description                                                    | Required | Default |
@@ -58,9 +127,22 @@ export class PaymentService {
 
 ---
 
+## Peer Dependencies
+
+| Package   | Required | Notes                                          |
+| --------- | -------- | ---------------------------------------------- |
+| `express` | Yes      | Required for `RequestIdMiddleware` types (`Request`, `Response`) |
+
+---
+
 ## Exports Summary
 
-| Export         | Type          | Description                                  |
-| -------------- | ------------- | -------------------------------------------- |
-| `LoggerModule` | NestJS Module | Global logging module with log-level control |
-| `Logger`       | Provider      | NestJS Logger configured with `APP_LOG_LEVEL`|
+| Export                  | Type          | Description                                                        |
+| ----------------------- | ------------- | ------------------------------------------------------------------ |
+| `LoggerModule`          | NestJS Module | Global logging module with log-level control                       |
+| `Logger`                | Provider      | NestJS Logger configured with `APP_LOG_LEVEL`                      |
+| `ContextLogger`         | Class         | Structured logger enriched with request context                    |
+| `RequestContextStore`   | Class         | AsyncLocalStorage-based per-request context (requestId, userId)    |
+| `RequestIdMiddleware`   | Middleware    | Extracts/generates `x-request-id` and wraps in context store       |
+| `IRequestContext`       | Interface     | Shape of the per-request context                                   |
+| `REQUEST_ID_HEADER`     | Constant      | Header name (`'x-request-id'`)                                     |

package/data/packages/platform-mailing/api/Class.MailHealthIndicator.md

@@ -5,7 +5,7 @@ editUrl: false
 ---
 # Class: MailHealthIndicator
 
-Defined in: [platform-mailing/src/terminus/MailHealthIndicator.ts:17](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/terminus/MailHealthIndicator.ts#L17)
+Defined in: platform-mailing/src/health/MailHealthIndicator.ts:17
 
 Health indicator for mail service.
 
@@ -21,7 +21,7 @@ Health indicator for mail service.
 new MailHealthIndicator(configService): MailHealthIndicator;
 ```
 
-Defined in: [platform-mailing/src/terminus/MailHealthIndicator.ts:31](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/terminus/MailHealthIndicator.ts#L31)
+Defined in: platform-mailing/src/health/MailHealthIndicator.ts:31
 
 Constructs a new instance of the `MailHealthIndicator` class.
 
@@ -40,10 +40,10 @@ Constructs a new instance of the `MailHealthIndicator` class.
 ### key
 
 ```ts
-readonly key: "mail" = 'mail';
+readonly key: string = 'mail';
 ```
 
-Defined in: [platform-mailing/src/terminus/MailHealthIndicator.ts:39](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/terminus/MailHealthIndicator.ts#L39)
+Defined in: platform-mailing/src/health/MailHealthIndicator.ts:39
 
 Unique key identifying the indicator
 
@@ -61,7 +61,7 @@ IHealthIndicator.key
 check(): HealthIndicatorResult<"mail">;
 ```
 
-Defined in: [platform-mailing/src/terminus/MailHealthIndicator.ts:51](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/terminus/MailHealthIndicator.ts#L51)
+Defined in: platform-mailing/src/health/MailHealthIndicator.ts:51
 
 Checks if the mail configuration is valid.
 

package/data/packages/platform-mailing/api/Class.MailModule.md

@@ -5,10 +5,13 @@ editUrl: false
 ---
 # Class: MailModule
 
-Defined in: [platform-mailing/src/tokens/MailModule.ts:108](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/tokens/MailModule.ts#L108)
+Defined in: [platform-mailing/src/tokens/MailModule.ts:46](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/tokens/MailModule.ts#L46)
 
 Represents the mail module.
 
+Delivery and template strategies are resolved at runtime based on
+configuration keys `MAIL_DELIVERY_STRATEGY` and `MAIL_TEMPLATE_STRATEGY`.
+
 ## Constructors
 
 ### Constructor
@@ -20,3 +23,27 @@ new MailModule(): MailModule;
 #### Returns
 
 `MailModule`
+
+## Methods
+
+### register()
+
+```ts
+static register(options?): DynamicModule;
+```
+
+Defined in: [platform-mailing/src/tokens/MailModule.ts:55](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/tokens/MailModule.ts#L55)
+
+Registers the mail module with optional configuration.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `options?` | [`IMailModuleOptions`](Interface.IMailModuleOptions) | Module registration options. |
+
+#### Returns
+
+`DynamicModule`
+
+A configured `DynamicModule`.