@breadstone/archipel-mcp 0.0.23 → 0.0.26

package/data/packages/platform-queue/api/Variable.AZURE_RECEIVE_WAIT_MS.md

@@ -0,0 +1,21 @@
+---
+title: 'Variable: AZURE\_RECEIVE\_WAIT\_MS'
+generated: true
+editUrl: false
+---
+# Variable: AZURE\_RECEIVE\_WAIT\_MS
+
+```ts
+const AZURE_RECEIVE_WAIT_MS: IConfigKey<number>;
+```
+
+Defined in: [azure/env.ts:24](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-queue/src/azure/env.ts#L24)
+
+Maximum wait time in milliseconds when receiving messages.
+
+## Default Value
+
+```ts
+5_000
+@public
+```

package/data/packages/platform-queue/api/Variable.BULLMQ_CONFIG_ENTRIES.md

@@ -0,0 +1,17 @@
+---
+title: 'Variable: BULLMQ\_CONFIG\_ENTRIES'
+generated: true
+editUrl: false
+---
+# Variable: BULLMQ\_CONFIG\_ENTRIES
+
+```ts
+const BULLMQ_CONFIG_ENTRIES: ReadonlyArray<Omit<IConfigRegistryEntry, "module">>;
+```
+
+Defined in: [bullmq/env.ts:39](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-queue/src/bullmq/env.ts#L39)
+
+All configuration entries required by the BullMQ queue provider.
+
+Pass this array to the module's `register()` method so that the
+configuration service validates and provides the values at startup.

package/data/packages/platform-queue/api/Variable.BULLMQ_PREFIX.md

@@ -0,0 +1,18 @@
+---
+title: 'Variable: BULLMQ\_PREFIX'
+generated: true
+editUrl: false
+---
+# Variable: BULLMQ\_PREFIX
+
+```ts
+const BULLMQ_PREFIX: IConfigKey<string>;
+```
+
+Defined in: [bullmq/env.ts:25](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-queue/src/bullmq/env.ts#L25)
+
+Optional key prefix applied to all BullMQ queues in Redis.
+
+## Default Value
+
+`''`

package/data/packages/platform-queue/api/Variable.BULLMQ_REDIS_URL.md

@@ -0,0 +1,21 @@
+---
+title: 'Variable: BULLMQ\_REDIS\_URL'
+generated: true
+editUrl: false
+---
+# Variable: BULLMQ\_REDIS\_URL
+
+```ts
+const BULLMQ_REDIS_URL: IConfigKey<string>;
+```
+
+Defined in: [bullmq/env.ts:17](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-queue/src/bullmq/env.ts#L17)
+
+Redis connection URL for BullMQ.
+
+## Example
+
+```ts
+`redis://localhost:6379`
+@public
+```

package/data/packages/platform-queue/api/Variable.PLATFORM_QUEUE_CONFIG_ENTRIES.md

@@ -0,0 +1,17 @@
+---
+title: 'Variable: PLATFORM\_QUEUE\_CONFIG\_ENTRIES'
+generated: true
+editUrl: false
+---
+# Variable: PLATFORM\_QUEUE\_CONFIG\_ENTRIES
+
+```ts
+const PLATFORM_QUEUE_CONFIG_ENTRIES: ReadonlyArray<Omit<IConfigRegistryEntry, "module">>;
+```
+
+Defined in: [env.ts:31](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-queue/src/env.ts#L31)
+
+All configuration entries required by `platform-queue`.
+
+Pass this array to the module's `register()` method so that the
+configuration service validates and provides the values at startup.

package/data/packages/platform-queue/api/Variable.QUEUE_JOB_STATUS.md

@@ -0,0 +1,30 @@
+---
+title: 'Variable: QUEUE\_JOB\_STATUS'
+generated: true
+editUrl: false
+---
+# Variable: QUEUE\_JOB\_STATUS
+
+```ts
+const QUEUE_JOB_STATUS: {
+  completed: "completed";
+  failed: "failed";
+  pending: "pending";
+  processing: "processing";
+};
+```
+
+Defined in: [models/IQueueJob.ts:10](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-queue/src/models/IQueueJob.ts#L10)
+
+Possible statuses of a queue job.
+
+Use as a const object and derive the union type via [QueueJobStatus](TypeAlias.QueueJobStatus).
+
+## Type Declaration
+
+| Name | Type | Default value | Description | Defined in |
+| ------ | ------ | ------ | ------ | ------ |
+| <a id="property-completed"></a> `completed` | `"completed"` | `'completed'` | Job finished successfully. | [models/IQueueJob.ts:16](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-queue/src/models/IQueueJob.ts#L16) |
+| <a id="property-failed"></a> `failed` | `"failed"` | `'failed'` | Job finished with an error. | [models/IQueueJob.ts:18](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-queue/src/models/IQueueJob.ts#L18) |
+| <a id="property-pending"></a> `pending` | `"pending"` | `'pending'` | Job is waiting to be picked up. | [models/IQueueJob.ts:12](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-queue/src/models/IQueueJob.ts#L12) |
+| <a id="property-processing"></a> `processing` | `"processing"` | `'processing'` | Job has been dequeued and is being processed. | [models/IQueueJob.ts:14](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-queue/src/models/IQueueJob.ts#L14) |

package/data/packages/platform-queue/api/Variable.QUEUE_MAX_JOBS.md

@@ -0,0 +1,21 @@
+---
+title: 'Variable: QUEUE\_MAX\_JOBS'
+generated: true
+editUrl: false
+---
+# Variable: QUEUE\_MAX\_JOBS
+
+```ts
+const QUEUE_MAX_JOBS: IConfigKey<number>;
+```
+
+Defined in: [env.ts:17](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-queue/src/env.ts#L17)
+
+Maximum number of jobs retained in the in-memory queue before eviction.
+
+## Default Value
+
+```ts
+10_000
+@public
+```

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

@@ -0,0 +1,49 @@
+---
+title: '@breadstone/archipel-platform-queue'
+generated: true
+editUrl: false
+---
+# @breadstone/archipel-platform-queue
+
+## Classes
+
+| Class | Description |
+| ------ | ------ |
+| [AzureQueue](Class.AzureQueue) | Azure Service Bus queue implementation. |
+| [BullMqQueue](Class.BullMqQueue) | BullMQ-backed queue implementation. |
+| [MemoryQueue](Class.MemoryQueue) | In-memory FIFO queue implementation. |
+| [QueueError](Class.QueueError) | Base error class for all queue-related errors. |
+| [QueueHealthIndicator](Class.QueueHealthIndicator) | Health indicator for the queue infrastructure. |
+| [QueueJobNotFoundError](Class.QueueJobNotFoundError) | Thrown when a queue job cannot be found by its ID. |
+| [QueueJobStateError](Class.QueueJobStateError) | Thrown when a queue job is in an invalid state for the requested transition. |
+| [QueueValidationError](Class.QueueValidationError) | Thrown when a queue operation receives invalid input. |
+
+## Interfaces
+
+| Interface | Description |
+| ------ | ------ |
+| [IAzureQueueOptions](Interface.IAzureQueueOptions) | Configuration options for [AzureQueue](Class.AzureQueue). |
+| [IBullMqQueueOptions](Interface.IBullMqQueueOptions) | Configuration options for [BullMqQueue](Class.BullMqQueue). |
+| [IMemoryQueueOptions](Interface.IMemoryQueueOptions) | Configuration options for [MemoryQueue](Class.MemoryQueue). |
+| [IQueue](Interface.IQueue) | Contract for queue implementations. |
+| [IQueueJob](Interface.IQueueJob) | Represents a job in a named queue with tracking metadata. |
+
+## Type Aliases
+
+| Type Alias | Description |
+| ------ | ------ |
+| [QueueJobStatus](TypeAlias.QueueJobStatus) | Union type derived from [QUEUE\_JOB\_STATUS](Variable.QUEUE_JOB_STATUS). |
+
+## Variables
+
+| Variable | Description |
+| ------ | ------ |
+| [AZURE\_CONFIG\_ENTRIES](Variable.AZURE_CONFIG_ENTRIES) | All configuration entries required by the Azure queue provider. |
+| [AZURE\_CONNECTION\_STRING](Variable.AZURE_CONNECTION_STRING) | Azure queue connection string. |
+| [AZURE\_RECEIVE\_WAIT\_MS](Variable.AZURE_RECEIVE_WAIT_MS) | Maximum wait time in milliseconds when receiving messages. |
+| [BULLMQ\_CONFIG\_ENTRIES](Variable.BULLMQ_CONFIG_ENTRIES) | All configuration entries required by the BullMQ queue provider. |
+| [BULLMQ\_PREFIX](Variable.BULLMQ_PREFIX) | Optional key prefix applied to all BullMQ queues in Redis. |
+| [BULLMQ\_REDIS\_URL](Variable.BULLMQ_REDIS_URL) | Redis connection URL for BullMQ. |
+| [PLATFORM\_QUEUE\_CONFIG\_ENTRIES](Variable.PLATFORM_QUEUE_CONFIG_ENTRIES) | All configuration entries required by `platform-queue`. |
+| [QUEUE\_JOB\_STATUS](Variable.QUEUE_JOB_STATUS) | Possible statuses of a queue job. |
+| [QUEUE\_MAX\_JOBS](Variable.QUEUE_MAX_JOBS) | Maximum number of jobs retained in the in-memory queue before eviction. |

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

@@ -0,0 +1,168 @@
+---
+title: platform-queue
+description: Provider-agnostic queue infrastructure with support for in-memory FIFO, BullMQ (Redis), and Azure Service Bus.
+order: 19
+tags: [queue, job-queue, fifo, memory-queue, bullmq, redis, azure-service-bus, ports-and-adapters, health]
+package: '@breadstone/archipel-platform-queue'
+---
+
+# platform-queue
+
+Provider-agnostic queue infrastructure for NestJS. Exposes a unified `IQueue` contract with three ready-made implementations: in-memory FIFO (`MemoryQueue`), BullMQ/Redis (`BullMqQueue`), and Azure Service Bus (`AzureQueue`). Jobs follow a lifecycle from pending through processing to completed or failed, with full metadata tracking.
+
+**Package:** `@breadstone/archipel-platform-queue`
+
+## Architecture
+
+```mermaid
+graph TD
+    Core["@breadstone/archipel-platform-queue<br/><i>IQueue, models, errors, MemoryQueue</i>"]
+    BullMQ["@breadstone/archipel-platform-queue/bullmq<br/><i>BullMqQueue</i>"]
+    Azure["@breadstone/archipel-platform-queue/azure<br/><i>AzureQueue</i>"]
+
+    BullMQ -->|implements| Core
+    Azure -->|implements| Core
+
+    BullMQ -.-|requires| R["bullmq"]
+    Azure -.-|requires| S["@azure/service-bus"]
+```
+
+Each provider SDK is an **optional peer dependency**. Install only the one you need. `MemoryQueue` ships with the core entry point and requires no additional dependencies.
+
+---
+
+## Quick Start
+
+### 1. Install the provider SDK (optional)
+
+```bash
+# Pick one (or use MemoryQueue without any extra SDK):
+yarn add bullmq
+yarn add @azure/service-bus
+```
+
+### 2. Register the queue
+
+```typescript
+import { Module } from '@nestjs/common';
+import { IQueue, MemoryQueue } from '@breadstone/archipel-platform-queue';
+
+@Module({
+  providers: [
+    {
+      provide: 'IQueue',
+      useFactory: () => new MemoryQueue({ maxJobs: 5_000 }),
+    },
+  ],
+  exports: ['IQueue'],
+})
+export class AppModule {}
+```
+
+### Switching providers
+
+Replace the imports — no other code change needed:
+
+```typescript
+import { BullMqQueue } from '@breadstone/archipel-platform-queue/bullmq';
+
+{
+  provide: 'IQueue',
+  useFactory: () => new BullMqQueue({ redisUrl: 'redis://localhost:6379' }),
+}
+```
+
+---
+
+## Queue Providers
+
+### Memory (built-in)
+
+**Entry point:** `@breadstone/archipel-platform-queue`
+
+| Variable         | Required | Default | Description                           |
+| ---------------- | -------- | ------- | ------------------------------------- |
+| `QUEUE_MAX_JOBS` | No       | `10000` | Maximum jobs retained before eviction |
+
+### BullMQ
+
+**Subpath:** `@breadstone/archipel-platform-queue/bullmq`
+**SDK:** `bullmq` ≥ 5.0.0
+
+| Variable          | Required | Default | Description                                  |
+| ----------------- | -------- | ------- | -------------------------------------------- |
+| `BULLMQ_REDIS_URL`| Yes      | —       | Redis connection URL (e.g. `redis://localhost:6379`) |
+| `BULLMQ_PREFIX`   | No       | `""`    | Optional key prefix for all BullMQ queues    |
+
+```typescript
+import { BullMqQueue, BULLMQ_CONFIG_ENTRIES } from '@breadstone/archipel-platform-queue/bullmq';
+```
+
+### Azure Service Bus
+
+**Subpath:** `@breadstone/archipel-platform-queue/azure`
+**SDK:** `@azure/service-bus` ≥ 7.0.0
+
+| Variable                  | Required | Default | Description                              |
+| ------------------------- | -------- | ------- | ---------------------------------------- |
+| `AZURE_CONNECTION_STRING` | Yes      | —       | Azure Service Bus connection string      |
+| `AZURE_RECEIVE_WAIT_MS`  | No       | `5000`  | Max wait time (ms) when receiving messages|
+
+```typescript
+import { AzureQueue, AZURE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-queue/azure';
+```
+
+---
+
+## Job Lifecycle
+
+| Status       | Description                                          |
+| ------------ | ---------------------------------------------------- |
+| `pending`    | Job is waiting to be picked up                       |
+| `processing` | Job has been dequeued and is being processed         |
+| `completed`  | Job finished successfully via `markCompleted()`      |
+| `failed`     | Job finished with an error via `markFailed()`        |
+
+---
+
+## Error Handling
+
+| Error Class             | Base Class   | When Thrown                                    |
+| ----------------------- | ------------ | ---------------------------------------------- |
+| `QueueError`            | `Error`      | Base class for all queue errors                |
+| `QueueJobNotFoundError` | `QueueError` | Job ID does not exist                          |
+| `QueueJobStateError`    | `QueueError` | Job is in wrong state for requested transition |
+| `QueueValidationError`  | `QueueError` | Empty queue name or error message              |
+
+---
+
+## Health Check
+
+The `QueueHealthIndicator` reports the queue subsystem as available. Import it from the `/health` subpath:
+
+```typescript
+import { QueueHealthIndicator } from '@breadstone/archipel-platform-queue/health';
+import { HealthModule } from '@breadstone/archipel-platform-health';
+
+@Module({
+  imports: [
+    QueueModule.register({ /* ... */ }),
+    HealthModule.withIndicators([QueueHealthIndicator]),
+  ],
+})
+export class AppModule {}
+```
+
+| Key | Check | Dependencies |
+| --- | ----- | ------------ |
+| `queue` | Always reports `up` | None |
+
+---
+
+## Peer Dependencies
+
+| Package              | Required | Notes                            |
+| -------------------- | -------- | -------------------------------- |
+| `@nestjs/common`    | Yes      | NestJS core                      |
+| `bullmq`            | Optional | Required for BullMQ provider     |
+| `@azure/service-bus` | Optional | Required for Azure Service Bus   |

package/data/packages/platform-resources/api/Class.BlobResourceStrategy.md

@@ -0,0 +1,195 @@
+---
+title: 'Class: BlobResourceStrategy'
+generated: true
+editUrl: false
+---
+# Class: BlobResourceStrategy
+
+Defined in: [strategies/BlobResourceStrategy.ts:47](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/BlobResourceStrategy.ts#L47)
+
+Strategy for loading resources from blob storage.
+
+## Implements
+
+- [`IResourceStrategy`](Interface.IResourceStrategy)
+
+## Constructors
+
+### Constructor
+
+```ts
+new BlobResourceStrategy(blobService, config?): BlobResourceStrategy;
+```
+
+Defined in: [strategies/BlobResourceStrategy.ts:63](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/BlobResourceStrategy.ts#L63)
+
+Constructs a new instance of the `BlobResourceStrategy` class.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `blobService` | [`IBlobServiceAdapter`](Interface.IBlobServiceAdapter) |
+| `config` | [`IBlobResourceStrategyConfig`](Interface.IBlobResourceStrategyConfig) |
+
+#### Returns
+
+`BlobResourceStrategy`
+
+## Accessors
+
+### name
+
+#### Get Signature
+
+```ts
+get name(): string;
+```
+
+Defined in: [strategies/BlobResourceStrategy.ts:72](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/BlobResourceStrategy.ts#L72)
+
+The unique name of this strategy.
+
+##### Returns
+
+`string`
+
+The unique name of this strategy.
+
+#### Implementation of
+
+[`IResourceStrategy`](Interface.IResourceStrategy).[`name`](Interface.IResourceStrategy#name)
+
+## Methods
+
+### exists()
+
+```ts
+exists(key): boolean;
+```
+
+Defined in: [strategies/BlobResourceStrategy.ts:136](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/BlobResourceStrategy.ts#L136)
+
+Checks if a resource exists without loading it.
+Note: Blob storage is inherently async, so this delegates to existsAsync internally.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `key` | `string` | The resource key |
+
+#### Returns
+
+`boolean`
+
+True if the resource exists
+
+#### Implementation of
+
+[`IResourceStrategy`](Interface.IResourceStrategy).[`exists`](Interface.IResourceStrategy#exists)
+
+***
+
+### existsAsync()
+
+```ts
+existsAsync(key): Promise<boolean>;
+```
+
+Defined in: [strategies/BlobResourceStrategy.ts:147](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/BlobResourceStrategy.ts#L147)
+
+Checks if a resource exists without loading it (asynchronous).
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `key` | `string` | The resource key |
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+Promise resolving to true if the resource exists
+
+#### Implementation of
+
+[`IResourceStrategy`](Interface.IResourceStrategy).[`existsAsync`](Interface.IResourceStrategy#existsasync)
+
+***
+
+### load()
+
+```ts
+load(key): IResourceResult | undefined;
+```
+
+Defined in: [strategies/BlobResourceStrategy.ts:88](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/BlobResourceStrategy.ts#L88)
+
+Loads a resource by its key.
+Note: Blob storage is inherently async, so this delegates to loadAsync internally.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `key` | `string` | The resource key |
+
+#### Returns
+
+[`IResourceResult`](Interface.IResourceResult) \| `undefined`
+
+The resource result or undefined if not found
+
+#### Implementation of
+
+[`IResourceStrategy`](Interface.IResourceStrategy).[`load`](Interface.IResourceStrategy#load)
+
+***
+
+### loadAsync()
+
+```ts
+loadAsync(key): Promise<IResourceResult | undefined>;
+```
+
+Defined in: [strategies/BlobResourceStrategy.ts:99](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/BlobResourceStrategy.ts#L99)
+
+Loads a resource by its key (asynchronous).
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `key` | `string` | The resource key |
+
+#### Returns
+
+`Promise`\<[`IResourceResult`](Interface.IResourceResult) \| `undefined`\>
+
+Promise resolving to the resource result or undefined if not found
+
+#### Implementation of
+
+[`IResourceStrategy`](Interface.IResourceStrategy).[`loadAsync`](Interface.IResourceStrategy#loadasync)
+
+***
+
+### whatDoIHave()
+
+```ts
+whatDoIHave(): void;
+```
+
+Defined in: [strategies/BlobResourceStrategy.ts:163](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/BlobResourceStrategy.ts#L163)
+
+List all files and folders in the base paths for debugging purposes.
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+[`IResourceStrategy`](Interface.IResourceStrategy).[`whatDoIHave`](Interface.IResourceStrategy#whatdoihave)