@breadstone/archipel-mcp 0.0.22 → 0.0.25

package/data/guides/queue-infrastructure.md

@@ -0,0 +1,329 @@
+---
+title: Queue Infrastructure
+description: Add job queue infrastructure to your NestJS application with in-memory FIFO, BullMQ (Redis), and Azure Service Bus providers.
+order: 25
+---
+
+# Queue Infrastructure
+
+This guide covers job queue infrastructure with `platform-queue`: choosing between in-memory, Redis-backed, and Azure Service Bus backends, managing job lifecycles, handling errors, and switching providers without code changes.
+
+---
+
+## Installation
+
+```bash
+yarn add @breadstone/archipel-platform-queue
+```
+
+For BullMQ (Redis), also install the SDK:
+
+```bash
+yarn add bullmq
+```
+
+For Azure Service Bus:
+
+```bash
+yarn add @azure/service-bus
+```
+
+---
+
+## Configuration
+
+### Core Variables
+
+```env
+QUEUE_MAX_JOBS=10000
+```
+
+`QUEUE_MAX_JOBS` is optional and only applies to `MemoryQueue`. When omitted, the default of `10_000` is used.
+
+### BullMQ Variables
+
+```env
+BULLMQ_REDIS_URL=redis://localhost:6379
+BULLMQ_PREFIX=myapp:
+```
+
+`BULLMQ_REDIS_URL` is required when using `BullMqQueue`. `BULLMQ_PREFIX` is optional (defaults to empty string).
+
+### Azure Service Bus Variables
+
+```env
+AZURE_CONNECTION_STRING=Endpoint=sb://my-namespace.servicebus.windows.net/;SharedAccessKeyName=...;SharedAccessKey=...
+AZURE_RECEIVE_WAIT_MS=5000
+```
+
+`AZURE_CONNECTION_STRING` is required when using `AzureQueue`. `AZURE_RECEIVE_WAIT_MS` is optional (defaults to `5000`).
+
+### Using Config Keys
+
+Import the typed config keys and pass them to your module registration:
+
+```typescript
+import { PLATFORM_QUEUE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-queue';
+import { BULLMQ_CONFIG_ENTRIES } from '@breadstone/archipel-platform-queue/bullmq';
+import { AZURE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-queue/azure';
+```
+
+---
+
+## Concepts
+
+`platform-queue` provides a generic `IQueue<TPayload>` interface with three implementations:
+
+| Implementation | Backend            | Persistence | Best for                                    |
+| -------------- | ------------------ | ----------- | ------------------------------------------- |
+| `MemoryQueue`  | In-memory          | No          | Development, testing, single-instance apps  |
+| `BullMqQueue`  | Redis via BullMQ   | Yes         | Multi-instance deployments, distributed jobs|
+| `AzureQueue`   | Azure Service Bus  | Yes         | Enterprise cloud messaging, peek-lock       |
+
+All implementations share the same `IQueue` contract, so switching providers requires only changing the import and constructor options — no business logic changes.
+
+### Job Lifecycle
+
+Every job follows a four-state lifecycle:
+
+```mermaid
+stateDiagram-v2
+    [*] --> pending : enqueue()
+    pending --> processing : dequeue()
+    processing --> completed : markCompleted()
+    processing --> failed : markFailed()
+```
+
+Each `IQueueJob` carries full metadata: `id`, `queueName`, `payload`, `status`, `attempts`, `createdAt`, `processedAt`, `completedAt`, `failedAt`, and an optional `errorMessage`.
+
+---
+
+## In-Memory Queue
+
+### Basic Setup
+
+`MemoryQueue` ships with the core entry point and requires no extra dependencies:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { MemoryQueue } from '@breadstone/archipel-platform-queue';
+
+@Module({
+    providers: [
+        {
+            provide: 'IQueue',
+            useFactory: () => new MemoryQueue({ maxJobs: 5_000 }),
+        },
+    ],
+    exports: ['IQueue'],
+})
+export class QueueModule {}
+```
+
+### Capacity Eviction
+
+When the total number of jobs across all named queues exceeds `maxJobs`, the oldest completed or failed jobs are evicted automatically. Pending and processing jobs are never evicted.
+
+> **When to use:** Development, automated tests, or single-instance services where persistence is not required.
+
+---
+
+## BullMQ (Redis)
+
+### Basic Setup
+
+`BullMqQueue` creates Redis-backed queues that survive process restarts and can be shared across multiple instances:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { BullMqQueue } from '@breadstone/archipel-platform-queue/bullmq';
+
+@Module({
+    providers: [
+        {
+            provide: 'IQueue',
+            useFactory: () =>
+                new BullMqQueue({
+                    redisUrl: 'redis://localhost:6379',
+                    prefix: 'myapp:',
+                }),
+        },
+    ],
+    exports: ['IQueue'],
+})
+export class QueueModule {}
+```
+
+### How It Works
+
+Each named queue lazily creates its own BullMQ `Queue` and `Worker` instance. When `dequeue()` is called, the worker picks the next available job using a one-time token. Job tokens are tracked internally so that `markCompleted()` and `markFailed()` can transition jobs to their terminal state.
+
+### Graceful Shutdown
+
+`BullMqQueue` implements `OnModuleDestroy` and automatically closes all queues and workers when the NestJS module is destroyed. No manual cleanup is needed.
+
+---
+
+## Azure Service Bus
+
+### Basic Setup
+
+`AzureQueue` integrates with Azure Service Bus using peek-lock message handling:
+
+```typescript
+import { Module } from '@nestjs/common';
+import { AzureQueue } from '@breadstone/archipel-platform-queue/azure';
+
+@Module({
+    providers: [
+        {
+            provide: 'IQueue',
+            useFactory: () =>
+                new AzureQueue({
+                    connectionString: 'Endpoint=sb://...',
+                    receiveWaitMs: 5_000,
+                }),
+        },
+    ],
+    exports: ['IQueue'],
+})
+export class QueueModule {}
+```
+
+### How It Works
+
+Senders and receivers are lazily created per queue name and cached for the lifetime of the instance. `enqueue()` sends a message to the queue, `dequeue()` receives the next message with peek-lock, `markCompleted()` completes the message, and `markFailed()` dead-letters it.
+
+### Graceful Shutdown
+
+`AzureQueue` implements `OnModuleDestroy` and automatically closes all senders, receivers, and the underlying `ServiceBusClient` when the module is destroyed.
+
+---
+
+## Usage in Services
+
+Inject the `IQueue` token and use the same API regardless of the underlying provider:
+
+```typescript
+import { Injectable, Inject } from '@nestjs/common';
+import { IQueue, QUEUE_JOB_STATUS } from '@breadstone/archipel-platform-queue';
+
+@Injectable()
+export class InvoiceService {
+    // #region Fields
+
+    private readonly _queue: IQueue;
+
+    // #endregion
+
+    // #region Ctor
+
+    constructor(@Inject('IQueue') queue: IQueue) {
+        this._queue = queue;
+    }
+
+    // #endregion
+
+    // #region Methods
+
+    public async scheduleInvoice(invoiceId: number): Promise<void> {
+        await this._queue.enqueue('invoices', { invoiceId });
+    }
+
+    public async processNext(): Promise<void> {
+        const job = await this._queue.dequeue<{ invoiceId: number }>('invoices');
+
+        if (!job) {
+            return;
+        }
+
+        try {
+            // ... process the invoice
+            await this._queue.markCompleted(job.id);
+        } catch (error) {
+            await this._queue.markFailed(job.id, (error as Error).message);
+        }
+    }
+
+    // #endregion
+}
+```
+
+---
+
+## Error Handling
+
+All queue implementations throw domain-specific errors that extend `QueueError`:
+
+| Error Class             | When Thrown                                             |
+| ----------------------- | ------------------------------------------------------- |
+| `QueueValidationError`  | Empty or whitespace-only queue name or error message    |
+| `QueueJobNotFoundError` | Job ID does not exist in the underlying store           |
+| `QueueJobStateError`    | Job is in the wrong state for the requested transition  |
+
+Handle these in your service layer or map them centrally via an exception filter:
+
+```typescript
+import { QueueJobNotFoundError, QueueJobStateError } from '@breadstone/archipel-platform-queue';
+
+try {
+    await this._queue.markCompleted(jobId);
+} catch (error) {
+    if (error instanceof QueueJobNotFoundError) {
+        this._logger.warn(`Job ${jobId} not found — may have been evicted.`);
+    } else if (error instanceof QueueJobStateError) {
+        this._logger.warn(`Job ${jobId} is not in processing state.`);
+    } else {
+        throw error;
+    }
+}
+```
+
+---
+
+## Listing Jobs
+
+Use `getJobs()` to retrieve all jobs for a named queue. This is useful for admin dashboards or monitoring:
+
+```typescript
+const jobs = await this._queue.getJobs('invoices');
+
+const pending = jobs.filter((j) => j.status === QUEUE_JOB_STATUS.pending);
+const failed = jobs.filter((j) => j.status === QUEUE_JOB_STATUS.failed);
+
+this._logger.log(`Queue 'invoices': ${pending.length} pending, ${failed.length} failed`);
+```
+
+---
+
+## Switching Providers
+
+Swap the provider by changing the import — no business logic changes needed:
+
+```typescript
+// Before: in-memory
+import { MemoryQueue } from '@breadstone/archipel-platform-queue';
+useFactory: () => new MemoryQueue({ maxJobs: 10_000 }),
+
+// After: Redis
+import { BullMqQueue } from '@breadstone/archipel-platform-queue/bullmq';
+useFactory: () => new BullMqQueue({ redisUrl: 'redis://localhost:6379' }),
+
+// After: Azure Service Bus
+import { AzureQueue } from '@breadstone/archipel-platform-queue/azure';
+useFactory: () => new AzureQueue({ connectionString: 'Endpoint=sb://...' }),
+```
+
+---
+
+## Best Practices
+
+| Practice                                    | Why                                                                   |
+| ------------------------------------------- | --------------------------------------------------------------------- |
+| Use `MemoryQueue` only for dev and tests    | Data is lost on restart; not suitable for production workloads         |
+| Set `maxJobs` for `MemoryQueue`             | Prevents unbounded memory growth in long-running processes            |
+| Always handle `markFailed`                  | Ensures failed jobs are properly tracked and not stuck in processing  |
+| Use typed payloads with generics            | `enqueue<T>()` and `dequeue<T>()` keep your job data type-safe       |
+| Rely on `OnModuleDestroy` for cleanup       | Both `BullMqQueue` and `AzureQueue` close connections automatically   |
+| Keep queue names short and descriptive      | e.g. `invoices`, `emails`, `reports` — avoid deeply nested names      |
+| Wrap queue calls in services                | Never call `IQueue` directly from controllers                         |

package/data/guides/telemetry-and-observability.md

@@ -135,6 +135,26 @@ export class PaymentService {
 
 All log entries automatically include `requestId` for request-level correlation.
 
+### ContextLogger (from platform-logging)
+
+For services that need automatic request context enrichment without manual `requestId` plumbing, use `ContextLogger` from `platform-logging`:
+
+```typescript
+import { ContextLogger } from '@breadstone/archipel-platform-logging';
+
+@Injectable()
+export class OrderService {
+  private readonly _logger = new ContextLogger(OrderService.name);
+
+  public async processOrder(orderId: string): Promise<void> {
+    this._logger.log('Processing order', { orderId });
+    // Automatically includes requestId + userId from RequestContextStore
+  }
+}
+```
+
+Pair with `RequestIdMiddleware` to propagate the `x-request-id` header across the request lifecycle. See the [platform-logging docs](../packages/platform-logging/) for setup details.
+
 ---
 
 ## Automatic Operation Instrumentation

package/data/packages/platform-analytics/api/Class.AnalyticsClientPort.md

@@ -120,6 +120,26 @@ Clear the current user context.
 
 ***
 
+### ping()
+
+```ts
+ping(): Promise<boolean>;
+```
+
+Defined in: [contracts/AnalyticsClientPort.ts:69](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/contracts/AnalyticsClientPort.ts#L69)
+
+Lightweight readiness check for the analytics provider.
+Override in adapters to verify SDK initialization.
+Defaults to `true` if not overridden.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+`true` if the provider is ready.
+
+***
+
 ### setUser()
 
 ```ts

package/data/packages/platform-analytics/api/Class.AnalyticsHealthIndicator.md

@@ -0,0 +1,78 @@
+---
+title: 'Class: AnalyticsHealthIndicator'
+generated: true
+editUrl: false
+---
+# Class: AnalyticsHealthIndicator
+
+Defined in: health/AnalyticsHealthIndicator.ts:17
+
+Health indicator for the analytics infrastructure.
+Calls [AnalyticsClientPort.ping](Class.AnalyticsClientPort#ping) to verify provider readiness.
+
+## Implements
+
+- `IHealthIndicator`
+
+## Constructors
+
+### Constructor
+
+```ts
+new AnalyticsHealthIndicator(analyticsClient?): AnalyticsHealthIndicator;
+```
+
+Defined in: health/AnalyticsHealthIndicator.ts:27
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `analyticsClient?` | [`AnalyticsClientPort`](Class.AnalyticsClientPort) |
+
+#### Returns
+
+`AnalyticsHealthIndicator`
+
+## Properties
+
+### key
+
+```ts
+readonly key: string = 'analytics';
+```
+
+Defined in: health/AnalyticsHealthIndicator.ts:35
+
+Unique key identifying the indicator
+
+#### Implementation of
+
+```ts
+IHealthIndicator.key
+```
+
+## Methods
+
+### check()
+
+```ts
+check(): Promise<HealthIndicatorResult<string>>;
+```
+
+Defined in: health/AnalyticsHealthIndicator.ts:48
+
+Pings the analytics provider to verify readiness.
+Returns disabled status when no client is configured.
+
+#### Returns
+
+`Promise`\<`HealthIndicatorResult`\<`string`\>\>
+
+The health indicator result.
+
+#### Implementation of
+
+```ts
+IHealthIndicator.check
+```

package/data/packages/platform-analytics/api/Class.AppInsightsAnalyticsClient.md

@@ -193,6 +193,30 @@ OnModuleInit.onModuleInit
 
 ***
 
+### ping()
+
+```ts
+ping(): Promise<boolean>;
+```
+
+Defined in: [contracts/AnalyticsClientPort.ts:69](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/contracts/AnalyticsClientPort.ts#L69)
+
+Lightweight readiness check for the analytics provider.
+Override in adapters to verify SDK initialization.
+Defaults to `true` if not overridden.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+`true` if the provider is ready.
+
+#### Inherited from
+
+[`AnalyticsClientPort`](Class.AnalyticsClientPort).[`ping`](Class.AnalyticsClientPort#ping)
+
+***
+
 ### setUser()
 
 ```ts

package/data/packages/platform-analytics/api/Class.DatadogAnalyticsClient.md

@@ -170,6 +170,30 @@ OnModuleInit.onModuleInit
 
 ***
 
+### ping()
+
+```ts
+ping(): Promise<boolean>;
+```
+
+Defined in: [contracts/AnalyticsClientPort.ts:69](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/contracts/AnalyticsClientPort.ts#L69)
+
+Lightweight readiness check for the analytics provider.
+Override in adapters to verify SDK initialization.
+Defaults to `true` if not overridden.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+`true` if the provider is ready.
+
+#### Inherited from
+
+[`AnalyticsClientPort`](Class.AnalyticsClientPort).[`ping`](Class.AnalyticsClientPort#ping)
+
+***
+
 ### setUser()
 
 ```ts

package/data/packages/platform-analytics/api/Class.NoopAnalyticsClient.md

@@ -136,6 +136,30 @@ Clear the current user context.
 
 ***
 
+### ping()
+
+```ts
+ping(): Promise<boolean>;
+```
+
+Defined in: [contracts/AnalyticsClientPort.ts:69](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/contracts/AnalyticsClientPort.ts#L69)
+
+Lightweight readiness check for the analytics provider.
+Override in adapters to verify SDK initialization.
+Defaults to `true` if not overridden.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+`true` if the provider is ready.
+
+#### Inherited from
+
+[`AnalyticsClientPort`](Class.AnalyticsClientPort).[`ping`](Class.AnalyticsClientPort#ping)
+
+***
+
 ### setUser()
 
 ```ts

package/data/packages/platform-analytics/api/Class.SentryAnalyticsClient.md

@@ -193,6 +193,30 @@ OnModuleInit.onModuleInit
 
 ***
 
+### ping()
+
+```ts
+ping(): Promise<boolean>;
+```
+
+Defined in: [contracts/AnalyticsClientPort.ts:69](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/contracts/AnalyticsClientPort.ts#L69)
+
+Lightweight readiness check for the analytics provider.
+Override in adapters to verify SDK initialization.
+Defaults to `true` if not overridden.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+`true` if the provider is ready.
+
+#### Inherited from
+
+[`AnalyticsClientPort`](Class.AnalyticsClientPort).[`ping`](Class.AnalyticsClientPort#ping)
+
+***
+
 ### setUser()
 
 ```ts

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

@@ -10,6 +10,7 @@ editUrl: false
 | Class | Description |
 | ------ | ------ |
 | [AnalyticsClientPort](Class.AnalyticsClientPort) | Abstract port for analytics and error tracking clients. Each provider (Sentry, Application Insights, Datadog) must implement this contract so that the consuming application can switch providers without changing business logic. |
+| [AnalyticsHealthIndicator](Class.AnalyticsHealthIndicator) | Health indicator for the analytics infrastructure. Calls [AnalyticsClientPort.ping](Class.AnalyticsClientPort#ping) to verify provider readiness. |
 | [AnalyticsModule](Class.AnalyticsModule) | NestJS module providing generic analytics and error tracking infrastructure. The specific analytics provider (Sentry, Application Insights, Datadog) is selected via the options. |
 | [AppInsightsAnalyticsClient](Class.AppInsightsAnalyticsClient) | Azure Application Insights implementation of the [AnalyticsClientPort](Class.AnalyticsClientPort). Uses the `applicationinsights` SDK for error tracking and analytics. |
 | [DatadogAnalyticsClient](Class.DatadogAnalyticsClient) | Datadog implementation of the [AnalyticsClientPort](Class.AnalyticsClientPort). Uses the `dd-trace` SDK for error tracking and analytics. |

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

@@ -2,7 +2,7 @@
 title: platform-analytics
 description: Provider-agnostic analytics and error tracking with pluggable clients.
 order: 14
-tags: [analytics, error-tracking, sentry, application-insights, datadog, observability, providers]
+tags: [analytics, error-tracking, sentry, application-insights, datadog, observability, providers, health]
 package: '@breadstone/archipel-platform-analytics'
 ---
 
@@ -168,6 +168,29 @@ This ensures no events are lost during application shutdown and prevents hanging
 
 ---
 
+## Health Check
+
+The `AnalyticsHealthIndicator` verifies that an `AnalyticsClientPort` is injected. If no analytics client is registered, it reports `disabled: true`. Import it from the `/health` subpath:
+
+```typescript
+import { AnalyticsHealthIndicator } from '@breadstone/archipel-platform-analytics/health';
+import { HealthModule } from '@breadstone/archipel-platform-health';
+
+@Module({
+  imports: [
+    AnalyticsModule.register({ /* ... */ }),
+    HealthModule.withIndicators([AnalyticsHealthIndicator]),
+  ],
+})
+export class AppModule {}
+```
+
+| Key | Check | Dependencies |
+| --- | ----- | ------------ |
+| `analytics` | `up` if `AnalyticsClientPort` injected, else `disabled` | `@Optional() AnalyticsClientPort` |
+
+---
+
 ## Exports Summary
 
 | Export                       | Type          | Description                                    |
@@ -181,3 +204,4 @@ This ensures no events are lost during application shutdown and prevents hanging
 | `AnalyticsLevel`             | Type          | Severity level union                           |
 | `IAnalyticsBreadcrumb`       | Interface     | Breadcrumb entry model                         |
 | `IAnalyticsUser`             | Interface     | User context model                             |
+| `AnalyticsHealthIndicator`   | Health        | Analytics readiness check (`/health` subpath)  |