@breadstone/archipel-mcp 0.0.22 → 0.0.25

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`.

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

@@ -5,16 +5,16 @@ editUrl: false
 ---
 # ~~Class: MailVerificationService~~
 
-Defined in: [platform-mailing/src/services/MailVerificationService.ts:20](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/services/MailVerificationService.ts#L20)
-
-Verifies SMTP server connectivity. Does **not** validate individual email
-addresses — only checks whether the configured SMTP transport is reachable.
+Defined in: [platform-mailing/src/services/MailVerificationService.ts:15](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/services/MailVerificationService.ts#L15)
 
 ## Deprecated
 
-Renamed to `SmtpConnectionVerifier` in a future release to better
-reflect its actual purpose. Prefer wrapping this in a health-check rather
-than calling it directly.
+Use [SmtpConnectionVerifier](Class.SmtpConnectionVerifier) instead. This class will be
+removed in a future major release.
+
+## Extends
+
+- [`SmtpConnectionVerifier`](Class.SmtpConnectionVerifier)
 
 ## Constructors
 
@@ -24,9 +24,9 @@ than calling it directly.
 new MailVerificationService(configService): MailVerificationService;
 ```
 
-Defined in: [platform-mailing/src/services/MailVerificationService.ts:35](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/services/MailVerificationService.ts#L35)
+Defined in: [platform-mailing/src/services/SmtpConnectionVerifier.ts:32](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/services/SmtpConnectionVerifier.ts#L32)
 
-Constructs a new instance of the `MailVerificationService` class.
+Constructs a new instance of the [SmtpConnectionVerifier](Class.SmtpConnectionVerifier) class.
 
 #### Parameters
 
@@ -38,6 +38,10 @@ Constructs a new instance of the `MailVerificationService` class.
 
 `MailVerificationService`
 
+#### Inherited from
+
+[`SmtpConnectionVerifier`](Class.SmtpConnectionVerifier).[`constructor`](Class.SmtpConnectionVerifier#constructor)
+
 ## Methods
 
 ### ~~sendTestEmail()~~
@@ -50,9 +54,9 @@ sendTestEmail(
 text): Promise<void>;
 ```
 
-Defined in: [platform-mailing/src/services/MailVerificationService.ts:76](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/services/MailVerificationService.ts#L76)
+Defined in: [platform-mailing/src/services/SmtpConnectionVerifier.ts:74](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/services/SmtpConnectionVerifier.ts#L74)
 
-Send an email for testing purposes or verification
+Send an email for testing purposes.
 
 #### Parameters
 
@@ -67,26 +71,55 @@ Send an email for testing purposes or verification
 
 `Promise`\<`void`\>
 
+#### Inherited from
+
+[`SmtpConnectionVerifier`](Class.SmtpConnectionVerifier).[`sendTestEmail`](Class.SmtpConnectionVerifier#sendtestemail)
+
+***
+
+### ~~verifyConnection()~~
+
+```ts
+verifyConnection(): Promise<boolean>;
+```
+
+Defined in: [platform-mailing/src/services/SmtpConnectionVerifier.ts:54](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/services/SmtpConnectionVerifier.ts#L54)
+
+Verifies that the configured SMTP server is reachable.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+`true` if the SMTP server is reachable, `false` otherwise.
+
+#### Inherited from
+
+[`SmtpConnectionVerifier`](Class.SmtpConnectionVerifier).[`verifyConnection`](Class.SmtpConnectionVerifier#verifyconnection)
+
 ***
 
 ### ~~verifyEmail()~~
 
 ```ts
-verifyEmail(email): Promise<boolean>;
+verifyEmail(_email): Promise<boolean>;
 ```
 
-Defined in: [platform-mailing/src/services/MailVerificationService.ts:54](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/services/MailVerificationService.ts#L54)
+Defined in: [platform-mailing/src/services/MailVerificationService.ts:27](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/services/MailVerificationService.ts#L27)
 
-Verifies if the email address is valid and reachable.
+Verifies SMTP server connectivity.
 
 #### Parameters
 
 | Parameter | Type | Description |
 | ------ | ------ | ------ |
-| `email` | `string` | The email address to verify |
+| `_email` | `string` | Unused. Kept for backward compatibility. |
 
 #### Returns
 
 `Promise`\<`boolean`\>
 
-Promise\<boolean\> - Resolves true if email exists, false otherwise
+#### Deprecated
+
+Use [SmtpConnectionVerifier.verifyConnection](Class.SmtpConnectionVerifier#verifyconnection) instead.
+The `email` parameter was never used.

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

@@ -0,0 +1,84 @@
+---
+title: 'Class: SmtpConnectionVerifier'
+generated: true
+editUrl: false
+---
+# Class: SmtpConnectionVerifier
+
+Defined in: [platform-mailing/src/services/SmtpConnectionVerifier.ts:17](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/services/SmtpConnectionVerifier.ts#L17)
+
+Verifies SMTP server connectivity. Does **not** validate individual email
+addresses — only checks whether the configured SMTP transport is reachable.
+
+## Extended by
+
+- [`MailVerificationService`](Class.MailVerificationService)
+
+## Constructors
+
+### Constructor
+
+```ts
+new SmtpConnectionVerifier(configService): SmtpConnectionVerifier;
+```
+
+Defined in: [platform-mailing/src/services/SmtpConnectionVerifier.ts:32](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/services/SmtpConnectionVerifier.ts#L32)
+
+Constructs a new instance of the SmtpConnectionVerifier class.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `configService` | `ConfigService` |
+
+#### Returns
+
+`SmtpConnectionVerifier`
+
+## Methods
+
+### sendTestEmail()
+
+```ts
+sendTestEmail(
+   from, 
+   to, 
+   subject, 
+text): Promise<void>;
+```
+
+Defined in: [platform-mailing/src/services/SmtpConnectionVerifier.ts:74](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/services/SmtpConnectionVerifier.ts#L74)
+
+Send an email for testing purposes.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `from` | `string` |
+| `to` | `string` |
+| `subject` | `string` |
+| `text` | `string` |
+
+#### Returns
+
+`Promise`\<`void`\>
+
+***
+
+### verifyConnection()
+
+```ts
+verifyConnection(): Promise<boolean>;
+```
+
+Defined in: [platform-mailing/src/services/SmtpConnectionVerifier.ts:54](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/services/SmtpConnectionVerifier.ts#L54)
+
+Verifies that the configured SMTP server is reachable.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+`true` if the SMTP server is reachable, `false` otherwise.

package/data/packages/platform-mailing/api/Interface.IMailModuleOptions.md

@@ -0,0 +1,36 @@
+---
+title: 'Interface: IMailModuleOptions'
+generated: true
+editUrl: false
+---
+# Interface: IMailModuleOptions
+
+Defined in: [platform-mailing/src/tokens/MailModule.ts:23](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/tokens/MailModule.ts#L23)
+
+Options for configuring the [MailModule](Class.MailModule).
+
+## Properties
+
+### configEntries?
+
+```ts
+readonly optional configEntries?: readonly Omit<IConfigRegistryEntry<unknown>, "module">[];
+```
+
+Defined in: [platform-mailing/src/tokens/MailModule.ts:34](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/tokens/MailModule.ts#L34)
+
+Additional or overriding configuration entries.
+Merged with the platform default entries.
+
+***
+
+### isGlobal?
+
+```ts
+readonly optional isGlobal?: boolean;
+```
+
+Defined in: [platform-mailing/src/tokens/MailModule.ts:28](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/tokens/MailModule.ts#L28)
+
+Whether to register the module globally.
+Defaults to `true`.

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

@@ -16,10 +16,11 @@ editUrl: false
 | [MailModule](Class.MailModule) | Represents the mail module. |
 | [MailService](Class.MailService) | Represents the `MailService` class. |
 | [MailTemplateEngine](Class.MailTemplateEngine) | The `MailTemplateEngine` class. |
-| [~~MailVerificationService~~](Class.MailVerificationService) | Verifies SMTP server connectivity. Does **not** validate individual email addresses — only checks whether the configured SMTP transport is reachable. |
+| [~~MailVerificationService~~](Class.MailVerificationService) | - |
 | [PostmarkDeliveryStrategy](Class.PostmarkDeliveryStrategy) | The `PostmarkDeliveryStrategy` class. |
 | [ResendDeliveryStrategy](Class.ResendDeliveryStrategy) | Delivers emails via the Resend API. |
 | [SendGridDeliveryStrategy](Class.SendGridDeliveryStrategy) | Delivers emails via the SendGrid API. |
+| [SmtpConnectionVerifier](Class.SmtpConnectionVerifier) | Verifies SMTP server connectivity. Does **not** validate individual email addresses — only checks whether the configured SMTP transport is reachable. |
 | [SmtpDeliveryStrategy](Class.SmtpDeliveryStrategy) | The `SmtpDeliveryStrategy` class. |
 | [TemplateFetchStrategyBase](Class.TemplateFetchStrategyBase) | Represents the base class for template fetch strategies. |
 
@@ -29,6 +30,7 @@ editUrl: false
 | ------ | ------ |
 | [IMailAttachment](Interface.IMailAttachment) | Represents an email attachment. |
 | [IMailEvents](Interface.IMailEvents) | Represents the contract of events emitted by the mail domain. |
+| [IMailModuleOptions](Interface.IMailModuleOptions) | Options for configuring the [MailModule](Class.MailModule). |
 | [IMailTemplateVariants](Interface.IMailTemplateVariants) | Represents the in-memory structure for a single template (multiple formats). |
 
 ## Type Aliases